Asterisk config zapata.conf

Business PBX Solutions
Provider Solution Details
Bicom VoIP Become an ITSP Now!
  • Become a serious competitor in VoIP Immediately
  • FULL Consultancy, Installation, Training & Support
  • Sell Hosted IP PBXs, Biz Lines, Call Centre
  • Turnkey Provisioning at your data center
Details
3CX Software PBX for Windows
  • Windows Software Solution
  • Easy to Install and Manage
  • Auto Configures Phones & Trunks
  • Android, iOS, Windows & Mac clients
Details

Zap Channel Module Configuration

The Zap channel module permits Asterisk to communicate with the Zaptel device driver, used to access Zaptel telephony interface cards. You configure Asterisk's Zap channel module in the zapata.conf file.

You will need the Zaptel kernel module device driver installed. See:


Although TDMoE is not directly related to Zapata hardware, it uses a pseudo-TDM engine, and gets configured here.

Creating Channels

The format of the zapata.conf file is unfortunately not as simple as it could be. Most keywords do not do anything by themselves; they merely set up the parameters of any channel definitions that follow. The channel keyword actually creates the channel, using the settings specified before it. For example, you might create two channels like this:

signalling=fxo_ks
language=en
context=reception
channel => 1

signalling=fxo_ks
language=fr
context=sales
channel => 2


This creates channel 1 with a default language code "en" and a context "reception". Channel 2 has a default language code "fr" and context "sales".

This is important, if you put something like echocancel=no before the channel definition, it will effect all channels unless you turn it on later with echocancel=yes. It progresses downward, but the definition must be above the channel=> statement.

Available Settings

Signalling Type

The signalling type to use with your interface is the only mandatory setting. You must set a signalling type before allocating a channel. If you are connecting analog telephone equipment, note that analog phone signalling can be a source of some confusion. FXS channels are signalled with FXO signalling, and vice versa. Asterisk 'talks' to internal devices as the opposite side. An FXO interface card is signalled with FXS signalling by Asterisk, and should be configured as such.

signalling: Sets the channel signalling type. These parameters should match the Zaptel driver configuration. The setting to use depends partly on which interface card you have. Asterisk will fail to start if a channel signalling definition is incorrect or unworkable, if the statements do not match the Zaptel driver configuration, or if the device is not present or properly configured. The correct setting to use is almost certainly one of the following four: fxs_ks, fxo_ks, pri_cpe or pri_net. This setting has no default value; you must set a value before allocating a channel. Asterisk supports the following signalling types:
  • e911: E911 (MF) style signalling. Originating switch goes off-hook, far-end winks, originating sends KP-911-ST, far-end gives answer supervision, Originating-end sends KP-0-ANI-ST
  • em: E & M Immediate Start
  • em_w: E & M Wink Start
  • em_e1: E & M CAS signalling for E1 lines
  • featd: Feature Group D (The fake, Adtran style, DTMF)
  • featdmf_ta: Feature Group D (The real thing, MF (domestic, US)) through a Tandem Access point
  • fgccama Feature Group C-CAMA (DP DNIS, MF ANI)
  • fgccamamf Feature Group C-CAMA MF (MF DNIS, MF ANI)
  • featdmf: Feature Group D (The real thing, MF (domestic, US))
  • featb: Feature Group B (MF (domestic, US))
  • fxs_ls: FXS (Loop Start)
  • fxs_gs: FXS (Ground Start)
  • fxs_ks: FXS (Kewl Start)
  • fxo_ls: FXO (Loop Start)
  • fxo_gs: FXO (Ground Start)
  • fxo_ks: FXO (Kewl Start)
  • pri_cpe: PRI signalling, CPE side
  • pri_net: PRI signalling, Network side (for instance, side that provides the dialtone)
  • sf: SF (Inband Tone) Signalling
  • sf_w: SF Wink
  • sf_featd: SF Feature Group D (The fake, Adtran style, DTMF)
  • sf_featdmf: SF Feature Group D (The real thing, MF (domestic, US))
  • sf_featb: SF Feature Group B (MF (domestic, US))

The following are used for Radio interfaces:

  • em_rx: Receive audio/COR on an E&M interface (1-way)
  • em_tx: Transmit audio/PTT on an E&M interface (1-way)
  • em_txrx: Receive audio/COR AND Transmit audio/PTT on an E&M interface (2-way)
  • em_rxtx: same as em_txrx (for our dyslexic friends)
  • fxs_rx: Receive audio/COR on an FXS kewlstart interface (FXO at the channel bank)
  • fxs_tx: Transmit audio/PTT on an FXS loopstart interface (FXO at the channel bank)
  • fxo_rx: Receive audio/COR on an FXO loopstart interface (FXS at the channel bank)
  • fxo_tx: Transmit audio/PTT on an FXO groundstart interface (FXS at the channel bank)
  • sf_rx: Receive audio/COR on an SF interface (1-way)
  • sf_tx: Transmit audio/PTT on an SF interface (1-way)
  • sf_txrx: Receive audio/COR AND Transmit audio/PTT on an SF interface (2-way)
  • sf_rxtx: same as sf_txrx (for our dyslexic friends)

signalling=fxo_ks



ISDN PRI Switch Configuration

If you have a PRI line, specify your type of switch here. (PRI is a type of ISDN typically used to connect a PBX to a telephone exchange. They have multiple channels on the one connection.)

switchtype: Sets the type of PRI switch being used. Default: national. Acceptable values are:
  • national: National ISDN type2 (common in the US)
  • ni1: National ISDN type 1
  • dms100: Nortel DMS100
  • 4ess: AT&T 4ESS
  • 5ess: Lucent 5ESS
  • euroisdn: EuroISDN
  • qsig: Minimalistic protocol to build a "network" with two or more PBX of different vendors!

resetinterval: sets the time in seconds between restart of unused channels, defaults to
3600 minimum 60 seconds. Some PBXs don't like channel restarts. so set the interval to a
very long interval e.g. 100000000 or 'never' to disable *entirely*.

If you are in Israel, the following is important:

As Bezeq in Israel doesn't like the B-Channel resets happening on the lines, it is best to set
the resetinterval to 'never' when installing a box in Israel. Our past experience also shows
that this parameter may also cause issues on local switches in the UK and China.

