As the name suggests, the cdr_adaptive_odbc module allows CDRs to be stored in a database through ODBC. The “adaptive” part of the name refers to the fact that it works to adapt to the table structure: there is no static table structure that must be used with this module. When the module is loaded (or reloaded), it reads the table structure. When logging CDRs, it looks for a CDR variable that matches each column name. This applies to both the built-in CDR variables and custom variables. If you want to log the built-in channel CDR variable, just create a column called channel.

Adding custom CDR content is as simple as setting it in the dialplan. For example, if we wanted to log the User-Agent that is provided by a SIP device, we could add that as a custom CDR variable:

exten => 105,n,Set(CDR(useragent)=${CHANNEL(useragent)})

To have this custom CDR variable inserted into the database by cdr_adaptive_odbc, all we have to do is create a column called useragent.

Multiple tables may be configured in the cdr_adaptive_odbc configuration file. Each goes into its own configuration section. The name of the section can be anything; the module does not use it. Here is an example of a simple table configuration:

[mytable]

connection = asterisk
table = asterisk_cdr

A more detailed example of setting up a database for logging CDRs can be found in Storing Call Detail Records (CDRs).

Table 24-4 lists the options that can be specified in a table configuration section in the cdr_adaptive_odbc.conf file.

In addition to the key/value pair fields that are shown in the previous table, cdr_adaptive_odbc.conf allows for a few other configuration items. The first is a column alias. Normally, CDR variables are logged to columns of the same name. An alias allows the variable name to be mapped to a column with a different name. The syntax is:

alias <CDR variable> => <column name>

Here is an example column mapping using the alias option:

alias src => source

It is also possible to specify a content filter. This allows you to specify criteria that must match for records to be inserted into the table. The syntax is:

filter <CDR variable> => <content>

Here is an example content filter:

filter accountcode => 123

Finally, cdr_adaptive_odbc.conf allows static content for a column to be defined. This can be useful when used along with a set of filters. This static content can help differentiate records that were inserted into the same table by different configuration sections. The syntax for static content is:

static <"Static Content Goes Here"> => <column name>

Here is an example of specifying static content to be inserted with CDRs:

static "My Content" => my_identifier

The cdr_csv module is a very simple CDR backend that logs CDRs into a CSV (comma separated values) file. The file is /var/log/asterisk/cdr-csv/Master.csv. As long as CDR logging is enabled in cdr.conf and this module has been loaded, CDRs will be logged to the Master.csv file.

While no options are required to get this module working, there are some options that customize its behavior. These options, listed in Table 24-5, are placed in the [csv] section of cdr.conf.

The order of CDR variables in CSV files created by the cdr_csv module is:

<accountcode>,<src>,<dst>,<dcontext>,<clid>,<channel>,<dstchannel>,<lastapp>, 
    <lastadata>,<start>,<answer>,<end>,<duration>,<billsec>,<disposition>, 
    <amaflags>[,<uniqueid>][,<userfield>]

This CDR backend allows for custom formatting of CDR records in a log file. This module is most commonly used for customized CSV output. The configuration file used for this module is /etc/asterisk/cdr_custom.conf. A single section called [mappings] should exist in this file. The [mappings] section contains mappings between a filename and the custom template for a CDR. The template is specified using Asterisk dialplan functions.

The following example shows a sample configuration for cdr_custom that enables a single CDR log file, Master.csv. This file will be created as /var/log/asterisk/cdr-custom/Master.csv. The template that has been defined uses both the CDR() and CSV_QUOTE() dialplan functions. The CDR() function retrieves values from the CDR being logged. The CSV_QUOTE() function ensures that the values are properly escaped for the CSV file format:

[mappings]

Master.csv => ${CSV_QUOTE(${CDR(clid)})},${CSV_QUOTE(${CDR(src)})},
   ${CSV_QUOTE(${CDR(dst)})},${CSV_QUOTE(${CDR(dcontext)})},
   ${CSV_QUOTE(${CDR(channel)})},${CSV_QUOTE(${CDR(dstchannel)})},
   ${CSV_QUOTE(${CDR(lastapp)})},${CSV_QUOTE(${CDR(lastdata)})},
   ${CSV_QUOTE(${CDR(start)})},${CSV_QUOTE(${CDR(answer)})},
   ${CSV_QUOTE(${CDR(end)})},${CSV_QUOTE(${CDR(duration)})},
   ${CSV_QUOTE(${CDR(billsec)})},${CSV_QUOTE(${CDR(disposition)})},
   ${CSV_QUOTE(${CDR(amaflags)})},${CSV_QUOTE(${CDR(accountcode)})},
   ${CSV_QUOTE(${CDR(uniqueid)})},${CSV_QUOTE(${CDR(userfield)})}

The cdr_manager backend emits CDRs as events on the Asterisk Manager Interface (AMI), which we discussed in detail in Chapter 20. This module is configured in the /etc/asterisk/cdr_manager.conf file. The first section in this file is the [general] section, which contains a single option to enable this module (the default value is no):

