install.sh

#!/usr/bin/env bash
# shellcheck shell=bash
# - - - - - - - - - - - - - - - - - - - - - - - - -
##@Version           :  202610111835-git
# @@Author           :  Jason Hempstead
# @@Contact          :  git-admin@casjaysdev.pro
# @@License          :  MIT or LICENSE.md
# @@ReadME           :  install.sh --help
# @@Copyright        :  Copyright: (c) 2026 Jason Hempstead, Casjays Developments
# @@Created          :  Thursday, May 22, 2026 14:29 UTC
# @@File             :  install.sh
# @@Description      :  Full FreeIPA + Keycloak SSO bootstrap script, distro-agnostic
# @@Changelog        :  Reverse-proxy Keycloak under /kc via Apache mod_rewrite
# @@TODO             :  None
# @@Other            :
# @@Resource         :  https://www.freeipa.org/page/Documentation
# @@Terminal App     :  yes
# @@sudo/root        :  yes
# @@Template         :  shell/bash
# - - - - - - - - - - - - - - - - - - - - - - - - -
# shellcheck disable=SC1001,SC1003,SC2001,SC2003,SC2016,SC2031,SC2034,SC2090,SC2115,SC2120,SC2155,SC2199,SC2229,SC2317,SC2329
# - - - - - - - - - - - - - - - - - - - - - - - - -
VERSION="202610111835-git"
# - - - - - - - - - - - - - - - - - - - - - - - - -
APPNAME="${0##*/}"
RUN_USER="${SUDO_USER:-$USER}"
SET_UID="${UID}"
SCRIPT_SRC_DIR="${BASH_SOURCE%/*}"
# - - - - - - - - - - - - - - - - - - - - - - - - -
set -euo pipefail
# - - - - - - - - - - - - - - - - - - - - - - - - -
# Color output — suppressed when NO_COLOR is set
INSTALL_COLOR_RED='\e[0;31m'
INSTALL_COLOR_GREEN='\e[0;32m'
INSTALL_COLOR_YELLOW='\e[1;33m'
INSTALL_COLOR_BLUE='\e[0;34m'
INSTALL_COLOR_RESET='\e[0m'
if [[ -n "${NO_COLOR:-}" ]]; then
  INSTALL_COLOR_RED=""
  INSTALL_COLOR_GREEN=""
  INSTALL_COLOR_YELLOW=""
  INSTALL_COLOR_BLUE=""
  INSTALL_COLOR_RESET=""
fi
# - - - - - - - - - - - - - - - - - - - - - - - - -
# Global state — populated by sub-functions, consumed by later stages
INSTALL_DISTRO=""
INSTALL_DISTRO_FAMILY=""
INSTALL_DISTRO_VERSION=""
FREEIPA_FQDN="${FREEIPA_FQDN:-}"
FREEIPA_DOMAIN="${FREEIPA_DOMAIN:-}"
FREEIPA_REALM="${FREEIPA_REALM:-}"
FREEIPA_CRED_FILE="${FREEIPA_CRED_FILE:-/etc/ipa/creds.conf}"
INSTALL_LEGACY_CRED_FILE="/root/.freeipa-install.conf"
INSTALL_DNS="false"
INSTALL_NO_NTP="false"
INSTALL_USE_AUTO_FORWARDERS="false"
INSTALL_DNS_FORWARDERS=""
INSTALL_CONFIGURE_REVERSE_ZONE="false"
INSTALL_USE_LETSENCRYPT="false"
INSTALL_USE_FREEIPA_CA="false"
INSTALL_USE_SELFSIGNED="false"
INSTALL_CERT_PATH=""
INSTALL_KEY_PATH=""
INSTALL_CHAIN_PATH=""
INSTALL_FULLCHAIN_PATH=""
INSTALL_ADMIN_PASSWORD=""
INSTALL_DM_PASSWORD=""
FREEIPA_DEBUG="${FREEIPA_DEBUG:-0}"
# - - - - - - - - - - - - - - - - - - - - - - - - -
# Keycloak / LDAP globals
INSTALL_LDAP_BASE_DN=""
FREEIPA_KEYCLOAK_PORT="${FREEIPA_KEYCLOAK_PORT:-}"
FREEIPA_KEYCLOAK_REALM="${FREEIPA_KEYCLOAK_REALM:-}"
INSTALL_KEYCLOAK_ADMIN_PASSWORD=""
INSTALL_KEYCLOAK_LDAP_PASSWORD=""
INSTALL_KEYCLOAK_DB_PASSWORD=""
FREEIPA_COMPOSE_DIR="${FREEIPA_COMPOSE_DIR:-/opt/keycloak}"
FREEIPA_KEYCLOAK_CONFIG_DIR="${FREEIPA_KEYCLOAK_CONFIG_DIR:-/etc/keycloak}"
INSTALL_LDIF_TMP=""
INSTALL_CCACHE_DIR=""
# - - - - - - - - - - - - - - - - - - - - - - - - -
# Mail (Postfix/Dovecot) globals
FREEIPA_MAIL_DOMAIN="${FREEIPA_MAIL_DOMAIN:-}"
FREEIPA_MAIL_BASE_DIR="${FREEIPA_MAIL_BASE_DIR:-/var/mail/vhosts}"
FREEIPA_MAIL_VUSER="${FREEIPA_MAIL_VUSER:-vmail}"
FREEIPA_MAIL_VID="${FREEIPA_MAIL_VID:-5000}"
INSTALL_MAIL_LDAP_PASSWORD=""
INSTALL_MAIL_CERT_PATH=""
INSTALL_MAIL_KEY_PATH=""
FREEIPA_MAIL_LOCAL_FALLBACK="${FREEIPA_MAIL_LOCAL_FALLBACK:-true}"
FREEIPA_MAIL_KEYCLOAK_AUTH="${FREEIPA_MAIL_KEYCLOAK_AUTH:-true}"
FREEIPA_MAIL_KEYCLOAK_CLIENT_ID="${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID:-dovecot-mail}"
INSTALL_MAIL_KEYCLOAK_SECRET=""
# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Standard Utility Functions ──────────────────────────────────────────────

__primary_ip() {
  # `hostname -I`'s first token is unreliable once Docker is installed (this
  # script installs it as a prerequisite): docker0/br-* bridge addresses can
  # sort before the real outbound interface. Ask the routing table which
  # source address it would actually use to reach the internet instead.
  local ip
  ip="$(\ip -4 route get 1.1.1.1 2>/dev/null | \awk '{for (i = 1; i <= NF; i++) if ($i == "src") print $(i + 1)}')"
  if [[ -z "${ip}" ]]; then
    ip="$(\hostname -I 2>/dev/null | \awk '{print $1}' || true)"
  fi
  printf '%s' "${ip}"
}

__random_password() {
  local length="${1:-32}"
  # tr reads /dev/urandom infinitely; head closes the pipe after N bytes, sending
  # SIGPIPE to tr. Run tr in a subshell and absorb the SIGPIPE with || true so
  # set -o pipefail does not propagate tr's exit 141 to the caller.
  # Excludes '#': Dovecot's config parser treats an unescaped '#' as a
  # comment start even mid-line (confirmed breaking dovecot-ldap.conf.ext's
  # dnpass), silently truncating any password that contains one.
  ( \tr -dc 'A-Za-z0-9!@$%^&*_+-' </dev/urandom 2>/dev/null || true ) | \head -c "${length}"
  printf '\n'
}

__random_port() {
  local port
  while :; do
    port=$(( 62000 + RANDOM % 3000 ))
    if ! \ss -tlnp 2>/dev/null | \grep -q -- ":${port} "; then
      printf '%s\n' "${port}"
      return 0
    fi
  done
}

__save_credential() {
  local file="${1:?Usage: __save_credential <file> <key> <value>}"
  local key="${2:?}"
  local value="${3:?}"
  local _dir="${file%/*}"
  [[ "${_dir}" == "${file}" ]] && _dir="."
  \mkdir -p "${_dir}"
  if [[ -f "${file}" ]] && \grep -q -- "^${key}=" "${file}"; then
    local tmp
    tmp="$(\mktemp)"
    \grep -v -- "^${key}=" "${file}" > "${tmp}"
    printf '%s=%s\n' "${key}" "${value}" >> "${tmp}"
    \mv "${tmp}" "${file}"
  else
    printf '%s=%s\n' "${key}" "${value}" >> "${file}"
    printf 'Generated %s (saved to %s)\n' "${key}" "${file}"
  fi
  \chmod 600 "${file}"
  if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
    \chown root:root "${file}"
  else
    \chown "${RUN_USER}:${RUN_USER}" "${file}"
  fi
}

__load_credential() {
  local file="${1:?Usage: __load_credential <file> <key>}"
  local key="${2:?}"
  [[ -f "${file}" ]] || return 1
  local val
  val="$(\grep -- "^${key}=" "${file}" | \tail -n1 | \cut -d= -f2- || true)"
  [[ -n "${val}" ]] || return 1
  printf '%s\n' "${val}"
}

# Older install.sh releases stored credentials at INSTALL_LEGACY_CRED_FILE
# (a dotfile in /root). On upgrade, move it to the new FREEIPA_CRED_FILE
# location once, so an upgraded script keeps reading the same generated
# passwords/ports a previous run already committed to, instead of treating
# this as a first-ever install and regenerating everything.
__migrate_legacy_credential_file() {
  local new_file="${1:?Usage: __migrate_legacy_credential_file <new_file>}"
  [[ -f "${INSTALL_LEGACY_CRED_FILE}" ]] || return 0
  [[ -f "${new_file}" ]] && return 0
  local dir="${new_file%/*}"
  [[ "${dir}" == "${new_file}" ]] && dir="."
  \mkdir -p "${dir}"
  \mv "${INSTALL_LEGACY_CRED_FILE}" "${new_file}"
  \chmod 600 "${new_file}"
  \chown root:root "${new_file}"
  __log "Migrated credentials from ${INSTALL_LEGACY_CRED_FILE} to ${new_file}"
}

# Older install.sh releases persisted the Keycloak port under its old key.
# Rename it in place so an upgraded script keeps the port the container uses.
__migrate_legacy_credential_keys() {
  local file="${1:?Usage: __migrate_legacy_credential_keys <file>}"
  [[ -f "${file}" ]] || return 0
  if \grep -q -- '^INSTALL_KEYCLOAK_PORT=' "${file}" && ! \grep -q -- '^FREEIPA_KEYCLOAK_PORT=' "${file}"; then
    \sed -i 's/^INSTALL_KEYCLOAK_PORT=/FREEIPA_KEYCLOAK_PORT=/' "${file}"
  fi
  \sed -i '/^\(INSTALL_\)\?FREEIPA_PORT=/d' "${file}"
}

__determine_domain_name() {
  local domain
  domain="$(\hostname -d 2>/dev/null)"
  if [[ -n "${domain}" ]]; then
    printf '%s\n' "${domain}"
    return 0
  fi
  local fqdn
  fqdn="$(\hostname -f 2>/dev/null)"
  if [[ -n "${fqdn}" && "${fqdn}" == *.* ]]; then
    printf '%s\n' "${fqdn#*.}"
    return 0
  fi
  return 1
}

__determine_hostname_name() {
  local fqdn
  fqdn="$(\hostname -f 2>/dev/null)"
  if [[ -n "${fqdn}" ]]; then
    printf '%s\n' "${fqdn}"
    return 0
  fi
  return 1
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Logging ─────────────────────────────────────────────────────────────────

__log() {
  printf "${INSTALL_COLOR_GREEN}[%s] %s${INSTALL_COLOR_RESET}\n" "$(\date +'%Y-%m-%d %H:%M:%S')" "$1"
}

__warn() {
  printf "${INSTALL_COLOR_YELLOW}[WARN] %s${INSTALL_COLOR_RESET}\n" "$1" >&2
}

__error() {
  printf "${INSTALL_COLOR_RED}[ERROR] %s${INSTALL_COLOR_RESET}\n" "$1" >&2
  # Messages that end in "(exit NN)" promise that status; honor it
  if [[ "$1" =~ \(exit\ ([0-9]+)\)$ ]]; then
    exit "${BASH_REMATCH[1]}"
  fi
  exit 1
}

__debug() {
  if [[ "${FREEIPA_DEBUG}" -eq 1 ]]; then
    printf "${INSTALL_COLOR_BLUE}[DEBUG] %s${INSTALL_COLOR_RESET}\n" "$1" >&2
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Help / Version ──────────────────────────────────────────────────────────

__help() {
  printf 'Usage: %s [OPTIONS]\n\n' "${APPNAME}"
  printf 'Full FreeIPA + Keycloak SSO bootstrap script — distro-agnostic.\n'
  printf 'Installs FreeIPA with DNS, NTP, optional Let'"'"'s Encrypt,\n'
  printf 'and deploys Keycloak SSO federated against FreeIPA LDAP.\n\n'
  printf 'Options:\n'
  printf '  -h, --help        Show this help and exit\n'
  printf '  -v, --version     Show version and exit\n'
  printf '      --debug       Enable debug output\n'
  printf '      --no-ntp      Skip time sync (needed in containers without CAP_SYS_TIME)\n'
  printf '      --color       Force color output\n'
  printf '      --no-color    Disable color output\n\n'
  printf 'Environment:\n'
  printf '  FREEIPA_FQDN             Override auto-detected hostname\n'
  printf '  FREEIPA_DOMAIN           Override auto-detected domain\n'
  printf '  FREEIPA_REALM            Override auto-detected Kerberos realm\n'
  printf '  FREEIPA_CRED_FILE        Credentials file path (default: /etc/ipa/creds.conf)\n'
  printf '  FREEIPA_DEBUG            Enable debug output when set to 1 (same as --debug)\n'
  printf '  FREEIPA_KEYCLOAK_PORT    Override Keycloak port (default: random in 62000-64999)\n'
  printf '  FREEIPA_KEYCLOAK_REALM   Override Keycloak realm (default: domain name)\n'
  printf '  FREEIPA_COMPOSE_DIR      Docker Compose directory (default: /opt/keycloak)\n'
  printf '  FREEIPA_KEYCLOAK_CONFIG_DIR  Keycloak config directory (default: /etc/keycloak)\n'
  printf '  FREEIPA_MAIL_DOMAIN      Mail domain for virtual mailboxes (default: FREEIPA_DOMAIN)\n'
  printf '  FREEIPA_MAIL_BASE_DIR    Maildir storage root (default: /var/mail/vhosts)\n'
  printf '  FREEIPA_MAIL_VUSER       System user/group owning mailbox storage (default: vmail)\n'
  printf '  FREEIPA_MAIL_VID         UID/GID for FREEIPA_MAIL_VUSER (default: 5000)\n'
  printf '  FREEIPA_MAIL_LOCAL_FALLBACK   Add a Unix/PAM passdb fallback (default: true)\n'
  printf '  FREEIPA_MAIL_KEYCLOAK_AUTH    Add a Keycloak OAUTHBEARER passdb (default: true)\n'
  printf '  FREEIPA_MAIL_KEYCLOAK_CLIENT_ID  Keycloak client ID for token introspection (default: dovecot-mail)\n'
  printf '  NO_COLOR                 Disable color output when set\n\n'
  printf 'Notes:\n'
  printf '  FreeIPA uses Apache on ports 80 and 443; HTTP requests redirect to HTTPS.\n'
  printf '  An installed nginx service is stopped, disabled, and masked.\n'
}

__version() {
  printf '%s version %s\n' "${APPNAME}" "${VERSION}"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Cleanup ─────────────────────────────────────────────────────────────────

__cleanup() {
  [[ -n "${INSTALL_LDIF_TMP}" && -f "${INSTALL_LDIF_TMP}" ]] && \rm -f "${INSTALL_LDIF_TMP}" 2>/dev/null || true
  [[ -n "${INSTALL_CCACHE_DIR:-}" && -d "${INSTALL_CCACHE_DIR}" ]] && \rm -rf "${INSTALL_CCACHE_DIR}" 2>/dev/null || true
}

# Diagnostic only — set -e already aborts on the failing command; this just
# names the line/command so a failure deep in a 10-20 minute run is legible.
__on_err() {
  local ec=$?
  __warn "Command failed (exit ${ec}) at line ${BASH_LINENO[0]:-?}: ${BASH_COMMAND}"
}

# Re-raise after cleanup so callers still see 128+N, not 0.
__on_signal() {
  local sig="${1:?Usage: __on_signal <INT|TERM>}"
  case "${sig}" in
    INT) __warn "Interrupted (SIGINT)."; exit 130 ;;
    TERM) __warn "Terminated (SIGTERM)."; exit 143 ;;
  esac
}

trap '__cleanup' EXIT
trap '__on_err' ERR
trap '__on_signal INT' INT
trap '__on_signal TERM' TERM
# Service restarts under Incus/systemd can emit a spurious SIGHUP during
# finalization. Ignore it so idempotent reruns complete instead of aborting
# late in the install.
trap ':' HUP

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Pre-flight checks ───────────────────────────────────────────────────────

__check_root() {
  if [[ "$(\id -u)" -ne 0 ]]; then
    __error "This script must be run as root (exit 77)"
    exit 77
  fi
}

# FreeIPA's own definition of "a server is configured here"
# (ipalib.facts.is_ipa_configured). /etc/ipa/default.conf alone proves nothing:
# an enrolled client, or the leftovers of an aborted install, have it too.
__freeipa_server_configured() {
  if \command -v python3 >/dev/null 2>&1 && python3 -c 'import ipalib.facts' >/dev/null 2>&1; then
    python3 -c 'import sys; from ipalib import facts; sys.exit(0 if facts.is_ipa_configured() else 1)' >/dev/null 2>&1
    return
  fi
  [[ -s /var/lib/ipa/sysrestore/sysrestore.state ]]
}

# Refuse, before anything on the host is changed, to run on a machine that has
# IPA client/stale configuration but no configured FreeIPA server.
__preflight_freeipa_state() {
  case "${INSTALL_DISTRO_FAMILY}" in
    *debian*|*ubuntu*|*suse*)
      __error "FreeIPA server install is not supported on ${INSTALL_DISTRO}: no freeipa-server package exists upstream for Debian/Ubuntu/openSUSE. Nothing was changed. Use RHEL-family or Fedora for the server role; client.sh supports this distro (exit 79)"
      ;;
  esac
  __freeipa_server_configured && return 0

  local foreign
  if foreign="$(__httpd_foreign_ssl_vhost)"; then
    __error "An HTTPS virtual host on port 443 is already defined in ${foreign}; FreeIPA needs port 443 for its web UI. Nothing was changed. Move that virtual host to another port (for example 8443) or disable it, then re-run (exit 81)"
  fi

  [[ -f /etc/ipa/default.conf ]] || return 0

  # An aborted ipa-server-install leaves server directories behind (even after its client part was configured);
  # a plain enrolled client has only the client sysrestore state
  local has_server_remnants=0 d
  for d in /etc/dirsrv/slapd-* /var/lib/pki/pki-tomcat /etc/pki/pki-tomcat /var/lib/ipa/sysrestore/sysrestore.state; do
    [[ -e "${d}" ]] && has_server_remnants=1
  done
  if ! \command -v ipa-server-install >/dev/null 2>&1 \
    || { [[ -f /var/lib/ipa-client/sysrestore/sysrestore.state ]] && [[ "${has_server_remnants}" -eq 0 ]]; }; then
    __error "/etc/ipa/default.conf exists but no FreeIPA server is configured here (this host is an IPA client or has foreign IPA state). Nothing was changed. Run 'ipa-client-install --uninstall' or remove the stale configuration, then re-run (exit 78)"
  fi

  # What remains is an aborted ipa-server-install; clear it so the install can be re-run
  __warn "Found remnants of an aborted FreeIPA server install; removing them with ipa-server-install --uninstall"
  \ipa-server-install --uninstall --unattended \
    || __error "Could not clean up the aborted FreeIPA install; see /var/log/ipaserver-uninstall.log (exit 78)"
  # A Dogtag Tomcat instance can be started by the failed installation after an
  # earlier uninstall disabled its unit. Stop that exact FreeIPA service before
  # the CA port preflight; unrelated services on 8443 remain untouched.
  local pki_service="pki-tomcatd@pki-tomcat.service"
  if \command -v systemctl >/dev/null 2>&1 && \systemctl is-active --quiet "${pki_service}"; then
    __warn "Stopping leftover FreeIPA Dogtag service ${pki_service}"
    \systemctl stop "${pki_service}" \
      || __error "Could not stop leftover FreeIPA Dogtag service ${pki_service} (exit 78)"
  fi
  \rm -f /etc/ipa/default.conf
  __log "Aborted FreeIPA install cleaned up"
}