For more information: tech at asterisk.org.il

overlapdial: Whether Asterisk can dial this switch using overlap digits. Default: no. If you need Direct Dial-in (DDI; in German "Durchwahl") you should change this to yes, then Asterisk will wait after the last digit it receives
overlapdial=yes

pridialplan: Sets an option required for some (rare) switches that require a dialplan parameter to be passed. This option is ignored by most PRI switches. It may be necessary on a few pieces of hardware. Valid options are: unknown, local, private, national, and international. This option can almost always be left unchanged from the default. Default: national.
pridialplan=local

priindication: Tells how Asterisk should indicate Busy() and Congestion() to the switch/user. Default: inband. Accepted values are:
  • inband: Asterisk plays indication tones without answering; not available on all PRI/BRI subscription lines
  • outofband: Asterisk disconnects with busy/congestion information code so the switch will play the indication tones to the caller. Busy() will now do same as setting PRI_CAUSE=17 and Hangup().
priindication=outofband

nsf: Used with AT&T PRIs. Default: none. Accepted values are:
  • none
  • sdn
  • megacom
  • tollfreemegacom
  • accunet

If outbound calls are being rejected due to "Mandatory information element missing" and the missing IE is 0x20, then you need this setting.

facilityenable: To enable transmission of facility-based ISDN supplementary services (such as caller name from CPE over facility), enable this option.


ISDN BRI Settings

Asterisk is basically capable of supporting BRI zaptel channels, as of (ADD VERSION HERE), but in a very limited manned. e.g: ptmp is not supported, and this may render it useless it many countries. You should basically use pri_cpi and pri_net for TE and NT, respectively. The rest of this section assumes that you have Bristuff installed.

In most cases you would use signalling=bri_cpe_ptmp (for TE: connecting to a telco) or signalling=bri_net_ptmp for NT (connecting an ISDN phone).
At chan_zap's level, we are dealing with ISDN. So theoretically there should be no difference between BRI and PRI. In practice most settings are similar

The recommended settings to try:

signalling=bri_cpe_ptmp
pridialplan=unknown
prilocaldialplan=unknown


Multi-link PPP Options

If you have an ISDN PRI, you may be able to run multi-link PPP over it, to provide you with a data connection. Multi-link PPP is a technology that allows channels on a PRI to be dynamically allocated between voice and data. Asterisk can take voice channels allocated to it, dial a Remote Access Server, and dump the channels into a special extension that delivers the channel to the zaptel data layer. Configure the settings here, and then see the ZapRAS command to make it happen.

PRI channels can have an idle extension and a minunused number. So long as at least minunused channels are idle, the Zap channel module will try to dial idledial on them, and then Asterisk will begin executing the commands for the context and extension specified by idleext. When channels are needed for voice calls, the "idle" calls are disconnected (so long as there are at least minidle calls still running, of course) to make more channels available. The primary use of this is to create a dynamic service, where idle channels are bundled through multilink PPP, thus more efficiently utilizing combined voice/data services than conventional fixed mappings/muxings.

minunused: The minimum number of unused channels available. If there are fewer channels available, Asterisk will not attempt to bundle any channels and give them to the data connection. Takes an integer.

minidle: The minimum number of idle channels to bundle for the data link. Asterisk will keep this number of channels open for data, rather than taking them back for voice channels when needed. Takes an integer.

idledial: The number to dial as the idle number. This is typically the number to dial a Remote Access Server (RAS). Channels being idled for data will be sent to this extension. Takes an integer that does not conflict with any other extension in the Dialplan, and has been defined as an idleext.

idleext: The extension to use as the idle extension. Takes a value in the form of exten@context. Typically, the extension would be an extension to run the ZapRAS command.
minunused=2
minidle=1
idledial=6999
idleext=6999@idle



Analog Trunk Features

usedistinctiveringdetection: Whether or not to attempt to recognize distinctive ring styles on incoming calls. This does not require audio analyisis because rings are simple transitions of the analog line. It's merely a matter of matching the transition pattern. Default: no.
usedistinctiveringdetection=yes

dring1, dring2, dring3: If you set usedistinctiveringdetection=yes, then you may define up to three different distinctive ring styles for Asterisk to attempt to recognize. Each style is defined as a comma separated list of up to three integers. Nobody has yet documented what these numbers mean, so you're on your own when it comes to trying to figure out what numbers to use for the distinctive ring syles used by your phone company in your country. But the tip is to use the Asterisk console in verbose mode, and apparently it reports numbers describing the ring patterns it sees. These patterns may be a starting point:
dring1=96,0,0
dring2=325,95,0
dring3=367,0,0

dring1context, dring2context, dring3context: Along with setting up to three distinctive ring patterns with dring1, dring2 and dring3, you also set corresponding contexts for incoming calls matching those distinctive ring patterns to jump into. If an incoming call does not match any of the distinctive ring patterns defined, then of course it will enter Asterisk with the default context defined for this channel.
dring1context=line2incoming
dring2context=business
dring3context=chocolate

busydetect: If enabled, Asterisk will analyze the audio coming in on the line during a call or a dial attempt to attempt to recognize busy signals. This is useful on analog trunk interfaces both to detect a busy signal when dialing out, and for detecting when the person has hung up. See also Disconnect Supervision. Be sure that you don't use this on digital interfaces like QuadBri cards and so on. Otherwise you will run in "broken calls" problems. default=no
busydetect=yes

busycount: This option requires busydetect=yes. You can specify how many busy tones to wait before hanging up. The default is 3, but better results can be achieved if set to 6 or even 8. The higher the number, the more time is needed to detect a disconnected channel, but the lower the probability mistaking some other sound as being a busy tone.
busycount=5

callprogress: Asterisk can attempt to monitor the state of the call to listen for a ringing tone, busy tone, congestion tone, and sounds indicating that the line has been answered. It appears that this feature is independent of the busydetect feature; it seems that both can run in parallel, and both will independently attempt to recognize a busy tone. The callprogress feature is highly experimental and can easily detect false answers, so don't count on it being very accurate. Also, it is currently configured only for standard U.S. phone tones. Default: no.
callprogress = yes

