AdminGuide:BasicConcepts:Extensions and SIP accounts
Return to AdminGuide:BasicConcepts
Extensions and SIP accounts
Extensions are the primary telephone entities. An extension is a logical entity identified by its number, which is used as the identifier for all calls made by the extension and is the number dialed by other users who wish to contact the extension. Each extension has a number of attributes that define its permissions (for outgoing calls from the extension) and behavior (for incoming calls to the extension), as well as a few identity records (first and last name of the person to whom the extension is assigned, its organizational unit, and so on).
SIP accounts are "service" entities. They are the credentials (username and secret) that need to be configured on a SIP terminal (hardphone or softphone) so that it can authenticate to the PBX. Authentication is performed by the devices with two procedures: "SIP registration" and the execution of a new call.
The relationship between extensions and SIP accounts is one-to-many: each extension can be linked to multiple SIP accounts, which all behave as the same telephone entity in terms of identity, presentation, permissions, etc.
It is also possible to create a unique user for each extension; different permissions and roles can be granted to these users, in order to allow them to access their personal web page, perform some administrative or configuration tasks, use the KalliopeCTI applications (desktop or mobile), and invoke the available REST APIs. Please see the users and roles page for more details.
SIP registration and multiple devices per extension
SIP registration informs the PBX of the current location of a SIP account, i.e. the IP address and port (plus the protocol, e.g. UDP, TCP, TLS, or WebSocket) where the SIP account can be reached when the PBX needs to send it a message (e.g. an INVITE related to an incoming call). Registration is performed by the device at boot time (if the account is correctly configured) and then refreshed periodically before its validity expires; each periodic registration requires the repetition of the authentication procedure. The lifetime of the registration is established during the registration procedure itself. The device inserts a "Proposed Expiry" value (in seconds, usually defaults to 3600) in its REGISTER request; upon successful authentication, the PBX responds with a "200 OK" message that notifies the actual registration lifetime to the device, which must then send a new registration before the timeout expires (usually this new registration is performed at about half time, to allow for re-transmission in case of failures). If the registration timeout expires without the reception of a registration refresh, then the location of the account is discarded by the PBX and the calls destined to that account will fail due to it being "unavailable".
KalliopePBX stores a single location for each configured SIP account; if the same SIP account is configured on multiple devices, all active at the same time, the periodic registration messages from each continuously change the location stored in KalliopePBX. A call to the SIP account is therefore presented only to the device that registered last. It is however possible to have multiple devices which behave as a single extension by defining one SIP account for each of the desired devices, and linking all these SIP accounts to the same extension.
Extension attributes and templates
Each extension has its own set of attributes that describe its identity and behavior. Some of these attributes are specific to each device and have to be individually configured, while others can be common to all or a subset of extensions. The former include the extension number itself (which must be unique within the PBX, or within each tenant for a multi-tenant PBX) as well as personal details such as first and last name, email address, and the personal PIN code used for authentication when accessing certain PBX services. The latter include call limits and permissions, and the failover actions to be executed on a failed call to the extension, based on the origin of the call and the cause of failure.
To ease the management of these common attributes, KalliopePBX introduces the concept of an extension template: a collection of attributes and settings that can be assigned to multiple extensions. Defining multiple templates (with different settings based on the extension type) reduces the number of settings that need to be specified for each single extension and helps quickly edit the same setting for all the extensions that share the same template simply by changing the value of the setting in the corresponding template.
In the configuration panel of each extension, it is possible to override any setting inherited from the associated template if a specific exception is needed. The overridden settings are not affected by changes to the template.
SIP account attributes
As with extensions, SIP accounts have some specific attributes (mainly the username, which must be unique within the PBX, and the SIP secret), while others may be common to a "class" of accounts. These include supported transport protocols, media, or codecs, the authorized ACL, and others; similarly to extensions, SIP account templates can be used to define classes of SIP accounts with common settings.
The extensions page contains the attributes of each KalliopePBX user. The main attribute that identifies each user is the telephone extension.
If multiple devices (Accounts) are linked to the same user, these will share the telephone identity defined on this page.
This means that, for example, all calls to an extension will be presented to all devices linked to the user, and all calls made from any of these devices will be made under the same telephone identity.
To configure extensions just open the operating menu and click on PBX > Extensions and Accounts.
To create a new extension proceed by clicking on "Add new extension".
- Enabled: Lets you disable an extension without losing its configuration.
- Extension: The internal phone number linked to the user.
- Name: Part of the name displayed to other users and shown in the phonebook.
- Last name: Part of the name displayed to other users and shown in the phonebook.
- Email address: Displayed in the phonebook.
- Mobile number: Displayed in the phonebook and used for Fork2Mobile and FastTransfer services.
- Service PIN: The code needed to access telephone services that require authentication (voicemail, switches, paging, electronic lock).
Account
Account
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Add existing account | Lets you link an existing SIP account to the extension. | Account |
| Create account | Lets you create a new SIP account to link to the extension. | Account |
Voicemail
Voicemail
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Create voicemail box | Lets you create a voicemail box for the account. | Yes / No |
| Email address | The address to which new message notifications are sent (optionally with audio file attached). | xxxxx@domain.yyy |
| Email notifications for new messages in voicemail box | If this option is enabled, the user will receive email notifications for new voicemail messages. | Yes / No |
| Forward audio messages as attachments | If this option is enabled, audio files containing recorded messages will be sent as email attachments. | Yes / No |
| Delete forwarded messages from Kalliope | If this option is enabled, forwarded messages will be deleted from KalliopePBX once the email is sent and will no longer be accessible from the phone and the KalliopeCTI mobile app. | Yes / No |
| Enabled | Lets you enable and disable voicemail without losing its settings and recorded messages. | Yes / No |
Local user settings
Local user settings
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Create local user | Lets you create a local user for KalliopePBX in order to enable GUI or CTI access. | Yes / No |
| Enable GUI access | Allows the user to access the web GUI as a standard tenant user. The role of the user can be changed on the users management page. | Yes / No |
| Enable CTI access | Allows the user to use the KalliopeCTI clients. In order to use KalliopeCTI Pro or Phone, you will need to add the license from the users management page. | Yes / No |
| Username | Username used for logging into the GUI or KalliopeCTI. | Alphanumeric |
| Password | Password used for logging into the GUI or KalliopeCTI. | Alphanumeric |
Template
Template
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Extension template | The template that contains the default parameters to use for the selected extension type. All attributes on the page will be changed to the default values, but it is possible to overwrite them if necessary. | Internal template |
Rubrica telefonica
Phonebook
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Show in local phonebook | Choose whether or not the extension is shown in the local phonebook. | Yes / No |
| LDAP publishing mode | How the extension is published to LDAP, among the available options. The general LDAP publishing rule is set in the LDAP settings page. | Disabled / LDAP publishing rule / Show the number below / LDAP publishing rule applied to the extension below |
| Custom LDAP extension | Extension to which the LDAP publishing rule is applied. This field will only be shown if the option LDAP publishing rule applied to the extension below is selected. | Numeric |
| Custom LDAP number | Phone number linked to the user in the LDAP phonebook. This field will only be shown if the option Show the number below is selected. | Numeric |
| Organization | Used when publishing the phonebook (corresponds to the organization attribute when publishing to LDAP). | Alphanumeric |
| Department | Used when publishing the phonebook (corresponds to the organizationUnit attribute when publishing to LDAP). | Alphanumeric |
Service classes
Service classes
| ||
|---|---|---|
Parameter |
Description |
Value
|
| Standard outbound routing class | The routing class applied to the user when the electronic lock is disabled. If the unlock mode is set to Open, this will be the class applied to all calls. | Outbound routing class |
| Restricted outbound routing class | The routing class applied to the user when the electronic lock is enabled. If the unlock mode is set to Open, this will never be applied. | Outbound routing class |
Limits
Limits
| |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Parameter |
Description |
Value
| |||||||||
| Concurrent call limit | The maximum number of allowed concurrent inbound and outbound calls on all accounts linked to the extension. Setting this limit to 1 will prevent the extension from accessing services such as attended transfer as the call on hold waiting to be transferred will still be considered active. | Numeric (0 = no limit) | |||||||||
| Busy level | The number of calls on all accounts linked to the extension after which the user is considered busy (the PBX will not present the call to the user's devices and answer with a 486 Busy Here SIP Message). Setting this limit to 1 for a single account will prevent inbound call notifications even if call waiting is enabled on the device. | Numeric (0 = no limit)
Electronic Lock
Open – The electronic lock is always disabled. Codice – Il lucchetto elettronico può essere sbloccato con il codice di sblocco definito nel piano di numerazione Password - Il lucchetto elettronico può essere sbloccato utilizzando il codice di sblocco e digitando successivamente il PIN dei servizi per l’interno |
Aperto / Codice / Password | ||||||||
| Politica di sblocco | Consente di scegliere la politica di sblocco per l’interno.
Per chiamata – Il lucchetto deve essere sbloccato prima di effettuare ogni chiamata Blocca automaticamente dopo il numero di minuti sottoindicato – Il lucchetto viene bloccato automaticamente allo scadere dell’intervallo indicato Sbloccato finché l’utente lo blocca nuovamente – Il lucchetto una volta sbloccato deve essere bloccato esplicitamente dall'utente |
Per chiamata / Blocca automaticamente dopo il numero di minuti sottoindicato / Sbloccato finché l’utente lo blocca nuovamente | |||||||||
| Durata dello sblocco (sec.) | Tempo dopo il quale l’interno viene bloccato. Applicabile solo se la politica di sblocco è Blocca automaticamente dopo il numero di minuti sottoindicato | Numerico | |||||||||
Prelievo di chiamata di gruppo
Parametro |
Descrizione |
Valore
|
|---|---|---|
| Gruppi di appartenenza | Elenco dei gruppi autorizzati a prelevare le chiamate dirette all’interno (le chiamate dirette a questo interno possono essere prelevate da tutti gli interni con autorizzazione al prelievo su uno di questi gruppi). | Gruppo di prelievo |
| Autorizzazione al prelievo | Elenco dei gruppi su cui l’interno è autorizzato a prelevare chiamate (l’interno può prelevare le chiamate dirette ad interni che hanno tra i gruppi di appartenenza un gruppo su cui l’interno è autorizzato al prelievo) | Gruppo di prelievo |
Trabocchi
Trabocchi
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Interno | Azione di trabocco su chiamate provenienti da un interno (anche remoto) | |
| Esterno | Azione di trabocco sulle chiamate provenienti dall’esterno | |
| Trasferimento | Azione di trabocco sui trasferimenti di chiamata | |
| Timeout (sec.) | Tempo alla scadenza del quale viene eseguita l’azione di trabocco configurata in caso di nessuna risposta | Numerico |
| Nessuna risposta | La chiamata è considerata senza risposta alla scadenza del timeout | Riaggancia / Selezione personalizzata / Chiedi selezione / Numero esterno / Interno / Gruppo / Coda / Controllo orario / IVR / Casella vocale / Stanza MeetMe |
| Occupato | L’interno è considerato occupato se è stato raggiunto il Busy Level impostato per l’interno oppure se il terminale invia il SIP Response 486 Busy Here | |
| Non disponibile | L’interno è considerato non disponibile se il terminale non è registrato o non è raggiungibile a livello IP oppure se il terminale invia il SIP Response 480 Temporarily Unavailable | |
Configurazione Account
Nel pannello Account sono definite le credenziali SIP utilizzabili da un dispositivo per registrarsi ed effettuare / ricevere chiamate tramite il KalliopePBX. A queste credenziali sono associati attributi per incrementare la sicurezza e modifiche del comportamento del KalliopePBX in termini di segnalazione e flussi audio da associare ad uno specifico dispositivo. Questi attributi sono definiti a livello di account e non di interno perché due account associati allo stesso interno ma a dispositivi differenti possono avere requisiti differenti.
Esempio: ad un interno posso associare un account utilizzato su un telefono fisico ed uno utilizzato su un softphone. Mentre per il telefono fisico posso utilizzare codec con maggior consumo di banda ad es. G711a per il softphone che viene utilizzato ad esempio in telelavoro posso scegliere di utilizzare codec quali il G729 che ottimizzano l’utilizzo della banda.
Per configurare gli account basta aprire il menu operativo e cliccare su PBX > Interni e Account. Per creare un nuovo account procedere cliccando su "Account" nella barra in alto e successivamente su "Aggiungi Account SIP"
- Abilitato: Consente di disabilitare un account senza perderne la configurazione
- KCTI Mobile App: Consente di utilizzare questo account con l'app mobile KalliopeCTI abilitando l'invio dei messaggi push per la segnalazione delle chiamate
- Nome utente: Username utilizzato per l’autenticazione SIP del dispositivo || Alfa-numerico
- Password: Password utilizzata per l’autenticazione SIP del dispositivo || Alfa-numerico
- Template dell'account: Indica il template account contenente i parametri di default da utilizzare per la tipologia di interno prescelta
- Abilita verifica di registrazione: Quando questa opzione è abilitata il KalliopePBX verifica che la richiesta di setup di chiamata (SIP INVITE) provenga dallo stesso IP:porta da cui ha ricevuto la richiesta di registrazione (SIP REGISTER)
- Indirizzo abilitato: Indica l’indirizzo ip o la subnet da cui il KalliopePBX accetta richieste di registrazione e setup di chiamata
- Maschera di sottorete abilitata: Completa l’informazione della ACL su base IP per le richieste di registrazione e setup di chiamata
- Abilita NAT: Quando questa opzione è abilitata il KalliopePBX ignora gli indirizzi IP presenti negli header SIP e SDP e risponde sempre all'indirizzo IP e porta da cui ha ricevuto la richiesta . Questa opzione deve essere abilitata solo per dispositivi si trovano dietro un NAT rispetto al KalliopePBX e che non risolvono il problema dell’attraversamento NAT (tramite STUN / ICE / ALG SIP).
- Abilita direct media: Questa opzione consente di instaurare dei flussi audio tra 2 PBX che si trovano in condizioni di visibilità diretta (no NAT). Se questa funzione è abilitata i servizi che richiedono il monitoraggio del flusso RTP (ad es. registrazione chiamate, trasferimento di chiamata e parcheggio con codici di servizio del KalliopePBX) sono disabilitati.
- Abilita SRTP: Questa opzione consente di abilitare il supporto alla cifratura dei flussi RTP. Poiché lo scambio delle chiavi avviene all’interno dei messaggi SIP / SDP in plaintext è opportuno utilizzare SRTP insieme alla cifratura della segnalazione mediante TLS. (vedi Configurazione TLS/SRTP)
Impostazioni di outbound proxy
Impostazioni di outbound proxy
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Indirizzo dell'outbound proxy | Consente di impostare l'indirizzo IP/hostname dell'outbound proxy da utilizzare | Alfa-numerico |
| Porta dell'outbound proxy | Consente di impostare la porta dell'outbound proxy da utilizzare | Numerico |
| Protocollo dell'outbound proxy | Consente di impostare il protocollo da utilizzare per comunicare con l'outbound proxy. È possibile impostare solamente protocolli abilitati nelle Impostazioni SIP | UDP / TCP / TLS / WS / WSS |
Impostazioni di trasporto
Impostazioni di trasporto
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Abilita trasporto UDP | Consente di abilitare il protocollo di trasporto UDP per la segnalazione SIP. Questa opzione non è presente se il trasporto UDP non è abilitato nelle Impostazioni SIP | Si / No |
| Abilita trasporto TCP | Consente di abilitare il protocollo di trasporto TCP per la segnalazione SIP. Questa opzione non è presente se il trasporto TCP non è abilitato nelle Impostazioni SIP | Si / No |
| Abilita trasporto TLS | Consente di abilitare il protocollo di trasporto TLS per la segnalazione SIP. Questa opzione non è presente se il trasporto TLS non è abilitato nelle Impostazioni SIP | Si / No |
| Abilita trasporto Web Socket | Consente di abilitare il protocollo di trasporto Web Socket (HTTP) per la segnalazione SIP. Questa opzione non è presente se il trasporto Web Socket (HTTP) non è abilitato nelle Impostazioni SIP | Si / No |
| Abilita trasporto Web Socket sicuro | Consente di abilitare il protocollo di trasporto Web Socket sicuro (HTTPS) per la segnalazione SIP. Questa opzione non è presente se il trasporto Web Socket sicuro (HTTPS) non è abilitato nelle Impostazioni SIP | Si / No |
Codec audio
Codec audio
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Aggiungi codec | In questa sezione è possibile selezionare e ordinare i codec audio utilizzabili dall'account (e che quindi verranno inseriti nella media description del protocollo SDP) | PCM a-law / G.722 / G.726 / G.729 / GSM / Opus / PCM u-law |
Codec video
Codec video
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Aggiungi codec | In questa sezione è possibile selezionare e ordinare i codec video utilizzabili dall'account (e che quindi verranno inseriti nella media description del protocollo SDP) | H.261 / H.263 / H.263+ / H.264 /VP8 |
Interno
Interno
| ||
|---|---|---|
Parametro |
Descrizione |
Valore
|
| Interno | In questa sezione è possibile selezionare l'interno al quale associare l'account SIP | Interno |