Phones

Phones

Estimated reading time: 13 min.

In this menu you edit the SIP setting for a SIP device. In general this is a phone, but it might be a door entrance system, a video surveillance system or an ATA.

The PBX is at it’s best if the settings of SIP devices are kept simple. The PBX user is where you link the specific and more advanced settings to. The SIP device can be used to make restrictions. For example, a phone in a public space can set up to only be able to call the emergency services. Or if you use the PBX as a multi-tenant system, you have the option to instruct the (physical) SIP device to go out via a specific trunk. This allows for controlled billing and to separate user groups. To an end-user, all this is transparent, e.g. the end user does not need to have a clue these restriction apply.

The phone grid

The phone grid gives you an overview of the basic settings of your phone. For the actual registration status and details of the capabilities, use the status screen.

The grid gives the default edit/add/remove buttons and also access to the global settings.

Global Settings

In this menu the settings defined are applied to all SIP devices that have the “use global settings” checked.

Tab General

The phone grid gives you an overview of the basic settings of your phone. For the actual registration status and details of the capabilities, use the status screen.

Recommended defaults should work fine. If you want to use different FQDN you can disable ‘use default address’ and specify a PBX Address at your own choice.

Encryption

Version 4.1.0 introduced SIP/TLS + SRTP support. The easiest way to setup encryption is to use our zero-touch provisioning as recommended settings will be set for you.

When using encryption you have the choice of encrypting both signalling and media or only signalling. Specific phones can be excluded phones by editing the phone and setting encryption to ‘off’ in the phone (encryption tab). This can be useful if e.g. only some of your phones support encryption.

Codecs

Only make changes here if you know what you are doing. Setting this incorrectly can result in poor sound quality and/or very limited number of concurrent calls. If not set properly the PBX will do codec translation this is a very expensive and CPU intense process, that will affect the performance of your system. Make changes here with care and verify your system is not transcoding.

What Codec to use or to force with your SIP provider? The default value works just about always when the Axeos software is used in Europe. No need to make changes here.

Extra config

Version 4.1.3 introduced a new feature: you can now edit phone config files and templates from the web interface via the ‘extra config’ tab in Phones/Global Settings (template) and the Phones/Phone edit dialog (phone config). This means you no longer need to use FTP to customize configurations.

  • If you want to upgrade a pbx running 4.1.2 firmware or older please be aware that template files (e.g. /templates/yealink/yealinkT4x-template.cfg) will be overwritten with a new default template. This is necessary in order to be able to facilitate the ‘extra config’ feature introduced in 4.1.3. Create a backup first.
  • Note that when your phones ‘write config file’ setting is set to ‘once’ or ‘never’ the phone config files are not overwritten (but the templates are).
  • Prior to upgrading you should backup your template files and phone config files. You can do this by either downloading a pbx backup from the ‘tools’ menu, of by downloading the files through FTP.
  • After upgrading you can add your template customisations in the ‘extra config’ tab in communication/phones global settings, and your phone-specific customisations in the ‘extra config’ of the of phones in communication/phones. Unfortunately this is an action that requires your manual input as this cannot be automated.
  • In order for the added custom values to be written to file you will need to set the ‘write config file’ setting to ‘always’.

  Only add extra custom settings in the extra config tab (do not copy-paste the full template contents).

Using this ‘extra config’ adds settings to MAC-address-oriented config files (<MAC>.cfg for Yealink devices or for Snom devices snom3xx-<MAC>.xml etc). The extra configuration settings added via the web interface are added at the end of the file (search for “Global settings extra configuration” and “Phone extra configuration” comments).

This extra config can overwrite configs generated by PBX from the template so e.g. an overwritten voicemail number will not work. If you run into issues like that simply remove the extra config you added and re-provision or factory restart the phone.

Changes can be done:

  • for the phone model in global settings (you can add something to your 30 YealinkT23 with just one edit and “OK”)
  • for one phone in phone edit dialog

When you use this you will need to take the following into account:

  • Yealink
    • The PBX updates the label for linekey1 so if you changed it in ‘extra config’ it will be overwritten when phone/user presence changes. Any other data generated by the pbx in the config file can be changed.
    • Some settings, e.g. security settings, may trigger the phone device to reboot.
  • Snom:
    • See Yealink, the same applies to Snom.
  • Cisco SPA:
    • Be very alert when making changes, as even a typo in SPA template can cause the phone device to start rebooting in a loop.
    • Some settings may trigger a few consecutive reboots, be patient.
  • Aastra – Some settings may trigger phone reboot
  • Tiptel – Some settings may trigger phone reboot

