9.4 KiB
Proxmox automation
CT 102 Keycloak provisioning profile
The replacement Keycloak LXC uses CT 104 as its measured reference. CT 104 currently exposes 2 vCPUs, 4 GiB RAM, 1 GiB swap and a 12 GiB root filesystem; the complete running stack uses about 626 MiB RAM and 2.6 GiB disk. CT 102 is therefore provisioned with the same CPU and memory allocation but a moderately larger root disk for parallel image versions, package updates and Ansible staging:
| Setting | CT 102 value |
|---|---|
| CT ID / hostname | 102 / keycloak |
| OS | Debian 13, amd64 |
| Container type | unprivileged LXC with nesting enabled |
| CPU | 2 cores |
| Memory | 4096 MiB |
| Swap | 1024 MiB |
| Root disk | 16 GiB, thin-provisioned LXC storage |
| Network | vmbr0, 10.0.0.4/24, gateway 10.0.0.1, IPv6 disabled |
| Boot / protection | start on boot, protection enabled after creation |
| Time zone | Europe/Berlin |
| Initial root SSH | not required; the hook installs and hardens OpenSSH |
| Post-install hook | /usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh |
The Community Scripts Podman helper does not currently expose a swap variable,
so the reviewed launcher sets pct set 102 --swap 1024 after successful
creation and then verifies the complete PVE configuration. The 2026-10-12 PVE
preflight established local as the active template storage and local-lvm as
the active thin-provisioned container storage, with sufficient free capacity.
The website-generated launcher is stored as provision-ct102-keycloak.sh, not
as the ambiguous install.sh. It contains no password or private key. It pins
the Community Scripts ProxmoxVE and core repositories to the revisions
audited on 2026-10-12, verifies the downloaded Podman entry script, names every
material CT setting explicitly, and rejects an occupied CT ID instead of
silently allowing the helper to choose another one.
Before running it, install the two hooks documented below on the PVE host and verify that CT 102 no longer exists. Then execute the reviewed host copy as root:
/usr/local/sbin/provision-ct102-keycloak.sh
The launcher deliberately does not delete or replace an existing container.
After Community Scripts returns, it configures 1024 MiB swap and treats the
otherwise non-fatal post-install hook result as mandatory: the PVE profile,
Debian release, Podman installation, SSH service, account UIDs and unattended
ansible-deploy sudo path must all pass before the launcher reports success.
The reviewed launcher copy has SHA-256
5105ff39bbbf6959a91fc2e5bda67cbf3bcf3eacdae4dcac5d70f5d0a636bd6f.
ghostnet-lxc-baseline.sh
The versioned source now lives at
../../../shared/scripts/ghostnet-lxc-baseline.sh. This script is the optional Community Scripts
post-install hook. Install the reviewed version on the Proxmox host as:
/usr/local/sbin/ghostnet-lxc-baseline.sh
The host-side copy is owned by root:root with mode 0750. Verify its
SHA-256 against the reviewed repository copy before executing it.
The Community Scripts field must contain that absolute path. The hook runs as
root on the Proxmox host after the guest has been provisioned and started.
Community Scripts supplies CTID; for a controlled rerun the CT ID can also be
passed as the first argument:
/usr/local/sbin/ghostnet-lxc-baseline.sh 104
The script is deliberately limited. It:
- requires an existing, running, unprivileged Debian 12 or newer LXC;
- aborts before account creation if UID/GID 1000 or 1001 is assigned or owns files unexpectedly;
- installs
ca-certificates,openssh-serverandsudoonly when missing; it does not use the hook as a general package-upgrade mechanism; - creates or validates locked
ghost-agentUID/GID 1000 andghostUID/GID 1001 accounts; - grants only
ghostmembership insudo; - prepares protected, empty
authorized_keysfiles without truncating an existing file; - disables SSH socket activation, enables and restarts the classic SSH service, validates its syntax and reports the guest host-key fingerprint.
- removes only the known dangling
wtmpdb-rotate.timerenable link left by the Debian 13 package transition, and only when its target is absent and no installed package owns that target.
It intentionally does not install public or private keys, set passwords, change root authentication, write an SSH hardening drop-in, configure a firewall, alter application users, or install application workloads. Those steps remain host-specific and require positive and negative access tests.
The script is idempotent for an already compliant guest. Any identity or
numeric-owner mismatch stops the hook instead of guessing a replacement UID.
Community Scripts retains the created LXC if the hook fails and writes hook
output to /var/log/community-scripts/post-install-<CTID>.log on the Proxmox
host.
The current reviewed copy has SHA-256
111f1b70e47e3a2f6a1bcce22cb0ec50aacd8fbcff37d87fbcf853a318381b10.
An earlier copy with SHA-256
a0ee32a8fc2854c29a83b17b4e0cdb5ad55cde36de92d562f6bd890dc93ae89e
was installed on the Ghostnet Proxmox host and rerun against CT 104 on
2026-10-06. The convergence run performed no package transaction, preserved
both authorized-key files and passed the subsequent access and SSH-denial
tests.
ghostnet-keycloak-ansible-bootstrap-hook.sh
This is the CT-102-specific Community Scripts post-install hook for the reproducible Keycloak rebuild. It calls the generic baseline above and then establishes only the transport and privilege boundary needed by Ansible:
- it refuses any CT ID other than 102, any helper application other than
Podman, a hostname other than
keycloak, or a guest without10.0.0.4; - it creates or validates
ghost-agent1000:1000,ghost1001:1001 andansible-deploy1002:1002; - it installs the three role-specific public keys, limited to the documented
management networks; the embedded keys must remain identical to
../ansible/files/ssh/keycloak-{ghost-agent,ghost,ansible-deploy}.pub; - it keeps
ghost-agentandansible-deploypasswords locked, grants onlyansible-deployreviewedNOPASSWD: ALL, and leavesghoston Debian's password-gatedsudopolicy; - it disables SSH root/password authentication, empties the helper's temporary
root
authorized_keys, and validates SSH and sudo before returning success.
The hook does not configure nftables, Podman, PostgreSQL or Keycloak. Those states belong to the Ansible roles and their idempotence tests.
The reviewed repository copy currently has SHA-256
0e0499bc44834fdcc7d31814a8b2b4a2bed527fc8d4051e66d6cd92ac32b86c3.
Verify the PVE-host copy against it before selecting the hook.
Install both reviewed scripts on the PVE host before launching the helper:
install -o root -g root -m 0750 \
ghostnet-lxc-baseline.sh \
/usr/local/sbin/ghostnet-lxc-baseline.sh
install -o root -g root -m 0700 \
ghostnet-keycloak-ansible-bootstrap-hook.sh \
/usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh
In the Podman helper's advanced settings, set the post-install hook to the absolute PVE-host path:
/usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh
Do not put this CT-specific path in a global Community Scripts defaults file.
The helper executes it as PVE root after starting the new LXC and writes its
output to /var/log/community-scripts/post-install-102.log. A non-zero hook
exit is reported by the helper but does not roll back the already-created
container or make the helper remove it; inspect the log and the resulting
guest before any rerun.
The script deliberately cannot provision the personal ghost password. Set
it without exposing it in chat or shell history:
pct exec 102 -- passwd ghost
After the hook, independently verify the new SSH host-key fingerprint through the PVE console, replace the obsolete CT-102 known-hosts entry, test all three positive/negative access paths, and only then run the Ansible preflight.
prepare-keycloak-cutover-dump.sh
This PVE-root operator script starts the final write freeze and therefore
causes a deliberate Keycloak outage. It refuses to run unless CT 104, CT 102
and CT 103 are running, both PostgreSQL services are healthy, CT 102 remains
empty and gated, and both NPM Keycloak proxy hosts still target CT 104 at
10.0.0.16.
After the explicit confirmation it stops only the CT 104 Keycloak application,
leaves its PostgreSQL running, creates and catalogs a custom-format
pg_dump --no-owner --no-acl, records the non-secret schema/realm summary,
and transfers all root-only artifacts through PVE into CT 102. SHA-256 is
checked at the source, on PVE and at the destination. If any step fails before
the target transfer has been fully verified, the trap attempts to restart CT
104 Keycloak. On success CT 104 deliberately remains stopped to prevent new
writes during restore and cutover.
Install the reviewed script as root on PVE and invoke it only at the agreed outage window:
install -o root -g root -m 0700 \
prepare-keycloak-cutover-dump.sh \
/usr/local/sbin/prepare-keycloak-cutover-dump.sh
GHOSTNET_CUTOVER_CONFIRMATION=STOP_CT104_AND_PREPARE_FINAL_KEYCLOAK_DUMP \
/usr/local/sbin/prepare-keycloak-cutover-dump.sh
The final output supplies the CT 102 dump path and digest required by
../ansible/playbooks/restore.yml. Do not restart CT 104 or open the CT
102 application gate between these two steps.
The current reviewed script has SHA-256
7bc07d03230e208d28465e07bee16370d80293541eeea97f4f28e5d1b946a291.