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_STAGING_DIR=/usr/local/var/hotrodd
  Environment=HOTROD_AUTH_DB=/usr/local/var/hotrodd/auth.db
  Environment=HOTROD_BIND_ADDRESS=127.0.0.1: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

  • 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_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 environment 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_LEGACY_SITES_SLS

    Used to specify a path to a sites.sls file to watch in the event that hotrodd is 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.

  • HOTROD_JWT_EXPIRY_MINS

    Specify the number of minutes that a JWT issued by hotrodd may be valid. The default value is 60.

  • HOTROD_ADDITIONAL_TARGET_CONTEXT_DIR

    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.

  • 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

• Add some files expected by hotrodd

  cat > /usr/local/var/hotrodd/system.sls << EOF
  Sites:
    - name: local
      bbox: local
      protected: true
  EOF
  

  For BMS support, else you will get constant warnings

  cat > /usr/local/var/hotrodd/sites.sls << EOF
  Sites: []
  EOF
  

• Create systemd unit file for hotrod-agent

  cat > /etc/systemd/system/hotrod-agent.service << EOF
  [Unit]
  Description=Hotrod agent
  After=hotrodd.target
  Wants=hotrodd.target
  
  [Service]
  Environment=HOTROD_JWT_PSK=secret
  Restart=on-failure
  ExecStart=/usr/local/bin/hotrod-agent --systemd --pipes-dir /usr/local/var/pipes --poll-interval 1 --url http://127.0.0.1:3000/ --target-id local
  
  [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.

• Ensure the services restart on boot, then go ahead and start the services:

  systemctl daemon-reload
  systemctl start hotrodd hotrod-agent
  

Following can run as normal user

• Look at output of hotrodd service, and get password from there

  journalctl --unit hotrodd
  

• Use above pasword to login to hotrodd, then run a basic command

  $ hotrod login admin
  ...
  $ hotrod targets list
   name  | id    | tags       | pipes  | last seen
  -------+-------+------------+--------+-----------
   local | local | system-sls |        |
  

  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.