O'Reilly logo

Asterisk: The Future of Telephony, 2nd Edition by Leif Madsen, Jared Smith, Jim Van Meggelen

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Chapter 4. Initial Configuration of Asterisk

I don’t always know what I’m talking about, but I know I’m right.

Muhammad Ali

Completing all the steps in Chapter 3 should have left you with a working Asterisk system. If it did not, please take the time to go back and review the steps, consult the wiki, engage the community, and get your system running.

Unfortunately, we cannot yet make any calls, because we have not yet created any channels. To get this plane to fly, we’re going to need some runways. While there are dozens of different channel types, and dozens of different ways to configure each type of channel, we just want to get some calls happening, so let’s try and keep things simple. We have decided to guide you through the configuration of four channels: a Foreign eXchange Office (FXO) channel, a Foreign eXchange Station (FXS) channel, a Session Initiation Protocol (SIP) channel, and an Inter-Asterisk eXchange (IAX) channel.[49] We selected these channel types because they are far and away the most popular channel types in use in small Asterisk systems, and one of the goals of this book is to keep things as simple as is reasonable. If we cover the basics of these channels, we will not have done an exhaustive survey of all channel types or topologies, but we will have created a base platform on which to develop your telecommunications system. Further scenarios and channel configuration details can be found in Appendix D.

Our first effort will be to explore the basic configuration of analog interfaces such as FXS and FXO ports with the use of a Digium TDM11B (which is an analog card with one FXS port and one FXO port).[50]

Next, we’ll tackle a few Voice over Internet Protocol (VoIP) interfaces: a local SIP and IAX2 channel connected to a softphone or hardphone, along with connecting two Asterisk boxes via these two popular protocols.

For SIP, we are going to cover Linksys, Polycom, Aastra, Grandstream, and Cisco sets. If we do not cover your phone model, we apologize, but what is important to realize is that while most of these devices have many different parameters that you can define, generally only a few parameters need to be defined in order to get the device to work. That will be our goal, because we figure it’s a lot less frustrating to tweak a functioning device than to get it perfectly set up on the first try. We won’t discuss all the features you may want your channel to have (such as caller ID or advanced codec and security settings), but you will be able to make and receive calls with your phone, which should put a smile on your face—a good state to be in as we dig deeper into things.

Once you’ve worked through this chapter, you will have a basic system consisting of many useful interfaces, which will provide the foundation we need to explore the extensions.conf file (discussed in detail in Chapter 5), where the dialplan is stored (technically, it contains the instructions Asterisk needs to build the dialplan). If you do not have access to the analog hardware, some of the examples will not be available to you, but you will still have configured a system suitable for a pure-VoIP environment.

What Do I Really Need?

The asterisk character (*) is used as a wildcard in many different applications. It is a good name for this PBX for many reasons, one of which is the enormous number of interface types to which Asterisk can connect. These include:

  • Analog interfaces, such as your telephone line and analog telephones

  • Digital circuits, such as T1 and E1 lines

  • VoIP protocols such as SIP and IAX[51]

Asterisk doesn’t need any specialized hardware—not even a sound card—even though it is common to expect a telephone system to physically connect to a voice network. There are many types of channel cards that allow you to connect your Asterisk to things like analog phones or PSTN circuits, but they are not essential to the functioning of Asterisk. On the user (or station) side of the system, you can choose from all kinds of softphones that are available for Windows, Linux, and other operating systems—or use almost any physical IP phone. That handles the telephone side of the system. On the carrier side, if you don’t connect directly to a circuit from your central office, you can still route your calls over the Internet using a VoIP service provider.

Working with Interface Configuration Files

In this chapter, we’re going to build an Asterisk configuration on the platform we have just installed. For the first few sections on FXO and FXS channels, we’ll assume that you have a Digium TDM11B kit (which comes with one FXO and one FXS interface). This will allow you to connect to an analog circuit (FXO) and to an analog telephone (FXS). Note that this hardware interface isn’t necessary; if you want to build an IP-only configuration, you can skip to the section on configuring SIP after reading the section on creating configuration files..

The configuration we do in this chapter won’t be particularly useful on its own, but it will be a kernel to build on. We’re going to touch on the following files:

zaptel.conf

Here, we’ll do low-level configuration for the hardware interface. We’ll set up one FXO channel and one FXS channel. This configures the driver for the Linux kernel.

zapata.conf

In this file, we’ll configure Asterisk’s interface to the hardware. This file contains a slightly higher-level configuration of the hardware in the Asterisk user-level process.

extensions.conf

The dialplans we create will be extremely primitive, but they will prove that the system is working.

sip.conf

This is where we’ll configure the SIP protocol.

iax.conf

This is where we’ll configure incoming and outgoing IAX channels.

In the following sections, you will be editing several configuration files. You’ll have to reload these files for your changes to take effect. After you edit the zaptel.conf file, you will need to reload the configuration for the hardware with /sbin/ztcfg -vv (you may omit the -vv if you don’t need verbose output). Changes made in zapata.conf will require a module reload from the Asterisk console; however, changing signaling methods requires a restart. You will need to perform an iax2 reload and a sip reload after editing the iax.conf and sip.conf files, respectively.

In order to test the new devices we have defined, we must have a dialplan through which we can make connections. Even though we have not discussed the Asterisk dialplan (that’s coming up in the next chapter), we want you to create a basic extensions.conf file so that we can test our work in this chapter.

Make a backup copy of the sample extensions.conf (try the bash command mv extensions.conf extensions.conf.sample), and then create a blank extensions.conf file (using the bash command touch extensions.conf), and insert the following lines:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[internal]

[phones]
include => internal

Note

In the [general] section, we have set autofallthrough=yes, which tells Asterisk to continue when an extension runs out of things to do. If you set this to no, then Asterisk will sit and wait for input after all priorities have executed. This is most prevalent if the Background() application is the last application executed in an extension. If set to yes (which is now the default in 1.4), Asterisk will drop the call after Background() finishes executing (at the end of the prompt(s) supplied to it). In order to force Asterisk to wait for input after the Background() application finishes playing the voice prompts supplied to it, we use the WaitExten() application.

Do not be afraid if what we’ve just written doesn’t make a whole lot of sense, as we haven’t explored the dialplan, applications, priorities, or extensions yet (that is coming up in the next chapter). So for now, just set autofallthrough=yes. It is safest to use the autofallthrough=yes command as we don’t want Asterisk hanging around waiting for input unless we explicitly tell it to do so.

There is nothing else for now, but we’ll be using this file as we go through this chapter to build a test dialplan so we can ensure that all of our devices are working. Also, be sure to run the dialplan reload command from the Asterisk CLI to update to the latest changes. Verify your changes by running the CLI command dialplan show:

*CLI> dialplan show
[ Context 'phones' created by 'pbx_config' ]
  Include =>        'internal'                                    [pbx_config]

[ Context 'internal' created by 'pbx_config' ]

[ Context 'incoming_calls' created by 'pbx_config' ]

[ Context 'default' created by 'pbx_config' ]

[ Context 'parkedcalls' created by 'res_features' ]
  '700' =>          1. Park((null))                               [res_features]

-= 1 extension (1 priority) in 5 contexts. =-

Note

You will see the parkedcalls context because it is an internal context to Asterisk, specified in the features.conf file.

Setting Up the Dialplan for Some Test Calls

Now let’s expand upon the test dialplan we started in the previous section, allowing us to dial back into the softphone after we have configured it and to use a dialplan application called Echo() that will allow us to test bidirectional audio. We’ll learn more about dialplans in Chapter 5, so for now, just add the italicized bits to your existing extensions.conf file. We’ll be making use of this dialplan throughout the chapter, and expanding on it in certain sections. Once you’ve entered the text into extensions.conf, reload the dialplan by running dialplan reload from the Asterisk console:

[globals]

[general]

