Skip to content

0023: A dedicated NAS deploy user that can only run the deploy ​

Note 2026-11-06: the git host and CI moved to GitHub (FEAW-Serv/getmy-books), ADR 0046. References below to the previous host are history; ADR 0046 says what replaces them.

Context ​

ADR 0019's pipeline deploy logs in to the NAS over SSH as rob, the owner's own account, which can run any command, including Docker (root-equivalent). A leaked pipeline key would hand over the NAS. The Product Owner's standing rule (2026-09-29): replace it with a dedicated deploy user, not in the docker group if that can be avoided, with a forced command in authorized_keys that only runs the deploy script, then remove the key from rob. Until that is done, deploy-nas skips with a warning (the NAS_DEPLOY_ENABLED repository variable), so main stays green.

Decision ​

Approved by the Product Owner on 2026-09-29, with two changes from the first draft: the deploy user unpacks the release and writes .env itself, into a folder it owns, and the root program takes no input at all; and root uses only a root-owned compose file installed from this repo, checked before every start.

  1. A deploy user on the NAS: a normal DSM user, not an administrator, not in the docker group, with its password field set to * so no password can ever match (not passwd -l, whose ! marks the account locked, which sshd may also apply to key logins), with a home folder for .ssh and the releases. Its login shell must be a real shell (/bin/sh), since DSM gives non-administrators /sbin/nologin and sshd runs the forced command through the login shell.

  2. A forced command on the key. The pipeline's new key is the only line in deploy's authorized_keys: restrict,from="<runner address>",command="/usr/local/bin/getmy-books-receive" ssh-ed25519 …. restrict turns off port, agent and X11 forwarding and the terminal; from= limits it to the runner; the client's own command is only read by the receive program, which accepts exactly deploy <40-hex commit>.

  3. getmy-books-receive, running as deploy (infra/nas/deploy/getmy-books-receive, installed root-owned at /usr/local/bin/, so deploy can run it but not change it):

    • reads one gzipped tar on standard input, at most 50 MB;
    • refuses anything but plain files and folders, absolute paths, paths with .., more than 20,000 entries or more than 300 MB unpacked;
    • unpacks into ~/getmy-books/releases/<commit>, owned by deploy, with infra/nas/.env mode 0600;
    • points ~/getmy-books/current at it, keeps the one before as previous for rollback, removes older releases;
    • then runs sudo -n /usr/local/sbin/getmy-books-up, and nothing else.
  4. getmy-books-up, the only root program (infra/nas/deploy/getmy-books-up, installed root-owned at /usr/local/sbin/): takes no input (no arguments, sudo resets the environment, standard input is closed). It:

    • uses only /usr/local/etc/getmy-books/docker-compose.yml, a root-owned copy of infra/nas/docker-compose.yml installed from this repo (-f), and refuses to start if that file isn't owned by root or is writable by anyone else;
    • resolves /var/services/homes/deploy/getmy-books/current, refusing anything that is not a release folder named by a full commit id, and uses it only as the build context and env file (--project-directory <release>/infra/nas, --env-file);
    • runs the compose check below on docker compose config (the file as Docker will run it, env applied), and refuses to start if it fails;
    • runs docker compose up -d --build --wait and checks /health reports that commit. The deploy account therefore supplies the code and the env file, but never what the containers are allowed to do. Amended 2026-11-03 (#79): the env file is an allow-list. Before any compose command reads it, getmy-books-up runs /usr/local/sbin/getmy-books-env-check on the release .env against /usr/local/etc/getmy-books/state/env-allowlist (root-owned, 0600, installed from infra/nas/deploy/env-allowlist, which holds exactly the names scripts/deploy-nas.sh sends). Every line must be NAME=value with the name on the list, set once; COMPOSE_* and DOCKER_* are refused even if listed, since COMPOSE_PROJECT_NAME would start a second project on an empty volume. up refuses if the allowlist is not root's. Only names are printed, never values. Inert until the owner installs the checker, the allowlist and the new up together; up without the allowlist refuses every deploy. 4a. The compose check (infra/nas/deploy/getmy-books-compose-check, installed root-owned at /usr/local/sbin/) refuses: privileged; host network, pid, ipc or user namespace; cap_add; devices; security_opt; volumes_from; any bind mount; any volume other than the app's data volume postgres-data; and driver_opts on a volume (a named volume can bind a host path that way). It prints only the reasons, never the config, which holds the resolved secrets. The host ipc, user namespace, security_opt and volumes_from refusals go slightly beyond the Product Owner's list, as the same kind of escape.

    Amended 2026-11-03 (#80, #77): an allow-list, not a deny-list. A deny-list passes any key it has not heard of, so the check now refuses anything not on its list, still in bash and awk on the same YAML stdin, so getmy-books-up and the sudo rule are unchanged.

    • Top level: name, services, networks, volumes.
    • A service: image, build, environment, env_file, restart, depends_on, healthcheck, logging, volumes, ports, networks, init, stop_grace_period, stop_signal, command, entrypoint, working_dir, profiles, labels, user, read_only, cap_drop. Any other key is refused by name.
    • Named refusals, besides the ones above: user root (or uid 0); sysctls; extra_hosts; tmpfs (as a key or a mount type); ulimits; any network_mode, including service:<x> and container:<x>; any pid, ipc or userns_mode.
    • image must be pinned by @sha256:<64 hex> (ADR 0028 decision 6, the pin half; the compose file pins postgres and a versioned cloudflared, #77).
    • build takes only context, dockerfile, args, target and labels (no build network, entitlements, secrets or ssh). Refusing build: itself waits for ADR 0028, when the app is pulled by digest.
    • ports only on postgres, until ADR 0030 removes its LAN port.
    • Volumes: postgres-data only, as a named volume (long syntax judged on type and source in either order); no external volume or network; networks use the bridge driver.
    • Layout: two-space block YAML, as docker compose config prints it. Tabs, flow-style YAML on any line (any value in braces or brackets but an empty {} or [], even behind an anchor or tag; a top-level section with a value, #332), other indents and a second document are refused rather than guessed at.

    The check runs under gawk, mawk and busybox awk. Inert until the owner reinstalls /usr/local/sbin/getmy-books-compose-check on the NAS from the merged commit; the compose-check v2 and v3 rules in docs/plans/deploy-hardening.md become additions to this list.

  5. Sudo rule (infra/nas/deploy/sudoers-getmy-books-deploy, installed as /etc/sudoers.d/getmy-books-deploy, mode 0440, checked with visudo -cf first): deploy ALL=(root) NOPASSWD: /usr/local/sbin/getmy-books-up "", so no arguments are allowed.

  6. The pipeline (scripts/deploy-nas.sh) sends one tar of the tracked files plus the env file (the allow-listed names from Doppler prd, amended 2026-11-03, #79), with the command deploy <commit>, and reports what the NAS prints. It no longer needs NAS_DEPLOY_DIR or NAS_DEPLOY_COMPOSE.

  7. Keys and settings. A new ed25519 key pair made for this job only. In Doppler prd: NAS_DEPLOY_USER becomes deploy and NAS_DEPLOY_SSH_KEY the new private key.

  8. Remove the old key from rob once one deploy has worked through deploy, and check it no longer logs in.

What changes, and where ​

WhereChange
NASCreate user deploy with a home folder and /bin/sh; its ~/.ssh/authorized_keys with the one forced-command line; /usr/local/bin/getmy-books-receive; /usr/local/sbin/getmy-books-up; /usr/local/sbin/getmy-books-compose-check; /usr/local/etc/getmy-books/docker-compose.yml; /etc/sudoers.d/getmy-books-deploy; last, remove the pipeline key line from rob's authorized_keys
Doppler prdNAS_DEPLOY_USER=deploy; NAS_DEPLOY_SSH_KEY replaced
RepoThe four files under infra/nas/deploy/; scripts/deploy-nas.sh; tests/infra/
Git hostNothing: the host had no repository variables, so the NAS_DEPLOY_ENABLED gate in ci.yml is removed once the checks pass
RunnerNothing

Order, with checks ​

a. Merge the repo changes with NAS_DEPLOY_ENABLED still off. b. Create the user; install the three programs, the root-owned compose file and the sudoers file from main. Checks: visudo -cf passes; sudo -l -U deploy lists only /usr/local/sbin/getmy-books-up ""; the programs and the compose file are owned by root and not writable by deploy; the compose check passes on the installed file; deploy is not in the docker or administrators groups. c. Add the key. Checks, from the runner's address: ssh deploy@nas id, a shell, scp and port forwarding are all refused; a request from any other address is refused. d. Update Doppler prd; the Product Owner sets NAS_DEPLOY_ENABLED=true; the next merge deploys. Check: /health shows the commit. e. Remove the key from rob. Check: it no longer logs in.

Done on 2026-09-29 ​

Steps b, c and d were run on the NAS by the agent, as the Product Owner asked, with every check passing. Step e follows the first deploy through deploy. The git host in use had no repository variables, so the NAS_DEPLOY_ENABLED gate was removed rather than set.

DSM 7.4.1 differs from a stock Linux host in ways the install had to follow:

  • Docker is at /usr/local/bin/docker, which is not on sudo's path. getmy-books-up sets its own PATH, so the deploy is unaffected.
  • There is no visudo. The sudoers rule is byte-identical to the one visudo accepted in a container dry run, and sudo -l was checked straight after installing it.
  • There is no getent; users are read from /etc/passwd.
  • synouser is at /usr/syno/sbin/synouser; sshd at /usr/bin/sshd.
  • /usr/local/sbin did not exist and was created (root, 0755).
  • DSM's sudo (1.9.5p2) accepts getmy-books-up with no arguments, and also with a literal "" argument; any other argument is refused. Harmless, since getmy-books-up never reads its arguments.
  • deploy's password field is *, not locked with !.
  • DSM resets a non-administrator's login shell to /sbin/nologin whenever it rewrites /etc/passwd (it did at 12:13 UTC on 2026-09-29, likely when another user's password changed). /sbin/nologin does not exist on DSM, so every deploy login then fails with "Permission denied, please try again." and the deploy job fails loudly. The first deploy through deploy failed this way; the shell was set back to /bin/sh. Fixed 2026-09-30 (#69, the Product Owner chose a DSM task):infra/nas/deploy/getmy-books-deploy-shell, installed root-owned as /usr/local/sbin/getmy-books-deploy-shell, puts /bin/sh back when the shell is /sbin/nologin and changes nothing otherwise. DSM Task Scheduler task 3, "GetMy Books: restore deploy shell", runs it as root every 5 minutes, all day. Tested: with the shell set to /sbin/nologin, the 09:05 run restored it. A reset can still break a deploy that starts in the 5 minutes before the next run; the job fails loudly and a rerun passes. With this in place, rob's old pipeline key (the fallback kept until now) was removed.

Consequences ​

  • A leaked pipeline key can only send a release tar from the runner's address; it gets no shell and cannot run commands of its choosing.
  • What root still takes from the deploy account: the code (built into the app image by the Dockerfile in the release) and the env file. A Dockerfile build runs inside Docker's build sandbox, and the compose file that decides mounts, privileges and networks is root's own, checked before every start. A change to infra/nas/docker-compose.yml needs the root-owned copy reinstalled from the repo by hand; until then the NAS keeps running the old file. Later (queued): build the image in CI and pull it by digest on the NAS, so nothing is built there at all.
  • DSM updates can reset the login shell, /etc/sudoers.d, /usr/local/bin, /usr/local/sbin or /usr/local/etc. After each DSM update the first deploy fails loudly rather than silently, and the files are reinstalled from this repo.
  • Docker access stays with root; deploy itself cannot run Docker.
  • Added 2026-11-03 (#78): infra/nas/manifest lists every file under infra/nas/ with its install destination, owner, mode and SHA-256 (tests/infra/nas-manifest.test.ts keeps it current), and infra/nas/deploy/getmy-books-drift-check, run daily as root by a DSM task, compares the installed files with it and alerts through the root alert.env when any differ, naming only the files in its log. Both are inert until the owner installs them. Who owns the install (a homelab-infra Ansible role or this hand install) is still the owner's decision (#78).
  • Decided 2026-11-04 (#78; Decided by: Product Owner): the install manifest plus the daily drift check is the answer for one NAS. The files stay installed by hand from this repo, checked against infra/nas/manifest every day; no homelab-infra Ansible role is written now. Ansible is revisited if a second host appears.
  • Recorded 2026-11-08 (#72; decision of 2026-11-06, Decided by: Product Owner): the target state for the owner's own rob account, which ADR 0023 did not cover. Done so far: the pipeline key and the unused wsl2-claude-code key are removed (2026-09-30), and the other automation keys carry no-agent-forwarding, no-port-forwarding,no-X11-forwarding,no-pty. Still to do, by the owner on the NAS (agents never change the NAS):
    1. replace the no-passphrase key robad@local-machine-nopass with a new passphrase-protected key (decided over DHCP reservations plus from=), proving the new key signs in before the old line is removed;
    2. give every remaining automation key in rob's authorized_keys a from= and a forced command, or move it to its own restricted user like deploy (the gh-actions-adviser-mcp-deploy and "ppp" keys need their runner hosts identified first);
    3. take rob out of the docker group once nothing under that account needs it, and check that sudo docker ps asks for a password. Target state: every key in rob's authorized_keys is either restricted or a passphrase-protected admin key, and rob cannot run docker without sudo.