install-homeserver.conf.example

# Answer file for scripts/install-homeserver.sh — the Linux-side
# equivalent of a Windows autounattend.xml: fill this in once, then the
# installer runs unattended and non-interactively from it.
#
# Copy this file, fill in every <PLACEHOLDER>, then run:
#   sudo ./scripts/install-homeserver.sh --config /path/to/your-filled-in.conf
#
# Put the filled-in copy at /etc/apiary/install-home.conf and
# `sudo ./scripts/install.sh --profile home` finds it without --config. It holds
# real keys and hostnames -- keep it out of version control wherever it lives.
#
# Never commit your filled-in copy. It will contain real IPs and a real
# git remote. Keep it next to the script but outside version control
# (.gitignore has a name-specific rule for this file — only the
# `.example` copy is tracked).

# --- Identity -----------------------------------------------------------
# Hostname this box should have. Leave empty to keep whatever's already set.
INSTALL_HOSTNAME="<HOSTNAME>"

# --- Repository -----------------------------------------------------------
# Where to clone APIARY from, and which ref to check out.
GIT_REPO_URL="<GIT_REMOTE_URL>"          # e.g. git@github.com:<org>/apiary.git
GIT_REF="main"

# #1019: Xore/auth-backend, checked out separately for its presentation-only
# themes/apiary/ (the Keycloak login theme) -- .github/workflows/deploy.yml's
# CI path does the equivalent with a second `actions/checkout`; this is
# install-homeserver.sh's from-scratch-install equivalent.
AUTH_THEME_REPO_URL="<GIT_REMOTE_URL>"   # e.g. git@github.com:<org>/auth-backend.git

# Public base domain the honeypot's own hostnames hang off (auth.<domain>,
# arcane.<domain>, dashboard.<domain>, ...). #1504: step_arcane_install
# derives Arcane's APP_URL (https://arcane.<domain>) and OIDC issuer
# (https://auth.<domain>/realms/apiary) from this for the honeypot-arcane
# .env it generates. Use the SAME value as honeypot-keycloak's
# KEYCLOAK_PUBLIC_DOMAIN.
#
# This is the BASE domain, NOT a service hostname. Set "example.com", never
# "auth.example.com" -- the installer prefixes the service label itself, so the
# latter yields arcane.auth.example.com and issuer auth.auth.example.com. Both
# are second-level subdomains, which a *.example.com wildcard certificate does
# not cover (it matches exactly one label). The 2026-09-03 rebuild was
# configured this way and the failure only surfaced later as OIDC discovery
# errors; the installer now rejects a value starting with a known service
# label, but the value still has to be right for labels it cannot guess.
KEYCLOAK_PUBLIC_DOMAIN="<KEYCLOAK_PUBLIC_DOMAIN>"   # e.g. honeypot.example (NOT auth.honeypot.example)

# #1502: Arcane manages the 32 honeypot-* stacks via directory-aware Git
# sync now, driven by arcane/manifests/home-production.json -- these two
# values authenticate step_arcane_import_stacks against this host's own
# Arcane instance. ARCANE_API_TOKEN can't be generated by this script
# itself: mint it by hand in Arcane's own UI (Settings -> API Keys) after
# logging in once, then paste it here. #1504: step_arcane_install now stands
# Arcane itself up from docker-compose.arcane.yml before the import step, so
# a from-scratch host no longer needs Arcane installed by hand first -- but
# it IS still a two-pass run: the first pass lands Arcane + Keycloak, then
# you log in once, mint the token, fill it in below, and re-run. See
# ARCANE_URL/ARCANE_API_TOKEN's own comment in install-homeserver.sh.
ARCANE_URL="<ARCANE_URL>"                # e.g. http://10.8.0.2:3552
ARCANE_API_TOKEN="<ARCANE_API_TOKEN>"

