How to configure a SIP endpoint for intra-office calling

Now that you’ve got Asterisk installed and running, it’s time to make it do something useful. In this article, you will implement the simple phone topology shown below:

Image

Here, you will begin diving into the configuration files, including PJSIP and the dialplan that you learned about in the previous article about Asterisk architecture. By the time you’re done, you will have two phones that are connected to Asterisk.

Note: Some commands executed in this article are performed from the Asterisk command prompt. You briefly entered the Asterisk command prompt in the article about installing Asterisk. As a refresher: You can connect to the CLI of a running Asterisk instance by executing asterisk -r from a standard terminal.

Configuring PJSIP

The first thing that you need to configure to deploy the topology is the PJSIP channel driver. The PJSIP channel driver enables Asterisk to handle SIP endpoints, such as the phones that you will connect to your Asterisk server.

To start, Asterisk needs a base config for PJSIP at /etc/asterisk/pjsip.conf. This base configuration, taken directly from the sample config, is just enough for PJSIP to listen on the standard UDP port 5060 for SIP. This setup tells the PJSIP channel driver to create a UDP transport bound to all IP addresses:

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

As always, ensure that you configure firewall rules to only permit access from hosts that you trust.

With a base configuration in place, you can reload the PJSIP module to pick up the changes:

asterisk-1*CLI> pjsip reload
Module 'res_pjsip.so' reloaded successfully.
Module 'res_pjsip_authenticator_digest.so' reloaded successfully.
Module 'res_pjsip_endpoint_identifier_ip.so' reloaded successfully.
Module 'res_pjsip_mwi.so' reloaded successfully.
Module 'res_pjsip_notify.so' reloaded successfully.
Module 'res_pjsip_outbound_publish.so' reloaded successfully.
Module 'res_pjsip_publish_asterisk.so' reloaded successfully.
Module 'res_pjsip_outbound_registration.so' reloaded successfully.
[Nov 26 03:10:33] NOTICE[12996]: sorcery.c:1334 sorcery_object_load: Type 'system' is not reloadable, maintaining previous values
asterisk-1*CLI>

Note that, because of the modular architecture of Asterisk, you don’t need to restart the entire service.

Next, you can check on your transport to ensure that it’s been successfully configured by checking on the PJSIP transports:

asterisk-1*CLI> pjsip show transports

Transport: <TransportId........> <Type> <cos> <tos> <BindAddress....................>
==========================================================================================

Transport: transport-udp udp 0 0 0.0.0.0:5060

Objects found: 1

Hint: Use tab-completion when working in the Asterisk CLI to see the available commands and options.

You now have PJSIP listening on a port, but this fact doesn’t do you much good without having the configuration in place to accept registrations from phones. Phone configuration actually requires that you configure a few sections for each phone. Each phone will need one of the following:

• Endpoint: Endpoints tie together the other parts of the SIP configuration that you will learn about below. You can think of an endpoint as an entity that you want to contact, such as a user’s phone.

• Auth: Auth sections store authentication data, such as a username and password for a SIP endpoint.

• Address of Record (AOR): According to the official Asterisk documentation, an AOR tells Asterisk "where an endpoint can be contacted." For example, the endpoint "Stacy’s phone" might be reachable at IP address 10.100.100.150 (its AOR).

One nice feature of PJSIP configuration is that it supports the idea of templates. If you find yourself reusing the same bits of config (e.g., the same endpoint settings), then you can create a template and reuse it for multiple configuration sections. Take a moment to review the official Asterisk documentation for more information about PJSIP configuration sections and how they relate to each other.

With that general knowledge out of the way, you can begin configuring sections for the two phones in your environment in the /etc/asterisk/psjip.conf file:

[alice-softphone]
type=endpoint
context=office-phones
disallow=all
allow=ulaw
auth=alice-auth
aors=alice-softphone

[alice-auth]
type=auth
auth_type=userpass
username=alice-softphone
password=Secret123

[alice-softphone]
type=aor
max_contacts=1

I won’t cover every piece of configuration here for the sake of time, but a high-level explanation should be sufficient to understand what is going on in this syntax. The first logical section is an endpoint section, as denoted by the type. It tells Asterisk that incoming calls should be placed in the office-phones context (more on contexts later), and the G.711 ulaw codec is the only allowed codec for this endpoint. The endpoint should use the alice-auth authentication section and the alice-softphone AOR. The auth and AOR sections are fairly self-explanatory. The max_contacts option in the AOR tells Asterisk that only one device (e.g., one phone) may be registered to this AOR at one time. Notice how the endpoint section type ties all of the other types together, as you learned earlier. Check out the docs for more information about each of the above options.

