Chapter 2. Asterisk Architecture

First things first, but not necessarily in that order.

Doctor Who

Asterisk is very different from other, more traditional PBXs, in that the dialplan in Asterisk treats all incoming channels in essentially the same manner, rather than separating them into stations, trunks, peripheral modules, and so forth.

In a traditional PBX, there is a logical difference between stations (telephone sets) and trunks (resources that connect to the outside world). This limitation makes creative routing in traditional PBXs very difficult or impossible.

Asterisk, on the other hand, does not have an internal concept of trunks or stations. In Asterisk, everything that comes into or goes out of the system passes through a channel of some sort. There are many different kinds of channels; however, the Asterisk dialplan handles all channels in a similar manner, which means that, for example, an internal user can exist on the end of an external trunk (e.g., a cell phone) and be treated by the dialplan in exactly the same manner as that user would be if they were on an internal extension. Unless you have worked with a traditional PBX¹, it may not be immediately obvious how powerful and liberating this is. Figure 2-1 illustrates the differences between the two architectures.

Figure 2-1. Asterisk versus PBX architecture

Modules

Asterisk is built on modules. A module is a loadable component that provides a specific functionality, such as a channel driver (for example, chan_pjsip.so), or a resource that allows connection to an external technology (such as func_odbc.so). Asterisk modules are loaded based on the parameters defined in the /etc/asterisk/modules.conf file. We will discuss the use of many modules in this book, however 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.

Note

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:

• Applications - The workhorses of the dialplan, such as Dial(), Voicemail(), Playback(), Queue and so forth

• Bridging modules - Mechanisms which connect channels (calls) to each other

• Call detail recording (CDR) modules

• Channel event logging (CEL) modules

• Channel drivers - Various connections into and out of the system. SIP messaging uses the PJSIP channel drivers

• Codec translators - Convert various codecs such as G729, G711, G711, Speex, and so forth

• Format interpreters - As above, but relating to files stored in the file system

• Dialplan functions - Enhance the capabilities of the dialplan

• PBX modules -

• Resource modules

• Add-on modules

• Test modules

In the following sections we have curated a list of modules we feel are important enough to be discussed in this book. There will be many other modules found in the Asterisk download, however many older modules are either deprecated, or have little or no support, and are therefore not recommended for production unless you have access to developers who can maintain them for you.

There is an official list of support status types included within menuselect².

Applications

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.

Table 2-1. Popular Dialplan applications

Name	Purpose
app_authenticate	Compares dual-tone multifrequency (DTMF) input against a provided string (password)
app_cdr	Writes ad hoc record to CDR
app_chanspy	Allows a channel to listen to audio on another channel
app_confbridge	Provides conferencing
app_dial	Used to connect channels together (i.e., make phone calls)
app_directed_pickup	Answers a call that’s ringing at another extension
app_directory	Presents the list of names from voicemail.conf
app_dumpchan	Dumps channel variables to Asterisk command-line interface (CLI)
app_echo	Echos received audio back to source channel (can be helpful in demonstrating latency)
app_exec	Contains Exec(), TryExec(), and ExecIf(): Executes a dialplan application conditionally
app_mixmonitor	Records both sides of a call (transmit and receive) and mixes them together into a single file
app_originate	Allows dialplan logic to originate a call (as opposed to call coming in on a channel)
app_page	Creates multiple audio connections to specified devices for public address (paging)
app_parkandannounce	Enables automated announcing of parked calls
app_playback	Plays a file to the channel (does not accept input)
app_playtones	Plays pairs of tones of specified frequencies (DTMF mostly)
app_queue	Provides Automatic Call Distribution (ACD)
app_read	Requests input of digits from callers and assigns input to a variable
app_readexten	Requests input of digits from callers and passes call to a designated extension and context
app_record	Records received audio to a file
app_senddtmf	Transmits DTMF to calling party
app_stack	Provides Gosub(), GoSubIf(), Return(), StackPop(), LOCAL(), and LOCAL_PEEK()
app_system	Executes commands in a Linux shell
app_transfer	Performs a transfer on the current channel
app_voicemail	Provides voicemail
app_while	Includes While(), EndWhile(), ExitWhile(), and ContinueWhile(); provides while-loop functionality in the dialplan

