<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>The module is a Resource List Server implementation following the
	specification in RFC 4662 and RFC 4826.
	</para>
	<para>
	The server is independent from local presence servers, retrieving presence
	information with Subscribe-Notify messages.
	</para>
	<para>
	The module uses the presence module as a library, as it requires a resembling
	mechanism for handling Subscribe. Therefore, in case the local presence server
	is not collocated on the same machine with the RL server, the presence module
	should be loaded in a library mode only (see doc for presence module).
	</para>

	<para>
	It handles subscription to lists in an event independent way. The default event
	is presence, but if some other events are to be handled by the server, they
	should be added using the module parameter "rls_events".
	</para>
	<para>
	It works with XCAP server for storage. There is also the possibility to
	configure it to work in an integrated_xcap server mode, when it only
	queries database for the resource lists documents. This is useful in a
	small architecture when all the clients use an integrated server and there
	are no references to exterior documents in their lists.
	</para>
	<para>
	The same as presence module, it has a caching mode with periodical update
	in database for subscribe information. The information retrieved with Notify
	messages is stored in database only.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>a database module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>sl</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>presence- in a library mode</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>pua</emphasis>.
			</para>

			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
		</itemizedlist>

		</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="rls.p.db_url">
		<title><varname>db_url</varname>(str)</title>
		<para>
		The database url.
		</para>
		<para>
		<emphasis>	Default value is <quote>&defaultdb;</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.rlpres_db_url">
		<title><varname>rlpres_db_url</varname>(str)</title>
		<para>
		The rlpres (rls_presentity table) database url.
		This parameter only needs to be specified if the rls_watchers table and
		rls_presentity tables are in different databases.
		rls_presentity is used to cache the bodies of back-end NOTIFY requests
		until an RLS NOTIFY can be sent.  On a multi-server system having a single
		cache for all active servers can cause issues if both servers try to send
		RLS NOTIFY requests at the same time.  This parameter enables each server
		to have its own (possibly local) rls_presentity table.
		</para>
		<para>
		<emphasis>	Default value is a mirror of the <quote>db_url</quote> setting.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlpres_db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlpres_db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.xcap_db_url">
		<title><varname>xcap_db_url</varname>(str)</title>
		<para>
		The xcap database url.
		This parameter only needs to be specified if the rls db and integrated
		xcap server db have different urls.
		</para>
		<para>
		<emphasis>	Default value is a mirror of the <quote>db_url</quote> setting.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xcap_db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "xcap_db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.db_mode">
		<title><varname>db_mode</varname>(int)</title>
		<para>
		The module supports 2 modes of operation, high speed memory
		based storage (mode 0), and database only (mode 2) where all
		data is stored in a database, allowing scalability at the
		expense of speed. Mode 1 is reserved.
		</para>
		<para>
		<emphasis>	Default value is <quote>0</quote>
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "db_mode", 2)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.xcap_table">
		<title><varname>xcap_table</varname>(str)</title>
		<para>
		The name of the xcap table in which the integrated server
		or the xcap_client module writes. If integrated_xcap_server
		parameter not set, the name of the table must be the same as
		the one set for the xcap_client module.
		</para>
		<para>
		<emphasis>	Default value is <quote>xcap</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xcap_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "xcap_table", "xcaps");
