Push Gateway

Last modified by Félix Olart on 2025/06/10 12:18
Contents

These instructions will help you to configure a Flexisip server to be used as push gateway.

Push gateways are SIP proxies that are in charge of routing INVITE requests to user agents and, if one of these does not answer, send a push notification to this user agent so it can be notified of the incoming call. Such a proxy typically has no authentication capabilities and then must delegate authentication to another proxy, called the backend server.

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 and several key/value parameters containing all the information needed in order to send a push notification to the mobile device.

Once the REGISTER request is received by 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 instance lifetime. 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 responds to the REGISTER request.

Next, the backend server receives the REGISTER request coming from the push gateway. Then, it carries 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 answer a 200 response to the push gateway. On 200 response receipt, the push gateway updates its registration database binding the SIP identity of the user agent to the contact URI with push notification information it has saved before. Then, it forwards the 200 response to the user agent to notify that the registration is successful.

600px-Pushgateway_register.png

Incoming calls

The backend server receives an INVITE request addressed to sip:alice@example.com. Then, it checks its registrar DB and finds 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.

600px-Pushgateway_incoming_call.png

Next, the push gateway receives the INVITE request. Then, it reverses 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 searching in its registrar DB. Then, the push gateway will first try to directly connect to the user agent and send a push notification to the device if it does not respond after a little delay. In that last case, the INVITE request will be sent again as soon as the user agent registers again.

600px-Pushgateway_incoming_call_2.png

Outgoing calls

There are two cases:

  • The user agent does not use the push gateway to send INVITE requests but the backend server directly. Then, we are exactly in the situation described in the section above.
  • The push gateway is used as an outbound proxy and then has to be customized in order to perform registrar DB checks only for requests coming from the backend server. That tweak will be detailed in that wiki later.

Requirements for the backend SIP server

The Flexisip push gateway mode will work 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 set to 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.

Configure 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:

[global]

# If user agents connect to the push gateway by using a host name instead of its IP address you must
# add the host name into that list. You can put several host names.
aliases=localhost

# You may change that value if you want your push gateway to 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 regardless of the domain.
# That is safe because the registration will be done only if the backend server answers '200' to
# the forwarded REGISTER request.
reg-domains=*

# Instructs the Registrar module to do the registration once the backend server answers '200'.
reg-on-response=true


[module::Router]

# That rule must be enabled if you intend to use the push gateway as the outbound proxy.
# With that rule, only requests coming from the backend server will enter in the Router module.
# All other requests will be forwarded directly. The ''doroute'' tag is automatically inserted into the masqueraded
# contact address by the ContactRouteInserter module before being forwarded to the backend server.
# So, requests coming 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 that last one before trying again.
fork-late=true


[module::PushNotification]

# The push notification module must of course be enabled. Be careful to set all the information needed
# by Flexisip to send push notifications on each platforms.
# See https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/Configuration/Push%20notifications/
enabled=true

# 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