Hide last authors
François Grisez 6.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
Simon Morlat 14.1 2 {{toc/}}
François Grisez 6.1 3 {{/box}}
François Grisez 10.1 5 The Flexisip Presence server is a SIP user-agent handling SUBSCRIBE/NOTIFY for the "presence" event. It implements the following RFCs:
Simon Morlat 1.1 6
7 * [[Session Initiation Protocol (SIP)-Specific Event Notification>>https://tools.ietf.org/html/rfc3265]] the base RFC for SUBSCRIBE/NOTIFY request.
8 * [[A Presence Event Package for the Session Initiation Protocol (SIP)>>https://tools.ietf.org/html/rfc3856]]
9 * [[Session Initiation Protocol (SIP) Event Notification Extension for Resource Lists>>https://tools.ietf.org/html/rfc4662]]
Simon Morlat 1.2 10 * [[Subscriptions to Request-Contained Resource Lists in the Session Initiation Protocol (SIP)>>https://tools.ietf.org/html/rfc5367]]
11 * [[Session Initiation Protocol (SIP) Extension for Event State Publication>>https://tools.ietf.org/html/rfc3903]]
12 * [[Presence Information Data Format (PIDF)>>https://tools.ietf.org/html/rfc3863]]
13 * [[RPID: Rich Presence Extensions to the Presence Information Data Format (PIDF)>>https://tools.ietf.org/html/rfc4480]]
Simon Morlat 1.1 14
François Grisez 11.1 15 The overall behavior of the presence server is quite simple: it receives SIP SUBSCRIBEs from clients that wish to receive presence information for an individual contact URI, or a list of URIs that represents a set of SIP contacts. The presence server processes the target URIs for which presence information is requested, and generates a SIP NOTIFY request back to the clients containing the presence information.
François Grisez 10.1 16
Simon Morlat 1.7 17 The presence information is obtained from two different sources:
François Grisez 7.1 18
19 * from PUBLISH requests received by clients, that directly publish their presence information on a regular basis. This presence information is called "short term presence".
François Grisez 10.1 20 * from the authentication database of the Flexisip. Because this database contains the list of SIP users that are member of the service, it allows to distribute to clients a long term reachability information about other users. Independently of the whether users are actively using their SIP application, the fact that some SIP users exist or not in the list of users that have registered an account on the SIP service gives a useful indication about their reachability. This presence information is referred as "long term presence".
Simon Morlat 1.7 22 The two sources are queried in that order: first long term presence, then short term presence. Then a presence PIDF+RPID document describing the results of the two sources is synthesized and send within a SIP NOTIFY.
Simon Morlat 1.1 23
Simon Morlat 1.7 24 = Operation in GNU/Linux =
Simon Morlat 1.1 25
François Grisez 10.1 26 From a system perspective, the presence server runs as a daemon in its own process, and hence has no adherence on the proxy from an execution standpoint. It can be started, stopped, restarted using usual SystemD commands, for example:
Simon Morlat 1.1 27
Simon Morlat 1.7 28 {{code language="sh"}}
Simon Morlat 1.1 29 systemctl status flexisip-presence
Simon Morlat 1.7 30 {{/code}}
Simon Morlat 1.1 31
32 It can of course be started from a terminal, for example:
Simon Morlat 1.7 34 {{code language="sh"}}
35 /opt/belledonne-communications/bin/flexisip --server presence --debug
36 {{/code}}
Simon Morlat 1.1 37
François Grisez 10.1 38 The configuration of the presence server is read by default from ///etc/flexisip/flexisip.conf//, mainly from the [[//[presence-server]// section>>doc:Flexisip.A\. Configuration Reference Guide.master.presence-server]].
Simon Morlat 1.1 39
Simon Morlat 1.7 40 = The presence server in the SIP network =
Simon Morlat 1.1 41
François Grisez 10.1 42 The presence server itself performs no authentication, no request integrity checking, no DoS protection, which are tasks left to the proxy server. Furthermore, it listens only on SIP/TCP. It is then recommended to configure the presence server to listen on a private IP address or localhost, so that it cannot be reached directly from the internet.
Simon Morlat 1.1 43
François Grisez 10.1 44 Instead, all requests shall first go through the Flexisip proxy server, that can then forward presence related requests to the the presence server thanks to the [[**Presence**>>doc:Flexisip.A\. Configuration Reference Guide.master.module.Presence]] module of the proxy. This module is in charge to recognize presence-related requests and forwards them to the presence server's URI.
Simon Morlat 1.7 46 = Using long-term presence =
Simon Morlat 1.1 47
François Grisez 10.1 48 The long-term presence information is obtained by querying the database setup in the [[//module::Authentication//>>doc:Flexisip.A\. Configuration Reference Guide.master.module.Authentication]] section of //flexisip.conf//, using the same SQL request as the configured to obtain passwords for a given user. In addition, the long-term information can be obtained through an alias indirection such as the e164 phone number of users. Indeed, users can typically be invited to register to the SIP service by providing two pieces of information:
François Grisez 8.1 49
50 * a username that they choose
51 * a phone number, usually verified thanks to a short code sent by SMS.
François Grisez 10.1 53 A typical use case for a communication app running on a phone is then to be able from the phone's address book to identify phone numbers that are part of the SIP service. This can be done thanks to the "long term presence" ability to use the alias indirection, according to the following flow:
Simon Morlat 1.7 54
François Grisez 10.1 55 ~1. the SIP client sends a SIP SUBSCRIBE with a self-contained resource list (RFC5367) containing SIP URIs with "phone=" parameter, containing all the phone numbers of the address book, for example:
Simon Morlat 1.7 56
57 {{code language="xml"}}
59 <resource-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:ietf:params:xml:ns:resource-lists">
Simon Morlat 1.1 60 <list>
61 <entry uri="sip:+195XXXXXXXX@sip.linphone.org;user=phone"/>
62 <entry uri="sip:+332XXXXXXXX@sip.linphone.org;user=phone"/>
63 <entry uri="sip:+33XXXXXXXXX@sip.linphone.org;user=phone"/>
64 ...
65 </list>
66 </resource-lists>
Simon Morlat 1.7 67 {{/code}}
Simon Morlat 1.1 68
François Grisez 10.1 69 2. The presence server extracts the phone numbers, and queries the authentication database (as setup in module::Authentication) to search for these phone numbers and return the list of SIP users matching these numbers. When the authentication database is configured to use the soci connector, the '//soci-users-with-phones-request//' SQL request is executed to obtain such list.
Simon Morlat 1.1 70
Simon Morlat 1.7 71 3. the presence server generates and sends a NOTIFY request including a PIDF+RPID body, containing the list of matched phone numbers and their associated SIP URI as a <contact> XML element, as well as the presence their associated presence information. The body is by default compressed to save bandwidth.
Simon Morlat 1.1 72
François Grisez 10.1 73 = Using resource lists =
Simon Morlat 1.1 74
François Grisez 10.1 75 Despite individual SUBSCRIBEs are supported, they are not an efficient way to obtain other users' presence in a real deployment. Indeed, for each contact in the address book for a given user, a SIP SUBSCRIBE will be generated, creating a dialog, and then NOTIFY requests will be received to get the presence of each contact. For that reason, the use of resource lists (RFC4662) by clients is highly recommended.
Simon Morlat 1.1 76
François Grisez 10.1 77 Resource lists can be of two types in the presence server.
Simon Morlat 1.1 78
Simon Morlat 1.7 79 == Dynamically client provided resources lists ==
François Grisez 10.1 81 These are self-contained resource lists as described in [[RFC5367>>https://tools.ietf.org/html/rfc5367]]. This use case is the typical one for a SIP service where users have an address book already populated on their phones. Should the local address book be updated by the user, a new SUBSCRIBE can be sent to reflect the change. To save bandwidth, the SIP user-agent may compress the SIP body with the standard "deflate" encoding.
Simon Morlat 1.7 82
83 == Server known resource lists ==
François Grisez 10.1 85 The SIP user-agent is configured to SUBSCRIBE to a URI identified resource list, such as "sip:bob-list@company.example.org". The user-agent has no idea about the elements of this list, but the server knows. When receiving such a SUBSCRIBE for URI identified resource list, the presence server can query a SQL database to obtain the list of SIP contacts that are part of the list. Then, presence information (long term, short term) is queried following the same process as for SUBSCRIBE self-contained resource lists.
Simon Morlat 1.7 86
Simon Morlat 14.1 87 The '//rls-database-connection// and '//rls-database-request'// properties of the //[presence-server]// section of the configuration define respectively the database connection and the SQL request to execute to obtain the content of the resource list. Please note that the SIP identity of the subscriber can be passed to the request, which allows to generate per-user content despite the name the SIP URI identifying the list can be the same for all users.
Simon Morlat 1.7 88
89 When the SIP client receives the NOTIFY from the server, it can then discover the members of the list, since the NOTIFY contains all the elements of the resource lists, as well as presence documents for contacts for which presence is known.
François Grisez 10.1 91 The server known resource lists are suitable for a SIP service where users don't have a populated address book already: for example for employees in a company, so that each employee can have the list of contact information and presence for his/her colleagues.
Simon Morlat 1.7 92
93 = Confidentiality rules for accessing the presence information =
François Grisez 12.1 95 Before a SIP SUBSCRIBE reaches the presence server, it goes through the SIP proxy that can authenticate or reject the request. However to ensure a reasonable protection of users' privacy, the presence server restricts the distribution of presence information to users that both subscribed to each other.
François Grisez 10.1 96
François Grisez 13.1 97 Let's take this concrete example:
François Grisez 10.1 98
François Grisez 13.1 99 1. A subscribes to B's presence but B does not subscribe to A's presence. Then, A will receive no information about B's presence.
100 1. B decides to subscribe for presence information for A. A and B are now mutually subscribed to each other's presence and the presence server notifies B's presence to A, as well as A's presence to B.
Simon Morlat 1.1 102 This rule stands for both long-term and short-term presence.
Simon Morlat 1.7 104 = High availability and scalability =
Simon Morlat 1.1 105
François Grisez 10.1 106 The presence server can be deployed redundantly, for example collocated with a proxy server node, as long as **only long-term presence** is required for the service.
107 Indeed, the distribution of short term presence information across presence server nodes is currently not implemented.