Supply some inline documentation in the default configuration file

1 files changed, 204 insertions, 94 deletions

diff --git a/conf/kolab.conf b/conf/kolab.conf
index fcce25f..2a0eacd 100644
--- a/conf/kolab.conf
+++ b/conf/kolab.conf
@@ -1,30 +1,130 @@
 [kolab]
-primary_domain = kolabsys.com
+; Set this to the primary domain name space served within this Kolab Groupware
+; deployment.
+primary_domain = example.org
+
+; This is the primary authentication mechanism used, and contains the list of
+; domain name spaces for this deployment. Each domain name space may have its
+; own auth_mechanism setting.
+;
+; Valid options currently include only 'ldap'.
 auth_mechanism = ldap
+
+; The IMAP backend to use - currently supported values include only
+; 'cyrus-imap'.
 imap_backend = cyrus-imap
 
 [ldap]
+; The URI to LDAP
 ldap_uri = ldap://localhost:389
-base_dn = dc=kolabsys,dc=com
+
+; The base dn for the deployment. Note that this is the highest level in the
+; tree Kolab will ever go. Should your OU structure allow it, you could set this
+; to ou=Kolab,ou=Not-So-Private,dc=example,dc=org.
+base_dn = dc=example,dc=org
+
+; The (administrative) bind dn and corresponding password.
+;
+; Feel free to set this to a DN with only read permissions on the tree. These
+; credentials are used by the Kolab Daemon only, as it might need to set
+; additional attributes in order to apply plugins successfully. Such attributes
+; could include the first two values in the 'mail_attributes' list (see further
+; down) to complete the 'recipient_policy' (see further down), mail quota,
+; the mail server attribute, and others.
 bind_dn = cn=Directory Manager
-bind_pw = 0B2NFj581H8kZgO
+bind_pw = Welcome123
+
+; Bind DN and password used for services. The DN should have read and search
+; privileges only, but should be able to read all relevant parts of the tree.
+;
+; These credentials are used by, among others, Postfix, Wallace, programs that
+; need to find the user DN before binding as the user (including the webadmin
+; API, Roundcube, Syncroton).
+service_bind_dn = uid=kolab-service,ou=Special Users,%(base_dn)s
+service_bind_pw = wc18bqshFmifGtN
+
+; The base DN, search scope and filter to use when searching for users of any
+; type. User types are of primary purpose to the web admin (API), but the
+; generic base DN, scope and filter allow us to configure other services as
+; well, including Address Books in Roundcube and for Syncroton, the list of
+; users in the web admin (API), etc.
 user_base_dn = ou=People,%(base_dn)s
 user_scope = sub
 user_filter = (objectclass=inetorgperson)
+
+; The base DN, scope and filter to use when searching for users of the 'kolab'
+; type. This filter is preferred when searching for Kolab users specifically,
+; such as in the synchronisation between LDAP and IMAP. Also, it is
+; (preferrably) only Kolab users that are allowed to login, use the SMTP server,
+; etc.
+;
+; Note that all user_* settings are valid, and those not available with a kolab_
+; prefix fall back to using the generic user_* equivalent setting.
+kolab_user_base_dn = ou=People,%(base_dn)s
 kolab_user_filter = (objectclass=kolabinetorgperson)
+
+; Add additional <key>_user_base_dn, <key>_user_scope and <key>_user_filter.
+; Useful for configuring sub-address books, and for the webadmin API when adding
+; new users of the example type key 'posix' - the new user will be added in the
+; OU configured below.
+;posix_user_base_dn = ou=POSIX Accounts,ou=People,%(base_dn)s
+;posix_user_scope = one
+;posix_user_filter = (&(objectclass=posixaccount)(uidnumber>=1000))
+
+; The same as for users, but applicable to groups
 group_base_dn = ou=Groups,%(base_dn)s
-group_scope = sub
 group_filter = (|(objectclass=groupofuniquenames)(objectclass=groupofurls))
+group_scope = sub
 kolab_group_filter = (|(objectclass=kolabgroupofuniquenames)(objectclass=kolabgroupofurls))
+
+; The base DN, scope and filter to use when searching for additional domain
+; name spaces in this environment.
 domain_base_dn = cn=kolab,cn=config
 domain_filter = (&(associatedDomain=*))
 domain_name_attribute = associateddomain
+; Attribute that holds the root dn for the domain name space. If this attribute
+; does not exist, a standard root dn is formed from the primary domain name
+; space (the value in the RDN), as follows:
+;
+;     'dc=' + ',dc='.join(domainname.split('.'))
+;
+; or, in example:
+;
+;     domain: example.org
+;     root dn: dc=example,dc=org
 domain_rootdn_attribute = inetdomainbasedn
-service_bind_dn = uid=kolab-service,ou=Special Users,dc=kolabsys,dc=com
-service_bind_pw = wc18bqshFmifGtN
+
+; The attribute that holds the quota.
 quota_attribute = mailquota
