A node is an agent for your Burrow on one of your hosts: ratel-node, running there as a service. It holds a connection open to your Burrow and carries out the instructions the Burrow sends it, with code built into it. Today that's setting up its host to trust the certificate authorities attached to it.
Add a node#
Open Nodes and select the
+at the top right of the table.Name the node, or leave the name empty to give it its host's name.
Pick the URL the node reaches your Burrow at. The list is the one a machine invitation offers, custom domains included.
Choose the Connection, described below, and select Create token.
Copy the token. On the host, install ratel-node and run its service script, which asks for it.
The token works once, and expires after the invitation expiry set under Settings, Security.
Connection#
Connection sets how the node checks that it reached your Burrow.
Connection | What it does |
|---|---|
Encrypted | The connection is encrypted, but the Burrow's identity isn't checked. Works everywhere, including behind a tunnel or proxy. This is the default. |
Encrypted + verified | The node checks your Burrow's identity, so nothing can impersonate it. Recommended. |
For a URL with a name on a Burrow that serves its own certificate, Encrypted + verified asks one more thing, Verify by: Burrow identity when the node reaches the Burrow directly, or System trust when a proxy or CDN in front of it presents its own certificate.
Tokens you haven't used yet#
Outstanding tokens are listed under Active Node Invitations below the nodes table, with when they were made and when they expire. Their row menu carries Show token, which gives back the token with the URL and connection it was made with, and Revoke, which cancels it.
Approval#
With Require machine & node approval on, a new node arrives with a Pending tag. It does nothing on its host until a member selects Approve from its row menu.
The nodes table#
Each row shows the node's name, its host's name and operating system, whether it's enabled, and when it was last heard from, in your Burrow's time format. The dot after the name is its connection:
Dot | Meaning |
|---|---|
Green, pulsing | Connected. |
Amber, pulsing | Connected, and its last instruction failed or got no answer. |
Red | Offline after a problem with its connection. |
Grey | Offline, or disabled. |
Point at the dot for what it means, since when, and the problem in full.
Manage a node#
Action | What it does |
|---|---|
Approve | Lets a pending node take instructions. |
Rename | Changes the node's name in your Burrow. Nothing changes on the host. |
Audit logs | Shows the node's own trail, to members who can read the audit log. |
Disable, Enable | Disabling ends the node's connection, and your Burrow refuses it until it's enabled. |
Remove | Detaches the node from its CAs and ends its connection, which is refused from then on. The node takes everything your Burrow had it put on its host back off. |
Audit log#
Each node's tokens, connections and instructions are recorded in your audit log, and each event can be sent to a webhook. A node's entries show its ratel-node version.
Event | Code | Severity |
|---|---|---|
Nodes listed |
| Info |
Node token made |
| Notice |
Node token shown again |
| Notice |
Node token revoked |
| Notice |
Node registered with a token |
| Notice |
A registration refused, with why |
| Warning |
Node approved |
| Notice |
Node disabled |
| Warning |
Node enabled |
| Notice |
Node renamed |
| Notice |
Node removed, with the CAs it was detached from |
| Warning |
Node connected |
| Info |
Node disconnected, with how |
| Info |
A connection refused. The same refusal again within the hour is counted on the next entry. |
| Warning, High when it may not have come from the node |
Node reported a new version, host name or platform |
| Info, Warning when its platform changed |
An instruction sent, and how the node answered it, with what it changed on its host |
| Info, Warning when it couldn't carry it out or didn't answer |