5785c0024c
swarm-controller's POST /api/agents now refuses (409) a name the swarm
has already placed on a different hive: a non-Destroyed declaration in
that hive's wanted state, or a SetAgentWanted node still queued for it.
The same name on the same hive is that agent being re-created and goes
through. A wanted state that cannot be read refuses (503/500) instead of
reading as "placed nowhere". Creations are serialised from that read to
the graph insert so two concurrent creations of one name cannot both
pass.
Hive-level creation is removed: hivectl `agent create` / `request-create`,
HostRequest::Spawn / RequestSpawn, the dashboard POST /api/request-spawn
route, and ApprovalKind::Spawn with its approve/resolve arms and the
approval-carrying `templates::spawn`. The swarm path (deploy request or
wanted-state sweep -> queue_first_deploy -> templates::first_deploy) used
none of them. Old `spawn` approval rows are skipped by collect_lenient,
as `init_config` rows were in a3b672d1.
policy.rs's comment on agent_object_name stated swarm-wide name
uniqueness as a fact; it now says where it is enforced and what that
check cannot see.
Refs #4396
260 lines
9.4 KiB
Markdown
260 lines
9.4 KiB
Markdown
# Command-Line Help for `swarmctl`
|
||
|
||
This document contains the help content for the `swarmctl` command-line program.
|
||
|
||
**Command Overview:**
|
||
|
||
* [`swarmctl`↴](#swarmctl)
|
||
* [`swarmctl agent`↴](#swarmctl-agent)
|
||
* [`swarmctl agent create`↴](#swarmctl-agent-create)
|
||
* [`swarmctl agent mint-identity`↴](#swarmctl-agent-mint-identity)
|
||
* [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token)
|
||
* [`swarmctl user`↴](#swarmctl-user)
|
||
* [`swarmctl user add`↴](#swarmctl-user-add)
|
||
* [`swarmctl user reset-password`↴](#swarmctl-user-reset-password)
|
||
* [`swarmctl user update`↴](#swarmctl-user-update)
|
||
* [`swarmctl user list`↴](#swarmctl-user-list)
|
||
* [`swarmctl forge`↴](#swarmctl-forge)
|
||
* [`swarmctl forge make-admin`↴](#swarmctl-forge-make-admin)
|
||
* [`swarmctl completions`↴](#swarmctl-completions)
|
||
|
||
## `swarmctl`
|
||
|
||
swarm-level operator CLI
|
||
|
||
**Usage:** `swarmctl [OPTIONS] <COMMAND>`
|
||
|
||
###### **Subcommands:**
|
||
|
||
* `agent` — Manage agents across the swarm
|
||
* `user` — Manage subjects in the swarm's SSO provider
|
||
* `forge` — Manage human accounts on the swarm's forge
|
||
* `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
|
||
|
||
###### **Options:**
|
||
|
||
* `--authelia-bin <PATH>` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH`
|
||
* `--users-file <PATH>` — Host-side path of authelia's users database — that is, the path inside the container, prefixed with the container's root.
|
||
|
||
This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
|
||
|
||
|
||
|
||
## `swarmctl agent`
|
||
|
||
Manage agents across the swarm
|
||
|
||
**Usage:** `swarmctl agent <COMMAND>`
|
||
|
||
###### **Subcommands:**
|
||
|
||
* `create` — Queue creation of a new agent on a hive in this swarm
|
||
* `mint-identity` — Queue a re-mint of an existing agent's identity at the swarm's secret store
|
||
* `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
|
||
|
||
|
||
|
||
## `swarmctl agent create`
|
||
|
||
Queue creation of a new agent on a hive in this swarm.
|
||
|
||
Asks the swarm-controller to insert its agent-creation job graph — SSO identity, forge user, config repo, and the deploy message that puts the agent on `--hive` — and prints the queued job's node id.
|
||
|
||
**This returns as soon as it queues the work.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest.
|
||
|
||
No approval gate guards this: running this binary already means being root on the controller's host.
|
||
|
||
**Usage:** `swarmctl agent create [OPTIONS] --hive <HIVE> <NAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<NAME>` — Name for the new agent: 1–63 characters of `[a-z0-9-]`.
|
||
|
||
Becomes an SSO subject, a forge user and a repository name, so it's validated here before queuing. The controller refuses a name the swarm has already placed on a different hive; the same name on the same hive re-creates that agent.
|
||
|
||
###### **Options:**
|
||
|
||
* `--hive <HIVE>` — Hive in this swarm to deploy the agent to.
|
||
|
||
Required, and deliberately not defaulted: it's an *address* — the hive that gets the deploy message — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses.
|
||
* `--controller-socket <PATH>` — swarm-controller's unix socket.
|
||
|
||
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
|
||
|
||
|
||
|
||
## `swarmctl agent mint-identity`
|
||
|
||
Queue a re-mint of an existing agent's identity at the swarm's secret store.
|
||
|
||
**The backfill verb.** Agent creation is event-driven and nothing at swarm level sweeps for agents that are missing a credential, so an agent created before a credential joined the mint never receives one. This re-runs the mint for one agent that already exists.
|
||
|
||
⚠️ **It re-mints the agent's store certificate**, which that agent picks up the next time its container boots. It leaves an existing queue secret exactly as it stands, so running this against an already-migrated agent doesn't disturb its queue connection.
|
||
|
||
Queues and returns, the same way `agent create` does — watch the swarm UI's job view for the outcome.
|
||
|
||
**Usage:** `swarmctl agent mint-identity [OPTIONS] <NAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<NAME>` — Name of an agent that already exists
|
||
|
||
###### **Options:**
|
||
|
||
* `--controller-socket <PATH>` — swarm-controller's unix socket.
|
||
|
||
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
|
||
|
||
|
||
|
||
## `swarmctl agent mint-forge-token`
|
||
|
||
Check one agent's forge token, and mint it if it's missing or stale.
|
||
|
||
swarm-controller does this for every agent with a store identity at start and every five minutes; this is for when waiting isn't an option. It leaves a current token alone.
|
||
|
||
Queues and returns, the same way `agent create` does — watch the swarm UI's job view for the outcome.
|
||
|
||
**Usage:** `swarmctl agent mint-forge-token [OPTIONS] <NAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<NAME>` — Name of an agent that already exists
|
||
|
||
###### **Options:**
|
||
|
||
* `--controller-socket <PATH>` — swarm-controller's unix socket.
|
||
|
||
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
|
||
|
||
|
||
|
||
## `swarmctl user`
|
||
|
||
Manage subjects in the swarm's SSO provider
|
||
|
||
**Usage:** `swarmctl user <COMMAND>`
|
||
|
||
###### **Subcommands:**
|
||
|
||
* `add` — Add a user, generating a password for them
|
||
* `reset-password` — Set a new password for an existing user, generating it the same way `user add` does
|
||
* `update` — Change an existing user's attributes
|
||
* `list` — List every user in authelia's users database
|
||
|
||
|
||
|
||
## `swarmctl user add`
|
||
|
||
Add a user, generating a password for them
|
||
|
||
**Usage:** `swarmctl user add [OPTIONS] <USERNAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<USERNAME>` — Login name. Conservative ASCII only — it's a YAML map key and reaches access-control rules and logs
|
||
|
||
###### **Options:**
|
||
|
||
* `--display-name <TEXT>` — Name shown in the SSO UI. Defaults to the username
|
||
* `--email <ADDRESS>`
|
||
* `--group <GROUP>` — Repeatable
|
||
|
||
|
||
|
||
## `swarmctl user reset-password`
|
||
|
||
Set a new password for an existing user, generating it the same way `user add` does.
|
||
|
||
authelia's file store has no self-service reset (no SMTP notifier), so this is the only way a human account gets a new password once an operator forgets the old one. Refuses if the user doesn't exist — there's no separate "create" path here.
|
||
|
||
**Usage:** `swarmctl user reset-password <USERNAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<USERNAME>` — Login name of an existing user
|
||
|
||
|
||
|
||
## `swarmctl user update`
|
||
|
||
Change an existing user's attributes.
|
||
|
||
Every flag is optional and they compose, so one call can set multiple things at once. Deliberately **doesn't** touch the password: regenerating a credential is a different intent from editing an attribute, and folded together an attribute edit can invalidate a login by accident.
|
||
|
||
**Usage:** `swarmctl user update [OPTIONS] <USERNAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<USERNAME>` — Login name of an existing user
|
||
|
||
###### **Options:**
|
||
|
||
* `--display-name <TEXT>` — Name shown in the SSO UI
|
||
* `--email <ADDRESS>`
|
||
* `--add-group <GROUP>` — Repeatable. Adding a group the user is already in isn't an error
|
||
* `--remove-group <GROUP>` — Repeatable. Fails if the user isn't in the group — a revocation that reports success without revoking is the failure nobody re-checks
|
||
|
||
|
||
|
||
## `swarmctl user list`
|
||
|
||
List every user in authelia's users database.
|
||
|
||
Read-only: it never writes the file. Shows every subject in it, including agent identities `swarm-authelia-bridge` created — one line per user: username, display name, email (if set), groups (if any).
|
||
|
||
**Usage:** `swarmctl user list`
|
||
|
||
|
||
|
||
## `swarmctl forge`
|
||
|
||
Manage human accounts on the swarm's forge
|
||
|
||
**Usage:** `swarmctl forge <COMMAND>`
|
||
|
||
###### **Subcommands:**
|
||
|
||
* `make-admin` — Make an existing forge user a site admin
|
||
|
||
|
||
|
||
## `swarmctl forge make-admin`
|
||
|
||
Make an existing forge user a site admin.
|
||
|
||
The forge creates a human's account on their first SSO login, and this fails until that login has happened. Running it on a site admin changes nothing. Refused for an agent.
|
||
|
||
**Usage:** `swarmctl forge make-admin [OPTIONS] <NAME>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<NAME>` — Forge username, the same as the user's SSO username
|
||
|
||
###### **Options:**
|
||
|
||
* `--controller-socket <PATH>` — swarm-controller's unix socket.
|
||
|
||
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
|
||
|
||
|
||
|
||
## `swarmctl completions`
|
||
|
||
Generate a shell completion script for `swarmctl` and print it to stdout.
|
||
|
||
Supports bash, zsh, fish, elvish and powershell. The nix package already installs bash/zsh/fish system-wide; this is for ad-hoc or other-shell use.
|
||
|
||
Dispatched before `PathArgs::resolve()` for the same reason as `markdown-docs`: emitting a completion script needs none of the `SWARMCTL_AUTHELIA_*` deployment env vars, and requiring them would make the package's own build-time invocation fail.
|
||
|
||
**Usage:** `swarmctl completions <SHELL>`
|
||
|
||
###### **Arguments:**
|
||
|
||
* `<SHELL>` — Shell to emit completions for
|
||
|
||
Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`
|
||
|
||
|
||
|
||
|