pulse: The standard installation of Asterisk does not permit you to specify that a Zaptel device use pulse dialing, even though the Zaptel driver supports pulse dialing. But you can apply a patch file to enable you to specify pulse dialing with the pulse keyword. See Pulse Dialling on Zap Channels for the patch.
pulse=yes

Analog Handset Features

adsi: If your handset has ADSI (Analog Display Services Interface) capability, set set adsi=yes. The ADSI specification is system similar to Caller ID to pass encoded information to an analog handset. It allows the creation of interactive visual menus on a multiline display, offering access to services such as voicemail through a text interface.

immediate: Normally (i.e. with immediate set to 'no', the default), when you lift an FXS handset, the Zaptel driver provides you a dialtone and listens for digits that you dial, passing them on to Asterisk. Asterisk waits until the number you've dialled matches an extension, and then begins executing the first command on the matching extension. If you set immediate=yes, then Asterisk will instruct the Zaptel driver to not generate a dialtone when you lift a handset, instead passing control immediately to Asterisk. Asterisk will start executing the commands for this channel's "s" extension. This is sometimes referred to as "batphone mode". Default: no.
immediate=yes

callwaiting: If enabled, Asterisk will generate "call waiting pips" when you are already in a conversation on your FXS handset when someone tries to call you. If the channel has call waiting by default, you can temporarily disable it by lifting the handset and dialing *70, whereupon you will get a dialrecall tone and may then dial the intended number. There is no corresponding way to temporarily enable call waiting for channels that have it off by default. Default: no.
callwaiting=yes

callwaitingcallerid: Sets whether Asterisk will send Caller ID data to the handset during call waiting indication. Requires also setting callwaiting=yes. Default: no.
callwaitingcallerid=yes

threewaycalling: If enabled, you can place a call on hold by pressing a hook flash, whereupon you get a dialrecall tone and can make another call. Default: no.
threewaycalling=yes

transfer: This option has effect only when threewaycalling=yes. If threewaycalling=yes and transfer=yes, then once you've placed a call on hold with a hook flash, you can transfer that call to another extension by dialling the extension and hanging up. Default: no.
transfer=yes

cancallforward: If enabled, you may activate "call forwarding immediate" by dialling *72 (whereupon you get a dialrecall tone) followed by the extension number you wish to forward your calls to. If someone dials your extension, the call will be redirected to the forwarding number. You may disable the call forwarding by dialing *73. Default: no.
cancallforward=yes

callreturn: If enabled, you may dial *69 to have Asterisk read to you the caller ID of the last person to call. You will hear the dialrecall tone if there is no record of a last caller. Default: no.
callreturn=yes

callgroup: A channel may belong to zero or more callgroups. Callgroups specify who may answer this phone when it is ringing. If this channel is ringing, then any other channel whose pickupgroups include one of this channel's callgroups may answer the call by dialing *8#. This feature is supported by Zap, SIP, Skinny and MGCP channels. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.
group=1
callgroup=1,2,3

pickupgroup: A channel may belong to zero or more pickupgroups. Pickupgroups specify whose phones you may answer. If another channel is ringing, and this channel's pickupgroups include one of the ringing channel's callgroups, then this channel may answer the call by dialing *8#. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.
group=1

See more about Channels and Groups

If you dial *8# when there is more than one channel whose calls you are eligible to answer, then it just answers the "first ringing channel", i.e. you have no control which one you pick up.
pickupgroup=3,4

useincomingcalleridonzaptransfer: If you set this option (Use Incoming Caller ID On Zap Transfer) to 'yes', then when you transfer a call to another phone, the original caller's Caller ID will get forwarded on too. Default: no.
useincomingcalleridonzaptransfer=yes

Caller ID Options

callerid: Sets the Caller ID string to forward to the recipient when calls come in from this channel. You normally use this to set the Caller ID for handsets. Specify the Caller ID name in double quotation marks, followed by the Caller ID number in <> symbols. For trunk lines, set to "asreceived" to pass the received Caller ID forward.
callerid="Mark Spencer" <256 428-6000>
callerid=
callerid=asreceived

Important Note: Caller ID can only be transmitted to the public phone network with supported hardware, such as a PRI. It is not possible to set external caller ID on analog lines.

usecallerid: For handsets, this option will cause Asterisk to send Caller ID data to the handset when ringing it. For trunk lines, this option causes Asterisk to look for Caller ID on incoming calls. Default: yes.
usecallerid=no

hidecallerid: (Not for FXO trunk lines) For PRI channels, this will stop the sending of Caller ID on outgoing calls. For FXS handsets, this will stop Asterisk from sending this channel's Caller ID information to the called party when you make a call using this handset. FXS handset users may enable or disable sending of their Caller ID for the current call only by lifting the handset and dialing *82 (enable) or *67 (disable); you will then get a "dialrecall" tone whereupon you can dial the number of the extension you wish to contact. Default: no.
hidecallerid=yes

restrictcid: (PRI channels only) This option has effect only when hidecallerid=no. If hidecallerid=no and restrictcid=yes, Asterisk will prevent the sending of the Caller ID data as a presentation number when making outgoing calls (ANI data is still sent). Default: no.
restrictcid=yes

usecallingpres: (PRI channels only) Whether or not to use the Caller ID presentation for the outgoing call that the calling switch is sending. See also the CallingPres command. Read more in this discussion from 2003.
usecallingpres=no

Incoming Caller ID Options

internationalprefix: 00
nationalprefix:0

If these are not set, missed calls or received calls show up without the leading zero, and you cannot call them back.

Audio Quality Tuning Options

These options adjust certain parameters of Asterisk that affect the audio quality of Zapata channels. See also:

relaxdtmf: If you are having trouble with DTMF detection, you can relax the DTMF detection parameters. Relaxing them may make the DTMF detector more likely to have "talkoff" where DTMF is detected when it shouldn't be. Default: no.
relaxdtmf=yes