Please note that the ‘extra config’ tab does not support internal variables used in template files such as ${(user.userName). Do not use “if” statements or variables with ${.

Please do not change Display name and Label for your phones. This is useles as the PBX will overwrite these to keep them consistent with PBX user names.

If you’re using the Yealink Configuration Generator Tool: the labels can be a bit misleading. If you use their CGT please note that the Extension is for pickup code, the value is for the PBX extension you want to subscribe to. E.g.:

Global settings encryption

Version 4.1.0 introduced SIP/TLS + SRTP support. Default setting is off, which offers you the ability to set one phone to ‘on’ and play around, before enabling encryption for all devices.

The easiest way to setup encryption is to use our zero-touch provisioning as recommended settings will be set for you.

When using encryption you have the choice of encrypting both signalling and media or only signalling. Specific phones can be excluded phones by editing the phone and setting encryption to ‘off’ in the phone (encryption tab). This can be useful if e.g. only some of your phones support encryption.

If you know what your’re doing and choose not to use zero-touch provisioning the PBX allows you to use a variety of settings:

  • Encryption: off, signalling & media, signalling only
  • Media encryption type: DTLS, SDES
  • DTLS setup: actpass, active, passive
  • DTLS verify: certificate, fingerprint, nothing
  • DTLS fingerprint: SHA-256, SHA-1

Please note that Snom only supports SDES for SRTP key exchange (no DTLS).

  • We’ve added “Sip/TLS Signalling” protocol to the firewall (system/firewall) now. You will need to use this rule if you want to use call encryption.
  • We recommend using a valid certificate. You can purchase one, and we facilitate using free Let’s Encrypt certificates. Be aware that changing or renewing the certificate (the latter is done automatically when using Let’s Encrypt) requires asterisk to reload. You can do this via Status/Services.Check Communication/Phones Global Settings
  • Make sure you have correctly set the “PBX address” field. This address should match the common name in your certificate or encryption will fail.
  • After encryption is enabled your phone(s) need to be re-provisioned.

if you are using custom configs (and want to use encryption) then you should add/edit these settings in your config files:

${systemConfig.pbxIp!} to ${systemConfig.pbxAddress!}

Snom:
${systemConfig.pbxAddress!};transport=tls
on
on
mandatory

Yealink:

security.cn_validation = 1
account.1.sip_server.1.transport_type = 2
account.1.srtp_encryption = 2

Aastra:
Aastra phones will need an additional line:

sips trusted certificates: certfilename.pem

Aastra phones will look for a certificate file in its directory.

sip transport protocol: 4
sips persistent tls: 1
#Persistent TLS requires the outbound proxy server and outbound proxy port.
sip outbound proxy: ${systemConfig.pbxAddress!}
sip outbound proxy port: 5061
sip srtp mode: 2

Please note that some Aastra firmware versions have a bug and require changes for proxy as well.

Tiptel:
Also requires certificate, crt file can be uploaded

account.1.transport = 2
account.1.srtp_encryption = 1

Tab phone

This tab holds the account related options of a phone. Here one can set the phone provisioning and if the phone is part of a callpickupgroup. Be aware that this a “physical” phone features which restricts flexibility. Use the end user interface to avoid this restriction.

  • Phone type: list of phone that can be auto-provisioned
  • Phone mac: the mac address of the phone needed to be able to provision the phone
  • Phone IP: you can be very strict and accept only a specific IPv4 address of a phone. By default any SIP registered will be used.
  • Name: the name of to be used when using the phone in a simple set up. This can hold the name of the user. You can use any name if you use PBX users instead of the simple set up
  • Username: (formerly ‘SIP login’) the login ID of the physical device. It is recommend to use the auto-generated string this enhances security. This login is not needed by end-users. With this the phone can SIP register itself and thus is then known by the PBX and can be found for inbound calls
  • Password: the password the phone must use for registration. Use the system generated passwords for random passwords
  • CallerID: instruct the phone to use a specific outgoing callerID or call out anonymous. when empty the outbound trunk setting is used. If callerID is set in the PBX user menu then the callerID of the user overrules this setting.
  • Language: language for the provisioning files
  • Permissions: what Permission profiles to apply. By default the default profile (=no restriction) applies.
  • Write config:
    • Always: generate a new config file when making changes in the settings
    • Delete: remove config file if any exist
    • Never: will not generate any config files. Useful when you want to use your own config files.
    • Once: generate a new config file if it does not exists. Useful when you want customize generated config files.
  • Vendor auto-provisioning: Set zero-touch vendor autoprovisioning on/off for this device.
  • Is pick-up group: a comma separated list of which callpickup group this phone is part of
  • Can pick-up groups: a comma separated list of groups this phone is allowed to pick up calls for
  • Allow hot desking: allow a PBX user to log on to this phone.
Please note that pickup groups and grab groups are not the same. Using the grab groups allows you to grab a call from the web interface (Mysettings/calls) where the pickup group (set in Communication/Phones) allows you to pickup a call using *8 from your phone. Be aware that:
  • ** is used when you want to pick up a specific ringing phone. For example dial **201 on your phone would pick up phone 201 if that is ringing. Please note that for this feature to work your inbound dial plan must use local extensions as actions. Eg. when you directly call a voip phone call pickup will not work.
  • *8 is a call pickup group. it would pick up phone 201 as well, if the user and the related to the ringing phone are in the same call pickup group. This setting is controlled in pickup group in tab phones and cannot be assigned to Phones/SIP login.

Also note that this does not work on calls that come in through an ACD.

Tab additional

Call behaviour and some network settings of the phone. The defaults used apply in most cases. Please note by default the custom outbound trunk points to the default trunk. Only for documentation purposes the custom outbound trunk is set in this example. In a simple set up you do not need to set custom Outbound trunk, Dial prefix and Outbound plan.

  • Custom outbound trunk: force outbound calls from this phone to use a specific trunk, for restrictions or billing purposes. Please note when you set custom outbound trunk for a phone, then you need to set the custom caller-id in the phone configuration too. See Phones → phone Tab → Caller ID field
  • Dial prefix: if custom outbound is set, what prefix to use. In most cases you’d leave this empty. If you do enter a prefix here your users have to use (only) this prefix in order to be able to call out.
  • Outbound plan: if using a custom trunk you can also select a specific outbound dial plan for more control on the outbound traffic
  • Context: what is this device part of default is internal. Other values bases on license are external or hotel
  • Smart routing: enable or disable SIP reINVITE. By default set off to avoid NAT trouble. Be aware that using smart routing might lead to 1-way audio issues as many firewalls do not allow using a new port to keep traffic locally. That’s a firewall problem, not a PBX problem. Smart routing is generally not recommended in common use cases.
  • DTMF mode: default RFC-2833. Other values are inband or info
  • NAT: default means enabled, it will add extra information about where the device is. Default this is enabled as it has no implication on in a non-NAT environment
  • Port: what service port to listen on
  • Keep alive: use SIP OPTIONS to force a firewall to keep its port open. Default enabled
  • Call limit: how many channels can be open in one given time
  • Account code: code that can be used for simple billing purposes, this is not meant for exact cost calculation
  • SIP transport: what IP protocol to use default is UDP which is recommended for VoIP traffic. Other options UDP, TCP and combination of the two.
  • Auto-answer header: what SIPheader to user along with ‘autoanswer’ option. This can be changed for ‘generic sip phone’, if default value does not work with your phone model try ‘Alert-Info: ;info=alert-autoanswer’.

Tab encryption

You can exclude phones by editing the phone and setting encryption to ‘off’. By using ‘default’ settings in the phone the pbx will look at the phones Global Settings. You can also leave encryption off in global settings and simply set it on for one device. This makes setting up a lot easier and doesn’t impact the other phones.

The easiest way to setup encryption is to use our zero-touch provisioning as recommended settings will be set for you.

When using encryption you have the choice of encrypting both signalling and media or only signalling. Specific phones can be excluded phones by editing the phone and setting encryption to ‘off’ in the phone (encryption tab). This can be useful if e.g. only some of your phones support encryption.

If you know what your’re doing and choose not to use zero-touch provisioning the PBX allows you to use a variety of settings:

  • Encryption: off, signalling & media, signalling only
  • Media encryption type: DTLS, SDES
  • DTLS setup: actpass, active, passive
  • DTLS verify: certificate, fingerprint, nothing
  • DTLS fingerprint: SHA-256, SHA-1

Please note that Snom only supports SDES for SRTP key exchange (no DTLS).

  • We’ve added “Sip/TLS Signalling” protocol to the firewall (system/firewall) now. You will need to use this rule if you want to use call encryption.
  • We recommend using a valid certificate. You can purchase one, and we facilitate using free Let’s Encrypt certificates. Be aware that changing or renewing the certificate (the latter is done automatically when using Let’s Encrypt) requires asterisk to reload. You can do this via Status/Services.Check Communication/Phones Global Settings
  • Make sure you have correctly set the “PBX address” field. This address should match the common name in your certificate or encryption will fail.
  • After encryption is enabled your phone(s) need to be re-provisioned.

if you are using custom configs (and want to use encryption) then you should add/edit these settings in your config files:

${systemConfig.pbxIp!} to ${systemConfig.pbxAddress!}

Snom:
${systemConfig.pbxAddress!};transport=tls
on
on
mandatory

Yealink:

security.cn_validation = 1
account.1.sip_server.1.transport_type = 2
account.1.srtp_encryption = 2

Aastra:
Aastra phones will need an additional line:

sips trusted certificates: certfilename.pem

Aastra phones will look for a certificate file in its directory.

sip transport protocol: 4
sips persistent tls: 1
#Persistent TLS requires the outbound proxy server and outbound proxy port.
sip outbound proxy: ${systemConfig.pbxAddress!}
sip outbound proxy port: 5061
sip srtp mode: 2

Please note that some Aastra firmware versions have a bug and require changes for proxy as well.

Tiptel:
Also requires certificate, crt file can be uploaded

account.1.transport = 2
account.1.srtp_encryption = 1

Tab codecs

What codecs to use. Keep the default values. If you set this incorrectly it can degrade your voice quality. If the PBX must do transcoding between e.g. ulaw and alaw it uses a lot of CPU resources. This significantly limits the number of concurrent calls. Make sure you know what you are doing when changing these settings. A video codec is possible as well but is only pass-through and will only work if the end-points can talk to each other. For this to work you must have smart routing enabled.

g729 codec support ended with Axeos version 4.0. We strongly advise you to not upgrade your 3.4.7 pbx to 4.0 if you require this codec, but please be aware of this codecs inherent disadvantages: dual-tone multi-frequency signaling (DTMF), fax transmissions, and high-quality audio cannot be transported reliably using the g729 codec. The GSM codec can be a valid alternative choice for your low-bandwith codec needs.

Tab User groups

You can assign this phone to a user group. Making it invisible to other user groups. You can use this for multi-tenant functions.

Tab Extra Config

As described above version 4.1.3 introduced a new feature: you can now edit phone config files and templates from the web interface via the ‘extra config’ tab in Phones/Global Settings (template) and the Phones/Phone edit dialog (phone config). This means you no longer need to use FTP to customize configurations.

  • If you want to upgrade a pbx running 4.1.2 firmware or older please be aware that template files (e.g. /templates/yealink/yealinkT4x-template.cfg) will be overwritten with a new default template. This is necessary in order to be able to facilitate the ‘extra config’ feature introduced in 4.1.3. Create a backup first.
  • Note that when your phones ‘write config file’ setting is set to ‘once’ or ‘never’ the phone config files are not overwritten (but the templates are).
  • Prior to upgrading you should backup your template files and phone config files. You can do this by either downloading a pbx backup from the ‘tools’ menu, of by downloading the files through FTP.
  • After upgrading you can then add your template customisations in the ‘extra config’ tab in communication/phones global settings, and your phone-specific customisations in the ‘extra config’ of the of phones in communication/phones. Unfortunately this is an action that requires your manual input as this cannot be automated.
  • In order for the added custom values to be written to file you will need to set the ‘write config file’ setting to ‘always’.

  Only add extra custom settings in the extra config tab (do not copy-paste the full template contents).

Using this ‘extra config’ adds settings to MAC-address-oriented config files (<MAC>.cfg for Yealink devices or for Snom devices snom3xx-<MAC>.xml etc). The extra configuration settings added via the web interface are added at the end of the file (search for “Global settings extra configuration” and “Phone extra configuration” comments).

This extra config can overwrite configs generated by PBX from the template so e.g. an overwritten voicemail number will not work. If you run into issues like that simply remove the extra config you added and re-provision or factory restart the phone.

Changes can be done:

  • for phone model in global settings (yep, you can add something to your 30 YealinkT23 with just one edit and “OK”)
  • for one phone in phone edit dialog

When you use this you will need to take the following into account:

  • Yealink
    • The PBX updates the label for linekey1 so if you changed it in ‘extra config’ it will be overwritten when phone/user presence changes. Any other data generated by the pbx in the config file can be changed.
    • Some settings, e.g. security settings, may trigger the phone device to reboot.
  • Snom:
    • See Yealink, the same applies to Snom.
  • Cisco SPA:
    • Be very alert when making changes, as even a typo in SPA template can cause the phone device to start rebooting in a loop.
    • Some settings may trigger consecutive reboots.
  • Aastra – Some settings may trigger phone reboot
  • Tiptel – Some settings may trigger phone reboot

Please note that the ‘extra config’ tab does not support internal variables used in template files such as ${(user.userName). Do not use “if” statements or variables with ${.

Please do not change Display name and Label for your phones. This is useles as the PBX will overwrite these to keep them consistent with PBX user names

Was this article helpful?
No