OpenCHAMI · seantronsen · Jun 23, 2026 · Jun 23, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/openchami.spec b/openchami.spec
@@ -30,18 +30,18 @@ The quadlets, systemd units, and config files for the Open Composable, Heterogen
 # 1) Install config, unit, and script files
 mkdir -p %{buildroot}/etc/openchami/configs \
          %{buildroot}/etc/openchami/pg-init \
-         %{buildroot}/etc/containers/systemd \
-         %{buildroot}/etc/systemd/system \
+         %{buildroot}/usr/share/containers/systemd \
+         %{buildroot}/usr/lib/systemd/system \
          %{buildroot}/usr/bin \
          %{buildroot}/etc/profile.d \
          %{buildroot}/usr/libexec/openchami
 
 cp -r systemd/configs/*                 %{buildroot}/etc/openchami/configs/
-cp -r systemd/containers/*              %{buildroot}/etc/containers/systemd/
-cp -r systemd/volumes/*                 %{buildroot}/etc/containers/systemd/
-cp -r systemd/networks/*                %{buildroot}/etc/containers/systemd/
-cp -r systemd/targets/*                 %{buildroot}/etc/systemd/system/
-cp -r systemd/system/*                  %{buildroot}/etc/systemd/system/
+cp -r systemd/containers/*              %{buildroot}/usr/share/containers/systemd/
+cp -r systemd/volumes/*                 %{buildroot}/usr/share/containers/systemd/
+cp -r systemd/networks/*                %{buildroot}/usr/share/containers/systemd/
+cp -r systemd/targets/*                 %{buildroot}/usr/lib/systemd/system/
+cp -r systemd/system/*                  %{buildroot}/usr/lib/systemd/system/
 cp scripts/bootstrap_openchami.sh       %{buildroot}/usr/libexec/openchami/
 cp scripts/openchami-certificate-update %{buildroot}/usr/bin/
 cp scripts/openchami_profile.sh         %{buildroot}/etc/profile.d/openchami.sh
@@ -60,20 +60,28 @@ chmod 644 %{buildroot}/etc/openchami/configs/*
 %files
 %license LICENSE
 %config(noreplace) /etc/openchami/configs/*
-/etc/containers/systemd/*
-/etc/systemd/system/openchami.target
-/etc/systemd/system/openchami-cert-renewal.service
-/etc/systemd/system/openchami-cert-renewal.timer
-/etc/systemd/system/openchami-cert-trust.service
+/usr/share/containers/systemd/*
+/usr/lib/systemd/system/openchami.target
+/usr/lib/systemd/system/openchami-cert-renewal.service
+/usr/lib/systemd/system/openchami-cert-renewal.timer
+/usr/lib/systemd/system/openchami-cert-trust.service
 /usr/libexec/openchami/bootstrap_openchami.sh
 /usr/libexec/openchami/ohpc-nodes.sh
 /etc/profile.d/openchami.sh
 /etc/openchami/pg-init/multi-psql-db.sh
 /usr/bin/openchami-certificate-update
 
 %pre
+# NOTES:
+# 1. `coresmd` refers to the legacy implementation before the CoreDNS split.
+# 2. Releases now install Quadlets under the standard system-managed path,
+#    `/usr/share/containers/systemd`, instead of the admin-managed
+#    `/etc/containers/systemd`. This aligns with standard systemd override
+#    semantics and keeps local modifications separate from packaged files.
+# 3. This warning and these comments will remain until support for the legacy,
+#    non-fabrica services is dropped.
 if [ -f /etc/containers/systemd/coresmd.container ]; then
-	echo 'WARNING: /etc/containers/systemd/coresmd.container as been replaced by /etc/containers/systemd/coresmd-coredhcp.container.'
+	echo 'WARNING: /etc/containers/systemd/coresmd.container as been replaced by /usr/share/containers/systemd/coresmd-coredhcp.container.'
 	echo '         Migrate to coresmd-coredhcp to avoid any issues.'
 fi
 

diff --git a/scripts/bootstrap_openchami.sh b/scripts/bootstrap_openchami.sh
@@ -23,32 +23,6 @@ create_secret_if_not_exists() {
   fi
 }
 
-# Function to define system_name and system_domain in the environment file
-generate_environment_file() {
-  local short_name=$(hostname -s)
-  local dns_name=$(hostname -d)
-  local system_fqdn=$(hostname)
-
-  sed -i "s/^SYSTEM_NAME=.*/SYSTEM_NAME=${short_name}/" /etc/openchami/configs/openchami.env
-  sed -i "s/^SYSTEM_DOMAIN=.*/SYSTEM_DOMAIN=${dns_name}/" /etc/openchami/configs/openchami.env
-  sed -i "s/^SYSTEM_URL=.*/SYSTEM_URL=${system_fqdn}/" /etc/openchami/configs/openchami.env
-  sed -i "s|^URLS_SELF_ISSUER=.*|URLS_SELF_ISSUER=https://${system_fqdn}|" /etc/openchami/configs/openchami.env
-  sed -i "s|^URLS_SELF_PUBLIC=.*|URLS_SELF_PUBLIC=https://${system_fqdn}|" /etc/openchami/configs/openchami.env
-  sed -i "s|^URLS_LOGIN=.*|URLS_LOGIN=https://${system_fqdn}/login|" /etc/openchami/configs/openchami.env
-  sed -i "s|^URLS_CONSENT=.*|URLS_CONSENT=https://${system_fqdn}/consent|" /etc/openchami/configs/openchami.env
-  sed -i "s|^URLS_LOGOUT=.*|URLS_LOGOUT=https://${system_fqdn}/logout|" /etc/openchami/configs/openchami.env
-}
-
-acme_correction() {
-  local system_fqdn=$(hostname)
-  primary_ip=$(hostname -I | awk '{print $1}')
-  sed -i "s|-d .* \\\\|-d ${system_fqdn} \\\\|" /etc/containers/systemd/acme-deploy.container
-  sed -i "s/^ContainerName=.*/ContainerName=${system_fqdn}/" /etc/containers/systemd/acme-register.container
-  sed -i "s/^HostName=.*/HostName=${system_fqdn}/" /etc/containers/systemd/acme-register.container
-  sed -i "s|-d .* \\\\|-d ${system_fqdn} \\\\|" /etc/containers/systemd/acme-register.container
-  sed -i "s|--add-host='demo\.openchami\.cluster:[0-9\.]*'|--add-host='${system_fqdn}:${primary_ip}'|" /etc/containers/systemd/opaal.container
-}
-
 # Check and create secrets with random passwords if needed
 
 # Postgres Password
