Telephone Naming Concepts

Before we get started with configuring Asterisk for our telephones, we are going to recommend some best practices regarding telephone naming.

First up, you should not assign your telephones an extension number; instead, design the system so that the extension number is assigned to the user, and then assign telephones or other resources to that user. The telephones themselves should be named in reference to something unique to them, such as a MAC address or computer name. In a flexible, next-generation PBX, you want to abstract the concepts of users, extension numbers, and telephones, so as to have the most flexibility and ease of management.

In Asterisk, there is really no concept of a user at all. Extensions are triggers that initiate a sequence of instructions. Yes, you might write a bit of dialplan specifying that when extension number 100 is dialed, Asterisk will ring the phone on your desk. However, extension 100 could just as easily access a company voicemail box, or perhaps play back a prompt, join a conference room, or do any number of other things. We can even write dialplan that specifies that extension 100 should ring the device on your desk from Monday to Friday between 9 A.M. and 5 P.M., but ring a device on someone else’s desk the rest of the time. Inversely, when a call is made from a device during business hours, the caller ID could show a daytime number, and the rest of the time could show an after-hours number (many reception desks become security desks at night).

In Asterisk, extensions are not phones. Therefore, don’t give your telephones identifiers that are extensions.

The abstraction between the name of an extension and the telephone that extension might ring is a powerful concept. An excellent example of this is a PBX feature commonly known as hot-desking, which allows users to share a desk and/or move around to different desks. Let’s say we have three sales agents who typically work outside of the office, but spend a couple of days each month in the office to do paperwork. Since they are unlikely to be on-site at the same time, instead of each agent having a separate telephone, they could share a single office phone (or on a larger scale, a dozen folks could share a pool of, say, three phones). This scenario illustrates the convenience (and necessity) of allowing the system to separate the concept of a user and extension from the physical phone.

The best way to name a physical desk phone (or any physical SIP endpoint) is using the MAC address of the device, which is unique to the phone, follows it where it goes, and doesn’t require configuration changes to the phone if the user changes. Some corporations have stickers they place on their equipment with a bar code and other information that allows them to keep stock of provisioned equipment; these unique codes would also be an acceptable choice to use for phone names, as they don’t provide any logical relation to a particular person, but do provide specific information about the devices themselves.

Softphones on laptops can also use a MAC address or serial number, but make sure the set name includes a reference to the fact that it’s a softphone. [JIM_VANM_SOFT] is a decent name, but [JIMS_PHONE] is not. If the softphone is running on a desk computer (i.e., it’s not going to move around with a user), then name it using the convention you use for your computers ([DESK-5F23-SOFT] or [CUST_SRVC_001_SOFT] are potentially good names).

The choice is yours as to how you want to name your phones. Our goal is simply to help you understand why the best practice is to abstract any concept of the telephone being owned by a person. A phone is just a way to get audio to and from a human, and signal back and forth, so it’s far better to make it possible to mix and match them as users move around, and people come and go.

Throughout this book, you’ll see us using phone names that look like MAC addresses (such as [0000F3000001] and [0000F3000002]), or generic desk names ([DESK-001-SOFT], [DESK-002-SOFT]) to differentiate between devices. You will generally want to use phone names that match the hardware you are using (or some other string that is unique to the device you are registering).

As a final consideration, we should make it clear that what we are suggesting regarding device names is not a technical requirement. You are free to name your devices anything you want, as long as they meet the requirements of Asterisk’s naming conventions for devices (stay with alphanumeric characters with no spaces and you’ll be fine).

You’ll see plenty of Asterisk systems that tie the device name to the extension of the user, but we’re not fans of this method.

Hardphones, Softphones, and ATAs

There are three types of endpoints you would typically provide your users to serve as a telephone set. They are popularly referred to as hardphones (or desk phones), softphones, and Analog Terminal Adaptors (ATAs).

A hardphone is a physical device—an office telephone. It has a handset, numbered buttons, a screen of some sort, and so on. It connects directly to the network and is probably what people are referring to when they talk about a VoIP telephone (or a SIP telephone). It’s normally going to sit on your desk, but it could be mounted on a wall, in an elevator, at a side-table, or in a box by the side of the road.

