- updated presence handbook and pa and rls documentation

 - cosmetical changes in rls and pa (removed unused parameters)

doc/presence/biblio.xml

@@ -50,8 +50,14 @@ package</ulink></title>
 Data Format</ulink></title>
 </biblioentry>
 
+<biblioentry id="pres_rpid">
+<abbrev>rpid</abbrev>
+<title><ulink url="http://www.ietf.org/internet-drafts/draft-ietf-simple-rpid-09.txt"
+>draft-ietf-simple-rpid-09.txt</ulink></title>
+</biblioentry>
+
 <biblioentry id="pres_rfc_publish">
-<abbrev>pidf</abbrev>
+<abbrev>publish</abbrev>
 <title><ulink url="http://www.ietf.org/rfc/rfc3903.txt">RFC 3903 - Event state 
 publication</ulink></title>
 </biblioentry>

doc/presence/draft_iptel_im_rules.xml

@@ -0,0 +1,174 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+	'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
+	
+<article lang="en" id="im_rules"><title>MESSAGE authorization rules</title>
+<articleinfo><author><firstname>Vaclav</firstname><surname>Kubart</surname></author>
+</articleinfo>
+<abstract><para>This document folows specification of authorization documents
+suggested by <xref linkend="common_auth"/> and defines document format for
+storing rules for authorization of instant messages.
+</para></abstract>
+
+<section><title>Terms</title>
+<para>
+<variablelist><title></title>
+<varlistentry>
+	<term>sender</term>
+	<listitem><para>User sending the instant message represented by URI present
+	in From header field.
+	</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term>recipient</term>
+	<listitem><para>User receiving the instant message represented by AOR/To
+	URI.</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</section>
+
+<!-- ******************** Documents ********************* -->
+<section id="docs"><title>Instant message authorization documents</title>
+<para>Instant message authorization document is XML document formated according
+to schema defined in <xref linkend="common_auth"/>. It inherits MIME
+type of common policy documents defined there - application/auth-policy+xml.
+</para>
+
+<para>All XML elements designed in this document belong to 
+<quote>urn:iptel:xml:ns:im-rules</quote> namespace.</para>
+
+<section><title>Conditions</title>
+<para>Conditions are processed according specification in <xref linkend="common_auth"/>.
+</para>
+
+<!--<section><title>Identity representation by URI</title>
+<para>
+</para>
+</section>-->
+
+<section><title>Sphere</title>
+<para>If the "instant messaging server" (proxy) trying to resolve authorization
+rules is bound together with presence server it can take the sphere value from
+presence server as defined in <xref linkend="pres_auth"/>, otherwise is sphere
+value considered undefined in terms of common policy processing.</para>
+
+<!-- <para>This sphere
+handling is due to near relation between presence and instant messaging.
+</para>-->
+
+</section>
+
+</section>
+
+<section><title>Actions</title>
+<para>This document defines one action - &lt;im-handling&gt;. It
+is defined an enumerated integer type (like sub-handling in <xref
+linkend="pres_auth"/>). Possible values are:</para>
+<variablelist><title></title>
+<varlistentry>
+	<term>block (value 0)</term>
+	<listitem><para>The message should not be delivered to the user and should
+	be rejected with 403 Forbidden result code. This is the dafault value of
+	im-handling.
+	</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term>allow (value 1)</term>
+	<listitem><para>The message should be delivered to the destination user.
+	</para></listitem>
+</varlistentry>
+</variablelist>
+
+
+<para>In the future may these values change.</para>
+<para>If there are more matching rules, the resulting action will be the maximum
+of their &lt;im-handling&gt; values.
+</para>
+</section>
+
+<section><title>Transformations</title>
+<para>Transformations are not defined at this moment. In the future there can be
+for example length limitations or some flagging (like <quote>spam</quote>) or
+rate limitations.
+</para>
+</section>
+
+
+</section>
+
+<section><title>Example</title>
+<para>
+<programlisting><![CDATA[
+<?xml version="1.0"?>
+<ruleset xmlns="urn:ietf:params:xml:ns:common-policy"
+xmlns:im="urn:iptel:xml:ns:im-rules">
+  <rule id="whitelist">
+    <conditions>
+      <identity>
+        <id>sip:[email protected]</id>
+        <id>sip:[email protected]</id>
+        <id>sip:[email protected]</id>
+        <id>sip:[email protected]</id>
+      </identity>
+    </conditions>
+    <actions>
+      <im:im-handling>allow</im:im-handling>
+    </actions>
+    <transformations/>
+  </rule>
+  <rule id="blacklist">
+    <conditions>
+      <identity>
+        <id>sip:[email protected]</id>
+      </identity>
+    </conditions>
+    <actions>
+      <im:im-handling>block</im:im-handling>
+    </actions>
+    <transformations/>
+  </rule>
+</ruleset>
+]]></programlisting>
+</para>
+</section>
+
+
+<section><title>Usage with XCAP</title>
+<para>This document defines <quote>im-rules</quote> as unique application usage
+ID (AUID) requiered by XCAP specification.
+</para>
+
+<section><title>Naming conventions</title>
+<para>When an instant message comes to a IM/presence server (proxy) within its
+domain, the server should look for document
+[xcap-root]/im-rules/users/[recipient username]/im-rules.xml and process rules
+in it.</para>
+</section>
+
+</section>
+
+<!-- ******************** Bibliography ********************* -->
+
+<bibliography id="bib">
+<note><para>There might be new versions of internet drafts and thus links to
+them my be obsolete. In such case try increment version in link or find the
+draft on <ulink url="http://www.ietf.org">IETF</ulink> by name.</para></note>
+
+<biblioentry id="common_auth">
+<abbrev>common auth</abbrev>
+<title><ulink
+url="http://www.ietf.org/internet-drafts/draft-ietf-geopriv-common-policy-05.txt"
+>draft-ietf-geopriv-common-policy-05.txt</ulink></title>
+</biblioentry>
+
+<biblioentry id="pres_auth">
+<abbrev>presence auth</abbrev>
+<title><ulink url="http://www.ietf.org/internet-drafts/draft-ietf-simple-presence-rules-03.txt"
+>draft-ietf-simple-presence-rules-03.txt</ulink> - presence authorization XML based data format 
+and usage with XCAP</title>
+</biblioentry>
+
+</bibliography>
+
+</article>

