# Asterisk Project : Configuring res_pjsip

Added by rnewton , edited by rnewton on Oct 03, 2013

# Overview

This page is intended to help an Asterisk administrator understand configuration fundamentals for the new SIP resources and channel driver included with Asterisk 12. It covers an explanation of configuration for pjsip.conf which configures the SIP resource modules utilized by the chan_pjsip driver.

If you are looking for info on how to configure sip.conf (the config used by the older SIP channel driver for Asterisk), then you'll want to go here Creating SIP Accounts for some basic info or check out the sip.conf sample file included in the /configs directory of your Asterisk source files.

# Before You Configure

This page assumes certain knowledge, or that you have completed a few prerequisites

- You have installed pjproject, a dependency for res_pjsip.
- You have Installed Asterisk including the res_pjsip and chan_pjsip modules (implying you installed their dependencies as well)
- You understand basic Asterisk concepts. Including the role of extensions.conf (dialplan) in your overall Asterisk configuration.

If you don't know anything about Asterisk yet, then you should probably start at the Getting Started section.

# Quick Start

If you like to play before you read or figure out things as you go; here's a few quick steps to get you started.

- Understand that res_pjsip is configured through pjsip.conf. This is where you'll be configuring everything related to your SIP trunks or phones.
- Look at the Full res_pjsip configuration examples by scenario section. Grab the example most appropriate to your goal and use that to replace your pjsip.conf.
- Reference documentation for all configuration parameters is available on the wiki:
  - Core res_pjsip configuration options
  - Configuration options for ACLs in res_pjsip_acl
  - Configuration options for outbound registration, provided by res_pjsip_outbound_registration
  - Configuration options for endpoint identification by IP address, provided by res_pjsip_endpoint_identifier_ip
- You'll need to tweak details in pjsip.conf and on your SIP device (for example IP addresses and authentication credentials) to get it working with Asterisk.
  Refer back to this page, the sample pjsip.conf, or the reference documentation if you get confused.

# pjsip.conf Explained

### Configuration Section Format

pjsip.conf is a flat text file composed of sections like most configuration files used with Asterisk. Each section defines configuration for a configuration object within res_pjsip or an associated module.

Sections are identified by names in square brackets. (see SectionName below)

Each section has one or more configuration options that can be assigned a value by using an equal sign followed by a value. (see ConfigOption and Value below)These options and values are the configuration for a particular component of functionality provided by the configuration object's respective Asterisk modules.

Every section will have a type option that defines what kind of section is being configured. You'll see that in every example config section below.

Syntax for res_sip config objects

[ SectionName ]
ConfigOption = Value
ConfigOption = Value

### Section Types

Below is a brief description of each section type and an example showing configuration of that section only. The module providing the configuration object related to the section is listed in parentheses next to each section name.

There are dozens of config options for some of the sections, but the examples below are very minimal for the sake of simplicity.

Option Values and Defaults

Icon

How do I know what values I can use for an option? Use the built-in configuration help at the CLI or view the wiki section listing all config option help text. You can use "config show help res_pjsip <configobject> <configoption>" to get help on a particular option. The output will typically describe the default value for an option as well. Link to list of config options goes here, once we have them pulled onto the wiki

Defaults: For many config options, it's very helpful to understand their default behavior. For example, endpoint's "transport=" option, if no value is assigned then Asterisk will *DEFAULT* to the first configured transport in pjsip.conf which is valid for the URI we are trying to contact.

#### ENDPOINT (res_pjsip)

Endpoint configuration provides numerous options relating to core SIP functionality and ties to other sections such as auth, aor and transport. You can't contact an endpoint without associating one or more AoR sections. An endpoint is essentially a profile for the configuration of a SIP endpoint such as a phone or remote server.

EXAMPLE BASIC CONFIGURATION

    [6001]
    type=endpoint
    context=default
    disallow=all
    allow=ulaw
    transport=simpletrans
    auth=auth6001
    aors=6001

If you want to define the Caller Id this endpoint should use, then add something like the following:

    trust_id_outbound=yes
    callerid=Spaceman Spiff <6001>

#### TRANSPORT (res_pjsip)

Configure how res_pjsip will operate at the transport layer. For example, it supports configuration options for protocols such as TCP, UDP or WebSockets and encryption methods like TLS/SSL. You can setup multiple transport sections and other sections (such as endpoints) could each use the same transport, or a unique one.

Icon