__check_requirements() {
  __log "Checking system requirements..."

  local mem_kb mem_gb disk_avail disk_gb
  mem_kb="$(\awk '/MemTotal/{print $2}' /proc/meminfo || true)"
  mem_gb=$(( mem_kb / 1024 / 1024 ))

  if [[ "${mem_gb}" -lt 2 ]]; then
    __error "System has less than 2 GB RAM (${mem_gb} GB). FreeIPA requires at least 2 GB."
  elif [[ "${mem_gb}" -lt 4 ]]; then
    __warn "System has less than 4 GB RAM (${mem_gb} GB). 4 GB+ recommended for full features."
  fi

  disk_avail="$(\df / | \tail -1 | \awk '{print $4}' || true)"
  disk_gb=$(( disk_avail / 1024 / 1024 ))

  if [[ "${disk_gb}" -lt 10 ]]; then
    __warn "Less than 10 GB disk space available (${disk_gb} GB). Consider freeing up space."
  fi

  if [[ "${FREEIPA_FQDN}" == "localhost" || "${FREEIPA_FQDN}" == "localhost.localdomain" ]]; then
    __error "Hostname is set to localhost. Configure a proper FQDN first."
  fi

  __log "System requirements check passed"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Distro detection ────────────────────────────────────────────────────────

__detect_distro() {
  if [[ -f /etc/os-release ]]; then
    # shellcheck source=/dev/null
    . /etc/os-release
    INSTALL_DISTRO="${ID:-unknown}"
    INSTALL_DISTRO_FAMILY="${ID_LIKE:-}"
    INSTALL_DISTRO_VERSION="${VERSION_ID:-unknown}"
  elif [[ -f /etc/redhat-release ]]; then
    INSTALL_DISTRO="rhel"
    INSTALL_DISTRO_FAMILY="rhel fedora"
    INSTALL_DISTRO_VERSION="unknown"
  elif [[ -f /etc/debian_version ]]; then
    INSTALL_DISTRO="debian"
    INSTALL_DISTRO_FAMILY="debian"
    INSTALL_DISTRO_VERSION="unknown"
  else
    __error "Cannot detect distribution"
  fi

  # Base distros (Fedora, Debian) set no ID_LIKE at all — only derivatives
  # (Alma/Rocky/CentOS, Ubuntu, openSUSE Leap/Tumbleweed) do. Fall back to
  # mapping ID itself so package-manager case statements downstream still
  # match instead of hitting "Unsupported distribution family: unknown".
  if [[ -z "${INSTALL_DISTRO_FAMILY}" ]]; then
    case "${INSTALL_DISTRO}" in
      fedora) INSTALL_DISTRO_FAMILY="fedora" ;;
      rhel|centos|almalinux|rocky) INSTALL_DISTRO_FAMILY="rhel fedora" ;;
      debian) INSTALL_DISTRO_FAMILY="debian" ;;
      opensuse*|sles) INSTALL_DISTRO_FAMILY="suse" ;;
      *) INSTALL_DISTRO_FAMILY="unknown" ;;
    esac
  fi

  __log "Detected distribution: ${INSTALL_DISTRO} ${INSTALL_DISTRO_VERSION} (family: ${INSTALL_DISTRO_FAMILY})"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Domain / hostname detection ─────────────────────────────────────────────

