RatelKey | Ratel Node

Install ratel-node on a host, connect it to your Burrow with a token, run it as a service, and keep it updated.

ratel-node is the agent your Burrow does work on a host through. It holds one connection open to your Burrow and carries out the instructions the Burrow sends it with code built into it. It comes with its own Java runtime, for Linux on x64 or arm64, macOS on Apple silicon or Intel, and Windows on x64.

It runs as a service under root, or SYSTEM on Windows, because the work it does is the host's own configuration. To register one with your Burrow, make a token on the Nodes page.

Install#

Download it into the folder it's to live in and unpack it. On Linux:

bash

curl -fsSL https://get.ratelkey.com/ratel-node/latest/ratel-node-linux-amd64.tar.gz | tar -xz
cd ratel-node

Each platform has its own archive, at https://get.ratelkey.com/ratel-node/latest/ followed by its name:

Platform	Archive
Linux, x64	`ratel-node-linux-amd64.tar.gz`
Linux, arm64	`ratel-node-linux-arm64.tar.gz`
macOS, Apple silicon	`ratel-node-darwin-arm64.tar.gz`
macOS, Intel	`ratel-node-darwin-amd64.tar.gz`
Windows, x64	`ratel-node-windows-amd64.zip`

Each archive's SHA-256 is at the same address with .sha256 added. On Windows, download the zip and extract it.

Connect it and run it as a service#

The service script installs ratel-node as a service that starts at boot. When the node isn't connected to a Burrow yet, it asks for a token first: paste the one from the Nodes page.

bash

sudo ./ratel-node-service.sh install

text

This node isn't connected to a Burrow yet.
Create a token on the Nodes tab in your Burrow, and paste it here.
Token:
Registering with https://burrow.example.com...
Connected to my-burrow as web-01.
ratel-node is running as a service, and starts at boot.

When your Burrow requires approval, setup says the node is registered and waiting for approval. Approve it on the Nodes page.

On Windows, run ratel-node-service.bat. It asks Windows for administrator rights, and its first option installs and starts the service.

The service runs as root, so its folder, and every folder above it, has to be one only root can change. Run from a folder others can change, such as a home folder, the script offers to move it to /opt/ratel-node on Linux or /usr/local/ratel-node on macOS, and carries on from there. On Windows it offers to copy it into Program Files\ratel-node.

The service script#

With no argument, the script shows the service's status and a menu. Each option is also a command:

Command	What it does
`install`	Connects the node if it isn't yet, then installs the service, or installs it again, and starts it.
`start`, `stop`	Starts or stops the service.
`status`	Says whether it's running, stopped or not installed.
`updates`	Chooses when it updates by itself.
`remove`	Stops the service and removes it. The folder and its data stay.

On Linux the service is systemd's ratel-node, and journalctl -u ratel-node -f follows it. On macOS it's a launchd daemon, and on Windows a service named RatelKey ratel-node.

In a script#

To connect a node without being asked, pass the token to setup, then install the service, which finds the node connected and asks nothing:

bash

sudo ./bin/ratel-node setup <token>
sudo ./ratel-node-service.sh install

On Windows, run ratel-node.bat setup <token> from a terminal opened as Administrator.

Updates#

The update script fetches the latest release, checks its signature and installs it, and the service restarts on the new version:

bash

sudo ./ratel-node-update.sh

sudo ./ratel-node-update.sh check only says whether a newer release exists, exiting with status 1 when one does. On Windows, run ratel-node-update.bat.

Every release is signed by RatelKey, and ratel-node checks the signature before anything is written. If the new version doesn't start, the previous one is put back.

Automatic updates#

ratel-node updates by itself once you choose when: Automatic updates in the service script's menu, or:

bash

sudo ./ratel-node-service.sh updates

It can update every 1 to 168 hours, or once a day at a time on the host's clock. sudo ./bin/ratel-node settings followed by every <hours>, daily <HH:MM> or off sets the same without a menu. The running node picks up a change within a minute.

The connection#

The node connects to the URL in its token and keeps the connection open, reconnecting by itself when it drops. A disabled node is refused until it's enabled, and a removed one from then on.

What it does on a host#

ratel-node carries out the instructions it has built in, when your Burrow sends them:

Instruction	What it does
SSH trust	Sets up the host's sshd to trust the certificate authorities attached to the node and refuse what they revoked, takes them off again when they're detached, and ends SSH sessions still open with a revoked certificate. On Linux with OpenSSH. See Certificate authorities.

A node removed from your Burrow takes everything the Burrow had it put on its host back off the next time it reaches the Burrow.

Its folder#

Everything ratel-node is lives in its folder, including its data: ratel-node/lib/app/data on Linux and macOS, and ratel-node\data on Windows. The data holds the node's key, which only root can read, or SYSTEM and Administrators on Windows, and its logs, under logs.

To take a node off a host, remove it on the Nodes page while it's connected, so it takes its SSH trust back off first. Then remove the service with sudo ./ratel-node-service.sh remove and delete the folder.