A softphone is a software application that runs on a laptop, desktop, smartphone, or other computing device. The audio must pass through the device’s sound system, so you normally need a headset that will work well with telephony applications. Softphone applications have become popular with smartphones because they allow you to connect to telephone networks other than just the cellular network (for example, you can register as an extension on your corporate PBX). The interface of the softphone is often styled to look like a physical telephone, but this is not necessary. WebRTC will allow all sorts of additional capabilities in this area, as it essentially allows a softphone to simply be part of a session within a browser. To the PBX, the softphone looks and behaves exactly the same as a hardphone.

An ATA is designed to allow traditional analog telephones (and other analog devices, such as fax machines, cordless phones, paging amplifiers, and such) to connect to a SIP network,¹ and will typically be a sandwich-sized box that contains an RJ-11 connector for the phone (commonly referred to as an FXS port), an RJ-45 connector for the network, and a power connector. Some ATAs may support more than one phone. Other ATAs may have advanced features in them such as a firewall or an FXO port (an analog port that can connect to a PSTN circuit). From the perspective of the PBX, the ATA looks exactly like a SIP telephone.

Hardphones have the advantage that the handsets have good acoustic properties for voice communications. Any decent-quality telephone is engineered to pick up the frequencies of the human voice, filter out unwanted background noise, and normalize the resulting waveform. People have been using telephones for as long as the telephone network has existed, and we tend to like what is familiar, so having a device that communicates with Asterisk using a familiar interface will be attractive to many users. Also, a hardphone does not require your computer to be running all the time.

Disadvantages to hardphones include the fact that they are not easily portable, and they are expensive relative to the many quality softphones on the market today that are available for free. Also, the extra clutter on your desk may not be desirable if you have limited work space. If you move around a lot and are not generally at the same location, a hardphone is not likely to suit your needs (although, one at each location you regularly visit might be a valid solution).

Softphones solve the portability issue by being installed on a device that is likely already moving with you, such as your laptop or smartphone. Also, their minimal cost (typically free, or around $30 for a fully featured one) is attractive. Since many softphones are free, it is likely that the first telephone set you connect to Asterisk will be a softphone. Also, because softphones are just software, they are easy to install and upgrade, and they commonly have other features that utilize other peripherals, like a webcam for video calling, or perhaps an ability to load files from your desktop for faxing. Another potentially huge advantage of a softphone is that it is often possible to integrate them with other applications running on the device.

Some of the disadvantages of softphones are the not-always-on nature of the devices, the necessity to put on a headset each time you take a call, and the fact that many PCs will at random times during the day choose to do something other than what the user wants them to do, which might cause the softphone to stop working while some background task hogs the CPU. In a mobile device, the softphone can consume resources, affecting battery life, performance, and operating expense.

ATAs have the advantage of allowing you to connect analog devices to your SIP network,² such as cordless phones (which are still superior in many cases to more advanced types of wireless phones, and far less expensive³), paging amplifiers, ringers, and antique telephones.⁴ ATAs can also sometimes be used to connect to old wiring, where a network connection might not function correctly, or to outbuildings (such as a gatehouse), where a standard ethernet connection would never reach.

The main disadvantage of an ATA is that you will not get the same features through an analog line as you would from a SIP telephone. This is technology that is over a century old.

With Asterisk, we don’t necessarily need to make the choice between having a softphone, a hardphone, or an ATA; it’s entirely possible and quite common to have a single extension number that rings multiple devices at the same time, such as a desk phone, the softphone on a laptop, a cell phone, and perhaps a strobe light in the back of the factory (where there is too much noise for a ringer to be heard).

More than any other endpoint, the softphone is set to evolve into something far more encompassing than a simple telephone application. The emergence of WebRTC may finally deliver that which has been predicted for many long years: the integration of real-time voice into computing (specifically web-based) applications. There are of course many ways to achieve this already, but WebRTC’s advantage is that it is an open standard, built right into all browsers with no plug-ins required. The softphone is dead; long live the softphone.

We still like a desk phone for regular telephone calls, though.

Configuring Asterisk

In this section we’ll cover how to configure PJSIP to handle various SIP endpoints. This was traditionally done by editing files in the /etc/asterisk/ directory; however, we have elected to demonstrate how this is done through a database, as it is a generally superior method, especially as a system grows. If you are more comfortable with using .conf files, you should find that fairly easy to do once you have the basics figured out.⁵

