Asterisk pjsip configuration: Difference between revisions

From 탱이의 잡동사니
Jump to navigation Jump to search
No edit summary
 
(9 intermediate revisions by the same user not shown)
Line 13: Line 13:


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 request. 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.
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 request. 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.
== Endpoint matching ==
Depending on the modules loaded, Asterisk can match SIP requests to an endpoint or aor in a few ways:
* Match a section name for endpoint type sections to the username in the "From" header of inbound SIP requests.
* Match a section name for aor type sections to the username in the "To" header of inbound SIP REGISTER requests.
* With an identify type section configured, match an inbound SIP request of any type to an endpoint or aor based on the IP source address of the request.


== Section types ==
== Section types ==
Line 72: Line 79:
cipher=
cipher=
method=
method=
</pre>
=== AUTH ===
provided by module: res_pjsip
Authentication sections hold the options and credentials related to inbound or outbound authentication. You'll associate other section such as endpoints or registrations to this one.
Multiple endpoints or registrations can use a single auth config if needed.
==== Example ====
An example with username and password authentication
<pre>
[auth6001]
type=auth
auth_type=userpass
password=6001
username=6001
</pre>
And then an example with MD5 authentication.
<pre>
[auth6001]
type=auth
auth_type=md5
md5_cred=51e63a3da6425a39aecc045ec45f1ae8
username=6001
</pre>
</pre>


Line 124: Line 157:
</pre>
</pre>


And an example that may work with SIP trunking provider.
<pre>
[mytrunk]
type=registration
transport=simpletrans
outbound_auth=mytrunk
server_uri=sip:sip.example.com
client_uri=sip:1234567890@sip.example.com
retry_interval=60
</pre>
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.
==== Example ====
<pre>
[example2.com]
type=domain_alias
domain=example.com
</pre>
=== ACL ===
provided by module: res_pjsip_acl
The ACL module used by 'res_pjsip'. This module is independent of 'endpoint' 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 ====
A configuration pulling from the acl.conf file:
<pre>
[acl]
type=acl
acl=example_named_acl1
</pre>
A configuration defined in the object itself.
<pre>
[acl]
type=acl
deny=0.0.0.0/0.0.0.0
permit=209.16.236.0
permit=209.16.236.1
</pre>
A configuration where we are restricting based on contact headers instead of IP addresses.
<pre>
[acl]
type=acl
contactdeny=0.0.0.0/0.0.0.0
contactpermit=209.16.236.0
contactpermit=209.16.236.1
</pre>
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.
res_pjsip_endpoint_identifier_ip 모듈에서 사용하는 섹션으로, Asterisk 로 들어오는 Incoming packet 들에 대해 어떻게 Endpoint 를 물릴 것인지를 정의한다. 즉, Incoming request : Endpoint mapper 이다.
만약 정의된 Identify 섹션이 없을 경우, res_pjsip_endpoint_identifier_user 에서 Endpoint 를 찾는 역할을 담당하게 되는데, FROM header 에서 user 부분만을 떼어서 매칭을 시도하게 된다.
==== Example ====
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.
<pre>
[6001]
type=identify
endpoint=6001
match=203.0.113.1
</pre>
=== 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 and 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.
== PJSIP with Proxy ==
<pre>
[myitsp]
type = endpoint
; other stuff
outbound_proxy = sip:192.168.0.1\;lr
</pre>
The proxy URIs have the "lr" parameter added. This is because most proxies these days follow RFC 3261 and are therefore "loose-routing". If it doesn't have it set, you will probably get a 404 response from the proxy. The "\" before the semicolon is important to keep the semicolon from being treated as a comment start character in the config file.
== See also ==
* https://wiki.asterisk.org/wiki/display/AST/PJSIP+Configuration+Sections+and+Relationships
* https://wiki.asterisk.org/wiki/display/AST/PJSIP+with+Proxies - PJSIP with Proxies


[[category:asterisk]]
[[category:asterisk]]

Latest revision as of 12:41, 11 September 2020

Overview

Asterisk pjsip configuration.

Configuration format

[  SectionName ] 
ConfigOption = Value 
ConfigOption = Value

Section names

대부분의 경우, 섹션 이름은 아무렇게나 지정할 수 있다. 예를 들어 transport 이름을 [transport-udp-nat] 와 같이 기억하기 쉽게 지정할 수도 있다.

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

Endpoint matching

Depending on the modules loaded, Asterisk can match SIP requests to an endpoint or aor in a few ways:

  • Match a section name for endpoint type sections to the username in the "From" header of inbound SIP requests.
  • Match a section name for aor type sections to the username in the "To" header of inbound SIP REGISTER requests.
  • With an identify type section configured, match an inbound SIP request of any type to an endpoint or aor based on the IP source address of the request.

Section types

Below is 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.

[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

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)

Reloading Config: Configuration for transport type sections can't be reloading 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

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:

[simpletranst]
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 section such as endpoints or registrations to this one.

Multiple endpoints or registrations can use a single auth config if needed.

Example

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

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 can not 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.

Registration: 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 you hard or soft phone configuration.

Example

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

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.

Example

This example shows you how you might configure registration and outbound authentication against another Asterisk system, where the other system is using the older cahn_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 call, 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 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

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.

Example

[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 'endpoint' 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

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

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.

res_pjsip_endpoint_identifier_ip 모듈에서 사용하는 섹션으로, Asterisk 로 들어오는 Incoming packet 들에 대해 어떻게 Endpoint 를 물릴 것인지를 정의한다. 즉, Incoming request : Endpoint mapper 이다.

만약 정의된 Identify 섹션이 없을 경우, res_pjsip_endpoint_identifier_user 에서 Endpoint 를 찾는 역할을 담당하게 되는데, FROM header 에서 user 부분만을 떼어서 매칭을 시도하게 된다.

Example

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

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

PJSIP with Proxy

[myitsp]
type = endpoint
; other stuff
outbound_proxy = sip:192.168.0.1\;lr

The proxy URIs have the "lr" parameter added. This is because most proxies these days follow RFC 3261 and are therefore "loose-routing". If it doesn't have it set, you will probably get a 404 response from the proxy. The "\" before the semicolon is important to keep the semicolon from being treated as a comment start character in the config file.

See also