nixos-servers/scripts/vault-fetch

vault-fetch

A helper script for fetching secrets from OpenBao/Vault and writing them to the filesystem.

Features

• AppRole Authentication: Uses role_id and secret_id from /var/lib/vault/approle/
• Individual Secret Files: Writes each secret key as a separate file for easy consumption
• Caching: Maintains a cache of secrets for fallback when Vault is unreachable
• Graceful Degradation: Falls back to cached secrets if Vault authentication fails
• Secure Permissions: Sets 600 permissions on all secret files

Usage

vault-fetch <secret-path> <output-directory> [cache-directory]

Examples

# Fetch Grafana admin secrets
vault-fetch hosts/ha1/mqtt-password /run/secrets/grafana /var/lib/vault/cache/grafana

# Use default cache location
vault-fetch hosts/ha1/mqtt-password /run/secrets/grafana

How It Works

1. Read Credentials: Loads role_id and secret_id from /var/lib/vault/approle/
2. Authenticate: Calls POST /v1/auth/approle/login to get a Vault token
3. Fetch Secret: Retrieves secret from GET /v1/secret/data/{path}
4. Extract Keys: Parses JSON response and extracts individual secret keys
5. Write Files: Creates one file per secret key in output directory
6. Update Cache: Copies secrets to cache directory for fallback
7. Set Permissions: Ensures all files have 600 permissions (owner read/write only)

Error Handling

If Vault is unreachable or authentication fails:

• Script logs a warning to stderr
• Falls back to cached secrets from previous successful fetch
• Exits with error code 1 if no cache is available

Environment Variables

• VAULT_ADDR: Vault server address (default: https://vault01.home.2rjus.net:8200)
• VAULT_SKIP_VERIFY: Skip TLS verification (default: 1)

Integration with NixOS

This tool is designed to be called from systemd service ExecStartPre hooks via the vault.secrets NixOS module:

vault.secrets.mqtt-password = {
  secretPath = "hosts/ha1/mqtt-password";
};

# Service automatically gets secrets fetched before start
systemd.services.mosquitto.serviceConfig = {
  EnvironmentFile = "/run/secrets/mqtt-password/password";
};

Requirements

• curl: For Vault API calls
• jq: For JSON parsing
• coreutils: For file operations

Security Considerations

• AppRole credentials stored at /var/lib/vault/approle/ should be root-owned with 600 permissions
• Tokens are ephemeral and not stored - fresh authentication on each fetch
• Secrets written to tmpfs (/run/secrets/) are lost on reboot
• Cache directory persists across reboots for service availability
• All secret files have restrictive permissions (600)