scripts: rework environment variables setup (#2716)

* outsourcing env variable setup

This commit contains major parts of the work of refactoring the setup
and usage of environment variables. It outsources the setup into its own
script and provides dedicated functions to be executed at a later point in time.

A **new** env variable was added: `USER_PROVISIONG` which provides a
better way of defining which method / protocol to use when it comes to
setting up users. This way, the `ENABLE_LDAP` variable is deprecated,
but all of this is backwards compatible due to a "compatibility layer", a function provided by the new variables script.

This is not a breaking change. It mostly refators internal scripts. The
only change facing the user-side is the deprecation of `ENABLE_LDAP`. We
can prolong the period of deprecation for this variable as long as we
want, because the new function that ensures backwards compatibility
provides a clean interface for the future.

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>

docs/content/config/advanced/auth-ldap.md

@@ -34,7 +34,9 @@ Those variables contain the LDAP lookup filters for postfix, using `%s` as the p
     A really simple `LDAP_QUERY_FILTER` configuration, using only the _user filter_ and allowing only `admin@*` to spoof any sender addresses.
 
     ```yaml
-    - ENABLE_LDAP=1
+    - ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+    - LDAP_START_TLS=yes
+    - ACCOUNT_PROVISIONER=LDAP
     - LDAP_SERVER_HOST=ldap.example.org
     - LDAP_SEARCH_BASE=dc=example,dc=org"
     - LDAP_BIND_DN=cn=admin,dc=example,dc=org
@@ -138,7 +140,7 @@ In addition to LDAP explanation above, when Docker Mailserver is intended to be
 
 The configuration shown to get the Group to work is from [here](https://doc.zarafa.com/trunk/Administrator_Manual/en-US/html/_MTAIntegration.html) and [here](https://kb.kopano.io/display/WIKI/Postfix).
 
-```
+```bash
 # user-patches.sh
 
 ...
@@ -149,7 +151,7 @@ grep -q '^special_result_attribute = member$' /etc/postfix/ldap-groups.cf || ech
 
 - In `/etc/ldap/ldap.conf`, if the `TLS_REQCERT` is `demand` / `hard` (default), the CA certificate used to verify the LDAP server certificate must be recognized as a trusted CA. This can be done by volume mounting the `ca.crt` file and updating the trust store via a `user-patches.sh` script:
 
-```
+```bash
 # user-patches.sh
 
 ...
@@ -160,7 +162,7 @@ update-ca-certificates
 
 The changes on the configurations necessary to work with Active Directory (**only changes are listed, the rest of the LDAP configuration can be taken from the other examples** shown in this documentation):
 
-```
+```yaml
 # If StartTLS is the chosen method to establish a secure connection with Active Directory.
 - LDAP_START_TLS=yes
 - SASLAUTHD_LDAP_START_TLS=yes
@@ -215,7 +217,8 @@ The changes on the configurations necessary to work with Active Directory (**onl
           - ENABLE_POSTGREY=1
 
           # >>> Postfix LDAP Integration
-          - ENABLE_LDAP=1
+          - ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+          - ACCOUNT_PROVISIONER=LDAP
           - LDAP_SERVER_HOST=ldap.example.org
           - LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=org
           - LDAP_BIND_PW=mypassword
@@ -287,7 +290,8 @@ The changes on the configurations necessary to work with Active Directory (**onl
           # <<< SASL Authentication
 
           # >>> Postfix Ldap Integration
-          - ENABLE_LDAP=1
+          - ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+          - ACCOUNT_PROVISIONER=LDAP
           - LDAP_SERVER_HOST=<yourLdapContainer/yourLdapServer>
           - LDAP_SEARCH_BASE=dc=mydomain,dc=loc
           - LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=loc

docs/content/config/environment.md

@@ -40,6 +40,17 @@ The log-level will show everything in its class and above.
 - 0 => state in default directories.
 - **1** => consolidate all states into a single directory (`/var/mail-state`) to allow persistence using docker volumes. See the [related FAQ entry][docs-faq-onedir] for more information.
 
+##### ACCOUNT_PROVISIONER
+
+Configures the provisioning source of user accounts (including aliases) for user queries and authentication by services managed by DMS (_Postfix and Dovecot_).
+
+User provisioning via OIDC is planned for the future, see [this tracking issue](https://github.com/docker-mailserver/docker-mailserver/issues/2713).
+
+- **empty** => use FILE
+- LDAP => use LDAP authentication
+- OIDC => use OIDC authentication (**not yet implemented**)
+- FILE => use local files (this is used as the default)
+
 ##### PERMIT_DOCKER
 
 Set different options for mynetworks option (can be overwrite in postfix-main.cf) **WARNING**: Adding the docker network's gateway to the list of trusted hosts, e.g. using the `network` or `connected-networks` option, can create an [**open relay**](https://en.wikipedia.org/wiki/Open_mail_relay), for instance if IPv6 is enabled on the host machine but not in Docker.
@@ -439,11 +450,7 @@ Note: The defaults of your fetchmailrc file need to be at the top of the file. O
 
 ##### ENABLE_LDAP
 
-- **empty** => LDAP authentification is disabled
-- 1 => LDAP authentification is enabled
-- NOTE:
-  - A second container for the ldap service is necessary (e.g. [docker-openldap](https://github.com/osixia/docker-openldap))
-  - For preparing the ldap server to use in combination with this container [this](http://acidx.net/wordpress/2014/06/installing-a-mailserver-with-postfix-dovecot-sasl-ldap-roundcube/) article may be helpful
+Deprecated. See [`ACCOUNT_PROVISIONER`](#account_provisioner).
 
 ##### LDAP_START_TLS
 

docs/content/contributing/coding-style.md

@@ -130,9 +130,7 @@ function _setup_postfix_aliases
 
     cp -f /tmp/docker-mailserver/postfix-virtual.cf /etc/postfix/virtual
 
-    # the `to` is important, don't delete it
-    # shellcheck disable=SC2034
-    while read -r FROM TO
+    while read -r FROM _
     do
       # Setting variables for better readability
       UNAME=$(echo "${FROM}" | cut -d @ -f1)

docs/content/examples/use-cases/forward-only-mailserver-with-ldap-authentication.md

@@ -30,7 +30,8 @@ We can create aliases with `./setup.sh`, like this:
 If you want to send emails from outside the mail-server you have to authenticate somehow (with a username and password). One way of doing it is described in [this discussion][github-issue-1247]. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on `mailserver.env` are:
 
 ```env
-ENABLE_LDAP=1
+ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+ACCOUNT_PROVISIONER=LDAP
 LDAP_START_TLS=yes
 LDAP_SERVER_HOST=ldap.example.org
 LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
@@ -104,9 +105,5 @@ You see that besides `query_filter`, I had to customize as well `result_attribut
 
     Another solution that serves as a forward-only mail-server is [this](https://gitlab.com/docker-scripts/postfix).
 
-!!! tip
-
-    One user reports only having success if `ENABLE_LDAP=0` was set.
-
 [docs-userpatches]: ../../config/advanced/override-defaults/user-patches.md
 [github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247