d13d913465a1b3287d97cea55d03cd785e820912
[sip-router] / modules_k / presence / doc / presence_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         <title>&adminguide;</title>
14         
15         <section>
16         <title>Overview</title>
17         <para> The Presence module implements the core functionality of SIP event notification.
18         It handles PUBLISH and SUBSCRIBE messages and generates
19         NOTIFY messages in a general, event independent way. It is extensible and allows registering 
20         events to it from other &kamailio; modules.
21         Supported SIP event packages are presence, presence.winfo, dialog;sla from the presence_xml
22         module and message-summary from the presence_mwi module.
23         </para>
24         <para>
25         The module uses database storage and memory caching (to improve performance).
26         The SIP SUBSCRIBE dialog information is stored in memory and 
27         is periodically updated in the database, while for PUBLISH only the presence
28         or absence of stored info for a certain resource is maintained in memory
29         to avoid unnecessary, costly database operations. 
30         It is possible to disable in-memory caching by configuring a fallback to database mode 
31         (by setting the module parameter "fallback2db"). In this mode, in case a searched record is not 
32         found in cache, the search is continued in database. This is useful for
33         an architecture in which processing and memory load might be divided on 
34         several &kamailio; instances, maybe on different servers using the same database.
35         This parameter remains only for legacy purposes. As a new feature for the presence engine, it is possible
36         to have three database modes, which one can configure through the dbmode parameter.
37         Setting dbmode to 0, 1, 2 respective will cause the subscribers to be retrieved from memory only,
38         from memory and to fallback to database mode in case a record is not found in memory, and from database only.
39         </para>
40         <para>The module implements several API functions, that can be used by other
41         modules. In fact, it can be used only as a resource module, or "library".
42         This mode of operation is enabled if the db_url parameter is not set to any value.
43         </para>
44         <para>
45         The &kamailio; Presence module implements the specifications in: RFC3265, RFC3856, RFC3857, 
46         RFC3858.
47         </para>
48         </section>
49
50         <section>
51         <title>Dependencies</title>
52         <section>
53                 <title>&kamailio; Modules</title>
54                 <para>
55                 The following modules must be loaded before this module:
56                         <itemizedlist>
57                         <listitem>
58                         <para>
59                                 <emphasis>a database module</emphasis>.
60                         </para>
61                         </listitem>
62                         <listitem>
63                         <para>
64                                 <emphasis>sl</emphasis>.
65                         </para>
66                         </listitem>
67                         <listitem>
68                         <para>
69                                 <emphasis>tm</emphasis>.
70                         </para>
71                         </listitem>
72                         </itemizedlist>
73                 </para>
74         </section>
75
76         <section>
77                 <title>External Libraries or Applications</title>
78                 <itemizedlist>
79                         <listitem>
80                         <para>
81                                 <emphasis>libxml</emphasis>.
82                         </para>
83                         </listitem>
84                 </itemizedlist>
85
86                 </section>
87         </section>
88         
89         <section>
90         <title>Exported Parameters</title>
91         <section>
92                 <title><varname>db_url</varname>(str)</title>
93                 <para>
94                 The database url.
95                 </para>
96                 <para>If set, the module is a fully operational
97                 presence server. Otherwise, it is used as a 'library', for 
98                 its exported functions.
99                 </para>
100                 <para>
101                 <emphasis>      Default value is <quote>NULL</quote>.   
102                 </emphasis>
103                 </para>
104                 <example>
105                 <title>Set <varname>db_url</varname> parameter</title>
106                 <programlisting format="linespecific">
107 ...
108 modparam("presence", "db_url", 
109         "&defaultdb;")
110 ...
111 </programlisting>
112                 </example>
113         </section>
114         <section>
115                 <title><varname>presentity_table</varname>(str)</title>
116                 <para>
117                 The name of the db table where PUBLISH presence information is stored.
118                 </para>
119                 <para>
120                 <emphasis>      Default value is <quote>presentity</quote>.
121                 </emphasis>
122                 </para>
123                 <example>
124                 <title>Set <varname>presentity_table</varname> parameter</title>
125                 <programlisting format="linespecific">
126 ...
127 modparam("presence", "presentity_table", "presentity")
128 ...
129 </programlisting>
130                 </example>
131         </section>
132         <section>
133                 <title><varname>active_watchers_table</varname>(str)</title>
134                 <para>
135                 The name of the db table where active subscription information is stored. 
136                 </para>
137                 <para>
138                 <emphasis>      Default value is <quote>active_watchers</quote>.
139                 </emphasis>
140                 </para>
141                 <example>
142                 <title>Set <varname>active_watchers_table</varname> parameter</title>
143                 <programlisting format="linespecific">
144 ...
145 modparam("presence", "active_watchers_table", "active_watchers")
146 ...
147 </programlisting>
148                 </example>
149         </section>
150         <section>
151                 <title><varname>watchers_table</varname>(str)</title>
152                 <para>
153                 The name of the db table where subscription states are stored.
154                 </para>
155                 <para>
156                 <emphasis>      Default value is <quote>watchers</quote>.
157                 </emphasis>
158                 </para>
159                 <example>
160                 <title>Set <varname>watchers_table</varname> parameter</title>
161                 <programlisting format="linespecific">
162 ...
163 modparam("presence", "watchers_table", "watchers")
164 ...
165 </programlisting>
166                 </example>
167         </section>
168
169         <section>
170                 <title><varname>clean_period</varname> (int)</title>
171                 <para>
172                 The period in seconds between checks if there are expired messages stored in database.
173                 </para>
174                 <para>
175                 <emphasis>Default value is <quote>100</quote>. A zero or negative value disables this activity.
176                 </emphasis>
177                 </para>
178                 <example>
179                 <title>Set <varname>clean_period</varname> parameter</title>
180                 <programlisting format="linespecific">
181 ...
182 modparam("presence", "clean_period", 100)
183 ...
184 </programlisting>
185                 </example>
186         </section>
187         <section>
188                 <title><varname>db_update_period</varname> (int)</title>
189                 <para>
190                 The period at which to synchronize cached subscriber info with the
191                 database.
192                 </para>
193                 <para>
194                 <emphasis>Default value is <quote>100</quote>. A zero or negative value disables synchronization.
195                 </emphasis>
196                 </para>
197                 <example>
198                 <title>Set <varname>db_update_period</varname> parameter</title>
199                 <programlisting format="linespecific">
200 ...
201 modparam("presence", "db_update_period", 100)
202 ...
203 </programlisting>
204                 </example>
205         </section>
206
207 <section>
208                 <title><varname>to_tag_pref</varname> (str)</title>
209                 <para>
210                 The prefix used when generating to_tag when sending replies for
211                 SUBSCRIBE requests.
212                 </para>
213                 <para>
214                 <emphasis>Default value is <quote>10</quote>.
215                 </emphasis>
216                 </para>
217                 <example>
218                 <title>Set <varname>to_tag_pref</varname> parameter</title>
219                 <programlisting format="linespecific">
220 ...
221 modparam("presence", "to_tag_pref", 'pres')
222 ...
223         </programlisting>
224                 </example>
225         </section>
226
227         <section>
228                 <title><varname>expires_offset</varname> (int)</title>
229                 <para>
230                 The value in seconds that should be subtracted from the expires value when
231                 sending a 200OK for a publish. It is used for forcing the client
232                 to send an update before the old publish expires.
233                 </para>
234                 <para>
235                 <emphasis>Default value is <quote>0</quote>.
236                 </emphasis>
237                 </para>
238                 <example>
239                 <title>Set <varname>expires_offset</varname> parameter</title>
240                 <programlisting format="linespecific">
241 ...
242 modparam("presence", "expires_offset", 10)
243 ...
244 </programlisting>
245                 </example>
246
247 </section>
248        <section>
249                <title><varname>max_expires</varname> (int)</title>
250                <para>
251                The the maximum admissible expires value for PUBLISH/SUBSCRIBE
252                message (in seconds).
253                </para>
254                <para>
255                <emphasis>Default value is <quote>3600</quote>.
256                </emphasis>
257                </para>
258                <example>
259                <title>Set <varname>max_expires</varname> parameter</title>
260                <programlisting format="linespecific">
261 ...
262 modparam("presence", "max_expires", 3600)
263 ...
264 </programlisting>
265                </example>
266        </section>
267
268 <section>
269                 <title><varname>server_address</varname> (str)</title>
270                 <para>
271                 The presence server address which will become the value of Contact header filed 
272                 for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY messages.
273                 </para>
274                 <example>
275                 <title>Set <varname>server_address</varname> parameter</title>
276                 <programlisting format="linespecific">
277 ...
278 modparam("presence", "server_address", "sip:10.10.10.10:5060")
279 ...
280 </programlisting>
281                 </example>
282         </section>
283 <section>
284                 <title><varname>fallback2db</varname> (int)</title>
285                 <para>
286                 Setting this parameter enables a fallback to db mode of operation.
287                 In this mode, in case a searched record is not found in cache, 
288                 the search is continued in database. Useful for an architecture in
289                 which processing and memory load might be divided on more servers
290                 using the same database.
291                 </para>
292                 <example>
293                 <title>Set <varname>fallback2db</varname> parameter</title>
294                 <programlisting format="linespecific">
295 ...
296 modparam("presence", "fallback2db", 1)
297 ...
298 </programlisting>
299                 </example>
300         </section>
301 <section>
302                 <title><varname>dbmode</varname> (int)</title>
303                 <para>
304                 This parameter sets the mode in which records are retrieved.
305                 Setting this parameter to 0 or 1 is equivalent to setting fallback2db to 0 or 1, respectiv.
306                 The dbmode parameter can also take a third value, 2, in which records are retrieved from database only.
307                 So, the three database modes in which the presence engine can operate are: memory only, fallback to database, and database only.
308                 </para>
309                 <example>
310                 <title>Set <varname>dbmode</varname> parameter</title>
311                 <programlisting format="linespecific">
312 ...
313 modparam("presence", "dbmode", 2)
314 ...
315 </programlisting>
316                 </example>
317         </section>
318         <section>
319                 <title><varname>subs_htable_size</varname> (int)</title>
320                 <para>
321                 The size of the in-memory hash table to store subscription dialogs.
322                 This parameter will be used as the power of 2 when computing table size.
323                 </para>
324                 <para>
325                 <emphasis>Default value is <quote>9 (512)</quote>.
326                 </emphasis>
327                 </para>
328                 <example>
329                 <title>Set <varname>subs_htable_size</varname> parameter</title>
330                 <programlisting format="linespecific">
331 ...
332 modparam("presence", "subs_htable_size", 11)
333 ...
334         </programlisting>
335                 </example>
336         </section>
337
338         <section>
339                 <title><varname>pres_htable_size</varname> (int)</title>
340                 <para>
341                 The size of the in-memory hash table to store publish records.
342                 This parameter will be used as the power of 2 when computing table size.
343                 </para>
344                 <para>
345                 <emphasis>Default value is <quote>9 (512)</quote>.
346                 </emphasis>
347                 </para>
348                 <example>
349                 <title>Set <varname>pres_htable_size</varname> parameter</title>
350                 <programlisting format="linespecific">
351 ...
352 modparam("presence", "pres_htable_size", 11)
353 ...
354         </programlisting>
355                 </example>
356         </section>
357         <section>
358                 <title><varname>enable_sphere_check</varname> (int)</title>
359                 <para>
360                 This parameter is a flag that should be set if permission rules include
361                 sphere checking.
362                 The sphere information is expected to be present in the RPID body
363                 published by the presentity. The flag is introduced as this check requires
364                 extra processing that should be avoided if this feature is not supported
365                 by the clients.
366                 </para>
367                 <para>
368                 <emphasis>Default value is <quote>0 </quote>.
369                 </emphasis>
370                 </para>
371                 <example>
372                 <title>Set <varname>enable_sphere_check</varname> parameter</title>
373                 <programlisting format="linespecific">
374 ...
375 modparam("presence", "enable_sphere_check", 1)
376 ...
377         </programlisting>
378                 </example>
379         </section>
380
381         <section>
382                 <title><varname>timeout_rm_subs</varname> (int)</title>
383                 <para>
384                 This parameter is a flag that should be set if subscriptions should be
385                 removed from the active_watchers when a NOTIFY times out. RFC3265
386                 section 3.2.2 defines this behaviour as a SHOULD, so by default it is
387                 on. Disabling this will keep subscriptions active on unreliable
388                 networks.
389                 </para>
390                 <para>
391                 <emphasis>Default value is <quote>1</quote>.
392                 </emphasis>
393                 </para>
394                 <example>
395                 <title>Set <varname>timeout_rm_subs</varname> parameter</title>
396                 <programlisting format="linespecific">
397 ...
398 modparam("presence", "timeout_rm_subs", 0)
399 ...
400         </programlisting>
401                 </example>
402         </section>
403
404 </section>
405
406 <section>
407         <title>Exported Functions</title>
408         <section>
409                 <title>
410                 <function moreinfo="none">handle_publish(char* sender_uri)</function>
411                 </title>
412                 <para>
413                 Handles PUBLISH requests by storing and updating 
414                 published information in memory cache and database, then calls functions to send 
415                 NOTIFY messages when changes in the published information occur.
416                 It takes one argument -> sender_uri. The parameter was added 
417                 for enabling BLA implementation. If present, notification of
418                 a change in published state is not sent to the respective uri
419                 even though a subscription exists.
420                 It should be taken from the Sender header. It was left at the
421                 decision of the administrator whether or not to transmit the 
422                 content of this header as parameter for handle_publish, to 
423                 prevent security problems.  
424                 </para>
425                 <para>
426                 This function can be used from REQUEST_ROUTE.
427                 </para>
428                 <para>
429                 <emphasis>Return code:</emphasis>
430                 <itemizedlist>
431                         <listitem>
432                         <para>
433                                 <emphasis> 1 - if success</emphasis>.
434                         </para>
435                         </listitem>
436                         <listitem>
437                         <para>
438                                 <emphasis> -1 - if error</emphasis>.
439                         </para>
440                         </listitem>
441                 </itemizedlist>
442                 </para>
443                 <para>
444                         The module sends an appropriate stateless reply
445                         in all cases.
446                 </para>
447
448                 <example>
449                 <title><function>handle_publish</function> usage</title>
450                 <programlisting format="linespecific">
451 ...
452         if(is_method("PUBLISH"))
453         {
454                 if($hdr(Sender)!= NULL)
455                         handle_publish("$hdr(Sender)");
456                 else
457                         handle_publish();
458                 t_release();
459         } 
460 ...
461 </programlisting>
462                 </example>
463         </section>
464
465         <section>
466                 <title>
467                 <function moreinfo="none">handle_subscribe()</function>
468                 </title>
469                 <para>
470                 The function which handles SUBSCRIBE requests. It stores or 
471                 updates information in memory and database and calls functions to send NOTIFY 
472                 messages when a SUBSCRIBE which initiate a dialog is received
473                 </para>
474                 <para>
475                 This function can be used from REQUEST_ROUTE.
476                 </para>
477                 <para>
478                 <emphasis>Return code:</emphasis>
479                 <itemizedlist>
480                         <listitem>
481                         <para>
482                                 <emphasis> 1 - if success</emphasis>.
483                         </para>
484                         </listitem>
485                         <listitem>
486                         <para>
487                                 <emphasis> -1 - if error</emphasis>.
488                         </para>
489                         </listitem>
490                 </itemizedlist>
491                 </para>
492                 <para>
493                         The module sends an appropriate stateless reply
494                         in all cases.
495                 </para>
496
497                 <example>
498                 <title><function>handle_subscribe</function> usage</title>
499                 <programlisting format="linespecific">
500 ...
501 if(method=="SUBSCRIBE")
502     handle_subscribe();
503 ...
504 </programlisting>
505                 </example>
506         </section>
507
508         <section>
509                 <title>
510                 <function moreinfo="none">pres_auth_status(watcher_uri, presentity_uri)</function>
511                 </title>
512                 <para>
513                 The function checks if watcher is authorized to subscribe
514                 event 'presence' of presentity.  Both watcher_uri and
515                 presentity_uri are pseudo variables.  Function returns
516                 ACTIVE_STATUS, if subscription is allowed and
517                 PENDING_STATUS, TERMINATED_STATUS, or WAITING_STATUS
518                 otherwise.  See presence/subscribe.h for the
519                 corresponding integer codes.  In case of error, function
520                 returns -1.
521                 </para>
522                 <para>
523                 This function can be used from REQUEST_ROUTE.
524                 </para>
525
526                 <example>
527                 <title><function>pres_auth_status</function> usage</title>
528                 <programlisting format="linespecific">
529 ...
530 if (method=="MESSAGE") {
531     pres_auth_status("$fu", $ru");
532     if ($retcode == 1) {
533         t_relay();
534     } else {
535         send_reply("403", "Forbidden");
536     }
537 }
538 ...
539 </programlisting>
540                 </example>
541         </section>
542
543         <section>
544                 <title>
545                 <function moreinfo="none">pres_refresh_watchers(uri, event, type)</function>
546                 </title>
547                 <para>
548                         The function can be used in configuration to triger notifies to watchers
549                         if a change in watchers authorization or in published state occurred
550                         (i.e., updates of xcap documents).
551                 </para>
552                 <para>Parameters:</para>
553                 <itemizedlist>
554                         <listitem>
555                                 <para>uri - the uri of the user who made the change
556                                 and whose watchers should be informed.</para>
557                         </listitem>
558                         <listitem>
559                                 <para>event - the event package.</para>
560                         </listitem>
561                         <listitem>
562                                 <para>type - it distinguishes between the two different types of events
563                                                 that can trigger the refresh, depending on its value:
564                                                 <itemizedlist>
565                                                         <listitem>
566                                                                 <para>0 - a change in watchers authentication.</para>
567                                                         </listitem>
568                                                         <listitem>
569                                                                 <para>
570                                                                         1 - a statical update in published state (either through direct
571                                                                         update in db table or by modifying the pidf manipulation document,
572                                                                         if pidf_manipulation parameter is set).
573                                                                 </para>
574                                                         </listitem>
575                                                 </itemizedlist>
576                                 </para>
577                         </listitem>
578         </itemizedlist>
579                 <para>
580                 This function can be used from ANY_ROUTE.
581                 </para>
582                 <example>
583                 <title><function>pres_refresh_watchers</function> usage</title>
584                 <programlisting format="linespecific">
585 ...
586 pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
587 ...
588 </programlisting>
589                 </example>
590         </section>
591
592         <section>
593                 <title>
594                 <function moreinfo="none">pres_update_watchers(uri, event)</function>
595                 </title>
596                 <para>
597                         The function can be used in configuration to triger updates to watchers
598                         status if a change in watchers authorization state occurred
599                         (i.e., updates of xcap documents change state from pending to active).
600                 </para>
601                 <para>Parameters:</para>
602                 <itemizedlist>
603                         <listitem>
604                                 <para>uri - the uri of the user who made the change
605                                 and whose watchers should be informed. Can be PV.</para>
606                         </listitem>
607                         <listitem>
608                                 <para>event - the event package (e.g., presence).</para>
609                         </listitem>
610         </itemizedlist>
611                 <para>
612                 This function can be used from ANY_ROUTE.
613                 </para>
614                 <example>
615                 <title><function>pres_update_watchers</function> usage</title>
616                 <programlisting format="linespecific">
617 ...
618 pres_update_watchers("sip:test@kamailio.org", "presence");
619 ...
620 </programlisting>
621                 </example>
622         </section>
623 </section>
624
625 <section>
626         <title>Exported MI Functions</title>
627         <section>
628                 <title>
629                 <function moreinfo="none">refreshWatchers</function>
630                 </title>
631                 <para>
632                 Triggers sending Notify messages to watchers if a change in watchers
633                 authorization or in published state occurred.
634                 </para>
635                 <para>
636                 Name: <emphasis>refreshWatchers</emphasis>
637                 </para>
638                 <para>Parameters:</para>
639                 <itemizedlist>
640                         <listitem>
641                                 <para>presentity_uri : the uri of the user who made the change
642                                 and whose watchers should be informed</para>
643                         </listitem>
644                         <listitem>
645                                 <para>event : the event package</para>
646                         </listitem>
647                         <listitem>
648                                 <para>refresh type : it distinguishes between the two different types of events
649                                                 that can trigger a refresh: 
650                                                 <itemizedlist>
651                                                         <listitem>
652                                                                 <para> a change in watchers authentication: refresh type= 0 ; </para>
653                                                         </listitem>
654                                                         <listitem>
655                                                                 <para>
656                                                                         a statical update in published state (either through direct 
657                                                                         update in db table or by modifying the pidf manipulation document,
658                                                                         if pidf_manipulation parameter is set): refresh type!= 0.
659                                                                 </para>
660                                                         </listitem>
661                                                 </itemizedlist>
662                                 </para>
663                         </listitem>
664         </itemizedlist>
665
666         <para>
667                 MI FIFO Command Format:
668                 </para>
669         <programlisting  format="linespecific">
670                 :refreshWatchers:fifo_reply
671                 sip:test@kamailio.org
672                 presence
673                 1
674                 _empty_line_
675                 </programlisting>
676         </section>
677
678         <section>
679           <title>
680                 <function moreinfo="none">cleanup</function>
681           </title>
682           <para>
683                 Manually triggers the cleanup functions for watchers and presentity tables. Useful if you
684                 have set <varname>clean_period</varname> to zero or less.
685           </para>
686           <para>
687                 Name: <emphasis>cleanup</emphasis>
688           </para>
689           <para>Parameters:<emphasis>none.</emphasis>emphasis></para>
690
691           <para>
692                 MI FIFO Command Format:
693           </para>
694           <programlisting  format="linespecific">
695                 :cleanup:fifo_reply
696                 _empty_line_
697           </programlisting>
698         </section>
699
700         </section>
701
702
703
704 <section>
705         <title>Installation</title>
706         <para>
707         The module requires 3 tables in the &kamailio; database: "presentity",
708         "active_watchers" and "watchers". The SQL 
709         syntax to create them can be found in presence-create.sql     
710         script in the database directories in the kamailio/scripts folder.
711         You can also find the complete database documentation on the
712         project webpage, &kamailiodbdocslink;.
713         </para>
714 </section>
715
716 </chapter>
717