Bridging Modules

Bridging modules perform the actual bridging of channels. These modules, listed in Table 2-2, are currently only used for (and are essential to) app_confbridge.

Table 2-2. Bridging modules

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

Call Detail Recording Modules

The CDR modules, listed in Table 2-3, are designed to facilitate as many methods of storing call detail records as possible. You can store CDRs to a file (the default), a database, Remote Authentication Dial In User Service (RADIUS), or syslog.

Note

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. Common call detail recording modules

Name	Purpose
cdr_adaptive_odbc	Allows writing of CDRs through ODBC framework with ability to add custom fields
cdr_csv	Writes CDRs to disk as a comma-separated values file
cdr_custom	Writes CDRs to a CSV file, but allows addition of custom fields
cdr_odbc	Writes CDRs through ODBC framework
cdr_syslog	Writes CDRs to syslog

Channel Event Logging Modules

Channel event logging (CEL) 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.

Table 2-4. Channel event logging modules

Name	Purpose
cel_custom	CEL to disk/file
cel_manager	CEL to AMI
cel_odbc	CEL to ODBC

Channel Drivers

Without channel drivers, Asterisk would have no way to make or receive 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. Some of Asterisk’s more popular channel drivers are listed in Table 2-5.

Table 2-5. Popular channel drivers

Name	Purpose
chan_bridge	Used internally by the ConfBridge() application; should not be used directly
chan_dahdi	Provides connection to PSTN cards that use DAHDI channel drivers
chan_local	Provides a mechanism to treat a portion of the dialplan as a channel
chan_motif	Implements the Jingle protocol, including the ability to connect to Google Talk and Google Voice; introduced in Asterisk 11
chan_multicast_rtp	Provides connection to multicast Realtime Transport Protocol (RTP) streams
chan_pjsip	Session Initiation Protocol (SIP) channel driver

Codec Translators

The codec³ translators (often called transcoders) 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.

Codecs are complex algorithms which handle conversion of analog information (sound, in this case, but could be video as well) into a digital format. Many codecs provide compression and error correction as well, but this is not a requirement.

Note

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).

Asterisk does a fairly good job of supporting codecs, but is mostly focused on the codecs typically used by telephone applications (as opposed to codes used for, say, music or video such as MP3 or MP4).

Table 2-6. Common Codec translators

Name	Purpose
codec_alaw	A-law PCM codec used all over the world on the PSTN (except Canada/USA). This (along with ulaw) should be enabled on all your channels.
codec_g729	Was until recently a patented codec, but is now royalty-free. As of this writing it is still sold by Digium as an add-on, but it can also be found as a free package. It’s a very popular codec if compression is desired (and CPU use is not an issue), but it imposes load on the CPU, adds latency to calls, reduces quality slightly, and will not reduce overhead in any way.
codec_a_mu	A-law to mu-law direct converter
codec_g722	Wideband audio codec
codec_gsm	Global System for Mobile Communications (GSM) codec. Very poor sound quality.
codec_ilbc	Internet Low Bitrate Codec
codec_lpc10	Linear Predictive Coding vocoder (extremely low bandwidth)
codec_resample	Resamples between 8-bit and 16-bit signed linear
codec_speex	Speex codec
codec_ulaw	Mu-law PCM codec used on PSTN in Canada/USA. It’s more formally written as μ-law, but not many people have a greek letter μ on their keyboard, so it’s popularly written as ulawa. This is often the default codec, and should be enabled on all your channels.
a Spoken, you should say ‘mew-law', but again, you’ll hear this spoken as ‘you-law’ very often.

Tip

Digium distributes some additional useful codec modules: codec_g729, codec_silk, codec_siren7, and codec_siren14. These codec modules are not open source for various reasons. You must purchase a license to use codec_g729, but the others are free. You can find them on the Digium site.