Reloading Config: Configuration for transport type sections can't be reloaded during run-time without a full module unload and load. You'll effectively need to restart Asterisk completely for your transport changes to take effect.

EXAMPLE BASIC CONFIGURATION

A basic UDP transport bound to all interfaces

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

Or a TLS transport, with many possible options and parameters:

    [simpletrans]
    type=transport
    protocol=tls
    bind=0.0.0.0
    ;various TLS specific options below:
    cert_file=
    privkey_file=
    ca_list_file=
    cipher=
    method=

#### AUTH (res_pjsip)

Authentication sections hold the options and credentials related to inbound or outbound authentication. You'll associate other sections such as endpoints or registrations to this one. Multiple endpoints or registrations can use a single auth config if needed.

EXAMPLE BASIC CONFIGURATION

An example with username and password authentication

    [auth6001]
    type=auth
    auth_type=userpass
    password=6001
    username=6001

And then an example with MD5 authentication

    [auth6001]
    type=auth
    auth_type=md5
    md5_cred=51e63a3da6425a39aecc045ec45f1ae8
    username=6001

#### AOR (res_pjsip)

A primary feature of AOR objects (Address of Record) is to tell Asterisk where an endpoint can be contacted. Without an associated AOR section, an endpoint cannot be contacted. AOR objects also store associations to mailboxes for MWI requests and other data that might relate to the whole group of contacts such as expiration and qualify settings.

When Asterisk receives an inbound registration, it'll look to match against available AORs.

Registrations: The name of the AOR section must match the user portion of the SIP URI in the "To:" header of the inbound SIP registration. That will usually be the "user name" set in your hard or soft phones configuration.

EXAMPLE BASIC CONFIGURATION

First, we have a configuration where you are expecting the SIP User Agent (likely a phone) to register against the AOR. In this case, the contact objects will be created automatically. We limit the maximum contact creation to 1. We could do 10 if we wanted up to 10 SIP User Agents to be able to register against it.

    [6001]
    type=aor
    max_contacts=1

Second, we have a configuration where you are not expecting the SIP User Agent to register against the AOR. In this case, you can assign contacts manually as follows. We don't have to worry about max_contacts since that option only affects the maximum allowed contacts to be created through external interaction, like registration.

    [6001]
    type=aor
    contact=sip:6001@192.0.2.1:5060

Third, it's useful to note that you could define only the domain and omit the user portion of the SIP URI if you wanted. Then you could define the user portion dynamically in your dialplan when calling the Dial application. You'll likely do this when building an AOR/Endpoint combo to use for dialing out to an ITSP. For example: "Dial(PJSIP/${EXTEN}@mytrunk)"

    [mytrunk]
    type=aor
    contact=sip:203.0.113.1:5060

#### REGISTRATION (res_pjsip_outbound_registration)

The registration section contains information about an outbound registration. You'll use this when setting up a registration to another system whether it's local or a trunk from your ITSP.

EXAMPLE BASIC CONFIGURATION

This example shows you how you might configure registration and outbound authentication against another Asterisk system, where the other system is using the older chan_sip peer setup.

This example is just the registration itself. You'll of course need the associated transport and auth sections. Plus, if you want to receive calls from the far end (who now knows where to send calls, thanks to your registration!) then you'll need endpoint, AOR and possibly identify sections setup to match inbound calls to a context in your dialplan.

    [mytrunk]
    type=registration
    transport=simpletrans
    outbound_auth=mytrunk
    server_uri=sip:myaccountname@203.0.113.1:5060
    client_uri=sip:myaccountname@192.0.2.1:5060
    retry_interval=60

And an example that may work with a SIP trunking provider

    [mytrunk]
    type=registration
    transport=simpletrans
    outbound_auth=mytrunk
    server_uri=sip:sip.example.com
    client_uri=sip:1234567890@sip.example.com
    retry_interval=60

#### DOMAIN_ALIAS (res_pjsip)

Allows you to specify an alias for a domain. If the domain on a session is not found to match an AoR then this object is used to see if we have an alias for the AoR to which the endpoint is binding. This sections name as defined in configuration should be the domain alias and a config option (domain=) is provided to specify the domain to be aliased.

EXAMPLE BASIC CONFIGURATION

    [example2.com]
    type=domain_alias
    domain=example.com

#### ACL (res_pjsip_acl)

The ACL module used by 'res_pjsip'. This module is independent of 'endpoints' and operates on all inbound SIP communication using res_pjsip. Features such as an Access Control List, as defined in the configuration section itself, or as defined in acl.conf. ACL's can be defined specifically for source IP addresses, or IP addresses within the contact header of SIP traffic.

