Enroll a computer
Add a computer to your organisation from its terminal, with or without a browser on it.
Enrolling a computer adds it to your Connect organisation, so its hubs and devices appear in Connect. The computer needs the Cambrionix Connect Suite installed and running.
Headless: one command with a code
Use this for servers, CI runners and anything else without a browser. Nobody signs in on the computer itself.
- In Connect, open Computers → Add a computer and choose Headless enrollment.
- Optionally give the computer a name. Without one, the CLI uses its host name.
- Choose Create enrollment command, pick the computer's operating system and copy the command.
- Run it on the computer. The page shows when the computer has joined.
The command installs the CLI from a signed link and enrolls the computer. It looks like this:
curl -LsSf '<signed install link>' | sh -s -- --enroll <code>$env:CAMBRIONIX_ENROLL_CODE='<code>'; irm '<signed install link>' | iexIf the CLI is already installed, run cambrionix-cli enroll --code <code> --yes instead.
The code starts with cbxc_ and includes the address of the Connect that created it, so a code from
staging enrolls into staging whichever Connect the CLI is configured for. --yes (or -y) answers
the one question enroll can ask: whether to leave an organization the computer already belongs
to. The install command passes it for you.
Enroll many computers
To enroll a fleet from provisioning scripts, cloud-init or Ansible, use an enrollment token instead of a code. One token works on any number of computers until it expires or you revoke it.
- In Connect, open Computers → Add a computer → Headless enrollment and choose Many computers.
- Choose how long the token lasts (7, 14 or 30 days) and choose Create enrollment token.
- Copy the token, and the install link for each operating system you use. Connect shows the token once. The install links work for as long as the token does.
Each computer needs the Cambrionix Connect Suite installed and running before it enrolls.
From a shell
Pass the token in the CAMBRIONIX_ENROLL_TOKEN environment variable. The installer hands it to the
CLI through the environment, so it never appears in the process list.
export CAMBRIONIX_ENROLL_TOKEN='<token>' curl -LsSf '<install link>' | sh -s -- --name build-07
$env:CAMBRIONIX_ENROLL_TOKEN='<token>'; irm '<install link>' | iexOn a computer that already has the CLI:
CAMBRIONIX_ENROLL_TOKEN='<token>' cambrionix-cli enroll --name build-07With Ansible
Encrypt the token with Ansible Vault and keep it with the install link in your group variables:
ansible-vault encrypt_string '<token>' --name cambrionix_enroll_token >> group_vars/cambrionix_hosts.yml echo "cambrionix_install_url: '<install link>'" >> group_vars/cambrionix_hosts.yml
This play installs the CLI where it's missing, then enrolls each host under its inventory name. Running it again changes nothing on hosts that have already joined.
- name: Enroll hosts into Cambrionix Connect hosts: cambrionix_hosts become: true vars: cambrionix_cli: /usr/local/bin/cambrionix-cli tasks: - name: Install the Cambrionix CLI ansible.builtin.shell: curl -LsSf '{{ cambrionix_install_url }}' | sh environment: CAMBRIONIX_CLI_UNMANAGED_INSTALL: /usr/local/bin args: creates: "{{ cambrionix_cli }}" - name: Enroll into Connect ansible.builtin.command: argv: ["{{ cambrionix_cli }}", "enroll", "--name", "{{ inventory_hostname }}", "--json"] environment: CAMBRIONIX_ENROLL_TOKEN: "{{ cambrionix_enroll_token }}" register: cambrionix_enroll changed_when: (cambrionix_enroll.stdout | from_json).changed
For Windows hosts, use ansible.windows.win_shell with irm '<install link>' | iex to install the
CLI. Then run cambrionix-cli enroll --json with the same environment.
With cloud-init
#cloud-config runcmd: # Install the Cambrionix Connect Suite first, then: - curl -LsSf '<install link>' | CAMBRIONIX_ENROLL_TOKEN='<token>' sh
Re-running, moving and revoking
- Already joined: a computer already in the token's organisation is left as it is.
enroll --jsonprints"changed": false. - In another organisation: enrolling fails, so a play never moves a computer by accident. Add
--replace --yesto move it. - Revoking: revoke a token under Active enrollment tokens on the same page. Computers that
already joined stay enrolled. To remove one, run
cambrionix-cli unenrollon it or delete it in Connect.
With a browser
Run cambrionix-cli enroll (or cambrionix-cli tui for the interactive screen).
The CLI prints a link and a QR code and opens your browser. Approve the computer there, or scan the
QR code and approve it on your phone. Add --no-browser on a computer without a desktop.
Moving a computer to another organisation
A computer belongs to one organisation at a time. If it's already enrolled, enroll asks before
leaving the current organisation; pass --replace to leave without asking. The CLI only leaves
the old organisation once it has the new invite, so a mistyped or expired code never leaves the
computer without an organisation.
cambrionix-cli enroll --code <code> --replace --yes cambrionix-cli unenroll # leave without joining another organisation
Scripting
enroll --json prints the result for provisioning tools:
{ "changed": true, "organizationId": "7c9e6679-7425-40de-944b-e07fc1f99a3d", "computerId": "35aea4bc-44d3-4e9e-9b3c-c33b965c5639", "serviceId": "36d5a398-e3ef-55f9-8b09-ba6351511464", "name": "build-07" }
changed is false when a token's computer had already joined. The code can also come from the
CAMBRIONIX_ENROLL_CODE environment variable, and a token from CAMBRIONIX_ENROLL_TOKEN. Both keep
the secret out of shell history and process lists.
Troubleshooting
| Message | What to do |
|---|---|
Relay API is not reachable | Install or start the Connect Suite, then run cambrionix-cli services list. |
No invite for this code | The code was used, expired or came from another Connect. Create a new command in Connect. |
this computer is already enrolled | Add --replace to move it to the new organisation. |
that isn't an enrollment token | Copy the whole token, starting cbxe_, from Many computers. |
joining the organization failed with a token | The token expired or was revoked. Create a new one. |
install.sh: error: unknown option | The install script predates CLI 0.2.1. Copy a new command or token from Connect. |
| Anything else | Run cambrionix-cli doctor, then cambrionix-cli support bundle --preset enrollment for support. |