doc/presence/install.xml

@@ -34,9 +34,9 @@ on common libraries which have their own dependencies as mentioned below.
 </itemizedlist>-->
 </section>
 
-<section><title>Installation steps</title>
+<section><title>Installation from CVS</title>
 <para>There is an example of steps which need to be done while installing SER
-with these libraries into directory /base/ser/directory (if no directory specified - 
+with shared libraries into directory /base/ser/directory (if no directory specified - 
 no prefix parameter given - default value is used: /usr/local/)
 <orderedlist>
 	<listitem><para>Download current ser sources:</para>
@@ -57,14 +57,40 @@ no prefix parameter given - default value is used: /usr/local/)
 	</listitem>
 </orderedlist>
 </para>
-</section> <!-- Installation steps -->
+</section> <!-- Installation from CVS -->
+
+<section><title>Installation from presence-snapshot</title>
+
+<para>There are snapshots of sources from CVS named "presence snapshots" on our
+FTP server ftp://ftp.iptel.org/pub/ser/presence/.</para>
+
+<para>Presence snapshot contains example config files, has modified Makefiles for
+simplier compilation and installation and it is a bit tested for presence
+functions. Snapshot compiles only modules needed by presence!</para>
+
+<para>There is an example of steps which need to be done while installing SER
+from presence snapshot into directory /base/ser/directory (if no directory specified - 
+no prefix parameter given - default value is used: /usr/local/)
+<orderedlist>
+	<listitem><para>Download last versiom from
+	ftp://ftp.iptel.org/pub/ser/presence/</para></listitem>
+
+	<listitem><para>Compile and install</para>
+	<para><userinput>make install prefix=/base/ser/directory</userinput></para>
+	</listitem>
+</orderedlist>
+</para>
+</section> <!-- Installation from snapshot -->
 
 <section><title>Running SER</title>
 <para>Linker used for dynamic linking must know, where to find these libraries.
 This may be done by setting <varname>LD_LIBRARY_PATH</varname> before
 startup.</para>
 <para><userinput>export LD_LIBRARY_PATH=/base/ser/directory/lib/ser</userinput></para>
-<para><userinput>/base/ser/directory/sbin/ser -f /base/ser/directory/etc/ser/ser.cfg</userinput></para>
+<para><userinput>/base/ser/directory/sbin/ser -f /base/ser/directory/etc/ser/ser.cfg</userinput></para> 
+
+<warning>If you want to run SER under sudo like <quote>sudo /base/ser/directory/sbin/ser -f
+/base/ser/directory/etc/ser/ser.cfg</quote> it might not work!</warning>
 </section> <!-- running SER -->
 
 </section>

doc/presence/intro.xml

@@ -3,7 +3,16 @@
 	'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
 	
 <section><title>Introduction</title>
