2 commits - Architecture_and_Design/en-US Release_Notes/en-US

Jeroen van Meeuwen vanmeeuwen at kolabsys.com
Tue Jul 31 17:51:58 CEST 2012


 Architecture_and_Design/en-US/Administration_Panel.xml     |  506 +++++++------
 Architecture_and_Design/en-US/Configuration_Management.xml |   14 
 Architecture_and_Design/en-US/Groupware_Overview.xml       |    2 
 Architecture_and_Design/en-US/Kolab_Daemon.xml             |  395 ++++++++++
 Architecture_and_Design/en-US/Terminology.xml              |    7 
 Release_Notes/en-US/Release_Notes.xml                      |    1 
 6 files changed, 694 insertions(+), 231 deletions(-)

New commits:
commit e28c4333c68a98dda6d99f8050aa46d612303bbb
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date:   Tue Jul 31 16:51:13 2012 +0100

    publican clean does it again

diff --git a/Release_Notes/en-US/Release_Notes.xml b/Release_Notes/en-US/Release_Notes.xml
index b969ad4..759724d 100644
--- a/Release_Notes/en-US/Release_Notes.xml
+++ b/Release_Notes/en-US/Release_Notes.xml
@@ -213,6 +213,7 @@ ssl_verify_host = false</screen>
 <screen># <userinput>mysql -u root -p roundcube -e 'show tables;'</userinput>
 Password:
 </screen>
+
             </para>
             <para>
                 The list of tables should include <literal>horde_cache</literal>.


commit af1cb58b04f10bc040779481a4dc848f6afd7ae7
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date:   Tue Jul 31 16:50:57 2012 +0100

    Update architecture and design guide

diff --git a/Architecture_and_Design/en-US/Administration_Panel.xml b/Architecture_and_Design/en-US/Administration_Panel.xml
index f02c4e5..75511f0 100644
--- a/Architecture_and_Design/en-US/Administration_Panel.xml
+++ b/Architecture_and_Design/en-US/Administration_Panel.xml
@@ -290,113 +290,257 @@
 
         </section>
 
-        <section id="sect-Architecture_and_Design-Web_Administration_Panel_API-The_domain_Service">
-            <title>The <literal>domain</literal> Service</title>
+        <section id="sect-Architecture_and_Design-Web_Administration_Panel_API-Service_Handlers">
+            <title>Service Handlers</title>
             <para>
-                The <literal>domain</literal> service makes available actions against a single domain entity, for example 'add' or 'delete'. For actions against multiple domain entities, such as 'list' and 'search', see <xref linkend="sect-Architecture_and_Design-Web_Administration_Panel_API-The_domains_Service" />.
+                The following service handlers are available:
             </para>
-            <section id="sect-Architecture_and_Design-The_domain_Service-domain.add_Method">
-                <title><literal>domain.add</literal> Method</title>
-                <para>
-                    Depending on the technology used, quite the variety of things may need to happen when adding a domain to a Kolab Groupware deployment. This is therefore a responsbility for the API rather then the client.
-                </para>
-                <formalpara id="form-Architecture_and_Design-domain.add_Method-Parameters">
-                    <title>Parameters</title>
-                    <para>
-                        The following parameters MUST be specified with the <literal>domain.add</literal> API call:
-                    </para>
+            <para>
+                <itemizedlist>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-domain">
+                            <title>domain</title>
+                            <para>
+                                Domain operations, such as obtaining information for them, or adding, editing and deleting a domain.
+                            </para>
 
-                </formalpara>
-                <para>
-                    <itemizedlist>
-                        <listitem>
-                            <formalpara id="form-Architecture_and_Design-domain.add_Method-domain">
-                                <title><literal>domain</literal></title>
-                                <para>
-                                    The domain name space to be added.
-                                </para>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                            </formalpara>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-domains">
+                            <title>domains</title>
+                            <para>
+                                short description
+                            </para>
 
-                        </listitem>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                    </itemizedlist>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-form_value">
+                            <title>form_value</title>
+                            <para>
+                                Service handler for form values. Can be used to generate form values (such as passwords for new users), and compose form values for form fields for which the value is to be composed using existing field values from other form fields.
+                            </para>
 
-                </para>
-                <para>
-                    The following parameters MAY be specified alongside the required parameters:
-                </para>
-                <para>
-                    <itemizedlist>
-                        <listitem>
-                            <formalpara id="form-Architecture_and_Design-domain.add_Method-parent">
-                                <title><literal>parent</literal></title>
-                                <para>
-                                    The domain name space for which the domain name space being created is an alias.
-                                </para>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                            </formalpara>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-group">
+                            <title>group</title>
                             <para>
-                                If specified, the parent MUST refer to an existing domain name space.
+                                short description
                             </para>
-                            <important>
-                                <para>
-                                    The user adding the domain name space as an alias is required to have administrative privileges over the parent domain name space.
-                                </para>
 
-                            </important>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                        </listitem>
-                        <listitem>
-                            <formalpara id="form-Architecture_and_Design-domain.add_Method-admin_group_name">
-                                <title><literal>admin_group_name</literal></title>
-                                <para>
-                                    The name of the group that is to be assigned administrative privileges over the domain name space.
-                                </para>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-groups">
+                            <title>groups</title>
+                            <para>
+                                short description
+                            </para>
 