echocancel: Disable or enable echo cancellation (default is 'yes'). It is recommended that you do not turn this off. You may specify echocancel as 'yes' (128 taps), 'no' (0 taps, disabled), or a preset number of taps which are one of 16, 32, 64, 128, or 256. Each tap is one sample from the data stream, so on a T1 this will be 1/8000 of a second. Accordingly the number of taps equate to a 2ms, 4ms, 8ms, 16ms or 32ms tail length. Beware that if you set echocancel to a different value, Asterisk will fall back to the default of 128 taps without warning.
echocancel=no

echocancelwhenbridged: Enables or disables echo cancellation during a bridged TDM call. In principle, TDM bridged calls should not require echo cancellation, but often times audio performance is improved with this option enabled. Default: no.
echocancelwhenbridged=yes

echotraining: In some cases, the echo canceller doesn't train quickly enough and there is echo at the beginning of the call which then quickly fades out. Enabling echo training will cause Asterisk to briefly mute the channel, send an impulse, and use the impulse response to pre-train the echo canceller so it can start out with a much closer idea of the actual echo. However, the characteristics of some trunks may change as the endpoints become connected and, if there is a considerable delay between the circuit being 'up' and the endpoints being finalised, the training impulse may measure the characteristics of the open trunk rather than the completed circuit. Accordingly you may either specify a value between 10ms and 4000ms to delay before starting the impulse response process or 'yes', which equates to 400ms. Default: undefined.
echotraining=no

rxgain: Adjusts receive gain. This is the audio recieved by Asterisk from the device. E.g: in a phone connected to a FXS channel, this would control the audio that is sent from the phone to Asterisk. This can be used to raise or lower the incoming volume to compensate for hardware differences. You specify gain as a decimal number from -100 to 100 representing dB. 10 is significantly high. Change these options by only a few dB at a time. Default value: 0.0
rxgain=4.2

txgain: Adjusts transmit gain. This is the audio transmitted by Asterisk to the device. E.g: in a phone connected to a FXS device this would control the audio that is heard in the handset. This can be used to raise or lower the outgoing volume to compensate for hardware differences. Takes the same type of argument as rxgain. Default: 0.0
txgain=-10.2

See: Asterisk zapata gain adjustment

Call Logging Options

Asterisk normally generates Call Detail Records (CDR), being a log or database of the calls made through Asterisk. This data can be used for Automated Machine Accounting (AMA). See Asterisk Billing.

accountcode: Sets the data for the "account code" field in the CDR for calls placed from this channel. The account code may be any alphanumeric string. It may be overridden at call time with the Asterisk cmd SetAccount command.
accountcode=spencer145

amaflags: Sets the AMA flags, affecting the categorization of entries in the call detail records. Possible values are:
  • default: Let the CDR system use its default value.
  • omit: Do not record calls.
  • billing: Mark the entry for billing
  • documentation: Mark the entry for documentation.
amaflags=billing

Timing Parameters


These keywords are used only with (non-PRI) T1 lines. All values are in milliseconds. These do not need to be set in most configurations, as the defaults work with most hardware. It has been noted that the common Adtran Atlas uses long winks of about 300 milliseconds, and channels from them should be configured accordingly.

prewink: Sets the pre-wink timing.
preflash: Sets the pre-flash timing.
wink: Sets the wink timing.
rxwink: Sets the receive wink timing.
rxflash: Sets the receive flash timing.
flash: Sets the flash timing.
start: Sets the start timing.
debounce: Sets the debounce timing. "The debounce settings in the Asterisk configuration affects how Asterisk
handles hookswitch transitions on its FXO/FXS interfaces." — Derek Bruce

rxwink=300
prewink=20~~

Other Features

mailbox: If this option is defined for a channel, then when the handset is lifted, Asterisk will check the voicemail mailbox(es) specified here for new (unheard) messages. If there are any unheard messages in any of the mailboxes, Asterisk will use a stutter dialtone rather than the ordinary dialtone. On supported hardware, the message waiting light will also be activated. It accomplishes this by sending a standard FSK tone down the line that lights up the MWI on any capable analog phone.

The parameters to this option are one or more comma-separated mailbox numbers, as defined in voicemail.conf.

mailbox = 1234
mailbox = 1,2

For each mailbox, if the mailbox is in a context other than "default", place the context after the mailbox number
separated by an at sign (@).

mailbox = 1234@office
mailbox = 12@office,34@home

group: Allows you to group together a number of channels so that the Dial command will treat the group as a single channel. When Dial tries to make a call on a Zap group, the Zap channel module will use the first available (i.e. non-busy) channel in the group for the call. Multiple group memberships may be specified with commas, and to signify no group membership, the portion after the equals sign may be omitted. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.

group=1
group=2,3
group=

See more about Channels and Groups

language: Each channel has a default language code that affects which language version of prerecorded sounds Asterisk uses for this channel. See Setting up a Multi-Language Asterisk Installation. The default is an empty string.
language=en

progzone: This defines the timing and frequencies for call progress detection, which are buried in the sources in asterisk/dsp.c. This is DIFFERENT than the call progress timing defined in zaptel/zonedata.c and in /etc/asterisk/indications.conf, and so far only options you can use (defined in dsp.c) are us, ca, br, cr and uk. (This was added sometime between 1.0.9 stable and 1.2 beta). Default is: us

Important Stuff

context: This specifies which context a call will start in. The context controls how Asterisk will handle the call. Contexts are defined in the Dialplan. Default: "default".
context=internal

channel: This keyword is unlike all the other keywords in this configuration file, because where all the other keywords merely specify settings to use, this keyword causes Asterisk to actually allocate a channel with the settings that have been specified earlier in the file.

The channel keyword defines one or more channels. Each channel definition will inherit all options stated ahead of it in this file. Channels maybe specified individually, separated by commas, or as a range separated by a hyphen. Allocating a channel will not "clear" the settings, so any channels defined later on in this file will inherit the options for this channel unless you override settings.

channel => 16
channel => 2,3
channel => 1-8

Obsolete Settings

stripmsd: (Obsolete) Strip the 'Most Significant Digit,' the first digit or digits from all calls outbound on the given trunk channels. Takes as an argument the number of digits to strip. Use ${EXTEN:x} for this functionality.


Example Settings Files



zapata.conf.sample