The configuration for Bob’s phone is nearly identical, so I won’t duplicate it here. The only difference is obviously the change in name, as well as the use of a different password.

You likely noticed that this configuration does not specify a numerical extension for the user’s phone. If you have worked with traditional phone systems, this is probably a strange concept. Asterisk decouples the actual endpoints (physical phones, softphones, etc.) from the extension in a powerful way. In Asterisk, an extension is simply uniquely identified code that is executed in the Asterisk dialplan when a call is received. You will see what this looks like soon, but for now, let’s focus on getting phones talking to Asterisk.

First, you must reload the PJSIP module to detect your configuration file changes. You can perform this reload exactly as you did with the previous reload with the pjsip reload command. Next, check to ensure that your AORS, auths, and endpoints were successfully configured:

asterisk-1*CLI> pjsip show aors

        Aor: <Aor..............................................> <MaxContact>
        Contact: <Aor/ContactUri............................> <Hash....> <Status> <RTT(ms)..>
==========================================================================================

        Aor: alice-softphone 1

        Aor: bob-softphone 1

Objects found: 2

asterisk-1*CLI> pjsip show auths

  

   I/OAuth: <AuthId/UserName.............................................................>

==========================================================================================

        Auth: alice-auth/alice-softphone
        Auth: bob-auth/bob-softphone

Objects found: 2

asterisk-1*CLI> pjsip show endpoints

  Endpoint: <Endpoint/CID.....................................> <State.....> <Channels.>
        I/OAuth: <AuthId/UserName...........................................................>
        Aor: <Aor............................................> <MaxContact>
        Contact: <Aor/ContactUri..........................> <Hash....> <Status> <RTT(ms)..>
   Transport: <TransportId........> <Type> <cos> <tos> <BindAddress..................>
     Identify: <Identify/Endpoint.........................................................>
        Match: <criteria.........................>
        Channel: <ChannelId......................................> <State.....> <Time.....>
        Exten: <DialedExten...........> CLCID: <ConnectedLineCID.......>
==========================================================================================

Endpoint: alice-softphone Unavailable 0 of inf
        InAuth: alice-auth/alice-softphone
        Aor: alice-softphone 1

Endpoint: bob-softphone Not in use 0 of inf
        InAuth: bob-auth/bob-softphone
        Aor: bob-softphone 1

Objects found: 2

Asterisk has detected the configuration file changes and created the appropriate internal configuration for each new PJSIP section. Next, you need to configure an actual endpoint, such as a phone, to talk with Asterisk.

Configuring a phone

I will be describing the use of Linphone, a free and open-source softphone, that can run directly on your computer. However, you can feel free to use a physical phone or a different type of softphone, if you know how to configure it. SIP accounts in Linphone can be set up with a helpful wizard from the Options -> Preferences -> Manage SIP Accounts menu. Clicking the Wizard button brings you to an initial welcome page:

Image

Proceeding with the wizard will present you with options for the type of account that you want to configure. Because you already created a SIP account on Asterisk, you can select the third option and continue:

Image

The last page of the wizard allows you to enter all of the details for the SIP account that you created in Asterisk. Remember to specify the correct IP address (or DNS name) for the server:

Image

Once you click Apply, you should see a successful registration in the UI. Asterisk will also allow you to verify the registration via the CLI. Remember that an address of record (AOR) tells Asterisk how to contact an individual endpoint. Therefore, if you take a look at the AORs in Asterisk, you will see that a Contact has been associated with the IP address of the remote phone:

asterisk-1*CLI> pjsip show aors

       Aor: <Aor..............................................> <MaxContact>
       Contact: <Aor/ContactUri............................> <Hash....> <Status> <RTT(ms)..>
==========================================================================================

       Aor: alice-softphone 1
       Contact: alice-softphone/sip:alice-softphone@10.100.1 340d949efa NonQual nan

       Aor: bob-softphone 1

Objects found: 2

Now that you have configured a phone for Alice, you can proceed with configuring a phone for Bob. If you are just following along to learn, you can actually add both accounts to the same Linphone instance and it should work just fine. Your test calls will just be to yourself!

Wrapping up

In this article, you learned how to configure the PJSIP channel driver in Asterisk. The PJSIP channel driver allows Asterisk to interact with SIP endpoints, such as a physical phone or a softphone. You learned how to perform enough configuration in both Asterisk and Linphone to connect and verify a softphone client in Asterisk. However, your phones still won’t be able to call each other until the necessary dialplan configuration is in place. I’ll cover that in the next article.