Hotrod Setup With systemd
This is helpful for testing locally.
hotrodd setup
Run the following as root
-
Prepare for hotrodd installation
mkdir --parents /usr/local/var/hotrodd
-
Create systemd unit file for hotrodd
cat > /etc/systemd/system/hotrodd.service << EOF [Unit] Description=Hotrod daemon After=network.target Wants=network.target [Service] Environment=HOTROD_JWT_PSK=secret Environment=HOTROD_TLS_CERT=/usr/local/var/hotrodd/cert.crt Environment=HOTROD_TLS_KEY=/usr/local/var/hotrodd/cert.key Environment=HOTROD_STAGING_DIR=/usr/local/var/hotrodd Environment=HOTROD_AUTH_DB=/usr/local/var/hotrodd/auth.db Environment=HOTROD_BIND_ADDRESS=0.0.0.0:3000 Environment=HOTROD_TARGETS_SYSTEM_SLS=/usr/local/var/hotrodd/system.sls Environment=HOTROD_LOG=audit=info,hotrodd=warn Restart=on-failure ExecStart=/usr/local/bin/hotrodd [Install] WantedBy=multi-user.target EOF
Environment variables accepted by hotrodd
Note that the following are also available as command line options, where, for example,
HOTROD_JWT_PSK=secret hotrodd
would be equivalent tohotrodd --jwt-psk secret
. Have a look athotrodd --help
.-
HOTROD_JWT_PSK
Hotrod uses AES256 Symmetric key encryption for it's authentication tokens (JWT). Use this environment variable to set a pre-determined key. If not specified, a random key will be generated every time
hotrodd
restarts. -
HOTROD_TLS_CERT and HOTROD_TLS_KEY
A pair to use if you want to use hotrodd via TLS (https). Note that these will have to be generated beforehand.
Example:
openssl req \ -new \ -newkey rsa:2048 \ -sha256 \ -days 1000 \ -nodes -x509 \ -keyout /usr/local/var/hotrodd/cert.key \ -out /usr/local/var/hotrodd/cert.crt \ -subj '/CN=hotrod/O=SomeCompany Self-Signed/C=ZA'
If these are not provided, a cleartext connection will be created, suitable only for use inside trusted environments or for testing.
-
HOTROD_STAGING_DIR
Specify a path to the staging directory that should be used for
hotrodd
. The staging directory is used byhotrodd
for all runtime configurations. If not specified, the current working directory will be used. -
HOTROD_AUTH_DB
This can be used to override the path and filename of the Hotrod credentials database. If not specified, a file named
hotrod_auth.db
will be created in the current working directory. -
HOTROD_BIND_ADDRESS
Socket address to bind to, default being 127.0.0.1:3000.
-
HOTROD_TARGETS_SYSTEM_SLS
Used to specify a path to a
system.sls
file. -
HOTROD_JWT_EXPIRY_MINS
Specify the number of minutes that a JWT issued by
hotrodd
may be valid. The default value is60
. -
HOTROD_LOG
Controls how much logging should happen
NOTE: This setting applies to all Hotrod executables.
Possible values:
- error
- warn
- info (the default)
- debug
- trace
-
Command Line Interface (CLI) setup
Run the following as normal user
-
Setup some environment variables
export HOTROD_TLS_INSECURE=true export HOTROD_URL https://localhost:3001
If plain text conenction is preferred, only set variable for
$HOTROD_URL
. -
Look at output of hotrodd service, and get password from there
journalctl --unit hotrodd
-
Use above pasword to login to hotrodd
$ hotrod login admin ...
-
Create an API key, to be used by
hotrod-agent
hotrod api-key issue agent
-
Add a Target
hotrod targets add test
This Target will be associated with the agent we will setup later on in this document.
-
Run a basic command
$ hotrod targets list name | id | tags | pipes | last seen -------+--------------------------------------+------+-------------+----------- test | 3e067214-76d7-4bce-a6a9-2e282bf7ccd7 | | |
Environment variables accepted by hotrod CLI
-
HOTROD_URL
This needs to be set to the remote instance of
hotrodd
. The CLI will cache JWT authentication tokens for each uniqueHOTROD_URL
in order to facilitate management of multiplehotrodd
instances.The default value is
http://localhost:3000
-
HOTROD_TLS_INSECURE=true
Set this environment variable to disable strict TLS certificate validation. This can be used for development and testing purposes where self-signed certificates might be in use. This environment variable weakens security and should never be used in a production environment.
The default value is
false
.
hotrod-agent setup
Create systemd unit file for hotrod-agent by running the following (as root)
cat > /etc/systemd/system/hotrod-agent.service << EOF
[Unit]
Description=Hotrod agent
After=hotrodd.target
Wants=hotrodd.target
[Service]
Environment=HOTROD_TLS_INSECURE=true
Environment=HOTROD_API_KEY=<api key generated by above "hotrod api-key issue" command
Environment=HOTROD_AGENT_POLL_INTERVAL=5
Environment=HOTROD_AGENT_TARGET_ID=<id generated by above "hotrod targets add" command
Environment=HOTROD_PIPES_DIR=/usr/local/var/pipes
Environment=HOTROD_URL=https://127.0.0.1:3000
Restart=on-failure
ExecStart=/usr/local/bin/hotrod-agent --agent
[Install]
WantedBy=multi-user.target
EOF
Environment variables accepted by hotrod-agent
-
HOTROD_URL
URL to the
hotrodd
listening port. Alternatively, this can be set with--url
option (as seen above). -
HOTROD_AGENT_POLL_INTERVAL
Specify the number of seconds to wait between polling
hotrodd
for potential updates. -
HOTROD_AGENT_LISTENER
Specify the port on which the agent should listen for logs and metrics from running Pipes. The same environment variable can be used to point a Pipe at a
hotrod-agent
to facilitate metric and log transmission. The default value islocalhost:4040
. -
HOTROD_AGENT_TARGET_ID
Specifies the target id of the
hotrod-agent
to identify thehotrod-agent
to thehotrodd
. Alternatively, this can be set with--target-id
option (as seen above). -
HOTROD_API_KEY
Specifies the API key used to authenticate this
hotrod-agent
tohotrodd
. Note that this can be substituted with the HOTROD_JWT_PSK environment variable. -
HOTROD_JWT_PSK
This sets a pre-determined JWT pre-shared key. The
hotrod-agent
will use it to forge JWT tokens, bypassing the need for an API key to be issued. This is only appropriate when runninghotrod-agent
in very secure environments and should be used sparingly. It is often used wherehotrod-agent
runs on the same server as thehotrodd
.
Final setup
-
Ensure the services restart on boot, then go ahead and start the services:
systemctl daemon-reload systemctl start hotrodd hotrod-agent
-
Ensure the agent does connect to hotrodd
$ hotrod targets list name | id | tags | pipes | last seen -------+--------------------------------------+------+-------------+----------- test | 3e067214-76d7-4bce-a6a9-2e282bf7ccd7 | | | 1s
Note the last seen column.
-
Add a license, if you have one
hotrod-beta license activate --file <license file>
-
Add a Pipe to test