Format Interpreters

Format interpreters (Table 2-7) perform a similar function as codec translators, but they do their work on files rather than channels, and handle more than just audio. 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.⁴

If you store a recording in several formats simultaneously (such as WAV, GSM, etc.), Asterisk will determine the least costly format⁵ to use when a channel needs to play that recording.

Table 2-7. Format interpreters

Name	Plays files stored in
format_g729	G.729: .g729
format_gsm	RPE-LTP (original GSM codec): .gsm
format_h264	H.264—video: .h264
format_ilbc	Internet Low Bitrate Codec: .ilbc
format_jpeg	Graphic file: .jpeg, .jpg
format _ogg_ vorbis	Ogg container: .ogg
format_pcm	Various Pulse-Coded Modulation formats: .alaw, .al, .alw, .pcm, .ulaw, .ul, .mu, .ulw, .g722, .au
format_siren14	G.722.1 Annex C (14 kHz): .siren14
format_siren7	G.722.1 (7 kHz): .siren7
format_sln	8-bit signed linear: .sln, .raw
format_vox	.vox
format_wav	.wav
format_wav_gsm	GSM audio in a WAV container: .wav, .wav49

Dialplan Functions

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

Table 2-8. A Curated List of Useful Dialplan functions

Name	Purpose
func_audiohookinherit	Allows calls to be recorded after transfer
func_blacklist	Writes/reads blacklist in astdb
func_callcompletion	Gets/sets call-completion configuration parameters for the channel
func_callerid	Gets/sets CallerID
func_cdr	Gets/sets CDR variable
func_channel	Gets/sets channel information
func_config	Includes AST_CONFIG(); reads variables from config file
func_curl	Uses cURL to obtain data from a URI
func_cut	Slices and dices strings
func_db	Provides astdb functions
func_devstate	Gets state of device
func_dialgroup	Creates a group for simultaneous dialing
func_dialplan	Validates that designated target exists in dialplan
func_env	Includes FILE(), STAT(), and ENV(); performs operating system actions
func_global	Gets/sets global variables
func_groupcount	Gets/sets channel count for members of a group
func_hangupcause	Gets/sets hangupcause information from the channel
func_logic	Includes ISNULL(), SET(), EXISTS(), IF(), IFTIME(), and IMPORT(); performs various logical functions
func_math	Includes MATH(), INC(), and DEC(); performs mathematical functions
func_odbc	Allows dialplan integration with ODBC resources
func_rand	Returns a random number within a given range
func_realtime	Performs lookups within the Asterisk Realtime Architecture (ARA)
func_redirecting	Provides access to information about where this call was redirected from
func_shell	Performs Linux shell operations and returns results
func_sprintf	Performs string format functions similar to C function of same name
func_srv	Performs SRV lookups in the dialplan
func_strings	Includes over a dozen string manipulation functions
func_timeout	Gets/sets timeouts on channel
func_uri	Converts strings to URI-safe encoding
func_vmcount	Returns count of messages in a voicemail folder for a particular user

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.

Table 2-9. PBX modules

Name	Purpose
pbx_config	This module provides the traditional, and most popular, dialplan language for Asterisk. Without this module, Asterisk cannot read extensions.conf.
pbx_dundi	Performs data lookups on remote Asterisk systems.
pbx_realtime	Provides functionality related to the Asterisk Realtime Architecture.
pbx_spool	Provides outgoing spool support relating to Asterisk call files.

Resource Modules

Resource modules integrate Asterisk with external resources. This group of modules has effectively turned into a catch-all for things that do not fit in other categories. We will break them into some subgroups of modules that are related.

Configuration backends

Asterisk is configured using text files in /etc/asterisk by default. These modules, listed in Table 2-10, offer alternative configuration methods. See XXX for detailed documentation on setting up database-backed configuration.

Table 2-10. Configuration backend modules

Name	Purpose
res_config_curl	Pulls configuration information using cURL
res_config_ldap	Pulls configuration information using LDAP
res_config_odbc	Pulls configuration information using ODBC