...
</programlisting>
		</example>
	</section>
	<section id="rls.p.rlsubs_table">
		<title><varname>rlsubs_table</varname>(str)</title>
		<para>
		The name of the db table where resource lists subscription
		information is stored.
		</para>
		<para>
		<emphasis>	Default value is <quote>rls_watchers</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlsubs_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlsubs_table", "rls_subscriptions")
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.rlpres_table">
		<title><varname>rlpres_table</varname>(str)</title>
		<para>
		The name of the db table where notified event specific
		information is stored.
		</para>
		<para>
		<emphasis>	Default value is <quote>rls_presentity</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlpres_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlpres_table", "rls_notify")
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.clean_period">
		<title><varname>clean_period</varname> (int)</title>
		<para>
		The period at which to check for expired information.
		0 means do not check.
		</para>
		<para>
		<emphasis>Default value is <quote>100</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "clean_period", 100)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.rlpres_clean_period">
		<title><varname>rlpres_clean_period</varname> (int)</title>
		<para>
		The period at which to check for expired rls_presentity information.
		-1 means do not use (clean_period) is used instead.
		0 means do not check.
		This option can be used when you want to check rls_presentity and
		rls_watchers on different timeouts.  This is useful when they are
		in different databases.
		</para>
		<para>
		<emphasis>Default value is <quote>-1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlpres_clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlpres_clean_period", 100)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.waitn_time">
		<title><varname>waitn_time</varname> (int)</title>
		<para>
		The maximum time period that RLS NOTIFY requests will
		be buffered for.  The server will attempt to send
		NOTIFY requests with the updated presence state of the
		subscribed list or watcher information within this
		many seconds of a change occurring.
		</para>
		<para>
		<emphasis>Default value is <quote>5</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>waitn_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "waitn_time", 10)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.notifier_poll_rate">
		<title><varname>notifier_poll_rate</varname> (int)</title>
		<para>
		The number of times per second that the notifier processes
		should check for work.  Approximately
		1/(waitn_time * notifier_poll_rate * notifier_processes) of the
		pending updates will be sent each time a notifier process runs.
		</para>
		<para>
		Separate notifier processes are only run when db_mode is 2
		(DB only mode).
		</para>
		<para>
		<emphasis>Default value is <quote>10</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>notifier_poll_rate</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "notifier_poll_rate", 20)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.notifier_processes">
		<title><varname>notifier_processes</varname> (int)</title>
		<para>
		The number of notifier processes that should be started.
		</para>
		<para>
		Separate notifier processes are only run when db_mode is 2
		(DB only mode).
		</para>
		<para>
		<emphasis>Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>notifier_processes</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "notifier_processes", 2)
...
</programlisting>
		</example>
	</section>

	<section id="rls.p.max_expires">
		<title><varname>max_expires</varname> (int)</title>
		<para>
		The maximum accepted expires for a subscription to a list.
		</para>
		<para>
		<emphasis>Default value is <quote>7200</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "max_expires", 10800)
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.expires_offset">
		<title><varname>expires_offset</varname> (int)</title>
		<para>
		This parameter only has an effect when the db_mode is DB_ONLY (mode 2).
		When expired subscribers are checked for deletion from the database,
		those that have a value in the expires column which is less than
		current_time - expires_offset are matched. Hence when an offset of zero
		is used, all those that expire prior the current time will be deleted.
		If an offset of 't' is used, only those that expired more than t seconds
		ago are deleted from the database.
		Negative offsets are treated as though an offset of zero was specified.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>expires_offset</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "expires_offset", 0)
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.hash_size">
		<title><varname>hash_size</varname> (int)</title>
		<para>
        The dimension of the hash table used to store subscription to a list.
        This parameter will be used as the power of 2 when computing table size.
		</para>
		<para>
		<emphasis>Default value is <quote>9 (512)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "hash_size", 11)
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.xcap_root">
		<title><varname>xcap_root</varname> (str)</title>
		<para>
		The address of the xcap server.
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.integrated_xcap_server">
		<title><varname>integrated_xcap_server</varname> (int)</title>
		<para>
		This parameter should be set if only integrated xcap servers
		are used to store resource lists.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>integrated_xcap_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "integrated_xcap_server", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.to_presence_code">
		<title><varname>to_presence_code</varname> (int)</title>
		<para>
		The code to be returned by rls_handle_subscribe function
		if the processed Subscribe is not a resource list Subscribe.
		This code can be used in an architecture with presence and rls
		servers collocated on the same machine, to call handle_subscribe
		on the message causing this code.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>to_presence_code</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "to_presence_code", 10)
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.rls_event">
		<title><varname>rls_event</varname> (str)</title>
		<para>
		The default event that RLS handles is presence. If some other
		events should also be handled by RLS they should be added using
		this parameter. It can be set more than once.
		</para>
		<para>
		<emphasis>Default value is <quote>"presence"</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rls_event</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rls_event", "dialog;sla")
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.outbound_proxy">
		<title><varname>outbound_proxy</varname> (str)</title>
		<para>
		The SIP address where to send RLS subscriptions (outbound
		proxy address as SIP URI).
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>outbound_proxy</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "outbound_proxy", "sip:presence.kamailio.org")
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.server_address">
		<title><varname>server_address</varname> (str)</title>
		<para>
			The address of the server that will be used as a contact in sent
			Subscribe requests and 200 OK replies for Subscribe requests for RLS.
			It is a mandatory parameter.
		</para>
		<example>
		<title>Set <varname>server_address</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "server_address", "sip:rls@ip.address.ofyour.proxy:5060")