The /usr/src/asterisk/configs/zapata.conf.sample file from your downloaded source code is the best reference for what keywords are available in your specific version of Asterisk.

See Also




Asterisk | Channels | Zap Channels | Asterisk Configuration

Zap Channel Module Configuration

The Zap channel module permits Asterisk to communicate with the Zaptel device driver, used to access Zaptel telephony interface cards. You configure Asterisk's Zap channel module in the zapata.conf file.

You will need the Zaptel kernel module device driver installed. See:


Although TDMoE is not directly related to Zapata hardware, it uses a pseudo-TDM engine, and gets configured here.

Creating Channels

The format of the zapata.conf file is unfortunately not as simple as it could be. Most keywords do not do anything by themselves; they merely set up the parameters of any channel definitions that follow. The channel keyword actually creates the channel, using the settings specified before it. For example, you might create two channels like this:

signalling=fxo_ks
language=en
context=reception
channel => 1

signalling=fxo_ks
language=fr
context=sales
channel => 2


This creates channel 1 with a default language code "en" and a context "reception". Channel 2 has a default language code "fr" and context "sales".

This is important, if you put something like echocancel=no before the channel definition, it will effect all channels unless you turn it on later with echocancel=yes. It progresses downward, but the definition must be above the channel=> statement.

Available Settings

Signalling Type

The signalling type to use with your interface is the only mandatory setting. You must set a signalling type before allocating a channel. If you are connecting analog telephone equipment, note that analog phone signalling can be a source of some confusion. FXS channels are signalled with FXO signalling, and vice versa. Asterisk 'talks' to internal devices as the opposite side. An FXO interface card is signalled with FXS signalling by Asterisk, and should be configured as such.

signalling: Sets the channel signalling type. These parameters should match the Zaptel driver configuration. The setting to use depends partly on which interface card you have. Asterisk will fail to start if a channel signalling definition is incorrect or unworkable, if the statements do not match the Zaptel driver configuration, or if the device is not present or properly configured. The correct setting to use is almost certainly one of the following four: fxs_ks, fxo_ks, pri_cpe or pri_net. This setting has no default value; you must set a value before allocating a channel. Asterisk supports the following signalling types:
  • e911: E911 (MF) style signalling. Originating switch goes off-hook, far-end winks, originating sends KP-911-ST, far-end gives answer supervision, Originating-end sends KP-0-ANI-ST
  • em: E & M Immediate Start
  • em_w: E & M Wink Start
  • em_e1: E & M CAS signalling for E1 lines
  • featd: Feature Group D (The fake, Adtran style, DTMF)
  • featdmf_ta: Feature Group D (The real thing, MF (domestic, US)) through a Tandem Access point
  • fgccama Feature Group C-CAMA (DP DNIS, MF ANI)
  • fgccamamf Feature Group C-CAMA MF (MF DNIS, MF ANI)
  • featdmf: Feature Group D (The real thing, MF (domestic, US))
  • featb: Feature Group B (MF (domestic, US))
  • fxs_ls: FXS (Loop Start)
  • fxs_gs: FXS (Ground Start)
  • fxs_ks: FXS (Kewl Start)
  • fxo_ls: FXO (Loop Start)
  • fxo_gs: FXO (Ground Start)
  • fxo_ks: FXO (Kewl Start)
  • pri_cpe: PRI signalling, CPE side
  • pri_net: PRI signalling, Network side (for instance, side that provides the dialtone)
  • sf: SF (Inband Tone) Signalling
  • sf_w: SF Wink
  • sf_featd: SF Feature Group D (The fake, Adtran style, DTMF)
  • sf_featdmf: SF Feature Group D (The real thing, MF (domestic, US))
  • sf_featb: SF Feature Group B (MF (domestic, US))

The following are used for Radio interfaces:

  • em_rx: Receive audio/COR on an E&M interface (1-way)
  • em_tx: Transmit audio/PTT on an E&M interface (1-way)
  • em_txrx: Receive audio/COR AND Transmit audio/PTT on an E&M interface (2-way)
  • em_rxtx: same as em_txrx (for our dyslexic friends)
  • fxs_rx: Receive audio/COR on an FXS kewlstart interface (FXO at the channel bank)
  • fxs_tx: Transmit audio/PTT on an FXS loopstart interface (FXO at the channel bank)
  • fxo_rx: Receive audio/COR on an FXO loopstart interface (FXS at the channel bank)
  • fxo_tx: Transmit audio/PTT on an FXO groundstart interface (FXS at the channel bank)
  • sf_rx: Receive audio/COR on an SF interface (1-way)
  • sf_tx: Transmit audio/PTT on an SF interface (1-way)
  • sf_txrx: Receive audio/COR AND Transmit audio/PTT on an SF interface (2-way)
  • sf_rxtx: same as sf_txrx (for our dyslexic friends)

signalling=fxo_ks



ISDN PRI Switch Configuration

If you have a PRI line, specify your type of switch here. (PRI is a type of ISDN typically used to connect a PBX to a telephone exchange. They have multiple channels on the one connection.)

switchtype: Sets the type of PRI switch being used. Default: national. Acceptable values are:
  • national: National ISDN type2 (common in the US)
  • ni1: National ISDN type 1
  • dms100: Nortel DMS100
  • 4ess: AT&T 4ESS
  • 5ess: Lucent 5ESS
  • euroisdn: EuroISDN
  • qsig: Minimalistic protocol to build a "network" with two or more PBX of different vendors!

resetinterval: sets the time in seconds between restart of unused channels, defaults to
3600 minimum 60 seconds. Some PBXs don't like channel restarts. so set the interval to a
very long interval e.g. 100000000 or 'never' to disable *entirely*.

If you are in Israel, the following is important:

As Bezeq in Israel doesn't like the B-Channel resets happening on the lines, it is best to set
the resetinterval to 'never' when installing a box in Israel. Our past experience also shows
that this parameter may also cause issues on local switches in the UK and China.

For more information: tech at asterisk.org.il

overlapdial: Whether Asterisk can dial this switch using overlap digits. Default: no. If you need Direct Dial-in (DDI; in German "Durchwahl") you should change this to yes, then Asterisk will wait after the last digit it receives
overlapdial=yes

