Skip to end of metadata
Go to start of metadata

The PJSIP Configuration Wizard (module res_pjsip_config_wizard) is a new feature in Asterisk 13.2.0.  While the basic chan_pjsip configuration objects (endpoint, aor, etc.) allow a great deal of flexibility and control they can also make configuring standard scenarios like trunk and user more complicated than similar scenarios in 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 chan_pjsip scenarios.

The following configurations demonstrate a simple ITSP scenario.








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:

typeMust be wizard

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

default = no 


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

default = no 


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

default = no


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 = ""


The transport to use for the endpoint and registrations

default = the pjsip default


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

default = sip:${REMOTE_HOST}


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}}}


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

default = sip:${REMOTE_HOST}


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

default = no 


Enables the automatic creation of dialplan hints.

Two entries will be created.  One hint for 'hint_exten' and one application to execute
when 'hint_exten' is dialed.

hint_contextThe context into which hints are placed.
hint_extenThe extension this hint will be registered with.

An application with parameters to execute when 'hint_exten' is dialed.

Example: Gosub(stdexten,${EXTEN},1(${HINT}))

These parameters are passed unmodified to the native object.



Configuration Notes:

  • Wizards must be defined in pjsip_wizard.conf.
  • Using pjsip_wizard.conf doesn't remove the need for pjsip.conf or any other config file.
  • Transport, system and global sections still need to be defined in pjsip.conf.
  • You can continue to create discrete endpoint, aor, etc. objects in pjsip.conf but there can be no name collisions between wizard created objects and discretely created objects.
  • 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 and ${REMOTE_HOST}.
  • 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 ${REMOTE_HOST} and ${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.
    • The name will be <wizard_name>-identify.
    • 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.
  • has_hint causes hints to be automatically created.
    • hint_exten 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.

Full Examples:



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:


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:


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.

  • No labels


  1. Max

    Does pjsip_wizard.conf completely replace pjsip.conf or "type = transport" should still go there?

    1. The wizard only processes type=wizard so all other types must go in pjsip.conf


      1. Max

        Thanks! IT would be nice to clarify what's the minimum set of files required in /etc/asterisk/ in order to use pjsip_wizard.conf. Do I need sorcery.conf? pjsip_notify.conf? anything else?

        1. Good point.  I'll fix the page up this week.


  2. Max

    There are multitude of asterisk gui/web management tools out there. Are there any which understand pjsip_wizard.conf?

    1. As far as I know, there aren't any tools which use the wizard.