abrown38andClaude Opus 5.5
7b3f0f764c
tls.acme names the certificate and jarl: the Jarl server and a token that may only write the challenge record. Steward gets the certificate with DNS-01 (lego), writing the record through Jarl's API into every view that has the zone, renews it with a third of its lifetime left and swaps it in without a restart. A check runs before every order: Jarl, the zone, the token's permission, a test record, the zone's name servers, public resolvers, clean-up; each step says what to fix. Staging by default. With a certificate, each listener serves HTTPS and plain HTTP on one port (redirecting plain HTTP, except from the server itself). steward cert / cert check / cert renew, Server -> Certificate in the web UI, GET /certificate, POST /certificate/check|renew. docs/certificates.md and docs/jarl.md (the Jarl user and the token's grant). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.8 KiB
Users, permissions and tokens
Users
Administrators may do everything, including managing users. Everyone
else gets grants, resource:access:
| Resource | read | write |
|---|---|---|
config |
settings, subnets, reservations, history, interfaces (the web UI shows the forms locked) | change them, undo, import |
leases |
leases and DHCP activity | delete a lease (making a reservation from one needs config:write too) |
audit |
the audit log | – |
The certificate (steward cert, Server → Certificate) is for administrators only.
| * | all of the above | |
Roles are ready-made sets of grants:
| Role | Grants |
|---|---|
viewer |
config:read leases:read |
operator |
config:write leases:write audit:read |
leases |
leases:read, e.g. for a monitoring script |
steward user add sam --role operator
steward user add monitor --no-password --role leases # tokens only
steward user update sam --grant config:read --grant leases:write
The last administrator can't be removed, demoted or disabled.
API tokens
A token has its user's permissions, or fewer. A token made with --role
or --grant can do only that, even if its user can do more:
steward token create backup-script --role leases --expires 365d
The secret is shown once; only its hash is stored. A restricted token can only create tokens with a subset of its own grants. The web UI only offers roles within what your account may do; a token with more would get no more than its user anyway.
Rotating gives a token a new secret, keeping its ID, name and permissions, so only the programs that use it need updating:
steward token rotate 7 --grace 1h # the old secret works for another hour
steward token rotate --current --save # this CLI's own token
A token that expires gets its lifetime again, from now (--expires 90d
or never to change it). Without --grace the old secret stops at once:
use that when it may have leaked. Using an old secret during its grace
period is logged, naming the token and the address, so you can find the
programs still to update. A restricted token may rotate itself and tokens
no wider than itself. steward token list
shows when each token was last used, and from where. steward token revoke ID stops one at once.
The local socket
On the server, /run/steward/steward.sock lets root and the steward
user act as administrator without a token. The audit log shows them by
their system user name. Both can already read the database, so this adds
convenience, not power. Anyone else on the socket needs a token.
The audit log
Logins (and failed ones), users, tokens, every configuration change (with
its history entry), lease deletions and imports are recorded with who, from
where and how: session, token or socket.