The channel configuration tables in the database⁶ contain the configuration details relevant to that channel driver, as well as the parameters and credentials specific to the SIP devices and providers you wish to connect to Asterisk (incoming and outgoing). To put that more simply: all calls in and out of Asterisk must pass through a channel.

Most parameters have defaults, which you will find documented in the sample files. Start with reading the pjsip.conf.sample file found in your ~/src/asterisk.<TAB>/configs/samples/ folder. It will provide plenty of information about defaults, as well as information about other resources worth reading. We will not use the file for the actual configuration (we are using the database instead); however, the file is an excellent reference, and you should keep it near at hand, as it will have the answers to many questions you may have about parameters.

We are going to focus on getting a basic device going for you as simply as possible. We have found that setting up channels is one of the more frustrating things new Asterisk users experience, and we want to demonstrate that at its most basic level, it does not need to be painful at all. Once you have succeeded here, you’ll always have a known-good configuration to fall back on, as you move forward into more complex scenarios.

How Channel Configuration Works with the Dialplan

Channels are how Asterisk connects calls to everything outside of it, but it is the dialplan that defines what happens to calls as they pass through the system. Therefore, channels and dialplan are inextricably linked. The dialplan is the heart of an Asterisk system: it controls how call logic is applied to any connection, from any channel, such as what happens when a device dials extension 101, or an incoming call from an external provider is routed to a DID. The PJSIP channel configuration tables in the database, plus the /etc/asterisk/extensions.conf file, will play a critical role in most—if not all—calls routed through the system. Once you have your channels configured, you will find that most of your work will be in the dialplan. We will dive deeply into this in upcoming chapters.

When a call comes into Asterisk, the identity of the incoming call is matched in the channel configuration for the protocol in use (SIP connections are handled by the PJSIP channel driver). The channel driver will handle authenticating the incoming connection. The channel configuration also defines where that channel will enter the dialplan.

Once Asterisk has determined how it will handle the channel (i.e., it’s authenticated and the various parameters for the call have been established), it can pass call control to the correct context in the dialplan. It is the context parameter in the ps_endpoints table that tells the channel where the call will enter the dialplan (which contains all the information about how to handle and route the call).

In Figure 5-2, we see that the call flow through the configuration, for an internal call (set-to-set), will look something like this:

1. User of set 0000f30A0A0101 dials 102.

2. Asterisk matches the incoming SIP request against an endpoint (and authenticates it).

3. The number dialed is matched to the [sets] context in the dialplan.

4. The Dial() application is used to send a call out a PJSIP channel, to the contact associated with 0000f30B0B02.

5. The contact address is determined (typically based on registration if it’s a set, but could be hardcoded as well if it is a trunk).

6. A SIP INVITE message is sent to the destination.

A key point to remember is that the channel configuration files control not only how calls enter the system, but also how they leave the system. So, for example, if one set calls another set, the channel configuration file is used not only to pass the call into the dialplan, but also to direct the call out from the dialplan to the destination.

Figure 5-2. Relationship of pjsip.conf to extensions.conf

$ mysql -D asterisk -u asterisk -p

mysql> select id,transport,aors,auth,context,disallow,allow from asterisk.ps_endpoints;
+--------------+---------------+--------------+--------------+----------+----------+-------+
| id           | transport     | aors         | auth         | context  | disallow | allow |
+--------------+---------------+--------------+--------------+----------+----------+-------+
| 0000f30A0A01 | transport-udp | 0000f30A0A01 | 0000f30A0A01 | starfish | all      | ulaw  |
| 0000f30B0B02 | transport-udp | 0000f30B0B02 | 0000f30B0B02 | starfish | all      | ulaw  |
+--------------+---------------+--------------+--------------+----------+----------+-------+
2 rows in set (0.00 sec)

mysql> insert into asterisk.ps_endpoints 
(id,transport,aors,auth,context,disallow,allow)
values
('SOFTPHONE_A','transport-tls','SOFTPHONE_A','SOFTPHONE_A','sets','all','ulaw'),
('SOFTPHONE_B','transport-tls','SOFTPHONE_B','SOFTPHONE_B','sets','all','ulaw'); 
Query OK, 2 rows affected (0.02 sec) 