[general]

enabled = yes

The other section in cdr_manager.conf is the [mappings] section. This allows for adding custom CDR variables to the manager event. The syntax is:

<CDR variable> => <Header name>

Here is an example of adding two custom CDR variables:

[mappings]

rate => Rate
carrier => Carrier

With this configuration in place, CDR records will appear as events on the manager interface. To generate an example manager event, we will use the following dialplan example:

exten => 110,1,Answer()
    same => n,Set(CDR(rate)=0.02)
    same => n,Set(CDR(carrier)=BS&S)
    same => n,Hangup()

This is the command used to execute this extension and generate a sample manager event:

*CLI> console dial 110@testing

Finally, this is an example manager event produced as a result of this test call:

Event: Cdr
Privilege: cdr,all
AccountCode: 
Source: 
Destination: 110
DestinationContext: testing
CallerID: 
Channel: Console/dsp
DestinationChannel: 
LastApplication: Hangup
LastData: 
StartTime: 2010-08-23 08:27:21
AnswerTime: 2010-08-23 08:27:21
EndTime: 2010-08-23 08:27:21
Duration: 0
BillableSeconds: 0
Disposition: ANSWERED
AMAFlags: DOCUMENTATION
UniqueID: 1282570041.3
UserField: 
Rate: 0.02
Carrier: BS&S

This module allows posting of CDRs to a MySQL database. We recommend that new installations use cdr_adaptive_odbc instead.

This module enables the legacy ODBC interface for CDR logging. New installations should use cdr_adaptive_odbc instead.

This module allows posting of CDRs to a PostgreSQL database. We recommend that new installations use cdr_adaptive_odbc instead.

The cdr_radius backend allows posting of CDRs to a RADIUS server. When using this module, each CDR is reported to the RADIUS server as a single stop event. This module is configured in the /etc/asterisk/cdr.conf file. Options for this module are placed in a section called [radius]. The available options are listed in Table 24-6.

This module allows posting of CDRs to a SQLite database using SQLite version 2. Unless you have a specific need for SQLite version 2 as opposed to version 3, we recommend that all new installations use cdr_sqlite3_custom.

This module requires no configuration to work. If the module has been compiled and loaded into Asterisk, it will insert CDRs into a table called cdr in a database located at /var/log/asterisk/cdr.db.

This CDR backend inserts CDRs into a SQLite database using SQLite version 3. The database created by this module lives at /var/log/asterisk/master.db. This module requires a configuration file, /etc/asterisk/cdr_sqlite3_custom.conf. The configuration file identifies the table name, as well as customizes which CDR variables will be inserted into the database:

[master]

table = cdr

;
; List the column names to use when inserting CDRs.
;
columns => calldate, clid, dcontext, channel, dstchannel, lastapp, lastdata,
    duration, billsec, disposition, amaflags, accountcode, uniqueid, userfield, 
    test


;
; Map CDR contents to the previously specified columns.
;
values => '${CDR(start)}','${CDR(clid)}','${CDR(dcontext)}','${CDR(channel)}',
    '${CDR(dstchannel)}','${CDR(lastapp)}','${CDR(lastdata)}','${CDR(duration)}',
    '${CDR(billsec)}','${CDR(disposition)}','${CDR(amaflags)}',
    '${CDR(accountcode)}','${CDR(uniqueid)}','${CDR(userfield)}','${CDR(test)}'

This module allows logging of CDRs using syslog. To enable this, first add an entry to the system’s syslog configuration file, /etc/syslog.conf. For example:

local4.*      /var/log/asterisk/asterisk-cdr.log

The Asterisk module has a configuration file, as well. Add the following section to /etc/asterisk/cdr_syslog.conf:

[cdr]

facility = local4
priority = info
template = "We received a call from ${CDR(src)}"

Here is an example syslog entry using this configuration:

$ cat /var/log/asterisk/asterisk-cdr.log

Aug 12 19:17:36 pbx cdr: "We received a call from 2565551212"

The cdr_tds module uses the FreeTDS library to post CDRs to a Microsoft SQL Server or Sybase database. It is possible to use FreeTDS with unixODBC, so we recommend using cdr_adaptive_odbc instead of this module.

In this example, we’ll show what a CDR looks like for a simple one-party call. Specifically, we will use the example of a user calling in to check her voicemail. Here is the extension from /etc/asterisk/extensions.conf:

exten => *98,1,VoiceMailMain(@${GLOBAL(VOICEMAIL_CONTEXT)})

This is the CDR from /var/log/asterisk/cdr-custom/Master.csv that was created as a result of calling this extension:

"""Console"" <2565551212>","2565551212","*98","UserServices","Console/dsp","",
    "VoiceMailMain","@shifteight.org","2010-08-16 01:08:44","2010-08-16 01:08:44",
    "2010-08-16 01:08:53","9","9","ANSWERED","DOCUMENTATION","","1281935324.0","",0

For this next example, we show what a CDR looks like for a simple two-party call. We’ll have one SIP phone place a call to another SIP phone. The call is answered and then hung up after a short period of time. Here is the extension that was dialed:

exten => 101,1,Dial(SIP/0000FFFF0002)

Here is the CDR that was logged to Master.csv as a result of this call:

"""Console"" <2565551212>","2565551212","101","LocalSets","Console/dsp",
    "SIP/0000FFFF0002-00000000","Dial","SIP/0000FFFF0002","2010-08-16 01:16:10",
    "2010-08-16 01:16:16","2010-08-16 01:16:29","19","13","ANSWERED",
    "DOCUMENTATION","","1281935770.2","",2

The cel_odbc.so module provides the ability to log CEL events to a database using ODBC. This module is not quite as adaptive as the CDR adaptive ODBC backend. For CEL events, there are no custom variables. However, this module will still adapt to the structure of the database, in that it will log the fields of CEL events for which there are corresponding columns and will not produce an error if there is not a column for every field. The configuration for this module goes in /etc/asterisk/cel_odbc.conf.

Multiple tables may be configured in the cel_odbc configuration file. Each goes into its own configuration section. The name of the section can be anything; the module does not use it. Here is an example of a simple table configuration:

[mytable]

connection = asterisk
table = asterisk_cel

The cel_odbc module will use the following columns, if they exist (see the table following this list for a set of mappings between event types and their integer value that will be inserted into the database):

Table 24-11 shows the mapping between event types and their integer values that will be inserted into the eventtype column of the database.

Table 24-12 shows the options that can be specified in a table configuration section in the cel_odbc.conf file.

In addition to the key/value pair fields that are shown in the previous table, cel_odbc.conf allows for a few other configuration items. The first is a column alias. Normally, CEL fields are logged to columns of the same name. An alias allows the variable name to be mapped to a column with a different name. The syntax is:

alias <CEL field> => <column name>

Here is an example column mapping using the alias option:

alias exten => extension

It is also possible to specify a content filter. This allows you to specify criteria that must match for records to be inserted into the table. The syntax is:

filter <CEL field> => <content>

Here is an example content filter:

filter appname => Dial

Finally, cel_odbc.conf allows static content to be specified for a column. This can be useful when used along with a set of filters. This static content can help differentiate records that were inserted into the same table by different configuration sections. The syntax for static content is:

static <"Static Content Goes Here"> => <column name>

Here is an example of specifying static content to be inserted with a CEL event:

static "My Content" => my_identifier

This CEL backend allows for custom formatting of CEL events in a log file. It is most commonly used for customized CSV output. The configuration file used for this module is /etc/asterisk/cel_custom.conf. A single section called [mappings] should exist in this file. This section contains mappings between filenames and the custom templates for CEL events. The templates are specified using Asterisk dialplan functions and a few special CEL variables.

The following example shows a sample configuration for cel_custom that enables a single CEL log file, Master.csv. This file will be created as /var/log/asterisk/cel-custom/Master.csv. The template that has been defined uses the CHANNEL(), CALLERID(), and CSV_QUOTE() dialplan functions. The CSV_QUOTE() function ensures that the values are properly escaped for the CSV file format. This example also references some special CEL variables, which are listed in Table 24-13.

Here is the example /etc/asterisk/cel_custom.conf file:

[mappings]

Master.csv => ${CSV_QUOTE(${eventtype})},${CSV_QUOTE(${eventtime})},
    ${CSV_QUOTE(${CALLERID(name)})},${CSV_QUOTE(${CALLERID(num)})},
    ${CSV_QUOTE(${CALLERID(ANI)})},${CSV_QUOTE(${CALLERID(RDNIS)})},
    ${CSV_QUOTE(${CALLERID(DNID)})},${CSV_QUOTE(${CHANNEL(exten)})},
    ${CSV_QUOTE(${CHANNEL(context)})},${CSV_QUOTE(${CHANNEL(channame)})},
    ${CSV_QUOTE(${CHANNEL(appname)})},${CSV_QUOTE(${CHANNEL(appdata)})},
    ${CSV_QUOTE(${CHANNEL(amaflags)})},${CSV_QUOTE(${CHANNEL(accountcode)})},
    ${CSV_QUOTE(${CHANNEL(uniqueid)})},${CSV_QUOTE(${CHANNEL(linkedid)})},
    ${CSV_QUOTE(${CHANNEL(peer)})},${CSV_QUOTE(${CHANNEL(userfield)})},
    ${CSV_QUOTE(${eventextra})}

The cel_manager backend emits CEL events on the Asterisk Manager Interface (we discussed the AMI in detail in Chapter 20). This module is configured in the /etc/asterisk/cel.conf file. This file should contain a single section called [manager], which contains a single option to enable this module. The default value is no, but you can enable it as follows:

[manager]

enabled = yes

With this configuration in place, CEL events will appear as events on the manager interface. To generate example manager events, we will use the following dialplan example:

exten => 111,1,Answer()
    same => n,CELGenUserEvent(Custom Event,Whiskey Tango Foxtrot)
    same => n,Hangup()

This is the command used to execute this extension and generate sample CEL events:

*CLI> console dial 111@testing

Finally, this is one of the example manager events produced as a result of this test call:

Event: CEL
Privilege: call,all
EventName: CHAN_START
AccountCode: 
CallerIDnum: 
CallerIDname: 
CallerIDani: 
CallerIDrdnis: 
CallerIDdnid: 
Exten: 111
Context: testing
Channel: Console/dsp
Application: 
AppData: 
EventTime: 2010-08-23 08:14:51
AMAFlags: NONE
UniqueID: 1282569291.1
LinkedID: 1282569291.1
Userfield: 
Peer: 

This module allows posting of CEL events to a PostgreSQL database. We recommend that new installations use cel_odbc instead.

The cel_radius backend allows posting of CEL events to a RADIUS server. When using this module, each CEL event is reported to the RADIUS server as a single stop event. This module is configured in the /etc/asterisk/cel.conf file. The options for this module, listed in Table 24-14, are placed in a section called [radius].

This CEL backend inserts CEL events into a SQLite database using SQLite version 3. The database created by this module lives at /var/log/asterisk/master.db. The configuration file for this module, /etc/asterisk/cel_sqlite3_custom.conf, identifies the table name, as well as customizes which CEL variables will be inserted into the database. It looks like this:

[master]

table = cel

;
; List the column names to use when inserting CEL events.
;
columns => eventtype, eventtime, cidname, cidnum, cidani, cidrdnis, ciddnid,
    context, exten, channame, appname, appdata, amaflags, accountcode, uniqueid,
    userfield, peer

;
; Map CEL event contents to the previously specified columns.
;
values => '${eventtype}','${eventtime}','${CALLERID(name)}','${CALLERID(num)}',
    '${CALLERID(ANI)}','${CALLERID(RDNIS)}','${CALLERID(DNID)}',
    '${CHANNEL(context)}','${CHANNEL(exten)}','${CHANNEL(channame)}',
    '${CHANNEL(appname)}','${CHANNEL(appdata)}','${CHANNEL(amaflags)}',
    '${CHANNEL(accountcode)}','${CHANNEL(uniqueid)}','${CHANNEL(userfield)}',
    '${CHANNEL(peer)}'

The cel_tds module uses the FreeTDS library to post CEL events to a Microsoft SQL Server or Sybase database. It is possible to use FreeTDS with unixODBC, so we recommend using cel_odbc instead of this module.

In this example, a single phone calls into an extension that plays back a prompt that says “Hello World.” This is the dialplan:

exten => 200,1,Answer()
    same => n,Playback(hello-world)
    same => n,Hangup()

Here are the CEL events that are logged as a result of making this call:

"CHAN_START","1282062437.436130","Julie Bryant","12565553333","","","","200",
   "LocalSets","SIP/0000FFFF0003-00000010","","","3","","1282062437.17",
   "1282062437.17","",""

"ANSWER","1282062437.436513","Julie Bryant","12565553333","12565553333","",
   "200","200","LocalSets","SIP/0000FFFF0003-00000010","Answer","","3","",
   "1282062437.17","1282062437.17","",""

"APP_START","1282062437.501868","Julie Bryant","12565553333","12565553333",
   "","200","200","LocalSets","SIP/0000FFFF0003-00000010","Playback",
   "hello-world","3","","1282062437.17","1282062437.17","",""

"APP_END","1282062439.008997","Julie Bryant","12565553333","12565553333","",
   "200","200","LocalSets","SIP/0000FFFF0003-00000010","Playback",
   "hello-world","3","","1282062437.17","1282062437.17","",""

"HANGUP","1282062439.009127","Julie Bryant","12565553333","12565553333","",
   "200","200","LocalSets","SIP/0000FFFF0003-00000010","","","3","",
   "1282062437.17","1282062437.17","",""

"CHAN_END","1282062439.009666","Julie Bryant","12565553333","12565553333",
   "","200","200","LocalSets","SIP/0000FFFF0003-00000010","","","3","",
   "1282062437.17","1282062437.17","",""

"LINKEDID_END","1282062439.009707","Julie Bryant","12565553333",
   "12565553333","","200","200","LocalSets","SIP/0000FFFF0003-00000010","",
   "","3","","1282062437.17","1282062437.17","",""

For the second example, one phone will call another via extension 101. This results in a call that has two channels that are bridged together. Here is the extension that was called in the dialplan:

exten => 101,1,Dial(SIP/0000FFFF0001)

Here are the CEL events that are generated as a result of making this call:

"CHAN_START","1282062455.574611","Julie Bryant","12565553333","","","","101",
   "LocalSets","SIP/0000FFFF0003-00000011","","","3","","1282062455.18",
   "1282062455.18","",""