[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()

[incoming_calls]

[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Answer()
exten => 500,n,Echo()
exten => 500,n,Hangup()

[phones]
include => internal

FXO and FXS Channels

The difference between an FXO channel and an FXS channel is simply which end of the connection provides the dial tone. An FXO port does not generate a dial tone; it accepts one. A common example is the dial tone provided by your phone company. An FXS port provides both the dial tone and ringing voltage to alert the station user of an inbound call. Both interfaces provide bidirectional communication (i.e., communication that is transmitted and received in both directions simultaneously).[52]

If your Asterisk server has a compatible FXO port, you can plug a telephone line from your telephone company (or “telco”) into this port. Asterisk can then use the telco line to place and receive telephone calls. By the same token, if your Asterisk server has a compatible FXS port, you may plug an analog telephone into your Asterisk server, so that Asterisk may call the phone and you may place calls.

Ports are defined in the configuration by the signaling they use, as opposed to the physical type of port they are. For instance, a physical FXO port will be defined in the configuration with FXS signaling, and an FXS port will be defined with FXO signaling. This can be confusing until you understand the reasons for it. FX_ cards are named not according to what they are, but rather according to what is connected to them. An FXS card, therefore, is a card that connects to a station. Since that is so, you can see that in order to do its job, an FXS card must behave like a central office and use FXO signaling. Similarly, an FXO card connects to a central office (CO), which means it will need to behave like a station and use FXS signaling. The modem in your computer is a classic example of an FXO device.

Warning

The older Digium X100P card used a Motorola chipset, and the X101P (which Digium sold before completely switching to the TDM400P) is based on the Ambient/Intel MD3200 chipset. These cards are modems with drivers adapted to utilize the card as a single FXO device (the telephone interface cannot be used as an FXS port). Support for the X101P card has been dropped in favor of the TDM series of cards.

These cards (or their clones) SHOULD NOT be used in production environments. They are $10 on eBay for a reason.

The X100P/X101P cards are poor cards for production use due to their tendency to introduce echo into your telephone calls, and their lack of remote disconnect supervision. Do yourself a favor and don’t waste your time with this hardware. You will find that if you ask the community for support of these cards, many responses will be hostile. You have been warned.

Determining the FXO and FXS Ports on Your TDM400P

Figure 4-1 contains a picture of a TDM400P with an FXS module and an FXO module. You can’t see the colors, but module 1 is a green FXS module, and module 2 is an orange-red FXO module. In the bottom-right corner of the picture is the Molex connector, where power is supplied from the computer’s power supply.

A TDM400P with an FXS module (1 across) and an FXO module (2 across)

Figure 4-1. A TDM400P with an FXS module (1 across) and an FXO module (2 across)

Warning

Plugging an FXS port (the green module) into the PSTN may destroy the module and the card due to voltage being introduced into a system that wants to produce voltage, not receive it!

Tip

Be sure to connect your computer’s power supply to the Molex connector on the TDM400P if you have FXS modules, as it is used to supply the voltage needed to drive the ring generator on the FXS ports. The Molex connector is not required if you have only FXO modules.

Configuring an FXO Channel for a PSTN Connection

We’ll start by configuring an FXO channel. First we’ll configure the Zaptel hardware, and then the Zapata hardware. We’ll set up a very basic dialplan, and we’ll show you how to test the channel.

Zaptel Hardware Configuration

The zaptel.conf file located in /etc/ is used to configure your hardware. The following minimal configuration defines an FXO port with FXS signaling:

fxsks=2
loadzone=us
defaultzone=us

In the first line, in addition to indicating whether we are using FXO or FXS signaling, we specify one of the following protocols for channel 2:

  • Loop start (ls)

  • Ground start (gs)

  • Kewlstart (ks)

The difference between loop start and ground start has to do with how the equipment requests a dial tone: a ground-start circuit signals the far end that it wants a dial tone by momentarily grounding one of the leads; a loop-start circuit uses a short to request a dial tone. Though not common for new installations, analog ground start lines still exist in many areas of the country.[53] Ground start is really a rather strange thing, because it doesn’t exist in its analog form in Asterisk, so technically, there is no ground signal happening, but is rather a signaling bit that is intended for analog circuitry that historically would have been at the end of the T1. If this does not make much sense, don’t sweat it; chances are you won’t have to worry about ground-start signaling. All home lines (and analog telephones/modems/faxes) in North America use loop-start signaling. Kewlstart is in fact the same as loop start, except that it has greater intelligence and is thus better able to detect far-end disconnects.[54] Kewlstart is the preferred signaling protocol for analog circuits in Asterisk.

To configure a signaling method other than kewlstart, replace the ks in fxsks with either ls or gs (for loop start or ground start, respectively).

loadzone configures the set of indications (as configured in zonedata.c) to use for the channel. The zonedata.c file contains information about all of the various sounds that a phone system makes in a particular country: dial tone, ringing cycles, busy tone, and so on. When you apply a loaded tone zone to a Zap channel, that channel will mimic the indications for the specified country. Different indication sets can be configured for different channels. The defaultzone is used if no zone is specified for a channel.

After configuring zaptel.conf, you can load the drivers for the card. modprobe is used to load modules for use by the Linux kernel. For example, to load the wctdm driver, you would run:

# modprobe wctdm

If the drivers load without any output, they have loaded successfully.[55] You can verify that the hardware and ports were loaded and configured correctly with the use of the ztcfg program:

# /sbin/ztcfg -vv

The channels that are configured and the signaling method being used will be displayed. For example, a TDM400P with one FXO module has the following output:

Zaptel Configuration
======================
Channel map:
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
1 channels configured.

If you receive the following error, you have configured the channel for the wrong signaling method (or there is no hardware present at that address):

ZT_CHANCONFIG failed on channel 2: Invalid argument (22)
Did you forget that FXS interfaces are configured with FXO signaling
and that FXO interfaces use FXS signaling?

To unload drivers from memory, use the rmmod (remove module) command, like so:

# rmmod wctdm

The zttool program is a diagnostic tool used to determine the state of your hardware. After running it, you will be presented with a menu of all installed hardware. You can then select the hardware and view the current state. A state of “OK” means the hardware is successfully loaded:

Alarms          Span
OK              Wildcard TDM400P REV E/F Board 1

Zapata Hardware Configuration

Asterisk uses the zapata.conf file to determine the settings and configuration for telephony hardware installed in the system. The zapata.conf file also controls the various features and functionality associated with the hardware channels, such as Caller ID, call waiting, echo cancellation, and a myriad of other options.

When you configure zaptel.conf and load the modules, Asterisk is not aware of anything you’ve configured. The hardware doesn’t have to be used by Asterisk; it could very well be used by another piece of software that interfaces with the Zaptel modules. You tell Asterisk about the hardware and control the associated features via zapata.conf:

[trunkgroups]
; define any trunk groups

[channels]
; hardware channels 
 

; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes

; define channels
context=incoming        ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks       ; Use FXS signaling for an FXO channel
channel => 2            ; PSTN attached to port 2

The [trunkgroups] section is used for connections where multiple physical lines are used as a single logical connection to the telephone network, and won’t be discussed further in this book. If you require this type of functionality, see the zapata.conf.sample file and your favorite search engine for more information.

The [channels] section determines the signaling method for hardware channels and their options. Once an option is defined, it is inherited down through the rest of the file. A channel is defined using channel =>, and each channel definition inherits all of the options defined above that line. If you wish to configure different options for different channels, remember that the options should be configured before the channel => definition.

We’ve enabled Caller ID with usecallerid=yes and specified that it will not be hidden for outgoing calls with hidecallerid=no. Call waiting is deactivated on an FXO line with callwaiting=no. Enabling three-way calling with threewaycalling=yes allows an active call to be placed on hold with a hook switch flash (discussed in Chapter 7) to suspend the current call. You may then dial a third party and join them to the conversation with another hook switch. The default is to not enable three-way calling.

Allowing call transfer with a hook switch is accomplished by configuring transfer=yes; it requires that three-way calling be enabled. The Asterisk echo canceller is used to remove the echo that can be created on analog lines. You can enable the echo canceller with echocancel=yes. The echo canceller in Asterisk requires some time to learn the echo, but you can speed this up by enabling echo training (echotraining=yes). This tells Asterisk to send a tone down the line at the start of a call to measure the echo, and therefore learn it more quickly.

When a call comes in on an FXO interface, you will want to perform some action. The action to be performed is configured inside a block of instructions called a context. Incoming calls on the FXO interface are directed to the incoming context with context=incoming. The instructions to perform inside the context are defined within extensions.conf.

Finally, since an FXO channel uses FXS signaling, we define it as such with signalling=fxs_ks.

Dialplan Configuration

The following minimal dialplan makes use of the Echo() application to verify that bidirectional communications for the channel are working:

[incoming]
; incoming calls from the FXO port are directed to this context 
;from zapata.conf
exten => s,1,Answer()
exten => s,n,Echo()

Whatever you say, the Echo() application will relay back to you.

Dialing In

Now that the FXO channel is configured, let’s test it. Run the zttool application and connect your PSTN line to the FXO port on your TDM400P. Once you have a phone line connected to your FXO port, you can watch the card come out of a RED alarm.

Now dial the PSTN number from another external phone (such as a cell phone). Asterisk will answer the call and execute the Echo() application. If you can hear your voice being reflected back, you have successfully installed and configured your FXO channel.

Configuring an FXS Channel for an Analog Telephone

The configuration of an FXS channel is similar to that of an FXO channel. Let’s take a look.

Zaptel Hardware Configuration

The following is a minimal configuration for an FXS channel on a TDM400P. The configuration is identical to the FXO channel configuration above, with the addition of fxoks=1.

Recall from our earlier discussion that the opposite type of signaling is used for FXO and FXS channels, so we will be configuring FXO signaling for our FXS channel. In the example below we are configuring channel 1 to use FXO signaling, with the kewlstart signaling protocol:

fxoks=1
fxsks=2
loadzone=us
defaultzone=us

After loading the drivers for your hardware, you can verify their state with the use of /sbin/ztcfg -vv:

Zaptel Configuration
======================

Channel map:

Channel 01: FXO Kewlstart (Default) (Slaves: 01)
Channel 02: FXS Kewlstart (Default) (Slaves: 02)

2 channels configured.

Zapata Hardware Configuration

The following configuration is identical to that for the FXO channel, with the addition of a section for our FXS port and, of the line immediate=no. The context for our FXS port is phones, the signaling is fxoks (kewlstart), and the channel number is set to 1.

FXS channels can be configured to perform one of two different actions when a phone is taken off the hook. The most common (and often expected) option is for Asterisk to produce a dial tone and wait for input from the user. This action is configured with immediate=no. The alternative action is for Asterisk to automatically perform a set of instructions configured in the dialplan instead of producing a dial tone, which you indicate by configuring immediate=yes.[56] The instructions to be performed are found in the context configured for the channel and will match the s extension (both of these topics will be discussed further in the following chapter).

Here’s our new zapata.conf:

[trunkgroups]
; define any trunk groups

[channels]
; hardware channels
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
immediate=no

; define channels
context=phones       ; Uses the [internal] context in extensions.conf
signalling=fxo_ks       ; Uses FXO signalling for an FXS channel 
 

channel => 1           ; Telephone attached to port 1

context=incoming       ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks       ; Use FXS signalling for an FXO channel
channel => 2           ; PSTN attached to port 2

Dialplan Configuration

We will make use of our minimal dialplan we configured earlier in the chapter to test our FXS port with the use of the Echo() application. The relevant section, which should already exist in your dialplan, looks like this:

[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()

[phones]
include => internal

Whatever you say, the Echo() application will relay back to you.

Configuring SIP Telephones

The Session Initiation Protocol (SIP),[57] commonly used in VoIP phones (either hard phones, or softphones), takes care of the setup and teardown of calls, along with any changes during a call such as call transfers. The purpose of SIP is to help two endpoints talk to each other (if possible, directly to each other). The SIP protocol is simply a signaling protocol, which means that its purpose is only to get the two endpoints talking to each other, and not to deal with the media of the call (your voice). Rather, your voice is carried using another protocol called the Real-Time Transport Protocol (RTP; RFC 3550) to transfer media directly between the two endpoints.

Note

We use the term media to refer to the data transferred between endpoints and used to reconstruct your voice at the other end. It may also refer to music or prompts from the PBX.

In the world of SIP, we call our endpoints user agents, of which there are two types: client and server. The client is the endpoint that generates the request, and the server processes the request and generates a response. When an endpoint wishes to place a call to another endpoint (such as our softphone calling another softphone), we generate our request and send this to a SIP proxy.[58] A proxy server will take the request, determine where the request is destined for, and forward it on. Once the two user agents have negotiated a successful call setup, the media is transported via the RTP protocol and sent directly between the two user agents. SIP proxies do not handle media; they simply deal with the SIP packets.

Asterisk, on the other hand, is called a Back-To-Back User Agent (B2BUA). This means that Asterisk acts like a user agent in either the server (receiving) or client (sending) role. So when our softphone dials an extension number, the call is set up between the softphone and Asterisk directly. If the logic we’ve built into Asterisk determines that you mean to call another user agent, then Asterisk acts as a user agent client and sets up another connection (known as a channel) to the other phone. The media between the two phones then flows directly through Asterisk.[59] From the viewpoint of the phones, they are talking with Asterisk directly.

Basic SIP Telephone Configuration in Asterisk

Configuring a SIP phone to work with Asterisk does not require much. However, because there are so many options possible in both Asterisk and the configuration of the particular telephone set or softphone, things can get confusing. Add to this the fact that similar things can have different names, and you have a recipe for frustration. What we are going to do, therefore, is give you the bare-bones basics. If you follow our advice, you should be able to get the sets we cover working (and be well on your way to getting a phone that we have not covered to work as well). We are not saying that this is the best way, or even the right way, but it is the simplest way, and from a working foundation, it is much easier to take a basic configuration and tweak things until you get the solution you need.

Note

Just as we did with the extensions.conf file; run the following commands in your bash shell:

            # mv sip.conf sip.conf.sample# touch sip.conf

Defining the SIP device in Asterisk

If you put the following in a sip.conf file, you will be able to register a phone to the system.

[general]

[1000]
type=friend
context=phones
host=dynamic

Not pretty, not secure, not flexible, not fully-featured, but this will work.

Even though we have named this SIP device 1000, and we are probably going to assign it that extension number, you should note that we could have named it whatever we wanted. Names such as mysipset, john, 0004f201ab0c are all valid, popular, and may suit your needs better.[60] What we are doing is assigning a unique identifier to a device, which will form part of the credentials when a call is placed using the SIP channel.

Since we want to be able to both send calls to the softphone and allow the client to place calls, we have defined the type as friend. The other two types are user and peer. From the viewpoint of Asterisk, a user is configured to enter the dialplan, and a peer is created for calls leaving the dialplan (via the Dial() application). A friend is simply a shortcut that defines both a user and a peer. If in doubt, define the type as friend.

The host option is used to define where the client exists on the network when Asterisk needs to send a call to it. This can either be defined statically by defining something like host=192.168.1.100, or if the client has a dynamic IP address, then we set host=dynamic. When the host option is set as dynamic, and the client is configured to register, Asterisk will receive a REGISTER packet from the endpoint (i.e., telephone set or softphone), telling Asterisk which IP address the SIP peer is using.

If you do not trust your network, you should probably also force the use of a password by adding the following to the device definition. This is one of those things that is not technically necessary, but is probably a good idea:

secret=guessthis

Configuring the Device Itself

In the configuration menus of the phone itself (which could be via a web GUI, through menus on the phone itself, or possibly using configuration files that are stored on a server), the unique identifier (which in this case is 1000) again forms part of the credentials for the authentication process. Naturally, for a connection to be successful, this has to match in both Asterisk and in the set itself. The fun begins when you realize that there is no set rule as to what this identifier is formally called. We have elected simply to call it the Unique Identifier.

Note

In the SIP RFC (http://www.faqs.org/rfcs/rfc3261.html), section 19.1 calls this user token, “the identifier of a particular resource at the host being addressed,” verbiage consistent with our usage of [1000] as the set identifier in the sip.conf file of Asterisk.

Instead, you will want to look for fields that are labeled user name, auth name, authentication name, and so on. The thing to remember is that since you know that the Asterisk end of the equation is configured simply and correctly, you can experiment with the phone setting until you find a combination that works. This is much better than the usual suffering that new users go through, as they change settings in both places and have no luck getting a phone to register.

Note

We’re gonna say it again: configure sip.conf in the simplest manner possible, and then don’t change your Asterisk configuration. Trust us; what we have written here will work. Get your set working (i.e., where you can make and receive calls), and you will be in a far better position to begin experimenting with different settings. We have seen too much suffering (including our own), and we want it to end.

Note

If you are running Asterisk and a softphone on the same system (i.e., running an X-Lite softphone and Asterisk on a laptop or desktop), then you will need to modify the SIP port that client listens on. It will need to be changed from 5060 to 5061 (or some other unused port) so that Asterisk and the softphone do not interfere with each other.

Essential Server Components

Before we get into how to define these files, there are a few things that need to be configured on your server. Running the right services on your network will ensure your Polycom sets can autoconfigure from the moment you plug them in. There’s a little work involved here, but we promise that the payoff is worth it. Once you’ve done this a few times, it only really takes a few minutes on each new system, and going forward, it’ll save you a lot of mucking about with web interfaces. When you take your new Polycom phone out of the box, plug it into your network, watch it autoconfigure itself, and then successfully register with your Asterisk machine, you will know the sort of joy that only geeks can experience.[61]

It’s not really that complicated. Where we think people get confused is in making sense of the various ways this can be achieved, because there are a lot of choices.

DHCP server

Typically, a DHCP server is used to configure basic IP parameters for a device (IP address, default gateway, and DNS), but the DHCP protocol can actually pass many other parameters. In our case, we want it to pass some information to the sets that will tell them where to download their config files from. Here is a sample config from a Linux DHCP server that will do what is required:

ddns-update-style interim;
ignore client-updates;

subnet 192.168.1.0 netmask 255.255.255.0 {
 option routers 192.168.1.1;
 option subnet-mask 255.255.255.0;
 option domain-name-servers 192.168.1.1;
 option ntp-servers pool.ntp.org;
 option time-offset -18000;

range dynamic-bootp 192.168.1.128 192.168.1.254;
default-lease-time 21600;
max-lease-time 43200;
}

Keep in mind that this assumes that the only things on this network are devices that belong to the phone system (this setup will hand out an IP address to any device that requests it). If you have a more complex environment, you will need to configure the DHCP daemon to handle the various devices it is serving. For example, you might want to devise a scope that restricts IP addresses in your voice LAN to Polycom phones. Since all Polycom IP desk phones have 00:04:f2 as their OUI (Organizationally Unique Identifier), you might choose to restrict scope based on that.

Note

In a Microsoft DHCP environment, the tftp-server-name is referred to as Boot server host name. It is defined under option 66.

The DHCP protocol is far more flexible than is often realized, because in most environments it is not used for complex provisioning tasks. With a little care and attention, you can devise a DHCP environment that serves both your voice and data devices and greatly simplifies administrative workload when adding new devices.

FTP server

FTP is currently our favorite[62]way to configure Polycom sets. We would recommend it over TFTP for any set that allows for both. To install it on your CentOS system, the following command will install VSFTPD, the Very Secure FTP Daemon:

# yum -y install vsftpd

Then, in order to lock things down, we need to prevent anonymous logins with a simple change to the vsftpd config file, /etc/vsftpd/vsftpd.conf:

# anonymous_enable=NO

Restart the server with service vsftpd restart. To ensure that the daemon runs after every reboot, run chkconfig vsftpd on.

Now, we have to create a user account and group for the sets to use. In this case, we will create an account for the Polycom sets:

# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp

Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can be changed, but will then require manual configuration from each set in order to advise them of their nonstandard credentials.[63]

For added security, let’s make sure the FTP server keeps that account in a chroot jail:

# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list

That pretty much does it as far as preparing the operating system to provide the required services to the phones.

In the next few sections we have provided instructions for various popular SIP telephones. Choose the section that applies best to the phone that you are planning to use (whether a hard- or soft-phone). You will note that we have given all of these phones the exact same unique identifier. If you plan on installing more than one of them, you will need to ensure that they have unique names, and be sure to update your sip.conf file to include those device definitions.

CounterPath’s X-Lite Softphone

CounterPath’s X-Lite softphone has become very popular with the Asterisk community. It is simple, functional, easy on the eyes, and—most importantly—free.

In this section we will be configuring the X-Lite softphone to connect to Asterisk. The IP address of the phone is 192.168.1.250, and Asterisk is located at 192.168.1.100. The X-Lite is available for Microsoft Windows, Mac, and Linux. You can obtain a copy of X-Lite from http://www.counterpath.com/index.php?menu=download.

Now let’s configure our softphone for connecting to our Asterisk box. To configure X-Lite, click on the Settings button, as circled in Figure 4-2.

X-Lite configuration

Figure 4-2. X-Lite configuration

Select System SettingsSIP Proxy[Default], which will display the default configuration for the softphone. Configure the screen as shown in Figure 4-3.

X-Lite user configuration

Figure 4-3. X-Lite user configuration

If you have not already started Asterisk, then start it now (see Chapter 3 for help installing and starting Asterisk). If Asterisk is running in the background, you can reconnect to the CLI by running the following command:

# asterisk -rvvv

You will then be given the Asterisk CLI like so:

*CLI>

If Asterisk was already running before changing the sip.conf as instructed in this chapter, then reload the dialplan and SIP channel with the following two commands:

*CLI> dialplan reload

*CLI>sip reload

In your X-Lite softphone client, close the Settings windows by clicking the BACK button until the windows are all closed. You should see X-Lite try to register to Asterisk, and if successful, you will see the following at the Asterisk CLI:

-- Registered SIP '1000' at 192.168.1.250 port 5061 expires 3600

You can verify the registration status at any time like so:

*CLI> sip show peers

Name/username              Host            Dyn Nat ACL Port     Status    
1000/1000                  192.168.1.250    D   N      5061    OK (63 ms)
1 sip peers [1 online , 0 offline]

More detailed stats of the peer can be shown as follows with sip show peer 1000:

*CLI> sip show peer 1000


  * Name       : 1000
  Secret       : <Not set>
  MD5Secret    : <Not set>
  Context      : phones
  Subscr.Cont. : <Not set>
  Language     : 
  AMA flags    : Unknown
  Transfer mode: open
  CallingPres  : Presentation Allowed, Not Screened
  Callgroup    : 
  Pickupgroup  : 
  Mailbox      : 
  VM Extension : asterisk
  LastMsgsSent : 32767/65535
  Call limit   : 0
  Dynamic      : Yes
  Callerid     : "" <>
  MaxCallBR    : 384 kbps
  Expire       : 1032
  Insecure     : no
  Nat          : RFC3581
  ACL          : No
  T38 pt UDPTL : No
  CanReinvite  : Yes
  PromiscRedir : No
  User=Phone   : No
  Video Support: No
  Trust RPID   : No
  Send RPID    : No
  Subscriptions: Yes
  Overlap dial : Yes
  DTMFmode     : rfc2833
  LastMsg      : 0
  ToHost       : 
  Addr->IP     : 192.168.1.250 Port 5061
  Defaddr->IP  : 0.0.0.0 Port 5060
  Def. Username: 1000
  SIP Options  : (none)
  Codecs       : 0x8000e (gsm|ulaw|alaw|h263)
  Codec Order  : (none)
  Auto-Framing:  No 
  Status       : Unmonitored
  Useragent    : X-Lite release 1105d
  Reg. Contact : sip:1000@192.168.1.250:5061

Polycom’s IP 430

A lot of folks say configuring Polycom phones is difficult. From what we can tell, they base this on one of two reasons: 1) The Polycom web-based interface is horrible, or 2) the automatic provisioning process is painful and confusing.

With respect to item 1, we agree. The web interface on the Polycom phones has got to be one of the most annoying web interfaces ever developed for an IP telephone. We don’t use it, and we don’t recommend it.[64]

So that leaves us with some sort of server-based configuration. Fortunately, in this regard, the Polycom IP phones are superb—so much so that we can pretty much forgive the web interface. Set configurations are stored in files on a server, and each set navigates to the server, downloads the configuration files that are relevant to it, and applies them to itself.

DHCP server

If you cannot control your DHCP server, you may have to manually specify the FTP server information on the phone. This is done by rebooting the set, pressing the setup button before the set begins the load process, and specifying the address of the FTP server in the small boot menu that these phones offer.

Protocol to use for downloading

The Polycom phones are able to download their configuration by one of three protocols: TFTP, HTTP, and FTP.

Right off the bat we are going to tell you to avoid TFTP. It is not secure, and the set cannot use date information to determine which versions of various files are the most current. It works, but there are better ways, and we are not going to discuss it further.

Polycom phones can pull their config data using HTTP as well, but it has not proven to be popular, and so we are going to move on.

FTP is currently the preferred method of allowing Polycom phones to obtain their configuration. It works well, is fairly easy to configure, and is well supported by the community.

FTP

FTP is currently our favorite way to configure Polycom sets. To install it on your CentOS system, the following command will install VSFTPD, the Very Secure FTP Daemon:

# yum -y install vsftpd

Then, in order to lock things down, we need to prevent anonymous logins, with a simple change to the vsftpd config file, /etc/vsftpd/vsftpd.conf:

# anonymous_enable=NO

Restart the server with service vsftpd restart. To ensure that the daemon runs after every reboot, run chkconfig vsftpd on.

Now, we have to create a user account and group for the Polycom sets to use:

# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp

Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can be changed, but will then require manual configuration from each set in order to advise them of their nonstandard credentials.[65]

For added security, let’s make sure the FTP server keeps that account in a chroot jail:

# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list

That pretty much does it as far as preparing the operating system to provide the required services to the phones.

The Polycom configuration files

While there seem to be a lot of different files that are needed to make a Polycom set work, they are each fairly easy to understand.

The bootROM

This can best be described as the BIOS and operating system of the phone. Perhaps there is a more technical explanation, but why make things confusing? The bootROM should not need to be updated regularly, but it is good to keep an eye on the current releases to see if a newer bootROM has features that will be of benefit in your environment. This file will be named bootrom.ld.

The application image

Since Polycom sets are capable of supporting other VoIP protocols (MGCP is supported, for example), the protocol that this set will employ forms part of the application image that the phone will download and run. If the image on the set is already correct, this file is not actually needed on the FTP server; however, it is common to have this file available to ensure that the most recent version of the protocol is available for the sets to download. You will sometimes receive phones that are not running the latest version, so having the most current image will ensure that all sets are up-to-date.

The sip.cfg file

There is normally only one version of this file on a system, but it can be named anything you want, and there can be as many different versions of this file as are needed. For example, if you had an office where there were two different languages in use, some users might prefer French on their set, and others English. In that case, you’d create a french.sip.conf file and an english.sip.conf file to handle each case. Name this file as you see fit, but pick a name that makes sense so that future administrators have a chance to make sense of your design choices.

The master config file for each phone

This file is very simple and small. It is named to match the MAC address of each phone (so each set will need its own copy of this file) and tells the set what other files it needs to download in order to configure itself. This is the first config file each set will read. In this file will be a reference to the application image this set will use (currently named sip.ld), as well as the names of the XML files that have the parameters for this phone (the .cfg files). A master config file for a set might look something like this:

'<?xml version="1.0" standalone="yes"?>'
'<!-- Default Master SIP Configuration File-->'
'<!-- Edit and rename this file to <Ethernet-address>.cfg for each phone.-->'
'<!-- $Revision: 1.14 $  $Date: 2005/07/27 18:43:30 $ -->'
'<APPLICATION APP_FILE_PATH="sip.ld" 
  CONFIG_FILES="phone1.cfg, sip.cfg" 
  MISC_FILES="" 
  LOG_FILE_DIRECTORY="" 
  OVERRIDES_DIRECTORY="" 
  CONTACTS_DIRECTORY=""
/>'

Note the name of the application file that we want this set to use, and the config files that it will be trying to find and apply.

The set-specific config file

We recommend giving the phone1.cfg files names that make sense. For example, SET<xxx>.cfg (such as SET201.cfg) to match the extension number of the phone, or FLOOR4CUBE23.cfg, or maybe BOB_SMITHS_IP430_SET.cfg, or whatever seems best to you. What’s the best way to name them? We’re going to answer that question by asking a question. Let’s say you have 100 of these phones. When you list the contents of the /home/PlcmSpIp folder, how do you want the 100 config files for the sets to appear?

Gotchas

Settings that are configured directly on the telephone will be stored on the filesystem of the set, and may take precedence over parameters passed in config files. If you are having any problems applying changes to a set, try reformatting the phone. This will force the set to accept the parameters contained in the config files.

Cisco 7960 Telephone

The venerable old C7960 is now a part of VoIP history. One of the first SIP telephones that could actually be taken seriously, the only real complaint one can have about this phone is the price: they are the Cadillac of SIP phones (meaning that they have all the bells and whistles but are tough to justify at the price, and are a little out of date sometimes).

If you can get one of these, you are getting an excellent SIP telephone. If you buy one new, be prepared to pay.

One of the ways this phone is out of date is the lack of remote provisioning from anything other than TFTP. TFTP has lost favor with networking professionals due to the lack of authentication and encryption, but since it is the only method of remotely provisioning the phone, we are going to have to use the tftp-server daemon. We can install tftp-server with the following command:

# yum install -y tftp-server

Once installed, we need to enable the server by modifying the /etc/xinetd.d/tftp file. To enable the TFTP server, change the disable=yes line to disable=no.

service tftp
{
    socket_type             = dgram
    protocol                = udp
    wait                    = yes
    user                    = root
    server                  = /usr/sbin/in.tftpd
    server_args             = -s /tftpboot
    disable                 = no
    per_source              = 11
    cps                     = 100 2
    flags                   = IPv4
}

Then start the TFTP server by running:

# service xinetd restart

We can verify the server is running with the following command:

# chkconfig --list | grep tftp
  tftp:   on

As long as tftp: on was returned, the server is up and running.

Note

Cisco phones by default are loaded with their own communication protocol known as SCCP (or Skinny). We will be showing you how to configure the phone, but due to the proprietary nature of Cisco and its phones, you will need to obtain the SIP firmware from your distributor. Also, there are both chan_sccp and chan_skinny modules for Asterisk, but they are beyond the scope of this book.

We will be registering our Cisco phone to the SIP friend we configured in Zaptel Hardware Configuration.” The following configuration file should be saved into a file taking the format of SIP<mac>.cnf, where <mac> represents the MAC address of the telephone device you are configuring. Place this file into the /tftpboot/ directory on your server:

# Line 1 Configuration
line1_name: "1000"
line1_authname: "1000"
line1_shortname: "Jimmy Carter"
line1_password: ""
line1_displayname: ""

# The phone label, displayed in the upper-righthand corner of the phone
phone_label: "aristotle" ; Has no effect on SIP messaging

# Phone password used for console or telnet access, limited to 31 characters
phone_password: "cisco"

Then configure the address to register in the SIPDefault.cnf file, also placed in the /tftpboot/ directory of your server. proxy1_address will contain the IP address of your Asterisk server of where the phone should register for line 1. The image_version contains the version of the .loads and .sb2 files the phone will load into memory.

image_version: P0S3-08-4-00
proxy1_address: 192.168.1.100

We need one additional file called OS79XX.TXT. This file contains only a single line―the .bin and .sbn file version to load into memory:

P003-08-4-00

In order for our Cisco 7960 to use these files, we need to tell the phone where to pull its configuration from. If using the DHCP server from your Linux server, you can modify the /etc/dhcpd.conf file in order to tell the phone where to pull its configuration from by adding the line:

option tftp-server-name "192.168.1.100";

which contains the IP address of the server hosting the TFTP server (assuming of course the TFTP server is configured at that address. This is the address we’ve been using for our Asterisk server, and we again assume you’ve installed the TFTP server on the same box as Asterisk). See DHCP server” for more information about configuring the DHCP server:

ddns-update-style interim;
ignore client-updates;

subnet 192.168.1.0 netmask 255.255.255.0 {
     option routers 192.168.1.1;
     option subnet-mask 255.255.255.0;
     option domain-name-servers 192.168.1.1;
     option tftp-server-name "192.168.1.100";
     option ntp-servers pool.ntp.org;
     option time-offset -18000;

    range dynamic-bootp 192.168.1.128 192.168.1.254;
    default-lease-time 21600;
    max-lease-time 43200;
}

Tip

Alternatively, you can configure from the phone itself to manually use an alternative TFTP server than that given by the DHCP server. To do so, press the settings button, (on the G version of the Cisco phones, this looks like a square with a check mark inside of it; G means Global). You will then need to unlock the settings by pressing the 9 key. The default password is cisco. Once the phone is unlocked, press the 3 key on the dialpad to enter the Network Configuration. Scroll down to option 32 and set the Alternate TFTP to YES. Then scroll up to option 7 and enter the IP address of the TFTP server you wish to boot from. Accept the settings and back out of the menu until the phone reboots itself. You can also use the *-6-settings three finger salute to reboot your phone at any time.

You can watch the phone pull its configuration from the TFTP server by using tshark (yum install ethereal). Filter on port 69 using the following command:

# tshark port 69

You should then be able to watch the network traffic from the phone requesting data from your TFTP server.

If all goes well, then you should see your phone registered to Asterisk!

Linksys SPA-942

Ever since they purchased Sipura Technologies, Linksys has been producing a line of economical VoIP telephones and ATAs (Analog Terminal Adaptors). Linksys has been stealing a lot of business from Cisco. If you have read Clayton M. Christensen’s The Innovator’s Dilemma (HarperCollins), it becomes easier to understand Cisco’s strategy with respect to Linksys.

Linksys (and Sipura) products are well regarded for their excellent quality, especially relative to their price, but they are also famous for being painfully difficult to configure. This is mostly because their configuration GUI offers hundreds of configurable parameters.

We don’t care about that. Here’s what you need to know to get an SPA-942 working with your Asterisk system (and, we hope, most other Linksys VoIP devices as well).

Logging in to the phone

The first thing you need to do is get the IP address of the phone so you can log in to the GUI interface. From the phone itself, select the icon that looks like a piece of paper with a dog-eared corner (right below the envelope icon). This is the Settings button, and is shown in Figure 4-4.

SPA-942 keypad

Figure 4-4. SPA-942 keypad

To get the IP address of the phone, press the Settings button, followed by 9 (or use directional pad and scroll down to Network). Then press the select button (there is a row of 4 buttons under the LCD screen—select is the leftmost button). The second field should show you the IP address of the phone.

Now open your browser, enter the IP address into the address bar, hit Enter, and you will be at the Info screen of the phone.

Registering your phone to Asterisk

Select the Admin Login link in the upper-right corner of the screen. Once you’ve done this, you will be given several new tabs, such as Regional, Phone, Ext 1, Ext 2, and User.

Select the Ext 1 tab which will set up our first line. Then make the following menu selections:

  1. General → Line Enable → yes

  2. NAT Settings → NAT Mapping Enable → no

  3. NAT Settings → NAT Keep Alive Enable → no

  4. Proxy and Registration → Proxy → enter the IP address of Asterisk (e.g., 192.168.1.100)

  5. Proxy and Registration → Register → yes

  6. Proxy and Registration → Make Call Without Reg → no

  7. Proxy and Registration → Ans Call Without Reg → no

  8. Subscriber Information → Display Name → Caller ID information

  9. Subscriber Information → User ID → 1000

  10. Subscriber Information → Password → (leave blank if you’re using the simple configuration from earlier in this chapter)

  11. Subscriber Information → Use Auth ID → yes

  12. Subscriber Information → Auth ID → 1000

  13. Audio Configuration → Preferred Codec → G711u

  14. Audio Configuration → Use Pref Codec Only → no

  15. Audio Configuration → Silence Supp Enable → no

  16. Audio Configuration → DTMF Tx Method → Auto

  17. Submit All Changes

And that’s it! Your phone should be registered to Asterisk now. You’ll know this because the first lighted line button beside the LCD screen will change from orange to green.

Configuring the Dialplan for Testing

In order to allow our phone to call other phones (or, if a multiline phone, to call itself), we need to modify the extensions.conf file. Building on what we had in Setting Up the Dialplan for Some Test Calls,” add the following parts to the [internal] context:

exten => 1000,1,Verbose(1|Extension 1000)
exten => 1000,n,Dial(SIP/1000,30)
exten => 1000,n,Hangup()

If you have two phones, or multiple lines configured, you can duplicate the previous configuration and change the 1000 to the other extension name.

Connecting to a SIP Service Provider

With the advent of Internet telephony, there has been an influx of Internet-based phone companies springing up all over the world! This gives you a large number of choices from which to choose. Many of these service providers allow you to connect your Asterisk-based system to their networks,[66] and some of them are even running Asterisk themselves!

The following configuration should get you connected with an Internet Telephony Service Provider (ITSP),[67] although it is impossible to know the unique configurations each service provider will require from you, and ideally the provider will give you the configuration required to connect your system with its own. However, not all are going to support Asterisk, so we’re going to provide you with a generic configuration which should help you get on your way and, ideally, going in a matter of minutes:

[my_service_provider]
type=peer
host=10.251.55.100
fromuser=my_unique_id
secret=my_special_secret
context=incoming_calls
dtmfmode=rfc2833
disallow=all
allow=gsm
allow=ulaw
deny=0.0.0.0/0
permit=10.251.55.100/32
insecure=invite

Most of the previous configuration may be familiar to you by now, but in case it’s not, here is a brief rundown.

By defining the type as a peer, we are telling Asterisk not to match on the [my_service_provider] name, but rather to match on the IP address in the INVITE message (when the provider is sending us a call). The host parameter is the IP address that we’ll place our calls to, and the IP address we’ll be matching on when receiving a call from the provider.

The fromuser parameter is going to affect the way our INVITE message is structured when sending the call to the provider. By setting our username in the fromuser parameter, we will modify the From: and Contact: fields of the INVITE when sending a call to the provider. This may be required by the provider if it’s using these fields as part of its authentication routine. You can see the places Asterisk modifies the header in the next two code blocks.

Without the fromuser:

Audio is at 66.135.99.122 port 18154
Adding codec 0x2 (gsm) to SDP
Adding codec 0x4 (ulaw) to SDP
Adding non-codec 0x1 (telephone-event) to SDP
Reliably Transmitting (no NAT) to 10.251.55.100:5060:
INVITE sip:15195915119@10.251.55.100 SIP/2.0
Via: SIP/2.0/UDP 66.135.99.122:5060;branch=z9hG4bK32469d35;rport
From: "asterisk" <sip:asterisk@66.135.99.122>;tag=as4975f3ff
To: <sip:15195915119@10.251.55.100>
Contact: <sip:asterisk@66.135.99.122>
Call-ID: 58e3dfb2584930cd77fe989c00986584@66.135.99.122
CSeq: 102 INVITE
User-Agent: Asterisk PBX
Max-Forwards: 70
Date: Fri, 20 Apr 2007 14:59:24 GMT
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 265

With the fromuser:

Audio is at 66.135.99.122 port 11700
Adding codec 0x2 (gsm) to SDP
Adding codec 0x4 (ulaw) to SDP
Adding non-codec 0x1 (telephone-event) to SDP
Reliably Transmitting (no NAT) to 10.251.55.100:5060:
INVITE sip:15195915119@10.251.55.100 SIP/2.0
Via: SIP/2.0/UDP 66.135.99.122:5060;branch=z9hG4bK635b0b1b;rport
From: "asterisk" <sip:my_unique_id@66.135.99.122>;tag=as3186c1ba
To: <sip:15195915119@10.251.55.100>
Contact: <sip:my_unique_id@66.135.99.122>
Call-ID: 0c7ad6156f92e70b1fecde903550a12f@66.135.99.122
CSeq: 102 INVITE
User-Agent: Asterisk PBX
Max-Forwards: 70
Date: Fri, 20 Apr 2007 15:00:30 GMT
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 265

The deny and permit statements are used to deny all incoming calls to this peer except the IP address defined by the permit parameter. This is simply a security measure used to make sure nothing else matches on this peer except traffic coming from the IP address we expect.

At the end is insecure=invite, which may be required for your provider. This is because the source of the INVITE may originate from its backend platform, but could be directed through its SIP proxy server. Basically what this means is that the IP address that the peer is coming from, and which you are matching on, may not be the IP address that is in the Contact line: field of the INVITE message when you are accepting a call from your provider. This tells Asterisk to ignore this inconsistency and to accept the INVITE anyway.

Tip

You may need to set invite=invite,port if the port address is also inconsistent with what Asterisk is expecting.

Now we need one additional parameter set in the [general] section of our sip.conf file: register. register is going to tell the service provider where to send calls when it has a call to deliver to us. This is Asterisk’s way of saying to the service provider, “Hey! If you’ve got a call for me, send it to me at IP address 10.251.55.100.” The register parameter takes the following form:

register => username:secret@my.service_provider.tld

Now we just need to configure a simple dialplan to handle our incoming calls and to send calls via the service provider. We’re going to modify the simple dialplan we started building in the Setting Up the Dialplan for Some Test Calls” section of this chapter. The italicized sections are the new parts that we’re adding to the dialplan, with everything else existing previously.[68]

[globals]

[general]

[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()

[incoming_calls]
exten => _X.,1.NoOp()
exten => _X.,n,Dial(SIP/1000)

[outgoing_calls]
exten => _X.,1,NoOp()
exten => _X.,n,Dial(SIP/my_service_provider/${EXTEN})

[internal]
exten => 1000,1,Verbose(1|Extension 1000)
exten => 1000,n,Dial(SIP/1000,30)
exten => 1000,n,Hangup()

exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()

[phones]
include => internalinclude => outgoing_calls

Connecting Two Asterisk Boxes Together via SIP

There may come a time when you have a pair of Asterisk boxes, and you’d like to pass calls between them. Luckily this isn’t very difficult, although it does have some oddities that we need to deal with, but from the configuration viewpoint it isn’t really all that difficult.

Our topology will consist of a SIP phone (Alice) registered to Asterisk A (Toronto), and a separate SIP phone (Bob) registered to Asterisk B (Osaka). At the end of this section, you will be able to set up a call from Alice to Bob (and vice versa) through your pair of Asterisk boxes (see Figure 4-5). This is a common scenario when you have two physical locations, such as a company with multiple offices that wants a single logical extension topology.

SIP trunking topology

Figure 4-5. SIP trunking topology

First, let’s configure our Asterisk boxes.

Configuring Our Asterisk Boxes

We have a pair of Asterisk boxes that we’re going to call Toronto and Osaka and that we’re going to have register to each other. We’re going to use the most basic sip.conf file that will work in this scenario. Just like the SIP phone configuration earlier in this chapter, it’s not necessarily the best way to do it, but it’ll work.

Here is the configuration for the Toronto box:

[general]
register => toronto:welcome@192.168.1.101/osaka

[osaka]
type=friend
secret=welcome
context=osaka_incoming
host=dynamic
disallow=all
allow=ulaw

And the configuration for the Osaka box:

[general]
register => osaka:welcome@192.168.2.202/toronto

[toronto]
type=friend
secret=welcome
context=toronto_incoming
host=dynamic
disallow=all
allow=ulaw

Many of the previous options may be familiar to you by now, but let’s take a look at them further just in case they are not.

The second line of the file tells our Asterisk box to register to the other box, with the purpose of telling the remote Asterisk box where to send calls when it wishes to send a call to our local Asterisk box. Remember how we mentioned a little oddity in the configuration? Notice that at the end of the registration line we tag on a forward slash and the username of the remote Asterisk box? What this does is tell the remote Asterisk box what digest name to use when it wants to set up a call. If you forget to add this, then when the far end tries to send you a call, you’ll see the following at your Asterisk CLI:

[Apr 22 18:52:32] WARNING[23631]: chan_sip.c:8117 check_auth: username mismatch, 
                                  have <toronto>, digest has <s>

So by adding the forward slash and username, we tell the other end what to place in the Digest username of the Proxy Authorization field in the SIP INVITE message.

The rest of the file is the authorization block we use to control the incoming and outgoing calls from the other Asterisk box. On the Toronto box, we have the [osaka] authorization block, and on the Osaka box, we have the [toronto] block. We define the type as a friend, which allows us to both receive and place calls from the other Asterisk box. The secret is the password the other system should use when authenticating. The context is where incoming calls are processed in the dialplan (extensions.conf). We set the host parameter to dynamic, which tells our Asterisk box that the other endpoint will register to us, thereby telling us what IP address to set up calls when we want to send a call to the other end. Finally, the disallow and allow parameters control the codecs we wish to use with the other end.

If you save the file and reload the SIP channel on both Asterisk boxes (sip reload from the Asterisk console), you should see something like the following, which will tell you the remote box successfully registered:

*CLI>     -- Saved useragent "Asterisk PBX" for peer toronto

You should see the status of the Host change from (Unspecified) to the IP address of the remote box when you run sip show peers:

*CLI> sip show peers
Name/username        Host            Dyn Nat ACL Port     Status               
toronto/osaka        192.168.2.202    D          5060     Unmonitored

You can verify that your own registration was successful by running sip show registry from the Asterisk console:

*CLI> sip show registry
Host                   Username    Refresh State      Reg.Time                 
192.168.1.101:5060     osaka       105 Registered     Sun, 22 Apr 2007 19:13:20

Now that our Asterisk boxes are happy with each other, let’s configure a couple of SIP phones so we can call between the boxes.

SIP Phone Configuration

See the Configuring an FXS Channel for an Analog Telephone” section of this chapter for more information about configuring SIP phones with Asterisk. Below is the configuration for two SIP phones in the sip.conf file for each server, which we’ll be referencing from the dialplan in the next section, thereby giving us two endpoints to call between. Append this configuration to the end of the sip.conf file on each respective server.

Toronto sip.conf:

[2000]
type=friend
host=dynamic
context=phones

Osaka sip.conf:

[1000]
type=friend
host=dynamic
context=phones

You should now have extension 1000 registered to Toronto, and extension 1001 registered to Osaka. You can verify this with the sip show peers command from the Asterisk console. Next, we’re going to configure the dialplan logic that will allow us to call between the extensions.

Configuring the Dialplan

Now we can configure a simple dialplan for each server allowing us to call between the two phones we have registered: one to Toronto, the other to Osaka. In the Working with Interface Configuration Files” section of this chapter, we asked you to create a simple extensions.conf file. We are going to build up a dialplan based on this simple configuration. The dialplan for each server will be very similar to the other one, but for clarity we will show both. The new lines we’re adding to the file will be italicized.

Toronto extensions.conf:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[phones]
include => internal
include => remote

[internal]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(SIP/${EXTEN},30)
exten => _2XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _2XXX,n,Hangup()

[remote]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(SIP/osaka/${EXTEN})
exten => _1XXX,n,Hangup()

[osaka_incoming]include => internal

Osaka extensions.conf:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[phones]
include => internal
include => remote

[internal]exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(SIP/${EXTEN},30)
exten => _1XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _1XXX,n,Hangup()

[remote]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(SIP/toronto/${EXTEN})
exten => _2XXX,n,Hangup()

[toronto_incoming]include => internal

Once you’ve configured your extensions.conf file, you can reload it from the Asterisk console with the dialplan reload command. Verify your dialplan loaded with the dialplan show command.

And that’s it! You should be able to place calls between your two Asterisk servers now.

Configuring an IAX Softphone

A major advantage of using the IAX2 protocol is that it is designed to be more friendly to working within odd network configurations, especially working behind NAT. This makes it a fantastic protocol for softphone clients since they are often utilized on laptops that roam into many different networks, often with no control of the network itself (such as when traveling between hotel networks).

The Inter-Asterisk eXchange (IAX) protocol is usually used for server-to-server communication; more hard phones are available that talk SIP. However, there are several softphones that support the IAX protocol, and work is progressing on several fronts for hard phone support in firmware. The primary difference between the IAX and SIP protocols is the way media (your voice) is passed between endpoints.

With SIP, the RTP (media) traffic is passed using different ports than those used by the signaling methods. For example, Asterisk receives the signaling of SIP on port 5060 and the RTP (media) traffic on ports 10,000 through 20,000 by default. The IAX protocol differs in that both the signaling and media traffic are passed via a single port: 4569. An advantage to this approach is that the IAX protocol tends to be better suited to topologies involving NAT.

There exist many IAX-based softphones, but not so many hardware based phones. The most pronounced reason is because IAX2 is not yet an IETF standard, yet many people have become early adopters and have reaped the benefits.

An excellent IAX2 softphone is idefisk, available at http://www.asteriskguru.com[69] for free download. The authors have had excellent results with this softphone, and since it runs on Microsoft Windows, Mac OS X, and Linux, it is an excellent cross-platform softphone to write about. We will be demonstrating version 1.31 in this book, although version 2.0 was recently released (April 2007) but is not yet available for Linux.

Configuring the Channel Configuration File (iax.conf)

Like the rest of this chapter, we’re attempting to get you up and running quickly with the smallest configuration file set possible in order to minimize the problems you may have in configuring your devices. Just like the sip.conf file, iax.conf requires only a few simple lines to get our IAX phone registered to Asterisk. Let’s take a look:

[general]
autokill=yes

[idefisk]
type=friend
host=dynamic
context=phones

Yes, really, that’s all you need to get your softphone up and running. It’s not the most secure or feature-rich configuration (we’re not even using a password), but this will work.

In the [general] section of our iax.conf file, we have a single option: autokill= yes. We use this option to avoid things from stalling when a peer does not ACK (reply) to our NEW packet (new call setup request) within 2000 milliseconds. Instead of the reply to value yes, you can set this to the number of milliseconds to wait for the ACK to our NEW packet. You can control the autokill option for each individual peer by defining qualify for those peers that you know may be on poor network connections.

The rest of the file contains the definition for our softphone. We define the type as friend, which tells Asterisk we will send calls to this device and also accept calls from this device. A friend is a shortcut for defining a separate peer (send calls to the softphone), and user (accept calls from the softphone). We could also have defined individual definitions for the peer and user like so:

[idefisk]
type=user
context=phones

[idefisk]
type=peer
host=dynamic

Once you’ve configured your iax.conf file, save the file and reload the IAX2 channel module from your Asterisk console with module reload chan_iax2.so. Confirm your new peer exists by running iax2 show peers.

localhost*CLI> iax2 show peers
Name/Username    Host                 Mask             Port          Status    
idefisk          (Unspecified)   (D)  255.255.255.255  0             Unmonitored
1 iax2 peers [0 online, 0 offline, 1 unmonitored]

Configure the Softphone

Once you’ve installed the idefisk softphone, open up the client and you’ll see the main screen shown in Figure 4-6.

idefisk

Figure 4-6. idefisk

After we’ve started the softphone, we need to configure our softphone so we can place calls. We also need to register to Asterisk so we can receive calls. To do this, Right-click on the icon in the top-left corner of the screen, which will open a drop-down menu. Select Account Options from the drop-down, which will bring up the screen shown in Figure 4-7.

idefisk Account Options screen

Figure 4-7. idefisk Account Options screen

Start by creating a new account on the softphone by clicking the New button and filling out the relevant information. The Host should point to the IP address or domain name of your Asterisk system, with the username matching that of the value located between the square brackets [ ] in your iax.conf file. Leave the password field blank, as we did not configure a secret in iax.conf, and the Caller ID and Number can be set to whatever you wish. If you want idefisk to register this account on startup, select the “Register on startup” checkbox. When done, click the OK button to save the new account.

If you clicked the “Register on startup checkbox,” then the phone will attempt to register to Asterisk. On the Asterisk console you will see output telling you that the phone has registered:

-- Registered IAX2 'idefisk' (UNAUTHENTICATED) at 127.0.0.1:32771

You can verify your registration with the iax2 show peers command at the Asterisk console:

localhost*CLI> iax2 show peers
Name/Username    Host                 Mask             Port          Status    
idefisk          127.0.0.1       (D)  255.255.255.255  32771         Unmonitored
1 iax2 peers [0 online, 0 offline, 1 unmonitored]

Configuring the Dialplan for Testing

One final thing to do is confirm dialing through our phone by configuring a simple dialplan in extensions.conf. You can simply test that you have audio in both directions by calling extension 500, or you can modify the dialplan we created in the Setting Up the Dialplan for Some Test Calls” section of this chapter to place some test calls. If you also configured a SIP phone at extension 1000 in the previous sections, then the following will not overlap with that, as we’ll be using extension 1001 (unless you configured multiple SIP extensions, in which case just configure a unique extension number for your IAX2 softphone):

[globals]

[general]

[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()

[incoming_calls]

[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()

exten => 1001,1,Verbose(1|Extension 1000)
exten => 1001,n,Dial(IAX2/idefisk,30)
exten => 1001,n,Hangup()

[phones]
include => internal

Connecting to an IAX Service Provider

Some Internet Telephony Service Providers (ITSPs) provide the ability to originate and terminate calls via the IAX2 protocol. Beyond minimizing the number of ports required to be open on the firewall (IAX2 only requires a single port for both signaling and media), the protocol’s trunking feature is attractive to both ITSPs and their customers due to the savings in bandwidth that can be obtained when running many simultaneous calls between endpoints.

If your ITSP is offering IAX2 termination, there is a strong chance it is running Asterisk; thus the configuration for connecting to these service providers is more than likely going to be similar to what we are providing here.

The following configuration is a template for connecting to an IAX2 service provider:

[general]
autokill=yes

register => username:password@my.service-provider.tld

[my_unique_id]
type=user
secret=my_unique_password
context=incoming_calls
trunking=yes
disallow=all
allow=gsm
allow=ulaw
deny=0.0.0.0/0.0.0.0
permit=10.251.100.1/255.255.255.255

[my_unique_id]
type=peer
host=10.251.100.1
trunking=yes
disallow=all
allow=gsm
allow=ulaw

To accept incoming calls from the Direct Inward Dialing (DID) number that your service provider assigned to you, we need to modify our extensions.conf file. Perhaps you want to send the call to an auto-attendant, or maybe simply to your desk phone. In either case, you can accept calls from your service provider and match on the incoming DID with the following bit of dialplan logic:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]
exten => 14165551212,1,NoOp()
exten => 14165551212,n,Dial(SIP/1000,30)
exten => 14165551212,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => 14165551212,n,Hangup()

exten => 4165551212,1,Goto(1${EXTEN})

[internal]

[phones]
include => internal

Connecting Two Asterisk Boxes Together via IAX

Often it is desirable to connect two physical Asterisk boxes together via IAX in order to send calls between two physical locations (the distance between these locations may be centimeters or kilometers). One of the advantages to using the IAX protocol to do this is a feature called trunking, which utilizes a method of sending the voice data for multiple calls at once with a single header. This has little effect on only one or two simultaneous calls, but if you are sending tens or hundreds of calls between two locations, the bandwidth savings by utilizing trunking can be tremendous.

Note

You will need a timing interface installed on your system, whether it be hardware from Digium or via the kernel by using the ztdummy driver. This will require you to have Zaptel installed on your system and running. See Chapter 3 for more information about installing Zaptel.

Configuring Our Asterisk Boxes

We’ll be utilizing a simple topology where we have two Asterisk boxes registered to each other directly, and separate phones registered to each Asterisk box. We’ll call the two Asterisk boxes Toronto and Osakafi (see Connecting Two Asterisk Boxes Together via SIP”). Bob’s phone will be registered and connected to Toronto, while Alice’s phone will be registered and connected to Osaka.

The first thing we want to do is create a new channel file (iax.conf) by renaming the current sample file to iax.conf.sample and creating a new blank iax.conf:

# cd /etc/asterisk
# mv iax.conf iax.conf.sample
#touch iax.conf

Next, open up the iax.conf file and enter the following configuration on the Toronto Asterisk box:

[general]
autokill=yes

register => toronto:welcome@192.168.1.107

[osaka]
type=friend
host=dynamic
trunk=yes
secret=welcome
context=incoming_osaka
deny=0.0.0.0/0.0.0.0
permit=192.168.1.107/255.255.255.255

autokill=yes was explained in the previous section, but its purpose is to make sure new calls being set up to a remote system that are not acknowledged within a reasonable amount of time (two seconds by default) are torn down correctly. This saves us from having a lot of hung channels simply waiting for an acknowledgement that probably isn’t coming.

The register line is used to tell the remote Asterisk box where we are so that when the box at 192.168.1.107 is ready to send us a call, it sends it to our IP address (in this case our IP address is 192.168.1.104, which you’ll see in the iax.conf configuration of the Osaka box). We send the username Toronto and the password welcome to Osaka, which authenticates our registration, and if accepted, writes the location of our Asterisk box into its memory for when it needs to send us a call.

The [Osaka] definition is used to control the authentication of the remote box and delivery into our dialplan. Osaka is the username used in the incoming authentication. We set the type to friend because we want to have both the ability to send calls to Osaka and to receive calls from Osaka. The host option is set to dynamic which tells Asterisk to send calls to the IP address obtained when the opposite endpoint registers with us.

In the introduction to this section, we mentioned the possible bandwidth savings when utilizing IAX2 trunking. It’s simple to enable this functionality in Asterisk, as we just need to add trunk=yes to our friend definition. As long as a timing interface is installed and running (i.e., dummy), then we can take advantage of IAX2 trunking.

The secret is straightforward: it’s our authentication password. We’re defining the [incoming_osaka] context as the place we will process incoming calls for this friend in the extensions.conf file. Finally, we block all IP addresses with the deny option from being allowed to authenticate, and explicitly permit 192.168.1.107.

The iax.conf configuration for Osaka is nearly identical, except for the changes in IP address and names:

[general]
autokill=yes

register => osaka:welcome@192.168.1.104

[toronto]
type=friend
host=dynamic
trunk=yes
secret=welcome
context=incoming_toronto
deny=0.0.0.0/0.0.0.0
permit=192.168.1.104/255.255.255.255

IAX Phone Configuration

In the Configure the Softphone” section, we configured our first IAX2 softphone using idefisk. The configuration we’ll be using here is nearly identical except for minor changes in order to cause the peers to be unique. If you’ve already configured a SIP softphone, then you can also utilize that on one (or both) of the peers. Remember that Asterisk is a multiprotocol application, and you can send a call from a SIP phone to Asterisk, across an IAX2 trunk, and then down to another SIP phone (or H.323, MGCP, etc.).

On Osaka:

[1001]
type=friend
host=dynamic
context=phones

On Toronto:

[2001]
type=friend
host=dynamic
context=phones

Next, configure your IAX2 softphone to register to Asterisk. If the phone successfully registers, you’ll see something like:

*CLI>     -- Registered IAX2 '1001' (UNAUTHENTICATED) at 192.168.1.104:4569

Configuring the Dialplan

In order to allow calling between our two Asterisk boxes over the IAX2 trunk, we need to configure a simple dialplan. The following dialplan will send all extensions in the 1000 range (1000–1999) to Osaka, and all extensions in the 2000 range (2000–2999) to Toronto. Our example is going to assume that you have configured a pair of IAX2 softphones, but feel free to utilize a SIP phone if you’ve already configured one (or two). Just be aware that you’ll need to change the Dial() application to send the call to the SIP phone via the SIP protocol instead of IAX2 (i.e. Dial(SIP/${EXTEN},30) instead of Dial(IAX2/${EXTEN},30)).

The extensions.conf file on Toronto:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[phones]
include => internal
include => remote

[internal]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(IAX2/${EXTEN},30)
exten => _2XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _2XXX,n,Hangup()

[remote]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(IAX2/osaka/${EXTEN})
exten => _1XXX,n,Hangup()

[osaka_incoming]
include => internal

The extensions.conf file on Osaka:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[phones]
include => internal
include => remote

[internal]exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(IAX2/${EXTEN},30)
exten => _1XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _1XXX,n,Hangup()

[remote]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(IAX2/toronto/${EXTEN})
exten => _2XXX,n,Hangup()

[toronto_incoming]
include => internal

Using Templates in Your Configuration Files

There is a little-known secret in Asterisk config files that is so brilliant that we had to devote a little section to it.

Let us say that you have 20 SIP phones that are all pretty much identical in terms of how they are configured. The documented way to create them is to specify the parameters for each. Part of such a sip.conf file might look like this:

[1000]
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1000
secret=AllYourSetsAreBelongToUs

[1001]
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1001
secret=AllYourSetsAreBelongToUs

[1002]
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1002
secret=AllYourSetsAreBelongToUs

Seems like a lot of extra typing, cutting, and pasting, yes? And what if you decide that you are going to change the context for your sets to another name. Not looking good, is it?

Enter the template. Let’s create the same SIP friends as we did above, only this time using the template construct:

[sets](!) ; <== note the exclamation point in parenthesis. That makes this a template.
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
secret=AllYourSetsAreBelongToUs

[1000](sets) ; <== note the template name in parenthesis. All of that templates  
             ; settings will be inhereted.
maibox=1000

[1001](sets)
maibox=1001

[1002](sets)
maibox=1002

This is one of the best kept secrets of conf file creation. In our experience, very few people use this, but for no other reason than that they don’t know about it. Well, that’s about to change. Our goal is to see everyone using these from now on; and yes, we will be checking.

Debugging

Several methods of debugging are available in Asterisk. Once you’ve connected to the console, you can enable different levels of verbosity and debugging output, as well as protocol packet tracing. We’ll take a look at the various options in this section.

Connecting to the Console

To connect to the Asterisk console, you can either start the server in the console directly (in which case you will not be able to exit out of the console without killing the Asterisk process), or start Asterisk as a daemon and then connect to a remote console.

To start the Asterisk process directly in the console, use the console flag:

# /usr/sbin/asterisk -c

To connect to a remote Asterisk console, start the daemon first and then connect with the -r flag:

# /usr/sbin/asterisk
#/usr/sbin/asterisk -r

If you are having a problem with a specific module not loading, or a module causing Asterisk to not load, start the Asterisk process with the -c flag to monitor the status of modules loading. For example, if you attempt to load the OSS channel driver (which allows the use of the CONSOLE channel), and Asterisk is unable to open /dev/dsp, you will receive the following error on startup:

WARNING[32174]: chan_oss.c:470 soundcard_init: Unable to open /dev/dsp: 
No such file or directory
  == No sound card detected -- console channel will be unavailable
  == Turn off OSS support by adding 'noload=chan_oss.so' in /etc/
     asterisk/modules.conf

Enabling Verbosity and Debugging

Asterisk can output debugging information in the form of WARNING, NOTICE, and ERROR messages. These messages will give you information about your system, such as registrations, status, and progression of calls, and various other useful bits of information. Note that WARNING and NOTICE messages are not errors; however, ERROR messages should be investigated. To enable various levels of verbosity, use set verbose followed by a numerical value. Useful values range from 3 to 10. For example, to set the highest level of verbosity, use:

# set verbose 10

You can also enable core debugging messages with set debug followed by a numerical value. To enable DEBUG output on the console, you may need to enable it in the logger.conf file by adding debug to the console => statement, as follows:

console => warning,notice,error,event,debug

Useful values for set debug range from 3 to 10. For example:

# set debug 10

Conclusion

If you've worked through all of the sections in this chapter, you will have configured a pair of analog interfaces, a local SIP and IAX2 channel connected to a softphone and/or a hardphone, and placed calls across servers using the SIP and IAX2 protocols. These configurations are quite basic, but they give us functional channels to work with. We will make use of them in the following chapters, while we learn to build more useful dialplans.



[49] Officially, the current version is IAX2, but since all support for IAX1 was dropped many years ago, whether you say “IAX” or “IAX2,” you are talking about the same version.

[50] This configuration used to be known as the Digium Dev-lite kit. For more information on FXS versus FXO, keep reading. Put simply, this card will give us one port to connect to a traditional analog line from the phone company (FXO), and one port to connect to an analog telephone (FXS), which is any type of phone that will work with a traditional home telephone circuit.

[51] …and H.323 and SCCP and MGCP and UNISTIM

[52] Bidirectional communication is also known as full duplex in some circles. Half duplex means communication is only traveling in one direction at a time.

[53] Yes, there is such a thing as ground-start signaling on channelized T1s, but that has nothing to do with an actual ground condition on the circuit (which is entirely digital).

[54] A far-end disconnect happens when the far end hangs up. In an unsupervised circuit, there is no method of telling the near end that the call has ended. If you are on the phone this is no problem, since you will know the call has ended and will manually hang up your end. If, however, your voicemail system is recording a message, it will have no way of knowing that the far end has terminated and will, thus, keep recording silence, or even the dial tone or reorder tone. Kewlstart can detect these conditions and disconnect the circuit.

[55] It is generally safe to assume that the modules have loaded successfully, but to view the debugging output when loading the module, check the console output (by default this is located on TTY terminal 9, but this is configurable in the safe_asterisk script—see the previous chapter for details).

[56] Also referred to as the Batphone method, and more formally known as an Automatic Ringdown or Private Line Automatic Ringdown (PLAR) circuit. This method is commonly used at rental car counters and airports.

[57] RFC 3261 is available at http://www.ietf.org/rfc/rfc3261.txt. While the document is fairly large, we strongly encourage anyone who wishes to become an Asterisk professional to read at least the first 100 or so pages of this document and to understand how calls are set up, as this knowledge will be imperative when you’re looking at a SIP trace (sip debug from the Asterisk console) trying to determine why your calls are not getting set up correctly.

[58] An excellent open source SIP proxy is OpenSER, available at http://www.openser.org.

[59] Yes, there are ways to making the media flow directly between the phones once the call is set up. This is done in the sip.conf file using either directrtpsetup=yes (an experimental option allowing the media to be redirected in the initial call setup) or canreinvite=yes (where media initially goes through Asterisk until a re-INVITE happens, at which point the media can be sent directly between the phones).

[60] The maximum length of a username is 255 characters.

[61] Typically, it’s at 4 A.M. on the morning of a critical 8 A.M. meeting, after having worked all weekend. Red Bull is probably the most popular drink of the Asterisk developers. Dr. Pepper would be a close second. Red Bull, anyone?

[62] FTP is preferred over TFTP due to the ability of a Polycom phone to see timestamps on FTP files. This allows the phone to avoid redownloading configuration files and firmware updates that it already has—thus shortening boot time.

[63] You can get into assigning complex and unguessable passwords for the phones to use, but unless you are going to input the passwords into each phone manually, you’ll have to pass them their FTP username and password from the DHCP server. Any device that can get on the voice network can get the same information from the DHCP server. We’re not telling you to ignore security; just don’t assume that creating separate passwords for each phone is going to improve security.

[64] Actually, it does serve one useful purpose, which is to allow you to log on to a set via a browser and query its configuration.

[65] You can get into assigning complex and unguessable passwords for the phones to use, but unless you are going to input the passwords into each phone manually, you’ll have to pass them their FTP user name and password from the DHCP server. Any device that can get on the voice network can get the same information from the DHCP server. We’re not telling you to ignore security, just don’t assume that creating separate passwords for each phone is going to improve security.

[66] Be sure to check the policy of any service provider you are looking to connect with, as some of them may not allow you to use a PBX system with its service.

[67] Also known as a VoIP Service Provider (VSP).

[68] We also assume you have configured at least one SIP extension from the previous section.

[69] The Asterisk Guru site is also an excellent source of documentation!

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required