-                            </formalpara>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-group_types">
+                            <title>group_types</title>
                             <para>
-                                This parameter is only valid for new domain name spaces added without a parent.
+                                short description
                             </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-resource">
+                            <title>resource</title>
                             <para>
-                                The administrative group is searched after the domain name space is added. Should the group not exist, it is created.
+                                short description
                             </para>
-                            <remark>What is the search filter for the group search?</remark>
 
-                        </listitem>
-                        <listitem>
-                            <formalpara id="form-Architecture_and_Design-domain.add_Method-admin_role_name">
-                                <title><literal>admin_role_name</literal></title>
-                                <para>
-                                    The name of the role that is to be assigned administrative privileges over the domain name space.
-                                </para>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                            </formalpara>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-resources">
+                            <title>resources</title>
                             <para>
-                                This parameter is only valid for new domain name spaces added without a parent.
+                                short description
                             </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-resource_types">
+                            <title>resource_types</title>
                             <para>
-                                The administrative role is searched after the domain name space is added. Should the role not exist, it is created.
+                                short description
                             </para>
-                            <remark>What is the search filter for the role search?</remark>
 
-                        </listitem>
-                        <listitem>
-                            <formalpara id="form-Architecture_and_Design-domain.add_Method-admin_user">
-                                <title><literal>admin_user</literal></title>
-                                <para>
-                                    The name of the admin user that is to be added to the <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_group_name" /> or <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_role_name" />.
-                                </para>
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
 
-                            </formalpara>
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-role">
+                            <title>role</title>
                             <para>
-                                This parameter is only valid for new domain name spaces added without a parent, that either have the <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_group_name" /> or <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_role_name" /> parameters defined as well.
+                                short description
                             </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-roles">
+                            <title>roles</title>
+                            <para>
+                                short description
+                            </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-role_types">
+                            <title>role_types</title>
+                            <para>
+                                short description
+                            </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-system">
+                            <title>system</title>
+                            <para>
+                                short description
+                            </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-user">
+                            <title>user</title>
+                            <para>
+                                short description
+                            </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-users">
+                            <title>users</title>
                             <para>
-                                The user is searched for after the domain name space is added and the <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_group_name" /> or <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_role_name" /> have been created. Should the user not exist, it is created.
+                                short description
                             </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <formalpara id="form-Architecture_and_Design-Service_Handlers-user_types">
+                            <title>user_types</title>
                             <para>
-                                Subsequently, the role named in <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_role_name" /> is attached to the user, or the user is added as a member of the group listed in the <xref linkend="form-Architecture_and_Design-domain.add_Method-admin_group_name" /> parameter.
+                                short description
+                            </para>
+
+                        </formalpara>
+                        <para>
+                            further description
+                        </para>
+
+                    </listitem>
+
+                </itemizedlist>
+
+            </para>
+
+        </section>
+
+        <section id="sect-Architecture_and_Design-Web_Administration_Panel_API-The_domain_Service">
+            <title>The <literal>domain</literal> Service</title>
+            <para>
+                The <literal>domain</literal> service makes available actions against a single domain entity, for example 'add' or 'delete'. For actions against multiple domain entities, such as 'list' and 'search', see <xref linkend="sect-Architecture_and_Design-Web_Administration_Panel_API-The_domains_Service" />.
+            </para>
+            <section id="sect-Architecture_and_Design-The_domain_Service-domain.add_Method">
+                <title><literal>domain.add</literal> Method</title>
+                <para>
+                    Depending on the technology used, quite the variety of things may need to happen when adding a domain to a Kolab Groupware deployment. This is therefore a responsbility for the API rather then the client.
+                </para>
+                <formalpara id="form-Architecture_and_Design-domain.add_Method-Parameters">
+                    <title>Parameters</title>
+                    <para>
+                        The following parameters MUST be specified with the <literal>domain.add</literal> API call:
+                    </para>
+
+                </formalpara>
+                <para>
+                    <itemizedlist>
+                        <listitem>
+                            <formalpara id="form-Architecture_and_Design-domain.add_Method-associateddomain">
+                                <title><literal>associateddomain</literal></title>
+                                <para>
+                                    One or more domain name spaces to be added.
+                                </para>
+
+                            </formalpara>
+                            <para>
+                                If more than one domain name space is specified (i.e. <literal>associateddomain</literal> consists of a list or array), the remaining domain name spaces are added as aliases.
                             </para>
 
                         </listitem>
@@ -497,132 +641,14 @@ except ValueError, e:
 
                 </formalpara>
                 <para>
-                    The authentication database technology referred to itself has the necessary settings to determine how a new domain can be added. The related settings for LDAP are <literal>domain_base_dn</literal>, <literal>domain_scope</literal>, <literal>domain_filter</literal>, <literal>domain_name_attribute</literal> (also used for the RDN).
+                    The authentication database technology referred to has the necessary settings to determine how a new domain can be added. The related settings for LDAP are <literal>domain_base_dn</literal>, <literal>domain_scope</literal>, <literal>domain_filter</literal>, <literal>domain_name_attribute</literal> (used for the RDN to compose the DN).
                 </para>
                 <para>
