Rudder relay API

The rudder-server-relay package provides an HTTP API. It is available on simple relays and root servers. It is an internal API, not exposed to users, and used to provide various Rudder features.

Remote Run

The remote run API is available at https://relay/rudder/relay-api/remote-run. It allows triggering a run on nodes (like with the rudder remote run command).


The remote run API applies to all nodes that are below the target relay server, which means:

  • All nodes directly connected to the server

  • All the relays that have the target node as policy server, and all nodes that are below them

In particular, it does not act on the target relay itself (except for the root server which is its own policy server).

There are different methods, whether you want to trigger all nodes, or only a part of them.


The remote run calls are not authenticated, but restricted to:

  • Local calls on the relay

  • The relay’s policy server

They requires allowing the policy server to connect to its nodes on port 5309.


This API provides the following methods:

  • POST /rudder/relay-api/remote-run/all: Trigger a run on all nodes below the target relay.

  • POST `/rudder/relay-api/remote-run/nodes/`<node-id>: Trigger a run on the node-id node (which must be under the target relay).

  • POST /rudder/relay-api/remote-run/nodes Trigger a run on the given nodes (which must be under the target relay), see the nodes parameter below.

The general parameters are:

  • keep_output = true or false: Should the agent output be returned (default: false)

  • asynchronous = true or false: Should the server return immediately after trigerring the agent or wait for remote runs to end (default: false)

  • classes = class or class1,class2,etc. for multiple classes: Classes to pass to the agent (default: none)

And, only for the /rudder/relay-api/remote-run/nodes call:

  • nodes = node_uuid or node_uuid1,node_uuid2,etc. for multiple nodes: Nodes to trigger (default: none)

Shared Files


The goal of this API is to share a file from node to node. The source nodes uses an API call to send the file, and the destination node will get the file using the same protocol as files shared from the policy server.

The relay that receives an API call to share a file (PUT) will:

  • share the file directly if the target nodes is one of its managed nodes.

  • send the file to a sub-relay if the target is somewhere under it

  • forward the file to its policy server if the target is nowhere under it

The relay that receive a HEAD call will:

  • If the file exists, compare the provided hash with the hash of the stored file, and return the result (true or false).

  • If the file does not exist, return false.

The ttl is stored along with the file, and a clean task will regularly run and check for outdated files to remove.

There are ncf generic method that allow easy access to those methods from the nodes.


This call is open to all nodes in the allowed networks of the target relay. The sent files are signed with the node’s key, and the signature is checked before being traited.


This API provides the following methods:

  • PUT /shared-files/ <target-uuid> / <source-uuid> / <file-id>

  • HEAD /shared-files/ <target-uuid> / <source-uuid> / <file-id> ?hash= file-hash

The common URL parameters are:

  • target-uuid = destination_node_uuid: where to send the file to

  • source-uuid = source_node_uuid: who sent the file

  • file-id = my_file_id: under which name to store the file, this needs to be unique

The URL parameters specific to the HEAD call are:

  • file-hash = value of the hash: hash of the shared file

The following are only needed for the PUT call:

  • hash_value = value of the hash: hash of the shared file

  • algorithm = sha1, sha256 or sha512: algorithm used to hash the file

  • digest = **: signature of the file

  • pubkey = **: public key

  • ttl = **: can be a number of second or a string of the long form "1day 2hours 3minute 4seconds" or abbreviated in the form "5h 3s"

  • header = rudder-signature-v1: signing format (for now, only one possible value)

← Security considerations Generic methods →