Modules

Digium Zaptel Cards (chan_zap)

chan_zap handles zaptel telephony devices like all newer Digium's cards, ISDN cards based on the HFC chipsets with zaphfc or qozap and alike.

zaptel.conf

This configuration file will most likely be found in /etc and not together with the other Asterisk configuration files. It defines which zaptel interfaces you have installed in your system, what dialtone these cards should use, depending on your country, and how many channels should be utilised.

First of all you should decide what dialtone your system should give the users:


				loadzone=us
				loadzone=uk
				defaultzone=us
				

The configuration example above loads the indication tones typical for the US and the UK. Available zones are: au, at, cl, es, fi, fr, gr, it, jp, nl, no, nz, tw, uk, us, us-old. These are all defined in zonedata.c in the Asterisk sourcetree. The defaultzone option defines, which tonezone should be used, if nothing else is defined.

Next we should define what kind of cards we have in the system. Let's start with two TDM400P cards, where one has 2 FXO modules and the other 6 ports are FXS ports.


				fxsks=1-2 ; FXO ports, card 1
				fxoks=3-8 ; FXS ports, card 1+2
				

You could also have one of the FXO modules on each card:


				fxsks=1,5 ; FXO ports, card 1+2
				fxoks=2-4 ; FXS ports, card 1
				fxoks=5-8 ; FXS ports, card 2
				

The order of the channels depends on which order the cards are in loaded in and what order the modules are sitting on the TDM400P. Notice that the options allways are reverse: fxsks for FXO ports and fxoks for FXS ports. That is the way it should be. There are three options for each type of interface (fxs and fxo): fxsls, which is fxs signaling with loopstart, fxsks, which is fxs signaling with koolstart and fxsgs, which is fxs signaling with groundstart. The same applies for fxols, fxoks and fxogs. The different types are telling the zaptel driver, if you telephone line tells you, that the other side has hung up or not. Some pstn lines, some not.

Loopstart

Loopstart does not include hangup notification unless specifically done through forward-disconnect.

Groundstart

Groundstart does include hangup notification.

Koolstart

Koolstart is also known as Disconnect Supervision, and is what you usually want to have for FXO devices. If your phone provider doesn't support that, the FXO device will basically not detect that the other side has hung up and Asterisk will try to continue servicing the port. If you can't get your Telco to give you Disconnect Supervision on your line there are possibilities to work around that. This can be done with some options in zapata.conf, but we will get to that.

Next in our journey through zaptel.conf we are getting to spans, which covers cards like the HFC-based cards and Digiums T1 and E1 cards. A span definition is in the following format:


				span=(spannum),(timing),(LBO),(framing),(coding)[,(crc)]
				

spannum tells more or less itself: which span are we talking about, there might be multiple, which you configure one by one.

timing tells how you want to syncronize the timing of the spans. '0' tells, that you don't want to use this span as sync source, '1' tells, that it is the primary sync source and '2' tells, that it is the secondary sync source.

LBO stands for "Line Build Out". It can be taken from the following table:

0: 0 db (CSU) / 0-133 feet (DSX-1)
1: 134-266 feet (DSX-1)
2: 267-399 feet (DSX-1)
3: 400-533 feet (DSX-1)
4: 534-655 feet (DSX-1)
5: -7.5 db (CSU)
6: -15 db (CSU)
7: -22.5 db (CSU)

framing and coding define how you will communicate with the hardware at the other end of the line. Here the values that fit for different line types:

T1 - framing is one of d4 or esf, coding is one of ami or b8zs
E1 - framing is one of cas or ccs, coding is one of ami or hdb3. E1's spans may also need to enable crc checking. That would be crc4 for crc

Let's take an example how a Digium T100P (one port T1 card) would look like:


				span=1,1,0,esf,b8zs
				bchan=1-23
				dchan=24
				

span defines the span as primary syncsource, 0 db (CSU), esf framing and b8zs coding. This is probably the most likely configuration that you will see. Channels 1-23 are B channels (data, voice, etc.) and channel 24 is used for signaling.

