update params template and move mailserver stuff

.gitattributes

@@ -74,3 +74,4 @@
 
 .gitattributes export-ignore
 .gitignore     export-ignore
+.vscode        export-ignore

.gitignore

@@ -3,4 +3,8 @@
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
+!.vscode/numbered-bookmarks.json
 *.code-workspace
+
+# ignore params files
+*.params

.vscode/numbered-bookmarks.json

@@ -0,0 +1,3 @@
+{
+	"bookmarks": []
+}

ab-openldap/ab-openldap.params.template

@@ -9,15 +9,20 @@
 #      incorrect: ORG_NAME="MyOrganization"
 #      correct:   ORG_NAME=MyOrganization
 #
-# Instead of typing a myriad of "-e ...", you can fill them all out in this 
+# Instead of typing a myriad of "-e ...", you can fill them all out in this
 # file and then use "--env-file ab-openldap.params" to tell docker to source
-# it's variables from here.  You can also combine both methods if you like.  
+# its variables from here.  You can also combine both methods if you like.
 # Most important, if you're using the convenience script, it draws all info from
 # this file!
 #
-# You should probably protect this file via file permissions since it likely 
+# You should probably protect this file via file permissions since it likely
 # will contain things like passwords!  Suggest restricting it to root only
 #    ex: chown root:root ab-openldap.parms && chmod 600 ab-openldap.parms
+#
+# N.B. If you change the convenience script name, you must also change this
+# file's name to match.
+#    ex: script name is 'runldap.sh' --> this file must be 'runldap.params'
+#
 ###
 
 ### Your timezone (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
@@ -43,17 +48,17 @@ BROWSER_PASS=ldapbind
 ANONYMOUS_BINDING=yes
 
 ### Location of your TLS files
-# Note: This section is only automated if using the script file to start the 
-# container.  If you are starting it manually and using '--env-file', you still 
+# Note: This section is only automated if using the script file to start the
+# container.  If you are starting it manually and using '--env-file', you still
 # have to manually bind-mount these files using '-v source:/certs/dest.file:ro'.
 #
-# If you're bind-mounting symlinks, remember that you have to fully expand them 
-# or Docker will try to bind the link instead of the target!  This is most 
+# If you're bind-mounting symlinks, remember that you have to fully expand them
+# or Docker will try to bind the link instead of the target!  This is most
 # common with Let's Encrypt.
 #
 # Example that does not work (binding directory instead of files):
 #   /etc/letsencrypt/live/mydomain.net:/certs:ro
-#   This will end up copying the symlinks themselves and, since the targets are 
+#   This will end up copying the symlinks themselves and, since the targets are
 #   not available to the container, it doesn't work!
 # Example of the right way (bind actual files):
 #   /etc/letsencrypt/live/mydomain.net/privkey.pem:/certs/privkey.pem:ro
@@ -62,7 +67,7 @@ ANONYMOUS_BINDING=yes
 #TLS_KEY=/etc/letsencrypt/live/mydomain.net/privkey.pem
 #TLS_CHAIN=/etc/letsencrypt/live/mydomain.net/chain.pem
 
-# The container will generate Diffie-Hellman parameters automatically the first 
+# The container will generate Diffie-Hellman parameters automatically the first
 # time it's launched with TLS certificates defined.
 
 ### Custom LDIFs
@@ -70,5 +75,24 @@ ANONYMOUS_BINDING=yes
 # variable commented-out if you don't have any LDIFs to apply.
 # MY_LDIF=/path/to/my/LDIFs
 
+### Enable checking passwords against IMAP/S server
+#
+# Setting the DOMAILAUTH variable to '1' tells openLDAP to verify SASL passwords
+# in the directory against an IMAP/S remote host. In other words, any user with
+# a password '{SASL}user@server.tld' will have their password checked by the
+# IMAP/S server using the provided email address and a 'NO/OK' reponse is fed
+# back to openLDAP. Please note, the remote mailserver *must* support IMAP/S
+# (i.e. secured IMAP).
+#
+# Specify the remote mailserver hostname using the MAILSERVER variable.
+#
+# If the remote mailserver implements IMAP/S (secure IMAP) on a non-standard
+# port (not port 993) then supply that using the MAILAUTHPORT variable.
+#
+# More details can be found in the wiki.
+###
+#DOMAILAUTH=0
+#MAILSERVER=mail.myserver.tld
+#MAILAUTHPORT=imaps
 
 #EOF

