Section 17.4. Asterisk Channels

17.4. Asterisk Channels

While extensions.conf is the main place Asterisk's dial-plan is configured, other files are needed to set up the VoIP and TDM interfacing necessary to allow the Asterisk server to communicate with the outside world. These files include zapata.conf , zaptel.conf , and sip.conf .

17.4.1. Zaptel Channels

Digium's Wildcard interface cards enable legacy channels so Asterisk can communicate using T1s and analog phones or POTS lines. Chapter 3 describe how to obtain and install Asterisk with the Linux drivers for a kernel interface to the Wildcard product line, an interface known as Zaptel.

Once installed, the ztcfg program, included with the drivers, can be used to query the zapata.conf file to validate your Zaptel channel configuration. These files determine:

• The ID number for each legacy interface channel that will be referenced in extensions.conf . Each card must be assigned a unique number

• The kind of signaling that each legacy interface card will use (T1, FXO, FXS, etc.)

• What localized ringback tones will be used with each interface card. English ringback tones sound different than American ones. Consult the latest Zaptel build to find out which localities are currently supported

• What telephony features are enabled on each channel (caller ID, autocallback, etc.)

• How distinctive ringing is handled on trunks and how it is generated for analog phones connected to the server

Executing /usr/sbin/ztcfg will tell you if the zaptel.conf file is valid for the hardware you've got installed. If ztcfg exits without giving you any output, your configuration is valid. If you'd like to see more verbose output, add a -v or -vv .

17.4.1.1 Using analog interfaces with Asterisk

The zaptel.conf file contains information used by Asterisk to determine what interface modules you're using with your Wildcard hardware. Each section in the zaptel.conf file describes a single interface's configuration. The following example zaptel.conf is for a system with two X100P cards and one TDM400P card with four FXS interfaces on it. It can support two POTS lines and four analog telephones:

 ; zaptel.conf example     loadzone = us     defaultzone=us     ; X100P cards     fxsks=1,2     ; TDM400P card     fxoks=3-6 

Depending upon the analog interface cards you've selected, you'll need configuration entries similar to those in Table 17-1.

Table 17-1. zaptel.conf analog interface configuration combinations

Card	Module configuration	zaptel.conf entry
1 X100P card	1 FXO interface	fxsks=1
2 X100P cards	1 FXO interface on each card	fxsks=1-2
1 S100U card	1 FXS interface	fxoks=1
2 S100U cards	1 FXS interface on each card	fxoks=1-2
1 TDM400P card	4 FXO interfaces	fxsks=1-4
1 TDM400P card	4 FXS interfaces	fxoks=1-4
1 TDM400P card	2 FXO interface, 2 FXS interfaces	fxsks=1-2
2 TDM400P cards	4 FXO interfaces on one card; 4 FXS interfaces on the other card	fxsks=1-4
2 TDM400P cards	2 FXO interfaces on the first card; 2 FXS interfaces on the first card; 4 FXO interfaces on the second card	fxsks=1,2,5,6,7,8

Besides FXO and FXS, Zaptel channels can be configured to use other types of signaling, including the T1 family, E&M, and in- band single frequency (SF). It's unlikely you'll need to use SF unless you're interfacing with some exotic legacy hardware.

zaptel.conf is the only Asterisk configuration located in /etc instead of / etc/asterisk .

While zaptel.conf establishes the choice of signaling for each piece of interface hardware, another file, zapata.conf , defines the telephony configuration of each channel. It establishes what telephony features the channel can use (caller ID, call-waiting, and so on). It describes how the channel behaves when used with distinctive ringing (see Project 12.5 for an example of a distinctive ring configuration) and whether the channel fits into a T1 interface configuration (T1s carry 24 channels).

In zapata.conf , the configuration parameters of each channel occur before the channel is designated with a number. (This is different from extensions.conf , where the extension number occurs at the top of its own section.) Consider the following zapata.conf file, which defines channels to correspond with the preceding zaptel.conf file:

 [channels]     language=en     context=default     signalling=fxs_ks     usecallerid=yes     hidecallerid=no     callwaiting=yes     callwaitingcallerid=yes     threewaycalling=yes     transfer=yes     callreturn=yes     channel => 1     channel => 2     signalling=fxo_ks     channel => 3     channel => 4     channel => 5     channel => 6 

