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
125 lines
3.2 KiB
Groff
125 lines
3.2 KiB
Groff
.Dd March 11, 2026
|
|
.Dt MCIASCTL 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mciasctl
|
|
.Nd MCIAS admin CLI (REST)
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl server Ar url
|
|
.Op Fl token Ar jwt
|
|
.Op Fl cacert Ar path
|
|
.Ar command
|
|
.Op Ar subcommand
|
|
.Op Ar flags
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the administrator command-line interface for MCIAS.
|
|
It connects to a running
|
|
.Xr mciassrv 1
|
|
instance via the REST API over HTTPS and provides subcommands for managing
|
|
accounts, roles, tokens, and Postgres credentials.
|
|
.Pp
|
|
Authentication is performed using a bearer JWT.
|
|
The token must have the
|
|
.Qq admin
|
|
role for most operations.
|
|
Pass the token with the
|
|
.Fl token
|
|
flag or by setting the
|
|
.Ev MCIAS_TOKEN
|
|
environment variable.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fl server Ar url
|
|
Base URL of the mciassrv instance.
|
|
Default:
|
|
.Qq https://localhost:8443 .
|
|
Can also be set with the
|
|
.Ev MCIAS_SERVER
|
|
environment variable.
|
|
.It Fl token Ar jwt
|
|
Bearer token for authentication.
|
|
Can also be set with the
|
|
.Ev MCIAS_TOKEN
|
|
environment variable.
|
|
.It Fl cacert Ar path
|
|
Path to a CA certificate in PEM format for TLS verification.
|
|
Useful when mciassrv uses a self-signed certificate.
|
|
If omitted, the system certificate pool is used.
|
|
.El
|
|
.Sh COMMANDS
|
|
.Ss account
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic account Ic list
|
|
Lists all accounts.
|
|
Credential fields are never included in the output.
|
|
.It Nm Ic account Ic create Fl username Ar name Fl password Ar pass Op Fl type Ar human|system
|
|
Creates a new account.
|
|
.Fl type
|
|
defaults to
|
|
.Qq human .
|
|
.It Nm Ic account Ic get Fl id Ar uuid
|
|
Returns the account with the given UUID.
|
|
.It Nm Ic account Ic update Fl id Ar uuid Op Fl status Ar active|inactive
|
|
Updates account fields.
|
|
Currently only status can be updated.
|
|
.It Nm Ic account Ic delete Fl id Ar uuid
|
|
Soft-deletes the account and revokes all its tokens.
|
|
.El
|
|
.Ss role
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic role Ic list Fl id Ar uuid
|
|
Lists the roles assigned to the account.
|
|
.It Nm Ic role Ic set Fl id Ar uuid Fl roles Ar role1,role2,...
|
|
Replaces the role set for the account with the comma-separated list.
|
|
.El
|
|
.Ss token
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic token Ic issue Fl id Ar uuid
|
|
Issues a new service token for a system account.
|
|
.It Nm Ic token Ic revoke Fl jti Ar jti
|
|
Revokes the token with the given JTI.
|
|
.El
|
|
.Ss pgcreds
|
|
.Bl -tag -width Ds
|
|
.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 Fl password Ar pass
|
|
Sets Postgres credentials for the account.
|
|
The credentials are encrypted with AES-256-GCM using the server master key.
|
|
.It Nm Ic pgcreds Ic get Fl id Ar uuid
|
|
Retrieves and prints the Postgres credentials.
|
|
The password is included in plaintext; treat the output as sensitive.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width Ds
|
|
.It Ev MCIAS_TOKEN
|
|
Bearer token used for authentication when
|
|
.Fl token
|
|
is not specified.
|
|
.It Ev MCIAS_SERVER
|
|
Base URL of the mciassrv instance when
|
|
.Fl server
|
|
is not specified.
|
|
.El
|
|
.Sh EXAMPLES
|
|
List all accounts:
|
|
.Bd -literal -offset indent
|
|
mciasctl -server https://auth.example.com -token $ADMIN_TOKEN account list
|
|
.Ed
|
|
.Pp
|
|
Create a human account:
|
|
.Bd -literal -offset indent
|
|
mciasctl account create -username alice -password s3cr3t
|
|
.Ed
|
|
.Pp
|
|
Grant the admin role:
|
|
.Bd -literal -offset indent
|
|
mciasctl role set -id $UUID -roles admin
|
|
.Ed
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr mciassrv 1 ,
|
|
.Xr mciasdb 1 ,
|
|
.Xr mciasgrpcctl 1
|