Push Gateway
This howto will help you to set a Flexisip server up to be used as push gateway.
Push gateways are SIP proxies that are in charge to route INVITE requests to concerned user agents and, should one of those does not answer, send a push notification in order the user be notified that it has an incoming call. Such a proxy have typically no authentication capability and then must be coupled with an authentication able proxy.
Principle
Registration of mobile user agents
Each mobile user agent uses the push gateway as proxy for REGISTER requests. Then, when a user agent starts, a REGISTER request from sip:alice@example.com and to sip:example.com is sent to the push gateway. The contact header of the request contains the resolved URI to use for connecting to the user agent plus several key/value parameters containing all the information needed in order to send a push notification to the mobile device.
Once the REGISTER request comes in the push gateway it is forwarded to the backend server by resolving the domain name of the request URI. Before forwarding, the push gateway replaces the domain of the contact URI by its own IP address and replaces all the URI parameters by a unique parameter called CtRt<random_key> containing the old domain. The random key is generated on Flexisip starting and does not change along the life of the instance. At this moment, no registration is done on the push gateway but the old contact URI is stored into a cache until the backend server send back a response to the REGISTER request.
Next, the backend server receives the REGISTER request coming from the push gateway. Then, it carry out the registration by associating the SIP identity of the user agent to the masqueraded contact URI. So, when the backend server receives INVITE requests addressed to that SIP identity it will forward them to the push gateway.
Once the registration is done, the backend server will send a 200 response to the push gateway. On 200 response receiving, the push gateway update its registration database binding the SIP identity of the user agent with the contact URI with push notification information it has saved before. Then, it forwards the 200 response to the user agent to notify it that the registration is successful.
Incoming calls
The backend server receives an INVITE request addressed to sip:alice@example.com. Then, it checks its registrar DB and find out that it must forward the request to the push gateway. The request URI is substituted by the contact URI found in the registrar DB before sending to the push gateway.
Next, the push gateway receives the INVITE request. Then, it reverse the masquerading by substituting the IP address contained in the request URI by the domain contained in the CtRt parameter. The request URI should be sip:alice@example.com then. So, the push gateway can find out the real contact URI of the user agent by looking for in its registrar DB. Then, the push gateway will firstly try to directly connect to the user agent and send a push notification to the device should does the user agent not answer after a little delay. In that last case, the INVITE request will be sent again as soon as the user agent is registered again.
Outgoing calls
There is two cases:
* Either the user agent does not use the push gateway to send its INVITE request but the backend server directly. Then, we are exactly in the situation described in the section above ;
* Or the push gateway is used as outbound proxy and then it has to be customized in order to do the registrar DB checking only for requests coming from the backend server. That tweak will be detailed later in that wiki.
Requirements for the backend sip server
The flexisip push gateway mode works provided that the backend SIP server meets some reasonable requirements:
- The backend SIP server must record the SIP URI contact address set by the client in the REGISTER as it is, without removing parameters. However, IP address and port may be modified to fix nat issues.
For example, if the client sends a register with Contact: <sip:bob@sip.example.org;someparameter=somevalue>;expires=3600, the registrar of the backend SIP server must route SIP requests to this client with the target uri to be sip:bob@sip.example.org;someparameter=somevalue ; not just sip:bob@sip.example.org, or even worse sip:sip.example.org . - It is better (but not mandatory) if the backend SIP server supports the Path header as defined in RFC3327.
Set up a push gateway with Flexisip
Create a new configuration file for Flexisip with the following command as root:
/opt/belledonne-communications/bin/flexisip --dump-all-default > /etc/flexisip/flexisip.conf
Edit /etc/flexisip/flexisip.conf and check the following settings:
# if user agents connect on the push gateway by using an host name instead of its IP address you must
# add the host name into that list. You can put several host name.
aliases=localhost
# you may change that value if you want your push gateway does not listen on SIP standard ports
transports=sip:*
[module::Registrar]
# the Registrar module must be enabled
enabled=true
# A '*' means the push gateway will register identities whatever the domain.
# That is safe because the registration will be done only if the backend server answers 200 to
# the forwarded REGISTER.
reg-domains=*
# Tell the registrar module to do the registration once the backend server answers 200.
reg-on-response=true
[module::Router]
# That rules must be enabled if you intend to use the push gateway as outbound proxy.
# With that rule, only requests coming from the backend server will enter in the module::Router. The
# others will be forwarded directly. The ''doroute'' tag is automatically inserted into the masqueraded
# contact address by the module::ContactRouteInserter before to be forwarded to the backend server.
# So, requests that will come from the backend server will have a ''doroute'' parameter in their
# request URI.
filter=(is_request && request.uri.params contains 'doroute') || is_response
# do not fail immediately when the push gateway cannot connect to a user agent but wait for a register
# from the last one before trying again.
fork-late=true
[module::PushNotification]
# The push notification module must be enabled of course. Be care to set all the information needed
# by Flexisip to send pushes for each platforms.
# See https://wiki.linphone.org/wiki/index.php/Flexisip:flexisip_configuration#Push_notificationf
enabled=true
# You may change that value if you want the push gateway wait lesser time before sending a push notification
timeout=5
# This module will masquerade contact headers before forwarding a REGISTER request.
# Settings for that module are not displayed in the default configuration file. So, you have
# to add it yourself.
[module::ContactRouteInserter]
enabled=true
# if not true, Flexisip will put the IP address of the user agent in the CtRt parameter instead of
# the domain used in the request URI of the REGISTER.
insert-domain=true