@@ -78,9 +52,3 @@ create_secret_if_not_exists "hydra_dsn" "$HYDRA_DSN"
 # POSTGRES_MULTIPLE_DATABASES
 POSTGRES_MULTIPLE_DATABASES="hmsds:smd-user:$(podman secret inspect smd_postgres_password --showsecret | jq -r '.[0].SecretData'),bssdb:bss-user:$(podman secret inspect bss_postgres_password --showsecret | jq -r '.[0].SecretData'),hydradb:hydra-user:$(podman secret inspect hydra_postgres_password --showsecret | jq -r '.[0].SecretData')"
 create_secret_if_not_exists "postgres_multiple_databases" "$POSTGRES_MULTIPLE_DATABASES"
-
-# openchami.env Configuration
-generate_environment_file
-
-# Correct the ACME files
-acme_correction
diff --git a/scripts/openchami-certificate-update b/scripts/openchami-certificate-update
@@ -1,30 +1,11 @@
-#!/bin/bash
+#!/usr/bin/bash
 
-update_dns() {
-    local system_fqdn=$1
-    local short_name="${system_fqdn%%.*}" 
-    local dns_name="${system_fqdn#*.}"
-    local primary_ip=$(hostname -I | awk '{print $1}')
-
-    # Update names in environment and acme containers
-    sed -i "s/^SYSTEM_NAME=.*/SYSTEM_NAME=${short_name}/" /etc/openchami/configs/openchami.env
-    sed -i "s/^SYSTEM_DOMAIN=.*/SYSTEM_DOMAIN=${dns_name}/" /etc/openchami/configs/openchami.env
-    sed -i "s/^SYSTEM_URL=.*/SYSTEM_URL=${system_fqdn}/" /etc/openchami/configs/openchami.env
-    sed -i "s|^URLS_SELF_ISSUER=.*|URLS_SELF_ISSUER=https://${system_fqdn}|" /etc/openchami/configs/openchami.env
-    sed -i "s|^URLS_SELF_PUBLIC=.*|URLS_SELF_PUBLIC=https://${system_fqdn}|" /etc/openchami/configs/openchami.env
-    sed -i "s|^URLS_LOGIN=.*|URLS_LOGIN=https://${system_fqdn}/login|" /etc/openchami/configs/openchami.env
-    sed -i "s|^URLS_CONSENT=.*|URLS_CONSENT=https://${system_fqdn}/consent|" /etc/openchami/configs/openchami.env
-    sed -i "s|^URLS_LOGOUT=.*|URLS_LOGOUT=https://${system_fqdn}/logout|" /etc/openchami/configs/openchami.env
-    sed -i "s|-d .* \\\\|-d ${system_fqdn} \\\\|" /etc/containers/systemd/acme-deploy.container
-    sed -i "s/^ContainerName=.*/ContainerName=${system_fqdn}/" /etc/containers/systemd/acme-register.container
-    sed -i "s/^HostName=.*/HostName=${system_fqdn}/" /etc/containers/systemd/acme-register.container
-    sed -i "s|-d .* \\\\|-d ${system_fqdn} \\\\|" /etc/containers/systemd/acme-register.container
-    sed -i "s|--add-host='.*|--add-host='${system_fqdn}:${primary_ip}'|" /etc/containers/systemd/opaal.container
-
-    # Reload systemD after .container changes
-    systemctl daemon-reload
+FILE_OVERRIDE_GLOBAL="/etc/containers/systemd/containers.d/99-openchami-site-override.conf"
+FILE_OVERRIDE_ACME_QUADLETS="/etc/containers/systemd/acme-.container.d/99-site-override.conf"
+FILE_OVERRIDE_ACME_REGISTER="/etc/containers/systemd/acme-register.container.d/99-site-override.conf"
 
-    echo "Changed FQDN to ${1}"
+notify_dns_change() {
+    echo "Changed FQDN to $1"
     echo 'Either restart all of the OpenCHAMI services:'
     echo
     echo '  sudo systemctl restart openchami.target'
@@ -35,28 +16,93 @@ update_dns() {
     echo
 }
 
+update_dns() {
+    local system_fqdn="$1"
+    local workfile
+
+    workfile="$(mktemp)"
+    trap 'rm -f "$workfile"' RETURN
+
+    echo "Updating local site-specific OpenCHAMI URL overrides..."
+    cat <<EOF > "${workfile}"
+# MANAGED BY '$0'
+[Container]
+Environment=URLS_SELF_ISSUER=https://${system_fqdn}
+Environment=URLS_SELF_PUBLIC=https://${system_fqdn}
+Environment=URLS_LOGIN=https://${system_fqdn}/login
+Environment=URLS_CONSENT=https://${system_fqdn}/consent
+Environment=URLS_LOGOUT=https://${system_fqdn}/logout
+Environment=BSS_IPXE_SERVER=${system_fqdn}
+EOF
+    install -D -m 0644 "${workfile}" "${FILE_OVERRIDE_GLOBAL}"
+
+    echo "Updating local site-specific OpenCHAMI ACME FQDN..."
+    cat <<EOF > "${workfile}"
+# MANAGED BY '$0'
+[Service]
+Environment=SYSTEM_FQDN=${system_fqdn}
+EOF
+    install -D -m 0644 "${workfile}" "${FILE_OVERRIDE_ACME_QUADLETS}"
+
+    cat <<EOF > "${workfile}"
+# MANAGED BY '$0'
+[Container]
+HostName=${system_fqdn}
+EOF
+    install -D -m 0644 "${workfile}" "${FILE_OVERRIDE_ACME_REGISTER}"
+}
+
+unset_dns() {
+    echo "Removing local site-specific OpenCHAMI overrides..."
+
+    local file
+    for file in \
+        "$FILE_OVERRIDE_GLOBAL" \
+        "$FILE_OVERRIDE_ACME_QUADLETS" \
+        "$FILE_OVERRIDE_ACME_REGISTER"
+    do
+        [ -e "$file" ] && rm -v "$file"
+    done
+}
+
 help_page() {
     echo "OpenCHAMI Certificate Update"
     echo "Update OpenCHAMI Certificates"
     echo "Usage: $0 update FQDN"
     echo
     echo "EXAMPLES:"
     echo "  $0 update demo.openchami.cluster"
-
 }
-case "$1" in 
+
+case "$1" in
     update)
         if [[ -z "$2" ]]; then
             help_page
         else
             if [[ $EUID -ne 0 ]]; then
-                echo "This script must be run as root" 
+                echo "This script must be run as root"
                 exit 1
             else
                 update_dns "$2"
+
+                # Reload SystemD after .container override changes
+                systemctl daemon-reload
+                notify_dns_change "$2"
             fi
         fi
         ;;
+    unset)
+        if [[ $EUID -ne 0 ]]; then
+            echo "This script must be run as root"
+            exit 1
+        else
+            unset_dns
+
+            # Reload SystemD after .container override changes
+            systemctl daemon-reload
+	    notify_dns_change "system hostname ($(hostnamectl hostname))"
+        fi
+        ;;
     *)
         help_page
         exit 1

