We’re going to want extra sound prompts installed instead of just the default core sound

prompts, and in a better-sounding format than GSM. We can do this with the menu-
select system by running make menuselect in the Asterisk source directory. Before ex-
ploring that, though, let’s talk about the different menuselect interfaces.

menuselect interfaces
There are two interfaces available for menuselect: curses and newt. If the libnewt libra-
ries are installed, you will get the blue and red interface shown in Figure 3-1. Otherwise,
by default menuselect will use the curses (black and white) interface shown in Figure 3-2.

The minimum screen size for the curses interface is 80x27, which means
it may not load if you’re using the default terminal size for a simple
distribution installation. This is not a problem when you’re using SSH
to reach the server remotely, as typically your terminal can be resized,
but if you’re working at the terminal directly you may need to have
screen buffers installed to enable a higher resolution, which is not rec-
ommended for a system running Asterisk. The solution is to use the
newt-based menuselect system.

Figure 3-1. menuselect using the newt interface

60 | Chapter 3: Installing Asterisk

Figure 3-2. menuselect using the curses interface

Installing Dependencies for newt-Based menuselect

To get the newt-based menuselect working, you need to have the libnewt development
libraries installed:
• CentOS: sudo yum install libnewt-devel
• Ubuntu: sudo apt-get install libnewt-dev
If you’ve previously used menuselect with the curses interface, you need to rebuild. You
can do this with the following commands:
$ cd ~/src/asterisk-complete/asterisk/1.8.<your version>/
$ cd menuselect
$ make clean
$ ./configure
$ cd ..
$ make menuselect

After that you should have the newt-based interface available to you.

Using menuselect
Run the following commands to start menuselect:
$ cd ~/src/asterisk-complete/asterisk/1.8.<your version>/
$ make menuselect

Base Configuration | 61
You will be presented with a screen such as that in Figure 3-1 or Figure 3-2. You can
use the arrow keys on your keyboard to move up and down. The right arrow key will
take you into a submenu, and the left arrow key will take you back. You can use the
space bar or Enter key to select and deselect modules. Pressing the q key will quit
without saving, while the x key will save your selections and then quit.

Module Dependencies
Modules that have XXX in front of them are modules that cannot be compiled because
the configure script was not able to find the dependencies required (for example, if you
don’t have the unixODBC development package installed, you will not be able to com-
pile func_odbc§). Whenever you install a dependency, you will always need to rerun
configure before you run menuselect, so that the new dependency will be properly lo-
cated. The dependant module will at that point be available in menuselect. If the module
selection still contains XXX, either the configure script is still unable to find the depend-
ency or not all dependencies have been satisfied.

Once you’ve started menuselect, scroll down to Core Sound Packages and press the
right arrow key (or Enter ) to open the menu. You will be presented with a list of
available options. These options represent the core sound files in various languages and
formats. By default, the only set of files selected is CORE-SOUNDS-EN-GSM, which is the
English-language Core Sounds package in GSM format.
Select CORE-SOUNDS-EN-WAV and CORE-SOUNDS-EN-ULAW (or ALAW if you’re outside of North
America or Japan‖), and any other sound files that may be applicable in your network.

The reason we have multiple formats for the same files is that Asterisk
can play back the appropriate format depending on which codec is ne-
gotiated by an endpoint. This can lower the CPU load on a system sig-
nificantly.

After selecting the appropriate sound files, press the left arrow key to go back to the
main menu. Then scroll down two lines to the Extra Sound Packages menu and press
the right arrow key (or Enter ). You will notice that by default there are no packages
selected. As with the core sound files, select the appropriate language and format to be
installed. A good option is probably to install the English sound files in the WAV, ULAW,
and ALAW formats.

§ Which we will cover in Chapter 16, along with many other cool things.
‖ If you want to understand all about mu-law and A-law, you can read the section “Logarithmic
companding” on page 607. All you need to know here is that outside of North America and Japan, A-law is
used.

62 | Chapter 3: Installing Asterisk

Once you’ve completed selecting the sound files, press the x key to save and exit
menuselect. You then need to install your new prompts by downloading them from the
Asterisk downloads site. This is done simply by running make install again:
$ sudo make install
$ sudo chown -R asteriskpbx:asteriskpbx /var/lib/asterisk/sounds/