pridialplan: Sets an option required for some (rare) switches that require a dialplan parameter to be passed. This option is ignored by most PRI switches. It may be necessary on a few pieces of hardware. Valid options are: unknown, local, private, national, and international. This option can almost always be left unchanged from the default. Default: national.
pridialplan=local

priindication: Tells how Asterisk should indicate Busy() and Congestion() to the switch/user. Default: inband. Accepted values are:
  • inband: Asterisk plays indication tones without answering; not available on all PRI/BRI subscription lines
  • outofband: Asterisk disconnects with busy/congestion information code so the switch will play the indication tones to the caller. Busy() will now do same as setting PRI_CAUSE=17 and Hangup().
priindication=outofband

nsf: Used with AT&T PRIs. Default: none. Accepted values are:
  • none
  • sdn
  • megacom
  • tollfreemegacom
  • accunet

If outbound calls are being rejected due to "Mandatory information element missing" and the missing IE is 0x20, then you need this setting.

facilityenable: To enable transmission of facility-based ISDN supplementary services (such as caller name from CPE over facility), enable this option.


ISDN BRI Settings

Asterisk is basically capable of supporting BRI zaptel channels, as of (ADD VERSION HERE), but in a very limited manned. e.g: ptmp is not supported, and this may render it useless it many countries. You should basically use pri_cpi and pri_net for TE and NT, respectively. The rest of this section assumes that you have Bristuff installed.

In most cases you would use signalling=bri_cpe_ptmp (for TE: connecting to a telco) or signalling=bri_net_ptmp for NT (connecting an ISDN phone).
At chan_zap's level, we are dealing with ISDN. So theoretically there should be no difference between BRI and PRI. In practice most settings are similar

The recommended settings to try:

signalling=bri_cpe_ptmp
pridialplan=unknown
prilocaldialplan=unknown


Multi-link PPP Options

If you have an ISDN PRI, you may be able to run multi-link PPP over it, to provide you with a data connection. Multi-link PPP is a technology that allows channels on a PRI to be dynamically allocated between voice and data. Asterisk can take voice channels allocated to it, dial a Remote Access Server, and dump the channels into a special extension that delivers the channel to the zaptel data layer. Configure the settings here, and then see the ZapRAS command to make it happen.

PRI channels can have an idle extension and a minunused number. So long as at least minunused channels are idle, the Zap channel module will try to dial idledial on them, and then Asterisk will begin executing the commands for the context and extension specified by idleext. When channels are needed for voice calls, the "idle" calls are disconnected (so long as there are at least minidle calls still running, of course) to make more channels available. The primary use of this is to create a dynamic service, where idle channels are bundled through multilink PPP, thus more efficiently utilizing combined voice/data services than conventional fixed mappings/muxings.

minunused: The minimum number of unused channels available. If there are fewer channels available, Asterisk will not attempt to bundle any channels and give them to the data connection. Takes an integer.

minidle: The minimum number of idle channels to bundle for the data link. Asterisk will keep this number of channels open for data, rather than taking them back for voice channels when needed. Takes an integer.

idledial: The number to dial as the idle number. This is typically the number to dial a Remote Access Server (RAS). Channels being idled for data will be sent to this extension. Takes an integer that does not conflict with any other extension in the Dialplan, and has been defined as an idleext.

idleext: The extension to use as the idle extension. Takes a value in the form of exten@context. Typically, the extension would be an extension to run the ZapRAS command.
minunused=2
minidle=1
idledial=6999
idleext=6999@idle



Analog Trunk Features

usedistinctiveringdetection: Whether or not to attempt to recognize distinctive ring styles on incoming calls. This does not require audio analyisis because rings are simple transitions of the analog line. It's merely a matter of matching the transition pattern. Default: no.
usedistinctiveringdetection=yes

dring1, dring2, dring3: If you set usedistinctiveringdetection=yes, then you may define up to three different distinctive ring styles for Asterisk to attempt to recognize. Each style is defined as a comma separated list of up to three integers. Nobody has yet documented what these numbers mean, so you're on your own when it comes to trying to figure out what numbers to use for the distinctive ring syles used by your phone company in your country. But the tip is to use the Asterisk console in verbose mode, and apparently it reports numbers describing the ring patterns it sees. These patterns may be a starting point:
dring1=96,0,0
dring2=325,95,0
dring3=367,0,0

dring1context, dring2context, dring3context: Along with setting up to three distinctive ring patterns with dring1, dring2 and dring3, you also set corresponding contexts for incoming calls matching those distinctive ring patterns to jump into. If an incoming call does not match any of the distinctive ring patterns defined, then of course it will enter Asterisk with the default context defined for this channel.
dring1context=line2incoming
dring2context=business
dring3context=chocolate

busydetect: If enabled, Asterisk will analyze the audio coming in on the line during a call or a dial attempt to attempt to recognize busy signals. This is useful on analog trunk interfaces both to detect a busy signal when dialing out, and for detecting when the person has hung up. See also Disconnect Supervision. Be sure that you don't use this on digital interfaces like QuadBri cards and so on. Otherwise you will run in "broken calls" problems. default=no
busydetect=yes

busycount: This option requires busydetect=yes. You can specify how many busy tones to wait before hanging up. The default is 3, but better results can be achieved if set to 6 or even 8. The higher the number, the more time is needed to detect a disconnected channel, but the lower the probability mistaking some other sound as being a busy tone.
busycount=5

callprogress: Asterisk can attempt to monitor the state of the call to listen for a ringing tone, busy tone, congestion tone, and sounds indicating that the line has been answered. It appears that this feature is independent of the busydetect feature; it seems that both can run in parallel, and both will independently attempt to recognize a busy tone. The callprogress feature is highly experimental and can easily detect false answers, so don't count on it being very accurate. Also, it is currently configured only for standard U.S. phone tones. Default: no.
callprogress = yes

pulse: The standard installation of Asterisk does not permit you to specify that a Zaptel device use pulse dialing, even though the Zaptel driver supports pulse dialing. But you can apply a patch file to enable you to specify pulse dialing with the pulse keyword. See Pulse Dialling on Zap Channels for the patch.
pulse=yes