diff --git a/systemd/configs/openchami.env b/systemd/configs/openchami.env
@@ -1,20 +1,12 @@
-# Environemnt Variables
-SYSTEM_NAME=demo
-SYSTEM_DOMAIN=openchami.cluster
+# openchami.env
+#
+# The environment variable definitions specified within this file can be
+# modified to customize the behavior of OpenCHAMI services.
 
-SYSTEM_URL=demo.openchami.cluster
-
-# Environemnt Variables
-URLS_SELF_ISSUER=https://${SYSTEM_URL}/
-URLS_SELF_PUBLIC=https://${SYSTEM_URL}/
-URLS_LOGIN=https://${SYSTEM_URL}/login
-URLS_CONSENT=https://${SYSTEM_URL}/consent
-URLS_LOGOUT=https://${SYSTEM_URL}/logout
-
-# Environemnt Variables
+# POSTGRESQL
 POSTGRES_USER=ochami
 
-# Environemnt Variables
+# BSS - Boot Script Service
 BSS_USESQL=true
 BSS_INSECURE=true
 BSS_DEBUG=true
@@ -25,18 +17,18 @@ BSS_DBUSER=bss-user
 BSS_JWKS_URL=http://opaal:3333/keys
 BSS_OAUTH2_ADMIN_BASE_URL=http://opaal:3333
 BSS_OAUTH2_PUBLIC_BASE_URL=http://opaal:3333
