Section

Column

Tip
Put about a half-page worth of content here. The Table Of Contents will be top-right aligned next to it. Remove this tip!

Overview

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus vel odio ullamcorper, laoreet odio non, tempus orci. Vivamus consectetur risus sit amet augue euismod interdum. Duis consequat rhoncus mi, eu sodales tellus imperdiet non. Duis tempor venenatis nunc in lacinia. Vivamus a blandit elit, id dapibus nibh. Aliquam suscipit nibh in metus sodales, ac ultrices odio sodales.

First Heading

Nullam pulvinar, metus non auctor mollis, sem purus aliquet libero, sit amet ullamcorper tellus tellus id orci. Phasellus auctor at risus eget interdum. Suspendisse potenti. Duis dolor dolor, aliquam non aliquet eget, aliquam ut enim. Donec fringilla cursus dolor et facilisis. Vestibulum vulputate euismod rhoncus. Suspendisse ut lacinia orci, ac accumsan diam. Suspendisse eu dignissim tellus.

item 1
item 2
item 3

Column

Panel

title	On this Page

Table of Contents

maxLevel	2

Second Heading

Nulla sollicitudin velit vitae orci aliquam venenatis. Etiam in leo vel risus porta rutrum. Fusce viverra, dui porttitor viverra ultricies, neque elit cursus ipsum, non pulvinar lectus ipsum et quam. Curabitur eu erat lacinia, congue est et, malesuada lacus. Donec est justo, ullamcorper vel scelerisque vitae, hendrerit sed purus.

first sub-heading

Duis molestie convallis lectus a porta. Vivamus semper, nunc ac interdum faucibus, nibh nunc ultrices felis, consequat condimentum massa risus nec justo. Fusce auctor orci a metus pellentesque, non posuere purus vehicula. In cursus ac tellus in iaculis.

second sub-heading

In mollis eu erat vel consequat. Phasellus sapien leo, venenatis sed tincidunt ut, dictum a arcu. Etiam at justo ornare, imperdiet justo non, sollicitudin diam. Fusce vitae malesuada massa. Integer quam sem, tristique faucibus semper iaculis, porttitor vel arcu.

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.

Panel

title	Syntax for res_sip config objects

[ SectionName ]
ConfigOption = Value
ConfigOption = Value

Column

Panel

title	On this Page

Table of Contents

maxLevel	2

Config Section Help and Defaults

Reference documentation for all configuration parameters is available on the wiki:

The same documentation is available at the Asterisk CLI as well. You can use "config show help <res_pjsip module name> <configobject> <configoption>" to get help on a particular option. That help will typically describe the default value for an option as well.

Tip
Defaults: For many config options, it's very helpful to understand their default behavior. For example, for the endpoint section "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.

Section Names

In most cases, you can name a section whatever makes sense to you. For example you might name a transport [transport-udp-nat] to help you remember how that section is being used.

However, in some cases, (endpoint and aor types) the section name has a relationship to its function. In the case of endpoint and aor their names must match the user portion of the SIP URI in the "From" header for inbound SIP requests. The exception to that rule is if you have an identify section configured for that endpoint. In that case the inbound request would be matched by IP instead of against the user in the "From" header.

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.

ENDPOINT

(provided by module: 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.

Expand

title	EXAMPLE BASIC CONFIGURATION

Code Block
[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:

Code Block
trust_id_outbound=yes callerid=Spaceman Spiff <6001>

TRANSPORT

(provided by module: 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. However, there are a couple caveats for creating multiple transports:

They cannot share the same IP+port or IP+protocol combination. That is, each transport that binds to the same IP as another must use a different port or protocol.
PJSIP does not allow multiple TCP or TLS transports of the same IP version (IPv4 or IPv6).

Info
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.

Expand

title	EXAMPLE BASIC CONFIGURATION

A basic UDP transport bound to all interfaces

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

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

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

AUTH

(provided by module: 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.

Expand

title	EXAMPLE BASIC CONFIGURATION

An example with username and password authentication

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

And then an example with MD5 authentication

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

AOR

(provided by module: 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.

Expand

title	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.

Code Block
[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.

Code Block
[6001] type=aor contact=sip:[email protected]: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)"

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

REGISTRATION

(provided by module: 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.

Expand

title	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.

Code Block
[mytrunk] type=registration transport=simpletrans outbound_auth=mytrunk server_uri=sip:[email protected]:5060 client_uri=sip:[email protected]:5060 retry_interval=60

And an example that may work with a SIP trunking provider

Code Block
[mytrunk] type=registration transport=simpletrans outbound_auth=mytrunk server_uri=sip:sip.example.com client_uri=sip:[email protected] retry_interval=60

What if you don't need to authenticate? You can simply omit the outbound_auth option.

DOMAIN_ALIAS

(provided by module: 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.

Expand

title	EXAMPLE BASIC CONFIGURATION

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

ACL

(provided by module: 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.

Expand

title	EXAMPLE BASIC CONFIGURATION

A configuration pulling from the acl.conf file:

Code Block
[acl] type=acl acl=example_named_acl1

A configuration defined in the object itself:

Code Block
[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.

Code Block
[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

(provided by module: 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.

Expand

title	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.

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

CONTACT

(provided by module: 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.

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

Gliffy Diagram


name	res_sip_configrelationships
pageid	25919621

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.

Expand

title	Unfamiliar with ERD? Click here to see a key...

Image Added

Versions Compared

Old Version 1

New Version Current

Key

Overview

First Heading

Second Heading

first sub-heading

second sub-heading

Configuration Section Format

Config Section Help and Defaults

Section Names

Section Types

ENDPOINT

TRANSPORT

AUTH

AOR

REGISTRATION

DOMAIN_ALIAS

ACL

IDENTIFY

CONTACT

Relationships of Configuration Objects in pjsip.conf

Page History

Versions Compared

Old Version 1

New Version Current

Key

Overview

First Heading

Second Heading

first sub-heading

second sub-heading

Configuration Section Format

Config Section Help and Defaults

Section Names

Section Types

ENDPOINT

TRANSPORT

AUTH

AOR

REGISTRATION

DOMAIN_ALIAS

ACL

IDENTIFY

CONTACT

Relationships of Configuration Objects in pjsip.conf