EXAMPLE BASIC CONFIGURATION

A configuration pulling from the acl.conf file:

    [acl]
    type=acl
    acl=example_named_acl1

A configuration defined in the object itself:

    [acl]
    type=acl
    deny=0.0.0.0/0.0.0.0
    permit=209.16.236.0
    permit=209.16.236.1

A configuration where we are restricting based on contact headers instead of IP addresses.

    [acl]
    type=acl
    contactdeny=0.0.0.0/0.0.0.0
    contactpermit=209.16.236.0
    contactpermit=209.16.236.1

All of these configurations can be combined.

#### IDENTIFY (res_pjsip_endpoint_identifier_ip)

Controls how the res_pjsip_endpoint_identifier_ip module determines what endpoint an incoming packet is from. If you don't have an identify section defined, or else you have res_pjsip_endpoint_identifier_ip loading after res_pjsip_endpoint_identifier_user, then res_pjsip_endpoint_identifier_user will identify inbound traffic by pulling the user from the "From:" SIP header in the packet. Basically the module load order, and your configuration will both determine whether you identify by IP or by user.

EXAMPLE BASIC CONFIGURATION

Its use is quite straightforward. With this configuration if Asterisk sees inbound traffic from 203.0.113.1 then it will match that to Endpoint 6001.

    [6001]
    type=identify
    endpoint=6001
    match=203.0.113.1

#### CONTACT (res_pjsip)

The contact config object effectively acts as an alias for a SIP URIs and holds information about an inbound registrations. Contact objects can be associated with an individual SIP User Agent and contain a few config options related to the connection. Contacts are created automatically upon registration to an AOR, or can be created manually by using the "contact=" config option in an AOR section. Manually configuring a CONTACT config object itself is outside the scope of this "getting started" style document.

### Config Section Help and Defaults

Once we have the XML configuration help pulled onto the wiki we'll put a link here to that wiki section.

In the meantime use the built-in configuration help to your advantage. You can use "config show help res_pjsip <configobject> <configoption>" to get help on a particular option. That help will typically describe the default value for an option as well.

### Relationships of Configuration Objects in pjsip.conf

Now that you understand the various configuration sections related to each config object, lets look at how they interrelate.

You'll see that the new SIP implementation within Asterisk is extremely flexible due to its modular design. A diagram will help you to visualize the relationships between the various configuration objects. The following entity relationship diagram covers only the configuration relationships between the objects. For example if an endpoint object requires authorization for registration of a SIP device, then you may associate a single auth object with the endpoint object. Though many endpoints could use the same or different auth objects.

Configuration Flow: This lets you know which direction the objects are associated to other objects. e.g. The identify config section has an option "endpoint=" which allows you to associate it with an endpoint object.

Entity Relationships | Relationship Descriptions
--- | ---
| ENDPOINT Many ENDPOINTs can be associated with many AORs Zero to many ENDPOINTs can be associated with zero to one AUTHs Zero to many ENDPOINTs can be associated with at least one TRANSPORT Zero to one ENDPOINTs can be associated with an IDENTIFY REGISTRATION Zero to many REGISTRATIONs can be associated with zero to one AUTHs Zero to many REGISTRATIONs can be associated with at least one TRANSPORT AOR Many ENDPOINTs can be associated with many AORs Many AORs can be associated with many CONTACTs CONTACT Many CONTACTs can be associated with many AORs IDENTIFY Zero to One ENDPOINTs can be associated with an IDENTIFY object ACL, DOMAIN_ALIAS These objects don't have a direct configuration relationship to the other objects.

# Full res_pjsip configuration examples by scenario

Below are some sample configurations to demonstrate various scenarios with complete pjsip.conf files.

### An endpoint with a single SIP phone with inbound registration to Asterisk

EXAMPLE CONFIGURATION

    ;===============TRANSPORT

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

    ;===============EXTENSION 6001

    [6001]
    type=endpoint
    context=internal
    disallow=all
    allow=ulaw
    transport=simpletrans
    auth=auth6001
    aors=6001

    [auth6001]
    type=auth
    auth_type=userpass
    password=6001
    username=6001

    [6001]
    type=aor
    max_contacts=1

- auth= is used for the endpoint as opposed to outbound_auth= since we want to allow inbound registration for this endpoint
- max_contacts= is set to something non-zero as we want to allow contacts to be created through registration