# Where the repo checkout used by Dockge should live. The basename MUST be
# "apiary" -- every split stack's compose file (citrix-honeypot, conpot,
# honeypot-keycloak, ...) hardcodes absolute /opt/stacks/apiary/... paths,
# and step_clone_repo symlinks /opt/stacks -> dirname(REPO_DIR), so
# /opt/stacks/apiary only resolves to the real checkout when REPO_DIR's
# last path segment is literally "apiary" (a stale "honeypot-stack" here,
# from before the repo's rename to APIARY, silently breaks every one of
# those stacks' builds on a fresh install).
REPO_DIR="/var/dockge/stacks/apiary"

# --- Networking (WireGuard tunnel to the VPS) ----------------------------
# This box's address on the WireGuard tunnel. Honeypot sensors bind only
# this address — see HP_BIND in the compose files. Never 0.0.0.0.
HOME_WG_ADDRESS="<HOME_WG_ADDRESS>/24"   # e.g. 10.8.0.2/24

# The VPS's WireGuard address and public endpoint (its real internet-facing
# IP or hostname, plus the WireGuard UDP port it listens on).
VPS_WG_ADDRESS="<VPS_WG_ADDRESS>"        # e.g. 10.8.0.1
VPS_WG_ENDPOINT="<VPS_PUBLIC_IP_OR_HOST>:<VPS_WG_PORT>"

# WireGuard keys. Generate with `wg genkey | tee privatekey | wg pubkey >
# publickey` — never reuse an example value, never commit a real one.
# HOME_WG_PRIVATE_KEY and HOME_WG_PRESHARED_KEY may both be left empty --
# the script generates fresh ones and pushes them to the VPS automatically.
# Leave them empty on a first-ever run; once the tunnel is up, fill in the
# real values from the resulting /etc/wireguard/wg0.conf so future re-runs
# reuse the same identity instead of rotating it every time (harmless but
# unnecessary churn on the VPS's peer config).
#
# #518 incident: an earlier version of this script only handled the private
# key, not the preshared key. The VPS's peer required a PSK (predating this
# script). Every run produced a wg0.conf that looked fine (`wg show`
# displayed the interface) but never completed a handshake -- 0 bytes
# received, forever, completely silently, because the verify step only
# checked the interface existed. Real attacker traffic never reached the
# honeypot sensors for the rest of that session. Both the missing PSK
# handling and the weak verify check are fixed now, but this is exactly the
# kind of failure that looks like success at a glance -- if you ever see
# "wireguard-verify OK" followed by no honeypot traffic, check
# `wg show wg0` for `latest handshake` and `transfer ... received`, not
# just that the interface exists.
HOME_WG_PRIVATE_KEY="<HOME_WG_PRIVATE_KEY>"
HOME_WG_PRESHARED_KEY="<HOME_WG_PRESHARED_KEY>"
VPS_WG_PUBLIC_KEY="<VPS_WG_PUBLIC_KEY>"

# --- VPS admin access (for the parts of setup that touch the VPS side) --
VPS_SSH_HOST="<VPS_PUBLIC_IP_OR_HOST>"
VPS_SSH_PORT="<VPS_SSH_PORT>"
VPS_SSH_USER="<VPS_SSH_USER>"
VPS_SSH_KEY="<PATH_TO_PRIVATE_KEY>"      # e.g. /home/<user>/.ssh/vps_key

# --- GPU / LLM / ML worker ------------------------------------------------
# Set to "false" on a box with no NVIDIA GPU to skip driver/toolkit/Ollama
# setup entirely rather than fail partway through.
ENABLE_GPU_STACK="true"

# --- Timezone / locale ----------------------------------------------------
INSTALL_TIMEZONE="<TIMEZONE>"            # e.g. Europe/Berlin

# --- Secret restore (LAN backup host) --------------------------------------
# Where the pre-rebuild .env backup lives (see #518's backup-blocker pass).
# BACKUP_HOST_PATH is the directory containing one subfolder per Dockge
# stack, each holding that stack's .env (e.g. <path>/honeypot-cowrie/.env).
BACKUP_HOST="<BACKUP_HOST_IP_OR_HOST>"
BACKUP_HOST_USER="<BACKUP_HOST_SSH_USER>"
BACKUP_HOST_KEY="<PATH_TO_PRIVATE_KEY>"  # e.g. /home/<user>/.ssh/backup_host_key
BACKUP_HOST_PATH="<PATH_ON_BACKUP_HOST>" # e.g. /home/<user>/honeypot-backups/<date>/home-env

