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,1 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, but 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 forthBridging modules—Mechanisms that 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 (Session Initiation Protocol)messaging uses the PJSIP channel drivers
Codec translators—Convert various codecs such as G729, G711, G722, Speex, and so forth
Format interpreters—As above, but relating to files stored in the filesystem
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. You’ll find many other modules in the Asterisk download, but 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.2
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.
| 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 a 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_stasis | Passes call control to an ARI application—many Asterisk developers use this one application, and from there handle all the rest of their development outside of the Asterisk dialplan |
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.
| 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.
| 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 (CSV) 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.
| 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.
| 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 codec3 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.
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). These are listed in Table 2-6.
| Name | Purpose |
|---|---|
codec_alaw | A-law PCM codec used all over the world on the PSTN (except Canada/USA). This codec (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_opus | Intended to replace speex (and vorbis). |
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 ulaw.a 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 pronounced “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, you would need to use a format interpreter to play that recording to any channels not using the GSM codec.4
If you store a recording in several formats simultaneously (such as WAV, GSM, etc.), Asterisk will determine the least costly format5 to use when a channel needs to play that recording.
| 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.
| 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 caller ID |
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.
| 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 Chapter 15 for detailed documentation on setting up database-backed configuration.
| 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.
| 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.
| Name | Purpose |
|---|---|
res_adsi | Provides ADSIa |
res_agi | Provides the Asterisk Gateway Interface (see Chapter 18) |
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_stasis | Ties together the various components of the Stasis application infrastructure |
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 (Table 2-13). 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.
| 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 real-time 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 building tests is available in the “Asterisk Test Suite” 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,6 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 logfiles. The /var/log/asterisk folder is where 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 Chapter 21.
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. 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 as well as 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, but 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, but 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 a result, understanding 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.
2 This is a command that is available as part of the installation process. We will discuss the use of menuselect in the installation chapter.
3 The term codec is short for “coder decoder.”
4 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.
5 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.
6 Not call detail records (CDRs), but rather audio recordings of
calls generated by the MixMonitor() and related
applications.