Analog Handset Features

adsi: If your handset has ADSI (Analog Display Services Interface) capability, set set adsi=yes. The ADSI specification is system similar to Caller ID to pass encoded information to an analog handset. It allows the creation of interactive visual menus on a multiline display, offering access to services such as voicemail through a text interface.

immediate: Normally (i.e. with immediate set to 'no', the default), when you lift an FXS handset, the Zaptel driver provides you a dialtone and listens for digits that you dial, passing them on to Asterisk. Asterisk waits until the number you've dialled matches an extension, and then begins executing the first command on the matching extension. If you set immediate=yes, then Asterisk will instruct the Zaptel driver to not generate a dialtone when you lift a handset, instead passing control immediately to Asterisk. Asterisk will start executing the commands for this channel's "s" extension. This is sometimes referred to as "batphone mode". Default: no.
immediate=yes

callwaiting: If enabled, Asterisk will generate "call waiting pips" when you are already in a conversation on your FXS handset when someone tries to call you. If the channel has call waiting by default, you can temporarily disable it by lifting the handset and dialing *70, whereupon you will get a dialrecall tone and may then dial the intended number. There is no corresponding way to temporarily enable call waiting for channels that have it off by default. Default: no.
callwaiting=yes

callwaitingcallerid: Sets whether Asterisk will send Caller ID data to the handset during call waiting indication. Requires also setting callwaiting=yes. Default: no.
callwaitingcallerid=yes

threewaycalling: If enabled, you can place a call on hold by pressing a hook flash, whereupon you get a dialrecall tone and can make another call. Default: no.
threewaycalling=yes

transfer: This option has effect only when threewaycalling=yes. If threewaycalling=yes and transfer=yes, then once you've placed a call on hold with a hook flash, you can transfer that call to another extension by dialling the extension and hanging up. Default: no.
transfer=yes

cancallforward: If enabled, you may activate "call forwarding immediate" by dialling *72 (whereupon you get a dialrecall tone) followed by the extension number you wish to forward your calls to. If someone dials your extension, the call will be redirected to the forwarding number. You may disable the call forwarding by dialing *73. Default: no.
cancallforward=yes

callreturn: If enabled, you may dial *69 to have Asterisk read to you the caller ID of the last person to call. You will hear the dialrecall tone if there is no record of a last caller. Default: no.
callreturn=yes

callgroup: A channel may belong to zero or more callgroups. Callgroups specify who may answer this phone when it is ringing. If this channel is ringing, then any other channel whose pickupgroups include one of this channel's callgroups may answer the call by dialing *8#. This feature is supported by Zap, SIP, Skinny and MGCP channels. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.
group=1
callgroup=1,2,3

pickupgroup: A channel may belong to zero or more pickupgroups. Pickupgroups specify whose phones you may answer. If another channel is ringing, and this channel's pickupgroups include one of the ringing channel's callgroups, then this channel may answer the call by dialing *8#. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.
group=1

See more about Channels and Groups

If you dial *8# when there is more than one channel whose calls you are eligible to answer, then it just answers the "first ringing channel", i.e. you have no control which one you pick up.
pickupgroup=3,4

useincomingcalleridonzaptransfer: If you set this option (Use Incoming Caller ID On Zap Transfer) to 'yes', then when you transfer a call to another phone, the original caller's Caller ID will get forwarded on too. Default: no.
useincomingcalleridonzaptransfer=yes

Caller ID Options

callerid: Sets the Caller ID string to forward to the recipient when calls come in from this channel. You normally use this to set the Caller ID for handsets. Specify the Caller ID name in double quotation marks, followed by the Caller ID number in <> symbols. For trunk lines, set to "asreceived" to pass the received Caller ID forward.
callerid="Mark Spencer" <256 428-6000>
callerid=
callerid=asreceived

Important Note: Caller ID can only be transmitted to the public phone network with supported hardware, such as a PRI. It is not possible to set external caller ID on analog lines.

usecallerid: For handsets, this option will cause Asterisk to send Caller ID data to the handset when ringing it. For trunk lines, this option causes Asterisk to look for Caller ID on incoming calls. Default: yes.
usecallerid=no

hidecallerid: (Not for FXO trunk lines) For PRI channels, this will stop the sending of Caller ID on outgoing calls. For FXS handsets, this will stop Asterisk from sending this channel's Caller ID information to the called party when you make a call using this handset. FXS handset users may enable or disable sending of their Caller ID for the current call only by lifting the handset and dialing *82 (enable) or *67 (disable); you will then get a "dialrecall" tone whereupon you can dial the number of the extension you wish to contact. Default: no.
hidecallerid=yes

restrictcid: (PRI channels only) This option has effect only when hidecallerid=no. If hidecallerid=no and restrictcid=yes, Asterisk will prevent the sending of the Caller ID data as a presentation number when making outgoing calls (ANI data is still sent). Default: no.
restrictcid=yes

usecallingpres: (PRI channels only) Whether or not to use the Caller ID presentation for the outgoing call that the calling switch is sending. See also the CallingPres command. Read more in this discussion from 2003.
usecallingpres=no

Incoming Caller ID Options

internationalprefix: 00
nationalprefix:0

If these are not set, missed calls or received calls show up without the leading zero, and you cannot call them back.

Audio Quality Tuning Options

These options adjust certain parameters of Asterisk that affect the audio quality of Zapata channels. See also:

relaxdtmf: If you are having trouble with DTMF detection, you can relax the DTMF detection parameters. Relaxing them may make the DTMF detector more likely to have "talkoff" where DTMF is detected when it shouldn't be. Default: no.
relaxdtmf=yes

echocancel: Disable or enable echo cancellation (default is 'yes'). It is recommended that you do not turn this off. You may specify echocancel as 'yes' (128 taps), 'no' (0 taps, disabled), or a preset number of taps which are one of 16, 32, 64, 128, or 256. Each tap is one sample from the data stream, so on a T1 this will be 1/8000 of a second. Accordingly the number of taps equate to a 2ms, 4ms, 8ms, 16ms or 32ms tail length. Beware that if you set echocancel to a different value, Asterisk will fall back to the default of 128 taps without warning.
echocancel=no