__detect_domain() {
  FREEIPA_FQDN="${FREEIPA_FQDN:-$(__determine_hostname_name 2>/dev/null || \hostname)}"

  if [[ "${FREEIPA_FQDN}" == *.* ]]; then
    # Extract domain from FQDN (everything after first label)
    FREEIPA_DOMAIN="${FREEIPA_DOMAIN:-${FREEIPA_FQDN#*.}}"
    FREEIPA_REALM="${FREEIPA_REALM:-${FREEIPA_DOMAIN^^}}"

    # For complex domains (>2 labels), note the primary domain
    local domain_parts
    domain_parts="${FREEIPA_DOMAIN//[^.]}"
    if [[ ${#domain_parts} -gt 1 ]]; then
      local primary_domain
      primary_domain="${FREEIPA_DOMAIN##*.}"
      primary_domain="${FREEIPA_DOMAIN%.*}.${primary_domain}"
      __log "Complex domain detected; primary domain: ${primary_domain}"
    fi
  elif [[ -n "${FREEIPA_DOMAIN}" ]]; then
    # Hostname has no domain but the caller already provided one
    FREEIPA_REALM="${FREEIPA_REALM:-${FREEIPA_DOMAIN^^}}"
    FREEIPA_FQDN="${FREEIPA_FQDN}.${FREEIPA_DOMAIN}"
  else
    if [[ -t 0 ]]; then
      __warn "No domain found in hostname. Enter domain manually:"
      printf 'Enter domain (e.g., example.com): '
      read -r FREEIPA_DOMAIN
    else
      __error "Non-interactive mode and no domain in hostname. Set FREEIPA_DOMAIN env var."
    fi
    FREEIPA_REALM="${FREEIPA_DOMAIN^^}"
    FREEIPA_FQDN="${FREEIPA_FQDN}.${FREEIPA_DOMAIN}"
  fi

  # DNS/LDAP hostnames and domains are lowercase by convention (and Kerberos
  # realms uppercase) regardless of how the caller cased an env override
  FREEIPA_FQDN="${FREEIPA_FQDN,,}"
  FREEIPA_DOMAIN="${FREEIPA_DOMAIN,,}"
  FREEIPA_REALM="${FREEIPA_REALM^^}"

  __log "Using hostname: ${FREEIPA_FQDN}"
  __log "Using domain:   ${FREEIPA_DOMAIN}"
  __log "Using realm:    ${FREEIPA_REALM}"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Package installation ────────────────────────────────────────────────────

__install_packages() {
  local pkg_mgr

  case "${INSTALL_DISTRO_FAMILY}" in
    *rhel*|*centos*)
      if \command -v dnf >/dev/null 2>&1; then
        pkg_mgr="dnf"
      else
        pkg_mgr="yum"
      fi
      __log "Installing FreeIPA packages via ${pkg_mgr}..."
      "${pkg_mgr}" update -y
      __install_ipa_packages "${pkg_mgr}" ipa-server ipa-server-dns ipa-server-trust-ad bind-utils chrony openldap-clients
      ;;

    # Fedora renamed the ipa-* packages to freeipa-* (RHEL/CentOS/Alma/Rocky
    # kept the ipa-* names) — matched after *rhel*/*centos* since a real
    # RHEL-like's family string ("rhel centos fedora") also contains "fedora".
    *fedora*)
      if \command -v dnf >/dev/null 2>&1; then
        pkg_mgr="dnf"
      else
        pkg_mgr="yum"
      fi
      __log "Installing FreeIPA packages via ${pkg_mgr}..."
      "${pkg_mgr}" update -y
      __install_ipa_packages "${pkg_mgr}" freeipa-server freeipa-server-dns freeipa-server-trust-ad bind-utils chrony openldap-clients
      ;;

    # No freeipa-server package exists for Debian/Ubuntu/openSUSE: verified
    # empirically (Docker, 2026-08) — Debian's own experimental repo has no
    # installable candidate, Ubuntu never shipped one (blocked upstream by a
    # bind-dyndb-ldap/bind9 packaging conflict) and its only PPA has been dead
    # since 2014, and openSUSE's security:idm OBS project ships freeipa-client
    # only. The FreeIPA server role is RHEL-family and Fedora only; client.sh
    # remains cross-distro and is unaffected.
    *debian*|*ubuntu*|*suse*)
      local unsupported_msg
      unsupported_msg="FreeIPA server install is not supported on ${INSTALL_DISTRO}"
      unsupported_msg+=" — no working freeipa-server package exists upstream for"
      unsupported_msg+=" Debian/Ubuntu/openSUSE. Use RHEL-family"
      unsupported_msg+=" (RHEL/CentOS/AlmaLinux/Rocky) or Fedora for the server"
      unsupported_msg+=" role; client.sh supports this distro."
      __error "${unsupported_msg}"
      ;;

    *)
      __error "Unsupported distribution family: ${INSTALL_DISTRO_FAMILY}"
      ;;
  esac
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── /etc/hosts ──────────────────────────────────────────────────────────────

__configure_hosts() {
  __log "Configuring /etc/hosts..."

  local primary_ip short_hostname
  primary_ip="$(__primary_ip)"
  if [[ -z "${primary_ip}" ]]; then
    __warn "Could not detect primary IP address; falling back to 127.0.0.1"
    primary_ip="127.0.0.1"
  fi

  __log "Using IP address: ${primary_ip}"

  # Remove stale aliases for the primary IP so reverse lookups return the IPA hostname.
  local escaped_ip="${primary_ip//./\\.}"
  \sed -i -E "/^[[:space:]]*${escaped_ip}[[:space:]]/d" /etc/hosts

  # Remove any existing entries for this FQDN then re-add with correct IP
  \sed -i "/${FREEIPA_FQDN}/d" /etc/hosts
  short_hostname="${FREEIPA_FQDN%%.*}"
  printf '%s %s %s\n' "${primary_ip}" "${FREEIPA_FQDN}" "${short_hostname}" >> /etc/hosts

  __log "Updated /etc/hosts"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Let's Encrypt certificate detection ─────────────────────────────────────

__check_letsencrypt_certs() {
  local le_live_dir="/etc/letsencrypt/live"
  [[ -d "${le_live_dir}" ]] || return 1

  __log "Checking for Let's Encrypt certificates..."

  local cert_dirs="" cert_count=0
  local cert_dir cert_name

  for cert_dir in "${le_live_dir}"/*; do
    [[ -d "${cert_dir}" ]] || continue
    [[ -f "${cert_dir}/cert.pem" ]] || continue
    [[ -f "${cert_dir}/privkey.pem" ]] || continue
    [[ -f "${cert_dir}/fullchain.pem" ]] || continue
    if ! \openssl x509 -in "${cert_dir}/cert.pem" -noout -checkhost "${FREEIPA_FQDN}" >/dev/null 2>&1; then
      __debug "Let's Encrypt candidate ${cert_dir##*/}: does not cover ${FREEIPA_FQDN}"
      continue
    fi
    cert_name="${cert_dir##*/}"
    if ! \openssl x509 -in "${cert_dir}/cert.pem" -noout -checkend 0 >/dev/null 2>&1; then
      __warn "Skipping Let's Encrypt certificate ${cert_name}: expired"
      continue
    fi
    if [[ "$(\openssl x509 -in "${cert_dir}/cert.pem" -noout -pubkey 2>/dev/null || true)" != "$(\openssl pkey -in "${cert_dir}/privkey.pem" -pubout 2>/dev/null || true)" ]]; then
      __warn "Skipping Let's Encrypt certificate ${cert_name}: private key does not match"
      continue
    fi
    # Self-signed and private-CA certificates (e.g. a bootstrap's placeholder under live/) are not for FreeIPA's public endpoints
    if ! \openssl verify -untrusted "${cert_dir}/fullchain.pem" "${cert_dir}/cert.pem" >/dev/null 2>&1; then
      __warn "Skipping certificate ${cert_name}: not issued by a publicly trusted CA"
      continue
    fi
    # Skip the README file that certbot places in the directory
    [[ "${cert_name}" == "README" ]] && continue
    cert_dirs="${cert_dirs} ${cert_dir}"
    cert_count=$(( cert_count + 1 ))
  done

  if [[ "${cert_count}" -eq 0 ]]; then
    __log "No Let's Encrypt certificates found in ${le_live_dir}"
    return 1
  fi

  local selected_dir=""

  if [[ "${cert_count}" -eq 1 ]]; then
    selected_dir="${cert_dirs# }"
    cert_name="${selected_dir##*/}"
    __log "Found 1 Let's Encrypt certificate: ${cert_name}"
  else
    __log "Found ${cert_count} Let's Encrypt certificates:"
    local i=1
    for cert_dir in ${cert_dirs}; do
      cert_name="${cert_dir##*/}"
      printf '  %d) %s\n' "${i}" "${cert_name}"
      i=$(( i + 1 ))
    done

    local cert_choice
    if [[ -t 0 ]]; then
      printf 'Select certificate to use (1-%d, 0 to skip): ' "${cert_count}"
      read -r cert_choice
    else
      # Non-interactive: auto-select the first certificate
      cert_choice=1
      __log "Non-interactive mode: auto-selecting first certificate"
    fi

    if [[ "${cert_choice}" -eq 0 ]] 2>/dev/null; then
      __log "Skipping Let's Encrypt certificates"
      return 1
    elif [[ "${cert_choice}" -ge 1 && "${cert_choice}" -le "${cert_count}" ]] 2>/dev/null; then
      i=1
      for cert_dir in ${cert_dirs}; do
        if [[ "${i}" -eq "${cert_choice}" ]]; then
          selected_dir="${cert_dir}"
          break
        fi
        i=$(( i + 1 ))
      done
    else
      __warn "Invalid selection; skipping Let's Encrypt certificates"
      return 1
    fi
  fi

  if [[ -f "${selected_dir}/cert.pem" && -f "${selected_dir}/privkey.pem" ]]; then
    INSTALL_CERT_PATH="${selected_dir}/cert.pem"
    INSTALL_KEY_PATH="${selected_dir}/privkey.pem"
    INSTALL_CHAIN_PATH="${selected_dir}/chain.pem"
    INSTALL_FULLCHAIN_PATH="${selected_dir}/fullchain.pem"
    __log "Using certificate: ${selected_dir##*/}"
    __log "  Certificate:  ${INSTALL_CERT_PATH}"
    __log "  Private key:  ${INSTALL_KEY_PATH}"
    __log "  Chain:        ${INSTALL_CHAIN_PATH}"
    __log "  Full chain:   ${INSTALL_FULLCHAIN_PATH}"
    return 0
  fi

  __warn "Certificate directory found but required files are missing"
  return 1
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── SSL certificate selection ───────────────────────────────────────────────

__configure_ssl_certs() {
  __log "Setting up SSL certificate options..."

  if __check_letsencrypt_certs; then
    __log "Using existing Let's Encrypt certificate"
    INSTALL_USE_LETSENCRYPT="true"
    INSTALL_USE_SELFSIGNED="false"
    INSTALL_USE_FREEIPA_CA="false"
    return 0
  fi

  # Fall back to FreeIPA's built-in CA
  __log "No Let's Encrypt certificates found; using FreeIPA built-in CA"
  INSTALL_USE_LETSENCRYPT="false"
  INSTALL_USE_FREEIPA_CA="true"
  INSTALL_USE_SELFSIGNED="false"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── DNS settings ────────────────────────────────────────────────────────────

__configure_dns_settings() {
  __log "Auto-detecting DNS configuration..."

  # On an idempotent rerun, the installed IPA DNS service already resolves the
  # hostname. Preserve the existing integrated-DNS state instead of treating
  # that successful lookup as evidence that IPA DNS is not in use.
  if __freeipa_server_configured && [[ -f "/etc/named/ipa-ext.conf" ]]; then
    INSTALL_DNS="true"
    INSTALL_CONFIGURE_REVERSE_ZONE="false"
    INSTALL_USE_AUTO_FORWARDERS="false"
    INSTALL_DNS_FORWARDERS=""
    __log "Integrated DNS is already installed; preserving existing configuration"
    __log "DNS configuration: integrated DNS=Yes"
    return 0
  fi

  if ! \nslookup "${FREEIPA_FQDN}" >/dev/null 2>&1; then
    __log "Hostname not resolvable via DNS; will install integrated DNS server"
    INSTALL_DNS="true"
    INSTALL_CONFIGURE_REVERSE_ZONE="true"
    # Extract only IPv4 nameservers from resolv.conf — skip IPv6 link-local
    # (fe80::) and pure IPv6 addresses; ipa-server-install check_forwarders
    # times out trying to validate link-local addresses from inside the container
    local _ns _ipv4_fwds=""
    while IFS= read -r _ns; do
      _ipv4_fwds="${_ipv4_fwds:+${_ipv4_fwds} }${_ns}"
    done < <(\awk '/^nameserver[[:space:]]+[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/{print $2}' /etc/resolv.conf)
    if [[ -n "${_ipv4_fwds}" ]]; then
      __log "Using IPv4 DNS forwarders: ${_ipv4_fwds}"
      INSTALL_DNS_FORWARDERS="${_ipv4_fwds}"
    else
      __log "No IPv4 DNS forwarders found; integrated DNS will run without forwarders"
    fi
    INSTALL_USE_AUTO_FORWARDERS="false"
  else
    __log "Hostname is resolvable; integrated DNS not required"
    INSTALL_DNS="false"
    INSTALL_USE_AUTO_FORWARDERS="false"
    INSTALL_CONFIGURE_REVERSE_ZONE="false"
  fi

  if [[ "${INSTALL_DNS}" == "true" ]]; then
    __log "DNS configuration: integrated DNS=Yes"
  else
    __log "DNS configuration: integrated DNS=No"
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── NTP / Chrony ────────────────────────────────────────────────────────────

__configure_ntp_settings() {
  if [[ "${INSTALL_NO_NTP}" == "true" ]]; then
    __log "Skipping NTP/Chrony configuration (--no-ntp)"
    return 0
  fi

  __log "Configuring NTP/Chrony..."

  # Find the exact unit name (chronyd.service on RHEL, chrony.service on Debian)
  # Match ^chrony[^-] to exclude chrony-wait.service and chronyd-restricted.service
  local chrony_unit
  chrony_unit="$(\systemctl list-unit-files 2>/dev/null | \awk '$1 ~ /^chronyd?\.service$/{print $1; exit}' || true)"

  if [[ -n "${chrony_unit}" ]]; then
    # enable is best-effort — may be masked in containers
    \systemctl enable "${chrony_unit}" 2>/dev/null || true
    # start requires CAP_SYS_TIME — non-fatal in containers
    if ! \systemctl start "${chrony_unit}" 2>/dev/null; then
      __warn "${chrony_unit} could not start (no CAP_SYS_TIME? running in container); continuing"
    else
      __log "${chrony_unit} enabled and started"
    fi
  else
    __warn "Chrony service not found; skipping NTP configuration"
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Let's Encrypt renewal hook ──────────────────────────────────────────────

__configure_letsencrypt_renewal() {
  __log "Installing Let's Encrypt certificate for FreeIPA HTTPS and LDAPS (mail reads it directly) and creating renewal hook..."

  local renewal_hook_dir="/etc/letsencrypt/renewal-hooks/deploy"
  local hook="${renewal_hook_dir}/freeipa-renew.sh"
  \mkdir -p "${renewal_hook_dir}"

  # The Let's Encrypt certificate serves every public-facing service: Apache HTTPS and LDAPS here,
  # Postfix and Dovecot straight from the same files. Kerberos, PKINIT and the CA keep IPA-issued certificates.
  # The issuer chain is added to IPA trust so IPA clients and services can validate it.
  {
    printf '#!/usr/bin/env sh\n'
    printf 'CRED_FILE=%q\n' "${FREEIPA_CRED_FILE}"
    printf 'FQDN=%q\n' "${FREEIPA_FQDN}"
    \cat << 'HOOKEOF'
# FreeIPA public certificate hook for Let's Encrypt (managed by install.sh)
# Run by certbot after a successful renewal, and once by install.sh.

LINEAGE="${RENEWED_LINEAGE:?RENEWED_LINEAGE not set}"
CERT_PATH="${LINEAGE}/fullchain.pem"
LEAF_PATH="${LINEAGE}/cert.pem"
KEY_PATH="${LINEAGE}/privkey.pem"
CHAIN_PATH="${LINEAGE}/chain.pem"

[ -f "${CERT_PATH}" ] && [ -f "${LEAF_PATH}" ] && [ -f "${KEY_PATH}" ] || exit 0

# certbot runs every deploy hook for every lineage it renews; only act for this host's certificate
openssl x509 -in "${LEAF_PATH}" -noout -checkhost "${FQDN}" >/dev/null 2>&1 || exit 0
openssl x509 -in "${LEAF_PATH}" -noout -checkend 0 >/dev/null 2>&1 || exit 0
[ "$(openssl x509 -in "${LEAF_PATH}" -noout -pubkey 2>/dev/null)" = "$(openssl pkey -in "${KEY_PATH}" -pubout 2>/dev/null)" ] || exit 0
openssl verify -untrusted "${CERT_PATH}" "${LEAF_PATH}" >/dev/null 2>&1 || exit 0

cred() { sed -n "s/^$1=//p" "${CRED_FILE}" | tail -n1; }
DM_PASS="$(cred INSTALL_DM_PASSWORD)"
ADMIN_PASS="$(cred INSTALL_ADMIN_PASSWORD)"
rc=0

# Make IPA trust the issuing chain so ipa-server-certinstall can validate it and IPA clients, sssd,
# Keycloak, Postfix and Dovecot verify LDAPS against /etc/ipa/ca.crt. The served chain normally stops at
# the intermediate; OpenSSL clients need the root as well, which comes from the system trust store.
if [ -f "${CHAIN_PATH}" ]; then
  TRUST_DIR="$(mktemp -d)"
  cp "${CHAIN_PATH}" "${TRUST_DIR}/chain.pem"
  python3 - "${CHAIN_PATH}" "${TRUST_DIR}/root.pem" <<'PYEOF' || true
import re, sys
from cryptography import x509
from cryptography.hazmat.primitives import serialization

def load_all(path):
    data = open(path, 'rb').read().decode('ascii', 'ignore')
    pems = re.findall(r'-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----', data, re.S)
    return [x509.load_pem_x509_certificate(p.encode()) for p in pems]

chain = load_all(sys.argv[1])
if not chain:
    sys.exit(0)
top = chain[-1]
if top.subject == top.issuer:
    sys.exit(0)
for bundle in ('/etc/pki/tls/certs/ca-bundle.crt', '/etc/ssl/certs/ca-certificates.crt'):
    try:
        candidates = load_all(bundle)
    except OSError:
        continue
    for cand in candidates:
        if cand.subject == top.issuer:
            open(sys.argv[2], 'wb').write(cand.public_bytes(serialization.Encoding.PEM))
            sys.exit(0)
PYEOF
  # The default credential cache can be unusable (KCM without sssd-kcm); use a private one
  CCACHE="$(mktemp)"
  KRB5CCNAME="FILE:${CCACHE}"
  export KRB5CCNAME
  if printf '%s\n' "${ADMIN_PASS}" | kinit admin >/dev/null 2>&1; then
    for f in "${TRUST_DIR}/root.pem" "${TRUST_DIR}/chain.pem"; do
      [ -s "${f}" ] || continue
      if ! out="$(ipa-cacert-manage install -t C,, "${f}" 2>&1)"; then
        printf '%s\n' "${out}" | grep -qi 'already' || { printf '%s\n' "${out}" >&2; rc=1; }
      fi
    done
    ipa-certupdate >/dev/null 2>&1 || rc=1
    kdestroy >/dev/null 2>&1 || true
  else
    echo "kinit admin failed" >&2
    rc=1
  fi
  rm -rf "${TRUST_DIR}"
  rm -f "${CCACHE}"
fi

# One certificate for every public-facing service that FreeIPA itself runs: Apache HTTPS and LDAPS.
# Postfix and Dovecot read the same files directly. Kerberos/PKINIT and the CA keep IPA-issued certificates.
if ipa-server-certinstall -w -d --pin= -p "${DM_PASS}" "${KEY_PATH}" "${CERT_PATH}"; then
  ipactl restart >/dev/null 2>&1 || rc=1
else
  rc=1
fi
for svc in postfix dovecot; do
  if systemctl is-active --quiet "${svc}" 2>/dev/null; then
    systemctl reload "${svc}" || rc=1
  fi
done

logger -t letsencrypt "FreeIPA HTTPS/LDAPS/mail certificate installed from ${LINEAGE} (rc=${rc})"
exit "${rc}"
HOOKEOF
  } > "${hook}"
  \chmod +x "${hook}"
  __log "Renewal hook created: ${hook}"

  if ! RENEWED_LINEAGE="${INSTALL_FULLCHAIN_PATH%/*}" "${hook}"; then
    __error "Could not install the Let's Encrypt certificate on FreeIPA HTTPS/LDAPS (exit 71)"
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── FreeIPA installation ────────────────────────────────────────────────────

# FreeIPA needs python3-mod_wsgi (the system Python). A Python-version-specific mod_wsgi from another repo
# (python3.11-mod_wsgi ...) ships the same files and cannot coexist with it in one Apache process, so
# the transaction conflicts. Remove only that package, say so, and retry once.
__install_ipa_packages() {
  local pkg_mgr="$1"
  shift
  if "${pkg_mgr}" install -y "$@"; then
    return 0
  fi
  local alt
  alt="$(\rpm -qa 2>/dev/null | \grep -E '^python3\.[0-9]+-mod_wsgi-' || true)"
  if [[ -z "${alt}" ]]; then
    return 1
  fi
  local p
  while IFS= read -r p; do
    __warn "Removing ${p}: it conflicts with the python3-mod_wsgi that FreeIPA requires"
    "${pkg_mgr}" remove -y "${p}" || return 1
  done <<< "${alt}"
  "${pkg_mgr}" install -y "$@"
}

__install_freeipa() {
  # Idempotency guard — skip if FreeIPA is already installed
  if __freeipa_server_configured; then
    __log "FreeIPA server already configured on this host; skipping ipa-server-install"
    # Still load credentials so downstream functions have them
    INSTALL_ADMIN_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_ADMIN_PASSWORD)" || {
      __warn "FreeIPA installed but admin password not found in ${FREEIPA_CRED_FILE}"
    }
    INSTALL_DM_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_DM_PASSWORD)" || {
      __warn "FreeIPA installed but DM password not found in ${FREEIPA_CRED_FILE}"
    }
    if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
      # Nginx may have owned ports 80/443 and kept Apache stopped on an existing host.
      # Start and verify FreeIPA's HTTP endpoint before certinstall calls its HTTPS API.
      __configure_freeipa_http
      __configure_letsencrypt_renewal
    fi
    return 0
  fi

  __log "Starting FreeIPA server installation..."

  # Load or generate admin password
  INSTALL_ADMIN_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_ADMIN_PASSWORD)" || {
    INSTALL_ADMIN_PASSWORD="$(__random_password 25)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_ADMIN_PASSWORD "${INSTALL_ADMIN_PASSWORD}"
  }

  # Load or generate Directory Manager password
  INSTALL_DM_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_DM_PASSWORD)" || {
    INSTALL_DM_PASSWORD="$(__random_password 25)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_DM_PASSWORD "${INSTALL_DM_PASSWORD}"
  }

  # Build installation command as an array to avoid quoting/eval issues
  local -a install_cmd
  install_cmd=(
    \ipa-server-install
    --unattended
    "--realm=${FREEIPA_REALM}"
    "--domain=${FREEIPA_DOMAIN}"
    "--hostname=${FREEIPA_FQDN}"
    "--admin-password=${INSTALL_ADMIN_PASSWORD}"
    "--ds-password=${INSTALL_DM_PASSWORD}"
  )

  if [[ "${INSTALL_NO_NTP}" == "true" ]]; then
    install_cmd+=( --no-ntp )
  fi

  if [[ "${INSTALL_DNS}" == "true" ]]; then
    install_cmd+=( --setup-dns )
    if [[ "${INSTALL_USE_AUTO_FORWARDERS}" == "true" ]]; then
      install_cmd+=( --auto-forwarders )
    elif [[ -n "${INSTALL_DNS_FORWARDERS}" ]]; then
      for _fwd in ${INSTALL_DNS_FORWARDERS}; do
        install_cmd+=( "--forwarder=${_fwd}" )
      done
    else
      install_cmd+=( --no-forwarders )
    fi
    if [[ "${INSTALL_CONFIGURE_REVERSE_ZONE}" == "true" ]]; then
      install_cmd+=( --auto-reverse )
    else
      install_cmd+=( --no-reverse )
    fi
  fi

  __log "Running FreeIPA installation (may take 10–20 minutes)..."
  if [[ "${FREEIPA_DEBUG}" -eq 1 ]]; then
    local _arg _shown=""
    for _arg in "${install_cmd[@]}"; do
      case "${_arg}" in
        --admin-password=*) _arg="--admin-password=xxxxx" ;;
        --ds-password=*) _arg="--ds-password=xxxxx" ;;
      esac
      _shown+=" ${_arg}"
    done
    __debug "ipa-server-install command:${_shown}"
  fi
  "${install_cmd[@]}"

  # If using Let's Encrypt, wire up the auto-renewal hook
  if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
    __configure_letsencrypt_renewal
  fi

  __log "FreeIPA server installation completed"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Apache port normalization ───────────────────────────────────────────────