+; A unique attribute that can be used to identify the entry beyond renames and
+; moves. Note that 'nsuniqueid' is specific to all Netscape-based directory
+; services.
+;
+; For OpenLDAP, use 'entrydn' - the 'entryUUID' can regrettably not be searched
+; with.
 unique_attribute = nsuniqueid
+
+; Attribute names that hold valid, internal recipient addresses. Note the use
+; of mail and alias frees up the use of mailAlternateAddress to contain a user's
+; external email address.
+;
+; Syntax is a comma- or comma-space separated list.
+;
+; The first value is used for the purpose of a single "primary" email address,
+; that could be subject to a recipient policy, the second is used for the
+; purpose of one or more secondary mail addresses, that could also be subject to
+; a recipient policy.
 mail_attributes = mail, alias
+
+; Attributes that hold valid authentication login names. Use 'mail', 'alias' and
+; optionally 'uid' (the uid is marked as an auth_attribute automatically), so
+; that a user can login with;
+;
+; - uid (i.e. 'jdoe'),
+; - mail, fully qualified and localpart only (i.e. "john.doe" and
+;   "john.doe@example.org"),
+; - alias, fully qualified and localpart only (i.e. "j.doe" and
+;   "j.doe@example.org).
 auth_attributes = mail, alias, uid
 
 [kolab_smtp_access_policy]
@@ -33,102 +133,112 @@ cache_retention = 30
 address_search_attrs = mail, alias
 
 [cyrus-imap]
+; The URI to use to connect to IMAP. Note that pykolab itself can detect whether
+; or not Cyrus IMAP is deployed in a Murder topology, and should be able to
+; connect to individual backends as well.
 uri = imaps://localhost:993
+; The login username to use for global administration.
 admin_login = cyrus-admin
-admin_password = xgbGH1xHSCFxPH2
+; The corresponding password.
+admin_password = Welcome123
 
 [cyrus-sasl]
+; The user canonification result attribute.
 result_attribute = mail
 
+; This is a domain name space specific section, that enables us to override
+; all settings, for example, the LDAP URI, base and bind DNs, scopes, filters,
+; etc. Note that overriding the LDAP settings for the primary domain name space
+; does not make any sense.
 [example.org]
 default_quota = 1048576
 primary_mail = %(givenname)s.%(surname)s@%(domain)s
 secondary_mail = {
-	0: {
-	"{0}.{1}@{2}": "format('%(givenname)s'[0:1].capitalize(), '%(surname)s', '%(domain)s')"
-	},
-	1: {
-	"{0}@{1}": "format('%(uid)s', '%(domain)s')"
-	},
-	2: {
-	"{0}@{1}": "format('%(givenname)s.%(surname)s', '%(domain)s')"
-	}
-	}
-autocreate_folders = {
-	'Archive': {
-	'quota': 0
-	},
-	'Calendar': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "event.default",
-	},
-	},
-	'Calendar/Personal Calendar': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "event",
-	},
-	},
-	'Configuration': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "configuration.default",
-	},
-	},
-	'Drafts': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "mail.drafts",
-	},
-	},
-	'Contacts': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "contact.default",
-	},
-	},
-	'Contacts/Personal Contacts': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "contact",
-	},
-	},
-	'Journal': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "journal.default",
-	},
-	},
-	'Notes': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': 'note.default',
-	},
-	},
-	'Sent': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "mail.sentitems",
-	},
-	},
-	'Spam': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "mail.junkemail",
-	},
-	},
-	'Tasks': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "task.default",
-	},
-	},
-	'Trash': {
-	'annotations': {
-	'/vendor/kolab/folder-test': "true",
-	'/vendor/kolab/folder-type': "mail.trash",
-	},
-	},
-	}
+        0: {
+                "{0}.{1}@{2}": "format('%(givenname)s'[0:1].capitalize(), '%(surname)s', '%(domain)s')"
+            },
+        1: {
+                "{0}@{1}": "format('%(uid)s', '%(domain)s')"
+            },
+        2: {
+                "{0}@{1}": "format('%(givenname)s.%(surname)s', '%(domain)s')"
+        }
+    }
 
+autocreate_folders = {
+        'Archive': {
+                'quota': 0
+            },
+        'Calendar': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "event.default",
+                    },
+            },
+        'Calendar/Personal Calendar': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "event",
+                    },
+            },
+        'Configuration': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "configuration.default",
+                    },
+            },
+        'Drafts': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "mail.drafts",
+                    },
+            },
+        'Contacts': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "contact.default",
+                },
+            },
+        'Contacts/Personal Contacts': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "contact",
+                    },
+            },
+        'Journal': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "journal.default",
+                    },
+            },
+        'Notes': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': 'note.default',
+                    },
+            },
+        'Sent': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "mail.sentitems",
+                    },
+            },
+        'Spam': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "mail.junkemail",
+                    },
+            },
+        'Tasks': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "task.default",
+                    },
+            },
+        'Trash': {
+                'annotations': {
+                        '/vendor/kolab/folder-test': "true",
+                        '/vendor/kolab/folder-type': "mail.trash",
+                    },
+            },
+    }