Relayd administration

The rudder-relayd service (added in 6.0) is part of the rudder-relay package and runs on all relays and root servers. It provides the relay API and handles inventories and reports forwarding to the root server from nodes.


Relay configuration is stored in /opt/rudder/etc/relay:

  • main.conf contains general configuration. Its content is managed by the Rudder agent of the relay.

  • logging.conf contains logging information.

Relay also reads the following data files:

  • /var/rudder/lib/relay/nodeslist.json: contains information about the nodes behind a relay

  • /var/rudder/lib/ssl/allnodescerts.pem (only on root server): contains the certificates of all nodes managed by the root server

Configuration reload uses the reload API endpoint, which allows systemctl reload rudder-relayd to be synchronous (and ensure configuration is already applied when command returns).

Reloading relayd configuration reloads all data files and update properties from logging.conf but not the ones from main.conf. Changing properties in main.conf requires a restart to be taken into account.

Data files

Relayd operates on different data directories:

  • /var/rudder/inventories (on on simple relays): to forward inventories to upstream relay or root server. On root server, the webapp monitors this folder directly.

  • /var/rudder/reports: to forward reports to upstream relay, or, on root server, to parse and insert reports into the database.

  • /var/rudder/shared-files/: files shared between nodes

  • /var/rudder/configuration-repository/shared-files (read-only): global shared files for Windows agents (Linux agent uses policy download protocol).


Relayd exposes its API on http://localhost:3030/rudder/relay-api/:

See the API documentation for more information.


Relayd outputs its logs on stdout. You can access its logs through journalctl -u rudder-relay.

The log level and filters are configurable in /opt/rudder/etc/relayd/logging.conf:

  • level is the global minimal log level. It can be error, warning, info, debug or trace

  • filter allows increasing the log level of a particular component, with [component]=level, like database=trace. You can also filter logs by node id with [database{node=root}]. Apply multiple filters by separating them with a comma.

Reload the service to update log level and filters.



You can use the service’s system API to check if it’s correctly running:

# Locally on the server or relay
curl http://localhost:3030/rudder/relay-api/1/system/status


  "result": "success",
  "action": "getStatus",
  "data": {
    "database": {
      "status": "success",
      "details": "string"
    "configuration": {
      "status": "error",
      "details": "configuration parsing error: missing field `node_id` for key `general` at line 45 column 1"

See the API documentation for details.

Prometheus endpoint

rudder-relayd provides a prometheus endpoint on http://localhost:3030/metrics.

See the API documentation for details.


Relayd runs with the rudder-relayd user and the rudder group. It also runs in a dedicated SELinux context on RHEL, and on recent systemd versions it runs with limited access to the filesystem (can only write into predefined data directories).

Synchronization via ssh

By default a relay synchronizes its managed nodes' policies via regular file download, the same as nodes use for update. This method doesn’t download a file if it’s not needed, but it can become slow when a lot of files are involved. For this reason, there is an option to replace this synchronization with rsync.

For this option to work, you need to have an ssh access from the relay to the server.

Here are the steps to enable it: * have a default key on the relay, if you don’t, simply run ssh-keygen * copy the relay’s public key on the server on the relay cat /root/.ssh/ on the server echo "<above content>" >> /root/.ssh/authorized_keys * check that ssh works from the relay: ssh root@<rudder server> * enable the option on the webapp in "Administration > Settings > Relay synchronization" * check that the synchronization works on the relay with agent run -ui

Be careful, this setup allows root access from the relay to the server. Two options can be used to limit the threat. On the server you should limit ssh options like agent forwarding and limit login via this key to the relay only. This is done by prefixing the line in /root/.ssh/authorized_keys with restrict,from="<relay ip>".

← Webapp administration Slapd administration →