...
		</programlisting>
		</example>
	</section>

	<section id="rls.p.max_notify_body_length">
		<title><varname>max_notify_body_length</varname> (int)</title>
		<para>
			The maximum size that the body of a NOTIFY message may be.
            If set to 0 (the default), no size limit is applied.
            Note that this refers only to the body, not the complete NOTIFY message.
		</para>
		<example>
		<title>Set <varname>max_notify_body_length</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "max_notify_body_length", 32000)
...
		</programlisting>
		</example>
	</section>
	<section id="rls.p.reload_db_subs">
	    <title><varname>reload_db_subs</varname> (integer)</title>
	    <para>
		    Reload subscriptions on module initialization (requires db_mode 0 (memory only mode)).
	    </para>
	    <para>
		<emphasis>
		    Default value is 0 (do not load rows from db).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>reload_db_subs</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "reload_db_subs", 1)
...
</programlisting>
	    </example>
	</section>
	<section id="rls.p.fetch_rows">
	    <title><varname>fetch_rows</varname> (integer)</title>
	    <para>
		Number of rows to be loaded in one step from database.
	    </para>
	    <para>
		<emphasis>
		    Default value is 500.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fetch_rows</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "fetch_rows", 1000)
...
</programlisting>
	    </example>
	</section>
	<section id="rls.p.disable_remote_presence">
	    <title><varname>disable_remote_presence</varname> (integer)</title>
	    <para>
		When set to a non-zero value RLS will not perform back-end SUBSCRIBEs
		to non-local presentities.
		When people have large contact lists RLS will make lots of back-end
		subscriptions for each local subscriber.  This can be a lot of traffic,
		and if the contact lists contain non-local (as in not on this Kamailio
		server or cluster) contacts this can result in a lot of Internet traffic.
		Setting this option to a non-zero value prevents RLS from performing
		back-end SUBSCRIBEs for remote presentities.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>disable_remote_presence</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "disable_remote_presence", 1)
...
</programlisting>
	    </example>
	</section>
	<section id="rls.p.max_backend_subs">
	    <title><varname>max_backend_subs</varname> (integer)</title>
	    <para>
		When set to a non-zero value RLS will limit the number of back-end
		SUBSCRIBEs for each RLS SUBSCRIBE to this value.
		Leaving this at the default of zero means no limit.
		When people have large contact lists RLS will make lots of back-end
		subscriptions.  This can easily overload a system.  This option allows
		you to limit the number of back-end SUBSCRIBEs to help prevent overload.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>max_backend_subs</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "max_backend_subs", 30)
...
</programlisting>
	    </example>
	</section>

</section>

<section>
	<title>Functions</title>
	<section id="rls.f.rls_handle_subscribe">
		<title>
		<function moreinfo="none">rls_handle_subscribe([watcher_uri])</function>
		</title>
		<para>
		This function detects if a Subscribe message should be
		handled by RLS. If not it replies with the configured
		to_presence_code. If it is, it extracts the dialog info and sends
		aggregate Notify requests with information for the list.
		</para>
		<para>
		By default this function uses the From: URI from the SUBSCRIBE
		request as the Watcher URI.  The optional watcher_uri parameter
		can be used to specify a different Watcher URI, possibly taken
		from a SIP header like P-Asserted-Identity:.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>rls_handle_subscribe</function> usage</title>
		<programlisting format="linespecific">
