129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# SOPS Secrets Management Guide
|
|
|
|
This guide covers how to manage encrypted secrets in Nix-Vibe using `sops-nix` with `age` encryption.
|
|
|
|
## Overview
|
|
|
|
- **Secrets File**: `secrets.yaml` (encrypted in Git)
|
|
- **Configuration**: `.sops.yaml` (public keys and creation rules)
|
|
- **Private Key**: Locally stored at `~/.config/sops/age/keys.txt` (Never commit this!)
|
|
|
|
## Prerequisites
|
|
|
|
The project includes `sops` in the default development environment. You can also run it temporarily:
|
|
|
|
```bash
|
|
nix shell nixpkgs#sops nixpkgs#age
|
|
```
|
|
|
|
## Adding or Updating Secrets
|
|
|
|
The easiest way to add a new secret (like a password or API key) is to use the `sops --set` command from the root of the repository.
|
|
|
|
### Adding a Key-Value Pair
|
|
|
|
```bash
|
|
sops --set '["<host-or-category>"]["<secret-name>"] "<value>"' secrets.yaml
|
|
```
|
|
|
|
*Example (Adding a server password):*
|
|
```bash
|
|
sops --set '["richmond-server"]["new-password"] "supersecret123"' secrets.yaml
|
|
```
|
|
|
|
*Example (Adding a global user password):*
|
|
```bash
|
|
sops --set '["users"]["petere-password"] "mypassword"' secrets.yaml
|
|
```
|
|
|
|
### Editing the Secrets File Directly
|
|
|
|
To open the entire decrypted file in your editor:
|
|
|
|
```bash
|
|
sops secrets.yaml
|
|
```
|
|
|
|
## Using Secrets in Configuration
|
|
|
|
### 1. NixOS System Secrets
|
|
|
|
In `hosts/<hostname>/configuration.nix`:
|
|
|
|
```nix
|
|
sops.secrets."machine-name/new-secret" = {
|
|
owner = "root";
|
|
group = "root";
|
|
mode = "0400";
|
|
};
|
|
```
|
|
|
|
**Note:** For user passwords, add `neededForUsers = true;` to ensure the secret is decrypted early enough for the account to be created.
|
|
|
|
### 2. Home Manager Secrets
|
|
|
|
Home Manager secrets are defined in the user's profile (e.g., `home-manager/users/petere.nix`):
|
|
|
|
```nix
|
|
sops.secrets."gemini-api-key" = { };
|
|
```
|
|
|
|
Access the decrypted path in your configuration:
|
|
`config.sops.secrets."gemini-api-key".path`
|
|
|
|
### 3. Rendered Templates (`sops.templates`)
|
|
|
|
For config files that embed a secret (e.g. an env file consumed by a container),
|
|
use `sops.templates` so sops-nix renders the file with correct permissions and
|
|
re-renders it at boot/switch — no shell `preStart` needed:
|
|
|
|
```nix
|
|
sops.templates."pihole-env" = {
|
|
content = ''
|
|
FTLCONF_webserver_api_password=${config.sops.placeholder."richmond-server/pihole-password"}
|
|
'';
|
|
path = "/run/pihole-env";
|
|
mode = "0600";
|
|
};
|
|
```
|
|
|
|
The `${config.sops.placeholder."<secret>"}` reference is substituted with the
|
|
decrypted value at runtime. Live examples: `hosts/richmond-server/configuration.nix`
|
|
(pihole + castopod env files).
|
|
|
|
### Multi-line Secrets
|
|
|
|
Store SSH keys and other multi-line values as YAML **block scalars** (using `|`)
|
|
so they decrypt with real newlines. `hosts/homeserver-1/configuration.nix`
|
|
installs the `restic-ssh-key` verbatim with `install`, so that secret must be
|
|
multi-line (not a single line with escaped spaces).
|
|
|
|
## Rotating / Adding New Machine Keys
|
|
|
|
When deploying to a new machine, you must generate an age key and add its public key to `.sops.yaml`.
|
|
|
|
1. **Generate the key on the target machine**:
|
|
```bash
|
|
mkdir -p ~/.config/sops/age
|
|
age-keygen -o ~/.config/sops/age/keys.txt
|
|
```
|
|
|
|
2. **Get the public key**:
|
|
```bash
|
|
cat ~/.config/sops/age/keys.txt | age-keygen -y
|
|
```
|
|
|
|
3. **Update `.sops.yaml`**:
|
|
Add the new public key to the `age` list.
|
|
|
|
4. **Re-encrypt the secrets file**:
|
|
```bash
|
|
sops updatekeys secrets.yaml
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- **"No sops config found"**: Ensure you are in the repository root.
|
|
- **Decryption Failure**: Ensure your private key is at `~/.config/sops/age/keys.txt` or set `export SOPS_AGE_KEY_FILE=...`.
|
|
- **Pure Evaluation Mode**: Nix Flakes in pure mode cannot read absolute paths (like `/run/secrets/...`). Use `sops.templates` or runtime injection instead of `preStart` (see `hosts/richmond-server/configuration.nix`).
|