baastide agent enroll

Enroll this machine in BaaStide

Synopsis

The "enroll" command exchanges an enrollment token, created in the BaaStide portal, for a durable agent identity. The token is single use, or a deployment token that enrolls many machines, each with its own identity. The identity is written to /etc/baastide/agent.conf (mode 0600): run it as root. On Windows it is written to %ProgramData%\BaaStide\agent.conf, readable by SYSTEM and Administrators only: run it as administrator.

An existing identity requires --force. After replacement, the service is restarted. Use --no-restart only when managing the daemon yourself.

Give the token with one of:

  --token-file <file>          read it from a file
  --token -                    read it from stdin
  BAASTIDE_ENROLL_TOKEN=<token> environment variable

"--token <token>" still works, but it puts the token in the process list and in the shell history: prefer the options above.

Without --server, the agent enrolls in the BaaStide SaaS. Use --server only for an on-prem instance. --server is the root URL of the instance, the same value as for install.sh (for example https://backup.example.com, not https://backup.example.com/api).

The agent pins the CA of the control channel. In the SaaS, the pins compiled in the binary also protect the enrollment itself. With --server, the first contact (this command) is protected by TLS only: check the URL and the network. The server then gives its CA pins (ca_fingerprints), written to the identity file, and every later connection checks them.

The agent sends the id of the machine (Windows MachineGuid, Linux /etc/machine-id or /var/lib/dbus/machine-id). The server refuses a machine already enrolled for the same client: a cloned VM must get a new id first (sysprep /generalize on Windows, systemd-machine-id-setup on Linux). Without an id, the agent enrolls with a warning.

A refusal is not retried: already enrolled machine, deployment token used up, revoked or expired, or network address not allowed by the token.

Exit status

Exit status is 0 if the machine is enrolled. Exit status is 1 if there was any error, including a refusal of the server.

baastide agent enroll [--token-file <file> | --token -] [--server <url>] [flags]

Examples

  # Enroll in the BaaStide SaaS with a token saved in a file
  baastide agent enroll --token-file /root/baastide-token

  # Read the token from stdin
  baastide agent enroll --token - < /root/baastide-token

  # Enroll again in an on-prem instance, replacing the current identity
  baastide agent enroll --token-file /root/baastide-token --server https://backup.example.com --force

Options

      --config file       agent identity file to write (default "/etc/baastide/agent.conf")
      --force             replace an existing identity
  -h, --help              help for enroll
      --no-restart        leave service restart to the caller
      --server url        BaaStide API url (on-prem only, default: the BaaStide SaaS)
      --service string    service to restart after replacing the identity (default "baastide.service")
      --token token       enrollment token from the BaaStide portal, "-" to read it from stdin
      --token-file file   read the enrollment token from file