Asterisk - Telephony on OpenBSD

[Ref: OpenBSD 5.5, Asterisk 11.9 (from ports), Asterisk the Definitive Guide, Secure Communications with OpenBSD and Asterisk, Asterisk: The Future of Telephony, pkg_add(1)]

Using your OpenBSD Host as the office Voice over IP hub has been supported through the Ports system for a good while. Asterisk has been updated regularly for a number of years. The following is one way of getting an Asterisk PBX up and running, confirming that the PBX answers your call.

The Internet is your friend, but it can also lead us astray, one thing to look out for is to ensure that the instructions you find are relevant to the version of the software you have installed. Asterisk has been around for a long time and guides relevant for one version can be misleading, totally incorrect when applied to an earlier or later version.

Online Reference documentation that are clear on which versions of Asterisk they document include:

The OReilly Book: Asterisk: The Future of Telephony is online in two editions, one each for releases 1.6 and 1.8.

The Asterisk WIKI

The Asterisk Doxygen [1.8 up to 2015]

When in doubt about options/features, the above documentation is a good reference to review other documentation available on the internet (including this one.)

Package Install

The simplest installation process begins with the OpenBSD package system (as noted above.)

For our development/test installation we will install the below packages. You can always install more (or less) now and later.

Package(s) Description
asterisk open source multi-protocol PBX and telephony toolkit
asterisk-core-sounds core sound files for Asterisk.
Pick the language(s) you wish to install (to start with, use all files in your language)
asterisk-extra-sounds additional sound files for Asterisk.
asterisk-g729 G.729a voice codec for Asterisk
asterisk-moh-opsound opsound music-on-hold for Asterisk (use all codecs)
asterisk-openbsd-moh OpenBSD songs for music-on-hold
sox Sound eXchange, the Swiss Army knnife of audio manipulation
We use this with tweeking our voicemail volume.
speex patent-free speech codec

The packages install their dependencies and give fair warning of additional information you need to review. Basic information is usually at:

  • /var/db/pkg/package-name/DESCR

More information may be available in

  • /usr/local/share/doc/pkg-readmes
  • /usr/local/share/doc/examples

You can trim and expand on the above modules once you have more confidence.

System Resources

[Ref: login.conf(5)]

A fully operational PBX uses up a fair amount of system resources. The following is how we can redefine available resource allocation for Asterisk through login.conf

File extract: /etc/login.conf

asterisk:\
    :openfiles-cur=512:\
    :openfiles-max=65535:\
    :tc=daemon:
Sites with very large /etc/login.conf files may wish to create a database version of the file, 
/etc/login.conf.db, for improved performance. Using a database version for small files does not 
result in a performance improvement. To build /etc/login.conf.db from /etc/login.conf the following 
command may be used:

[Ref: cap_mkdb(1)]

# [ -f /etc/login.conf.db ] && cap_mkdb /etc/login.conf

[Ref: vipw(8), usermod(8)]

Ensure that our local user account is using the new filesize limits. Use vipw(8), or usermod(8) "-L login-class" to set the login class:

$ sudo usermod -L asterisk _asterisk

vipw(8) screen-output extract /etc/passwd:

_asterisk:*************:545:545:asterisk:0:0:PBX Phone System:/var/spool/asterisk:/bin/ksh

DNS

[Ref: resolv.conf(5)]

DNS, Name Resolution matters. Make sure you have configured your name resolution correctly.

File extract: /etc/resolv.conf

search example.com
nameserver ip-address-1
nameserver ip-address-2
lookup file bind

[Ref: hostname.if(5)]

File extract: /etc/hostname.nic1

inet host-ip-address host-ip-netmask host-ip-broadcast

[Ref: hosts(5)]

File extract: /etc/hosts

127.0.0.1       localhost
::1             localhost
host-ip-address pbxhost.example.com pbxhost

Initial Start