__fix_freeipa_wsgi_cgi_handler() {
  [[ -d /etc/httpd/conf.d ]] || return 0

  # Some host bootstrap configs register every .py file as CGI. That overrides
  # FreeIPA's WSGI mapping and makes Apache try to execute its non-executable
  # wsgi.py, returning HTTP 500 from /ipa/json. Scope the override to that one
  # FreeIPA script and load it after the host's other conf.d files.
  local wsgi_handler_conf="/etc/httpd/conf.d/zz-freeipa-wsgi-handler.conf"
  local cgi_python=false f
  while IFS= read -r f; do
    if \awk '
      {
        sub(/[[:space:]]*#.*/, "")
        if (tolower($1) == "addhandler" && tolower($2) == "cgi-script") {
          for (i = 3; i <= NF; i++) if ($i == ".py") found = 1
        }
      }
      END { exit !found }
    ' "${f}"; then
      cgi_python=true
      break
    fi
  done < <(\find /etc/httpd -type f -name '*.conf' 2>/dev/null || true)

  if [[ "${cgi_python}" == "true" ]]; then
    if [[ -e "${wsgi_handler_conf}" ]] \
      && ! \grep -qF -- '# Written by install.sh: preserve FreeIPA WSGI handling when hosts register Python as CGI' "${wsgi_handler_conf}"; then
      __error "Refusing to overwrite existing Apache config ${wsgi_handler_conf} (exit 80)"
    fi
    {
      printf '# Written by install.sh: preserve FreeIPA WSGI handling when hosts register Python as CGI\n'
      printf '<Directory "/usr/share/ipa">\n  <Files "wsgi.py">\n    SetHandler wsgi-script\n  </Files>\n</Directory>\n'
    } > "${wsgi_handler_conf}"
    __log "Added ${wsgi_handler_conf} to keep FreeIPA wsgi.py under mod_wsgi"
  elif [[ -f "${wsgi_handler_conf}" ]] \
    && \grep -qF -- '# Written by install.sh: preserve FreeIPA WSGI handling when hosts register Python as CGI' "${wsgi_handler_conf}"; then
    \rm -f "${wsgi_handler_conf}"
    __log "Removed obsolete FreeIPA WSGI handler override"
  fi
}

# Some hosts run Apache on 81/8443 behind an nginx that owns 80/443. FreeIPA
# needs 80/443 for its own Apache, and its CA (Dogtag) binds 8443 itself, so a
# stock Apache listener on 8443 keeps the CA from starting. Move Listen 81 back
# to 80, drop Listen 8443 (mod_ssl's ssl.conf supplies 443) and disable the
# virtual hosts that were bound to 81/8443: left
# on 80/443 they would sit in front of FreeIPA's own vhost (a catch-all vhost
# with its own certificate serves that certificate to FreeIPA itself and breaks
# its client-side verification). Keep a backup of every file touched and prove
# the configuration still parses instead of trusting the edit.
__fix_httpd_ports() {
  local re='^[[:space:]]*Listen[[:space:]]+([^#[:space:]]*:)?(81|8443)([[:space:]]|$)|^[[:space:]]*<VirtualHost[^>]*:(81|8443)>'
  [[ -d /etc/httpd ]] || return 0
  __fix_freeipa_wsgi_cgi_handler
  # An installed FreeIPA already owns these ports (its CA holds 8443); nothing to do
  __freeipa_server_configured && return 0

  local -a files=()
  local f
  while IFS= read -r f; do
    files+=("${f}")
  done < <(\grep -rlisE --include='*.conf' -- "${re}" /etc/httpd || true)
  __debug "Apache files with 81/8443 listeners: ${files[*]:-none}"

  local rc_before=0 out=""
  if [[ "${#files[@]}" -eq 0 ]]; then
    __log "Apache configuration has no 81/8443 listeners; nothing to rewrite"
  else
    if \command -v httpd >/dev/null 2>&1; then
      \httpd -t >/dev/null 2>&1 || rc_before=1
    fi
    __rewrite_httpd_ports "${re}" "${rc_before}" "${files[@]}"
  fi

  __ensure_stock_ssl_conf
  __ensure_httpd_modules

  # A running httpd keeps its old sockets until restarted. Key this on what it
  # is actually listening on, not on whether files changed, so a re-run after a
  # failed attempt still releases 81/8443 before ipa-server-install checks them.
  if \ss -H -ltnp 2>/dev/null | \awk '$4 ~ /:(81|8443)$/ && /httpd/ {f=1} END{exit !f}'; then
    __log "Restarting Apache so it releases ports 81/8443"
    \systemctl restart httpd || __error "Could not restart Apache after moving it off 81/8443 (exit 75)"
  fi

  local port holder
  for port in 8443 8080 8005 8009; do
    holder="$(\ss -H -ltnp 2>/dev/null | \awk -v p=":${port}$" '$4 ~ p {print $NF; exit}')"
    if [[ -n "${holder}" ]]; then
      __error "Port ${port} is in use (${holder}); FreeIPA's CA needs 8005, 8009, 8080 and 8443 (exit 76)"
    fi
  done
}

# FreeIPA's ipa.conf uses directives from several Apache modules. Hosts whose
# httpd.conf lists modules inline and does not include conf.modules.d (with the
# packaged module configs emptied) never load mod_auth_gssapi and friends, so
# httpd refuses to start with "Invalid command 'GssapiUseSessions'". Load only
# the missing ones through a drop-in; the administrator's own modules are untouched.
__ensure_httpd_modules() {
  if ! \command -v httpd >/dev/null 2>&1; then
    __debug "httpd is not installed; skipping the Apache module check"
    return 0
  fi
  [[ -d /etc/httpd/conf.d ]] || return 0
  if __freeipa_server_configured; then
    __debug "FreeIPA server already configured; skipping the Apache module check"
    return 0
  fi

  # Some repositories ship python3-mod_wsgi with a module config that loads mod_wsgi_python3.so while the
  # package only provides mod_wsgi.so, so httpd cannot start at all. The config guards that LoadModule
  # with <IfModule !wsgi_module>; loading wsgi_module from the file that exists first satisfies it
  # without touching package-owned files.
  # mod_ssl generates its default localhost certificate when httpd first starts (httpd-init.service); a host
  # whose httpd could never start lacks it and ssl.conf then fails to parse, hiding every other problem
  if [[ ! -s /etc/pki/tls/certs/localhost.crt && -x /usr/libexec/httpd-ssl-gencerts ]]; then
    __debug "Generating mod_ssl's default localhost certificate (httpd-ssl-gencerts)"
    \/usr/libexec/httpd-ssl-gencerts >/dev/null 2>&1 || true
  fi

  local test_out
  if ! test_out="$(\httpd -t 2>&1)"; then
    if [[ "${test_out}" == *"Cannot load modules/mod_wsgi_python3.so"* \
      && -e /etc/httpd/modules/mod_wsgi.so && -d /etc/httpd/conf.modules.d ]]; then
      local wsgi_fix="/etc/httpd/conf.modules.d/00-freeipa-wsgi.conf"
      printf '# Written by install.sh: the packaged module config references a mod_wsgi_python3.so that does not exist\nLoadModule wsgi_module modules/mod_wsgi.so\n' > "${wsgi_fix}"
      # Only the dangling reference has to be gone; anything else is reported by the checks below
      if [[ "$(\httpd -t 2>&1 || true)" != *"mod_wsgi_python3.so"* ]]; then
        __log "Added ${wsgi_fix}: the packaged mod_wsgi config references a file that does not exist"
      else
        \rm -f "${wsgi_fix}"
        return 0
      fi
      if ! \httpd -t >/dev/null 2>&1; then
        __debug "Apache configuration still has errors after the mod_wsgi repair; skipping the module check"
        return 0
      fi
    else
      # Any other broken configuration cannot be repaired here; the later checks report it
      __debug "Apache configuration is invalid and not repairable here: ${test_out}"
      return 0
    fi
  fi

  local dropin="/etc/httpd/conf.d/00-freeipa-modules.conf" loaded m so cand
  local -a missing=() lines=()
  loaded="$(\httpd -M 2>/dev/null || true)"
  # Modules for the directives ipa.conf, ipa-rewrite.conf, ipa-pki-proxy.conf and mod_ssl's ssl.conf use;
  # ipa.conf loads mod_lookup_identity itself
  for m in auth_gssapi wsgi session session_cookie proxy proxy_http rewrite headers ssl expires \
    alias access_compat authn_core authz_core socache_shmcb; do
    [[ "${loaded}" == *" ${m}_module "* ]] && continue
    so=""
    for cand in "mod_${m}.so" "mod_${m}_python3.so"; do
      if [[ -e "/etc/httpd/modules/${cand}" ]]; then
        so="${cand}"
        break
      fi
    done
    [[ -n "${so}" ]] || __error "Apache module ${m}_module required by FreeIPA is not installed (exit 80)"
    missing+=("${m}")
    lines+=("LoadModule ${m}_module modules/${so}")
  done
  if [[ "${#missing[@]}" -eq 0 ]]; then
    __debug "All Apache modules required by FreeIPA are already loaded"
    return 0
  fi

  {
    printf '# Written by install.sh: modules required by FreeIPA that httpd.conf does not load\n'
    printf '%s\n' "${lines[@]}"
  } > "${dropin}"
  if ! \httpd -t >/dev/null 2>&1; then
    \rm -f "${dropin}"
    __error "Loading the Apache modules required by FreeIPA (${missing[*]}) made the configuration invalid; reverted (exit 80)"
  fi
  __log "Added ${dropin} to load Apache modules required by FreeIPA: ${missing[*]}"
}

# Prints the first Apache file (other than mod_ssl's ssl.conf) that defines an enabled virtual host on port 443
__httpd_foreign_ssl_vhost() {
  local conf="/etc/httpd/conf.d/ssl.conf" f
  [[ -d /etc/httpd ]] || return 1
  while IFS= read -r f; do
    [[ "${f}" == "${conf}" ]] && continue
    if \grep -vE '^[[:space:]]*#' "${f}" 2>/dev/null \
      | \grep -qiE '^[[:space:]]*<VirtualHost[^>]*:443([[:space:]>]|$)'; then
      printf '%s\n' "${f}"
      return 0
    fi
  done < <(\find /etc/httpd -type f -name '*.conf' 2>/dev/null || true)
  return 1
}

# FreeIPA configures TLS by editing directives inside mod_ssl's default
# <VirtualHost _default_:443>. On a host whose ssl.conf was emptied or has no
# vhost, those edits land outside any vhost, SSLEngine is never enabled and
# port 443 answers plain HTTP. Restore the packaged ssl.conf in that case.
__ensure_stock_ssl_conf() {
  local conf="/etc/httpd/conf.d/ssl.conf" tmp pkg
  [[ -d /etc/httpd/conf.d ]] || return 0
  \command -v rpm >/dev/null 2>&1 || return 0
  pkg="$(\rpm -q mod_ssl 2>/dev/null)" || return 0
  if \grep -qiE '^[[:space:]]*<VirtualHost' "${conf}" 2>/dev/null; then
    return 0
  fi

  # FreeIPA cannot own 443 next to an administrator's vhost there; the preflight refuses that case
  __httpd_foreign_ssl_vhost >/dev/null && return 0

  if ! \command -v rpm2cpio >/dev/null 2>&1 || ! \command -v cpio >/dev/null 2>&1; then
    __error "rpm2cpio and cpio are required to restore ${conf} (exit 77)"
  fi
  tmp="$(\mktemp -d)"
  ( cd "${tmp}" && \dnf download -q "${pkg}" >/dev/null 2>&1 ) \
    || { \rm -rf "${tmp}"; __error "Could not download ${pkg} to restore ${conf} (exit 77)"; }
  ( cd "${tmp}" && \rpm2cpio ./*.rpm | \cpio -idm ./etc/httpd/conf.d/ssl.conf >/dev/null 2>&1 )
  if [[ ! -s "${tmp}/etc/httpd/conf.d/ssl.conf" ]]; then
    \rm -rf "${tmp}"
    __error "${pkg} did not provide ${conf} (exit 77)"
  fi
  [[ -e "${conf}.pre-freeipa" ]] || \cp -p "${conf}" "${conf}.pre-freeipa" 2>/dev/null || true
  \cp "${tmp}/etc/httpd/conf.d/ssl.conf" "${conf}"
  \rm -rf "${tmp}"
  __log "Restored the packaged ${conf} (it had no virtual host; backup: ${conf}.pre-freeipa)"
}

# Rewrite the 81/8443 listeners in the given files; restore them if httpd -t
# turns invalid because of the change. Args: <regex> <rc_before> <file>...
__rewrite_httpd_ports() {
  local re="$1" rc_before="$2"
  shift 2
  local -a files=("$@")
  local f out=""

  for f in "${files[@]}"; do
    [[ -e "${f}.pre-freeipa" ]] || \cp -p "${f}" "${f}.pre-freeipa"
    \awk '
      BEGIN { IGNORECASE = 1 }
      /^[[:space:]]*<VirtualHost[^>]*:(81|8443)>/ { inblock = 1 }
      { if (inblock) { print "# freeipa-disabled: " $0 } else { print $0 } }
      inblock && /^[[:space:]]*<\/VirtualHost>/ { inblock = 0 }
    ' "${f}" > "${f}.freeipa-tmp" && \mv -f "${f}.freeipa-tmp" "${f}"
    \sed -i -E \
      -e 's/^([[:space:]]*Listen[[:space:]]+([^#[:space:]]*:)?)81([[:space:]]|$)/\180\3/I' \
      -e 's/^([[:space:]]*Listen[[:space:]]+([^#[:space:]]*:)?8443([[:space:]]|$).*)$/# freeipa-disabled: \1/I' \
      "${f}"
    __log "Moved Apache Listen 81 to 80 and disabled Listen 8443 plus the 81/8443 virtual hosts in ${f} (backup: ${f}.pre-freeipa)"
  done

  # Bootstrap configurations can declare the same legacy listener in several
  # included files. Rewriting each Listen 81 independently would then leave
  # duplicate Listen 80 directives, which makes Apache refuse to start.
  local -a all_conf_files=()
  while IFS= read -r f; do
    all_conf_files+=("${f}")
  done < <(\find /etc/httpd -type f -name '*.conf' -print 2>/dev/null || true)
  if ((${#all_conf_files[@]} > 0)); then
    for f in "${all_conf_files[@]}"; do
      : > "${f}.freeipa-tmp" || __error "Could not prepare Apache config for listener normalization: ${f}"
    done
    \awk '
      FNR == 1 {
        if (output != "") close(output)
        output = FILENAME ".freeipa-tmp"
      }
      /^[[:space:]]*Listen[[:space:]]/ && tolower($2) ~ /(^|:)80$/ {
        key = tolower($2 " " $3)
        if (seen[key]++) {
          sub(/^[[:space:]]*/, "")
          print "# freeipa-disabled: duplicate listener " $0 > output
          next
        }
      }
      { print > output }
      END { if (output != "") close(output) }
    ' "${all_conf_files[@]}" || __error "Could not normalize duplicate Apache port 80 listeners"
    for f in "${all_conf_files[@]}"; do
      if ! \cmp -s "${f}" "${f}.freeipa-tmp"; then
        [[ -e "${f}.pre-freeipa" ]] || \cp -p "${f}" "${f}.pre-freeipa"
        \mv -f "${f}.freeipa-tmp" "${f}"
        __log "Disabled duplicate Apache port 80 listener in ${f} (backup: ${f}.pre-freeipa)"
      else
        \rm -f "${f}.freeipa-tmp"
      fi
    done
  fi

  if \grep -rqisE --include='*.conf' -- "${re}" /etc/httpd; then
    __error "Apache still has a 81/8443 listener after moving ports (exit 74)"
  fi

  if \command -v httpd >/dev/null 2>&1; then
    if ! out="$(\httpd -t 2>&1)"; then
      if [[ "${rc_before}" -eq 0 ]]; then
        for f in "${files[@]}"; do
          \cp -p "${f}.pre-freeipa" "${f}"
        done
        __error "Apache configuration is invalid after moving ports to 80/443; originals restored: ${out}"
      fi
      __warn "Apache configuration was already invalid before the port change: ${out}"
    fi
  fi
}

# ─── FreeIPA HTTP configuration verification ────────────────────────────────

__configure_freeipa_http() {
  __log "Configuring FreeIPA Apache on standard HTTP and HTTPS ports..."
  local _web_units
  _web_units="$(\systemctl list-unit-files 2>/dev/null | \awk '{print $1}' || true)"
  if printf '%s\n' "${_web_units}" | \grep -q -- "^httpd.service$"; then
    \systemctl restart httpd
  elif printf '%s\n' "${_web_units}" | \grep -q -- "^apache2.service$"; then
    \systemctl restart apache2
  fi

  __verify_freeipa_http
}

__disable_nginx_service() {
  local unit_state="not-found"
  if ! \command -v systemctl >/dev/null 2>&1; then
    if \command -v nginx >/dev/null 2>&1; then
      __error "nginx is installed but systemctl is unavailable; stop and mask nginx before installing FreeIPA"
    fi
    return 0
  fi

  unit_state="$(\systemctl show --property=LoadState --value nginx.service 2>/dev/null || true)"
  if ! \command -v nginx >/dev/null 2>&1 && [[ "${unit_state}" == "not-found" || -z "${unit_state}" ]]; then
    __log "nginx is not installed"
    return 0
  fi

  if \systemctl is-active --quiet nginx.service; then
    \systemctl stop nginx.service || __error "Could not stop nginx; FreeIPA requires ports 80 and 443"
  fi
  if [[ "${unit_state}" != "not-found" && "${unit_state}" != "masked" && -n "${unit_state}" ]]; then
    \systemctl disable nginx.service >/dev/null 2>&1 || true
  fi
  \systemctl mask nginx.service >/dev/null || __error "Could not mask nginx.service"
  __log "Disabled and masked nginx; FreeIPA Apache will own ports 80 and 443"
}

__verify_freeipa_http() {
  local listeners port response status redirect
  listeners="$(\ss -H -ltn 2>/dev/null || true)"
  for port in 80 443; do
    if ! \awk -v suffix=":${port}" '$4 ~ (suffix "$") { found = 1 } END { exit !found }' <<< "${listeners}"; then
      __error "FreeIPA Apache is not listening on port ${port}"
    fi
  done

  response="$(\curl -q --silent --show-error --insecure --max-time 15 --output /dev/null --write-out '%{http_code} %{redirect_url}' \
    --resolve "${FREEIPA_FQDN}:80:127.0.0.1" "http://${FREEIPA_FQDN}/ipa/ui" 2>/dev/null)" \
    || __error "Could not verify FreeIPA HTTP to HTTPS redirect"
  status="${response%% *}"
  redirect="${response#* }"
  if [[ ( "${status}" != "301" && "${status}" != "302" ) || "${redirect}" != "https://${FREEIPA_FQDN}"* ]]; then
    __error "FreeIPA HTTP endpoint did not redirect to HTTPS for ${FREEIPA_FQDN} (status ${status})"
  fi
  __log "Verified FreeIPA listens on ports 80 and 443 and redirects HTTP to HTTPS"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Keycloak Apache reverse proxy ───────────────────────────────────────────
#
# Keycloak is deliberately left at its own default root path (no
# KC_HTTP_RELATIVE_PATH) — that keeps direct access via FREEIPA_KEYCLOAK_PORT
# working at "/" with no prefix, for anyone who wants to reach it without
# going through Apache. mod_rewrite's [P] flag proxies "/kc/*" to Keycloak
# with the prefix stripped, so Keycloak itself never knows it's under a
# prefix. Because Keycloak's HTML/JS then generates absolute links like
# "/realms/...", "/resources/...", "/js/..." (unaware of "/kc"), those exact
# top-level paths are proxied through too, unprefixed, so the browser's
# follow-up requests still land on Keycloak rather than 404 against
# FreeIPA's own vhost. This path list matches the Keycloak version pinned in
# __install_keycloak_docker's docker-compose.yml and may need updating on a
# major Keycloak upgrade.
__configure_apache_keycloak_proxy() {
  local apache_conf_dir="" ssl_conf=""
  if [[ -d "/etc/httpd/conf.d" ]]; then
    apache_conf_dir="/etc/httpd/conf.d"
    ssl_conf="/etc/httpd/conf.d/ssl.conf"
  elif [[ -d "/etc/apache2/conf-available" ]]; then
    apache_conf_dir="/etc/apache2/conf-available"
    ssl_conf="/etc/apache2/conf-available/ssl.conf"
  else
    __warn "Could not find Apache configuration directory; skipping Keycloak proxy config"
    return 0
  fi

  # Keycloak's docker-compose publishes on the docker0 bridge address, not
  # 127.0.0.1 — see the "172.17.0.1:${FREEIPA_KEYCLOAK_PORT}" host-port
  # binding in __install_keycloak_docker's compose file. Proxying to
  # 127.0.0.1 here would connect-refuse.
  local kc_conf="${apache_conf_dir}/freeipa-keycloak-proxy.conf"
  \cat > "${kc_conf}" << EOF
# Keycloak reverse proxy under /kc — managed by install.sh
<IfModule mod_proxy.c>
  ProxyPreserveHost On
  ProxyPassReverse /kc/ http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}/
</IfModule>

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^/kc\$ /kc/ [R=301,L]
  RewriteRule ^/kc/(.*)\$ http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}/\$1 [P,L]
  RewriteRule ^/(admin|realms|resources|js|welcome-content|robots\.txt)(.*)\$ http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}/\$1\$2 [P,L]
