Communication between servers and nodes uses two channels:
HTTPS from nodes to servers
Custom protocol wrapped in TLS on tcp/5309, from nodes to server to download policies and (optionally) from server to nodes to trigger runs.
Both enforce using TLS 1.2+.
We recommend using a VPN for all communications between node and server if on a public network. If it’s not the case, it’s necessary to follow the following guide to improve security level.
On all agents and relays, and servers:
/var/rudder/cfengine-community/ppkeys/localhost.priv, the node’s private key, that allows the node to download its policies. It is a 4096-bit RSA key.
/var/rudder/cfengine-community/ppkeys/localhost.pub, the node’s public key
/opt/rudder/etc/agent.cert, the node’s certificate. It is embedded in inventories and signs inventories and compliance reports.
Only on servers and relays:
/opt/rudder/etc/rudder.key, the HTTP server’s private key. It is a 2048-bit RSA key by default.
/opt/rudder/etc/rudder.crt, the HTTP server’s certificate chain. It is generated as a self-signed certificate at server installation. See procedure below to replace it by a valid one.
This protocol is used for:
Policy download on Linux and AIX nodes
Remote run from policy servers to nodes
It uses the key pairs in
/var/rudder/cfengine-community/ppkeys/ to authenticate the node and server during
The server is trusted by the node at first connection ("Trust On First Use") by default, but you can provide a public key to pre-establish trust (see guide below).
HTTPS is used for:
Sending inventories and reports from nodes to policy servers
Remote-run trigger between root server and relays
File sharing between nodes and policy server
Policies and shared-files downloads on Windows nodes
Our HTTPS setup uses standard certificates, that are self-signed by default, and nodes do not verify their policy server’s certificate when sending an inventory or a report.
Follow the guide below to replace them by valid certificates and enable certificate validation.
Inventories and reports are sent without client authentication at HTTP level, but they are signed the node’s certificate, and checked on central server before being processed.
For Windows policy and file download, HTTPS client authentication is done using the
agent.cert node’s certificate
for allow allow access to the node with the matching private key.
The following steps allows configuring Rudder to enforce certificate validation and establishing trust with pre-shared information during agent provisioning.
To enforce secure communications with the nodes, follow these steps on the root server.
Check that the reporting protocol is set to HTTPS only, as it enforces only accepting signed reports.
Replace the default self-signed certificate by a valid one (i.e. recognized by the nodes) certificate in place in:
|You need to make sure all nodes use a hostname that matches this certificate as their configured policy server.|
You can for example use Let’s Encrypt to get free certificates if your server has an access to the Internet.
In this case you should copy
rudder.key, and automate this copy to allow automatic renewal.
Then enable Enforce validation of policy server certificate for inventory and reporting in Settings → General → Certificate validation. This will make nodes require a valid certificate to send reports and inventories.
Once enabled, all nodes will check the server’s certificate before sending reports or inventories (after the first successful policy update). Next step will do the same for the first agent run, with initial policies.
To enforce certificate verification from agent install (and not only after first generation and policy update), we need to modify initial policies served by the root server.
|Currently initial policies are not configurable, so this change needs to be done after each upgrade.|
On the root server, in
"rudder_verify_certs" expression => strcmp("", "true"); # should be replaced by "rudder_verify_certs" expression => "true";
# add "RUDDER_VERIFY_CERTIFICATES":"true",
After these changes all new nodes will validate certificates from first run.
This section expects that the server-side setup has been done. At allows going a bit further by providing a hash of the server key at installation to validate the server identity from the first connection, and avoid trusting the first host it connects to.
It requires providing local changes to the agent as part of the provisioning process. Here policy server’s refers to you node’s server, it can be a relay or a root server.
Compute policy server’s hash key with:
cf-key -p /var/rudder/cfengine-community/ppkeys/localhost.pub
/var/rudder/cfengine-community/ppkeys/localhost.pub from the policy server server on each provisioned node to
So that it looks like:
# cat /var/rudder/cfengine-community/ppkeys/root-MD5\=1ec2213e08921bd3444861f7b4a60919.pub -----BEGIN RSA PUBLIC KEY----- MIICCgKCAgEA78g1gmG98Sh4hso8mYGagj98M+SZU7mklbC5Ylv90mecsLD9QlcZ j64z5uABclz5lErdbtVu7ix4Tk5PyrTW0vbh40tqa48oifPl4iA7hQUmYpnnO8Sp h/HCcHGsiLrW5PytDN2JcOaRZz03cOaoze29KkQgjav+DNZdzqV79aVnujaRqTPY G6B3pInhVeKgiuJkXQEiql4f4GdBHZTkEDz2ammjqu507NL8iPkJs1mE8N0Q0CtC mgXNqzS6bIzTLMgBU1MK77NLsPs2GsNo9x6V/CuutmUHwlccdf1NVyhO9EpzxY1C TFzojgPT62pKR5Ehgl9bHyVGF1RY0kxwKfXJqyVZg87z7jh3YjyzG4RWsihNyiRe HUuKK+rpMj+QwRbbt/97siDxHb6OShKDEWJoR8aj//vY03c79zXtZtoAcpPDp5Et jNUEYqnVZabEuryaUsAOD0Dyx3twWEm1DW+4PJYUYDlNtcuD8X3kvyOnjBy9AbbR irG1iZFVLzyNaX/0ijdY94+iw2c1Ga4HQp6MAdkKiaJlN7pkRksd4778dZRimYiu dD42Nb36YQca50d0sHKalWFTBaT+ksRSrFZVs1Wb8yE9KkJf4bYLRYLhIdYTra22 C9o5xHCOTDecATXMg0gGQHbjm0x0a1nt+X1gyyjNfHLX13n5as9JXf0CAwEAAQ== -----END RSA PUBLIC KEY-----
Now you can set your policy server with
rudder agent policy-server mypolicyserver
and the agent will only accept the connection if it matches the provided key hash.
← Uninstall Relayd administration →