diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 5cd7908..195fc9f 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -81,6 +81,27 @@ When the user's value is inside the range, it stands: `12 (app, machine policy r `policy set appSettings.plugins.overrides` fails with exit code 3: it can't be locked, use `plugins.enabled` and `plugins.disabled`. A range with nothing allowed (`--min 25 --max 30` on the lifetime) fails with exit code 3 and `leaves no allowed value`. +### `enroll` + +Enrols this machine in a company's Voltius team. It writes the [enrolment token](../teams/enrollment-tokens.md) into the machine policy, and Voltius asks people to sign in to the team at the next launch. Writing needs root (sudo) or Administrator. + +| Command | What it does | +|---|---| +| `enroll ` | Check the token with its server, then write it | +| `enroll --no-verify` | Write it without asking the server. For image builds with no network | +| `enroll --show` | Print the team, server and the first 8 characters of the token id, never the secret. Checks the server unless you add `--no-verify` | +| `enroll --remove` | Remove this machine's enrolment | + +```text +$ sudo voltius-cli enroll "vte1.…" +Enrolled this machine in Acme (voltius.acme.com). Voltius asks people to sign in at next launch. +``` + +- Running it again with the same token writes nothing and prints `Already enrolled in Acme (voltius.acme.com).` +- If the server can't be reached and the token is already set, it prints `Already enrolled`, says it couldn't check, and exits 0. With a new token, an unreachable server is exit code 5. +- A token that isn't recognised, was revoked or has expired, or whose team's plan has lapsed fails with exit code 3 and writes nothing. So does a token for a server other than the one `server.url` locks this machine to. A malformed token is exit code 2. +- With `--json`, `enroll ` prints `{"changed": true, "team": "Acme", "server": "https://voltius.acme.com"}`. `team` is `null` with `--no-verify`. Use `changed` for Ansible's `changed_when`, see [Enrolment tokens](../teams/enrollment-tokens.md#enrol-a-fleet). + ### `config` | Command | What it does | diff --git a/docs/reference/machine-policy.md b/docs/reference/machine-policy.md index ecd6e40..a827937 100644 --- a/docs/reference/machine-policy.md +++ b/docs/reference/machine-policy.md @@ -45,6 +45,7 @@ When several layers set a key, the first of these wins: machine policy, then the | `server.allowOther` | bool | `false` blocks accounts on any other server. Scheme, host, port and path must match `server.url`, so `https://api.acme.com` does not admit `http://acme.com` or `https://www.acme.com` | | `server.previousUrls` | list of URLs | Addresses `server.url` used to have. Locked only. See [Moving the server](#moving-the-server) | | `sshConfig.import` | bool | The `~/.ssh/config` import switch | +| `enrollment.token` | string | An [enrolment token](../teams/enrollment-tokens.md). Locked only, never under `defaults`. Write it with `voltius-cli enroll`. Voltius asks people on the machine to sign in to the token's team | | `plugins.install` | list of plugin ids | Locked: installed and can't be removed. Default: installed once, users may remove it | | `plugins.enabled` / `plugins.disabled` | list of plugin ids | Forced on / off (locked), or turned on / off once (default) | | `plugins.allowInstall` | bool | `false`: users can only install plugins listed in `plugins.install`. Updates of installed plugins still work | @@ -63,6 +64,8 @@ When several layers set a key, the first of these wins: machine policy, then the Only the keys with a Range entry accept a [range](#ranges). `voltius-cli policy check` rejects unknown keys, wrong types, values outside a key's domain (a locale that doesn't exist, a TTL of 5) and `appSettings.plugins.overrides` under `policy`. Voltius itself ignores unknown keys, so a newer policy file still works on an older Voltius. +The token file can be world-readable like the rest of the policy: a token identifies your server and team, but it doesn't decrypt anything, and the server decides who joins. See [Enrol a fleet](../teams/enrollment-tokens.md#enrol-a-fleet). + Plugin keys take the **plugin id** (`plugin-docker`), not the folder name. In **Settings → Plugins**, a plugin installed through `plugins.install` carries an **Organization** badge. When `plugins.allowInstall` is `false`, the Browse tab says installing is turned off and only the listed plugins can be installed. diff --git a/docs/teams/enrollment-tokens.md b/docs/teams/enrollment-tokens.md index ff0ee91..c133d32 100644 --- a/docs/teams/enrollment-tokens.md +++ b/docs/teams/enrollment-tokens.md @@ -45,9 +45,67 @@ The section also shows when the token was last used and how many people are wait ## Using a token -In this release, admins can create tokens and decide join requests. The ways to use a token arrive in a later release: `voltius-cli enroll ` to enrol a machine from the command line, and a first-launch screen in the app. Until then, keep the token for your rollout and invite people individually. +There are three ways to hand a token to people. With a token, sign-up works even when the server has sign-up closed. Each token allows up to 500 sign-ups a day, so rolling out from one office address is fine. -With a token, sign-up works even when the server has sign-up closed. Each token allows up to 500 sign-ups a day, so rolling out from one office address is fine. +- **Machines you manage.** Run `voltius-cli enroll` on each one. See [Enrol a fleet](#enrol-a-fleet). +- **A link.** Next to the token, shown once after you create it, **Copy link** copies a link you can email or post. Opening it in Voltius starts the join. Anyone who has the link can ask to join, as with the token itself. +- **The token itself.** People paste it into Voltius. See [What people see](#what-people-see). + +## Enrol a fleet + +Run `voltius-cli enroll` as root or Administrator on each machine. It writes the token into the [machine policy](../reference/machine-policy.md) as `enrollment.token`. The next time Voltius starts on that machine, it asks the person to sign in to your team. + +```sh +sudo voltius-cli enroll "vte1.…" +``` + +By default the command asks your server to check the token first and prints the team name. Running it again with the same token changes nothing. See [`enroll` in the command line reference](../reference/cli.md#enroll) for the options and exit codes. + +With Ansible, `--json` reports whether the file changed: + +```yaml +- name: Enrol this machine in the company Voltius team + ansible.builtin.command: voltius-cli enroll "{{ voltius_enrollment_token }}" --json + become: true + register: voltius_enroll + changed_when: (voltius_enroll.stdout | from_json).changed +``` + +Keep `voltius_enrollment_token` in Ansible Vault or your secrets store. The token can't decrypt anything, but anyone who has it can ask to join. + +When you build a machine image without network access, add `--no-verify` to write the token without asking the server. The server checks it when someone first uses it. + +If the machine's policy locks `server.url` to a different server than the token's, the command refuses. Use the token from the locked server. + +To enrol every machine and also lock your server, set both: + +```sh +sudo voltius-cli policy set server.url https://voltius.acme.com +sudo voltius-cli enroll "vte1.…" +``` + +Rotating or revoking the token doesn't remove it from machines. Run `voltius-cli enroll` with the new token, or `voltius-cli enroll --remove`. + +## What people see + +**First launch.** On a machine with a token, a new person sees **Sign in to ** instead of the generic welcome screen. The server is your organization's and can't be changed here. They create an account or sign in with their email, and the join request is sent. If the token has domains, the form says which email to use. **Skip for now** is always there. + +**A link.** Opening the link shows the team and the server, and asks first: *Only continue if your company sent you this link.* Nothing is sent until they continue. Then they get the same form. People who are already signed in to that server can join with the account they have, or use another one. + +**A pasted token.** On the first-launch screen, **Have an enrolment token?** opens a field for it. The same confirm step appears. Tokens written by `voltius-cli enroll` don't ask, because an administrator of the machine put them there. + +If a person skipped, or you enrol a machine later, a notification says **Your organization uses on Voltius**, with **Sign in**. + +After they submit, the screen says what happens next: + +| Result | What they see | +|---|---| +| Admitted | **You're in .** Team vaults appear once an admin's Voltius is online. | +| Waiting for approval | **Request sent.** An admin approves it and they get a notification. | +| Email not verified | **Verify your email to join.** They join automatically once they click the link, and can use **Resend email**. | +| No free seat | ** has no free seat.** An admin has been notified. | + +The same status stays in their notifications until it resolves: waiting for approval, verify your email, or **You joined ** once an admin approves. If an admin denies the request, the notification says the team declined it. On a machine with a token, **Ask again** sends a new request. ## How people are admitted