</IfModule>

RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
EOF

  if [[ -d "/etc/apache2/conf-enabled" ]]; then
    \ln -sf "${kc_conf}" /etc/apache2/conf-enabled/freeipa-keycloak-proxy.conf
  fi

  # A plain conf.d/*.conf file is loaded at Apache's global/server scope,
  # not inside the <VirtualHost _default_:443> block that handles HTTPS,
  # so its RewriteRule/
  # ProxyPass directives would never be evaluated. ipa-rewrite.conf avoids
  # this by being Include'd from inside that VirtualHost (see ssl.conf) —
  # mirror that exact pattern here, idempotently.
  if [[ -f "${ssl_conf}" ]] && ! \grep -q -- "Include ${kc_conf}" "${ssl_conf}" 2>/dev/null; then
    \sed -i "/^Include .*ipa-rewrite\.conf\$/a Include ${kc_conf}" "${ssl_conf}"
    \grep -q -- "Include ${kc_conf}" "${ssl_conf}" \
      || __error "Keycloak proxy include was not added to ${ssl_conf}"
    __log "Included freeipa-keycloak-proxy.conf inside the SSL VirtualHost"
  fi

  local _web_units
  _web_units="$(\systemctl list-unit-files 2>/dev/null | \awk '{print $1}' || true)"
  if printf '%s\n' "${_web_units}" | \grep -q -- "^httpd.service$"; then
    \systemctl restart httpd
  elif printf '%s\n' "${_web_units}" | \grep -q -- "^apache2.service$"; then
    \systemctl restart apache2
  fi

  __log "Configured Apache to reverse-proxy Keycloak under /kc on port 443"
  __verify_freeipa_http
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── LDAP base DN derivation ─────────────────────────────────────────────────

__derive_ldap_base_dn() {
  local dn="" part
  local IFS='.'
  for part in ${FREEIPA_DOMAIN}; do
    dn="${dn},dc=${part}"
  done
  INSTALL_LDAP_BASE_DN="${dn#,}"
  FREEIPA_KEYCLOAK_REALM="${FREEIPA_KEYCLOAK_REALM:-${FREEIPA_DOMAIN}}"
  __log "LDAP base DN: ${INSTALL_LDAP_BASE_DN}"
  __log "Keycloak realm: ${FREEIPA_KEYCLOAK_REALM}"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Docker installation ─────────────────────────────────────────────────────

__install_docker() {
  if \command -v docker >/dev/null 2>&1; then
    __log "Docker already installed; checking daemon availability"
    if \command -v systemctl >/dev/null 2>&1; then
      \systemctl enable docker >/dev/null 2>&1 \
        || __error "Docker is installed but docker.service could not be enabled"
      \systemctl start docker >/dev/null 2>&1 \
        || __error "Docker is installed but docker.service could not be started; check 'systemctl status docker'"
    fi
    \docker info >/dev/null 2>&1 \
      || __error "Docker is installed but its daemon is unavailable; check 'systemctl status docker'"
    __log "Docker daemon is available"
    return 0
  fi

  __log "Installing Docker CE..."

  case "${INSTALL_DISTRO_FAMILY}" in
    *rhel*|*fedora*|*centos*)
      local repo_distro
      case "${INSTALL_DISTRO}" in
        fedora) repo_distro="fedora" ;;
        centos) repo_distro="centos" ;;
        *)      repo_distro="rhel"   ;;
      esac
      \dnf install -y dnf-plugins-core
      \dnf config-manager --add-repo "https://download.docker.com/linux/${repo_distro}/docker-ce.repo"
      \dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
      ;;

    *debian*|*ubuntu*)
      \apt-get install -y ca-certificates curl gnupg
      \mkdir -p /etc/apt/keyrings
      \curl -q -fsSL "https://download.docker.com/linux/${INSTALL_DISTRO}/gpg" | \gpg --dearmor -o /etc/apt/keyrings/docker.gpg
      \chmod a+r /etc/apt/keyrings/docker.gpg
      local arch codename
      arch="$(\dpkg --print-architecture)"
      # Source os-release to get VERSION_CODENAME
      # shellcheck source=/dev/null
      . /etc/os-release
      codename="${VERSION_CODENAME:-}"
      printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/%s %s stable\n' \
        "${arch}" "${INSTALL_DISTRO}" "${codename}" > /etc/apt/sources.list.d/docker.list
      \apt-get update && \apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
      ;;

    *)
      __error "Unsupported distribution family for Docker install: ${INSTALL_DISTRO_FAMILY}"
      ;;
  esac

  \systemctl enable docker && \systemctl start docker
  __log "Docker installed and started"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── jq installation ─────────────────────────────────────────────────────────

__install_jq() {
  if \command -v jq >/dev/null 2>&1; then
    __log "jq already installed; skipping"
    return 0
  fi

  __log "Installing jq..."

  case "${INSTALL_DISTRO_FAMILY}" in
    *rhel*|*fedora*|*centos*)
      if \command -v dnf >/dev/null 2>&1; then
        \dnf install -y jq
      else
        \yum install -y jq
      fi
      ;;
    *debian*|*ubuntu*)
      \apt-get install -y jq
      ;;
    *suse*)
      \zypper install -y jq
      ;;
    *)
      __error "Unsupported distribution family for jq install: ${INSTALL_DISTRO_FAMILY}"
      ;;
  esac

  __log "jq installed"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Prerequisites ───────────────────────────────────────────────────────────

__install_prerequisites() {
  __log "Installing prerequisites..."
  __install_docker
  __install_jq
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── FreeIPA post-config for Keycloak ────────────────────────────────────────

__setup_freeipa_for_keycloak() {
  __log "Configuring FreeIPA for Keycloak LDAP federation..."

  # Load or generate Keycloak LDAP bind password
  INSTALL_KEYCLOAK_LDAP_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_LDAP_PASSWORD)" || {
    INSTALL_KEYCLOAK_LDAP_PASSWORD="$(__random_password 32)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_LDAP_PASSWORD "${INSTALL_KEYCLOAK_LDAP_PASSWORD}"
  }

  \mkdir -p "${FREEIPA_KEYCLOAK_CONFIG_DIR}"

  # Obtain a Kerberos ticket for the admin user
  printf '%s\n' "${INSTALL_ADMIN_PASSWORD}" | \kinit "admin@${FREEIPA_REALM}"

  # Create temp dir before mktemp to ensure parent exists
  \mkdir -p "${TMPDIR:-/tmp}/scriptmgr"
  INSTALL_LDIF_TMP="$(\mktemp "${TMPDIR:-/tmp}/scriptmgr/freeipa-XXXXXX.ldif")"

  # Write LDIF for the Keycloak sysaccount bind user
  {
    printf 'dn: uid=keycloak,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'objectClass: account\n'
    printf 'objectClass: simplesecurityobject\n'
    printf 'uid: keycloak\n'
    # 389-ds only recognizes its own registered storage-scheme prefixes;
    # {cleartext} is not one of them (the scheme is named "Clear", prefix
    # {CLEAR}) so a value tagged with it fails to verify on bind.
    printf 'userPassword: {CLEAR}%s\n' "${INSTALL_KEYCLOAK_LDAP_PASSWORD}"
    printf 'passwordExpirationTime: 20380119031407Z\n'
    printf 'nsIdleTimeout: 0\n'
  } > "${INSTALL_LDIF_TMP}"

  # Use FQDN — not localhost — so Kerberos resolves ldap/{FQDN}@REALM correctly
  # ldapadd is add-only: on a re-run the entry already exists and this fails,
  # which previously left userPassword un-synced with FREEIPA_CRED_FILE if it
  # was ever set incorrectly. Fall back to an explicit password replace so
  # the LDAP entry always converges on the saved credential.
  if ! \ldapadd -Y GSSAPI -H "ldap://${FREEIPA_FQDN}" -f "${INSTALL_LDIF_TMP}" 2>/dev/null; then
    {
      printf 'dn: uid=keycloak,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
      printf 'changetype: modify\n'
      printf 'replace: userPassword\n'
      printf 'userPassword: {CLEAR}%s\n' "${INSTALL_KEYCLOAK_LDAP_PASSWORD}"
    } | \ldapmodify -Y GSSAPI -H "ldap://${FREEIPA_FQDN}"
  fi

  # Remove LDIF immediately — it contained a cleartext password
  \rm -f "${INSTALL_LDIF_TMP}"
  INSTALL_LDIF_TMP=""

  # Create HTTP service principal for Kerberos SPNEGO
  __ipa_service_add "HTTP/${FREEIPA_FQDN}"

  # Export keytab for Keycloak
  \ipa-getkeytab -p "HTTP/${FREEIPA_FQDN}@${FREEIPA_REALM}" -k "${FREEIPA_KEYCLOAK_CONFIG_DIR}/keycloak.keytab"
  \chmod 600 "${FREEIPA_KEYCLOAK_CONFIG_DIR}/keycloak.keytab"

  # ipa-getkeytab generates a fresh random key each time it exports one for
  # this principal, bumping its kvno. Since HTTP/${FREEIPA_FQDN} is the same
  # principal Apache's own gssproxy keytab was provisioned with, the export
  # above just invalidated Apache's copy — breaking IPA's own web UI/CLI
  # SPNEGO auth. Re-sync gssproxy's keytab to the same new key immediately
  # so both consumers stay in sync, then restart gssproxy to pick it up.
  local _gssproxy_keytab="/var/lib/ipa/gssproxy/http.keytab"
  if [[ -f "${_gssproxy_keytab}" ]]; then
    \ipa-getkeytab -p "HTTP/${FREEIPA_FQDN}@${FREEIPA_REALM}" -k "${_gssproxy_keytab}"
    \chown root:root "${_gssproxy_keytab}"
    \chmod 600 "${_gssproxy_keytab}"
    \systemctl restart gssproxy
  fi

  # Export IPA CA certificate so Keycloak can trust LDAPS
  \cp /etc/ipa/ca.crt "${FREEIPA_KEYCLOAK_CONFIG_DIR}/ipa-ca.crt"
  \chmod 644 "${FREEIPA_KEYCLOAK_CONFIG_DIR}/ipa-ca.crt"

  # Destroy Kerberos ticket — no longer needed
  \kdestroy 2>/dev/null || true

  __log "FreeIPA configured for Keycloak federation"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Docker Compose helper ───────────────────────────────────────────────────

__compose() {
  if \docker compose version >/dev/null 2>&1; then
    \docker compose "$@"
  else
    \docker-compose "$@"
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Keycloak Docker deployment ──────────────────────────────────────────────

__install_keycloak_docker() {
  # Idempotency guard — if Keycloak container is already running, just ensure
  # credentials are loaded and skip docker-compose regeneration.
  if \docker inspect keycloak >/dev/null 2>&1; then
    __log "Keycloak container already exists; loading credentials and skipping redeploy"
    INSTALL_KEYCLOAK_ADMIN_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_ADMIN_PASSWORD)" || {
      __warn "Keycloak running but admin password not in ${FREEIPA_CRED_FILE}"
    }
    INSTALL_KEYCLOAK_DB_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_DB_PASSWORD)" || true
    return 0
  fi

  __log "Deploying Keycloak via Docker Compose..."

  # Load or generate Keycloak admin password
  INSTALL_KEYCLOAK_ADMIN_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_ADMIN_PASSWORD)" || {
    INSTALL_KEYCLOAK_ADMIN_PASSWORD="$(__random_password 32)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_ADMIN_PASSWORD "${INSTALL_KEYCLOAK_ADMIN_PASSWORD}"
  }

  # Load or generate Keycloak database password
  INSTALL_KEYCLOAK_DB_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_DB_PASSWORD)" || {
    INSTALL_KEYCLOAK_DB_PASSWORD="$(__random_password 32)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_KEYCLOAK_DB_PASSWORD "${INSTALL_KEYCLOAK_DB_PASSWORD}"
  }

  # FREEIPA_KEYCLOAK_PORT is resolved once in __main (env override > saved
  # credential > random); don't re-read it here or a caller-supplied value gets
  # silently discarded.
  if [[ -z "${FREEIPA_KEYCLOAK_PORT}" ]]; then
    FREEIPA_KEYCLOAK_PORT="$(__load_credential "${FREEIPA_CRED_FILE}" FREEIPA_KEYCLOAK_PORT)" || {
      FREEIPA_KEYCLOAK_PORT="$(__random_port)"
      __save_credential "${FREEIPA_CRED_FILE}" FREEIPA_KEYCLOAK_PORT "${FREEIPA_KEYCLOAK_PORT}"
    }
  fi

  local primary_ip
  primary_ip="$(__primary_ip)"

  \mkdir -p "${FREEIPA_COMPOSE_DIR}"

  # docker compose re-interpolates ${VAR}/$VAR inside the YAML file it reads,
  # so a literal '$' from __random_password's charset followed by identifier
  # characters is silently stripped as an unset-variable reference — corrupting
  # the password with no error at `compose up` time. Escape '$' as '$$' (the
  # compose-file literal-dollar syntax) only in the values written below.
  local kc_admin_password_escaped="${INSTALL_KEYCLOAK_ADMIN_PASSWORD//\$/\$\$}"
  local kc_db_password_escaped="${INSTALL_KEYCLOAK_DB_PASSWORD//\$/\$\$}"

  # Generate docker-compose.yml with all values hardcoded — no .env required
  \cat > "${FREEIPA_COMPOSE_DIR}/docker-compose.yml" << EOF
# Generated by install.sh — do not edit manually
# Regenerate by re-running install.sh

services:
  postgres:
    image: postgres:16-alpine
    container_name: keycloak-db
    restart: unless-stopped
    pull_policy: missing
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: "${kc_db_password_escaped}"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: unless-stopped
    pull_policy: missing
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: "${kc_db_password_escaped}"
      KC_HTTP_ENABLED: "true"
      KC_HTTP_PORT: "${FREEIPA_KEYCLOAK_PORT}"
      KC_HOSTNAME_STRICT: "false"
      # KC_PROXY: edge is the deprecated Hostname v1 proxy option (Keycloak
      # logs "Hostname v1 options [proxy] are still in use" and still emits
      # http:// links behind TLS termination). KC_PROXY_HEADERS: xforwarded
      # is its Hostname v2 replacement — it makes Keycloak trust the
      # X-Forwarded-Proto/Port/For headers Apache sets, so redirect and
      # asset URLs come back with the correct https scheme and port when
      # reached through the /kc reverse proxy.
      KC_PROXY_HEADERS: xforwarded
      KC_TRUSTSTORE_PATHS: /etc/keycloak/ipa-ca.crt
      # The deprecated KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD pair creates a
      # "temporary" admin that Keycloak forces through a password-change
      # flow in its web UI before any API password grant will succeed —
      # every scripted token request below fails with invalid_user_credentials
      # until that UI step runs. KC_BOOTSTRAP_ADMIN_USERNAME/PASSWORD creates
      # a normal, immediately usable admin instead.
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: "${kc_admin_password_escaped}"
      KC_LOG_LEVEL: INFO
      JAVA_OPTS_APPEND: -Djava.security.krb5.conf=/etc/krb5.conf
    volumes:
      - "${FREEIPA_KEYCLOAK_CONFIG_DIR}/keycloak.keytab:/etc/keycloak/keycloak.keytab:ro"
      - "${FREEIPA_KEYCLOAK_CONFIG_DIR}/ipa-ca.crt:/etc/keycloak/ipa-ca.crt:ro"
      - "/etc/krb5.conf:/etc/krb5.conf:ro"
      - keycloak_data:/opt/keycloak/data
    ports:
      - "172.17.0.1:${FREEIPA_KEYCLOAK_PORT}:${FREEIPA_KEYCLOAK_PORT}"
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - keycloak
    extra_hosts:
      - "${FREEIPA_FQDN}:${primary_ip}"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"
    healthcheck:
      test:
        - CMD-SHELL
        - >
          exec 3<>/dev/tcp/localhost/${FREEIPA_KEYCLOAK_PORT} &&
          printf 'GET /realms/master/.well-known/openid-configuration HTTP/1.0\\r\\nHost: localhost\\r\\n\\r\\n' >&3 &&
          grep -q -- 'issuer' <&3
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 90s

networks:
  keycloak:
    name: keycloak
    driver: bridge

volumes:
  postgres_data:
  keycloak_data:
EOF

  \chmod 600 "${FREEIPA_COMPOSE_DIR}/docker-compose.yml"

  __compose -f "${FREEIPA_COMPOSE_DIR}/docker-compose.yml" up -d

  __log "Keycloak containers started"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Wait for Keycloak readiness ─────────────────────────────────────────────

