Kyle Isom
941c71f2d1
- Makefile: build/test/lint/generate/man/install/clean/dist/docker; CGO_ENABLED=1 throughout; VERSION from git describe --tags --always - Dockerfile: multi-stage (golang:1.26-bookworm builder -> debian:bookworm-slim runtime); non-root uid 10001 (mcias), VOLUME /data, EXPOSE 8443/9443; no toolchain in final image - dist/mcias.service: hardened systemd unit (ProtectSystem=strict, ProtectHome, PrivateTmp, NoNewPrivileges, MemoryDenyWriteExecute, CapabilityBoundingSet= empty, EnvironmentFile, LimitNOFILE=65536) - dist/mcias.env.example: passphrase env file template - dist/mcias.conf.example: fully-commented production TOML config - dist/mcias-dev.conf.example: local dev config (/tmp, short expiry) - dist/mcias.conf.docker.example: container config template - dist/install.sh: POSIX sh idempotent installer; creates mcias user/group, installs binaries, /etc/mcias, /var/lib/mcias, systemd unit, man pages; prints post-install instructions - man/man1/mciassrv.1: mdoc synopsis/config/API/signals/files - man/man1/mciasctl.1: mdoc all subcommands/env/examples - man/man1/mciasdb.1: mdoc trust model/safety/all subcommands - man/man1/mciasgrpcctl.1: mdoc gRPC commands/grpcurl example - README.md: user-facing quick-start, first-run setup, build instructions, CLI references, Docker deployment, security notes - .gitignore: added /bin/, dist/mcias_*.tar.gz, man/man1/*.gz
204 lines
5.6 KiB
Groff
204 lines
5.6 KiB
Groff
.Dd March 11, 2026
|
|
.Dt MCIASDB 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mciasdb
|
|
.Nd MCIAS database maintenance tool
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl config Ar path
|
|
.Ar command
|
|
.Op Ar subcommand
|
|
.Op Ar flags
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the MCIAS database maintenance tool.
|
|
It operates
|
|
.Em directly
|
|
on the SQLite database file, bypassing the mciassrv REST API.
|
|
.Pp
|
|
Use
|
|
.Nm
|
|
for:
|
|
.Bl -bullet -compact
|
|
.It
|
|
Break-glass recovery when the server is unavailable.
|
|
.It
|
|
Offline account and role management before first server start.
|
|
.It
|
|
Schema verification and migration.
|
|
.It
|
|
Token pruning and audit log inspection.
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
requires the same master key configuration as
|
|
.Xr mciassrv 1
|
|
to decrypt secrets at rest.
|
|
.Sh TRUST MODEL AND SAFETY WARNINGS
|
|
.Nm
|
|
has
|
|
.Em direct write access
|
|
to the database and can modify any record without going through the server's
|
|
validation logic.
|
|
Use it only when necessary.
|
|
.Bl -bullet
|
|
.It
|
|
Run
|
|
.Nm
|
|
on the same host as the database file.
|
|
Never copy the database to an untrusted host.
|
|
.It
|
|
The master key passphrase (or keyfile) must be available.
|
|
Set the environment variable named by
|
|
.Sy passphrase_env
|
|
in the config, or ensure the keyfile is accessible.
|
|
.It
|
|
All write operations append an audit log entry tagged
|
|
.Qq actor:mciasdb .
|
|
.It
|
|
Avoid running
|
|
.Nm
|
|
while mciassrv is under heavy write load; SQLite WAL mode provides some
|
|
isolation, but schema migrations acquire an exclusive lock.
|
|
.El
|
|
.Sh OPTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fl config Ar path
|
|
Path to the TOML configuration file.
|
|
Defaults to
|
|
.Pa mcias.toml
|
|
in the current directory.
|
|
.El
|
|
.Sh COMMANDS
|
|
.Ss schema
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic schema Ic verify
|
|
Reports the current schema version.
|
|
Exits 0 if the schema is up to date; exits 1 if migrations are pending.
|
|
.It Nm Ic schema Ic migrate
|
|
Applies any pending migrations and reports each one applied.
|
|
Exits 0 on success.
|
|
.El
|
|
.Ss account
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic account Ic list
|
|
Prints UUID, username, type, and status for all accounts.
|
|
.It Nm Ic account Ic get Fl -id Ar uuid
|
|
Prints the account record for the given UUID.
|
|
.It Nm Ic account Ic create Fl -username Ar name Fl -type Ar human|system
|
|
Inserts a new account row and prints the new UUID.
|
|
.It Nm Ic account Ic set-password Fl -id Ar uuid
|
|
Prompts for a new password twice (confirmation).
|
|
Re-hashes with Argon2id and updates the row.
|
|
No
|
|
.Fl -password
|
|
flag is provided; the password is always read interactively.
|
|
.It Nm Ic account Ic set-status Fl -id Ar uuid Fl -status Ar STATUS
|
|
Updates the account status.
|
|
Valid statuses:
|
|
.Qq active ,
|
|
.Qq inactive ,
|
|
.Qq deleted .
|
|
.It Nm Ic account Ic reset-totp Fl -id Ar uuid
|
|
Clears the TOTP secret and disables TOTP for the account.
|
|
The user will be able to log in with password only until they re-enrol.
|
|
.El
|
|
.Ss role
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic role Ic list Fl -id Ar uuid
|
|
Prints the roles assigned to the account.
|
|
.It Nm Ic role Ic grant Fl -id Ar uuid Fl -role Ar role
|
|
Adds a role to the account.
|
|
.It Nm Ic role Ic revoke Fl -id Ar uuid Fl -role Ar role
|
|
Removes a role from the account.
|
|
.El
|
|
.Ss token
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic token Ic list Fl -id Ar uuid
|
|
Prints JTI, issued_at, expires_at, and revoked_at for all tokens associated
|
|
with the account.
|
|
.It Nm Ic token Ic revoke Fl -jti Ar jti
|
|
Sets revoked_at to the current time on the specified token row.
|
|
.It Nm Ic token Ic revoke-all Fl -id Ar uuid
|
|
Revokes all non-revoked tokens for the account.
|
|
A no-op (exits 0) if no active tokens exist.
|
|
.El
|
|
.Ss prune
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic prune Ic tokens
|
|
Deletes rows from the token_revocation table where expires_at is in the past.
|
|
Prints the number of rows removed.
|
|
.El
|
|
.Ss audit
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic audit Ic tail Op Fl -n Ar N
|
|
Prints the last N audit events, newest last.
|
|
Default: 50.
|
|
.It Nm Ic audit Ic query Op Fl -account Ar uuid Op Fl -type Ar event_type Op Fl -since Ar timestamp Op Fl -json
|
|
Queries the audit log.
|
|
Filters are combinable (AND semantics).
|
|
.Fl -since
|
|
accepts an RFC 3339 timestamp.
|
|
.Fl -json
|
|
emits newline-delimited JSON instead of tabular output.
|
|
.El
|
|
.Ss pgcreds
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic pgcreds Ic get Fl -id Ar uuid
|
|
Decrypts and prints the Postgres credentials for the account.
|
|
A warning header is printed before the output because the password is
|
|
displayed in plaintext.
|
|
.It Nm Ic pgcreds Ic set Fl -id Ar uuid Fl -host Ar host Fl -port Ar port Fl -db Ar db Fl -user Ar user
|
|
Prompts for the Postgres password interactively (no
|
|
.Fl -password
|
|
flag).
|
|
Encrypts with AES-256-GCM using the master key and stores the record.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Verify schema after upgrade:
|
|
.Bd -literal -offset indent
|
|
MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf schema verify
|
|
.Ed
|
|
.Pp
|
|
Create an admin account before first server start:
|
|
.Bd -literal -offset indent
|
|
MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\
|
|
account create --username admin --type human
|
|
MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\
|
|
account set-password --id <UUID>
|
|
MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\
|
|
role grant --id <UUID> --role admin
|
|
.Ed
|
|
.Pp
|
|
Tail the last 20 audit events:
|
|
.Bd -literal -offset indent
|
|
MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\
|
|
audit tail --n 20
|
|
.Ed
|
|
.Sh ENVIRONMENT
|
|
The environment variable named by
|
|
.Sy passphrase_env
|
|
in the configuration file must be set to the master key passphrase, unless
|
|
.Sy keyfile
|
|
is used instead.
|
|
.Pp
|
|
Example (with default config):
|
|
.Bd -literal -offset indent
|
|
export MCIAS_MASTER_PASSPHRASE=your-passphrase
|
|
mciasdb --config /etc/mcias/mcias.conf account list
|
|
.Ed
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh FILES
|
|
.Bl -tag -width Ds
|
|
.It Pa /etc/mcias/mcias.conf
|
|
Default configuration file location.
|
|
.It Pa /var/lib/mcias/mcias.db
|
|
SQLite database.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr mciassrv 1 ,
|
|
.Xr mciasctl 1 ,
|
|
.Xr mciasgrpcctl 1
|