-                    After checking the domain does not already exist (using administrative credentials), the domain is added using the credentials for the logged in user. This is an access control verification step only; the logged in user must have 'add' rights on the domain base distinguished name.
+                    After checking the domain does not already exist (using administrative credentials), the domain is added using the credentials for the logged in user. This is an access control verification step only; the logged in user must have 'add' rights on the <xref linkend="form-Architecture_and_Design-Terminology-Domain_Base_DN" />.
                 </para>
                 <para>
-                    Additional steps when adding a (primary) domain name space is to create the databases and populate the root dn. Below is a snippet of script doing just that for <literal>example.org</literal> against a 389 Directory Server.
+                    Additional steps when adding a (primary) domain name space is to create the databases and populate the root dn.
                 </para>
-
-<programlisting language="Bash">#!/bin/bash
-
-if [ $# -ne 1 ]; then
-    read -p "Domain: " domain
-else
-    domain=$1
-fi
-
-domain_db=$(echo ${domain} | sed -e 's/\./_/g')
-domain_dn=$(echo ${domain} | sed -e 's/\./,dc=/g')
-domain_dn="dc=${domain_dn}"
-
-. ./zzz-settings.sh
-
-(
-    echo "dn: associateddomain=${domain},cn=kolab,cn=config"
-    echo "associateddomain: ${domain}"
-    echo "objectClass: top"
-    echo "objectClass: inetdomain"
-    echo "objectClass: domainrelatedobject"
-    echo "objectClass: organization"
-    echo "o: ${domain}"
-    echo ""
-    echo "dn: cn=${domain_db},cn=ldbm database,cn=plugins,cn=config"
-    echo "objectClass: top"
-    echo "objectClass: extensibleObject"
-    echo "objectClass: nsBackendInstance"
-    echo "cn: ${domain_db}"
-    echo "nsslapd-suffix: ${domain_dn}"
-    echo "nsslapd-cachesize: -1"
-    echo "nsslapd-cachememsize: 10485760"
-    echo "nsslapd-readonly: off"
-    echo "nsslapd-require-index: off"
-    echo "nsslapd-directory: /var/lib/dirsrv/slapd-${instance}/db/${domain_db}"
-    echo "nsslapd-dncachememsize: 10485760"
-    echo ""
-    echo "dn: cn=$(echo ${domain_dn} | sed -e 's/,/\\2C/g' -e 's/=/\\3D/g'),cn=mapping tree,cn=config"
-    echo "objectClass: top"
-    echo "objectClass: extensibleObject"
-    echo "objectClass: nsMappingTree"
-    echo "nsslapd-state: backend"
-    echo "cn: ${domain_dn}"
-    echo "nsslapd-backend: ${domain_db}"
-    echo ""
-    echo "dn: ${domain_dn}"
-    echo "dc: $(echo ${domain} | cut -d'.' -f 1)"
-    echo "objectClass: top"
-    echo "objectClass: domain"
-    echo "aci: (targetattr=\"carLicense || description || displayName || facsimileTelephoneNumber || homePhone || homePostalAddress || initials || jpegPhoto || labeledURI || mail || mobile || pager || photo || postOfficeBox || postalAddress || postalCode || preferredDeliveryMethod || preferredLanguage || registeredAddress || roomNumber || secretary || seeAlso || st || street || telephoneNumber || telexNumber || title || userCertificate || userPassword || userSMIMECertificate || x500UniqueIdentifier\")(version 3.0; acl \"Enable self write for common attributes\"; allow (write) userdn=\"ldap:///self\";)"
-    echo "aci: (targetattr =\"*\")(version 3.0;acl \"Directory Administrators Group\";allow (all) (groupdn=\"ldap:///cn=Directory Administrators,${domain_dn}\");)"
-    echo "aci: (targetattr=\"*\")(version 3.0; acl \"Configuration Administrators Group\"; allow (all) groupdn=\"ldap:///cn=Configuration Administrators,ou=Groups,ou=TopologyManagement,o=NetscapeRoot\";)"
-    echo "aci: (targetattr=\"*\")(version 3.0; acl \"Configuration Administrator\"; allow (all) userdn=\"ldap:///uid=admin,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot\";)"
-    echo "aci: (targetattr = \"*\")(version 3.0; acl \"SIE Group\"; allow (all) groupdn = \"ldap:///cn=slapd-ldap01,cn=389 Directory Server,cn=Server Group,cn=hosted04.klab.cc,ou=klab.cc,o=NetscapeRoot\";)"
-    echo ""
-    echo "dn: cn=Directory Administrators,${domain_dn}"
-    echo "objectClass: top"
-    echo "objectClass: groupofuniquenames"
-    echo "cn: Directory Administrators"
-    echo "uniqueMember: cn=Directory Manager"
-    echo ""
-
-    echo "dn: ou=Groups,${domain_dn}"
-    echo "objectClass: top"
-    echo "objectClass: organizationalunit"
-    echo "ou: Groups"
-    echo ""
-
-    echo "dn: ou=People,${domain_dn}"
-    echo "objectClass: top"
-    echo "objectClass: organizationalunit"
-    echo "ou: People"
-    echo ""
-
-    echo "dn: ou=Special Users,${domain_dn}"
-    echo "objectClass: top"
-    echo "objectClass: organizationalUnit"
-    echo "ou: Special Users"
-    echo "description: Special Administrative Accounts"
-    echo ""
-
-    echo "dn: uid=kolab-service,ou=Special Users,${domain_dn}"
-    echo "uid: kolab-service"
-    echo "givenName: Kolab"
-    echo "objectClass: top"
-    echo "objectClass: person"
-    echo "objectClass: inetOrgPerson"
-    echo "objectClass: organizationalPerson"
-    echo "sn: Service Account"
-    echo "cn: Kolab Service Account"
-    echo "userPassword: ${kolab_service_pass}"
-    echo ""
-
-    echo "dn: uid=cyrus-murder,ou=Special Users,${domain_dn}"
-    echo "uid: cyrus-murder"
-    echo "givenName: Cyrus"
-    echo "objectClass: top"
-    echo "objectClass: person"
-    echo "objectClass: inetOrgPerson"
-    echo "objectClass: organizationalPerson"
-    echo "sn: Murder"
-    echo "cn: Cyrus Murder"
-    echo "userPassword: ${cyrus_murder_pass}"
-    echo ""
-
-    echo "dn: uid=cyrus-admin,ou=Special Users,${domain_dn}"
-    echo "uid: cyrus-admin"
-    echo "givenName: Cyrus"
-    echo "objectClass: top"
-    echo "objectClass: person"
-    echo "objectClass: inetOrgPerson"
-    echo "objectClass: organizationalPerson"
-    echo "sn: Administrator"
-    echo "cn: Cyrus Administrator"
-    echo "userPassword: ${cyrus_admin_pass}"
-    echo ""
-
-) | ldapadd -x -h ${ldap_server} -D "cn=Directory Manager" -w "${dirmgr_pass_plain}" -c</programlisting>
                 <section id="sect-Architecture_and_Design-domain.add_Method-TODO">
                     <title>TODO</title>
                     <para>
@@ -1203,13 +1229,6 @@ print result['userpassword']
                     </para>
 
                 </formalpara>
-                <formalpara id="form-Architecture_and_Design-group.info_Method-Example_Client_Implementation">
-                    <title>Example Client Implementation</title>
-                    <para>
-                        para
-                    </para>
-
-                </formalpara>
                 <formalpara id="form-Architecture_and_Design-group.info_Method-Response">
                     <title>Response</title>
                     <para>
@@ -1633,10 +1652,45 @@ if response_data.has_key('result'):
                 <formalpara id="form-Architecture_and_Design-user.add_Method-Parameters">
                     <title>Parameters</title>
                     <para>
-                        params: user_type_id (obtain from <literal>user_types.list</literal>)
+                        A required parameter is the <literal>user_type_id</literal> (obtain from <literal>user_types.list</literal>). Further required parameters are the keys of the <literal>form_fields</literal> array for the user type with that id.
                     </para>
 
                 </formalpara>
+                <example id="exam-Architecture_and_Design-user.add_Method-Example_set_of_required_parameters">
+                    <title>Example set of required parameters</title>
+                    <para>
+                        A simple user type could look as follows:
+                    </para>
+
+<programlisting language="PHP/PHP">
+$id = 1;
+$key = 'simple';
+$description = 'A simple user type';
+$attributes = Array(
+        'auto_form_fields' => Array(),
+        'form_fields' => Array(
+                'cn' => Array(),
+                'mail' => Array(),
+            ),
+        'fields' => Array(
+                'objectclass' => Array(
+                        'top'
+                        'inetorgperson'
+                    ),
+            ),
+    );
+</programlisting>
+                    <para>
+                        Additional required parameters for this user type (with ID 1) would include <literal>cn</literal> and <literal>mail</literal>.
+                    </para>
+
+                </example>
+                <note>
+                    <para>
+                        Note that keys of the array <literal>auto_form_fields</literal> may be submitted, but are honored only if <literal>admin_auto_fields_rw</literal> is set to true or 1. If this setting is not specified (the default), form field values are re-generated. The client interface should have disabled input for these form fields.
+                    </para>
+
+                </note>
                 <formalpara id="form-Architecture_and_Design-user.add_Method-HTTP_Methods">
                     <title>HTTP Method(s)</title>
                     <para>
@@ -1651,6 +1705,12 @@ if response_data.has_key('result'):
                     </para>
 
                 </formalpara>
+
+<programlisting language="Python">
+headers = { 'X-Session-Token': <replaceable><token></replaceable> }
+params = { 'cn': 'John Doe', 'mail': 'john.doe at example.org' }
+request('POST', 'user.add', params, headers)
+</programlisting>
                 <formalpara id="form-Architecture_and_Design-user.add_Method-Response">
                     <title>Response</title>
                     <para>
@@ -2146,8 +2206,8 @@ if response_data.has_key('result'):
                 <para>
                     <itemizedlist>
                         <listitem>
-                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-_id_">
-                                <title> <literal>id</literal> </title>
+                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-id">
+                                <title><literal>id</literal></title>
                                 <para>
                                     Of type INT, this attribute is automatically assigned by the database backend, unless specifically supplied on insert.
                                 </para>
@@ -2156,8 +2216,8 @@ if response_data.has_key('result'):
 
                         </listitem>
                         <listitem>
-                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-_key_">
-                                <title> <literal>key</literal> </title>
+                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-key">
+                                <title><literal>key</literal></title>
                                 <para>
                                     Of type VARCHAR(16), the <literal>key</literal> attribute is to hold a machine readable name.
                                 </para>
@@ -2166,8 +2226,8 @@ if response_data.has_key('result'):
 
                         </listitem>
                         <listitem>
-                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-_name_">
-                                <title> <literal>name</literal> </title>
+                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-name">
+                                <title><literal>name</literal></title>
                                 <para>
                                     Of type VARCHAR(128), the <literal>name</literal> attribute is to be the human-readable name for the user type.
                                 </para>
@@ -2176,8 +2236,8 @@ if response_data.has_key('result'):
 
                         </listitem>
                         <listitem>
-                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-_description_">
-                                <title> <literal>description</literal> </title>
+                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-description">
+                                <title><literal>description</literal></title>
                                 <para>
                                     Of type VARCHAR(256), the <literal>description</literal> attribute holds the description for the user type.
                                 </para>
@@ -2186,8 +2246,8 @@ if response_data.has_key('result'):
 
                         </listitem>
                         <listitem>
-                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-_attributes_">
-                                <title> <literal>attributes</literal> </title>
+                            <formalpara id="form-Architecture_and_Design-Storage_Format_for_user_type-attributes">
+                                <title><literal>attributes</literal></title>
                                 <para>
                                     Of type TEXT, the <literal>attributes</literal> contains a serialized JSON object with the information needed for the API and client interface to build queries and forms for the user type.
                                 </para>
@@ -2199,8 +2259,8 @@ if response_data.has_key('result'):
                     </itemizedlist>
 
                 </para>
-                <section id="sect-Architecture_and_Design-Storage_Format_for_user_type-_The_attributes_Attribute_Value_Format">
-                    <title> The <literal>attributes</literal> Attribute Value Format</title>
+                <section id="sect-Architecture_and_Design-Storage_Format_for_user_type-The_attributes_Attribute_Value_Format">
+                    <title>The <literal>attributes</literal> Attribute Value Format</title>
                     <para>
                         The structure of the <literal>attributes</literal> attribute value is:
                     </para>
@@ -2228,7 +2288,7 @@ if response_data.has_key('result'):
                     <para>
                         <itemizedlist>
                             <listitem>
-                                <formalpara id="form-Architecture_and_Design-_The_attributes_Attribute_Value_Format-auto_form_fields">
+                                <formalpara id="form-Architecture_and_Design-The_attributes_Attribute_Value_Format-auto_form_fields">
                                     <title><literal>auto_form_fields</literal></title>
                                     <para>
                                         The <literal>auto_form_fields</literal> key holds an array of form fields that correspond with attributes for which the value is to be generated automatically, using an API call.
@@ -2241,7 +2301,7 @@ if response_data.has_key('result'):
                                 <para>
                                     Each array key corresponds with a user attribute name, and it's value is an array containing the name of the form fields for which the value to submit as part of the API call.
                                 </para>
-                                <example id="exam-Architecture_and_Design-_The_attributes_Attribute_Value_Format-A_Users_displayname">
+                                <example id="exam-Architecture_and_Design-The_attributes_Attribute_Value_Format-A_Users_displayname">
                                     <title>A User's <literal>displayname</literal></title>
                                     <para>
                                         Provided the user type's <literal>auto_form_fields</literal> contains an array key of <literal>displayname</literal>, the array value for this key could look as follows:
@@ -2276,7 +2336,7 @@ if response_data.has_key('result'):
 
                             </listitem>
                             <listitem>
-                                <formalpara id="form-Architecture_and_Design-_The_attributes_Attribute_Value_Format-form_fields">
+                                <formalpara id="form-Architecture_and_Design-The_attributes_Attribute_Value_Format-form_fields">
                                     <title><literal>form_fields</literal></title>
                                     <para>
                                         The <literal>form_fields</literal> key holds an array of form fields that require user input.
@@ -2290,7 +2350,7 @@ if response_data.has_key('result'):
                                     Because some attributes can be multi-valued, or have a limited list of options, each defined form field in <literal>form_fields</literal> can hold an array with additional key => value pairs illustrating the type of form field that should be used, and what format to expect the result value in.
                                 </para>
                                 <para>
-                                    <itemizedlist id="item-Architecture_and_Design-_The_attributes_Attribute_Value_Format-Additional_Information_in_form_fields">
+                                    <itemizedlist id="item-Architecture_and_Design-The_attributes_Attribute_Value_Format-Additional_Information_in_form_fields">
                                         <title>Additional Information in <literal>form_fields</literal></title>
                                         <listitem>
                                             <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-maxlength">
@@ -2406,7 +2466,7 @@ if response_data.has_key('result'):
 
                             </listitem>
                             <listitem>
-                                <formalpara id="form-Architecture_and_Design-_The_attributes_Attribute_Value_Format-fields">
+                                <formalpara id="form-Architecture_and_Design-The_attributes_Attribute_Value_Format-fields">
                                     <title><literal>fields</literal></title>
                                     <para>
                                         The <literal>fields</literal> key holds an array of form fields and values for said form fields, that are static. One example of such form fields is <literal>objectclass</literal>.
diff --git a/Architecture_and_Design/en-US/Configuration_Management.xml b/Architecture_and_Design/en-US/Configuration_Management.xml
index d24f454..487c3f7 100644
--- a/Architecture_and_Design/en-US/Configuration_Management.xml
+++ b/Architecture_and_Design/en-US/Configuration_Management.xml
@@ -192,12 +192,12 @@ key2 = value
 
                         </formalpara>
                         <para>
-                             Possible options currently include: 'ldap'.
-                         </para>
+                            Possible options currently include: 'ldap'.
+                        </para>
 
                     </listitem>
                     <listitem>
-                        <formalpara id="form-Architecture_and_Design-kolab-primary_domain_pykolab.constants.domainname">
+                        <formalpara id="form-Architecture_and_Design-kolab-primary_domain_constants.domainname">
                             <title><literal>primary_domain</literal> (<emphasis>constants.domainname</emphasis>)</title>
                             <para>
                                 The primary domain name space for this Kolab deployment. If not set, defaults to the value of the PyKolab constant <literal>domainname</literal>, which is derived from the system fully qualified domain name.
@@ -365,12 +365,14 @@ key2 = value
 
                     </listitem>
                     <listitem>
-                        <formalpara>
+                        <formalpara id="form-Architecture_and_Design-ldap-user_name_attribute_uid">
                             <title><literal>user_name_attribute</literal> (<emphasis>uid</emphasis>)</title>
                             <para>
                                 The RDN attribute name (and value) to use. The value for this configuration setting should use a globally unique attribute.
                             </para>
+
                         </formalpara>
+
                     </listitem>
                     <listitem>
                         <formalpara id="form-Architecture_and_Design-ldap-user_scope_sub">
@@ -466,12 +468,14 @@ key2 = value
 
                     </listitem>
                     <listitem>
-                        <formalpara>
+                        <formalpara id="form-Architecture_and_Design-ldap-group_name_attribute_cn">
                             <title><literal>group_name_attribute</literal> (<emphasis>cn</emphasis>)</title>
                             <para>
                                 The RDN attribute to use for groups. This should use a globally unique attribute.
                             </para>
+
                         </formalpara>
+
                     </listitem>
                     <listitem>
                         <formalpara id="form-Architecture_and_Design-ldap-group_scope_sub">
diff --git a/Architecture_and_Design/en-US/Groupware_Overview.xml b/Architecture_and_Design/en-US/Groupware_Overview.xml
index 23ad7d7..40826e2 100644
--- a/Architecture_and_Design/en-US/Groupware_Overview.xml
+++ b/Architecture_and_Design/en-US/Groupware_Overview.xml
@@ -397,6 +397,6 @@
         </itemizedlist>
 
     </para>
-    //  -->
+    //    -->
 </chapter>
 
diff --git a/Architecture_and_Design/en-US/Kolab_Daemon.xml b/Architecture_and_Design/en-US/Kolab_Daemon.xml
index 2650ab3..36b5a10 100644
--- a/Architecture_and_Design/en-US/Kolab_Daemon.xml
+++ b/Architecture_and_Design/en-US/Kolab_Daemon.xml
@@ -6,13 +6,404 @@
 <chapter id="chap-Architecture_and_Design-Kolab_Daemon">
     <title>Kolab Daemon</title>
     <para>
-        The Kolab daemon is a multi-process daemon that synchronizes the authentication and authorization database mutations with various aspects of a Kolab Groupware deployment.
+        The Kolab daemon is a multi-threaded daemon that synchronizes mutations made in the authentication and authorization database(s) with other components of a Kolab Groupware deployment.
     </para>
     <para>
+        This chapter describes how the Kolab daemon functions in detail, starting with <xref linkend="proc-Architecture_and_Design-Kolab_Daemon-Startup_amp_Continued_Operations_of_the_Kolab_Daemon" />.
+    </para>
+    <procedure id="proc-Architecture_and_Design-Kolab_Daemon-Startup_amp_Continued_Operations_of_the_Kolab_Daemon">
+        <title>Startup & Continued Operations of the Kolab Daemon</title>
+        <step>
+            <para>
+                Upon starting the Kolab daemon, a process <application>kolabd</application> obtains the primary authentication mechanism using the [kolab]/auth_mechanism setting in /etc/kolab/kolab.conf
+            </para>
+
+        </step>
+        <step>
+            <para>
+                Subsequently, using the primary section related to the authentication mechanism (i.e. [ldap] or [sql]), it determines the list of (parent) domain name spaces this environment services. The Kolab daemon does so in an endless loop in the master process, and refreshes this list every 10 minutes.
+            </para>
+            <para>
+                Related settings for LDAP include domain_root_dn, (kolab_)domain_filter, domain_name_attribute, domain_scope and domain_rootdn_attribute. Of impact as well, are ldap_uri, bind_dn, bind_pw.
+            </para>
+
+        </step>
+        <step>
+            <para>
+                For each (parent) domain name space it finds, a new process is created. For more details on process operations, please see <xref linkend="proc-Architecture_and_Design-Kolab_Daemon-Kolab_Daemon_Domain_Process_Operations" />.
+            </para>
+
+        </step>
+        <step>
+            <para>
+                Processes are named after their parent domain name space's unique_attribute (entryUUID or nsuniqueid). Should a process die, it is removed from the pool of existing processes, and restarted on the next iteration of listing domains.
+            </para>
+
+        </step>
+
+    </procedure>
+
+    <procedure id="proc-Architecture_and_Design-Kolab_Daemon-Kolab_Daemon_Domain_Process_Operations">
+        <title>Kolab Daemon Domain Process Operations</title>
+        <step>
+            <para>
+                Get from configuration the filter settings for the following objects, whichever applicable, and compose a single filter of them.
+            </para>
+            <para>
+                <itemizedlist id="item-Architecture_and_Design-Kolab_Daemon_Domain_Process_Operations-Object_Types">
+                    <title>Object Types</title>
+                    <listitem>
+                        <para>
+                            users,
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            groups,
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            shared folders,
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            roles,
+                        </para>
+
+                    </listitem>
+
+                </itemizedlist>
+
+            </para>
+            <para>
+                The configured filter is obtained by first attempting to get the 'kolab' type prefixed filter, i.e. 'kolab_user_filter', and falls back to the non-type specific filter, i.e. 'user_filter'.
+            </para>
+            <para>
+                The composed search filter for users, groups and shared folders could look like:
+            </para>
+            <example id="exam-Architecture_and_Design-Kolab_Daemon_Domain_Process_Operations-Example_users_groups_and_shared_folders_search_filter">
+                <title>Example users, groups and shared folders search filter</title>
+                <para>
+
+<screen>(|(objectclass=kolabinetorgperson)(|(objectclass=kolabgroupofuniquenames)(objectclass=kolabgroupofurls))(objectclass=kolabsharedfolder))</screen>
+
+                </para>
+
+            </example>
+
+        </step>
+        <step>
+            <para>
+                Create a search for object types relevant to domain. Here, the Kolab Daemon splits up depending on the supported controls on LDAP server technology, and the queries supported by SQL server technology.
+            </para>
+
+        </step>
+
+    </procedure>
+
+    <procedure id="proc-Architecture_and_Design-Kolab_Daemon-LDAP_amp_Persistent_Search">
+        <title>LDAP & Persistent Search</title>
+        <step>
+            <para>
+                The search is created to return all entries with a modification timestamp equal to or greater than the last time the Kolab Daemon had successfully followed up on a controlled search EntryChangeNotification.
+            </para>
+
+        </step>
+        <step>
+            <para>
+                For each entry returned follow up with the appropriate action using the client EntryChangeNotification control:
+            </para>
+            <formalpara id="form-Architecture_and_Design-LDAP_amp_Persistent_Search-None">
+                <title><literal>None</literal></title>
+                <para>
+                    An EntryChangeNotification of type <literal>None</literal> (as in the original results set) looks as follows (markup for readibility):
+                </para>
+
+            </formalpara>
+            <example id="exam-Architecture_and_Design-LDAP_amp_Persistent_Search-Example_Persistent_Search_result_no_EntryChangeNotification">
+                <title>Example Persistent Search result (no EntryChangeNotification)</title>
+                <para>
+
+<screen>DEBUG [18116]: LDAP Search Result Data Entry:
+DEBUG [18116]:    DN: 'uid=doe,ou=People,dc=example,dc=org'
+DEBUG [18116]:    Entry: {
+        'displayName': ['Doe, John'],
+        'cn': ['John Doe'],
+        'preferredLanguage': ['en_US'],
+        'userPassword': ['{SSHA}SomethingSomething=='],
+        'mailAlternateAddress': ['j.doe at example.org', 'doe at example.org'],
+        'objectClass': [
+                'top',
+                'inetorgperson',
+                'kolabinetorgperson',
+                'mailrecipient',
+                'organizationalperson',
+                'person'
+            ],
+        'sn': ['Doe'],
+        'mail': ['john.doe at example.org'],
+        'ou': ['ou=people,dc=example,dc=org'],
+        'givenName': ['John'],
+        'uid': ['doe']
+    }
+</screen>
+
+                </para>
+
+            </example>
+            <formalpara id="form-Architecture_and_Design-LDAP_amp_Persistent_Search-add">
+                <title><literal>add</literal></title>
+                <para>
+                    An EntryChangeNotification of type <literal>add</literal> looks as follows (markup for readibility):
+                </para>
+
+            </formalpara>
+            <example id="exam-Architecture_and_Design-LDAP_amp_Persistent_Search-Example_Persistent_Search_result_EntryChangeNotification_of_type_add">
+                <title>Example Persistent Search result (EntryChangeNotification of type <literal>add</literal>)</title>
+                <para>
+
+<screen>DEBUG [4595]: LDAP Search Result Data Entry:
+DEBUG [4595]:    DN: 'uid=doe,ou=People,dc=example,dc=org'
+DEBUG [4595]:    Entry: {
+        'displayName': ['Doe, John'],
+        'cn': ['John Doe'],
+        'preferredLanguage': ['en_US'],
+        'userPassword': ['{SSHA}SomethingSomething=='],
+        'nsuniqueid': ['afda3481-83c311e1-9bbdc2f1-b2ae40b4'],
+        'mailAlternateAddress': ['j.doe at example.org', 'doe at example.org'],
+        'objectClass': [
+                'top',
+                'inetorgperson',
+                'kolabinetorgperson',
+                'mailrecipient',
+                'organizationalperson',
+                'person'
+            ],
+        'sn': ['Doe'],
+        'mail': ['john.doe at example.org'],
+        'ou': ['ou=people,dc=example,dc=org'],
+        'givenName': ['John'],
+        'uid': ['doe']
+    }
+DEBUG [4595]: Entry Change Notification attributes:
+DEBUG [4595]:    Change Type: 1 ('add')
+DEBUG [4595]:    Previous DN: None
+</screen>
+
+                </para>
+
+            </example>
+
+        </step>
+        <step>
+            <para>
+                The Kolab Daemon determines the type of object having been added, modified, deleted or moved by matching the object against any of the object type specific search filters.
+            </para>
+
+        </step>
+        <step>
+            <para>
+                Subsequently, it calls either one of the functions;
+            </para>
+            <para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+                            _change_group_none(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_user_none(entry, change)
+                        </para>
+                        <procedure>
+                            <step>
+                                <para>
+                                    Check if a result attribute exists with a valid value
+                                </para>
+                                <substeps>
+                                    <step>
+                                        <para>
+                                            if not, see if recipient policy exists
+                                        </para>
+                                        <substeps>
+                                            <step>
+                                                <para>
+                                                    if yes, populate result attribute and continue as if result attribute always existed
+                                                </para>
+
+                                            </step>
+                                            <step>
+                                                <para>
+                                                    if not, ignore the entry
+                                                </para>
+
+                                            </step>
+
+                                        </substeps>
+
+                                    </step>
+                                    <step>
+                                        <para>
+                                            if yes, check if mailbox exists
+                                        </para>
+                                        <substeps>
+                                            <step>
+                                                <para>
+                                                    if not, create mailbox
+                                                </para>
+
+                                            </step>
+                                            <step>
+                                                <para>
+                                                    if yes, continue
+                                                </para>
+
+                                            </step>
+
+                                        </substeps>
+
+                                    </step>
+
+                                </substeps>
+
+                            </step>
+
+                        </procedure>
+
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_role_none(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_sharedfolder_none(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_group_add(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_user_add(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_role_add(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_sharedfolder_add(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_group_delete(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_user_delete(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_role_delete(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_sharedfolder_delete(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_group_modify(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_user_modify(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_role_modify(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_sharedfolder_modify(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_group_modrdn(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_user_modrdn(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_role_modrdn(entry, change)
+                        </para>
+
+                    </listitem>
+                    <listitem>
+                        <para>
+                            _change_sharedfolder_modrdn(entry, change)
+                        </para>
+
+                    </listitem>
+
+                </itemizedlist>
+
+            </para>
+
+        </step>
+
+    </procedure>
+
+    <para>
         Using the <literal>[ldap]</literal> <literal>domain_*</literal> settings, (domain_base_dn, domain_search_filter, domain_search_scope, domain_name_attribute, ...), the Kolab daemon determines the number of authentication databases for which to render service, as each domain name space may require either a switch in authn/authz technology, or different bind credentials.
     </para>
     <note>
-        This functionality is currently limited to LDAP only.
+        <para>
+            This functionality is currently limited to LDAP only.
+        </para>
+
     </note>
     <para>
         To illustrate, one of its responsibilities is to make sure adding a new user is propagated in the form of a new mailbox.
diff --git a/Architecture_and_Design/en-US/Terminology.xml b/Architecture_and_Design/en-US/Terminology.xml
index 9aa02c3..ad8742a 100644
--- a/Architecture_and_Design/en-US/Terminology.xml
+++ b/Architecture_and_Design/en-US/Terminology.xml
@@ -62,6 +62,13 @@
 <screen>$ <userinput>ldapsearch -x -b "ou=People,dc=example,dc=org"</userinput></screen>
 
     </para>
+    <formalpara id="form-Architecture_and_Design-Terminology-Domain_Base_DN">
+        <title>Domain Base DN</title>
+        <para>
+            The base dn used for domain name spaces.
+        </para>
+
+    </formalpara>
     <formalpara id="form-Architecture_and_Design-Terminology-Bind_Credentials">
         <title>Bind Credentials</title>
         <para>





More information about the commits mailing list