Holy. Shit. Getting a basic Asterisk system set up is a pain in the ass. Not because Asterisk is a shoddy product—it really is awesome—but because there is a certain lack of tutorials and introductory material, and getting help from IRC can be excruciating when the people who hold all of the sacred knowledge talk to you condescendingly.

I’m a Ruby developer and have never wet my feet with telephony. Never. That said, all I wanted to do was get a basic setup and make a few phone calls and feel a little encouraged by having a working system. This task took me about two or three days. Someone on IRC that I spoke with said it took them three months. I hope to ease this enormous barrier to entry for you telephony newbies with a tutorial.

Before the tutorial, I have some general advice when learning Asterisk.

Advice

Unfortunately, the information about Asterisk is scattered. In addition to being scattered, there are a lot of deep and potentially foreign concepts you must learn in order to be proficient with Asterisk. My advice to you is to compile a list of terms and concepts that you find yourself unfamiliar with, then research those terms and concepts and define them in your own words. When you can define the concepts you can confirm that you understand them.

The documentation on the Asterisk website is sparse, so there are sites like voip-info.org which serve to supplement the official documentation. There’s also a book called “Asterisk: The Future of Telephony”. Unfortunately it’s outdated and uses a version older than Asterisk 1.6, but it is still immensely useful. I’d recommend reading through the whole thing and then going back to chapter one when you want to actually experiment with Asterisk. The reason I recommend this is because the Asterisk book is strangely organized, and you will hit roadblocks when attempting to take Asterisk for a test drive because the book clarifies critical information in later chapters.

Google everything. You will need to do a lot of research alongside your Asterisk endeavors. This is mandatory. Otherwise, you will fail. Asterisk is a foreign beast to non-telephony folks, so polish up your Google-fu.

Beware of IRC. As usual, asking questions on IRC might yield condescending responses if you don’t fully understand everything (which seems to defeat the purpose, am I right?). People involved in telephony seem to be grumpy, so take their advice with a grain of salt. They are helpful, but very cranky. You’ve been warned.

On to the tutorial.

Asterisk tutorial

To get the most out of the tutorial, it’s best read from start to finish. Experimenting half-way might yield frustration. If you’re like me, you get impatient and want to experiment incrementally with every new bit of information you acquire. Unfortunately, the tutorial is not organized like this. It’s designed so that the Eureka moment is at the very end. Silly how that works.

For this tutorial I’m going to use the following technologies.

• Ubuntu 10.04
• Asterisk 1.6.2.5-0Ubuntu1 straight from the Lucid Lynx repositories
• Twinkle soft phone

I’m going to install Asterisk on a remote server, and two soft phones (SIP phones) on my desktop. You may have two different soft phones on different computers if you want.

Install Asterisk with sudo apt-get install asterisk. Typically Asterisk is run on a remote server, but if you only have one box, installing it locally is fine too.

Install soft phones. You can install either Ekiga, LinPhone, X-Lite, Twinkle, or whatever soft phone you want that supports SIP. For this tutorial I’m using Twinkle, and I strongly recommend it. I chose Twinkle (sudo apt-get install twinkle) because I can run two instances on one machine, and Twinkle also lets you change the SIP port.

Put the following in your /etc/asterisk/sip.conf file.

[general]
context=default
allowoverlap=no
bindport=5060
bindaddr=0.0.0.0
srvlookup=yes

[blaine]
type=friend
context=phones
host=dynamic

[billy]
type=friend
context=phones
host=dynamic

The entries [billy] and [blaine] define SIP devices. The book’s example names them [1000] and [1001], which look like extensions! Don’t be fooled by the book! You’re not defining extensions, even though the book makes them look like extensions. I have renamed the book’s example entries to [blaine] and [billy] for clarity. Take some time to burn the following into your skull: “sip.conf is where I define SIP devices, extensions.conf is where I define arbitrary extensions”. I made the mistake of getting confused and thinking that I have defined extensions by making entries in my sip.conf file. This is not the case, don’t make my silly mistake.

Great. Thus far Asterisk now knows that you have two SIP phones. What it doesn’t know is what to do with them or how to reach them. That’s where your extensions.conf file comes in. Put the following in your /etc/asterisk/extensions.conf file.

[globals]

[general]
autofallthrough=yes

[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()

[incoming_calls]

[internal]
exten => s,1,Verbose(1|Echo test application)
exten => s,n,Echo()
exten => s,n,Hangup()

exten => 1000,1,Verbose(1|Extension 1000)
exten => 1000,n,Dial(SIP/billy,30)
exten => 1000,n,Hangup()

exten => 1002,1,Verbose(1|Extension 1002)
exten => 1002,n,Dial(SIP/blaine,30)
exten => 1002,n,Hangup()

[phones]
include => internal
include => default

This configuration gives the SIP phone called billy an extension of 1000 and blaine an extension of 1002. I don’t know what the other stuff means because I basically ripped out the example configuration from the book and made minor changes.

Now make Asterisk aware of these changes. Use the Asterisk CLI by doing asterisk -r as root and then enter reload. Now Asterisk not only knows about your SIP phone devices, but it has extensions attached to them. Which means they are now actually reachable.

Once you’re this far, you should be able to configure a couple of soft phones and have them call each other. However; one thing you must watch out for, if you’re trying to configure two soft phones on the same box, they will both try to use the same port and fail will ensue. If you have both soft phones and the Asterisk server running on the same box, all three will be fighting for port 5060. If you’re doing it all on one box, leave the Asterisk server using 5060, and configure the soft phones to use something like 5058 and 5059.

If you’re using Twinkle, fire it up for initial configuration. When I was prompted how I want to configure Twinkle, I chose Profile editor. For the profile name I put “Blaine” and hit OK. The next screen will ask you for your SIP information. Your name can be anything, I put Blaine. The User name is the matching SIP account blaine defined in sip.conf. The Domain is the IP address or host name of the box you have Asterisk sitting on. If Asterisk is running on your local box, put either localhost or 127.0.0.1. Leave the other options blank and hit OK. For this tutorial, at this point after configuring one instance of Twinkle, I launched another, and when asked if I want to start anyway despite Twinkle already running, I selected yes. In my second instance of Twinkle, I was asked to select a profile. I clicked on Editor under the Create profile section. I called my second profile Billy. I put Billy for the Your name field, billy for the User name, and then my Asterisk host name/IP for Domain. I left the rest blank and clicked OK. At the profile selection screen, I clicked System Settings and changed the port to something different than my first running instance of Twinkle and clicked OK. I then checked Billy for my profile and clicked Run.

If you’ve followed me this far, you should have two Twinkle soft phones running on your local box, both on separate ports. Now you need to register these soft phones with Asterisk. Simply select the Registration menu and click Register. This will make Twinkle talk to Asterisk and say: “Hey, I’m here, I’m awake, and I’m ready to take phone calls, but I’m running on a non-standard port, so make note of that please.”

Once both soft phones are registered, you can now put in an extension on the Call line in Twinkle, and click Dial. And once you do, witness the glory of your other soft phone ringing with a status of “Incoming Call”.