### A SIP trunk to your service provider, including outbound registration

EXAMPLE CONFIGURATION

Trunks are a little tricky since many providers have unique requirements. Your final configuration may differ from what you see here.

    ;==============TRANSPORTS

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

    ;===============TRUNK

    [mytrunk]
    type=registration
    transport=simpletrans
    outbound_auth=mytrunk
    server_uri=sip:sip.example.com
    client_uri=sip:1234567890@sip.example.com
    retry_interval=60

    [mytrunk]
    type=auth
    auth_type=userpass
    password=1234567890
    username=1234567890

    [mytrunk]
    type=aor
    contact=sip:203.0.113.1:5060

    [mytrunk]
    type=endpoint
    transport=simpletrans
    context=from-external
    disallow=all
    allow=ulaw
    outbound_auth=mytrunk
    aors=mytrunk

    [mytrunk]
    type=identify
    endpoint=mytrunk
    match=203.0.113.1

- "contact=sip:203.0.113.1:5060", we don't define the user portion statically since we'll set that dynamically in dialplan when we call the Dial application.
  See the dialing examples in the section "Dialing using chan_pjsip" for more.

- "outbound_auth=mytrunk", we use "outbound_auth" instead of "auth" since the provider isn't typically going to authenticate with us when calling, but we will probably
  have to authenticate when calling through them.

- We use an identify object to map all traffic from the provider's IP as traffic to that endpoint since the user portion of their From: header may vary with each call.
- This example assumes that sip.example.com resolves to 203.0.113.1

### Multiple endpoints with phones registering to Asterisk, using templates

EXAMPLE CONFIGURATION

We want to show here that generally, with a large configuration you'll end up using templates to make configuration easier to handle when scaling. This avoids having redundant code in every similar section that you create.

     ;===============TRANSPORT

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

    ;===============ENDPOINT TEMPLATES

    [endpoint-basic](!)
    type=endpoint
    transport=simpletrans
    context=internal
    disallow=all
    allow=ulaw

    [auth-userpass](!)
    type=auth
    auth_type=userpass

    [aor-single-reg](!)
    type=aor
    max_contacts=1

    ;===============EXTENSION 6001

    [6001](endpoint-basic)
    auth=auth6001
    aors=6001

    [auth6001](auth-userpass)
    password=6001
    username=6001

    [6001](aor-single-reg)

    ;===============EXTENSION 6002

    [6002](endpoint-basic)
    auth=auth6002
    aors=6002

    [auth6002](auth-userpass)
    password=6002
    username=6002

    [6002](aor-single-reg)

    ;===============EXTENSION 6003

    [6003](endpoint-basic)
    auth=auth6003
    aors=6003

    [auth6003](auth-userpass)
    password=6003
    username=6003

    [6003](aor-single-reg)

Obviously the larger your configuration is, the more templates will benefit you. Here we just break apart the endpoints with templates, but you could do that with any config section that needs instances with variation, but where each may share common settings with their peers.

# Dialing using chan_pjsip

### Dialing from dialplan in extensions.conf

We are assuming you already know a little bit about the Dial application here. To see the full help for it, see "core show help application dial" on the Asterisk CLI, or see Application_Dial

Below we'll simply dial an endpoint using the chan_pjsip channel driver. This is really going to look at the AOR of the same name as the endpoint and start dialing the contacts associated.

    exten => _6XXX,1,Dial(PJSIP/${EXTEN})

Heres how you would dial with an explicit SIP URI, user and domain, via an endpoint (in this case dialing out a trunk), but not using its associated AOR/contact objects.

    exten => _9NXXNXXXXXX,1,Dial(PJSIP/mytrunk/sip:${EXTEN:1}@203.0.113.1:5060)

This uses a contact(and its domain) set in the AOR associated with the mytrunk endpoint, but still explicitly sets the user portion of the URI in the dial string. For the AOR's contact, you would define it in the AOR config without the user name.

    exten => _9NXXNXXXXXX,1,Dial(PJSIP/${EXTEN:1}@mytrunk)

# Old to New - sip.conf to pjsip.conf example comparison

We want to provide some examples of what similar configurations would look like between the old sip.conf and the new pjsip.conf

These examples contain only the configuration required for sip.conf/pjsip.conf as the configuration for other files should be the same excepting the Dial statements in your extensions.conf

There is also a script available to provide a basic conversion of a sip.conf config to a pjsip.conf config. ADD A LINK TO SIP.CONF to PJSIP.CONF SCRIPT WHEN READY

