Commissioning Machines

Prerequisites and Roles

A machine cannot sign itself up to your network. Instead, you commission each machine in advance in the console. The guardian creates the machine's identity and signs its credential, and the machine's operator receives one file: the manifest.

Before you commission a machine, check the following:

• You have the manager or admin role.
• The realm credential is in place. Until it is, the guardian refuses to commission machines, and the console shows the steps to put the credential in place.
• The signer is running. While it is down, the Commission and sign button is greyed out and the console shows this banner: “The signer keeps failing. Nothing can be commissioned and no node can renew while it is down.”

The realm you commission a machine into decides its role, so you never choose the role yourself.

Commissioning a Machine

The Manifest

The manifest is a single base64 file that defines the machine. Anyone who holds it can act as that machine and keep its credential current. It contains:

• The machine's identity seed and its credential.
• The bootstrap list, with your bootstrap nodes first.
• The address the machine renews at, and the secret it renews with.
• A collector credential for telemetry, separate from the renewal secret, and the export settings.
• The machine's overlay address, its taints and the ID of its realm.

The manifest never contains a power, so no machine can block, move or reconfigure another. The guardian also tells browsers and caches not to store a copy.

Taints and Compartments

A taint is a label that places a machine in a compartment inside its realm. The taints you commission a machine with are part of its credential, and every renewal keeps them. A machine with no taints sits in the realm's default compartment.

An admin can later move a running machine to other compartments with Compartments on the machine's panel. Every member of the realm then treats the machine as being in the new compartments. The credential keeps the commissioned taints, so a machine rebuilt from its manifest starts in those again.

The panel's Taints row shows which set applies. It reads office · as commissioned, or it shows the new set and when the machine was moved. See Moving Between Compartments.

Bootstrap Nodes

Bootstrap nodes are your own publicly reachable machines, and every other machine starts from them. Commission them into the guardian realm before any other machine.

• Give each bootstrap node the host:port it listens on. Every machine you commission must be able to reach that address. The guardian host does not listen for them.
• Every manifest lists the bootstrap nodes. When you commission or revoke one, new manifests get the new list, and deployed machines get it at their next renewal.
• The admin nodes reach your network through the bootstrap nodes, so they have nothing to connect to until you commission the first one. After any change to the list, each admin node restarts with the new list at the next round.

After Commissioning

After commissioning, the machine renews its own credential through the guardian, and you manage it from its panel. The panel's footer offers these actions, depending on your role:

Renewal needs no action from you. See Renewal.

To remove the machine, revoke it. To shut it out at once, block it as well. See Revocation and Blocks.