Hotrod Setup With systemd
This is helpful for testing locally, where you don't need the entirety of the Bbox Management Server (BMS).
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_LEGACY_SITES_SLS=/usr/local/var/hotrodd/sites.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 hotroddwould be equivalent to
hotrodd --jwt-psk secret. Have a look at
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
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.
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.
Specify a path to the staging directory that should be used for
hotrodd. The staging directory is used by
hotroddfor all runtime configurations. If not specified, the current working directory will be used.
This can be used to override the path and filename of the Hotrod credentials database. If not specified, a file named
hotrod_auth.dbwill be created in the current working directory.
Socket address to bind to, default being 127.0.0.1:3000.
Used to specify a path to a
Used to specify a path to a
sites.slsfile to watch in the event that
hotroddis used in an environment with the Panoptix Bbox Management Server (BMS). This will cause Targets to be automatically added for every Bbox that is managed by the BMS.
Specify the number of minutes that a JWT issued by
hotroddmay be valid. The default value is
Specify a path to additional Context, to supplement that added via Pipes definitions, and via Hotrod CLI. This used in an environment with the Panoptix Bbox Management Server (BMS). Context variables will automatically be added to targets that match files in this location, and receives greater precedence over other Context variables, in the case of conflicts.
Controls how much logging should happen
NOTE: This setting applies to all Hotrod executables.
- info (the default)
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
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 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
This needs to be set to the remote instance of
hotrodd. The CLI will cache JWT authentication tokens for each unique
HOTROD_URLin order to facilitate management of multiple
The default value is
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
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
URL to the
hotroddlistening port. Alternatively, this can be set with
--urloption (as seen above).
Specify the number of seconds to wait between polling
hotroddfor potential updates.
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-agentto facilitate metric and log transmission. The default value is
Specifies the target id of the
hotrod-agentto identify the
hotrodd. Alternatively, this can be set with
--target-idoption (as seen above).
Specifies the API key used to authenticate this
hotrodd. Note that this can be substituted with the HOTROD_JWT_PSK environment variable.
This sets a pre-determined JWT pre-shared key. The
hotrod-agentwill use it to forge JWT tokens, bypassing the need for an API key to be issued. This is only appropriate when running
hotrod-agentin very secure environments and should be used sparingly. It is often used where
hotrod-agentruns on the same server as the
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