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 to hotrodd --jwt-psk secret. Have a look at hotrodd --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 by hotrodd 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 is 60.

    • 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 unique HOTROD_URL in order to facilitate management of multiple hotrodd 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 is localhost:4040.

  • HOTROD_AGENT_TARGET_ID

    Specifies the target id of the hotrod-agent to identify the hotrod-agent to the hotrodd. 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 to hotrodd. 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 running hotrod-agent in very secure environments and should be used sparingly. It is often used where hotrod-agent runs on the same server as the hotrodd.

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