Chapter 13. Managing Your Asterisk System

It won’t be covered in the book. The source code has to be useful for something, after all.

Larry Wall

While there is a cornucopia of creative things that you are going to want to do with your spanking-new Asterisk system, there are also some basic, unglamorous, dare we say, boring things that need to be discussed.

Call Detail Recording

Without even being told, Asterisk assumes that you want to store CDR information.[139]

By default, Asterisk will create a CSV file and place it in the folder /var/log/asterisk/cdr-csv/.[140] To the naked eye, this file looks like a bit of a mess. If, however, you separate each line according to the commas, you will find that each line contains information about a particular call, and that the commas separate the following values:

accountcode

Assigned if configured for the channel in the channel configuration file (i.e., sip.conf). The account code is assigned on a per-channel basis. You can also change this value from the dialplan by setting CDR(accountcode).

src

Received Caller ID (string, 80 characters).

dst

Destination extension.

dcontext

Destination context.

clid

Caller ID with text (80 characters).

channel

Channel used (80 characters).

dstchannel

Destination channel, if appropriate (80 characters).

lastapp

Last application, if appropriate (80 characters).

lastdata

Last application data (arguments, 80 characters).

start

Start of call (date/time).

answer

Answer of call (date/time).

end

End of call (date/time).

duration

Total time in system, in seconds (integer), from dial to hangup.

billsec

Total time call is up, in seconds (integer), from answer to hangup.

disposition

What happened to the call (ANSWERED, NO ANSWER, BUSY).

amaflags

What flags to use (DOCUMENTATION, BILL, IGNORE, etc.), specified on a per-channel basis, like accountcode. AMA flags stand for Automated Message Accounting flags, which are somewhat standard (supposedly) in the industry.

userfield

A user-defined field, maximum 255 characters.

Managing Logs

Asterisk activity generates events that will cause the creation of an entry in either the main system logs, or in Asterisk’s own logfiles. On a busy system (or a system that is experiencing a severe problem), these logfiles can grow very large, very quickly. If debugging is turned on, the processes involved in writing to these logfiles can begin to have an effect on system performance. By default, Asterisk will simply add to the files until the hard drive is full. Fortunately, Linux provides utilities to handle the rotation of logfiles (so that no single file becomes too large), and also the deletion of older logfiles (which will prevent the system from getting clogged with logfiles).

The logrotate utility is normally run once per day by the operating system. Unfortunately, since there is no script installed to instruct logrotate on how to handle Asterisk, its logfiles will grow unchecked until a rotate script is added to handle them. In order to make that happen, we need to set up parameters for Asterisk in a file in the /etc/logrotate.d directory. This file will need to rotate the current logfile, and then send Asterisk instructions to rotate its own logger (causing it to stop using the now old logfile, and generate a new file).

Create a new file /etc/logrotate.d/asterisk and place the following lines in it:

/var/log/asterisk/* /var/log/asterisk/cdr-csv {
missingok
sharedscripts
monthly
rotate 12
postrotate
    asterisk -rx "logger reload" > /dev/null 2> /dev/null
endscript
}

This file tells the logrotate utility to rotate the Asterisk logs every month, save 12 months worth of logs, and then tell Asterisk that the logfiles have been rotated (which will cause Asterisk to create new logfiles and begin writing to them). We selected these values arbitrarily. Feel free to adjust them to suit your needs.

Running Asterisk As a Non-root User

By default, Asterisk runs as the root user, and while we don’t have any hard data, our own experiences lead us to conclude that the vast majority of Asterisk systems are run in this default state. From a security perspective, this represents an unacceptable risk―strangely, one which most of us seem willing to take.

Running Asterisk as non-root is not terribly hard to achieve, but it requires a few extra steps, and debugging it can be frustrating if you do not understand how Linux permissions work. However, from a security perspective it is well worth the effort.

We’re going to run Asterisk as the user asterisk, so we need to create that user on our system first. The following commands will be run as root. We’ll tell you when to switch and use the asterisk user that we’re about to create:

# adduser -c "Asterisk PBX" asterisk
#passwd asterisk

Now that you’ve created the asterisk user, let’s switch to that user, with which we’ll perform the rest of the commands. Once we su to the asterisk user,[141] we can download a copy of Asterisk via SVN, FTP or WGET, and then compile and install. We’re going to grab a copy of Asterisk from the SVN repository in the following example.

Note

1.4.5 is the current release version at the time of this writing, but it won’t be by the time you read this, so check the Asterisk web site for the latest version. In other words, don’t just type 1.4.5 whenever you see us refer to it. Find out what is current and use that instead.

# su - asterisk
$ svn co http://svn.digium.com/svn/asterisk/tags/1.4.5 asterisk-1.4.5
$ cd asterisk-1.4.5
$ ./configure --prefix=$HOME/asterisk-bin --sysconfdir=$HOME/asterisk-bin 
  --localstatedir=$HOME/asterisk-bin
$ make menuselect
$make install

When running the ./configure script with the --prefix flag, we’re telling the system to install the binary components into our $HOME[142] directory under the subdirectory called asterisk-bin. The --sysconfdir flag tells the system where to place the configuration files, and --localstatedir tells the system where to install additional files, such as sounds. The key here is that since we are downloading, compiling, and installing as the user asterisk, everything that only gets created will be assigned to that user, and have the permissions granted to that user.

We can now install the sample files as well into the $HOME/asterisk-bin/asterisk directory:

$ make samples

Test starting up Asterisk with the following command:

$ ./asterisk-bin/sbin/asterisk -cvvv

Normally, Asterisk needs to be run as a service. During installation, the make config command will install the init scripts. Unfortunately, this will not work when you are logged in as the user asterisk, because only the root user has the authority to make changes to system startup commands. It would appear that what we need to do is log in as root, navigate to the /home/asterisk/asterisk-1.4.5 folder, and run the make config command again (now with the authority to really make it happen). Problem solved, right?

Yes, but not quite. If you run the service asterisk start command, you will find that it complains that it cannot find asterisk. Know why? Because the init script figures the asterisk executable got installed in /usr/sbin, where it would be if we had installed asterisk as root. So, we need to tell the init script where to find asterisk and the safe_asterisk script, like this:

# ln -s /home/asterisk/asterisk-bin/sbin/asterisk /usr/sbin/asterisk
#ln -s /home/asterisk/asterisk-bin/sbin/safe_asterisk /usr/sbin/safe_asterisk

Since the init script utilizes the safe_asterisk script, and by default wants to start Asterisk as the root user, we have to modify the safe_asterisk script telling it to run Asterisk as our non-root user. So open up the safe_asterisk script with your favorite text editor and look for the ASTARGS variable (around line 78). Then add -U asterisk between the quotes like so:

#
# Don't fork when running "safely"
#
ASTARGS="-U asterisk"

Go ahead and start Asterisk by running service asterisk start and verify Asterisk is running as the asterisk user using the ps command:

# service asterisk start
# ps aux | grep asterisk

503      30659  0.0  1.8  26036  8692 pts/2    Sl   15:07   0:00 
/home/asterisk/asterisk-bin/sbin/asterisk -U asterisk -vvvg -c

The 503 is actually our asterisk user, which we verify by looking at the /etc/passwd file:

# cat /etc/passwd

asterisk:x:503:503:Asterisk PBX:/home/asterisk:/bin/bash

Reboot the system to ensure that everything comes up as required. Keep in mind that a lot of things that you do with Asterisk might assume that you are running as root, so keep an eye out for errors that relate to a lack of permission. Your Asterisk process may think it is the superuser, but we have clipped its wings somewhat.

Why go through the trouble? The advantage of this is simply that if any security vulnerability in Asterisk[143] allows someone to access the box through the Asterisk account, he will be limited to system activities allowed by that account. When Asterisk is run as root, a security compromise gives the intruder full control of your system.

Customizing System Prompts

In keeping with the seemingly limitless flexibility of Asterisk, you can also modify the system prompts. This is very simple to explain, but generally difficult to do well.

With more than 300 system prompts in the main distribution, and an additional 600 in the asterisk-sounds add-on, if you’re contemplating customizing all of them you’d better have either a lot of money or a lot of time on your hands.

An audio engineer is also recommended to ensure that the recordings are normalized to –3 dB and that all prompts start and end at a zero-crossing point (with just the right amount of silence prepended and appended).

Once you have the recordings, the actual implementation is easy—simply replace the files in /var/lib/asterisk/sounds with the ones you have created.

Alternatively, you can opt to record your own prompts and place them in a folder of your choosing. When you refer to sound files with the Playback() or Background() applications, you can refer to the full pathname of the sound file, or to any subdirectory of /var/lib/asterisk/sounds/.

Note that the default sounds that come with Asterisk are delivered in GSM format. We would not normally recommend storing them in this format (unless you have a lot of channels that will be entering the system using the GSM codec). Sure, you save some hard drive space, but the extra load on your CPU when it has to transcode all these files (not to mention the lower overall quality of the sound) makes the use of GSM undesirable, to our thinking. Use uncompressed files (such as .wav, .ulaw or .alaw) and your CPU will not have to work as hard. As an added bonus, your prompts will sound better.

Music on Hold

Any popular PBX system offers the ability to supply a source of music to be played for callers while on hold. Asterisk allows for a lot of creativity in this regard.

Nowadays, everyone is familiar with the MP3 music format, and there is a lot of interest in using MP3s as a music-on-hold source. The concept sure seems like a good idea, but there are a few things that we think should be given some consideration:

  • MP3 files are extremely complex, and require a substantial amount of CPU to decode. If you have a lot of channels pulling music from the system (for example, people sometimes like to listen to music through their phone, or a call center may have several callers on hold), the load on the CPU caused by all of the transcoding of the stored MP3 files could place too much demand on a machine that is otherwise suitable to the performance needs of the system.

  • Current-generation hard drives hold a lot of data, so there may not be any reason to worry about cutting down hard drive use. Compressed audio makes sense from a distribution standpoint (an MP3 is a much smaller download than the equivalent in .wav format), but once on your system, do we really care how much space they take up?

  • MP3 files don’t usually come with the right sort of licensing. ;-)

Taking all of this into consideration, we recommend that you convert your music sources into the native format of the various codecs you may be supporting. For example, if you support μlaw for your internal phones, and G.729 on your VoIP circuits, you will want to store your music in both formats so that Asterisk will not have to perform transcoding to play music to calls on those channels.

We often use public domain music (or Creative Commons licensed music) on our systems. Creative Commons music often comes in ogg-Vorbis format (which is conceptually similar to MP3, but not compatible). In order to play .ogg or .mp3 files on our Asterisk system, we are going to convert them to a format that Asterisk can easily handle. This requires the following steps:

  1. We need to make sure that SoX, the Sound eXchange utility, is installed. If not, run the following command to install it:

    $ yum install sox
  2. Download the music that you have chosen to a working folder on your system (/tmp is probably a suitable location). As an example, the following command downloaded some nice piano music by Pachelbel for us:

    $ wget http://upload.wikimedia.org/wikipedia/commons/6/62/Pachelbel%27s_Canon.ogg
  3. Now we have to convert the song from ogg-Vorbis format to a format more suitable to Asterisk:

    $ sox Pachelbel\'s_Canon.ogg -r 8000 -c 1 -s -w moh1.wav resample -ql

    Tip

    You may also need to adjust the amplitude with the -v option.

    We’ve now taken our source file, converted it to a .wav file suitable to Asterisk,[146] and saved the resulting file as moh1.wav.

  4. Almost done now. We just need to create a folder for the permanent home of the new files (/tmp is certainly no place for them):

    $ mkdir /var/lib/asterisk/mohwav

    and then move them there:

    $ mv *.wav /var/lib/asterisk/mohwav
  5. Since we have placed our music files in a different folder from that where Asterisk installs its sample music, we will need to change the configuration file to reflect this. Edit your /etc/asterisk/musiconhold.conf file with one that contains the following:

    [default]
    mode=files
    directory=/var/lib/asterisk/mohwav
    random=yes

As for what to play, that will depend on what image you want to project to your callers. Regardless of your choice, you should keep some things in mind:

  • People don’t actually want to be on hold, so they are not usually planning to be there for long. This means that there is not much point in providing them with a mind-expanding musical experience. If things go as they hope, they won’t be there long enough to get into it.

  • The fidelity on a phone system does not allow for accurate reproduction of tones. Heavy bass generally sounds terrible, and high frequencies will typically just end up as noise. Keep the music simple, and it is more likely to sound good.

  • Musical tastes are as varied as people, and while it might be nice to try and cover a wide range of styles, music that is too eclectic is more likely to annoy than enlighten.

Classical music addresses all of the above criteria, and it is easy to obtain. It also sounds classy (go figure!), so it is a pretty safe choice, although we’ll admit it doesn’t usually score any points in the hipness department.

Asterisk includes three songs with the source code download that are licensed for use with Asterisk. These songs are intended as samples. Since there are only three of them, people who call you regularly will quickly tire of them. We have a recurring nightmare in which the worldwide success of Asterisk means that the human race is forced to listen to the same three songs as music on hold. That is why we wrote this section for you.

Conclusion

This chapter could easily become a book (and possibly will one day). We have chosen a few topics to cover that we think will provide value to most readers, but there are certainly many more topics that can be discussed. As with so many things in this book, we have merely scratched the surface.



[139] If you are wondering why such an obviously simple thing seems to be such an achievement, the reason is simply that many traditional PBXes do not have this capability built in. With those systems, you have to purchase some sort of third-party appliance even just to capture the raw call data. Asterisk simply stores it. No drama. No cost. No kidding.

[140] A Comma Separated Values (CSV) file is a common method of formatting database-type information in a text file. You can open CSV files with a text editor, but most spreadsheet and database programs will also read them and properly parse them into rows and columns.

[141] su historically means super-user, but nowadays it could also mean switch-user or substitute-user. The - in the command tells su to use the environment for that user (for example to use the PATH for that user)

[142] $HOME is a system variable that defines the path to the home directory for the current user, i.e., /home/asterisk.

[143] If you walk up to any system that’s running Asterisk, hook a keyboard and screen up to it, and press Alt-F9; you will be connected to the Asterisk CLI. Press ! and hit Return, and you will have a shell. If Asterisk is running as root, you now own that system.

[144] We were going to say “accentless English”, but then we’d have to apologize to folks from the British Isles, Australia, South Africa, and who knows where else. We are not experts in languages, dialects, and such, but our ears tell us that there is a type of accent that in North America is common for professional voices. This is the accent that is common to the Pacific coast from San Diego to Seattle, and most of English-speaking Canada as well. Both June and Allison deliver English prompts in this accent, and we think it sounds great.

[145] Seed a search with the term “Creative Commons music” to find more freely usable music.

[146] Note that we could have used any format that was compatible with Asterisk; we’ve just chosen .wav for this example because it is easy for the CPU to transcode into μlaw/alaw/slin on the fly, yet remains easy to work with in other environments.

Get Asterisk: The Future of Telephony, 2nd Edition now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.