# --- Pihole (reconstructed; not part of this repo) -------------------------
# Pihole is real home-LAN DNS infra, not a honeypot component -- it must NOT
# bind 0.0.0.0 or the honeypot sensors' WireGuard IP (HOME_WG_ADDRESS above),
# since hp-dns-honeypot already owns port 53/udp there and a wildcard bind
# collides with it (confirmed live, #518). Pick the actual home-LAN-facing
# interface IP on this box -- if it has more than one LAN interface, use the
# one you want the DNS server actually serving, not whichever the default route
# happens to prefer.
TECHNITIUM_LAN_IP="<HOME_LAN_IP>"         # e.g. 192.168.1.10

# Optional. Set if this fleet has a second, externally-managed Technitium
# node (e.g. a workstation running its own instance) that is the PRIMARY --
# the master where zones are actually edited, with the node this script
# provisions running as its secondary. The host resolver order (#2974) is
# built primary-first, so this is listed ahead of TECHNITIUM_LAN_IP. Leave
# unset if there is only the one node this script provisions.
TECHNITIUM_PRIMARY_IP=""                  # e.g. 192.168.1.5

# Optional, and off by default. Comma-separated public resolvers to append
# AFTER the Technitium nodes in the host resolver order (#2974). Only set
# this if outbound port 53 to the internet actually works on this network:
# where it is blocked (this fleet's LAN, confirmed live 2026-09-05) a public
# entry is not a fallback, it is a full resolver timeout charged to every
# lookup that has to reach past Technitium.
HOST_RESOLVER_PUBLIC_FALLBACK=""          # e.g. 1.1.1.1,8.8.8.8

# --- Sandbox VM restore (GHOSTS + Windows detonation) ----------------------
# Optional and gated separately from everything above: this is a 170G+
# transfer (golden images, ISOs, VM disks) and a genuinely separate
# subsystem (KVM/libvirt, not Docker). Set to "false" to skip it entirely.
ENABLE_SANDBOX_RESTORE="false"
# Only needed if ENABLE_SANDBOX_RESTORE=true. Same backup host as
# BACKUP_HOST above, different subdirectory -- the one holding golden-images/,
# isos/, vms/, etc. (e.g. <path>/home-sandbox).
#
# Prefix with "local:" to restore from a directory on THIS host instead of
# over SSH, e.g.
#   BACKUP_HOST_SANDBOX_PATH="local:/mnt/usb-recovery/apiary-backups/sandbox-<stamp>"
# which is the right answer whenever the backup drive holding the golden
# images is attached to the machine being rebuilt -- 66G over the LAN and back
# to the same box buys nothing. The step fails loudly if the local path does
# not exist, because an unmounted mountpoint would otherwise "restore" an
# empty tree without complaint.
BACKUP_HOST_SANDBOX_PATH="<PATH_ON_BACKUP_HOST>"

# --- Windows sandbox GPU passthrough (#1609 Phase 7) ----------------------
# vendor:device IDs of the discrete GPU handed to the Windows detonation
# domain, comma-separated, INCLUDING its HDMI-audio function -- both functions
# of the card have to move together or the IOMMU group is split. Read them off
# `lspci -nn`, e.g. a card shown as
#     17:00.0 VGA compatible controller [0300]: ... [10de:1c31]
#     17:00.1 Audio device [0403]: ...             [10de:10f1]
# gives VFIO_PASSTHROUGH_PCI_IDS="10de:1c31,10de:10f1".
#
# Leave EMPTY to skip passthrough entirely; step_vfio_gpu_passthrough is a
# no-op then. This is deliberately not auto-detected: on a host with more than
# one GPU, picking the wrong one takes it away from the host. The step refuses
# outright if the IDs match the boot VGA, and requires a reboot to take effect.
#
# Note this also enables IOMMU if it is not already active. Do not assume it
# is: the 2026-09-03 Rocky rebuild came up with zero IOMMU groups on hardware
# that had 87 of them under the previous OS.
VFIO_PASSTHROUGH_PCI_IDS=""