"APP_START","1282062455.574872","Julie Bryant","12565553333","12565553333","",
   "101","101","LocalSets","SIP/0000FFFF0003-00000011","Dial",
   "SIP/0000FFFF0001","3","","1282062455.18","1282062455.18","",""

"CHAN_START","1282062455.575044","Candice Yant","12565551111","","","","s",
   "LocalSets","SIP/0000FFFF0001-00000012","","","3","","1282062455.19",
   "1282062455.18","",""

"ANSWER","1282062458.068134","","101","12565551111","","","101","LocalSets",
   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",
   "1282062455.19","1282062455.18","",""

"ANSWER","1282062458.068361","Julie Bryant","12565553333","12565553333","",
   "101","101","LocalSets","SIP/0000FFFF0003-00000011","Dial",
   "SIP/0000FFFF0001","3","","1282062455.18","1282062455.18","",""

"BRIDGE_START","1282062458.068388","Julie Bryant","12565553333",
   "12565553333","","101","101","LocalSets","SIP/0000FFFF0003-00000011",
   "Dial","SIP/0000FFFF0001","3","","1282062455.18","1282062455.18","",""

"BRIDGE_END","1282062462.965704","Julie Bryant","12565553333","12565553333",
   "","101","101","LocalSets","SIP/0000FFFF0003-00000011","Dial",
   "SIP/0000FFFF0001","3","","1282062455.18","1282062455.18","",""

"HANGUP","1282062462.966097","","101","12565551111","","","","LocalSets",
   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",
   "1282062455.19","1282062455.18","",""

"CHAN_END","1282062462.966119","","101","12565551111","","","","LocalSets",
   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",
   "1282062455.19","1282062455.18","",""

"APP_END","1282062462.966156","Julie Bryant","12565553333","12565553333","",
   "101","101","LocalSets","SIP/0000FFFF0003-00000011","Dial",
   "SIP/0000FFFF0001","3","","1282062455.18","1282062455.18","",""

"HANGUP","1282062462.966215","Julie Bryant","12565553333","12565553333",
   "","101","101","LocalSets","SIP/0000FFFF0003-00000011","","","3","",
   "1282062455.18","1282062455.18","",""

"CHAN_END","1282062462.966418","Julie Bryant","12565553333","12565553333",
   "","101","101","LocalSets","SIP/0000FFFF0003-00000011","","","3","",
   "1282062455.18","1282062455.18","",""

"LINKEDID_END","1282062462.966441","Julie Bryant","12565553333",
   "12565553333","","101","101","LocalSets","SIP/0000FFFF0003-00000011",
   "","","3","","1282062455.18","1282062455.18","",""

In this final example, a transfer will be executed. The call is started by calling a phone via extension 102. That call is then transferred to another phone at extension 101. Here is the relevant dialplan:

exten => 101,1,Dial(SIP/0000FFFF0001)
exten => 102,1,Dial(SIP/0000FFFF0002)

Here are the CEL events logged as a result of this call scenario:

"CHAN_START","1282062488.028200","Julie Bryant","12565553333","","","",
   "102","LocalSets","SIP/0000FFFF0003-00000013","","","3","",
   "1282062488.20","1282062488.20","",""

"APP_START","1282062488.028464","Julie Bryant","12565553333","12565553333",
   "","102","102","LocalSets","SIP/0000FFFF0003-00000013","Dial",
   "SIP/0000FFFF0002","3","","1282062488.20","1282062488.20","",""

"CHAN_START","1282062488.028762","Brooke Brown","12565552222","","","",
   "s","LocalSets","SIP/0000FFFF0002-00000014","","","3","","1282062488.21",
   "1282062488.20","",""

"ANSWER","1282062492.565759","","102","12565552222","","","102","LocalSets",
   "SIP/0000FFFF0002-00000014","AppDial","(Outgoing Line)","3","",
   "1282062488.21","1282062488.20","",""

"ANSWER","1282062492.565973","Julie Bryant","12565553333","12565553333","",
   "102","102","LocalSets","SIP/0000FFFF0003-00000013","Dial",
   "SIP/0000FFFF0002","3","","1282062488.20","1282062488.20","",""

"BRIDGE_START","1282062492.566001","Julie Bryant","12565553333",
   "12565553333","","102","102","LocalSets","SIP/0000FFFF0003-00000013",
   "Dial","SIP/0000FFFF0002","3","","1282062488.20","1282062488.20","",""

"CHAN_START","1282062497.940687","","","","","","s","LocalSets",
   "AsyncGoto/SIP/0000FFFF0002-00000014","","","3","","1282062497.22",
   "1282062488.20","",""

"BLINDTRANSFER","1282062497.940925","Julie Bryant","12565553333","12565553333","",
   "102","102","LocalSets","SIP/0000FFFF0003-00000013","Dial","SIP/0000FFFF0002",
   "3","","1282062488.20","1282062488.20",
   "AsyncGoto/SIP/0000FFFF0002-00000014<ZOMBIE>",""