To verify the base installation is working, run Asterisk in foreground mode ("-c" control console) with some "-v verbose" output so we can take a peak into it's activities.

$ sudo /usr/local/sbin/asterisk -cvvv

If Asterisk has been successfully installed, you should see a screen response such as the below:

...
...
Asterisk Ready.

Run the Asterisk CLI module show command, to list the number of modules installed in your configuration.

Asterisk Ready.
*CLI> module show
... very long list ...
203 modules loaded

Woohoo, Asterisk has been successfully installed, together with some modules we want to use (if we knew how to use them.)

Stop

We stop Asterisk to continue our installation using core stop now

*CLI> core stop now

Obviously, that's not something you want to do during production, as the command will literally shutdown all services (which means all current calls will be terminated.)

The standard way of starting Asterisk is through the provided rc.d(1) scripts. We either start Asterisk together with the system start up in rc.conf.local or at the command-line.

$ sudo /etc/rc.d/asterisk start

Monitoring

[Ref Logging, Logging Format, /var/log/asterisk/messages]

Monitoring the console, and asterisk log files will get you to stable environment faster.

There will be errors in our configuration, make use of the information Asterisk gives you..

Address ERROR log entries.

At this early stage, we can safely ignore some errors (such as complaints about missing configuration for different options like iax.conf and gtalk.conf) when we are intentionally not using those 'features' and can safely ignore related errors.

Log extract: /var/log/asterisk/messages

DATE NOTICE[id] chan_sip.c: Peer 'XYZ' is now Reachable. (5ms /2000ms)
...
DATE ERROR[id] chan_gtalk.c: Unable to read config file gtalk.conf. Not loading module.
DATE ERROR[id] chan_jingle.c: Unable to load config file jingle.conf. Not loading module.
...
DATE ERROR[id] chan_sip.c: !!! use the global 'nat' settings and do not set 'nat' per peer/user.
...
DATE NOTICE[id] chan_sip.c: The 'username' field for sip peers has been deprecated in favor of the term 'defaultuser'

Startup Scripts

[Ref rc.d(8)]

The OpenBSD pkg_add(8) installation creates the Asterisk rc.d(8) startup script:

  • /etc/rc.d/asterisk

Configure automatic start/shutdown daemons through the pkg_scripts" variable in the file: */etc/rc.conf.local

File extract: /etc/rc.conf.local

pkg_scripts="asterisk"

A standardised method for starting, stopping, and reloading Asterisk is with the provided script.

  • /etc/rc.d/asterisk

ReadMe files

OpenBSD packages store customisation/installation in readme files stored under: /usr/local/share/doc/pkg-readmes.

It is advisable you at least browse:

  • asterisk
  • asterisk-g729

When there's a conflict between these instructions and the pkg-readmes, follow the official documentation.

Indications

[Ref: Install]

The wonderful thing about the packaged system, is that it basically just works. You can refer to the documentation and update the basic configuration.

One real basic configuration, that is unlikely to break your system, is setting the type of ringtone for your phones. I'd never thought that different countries could pick any random sequence of tones as a national standard?

There isn't a 'designated' standard for Tonga, so I'm just picking a 'standard'

File: /etc/asterisk/indications.conf

country=au

The "country" option is related to further [au], [gb] 'definitions' in the file, so you can't just pick a random two letter acronym and expect it to work.

Connect a Device

Before a device can successfully send and recieve calls Asterisk must be made aware of the device. This is done by having our phone/device 'register' with the Asterisk server.

  • Softphones are Software based phones.
  • Hardphones are hardware devices.

Devices connect and communicate with Asterisk over a 'channel'. SIP (configured in sip.conf) is the commonstandard for registering devices, and Asterisk also supports an independent protocol IAX2 (configured in iax.conf).

This guide mostly deals with SIP, and many of the configuration settings have equivalents in IAX.

SIP

[Ref: sip docs]

The documentation, and sample files are discussed in part below where we are going to use an extension [100].