__wait_for_keycloak() {
  __log "Waiting for Keycloak to become ready (up to 300 s)..."
  local elapsed=0
  while [[ "${elapsed}" -lt 300 ]]; do
    # Use the OIDC discovery document as the readiness probe — it is served only
    # after Keycloak's HTTP servlet is fully initialised and the master realm
    # exists. The /health/ready path returns 404 on the main port in KC 26
    # (health lives on the management port 9000 which is not host-bound here).
    if \curl -q -LSs --max-time 5 \
        "http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}/realms/master/.well-known/openid-configuration" \
        2>/dev/null | \grep -q -- '"issuer"'; then
      __log "Keycloak is ready"
      return 0
    fi
    __log "  ... waiting (${elapsed}s elapsed)"
    sleep 10
    elapsed=$(( elapsed + 10 ))
  done
  __error "Keycloak did not become ready within 300 seconds (exit 69)"
  exit 69
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Keycloak admin token helper ─────────────────────────────────────────────

__keycloak_admin_token() {
  local kc_url="http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}"
  local token attempt=0
  # Retry up to 6 times (60 s total) — Keycloak may still be warming up its
  # HTTP servlet even after the OIDC discovery probe passes.
  while [[ "${attempt}" -lt 6 ]]; do
    token="$(\curl -q -LSs --max-time 10 -X POST \
      "${kc_url}/realms/master/protocol/openid-connect/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "grant_type=password" \
      --data-urlencode "client_id=admin-cli" \
      --data-urlencode "username=admin" \
      --data-urlencode "password=${INSTALL_KEYCLOAK_ADMIN_PASSWORD}" \
      2>/dev/null | \jq -r '.access_token // empty' 2>/dev/null)"
    if [[ -n "${token}" && "${token}" != "null" ]]; then
      printf '%s\n' "${token}"
      return 0
    fi
    attempt=$(( attempt + 1 ))
    sleep 10
  done
  __error "Could not obtain Keycloak admin token after ${attempt} attempts"
  return 1
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Keycloak REST call helper ───────────────────────────────────────────────

# Run one Keycloak admin REST call and fail the install on any non-2xx answer,
# so a rejected request can never be reported as a configured step.
# Usage: __kc_call <METHOD> <path> [json-body]
# Sets KC_BODY (response body) and KC_LOCATION (Location header, if any).
__kc_call() {
  local method="${1:?}" path="${2:?}" body="${3:-}"
  local token hdr out code
  token="$(__keycloak_admin_token)"
  hdr="$(\mktemp)"
  out="$(\mktemp)"
  local -a args=( -q -LSs --max-time 60 -X "${method}" -D "${hdr}" -o "${out}" -w '%{http_code}' -H "Authorization: Bearer ${token}" )
  [[ -n "${body}" ]] && args+=( -H "Content-Type: application/json" -d "${body}" )
  code="$(\curl -q "${args[@]}" "http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}${path}")" || code="000"
  KC_BODY="$(<"${out}")"
  KC_LOCATION="$(\grep -i -- '^location:' "${hdr}" | \tail -n1 | \tr -d '\r\n' || true)"
  \rm -f "${hdr}" "${out}"
  if [[ ! "${code}" =~ ^2[0-9][0-9]$ ]]; then
    __error "Keycloak ${method} ${path} failed (HTTP ${code}): ${KC_BODY:0:300}"
  fi
}

# Add service principals even when the host resolver cannot see IPA's own DNS zone.
# Some host bootstrap configurations keep resolv.conf immutable and pointed at an upstream resolver.
__ipa_service_add() {
  local out
  if ! out="$(\ipa service-add --force "$1" 2>&1)"; then
    if ! \grep -qi -- 'already exists' <<< "${out}"; then
      __error "ipa service-add $1 failed: ${out}"
    fi
  fi
}

# ─── Keycloak REST API configuration ─────────────────────────────────────────

__configure_keycloak() {
  __log "Configuring Keycloak realm and LDAP federation..."

  local kc_url="http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}"
  local token

  # Step 1 — Create realm (idempotent: skip if realm already exists)
  token="$(__keycloak_admin_token)"
  local realm_exists
  realm_exists="$(\curl -q -LSs --max-time 10 \
    "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}" \
    -H "Authorization: Bearer ${token}" \
    2>/dev/null | \jq -r '.realm // empty' 2>/dev/null)"

  if [[ -z "${realm_exists}" ]]; then
    __kc_call POST "/admin/realms" "$(\jq -n --arg r "${FREEIPA_KEYCLOAK_REALM}" --arg d "${FREEIPA_DOMAIN}" \
      '{realm: $r, enabled: true, displayName: ("SSO — " + $d), sslRequired: "external", registrationAllowed: false, bruteForceProtected: true}')"
    __log "Realm ${FREEIPA_KEYCLOAK_REALM} created"
  else
    __log "Realm ${FREEIPA_KEYCLOAK_REALM} already exists; skipping creation"
  fi

  # Step 2 — Create LDAP user federation component (idempotent — check first)
  token="$(__keycloak_admin_token)"

  # Check if freeipa-ldap component already exists
  local _existing_comp
  _existing_comp="$(\curl -q -LSs --max-time 10 \
    "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}/components?type=org.keycloak.storage.UserStorageProvider&name=freeipa-ldap" \
    -H "Authorization: Bearer ${token}" 2>/dev/null | \jq -r 'if type == "array" then .[0].id // empty else empty end' 2>/dev/null || true)"

  local ldap_body
  ldap_body="$(\jq -n \
    --arg fqdn "${FREEIPA_FQDN}" \
    --arg base_dn "${INSTALL_LDAP_BASE_DN}" \
    --arg ldap_pass "${INSTALL_KEYCLOAK_LDAP_PASSWORD}" \
    --arg realm "${FREEIPA_REALM}" \
    --arg keytab "/etc/keycloak/keycloak.keytab" \
    '{
      name: "freeipa-ldap",
      providerId: "ldap",
      providerType: "org.keycloak.storage.UserStorageProvider",
      config: {
        enabled: ["true"],
        priority: ["0"],
        importEnabled: ["true"],
        editMode: ["READ_ONLY"],
        syncRegistrations: ["false"],
        vendor: ["rhds"],
        usernameLDAPAttribute: ["uid"],
        rdnLDAPAttribute: ["uid"],
        uuidLDAPAttribute: ["ipaUniqueID"],
        # FreeIPA user entries (including the built-in admin account) carry
        # person/posixaccount/inetuser/krbprincipalaux, NOT inetOrgPerson or
        # organizationalPerson — filtering on those classes matches zero
        # FreeIPA users, so LDAP sync silently imports nobody.
        userObjectClasses: ["person, posixaccount"],
        connectionUrl: [("ldaps://" + $fqdn + ":636")],
        usersDn: [("cn=users,cn=accounts," + $base_dn)],
        authType: ["simple"],
        bindDn: [("uid=keycloak,cn=sysaccounts,cn=etc," + $base_dn)],
        bindCredential: [$ldap_pass],
        searchScope: ["1"],
        pagination: ["true"],
        connectionPooling: ["true"],
        connectionTimeout: ["5000"],
        readTimeout: ["10000"],
        useTruststoreSpi: ["ldapsOnly"],
        kerberosIntegration: ["true"],
        serverPrincipal: [("HTTP/" + $fqdn + "@" + $realm)],
        keyTab: [$keytab],
        kerberosRealm: [$realm],
        allowKerberosAuthentication: ["true"],
        useKerberosForPasswordAuthentication: ["false"],
        updateProfileFirstLogin: ["false"],
        cachePolicy: ["DEFAULT"],
        batchSizeForSync: ["1000"],
        fullSyncPeriod: ["-1"],
        changedSyncPeriod: ["86400"]
      }
    }')"

  local ldap_response component_id
  if [[ -n "${_existing_comp}" && "${_existing_comp}" != "null" ]]; then
    component_id="${_existing_comp}"
    # Update in place so config drift (e.g. a fixed bind password, a corrected
    # userObjectClasses filter after a script upgrade) is reconciled on every
    # re-run instead of being permanently frozen at whatever was first created.
    __kc_call PUT "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/components/${component_id}" \
      "$(printf '%s\n' "${ldap_body}" | \jq --arg id "${component_id}" '. + {id: $id}')"
    __log "LDAP federation component already exists (id: ${component_id}); config updated"
  else
    __kc_call POST "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/components" "${ldap_body}"
    component_id="${KC_LOCATION##*/}"
    __log "LDAP federation component created (id: ${component_id})"
  fi

  if [[ -z "${component_id}" ]]; then
    __error "Could not get the LDAP federation component ID from Keycloak"
  fi

  # Step 3 — Trigger full LDAP sync
  __kc_call POST "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/user-storage/${component_id}/sync?action=triggerFullSync"

  __log "LDAP full sync triggered"

  # Step 4 — Wait for admin user to appear after sync (up to 60 s)
  # Refresh token — previous one may be stale after sync wait
  token="$(__keycloak_admin_token)"
  local admin_user_id="" attempt=0
  while [[ -z "${admin_user_id}" || "${admin_user_id}" == "null" ]] && [[ "${attempt}" -lt 12 ]]; do
    sleep 5
    # Refresh token every 3 attempts to avoid 401
    if [[ $(( attempt % 3 )) -eq 0 ]]; then
      token="$(__keycloak_admin_token)"
    fi
    local _users_resp
    _users_resp="$(\curl -q -LSs --max-time 10 \
      "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}/users?username=admin&exact=true" \
      -H "Authorization: Bearer ${token}" 2>/dev/null)"
    admin_user_id="$(printf '%s\n' "${_users_resp}" | \jq -r 'if type == "array" then .[0].id // empty else empty end' 2>/dev/null || true)"
    attempt=$(( attempt + 1 ))
  done

  if [[ -z "${admin_user_id}" || "${admin_user_id}" == "null" ]]; then
    __error "Admin user did not appear in Keycloak after the LDAP sync"
  fi

  # Step 5 — Assign realm-admin role to admin user

  # Refresh token before role assignment
  token="$(__keycloak_admin_token)"

  # Get realm-management client ID
  local rm_client_id _clients_resp
  _clients_resp="$(\curl -q -LSs --max-time 10 \
    "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients?clientId=realm-management" \
    -H "Authorization: Bearer ${token}" 2>/dev/null)"
  rm_client_id="$(printf '%s\n' "${_clients_resp}" | \jq -r 'if type == "array" then .[0].id // empty else empty end' 2>/dev/null || true)"

  if [[ -z "${rm_client_id}" || "${rm_client_id}" == "null" ]]; then
    __error "Could not find the realm-management client in Keycloak"
  fi

  # Get realm-admin role details
  local role_info role_id role_name
  role_info="$(\curl -q -LSs --max-time 10 \
    "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients/${rm_client_id}/roles/realm-admin" \
    -H "Authorization: Bearer ${token}" 2>/dev/null)"
  role_id="$(printf '%s\n' "${role_info}" | \jq -r '.id // empty' 2>/dev/null || true)"
  role_name="$(printf '%s\n' "${role_info}" | \jq -r '.name // empty' 2>/dev/null || true)"

  if [[ -z "${role_id}" || "${role_id}" == "null" ]]; then
    __error "Could not find the realm-admin role in Keycloak"
  fi

  # Assign realm-admin role to the admin user
  __kc_call POST "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/users/${admin_user_id}/role-mappings/clients/${rm_client_id}" \
    "[$(\jq -n --arg id "${role_id}" --arg name "${role_name}" '{id: $id, name: $name}')]"
  # Confirm the mapping really exists rather than trusting the POST alone
  __kc_call GET "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/users/${admin_user_id}/role-mappings/clients/${rm_client_id}"
  \jq -e --arg n "${role_name}" 'map(.name) | index($n)' <<< "${KC_BODY}" >/dev/null \
    || __error "realm-admin role is not mapped to the Keycloak admin user"

  __log "Keycloak realm configured. Admin promoted to realm-admin."
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Keycloak confidential client for Dovecot OAuth2 introspection ───────────

__configure_keycloak_mail_client() {
  if [[ "${FREEIPA_MAIL_KEYCLOAK_AUTH}" != "true" ]]; then
    __log "Keycloak mail auth disabled (FREEIPA_MAIL_KEYCLOAK_AUTH=false); skipping"
    return 0
  fi

  __log "Configuring Keycloak confidential client for Dovecot token introspection..."

  local kc_url="http://172.17.0.1:${FREEIPA_KEYCLOAK_PORT}"
  local token
  token="$(__keycloak_admin_token)"

  INSTALL_MAIL_KEYCLOAK_SECRET="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_MAIL_KEYCLOAK_SECRET)" || {
    INSTALL_MAIL_KEYCLOAK_SECRET="$(__random_password 32)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_MAIL_KEYCLOAK_SECRET "${INSTALL_MAIL_KEYCLOAK_SECRET}"
  }

  local existing_client_id
  existing_client_id="$(\curl -q -LSs --max-time 10 \
    "${kc_url}/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients?clientId=${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID}" \
    -H "Authorization: Bearer ${token}" 2>/dev/null | \jq -r 'if type == "array" then .[0].id // empty else empty end' 2>/dev/null || true)"

  local client_body
  client_body="$(\jq -n \
    --arg cid "${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID}" \
    --arg secret "${INSTALL_MAIL_KEYCLOAK_SECRET}" \
    '{
      clientId: $cid,
      enabled: true,
      protocol: "openid-connect",
      publicClient: false,
      standardFlowEnabled: false,
      directAccessGrantsEnabled: true,
      serviceAccountsEnabled: true,
      secret: $secret,
      protocolMappers: [{
        name: "dovecot-audience",
        protocol: "openid-connect",
        protocolMapper: "oidc-audience-mapper",
        config: {
          "included.client.audience": $cid,
          "id.token.claim": "false",
          "access.token.claim": "true"
        }
      }]
    }')"

  if [[ -n "${existing_client_id}" && "${existing_client_id}" != "null" ]]; then
    __kc_call PUT "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients/${existing_client_id}" \
      "$(printf '%s\n' "${client_body}" | \jq --arg id "${existing_client_id}" '. + {id: $id}')"
    __log "Keycloak mail client ${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID} already exists; config updated"
  else
    __kc_call POST "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients" "${client_body}"
    __log "Keycloak mail client ${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID} created"
  fi

  # Read the client back and confirm what Dovecot depends on is really there
  __kc_call GET "/admin/realms/${FREEIPA_KEYCLOAK_REALM}/clients?clientId=${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID}"
  \jq -e '.[0] | .enabled and .directAccessGrantsEnabled and (.protocolMappers | map(.name) | index("dovecot-audience"))' \
    <<< "${KC_BODY}" >/dev/null \
    || __error "Keycloak client ${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID} is missing its audience mapper or direct grants"

  __log "Keycloak mail client configured"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Post-install stubs ───────────────────────────────────────────────────────

# AD trust support (ipa-adtrust-install) is enabled unconditionally as part of
# setup — only RHEL-family and Fedora have a working freeipa-server package
# (verified empirically; Debian/Ubuntu/openSUSE abort earlier in
# __install_packages), so this never reaches ipa-adtrust-install on those.
__configure_ad_trust() {
  case "${INSTALL_DISTRO_FAMILY}" in
    *rhel*|*centos*|*fedora*) ;;
    *)
      __log "AD trust setup (ipa-adtrust-install) is only supported on RHEL-family and Fedora; skipping on ${INSTALL_DISTRO}"
      return 0
      ;;
  esac

  # ipa-adtrust-install stores its config in the Samba registry (smb.conf just
  # `include`s it), so "netbios name" shows up under `net conf list`, not in
  # smb.conf itself. Its own docs warn re-running --add-sids on an
  # already-trusted server can cause high replication traffic, so use that as
  # the idempotency marker rather than re-running unconditionally
  if \net conf list 2>/dev/null | \grep -q -- "netbios name"; then
    __log "AD trust already configured (Samba registry has a netbios name); skipping ipa-adtrust-install"
    return 0
  fi

  __log "Configuring AD trust support (ipa-adtrust-install)..."

  printf '%s\n' "${INSTALL_ADMIN_PASSWORD}" | \kinit "admin@${FREEIPA_REALM}"

  # Note: ipa-adtrust-install does not support GSSAPI or stdin password input.
  # The admin password appears in process arguments briefly during execution.
  # This is a known limitation of the tool.
  if ! \ipa-adtrust-install -U -a "${INSTALL_ADMIN_PASSWORD}" --add-sids; then
    __warn "ipa-adtrust-install failed — AD trust support was not configured; run it manually if needed"
    return 0
  fi

  __log "AD trust support configured"
}

__create_initial_objects() {
  __log "Initial user/group creation skipped — use the web UI or CLI after installation"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Mail (Postfix/Dovecot) package installation ─────────────────────────────

__install_mail_packages() {
  if \command -v postfix >/dev/null 2>&1 && \command -v dovecot >/dev/null 2>&1; then
    __log "Postfix and Dovecot already installed; skipping"
    return 0
  fi

  __log "Installing Postfix and Dovecot..."

  case "${INSTALL_DISTRO_FAMILY}" in
    *rhel*|*fedora*|*centos*)
      \dnf install -y postfix postfix-ldap dovecot dovecot-pigeonhole
      ;;
    *debian*|*ubuntu*)
      \apt-get install -y postfix postfix-ldap dovecot-core dovecot-imapd dovecot-pop3d dovecot-lmtpd dovecot-ldap
      ;;
    *suse*)
      \zypper install -y postfix postfix-ldap dovecot dovecot-backend-ldap
      ;;
    *)
      __error "Unsupported distribution family for mail package install: ${INSTALL_DISTRO_FAMILY}"
      ;;
  esac

  __log "Postfix and Dovecot installed"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── FreeIPA post-config for Mail ─────────────────────────────────────────────