The files will be downloaded, extracted, and installed into the appropriate location
(/var/lib/asterisk/sounds/<language>/ by default). Your Asterisk server will need to have
a working Internet connection in order to retrieve the files.

Scripting menuselect
Administrators often build tools when performing installations on several machines,
and Asterisk is no exception. If you need to install Asterisk onto several machines, you
may wish to build a set of scripts to help automate this process. The menuselect system
contains command-line options that you can use to enable or disable the modules that
are built and installed by Asterisk.
If you are starting with a fresh checkout of Asterisk, you must first execute the config-
ure script in order to determine what dependencies are installed on the system. Then
you need to build the menuselect application and run the make menuselect-tree com-
mand to build the initial tree structure:
$ cd ~/src/asterisk-complete/asterisk/1.8.<your version>/
$ ./configure
$ cd menuselect
$ make menuselect
$ cd ..
$ make menuselect-tree
Generating input for menuselect ...

For details about the options available, run menuselect/menuselect --help from the top
level of your Asterisk source directory. You will be returned output like the following:
Usage: menuselect/menuselect [--enable <option>] [--disable <option>]
[--enable-category <category>] [--enable-all]
[--disable-category <category>] [--disable-all] [...]
[<config-file> [...]]
Usage: menuselect/menuselect { --check-deps | --list-options
| --list-category <category> | --category-list | --help }
[<config-file> [...]]

The options displayed can then be used to control which modules are installed via the
menuselect application. For example, if you wanted to disable all modules and install
a base system (which wouldn’t be of much use) you could use the command:
$ menuselect/menuselect --disable-all menuselect.makeopts

If you then look at the menuselect.makeopts file, you will see a large amount of text that
displays all the modules and categories that have been disabled. Let’s say you now want
to enable the SIP channel and the Dial() application. Enabling those modules can be

Base Configuration | 63
done with the following command, but before doing that look at the current menuse-
lect.makeopts (after disabling all the modules) and locate app_dial in the MENUSE
LECT_APPS category and chan_sip in the MENUSELECT_CHANNELS category. After executing
the following command, look at the menuselect.makeopts file again, and you will see
that those modules are no longer listed:
$ menuselect/menuselect --disable-all --enable chan_sip \
--enable app_dial menuselect.makeopts

The modules listed in the menuselect.makeopts file are those that will
not be built—modules that are not listed will be built when the make
application is executed.

You can then build the menuselect.makeopts file in any way you want by utilizing the
other commands, which will allow you to build custom installation scripts for your
system using any scripting language you prefer.

Updating Asterisk
If this is your first installation, you can skip ahead to the section “Base Configura-
tion” on page 51. If you’re in the process of updating your system, however, there are
a couple of things you should be aware of.

When we say updating your system, that is quite different from upgrad-
ing your system. Updating your system is the process of installing new
minor versions of the same branch. For example, if your system is run-
ning Asterisk 1.8.2 and you need to upgrade to the latest bug fix version
for the 1.8 branch, which was version 1.8.3, you’d be updating your
system to 1.8.3. In contrast, we use the term upgrade to refer to changes
between Asterisk branches (major version number increases). So, for
example, an upgrade would be going from Asterisk 1.4.34 to Asterisk
1.8.0.

When performing an update, you follow the same instructions outlined in the section
“How to Install It” on page 48.

Additionally, if you’ve checked out a new directory for this version of

Asterisk (versus running svn up on a checked-out branch), and previ-
ously used menuselect to tweak the modules to be compiled, you can
copy the menuselect.makeopts file from one directory to another prior
to running ./configure. By copying menuselect.makeopts from the old
version to the new version, you save the step of having to (de)select all
your modules again.

64 | Chapter 3: Installing Asterisk

The basic steps are:
$ cd ~/src/asterisk-complete/asterisk/1.8.<your version number>/
$ ./configure
$ make
$ make install

You don’t need to run sudo make install because we’ve already set the
directory ownership to the asteriskpbx user. You should be able to install
new files directly into the appropriate directories.

Upon installation, however, you may get a message like the following:
WARNING WARNING WARNING

Your Asterisk modules directory, located at

/usr/lib/asterisk/modules
contains modules that were not installed by this
version of Asterisk. Please ensure that these
modules are compatible with this version before
attempting to run Asterisk.

