Revision 7f09227c
Added by Alexis Mousset over 7 years ago
| 8_reference/80_relay_api.txt | ||
|---|---|---|
|
=== 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).
|
||
|
|
||
|
===== Description
|
||
|
|
||
|
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.
|
||
|
|
||
|
===== Security
|
||
|
|
||
|
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.
|
||
|
|
||
|
===== Usage
|
||
|
|
||
|
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*)
|
||
|
* `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
|
||
|
|
||
|
===== Description
|
||
|
|
||
|
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.
|
||
|
|
||
|
===== Security
|
||
|
|
||
|
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 beeing traited.
|
||
|
|
||
|
===== Usage
|
||
|
|
||
|
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)
|
||
|
|
||
Also available in: Unified diff
Fixes #9997: Document the relay API