3.3. Compiling and Installing Asterisk
RPM packages are available to simplify Asterisk's installation, but manual compiling is relatively easy. So we are going to download, compile, and install Asterisk the old-fashioned way. Real performance mechanics prefer a manual transmission over an automatic for better command and control, after all.
The development branch you'll download from is stablethough once you get comfortable with Asterisk, you'll want to jump out on the bleeding edge and try the developer releases, too. Each release tends to introduce something new and worthwhile, even if it's not in the stable branch yet.
The easiest place to download the Asterisk software is the CVS repository at Digium, the company responsible for Asterisk and the hardware components that work with it. To access the CVS repository, you'll need to be logged into your Linux computer at a shell prompt as root. Type these commands to run the CVS checkout routine and download the source code:
# cd /usr/src # export CVSROOT=:pserver:firstname.lastname@example.org:/usr/cvsroot # cvs login # cvs checkout zaptel libpri asterisk
Alternatively, you can specify a particular version of Asterisk:
# cvs checkout -r v1-0 asterisk
When prompted, use "anoncvs" as a password. If your Linux distribution doesn't use /usr/src , then substitute the source path that's appropriate. The CVS client you're running here will create the /usr/src/asterisk directory that contains all the Asterisk source code. Once the download completes, you are ready to begin compiling.
3.3.1. Install the Software Components of Asterisk
Asterisk consists of several software components for Linux. These packages are not all required, as some of them are drivers for Digium's interface cards. If you aren't planning to use Digium's card, you'll need to build only the last of the three, "Asterisk":
If you're wondering about these technical terms, don't worry. As you experiment with Asterisk and learn more about VoIP, they'll become very familiar. For now, just compile and install all three of them.
Since you ran the CVS download, the source code for each of the Asterisk software components is sitting in its respective directory in /usr/src . Let's compile each software component by issuing the following commands:
# cd zaptel # make clean ; make install # cd ../libpri # make clean ; make install # cd ../asterisk # make clean ; make install
Again, zaptel and libpri need only be compiled if you're planning on using legacy interface cards. Many of the examples in this book make use of legacy devices, so it's probably a good idea to compile them all right now.
It should take 20 minutes at most to complete the whole build on an average PC. Once built, Asterisk is ready to use. But you can't drive this Ferrari without a license, and you can't really use Asterisk until you understand the basics of configuring it. So it's time for driving school. To get started, do this:
# make samples
Now, a basic sample set of Asterisk configuration files is set up in /etc/asterisk .
3.3.2. For Those Who Prefer RPM Packages
Red Hat RPM packages for Asterisk and the driver modules can be obtained from http://www.macvoip.com or from http://www.n2net.net.
3.3.3. Loading the Interfacing Drivers
The software drivers that allow Asterisk to use telephone line interfaces (like the X100P) come in the form of kernel modules (files that add core functionality to the operating system), and we compiled them in the previous section. In order to make sure Asterisk will function correctly, you'll need to load the modules using these shell commands:
# modprobe zaptel # modprobe wcfx ## if you're using a TDM400P # modprobe wcfxo ## if you're using a X100P # ztcfg -vvv ## more verbosity with every 'v'
These commands enable the Digium X100P card in your computer (if you're using one) and create logical channels that Asterisk can use for voice traffic. The order of execution of these commands is important, because voice channels are numbered in the same order their interface cards are enabled. If you had two X100P cards installed or a TDM400P with two FXO modules, you would have two logical voice channels.
In the three preceding modprobe commands, the zaptel driver loads low-level support for any of Digium's cards, while the wcfxo and wcfxs modules load signaling support for analog telephone lines and phones, respectively. You'll use different combinations of kernel modules depending on what types of interfacing you're using: if you had an analog telephone connected directly to a TDM400P, for example, you would also need to modprobe the wcfxs module.
The ztcfg command tests the specific configuration of each voice channel as specified in the /etc/zaptel.conf file. You'll need to visit this file with your text editor before you can use analog phone linesand we'll do exactly that in Chapter 4. Non-Zaptel (i.e., non-Digium) is configured elsewhere.
You aren't required to use Digium's interface cards in order to experiment with VoIPbut if you want your VoIP phones to be able to talk to the public telephone system, your Asterisk server will need to hook into a traditional telephone company line. See the section called "Installing Legacy Interface Cards" earlier in this chapter to learn how to install an interface card. Other kernel modules besides the ones shown here are relevant to Asterisk. Each supports a different model of interface hardware.
Here's a summary of the kernel modules that correspond to some of the interface cards described in the "Installing Legacy Interface Cards" section:
A basic Asterisk setup, like the one in Figure 3-2, uses VoIP phones on the LAN that can connect to the public telephone system through a single analog telephone line. Using an X100P card, you'll need to load only the zaptel and wcfxo modules. The right modules must be loaded in order to launch Asterisk if it is configured to use traditional voice interfaces. If you don't load the right modules first, the Asterisk server won't start and you'll get a message in Asterisk's standard error output about it.
It's very easy to accidentally enable Asterisk to use a channel that hasn't been set up by modprobing the right module or to install a new interface card and then forget to modprobe it before launching Asterisk. Both of these situations will result in an Asterisk that won't start up. One way avoid this problem is to have your startup scripts attempt to modprobe them all, regardless of whether the corresponding hardware is installed.
3.3.4. Starting and Stopping the Asterisk Server
The Asterisk binary is the program that you execute whenever you want to start the Asterisk server or connect to it for management purposes. The same program has two distinct modes of operationserver mode and client mode. The server is the instance of Asterisk that stays running all the time, handling calls, recording voice mail, greeting callers while users are away, and so on. The client is the instance of Asterisk that allows you to monitor and manipulate the server while it runs. The mode the program uses depends on how Asterisk is invoked at the command prompt or within a shell script.
To launch Asterisk in server mode, execute this command:
# asterisk &
To connect Asterisk in client mode on a machine already running in server mode, execute this command:
# asterisk -r
Once the Asterisk client is connected to the Asterisk server, you can use Asterisk's command-line interface to issues queries and commands about the telephony server. These include listing calls-in-progress, listing used and unused channels, and stopping the Asterisk server.
Several Asterisk CLI commands shut down the server:
The restart commands stop and then restart the Asterisk server process, which can be helpful in situations where the server's configuration has significantly changed and needs to be restarted. The stop commands just shut the Asterisk server process down. You'll have to execute the Asterisk program to get it running again.
The now and when convenient arguments tell Asterisk how quickly to shut down or restart. If you want to ignore the current calls and tasks in progress on the server, now is appropriate. If you want Asterisk to wait until all the calls and tasks are finished and there is no call activity at all, when convenient is appropriate. Generally , especially if you're planning to have any callers beside yourself on the system, get in the habit of using when convenient .
Of course, in extreme circumstances, like if the Asterisk CLI is unavailable or not responsive , you can stop the Asterisk server process from a shell like this. Get the process ID (PID) of the Asterisk server process:
# ps ax grep asterisk
You'll see something like this:
424 std S+ 0:00.00 asterisk
The first bit of information is the PID, or process ID. Now, use that PID to kill the Asterisk server process:
# kill -9 425
The -9 is the same as using now at the Asterisk CLI. Any outstanding Asterisk threads, including calls in progress, filesystem requests such as logging, and administrative instructions, are immediately and abruptly ended so the server process can terminate. This technique is a last-ditch effort that should be avoided if possible.
3.3.5. Configuring for Automatic Startup at Boot Time
In Red Hat Linux, a tree of shell script files dictates the startup procedure for the operating system. After the kernel loads, user commands are executed in the sequence spelled out by the scripts located in /etc/rc.d . There are two accepted methods for adding Asterisk to the startup sequence: one that uses modifications to rc.local (the quick and dirty method), and another that involves a script wholly dedicated to Asterisk.
22.214.171.124 Using rc.local to launch Asterisk
To make Asterisk start automatically at boot time, modify one of the boot-time scripts, rc.local , to launch Asterisk in server mode. While you may find the second boot-time method more to your liking, this one shows how to launch Asterisk short and sweetin four lines of shell commands.
Edit the script called /etc/rc.d/rc.local , adding commands to automatically start the Asterisk server. You can use Pico or your favorite Unix text editor to put these commands into the script:
export LD_ASSUME_KERNEL=2.4.1 modprobe zaptel ## optional modprobe wcfxo ztcfg /usr/sbin/asterisk -vvv &> /var/log/asterisk/pbx-tty.log &
The first line takes care of an incompatibility that Red Hat 9 imposes (you don't need this line for Red Hat 7.3 and 8), while the second and third lines load the Digium hardware kernel modules. The last line launches the Asterisk server using the -vvv switch for very verbose output (the more v s you use, the more detailed the logging is). The last line also redirects that output to a file called /var/log/asterisk/pbx-tty.log . Asterisk will now be launched as root by Red Hat's startup routine whenever the computer is booted .
126.96.36.199 Using the safe_asterisk script
The Asterisk distribution is equipped with a script that attempts to relaunch the Asterisk server if it crashes. While rare, the Asterisk software can have fatal exceptionswhich result in the shutdown of Asterisk. The script can be found in /usr/sbin/safe_asterisk . It passes all command-line arguments to the Asterisk instance, and it redirects all output to the shell, so you can further redirect the output like the previous argument. The safe_asterisk script does not restart Asterisk if you shut it down intentionally, say, using a kill command.
188.8.131.52 Setting up a Red Hat init script for Asterisk
The second method of adding Asterisk to your server's startup routing is to generate a Red Hat init script. This method produces a larger script that Linux newbies may have a hard time dissecting, but it also gives you more power. That is, the init script is useful at times other than boot time.
To generate Red Hat-friendly initialization scripts for Asterisk, you'll need to run a make config from the directory where the Asterisk source code resides:
# cd /usr/src/asterisk # make config
You will see this output or something close to it:
if [ -d /etc/rc.d/init.d ]; then \ install -m 755 init.asterisk /etc/rc.d/init.d/asterisk; \ /sbin/chkconfig --add asterisk; \ elif [ -d /etc/init.d ]; then \ install -m 755 init.asterisk /etc/init.d/asterisk; \ fi
Now, you can issue /etc/rc.d/init.d/asterisk to control Asterisk with these command-line arguments:
3.3.6. Securing the Asterisk Instance
By default, Asterisk runs as rootthe user account with total, unrestricted power. This is generally considered a bad idea, and it's the reason Apache, the web server, doesn't usually run as root. If Asterisk is compromised by an ill-willed network prowler, it's possible that the intruder could gain the power of root. That is, unless you make Asterisk run as a less godly user.
To do this, create a user called "asterisk" by issuing the Red Hat adduser command (other Unixes could use useradd instead):
# adduser -c "Asterisk PBX" -d /var/lib/asterisk asterisk
Next, you'll need to alter Asterisk's make file, located at /usr/src/asterisk/Makefile . Using Pico or your favorite text editor, find the ASTVARRUNDIR constant in the file, and alter its definition to match what follows :
The directory referenced here needs to be writable by the user running Asterisk, and the directory normally used should be writable only by root. So by changing the setting, you're allowing Asterisk to use a directory that can be written by its own non-root user account. Now, recompile Asterisk using this sequence of commands:
# cd /usr/src/asterisk # make clean ; make install
Once the recompile and install are done, you'll need to make sure the new user account has appropriate permission to several Asterisk- related directories, including the one you referenced in the altered Makefile:
# chown -R asterisk:asterisk /var/lib/asterisk # chown -R asterisk:asterisk /var/log/asterisk # chown -R asterisk:asterisk /var/run/asterisk # chown -R asterisk:asterisk /var/spool/asterisk # chown -R asterisk:asterisk /dev/zap # chmod -R u=rwX,g=rX,o= /var/lib/asterisk # chmod -R u=rwX,g=rX,o= /var/log/asterisk # chmod -R u=rwX,g=rX,o= /var/run/asterisk # chmod -R u=rwX,g=rX,o= /var/spool/asterisk # chmod -R u=rwX,g=rX,o= /dev/zap # chown -R root:asterisk /etc/asterisk # chmod -R u=rwX,g=rX,o= /etc/asterisk
You can now launch the Asterisk server from the new user account or from root using the su command:
# su asterisk -c /usr/sbin/safe_asterisk
Finally, you'll need to adjust the safe_asterisk script so that it uses the new user account to launch Asterisk, rather than root. To do this, open /usr/sbin/safe_asterisk in Pico or your favorite text editor, and add su asterisk -c before each instance of an asterisk command. Be sure to leave the commands unchanged, aside from prefixing them with the su command.
Once these steps are taken, Asterisk will have only as much power as you grant the "asterisk" user. Would-be attackers may be able to crash Asterisk, but in so doing, they won't be able to gain access to root's credentials.
3.3.7. Asterisk on Mac OS X
Besides Linux, Asterisk will run on some commercial Unixes, including the most popular of those, Mac OS X. A binary (already-compiled) distribution is available from http://www.macvoip.com. The configuration examples described earlier won't work on OS X, because it's a totally different flavor of Unix than Red Hat Linux. If you are looking for a good reference for learning the Mac's flavor of Unix, try Mac OS X Panther for Unix Geeks (O'Reilly).
As of this writing, drivers for legacy interface cards have not been ported to OS X, but with IP phones, the Mac port is fully functional. Indeed, with Applescript, iCal, and iTunes at every Mac user's disposal, there are big possibilities for fun Asterisk hacks. Again, all the examples in this book are geared to Red Hat Linux systems.
Developers interested in porting the hardware to the Mac should consider the work of the Asterisk on BSD project, for which Digium operates an email support list. Mac OS X has a version of BSD Unix called Darwin at its core, so it should be easier to port Asterisk-related code to the Mac from the existing BSD code rather than from the Linux code.
3.3.8. Project 3.1. Test an IP Phone with Asterisk
184.108.40.206.1 What you need for this project:
You've done some Asterisk compiling and customization using the Linux shell. But once Asterisk is installed, you'd probably prefer to interact with it from a more appropriate devicea telephone. In this project, we'll use the SIP telephone we configured in Projects 2.1 and 2.2 in order to access the de facto autoattendant greeting and access a brief demonstration of an IAX (Inter-Asterisk Exchange) trunk over the Internet. Sound like too much? Don't worry; most of this is already configured with Asterisk out of the box. The toughest part for a VoIP beginner will be making sure Asterisk is able to answer SIP callsand that's pretty easy.
SIP (Session Initiation Protocol) is one of several standards that allow IP voice endpoints and application servers such as Asterisk (and ReSIProcator and SIP Express Router) to establish, monitor, and tear down media sessions across the network. Asterisk uses SIP to facilitate calls on behalf of SIP-based IP phones like the Budgetone 101, the Cisco SIP IP Phone 7960, or the Avaya 4602.
220.127.116.11 Verify Asterisk's SIP server is running
To get started, Asterisk will need its SIP server module running so that it can listen for SIP calls. By default, Asterisk's SIP server module listens on UDP port 5060, the commonly used port number for SIP. If you use the SIP phone (10.1.1.103) to dial the Asterisk server (10.1.1.10) by IP address, you should get a 404 message on the phone's display: 404 is a SIP error code that means "Not Found"just like the 404 message used on the Web. If you get this response from the Asterisk server, it means the SIP module is listening and has responded to you.
Now, in order to go from dialing only by IP address to dialing by extension, the IP phone must be pointed to the SIP server.
18.104.22.168 Set the IP phone to use a SIP server
The IP phone, whose address is 10.1.1.103, must be set to use a SIP server if it is to make calls other than the IP-to-IP type described in Chapter 2. In the test network, the IP phone should refer to the IP address of the Asterisk server, 10.1.1.10, as its SIP server. (For the details on SIP servers, refer to Chapter 7.)
Configure the SIP user ID setting as 103, too. For the DTMF Mode option, select SIP Info . Then apply the config changes and reboot the IP phone. The same configuration options are supported by other makes of SIP phone, too. The configuration page for a Budgetone phone that has been configured to use a local SIP server is shown in Figure 3-4.
22.214.171.124 Allow the IP phone to place calls via Asterisk
Until you authorize a SIP phone to communicate with Asterisk using Asterisk's SIP configuration file, you will always receive SIP error messages when trying to dial to (or through) the Asterisk server. This is Asterisk's way of ignoring what it sees as an unauthorized endpoint. Unlike traditional PBXs, which tend to give network access to any phone connected on an active port, SIP servers tend to enforce some securityusually in the form of authentication.
Figure 3-4. A Grandstream Budgetone that has been configured to use a SIP server at 10.1.1.10
Let's tell the Asterisk server to stop ignoring requests from your IP phone. Asterisk, the softPBX, refers to IP phones and other SIP devices as peers . SIP peers are defined in Asterisk's configuration file, /etc/asterisk/sip.conf . To enable the phone as configured in Figure 3-4, add the following to the end of this file:
[defaultsip] type=friend context=default username=103 fromuser=SIP Phone callerid=103 host=10.1.1.103 nat=no canreinvite=yes dtfmode=info disallow=all allow=ulaw
The preceding section adds the 10.1.1.103 IP phone that matches the configuration of the earlier Grandstream Budgetone. Don't worry about the meaning of this syntaxthese settings are covered in more detail later.
126.96.36.199 Restart or reload?
There are two ways to enable the configuration change you've just made. One is to restart Asterisk:
# /etc/rc.d/init.d/asterisk restart
Bear in mind that restarting your softPBX might be acceptable at home or even in a small-office environment, but you'd better make sure there are no calls in progress if you restart it in any production environment, lest you draw the ire of angry phone users. Perhaps a better way to handle the addition of a new endpoint to the softPBX is the reload method. To do this, log into the Asterisk CLI using:
# asterisk -r
Then issue the Asterisk reload command:
You'll notice that no calls are interrupted when the reload occurs. This should keep everyone who is using the system while you work happy.
Now you can place calls to the Asterisk server and to the other peers and channels that will be connected to it. The default configuration installed with Asterisk when you compiled it allows for several interesting demonstrations of its capabilities using a SIP phone. (They can also be tried using an analog phone, which we'll cover later.)
188.8.131.52 Listen to the Asterisk automated greeting using an IP phone
In its default configuration, Asterisk has an autoattendant that can route calls using an automated attendant. To try it out, take the IP phone off hook and dial 2. Then dial Send. You will hear a friendly voice saying, "Asterisk is an open source, fully featured PBX and IVR platform..."
184.108.40.206 Listen to a voice over Internet greeting
While listening to the automated attendant greeting, dial 500. This will cause the Asterisk server to greet you; connect you to a server at Digium, Inc., using the Internet; and allow you to listen to another automated greetingthe one being played back by a production Asterisk PBX at Digium's office. This connection does not use the PSTN at all, but rather a Voice over IP "trunk" that is set up on the fly by Asterisk.
The connection to Digium is established using IAX, not SIP. So the Asterisk server is managing two different kinds of channels simultaneously in order to facilitate this call. Listen to the sound quality. Do you notice any difference between the quality of the autoattendant on your Asterisk server and the one on Digium's? The difference in quality should be negligible, if even noticeable, especially over a fast Internet connection.
You can also perform an echo test by dialing 600 and accessing Asterisk's built-in voice mail service by dialing 8500. These are covered in greater detail later.
3.3.9. Installing Mpg123
The application responsible for providing music and messages for holding callers is called Mpg123, but don't confuse it with the Mpg321 application that ships with Red Hat Linux. Mpg321 doesn't work with Asterisk, so you must replace it with Mpg123.
To do this, start by shutting down the Asterisk server process if it's running. Then, make sure there are no Mpg321 or Mpg123 processes running:
# ps ax grep mpg123 900 std S+ 0:00.00 mpg123 # kill 900 # ps ax grep mpg321 1024 std S+ 0:00.00 mpg321 # kill 1024
You may not actually have both applications running, or even installed, but it's best to make sure neither is running before you proceed.
By default, Red Hat has symbolic links for the Mpg321 package that make it appear synonymously with Mpg123. These must be removed in order to install the correct package:
# rm /usr/bin/mpg123 # rm /usr/local/bin/mpg123
Next, download a Red Hat Linux-compatible build (RPM package) of Mpg123 from http://www.mpg123.de and install it with a command similar to this one, called from the directory where the downloaded file is saved:
# rpm -iv mpg123-0.59r-1.i386.rpm
Along with Mpg123, Asterisk uses the configuration file called /etc/asterisk/musiconhold.conf to define various "classes" of music-on-hold . Each class can be used in different situations or contexts depending on how the Asterisk administrator opts to handle each hold scenario. Mpg123 isn't required to deliver prerecorded sounds; Asterisk can do that on its own using files in the GSM-encoded format (and other telephony codec formats). What Mpg123 does is allow MP3 files to be played back for holding callers to listen to while they wait. On-hold music is covered in detail in Chapters 12 and 17.