mysql> select id,transport,aors,auth,context,disallow,allow from ps_endpoints;
+--------------+---------------+--------------+--------------+---------+----------+-------+
| id           | transport     | aors         | auth         | context | disallow | allow |
+--------------+---------------+--------------+--------------+---------+----------+-------+
| 0000f30A0A01 | transport-udp | 0000f30A0A01 | 0000f30A0A01 | sets    | all      | ulaw  |
| 0000f30B0B02 | transport-udp | 0000f30B0B02 | 0000f30B0B02 | sets    | all      | ulaw  |
| SOFTPHONE_A  | transport-tls | SOFTPHONE_A  | SOFTPHONE_A  | sets    | all      | ulaw  |
| SOFTPHONE_B  | transport-tls | SOFTPHONE_B  | SOFTPHONE_B  | sets    | all      | ulaw  |
+--------------+---------------+--------------+--------------+---------+----------+-------+
4 rows in set (0.00 sec)

mysql> insert into asterisk.ps_aors (id,max_contacts) 
values ('SOFTPHONE_A',2),('SOFTPHONE_B',2);
Query OK, 2 rows affected (0.01 sec) 

mysql> select id from asterisk.ps_aors;
+--------------+
| id           |
+--------------+
| 0000f30A0A01 |
| 0000f30B0B02 |
| SOFTPHONE_A  |
| SOFTPHONE_B  |
+--------------+
4 rows in set (0.00 sec)

insert into asterisk.ps_auths (id,auth_type,password,username) 
values ('SOFTPHONE_A','userpass','iwouldnotifiwereyou','SOFTPHONE_A'), 
('SOFTPHONE_B','userpass','areyoueventrying','SOFTPHONE_B');

Query OK, 2 rows affected (0.00 sec)

mysql> select id,auth_type,password,username
    -> from asterisk.ps_auths;
+--------------+-----------+----------------------+--------------+
| id           | auth_type | password             | username     |
+--------------+-----------+----------------------+--------------+
| 0000f30A0A01 | userpass  | not very secure      | 0000f30A0A01 |
| 0000f30B0B02 | userpass  | hardly to be trusted | 0000f30B0B02 |
| SOFTPHONE_A  | userpass  | iwouldnotifiwereyou  | SOFTPHONE_A  |
| SOFTPHONE_B  | userpass  | areyoueventrying     | SOFTPHONE_B  |
+--------------+-----------+----------------------+--------------+
4 rows in set (0.00 sec)

mysql> exit
$ sudo asterisk -rvvvvv
*CLI> pjsip show endpoints

 Endpoint:  0000f30A0A01                                         Unavailable   0 of inf
     InAuth:  0000f30A0A01/0000f30A0A01
        Aor:  0000f30A0A01                                       2
  Transport:  transport-udp             tls      0      0  0.0.0.0:5061

 Endpoint:  0000f30B0B02                                         Not in use    0 of inf
     InAuth:  0000f30B0B02/0000f30B0B02
        Aor:  0000f30B0B02                                       2
      Contact:  0000f30B0B02/sip:[email protected] 7542ca7ce1 Unknown         nan
  Transport:  transport-udp             udp      0      0  0.0.0.0:5060

 Endpoint:  SOFTPHONE_A                                          Unavailable   0 of inf
     InAuth:  SOFTPHONE_A/SOFTPHONE_A
        Aor:  SOFTPHONE_A                                        2

 Endpoint:  SOFTPHONE_B                                          Unavailable   0 of inf
     InAuth:  SOFTPHONE_B/SOFTPHONE_B
        Aor:  SOFTPHONE_B                                        2

$ sudo vim /etc/asterisk/pjsip.conf

