vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
hyperhive/docs/tools/swarmctl-cli.md
atlas 1442168715 swarmctl: re-mint an existing agent's store identity 
Agent creation at swarm level is event-driven and nothing sweeps for
agents missing a credential, so an agent created before a credential
joined the mint never receives one -- nothing comes back around to it.
Without a way to re-run the mint by hand, the only route to giving an
existing agent its queue credential would be to delete and recreate the
agent.

POST /api/agents/{name}/identity enqueues the same MintAgentIdentity
node POST /api/agents declares, rather than writing inline: a second
code path that mints an identity is a second place for the four strings
that have to agree to disagree. swarmctl agent mint-identity is the
operator end, the same POST-and-print-the-node-id shape agent create
already has.

--hive is required on both ends. Neither the CLI nor the controller
keeps a roster of which agent runs where, and the credentials this mints
name a hive, so a default would be a guess that hands an agent subjects
on a hive it does not run on.

Documents the backfill as a runbook step, and fills in the renewal cell
the credential matrix requires for the new row.
2026-09-21 20:38:55 +02:00

7.1 KiB
Raw Blame History

Command-Line Help for swarmctl

This document contains the help content for the swarmctl command-line program.

Command Overview:

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
  • 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

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.

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. The agent's queue secret is left exactly as it is if it already has one, so running this against an already-migrated agent does not 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] --hive <HIVE> <NAME>

Arguments:
  • <NAME> — Name of an agent that already exists
Options:

  • --hive <HIVE> — The hive that agent runs on.

    Required, and deliberately not defaulted: the credentials this mints name a hive, and neither this CLI nor the controller keeps a roster of which agent is on which hive. Naming the wrong one gives the agent an identity scoped to a hive it does not run on. The controller checks the value 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 user

Manage subjects in the swarm's SSO provider

Usage: swarmctl user <COMMAND>

Subcommands:
  • add — Add a user, generating a password for them
  • 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 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 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