ab-openldap/ab-openldap.sh

@@ -1,8 +1,8 @@
 #!/bin/sh
 
 #
-### start openldap container using params file variables
-# version 3.2
+# start openldap container using params file variables
+# version 4.0
 #
 
 
@@ -66,9 +66,11 @@ scriptHelp () {
     printf "\n"
     textblock "${bold}Usage: $scriptName [parameters]${norm}"
     printf "\n"
-    textblock "This is a simple helper script so you can avoid lengthy typing when working with the openLDAP container. The script reads the contents of 'ab-openldap.params' and constructs various 'docker run' commands based on that file. The biggest timesaver is working with certificates. If they are specified in the '.params' file, the script will automatically bind-mount them so openLDAP starts in 'TLS required' mode."
+    textblock "This is a simple helper script so you can avoid lengthy typing when working with the openLDAP container. The script reads the contents of '${scriptName%.*}.params' and constructs various 'docker run' commands based on that file. The biggest timesaver is working with certificates. If they are specified in the '.params' file, the script will automatically bind-mount them so openLDAP starts in 'TLS required' mode."
     printf "\n"
-    textblock "If you run the script with no parameters, it will execute the container 'normally': Run in detached mode with openLDAP automatically launched and logging to stdout. If you specified certificates, openLDAP will require a TLS connection. All modes of operation allow you to enter the container and connect directly using UNIX sockets also."
+    textblock "If you run the script with no parameters, it will execute the container 'normally'. That is: Run in detached mode with openLDAP automatically launched and logging to stdout. If you specified certificates, openLDAP will require a TLS connection. All modes of operation allow you to enter the container and connect directly using UNIX sockets as root with *unrestricted* access to all DITs and objects."
+    printf "\n"
+    textblock "If you want to verify SASL passwords against an IMAP/S server, please refer to the '.params' template file and the wiki for more information."
     printf "\n"
     textblock "Containers run in SHELL mode are ALWAYS removed upon exit as they are meant for testing only. By default, containers run without '--rm' will be restarted automatically unless they are manually stopped via 'docker stop...'"
     printf "\n"
@@ -117,13 +119,13 @@ if [ ! "$( id -u )" -eq 0 ]; then
 fi
 
 # does the params file exist?
-if [ ! -f "./ab-openldap.params" ]; then
-    consoleError '3' "Cannot find 'ab-openldap.params' file in the same directory as this script."
+if [ ! -f "${scriptName%.*}.params" ]; then
+    consoleError '3' "Cannot find '${scriptName%.*}.params' file in the same directory as this script."
     exit 3
 fi
 
 # read .params file
-. ./ab-openldap.params
+. ./${scriptName%.*}.params
 
 # process startup parameters
 while [ $# -gt 0 ]; do
@@ -208,7 +210,7 @@ if [ $clean = true ]; then
     printf "%sThis action CANNOT be undone!%s\n\n" \
         "$red" "$norm"
     prompt_yn
-    
+
     # get all ab-openldap containers
     containers=$(docker ps -a --no-trunc --filter "label=org.label-schema.name=ab-openldap" --format "{{ .Names }}")
     # check for null value -- no containers to remove
@@ -247,11 +249,11 @@ elif [ $restore = true ]; then
     printf "To avoid errors due to existing files, this script will delete any volumes that have the following names (based on --data and --ldif):\n"
     printf "\t%s\n\t%s\n" "$volume_data" "$volume_ldif"
     prompt_yn
-    
+
     # delete any conflicting volumes
     docker volume rm -f ${volume_data} > /dev/null 2>&1
     docker volume rm -f ${volume_ldif} > /dev/null 2>&1
-    
+
     # run temporary container to merge backup data into volumes
     docker run --rm \
         -v "$volume_data":/var/openldap/data \