echocancelwhenbridged: Enables or disables echo cancellation during a bridged TDM call. In principle, TDM bridged calls should not require echo cancellation, but often times audio performance is improved with this option enabled. Default: no.
echocancelwhenbridged=yes

echotraining: In some cases, the echo canceller doesn't train quickly enough and there is echo at the beginning of the call which then quickly fades out. Enabling echo training will cause Asterisk to briefly mute the channel, send an impulse, and use the impulse response to pre-train the echo canceller so it can start out with a much closer idea of the actual echo. However, the characteristics of some trunks may change as the endpoints become connected and, if there is a considerable delay between the circuit being 'up' and the endpoints being finalised, the training impulse may measure the characteristics of the open trunk rather than the completed circuit. Accordingly you may either specify a value between 10ms and 4000ms to delay before starting the impulse response process or 'yes', which equates to 400ms. Default: undefined.
echotraining=no

rxgain: Adjusts receive gain. This is the audio recieved by Asterisk from the device. E.g: in a phone connected to a FXS channel, this would control the audio that is sent from the phone to Asterisk. This can be used to raise or lower the incoming volume to compensate for hardware differences. You specify gain as a decimal number from -100 to 100 representing dB. 10 is significantly high. Change these options by only a few dB at a time. Default value: 0.0
rxgain=4.2

txgain: Adjusts transmit gain. This is the audio transmitted by Asterisk to the device. E.g: in a phone connected to a FXS device this would control the audio that is heard in the handset. This can be used to raise or lower the outgoing volume to compensate for hardware differences. Takes the same type of argument as rxgain. Default: 0.0
txgain=-10.2

See: Asterisk zapata gain adjustment

Call Logging Options

Asterisk normally generates Call Detail Records (CDR), being a log or database of the calls made through Asterisk. This data can be used for Automated Machine Accounting (AMA). See Asterisk Billing.

accountcode: Sets the data for the "account code" field in the CDR for calls placed from this channel. The account code may be any alphanumeric string. It may be overridden at call time with the Asterisk cmd SetAccount command.
accountcode=spencer145

amaflags: Sets the AMA flags, affecting the categorization of entries in the call detail records. Possible values are:
  • default: Let the CDR system use its default value.
  • omit: Do not record calls.
  • billing: Mark the entry for billing
  • documentation: Mark the entry for documentation.
amaflags=billing

Timing Parameters


These keywords are used only with (non-PRI) T1 lines. All values are in milliseconds. These do not need to be set in most configurations, as the defaults work with most hardware. It has been noted that the common Adtran Atlas uses long winks of about 300 milliseconds, and channels from them should be configured accordingly.

prewink: Sets the pre-wink timing.
preflash: Sets the pre-flash timing.
wink: Sets the wink timing.
rxwink: Sets the receive wink timing.
rxflash: Sets the receive flash timing.
flash: Sets the flash timing.
start: Sets the start timing.
debounce: Sets the debounce timing. "The debounce settings in the Asterisk configuration affects how Asterisk
handles hookswitch transitions on its FXO/FXS interfaces." — Derek Bruce

rxwink=300
prewink=20~~

Other Features

mailbox: If this option is defined for a channel, then when the handset is lifted, Asterisk will check the voicemail mailbox(es) specified here for new (unheard) messages. If there are any unheard messages in any of the mailboxes, Asterisk will use a stutter dialtone rather than the ordinary dialtone. On supported hardware, the message waiting light will also be activated. It accomplishes this by sending a standard FSK tone down the line that lights up the MWI on any capable analog phone.

The parameters to this option are one or more comma-separated mailbox numbers, as defined in voicemail.conf.

mailbox = 1234
mailbox = 1,2

For each mailbox, if the mailbox is in a context other than "default", place the context after the mailbox number
separated by an at sign (@).

mailbox = 1234@office
mailbox = 12@office,34@home

group: Allows you to group together a number of channels so that the Dial command will treat the group as a single channel. When Dial tries to make a call on a Zap group, the Zap channel module will use the first available (i.e. non-busy) channel in the group for the call. Multiple group memberships may be specified with commas, and to signify no group membership, the portion after the equals sign may be omitted. Group numbers can range from 0 to 31. The default value is an empty string, i.e. no groups.

group=1
group=2,3
group=

See more about Channels and Groups

language: Each channel has a default language code that affects which language version of prerecorded sounds Asterisk uses for this channel. See Setting up a Multi-Language Asterisk Installation. The default is an empty string.
language=en

progzone: This defines the timing and frequencies for call progress detection, which are buried in the sources in asterisk/dsp.c. This is DIFFERENT than the call progress timing defined in zaptel/zonedata.c and in /etc/asterisk/indications.conf, and so far only options you can use (defined in dsp.c) are us, ca, br, cr and uk. (This was added sometime between 1.0.9 stable and 1.2 beta). Default is: us

Important Stuff

context: This specifies which context a call will start in. The context controls how Asterisk will handle the call. Contexts are defined in the Dialplan. Default: "default".
context=internal

channel: This keyword is unlike all the other keywords in this configuration file, because where all the other keywords merely specify settings to use, this keyword causes Asterisk to actually allocate a channel with the settings that have been specified earlier in the file.

The channel keyword defines one or more channels. Each channel definition will inherit all options stated ahead of it in this file. Channels maybe specified individually, separated by commas, or as a range separated by a hyphen. Allocating a channel will not "clear" the settings, so any channels defined later on in this file will inherit the options for this channel unless you override settings.

channel => 16
channel => 2,3
channel => 1-8

Obsolete Settings

stripmsd: (Obsolete) Strip the 'Most Significant Digit,' the first digit or digits from all calls outbound on the given trunk channels. Takes as an argument the number of digits to strip. Use ${EXTEN:x} for this functionality.


Example Settings Files



zapata.conf.sample

The /usr/src/asterisk/configs/zapata.conf.sample file from your downloaded source code is the best reference for what keywords are available in your specific version of Asterisk.

See Also




Asterisk | Channels | Zap Channels | Asterisk Configuration

Created by: oej, Last modification: Mon 30 of Aug, 2010 (23:04 UTC) by shuheiy
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+