Calendar integration

Asterisk includes some integration with calendar systems. You can read and write calendar information from the dialplan. You can also have calls originated based on calendar entries. The core calendar integration is provided by the res_calendar module. The rest of the modules provide the ability to connect to specific types of calendar servers. Table 2-11 lists the calendar integration modules.

Table 2-11. Calendar integration modules

Name	Purpose
res_calendar	Enables base integration to calendaring systems
res_calendar_caldav	Allows features provided by res_calendar to connect to calendars via CalDAV
res_calendar_exchange	Allows features provided by res_calendar to connect to MS Exchange
res_calendar_icalendar	Allows features provided by res_calendar to connect to Apple/Google iCalendar

Other resource modules

Table 2-12 includes the rest of the resource modules that did not fit into one of the subgroups we defined earlier in this section.

Table 2-12. Resource modules

Name	Purpose
res_adsi	Provides ADSIa
res_agi	Provides the Asterisk Gateway Interface (see XXX)
res_corosync	Provides distributed message waiting indication (MWI) and device state notifications via the Corosync Cluster Engine
res_crypto	Provides cryptographic capabilities
res_curl	Provides common subroutines for other cURL modules
res_fax	Provides common subroutines for other fax modules
res_fax_spandsp	Plug-in for fax using the spandsp package
res_http_post	Provides POST upload support for the Asterisk HTTP server
res_http_websocket	Provides WebSocket support for the Asterisk internal HTTP server (required by WebRTC)
res_monitor	Provides call-recording resources
res_musiconhold	Provides music on hold (MOH) resources
res_mutestream	Allows muting/unmuting of audio streams
res_odbc	Provides common subroutines for other ODBC modules
res_phoneprov	Provisions phones from Asterisk HTTP server
res_pktccops	Provides PacketCable COPS resources
res_security_log	Enables logging of security events generated by other parts of Asterisk
res_snmp	Provides system status information to an SNMP-managed network
res_speech	Generic speech recognition APIb
res_xmpp	Provides XMPP resources (FKA Jabber)
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.

Add-on Modules

Add-on 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.

Table 2-13. Add-on modules

Name	Purpose	Popularity/Status
chan_ooh323	Enables making and receiving VoIP calls using the H.323 protocol	Usable
format_mp3	Allows Asterisk to play MP3 files	Usable
res_config_mysql	Uses a MySQL database as a realtime configuration backend	Useful

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.

File Structure

Asterisk is a complex system, composed of many resources. These resources make use of the filesystem in several ways. Since Linux is so flexible in this regard, it is helpful to understand what data is being stored, so that you can understand where you are likely to find a particular bit of stored data (such as voicemail messages or logfiles).

Configuration Files

The Asterisk configuration files include extensions.conf, pjsip.conf, modules.conf, and dozens of other files that define parameters for the various channels, resources, modules, and functions that may be in use.

These files will normally be found in /etc/asterisk. You will be working in this folder a lot as you configure and administer your Asterisk system.

Modules

Asterisk modules are usually installed to the /usr/lib/asterisk/modules folder. You will not normally have to interact with this folder; however, it will be occasionally useful to know where the modules are located. For example, if you upgrade Asterisk and select different modules during the menuselect phase of the install, the old (incompatible) modules from the previous Asterisk version will not be deleted, and you will get a warning from the install script. Those old files will need to be deleted from the modules folder. This can be done either manually or with the “uninstall” make (make uninstall) target.

The Resource Library

There are several resources that require external data sources. For example, music on hold (MOH) can’t happen unless you have some music to play. System prompts also need to be stored somewhere on the hard drive. The /var/lib/asterisk folder is where system prompts, AGI scripts, music on hold, and other resource files are stored.

The Spool

The spool is where applications store files on a Linux system that are going to change frequently, or that will be processed by other processes at a later time. For example, Linux print jobs and pending emails are normally written to the spool until they are processed.

