chan_sip, Asterisk's PJSIP implementation allows for configuration of outbound registrations. Unlike
chan_sip, it is not implemented in an obnoxious way. Like with most concepts in PJSIP configuration, outbound registrations are confined to a configuration section of their own.
A list of outbound registration configuration options can be found on this page. Here is a simple example configuration for an outbound registration to a provider:
This results in the following outbound REGISTER request being sent by Asterisk:
Let's go over how the options were applied to this REGISTER:
server_uriis the actual URI where the registrar is located. If you are registering with a SIP provider, they should give this information to you.
client_uriis used in the To and From headers of the REGISTER. In other words, this is the address of record to which you are binding a contact URI. If registering to a SIP provider, they may require you to provide a specific username in order to identify that the REGISTER is coming from you. Note that the domain of the
client_uriis the same as the server URI. This is common when indicating that the registrar receiving the REGISTER is responsible for the URI being registered to it.
contact_useroption can be seen in the user portion of the URI in the Contact header. This allows for you to control where incoming calls from the provider will be routed. Calls from the provider will arrive in this extension in the dialplan. Note that this option does not relate to endpoint-related options. For information on relating outbound registrations and endpoints, see the following section.
An English translation of the above REGISTER is "Tell the server at sip:email@example.com that when SIP traffic arrives addressed to sip:firstname.lastname@example.org, the traffic should be sent to sip:email@example.com." Note in this example that 10.24.20.249 is the IP address of the Asterisk server that sent the outbound REGISTER request.
Outbound registrations and endpoints
If you examine the configuration options linked in the previous section, you will notice that there is nothing that ties an outbound registration to an endpoint. The two are considered completely separate from each other, as far as Asterisk is concerned. However, it is likely that if you are registering to an ITSP, you will want to receive incoming calls from that provider. This means that you will need to set up an endpoint that represents this provider. An example of such an endpoint configuration can be found here, but it is a bit complex. Let's instead make a simpler one just for the sake of explanation. Assuming the previous registration has been configured, we can add the following:
This represents the bare minimum necessary in order to accept incoming calls from the provider. The
identify section makes it so that incoming SIP traffic from the IP address in the
match option will be associated with the endpoint called
If you also wish to make outbound calls to the provider, then you would also need to add an AoR section so that Asterisk can know where to send calls directed to "my_provider_endpoint".
It is likely that if you are registering to a provider, you will need to provide authentication credentials. Authentication for outbound registrations is configured much the same as it is for endpoints. The
outbound_auth option allows for you to point to a
type = auth section in your configuration to refer to when a registrar challenges Asterisk for authentication. Let's modify our configuration to deal with this:
With this configuration, now if the registrar responds to a REGISTER by challenging for authentication, Asterisk will use the authentication credentials in the provider_auth section in order to authenticate. Details about what options are available in auth sections can be found here in the "auth" section.
Dealing with Failure
Temporary and Permanent Failures
Whenever Asterisk sends an outbound registration and receives some sort of failure response from the registrar, Asterisk makes a determination about whether a response can be seen as a permanent or temporary failure. The following responses are always seen as temporary failures:
- No Response
- 408 Request Timeout
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Server Timeout
- Any 600-class response
In addition, there is an option called
auth_rejection_permanent that can be used to determine if authentication-related rejections from a registrar are treated as permanent or temporary failures. By default, this option is enabled, but disabling the setting means the following two responses are also treated as temporary failures:
- 401 Unauthorized
- 407 Proxy Authentication Required
What is meant by temporary and permanent failures? When a temporary failure occurs, Asterisk may re-attempt registering if a
retry_interval is configured in the outbound registration. The
retry_interval is the number of seconds Asterisk will wait before attempting to send another REGISTER request to the registrar. By default, outbound registrations have a
retry_interval of 60 seconds. Another configuration option,
max_retries, determines how many times Asterisk will attempt to re-attempt registration before permanently giving up. By default,
max_retries is set to 10.
Permanent failures result in Asterisk immediately ceasing to re-attempt the outbound registration. All responses that were not previously listed as temporary failures are considered to be permanent failures. There is one exception when it comes to permanent failures. The
forbidden_retry_interval can be set such that if Asterisk receives a 403 Forbidden response from a registrar, Asterisk can wait the number of seconds indicated and re-attempt registration. Retries that are attempted in this manner count towards the same
max_retries value as temporary failure retries.
Let's modify our outbound registration to set these options to custom values:
In general, this configuration is more lenient than the default. We will retry registration more times, we will retry after authentication requests and forbidden responses, and we will retry more often.
CLI and AMI
You can monitor the status of your configured outbound registrations via the CLI and the Asterisk Manager Interface. From the CLI, you can issue the command
pjsip show registrations to list all outbound registrations. Here is an example of what you might see:
On this particular Asterisk instance, there are two outbound registrations configured. The headers at the top explain what is in each column. The "Status" can be one of the following values:
- Unregistered: Asterisk is currently not registered. This is most commonly seen when the registration has not yet been established. This can also be seen when the registration has been forcibly unregistered or if the registration times out.
- Registered: Asterisk has successfully registered.
- Rejected: Asterisk attempted to register but a failure occurred. See the above section for more information on failures that may occur.
- Stopped: The outbound registration has been removed from configuration, and Asterisk is attempting to unregister.
In addition, you can see the details of a particular registration by issuing the
pjsip show registration <registration name> command. If I issue
pjsip show registration my_provider, I see the following:
This provides the same status line as before and also provides the configured values for the outbound registration.
AMI provides the
PJSIPShowRegistrationsOutbound command that provides the same information as the CLI commands. Here is an example of executing the command in an AMI session:
The command sends
OutboundRegistrationDetail events for each configured outbound registration. Most information is the same as the CLI displays, but there is one additional piece of data displayed: NextReg. This is the number of seconds until Asterisk will send a new REGISTER request to the registrar. In this particular scenario, that number is 0 because the two outbound registrations have reached their maximum number of retries.
The AMI and CLI provide ways for you to manually unregister if you want. The CLI provides the
pjsip send unregister <registration name> command. AMI provides the
PJSIPUnregister command to do the same thing.
At the time of this wiki article writing, it is not possible, nor would it be recommended, to use dynamic realtime for outbound registrations. The code in
res_pjsip_outbound_registration.so, the module that allows outbound registrations to occur, does not attempt to look outside of
pjsip.conf for details regarding outbound registrations. This is done because outbound registrations are composed both of the configuration values as well as state (e.g. how many retries have we attempted for an outbound registration). When pulling configuration from a file, a reload is necessary, which makes it easy to have a safe place to transfer state information or alter configuration values when told that things have changed. With dynamic realtime, this is much harder to manage since presumably the configuration could change at any point.
If you prefer to use a database to store your configuration, you are free to use static realtime for outbound registrations instead. Like with a configuration file, you will be forced to reload (from the CLI,
module reload res_pjsip_outbound_registration.so) in order to apply configuration changes.