Configuring and Using SIP Domains in Asterisk

What are SIP Domains?

SIP requests delivered to a Proxy server or other SIP device must contain details of valid destinations and end-points that are to be reached or which are to receive responses. The address of a SIP device is generally referred to as its URI (Uniform Resource Identifier) – it has to uniquely define the location of the device on the Internet or within the scope of the network infrastructure that is being used. SIP URI’s are written in the form “sip:number@sip_domain”. This has many similarities with the very familiar format used for email addresses.

A SIP Domain represents a place-holder for a collection of SIP addresses that share a common home. That home is not necessarily a physical location or a server, but could be an organisation or business. Equally it could be a VoIP hosting service such as callcentric, voiptalk, sipgate etc. When looking at the hosted service scenario, there are useful parallels to be drawn between hosted SIP services and hosted email services such as gmail.

SIP Domains and DNS

Just as for email domains, the mechanism that allows SIP domains to be converted into IP addresses is DNS. For situations where DNS resolution is not possible, the IP address of the relevant SIP Proxy server or Asterisk server may be used instead. However, this is not the preferred option and should be regarded as distinctly “second best”, especially for any public VoIP service that is reached via the Internet.

DNS provides two possible mechanisms for resolving SIP Domain Names

  1. Host records
  2. SRV records (for a description, look at the Wikipedia entry for SRV Records)

Host records provide the conventional mappings from host.domain to IP address, or simply domain to IP address.

SRV records provide a more sophisticated solution, and in many ways they are equivalent to the MX record in email. However, they are far from universally used in the World of SIP and consequently many VoIP service providers don’t bother with them. Most IP phones include an option to use SRV records to resolve domain names, but the default setting is usually “off”. This is something of a shame because they provide a much more powerful solution than simple host name resolution – SRV records can specify which communication protocol should be used (UDP or TCP) and also it is possible to have more than one SRV record for the same SIP domain so an element of failover or redundancy can be incorporated into the SIP client’s behaviour.

Note: For an organisation that wants to operate its own SIP domain, there might be a temptation to use the same company domain name for SIP as is used for the web site and for email. However, it would be difficult to manage the DNS correctly if the same domain name was used for web, email and SIP. In practice, it is best if the SIP domain is the host name of your SIP Proxy server or, better, a new dedicated domain name used only for SIP.

Asterisk SIP Domains

SIP Domains are defined in SIP.CONF (chan_sip only)
SIP domains can be defined in the SIP.CONF file, although their use is optional. When used, they provide enhanced security because registrations will only be accepted when they come from an IP phone (or other SIP client) that is using one of the recognised domains. When Asterisk knows the identity of all its local SIP domains, this allows a higher level of security in the routing of SIP-to-SIP calls too – see the option “allowexternaldomains”.

In the general section of SIP.CONF you can define domains using either (or both) of the following parameters:

  • domain=name,context
  • autodomain=yes

The domain parameter is used to explicitly define one domain. If you have more than one, simply add as many new lines as required with one domain definition on each. Note that the second parameter “context” is optional – it is discussed in more detail below.

The autodomain parameter can be set to “yes” or “no”. When autodomain is enabled, Asterisk will create a domain with the same name as the host machine. It may also create some other domains based on DNS lookups and known IP addresses. For example, it may create domains based on the values given for the parameters “bindaddr” and “externip”. To check the list of domains created by autodomain, go to the Asterisk CLI and type “sip show domains” – look for those with [Automatic] in the column “Set by”.

Using Asterisk without support for SIP domains
If no domains are explicitly defined and the autodomain option is set to “no”, then Asterisk relaxes its security and operates as if all SIP domains are valid. You can see if Asterisk is operating with no support for SIP domains, by issuing the command “sip show domains” at the CLI.

We recommend that support for SIP domains is enabled because it provides greater security and, potentially, greater flexibility in the dial plan.

What do Asterisk SIP domains do?

Asterisk’s SIP domains don’t initially stand out as being very important, but they actually play a useful role both for server location and client authentication. Furthermore, they can have a profound influence on call routing when a context is specified alongside the domain name. This is because Asterisk treats the “domain context” as the highest ranking location for the starting point of your dial plan (the dial plans are located in extensions.conf). To summarise, SIP domains have a threefold purpose within Asterisk:

1. Server location
Depending on your ability to access and modify DNS settings, it is possible to set up one or more Asterisk SIP domains that match appropriate DNS records and allow users to put a human-readable domain name into the relevant field on their IP phones. This makes it much easier to configure the IP phone and also means that you can move your Asterisk server to a new IP address with just a few changes to your DNS records.

2. Authentication during registration
Asterisk will normally only allow a SIP client to register if the SIP domain being used by the client matches one of its local SIP domains. By default, when you first start using Asterisk it will either disable domain support altogether or will include its own IP address as an “automatic” domain. This means you should be able to use the IP address of the Asterisk server when configuring an IP phone as a local extension, or other client device.

3. Dial plan identification
As mentioned above, the context given alongside the domain name in SIP.CONF takes precedence over all other contexts that you might have included elsewhere in SIP.CONF. Failure to appreciate this could lead to confusion during configuration and testing of SIP clients.

Example SIP.CONF entries that determine SIP Domains

Here is a sample snippet from the opening section of Asterisk’s SIP.CONF file. It includes a number of parameters relevant to Asterisk’s handling of SIP domains:

[general] context = sip-in
bindport = 5060
bindaddr =

; sip domain settings

autodomain = yes
domain = smartvox.local
domain =
domain = sip1.smartvox.local,sip1-in
domain = sip2.smartvox.local,sip2-in
realm = asterisk

; sip-to-sip security related settings

allowexternaldomains = no
allowguest = no

Let’s look at each of the parameters from the sample and discuss what they mean:

context: This sets the default dial plan context for all inbound SIP calls to your Asterisk server. The default can be over-ridden in other parts of the sip.conf file, but in the absence of a more specific context selection this will be the context used to route a SIP call arriving at your server. Dial plan contexts are located in extensions.conf.

bindport and bindaddr: Tells Asterisk which ethernet port and interface to use for SIP messages. If your Asterisk server has more than one interface and you want to be able to handle SIP requests at all of them, you can set “bindaddr=”. It will then accept incoming requests on any interface. SIP packets that it sends to other devices will be routed according to the host machines normal IP routing rules – these can be checked and modified using the Linux route command.

autodomain: This is an important setting with respect to SIP domains. When it is set to “no”, Asterisk will only recognise domains that were explicitly defined or will simply not support SIP domains at all (if there were no explicitly defined domains). If you set it to “yes” please be aware that Asterisk will create a domain based on the external IP address of your firewall as specified in the “externip” parameter. This might represent a compromise on your SIP security. If you don’t want a domain to be created based on “externip”, then set “autodomain=no” and explicitly add domains for your local (internal) IP address and for any other domains you require.

domain: This parameter is used to explicitly add domains. Use this to add domains that were not automatically created by “autodomain” or to add all domains if you chose to set “autodomain=no”. You can add as many domains as you like – enter the details for each new domain on a new line in sip.conf.

Note how the third and fourth examples in the above sample have a second value appended after the name of the domain. This second value is the name of the context that will be used for the dial plan for all calls sent to this domain. This will include calls made from local IP phones if the IP phone used this domain name in its SIP account information.

realm: SIP authentication is generally based on the exchange of encrypted usernames and passwords. The SIP protocols have been designed to support relatively complex authentication scenarios – for example, SIP client A makes a call via SIP Proxy Server B which forwards the request to SIP Proxy Server C which forwards the request to remote SIP client D. In these more complex scenarios it is possible that the list of usernames/passwords known to SIP Server B is completely different to the list known to SIP Server C. To accommodate the anticipated requirement to be able to authenticate at third-party servers, the SIP protocol uses the concept of “realms”. A realm essentially identifies a security boundary. You don’t just request a password to match the given username, but you also specify which security realm the username/password exists in. I have not so far found a case where the realm setting needed to be anything other than the default value “realm=asterisk”. If anyone reading this is aware of a scenario where realm makes a difference, please let me know.

allowexternaldomains: Tells Asterisk whether or not to allow SIP-to-SIP calls to non-local domains. The default setting for this option is “yes”.

allowguest: Tells Asterisk to allow or reject guest calls.

Checking the list of supported SIP domains

When you have finished editing the sip.conf file, you will need to tell Asterisk to reload the file. You do this at the Asterisk CLI (Command Line Interface) by typing the command “sip reload”. Now you should check the domain list using the command “sip show domains”.