How to set up Asterisk

Setting up Asterisk

I've been meaning to set up VoIP services for a long time, but I didn't finally get around to installing Asterisk until late December 2005. It hasn't been easy. At the time of writing, I still don't have a functional configuration. Currently, this page documents some of the problems I've had. I'll update it when I have things working.

The documentation

I started by buying the book Asterisk: The Future of Telephony , from O'Reilly. It was less help than I had hoped; it seems to have been sloppily and hurriedly produced. For example, at the end of Chapter 1, the rest of the book is described with chapter numbers off by one. This text appears to be a duplication of the overview in the Preface, which at least gets the chapter numbers correct. It looks as if Chapter 1 was originally intended to be part of the introduction, which would also have made more sense. Chapter 2 describes how to prepare a system, and chapter 3 explains how to install Asterisk, something that the FreeBSD ports collection does for me, so I started at chapter 4, “Initial Configuration of Asterisk”. Here are some of the issues I've had.

I suppose the first problem is that this chapter shouldn't be there yet. I want to know how Asterisk works. How do SIP, IAX and friends fit together? How does VoIP work at all? How can you configure a system when you don't know how it will work?
I'd assume that a PBX corresponds more to a typical Internet server (for example, a mail transport agent or a web server). The main function must be routing. But Chapter 4 starts with a description of how to configure Zaptel (not part of Asterisk) for a specific VoIP end user card (Digium Dev-Lite, not easily available in Australia) so that you can connect a telephone. It does say that this is optional; but if you don't read the section, you miss what little overview they present of the myriad Asterisk configuration files, as well as more generic information about interfaces.

There are two kinds of interface, with names must be some of the most stupid I've come across:
- An FXO (“Foreign Exchange Office”) interface is what we used to call DTE (“Data Terminal Equipment”): it's the passive end of the link.
- The FXS (“Foreign Exchange Station”) interface is the active end of the link, comparable to DCE (“Data Communications Equipment”). It differs from the FXO by generating a dial tone.
So what's so stupid about these names? Firstly, Foreign Exchange is a well-known term referring to the international currency market; it makes no sense at all to me in this context. Secondly, the terms station and office refer to what I would call a phone and a telephone exchange respectively. There's every reason to believe that the Powers That Be have got the names reversed. This is not any fault of the book, of course, but it's symptomatic for the problems people have to face when setting up VoIP.
If you're configuring only SIP (whatever that may be; this is the first mention I've seen in the book, another problem arising from the missing overview chapter), you continue on page 67, which finally does tell you that SIP means Session Initiation Protocol: it's the signalling part of VoIP. It describes parts of a sip.conf file, the configuration file for SIP. The file isn't the default file installed by Asterisk, which includes lots of comments; instead it's hand written, and the text doesn't even describe all the entries. The first line is
```
context=default
```
It might be reasonable to assume that default is a keyword, but it could equally well be a reference to something in this or another configuration file. It should at least be described in the text; but it isn't. The configuration file distributed with Asterisk, which this book doesn't use, is more informative:
```
context=default                 ; Default context for incoming calls
```
So what kind of context do you use for outgoing calls? It seems that default is, in fact, a name for this particular entry, and there can be more. But I'm not sure of that; another uncertainty which I'm forced to investigate.
The next line is
```
srvlookup=yes
```
The text continues to explain that this means that Asterisk will use DNS SRV records, “a way of setting up a logical, resolvable address where you can be reached.”. And how? No idea. This is the only mention of SRV records in the book, at least as far as I can tell from the index, and it gives no further information. Edwin Groothuis helped: an SRV record looks like this (this is mine):
```
_sip._udp.lemis.com.  3600  IN  SRV   0 0 5060 echunga.lemis.com.
```
This tells us:
- This entry relates to a SIP connection via UDP to the domain lemis.com. SRV records are not VoIP specific: they're a general way of describing network accessible services.
- It expires in 3600 seconds, and it's an Internet domain SRV record (this is the generic syntax for DNS records)
- It has a priority of 0 and order 0. Priority is similar to the priority in an MX record.
- It connects via port 5060 (sip)
- This service is provided by echunga.lemis.com.
The next section tells you how to set up a soft phone, though the Asterisk configuration isn't complete yet. It expects you to test it anyway, which of course fails.

Configuration files

I'm still trying to understand the configuration files. Here's what I have so far:

asterisk.conf describes the directories which asterisk uses.
sip.conf describes the SIP configuration.
iax.conf describes the configutarion for IAX, the protocol that Asterisk servers use when talking to each other. The book does not use the default installed file, but starts again from scratch (on page 73), making it difficult to correlate the entries. difficult to keep up. The book also doesn't describe the entries; the default config file does. For example, there's an entry in the sample file:
```
inkeys=freeworlddialup
```
The book doesn't describe these at all. The corresponding sample configuration file states:
```
If "rsa" authentication is used, "inkeys" is a list of acceptable public keys on the local
system that can be used to authenticate the remote peer, separated by the ":" character.
"outkey" is a single, private key to use to authenticate to the other side.  Public keys
are named /var/lib/asterisk/keys/<name>.pub while private keys are named
/var/lib/asterisk/keys/<name>.key.  Private keys should always be 3DES encrypted.
```
This is the kind of difference which makes me wonder why I bothered to buy the book.
manager.conf describes the Asterisk Manager Interface. It's read in on startup and (according to the comments) on login.
rtp.conf is undocumented beyond stating that it's an RTP configuration file, whatever that might mean. It doesn't seem to need changing.
modules.conf describes the how to handle loadable modules. For some reason it gets read twice.

My setup problems

Armed with such documentation, it's not surprising that I ran into problems. The next problem was that starting Asterisk didn't. Once I found the log files (in FreeBSD they're in in /var/log/asterisk), I found the messages:

Dec 29 11:44:02 WARNING[63086]: Unable to open pseudo channel for timing...  Sound may be choppy.
Dec 29 11:44:02 WARNING[63086]: Unable to lookup 'static'
Dec 29 11:44:02 WARNING[63086]: Unable to open IAX timing interface: No such file or directory
Dec 29 11:44:02 WARNING[63086]: Unable to get our IP address, Skinny disabled
Dec 29 11:44:02 WARNING[63086]: found category [general]
Dec 29 11:44:02 WARNING[63086]: Unable to re-open DSP device: No such file or directory
Dec 29 11:44:02 WARNING[63086]: find_desc could not find <dsp>
Dec 29 11:44:02 NOTICE[63086]: Device dsp not found
Dec 29 11:44:02 WARNING[63086]: chan_oss.so: load_module failed, returning -1
Dec 29 11:44:02 WARNING[63086]: Loading module chan_oss.so failed!

None of these messages made much sense. Why is it a warning to find a category [general]? About the only thing that did make sense was the message Device dsp not found. This system doesn't have a sound card configured; since I didn't want sound, that's not important. More to the point, though, there's nothing in there saying why Asterisk stopped. The book says (p 75):

Note that WARNING and NOTICE messages are not errors; however, ERROR messages should be investigated.

Without any other help, I ran Asterisk under ktrace and finally found a comment in modules.conf:

; Load either OSS or ALSA, not both
; By default, load OSS only (automatically) and do not load ALSA
;
noload => chan_alsa.so
;noload => chan_oss.so

Looking up elsewhere, I discovered that OSS and ALSA are sound card drivers. That makes more sense of the last log message above. After making the following change, I was able to start Asterisk and leave it running.

--- modules.conf-dist   Thu Dec 29 10:32:13 2005
+++ modules.conf        Thu Dec 29 13:03:07 2005
@@ -30,7 +30,7 @@
 ; By default, load OSS only (automatically) and do not load ALSA
 ;
 noload => chan_alsa.so
-;noload => chan_oss.so
+noload => chan_oss.so
 ;
 ; Module names listed in "global" section will have symbols globally
 ; exported to modules loaded after them.

Finally I had things running. It turns out that you can run Asterisk in “console” mode (i.e. not as a daemon). I suppose it's not surprising that it should have its oven views of what the console output should look like:

Emetic printout

Fortunately you can turn these colours off with the -n option.

Conclusion

I can't really conclude yet, of course; I'm not done. But the current state of affairs is that I'm continuing with the book, and the next chapter looks (marginally) better. The book has three authors, something that I've always found a problem. I suspect that chapters 4 and 5 were written by different people. Maybe, by the time I've fought my way through to the end of the book, I'll be happier with it. I'll certainly have more experience.

Greg's diary	Greg's photos	Greg's links	Greg's home page

	$Id: asterisk.html,v 1.2 2005/12/30 02:05:35 grog Exp $