-BSS_IPXE_SERVER=${SYSTEM_URL}
+# BSS_IPXE_SERVER=%H
 BSS_CHAIN_PROTO=https
 
-# Environemnt Variables
+# SMD - State Management Database
 SMD_DBHOST=postgres
 SMD_DBPORT=5432
 SMD_DBNAME=hmsds
 SMD_DBUSER=smd-user
 SMD_DBOPTS=sslmode=disable
 SMD_JWKS_URL=http://opaal:3333/keys
 
-# Environemnt Variables
+# ACME - Smallstep - Automated Certificate Management Environment
 STEPPATH=/home/step
 DOCKER_STEPCA_INIT_NAME=OpenCHAMI
 DOCKER_STEPCA_INIT_DNS_NAMES=step-ca,step-ca.openchami.cluster
@@ -45,14 +37,38 @@ DOCKER_STEPCA_INIT_PASSWORD="supersecretpassword"
 DOCKER_STEPCA_INIT_PROVISIONER_NAME="Admin"
 DOCKER_STEPCA_INIT_PROVISIONER_PASSWORD="provisionerpassword"
 
-# Environemnt Variables
+# OPAAL - OIDC Provider Automated Authorization Login
 OPAAL_URL=http://opaal:3333
 HSM_URL=http://smd:27779
 ANSIBLE_HOST_KEY_CHECKING=False
 
