Versions Compared

Key

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

The PJSIP Configuration Wizard (module res_pjsip_config_wizard) is a new feature in Asterisk 13.2.0.  While the basic basic chan_pjsip configuration objects (endpoint, aor, etc.) allow a great deal of flexibility and control they can also make configuring standard scenarios like like trunk and and user more complicated than than sip.conf and users.conf.  The PJSIP Configuration Wizard aims to ease that burden by providing a single object called 'wizard' that be used to configure most common common chan_pjsip scenarios.

The following configurations demonstrate a simple ITSP scenario.

pjsip_wizard.conf

Code Block
[my-itsp]
type = wizard
sends_auth = yes
sends_registrations = yes
remote_hosts = sip.my-itsp.net
outbound_auth/username = my_username
outbound_auth/password = my_password
endpoint/context = default
aor/qualify_frequency = 15


 

 

 

pjsip.conf

Code Block
[my-itsp]
type = endpoint
aors = my-itsp
outbound_auth = my-itsp-auth
context = default
 
[my-itsp]
type = aor
contact = sip:sip.my-itsp.net
qualify_frequency = 15

[my-itsp-auth]
type = auth
auth_type = userpass
username = my_username
password = my_password

[my-itsp-reg]
type = registration
outbound_auth = my-itsp-auth
server_uri = sip:sip.my-itsp.net
client_uri = sip:my_username@sip.my-itsp.net

[my-itsp-identify]
type = identify
endpoint = my-itsp
match = sip.my-itsp.net

 

 

Both produce the same result.  In fact, the wizard creates standard chan_pjsip objects behind the scenes.  In the above example...

  • An endpoint and aor are created with the same name as the wizard.
  • The 'endpoint/context' and 'aor/qualify_fequency' parameters are added to them.
  • 'remote_hosts' captures the remote host for all objects.
  • A contact for the aor is created for each remote host.
  • 'sends_auth = yes' causes an auth object to be created.
  • 'outbound_auth/username' and 'outbound_auth/password' are added to it.
  • An outbound_auth line is added to the endpoint.
  • 'sends_registrations = yes' causes a registration object to be created.
  • An outbound_auth line is added to the registration.
  • The server_uri and client_uri are constructed using the remote host and username.
  • An identify object is created and a match is added for each remote host.

 

Configuration Reference:

ParameterDescription
typeMust be 'wizard'
sends_auth

Will create an outbound auth object for the endpoint and
registration. At least 'outbound/username' must be specified.

(default = "no")

accepts_auth

Will create an inbound auth object for the endpoint.
At least 'inbound/username' must be specified.

(default = "no")

sends_registrations

Will create an outbound registration object for each
host in remote_hosts.

(default: "no")

remote_hosts

A comma separated list of remote hosts in the form of
<ipaddress | hostname>[:port] [, ... ]
If specified, a static contact for each host will be created
in the aor. If accepts_registrations is no, an identify
object is also created with a match line for each remote host.
Hostnames must resolve to A, AAAA or CNAME records.
SRV records are not currently supported.

(default: "")

transport

The transport to use for the endpoint and registrations
(default: the pjsip default)

server_uri_pattern

The pattern used to construct the registration
server_uri. The replaceable parameter ${REMOTE_HOST} is
available for use.

(default: "sip:${REMOTE_HOST}")

client_uri_pattern

The pattern used to construct the registration client_uri.
The replaceable parameters ${REMOTE_HOST} and
${USERNAME} are available for use.

(default: "sip:${USERNAME}@${REMOTE_HOST}")

contact_pattern

The pattern used to construct the aor contact.
The replaceable parameter ${REMOTE_HOST} is available for use.

(default: "sip:${REMOTE_HOST}")

has_phoneprov

Will create a phoneprov object. If yes, both phoneprov/MAC and phoneprov/PROFILE
must be specified.

(default: "no")

<object>/<parameter>These parameters are passed unmodified to the native object.

 

 