For channels 3 through 6, all but the signalling setting are inherited from the previous definitions used first for channels 1 and 2. Table 17-2 lists commonly used zapata.conf settings and describes what they do.

Table 17-2. zapata.conf frequently used channel configuration options (default values are in boldface)

Setting	Description	Common values
accountcode	Free-form account code to be associated with this channel's calls in the CDR
adsi	Whether or not to use analog display services interface signals with this channel	yes; no
cadence	Establishes a dinstinctive ring pattern for this channel	length on, length silent, {length on},{length silent}
callerid	For trunk interfaces, overrides the caller ID number for this channel; to retain the supplied caller ID number, use asreceived	asreceived
callreturn	Whether or not to allow auto call return via *69	yes; no
callwaiting	For FXO channels, whether or not to allow call-waiting	yes; no
callwaitingcallerid	Whether to allow caller ID signals for call-waiting calls	yes; no
context	The context calls originated from this channel are directed to	default
dring n	Recognizes the ring pattern for incoming distinctive ring of type n
dring n context	Sets the context in which to place incoming calls that match ring pattern n
echocancel	Enables echo cancellation on this channel to reduce unwanted echo between IP destinations and legacy endpoints or the PSTN	yes; no
echocancelwhenbridged	Enables echo cancellation when the call path is all-TDM; recommend disabling this option on all channels	yes; no
echotraining	Enables automatic calibration of echo cancellation on Zaptel channels
flash	The length of time in ms to use for flash-hook signaling	750
group	The number of the outgoing rollover group this channel is a member of
hidecallerid	Whether or not to send caller ID signals on this channel	yes; no
jitterbuffers	Sets up jitter buffering for all calls on this channel, each buffer is 20 ms in length	4
language	The local language to be used with this channel
mailbox	The voice mailbox associated with this channel; produces stutter dial-tone when message waiting
musiconhold	Which class of music-on-hold will be played on this channel	default
overlapdial	Allows dialed DTMF digits to overlap	yes; no
rxwink	The length of time in ms to wait before receiving DID signals, if applicable
signalling	The signaling protocol to use with this channel	em; em_w; featd; featdmf; fxs_ls; fxs_gs; fxs_ks; fxo_ls; fxo_gs; fxo_ks; pri_cpe; pri_net
switchtype	The type of PRI switching to use on this channel, if applicable	national; dms100; 4ess; 5ess; euroisdn; ni1
threewaycalling	Whether to permit three-way calling	yes; no
TRansfer	Allow flash-hook call transfer during three-way calling	yes; no
usecallerid	Whether to use caller ID signals from this channel	yes; no
usedistinctiveringdetection	Whether or not to try to pick up distinctive rings on this channel	yes; no

17.4.1.2 Using T1 interfaces with Asterisk

Zaptel channels can also be used on T1 or E1 interfaces. Digium's T100P, T400P, T405P, T410P, TE110P, TE405P, and TE410P cards offer support for as many as four T1 or E1 circuits per card. These cards come equipped for different bus voltages, so double-check yours and indicate whether you need 3.3 volts or 5 volts when ordering. Cards with model numbers that begin with T work with T1s, while TE cards work with T1s or E1s.

In order to use any Zaptel interfaces with Asterisk, the right kernel modules must be loaded at boot time. For T1 and E1 interfaces, the module to load is wct1xxp for single-span T1/E1 cards and wc4xxp for quad-span T1/E1 cards. TE110P and TE4xxP cards use wcte11xp and wct4xxp , respectively.

Most T1 setups will use PRI signaling for trunking of PSTN dial-tone. But Zaptel T1 channels could be used for other purposes as well. Connected to a channel bank, a T1 channel can support up to 24 legacy phones. A T1 channel can also connect directly to another PBX that also supports T1/E1 connections.

The most common T1 channel, for a PRI trunk circuit, is straightforward to set up. First, a span definition in zaptel.conf . A span is a single leg of a point-to-point T1 connection link, defined at the data link layer. Just as DSU/CSUs deal with only a particular span of a T1 circuit, Zaptel deals with only a single span. Spans are defined in the following format:

 span=  span number  ,  timing  ,  LBO  ,  framing  ,  coding  