-<para>
+<para>This document describes usage of SIP Express Router as a presence server.
 <!-- TODO: What is presence, ... (use doc from PIC-SE wiki?) -->
 </para>
+<para>Main features:
+<itemizedlist>
+	<listitem><para>presence events with XCAP authorization</para></listitem>
+	<listitem><para>presence watcherinfo</para></listitem>
+	<listitem><para>resource list server (only for presence now)</para></listitem>
+	<listitem><para>B2BUA for presence events (no resource list support now)</para></listitem>
+	<listitem><para>MESSAGE authorization</para></listitem>
+</itemizedlist>
+</para>
 </section>

doc/presence/presence_book.xml

@@ -14,12 +14,15 @@ http://www.sagehill.net/docbookxsl/ValidXinclude.htm -->
 	<include xmlns="http://www.w3.org/2001/XInclude" href="intro.xml"/>
 	<include xmlns="http://www.w3.org/2001/XInclude" href="xcap.xml"/>
 	<include xmlns="http://www.w3.org/2001/XInclude" href="install.xml"/>
-	<section><title>Presence modules</title>
+<!--	<section><title>Presence modules</title> -->
 	<include xmlns="http://www.w3.org/2001/XInclude" href="../../modules/pa/doc/pa.xml"/>
 	<include xmlns="http://www.w3.org/2001/XInclude" href="../../modules/rls/doc/rls.xml"/>
 	<include xmlns="http://www.w3.org/2001/XInclude" href="../../modules/presence_b2b/doc/presence_b2b.xml"/>
-	</section>
+<!--	</section>-->
 	<include xmlns="http://www.w3.org/2001/XInclude" href="examples.xml"/>
+	
+	<include xmlns="http://www.w3.org/2001/XInclude" href="draft_iptel_im_rules.xml"/>
+	
 	<include xmlns="http://www.w3.org/2001/XInclude" href="biblio.xml"/>
 	
 	
@@ -34,4 +37,10 @@ http://www.sagehill.net/docbookxsl/ValidXinclude.htm -->
 <!--		<xi:include href="todo.xml"/>-->
 <!--	</chapter>-->
 
+<!--	<appendix><title>Appendix</title><toc/>
+	<include xmlns="http://www.w3.org/2001/XInclude" 
+		href="draft_iptel_im_rules.xml"/>
+	</appendix>
+-->
+
 </article>

doc/presence/xcap.xml

@@ -24,16 +24,16 @@ data. From the SER's point of view are interesting:
 <para>Definition of authorization documents and theirs usage is specified in <xref 
 linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 
 linkend="pres_draft_auth"/>. Both documents are quite common and in SER's
-presence modules implemented only partialy.
-</para>
+presence modules implemented only partialy. For more information about XCAP
+authorization see details in <xref linkend="pa.xcap"/>.</para>
 </section> <!-- XCAP authorization -->
 
 <section><title>Buddy lists</title>
 <para>XCAP server may be used for storing lists of users too. These lists may be
 used for presence subscriptions - subscription to such list means subscription
-to all users at once. This reduces number of created subscriptions and may
+to all users on it at once. This reduces number of created subscriptions and may
 reduce data transfers between server and client too; but presence documents for
-lists of users may be very big.</para>
+lists of users may be very big and thus require TCP connection.</para>
 
 <para>There may be not only lists for individual users with their contacts but 
 there may be other sort of lists representing some <quote>logical
@@ -48,7 +48,8 @@ there. Such customer may simply watch presence state of
 linkend="pres_draft_rls"/> and their usage with SIP in <xref
 linkend="pres_draft_rls_sip"/>. These lists are partialy implemented in <link
 linkend="pres_rls">RLS module</link>.
-</para>
+For more information about resource lists see details in <xref
+linkend="rls.xcap"/>.</para>
 </section> <!-- buddy lists -->
 
 <section><title>Manipulation with XCAP documents</title>
@@ -62,118 +63,6 @@ not much client software supporting it.
 
 </section> <!-- XCAP introduction -->
 
