summaryrefslogtreecommitdiff
path: root/Architecture_and_Design/en-US/Kolab_Daemon.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Architecture_and_Design/en-US/Kolab_Daemon.xml')
-rw-r--r--Architecture_and_Design/en-US/Kolab_Daemon.xml395
1 files changed, 393 insertions, 2 deletions
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 &amp; 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 &amp; 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@example.org', 'doe@example.org'],
+ 'objectClass': [
+ 'top',
+ 'inetorgperson',
+ 'kolabinetorgperson',
+ 'mailrecipient',
+ 'organizationalperson',
+ 'person'
+ ],
+ 'sn': ['Doe'],
+ 'mail': ['john.doe@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@example.org', 'doe@example.org'],
+ 'objectClass': [
+ 'top',
+ 'inetorgperson',
+ 'kolabinetorgperson',
+ 'mailrecipient',
+ 'organizationalperson',
+ 'person'
+ ],
+ 'sn': ['Doe'],
+ 'mail': ['john.doe@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.