"BRIDGE_END","1282062497.940961","Julie Bryant","12565553333","12565553333","",
   "102","102","LocalSets","SIP/0000FFFF0003-00000013","Dial",
   "SIP/0000FFFF0002","3","","1282062488.20","1282062488.20","",""

"APP_START","1282062497.941021","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","Dial","SIP/0000FFFF0001","3","",
   "1282062497.22","1282062488.20","",""

"CHAN_START","1282062497.941207","Candice Yant","12565551111","","","","s",
   "LocalSets","SIP/0000FFFF0001-00000015","","","3","","1282062497.23",
   "1282062488.20","",""

"HANGUP","1282062497.941361","","","","","","","LocalSets",
   "AsyncGoto/SIP/0000FFFF0002-00000014<ZOMBIE>","AppDial",
   "(Outgoing Line)","3","","1282062488.21","1282062488.20","",""

"CHAN_END","1282062497.941380","","","","","","","LocalSets",
   "AsyncGoto/SIP/0000FFFF0002-00000014<ZOMBIE>","AppDial","(Outgoing Line)",
   "3","","1282062488.21","1282062488.20","",""

"APP_END","1282062497.941415","Julie Bryant","12565553333","12565553333","",
   "102","102","LocalSets","SIP/0000FFFF0003-00000013","Dial",
   "SIP/0000FFFF0002","3","","1282062488.20","1282062488.20","",""

"HANGUP","1282062497.941453","Julie Bryant","12565553333","12565553333",
   "","102","102","LocalSets","SIP/0000FFFF0003-00000013","","","3","",
   "1282062488.20","1282062488.20","",""

"CHAN_END","1282062497.941474","Julie Bryant","12565553333","12565553333",
   "","102","102","LocalSets","SIP/0000FFFF0003-00000013","","","3","",
   "1282062488.20","1282062488.20","",""

"ANSWER","1282062500.559578","","101","12565551111","","","101","LocalSets",
   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","",
   "1282062497.23","1282062488.20","",""

"BRIDGE_START","1282062500.559720","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","Dial","SIP/0000FFFF0001","3","","1282062497.22",
   "1282062488.20","",""

"BRIDGE_END","1282062512.742600","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","Dial","SIP/0000FFFF0001","3","","1282062497.22",
   "1282062488.20","",""

"HANGUP","1282062512.743006","","101","12565551111","","","","LocalSets",
   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","","1282062497.23",
   "1282062488.20","",""

"CHAN_END","1282062512.743211","","101","12565551111","","","","LocalSets",
   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","","1282062497.23",
   "1282062488.20","",""

"APP_END","1282062512.743286","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","Dial","SIP/0000FFFF0001","3","","1282062497.22",
   "1282062488.20","",""

"HANGUP","1282062512.743346","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","","","3","","1282062497.22","1282062488.20",
   "",""

"CHAN_END","1282062512.743371","","102","12565552222","","","101","LocalSets",
   "SIP/0000FFFF0002-00000014","","","3","","1282062497.22","1282062488.20",
   "",""

"LINKEDID_END","1282062512.743391","","102","12565552222","","","101",
   "LocalSets","SIP/0000FFFF0002-00000014","","","3","","1282062497.22",
   "1282062488.20","",""

In CentOS, you simply need to install the net-snmp-devel package:

$ sudo yum install net-snmp-devel

See the upcoming section Recompiling Asterisk with the res_snmp module for a description of how to recompile Asterisk with SNMP support.

Under Ubuntu, the following package needs to be installed:

$ sudo apt-get install snmp libsnmp-dev snmpd

See the next section for a description of how to recompile Asterisk with SNMP support.

Once you’ve satisfied the dependencies for SNMP, you can recompile Asterisk with SNMP support:

$ cd ~/src/asterisk-complete/asterisk/1.8/
$ ./configure
$ make menuselect  # verify that res_snmp is selected under Resource Modules 
$ sudo make install

You then need to copy the sample config file over to the /etc/asterisk folder:

$ sudo cp ~/src/asterisk-complete/asterisk/1.8/configs/res_snmp.conf.sample  
/etc/asterisk/res_snmp.conf

We’ll talk about configuring this file for use with OpenNMS in the next section.

The OpenNMS wiki has detailed instructions for installing OpenNMS, which you can find at http://opennms.org/wiki/Installation:Yum.

Since the OpenNMS wiki provides all the required instructions, we’ll leave it to the experts to lead you through the first part of the installation. Once you’ve installed OpenNMS, come back here and we’ll take you through how to configure it to work with Asterisk.

The instructions for installing OpenNMS on the wiki use SNMPv2c, which is not a secure method of abstracting data from the SNMP protocol. Since we want to build a secure system, our instructions will show you how to enable SNMPv3 support.^[174]

