Credential chain¶
The server needs passwords and tokens: the operator account password, NAS and Time Machine logins, the PIA VPN account, Wi-Fi, and Cloudflare tokens. This page explains where each secret starts, how it moves to the service that uses it, and why long-running services take secrets from the environment, a file or stdin, and not from the command line.
Two chains, not one¶
Secrets reach the server by two routes.
| Chain | Secrets | Source | Lands in |
|---|---|---|---|
| Package chain | operator password, NAS, Time Machine, Wi-Fi, OpenSubtitles, PIA |
1Password, read on the dev Mac | The admin login keychain |
| System keychain chain | Cloudflare API token, tunnel token, read-only Access token | You type each one at a prompt on the server | /Library/Keychains/System.keychain |
The package chain exists because first boot runs before the Mac mini has any account that could sign in to 1Password. The System keychain chain exists because root daemons read those tokens, and the System keychain is the keychain that root reads without a GUI session.
The package chain¶
flowchart LR
op["1Password<br>op:// item references"]
prep["prep-airdrop.sh<br>(dev Mac)"]
pkg["package keychain<br>mac-server-setup-db"]
fb["first-boot.sh<br>(admin)"]
login["admin login keychain"]
setup["app-setup scripts"]
svc["service files and containers"]
op --> prep --> pkg -- AirDrop --> fb --> login --> setup --> svc
- 1Password. It is the source of truth.
prep-airdrop.shreads each item withop readon the dev Mac. A rotation starts here. - The package keychain.
prep-airdrop.shcreates a keychain namedmac-server-setup, stores each secret in it, reads each one back to check it, locks the keychain, and copies the file into the package asconfig/mac-server-setup-db. Service names follow the pattern<purpose>-<server name>, for examplepia-account-macmini. A login and password pair is stored as oneusername:passwordstring. - First boot import.
first-boot.shunlocks the package keychain and copies each item into theadminuser's default keychain, which is the login keychain. An optional item that is missing gives a warning, not an error. - App setup. Each setup script reads what it needs from the
adminkeychain and writes it into the form its service uses. For example,podman-transmission-setup.shwrites the PIA account to~operator/containers/transmission/.envwith mode 600. - Runtime. The service reads its own file. It does not read a keychain at run time. The secrets sit in the
adminlogin keychain, and the services run asoperator. That keychain opens only with theadminpassword.operatoris in theadmingroup, but group membership does not unlock another user's keychain.
What protects the package keychain¶
The package keychain's password is the dev Mac's hardware UUID. prep-airdrop.sh writes that password into config/keychain_manifest.conf in the same package, with mode 600. The keychain therefore keeps secrets out of plain-text config files and lets security check each value, but anyone who has the whole package can open it. Treat the whole package as a secret. first-boot.sh copies the package keychain into the admin keychain folder and keeps the original, so that a second run works. The setup scripts have no step that deletes either copy.
The hardware fingerprint has a second use. first-boot.sh refuses to run on the machine that built the package, which stops a mistaken run on the dev Mac.
Package keychain services¶
Each service name ends in the lowercased SERVER_NAME, and the account name is that same lowercased name. HOSTNAME_OVERRIDE does not change them.
| Service | Holds | Present when |
|---|---|---|
operator-<server name> |
The operator account password |
Always; prep-airdrop.sh creates the 1Password item if it is missing |
plex-nas-<server name> |
Media NAS username:password |
The ONEPASSWORD_PLEX_NAS_ITEM item exists |
timemachine-<server name> |
Time Machine share username:password |
The ONEPASSWORD_TIMEMACHINE_ITEM item exists |
wifi-<server name> |
The Wi-Fi password | You choose the script-based Wi-Fi setup |
opensubtitles-<server name> |
OpenSubtitles username:password |
The ONEPASSWORD_OPENSUBTITLES_ITEM item exists |
pia-account-<server name> |
PIA username:password |
ONEPASSWORD_PIA_ITEM is set |
What else the package carries¶
- SSH keys.
prep-airdrop.shcopies both halves of the dev Mac's~/.ssh/id_ed25519key pair intossh_keys/.setup-ssh-access.shinstalls the private and public key in theadminaccount's~/.ssh, and the public key asauthorized_keysfor bothadminandoperator. The private key is one more reason to treat the whole package as a secret. - The Apple Account password. It is not in the keychain.
prep-airdrop.shmakes a view-once 1Password share link for theONEPASSWORD_APPLEID_ITEMitem and writes it toconfig/apple_id_password.url. The link works once.
The System keychain chain¶
Root daemons read the Cloudflare tokens from the System keychain each time they start. The pattern is the same for each one: a small wrapper reads the token, exports it to an environment variable, and uses exec to start the real program.
| Token | Read by | Passed on as |
|---|---|---|
cloudflare-api-token |
caddy-wrapper.sh and the DDNS updater (root) |
CF_API_TOKEN environment variable |
cloudflare-tunnel-token |
cloudflared-wrapper.sh (root) |
TUNNEL_TOKEN environment variable |
cloudflare-access-readonly-token |
access-policy-watchdog-setup.sh (root, at deploy) |
A mode 600 file that operator owns |
The read-only Access token goes to a file because the drift watchdog runs as operator, which cannot read the System keychain. The setup script writes the file through a shell redirect into a file created with umask 077, so the token is never an argument. The token can only read Access and tunnel configuration. See Tunnel security layers.
Do not use cloudflared service install <token>. It writes the token into a LaunchDaemon plist, and those files are readable by every user.
Why long-running services keep secrets off argv¶
On macOS, ps shows the full argument list of every process to every user. A secret on a command line is visible to any account on the machine for as long as that process runs. Environment variables of another user's process are not shown that way, and a file with mode 600 is readable only by its owner.
The long-running parts follow these rules:
- Wrappers export and exec.
caddy-wrapper.shandcloudflared-wrapper.shput the token in the environment and replace themselves with the real program.cloudflared tunnel runtakes no token argument. - curl reads headers from stdin. The drift watchdog sends
Authorization: Bearer ...tocurl -K -through a pipe fromprintf, which is a shell builtin and so is not a separate process. - Containers get an env file. The Transmission container is created with
--env-file, not-e PIA_PASSWORD=.... Because--env-fileis read only when the container is created, a password change needs a container recreate, not a restart. - People type secrets at a prompt. To add a keychain item by hand, give
security add-generic-passwordthe-wflag with no value, as the last argument, so it prompts. The value is then not in shell history or the process list. If a keychain path follows a bare-w,securitycan take the path as the password.
Where the rule does not hold yet¶
Some commands still pass secrets as arguments. While each one runs, any local account can see the value with ps.
At setup time, for a few seconds each:
prep-airdrop.shandfirst-boot.shcallsecurity add-generic-password -w "<value>"andsecurity create-keychain -p.first-boot.shpasses theoperatorandadminpasswords tosysadminctlas arguments.- The hint that
cloudflare-ddns-setup.shprints, when the token is missing, puts the token on thesecuritycommand line.
After setup:
- The PIA port manager inside the container passes the PIA account to
curlas arguments, each time it asks for a port-forwarding token, for as long as the container runs. - The PIA port-forwarding probe, which you run when you need it, passes the account to
podman exec -eand tocurl.
See PIA VPN.
Rotating a secret¶
A rotation must go through every stage that holds a copy, in order. For a package-chain secret: change it at the provider, update 1Password, update the admin keychain item on the server, then run the setup script again so that it rewrites the service file. For the PIA account, the container must then be recreated. PIA VPN gives the full procedure. For a System keychain token, replace the keychain item and restart the daemon that reads it.
For the older description of the keychain format and service names, see Keychain credential management.