Configuring SIP peers

 

Asterisk can communicate using several different VoIP protocols, as well as interface with telephony hardware for accessing things like analog telephone lines and phones, or digital connections like T1/E1 and ISDN.

We're only going to cover SIP in this primer, which is pretty much the standard VoIP protocol;  If you decide to get service from an ITSP to make and recieve phone calls, it will be over SIP.  For now we can begin setting up and playing with Asterisk without any investment in additional hardware or services, by using softphones - pieces of software that act like physical SIP phones.

This guide assumes that the phone/softphone you will be using is on the same local network as the Asterisk server is on, and that there are no firewalls or NAT routers involved (which we'll cover in a separate section.)  In this example setup, our Asterisk server's IP is going to be 10.0.0.1 and our test phone will be 10.5.5.5.

First, let's start off by configuring the SIP peer entry in Asterisk that a phone can connect to.  Using your favorite text editor, create the file /etc/asterisk/sip.conf and put in the following:

[general]
allowguest=no

[TestPhone-A]
type=peer
host=dynamic
secret=somepassword
context=internal

The [general] section is used to set some global (or general) options, as well as set default options that will automatically apply to all SIP device entries that follow.  We're only setting one general option at the  moment, allowguest=no, which tells Asterisk to reject unauthenticated calls (calls coming from devices which we haven't specifically configured.)

The [TestPhone-A] section is the definition of our first device, called TestPhone-A.  You can generally name your devices almost anything you want (no spaces or odd characters), although there are other considerations which I'm not going to cover for now.

The first option for our device, type, is probably one of the most confusing bits of Asterisk to a new user and the source of the most angst.  When Asterisk receives an INVITE via SIP (a call coming into Asterisk, whether from the outside world or from your desk phone) Asterisk tries to match the call to an entry in sip.conf to determine what it should do with the call.  The type=xxx line controls how Asterisk will try to make that match.  There are three choices; user, peer, and friend.

A user matches incoming calls to a device entry by its name, which is the bit in brackets - [TestPhone-A] in our example - based on the name given in the From: header of the incoming call.  A user entry does not have an IP address associated with it, and as such can only be used to send calls to Asterisk.  That is, Asterisk cannot place a call to a user, it can only receive a call from a userIt's fairly rare to use type=user.

A peer matches incoming calls to a device entry based on the IP and port number the call comes from, which is set with the host and port options (more on this below.)  Because a peer has an IP address and port number associated with it, a peer can be called, unlike a user.

A friend is a combination of both a user and a peer.  Internally Asterisk keeps track of users and peers as two separate lists, and a friend actually creates 2 entries, one in each list; one with a type of user and one with a type of peer.

When Asterisk receives a call, it first tries to match the call to a user by matching its From: name to a device name in the user list, and then failing that, as a peer by matching the IP address and port number to a device in the peer list. 

99% of the time you are going to use type=peer to match by IP/port, and we have here.

In the next line, we have specified host=dynamic which means we don't know the current IP address of the device, possibly because it might often change.  In this case the device must first register to Asterisk in order to inform it of its IP and port number.

So how can a dynamic peer ever register?

If you were paying attention above, you should be saying to yourself "Wait, if a type=peer gets matched by its IP address and port, but we haven't configured an IP for the peer, how can it ever work?"

The device type rules above only apply to INVITE messages, or calls.  When a device sends a REGISTER message to Asterisk, it is handled separately and always gets matched by its device name.

Moving along, we set a password for the device with secret=somepassword, which the device will need in order to successfully authenticate to Asterisk.  All of the typical security practices apply; don't actually use something as lame as "somepassword" for passwords.

Finally, we set context=internal for the device.  The context refers to a section of the dialplan, something we haven't talked about yet (but will in the next section.)  In short, the dialplan is what actually makes Asterisk do something with calls, and contexts allow you to separate what happens to calls that originate from different places.

That's it for our basic device configuration!  However, since we ran Asterisk in the previous section without having made sip.conf first, the SIP channel driver isn't loaded.  We can manually load it without restarting Asterisk.  On the Asterisk console, type

primer*CLI> module load chan_sip

You will see some output indicating the module loaded, parsed sip.conf, and added a bunch of applications and functions to the system.  We can see if the SIP peer we configured was sucessfully added:

primer*CLI> sip show peers
Name/username    Host            Dyn Forcerport ACL Port   Status      Description
TestPhone-A      (Unspecified)    D   a             0      Unmonitored
1 sip peers [Monitored: 0 online, 0 offline Unmonitored: 0 online, 1 offline]

Note the (Unspecified) listed for our TestPhone-A under Host.  Let's actually connect a device up to it.

 

Connecting a SIP device

 

In this tutorial we're going to use a softphone, but it could very well be an actual SIP handset if you have one.  For this example I'm going to use Zoiper Classic which is a free softphone available on multiple platforms, but there are tons of other SIP softphones that will work as well - Blink, 3CXPhone and Linphone to name a few.  The general concepts are all the same no matter which you use.

On the main Zoiper window, hit the wrench icon at the end of the row of buttons, and then click "Add new SIP account" on the left.  Name it whatever you like, perhaps the name you've given to your Asterisk server.

Next, fill in your server and user information.  As mentioned at the top of this page, our test server's IP is 10.0.0.1.  The Username is TestPhone-A, which is the device we created in sip.conf.  Enter your password accordingly from the secret set in sip.conf.  Finally, for Caller ID Name, I've just used "Bob" because that happens to be my name.

zoiper-sip.gif

Click OK to save and return to the main Zoiper window.  At the bottom of the window you should see the account name you added, and if it doesn't say (Registered) next to it, click the Register button.

Looking at the Asterisk console, you should see a message:

-- Registered SIP 'TestPhone-A' at 10.5.5.5:5060

The IP shown would obviously be that of whatever machine you are running the softphone on; the port number could be almost anything but will typically be 5060.  You might have also seen a NOTICE or two that say "Received SIP subscribe for peer without mailbox" which you can safely ignore for now.

If we look at the peer list again, we should see our TestPhone-A showing the newly discovered IP:

primer*CLI> sip show peers
Name/username    Host            Dyn Forcerport ACL Port   Status      Description
TestPhone-A      10.5.5.5         D   A             5060   Unmonitored
1 sip peers [Monitored: 0 online, 0 offline Unmonitored: 1 online, 0 offline]

Hurray!  Your phone successfully registered to Asterisk, which has associated that IP address and port number with the TestPhone-A peer.

Now we need to setup one more crucial thing so our phone can actually do something - the dialplan.