[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0

[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0
cert_file=/home/asterisk/certs/self-signed.crt       #if you used certbot, the location
priv_key_file=/home/asterisk/certs/self-signed.key   #of those keys goes here

*CLI> module reload res_pjsip.so

$ sudo grep -i sealert /var/log/messages |egrep "cert|crt" 

SELinux is preventing ... on the file /home/asterisk/certs/self-signed.crt. 
 For complete SELinux messages run: sealert -l 1dbe51e2-7321-41d3-a5bb-f8f1b4a6f787

SELinux is preventing ... on the directory certs. 
 For complete SELinux messages run: sealert -l 879db542-e0a9-43e8-8763-62fcf068bfee

SELinux is preventing ... on the file self-signed.crt. 
 For complete SELinux messages run: sealert -l 8fb85940-ee82-44bd-adcb-e30d31ee516a

$ sealert -l 8fb85940-ee82-44bd-adcb-e30d31ee516a

SELinux is preventing asterisk from read access on the file self-signed.crt.
*****  Plugin catchall (100. confidence) suggests   **************************
You can generate a local policy module to allow this access.
allow this access for now by executing:
# ausearch -c 'asterisk' --raw | audit2allow -M my-asterisk
# semodule -i my-asterisk.pp

$ sudo ausearch -c 'asterisk' --raw | audit2allow -M my-asterisk

$ sudo semodule -i my-asterisk.pp

*CLI> pjsip show transports
Transport:  <TransportId........>  <Type>  <cos>  <tos>  <BindAddress....................>
==========================================================================================
Transport:  transport-tls             tls      0      0  0.0.0.0:5061
Transport:  transport-udp             udp      0      0  0.0.0.0:5060

Testing to Ensure Your Devices Have Registered

Once your devices have registered to Asterisk, you will be able to query the location and state of them from the Asterisk CLI.

Verifying the registration of a set is the simplest way to verify that you have configured it correctly.

To check the registration status of a device, simply call up the Asterisk CLI:

$ sudo asterisk -rvvvv

Typing the following command returns a listing of all the peers that Asterisk knows about (devices that have registered will have a corresponding Contact):

*CLI> pjsip show aors
      Aor:  <Aor..............................................>  <MaxContact>
    Contact:  <Aor/ContactUri............................> <Hash....> <Status> <RTT(ms)..>
==========================================================================================
      Aor:  0000f30A0A01                                         2

      Aor:  0000f30B0B02                                         2
    Contact:  0000f30B0B02/sip:[email protected]:5 7542ca7ce1 Unknown         nan

      Aor:  SOFTPHONE_A                                          2

      Aor:  SOFTPHONE_B                                          2

A Basic Dialplan to Test Your Devices

In the next chapter we’re going to dive into the Asterisk dialplan. Here, we’re going to lay down a very simple dialplan so that if you register devices to the various SIP endpoints already in the PJSIP configuration, you should be able to make test calls between them.

$ sudo -u asterisk vim /etc/asterisk/extensions.conf

[general]
[globals]

[sets]
exten => 100,1,Dial(PJSIP/0000f30A0A01)

exten => 101,1,Dial(PJSIP/0000f30B0B02)

exten => 102,1,Dial(PJSIP/SOFTPHONE_A)

exten => 103,1,Dial(PJSIP/SOFTPHONE_B)

exten => 200,1,Answer()
     same => n,Playback(hello-world)
     same => n,Hangup()

From your Asterisk console type the following command:

*CLI> dialplan reload

*CLI> dialplan show

You will see that in the context sets there are some extension numbers you can call.

This basic dialplan will allow you to dial your SIP devices using extensions 100, 101, 102, and 103. You can also listen to the hello-world prompt that was created for this book by dialing extension 200.

Register a couple of SIP phones (you can download a softphone to your PC and another one to a tablet or smartphone). You should be able to dial between your extensions. Open up the CLI in order to see the call progression. You should see something like this (and the set you are calling should ring):

    -- Executing [102@sets:1] Dial("PJSIP/SOFTPHONE_A-00000001", "PJSIP/0000f30B0B02") 
    -- Called PJSIP/0000f30B0B02
    -- PJSIP/0000f30B0B02-00000002 is ringing

If this does not happen, review your configuration and registration and ensure you have not made any typos.

If you register a second device (you have four of them now!), you can make test calls between them.

Spend a bit of time on this and make sure you understand it all. It’s all critical to everything that follows.

Under the Hood: Your First Call

In order to get you thinking about what is happening under the hood, we’re going to briefly cover some of what is actually happening with the SIP protocol when two sets on the same Asterisk system call each other.

For the call you just made, the dialogs shown in Figure 5-3 will have taken place.

For more details on how SIP messaging works, please refer to the SIP RFC.

Figure 5-3. SIP dialogs

Conclusion

In this chapter you learned best practices for device naming by abstracting the concepts of users, extension numbers, and devices, and how to define the device configuration and authentication parameters in the channel configuration files. Next, we’ll delve into the magic of Asterisk that is the dialplan, and see how simple things can create great results.