span number is a value you assign to this span to identify it. timing can be , 1 , or 2 . 1 and 2 means that Zaptel will use this span as a primary or secondary synchronization source, respectively. means Zaptel won't use it as a synchronization source. LBO , or line build out, is a value that tells Zaptel the distance to the T1/E1 smart jack and roughly what gain level ought to be used to accommodate for attenuation. Most setups will use a value of , which is good for up to 133 feet or roughly 40 meters . framing is an option that describes what kind of T1 framing method to usesuperframe, extended superframe, etc. Most T1 channels will use esf for extended superframe. Finally, coding is used to describe the data coding technique, which will always be b8zs for T1s and hdb3 for E1s.

B8ZS, also called clear channel, is the most popular coding scheme used on T1 circuits. B8ZS uses an electrical signaling trick called bipolar violations to mark time syncs into the stream of data. The receiving device recognizes these bipolar violations and uses it to keep synchronized with the sending device.

Following the span declaration, dchan and bchan options describe which channels are the bearer channels and which the signaling channel:

 ; zaptel.conf     span=1,1,0,esf,b8zs     bchan=1-23     dchan=24 

Corresponding to this configuration are entries in the zapata.conf file, that describe how the telephony features will work on the channels served by this T1:

 ; zapata.conf     switchtype=national     context=default     signalling=pri_cpe     group=1     callerid=1-800-534-1550     channel => 1-23 

zaptel.conf sets up a T1 span, configures the 24 DS0 channels on the T1, and sets the framing and coding. Then zapata.conf configures the telephony apparatus for those channels: national PRI signaling, a custom caller ID string, and the default dial-plan context. The channels are grouped into a single rollover group ( 1 ). Finally, on the last line, these settings are applied to Zaptel channels 1 through 23. Within the dial-plan, these channels will be referenced as Zap/1 , Zap/2 , and so on.

E1 circuits will have 31 bearer channels and typically use HDB3 coding instead of B8ZS. Keep that in mind if you're working outside North America.

17.4.2. SIP Channels

Asterisk implements SIP only partially. Though SIP itself describes a total PBX replacement approach using VoIP, Asterisk employs SIP mainly for connecting IP phones and for trunking to other systems that also use SIPlike Zaptel. Asterisk deals with its SIP subsystem in terms of channels: legs of a call. Two channels are needed to complete a call between two SIP phones. A call between an analog phone and a SIP phone also requires two channels: one Zaptel channel and one SIP channel.

Asterisk refers to devices that communicate with it by SIP peers . A SIP channel is established when a call is received from, or directed to, a SIP peer. SIP phones are peers, and so are remote SIP servers and SIP ATAs. Anything with a SIP UA and SA is considered a peer, and all SIP peers are configured in the same file: sip.conf .

The sip.conf file has been used throughout the book to set up various projects. In Project 3.1, a basic SIP peer was set up to allow an IP phone to interact with Asterisk's default voice menus and prompts. In Project 4.2, a group of SIP phones was configured to behave as a ring group.

There's almost nothing you can't do with a SIP channel that you can with a traditional TDM channel. Those few things you can't docreating your own ring cadences, for examplehave their own SIP equivalents anyway. Instead of cadences, most SIP phones just let you use WAV or GSM sound files with distinctive ringing.

17.4.2.1 SIP peer configuration

The /etc/asterisk/sip.conf file is organized into a general section that's followed by individual, peer-specific sections. The general section establishes parameters that apply globally to Asterisk's SIP module, while the peer-specific sections deal only with individual SIP endpoint configurations.

In the general section, you can establish what codecs are allowed and restricted for all SIP peers, the default context for incoming SIP calls, which type-of-service tags will be used with SIP media channels, and whether or not peers will be authenticated.Table 17-3 shows the settings that can be used in the general section of sip.conf :

Table 17-3. Asterisk general SIP configuration settings (default values are in boldface)