However, because SNMPv3 can be a bit of an unwieldy beast, and because you may not wish to enable SNMPv3 for some reason (e.g., if your version of SNMP was not compiled with OpenSSL support), we will provide instructions for configuring the SNMP daemon for both SNMPv2c and SNMPv3.

It tends to be easier to configure the system for SNMPv2c first and then update it to SNMPv3, as the steps to get SNMPv3 set up properly are more complex.

In the /etc/asterisk/res_snmp.conf file that you’ve copied over from your source directory, there are two lines you must uncomment:

[general]
;subagent=yes
;enabled=yes

Modify the res_snmp.conf file so both the SNMP client and the subagent are enabled:

[general]
subagent=yes
enabled=yes

After modifying this file, you will need to reload the res_snmp.so module in order for the changes to take effect:

*CLI> module unload res_snmp.so

Unloaded res_snmp.so
 Unloading [Sub]Agent Module
  == Terminating SubAgent

*CLI> module load res_snmp.so

Loaded res_snmp.so
  == Parsing '/etc/asterisk/res_snmp.conf':   == Found
 Loading [Sub]Agent Module
 Loaded res_snmp.so => (SNMP [Sub]Agent for Asterisk)
  == Starting SubAgent

Now you can modify the /etc/snmp/snmpd.conf file for SNMP on the host machine. Rename the current example configuration file and create a new snmpd.conf file:

$ cd /etc/snmp
$ sudo mv snmpd.conf snmpd.sample

The first thing to do is to add the permissions control to the file. We suggest you read the /etc/snmpd/snmp.sample file that you just renamed to get a better idea of how the permissions are being set up. Then, add the following to your snmpd.conf file:

$ sudo cat > snmpd.conf

com2sec notConfigUser  default       public

group   notConfigGroup v1           notConfigUser
group   notConfigGroup v2c           notConfigUser

view all    included  .1
view system included  .iso.org.dod.internet.mgmt.mib-2.system

access  notConfigGroup ""      any       noauth    exact  all    none none

syslocation Caledon, ON
syscontact Leif Madsen [email protected]

Ctrl+D

Now we need to enable the AgentX subagent support so information about our Asterisk system can be found:

$ sudo cat >> snmpd.conf

master agentx
agentXSocket /var/agentx/master
agentXPerms 0660 0775 nobody root

sysObjectID .1.3.6.1.4.1.22736.1

Ctrl+D

By adding the master agentx line and the agentX options, we’ve enabled Asterisk to communicate with the SNMP daemon. The agentXPerms option is stating that Asterisk is running as root. If your Asterisk system is running in a different group, change root to the group that Asterisk is running as.

Just below the AgentX configuration, we added the sysObjectID option. The purpose of adding the sysObjectID string is so OpenNMS will know that this host system is running Asterisk, allowing it to dynamically grab additional graphing information.

Once you’ve performed these configuration steps, you need to restart the SNMP daemon:

$ sudo /etc/init.d/snmpd restart

To verify that the information can be polled correctly, utilize the snmpwalk application:

$ snmpwalk -On -v2c -c public 127.0.0.1 .1.3.6.1.4.1.22736

You should get several lines of information flowing across your screen if your configuration is correct, much like the following:

.1.3.6.1.4.1.22736.1.5.4.1.4.3 = INTEGER: 2
.1.3.6.1.4.1.22736.1.5.4.1.4.4 = INTEGER: 2
.1.3.6.1.4.1.22736.1.5.4.1.4.5 = INTEGER: 1
.1.3.6.1.4.1.22736.1.5.4.1.4.6 = INTEGER: 1
.1.3.6.1.4.1.22736.1.5.4.1.5.1 = INTEGER: 1
...etc

At this point your host system should be ready for OpenNMS to connect and gather the information it needs. Proceed by adding a node to the system and filling in the appropriate information. After a period of time, OpenNMS will poll the host system and have access to the Asterisk statistics. You should be able to click on Resource Graphs after selecting the node you created and see a selection of graphs available, such as SIP, DAHDI, Local, etc.

Enabling SNMPv3 allows you to securely connect and transmit data from the SNMP daemon to the SNMP client. This may not be necessary in a local environment, especially if the client and the daemon are running on the same machine. However, when traversing public networks it is important to secure this data.

First, you need to stop the SNMP daemon, using the init script or the service command:

$ sudo /etc/init.d/snmpd stop

After stopping the daemon, you need to add the initial user to the /var/net-snmp/snmpd.conf file. This file is dynamic in nature and should only be modified when the SNMP daemon has been stopped.

You need to create a bootstrap user that you will be able to use to create the administration user in the next step. Add the following line to the /var/net-snmp/snmpd.conf file:

createUser initial MD5 setup_passphrase DES

After adding it, save the file and exit. Next, you need to add permissions to the /etc/snmp/snmpd.conf file. Add the following line to give the initial user read/write permissions:

rwuser initial

After making these modifications, you can restart the SNMP daemon:

$ sudo /etc/init.d/snmpd start

Starting snmpd:                                            [  OK  ]

