Add PA-VM shutdown script, reading the API key from conf/

stop-pa-vm.service calls the PAN-OS XML API on host shutdown so the firewall
VM goes down cleanly rather than being killed.

The API key is read from conf/pa-vm.conf, resolved relative to the script.
See conf/pa-vm.conf.example.

Pass the request through curl --config on stdin with the key in an X-PAN-KEY
header, instead of embedding it in the URL. A key in the query string is
visible in ps and would be recorded in any proxy or webserver log along the
path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

conf/pa-vm.conf.example

@@ -0,0 +1,17 @@
+# Credentials for pa-vm_api_stop.sh (PAN-OS XML API shutdown).
+#
+# Copy to conf/pa-vm.conf next to the scripts and lock it down:
+#   cp conf/pa-vm.conf.example conf/pa-vm.conf
+#   chmod 0600 conf/pa-vm.conf
+#
+# The script looks for it relative to its own location, so this works both in a
+# checkout and deployed at /opt/ergosteur. Override with PA_VM_CONFIG.
+#
+# Generate a key with:
+#   curl -k -X POST 'https://<host>/api/?type=keygen' \
+#        --data-urlencode 'user=<user>' --data-urlencode 'password=<password>'
+
+PA_VM_HOST=pa-vm
+
+# Passed as an X-PAN-KEY header via curl --config, so it stays out of argv.
+PA_VM_API_KEY=changeme

pa-vm_api_stop.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Gracefully shut down the PA-VM firewall through the PAN-OS XML API.
+# Invoked as ExecStop by stop-pa-vm.service so the firewall goes down cleanly on host shutdown.
+set -euo pipefail
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+CONFIG=${PA_VM_CONFIG:-$SCRIPT_DIR/conf/pa-vm.conf}
+
+if [[ ! -r "$CONFIG" ]]; then
+    echo "Error: cannot read $CONFIG" >&2
+    echo "Copy conf/pa-vm.conf.example there and fill in the API key." >&2
+    exit 1
+fi
+
+# shellcheck source=/dev/null
+. "$CONFIG"
+
+: "${PA_VM_HOST:?not set in $CONFIG}"
+: "${PA_VM_API_KEY:?not set in $CONFIG}"
+
+wall "Shutting down PA-VM via XML API"
+
+# --config - takes the request on stdin so the API key never reaches the process
+# table. --insecure is deliberate: the firewall serves a self-signed certificate.
+/usr/bin/curl --config - <<EOF
+url = "https://${PA_VM_HOST}/api/?type=op&cmd=<request><shutdown><system></system></shutdown></request>"
+header = "X-PAN-KEY: ${PA_VM_API_KEY}"
+insecure
+silent
+show-error
+fail
+EOF

systemd-system/stop-pa-vm.service

@@ -0,0 +1,10 @@
+[Unit]
+Description=Stop PA-VM via XML API
+
+[Service]
+Type=oneshot
+RemainAfterExit=true
+ExecStop=/opt/ergosteur/pa-vm_api_stop.sh
+
+[Install]
+WantedBy=multi-user.target