The sip.conf file format is an INI file format where we have categories (such as a device registered name/extension) defined in square brackets "[" and "]" with fields and their values separated by an equal sign.

File: /etc/asterisk/sip.conf

[general]
disallow=all
allow=ulaw,alaw

[100]
type=friend
secret=SuperSecret1
host=dynamic
directmedia=yes
qualify=yes
mailbox=100
context=default

[101]
type=friend
secret=SuperSecretA
host=dynamic
directmedia=yes
qualify=yes
mailbox=100
context=default

The shows two device name/extensions 100 and 101 (inside square brackets) with configuration values such as:

  • type=friend
  • secret= (unknown password)

Reload SIP Configuration

Asterisk only reads the configuration files on start up. When you make changes to configuration settings, you need to force Asterisk to reload those configurations. We want to use the Asterisk console, so to reload the SIP configuration file we can do the following:

$ sudo asterisk -rvvv
Asterisk Ready.
*CLI> sip reload
...

Softphone

To test our PBX, we'll configure a soft phone with the above extension number.

Jitsi

We'll use the Jitsi SIP client and monitor the registration process by using the "console" output as abov.

Start Asterisk (if it isn't already running) and connect to the console

$ sudo /etc/rc.d/asterisk start
$ sudo asterisk -rvvv

You can also monitor the log output at /var/log/asterisk/messages

Basic configuration for Jitsi 1.0
  • File --> Add New Account
  • Network: --> select: SIP
  • Username/Password:
    • Username: 100@ip-address-of-asterisk-host
    • Password: <<something>> as above
    • click: Add

After successfully configuring your Jitsi client, you should see the console report:

   -- Registered SIP '100' at my-ip-address:5060
[Mnth DD HH:MM:SS:] **NOTICE**[9939]: **chan_sip.c:20788 handle_response_peerpoke:** Peer '100' is now Reachable.
*CLI> sip show peers
Name/username        Host                          Dyn Forceport   ACL  Port  Status
100/100              (my-ip-address)                D    N              5060  OK (22 ms)
101                  (unspecified)                  D    N              0     UNKNOWN
*CLI> sip show peer 100
Name           : 100
...
...
User Reason    : No
Encryption     : No

Validate Connection

With only our one device connected, you can 'ring' the device from the console command

  • console dial ${EXTEN}
1 voip2*CLI> console dial 100
   -- Called SIP/100
    -- SIP/100-0000001c is ringing
1 voip2*CLI> channel originate SIP/100 application Playback tt-monkeys
    -- Called 100
    -- SIP/100-0000001d is ringing
    -- SIP/100-0000001d answered
    --  Playing 'tt-monkeys.slin' (language 'en')

Connect a Call

[Ref: Dial Plans. extensions.conf]

The nice thing about the OpenBSD package installation is that is very bare, the bad thing about the OpenBSD package installation is that it is very bare.

SIP is used for registrating users/devices, but calls are interpreted and actioned using Dial Plans. The default dial plan is configured in ./extensions.conf

; extensions.conf - the Asterisk dial plan
;
; Static extension configuration file, used by
; the pbx_config module. This is where you configure all your
; inbound and outbound calls in Asterisk.
;
; This configuration file is reloaded
; - With the "dialplan reload" command in the CLI
; - With the "reload" command (that reloads everything) in the CLI    

Configure and connect another device (as per above for 100) to 101 so two devices are connected.

You can now use one device to call the other. With two SIP devices registered to our PBX, we can use the Asterisk console to connect two devices together.

File extract: /etc/asterisk/extensions.conf

1 [default]
2 exten => _100,1,Dial(SIP/100,60) 
3 exten => _101,1,Dial(SIP/101,60)

After you have both devices (100 and 101) registered/connected, you should be able to dial from one device to the other.

Beginning

Hopefully the above has provided you with some assistance in getting Asterisk up and running on your preferred Operating System.

This is only the beginning.