Using your initial user, you now need to create a user for OpenNMS to connect to. You’ll do this with the snmpusm^[175] application. Execute the following command, which will clone the opennmsUser user from the initial user. We configured the password setup_passphrase for the authentication and privacy settings when we added the initial user to the /var/net-snmp/snmpd.conf file:

$ sudo snmpusm -v3 -u initial -n "" -l authPriv 
-a MD5 -A setup_passphrase 
-x DES -X setup_passphrase 
localhost create opennmsUser initial

User successfully created.

Now change the passphrase for the opennmsUser with the following command:

$ sudo snmpusm -v 3 -u initial -n "" -l authPriv 
-a MD5 -A setup_passphrase 
-x DES -X setup_passphrase 
-Ca -Cx localhost passwd setup_passphrase 
0p3nNMSv3 opennmsUser

SNMPv3 Key(s) successfully changed.

You can now test to make sure you’re getting results from your user by utilizing the snmpwalk application:

$ sudo snmpwalk -v 3 -u opennmsUser -n "" -l authPriv 
-a MD5 -A 0p3nNMSv3 
-x DES -X 0p3nNMSv3 
localhost ifTable

IF-MIB::ifIndex.1 = INTEGER: 1
IF-MIB::ifIndex.2 = INTEGER: 2
IF-MIB::ifIndex.3 = INTEGER: 3
IF-MIB::ifDescr.1 = STRING: lo
IF-MIB::ifDescr.2 = STRING: eth0
IF-MIB::ifDescr.3 = STRING: sit0

Now that you have data being returned, lock down the /etc/snmp/snmpd.conf file to make sure only the opennmsUser can read data from the SNMP daemon.

The file will look quite similar to the one in the previous section, for configuring SNMPv2c. We’ve commented out the lines you no longer need with the hash symbol (#) and added new group and access lines to control access to the SNMP daemon:

com2sec notConfigUser  default       public

#group   notConfigGroup v1            notConfigUser
#group   notConfigGroup v2c           notConfigUser
group   notConfigGroup usm           opennmsUser

#view    systemview    included   .1.3.6.1.2.1.1
#view    systemview    included   .1.3.6.1.2.1.25.1.1
view    all           included   .1

#access  notConfigGroup ""      any       noauth    exact  all    none none
access  notConfigGroup ""       usm       priv      exact  all    none none


syslocation Caledon, ON
syscontact Leif Madsen [email protected]


#rwuser initial

master agentx
agentXSocket /var/agentx/master
agentXPerms 0660 0775 nobody root

sysObjectID .1.3.6.1.4.1.22736.1

On the group line, we’ve configured the system to use usm (the User-based Security Model) and permitted the opennmsUser to connect. We control how it can connect with the access line, where we’ve enabled access via the notConfigGroup using usm and the priv model, which makes sure we connect using both authentication and privacy settings. These in turn make sure that we authenticate securely and transmit data encrypted.

After modifying the /etc/snmp/snmpd.conf file, restart the SNMP daemon one last time:

$ sudo /etc/init.d/snmpd restart

Then verify that you can still access data via snmpwalk:

$ sudo snmpwalk -v 3 -u opennmsUser -n "" -l authPriv 
-a MD5 -A 0p3nNMSv3 
-x DES -X 0p3nNMSv3 
localhost ifTable

and that Asterisk is still able to connect via AgentX with snmpwalk:

$ sudo snmpwalk -v 3 -u opennmsUser -n "" -l authPriv 
-a MD5 -A 0p3nNMSv3 
-x DES -X 0p3nNMSv3 
localhost .1.3.6.1.4.1.22736

If all goes well, you should get lots of lines back, including:

SNMPv2-SMI::enterprises.22736.1.5.4.1.2.1 = STRING: "SIP"
SNMPv2-SMI::enterprises.22736.1.5.4.1.2.2 = STRING: "IAX2"
SNMPv2-SMI::enterprises.22736.1.5.4.1.2.3 = STRING: "Bridge"
SNMPv2-SMI::enterprises.22736.1.5.4.1.2.4 = STRING: "MulticastRTP"
SNMPv2-SMI::enterprises.22736.1.5.4.1.2.5 = STRING: "DAHDI"
SNMPv2-SMI::enterprises.22736.1.5.4.1.2.6 = STRING: "Local"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.1 = STRING: "Session Initiation Protocol(SIP)"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.2 = STRING: "Inter Asterisk eXchange Driver"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.3 = STRING: "Bridge Interaction Channel"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.4 = STRING: "Multicast RTP Paging Channel"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.5 = STRING: "DAHDI Telephony Driver"
SNMPv2-SMI::enterprises.22736.1.5.4.1.3.6 = STRING: "Local Proxy Channel Driver"

If you don’t get data returned right away, it could be because the Asterisk res_snmp.so module has not reconnected to the SNMP daemon. You can force this either by restarting Asterisk, or by unloading and reloading the res_snmp.so module from the Asterisk CLI.