refactor: relay.sh (#3845)

* chore: `relay.sh` helper - Reference user config paths via variables

* chore: Better document postfix helper `_vhost_collect_postfix_domains()`

The functionality is effectively the same for the two configs for the most part when it comes to parsing out a domain from the target value.

Virtual aliases is more flexible in value, which may not have a domain-part present (manual user edit).

* chore: `check-for-change.sh` - Support VHOST change visibility

- Moves the "handle changes" logic into it's own scoped function, out of the main change detection loop logic.
- This will be benefit a future commit change that will rely on `VHOST_UPDATED=1`.

* chore: `relay.sh` - Minor revisions to minimize diff noise

- Better phrasing of the current logic comments.
- Regex patterns assigned to variables (easier to grok intention)
- Bulk of the logic for generating `/etc/postfix/relayhost_map` wrapped into a separate function with Postfix config setting handled separately.

* refactor: `relay.sh` opt-out logic

- Split the two distinct features that configure `/etc/postfix/relayhost_map` into separate functions (_`MATCH_VALID` var no longer needed for legacy support_).
- Instead of extracting domains from `postfix-accounts.cf` + `postfix-virtual.cf`, this has already been handled at `/etc/postfix/vhost`, sourcing from there is far less complicated.
- Rename loop var `DOMAIN_PART`to `SENDER_DOMAIN` for better context of what it represents when appended to the config file.
- Revised maintenance notes + guidance towards a future refactor of this relayhost feature support.

* docs: `relay.sh` - Additional comment revisions

* feat: `DEFAULT_RELAY_HOST` can now also use relay credentials ENV

- Remove comment regarding `smtp_sasl_password_maps = static:${RELAY_USER}:${RELAY_PASSWORD}`, it could be used but `main.cf` presently has `644` permissions vs the `sasl_passwd` file permissions of `600`, less secure at preventing leaking of secrets (ignoring the ENV exposure itself).
- Move the `main.cf` settings specific to relayhost credentials support / security into to the relevant function scope instead. This also allows for the configuration to be applied by a change detection event without container restart requirement.
- Outer functions for setup and change detection to call have a clearer config dependency guard, as does the `_legacy_support()`.
- These changes now support `DEFAULT_RELAY_HOST` to leverage the relay credentials ENV as well.
- `DATABASE_RELAYHOSTS` is available in scope to the functions called here that reference it.

* docs: Revised ENV docs on relay host config

Better quality guidance on configuring relay hosts.

* chore: Add entry to `CHANGELOG.md`

* fix: `relay.sh` - `grep` regex compatibility with `+` requires `-E`

* chore: `postfix.sh` - `FIRST_FIELD` => More descriptive field name

target/scripts/check-for-changes.sh

@@ -49,17 +49,7 @@ function _check_for_changes() {
 
     local CHANGED
     CHANGED=$(_get_changed_files "${CHKSUM_FILE}" "${CHKSUM_FILE}.new")
-
-    # Handle any changes
-    _ssl_changes
-    _postfix_dovecot_changes
-    _rspamd_changes
-
-    _log_with_date 'debug' 'Reloading services due to detected changes'
-
-    [[ ${ENABLE_AMAVIS} -eq 1 ]] && _reload_amavis
-    _reload_postfix
-    [[ ${SMTP_ONLY} -ne 1 ]] && dovecot reload
+    _handle_changes
 
     _remove_lock
     _log_with_date 'debug' 'Completed handling of detected change'
@@ -69,6 +59,29 @@ function _check_for_changes() {
   fi
 }
 
+function _handle_changes() {
+  # Variable to identify any config updates dependent upon vhost changes.
+  local VHOST_UPDATED=0
+  # These two configs are the source for /etc/postfix/vhost (managed mail domains)
+  if [[ ${CHANGED} =~ ${DMS_DIR}/postfix-(accounts|virtual).cf ]]; then
+    _log_with_date 'trace' 'Regenerating vhosts (Postfix)'
+    # Regenerate via `helpers/postfix.sh`:
+    _create_postfix_vhost
+
+    VHOST_UPDATED=1
+  fi
+
+  _ssl_changes
+  _postfix_dovecot_changes
+  _rspamd_changes
+
+  _log_with_date 'debug' 'Reloading services due to detected changes'
+
+  [[ ${ENABLE_AMAVIS} -eq 1 ]] && _reload_amavis
+  _reload_postfix
+  [[ ${SMTP_ONLY} -ne 1 ]] && dovecot reload
+}
+
 function _get_changed_files() {
   local CHKSUM_CURRENT=${1}
   local CHKSUM_NEW=${2}
@@ -85,9 +98,9 @@ function _get_changed_files() {
 }
 
 function _reload_amavis() {
-  if [[ ${CHANGED} =~ ${DMS_DIR}/postfix-accounts.cf ]] || [[ ${CHANGED} =~ ${DMS_DIR}/postfix-virtual.cf ]]; then
-    # /etc/postfix/vhost was updated, amavis must refresh it's config by
-    # reading this file again in case of new domains, otherwise they will be ignored.
+  # /etc/postfix/vhost was updated, amavis must refresh it's config by
+  # reading this file again in case of new domains, otherwise they will be ignored.
+  if [[ ${VHOST_UPDATED} -eq 1 ]]; then
     amavisd reload
   fi
 }
@@ -114,14 +127,12 @@ function _postfix_dovecot_changes() {
   # - postfix-sasl-password.cf used by _relayhost_sasl
   # - _populate_relayhost_map relies on:
   #   - postfix-relaymap.cf
-  #   - postfix-accounts.cf + postfix-virtual.cf (both will be dropped in future)
-  if [[ ${CHANGED} =~ ${DMS_DIR}/postfix-accounts.cf      ]] \
-  || [[ ${CHANGED} =~ ${DMS_DIR}/postfix-virtual.cf       ]] \
+  if [[ ${VHOST_UPDATED} -eq 1 ]] \
   || [[ ${CHANGED} =~ ${DMS_DIR}/postfix-relaymap.cf      ]] \
   || [[ ${CHANGED} =~ ${DMS_DIR}/postfix-sasl-password.cf ]]
   then
     _log_with_date 'trace' 'Regenerating relay config (Postfix)'
-    _rebuild_relayhost
+    _process_relayhost_configs
   fi
 
   # Regenerate system + virtual account aliases via `helpers/aliases.sh`:
@@ -129,14 +140,6 @@ function _postfix_dovecot_changes() {
   [[ ${CHANGED} =~ ${DMS_DIR}/postfix-regexp.cf  ]] && _handle_postfix_regexp_config
   [[ ${CHANGED} =~ ${DMS_DIR}/postfix-aliases.cf ]] && _handle_postfix_aliases_config
 
-  # Regenerate `/etc/postfix/vhost` (managed mail domains) via `helpers/postfix.sh`:
-  if [[ ${CHANGED} =~ ${DMS_DIR}/postfix-accounts.cf ]] \
-  || [[ ${CHANGED} =~ ${DMS_DIR}/postfix-virtual.cf  ]]
-  then
-    _log_with_date 'trace' 'Regenerating vhosts (Postfix)'
-    _create_postfix_vhost
-  fi
-
   # Legacy workaround handled here, only seems necessary for _create_accounts:
   # - `helpers/accounts.sh` logic creates folders/files with wrong ownership.
   _chown_var_mail_if_necessary