-<section><title>XCAP authorization and SER</title>
-
-<section><title>Authorization document URI</title>
-<para>Authorization documents are read for presentities according to their presentity
-URIs. Presentity URI is AOR of SUBSCRIBE request. Resulting URI will be:</para>
-<para>
-<filename>&lt;xcap-root&gt;/pres-rules/users/&lt;username&gt;/presence-rules.xml</filename>
-where <parameter>&lt;xcap-root&gt;</parameter> is set in configuration and
-<parameter>&lt;username&gt;</parameter> is username from presentity URI.
-</para>
-
-<example><title>authorization document uri</title>
-<para>For example for presentity <literal>sip:[email protected]</literal> and
-<parameter>xcap-root</parameter> <literal>http://localhost/xcap-root</literal> will be
-the URI for the authorization document
-<filename>http://localhost/xcap-root/pres-rules/users/smith/presence-rules.xml</filename>
-</para>
-</example>
-
-</section>
-
-<section><title>Disadvantages</title>
-<para>One of the worst disadvantages of XCAP authorization is slowness of XCAP
-queries compared to - for example - data stored in local database. This is the
-reason for caching XCAP queries and responses, but there is a problem - how to
-detect changes in data stored on XCAP server. One of possible solutions is to 
-implement client for <quote>XCAP change notifications</quote> described in <xref
-linkend="pres_draft_xcap_change"/> and <xref linkend="pres_draft_xcap_profiles"/>
-(planned in future versions).</para>
-</section>
-
-<section><title>Standard incompliances</title>
-<para>SER's XCAP authorization support is not finished yet, there are some standard
-incompliances now:
-<itemizedlist>
-	<listitem><para>ignored sphere</para></listitem>
-	<listitem><para>ignored date and time conditions</para></listitem>
-	<listitem><para>ignored transformations</para></listitem>
-</itemizedlist>
-</para>
-</section>
-
-</section> <!-- XCAP authorization in SER -->
-
-<section><title>Resource lists and SER</title>
-<para>There is a problem of resource lists usage: The draft <xref
-linkend="pres_draft_rls"/> describes that a Resource Lists Server operates with
-<quote>rls-services</quote> document - NOT directly with the user's buddy list,
-but tested client software doesn't store <quote>rls-services</quote> documents,
-only <quote>resource list documents</quote> (buddy lists).</para>
-
-<para>It is possible now to change mode of processing subscriptions (see <link
-linkend="rls.parameters">RLS module parameters</link> so it works directly with
-resource list documents published by client instead of rls-services document.
-</para>
-
-<section><title>RLS document URI</title>
-<para>The construction of rls-services document URI is described in <xref
-linkend="pres_draft_rls"/>. Only in short: the AOR from SIP SUBSCRIBE request is
-combined with XCAP root given in configuration like this:</para>
-<para>
-<filename>&lt;xcap-root&gt;/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;AOR&gt;%22]</filename>.
-</para>
-<para><emphasis>
-This URI doesn't not specify namespaces as mentioned in definition, but this is 
-due to problems with XCAP server used for tests (problems querying
-parts of documents with namespaces).</emphasis></para>
-<example><title>rls-services uri example</title>
-<itemizedlist>
-	<listitem><para><varname>xcap-root</varname> = <literal>http://localhost/xcap-root</literal></para></listitem>
-	<listitem><para><varname>AOR</varname> = <literal>sip:[email protected]</literal></para></listitem>
-</itemizedlist>
-<para>Resulting rls-services document describing the list will be get from URI: 
-<filename>http://localhost/xcap-root/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;[email protected]&gt;%22]</filename>,
-which means the <literal>service</literal> element with
-<parameter>uri</parameter> parameter value
-<literal>[email protected]</literal> stored in rls-services document named
-index.
-</para></example>
-
-<section><title>Disadvantages</title>
-<para>Working with URIs presented in this section have one big disadvantage - it
-needs full XCAP server which is able to work with partial documents and able to
-process XPointer expressions in XCAP queries.</para>
-
-<para>Due to unavailability of free XCAP servers is there a possibility to
-use SER's RLS server in mode of <emphasis>reduced XCAP server needs</emphasis> 
-(see <link linkend="rls.parameters">RLS module parameters</link>). If operating 
-in this mode, RLS requests full rls-service document from uri 
-<filename>&lt;xcap-root&gt;/rls-services/global/index</filename>, inspects it
-and finds requested resource list according to URI and AOR by itself.
-(Only if possible! There can't be links 
-to partial documents in rls-services document.)
-</para>
-</section> <!-- disadvantages -->
-
-</section>
-
-<section><title>Standard incompliances</title>
-<para>SER's resource lists support is not finished yet, there are some standard
-incompliances now:
-<itemizedlist>
-	<listitem><para>uri canonicalization not done yet according to definition</para></listitem>
-	<listitem><para>no subscriptions made to external servers (subscriptions
-	only within one SER instance)</para></listitem>
-	<listitem><para>full status documents only</para></listitem>
-</itemizedlist>
-</para>
-</section>
-
-</section> <!-- resource lists and SER -->
-
 <section id="xcap.examples"><title>XCAP examples</title>
 <note><para>XCAP documents examples published there doesn't use correct XML
 namespaces due to problems with XCAP server used for tests (probles querying