-# Environemnt Variables for cloud-init
+# cloud-init-server
 LISTEN=:27777
 SMD_URL=http://smd:27779
 OPAAL_URL=http://opaal:3333
 JWKS_URL=http://opaal:3333/keys
 IMPERSONATION=true
+
+# global vars
+#
+# NOTE: The following variables are assigned dynamically using a systemd unit
+# override configuration file: /usr/share/containers/systemd/containers.d/10-openchami.conf
+#
+# '%H' expands to the system hostname and serves as a sane dynamic default. To
+# deviate from these default settings, run `openchami-certificate-update`
+# URLS_SELF_ISSUER=https://%H/
+# URLS_SELF_PUBLIC=https://%H/
+# URLS_LOGIN=https://%H/login
+# URLS_CONSENT=https://%H/consent
+# URLS_LOGOUT=https://%H/logout
+# BSS_IPXE_SERVER=%H
+
+# NOTE: If site-specific modifications were applied via
+# `openchami-certificate-update`, the value overrides can be found in
+# /etc/containers/systemd/containers.d/99-openchami-site-override.conf
+# URLS_SELF_ISSUER=https://%H/
+# URLS_SELF_PUBLIC=https://%H/
+# URLS_LOGIN=https://%H/login
+# URLS_CONSENT=https://%H/consent
+# URLS_LOGOUT=https://%H/logout
+# BSS_IPXE_SERVER=%H
diff --git a/systemd/containers/acme-deploy.container b/systemd/containers/acme-deploy.container
@@ -17,23 +17,43 @@ Volume=haproxy-certs:/etc/haproxy/certs/:z
 # Networks for the Container to use
 Network=openchami-cert-internal.network
 
+# Environment Variables
+EnvironmentFile=/etc/openchami/configs/openchami.env
+
 # haproxy deploy hook requires the directory to be specified in an environment variable
 Environment=DEPLOY_HAPROXY_PEM_PATH=/etc/haproxy/certs
 
-# Environment Variables
-EnvironmentFile=/etc/openchami/configs/openchami.env
+# NOTE: Do not modify this environment variable. It exists solely as a
+# placeholder to trigger systemd environment variable expansion.
+#
+# The [Container] Environment= directive only generates Podman's `-e` options;
+# it does not define a systemd environment variable. As a result, values
+# referenced by systemd (which may themselves contain systemd specifiers such
+# as %H) are not expanded as intended, and the variable must be defined twice:
+#
+#   1. Under [Service] so systemd can expand it while parsing the unit.
+#   2. Under [Container] so the container receives the final value as an
+#      environment variable.
+#
+# If you need to override this value, override the corresponding Environment=
+# entry in the [Service] section instead.
+Environment=SYSTEM_FQDN=${SYSTEMD_FQDN}
 
 # Command
 Exec=--deploy \
   --ca-bundle /root_ca/root_ca.crt \
   --server https://step-ca:9000/acme/acme/directory \
-  -d ${SYSTEM_URL} \
+  -d ${SYSTEM_FQDN} \
   --home /acme.sh \
   --standalone \
   --deploy-hook haproxy \
-  --force
+  --force'
 
 [Service]
 Restart=on-failure
 Type=oneshot
 RemainAfterExit=yes
+
+# OPTIONAL: OpenCHAMI site-specific overrides are managed in
+# /etc/containers/systemd/acme-deploy.service.d/99-site-override.conf
+Environment=SYSTEM_FQDN=%H