In Asterisk, the spool is used to store transient items such as voice messages, call recordings,⁶ call files, and so forth.

The Asterisk spool will be found under the /var/spool/asterisk directory.

Logging

Asterisk is capable of generating several different kinds of log files. The /var/log/asterisk folder is where things such as call detail records (CDRs), channel events from CEL, debug logs, queue logs, messages, errors, and other output are written.

This folder will be extremely important for any troubleshooting efforts you undertake. We will talk more about how to make use of Asterisk logs in XXX.

The Dialplan

The dialplan is the heart of Asterisk. All channels that arrive in the system will be passed through the dialplan, which contains the call-flow scripts that determine how incoming calls are handled.

Dialplan is typically written using Asterisk’s own dialplan syntax, which is stored in a file named /etc/asterisk/extensions.conf. There are other ways to control call flow, and we will explore them later, but no matter which method you eventually employ, you will find that a basic understanding of the traditional dialplan will be immensely helpful, and that is what we will focus on for most of the first two-thirds of this book.

Later, we will explore handling call-flow outside of the dialplan, using technologies such as AMI, AGI and ARI.

Hardware

Asterisk is capable of communicating with a vast number of different technologies. In general, these connections are made across a TCP/IP network connection (usually using SIP). However, connections to more traditional telecom circuits, such as PRI (T1, E1 etc), BRI (EuroISDN) SS7 (mostly T1 and E1) and analog (everything from a few FXO and FXS ports, up to large channel banks fed through T1/E1 CAS/RBS connections), can also be achieved using physical cards installed in a server.

Many companies produce this hardware, such as Digium (the sponsor, owner, and primary developer of Asterisk), Sangoma (who recently purchased Digium), Dialogic (also a Sangoma company), OpenVox, Pika, Voicetronix, beroNet, and many others. All of these companies have been involved with Asterisk for many years.

The most popular hardware for Asterisk is generally designed to work through the Digium Asterisk Hardware Device Interface (known as DAHDI). This is a complex architecture, and is out of the scope of this book. Server-based telephony cards will all have installation requirements unique to the manufacturer, and will require you to have strong skills in both Linux hardware installation and, also, traditional PSTN circuit troubleshooting and provisioning.

If you need to interface with traditional PSTN circuits using Asterisk, we recommend that you keep Asterisk as a SIP-only platform, and interface using a third-party gateway of some sort. Be warned; this is not entry level stuff, and if you are just starting out with Asterisk, you are strongly advised to keep your initial solutions to SIP-only.

Asterisk Versioning

The Asterisk release methodology has gone through several styles over time. This has led to some confusion in the past, however these days the versioning is fairly straightforward, and relatively easy to understand. Digium has maintained an excellent reference at the Asterisk wiki, and we encourage you to go there for the latest details on Asterisk versions.

This book was written and tested using version 16, however you will find that the fundamental concepts we explore will be relevant to most Asterisk versions. The conceptual structure of Asterisk has not changed for quite some time, and as of this writing there are no known plans to change that going forward. Future versions will deliver more powerful multimedia and conferencing capabilities, to be sure, but they are likely to be implemented within the existing structure.

Conclusion

Asterisk is composed of many different technologies, most of which are complicated in their own right. As such, the understanding of Asterisk architecture can be overwhelming. Still, the reality is that Asterisk is well-designed for what it does and, in our opinion, has achieved a remarkable balance between flexibility and complexity.

1 A good indicator that you’ve worked with traditional PBXs is the presence of a large callus on your forehead, obtained from smashing your head against a brick wall too many times to count.

² This is command that is available as part of the installation process. We will discuss the use of menuselect in the installation chapter.

³ The term ‘codec’ is short for ‘coder decoder’.

⁴ 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 fewer CPU cycles.

⁵ Some codecs will impose a significant load on the CPU, so much so that a system that might support several hundred channels without transcoding will only handle a few dozen when transcoding is in use.

⁶ Not call detail records (CDRs), but rather audio recordings of calls generated by the MixMonitor() and related applications.