1# Upgrading Gordon
2
3This guide covers breaking changes and migration steps between major versions.
4
5## v2.16.0 to v2.30.0
6
7### Breaking: Password Authentication Removed
8
9Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.
10
11**What changed:**
12
13- `auth.type = "password"` is no longer accepted
14- `auth.password` and `auth.password_hash` config fields are removed
15- The `gordon auth password hash` CLI command is removed
16- The `gordon auth login` command now requires `--token` (no more interactive password prompt)
17- The `/auth/password` endpoint now returns `410 Gone`
18- Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via `/auth/token`
19
20**New features:**
21
22- `auth.access_token_ttl` configures the lifetime of ephemeral access tokens issued by `/auth/token` (default: `"15m"`)
23- `gordon auth show-token` prints the stored token for a remote
24- `gordon auth logout` removes the stored token (with optional `--revoke`)
25- Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
26- Admin scopes (`admin:*:*`, `admin:routes:read`, etc.) allow fine-grained access control for remote CLI operations
27
28**Migration steps:**
29
301. **Before upgrading**, generate a token on your current Gordon instance:
31
32   ```bash
33   gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
34   ```
35
36   Save this token securely. You will need it after upgrading. Admin scopes (`admin:*:*`) are only available after upgrading to v2.30.0 — regenerate your token with admin scopes after the upgrade if needed.
37
382. **Update remotes** to use the generated token:
39
40   ```bash
41   gordon auth login --token <token>
42   # or
43   gordon remotes set-token prod <token>
44   ```
45
463. **Update your config** to remove password fields:
47
48   **Before (v2.16.0):**
49
50   ```toml
51   [auth]
52   enabled = true
53   secrets_backend = "pass"
54   username = "deploy"
55   password_hash = "gordon/auth/password_hash"
56   token_secret = "gordon/auth/token_secret"
57   ```
58
59   **After (v2.30.0):**
60
61   ```toml
62   [auth]
63   enabled = true
64   secrets_backend = "pass"
65   token_secret = "gordon/auth/token_secret"
66   access_token_ttl = "15m"
67   ```
68
694. **Update CI/CD pipelines** to use `GORDON_TOKEN` environment variable for authentication. See the [deployment guides](./deployment/index.md).
70
715. **Upgrade the binary** and restart:
72
73   ```bash
74   curl -fsSL https://gordon.bnema.dev/install | bash
75   systemctl --user restart gordon
76   ```
77
786. **Verify** the server starts without errors:
79
80   ```bash
81   journalctl --user -u gordon -f
82   ```
83
84### New: Configurable Access Token TTL
85
86Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl` (default `"15m"`, maximum `"1h"`).
87
88Tokens with a lifetime at or below `MaxAccessTokenLifetime` (1 hour) are treated as ephemeral: they skip token store validation for performance, which means they **cannot be individually revoked**. They become invalid only when they naturally expire. Shortening `auth.access_token_ttl` only reduces the exposure window; it does not enable per-token revocation. If you need explicit revocation, use a stored long-lived token instead of `/auth/token`.
89
90```toml
91[auth]
92access_token_ttl = "30m"
93```
94
95### New: Admin Scopes
96
97Tokens can now include fine-grained admin scopes for remote CLI operations:
98
99```bash
100# Full admin access
101gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
102
103# Read-only monitoring
104gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
105
106# CI deploy with route read + config write
107gordon auth token generate --subject ci --scopes "push,pull,admin:routes:read,admin:config:write" --expiry 0
108```
109
110See [Token Scopes](./config/auth.md#token-scopes) for the full list.
111
112## v2.6.0 to v2.7.0
113
114### Breaking: Token Secret Required
115
116Gordon v2.7.0 requires a `token_secret` for JWT authentication. The server will not start without it configured.
117
118**Error you'll see:**
119```
120Error: token_secret is required for JWT token generation; set GORDON_AUTH_TOKEN_SECRET environment variable or configure auth.token_secret
121```
122
123**Choose one of these migration options:**
124
125#### Option A: Environment Variable (simplest)
126
127```bash
128# Generate a random secret
129export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
130
131# Add to your shell profile or systemd service
132echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
133```
134
135For systemd services:
136```bash
137mkdir -p ~/.config/systemd/user/gordon.service.d
138cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
139[Service]
140Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
141EOF
142systemctl --user daemon-reload
143systemctl --user restart gordon
144```
145
146#### Option B: Config File with Pass (recommended for production)
147
148```bash
149# Generate and store secret in pass
150openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
151
152# Update your gordon.toml
153```
154
155```toml
156[auth]
157enabled = true
158secrets_backend = "pass"
159token_secret = "gordon/auth/token_secret"
160```
161
162#### Option C: Config File with Unsafe Backend (development only)
163
164```bash
165# Generate secret file
166mkdir -p ~/.gordon/secrets
167openssl rand -base64 32 > ~/.gordon/secrets/token_secret
168chmod 600 ~/.gordon/secrets/token_secret
169```
170
171```toml
172[auth]
173enabled = true
174secrets_backend = "unsafe"
175token_secret = "token_secret"
176```
177
178### Breaking: Unsafe Token Store Warning
179
180Using `secrets_backend = "unsafe"` now logs a warning on startup:
181```
182WRN using unsafe secrets backend - secrets are stored in plain text
183```
184
185This is intentional to encourage secure secret storage in production. The warning can be ignored for development.
186
187### New Features
188
189- **Attachment secrets discovery**: `gordon secrets list <domain>` now shows secrets for attachment containers
190- **Auth login command**: `gordon auth login --remote <name>` for password authentication
191- **Rate limiting**: Configurable rate limits under `[api.rate_limit]`
192
193### Security Improvements
194
195v2.7.0 includes a comprehensive security audit with:
196
197- JWT tokens now include "not before" (nbf) claim
198- SSRF protection for external routes
199- Security headers middleware
200- Rate limiting on registry and token endpoints
201- Command injection prevention in pass provider
202- Path traversal prevention in secrets store
203
204## v2.5.0 to v2.6.0
205
206### Breaking: Config Restructure
207
208The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
209
210**Before (v2.5.0):**
211```toml
212[secrets]
213backend = "pass"
214
215[registry_auth]
216enabled = true
217type = "password"
218password_hash = "gordon/registry/password_hash"
219```
220
221**After (v2.6.0+):**
222```toml
223[auth]
224enabled = true
225secrets_backend = "pass"
226password_hash = "gordon/auth/password_hash"
227```
228
229### Breaking: Auth Enabled by Default
230
231Gordon keeps auth enabled by default. If you set `auth.enabled = false`, Gordon runs in local-only mode (`/admin/*` disabled, `/v2/*` loopback-only).
232
233### Breaking: Secret Paths Changed
234
235If using pass or sops, update your secret paths:
236- `gordon/registry/*` → `gordon/auth/*`
237
238## General Upgrade Process
239
2401. **Read the changelog** for your target version
2412. **Backup your config** before upgrading
2423. **Test in staging** if possible
2434. **Upgrade the binary**:
244   ```bash
245   curl -fsSL https://gordon.bnema.dev/install | bash
246   ```
2475. **Restart Gordon**:
248   ```bash
249   systemctl --user restart gordon
250   ```
2516. **Check logs** for any errors:
252   ```bash
253   gordon logs
254   ```
255
256## Getting Help
257
258- [GitHub Issues](https://github.com/bnema/gordon/issues)
259- [Documentation](https://gordon.bnema.dev/docs)