7 commits - Administrator_Guide/en-US Architecture_and_Design/en-US
Jeroen van Meeuwen
vanmeeuwen at kolabsys.com
Sun Apr 1 15:03:17 CEST 2012
Administrator_Guide/en-US/Combating_Spam.xml | 2
Architecture_and_Design/en-US/Administration_Panel.xml | 718 ++++++++++++-
Architecture_and_Design/en-US/Configuration_Management.xml | 92 +
Architecture_and_Design/en-US/Groupware_Overview.xml | 6
Architecture_and_Design/en-US/Kolab_Content_Filters.xml | 2
Architecture_and_Design/en-US/Kolab_Daemon.xml | 20
Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml | 5
7 files changed, 801 insertions(+), 44 deletions(-)
New commits:
commit 8bb0d402b9b7cee0fc924ea570226f914f933643
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 14:03:00 2012 +0100
Update verbiage in Kolab SMTP Access Policy
diff --git a/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml b/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml
index 5b38b63..033b473 100644
--- a/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml
+++ b/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml
@@ -6,7 +6,10 @@
<chapter id="chap-Architecture_and_Design-Kolab_SMTP_Access_Policy">
<title>Kolab SMTP Access Policy</title>
<para>
- The Kolab SMTP Access Policy is a policy service for Postfix that allows delegation, mandatory recipient and sender access controls to be applied, using the <ulink url="http://www.postfix.org/SMTPD_POLICY_README.html">Postfix SMTPD Policy</ulink>, and verifies envelope sender addresses used against the authentication and authorization database.
+ The Kolab SMTP Access Policy is a policy service for Postfix that applies mandatory recipient and sender address access controls using the <ulink url="http://www.postfix.org/SMTPD_POLICY_README.html">Postfix SMTPD Policy</ulink>.
+ </para>
+ <para>
+ It verifies envelope sender address used in the message against the authentication and authorization database.
</para>
<section id="sect-Architecture_and_Design-Kolab_SMTP_Access_Policy-What_the_Kolab_SMTP_Access_Policy_is">
<title>What the Kolab SMTP Access Policy is</title>
commit daf950b80f1cd671b06cc40653fe16df5507eaef
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 14:01:23 2012 +0100
Start work on the Kolab daemon
diff --git a/Architecture_and_Design/en-US/Kolab_Daemon.xml b/Architecture_and_Design/en-US/Kolab_Daemon.xml
index c428886..2650ab3 100644
--- a/Architecture_and_Design/en-US/Kolab_Daemon.xml
+++ b/Architecture_and_Design/en-US/Kolab_Daemon.xml
@@ -6,7 +6,25 @@
<chapter id="chap-Architecture_and_Design-Kolab_Daemon">
<title>Kolab Daemon</title>
<para>
- TODO
+ The Kolab daemon is a multi-process daemon that synchronizes the authentication and authorization database mutations with various aspects of a Kolab Groupware deployment.
+ </para>
+ <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.
+ </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.
+ </para>
+ <para>
+ The master process determines the number of domain name spaces served from different authentication and authorization sources.
+ </para>
+ <para>
+ For LDAP based deployments, this includes multiple domain name spaces served with different root dns.
+ </para>
+ <para>
+ It uses /etc/kolab/kolab.conf, section ldap, keys domain_base_dn, domain_rootdn_attribute, domain_filter, domain_name_attribute.
</para>
</chapter>
commit 64a814dad480a281aae360b2c15d668638a2c9b6
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 14:00:18 2012 +0100
Update verbiage on Groupware Overview
diff --git a/Architecture_and_Design/en-US/Groupware_Overview.xml b/Architecture_and_Design/en-US/Groupware_Overview.xml
index ca6dad1..23ad7d7 100644
--- a/Architecture_and_Design/en-US/Groupware_Overview.xml
+++ b/Architecture_and_Design/en-US/Groupware_Overview.xml
@@ -60,7 +60,7 @@
All of the former are capabilities provided by Kolab Groupware itself.
</para>
<para>
- Collaboration also includes, however;
+ Technologies assisting collaborative efforts also include, however;
</para>
<para>
<itemizedlist>
@@ -118,8 +118,9 @@
</para>
<para>
- While each of the aforementioned aspects of groupware and collaboration is available as Free Software, integration is another topic.
+ While each of the aforementioned aspects of groupware and collaboration is available as Free Software, integration is an entirely different topic.
</para>
+ <!--
<para>
The following is a list of items that somehow, to some extent, relate to a groupware environment;
</para>
@@ -396,5 +397,6 @@
</itemizedlist>
</para>
+ // -->
</chapter>
commit 4bf342479f954c32d39d30de2284077c86761360
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 13:59:53 2012 +0100
Update chapter on configuration management
diff --git a/Architecture_and_Design/en-US/Configuration_Management.xml b/Architecture_and_Design/en-US/Configuration_Management.xml
index af17bf2..d24f454 100644
--- a/Architecture_and_Design/en-US/Configuration_Management.xml
+++ b/Architecture_and_Design/en-US/Configuration_Management.xml
@@ -151,7 +151,7 @@ admins: cyrus-admin
<section id="sect-Architecture_and_Design-Configuration_Management-Kolab_Configuration_File">
<title>Kolab Configuration File</title>
<para>
- The Kolab configuration file is <filename>/etc/kolab/kolab.conf</filename>.
+ The main Kolab configuration file is <filename>/etc/kolab/kolab.conf</filename>.
</para>
<note>
<title>TODO</title>
@@ -179,7 +179,7 @@ key2 = value
<section id="sect-Architecture_and_Design-Kolab_Configuration_File-kolab">
<title>[kolab]</title>
<para>
- The following is an overview of settings in the <literal>[kolab]</literal> section:
+ The following is an overview of settings available in the <literal>[kolab]</literal> section:
</para>
<para>
<itemizedlist>
@@ -187,15 +187,18 @@ key2 = value
<formalpara id="form-Architecture_and_Design-kolab-auth_mechanism_ldap">
<title><literal>auth_mechanism</literal> (<emphasis>ldap</emphasis>)</title>
<para>
- The authentication and authorization database technology to use for the primary domain name space in this Kolab deployment. If not set, defaults to a value of 'ldap'. Possible options include: 'ldap'.
+ The authentication and authorization database technology to use for the primary domain name space in this Kolab deployment. If not set, defaults to a value of 'ldap'.
</para>
</formalpara>
+ <para>
+ Possible options currently include: 'ldap'.
+ </para>
</listitem>
<listitem>
<formalpara id="form-Architecture_and_Design-kolab-primary_domain_pykolab.constants.domainname">
- <title><literal>primary_domain</literal> (<emphasis>pykolab.constants.domainname</emphasis>)</title>
+ <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.
</para>
@@ -211,6 +214,9 @@ key2 = value
</para>
</formalpara>
+ <para>
+ Valid options currently include: <emphasis>cyrus-imap</emphasis>
+ </para>
</listitem>
<listitem>
@@ -261,12 +267,12 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-base_dn_None">
<title><literal>base_dn</literal> (<emphasis>None</emphasis>)</title>
<para>
- This setting contains the absolute top-level that Kolab is allowed to use. While most commonly the same value as the root distinguished name (root dn) for the tree, for example <emphasis>dc=example,dc=org</emphasis> this just is not always the case.
+ This setting contains the absolute top-level that Kolab is allowed to use. While most commonly the same value as the root distinguished name (root dn) for the tree, <emphasis>dc=example,dc=org</emphasis> for example, this is not always the case.
</para>
</formalpara>
<para>
- Despite the fact that we can generate a domain-component oriented naming scheme base dn from the domain name space configured as or believed to be the primary domain, we require configuration of the overall base distinguished name (base dn) as LDAP trees may use a non-domain component oriented naming scheme, such as <emphasis>o=organization,c=nl</emphasis>, or use a different level of depth.
+ Despite the fact that Kolab can generate a domain-component oriented naming scheme base dn from the domain name space configured as or believed to be the primary domain, Kolab often requires the configuration of the overall base distinguished name (base dn) as LDAP trees may use a non-domain component oriented naming scheme, such as <emphasis>o=organization,c=nl</emphasis>, or use a different level of depth.
</para>
</listitem>
@@ -274,7 +280,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-bind_dn_None">
<title><literal>bind_dn</literal> (<emphasis>None</emphasis>)</title>
<para>
- The distinguished name of the account to use for bind operations. This is (or should be) part of a set of bind credentials used as a last resort only.
+ The distinguished name of the account to use for bind operations. This is part of a set of bind credentials used as a last resort only.
</para>
</formalpara>
@@ -300,20 +306,26 @@ key2 = value
</listitem>
<listitem>
- <formalpara id="form-Architecture_and_Design-ldap-auth_attrs_mail">
- <title><literal>auth_attrs</literal> (<emphasis>mail</emphasis>)</title>
+ <formalpara id="form-Architecture_and_Design-ldap-auth_attributes_mail">
+ <title><literal>auth_attributes</literal> (<emphasis>mail</emphasis>)</title>
<para>
- para
+ A comma- or comma-space separated list of entry attribute names of which the value is to be allowed as the login name during authentication.
</para>
</formalpara>
+ <para>
+ This enables an administrator to allow users to login with their entry's <literal>uid</literal> attribute value, in addition to their entry's <literal>mail</literal> attribute value.
+ </para>
+ <para>
+ Common attribute names in this list include: <literal>alias</literal>, <literal>mail</literal>, <literal>mailAlternateAddress</literal>, <literal>uid</literal>.
+ </para>
</listitem>
<listitem>
<formalpara id="form-Architecture_and_Design-ldap-quota_attribute_mailquota">
<title><literal>quota_attribute</literal> (<emphasis>mailquota</emphasis>)</title>
<para>
- para
+ The attribute to use for a user's mail quota.
</para>
</formalpara>
@@ -323,7 +335,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-mailserver_attribute_mailhost">
<title><literal>mailserver_attribute</literal> (<emphasis>mailhost</emphasis>)</title>
<para>
- para
+ The attribute to use for a user's mail server.
</para>
</formalpara>
@@ -333,27 +345,38 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-user_base_dn_base_dns">
<title><literal>user_base_dn</literal> (<emphasis>%(base_dn)s</emphasis>)</title>
<para>
- para
+ The base dn to use when searching for users.
</para>
</formalpara>
+ <para>
+ If not specified, the value of <xref linkend="form-Architecture_and_Design-ldap-base_dn_None" /> is used.
+ </para>
</listitem>
<listitem>
<formalpara id="form-Architecture_and_Design-ldap-user_filter_objectClass">
<title><literal>user_filter</literal> (<emphasis>(objectClass=*)</emphasis>)</title>
<para>
- para
+ The filter to use when searching for users.
</para>
</formalpara>
</listitem>
<listitem>
+ <formalpara>
+ <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">
<title><literal>user_scope</literal> (<emphasis>sub</emphasis>)</title>
<para>
- para
+ The scope to use when searching for users.
</para>
</formalpara>
@@ -363,17 +386,20 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-kolab_user_base_dn_base_dns">
<title><literal>kolab_user_base_dn</literal> (<emphasis>%(base_dn)s</emphasis>)</title>
<para>
- para
+ The base dn to use when searching for users of type 'kolab'.
</para>
</formalpara>
+ <para>
+ If not specified, the value of <xref linkend="form-Architecture_and_Design-ldap-user_base_dn_base_dns" /> is used.
+ </para>
</listitem>
<listitem>
<formalpara id="form-Architecture_and_Design-ldap-kolab_user_filter_objectClass">
<title><literal>kolab_user_filter</literal> (<emphasis>(objectClass=*)</emphasis>)</title>
<para>
- para
+ The filter to use when searching for users of type 'kolab'.
</para>
</formalpara>
@@ -383,7 +409,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-kolab_user_scope_sub">
<title><literal>kolab_user_scope</literal> (<emphasis>sub</emphasis>)</title>
<para>
- para
+ The scope to use when searching for users of type 'kolab'.
</para>
</formalpara>
@@ -393,7 +419,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-special_user_base_dn_base_dns">
<title><literal>special_user_base_dn</literal> (<emphasis>%(base_dn)s</emphasis>)</title>
<para>
- para
+ The base dn to use when searching for users of type 'special'.
</para>
</formalpara>
@@ -403,7 +429,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-special_user_filter_objectClass">
<title><literal>special_user_filter</literal> (<emphasis>(objectClass=*)</emphasis>)</title>
<para>
- para
+ The filter to use when searching for users of type 'special'.
</para>
</formalpara>
@@ -413,7 +439,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-special_user_scope_sub">
<title><literal>special_user_scope</literal> (<emphasis>sub</emphasis>)</title>
<para>
- para
+ The scope to use when searching for users of type 'special'.
</para>
</formalpara>
@@ -423,7 +449,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-group_base_dn_base_dns">
<title><literal>group_base_dn</literal> (<emphasis>%(base_dn)s</emphasis>)</title>
<para>
- para
+ The base dn to use when searching for groups.
</para>
</formalpara>
@@ -433,17 +459,25 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-group_filter_objectClass">
<title><literal>group_filter</literal> (<emphasis>(objectClass=*)</emphasis>)</title>
<para>
- para
+ The filter to use when searching for groups.
</para>
</formalpara>
</listitem>
<listitem>
+ <formalpara>
+ <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">
<title><literal>group_scope</literal> (<emphasis>sub</emphasis>)</title>
<para>
- para
+ The scope to use when searching for groups.
</para>
</formalpara>
@@ -453,7 +487,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-domain_base_dn_base_dns">
<title><literal>domain_base_dn</literal> (<emphasis>%(base_dn)s</emphasis>)</title>
<para>
- para
+ The base dn to use when searching for domains.
</para>
</formalpara>
@@ -463,7 +497,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-domain_filter_objectClass">
<title><literal>domain_filter</literal> (<emphasis>(objectClass=*)</emphasis>)</title>
<para>
- para
+ The filter to use when searching for domains.
</para>
</formalpara>
@@ -473,7 +507,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-domain_scope_sub">
<title><literal>domain_scope</literal> (<emphasis>sub</emphasis>)</title>
<para>
- para
+ The scope to use when searching for domains.
</para>
</formalpara>
@@ -483,7 +517,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-domain_name_attribute_associateddomain">
<title><literal>domain_name_attribute</literal> (<emphasis>associateddomain</emphasis>)</title>
<para>
- para
+ The naming attribute for domains. Results in the first value of the list of values contained within the attribute values for a single entry to be used as the Relative Distinguished Name (RDN).
</para>
</formalpara>
@@ -493,7 +527,7 @@ key2 = value
<formalpara id="form-Architecture_and_Design-ldap-domain_rootdn_attribute_inetdomainbasedn">
<title><literal>domain_rootdn_attribute</literal> (<emphasis>inetdomainbasedn</emphasis>)</title>
<para>
- para
+ The attribute that contains a reference to the root dn to use for the domain.
</para>
</formalpara>
commit add52305fc8cb050fd740d92a618fa5396eff383
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 13:59:21 2012 +0100
Tweak language in combating spam
diff --git a/Administrator_Guide/en-US/Combating_Spam.xml b/Administrator_Guide/en-US/Combating_Spam.xml
index f5b6244..81e3225 100644
--- a/Administrator_Guide/en-US/Combating_Spam.xml
+++ b/Administrator_Guide/en-US/Combating_Spam.xml
@@ -15,7 +15,7 @@
A common deployment is to define deployment-wide user preferences and to use a single, deployment-wide set of rules for <application>SpamAssassin</application> to operate with -including Bayes database(s).
</para>
<para>
- The problems start when individual users mark legitimate email as spam, most notably the company newsletter or correspondation they have opted in for some time ago, but wish to no longer receive. Users tend to ignore the long-term effects of marking these message as spam, if at all they are aware of any, and just want such messages out of they way.
+ The problems start when individual users mark legitimate email as spam, most notably the company newsletter or correspondation they have opted in some time ago, but wish to no longer receive. Users tend to ignore the long-term effects of marking these message as spam, if at all they are aware of any, and just want such messages out of their way.
</para>
<para>
Common examples of the sort of messages that are often marked as spam while being legitimate traffic include:
commit a15f0bac02709e5ef8c8ca64f80120c1db9fecd6
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 13:58:46 2012 +0100
Update documentation on Administration Panel
diff --git a/Architecture_and_Design/en-US/Administration_Panel.xml b/Architecture_and_Design/en-US/Administration_Panel.xml
index 9c413df..c44aae9 100644
--- a/Architecture_and_Design/en-US/Administration_Panel.xml
+++ b/Architecture_and_Design/en-US/Administration_Panel.xml
@@ -192,7 +192,10 @@
In another rule-of-thumb we outline the naming convention for services and methods.
</para>
<para>
- Service names consist of an object name either in singular or plural form. The singular form depicts actions are placed against a single instance of an object, such as <literal>object.add</literal>, whereas the plural form depicts actions are placed against multiple instances of an object, such as <literal>objects.list</literal> or <literal>objects.search</literal>.
+ Service names consist of an object name either in singular or plural form. The singular form depicts actions are placed against a single instance of an object, such as <literal>object.add</literal>, or at most one result entry is expected, such as <literal>object.find</literal>.
+ </para>
+ <para>
+ The plural form depicts actions that are placed against multiple instances of an object, such as <literal>objects.list</literal> or <literal>objects.search</literal>, or expect zero, one or more result entries to be returned.
</para>
<para>
Method names often imply an action is placed against one or more objects in one request. Certain actions may be confusing though. For these we have the following rules;
@@ -203,7 +206,7 @@
<formalpara id="form-Architecture_and_Design-Service_and_Method_Naming_Convention-Finding_an_object">
<title>Finding an object</title>
<para>
- The method <literal>find</literal> is always executed against the service with the singular form of the object name. The target of calling a <literal>find</literal> method is to obtain exactly one instance of an object. The method should fail if the result set contains any number of objects not one.
+ The method <literal>find</literal> is always executed against the service with the singular form of the object name. The target of calling a <literal>find</literal> method is to obtain exactly zero or one instance of an object. The method should fail if the result set contains any number of objects not zero or one.
</para>
</formalpara>
@@ -246,6 +249,19 @@
</para>
<para>
+ The reponse to a successful request that is expected to return a zero or one item, such as <literal>find</literal> methods, includes a result layout as follows:
+ </para>
+ <para>
+
+<screen language="Python">{
+ "status": "OK",
+ "result": {
+ (... entry data ...)
+ }
+}</screen>
+
+ </para>
+ <para>
The reponse to a successful request that is expected to return a list of zero, one or more items, such as <literal>list</literal> and <literal>search</literal> methods, includes a result layout as follows:
</para>
<para>
@@ -282,7 +298,7 @@
<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.
+ 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>
@@ -307,28 +323,88 @@
</itemizedlist>
</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-owner">
- <title><literal>owner</literal></title>
+ <formalpara id="form-Architecture_and_Design-domain.add_Method-parent">
+ <title><literal>parent</literal></title>
<para>
- If specified, MUST refer to an existing domain name space.
+ The domain name space for which the domain name space being created is an alias.
</para>
</formalpara>
- <remark> We need to verify owner is a valid attribute to an associated domain, and/or find a different mechanism for delegation between ISP, any level of resellers, and customers. Note that perhaps also the level of delegation can be tricky (@hotmail.com hosted style) </remark>
+ <para>
+ If specified, the parent MUST refer to an existing domain name space.
+ </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>
+
+ </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>
+
+ </formalpara>
+ <para>
+ This parameter is only valid for new domain name spaces added without a parent.
+ </para>
+ <para>
+ The administrative group is searched after the domain name space is added. Should the group not exist, it is created.
+ </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>
+ This parameter is only valid for new domain name spaces added without a parent.
+ </para>
+ <para>
+ The administrative role is searched after the domain name space is added. Should the role not exist, it is created.
+ </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>
+ 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.
+ </para>
+ <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.
+ </para>
+ <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.
+ </para>
</listitem>
</itemizedlist>
</para>
- --> <formalpara id="form-Architecture_and_Design-domain.add_Method-HTTP_Methods">
+ <formalpara id="form-Architecture_and_Design-domain.add_Method-HTTP_Methods">
<title>HTTP Method(s)</title>
<para>
POST, with an <literal>X-Session-Token</literal> HTTP/1.1 header.
@@ -752,6 +828,343 @@ domain_dn="dc=${domain_dn}"
</section>
+ <section id="sect-Architecture_and_Design-Web_Administration_Panel_API-The_form_value_Service">
+ <title>The <literal>form_value</literal> Service</title>
+ <section id="sect-Architecture_and_Design-The_form_value_Service-form_value.generate_Method">
+ <title><literal>form_value.generate</literal> Method</title>
+ <para>
+ This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested.
+ </para>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-Parameters">
+ <title>Parameters</title>
+ <para>
+ The <literal>form_value.generate</literal> API call accepts the following parameters:
+ </para>
+
+ </formalpara>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-attribute">
+ <title>attribute</title>
+ <para>
+ The name of the attribute to generate the new value for.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-data">
+ <title>data</title>
+ <para>
+ An array with key => value pairs containing the attribute name (key) and attribute value (value) to use to generate the new value for the attribute supplied in <xref linkend="form-Architecture_and_Design-form_value.validate_Method-attribute" />.
+ </para>
+
+ </formalpara>
+ <para>
+ This parameter is required for certain attributes, such as <literal>cn</literal>, but not for other attributes, such as <literal>userPassword</literal>.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-user_type_id">
+ <title>user_type_id</title>
+ <para>
+ An optional parameter to indicate to the API that the formation policy for users should be used.
+ </para>
+
+ </formalpara>
+ <para>
+ Supply an integer indicating the user type to use policies for that user type.
+ </para>
+ <para>
+ Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type.
+ </para>
+ <para>
+ Supply a boolean False to reject the use of any user policy.
+ </para>
+ <para>
+ The default for this parameter is False.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-group_type_id">
+ <title>group_type_id</title>
+ <para>
+ An optional parameter to indicate to the API that the formation policy for groups should be used.
+ </para>
+
+ </formalpara>
+ <para>
+ Supply an integer indicating the group type to use policies for that group type.
+ </para>
+ <para>
+ Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type.
+ </para>
+ <para>
+ Supply a boolean False to reject the use of any group policy.
+ </para>
+ <para>
+ The default for this parameter is False.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <important>
+ <para>
+ The API call does not allow both the <literal>user_type_id</literal> and <literal>group_type_id</literal> to;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ both be boolean False,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ both be boolean True,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ both be an integer reference to each respective type ID.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </important>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-HTTP_Methods">
+ <title>HTTP Method(s)</title>
+ <para>
+ POST, with an <literal>X-Session-Token</literal> HTTP/1.1 header.
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-Example_Client_Implementation">
+ <title>Example Client Implementation</title>
+ <para>
+ A client could choose to have a user's password generated by the API.
+ </para>
+
+ </formalpara>
+ <example id="exam-Architecture_and_Design-form_value.generate_Method-Generate_the_User_Password_with_the_API">
+ <title>Generate the User Password with the API</title>
+ <para>
+
+<screen language="Python">result = request('POST', 'form_value.generate_userpassword')
+print result['userpassword']
+</screen>
+
+ </para>
+
+ </example>
+ <formalpara id="form-Architecture_and_Design-form_value.generate_Method-Response">
+ <title>Response</title>
+ <para>
+
+<screen language="Python">{
+ "status": "OK",
+ "result": {
+ "password": "3SQLAdcW_KZL5vO"
+ }
+ }</screen>
+
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-The_form_value_Service-form_value.list_options_Method">
+ <title><literal>form_value.list_options</literal> Method</title>
+ <para>
+ para
+ </para>
+ <formalpara id="form-Architecture_and_Design-form_value.list_options_Method-Parameters">
+ <title>Parameters</title>
+ <para>
+ params
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.list_options_Method-HTTP_Methods">
+ <title>HTTP Method(s)</title>
+ <para>
+ POST, with an <literal>X-Session-Token</literal> HTTP/1.1 header.
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.list_options_Method-Example_Client_Implementation">
+ <title>Example Client Implementation</title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.list_options_Method-Response">
+ <title>Response</title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-The_form_value_Service-form_value.validate_Method">
+ <title><literal>form_value.validate</literal> Method</title>
+ <para>
+ para
+ </para>
+ <para>
+ This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested.
+ </para>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-Parameters">
+ <title>Parameters</title>
+ <para>
+ The <literal>form_value.validate</literal> API call accepts the following parameters:
+ </para>
+
+ </formalpara>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-attribute">
+ <title>attribute</title>
+ <para>
+ The name of the attribute to validate the value for.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-data">
+ <title>data</title>
+ <para>
+ The data to validate.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-user_type_id">
+ <title>user_type_id</title>
+ <para>
+ An optional parameter to indicate to the API that the validation policy for users should be used.
+ </para>
+
+ </formalpara>
+ <para>
+ Supply an integer indicating the user type to use policies for that user type.
+ </para>
+ <para>
+ Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type.
+ </para>
+ <para>
+ Supply a boolean False to reject the use of any user policy.
+ </para>
+ <para>
+ The default for this parameter is False.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-group_type_id">
+ <title>group_type_id</title>
+ <para>
+ An optional parameter to indicate to the API that the validation policy for groups should be used.
+ </para>
+
+ </formalpara>
+ <para>
+ Supply an integer indicating the group type to use policies for that group type.
+ </para>
+ <para>
+ Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type.
+ </para>
+ <para>
+ Supply a boolean False to reject the use of any group policy.
+ </para>
+ <para>
+ The default for this parameter is False.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <important>
+ <para>
+ The API call does not allow both the <literal>user_type_id</literal> and <literal>group_type_id</literal> to;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ both be boolean False,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ both be boolean True,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ both be an integer reference to each respective type ID.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </important>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-HTTP_Methods">
+ <title>HTTP Method(s)</title>
+ <para>
+ POST, with an <literal>X-Session-Token</literal> HTTP/1.1 header.
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-Example_Client_Implementation">
+ <title>Example Client Implementation</title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+ <formalpara id="form-Architecture_and_Design-form_value.validate_Method-Response">
+ <title>Response</title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </section>
+
+
+ </section>
+
<section id="sect-Architecture_and_Design-Web_Administration_Panel_API-The_group_Service">
<title>The <literal>group</literal> Service</title>
<section id="sect-Architecture_and_Design-The_group_Service-group.info_Method">
@@ -1720,6 +2133,293 @@ if response_data.has_key('result'):
</section>
+ <section id="sect-Architecture_and_Design-The_user_types_Service-Storage_Format_for_user_type">
+ <title>Storage Format for <literal>user_type</literal></title>
+ <para>
+ The user types are backed by database entries, containing the following attributes per user type:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <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>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <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>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <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>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <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>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <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>
+
+ </formalpara>
+
+ </listitem>
+
+ </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>
+ <para>
+ The structure of the <literal>attributes</literal> attribute value is:
+ </para>
+
+<screen language="PHP/PHP">Array(
+ "<form_field_type>" => Array(
+ "<form_field_name>" => Array(
+ ['data' => Array(
+ "<form_field_name>"[,
+ "<form_field_name>"[,
+ "<form_field_name>"],]
+ ),]
+ ['type' => "text|select|multiselect|...",]
+ ['values' => Array(
+ "<value1>"[,
+ "<value1>"[,
+ "<value1>"],]
+ ),]
+ )
+ )
+ )</screen>
+ <para>
+ The <literal>attributes</literal> attribute to a <literal>user_type</literal> entry holds an array with any or all of the following <emphasis><form_field_type></emphasis> keys:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <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.
+ </para>
+
+ </formalpara>
+ <para>
+ The key name for each key => value pair indicates the form field name for which the value is to be generated automatically.
+ </para>
+ <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">
+ <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:
+ </para>
+ <para>
+
+<screen language="PHP/PHP">Array(
+ 'auto_form_fields' => Array(
+ 'displayname' => Array(
+ 'data' => Array(
+ 'givenname',
+ 'sn'
+ ),
+ ),
+ (...)
+ ),
+ (...)
+ );</screen>
+
+ </para>
+ <para>
+ This indicates to the client that a form field named 'displayname' is to be populated with the information contained within the form fields named 'givenname' and 'sn'.
+ </para>
+ <para>
+ If the client is capable of doing so, it should also update the form field named 'displayname' after the values for any of the form fields named 'givenname' or 'sn' have been changed.
+ </para>
+
+ </example>
+ <para>
+ With a JSON object payload containing the values of the form fields for which the names are contained within the 'data' key, if any, the client should submit a POST request on change of these form fields, and will be returned the new value for the automatically generated form field.
+ </para>
+
+ </listitem>
+ <listitem>
+ <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.
+ </para>
+
+ </formalpara>
+ <para>
+ The key name for each key => value pair indicates the form field name for which the value is to be supplied by the user.
+ </para>
+ <para>
+ 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">
+ <title>Additional Information in <literal>form_fields</literal></title>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-maxlength">
+ <title><literal>maxlength</literal></title>
+ <para>
+ For a form field of type <xref linkend="form-Architecture_and_Design-Additional_Information_in_form_fields-text" /> or type <xref linkend="form-Architecture_and_Design-Additional_Information_in_form_fields-list" />, this value holds the maximum length for a given item.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-type">
+ <title><literal>type</literal></title>
+ <para>
+ The <literal>type</literal> is to indicate the type of form field. Options include;
+ </para>
+
+ </formalpara>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-text">
+ <title><literal>text</literal></title>
+ <para>
+ This is a regular input field of type text.
+ </para>
+
+ </formalpara>
+ <para>
+ This is the default.
+ </para>
+ <para>
+ Additional parameters for a text form field include <xref linkend="form-Architecture_and_Design-Additional_Information_in_form_fields-maxlength" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-list">
+ <title><literal>list</literal></title>
+ <para>
+ A form field of type <literal>list</literal> is expecting a list of text input values.
+ </para>
+
+ </formalpara>
+ <para>
+ A client web interface could choose to display a textarea with the instructions to supply one item per line, or more advanced (better) equivalents, such as an add/delete widget.
+ </para>
+ <para>
+ A client command-line interface could choose to prompt for input values until an empty value is supplied.
+ </para>
+ <para>
+ Additional parameters for a list form field include <xref linkend="form-Architecture_and_Design-Additional_Information_in_form_fields-maxlength" />, which holds the maximum length of each text value in the list.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-multiselect">
+ <title><literal>multiselect</literal></title>
+ <para>
+ This form field is a select list, where multiple options may be selected (as opposed to a <xref linkend="form-Architecture_and_Design-Additional_Information_in_form_fields-select" /> list, where only one option may be selected).
+ </para>
+
+ </formalpara>
+ <para>
+ A client interface MUST consult the <literal>form_value.list_options</literal> API call for options, described in <xref linkend="sect-Architecture_and_Design-The_form_value_Service-form_value.list_options_Method" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-select">
+ <title><literal>select</literal></title>
+ <para>
+ This form field is a selection list, of which one option may be selected.
+ </para>
+
+ </formalpara>
+ <para>
+ A client interface MUST consult the <literal>form_value.list_options</literal> API call for options, described in <xref linkend="sect-Architecture_and_Design-The_form_value_Service-form_value.list_options_Method" />.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-value_source">
+ <title><literal>value_source</literal></title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-Additional_Information_in_form_fields-values">
+ <title><literal>values</literal></title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <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>.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </section>
+
+
+ </section>
+
</section>
commit 980ecfc07811af925a6d3381d1ce46fa8aee99a4
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Sun Apr 1 13:56:48 2012 +0100
publican clean does it again
diff --git a/Architecture_and_Design/en-US/Kolab_Content_Filters.xml b/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
index e59831c..7ecad4e 100644
--- a/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
+++ b/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
@@ -726,7 +726,7 @@ def execute(*args, **kw):
<para>
This is to ensure that, should the daemon's operations be interrupted at this point, data is not lost.
</para>
- </step>// --> <step>
+ </step>// --> <step>
<para>
The <literal>optout</literal> module creates a new spool file <filename>/var/spool/pykolab/wallace/optout/ACCEPT/tmpQWE123</filename> with the From: header intact, and the CC: header intact. It removes the To: header contents.
</para>
More information about the commits
mailing list