__setup_freeipa_for_mail() {
  __log "Configuring FreeIPA for Postfix/Dovecot LDAP integration..."

  FREEIPA_MAIL_DOMAIN="${FREEIPA_MAIL_DOMAIN:-${FREEIPA_DOMAIN}}"

  # Load or generate the mail LDAP bind password — used only for read-only
  # LDAP lookups; actual user password checks happen via auth_bind against
  # the user's own DN, so FreeIPA's Kerberos-backed password stays authoritative
  INSTALL_MAIL_LDAP_PASSWORD="$(__load_credential "${FREEIPA_CRED_FILE}" INSTALL_MAIL_LDAP_PASSWORD)" || {
    INSTALL_MAIL_LDAP_PASSWORD="$(__random_password 32)"
    __save_credential "${FREEIPA_CRED_FILE}" INSTALL_MAIL_LDAP_PASSWORD "${INSTALL_MAIL_LDAP_PASSWORD}"
  }

  # Obtain a Kerberos ticket for the admin user
  printf '%s\n' "${INSTALL_ADMIN_PASSWORD}" | \kinit "admin@${FREEIPA_REALM}"

  \mkdir -p "${TMPDIR:-/tmp}/scriptmgr"
  INSTALL_LDIF_TMP="$(\mktemp "${TMPDIR:-/tmp}/scriptmgr/freeipa-mail-XXXXXX.ldif")"

  {
    printf 'dn: uid=mail,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'objectClass: account\n'
    printf 'objectClass: simplesecurityobject\n'
    printf 'uid: mail\n'
    printf 'userPassword: {CLEAR}%s\n' "${INSTALL_MAIL_LDAP_PASSWORD}"
    printf 'passwordExpirationTime: 20380119031407Z\n'
    printf 'nsIdleTimeout: 0\n'
  } > "${INSTALL_LDIF_TMP}"

  # ldapadd is add-only: on a re-run the entry already exists and this fails,
  # so fall back to an explicit password replace to converge on the saved
  # credential (same pattern as the Keycloak sysaccount above).
  if ! \ldapadd -Y GSSAPI -H "ldap://${FREEIPA_FQDN}" -f "${INSTALL_LDIF_TMP}" 2>/dev/null; then
    {
      printf 'dn: uid=mail,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
      printf 'changetype: modify\n'
      printf 'replace: userPassword\n'
      printf 'userPassword: {CLEAR}%s\n' "${INSTALL_MAIL_LDAP_PASSWORD}"
    } | \ldapmodify -Y GSSAPI -H "ldap://${FREEIPA_FQDN}"
  fi

  # Remove LDIF immediately — it contained a cleartext password
  \rm -f "${INSTALL_LDIF_TMP}"
  INSTALL_LDIF_TMP=""

  # Service principals backing the shared Postfix/Dovecot TLS certificate
  __ipa_service_add "smtp/${FREEIPA_FQDN}"
  __ipa_service_add "imap/${FREEIPA_FQDN}"

  \kdestroy 2>/dev/null || true

  \mkdir -p /etc/mail/certs
  # certmonger must be able to create its key and certificate here under
  # enforcing SELinux; cert_t is the writable certificate-file context.
  # Guarded because semanage ships in policycoreutils-python-utils, which only
  # arrives transitively via ipa-server-common; it is absent on a Debian-family
  # host and restorecon is equally optional there.
  if \command -v semanage >/dev/null 2>&1; then
    \semanage fcontext -a -t cert_t "/etc/mail/certs(/.*)?" 2>/dev/null ||
      \semanage fcontext -m -t cert_t "/etc/mail/certs(/.*)?" 2>/dev/null || true
  fi
  \restorecon -RF /etc/mail/certs 2>/dev/null || true
  INSTALL_MAIL_CERT_PATH="/etc/mail/certs/mail.pem"
  INSTALL_MAIL_KEY_PATH="/etc/mail/certs/mail.key"

  # A publicly trusted certificate is used for the public mail ports when one exists (renewed by the certbot
  # hook, which reloads Postfix and Dovecot); otherwise a FreeIPA-issued certificate tracked by certmonger.
  if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
    INSTALL_MAIL_CERT_PATH="${INSTALL_FULLCHAIN_PATH}"
    INSTALL_MAIL_KEY_PATH="${INSTALL_KEY_PATH}"
    __log "Mail TLS uses the Let's Encrypt certificate (${INSTALL_MAIL_CERT_PATH})"
    __log "FreeIPA configured for mail (Postfix/Dovecot) integration"
    return 0
  fi
  if ! \getcert list -f "${INSTALL_MAIL_CERT_PATH}" >/dev/null 2>&1; then
    if [[ -e "${INSTALL_MAIL_CERT_PATH}" || -e "${INSTALL_MAIL_KEY_PATH}" ]]; then
      \rm -f "${INSTALL_MAIL_CERT_PATH}" "${INSTALL_MAIL_KEY_PATH}"
    fi
    \ipa-getcert request \
      -f "${INSTALL_MAIL_CERT_PATH}" \
      -k "${INSTALL_MAIL_KEY_PATH}" \
      -N "CN=${FREEIPA_FQDN}" \
      -K "smtp/${FREEIPA_FQDN}" \
      -D "${FREEIPA_FQDN}" \
      -B "chown root:postfix ${INSTALL_MAIL_KEY_PATH}; chmod 640 ${INSTALL_MAIL_KEY_PATH}" \
      -C "systemctl reload postfix dovecot 2>/dev/null || true" \
      -w
  fi

  # Wait for certmonger to finish issuing the certificate (local CA — fast)
  local elapsed=0
  while [[ "${elapsed}" -lt 60 ]]; do
    if \getcert list -f "${INSTALL_MAIL_CERT_PATH}" 2>/dev/null | \grep -q -- 'status: MONITORING'; then
      break
    fi
    sleep 2
    elapsed=$(( elapsed + 2 ))
  done
  if ! \getcert list -f "${INSTALL_MAIL_CERT_PATH}" 2>/dev/null | \grep -q -- 'status: MONITORING'; then
    __error "Mail TLS certificate was not issued within 60 seconds (exit 70)"
    exit 70
  fi

  \chown root:postfix "${INSTALL_MAIL_KEY_PATH}"
  \chmod 640 "${INSTALL_MAIL_KEY_PATH}"

  __log "FreeIPA configured for mail (Postfix/Dovecot) integration"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Mail storage (virtual mailboxes) ────────────────────────────────────────

__create_mail_storage() {
  __log "Preparing mail storage..."

  if ! \getent group "${FREEIPA_MAIL_VUSER}" >/dev/null 2>&1; then
    \groupadd -g "${FREEIPA_MAIL_VID}" "${FREEIPA_MAIL_VUSER}"
  fi
  if ! \getent passwd "${FREEIPA_MAIL_VUSER}" >/dev/null 2>&1; then
    \useradd -r -u "${FREEIPA_MAIL_VID}" -g "${FREEIPA_MAIL_VID}" \
      -d "${FREEIPA_MAIL_BASE_DIR}" -s /usr/sbin/nologin "${FREEIPA_MAIL_VUSER}"
  fi

  \mkdir -p "${FREEIPA_MAIL_BASE_DIR}/${FREEIPA_MAIL_DOMAIN}"
  \chown -R "${FREEIPA_MAIL_VUSER}:${FREEIPA_MAIL_VUSER}" "${FREEIPA_MAIL_BASE_DIR}"
  \chmod -R 750 "${FREEIPA_MAIL_BASE_DIR}"

  __log "Mail storage ready at ${FREEIPA_MAIL_BASE_DIR}/${FREEIPA_MAIL_DOMAIN}"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Postfix configuration ───────────────────────────────────────────────────

__configure_postfix() {
  __log "Configuring Postfix..."

  \mkdir -p /etc/postfix/ldap

  {
    printf 'server_host = %s\n' "${FREEIPA_FQDN}"
    printf 'server_port = 389\n'
    printf 'start_tls = yes\n'
    printf 'tls_ca_cert_file = /etc/ipa/ca.crt\n'
    printf 'version = 3\n'
    printf 'bind = yes\n'
    printf 'bind_dn = uid=mail,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'bind_pw = %s\n' "${INSTALL_MAIL_LDAP_PASSWORD}"
    printf 'search_base = cn=users,cn=accounts,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'scope = sub\n'
    # %%u/%%d split the recipient into user/domain parts and recombine against
    # the canonical mail domain, so a *.FREEIPA_MAIL_DOMAIN subdomain recipient
    # (accepted by the regexp virtual_mailbox_domains map above) still matches
    # the user's single canonical "mail" attribute instead of bouncing 550.
    printf 'query_filter = (&(objectClass=posixAccount)(mail=%%u@%s))\n' "${FREEIPA_MAIL_DOMAIN}"
    printf 'result_attribute = uid\n'
  } > /etc/postfix/ldap/virtual-mailbox.cf
  \chown root:postfix /etc/postfix/ldap/virtual-mailbox.cf
  \chmod 640 /etc/postfix/ldap/virtual-mailbox.cf

  {
    printf 'server_host = %s\n' "${FREEIPA_FQDN}"
    printf 'server_port = 389\n'
    printf 'start_tls = yes\n'
    printf 'tls_ca_cert_file = /etc/ipa/ca.crt\n'
    printf 'version = 3\n'
    printf 'bind = yes\n'
    printf 'bind_dn = uid=mail,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'bind_pw = %s\n' "${INSTALL_MAIL_LDAP_PASSWORD}"
    printf 'search_base = cn=users,cn=accounts,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'scope = sub\n'
    # Same subdomain-normalization as virtual-mailbox.cf above.
    printf 'query_filter = (&(objectClass=posixAccount)(mail=%%u@%s))\n' "${FREEIPA_MAIL_DOMAIN}"
    printf 'result_attribute = mail\n'
  } > /etc/postfix/ldap/virtual-alias.cf
  \chown root:postfix /etc/postfix/ldap/virtual-alias.cf
  \chmod 640 /etc/postfix/ldap/virtual-alias.cf

  # Postfix's virtual_mailbox_domains takes a literal list or a lookup table —
  # it has no built-in glob/wildcard syntax — so a regexp: map is the correct
  # way to accept both the exact domain and any *.{domain} subdomain
  local mail_domain_regex="${FREEIPA_MAIL_DOMAIN//./\\.}"
  printf '/^([^@]+\\.)?%s$/    OK\n' "${mail_domain_regex}" > /etc/postfix/regexp-virtual-domains
  \chown root:postfix /etc/postfix/regexp-virtual-domains
  \chmod 640 /etc/postfix/regexp-virtual-domains

  local marker_begin="# --- scriptmgr-freeipa mail block (begin) ---"
  local marker_end="# --- scriptmgr-freeipa mail block (end) ---"

  # Remove any previously-written block so re-runs converge instead of duplicating
  \sed -i "/^${marker_begin}\$/,/^${marker_end}\$/d" /etc/postfix/main.cf

  # Comment out distro-default keys our block redefines, so postconf -n has one value each
  \sed -i -E \
    -e 's/^(smtpd_tls_cert_file[[:space:]]*=.*)$/# \1 (superseded by scriptmgr-freeipa mail block)/' \
    -e 's/^(smtpd_tls_key_file[[:space:]]*=.*)$/# \1 (superseded by scriptmgr-freeipa mail block)/' \
    -e 's/^(inet_interfaces[[:space:]]*=.*)$/# \1 (superseded by scriptmgr-freeipa mail block)/' \
    -e 's/^(mydestination[[:space:]]*=.*)$/# \1 (superseded by scriptmgr-freeipa mail block)/' \
    /etc/postfix/main.cf

  {
    printf '%s\n' "${marker_begin}"
    printf 'virtual_mailbox_domains = regexp:/etc/postfix/regexp-virtual-domains\n'
    printf 'virtual_mailbox_base = %s\n' "${FREEIPA_MAIL_BASE_DIR}"
    printf 'virtual_mailbox_maps = ldap:/etc/postfix/ldap/virtual-mailbox.cf\n'
    printf 'virtual_alias_maps = ldap:/etc/postfix/ldap/virtual-alias.cf\n'
    printf 'virtual_uid_maps = static:%s\n' "${FREEIPA_MAIL_VID}"
    printf 'virtual_gid_maps = static:%s\n' "${FREEIPA_MAIL_VID}"
    printf 'virtual_transport = lmtp:unix:private/dovecot-lmtp\n'
    printf 'smtpd_sasl_type = dovecot\n'
    printf 'smtpd_sasl_path = private/auth\n'
    printf 'smtpd_sasl_auth_enable = yes\n'
    printf 'smtpd_sasl_security_options = noanonymous\n'
    printf 'smtpd_recipient_restrictions = permit_sasl_authenticated,permit_mynetworks,reject_unauth_destination\n'
    printf 'smtpd_relay_restrictions = permit_sasl_authenticated,permit_mynetworks,reject_unauth_destination\n'
    printf 'smtpd_tls_cert_file = %s\n' "${INSTALL_MAIL_CERT_PATH}"
    printf 'smtpd_tls_key_file = %s\n' "${INSTALL_MAIL_KEY_PATH}"
    printf 'smtpd_tls_CAfile = /etc/ipa/ca.crt\n'
    printf 'smtpd_tls_security_level = may\n'
    printf 'smtpd_tls_auth_only = yes\n'
    printf 'smtp_tls_security_level = may\n'
    printf 'myhostname = %s\n' "${FREEIPA_FQDN}"
    printf 'mydomain = %s\n' "${FREEIPA_MAIL_DOMAIN}"
    printf 'myorigin = $mydomain\n'
    printf 'inet_interfaces = all\n'
    printf 'mydestination = localhost\n'
    printf '%s\n' "${marker_end}"
  } >> /etc/postfix/main.cf

  # Enable submission (587) and smtps (465) — idempotent, only append once
  if ! \grep -q -- '^submission ' /etc/postfix/master.cf; then
    {
      printf 'submission inet n       -       n       -       -       smtpd\n'
      printf '  -o syslog_name=postfix/submission\n'
      printf '  -o smtpd_tls_security_level=encrypt\n'
      printf '  -o smtpd_sasl_auth_enable=yes\n'
      printf '  -o smtpd_relay_restrictions=permit_sasl_authenticated,reject\n'
    } >> /etc/postfix/master.cf
  fi
  if ! \grep -q -- '^smtps ' /etc/postfix/master.cf; then
    {
      printf 'smtps     inet  n       -       n       -       -       smtpd\n'
      printf '  -o syslog_name=postfix/smtps\n'
      printf '  -o smtpd_tls_wrappermode=yes\n'
      printf '  -o smtpd_sasl_auth_enable=yes\n'
      printf '  -o smtpd_relay_restrictions=permit_sasl_authenticated,reject\n'
    } >> /etc/postfix/master.cf
  fi

  \systemctl enable postfix
  \systemctl restart postfix

  __log "Postfix configured"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Dovecot configuration ───────────────────────────────────────────────────

# Allow dovecot_auth_t to reach the Keycloak introspection port under SELinux.
__allow_dovecot_keycloak_selinux() {
  if ! \command -v checkmodule >/dev/null 2>&1 || ! \command -v semodule_package >/dev/null 2>&1; then
    local _pm="dnf"
    \command -v dnf >/dev/null 2>&1 || _pm="yum"
    "${_pm}" install -y checkpolicy policycoreutils >/dev/null 2>&1 || true
  fi
  if ! \command -v checkmodule >/dev/null 2>&1 || ! \command -v semodule_package >/dev/null 2>&1; then
    __warn "checkmodule/semodule_package unavailable; Dovecot may be unable to reach Keycloak under SELinux"
    return 0
  fi
  if \command -v semanage >/dev/null 2>&1; then
    \semanage port -m -t http_port_t -p tcp "${FREEIPA_KEYCLOAK_PORT}" 2>/dev/null \
      || \semanage port -a -t http_port_t -p tcp "${FREEIPA_KEYCLOAK_PORT}" 2>/dev/null || true
  fi
  local _dir
  _dir="$(\mktemp -d)"
  {
    printf 'module scriptmgr_dovecot_keycloak 1.0;\n\n'
    printf 'require {\n  type dovecot_auth_t;\n  type http_port_t;\n  class tcp_socket name_connect;\n}\n\n'
    printf 'allow dovecot_auth_t http_port_t:tcp_socket name_connect;\n'
  } > "${_dir}/scriptmgr_dovecot_keycloak.te"
  if \checkmodule -M -m -o "${_dir}/scriptmgr_dovecot_keycloak.mod" "${_dir}/scriptmgr_dovecot_keycloak.te" >/dev/null 2>&1 \
    && \semodule_package -o "${_dir}/scriptmgr_dovecot_keycloak.pp" -m "${_dir}/scriptmgr_dovecot_keycloak.mod" >/dev/null 2>&1 \
    && \semodule -i "${_dir}/scriptmgr_dovecot_keycloak.pp" >/dev/null 2>&1; then
    __log "SELinux: allowed Dovecot to connect to Keycloak port ${FREEIPA_KEYCLOAK_PORT}"
  else
    __warn "Could not install SELinux policy module for Dovecot -> Keycloak"
  fi
  \rm -rf "${_dir}"
}

__configure_dovecot() {
  __log "Configuring Dovecot..."

  # Disable the distro-default system passdb/userdb include — our own block
  # below adds the local Unix fallback explicitly (via pam/passwd) instead,
  # so FreeIPA LDAP stays authoritative and tried first
  if [[ -f /etc/dovecot/conf.d/10-auth.conf ]]; then
    \sed -i 's/^!include auth-system.conf.ext/#!include auth-system.conf.ext/' \
      /etc/dovecot/conf.d/10-auth.conf
  fi

  if [[ "${FREEIPA_MAIL_LOCAL_FALLBACK}" == "true" && ! -f /etc/pam.d/dovecot ]]; then
    {
      printf '#%%PAM-1.0\n'
      printf 'auth    required        pam_unix.so\n'
      printf 'account required        pam_unix.so\n'
    } > /etc/pam.d/dovecot
  fi

  {
    printf 'hosts = %s\n' "${FREEIPA_FQDN}"
    printf 'tls = yes\n'
    printf 'tls_ca_cert_file = /etc/ipa/ca.crt\n'
    printf 'dn = uid=mail,cn=sysaccounts,cn=etc,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'dnpass = %s\n' "${INSTALL_MAIL_LDAP_PASSWORD}"
    # Validate the user's own password via a bind as their own DN — FreeIPA
    # locks down userPassword reads, so this is the supported check method
    printf 'auth_bind = yes\n'
    printf 'auth_bind_userdn = uid=%%n,cn=users,cn=accounts,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'ldap_version = 3\n'
    printf 'base = cn=users,cn=accounts,%s\n' "${INSTALL_LDAP_BASE_DN}"
    printf 'scope = subtree\n'
    printf 'user_filter = (&(objectClass=posixAccount)(uid=%%n))\n'
    printf 'pass_filter = (&(objectClass=posixAccount)(uid=%%n))\n'
    printf 'user_attrs = =home=%s/%s/%%n,=uid=%s,=gid=%s\n' \
      "${FREEIPA_MAIL_BASE_DIR}" "${FREEIPA_MAIL_DOMAIN}" "${FREEIPA_MAIL_VID}" "${FREEIPA_MAIL_VID}"
  } > /etc/dovecot/dovecot-ldap.conf.ext
  \chown root:dovecot /etc/dovecot/dovecot-ldap.conf.ext
  \chmod 640 /etc/dovecot/dovecot-ldap.conf.ext

  local auth_mechanisms="plain login"
  local passdb_blocks userdb_blocks
  # Command substitution strips trailing newlines, so each block ends with an
  # explicit newline appended outside $(...) — otherwise concatenated blocks
  # glue together onto one line and dovecot.conf fails to parse
  passdb_blocks="$(printf 'passdb {\n  driver = ldap\n  args = /etc/dovecot/dovecot-ldap.conf.ext\n  mechanisms = plain login\n}')"$'\n'
  userdb_blocks="$(printf 'userdb {\n  driver = ldap\n  args = /etc/dovecot/dovecot-ldap.conf.ext\n}')"$'\n'

  # Local Unix fallback — tried only when LDAP reports the user as unknown,
  # so FreeIPA-directory users always authenticate via LDAP first
  if [[ "${FREEIPA_MAIL_LOCAL_FALLBACK}" == "true" ]]; then
    passdb_blocks+="$(printf 'passdb {\n  driver = pam\n  args = dovecot\n  mechanisms = plain login\n}')"$'\n'
    userdb_blocks+="$(printf 'userdb {\n  driver = passwd\n  override_fields = mail=maildir:~/Maildir\n}')"$'\n'
  fi

  # Keycloak OAuth2 token introspection — scoped to oauthbearer/xoauth2 only,
  # so plain/login clients keep going through LDAP (and local) above
  if [[ "${FREEIPA_MAIL_KEYCLOAK_AUTH}" == "true" ]]; then
    auth_mechanisms+=" oauthbearer xoauth2"
    {
      printf 'introspection_url = http://172.17.0.1:%s/realms/%s/protocol/openid-connect/token/introspect\n' \
        "${FREEIPA_KEYCLOAK_PORT}" "${FREEIPA_KEYCLOAK_REALM}"
      printf 'introspection_mode = post\n'
      printf 'client_id = %s\n' "${FREEIPA_MAIL_KEYCLOAK_CLIENT_ID}"
      printf 'client_secret = %s\n' "${INSTALL_MAIL_KEYCLOAK_SECRET}"
      # 'email' not 'preferred_username': every other passdb (LDAP, PAM) and
      # this stack's documented login convention use the full user@domain
      # address. Keycloak's preferred_username claim has no domain, so
      # matching on it would reject a full-email SASL login. Verified:
      # a full-email XOAUTH2 login succeeds with email, fails with
      # preferred_username.
      printf 'username_attribute = email\n'
      printf 'active_attribute = active\n'
      printf 'active_value = true\n'
    } > /etc/dovecot/dovecot-oauth2.conf.ext
    \chown root:dovecot /etc/dovecot/dovecot-oauth2.conf.ext
    \chmod 640 /etc/dovecot/dovecot-oauth2.conf.ext

    # On an SELinux-enforcing host dovecot_auth_t may not connect to the
    # Keycloak port (introspection then fails with "Permission denied" and
    # every OAUTHBEARER/XOAUTH2 login is a temporary failure). Label the port
    # http_port_t and allow that one connection with a small local policy module.
    if \command -v getenforce >/dev/null 2>&1 && [[ "$(\getenforce 2>/dev/null)" != "Disabled" ]]; then
      __allow_dovecot_keycloak_selinux
    fi

    passdb_blocks+="$(printf 'passdb {\n  driver = oauth2\n  mechanisms = xoauth2 oauthbearer\n  args = /etc/dovecot/dovecot-oauth2.conf.ext\n}')"$'\n'
  fi

  local marker_begin="# --- scriptmgr-freeipa mail block (begin) ---"
  local marker_end="# --- scriptmgr-freeipa mail block (end) ---"

  \sed -i "/^${marker_begin}\$/,/^${marker_end}\$/d" /etc/dovecot/dovecot.conf

  {
    printf '%s\n' "${marker_begin}"
    printf 'mail_location = maildir:%s/%%d/%%n\n' "${FREEIPA_MAIL_BASE_DIR}"
    printf 'disable_plaintext_auth = yes\n'
    printf 'auth_mechanisms = %s\n' "${auth_mechanisms}"
    printf '%s' "${passdb_blocks}"
    printf '%s' "${userdb_blocks}"
    printf 'ssl = required\n'
    printf 'ssl_cert = <%s\n' "${INSTALL_MAIL_CERT_PATH}"
    printf 'ssl_key = <%s\n' "${INSTALL_MAIL_KEY_PATH}"
    printf 'protocols = imap pop3 lmtp\n'
    printf 'service lmtp {\n  unix_listener /var/spool/postfix/private/dovecot-lmtp {\n    mode = 0600\n    user = postfix\n    group = postfix\n  }\n}\n'
    printf 'service auth {\n  unix_listener /var/spool/postfix/private/auth {\n    mode = 0666\n    user = postfix\n    group = postfix\n  }\n}\n'
    printf '%s\n' "${marker_end}"
  } >> /etc/dovecot/dovecot.conf

  \systemctl enable dovecot
  \systemctl restart dovecot

  __log "Dovecot configured"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Summary ─────────────────────────────────────────────────────────────────

__display_summary() {
  local primary_ip
  primary_ip="$(__primary_ip)"

  __log "FreeIPA + Keycloak Installation Summary"
  printf '==========================================\n'
  printf 'Hostname:                  %s\n' "${FREEIPA_FQDN}"
  printf 'Domain:                    %s\n' "${FREEIPA_DOMAIN}"
  printf 'Realm:                     %s\n' "${FREEIPA_REALM}"
  printf 'Web ports:                 HTTP 80 → HTTPS 443\n'
  printf 'Admin username:            admin\n'
  printf 'Admin password:            (saved to %s)\n' "${FREEIPA_CRED_FILE}"
  printf 'Directory Manager pass:    (saved to %s)\n' "${FREEIPA_CRED_FILE}"
  if [[ "${INSTALL_DNS}" == "true" ]]; then
    printf 'Integrated DNS:            Yes\n'
  else
    printf 'Integrated DNS:            No\n'
  fi
  if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
    printf 'SSL Certificate:           Let'"'"'s Encrypt\n'
    printf 'Certificate path:          %s\n' "${INSTALL_CERT_PATH}"
    printf 'Auto-renewal:              Configured\n'
  elif [[ "${INSTALL_USE_FREEIPA_CA}" == "true" ]]; then
    printf 'SSL Certificate:           FreeIPA built-in CA\n'
  elif [[ "${INSTALL_USE_SELFSIGNED}" == "true" ]]; then
    printf 'SSL Certificate:           Self-signed\n'
  else
    printf 'SSL Certificate:           Manual configuration required\n'
  fi
  printf '==========================================\n\n'

  printf 'Access FreeIPA:\n'
  printf '  HTTP:  http://%s/ipa/ui (redirects to HTTPS)\n' "${FREEIPA_FQDN}"
  printf '  HTTPS: https://%s/ipa/ui\n\n' "${FREEIPA_FQDN}"

  printf 'Service management:\n'
  printf '  ipactl status    — check all services\n'
  printf '  ipactl start     — start all services\n'
  printf '  ipactl stop      — stop all services\n'
  printf '  ipactl restart   — restart all services\n\n'

  printf 'Next steps:\n'
  printf '  1. Access the admin interface and complete initial setup\n'
  printf '  2. Retrieve admin and Directory Manager passwords from %s\n' "${FREEIPA_CRED_FILE}"
  if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
    printf '  3. Let'"'"'s Encrypt certificates will auto-renew via the installed hook\n'
  fi

  if [[ "${INSTALL_DNS}" == "true" ]]; then
    printf '\nDNS configuration:\n'
    printf '  Set nameserver to: %s\n' "${primary_ip}"
    printf '  Test DNS: dig %s @%s\n' "${FREEIPA_FQDN}" "${primary_ip}"
  fi

  printf 'Kerberos:\n'
  printf '  kinit admin   — get Kerberos ticket for admin\n'
  printf '  klist         — list active tickets\n'
  printf '  kdestroy      — destroy tickets\n\n'

  printf 'Important files:\n'
  printf '  /etc/ipa/default.conf             — IPA configuration\n'
  printf '  /var/log/ipaserver-install.log    — installation log\n'
  printf '  /var/log/httpd/                   — web server logs\n'
  printf '  /var/log/dirsrv/                  — directory server logs\n'
  printf '  %s        — generated credentials\n' "${FREEIPA_CRED_FILE}"

  printf '\nKeycloak SSO:\n'
  printf '  Via Apache:     https://%s/kc\n' "${FREEIPA_FQDN}"
  printf '  Direct (internal): http://172.17.0.1:%s\n' "${FREEIPA_KEYCLOAK_PORT}"
  printf '  Admin user:     admin (Keycloak master realm)\n'
  printf '  Admin pass:     (saved to %s)\n' "${FREEIPA_CRED_FILE}"
  printf '  Realm:          %s\n' "${FREEIPA_KEYCLOAK_REALM}"
  printf '  LDAP sync:      FreeIPA → Keycloak federation active\n'
  printf '  Kerberos SPNEGO: HTTP/%s@%s\n' "${FREEIPA_FQDN}" "${FREEIPA_REALM}"
  printf '  Docker compose: %s/docker-compose.yml\n' "${FREEIPA_COMPOSE_DIR}"
  printf '  Credentials:    %s\n' "${FREEIPA_CRED_FILE}"

  printf '\nMail (Postfix/Dovecot):\n'
  printf '  Domain:           %s (and *.%s)\n' "${FREEIPA_MAIL_DOMAIN}" "${FREEIPA_MAIL_DOMAIN}"
  printf '  SMTP (STARTTLS):  %s:587\n' "${FREEIPA_FQDN}"
  printf '  SMTPS:            %s:465\n' "${FREEIPA_FQDN}"
  printf '  IMAP (TLS):       %s:993\n' "${FREEIPA_FQDN}"
  printf '  POP3 (TLS):       %s:995\n' "${FREEIPA_FQDN}"
  printf '  Auth (LDAP):      FreeIPA LDAP bind — any posixAccount user with a mail attribute\n'
  if [[ "${FREEIPA_MAIL_LOCAL_FALLBACK}" == "true" ]]; then
    printf '  Auth (local):     Unix/PAM fallback for non-LDAP accounts (plain/login only)\n'
  fi
  if [[ "${FREEIPA_MAIL_KEYCLOAK_AUTH}" == "true" ]]; then
    printf '  Auth (Keycloak):  OAUTHBEARER/XOAUTH2 via token introspection (IMAP/POP3 only)\n'
  fi
  printf '  Mailbox storage:  %s/%s/<uid>\n' "${FREEIPA_MAIL_BASE_DIR}" "${FREEIPA_MAIL_DOMAIN}"
  if [[ "${INSTALL_USE_LETSENCRYPT}" == "true" ]]; then
    printf '  TLS certificate:  Let'"'"'s Encrypt (refreshed by the certbot renewal hook)\n'
  else
    printf '  TLS certificate:  FreeIPA-issued, tracked by certmonger (auto-renews)\n'
  fi
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Argument parsing ─────────────────────────────────────────────────────────

__parse_args() {
  local _opts
  _opts="$(getopt -o hv -l help,version,debug,color,no-color,no-ntp -n "${APPNAME}" -- "$@")" || { __help; exit 2; }
  eval set -- "${_opts}"
  while true; do
    case "$1" in
      -h|--help)
        __help
        exit 0
        ;;
      -v|--version)
        __version
        exit 0
        ;;
      --debug)
        FREEIPA_DEBUG=1
        shift
        ;;
      --no-ntp)
        INSTALL_NO_NTP="true"
        shift
        ;;
      --color)
        unset NO_COLOR
        INSTALL_COLOR_RED='\e[0;31m'
        INSTALL_COLOR_GREEN='\e[0;32m'
        INSTALL_COLOR_YELLOW='\e[1;33m'
        INSTALL_COLOR_BLUE='\e[0;34m'
        INSTALL_COLOR_RESET='\e[0m'
        shift
        ;;
      --no-color)
        NO_COLOR=1
        INSTALL_COLOR_RED=""
        INSTALL_COLOR_GREEN=""
        INSTALL_COLOR_YELLOW=""
        INSTALL_COLOR_BLUE=""
        INSTALL_COLOR_RESET=""
        shift
        ;;
      --)
        shift
        break
        ;;
      *)
        break
        ;;
    esac
  done
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# ─── Main ────────────────────────────────────────────────────────────────────

