Agent Setup

This section assumes that You have installed the Hotrod binary, and that Hotrod Server is configured and running.

Setting up a new Hotrod agent involves:

1. Creating an agent identifier and API key for it on Hotrod Server
2. Creating a data directory
3. Creating a systemd unit file to manage the process
4. Starting the agent

note

The evaluation license only allows 2 agents. When using Hotrod Server in stand-alone mode, it's internal agent will count towards that limit.

Generate an API key

We need to pre-configure an identifier and API key for the agent before it can connect to Hotrod Server. This can be done either via the UI, or hotrod's CLI interface.

Via Hotrod UI

Log in to Hotrod Server's web interface. Navigate to Agents in the top navigation, then select New Agent.

Create a new agent with a specified name and identifier.

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

note

Agent identifiers must be unique, and may contain only ascii letters, numbers, periods (.) and hyphens (-).

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

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

note

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

Via Hotrod CLI

Similar to using the UI, adding an agent via Hotrod CLI is a two-step process.

note

Hotrod CLI is an interface to Hotrod Server's HTTP API.

By default, the CLI assumes a Hotrod Server is running on localhost:3000.

A HOTROD_URL environment variable instructs the Hotrod CLI where to locate the Hotrod Server HTTP API.

If You changed the default bind address of Hotrod Server's HTTP API, set an environment variable:

export HOTROD_URL=http://localhost:3000

Authenticate against Hotrod Server using:

hotrod login admin

note

On your first interaction with Hotrod CLI, you will be prompted to accept the End User License Agreement. Press enter to scroll through the EULA, and follow the prompts.

After providing the password correctly, you should see Login successful.Then add the new agent:

hotrod agents add agent3 --id agent3

And lastly, create an associated API key:

hotrod api-key issue agent3

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

Copy the key value for later use.

note

The names used to identify API keys are unrelated to agent identifiers. We're using agent1 for both, as a practical convention.

Create a system user and group

If they do not yet exist, create a system user and group under which the agent will be executed:

adduser --system --home /home/hotrod --disabled-login --group hotrod

Warning

Do not run Hotrod Agent with root privileges. The agent runtime can execute pipes with exec inputs, which can execute arbitrary commands on the host.

Create a data directory

A Hotrod Agent requires a data directory to store pipe definitions and some state information.

Create a data directory with appropriate ownership:

mkdir /var/lib/hotrod-agent1
chown -R hotrod:hotrod /var/lib/hotrod-agent1

Setup systemd service

Create a systemd unit file. Since each agent process must have a unique name, we'll name this agent as hotrod-agent1.

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

Hotrod Agents are configured through either command line flags or environment variables. We'll be using the latter.

At minimum, a Hotrod Agent needs:

• A unique agent ID (HOTROD_AGENT_ID).
• An API key to authenticate against a Hotrod Server (HOTROD_AGENT_API_KEY).
• The network location of the Hotrod Server that will manage it (HOTROD_URL).
• A working 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 two should be mentioned here:

• HOTROD_AGENT_POLL_INTERVAL determines how often the agent will update it's Hotrod Server. Default: 15 seconds.
• HOTROD_AGENT_LISTENER determines which host IP and port the agent will listen on for internal updates. Default: 127.0.0.1:4040

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

note

It's possible to co-locate one or more agents on the same host that runs Hotrod Server. Note that when Hotrod server is started with it's own internal agent (hotrun run stand-alone), the internal agent will use port 4040 on the host. This means that co-located agents on the same host must be configured to listen on different ports.

We'll specify the agent's configuration in the unit file, as follows:

[Unit]
Description=hotrod-agent1

[Install]
WantedBy=multi-user.target

[Service]
User=hotrod
Group=hotrod
Restart=on-failure
ExecStart=hotrod run agent --agent-pipe-scheduler

Environment=HOTROD_AGENT_ID=agent1
Environment=HOTROD_AGENT_POLL_INTERVAL=15
Environment=HOTROD_URL=http://localhost:3000
Environment=HOTROD_PIPES_DIR=/var/lib/hotrod-agent1
Environment=HOTROD_AGENT_API_KEY=F4177-AM9PZIEW7MPI7IL28ERE
Environment=HOTROD_LICENSE_EULA_ACCEPT=yes
Environment=HOTROD_AGENT_LISTENER=127.0.0.1:4041

At minimum, you should change HOTROD_AGENT_API_KEY to match the key you previously created.

We've added an additional environment variable:

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

note

The value of HOTROD_AGENT_ID should match the agent identifier previously configured on Hotrod Server.

Once you have saved the unit file, reload systemd's unit definitions:

systemctl daemon-reload

To start the agent at system boot, we enable the service with:

systemctl enable hotrod-agent1

Finally, start Hotrod Server:

systemctl start hotrod-agent1

And verify that it started started successfully:

systemctl status hotrod-agent1

journalctl -u hotrod-agent1

If there were no startup issues, a Hotrod Agent should now be running. It will register itself with it's configured Hotrod Server, using the specified API key.

The server's front end should indicate the agent status on the dashboard. Alternatively, you can inspect the agent status via Hotrod CLI:

hotrod agents list

At this point, the agent is ready to receive pipes via Hotrod Server, and execute them.