Agent Setup

This section assumes that you have installed the HOTROD executable, and that the Server is in fact configured and running.

note

For the current deployment scenario, the Server and external Agents do not share a single host. Should you require the above, additional security precautions need to be taken. For example: separate system accounts for the Server and Agent need to be created. Contact support to learn more.

Set up a new Agent as follows:

1. Create an Agent ID and API key on the Server.

2. Create a data directory.

3. Creat a systemd service unit file

4. Start the Agent

note

The evaluation license allows 1 external Agent.

Generate an API key

An Agent ID and API key are required for the Agent before it can connect to the Server. This can be done either via the web-based UI or the CLI.

Via web-based UI

Log in to the Server. Go to Agents in the top navigation, then select NEW AGENT.

Create a new Agent with a specified name and ID.

The Agent name is a human-readable designation (a label), while the Agent ID will be used in the Agent configuration.

note

An Agent ID must be unique, and may contain only ASCII letters, numbers, periods (.), and hyphens (-).

Next, create an API key for the Agent. Go to Manage > Keys in the top navigation.

Then create a name for the new API key, select Add and copy the key value for later use.

note

Key names must be between at least 5 and 50 characters in length and comprised solely of letters, numbers, dashes, and hyphens.

Via the CLI

Adding an Agent via the CLI is a two-step process, much like the method above that uses the web-based UI.

note

The CLI is a wrapper to the Server HTTP API. By default, the CLI assumes a Server is listening on http://localhost:3000. A HOTROD_URL environment variable instructs the CLI where to locate the Server HTTP API.

If you changed the default bind address of the Server, set HOTROD_URL, for example:

$> export HOTROD_URL="http://localhost:4000"

Log in to the Server:

$> hotrod login admin

note

On your first interaction with the CLI, you'll be prompted to accept the EULA. Press Enter to scroll through the EULA and follow the prompts.

After providing the password, you will see Login successful. Then add the new Agent:

$> hotrod agents add agent1 --id agent1

Lastly, create an associated API key:

$> hotrod api-key issue agent1

API-KEY(agent1;api_read;default) F4177-AM9PZIEW7MPI7IL28ERE

Remember

Copy the key value (F4177-AM9PZIEW7MPI7IL28ERE) for later use.

note

The API key name is unrelated to an Agent ID. For simplicity, we're using agent1 for both.

Create a system account

Create a system account under which the Agent will run:

adduser --system --home /var/lib/hotrod-agent --disabled-login --group hotrod

danger

Do not run the Agent with root privileges. The Agent can execute Pipes with exec inputs, which in turn can execute arbitrary commands on the host.

Create a data directory

An Agent requires a data directory to store Pipe definitions and some state information.

The hotrod user home directory is /var/lib/hotrod-agent and it will also serve as the data directory.

:::security Secure environments require 0700 permissions on the data directory! :::

If a different data directory is required, create it with the appropriate ownership and permissions. For example:

$> sudo mkdir /data/hotrod

$> sudo chown hotrod:hotrod /data/hotrod

Create systemd Files

Create a systemd service unit file:

vi /etc/systemd/system/hotrod-agent1.service

The file must contain the following:

[Unit]
Description=Hotrod Agent
After=network.target auditd.service

[Service]
EnvironmentFile=/etc/default/hotrod-agent
User=hotrod
Group=hotrod
ExecStart=/usr/sbin/hotrod run agent
Restart=on-failure
RestartSec=60

[Install]
WantedBy=multi-user.target

Create an environment file for the EnvironmentFile setting:

$> sudo vi /etc/default/hotrod-agent

Here, the Agent is configured through either hotrod run agent options or environment variables. In this case, we'll be using the latter.

tip

See hotrod run agent --help for startup options and their environment variable equivalents and the reference.

At a minimum, the Agent needs to know:

• A unique Agent ID (HOTROD_AGENT_ID).

• An API key to authenticate against a Server (HOTROD_AGENT_API_KEY).

• The Server URL (HOTROD_URL).

• A data directory to store Pipe definitions and other state data (HOTROD_PIPES_DIR).

• Which Pipe scheduler mechanism to use (internal, or systemd if available).

Additional configuration options are optional, but three should be mentioned here:

• HOTROD_AGENT_POLL_INTERVAL determines how often the Agent will poll the Server to check for updates. Default: 15 seconds..

• HOTROD_AGENT_LISTENER determines which address and port the Agent will listen on for internal updates. Default: 127.0.0.1:4040.

• HOTROD_LICENSE_EULA_ACCEPT=yes prevents the one-time prompt for accepting the End User License Agreement.

note

It's possible to co-locate one or more agents on the same host with the Server. When the Server is started with the built-in Agent (hotrun run server), the built-in Agent will bind to port 4040 on the host. This means that co-located Agents on the same host must be configured to listen on different ports.

Therefore, the file should contain the following:

HOTROD_AGENT_ID=agent1
HOTROD_AGENT_API_KEY=F4177-AM9PZIEW7MPI7IL28ERE
HOTROD_PIPES_DIR=/var/lib/hotrod-agent
HOTROD_URL=http://<server>:3000
HOTROD_LICENSE_EULA_ACCEPT=yes

Change the HOTROD_AGENT_API_KEY to match the key you previously created.

Change the HOTROD_URL to the Server address or hostname (confirm that your DNS is configured).

note

The value of HOTROD_AGENT_ID should match the Agent ID previously configured on the Server.

Once you have saved the service unit file, reload systemd:

$> sudo systemctl daemon-reload

To start the Agent at boot, enable the service with:

$> sudo systemctl enable hotrod-agent

Finally, start the Agent:

$> sudo systemctl start hotrod-agent

Verify that the Agent started successfully:

$> systemctl status hotrod-agent

It's a good idea to inspect the startup output, which might contain an error or warn:

$> journalctl -u hotrod-agent

An Agent should now be running. It will register with the Server, using the specified API key.

The Server should indicate the Agent status on the Dashboard. Alternatively, you can inspect the Agent status on the Server:

$> hotrod agents list

At this point, the Agent is ready to run received Pipes from the Server.