Another example with a TE410P, 4 E1 spans:


				span=1,1,0,ccs,hdb3,crc4
				span=2,0,0,ccs,hdb3,crc4
				span=3,0,0,ccs,hdb3,crc4
				span=4,0,0,ccs,hdb3,crc4
				
				bchan=1-15,32-46,63-77,94-108
				dchan=16,47,78,109
				bchan=17-31,48-62,79-93,110-124
				

This is a bit more complicated as you can see. We have 4 spans here, span 1 is the sync source, the spans use ccs framing and hdb3 coding, beyond that they are also configured for crc. Channels 1-15 and 17-31, 30 channels in total, on each span are configured as B channels (data, voice, etc.). Channel 16 is allways the D channel used for signaling. This setup is what you see on a DSS1 PRI, the most common ISDN protocol used in Europe. One note for the TE410P (and TE405P of course) should be added: If you configure it, run ztcfg to initialize the card and it comes up and complains about channel 97 then you have forgot to set the jumpers to E1 on the card.

Last but not least a example for a BRI interface using a HFC based ISDN card:


				span=1,1,3,ccs,ami
				bchan=1-2   
				dchan=3
				span=2,1,3,ccs,ami
				bchan=4-5   
				dchan=6
				

The span entries are needed, but actually only dummies, they are not really interpreted by Asterisk. You will however have to define, that you have two B channels and one D channel on each card.

Once the configuration in zaptel.conf has been changed, you should run ztcfg to reinitialize your zaptel hardware and then restart asterisk after that. For having ztcfg run on boot, you should add the following to your modules.conf:


				post-install wct4xxp /sbin/ztcfg
				

wct4xxp should be replaced with the zaptel module that is loaded as the last one, which ever that is.

ISDN CAPI (chan_capi)

To use chan_capi you must have support for CAPI and your ISDN card in your kernel configuration. You will have to check with your vendor to see if your particular card is supported, but Linux has good support for ISDN cards, so most likely it will. Cards such as Eicon and AVM are known to work with Asterisk. However it can be a bit tricky to get CAPI support working for different ISDN cards. chan_capi only provides TE mode, you can only use it for connecting your asterisk box to a ISDN line, not connect phones internally to the ISDN card. Also have a look in the chapter about "Building additional modules" which will give you a good idea, what cards can be used, where you can download kernel drivers for these and how you get them to work. Once that is done, you can continue with this section and configure chan_capi.

This is a list of the features implemented in chan_capi:

chan_capi is a third party module, that has to be downloaded seperatly from Asterisk. It can be downloaded at: http://www.junghanns.net/asterisk/.

capi.conf

The configuration of capi based devices is fairly straight forward. The first section we need to edit is [general]. section.


				[general]
				nationalprefix=0
				internationalprefix=00
				rxgain=0.8
				txgain=0.8
				

nationalprefix and internationalprefix define which prefix Asterisk should add in front of the caller-id on incoming calls. ISDN works like this; the caller-id is transferred without the prefix and there is a special indicator, on call setup, what kind of call we are talking about. Since Asterisk does not differenciate between different countries, and the prefix can be different from country to country, this can be set here. For example, the international prefix in North America is "011", but in most European countries it is "00". rxgain and txgain allow you to adjust the receiving and transmitting gain (volume) respectfully. These numbers are in decibals (dB) so only adjust in small incremements. Setting these too high will cause Asterisk to produce echo on the channel.

Next up is the [interfaces] section. This section defines which capi interfaces you want to add to Asterisk and which numbers are available. ISDN can be configured two ways: Point to Multi-Point (PMP) or Point to Point (PtP). Here is a typical PMP setup:


				[interfaces]
				msn=2043986,2043987
				incomingmsn=*
				controller=1
				devices=2
				softdtmf=1
				accountcode=
				context=default
				callgroup=1
				;mode=immediate
				;deflect=12345678
				;echosquelch=1
				;echocancel=yes
				;echotail=64
				

msn specifies which MSNs (or DIDs) you want to use for outgoing calls. There is a limitation of up to 5 MSNs, but usually it is enough to specify one of them. You can set the MSN you want to show on outgoing calls by setting the ${CALLERIDNUM} variable in your dialplan. On incomingmsn you can specify, which MSNs Asterisk should react on. A "*" tells Asterisk to react on any call, no matter what MSN it has.