Setting	Description	Possible values
allow	Used with disallow ; describes which codecs can be used with SIP peers on this server.	mlaw; Alaw; gsm; g729; g723; g726; speex; all
autocreatepeer	Causes Asterisk to forgo all SIP authentication; probably useful only in a carrier network where there are substantial controls on network access.	yes; no
bindaddr	The IP address you want Asterisk's SIP SA to listen on, if other than one that's already bound.
canreinvite	Allows SIP peers to establish media channels directly to each other using the REINVITE method instead of using the server as a call path.	yes; no
context	The default context in which to place incoming SIP calls.
defaultexpirey	The interval, in seconds, between registration attempts when Asterisk is used as a SIP client.	120
disallow	Specifies codecs that won't be permitted with any SIP channels unless specifically allowed for at the channel level.
externip	The IP address to use in SIP headers if the Asterisk server is behind a static NAT firewall. The address you use would actually be bound on the firewall, not on the Asterisk server. See also nat .
fromdomain	Sets the domain name to use for outgoing SIP calls when Asterisk is used as a SIP client.
maxexpirey	The longest time, in seconds, a registered SIP client can remain so before reregistering.	3600
nat	Tells the Asterisk server whether or not it is behind a NAT firewall.
port	The port number to bind the SIP SA to, if other than the default.	5060
srvlookup	Allows Asterisk to call SIP users by their SIP URI via a DNS lookup. Only works when DNS provides an SRV record for the SIP domain in question.	yes; no
tos	Establishes the ToS bits sent with SIP channels' RTP media packets on this server. To specify DiffServ Expedited Forwarding, use 0xB8 .
useragent	Specifies a custom SIP user agent header. Normally, this header describes the type of IP phone being used to place the call.

Once you've established the Asterisk server's global SIP peer functionality in the general section, you can configure individual peersthe actual IP phones and trunk connections. A few settings, like allow and disallow , are applicable to the individual peers as they are to the general section, as shown in Table 17-4.

Table 17-4. Asterisk SIP peer settings (default values are bolded)

Setting	Description	Possible values
accountcode	Associates all calls to and from this peer with an account code in the CDR. Can be used for billing purposes.
Amaflags	Standardized billing flags for use in CDR records.	default ; omit; billing; documentation
callgroup	The number of the call group that this SIP channel is a member of; default is none .
Canreinvite	Allows the SIP peer to be used in calls with independent call paths via the SIP REINVITE method.	yes; no
Context	The dial-plan context for calls from this peer.	default
Defaultip	The IP address to contact a SIP peer for calls in the event it isn't registered. Requires that the host setting be dynamic .
dtmfmode	Instructs Asterisk on how to send and receive DTMF signals to/from this peer. The inband method only works well with G.711 codec.	inband; info ; rfc2833
Fromuser	Overrides the caller ID username for calls to SIP SAs only, not for calls that ultimately reach a legacy endpoint.
Fromdomain	Establishes the SIP domain to associate with calls placed from this peer.
Host	The method by which this peer can be reached. Peers using dynamic must be registered locally or you must provide a defaultip setting too. Otherwise, provide a static IP address for host.	dynamic or an IP address
incominglimit	Maximum number of simultaneous calls allowed from this peer.
insecure	Forgoes matching the IP address and port of this peer with its configuration in sip.conf . Probably only useful in the lab to toggle this check on and off. Peers that need a constantly changing IP address can use host=dynamic .	yes; no
language	A setting that allows IVR prompts to be localized when this peer is interacting with the voice menus on the server.
Outgoinglimit	The maximum number of simultaneous calls allowed to this peer.
Mailbox	The mailbox number to associate with this peer's message-waiting indicator, if applicable.
Md5secret	The MD5 hash of the peer's SIP username and password; optional measure designed to make password transmittal more secure.
Musiconhold	The default class of music-on-hold to use with calls to and from this peer.	default
Nat	Allows this peer to be behind a NAT firewall and still work with Asterisk.	yes; no
Pickupgroup	The number of the pickup group that this SIP channel is a member of. Default is none .
Port	The SIP port on this peer's UA.	5060
Restrictcid	Allows the caller ID signals for calls from this peer to be hidden from the receiver.	yes; no
Rtptimeout	The number of seconds before Asterisk will disconnect calls to/from this peer due to no RTP activity (unless the call is on hold).
rtpholdtimeout	The number of seconds before Asterisk will disconnect calls to/from this peer due to no RTP activity while on hold. Must be greater than rtptimeout .
Secret	The SIP password (shared secret) used for all INVITE methods to or from this peer.
Type	The kind of peer this is. Friends can call and receive. Peers can receive only. Users can call only.	friend ; peer; user
Username	The SIP username used to authenticate INVITEs to and from this peer.