The Hitchhiker's Guide to Asterisk | ||
---|---|---|
<<< Previous | Modules, or "Things that make Asterisk work." | Next >>> |
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.
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:
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.
You could also have one of the FXO modules on each card:
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 does not include hangup notification unless specifically done through forward-disconnect.
Groundstart does include hangup notification.
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:
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 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:
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:
wct4xxp should be replaced with the zaptel module that is loaded as the last one, which ever that is.
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:
ISDN connection handling (CID,DNID)
multiple controller support
digital audio support
DTMF detection/generation
incoming/outgoing calls
CLIP/CLIR
early B3 connects
native ISDN indications
CD, HOLD, RETRIEVE, etc.
overlap sending (dialtone)
DID on point-to-point (PTP)
call progress (INFO_IND)
RX/TX gains
call deflection on circuit busy
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/.
The configuration of capi based devices is fairly straight forward. The first section we need to edit is [general]. section.
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 |
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:
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.Features at a glance:
TE and NT mode (NT mode is currently only supported on HFC based cards)
PTP and PMP mode
DTMF detection
display text messages on isdn phones with alphanumeric display
utilizes new isdn4linux mISDN architecture in *
chan_mISDN is a third party channel module, that has to downloaded seperatly. It can be found at: http://www.beronet.com/?PageID=3017.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This example would detect the extension the caller is coming from and drop them into the voicemail system.
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
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:
where the first number is the conference number and the second is the deafult password for the conference.
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) |
<<< Previous | Home | Next >>> |
Modules, or "Things that make Asterisk work." | Up | The Asterisk Cookbook |