With controller you specify what controller you are configuring. You can have more than one controller in your system and all can be configured individually. devices tells chan_capi how many b-channels your ISDN card can handle. softdtmf=1 will use Asterisk's dsp functions to detect and generate the DTMF tones. softdtmf=0 will use your capi controller to do the detection/generation. Unless you have an active card you should use softdtmf=1.

accountcode is for billing purposes. context defines which context chan_capi should send incoming calls from the ISDN card to. callgroup defines which callgroup the controller is a member of. You can have several controllers in the same callgroup, that then would react in the same way. If mode is set to immediate, the ISDN card answers the call and immediatly passes it on to Asterisk. The default behavior would be, that you need to answer the call in your dialplan.

deflect defines a phone number that you automatically want to deflect calls to if both b-channels on your ISDN card are busy. Deflect on busy has to be enabled during compile, if you want that feature to work.

echosquelch, echocancel and echotail are values, that you normally need not to change. If you are dealing with echo issues, it might be an idea to try testing different values here.

The typical PtP setup would look like this:


				[interfaces]
				isdnmode=ptp
				msn=20439
				controller=1
				devices=30
				softdtmf=0
				accountcode=
				context=default
				callgroup=1
				

The options for a Point to Point setup are basically the same as for the PMP setup. msn now only holds the prefix of your msn, the suffix will be transferred to Asterisk as an extension. isdnmode=ptp tells chan_capi, that the card is to be run in Point to Point mode (Default would be Point to Multi-Point mode). All other values are to be configured the same way with Point to Multi-Point mode.

mISDN (chan_mISDN)

Features at a glance:

chan_mISDN is a third party channel module, that has to downloaded seperatly. It can be found at: http://www.beronet.com/?PageID=3017.

Voicetronix Cards (chan_vpb)

vpb.conf

vpb.conf holds the configuration for the VoiceTronix line of OpenLine and OpenSwitch hardware. The VoiceTronix hardware can be either FXO or FXS channels, depending on how the card is set up. The OpenSwitch 6 OpenSwitch 12 have 6 or 12 respective Loop-Start (FXO) or Station (FXS) user-configurable analogue ports. The OpenLine 4 has 4 Loop-Start (FXO) ports.

All of the options in the configuration file are shown in the example configuration file that comes with the driver. The one configuration file can handle all of the voicetronix cards/boards in the machine.


				[general]
				cards = 1
				type = v6pci
			
				[interfaces]
				board = 1
				echocancel = on
				callerid = on
				context = default
				txhwgain = 6
				rxhwgain = -3
				txgain = 12
				rxgain = 6
				mode = fxo
				channel = 1
				channel = 2
				channel = 3
				;channel = 4
				;mode = fxs
				;channel = 5
				;channel = 6

				board = 2
				echocancel = on
				callerid = on
				context = default
				txhwgain = 6
				rxhwgain = -3
				txgain = 12
				rxgain = 6
				mode = fxo
				channel = 1
				channel = 2
				channel = 3
				;channel = 4
				;mode = fxs
				;channel = 5
				;channel = 6
			
				

The general section allows you to make settings that affect all boards, as well as define the number of boards (cards),of the same type, in the machine. The type variable setting lets you define the card types that are in the system, valid entries are: v4pci (OpenLine 4) and v12pci (OpenSwitch 6 and 12). The cards variable is the number of VoiceTronix cards in the server.

The interfaces section contains the information about the specific cards in the system. The interfaces section is broken up by board variables. Everything from a board = line to the next board = line is considered part of that board definition. The echocancel variable can be turned on (or off) to effect echo cancellation. This can compensate for lower quality lines when working with a channel in FXO mode. The callerid variable can be turned on for the detection of callerid data on the FXO channels of a card. The context variable is the Asterisk context that incoming calls will be put into. This should point to a context that can answer incoming calls. The txhwgain rxhwgain variables control the amount of gain on the transmit and recieve volumes that is performed in the hardware DSP. The txgain and rxgain variables control the amount of gain on the transmit and recieve volumes performed in software. The channel variable is used to define the existance of a particular channel. If channels 1, 2, and 3 are available on an OpenSwitch 6 card, the above example will work.