### Example Endpoint Configuration

This examples shows the configuration required for:

- two SIP phones need to make calls to or through Asterisk, we also want to be able to call them from Asterisk
- for them to be identified as users (in the old chan_sip) or endpoints (in the new res_sip/chan_pjsip)
- both devices need to use username and password authentication
- 6001 is setup to allow registration to Asterisk, and 6002 is setup with a static host/contact

sip.conf | pjsip.conf
--- | ---
    [general]
    udpbindaddr=0.0.0.0

    [6001]
    type=friend
    host=dynamic
    disallow=all
    allow=ulaw
    context=internal
    secret=1234

    [6002]
    type=friend
    host=192.0.2.1
    disallow=all
    allow=ulaw
    context=internal
    secret=1234
    [simpletrans]
    type=transport
    protocol=udp
    bind=0.0.0.0

    [6001]
    type = endpoint
    transport = simpletrans
    context = internal
    disallow = all
    allow = ulaw
    aors = 6001
    auth = auth6001

    [6001]
    type = aor
    max_contacts = 1

    [auth6001]
    type=auth
    auth_type=userpass
    password=1234
    username=6001

    [6002]
    type = endpoint
    transport = simpletrans
    context = internal
    disallow = all
    allow = ulaw
    aors = 6002
    auth = auth6002

    [6002]
    type = aor
    contact = sip:6002@192.0.2.1:5060

    [auth6002]
    type=auth
    auth_type=userpass
    password=1234
    username=6001

### Example SIP Trunk Configuration

This shows configuration for a SIP trunk as would typically be provided by an ITSP. That is registration to a remote server, authentication to it and a peer/endpoint setup to allow inbound calls from the provider.

- SIP provider requires registration to their server with a username of "myaccountname" and a password of "1234567890"
- SIP provider requires registration to their server at the address of 203.0.113.1:5060
- SIP provider requires outbound calls to their server at the same address of registration, plus using same authentication details.
- SIP provider will call your server with a user name of "mytrunk". Their traffic will only be coming from 203.0.113.1

sip.conf | pjsip.conf
--- | ---
    [general]
    udpbindaddr=0.0.0.0

    register => myaccountname:1234567890@203.0.113.1:5060

    [mytrunk]
    type=friend
    secret=1234567890
    username=myaccountname
    host=203.0.113.1
    disallow=all
    allow=ulaw
    context=from-external
    [simpletrans]
    type=transport
    protocol=udp
    bind=0.0.0.0

    [mytrunk]
    type=registration
    transport=simpletrans
    outbound_auth=mytrunk
    server_uri=sip:myaccountname@203.0.113.1:5060
    client_uri=sip:myaccountname@192.0.2.1:5060

    [mytrunk]
    type=auth
    auth_type=userpass
    password=1234567890
    username=myaccountname

    [mytrunk]
    type=aor
    contact=sip:203.0.113.1:5060

    [mytrunk]
    type=endpoint
    transport=simpletrans
    context=from-external
    disallow=all
    allow=ulaw
    outbound_auth=mytrunk
    aors=mytrunk

    [mytrunk]
    type=identify
    endpoint=mytrunk
    match=203.0.113.1

# Disabling res_pjsip and chan_pjsip

There are several methods to disable or remove modules in Asterisk. Which method is best depends on your intent.

If you have built Asterisk with the PJSIP modules, but don't intend to use them at this moment, you might consider the following:

1. Edit the file modules.conf in your Asterisk configuration directory. (typically /etc/asterisk/)

       noload => res_pjsip_pubsub.so
       noload => res_pjsip_session.so
       noload => chan_pjsip.so
       noload => res_pjsip_exten_state.so
       noload => res_pjsip_log_forwarder.so

   Having a noload for the above modules should (at the moment of writing this) prevent any PJSIP related modules from loading.

2. Restart Asterisk!

Other possibilities would be:

- Remove all PJSIP modules from the modules directory (often, /usr/lib/asterisk/modules)
- Remove the configuration file (pjsip.conf)
- Un-install and re-install Asterisk with no PJSIP related modules.
- If you are wanting to use chan_pjsip alongside chan_sip, you could change the port or bind interface of your chan_pjsip transport in pjsip.conf

## Attachments:

res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)
res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)
res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)
res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)
res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)
res_sip_configrelationships (application/gliffy+json)
res_sip_configrelationships.png (image/png)