About the examples and conf file samples used in this article
The following sections will guide you through the setup of a small Asterisk system using shared line appearances. Each step is explained to show how it works. The dial plan examples will start with a fairly simple configuration and we will then gradually improve the dial plan to make it handle a broader range of user actions.
All examples are based on a setup with two IP phones being used as extensions (or stations) and two shared trunk lines. The device types used for the trunk lines are not completely fixed and may vary a little from example to example – this is to show you how the configuration would be done for different technologies. For example, we will illustrate how to use zap FXO trunks, Pika FXO and a single channel SIP account such as you might have with a VoIP service provider.
The examples are taken from a test rig using a Grandstream GXP2000 configured as extension 4001 and an Aastra 53i configured as extension 4003. Details for other makes and models of phone will be added as and when those phones become available for inclusion in our test rig. If you are in a position to provide an IP phone on loan that you would like to see included then please contact John using the phone or email contact details provided on this web site.
Dial patterns used in the examples
The dial plans on the test rig are based on the assumption that internal extensions all have 4 digit numbers – analogue extensions are 3001, 3002, etc and IP phones are 4001, 4002, 4003 etc. PSTN numbers are assumed to start with zero and to be more than 5 digits long.
The SLA.CONF configuration file
Core entities: Trunks and Stations
SLA.CONF contains definitions for the participating trunk lines and “stations” (i.e. extensions) within your system. The trunk definitions have “type=trunk” and the extensions have “type=station”. Each definition starts with a name tag in square brackets. The names you use for the entities in SLA.CONF are arbitrary, but in general you should choose short meaningful names (the names you use here must later be matched to entries you will be adding within the dial plan and when configuring your IP phones – hence the choices you make here are important).
The convention in nearly all the examples I have seen is to call the trunk objects “line1”, “line2” etc. The name tags you use for the stations should clearly describe the extension they refer to, avoiding any possibility of ambiguity. The convention adopted by the author and used in all the examples here is to prefix the actual extension number with 8*. For example, extension 4001 is given the name tag “8*4001” and 4002 becomes “8*4002”. This convention has been chosen for sound reasons – firstly, it is important to avoid using just the extension number alone because this could lead to ambiguity in the dial plan. The choice of “8*” is based on the following:
- It is easy to read and see the actual extension number because * provides a visual break
- It is unlikely that a user would accidentally dial 8* from their phone
- It is known to work correctly on the IP phones tested (some prefixes did not)
- It is tested and known to correctly match number patterns such as “_8*40.” in the dial plan. Some other prefixes we tried did not.
The device parameter has a different role in trunks than it has in stations. For the trunks, it tells Asterisk how to get access to the relevant trunk line when the user wants to make a call. For the stations, it tells Asterisk what device to ring when an inbound call arrives on a trunk. For greatest flexibility, we recommend that you set the trunk device to “Local” with a start point in your dial plan similar to the example below.
Configuring a trunk line
Here is an example section from SLA.CONF showing the parameters used to define trunk line 1.
The device parameter tells Asterisk what to do when a user presses the programmed key on their phone to seize a trunk line and make an outbound call. If you are using Zap ports for the trunks, then Asterisk will recognise a definition such as “device=Zap/1”. However, if you want to use non-Zap ports then you should use a setting such as the one shown in the above example. By using “Local” followed by a start point in extensions.conf, you can control how Asterisk seizes the line. The start point in our example would be in the context [line1-out] at priority 1 of the section defined for extension “sla”. A line such as this:
|[line1-out] exten => sla,1,Disa(no-password|fxo-out)|
The dial plan associated with dialling and making outbound calls is explained in more detail later here.
The ringtimeout parameter determines for how long (in secoonds) an incoming call should ring before the SLATrunk function returns with a RINGTIMEOUT result. For more details see the explanation for the SLATrunk function below.
The barge parameter determines whether other extensions are permitted to join an existing call in a conference by pressing their shared line key. If extension A answers the call on line 1, the lamp for line 1 will be lit on all the other participating extensions. At this point, if a user at extension B presses the key for line 1, they will become conferenced with the existing call. Setting “barge=no” would prevent this from happening. The default setting is “yes”.
The hold parameter determines whether a call placed on hold by a particular extension can be retrieved from hold by other stations. It takes one of two values: “open” or “private”. The default option is “open”, meaning that any other extension participating in SLA can retrieve a call that has been put on hold. The alternative, “private”, means that only the extension that put the call on hold is allowed to retrieve it.
Configuring an extension or “Station”
Here is an example section from SLA.CONF showing the parameters used to define extension 4001.
; Grandstream GXP2000
The device parameter tells Asterisk which device to ring when an incoming call arrives on an associated trunk line. In the example shown above, we have said that SIP extension 4001 should ring immediately any call arrives on line1 or line2. It is permitted to have many “station” entities participating in SLA thereby allowing multiple extensions to ring simultaneously when an incoming call arrives.
The ringdelay parameter determines a delay (in seconds) before this extension should start ringing. The timer starts when the SLATrunk function is called from within the dial plan. You can set different ringdelay values against each trunk line if you want – this option allows quite complex ringing patterns to be programmed for different trunks and different extension phones.
The ringtimeout parameter determines how long the ringing should last at this station. You can set different ringtimeout values against each trunk line if you want – this option, when used in conjunction with ringdelay, allows quite complex ringing patterns to be programmed such as delivering a splash ring on secondary extensions if an incoming call has not been answered within, say, 20 seconds.
The trunk parameter tells Asterisk which trunk lines are presented at this extension. What do I mean by “presented”? It means two things – first it defines for which trunks this phone should ring (i.e. when an incoming call arrives on the trunk); second, it tells Asterisk to expect that this extension phone has got programmed keys assigned to those trunk lines. Asterisk will maintain an array of internal states for the shared line keys it knows are on the phone and will accept SUBSCRIBE requests that are mapped to those line states from the phone.
Tip: Although it is not stated in the developer’s documentation, it does not actually matter if the phone doesn’t have any programmed keys assigned. This means you could, for example, make an analogue extension be part of the ring group. It would not have any shared line keys so you would not get a lamp showing line activity and it would be difficult for the phone to participate in other SLA features like call transfer, but it would ring and could therefore answer incoming calls.
Configuring the Aastra 53i Phone for SLA
Configuring the Global SIP Account
SIP Accounts are configured under the Advanced Settings section of the web admin page. In our example, the Aastra is linked to a pre-defined user account in Asterisk – username and extension number are both set to 4003.
Using the web interface, login as admin then select Advanced Settings|Global SIP
On this page you should program default settings for SIP registration and the addresses and port numbers for the various SIP servers (Proxy, Outbound Proxy and Registrar). These will usually all be set to point to your Asterisk server – probably using the default SIP port of 5060. Note that Line Mode is left as “Generic”.
Configuring SIP Accounts for Lines
The Aastra-53i allows accounts to be created for up to 9 lines, although only the first three have line keys on the phone set. If you want, you can associate a different SIP user account with each line. Furthermore, under Preferences, there is an option to set which line account is the preferred one. However, if you don’t have a specific need for multiple accounts, keep things simple and for line 1 just use the same login details already given in your Global SIP account. Lines 2 to 9, just leave blank.
Using the web interface, login as admin then select Advanced Settings|Line 1
To use the default settings from the Global SIP account, you can leave various fields with their default values. For example, Server addresses can be left as 0.0.0.0 and port numbers can be left as 0. The Global defaults are then used. However, if you enter new data into some of the fields for Caller ID, Authentication and Password, then it is best to enter values for all of these fields. Leave Line Mode set to “Generic”.
Configuring the Programmable Keys
Using the web interface, login as admin then select Operation|Programmable Keys
Using the drop-down selector, set Type to BLF.
Value must be set to a combination of the name tags used in SLA.CONF to describe the station and the line (linked by the underscore character). For example, if the station is referred to as 8*4001 in SLA.CONF and each trunk line was named line1, line2, etc, then Value would be set to:
Line is used to select one of the phone’s lines. If the Global SIP account is used for this purpose then you can set Line to global.
Configuring the Grandstream GXP2000 Phone for SLA
Using the web interface, login as admin then select BASIC SETTINGS
Scroll down to the section where the “Multi Purpose Keys” are defined. Using the drop-down selector, set Key Mode to Busy Lamp Field (BLF).
UserID must be set to a combination of the name tags used in SLA.CONF to describe the station and the line (linked by the underscore character). For example, if the station is referred to as 8*4001 in SLA.CONF and each trunk line was named line1, line2, etc, then UserID would be set to:
The box labeled Name is used to display information on the LCD screen and you should enter a short text description such as “Trunk Line 1” or “Shared Line 1” or whatever you want.
Account is used to select a SIP user account. It should be the account the phone uses to register with Asterisk.
For part 3 of this article, click here