Card configurations of 0 FXS and 6 FXO, 2 FXS and 4 FXO, 4 FXS and 2 FXO, 6 FXS and 0 FXO are available for the OpenSwitch 6. Configurations of 0 FXS and 12 FXO, 4 FXS and 8 FXO, 8 FXS and 4 FXO, 12 FXS and 4 FXO are available on the OpenSwitch 12. These must be setup with onboard jumpers before Asterisk can use them. For more information about how to configure the OpenLine and OpenSwitch cards please refer to the driver documentation that comes with the card.

Defining IAX Channels and connections (chan_iax & chan_iax2)

iax.conf

iax.conf holds the basic configuration for IAX and all the accounts, that * uses to communicate with other voip services over IAX. IAX is one of the VoIP protocols, that * can handle.

Defining SIP Channels and connections (chan_sip)

sip.conf

sip.conf holds the basic configuration for SIP and all the accounts, that * uses to communicate with other voip services over SIP. SIP is one of the VoIP protocols, that * can handle.

rtp.conf

The SIP protocol uses port 5060 for control messages between the two talking end points. However the RTP audio stream comes over a different range of ports which need to be opened on any firewall, or forwarded to any NAT'd Asterisk box. This can be configured in the rtp.conf file located in /etc/asterisk/.

By default Asterisk will accept RTP messages in the range of 10000 through 20000. Many people may not need this large of a range, and very well may not want to open that many ports on their firewall. If you want to change the range that Asterisk will listen for the RTP stream on, you simply need to change the start and stop range. The following is the default example that comes with the sample configuration files


				; RTP Configuration
				[general]

				; RTP start and RTP end configure start and end addresses
				rtpstart=10000
				rtpend=20000
				

rtpstart is the first port that Asterisk will accept RTP data on and rtpend is the last port that Asterisk will accept RTP data on. Simply change these values to suit your needs.

Defining H.323 channels and connections (chan_h323)

This channel module is part of the Asterisk CVS tree now. It uses the Asterisk RTP stack and implements H.323 in one shared library.

asterisk-oh323, or another way of getting H.323 connectivity (chan_oh323)

This was the first channel module available to Asterisk, that implemented H.323. It simulates a pseudo soundcard implementation to pass audio from Asterisk to the Open H.323 stack.

Configuring E.164 lookups (app_enumlookup)

enum.conf

enum.conf is used for configuring Enum. Enum is a telephony technology which allows users of disparate networks and technologies to call each other through the use of a common routing database. This database is DNS records on a centralized server. This technology is discussed in depth in chapter 7.

Voicemail (app_voicemail)

voicemail.conf

The voicemail subsystem of asterisk is a powerful tool, able to send emails on the receipt of voicemail, cope with different timezone for different users and even do voicemail virtual hosting.

Voicemail is configured using the voicemail.conf file in the /etc/asterisk directory by default. A simple example is shown below.

voicemail.conf


				[general]
				format=wav|wav49|gsm
				serveremail=root@localhost
				attach=yes
				maxmessage=180
				maxgreet=60

				[default]
				2000 => 4321,Jeffery Alterton,jeff@example.com
				

This is about as simple as you can get for the voicemail system, setting up a single mailbox and sending an email with the message attached when a voicemail is left.

In the dial plan voicemail would be ran using something like one of the following examples.

extensions.conf


				[default]
				exten => 2000,1,Answer  ; answer the channel
				exten => 2000,2,Dial(SIP/2000,16,tr)  ; dial channel supplied by ${ARG1}
				exten => 2000,3,Voicemail(u2000) ; if no answer, goto unavailable vm
				exten => 2000,4,Hangup  ; hangup the channel
				exten => 2000,103,Voicemail(b2000)  ; if the channel is busy, goto busy vm
				exten => 2000,104,Hangup  ; hangup the channel
				

In this example if extension 2000 is dialled then the call is answered and extension 2000 is dialed over sip (see the [2000] section of sip.conf) if the call fails due to being unavailible then it continues running at the next step which in this example is the voicemail system with an unavailible message. If the call fails due to being busy the flow jumps to priority n+101 (2+101 in this example see the section on the extensions.conf file for more details) and starts running from there. Which in this example is voicemail with a busy anouncement. In both cases after voicemail is finished the call is hung up.

