Outside Connectivity(Asterisk)-I
The architecture of Asterisk is significant, due in large part to the fact that it treats all channel types as equal. This is in contrast to a traditional PBX, where trunks (which connect to the outside world) and extensions (which connect to users and resources) are very different. The fact that the Asterisk dialplan treats all channels in a similar manner means that in an Asterisk system you can accomplish very easily things that are much more difficult (or impossible) to achieve on a traditional PBX.
This flexibility does come with a price, however. Since the system does not inherently know the difference between an internal resource (such as a telephone set) and an external resource (such as a telco circuit), it is up to you to ensure that your dialplan
handles each type of resource appropriately.
The Basics of Trunking
The purpose of trunking is to provide a shared connection between two entities. For example, a trunk road would be a highway that connects two towns together. Railroads used the term “trunk” extensively, to refer to a major line that connected feeder lines together.
Similarly, in telecom, trunking is used to connect two systems together. Carriers use telecom trunks to connect their networks together, and in a PBX, the circuits that connect the PBX to the outside world are commonly referred to as trunks (although the
carriers themselves do not generally consider these to be trunks). From a technical perspective, the definition of a trunk is not as clear as it used to be (PBX trunks used totally different technology from station circuits), but as a concept, trunks are still very
important. For example, with VoIP, everything is actually peer-to-peer (so from a technology perspective there isn’t really such a thing as a trunk anymore), but it is still useful to be able to differentiate between VoIP resources that connect to the outside world and VoIP resources that connect to user endpoints (such as SIP telephones).
It’s probably easiest to think of a trunk as a collection of circuits that service a route. So, in an Asterisk PBX, you might have trunks that go to your VoIP provider for long- distance calls, trunks for your PSTN circuits, and trunks that connect your various offices together. These trunks might actually run across the same network connection, but in your dialplan you could treat them quite differently.
While we believe that VoIP will eventually completely replace the PSTN, many of the concepts that are in use on VoIP circuits (such as a “phone number”) owe their existence more to history than any technical requirement, and thus we feel it will be helpful to discuss using traditional PSTN circuits with Asterisk before we get into VoIP.
Fundamental Dialplan for Outside Connectivity
In a traditional PBX, external lines are generally accessed by way of an access code that must be dialed before the number. It is common to use the digit 9 for this purpose.
In Asterisk, it is similarly possible to assign 9 for routing of external calls, but since the Asterisk dialplan is so much more intelligent, it is not really necessary to force your users to dial 9 before placing a call. Typically, you will have an extension range for your system (say, 100–199), and a feature code range (*00 to *99). Anything outside those ranges that matches the dialing pattern for your country or region can be treated as an external call.
If you have one carrier providing all of your external routing, you can handle your external dialing through a few simple pattern matches. The example in this section is valid for the North American Numbering Plan (NANP). If your country is not within
the NANP (which serves Canada, the US, and several Caribbean countries), you will need a different pattern match.
The [globals] section contains two variables, named LOCAL and TOLL . 3 The purpose of these variables is to simplify management of your dialplan should you ever need to change carriers. They allow you to make one change to the dialplan that will affect all places where the specified channel is referenced:
[globals]
LOCAL=DAHDI/G0 ; assuming you have a PSTN card in your system
TOLL=SIP/YourVoipCarrier ; as defined in sip.conf
The [external] section contains the actual dialplan code that will recognize the numbers dialed and pass them to the Dial() application:
[external]
exten => _NXXNXXXXXX,1,Dial(${LOCAL}/${EXTEN}) ; 10-digit pattern match for NANP
exten => _NXXXXXX,1,Dial(${LOCAL}/${EXTEN}) ; 7-digit pattern match for NANP
exten => _1NXXNXXXXXX,1,Dial(${TOLL}/${EXTEN}) ; Long-distance pattern match
; for NANP
exten => _011.,1,Dial(${TOLL}/${EXTEN}) ; International pattern match for
; calls made from NANP
; This section is functionally the same as the above section.
; It is for people who like to dial ‘9’ before their calls
exten => _9NXXNXXXXXX,1,Dial(${LOCAL}/${EXTEN:1})
exten => _9NXXXXXX,1,Dial(${LOCAL}/${EXTEN:1})
exten => _91NXXNXXXXXX,1,Dial(${TOLL}/${EXTEN:1})
exten => _9011.,1,Dial(${TOLL}/${EXTEN:1})
In any context that would be used by sets or user devices, you would use an include=> directive to allow access to the external context:
[LocalSets]
include => external
**IMPORTANT POINT=== It is critically important that you do not include access to the external lines in any context that might process an incoming call. The risk here is that a phishing bot could eventually gain access to your outgoing trunks (you’d be surprised at how common these phishing bots are). We cannot stress enough how important it is that you ensure that no external resource can access your toll lines.
PSTN Circuits
The public switched telephone network (PSTN) has existed for over a century. It is the precursor to many of the technologies that shape our world today, from the Internet to MP3 players.
Traditional PSTN Trunks
There are two types of fundamental technology that phone carriers use to deliver telephone circuits: analog and digital.
Analog telephony
The first telephone networks were all analog. The audio signal that you generated with your voice was used to generate an electrical signal that was carried to the other end. The electrical signal had the same characteristics as the sound being produced. Analog circuits have several characteristics that differentiate them from other circuits you might wish to connect to Asterisk:
• No signaling channel exists—most signaling is electromechanical.
• Disconnect supervision is usually delayed by several seconds, and is not completely reliable.
• Far-end supervision is minimal (for example, answer supervision is lacking).
• Differences in circuits means that audio characteristics will vary from circuit to circuit and will require tuning.
Analog circuits that you wish to connect to your Asterisk system will need to connect to a Foreign eXchange Office (FXO) port. Since there is no such thing as an FXO port in any standard computer, an FXO card must be purchased and installed in the system
in order to connect traditional analog lines. Analog ports are not generally used in medium to large systems. They are most com‐
monly used in smaller offices (less than 10 lines; less than 30 phones). Your decision to use analog might be based on some of the following factors:
• Availability of digital trunks in your area
• Cost (analog is less expensive at smaller densities, but more expensive at higher densities)
• Logistics (if you already have analog lines installed, you may wish to keep them)
From a technical perspective, you would normally want to have digital rather than analog circuits. Reality does not always accommodate, though, so analog will likely be around for a few more years yet.
Digital telephony
Digital telephony was developed in order to overcome many of the limitations of analog. Some of the benefits of digital circuits include:
• No loss of amplitude over long distances
• Reduced noise on circuits (especially long-distance circuits)
• Ability to carry more than one call per circuit
• Faster call setup and teardown
• Richer signaling information (especially if using ISDN)
• Lower cost for carriers
• Lower cost for customers (at higher densities)
In an Asterisk system (or any PBX, for that matter), there are several types of digital circuits you might want to connect:
T1 (24 channels)
Used in Canada and the United States (mostly for ISDN-PRI)
E1 (32 channels)
Used in the rest of the world (ISDN-PRI or MFC/R2)
BRI (2 channels)
Used for ISDN-BRI circuits (Euro-ISDN)
Note that the physical circuit can be further defined by the protocol running on the circuit. For example, a T1 could be used for either ISDN-PRI or CAS, and an E1 could be used for ISDN-PRI, CAS, or MFC/R2. We’ll discuss the different protocols in the
next section.
Installing PSTN Trunks
Depending on the hardware you have installed, the process for installing your PSTN cards will vary. We will discuss installation in general terms, which will apply to all Digium PSTN cards. Other manufacturers tend to provide installation scripts with their
hardware, which will automate much of this for you.
Downloading and installing DAHDI
The Digium Asterisk Hardware Device Interface, or DAHDI (formerly known as Zaptel), is the software Asterisk uses to interface with telephony hardware. We recommend that you install it even if you have no hardware installed, because DAHDI is a dependency. required for building the timing module res_timing_dahdi and is used for Asterisk dialplan applications such as MeetMe() .
Another dependency is required for installing DAHDI, and that is the kernel source. It is important that the kernel version being used match exactly that of the kernel source being installed. You can use uname -a to verify the currently running kernel version:
RHEL
sudo yum install kernel-devel
Ubuntu
sudo apt-get install linux-headers-uname -r
The use of uname -r surrounded by backticks ( ` ) is for filling in the currently running kernel version so the appropriate package is installed.
The following commands show how to install DAHDI-linux-complete 2.6.1+2.6.1. There may be a newer version available by the time you are reading this, so check downloads.asterisk.org first.
If there is a newer version available, just replace the version number in the commands:
$ cd ~/src/asterisk-complete/
$ mkdir dahdi
$ cd dahdi/
$ svn co http://svn.asterisk.org/svn/dahdi/linux-complete/tags/2.6.1+2.6.1
$ cd 2.6.1+2.6.1
If you are using 64-bit RHEL, use the following commands to compile and install DAHDI:
$ cd tools
$ ./configure –libdir=/usr/lib64
$ make
$ sudo make install
$ cd ../linux
$ make
$ sudo make install
$ cd ..
$ sudo make config
For any other platform, use this set of commands to compile and install DAHDI:
$ make all
$ sudo make install
$ sudo make config
LibPRI
LibPRI is a library that adds support for ISDN (PRI and BRI). The use of LibPRI is optional, but since it takes very little time to install, doesn’t interfere with anything, and will come in handy if you ever want to add cards to a system at a later point, we recommend that you install it now. Be sure to install DAHDI prior to installation of LibPRI as there is a dependency on a DAHDI header file during compilation. Check out the latest version of LibPRI and compile it thus:
Check out the latest version of LibPRI and compile it thus:
$ cd ~/src/asterisk-complete/
$ mkdir libpri
$ cd libpri/
$ svn co http://svn.asterisk.org/svn/libpri/tags/1.4.<your version number>
$ cd 1.4.<your version number>
$ make
Use the following command to install LibPRI if you are using 64-bit RHEL:
$ sudo make install libdir=/usr/lib64
For any other platform, use this command to install LibPRI:
$ sudo make install
Asterisk
With both DAHDI and LibPRI installed, we can now install Asterisk:
$ cd ~/src/asterisk-complete/asterisk/11
If you are running 64-bit RHEL, run the configure script with the libdir option:
$ ./configure –libdir=/usr/lib64
On any other platform, run the configure script without any arguments:
$ ./configure
Finally, compile and install Asterisk:
$ make
$ sudo make install
$ sudo make config
Disable Loading Extra DAHDI Modules
By default DAHDI will load all compiled modules into memory. As this is unnecessary, let’s disable loading any of the hardware modules for now. If no modules are loaded in the configuration files, DAHDI will load the dahdi_dummy driver, which provides an
interface for Asterisk to get timing from the kernel so that timing dependent modules such as MeetMe and IAX2 trunking work correctly.
The configuration file defining which modules DAHDI will load is in /etc/dahdi/modules . To disable loading of extra modules, all we need to do is edit the modules file and comment out all the modules by placing a hash ( # ) at the start of each line. When
you’re done, your modules configuration file should look similar to the following:
# Contains the list of modules to be loaded / unloaded by /etc/init.d/dahdi.
# NOTE: Please add/edit /etc/modprobe.d/dahdi or /etc/modprobe.conf if you
# would like to add any module parameters.
# Format of this file: list of modules, each in its own line.
# Anything after a ‘#’ is ignored, likewise trailing and leading
# whitespace and empty lines.
# Digium TE205P/TE207P/TE210P/TE212P: PCI dual-port T1/E1/J1
# Digium TE405P/TE407P/TE410P/TE412P: PCI quad-port T1/E1/J1
# Digium TE220: PCI-Express dual-port T1/E1/J1
# Digium TE420: PCI-Express quad-port T1/E1/J1
#wct4xxp
# Digium TE120P: PCI single-port T1/E1/J1
# Digium TE121: PCI-Express single-port T1/E1/J1
# Digium TE122: PCI single-port T1/E1/J1
#wcte12xp
# Digium T100P: PCI single-port T1
# Digium E100P: PCI single-port E1
#wct1xxp
# Digium TE110P: PCI single-port T1/E1/J1
#wcte11xp
# Digium TDM2400P/AEX2400: up to 24 analog ports
# Digium TDM800P/AEX800: up to 8 analog ports
# Digium TDM410P/AEX410: up to 4 analog ports
#wctdm24xxp
# X100P – Single port FXO interface
# X101P – Single port FXO interface
#wcfxo
# Digium TDM400P: up to 4 analog ports
#wctdm
# Digium B410P: 4 NT/TE BRI ports
#wcb4xxp
# Digium TC400B: G729 / G723 Transcoding Engine
#wctc4xxp
# Xorcom Astribank Devices
#xpp_usb
You can then restart your DAHDI process to unload any existing drivers that were loaded, and load just the dahdi_dummy module with the init script:
$ sudo /etc/init.d/dahdi restart
Unloading DAHDI hardware modules: done
Loading DAHDI hardware modules:
No hardware timing source found in /proc/dahdi, loading dahdi_dummy
Running dahdi_cfg:
Use the following command to install LibPRI if you are using 64-bit RHEL:
$ sudo make install libdir=/usr/lib64
For any other platform, use this command to install LibPRI:
$ sudo make install
Configuring digital circuits
Digital telephony was developed by carriers as a way to reduce the cost of long-distance circuits, as well as improve transmission quality. The entire PSTN backbone has been fully digital for many years now. The essence of a digital circuit is the digitization of the audio, but digital trunks also allow for more complex and reliable signaling. Several standards have been developed and deployed, and for each standard there may be regional differences as well.
PRI ISDN
Primary Rate Interface ISDN (commonly known as PRI) is a protocol designed to run primarily on a DS1 circuit (a T1 or E1, depending on where you are in the world) between a carrier and a customer. PRI uses one of the DS0 channels as a signaling channel (referred to as the D-channel). A typical PRI circuit is therefore broken down into a group of B-channels (the bearer channels that actually carry the calls), and a D-channel for signaling. Although it is most common to find a PRI circuit being
carried across a single physical circuit (such as a T1 or E1), it is possible to have a PRI circuit span multiple DS1s, and even to have multiple D-channels.
While there are many different ways to configure PRI circuits, we are hoping to avoid confusing you with all the options (many of which are obsolete or at least no longer in common use), and instead provide examples of the more common configurations.
Most PRI circuits in North America will use a T1 with the following characteristics:
• Line code: B8ZS (bipolar with 8-zeros substitution)
• Framing: ESF (extended superframe)
You will need to configure two files. The /etc/dahdi/system.conf file should look some‐
thing like this:
loadzone = us
defaultzone = us
span = 1,1,0,esf,b8zs
bchan = 1-23
echocanceller = mg2,1-23
hardhdlc = 24
And the /etc/asterisk/chan_dahdi.conf file should look like this:
[trunkgroups]
[channels]
usecallerid = yes
hidecallerid = no
callwaiting = yes
usecallingpres = yes
callwaitingcallerid = yes
threewaycalling = yes
transfer = yes
canpark = yes
cancallforward = yes
callreturn = yes
echocancel = yes
echocancelwhenbridged = yes
relaxdtmf = yes
rxgain = 0.0
txgain = 0.0
group = 1
callgroup = 1
pickupgroup = 1
immediate = no
switchtype = national ; commonly referred to as NI2
context = from-pstn
group = 0
echocancel = yes
signalling = pri_cpe
channel => 1-23
Some carriers will use Nortel’s DMS switch, which commonly uses the DMS100 protocol instead of National ISDN 2. In this case you would set the switchtype to DMS100 :
switchtype = dms100;
Outside of Canada and the US, PRI circuits will be carried on an E1 circuit.
In Europe, an E1 circuit used for PRI will normally have the following characteristics:
• Line code: CCS
• Framing: HDB3 (high-density bipolar)
The /etc/dahdi/system.conf file might look something like this:
span = 1,0,0,ccs,hdb3,crc4
bchan = 1-15,17-31
hardhdlc = 16
And the /etc/asterisk/chan_dahdi.conf file should look something like this:
[trunkgroups]
[channels]
usecallerid = yes
hidecallerid = no
callwaiting = yes
usecallingpres = yes
callwaitingcallerid = yes
threewaycalling = yes
transfer = yes
canpark = yes
cancallforward = yes
callreturn = yes
echocancel = yes
echocancelwhenbridged = yes
relaxdtmf = yes
rxgain = 0.0
txgain = 0.0
group = 1
callgroup = 1
pickupgroup = 1
immediate = no
switchtype = qsig
context = pri_incoming
group = 0
signalling = pri_cpe
channel => 1-15,17-31
BRI ISDN. Basic Rate Interface ISDN (commonly known as BRI, or sometimes even just ISDN) was intended to be the smaller sibling to PRI. BRI only provides two 64K B-channels and a 16K D-channel. The use of BRI has been somewhat limited in North
America (we don’t recommend using it for any reason), but in some countries in Europe it is widely used and has almost completely replaced analog.
BRI support under Asterisk will be different depending on the BRI card you are installing. The manufacturer of your BRI card will provide specific installation instructions for its hardware.
MFC/R2. The MFC/R2 protocol could be thought of as a precursor to ISDN. It was at first used on analog circuits, but it is now mostly deployed on the same E1 circuits that also carry ISDN-PRI. This protocol is not typically found in Canada, the US, or Western Europe, but it is very popular in some parts of the world (especially Latin America and Asia), mostly because it tends to be a less expensive service offering from the carriers.
There are many different flavors of this protocol, each country having a different regional variant.
The OpenR2 project provides the libopenr2 library, which needs to be installed on your system in order for Asterisk to support your R2 circuits. Before installing libopenr2 , however, you need to have DAHDI installed.
The compilation and installation order, therefore, is:
1. DAHDI
2. libopenr2
3. Asterisk
Once OpenR2 has been installed, you can use the r2test application to see a list of variants that are supported:
$ r2test -l
Variant Code Country
AR Argentina
BR Brazil
CN China
CZ Czech Republic
CO Colombia
EC Ecuador
ITU International Telecommunication Union
MX Mexico
For additional information on configuring R2 support in Asterisk, see the configs/chan_dahdi.conf.sample file included in the Asterisk source tree (search for “mfcr2”). Additionally, OpenR2 contains some sample configuration files for connecting Asterisk
to networks in various countries. To read information about some of the country variants, search the /doc/asterisk folder and refer to the documents inside the appropriate subdirectory:
$ ls doc/asterisk/
ar br ec mx ve
As an example, OpenR2 provides a sample configuration for connecting to Telmex or Axtel in Mexico. We’ll step you through this to give you an idea of the process. First, you must configure DAHDI by modifying /etc/dahdi/system.conf as shown here:
loadzone = us
defaultzone = us
span = 1,1,0,cas,hdb3
cas = 1-15:1101
cas = 17-31:1101
span = 2,1,0,cas,hdb3
cas = 32-46:1101
cas = 48-62:1101
Next, you must configure Asterisk by modifying /etc/asterisk/chan_dahdi.conf as follows:
signalling = mfcr2
mfcr2_variant = mx
mfcr2_get_ani_first = no
mfcr2_max_ani = 10
mfcr2_max_dnis = 4
mfcr2_category = national_subscriber
mfcr2_mfback_timeout = -1
mfcr2_metering_pulse_timeout = -1
; this is for debugging purposes
mfcr2_logdir = log
mfcr2_logging = all
; end debugging configuration
channel => 1-15
channel => 17-31
Configuring analog circuits
There are many companies producing PSTN cards for Asterisk. The card will need to have its drivers installed so that Linux can recognize it (DAHDI ships with these drivers for Digium cards). From that point, configuration is handled by the Asterisk module
chan_dahdi .
In order to configure an FXO card to work with Asterisk, two files are required: the first is not an Asterisk configuration file, and is thus located in the /etc/dahdi folder on your system. This file, system.conf, allows you to define some basic parameters, as well as
specify the channels that will be available to your system. Our example assumes a four port FXO card, but many different combinations are possible, depending on your hardware:
loadzone = us ;tonezone defines sounds the interface must produce
;(dial tone, busy signal, ringback)
defaultzone = us ; define a default tonezone
fxsks = 1-4 ; which channels on the card will have these parameters
Once your card and channels are known to the operating system, you must configure them for Asterisk by means of the file /etc/asterisk/chan_dahdi.conf:
[channels]
;
; To apply other options to these channels, put them before “channel”.
;
signalling = fxs_ks ; in Asterisk, FXO channels use FXS signaling
; (and yes, FXS channels use FXO signaling)
channel => 1-4 ; apply all the previously defined settings to this channel
In this example, we have told Asterisk that the first four DAHDI channels in the system are FXO ports.
The s extension
If you are connecting to the PSTN using analog channels, we need to explain extension s . When calls enter a context without a specific destination extension (for example, a ringing FXO line from the PSTN), they are passed to the s extension. (The s stands for “start,” as this is where a call will start if no extension information was passed with the call). This extension can also be useful for accepting calls that have been redirected from other parts of the dialplan. For example, if we had a list of Direct Inward Dialing (DID) numbers that were all going to the same place, we might want to point each DID to the s extension, rather than having to code duplicate dialplan logic for each DID.
Since this is exactly what we need for our dialplan, let’s begin to fill in the pieces. We will be performing three actions on the call (answer it, play a sound file, and hang it up), so our s extension will need three priorities. We’ll place the three priorities below [incoming] , because we have decided that all incoming calls should start in this context;
[incoming]
exten => s,1,Answer()
same => n,Playback(tt-weasels)
same => n,Hangup()
Obviously, you would not normally want to answer a call and then hang up. Typically, an incoming call will either be answered by an automated attendant, or ring directly to a phone (or group of phones).