# The host's default credential cache may be unusable: krb5.conf.d/kcm_default_ccache selects KCM:, and a
# bootstrap that disables sssd-kcm.socket makes every kinit/klist/ipa fail with "No KCM server found". All
# Kerberos work in this script goes through a private file cache instead.
__use_private_ccache() {
  INSTALL_CCACHE_DIR="$(\mktemp -d /run/freeipa-install.XXXXXX 2>/dev/null || \mktemp -d)"
  export KRB5CCNAME="FILE:${INSTALL_CCACHE_DIR}/krb5cc"
}

# The install runs for many minutes and is often started over SSH. If that terminal goes away, SIGHUP would
# kill it half way through ipa-server-install. Ignore SIGHUP (inherited by everything started from here) and
# route output through a relay that keeps draining after the terminal is gone, so writes never fail with
# EIO/EPIPE under set -e. Nothing is written to a log file: the summary prints credentials.
__survive_hangup() {
  trap '' HUP
  exec > >(\cat; \cat >/dev/null) 2>&1
}

__main() {
  __parse_args "$@"

  __survive_hangup
  __use_private_ccache

  __log "Starting Full FreeIPA + Keycloak SSO installation"

  __check_root
  __detect_distro
  __detect_domain
  __check_requirements
  __preflight_freeipa_state

  __migrate_legacy_credential_file "${FREEIPA_CRED_FILE}"
  __migrate_legacy_credential_keys "${FREEIPA_CRED_FILE}"

  # A caller-supplied FREEIPA_KEYCLOAK_PORT wins over its saved credential.
  if [[ -z "${FREEIPA_KEYCLOAK_PORT}" ]]; then
    FREEIPA_KEYCLOAK_PORT="$(__load_credential "${FREEIPA_CRED_FILE}" FREEIPA_KEYCLOAK_PORT)" || {
      FREEIPA_KEYCLOAK_PORT="$(__random_port)"
      __save_credential "${FREEIPA_CRED_FILE}" FREEIPA_KEYCLOAK_PORT "${FREEIPA_KEYCLOAK_PORT}"
    }
  fi
  __log "Selected Keycloak port: ${FREEIPA_KEYCLOAK_PORT}"
  __debug "Credentials file: ${FREEIPA_CRED_FILE}; compose dir: ${FREEIPA_COMPOSE_DIR}"

  __disable_nginx_service
  __install_prerequisites
  __configure_hosts
  __install_packages
  __configure_ntp_settings
  __configure_ssl_certs
  __configure_dns_settings
  __fix_httpd_ports
  __install_freeipa
  __configure_freeipa_http
  __derive_ldap_base_dn
  __setup_freeipa_for_keycloak
  __install_keycloak_docker
  __wait_for_keycloak
  __configure_keycloak
  __configure_apache_keycloak_proxy
  __configure_ad_trust
  __create_initial_objects
  __install_mail_packages
  __setup_freeipa_for_mail
  __configure_keycloak_mail_client
  __create_mail_storage
  __configure_postfix
  __configure_dovecot
  __display_summary

  __log "FreeIPA + Keycloak installation and configuration completed"
  __log "Access the web interface over HTTPS on port 443"
}

# - - - - - - - - - - - - - - - - - - - - - - - - -

# Run main only when executed directly (not sourced)
if [[ "${BASH_SOURCE[0]:-${0}}" == "${0}" ]]; then
  __main "$@"
fi

# ex: ts=2 sw=2 et filetype=sh