...
For presence and rls on the same machine:
	modparam("rls", "to_presence_code", 10)

	if(is_method("SUBSCRIBE"))
	{
		$var(ret_code)= rls_handle_subscribe();

		if($var(ret_code)== 10)
				handle_subscribe();

		t_release();
	}

For rls only:
	if(is_method("SUBSCRIBE"))
	{
		rls_handle_subscribe();
		t_release();
	}

...
</programlisting>
		</example>
	</section>

	<section id="rls.f.rls_handle_notify">
		<title>
		<function moreinfo="none">rls_handle_notify()</function>
		</title>
		<para>
		Handle NOTIFY requests.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>rls_handle_notify</function> usage</title>
		<programlisting format="linespecific">
...
if(method=="NOTIFY")
    rls_handle_notify();
...
</programlisting>
		</example>
	</section>

	<section id="rls.f.rls_update_subs">
		<title>
		<function moreinfo="none">rls_update_subs(uri, event)</function>
		</title>
		<para>
		This function can be used in configuration to trigger updates to
		resource list subscriptions (for example, after the contents of a
		resource list has changes).
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem>
				<para>uri - the uri of the user who made the change
				and whose resource list subscriptions should be
				updated</para>
			</listitem>
			<listitem>
				<para>event - the event package (e.g. presence).
				</para>
			</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>rls_update_subs</function> usage</title>
		<programlisting format="linespecific">
...
Within event_route[xhttp:request]:
	case "PUT":
		xcaps_put("$var(uri)", "$var(doc_uri)", "$rb");
		if($xcapuri(u=>auid)=~"pres-rules") {
			pres_update_watchers("$var(uri)", "presence");
			pres_refresh_watchers("$var(uri)", "presence", 1);
		} else if ($xcapuri(u=>auid)=~"resource-lists"
			   || $xcapuri(u=>auid)=~"rls-services") {
			rls_update_subs("$var(uri)", "presence");
		}
		exit;
		break;
...
</programlisting>
		</example>
	</section>
</section>

<section>
	<title>RPC Commands</title>
	<section id="rls.rpc.cleanup">
	  <title>rls.cleanup</title>
	  <para>
		Manually triggers the cleanup functions for the rls_watchers and
		rls_presentity tables. Useful if you have set
		<varname>clean_period</varname> to zero or less.
	  </para>
	  <para>
		Name: <emphasis>rls.cleanup</emphasis>
	  </para>
	  <para>Parameters: <emphasis>none</emphasis></para>

	  <para>
		RPC Command Format:
	  </para>
	  <programlisting  format="linespecific">
...
&kamcmd; rls.cleanup
...
	  </programlisting>
	</section>
	<section id="rls.rpc.update_subs">
	  <title>rls.update_subs</title>
	  <para>
		Manually triggers updates to resource list subscriptions (for example,
		after the contents of a resource list has changes).
	  </para>
	  <para>
		Name: <emphasis>rls.cleanup</emphasis>
	  </para>
	  <para>Parameters:</para>
		<itemizedlist>
			<listitem>
				<para>uri - the uri of the user who made the change
				and whose resource list subscriptions should be
				updated</para>
			</listitem>
			<listitem>
				<para>event - the event package (e.g. presence).
				</para>
			</listitem>
		</itemizedlist>
	  <para>
		RPC Command Format:
	  </para>
	  <programlisting  format="linespecific">
...
&kamcmd; rls.update_subs sip:alice@domain.com presence
...
	  </programlisting>
	</section>
</section>

<section>
	<title>Installation</title>
	<para>
	The module requires 2 tables in &kamailio; database: rls_presentity
	and rls_watchers. The SQL syntax to create them can be found in
	rls-create.sql script in the database directories in
	the kamailio/scripts folder.
	You can also find the complete database documentation on the
	project webpage, &kamailiodbdocslink;.
	</para>
</section>

</chapter>