To access your voicemail you need a different application. This application is called VoicemailMain and is shown in the example below.


				exten => 1000,1,Answer
				exten => 1000,2,VoicemailMain()
				exten => 1000,3,HangUp
				

Now when the user dials extension 1000 they will be prompted to enter their voicemailbox and pin and dropped into the voicemail system to listen to messages.

VoicemailMain can also take the mailbox number to drop them into requesting only a pin in this case.


				exten => 1000,1,Answer
				exten => 1000,2,VoicemailMain(${CALLERIDNUM})
				exten => 1000,3,HangUp
				

This example would detect the extension the caller is coming from and drop them into the voicemail system.

Conferencing (app_meetme)

meetme.conf

MeetMe is the Asterisk conferencing application, allowing multiple parties to all be part of the same phone call. It can be configured many ways, for example one person talking and many listening or as a many to many conference. It is possible to give certain users the ability to try to control the conference with the admin functions.

It is generally controlled via the dial plan using two applications. MeetMe and MeetMeCount, and requires a timing source to be present in the system being used. ztdummy works fine for this and it is not necessary to use a zaptel card. However, ztdummy does not provide as reliable or scalable timing as a hardware interface, so use with caution.

MeetMeCount returns the number of people active in a certain conference. MeetMe is much more complex in that it can take many options allowing privleges and abilities to be granted or taken away to users. For example you could have two extentions, one allowing the speaker to enter the room with a password and the ability to address the conference and another only allowing people to listen with no password.

This could be done as follows:

in extensions.conf


				[conference]
				exten => 51000,1,MeetMe(1000|tp|1234) ;speaker can speak and can exit with the press of #
				exten => 1000,1,MeetMe(1000|mq) ;listeners can only recieve audio from the conference and when joining or leaving wont produce sound.
				

and in meetme.conf


				[rooms]
				conf => 1000
				

The options are as follows (accurate as of 2004-05-30):

'm' -- set monitor only mode (Listen only, no talking)
't' -- set talk only mode. (Talk only, no listening)
'p' -- allow user to exit the conference by pressing '#'
'd' -- dynamically add conference
'D' -- dynamically add conference, prompting for a PIN
'e' -- select an empty conference
'E' -- select an empty pinless conference
'v' -- video mode
'q' -- quiet mode (don't play enter/leave sounds)
'M' -- enable music on hold when the conference has a single caller
'x' -- exit the conference if the last marked user left
'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND}
's' -- Present menu (user or admin) when '*' is received ('send' to menu)
'a' -- set admin mode

You can also get this list by typing 'show application meetme' within the asterisk shell.

meetme.conf simply lists all the staticly generated conferences in asterisk in the form:


				conf => 1000
				conf => 1000,1234
				

where the first number is the conference number and the second is the deafult password for the conference.

Call Parking (app_parkandannounce)

parking.conf

The parking.conf file controls the extension numbers for call parking. Call parking allows a caller to be placed into an extension where you can retrieve the call from any other phone attached to Asterisk. This is done by transfering the user to the "call parking" extension. Once transfered to that extension, Asterisk will announce the extension that the call can be retrieved from.

For example, lets say John Smith calls Company XYZ and asks for Jane Doe. Instead of transfering the call to a specific extension, you could place the caller into call parking where Asterisk will tell you which extension the call has been placed into. You could then announce over a PA system for John Smith to call that extension number where he could retrieve the call no matter where he was in the building.

The following is an example parking.conf configuration:


				[general]
				parkext => 501 ; What ext. to dial to park
				parkpos => 502-520 ; What extensions to park calls on
				
				context => parkedcalls ; Which context parked calls are in
				
				parkingtime => 45	; Number of seconds a call can be parked 
				for (default is 45 seconds)
				
To park a call you will press '#' to transfer the caller to an extension. parkext is the configurable extension number to dial in order to park the caller. Once parked, Asterisk will announce the extension which the caller has been parked in. This will be in the range specified by parkpos. Parked calls are placed into the context defined by context. This allows you to use things like Music On Hold (MOH) for your parked callers. parkingtime is the timeout time that the caller will be left parked until the original extension from where the call was parked will ring to tell the operator that the call has not been un-parked yet.