1 files changed, 131 insertions, 0 deletions
diff --git a/doc/wiki/Pigeonhole.Sieve.Configuration.LDAP.txt b/doc/wiki/Pigeonhole.Sieve.Configuration.LDAP.txt
new file mode 100644
index 0000000..e122156
--- /dev/null
+++ b/doc/wiki/Pigeonhole.Sieve.Configuration.LDAP.txt
@@ -0,0 +1,131 @@
+Pigeonhole Sieve: LDAP Lookup for Sieve Scripts
+===============================================
+
+The 'ldap' <location type> [Pigeonhole.Sieve.Configuration.txt] is used to
+retrieve Sieve scripts from an LDAP database. To retrieve a Sieve script from
+the LDAP database, at most two lookups are performed. First, the LDAP entry
+containing the Sieve script is searched using the specified LDAP search filter.
+If the LDAP entry changed since it was last retrieved (or it was never retieved
+before), the attribute containing the actual Sieve script is retrieved in a
+second lookup. In the first lookup, a special attribute is read and checked for
+changes. Usually, this is the 'modifyTimestamp' attribute, but an alternative
+can be configured.
+
+Note that, by default, compiled binaries are not stored at all for Sieve
+scripts retrieved from an LDAP database. The ';bindir=<path>' option needs to
+be specified in the <location specification>
+[Pigeonhole.Sieve.Configuration.txt].
+
+Depending on how Pigeonhole was configured and compiled (refer to INSTALL file
+for more information), LDAP support may only be available when a plugin called
+'sieve_storage_ldap' is loaded.
+
+Configuration
+-------------
+
+If support for the 'ldap' location type is compiled as a plugin, it needs to be
+added to the sieve_plugins setting before it can be used, e.g.:
+
+---%<-------------------------------------------------------------------------
+sieve_plugins = sieve_storage_ldap
+---%<-------------------------------------------------------------------------
+
+The 'ldap' script location syntax is specified as follows:
+
+---%<-------------------------------------------------------------------------
+location = ldap:<config-file>[;<option>[=<value>][;...]]
+---%<-------------------------------------------------------------------------
+
+The '<config-file>' is a filesystem path that points to a configuration file
+containing the actual configuration for this 'ldap' script location.
+
+The following additional location options are recognized:
+
+user=<username> :
+  Overrides the user name used for the lookup. Normally, the name of the user
+  running the Sieve interpreter is used.
+
+If the name of the Script is left unspecified and not otherwise provided by the
+Sieve interpreter, the name defaults to `'default''.
+
+The configuration file is based on the auth userdb/passdb LDAP configuration
+[http://wiki2.dovecot.org/AuthDatabase/LDAP]. The following options are
+specific to the Sieve ldap location type:
+
+sieve_ldap_filter = (&(objectClass=posixAccount)(uid=%u)) :
+  The LDAP search filter that is used to find the entry containing the Sieve
+  script.
+
+sieve_ldap_script_attr = mailSieveRuleSource :
+  The name of the attribute containing the Sieve script itself.
+
+sieve_ldap_mod_attr = modifyTimestamp :
+  The name of the attribute used to detect modifications to the LDAP entry.
+
+Example
+-------
+
+The dovecot configuration:
+
+---%<-------------------------------------------------------------------------
+plugin {
+  sieve = ldap:/etc/dovecot/sieve-ldap.conf;bindir=~/.sieve-bin/
+}
+---%<-------------------------------------------------------------------------
+
+The contents of sieve-ldap.conf:
+
+---%<-------------------------------------------------------------------------
+# This file needs to be accessible by the Sieve interpreter running in
+LDA/LMTP.
+# This requires acces by the mail user. Don't use privileged LDAP credentials
+# here as these may likely leak. Only search and read access is required.
+
+# Space separated list of LDAP hosts to use. host:port is allowed too.
+hosts = localhost
+
+# Distinguished Name - the username used to login to the LDAP server.
+# Leave it commented out to bind anonymously.
+dn = cn=sieve,ou=Programs,dc=example,dc=org
+
+# Password for LDAP server, if dn is specified.
+dnpass = secret
+
+# Simple binding.
+sasl_bind = no
+
+# No TLS
+tls = no
+
+# LDAP library debug level as specified by LDAP_DEBUG_* in ldap_log.h.
+# -1 = everything. You may need to recompile OpenLDAP with debugging enabled
+# to get enough output.
+debug_level = 0
+
+# LDAP protocol version to use. Likely 2 or 3.
+ldap_version = 3
+
+# LDAP base
+base = dc=mail,dc=example,dc=org
+
+# Dereference: never, searching, finding, always
+deref = never
+
+# Search scope: base, onelevel, subtree
+scope = subtree
+
+# Filter for user lookup. Some variables can be used:
+#   %u      - username
+#   %n      - user part in user@domain, same as %u if there's no domain
+#   %d      - domain part in user@domain, empty if there's no domain
+#   %{name} - name of the Sieve script
+sieve_ldap_filter = (&(objectClass=posixAccount)(uid=%u))
+
+# Attribute containing the Sieve script
+sieve_ldap_script_attr = mailSieveRuleSource
+
+# Attribute used for modification tracking
+sieve_ldap_mod_attr = modifyTimestamp
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)