Asterisk is built on modules. A module is a loadable component that provides a specific functionality, such as a channel driver (for example,, or a resource that allows connection to an external technology (such as Asterisk modules are loaded based on the /etc/asterisk/modules.conf file. We will discuss the use of many modules in this book. At this point we just want to introduce the concept of modules, and give you a feel for the types of modules that are available.

It is actually possible to start Asterisk without any modules at all, although in this state it will not be capable of doing anything. It is useful to understand the modular nature of Asterisk in order to appreciate the architecture.


You can start Asterisk with no modules loaded by default and load each desired module manually from the console, but this is not something that you’d want to put into production; it would only be useful if you were performance-tuning a system where you wanted to eliminate everything not required by your specific application of Asterisk.

The types of modules in Asterisk include the following:

In the following sections we will list each module available within these categories, briefly identify its purpose, and give our opinion on its relative popularity and/or importance (while some modules are proven and deservedly popular, others are quite old, are barely ever used anymore, and are only maintained for the purpose of backward-compatibility). The details of how specific modules work will be covered in various chapters throughout the book, depending on what the module is and what it does. Some modules will be covered thoroughly; others may not be covered at all.

Regarding the Popularity/Status column in the tables that follow, the following list contains our opinions with respect to the meanings we have chosen (your mileage may vary):


This module is ancient history. If you use it, be aware that you are mostly on your own when it comes to any sort of community support.


This module is new or experimental, and is not suitable for production.


This module is current, maintained, popular, and recommended.


This module works but may be incomplete or unpopular, and/or is not recommended by the authors.


This module is quite new, and its completeness and popularity are difficult to gauge at this time.


This module has been replaced by something that is considered superior.


This module has limitations that may make it unsuitable to your requirements.


This module is one you’ll never want to be without.

And now, without further ado, let’s take a look at the modules, grouped by module type.


Dialplan applications are used in extensions.conf to define the various actions that can be applied to a call. The Dial() application, for example, is responsible for making outgoing connections to external resources and is arguably the most important dialplan application. The available applications are listed in Table 2.1, “Dialplan applications”.

Table 2.1. Dialplan applications

app_adsiprog Loads Analog Display Services Interface (ADSI) scripts into compatible analog phonesInsignificant
app_alarmreceiver Supports receipt of reports from alarm equipmentInsignificant
app_amd Detects answering machinesUnreliable
app_authenticate Compares dual-tone multi-frequency (DTMF) input against a provided string (password)Useful
app_cdr Writes ad hoc record to CDRUseful
app_celgenuserevent Generates user-defined events for CELNew
app_chanisavail Checks the status of a channelUnreliable
app_channelredirect Forces another channel into a different part of the dialplanUseful
app_chanspy Allows a channel to listen to audio on another channelUseful
app_confbridge Provides conferencing (new version)New—not fully featured yet
app_controlplayback Plays back a prompt and offers fast forward and rewind functionsUseful
app_dahdibarge Allows barging in on a DAHDI channelDeprecated—see app_chanspy
app_dahdiras Creates a RAS server over a DAHDI channel (no modem emulation)Insignificant
app_db Used to add/change/delete records in Asterisk’s built-in Berkeley databaseDeprecated—see func_db
app_dial Used to connect channels together (i.e., make phone calls)Essential
app_dictate Plays back a recording and offers start/stop functionsUseful
app_directed_pickup Answers a call for another extensionUseful
app_directory Presents the list of names from voicemail.confUseful
app_disa Provides dialtone and accepts DTMF inputUseful[a]
app_dumpchan Dumps channel variables to Asterisk command-line interface (CLI)Useful
app_echo Loops received audio back to source channelUseful
app_exec Contains Exec(), TryExec(), and ExecIf(); executes a dialplan application based on conditionsUseful
app_externalivr Controls Asterisk as with an AGI, only asynchronouslyUseful
app_fax Provides SendFax() and ReceiveFax()Useful[b]
app_festival Enables basic text to speech using Festival TTS engineUsable
app_flash Performs a hook-switch flash on channels (primarily analog)Useful
app_followme Performs find me/follow me functionality based on followme.confUseful
app_forkcdr Starts new CDR record on current callUsable
app_getcpeid Gets the ADSI CPE IDInsignificant
app_ices Sends audio to an Icecast serverUsable
app_image Transmits an image to supported devicesLimited
app_ivrdemo Sample application for developersInsignificant
app_jack Works with JACK Audio Connection Kit to share audio between compatible applicationsUseful
app_macro Triggers dialplan macrosDeprecated—see GoSub()
app_meetme Provides multiparty conferencingUseful—fully featured
app_milliwatt Generates 1004-Hz tone for testing loss on analog circuitsUseful
app_minivm Provides primitive functions to allow you to build your own voicemail application in dialplanUsable
app_mixmonitor Records both sides of a call and mixes them togetherUseful
app_morsecode Generates Morse codeUsable
app_mp3 Uses mpg123 to play an MP3Insignificant
app_nbscat Streams audio from Network Broadcast Stream (NBS)Insignificant
app_originate Allows origination of a callUseful
app_osplookup Performs Open Settlement Protocol (OSP) lookupUsable
app_page Creates multiple audio connections to specified devices for public address (paging)Useful
app_parkandannounce Enables automated announcing of parked callsUsable
app_playback Plays a file to the channel (does not accept input)Useful
app_playtones Plays pairs of tones of specified frequenciesUseful
app_privacy Requests input of caller’s phone number if no CallerID is receivedInsignificant
app_queue Provides Automatic Call Distribution (ACD)Useful
app_read Requests input of digits from callers and assigns input to a variableUseful
app_readexten Requests input of digits from callers and passes call to a designated extension and contextUsable
app_readfile Loads contents of a text file into a channel variableDeprecated—see the FILE() function in func_env
app_record Records received audio to a fileUseful
app_rpt Provides a method to interface with an audio board for the app_rpt projectLimited
app_sayunixtime Plays back time in specified formatUseful
app_senddtmf Transmits DTMF to calling partyUseful
app_sendtext Sends a text string to compatible channelsInsignificant
app_setcallerid Sets CallerID on a channelDeprecated—see func_callerid
app_skel Sample application for developersUseful[c]
app_sms Sends SMS message in compatible countriesLimited
app_softhangup Requests hangup of channelUseful
app_speech_utils Provides utilities relating to speech recognitionUseful[d]
app_stack Provides Gosub(), GoSubIf(), Return(), StackPop(), LOCAL(), and LOCAL_PEEK()Essential
app_system Executes commands in a Linux shellUseful
app_talkdetect Similar to app_background, but allows for any received audio to interrupt playbackUseful
app_test Client/server testing applicationUsable
app_transfer Performs a transfer on the current channelUseful
app_url Passes a URI to the called channelLimited
app_userevent Generates a custom event in the Asterisk Manager Interface (AMI)Useful
app_verbose Generates a custom event in the Asterisk CLIUseful
app_voicemail Provides voicemailEssential
app_waitforring Waits for a RING signaling event (not to be confused with RINGING); most likely unnecessary, as only chan_dahdi with analog channels where ringing is received (such as an FXO port) generates the RING signaling eventInsignificant
app_waitforsilence Includes WaitForSilence() and WaitForNoise(); listens to the incoming channel for a specified number of milliseconds of noise/silenceUseful
app_waituntil Waits until current Linux epoch matches specified epochUseful
app_while Includes While(), EndWhile(), ExitWhile(), and ContinueWhile(); provides while-loop functionality in the dialplanUseful
app_zapateller Generates SIT tone to discourage telemarketersUsable

[a] The use of (DISA) is considered to be a security risk.

[b] Requires a suitable DSP engine to handle encoding/decoding of fax signaling (see Chapter 19, Fax).

[c] If you are a developer.

[d] Requires an external speech recognition application.

Bridging Modules

Bridging modules are new in Asterisk 1.8: they perform the actual bridging of channels in the new bridging API. Each provides different features, which get used in different situations depending on what a bridge needs. These modules, listed in Table 2.2, “Bridging modules”, are currently only used for (and are essential to) app_confbridge.

Table 2.2. Bridging modules

NamePurpose Popularity/Status
bridge_builtin_features Performs bridging when utilizing built-in user features (such as those found in features.conf).New
bridge_multiplexed Performs complex multiplexing, as would be required in a large conference room (multiple participants). Currently only used by app_confbridge.New
bridge_simple Performs simple channel-to-channel bridging.New
bridge_softmix Performs simple multiplexing, as would be required in a large conference room (multiple participants). Currently only used by app_confbridge.New

Call Detail Recording Modules

The CDR modules, listed in Table 2.3, “Call detail recording modules”, are designed to facilitate as many methods of storing call detail records as possible. You can store CDRs to a file (default), a database, RADIUS, or syslog.


Call detail records are not intended to be used in complex billing applications. If you require more control over billing and call reporting, you will want to look at channel event logging, discussed next. The advantage of CDR is that it just works.

Table 2.3. Call detail recording modules

cdr_adaptive_odbc Allows writing of CDRs through ODBC framework with ability to add custom fieldsUseful
cdr_csv Writes CDRs to disk as a comma-separated values fileUsable
cdr_custom As above, but allows for the addition of custom fieldsUseful
cdr_manager Outputs CDRs to Asterisk Manager Interface (AMI)Useful
cdr_odbc Writes CDRs through ODBC frameworkUsable
cdr_pgsql Writes CDRs to PostgreSQLUseful
cdr_radius Writes CDRs to RADIUSUsable—does not support custom fields
cdr_sqlite Writes CDRs to SQLite2 databaseDeprecated—use sqlite3_custom
cdr_sqlite3_custom Writes CDRs to SQLite3 with custom fieldsUseful
cdr_syslog Writes CDRs to syslogUseful
cdr_tds Writes CDRs to Microsoft SQL or SybaseUsable—requires an old version of libtds

We will discuss some reporting packages that you may wish to use with CDR in Chapter 25, Web Interfaces.

Channel Event Logging Modules

Channel event logging provides much more powerful control over reporting of call activity. By the same token, it requires more careful planning of your dialplan, and by no means will it work automatically. Asterisk’s CEL modules are listed in Table 2.4, “Channel event logging modules”.

Table 2.4. Channel event logging modules

cel_custom CEL to disk/fileUseful
cel_manager CEL to AMIUseful
cel_odbc CEL to ODBCUseful
cel_pgsql CEL to PostgreSQLUseful
cel_radius CEL to RADIUSUsable—does not support custom fields
cel_sqlite3_custom CEL to Sqlite3Useful
cel_tds CEL to Microsoft SQL or SybaseUsable—requires an old version of libtds

Channel Drivers

Without channel drivers, Asterisk would have no way to make calls. Each channel driver is specific to the protocol or channel type it supports (SIP, ISDN, etc.). The channel module acts as a gateway to the Asterisk core. Asterisk’s channel drivers are listed in Table 2.5, “Channel drivers”.

Table 2.5. Channel drivers

NamePurpose Popularity/Status
chan_agent Provides agent channel for Queue()Useful
|chan_alsa Provides connection to Advanced Linux Sound ArchitectureUseful
chan_bridge Used internally by the ConfBridge() application; should not be used directlyEssential [a]
chan_console Provides connection to portaudioNew
chan_dahdi Provides connection to PSTN cards that use DAHDI channel driversUseful
chan_gtalk Provides connection to Google TalkUsable
chan_h323 Provides connection to H.323 endpointsDeprecated—see chan_ooh323 in Table 2.11, “Addon modules”
chan_iax2 Provides connection to IAX2 endpointsUseful
chan_jingle Provides connection to Jingle-enabled endpointsUsable
chan_local Provides a mechanism to treat a portion of the dialplan as a channelUseful
chan_mgcp Media Gateway Control Protocol channel driverUsable
chan_misdn Provides connection to mISDN supported ISDN cardsLimited
chan_multicast_rtp Provides connection to multicast RTP streamsUseful
chan_nbs Network Broadcast Sound channel driverInsignificant
chan_oss Open Sound System driverUseful
chan_phone Linux telephony interface driver (very old)Insignificant
chan_sip Session Initiation Protocol channel driverEssential
chan_skinny Cisco Skinny Client Control Protocol (SCCP) channel driverUsable
chan_unistim Nortel Unistim protocol channel driverUsable
chan_usbradio Channel driver for CM108 USB cards with radio interfaceUsable
chan_vpb Voicetronix channel driverInsignificant[b]

[a] If you are using the ConfBridge() application.

[b] Some Voicetronix hardware is supported by Zaptel using an addon Zaptel module distributed by Voicetronix. However, Zaptel is no longer supported by Asterisk and this driver has not been ported to DAHDI.

Codec Translators

The codec translators (Table 2.6, “Codec translators”) allow Asterisk to convert audio stream formats between calls. So if a call comes in on a PRI circuit (using G.711) and needs to be passed out a compressed SIP channel (e.g., using G.729, one of many codecs that SIP can handle), the relevant codec translator would perform the conversion.[13]


If a codec (such as G.729) uses a complex encoding algorithm, heavy use of transcoding can place a massive burden on the CPU. Specialized hardware for the decoding/encoding of G.729 is available from hardware manufacturers such as Sangoma and Digium (and likely others).

Table 2.6. Codec translators

codec_adpcm Adaptive Differential Pulse Coded Modulation codecInsignificant
codec_alaw A-law PCM codec used all over the world (except Canada/USA) on the PSTNEssential
codec_a_mu A-law to mu-law direct converterUseful
codec_dahdi Utilizes proprietary Digium hardware transcoding cardEssential[a]
codec_g722 Wideband audio codecUseful
codec_g726 Flavor of ADPCMInsignificant
codec_gsm Global System for Mobile Communications (GSM) codecUseful
codec_ilbc Internet Low Bitrate CodecInsignificant
codec_lpc10 Linear Predictive Coding vocoder (extremely low bandwidth)Insignificant
codec_resample Resamples between 8-bit and 16-bit signed linearUsable
codec_speex Speex codecUsable
codec_ulaw Mu-law PCM codec used in Canada/USA on PSTNEssential

[a] If you are using a Digium codec transcoder card.

Format Interpreters

Format interpreters (Table 2.7, “Format interpreters”) perform the function of codec translators, but they do their work on files rather than channels. If you have a recording on a menu that has been stored as GSM, a format interpreter would need to be used to play that recording to any channels not using the GSM codec.[14]

If you store a recording in several formats (such as WAV, GSM, etc.), Asterisk will determine the least costly format[15] to use when a channel requires that recording.

Table 2.7. Format interpreters

NamePlays files stored in Popularity/Status
format_g723 G.723 .g723Insignificant
format_g726 G.726 .g726Insignificant
format_g729 G.729 .g729Useful
format_gsm RPE-LTP (original GSM codec) .gsmUsable
format_h263 H.263—video .h263Usable
format_h264 H.264—video .h264Usable
format_ilbc Internet Low Bitrate Codec .ilbcInsignificant
format_jpeg Graphic file .jpeg .jpgInsignificant
format _ogg_ vorbis Ogg container .oggUsable
format_pcm Various Pulse-Coded Modulation formats: .alaw, .al, .alw, .pcm, .ulaw, .ul, .mu, .ulw, .g722, .auUseful
format_siren14 G.722.1 Annex C (14 kHz) .siren14New
format_siren7 G.722.1 (7 kHz) .siren7New
format_sln16 16-bit signed linear .sln16New
format_sln 8-bit signed linear .sln .rawUseful
format_vox .vox Insignificant
format_wav .wav Useful
format_wav_gsm GSM audio in a WAV container .WAV, .wav49Usable

Dialplan Functions

Dialplan functions, listed in Table 2.8, “Dialplan functions”, complement the dialplan applications (see the section called “Applications”). They provide many useful enhancements to things like string handling, time and date wrangling, and ODBC connectivity.

Table 2.8. Dialplan functions

func_aes Encrypts/decrypts an AES stringUseful
func_audiohookinherit Allows calls to be recorded after transferUseful
func_base64 Encodes/decodes a base-64 stringUsable
func_blacklist Writes/reads blacklist in astdbUseful
func_callcompletion Gets/sets call completion configuration parameters for the channelNew
func_callerid Gets/sets CallerIDUseful
func_cdr Gets/sets CDR variableUseful
func_channel Gets/sets channel informationUseful
func_config Includes AST_CONFIG(); reads variables from config fileUsable
func_connectedline Changes connected line information on supported handsetsNew
func_curl Uses cURL to obtain data from a URIUseful
func_cut Slices and dices stringsUseful
func_db Provides astdb functionsUseful
func_devstate Gets state of deviceUseful
func_dialgroup Creates a group for simultaneous dialingUseful
func_dialplan Validates that designated target exists in dialplanUseful
func_enum Performs ENUM lookupUseful
func_env Includes FILE(), STAT(), and ENV(); performs operating system actionsUseful
func_extstate Returns status of a hinted extensionUseful
func_global Gets/sets global variablesUseful
func_groupcount Gets/sets channel count for members of a groupUseful
func_iconv Converts between character setsUsable
func_lock Includes LOCK(), UNLOCK(), and TRYLOCK(); sets a lock that can be used to avoid race conditions in the dialplanUseful
func_logic Includes ISNULL(), SET(), EXISTS(), IF(), IFTIME(), and IMPORT(); performs various logical functionsUseful
func_math Includes MATH(), INC(), and DEC(); performs mathematical functionsUseful
func_md5 Converts supplied string to an MD5 hashUseful
func_module Checks to see if supplied module is loaded into memoryUsable
func_odbc Allows dialplan integration with ODBC resourcesUseful
func_pitchshift Shifts the pitch of an audio streamUseful
func_rand Returns a random number within a given rangeUseful
func_realtime Performs lookups within the Asterisk Realtime Architecture (ARA)Useful
func_redirecting Provides access to information about where this call was redirected fromUseful
func_sha1 Converts supplied string to an SHA1 hashUseful
func_shell Performs Linux shell operations and returns resultsUseful
func_speex Reduces noise and performs dB gain/loss on an audio streamUseful
func_sprintf Performs string format functions similar to C function of same nameUseful
func_srv Perform SRV lookups in the dialplanUseful
func_strings Includes over a dozen string manipulation functionsUseful
func_sysinfo Gets system information such as RAM, swap, load average, etc.Useful
func_timeout Gets/sets timeouts on channelUseful
func_uri Converts strings to URI-safe encodingUseful
func_version Returns Asterisk version informationUsable
func_vmcount Returns count of messages in a voicemail folder for a particular userUseful
func_volume Sets volume on a channelUseful

PBX Modules

The PBX modules are peripheral modules that provide enhanced control and configuration mechanisms. For example, pbx_config is the module that loads the traditional Asterisk dialplan. The currently available PBX modules are listed in Table 2.9, “PBX modules”.

Table 2.9. PBX modules

pbx_ael Asterisk Extension Logic (AEL) offers a dialplan scripting language that looks like a modern programming language.Usable[a]
pbx_config This is the traditional, and most popular, dialplan language for Asterisk. Without this module, Asterisk cannot read extensions.conf.Useful
pbx_dundi Performs data lookups on remote Asterisk systems.Useful
pbx_loopback Performs something similar to a dialplan include, but in a deprecated manner.Insignificant[b]
pbx_lua Allows creation of a dialplan using the Lua scripting language.Useful
pbx_realtime Provides functionality related to the Asterisk Realtime Architecture.Useful
pbx_spool Provides outgoing spool support relating to Asterisk call files.Useful

[a] We have not found too many people using AEL. We suspect this is because most developers will tend to use AGI/AMI if they do not want to use traditional dialplans.

[b] We’ve never heard of this being used in production.

Resource Modules

Resource modules integrate Asterisk with external resources. For example, res_odbc allows Asterisk to interoperate with ODBC database connections. The currently available resource modules are listed in Table 2.10, “Resource modules”.

Table 2.10. Resource modules

res_adsi Provides ADSIEssential[a]
res_ael_share Provides shared routines for use with pbx_aelEssential if you’re using AEL
res_agi Provides Asterisk Gateway InterfaceUseful
res_ais Provides distributed message waiting indication (MWI) and device state notifications via an implementation of the AIS standard, such as OpenAISUseful
res_calendar Enables base integration to calendaring systemsUseful
res_calendar_caldav Provides CalDAV-specific capabilitiesUseful
res_calendar_exchange Provides MS Exchange capabilitiesUseful
res_calendar_icalendar Provides Apple/Google iCalendar capabilitiesUseful
res_clialiases Creates CLI aliasesUseful
res_clioriginate Originates a call from the CLIUsable
res_config_curl Pulls configuration information using cURLUseful
res_config_ldap Pulls configuration information using LDAPUsable
res_config_odbc Pulls configuration information using ODBCUseful
res_config_pgsql Pulls configuration information using PostgreSQLUsable
res_config_sqlite Pulls configuration information using SQLiteUsable
res_convert Uses the CLI to perform file conversionsUsable
res_crypto Provides cryptographic capabilitiesUseful
res_curl Provides common subroutines for other cURL modulesUseful
res_fax Provides common subroutines for other fax modulesUseful
res_fax_spandsp Plug-in for fax using the spandsp packageUseful
res_http_post Provides POST upload support for the Asterisk HTTP serverUsable
res_jabber Provides Jabber/XMPP resourcesUseful
res_limit Enables adjusting of system limits on the Asterisk processUsable
res_monitor Provides call recording resourcesUseful
res_musiconhold Provides music on hold (MOH) resourcesEssential
res_mutestream Allows muting/unmuting of audio streamsNew
res_odbc Provides common subroutines for other ODBC modulesUseful
res_phoneprov Provisions phones from Asterisk HTTP serverNew
res_pktccops Provides PacketCable COPS resourcesNew
res_realtime Provides CLI commands for the Asterisk Realtime Architecture (ARA)Useful
res_rtp_asterisk Provides RTPEssential
res_rtp_multicast Provides multicast-RTPNew
res_security_log Enables security loggingNew
res_smdi Provides voicemail notification using the SMDI protocolLimited
res_snmp Provides system status information to an SNMP-managed networkUsable
res_speech Generic speech recognition APILimited[b]
res_timing_dahdi Provides timing using the DAHDI kernel interfaceUseful
res_timing_kqueue Provides timing using a kernel feature in some BSDs, including Mac OS XNew
res_timing_pthread Provides timing using only parts of the standard pthread API; less efficient but more portable than other timing modules.Useful
res_timing_timerfd Provides timing using the timerfd API provided by newer versions of the Linux kernelUseful

[a] While most of the ADSI functionality in Asterisk is never used, the voicemail application uses this resource.

[b] Requires a separately licensed product in order to be used.

Addon Modules

Addon modules are community-developed modules with different usage or distribution rights from those of the main code. They are kept in a separate directory and are not compiled and installed by default. To enable these modules, use the menuselect build configuration utility. Currently available addon modules are listed in Table 2.11, “Addon modules”.

Table 2.11. Addon modules

app_mysql Executes MySQL queries with a dialplan applicationDeprecated—see func_odbc
app_saycountpl Says Polish counting wordsDeprecated—now integrated in say.conf
cdr_mysql Logs call detail records to a MySQL databaseUsable—we recommend cdr_adaptive_odbc instead
chan_mobile Enables making and receiving phone calls using cell phones over BluetoothLimited[a]
chan_ooh323 Enables making and receiving VoIP calls using the H.323 protocolUsable
format_mp3 Allows Asterisk to play MP3 filesUsable
res_config_mysql Uses a MySQL database as a real-time configuration backendUseful

[a] While chan_mobile works great with many phones, problems have been reported with some models. When a problem does occur, it is very difficult for developers to solve unless they have a phone of the same model to test with.

Test Modules

Test modules are used by the Asterisk development team to validate new code. They are constantly changing and being added to, and are not useful unless you are developing Asterisk software.

If you are an Asterisk developer, however, the Asterisk Test Suite may be of interest to you as you can build automated tests for Asterisk and submit those back to the project, which runs on several different operating systems and types of machines. By expanding the number of tests constantly, the Asterisk project avoids the creation of regressions in code. By submitting your own tests to the project, you can feel more confident in future upgrades.

More information about installing the Asterisk Test Suite is available in this blog post: More information about building tests is available in this document: or you can join the #asterisk-testing channel on the Freenode IRC network.

[13] More information about what codecs are and how they work is available in the section called “Codecs”.

[14] It is partly for this reason that we do not recommend the default GSM format for system recordings. WAV recordings will sound better and use less CPU.

[15] Some codecs can impose a significant load on the CPU, such that a system that could support several hundred channels without transcoding might only be able to handle a few dozen when transcoding is in use.