Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 This tuto will help you to set a Flexisip server up to be used as push gateway.
6
7 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 delegate authentication to another proxy, called //backend server//.
8
9 = Principle =
10
11 == Registration of mobile user agents ==
12
13 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.
14
15 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.
16
17 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.
18
19 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.
20
21 [[image:600px-Pushgateway_register.png||height="423" width="600"]]
22
23 == Incoming calls ==
24
25 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.
26
27 [[image:600px-Pushgateway_incoming_call.png||height="413" width="600"]]
28
29 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.
30
31 [[image:600px-Pushgateway_incoming_call_2.png||height="413" width="600"]]
32
33 == Outgoing calls ==
34
35 There is two cases:
36
37 * 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 ;
38 * 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.
39
40 = Requirements for the backend sip server =
41
42 The flexisip push gateway mode works provided that the backend SIP server meets some reasonable requirements:
43
44 * 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.
45 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// .
46 * It is better (but not mandatory) if the backend SIP server supports the Path header as defined in [[RFC3327>>https://tools.ietf.org/html/rfc3327]].
47
48 = Set up a push gateway with Flexisip =
49
50 Create a new configuration file for Flexisip with the following command as root:
51 {{code}}/opt/belledonne-communications/bin/flexisip --dump-all-default > /etc/flexisip/flexisip.conf{{/code}}
52
53 Edit /etc/flexisip/flexisip.conf and check the following settings:
54
55 {{code}}
56 [global]
57
58 # if user agents connect on the push gateway by using an host name instead of its IP address you must
59 # add the host name into that list. You can put several host name.
60 aliases=localhost
61
62 # you may change that value if you want your push gateway does not listen on SIP standard ports
63 transports=sip:*
64
65 [module::Registrar]
66
67 # the Registrar module must be enabled
68 enabled=true
69
70 # A '*' means the push gateway will register identities whatever the domain.
71 # That is safe because the registration will be done only if the backend server answers 200 to
72 # the forwarded REGISTER.
73 reg-domains=*
74
75 # Tell the registrar module to do the registration once the backend server answers 200.
76 reg-on-response=true
77
78
79 [module::Router]
80
81 # That rules must be enabled if you intend to use the push gateway as outbound proxy.
82 # With that rule, only requests coming from the backend server will enter in the module::Router. The
83 # others will be forwarded directly. The ''doroute'' tag is automatically inserted into the masqueraded
84 # contact address by the module::ContactRouteInserter before to be forwarded to the backend server.
85 # So, requests that will come from the backend server will have a ''doroute'' parameter in their
86 # request URI.
87 filter=(is_request && request.uri.params contains 'doroute') || is_response
88
89 # do not fail immediately when the push gateway cannot connect to a user agent but wait for a register
90 # from the last one before trying again.
91 fork-late=true
92
93
94 [module::PushNotification]
95
96 # The push notification module must be enabled of course. Be care to set all the information needed
97 # by Flexisip to send pushes for each platforms.
98 # See https://wiki.linphone.org/wiki/index.php/Flexisip:flexisip_configuration#Push_notificationf
99 enabled=true
100
101 # You may change that value if you want the push gateway wait lesser time before sending a push notification
102 timeout=5
103
104
105 # This module will masquerade contact headers before forwarding a REGISTER request.
106 # Settings for that module are not displayed in the default configuration file. So, you have
107 # to add it yourself.
108 [module::ContactRouteInserter]
109 enabled=true
110
111 # if not true, Flexisip will put the IP address of the user agent in the CtRt parameter instead of
112 # the domain used in the request URI of the REGISTER.
113 insert-domain=true
114 {{/code}}