Section 3.4. Monitoring Asterisk

3.4. Monitoring Asterisk

There are several ways to monitor Asterisk. Most notably, the Asterisk CLI console application ( asterisk -r ) offers a real-time console log. When you launched Asterisk with the -v option, this was enabled. The more v 's, the more detail goes into the console log. The same is true of the logfiles that Asterisk puts out.

3.4.1.1 Asterisk's logfiles

In addition to standard output and standard error, which you can redirect using the shell, Asterisk has some important logfiles. They are stored in /var/log/asterisk by default. If you want them to be stored elsewhere, edit /etc/asterisk.conf as such. The three ASCII logfiles enabled upon installation are:

event_log

Stores Asterisk system events, when triggered according to the Asterisk configuration

messages

Stores debugging, error, and warning messages generated by most Asterisk modules

cdr-csv

Stores the Call Detail Record, or CDR, which records the channels, actions, and durations of each call placed through the softPBX

Chapter 10 covers Asterisk's logfiles in much greater detail.

3.4.1.2 Astman

The Asterisk Manager is a text-based socket API that allows management applications to monitor and control the Asterisk server. One such application is Astman, which is included in the Asterisk distribution. Astman allows you to watch a list of calls in progress and allows you to redirect calls and disconnect them.

Before you can use Astman, though, you need to make sure Asterisk's Management API is running, by way of the /etc/asterisk/manager.conf config file. Here's a sample:

 ;     ; Sample astman config     ;     [general]     enabled = yes     port = 5038     bindaddr = 0.0.0.0     [ted]     secret = hansolo     allow = 0.0.0.0/0.0.0.0     read = system,call,log,verbose,command,agent     write = system,call,log,verbose,command,agent 

This sample config starts the Asterisk Manager listening on TCP port 5038, and allows all hosts ( allow=0.0.0.0 . . . ) to connect. If your Asterisk server is accessible from the Internet or untrusted hosts, you'll want to make the allow directive more strict. The user called "ted" will be authenticated by the password "hansolo" and his administrative permissions are described by the read and write directives. You could set up other users with different credentials.

manager.conf 's settings are for the Asterisk Manager API, not just the Astman program. Other applications that you use with the API will be subject to these settings, too.

Once you've set up your manager.conf file, restart Asterisk and issue this command on the Asterisk server:

 astman localhost 

Log into Astman using the username and password you established in the manager.conf file (see Figure 3-5).

Figure 3-5. The Astman login prompt

3.4.1.3 Channels

Once you log in to Astman, you are shown a channel list. Channels are logical pathways for voice connections at the application layer, just as TCP and UDP provide logical pathways for data transfer and the transport layer. Whenever an endpoint contacts the Asterisk server, a channel is established that remains open for the duration of the connection. If one endpoint calls another endpoint via the Asterisk softPBX, two channels are establishedone to each endpoint. If one endpoint calls another endpoint that is hosted by a completely separate Asterisk server, two channels on each server are established, meaning that, between the two servers, it required four channels to connect a single call. Astman can monitor the channels on only a single Asterisk server, though.

Proprietary IP telephony environments work similarly. Cisco, Avaya, and Nortel softPBXs handle logical voice channels, but none really states it as such in their management applications.

There is one line for each voice channel currently in use on the Asterisk server. In Figure 3-6, you can see that there is a call in progress to extension 500 using SIP, and an outbound call to a VoIP peer on the Internet using the IAX (Inter-Asterisk Exchange) protocol. In fact, the screen grab in Figure 3-6 was taken during the Internet-based VoIP demonstration outlined in Project 3.1.

Figure 3-6. Astman's channel list

Most IP PBX vendors provide an application similar to Astman. Avaya's CallStatus, shown in Figure 3-7, is an administrator application that shows activity on Avaya's small-office softPBX (called IP Office), similar to Astman's function with Asterisk. Every call that is currently active on the Avaya system, whether placed by an inside user or received from the PSTN, is shown on CallStatus. Astman functions the same way, although it provides less detail about each call and has one channel per line rather than one call per line.

Figure 3-7. Avaya's proprietary CallStatus application is more advanced than Astmanbut works only with Avaya's PBX

If you want to develop a more advanced version of Astman or create your own management or CTI (computer-telephony integration) applications, then the Asterisk Management API is the way to go. It's a text-based protocol that provides you with the ability to monitor the system, direct calls in progress, originate calls, and add or remove extensions.

The API can be used in conjunction with other applications to automate telephony functions. One example would be an attendant console application that somebody in a front-desk receptionist role could use to direct a call center. Another might be an autodialer for a personal information management application like Microsoft Outlook or Lotus Notes. It's also possible to link web-based applications with Asterisk using the Management API, so you could create an HTML frontend for a voice chat system or create a web-based answering machine.

The Management API has a number of quirks that are identified in Digium's bug-tracking system located at http:// bugs .digium.com. It would be a good idea to review the information here before embarking on any ambitious API projects. Refer to the appendixes for a list of Management API commands.