Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column

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
titleSyntax for res_sip config objects

[  SectionName ]
ConfigOption = Value
ConfigOption = Value

Column
Panel
titleOn this Page

Table of Contents
maxLevel2

Config Section Help and Defaults

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

...

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 "To" 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 "To" 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)

...

Expand
titleEXAMPLE 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)

...

Expand
titleEXAMPLE 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=
privkey_file=
ca_list_file=
cipher=
method=

AUTH

(provided by module: res_pjsip)

...

Expand
titleEXAMPLE 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)

...

Expand
titleEXAMPLE 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)

...

Expand
titleEXAMPLE 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

DOMAIN_ALIAS

(provided by module: res_pjsip)

...

Expand
titleEXAMPLE BASIC CONFIGURATION
Code Block
[example2.com]
type=domain_alias
domain=example.com

ACL

(provided by module: res_pjsip_acl)

...

Expand
titleEXAMPLE 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)

...

Expand
titleEXAMPLE 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.

...