chan_mgcp.so
chan_oss.so
chan_phone.so
chan_skinny.so
chan_skype.so
codec_g729a.so
res_skypeforasterisk.so

WARNING WARNING WARNING

This warning message is indicating that modules installed in the /usr/lib/asterisk/mod-

ules/ directory are not compatible with the version you’ve just installed. This most often
occurs when you have installed modules in one version of Asterisk, and then installed
a new version of Asterisk without compiling those modules (as the installation process
will overwrite any modules that existed previously, replacing them with their upgraded
versions).
To get around the warning message, you can clear out the /usr/lib/asterisk/modules/
directory prior to running make install. There is a caveat here, though: if you’ve installed
third-party modules, such as commercial modules from Digium (including chan_skype,
codec_g729a, etc.), you will need to reinstall those if you’ve cleared out your modules
directory.
It is recommended that you keep a directory with your third-party modules in it that
you can reinstall from upon update of your Asterisk system. So, for example, you might
create the /usr/src/asterisk-complete/thirdparty/1.8 directory as follows:

Updating Asterisk | 65
 $ cd ~/src/asterisk-complete/
$ mkdir thirdparty/
$ mkdir thirdparty/1.8/

Downloading third-party modules into this directory allows you to easily reinstall those
modules when you upgrade. Just follow the installation instructions for your module,
many of which will be as simple as rerunning make install from the modules source
directory or copying the precompiled binary to the /usr/lib/asterisk/modules/ directory.

Be sure to change the file permissions to match those of the user running
Asterisk!

Common Issues
In this section we’re going to cover some common issues you may run into while
compiling Asterisk, DAHDI, or LibPRI. Most of the issues you’ll run into have to do
with missing dependencies. If that is the case, please review “Software Dependen-
cies” on page 44 to make sure you’ve installed everything you need.

Any time you install additional packages, you will need to run
the ./configure script in your Asterisk source in order for the new package
to be detected.

-bash: wget: command not found

This message means you have not installed the wget application, which is required for
you to download packages from the Asterisk downloads site, for Asterisk to download
sound files, or for DAHDI to download firmware for hardware.

Ubuntu CentOS
$ sudo apt-get install wget $ sudo yum -y install wget

configure: error: no acceptable C compiler found in $PATH

This means that the Asterisk configure script is unable to find your C compiler, which
typically means you have not yet installed one. Be sure to install the gcc package for
your system.

Ubuntu CentOS
$ sudo apt-get install gcc $ sudo yum install gcc

66 | Chapter 3: Installing Asterisk

make: gcc: command not found
This means that the Asterisk configure script is unable to find your C compiler, which
typically means you have not yet installed one. Be sure to install the gcc package for
your system.

Ubuntu CentOS
$ sudo apt-get install gcc $ sudo yum install gcc

configure: error: C++ preprocessor “/lib/cpp” fails sanity check

This error is presented by the Asterisk configure script when you have not installed the
GCC C++ preprocessor.

Ubuntu CentOS
$ sudo apt-get install g++ $ sudo yum install gcc-c++

configure: error: *** Please install GNU make. It is required to build Asterisk!
This error is encountered when you have not installed the make application, which is
required to build Asterisk.

Ubuntu CentOS
$ sudo apt-get install make $ sudo yum install make

configure: *** XML documentation will not be available because the

‘libxml2’ development package is missing.
You will encounter this error when the XML parser libraries are not installed. These
are required by Asterisk 1.8 and later, since console documentation (e.g., when you
run core show application dial on the Asterisk CLI) is generated from XML.

Ubuntu CentOS
$ sudo apt-get install libxml2-dev $ sudo yum install libxml2-devel

configure: error: *** termcap support not found

This error happens when you don’t have the ncurses development library installed,
which is required by menuselect and for other console output in Asterisk.

Ubuntu CentOS
$ sudo apt-get install ncurses-dev $ sudo yum install ncurses-devel

Common Issues | 67
You do not appear to have the sources for the 2.6.18-164.6.1.el5 kernel
installed.
You will get this error when attempting to build DAHDI without having installed the
Linux headers, which are required for building Linux drivers.

Ubuntu CentOS
$ sudo apt-get install linux-headers-`uname -r` $ sudo yum install kernel-devel