Configuration Notes:

  • Wizards must be defined in 'pjsip_wizard.conf'.
  • An endpoint and aor are created for each wizard.
    • The endpoint and aor are named the same as the wizard.
    • Parameters are passed to them using the 'endpoint/' and 'aor/' prefixes.
    • A contact is added to the aor for each remote host using the contact_pattern.
  • 'sends_auth' causes an 'auth' object to be created.
    • The name will be '<wizard_name>-oauth'.
    • Parameters are passed to it using the 'outbound_auth/' prefix.
    • The endpoint automatically has an 'outbound_auth' parameter added to it.
    • Registrations automatically have an 'outbound_auth' parameter added to them (if registrations are created, see below). 
  • 'accepts_auth' causes an 'auth' object to be created.
    • The name will be '<wizard_name>-iauth'.
    • Parameters are passed to it using the 'inbound_auth/' prefix.
    • The endpoint automatically has an 'auth' parameter added to it.
  • 'sends_registrations' causes an outbound registration object to be created for each remote host.
    • The name will be '<wizard_name>-reg-<n>' where n starts at 0 and increments by 1 for each remote host.
    • Parameters are passed to them using the 'registration/' prefix.
    • You should not use a wizard in situations whereyou need to pass different parameters to each registration.
    • 'server_uri' and 'client_uri' are constructed using their respective patterns using the remote host and 'outbound_auth/username'.
  • If 'accepts_registrations' is specified, 'remote_hosts' must NOT be specified and no contacts are added to the aor.  This causes registrations to be accepted.
  • If 'accepts_registrations' is NOT specified or set to 'no', then an identify object is created to match incoming requests to the endpoint.
    • Parameters are passed to it using the 'identify/' prefix although there really aren't any to pass.
  • If 'has_phoneprov' is specified, a phoneprov object object is created.
    • The name will be '<wizard_name>-phoneprov'.
    • Both 'phoneprov/MAC' and 'phoneprov/PROFILE' must be specified.
  • All created objects must pass the same edit criteria they would have to pass if they were specified discretely.
  • All created objects will have a '@pjsip_wizard=<wizard_name>' parameter added to them otherwise they are indistinguishable from discretely created ones.
  • All created object are visible via the CLI and AMI as though they were created discretely.
  • Wizard created objects can co-exist with discretely created objects.
  • There can be no name collisions between wizard created objects and discretely created objects.

 

Full Examples:

 Phones:

ConfigurationNotes
Code Block
[user_defaults](!)
type = wizard
transport = ipv4
accepts_registrations = yes
sends_registrations = no
accepts_auth = yes
sends_auth = no
endpoint/context = DLPN_DialPlan1
endpoint/allow_subscribe = yes
endpoint/allow = !all,ulaw,gsm,g722
endpoint/direct_media = yes
endpoint/force_rport = yes
endpoint/disable_direct_media_on_nat = yes
endpoint/direct_media_method = invite
endpoint/ice_support = yes
endpoint/moh_suggest = default
endpoint/send_rpid = yes
endpoint/rewrite_contact = yes
endpoint/send_pai = yes
endpoint/allow_transfer = yes
endpoint/trust_id_inbound = yes
endpoint/device_state_busy_at = 1
endpoint/trust_id_outbound = yes
endpoint/send_diversion = yes
aor/qualify_frequency = 30
aor/authenticate_qualify = no
aor/max_contacts = 1
aor/remove_existing = yes
aor/minimum_expiration = 30
aor/support_path = yes
phoneprov/PROFILE = profile1

[1000](user_defaults)
inbound_auth/username = 1000
inbound_auth/password = somepassword

[1001](user_defaults)
endpoint/callerid = User 1 <1001>
endpoint/allow = !all,ulaw
inbound_auth/username = 1001
inbound_auth/password = somepassword
has_phoneprov = yes
phoneprov/MAC = deadbeef4dad

 

This example demonstrates the power of both wizards and templates.

Once the template is created, adding a new phone could be as simple as creating a wizard object
with nothing more than a username and password.  You don't even have to specify 'type' because it's
inherited from the template.

Of course, you can override ANYTHING in the wizard object or specify everything and not use templates at all.

Trunk to an ITSP requiring registration:

ConfigurationNotes
Code Block
[trunk_defaults](!)
type = wizard
transport = ipv4
endpoint/allow_subscribe = no
endpoint/allow = !all,ulaw
aor/qualify_frequency = 30
registration/expiration = 1800
 
[myitsp](trunk_defaults)
sends_auth = yes
sends_registrations = yes
endpoint/context = DID_myitsp
remote_hosts = sip1.myitsp.net,sip2.myitsp.net
accepts_registrations = no
endpoint/send_rpid = yes
endpoint/send_pai = yes
outbound_auth/username = my_username
outbound_auth/password = my_password
 
[my_other_itsp](trunk_defaults)
sends_auth = yes
sends_registrations = yes
endpoint/context = DID_myitsp
remote_hosts = sip1.my-other-itsp.net,sip2.my-other-itsp.net
accepts_registrations = no
endpoint/send_rpid = yes
endpoint/send_pai = yes
outbound_auth/username = my_username
outbound_auth/password = my_password
registration/expiration = 900
registration/support_path = no

This is an example of trunks to 2 different ITSPs each of which has a primary and
backup server.

It also shows most of the endpoint and aor parameters being left at their defaults.

In this scenario, each wizard object takes the place of an endpoint, aor, auth,
identify and 2 registrations.

Trunk between trusted peers:

ConfigurationNotes
Code Block
[trusted-peer](trunk_defaults)
endpoint/context = peer_context
remote_hosts = sip1.peer.com:45060
sends_registrations = no
accepts_registrations = no
sends_auth = no
accepts_auth = no

This one's even simpler. The 'sends_' and 'accepts_' parameters all default to 'no' so you don't really
even have to specify them unless your template has them set to 'yes'.