E: Unable to lock the administration directory (/var/lib/dpkg/), are you root?

If you encounter this error it’s likely that you forgot to prepend sudo to the start of the
command you were running, which requires root permissions.

Upgrading Asterisk
Upgrading Asterisk between major versions, such as from 1.2 to 1.4 or from 1.6.2 to
1.8 is akin to upgrading an operating system. Once a phone switch is in production, it
is terribly disruptive for that system to be unavailable for nearly any length of time, and
the upgrade of that phone system needs to be well thought-out, planned, and tested as
much as possible prior to deployment. And because every deployment is different, it is
difficult, if not impossible, for us to walk you through a real system upgrade. However,
we can certainly point you in the right direction for the information you require in order
to perform such an upgrade, thereby giving you the tools you need to be successful.
A production Asterisk system should never be upgraded between major versions with-
out first deploying it into a development environment where the existing configuration
files can be tested and reviewed against new features and syntax changes between ver-
sions. For example, it may be that your dialplan relies on a deprecated command and
should be updated to use a new command that contains more functionality, has a better
code base, and will be updated on a more regular basis. Commands that are deprecated
are typically left in the code for backward-compatibility, but issues reported about these
deprecated commands will be given lower priority than issues to do with the newer
preferred methods.
There exist two files that should be read prior to any system upgrade: CHANGES and
UPGRADE.txt, which are shipped with the Asterisk source code. These files contain
details on changes to syntax and other things to be aware of when upgrading between
major versions. The files are broken into different sections that reference things such
as dialplan syntax changes, channel driver syntax changes, functionality changes, and
deprecation of functionality, with suggestions that you update your configuration files
to use the new methods.

68 | Chapter 3: Installing Asterisk

Another thing to consider when performing an upgrade is whether you really need to
perform the upgrade in the first place. If you’re using a long-term support (LTS)# ver-
sion of Asterisk and that version is happily working along for you, perhaps there is no
reason to upgrade your existing production system. An alternative to upgrading the
entire system is simply to add functionality to your system by running two versions
simultaneously on separate systems. By running separate boxes, you can access the
functionality added to a later version of Asterisk without having to disrupt your existing
production system. You can then perform the migration more gradually, rather than
doing a complete system upgrade instantly.
Two parts of Asterisk should be thoroughly tested when performing an upgrade be-
tween major versions: the Asterisk Manager Interface (AMI) and the Asterisk Gateway
Interface (AGI).
These two parts of Asterisk rely on testing your code to make sure any cleanup of syntax
changes in either the AMI or the AGI, or added functionality, does not interfere with
your existing code. By performing a code audit on what your program is expecting to
send or receive against what actually happens, you can save yourself a headache down
the road.
The testing of call detail records (CDRs) is also quite important, especially if they are
relied upon for billing. The entire CDR structure is really designed for simple call flows,
but it is often employed in complex call flows, and when someone reports an issue to
the tracker and it is fixed, it can sometimes have an effect on others who are relying on
the same functionality for different purposes. Asterisk 1.8 now includes channel event
logging (CEL), which is a system designed to get around some of the limitations of CDR
in more complex call flows (such as those that involve transfers, etc.). More information
about CEL is available in “CEL (Channel Event Logging)” on page 537.
Upgrading Asterisk can be a successful endeavor as long as sufficient planning and
testing are carried out prior to the full rollout. In some cases migrating to a separate
physical machine on which you’ve performed testing is preferred, as it can give you a
system to roll back to in case of some failure that can’t be resolved immediately. It’s
the planning, and particularly having a backup plan, that is the most important aspect
of an Asterisk upgrade.

Conclusion
In this chapter we looked at how to install an operating system (one of Ubuntu or
CentOS) and Asterisk itself. We did this securely by installing via sudo and running
Asterisk as the non-root user asteriskpbx. We are well on our way to building a func-
tional Asterisk system that will serve us well. In the following chapters we will explore

#More information about Asterisk releases and their support schedule is available at https://wiki.asterisk.org/
wiki/display/AST/Asterisk+Versions.

Conclusion | 69
how to connect devices to our Asterisk system in order to start placing calls internally
and how to connect Asterisk to outside services in order to place phone calls to end-
points connected to the PSTN and accept calls from those endpoints.

70 | Chapter 3: Installing Asterisk