Node management

Reinitialize policies for a Node

To reinitialize the policies for a Node, delete the local copy of the Applied Policies fetched from the Rudder Server, and create a new local copy of the initial promises.

rudder agent reset

At next run of the Rudder Agent (it runs every five minutes), the initial promises will be used.


Use this procedure with caution: the Applied Policies of a Node should never get broken, unless some major change has occurred on the Rudder infrastructure, like a full reinstallation of the Rudder Server.

Completely reinitialize a Node

You may want to completely reinitialize a Node to make it seen as a new node on the server, for example after cloning a VM.


This command will permanently delete your node uuid and keys, and no configuration will be applied before re-accepting and configuring the node on the server.

The command to reinitialize a Node is:

rudder agent reinit

This command will delete all local agent data, including its uuid and keys, and also reset the agent internal state. The only configuration kept is the server hostname or ip configured in policy_server.dat. It will also send an inventory to the server, which will treat it as a new node inventory.

Change the agent run schedule

By default, the agent runs on all nodes every 5 minutes. You can modify this value in SettingsGeneral page in Agent Run Schedule section, as well as the "splay time" across nodes (a random delay that alters scheduled run time, intended to spread load across nodes).


This settings can also be modified Node by Node, allowing you to customize the agent behavior (Node with little ressource like a Raspberry Pi or with limited bandwith). To do that, go into the Node details in the Settings tab


When reducing notably the run interval length, reporting can be in No report state until the next run of the agent, which can take up to the previous (longer) interval.

Installation of the Rudder Agent

Static files

At installation of the Rudder Agent, files and directories are created in following places:

Scripts to integrate Rudder Agent in the system (init, cron).
Initialization promises for the Rudder Agent. These promises are used until the Node has been validated in Rudder. They are kept available at this place afterwards.
The FusionInventory Inventory tool and its Perl dependencies.
Wrapper script to launch the inventory.
Binaries for CFEngine Community.
This is the working directory for CFEngine Community.

Generated files

At the end of installation, the CFEngine Community working directory is populated for first use, and unique identifiers for the Node are generated.

CFEngine Community binaries are copied there.
Contains the actual working CFEngine Community promises. Initial promises are copied here at installation. After validation of the Node, Applied Policies, which are the CFEngine promises generated by Rudder for this particular Node, will be stored here.
An unique SSL key generated for the Node at installation time.
An unique identifier for the Node is generated into this file.


After all of these files are in place, the CFEngine Community daemons are launched:

This CFEngine Community daemon is launching the CFEngine Community Agent cf-agent every 5 minutes.
This CFEngine Community daemon is listening on the network on Rudder Root and Relay servers, serving policies and files to Rudder Nodes.


At this point, you should configure the Rudder Agent to actually enable the contact with the server. Type in the IP address of the Rudder Root Server in the following file:

echo *root_server_IP_address* > /var/rudder/cfengine-community/policy_server.dat

Rudder Agent interactive

You can force the Rudder Agent to run from the console and observe what happens.

rudder agent run
[Caution]Error: the name of the Rudder Root Server can’t be resolved

If the Rudder Root Server name is not resolvable, the Rudder Agent will issue this error:

rudder agent run

Unable to lookup hostname (rudder-root) or cfengine service: Name or service not known

To fix it, either you set up the agent to use the IP address of the Rudder root server instead of its Domain name, either you set up accurately the name resolution of your Rudder Root Server, in your DNS server or in the hosts file.

The Rudder Root Server name is defined in this file

echo *IP_of_root_server* > /var/rudder/cfengine-community/policy_server.dat
[Caution]Error: the CFEngine service is not responding on the Rudder Root Server

If the CFEngine is stopped on the Rudder Root Server you will get this error:

# rudder agent run
 !! Error connecting to server (timeout)
 !!! System error for connect: "Operation now in progress"
 !! No server is responding on this port
Unable to establish connection with rudder-root

Restart the CFEngine service:

service rudder-agent restart

Processing new inventories on the server

Verify the inventory has been received by the Rudder Root Server

There is some delay between the time when the first inventory of the Node is sent, and the time when the Node appears in the New Nodes of the web interface. For the brave and impatient, you can check if the inventory was sent by listing incoming Nodes on the server:

ls /var/rudder/inventories/incoming/

Process incoming inventories

On the next run of the CFEngine agent on Rudder Root Server, the new inventory will be detected and sent to the Inventory Endpoint. The inventory will be then moved in the directory of received inventories. The Inventory Endpoint do its job and the new Node appears in the interface.

You can force the execution of CFEngine agent on the console:

rudder agent run

Validate new Nodes

User interaction is required to validate new Nodes.

Prepare policies for the Node

Policies are not shared between the Nodes for obvious security and confidentiality reasons. Each Node has its own set of policies. Policies are generated for Nodes according in the following states:

  1. Node is new;
  2. Inventory has changed;
  3. Technique has changed;
  4. Directive has changed;
  5. Group of Node has changed;
  6. Rule has changed;
  7. Regeneration was forced by the user.

Figure 17. Generate policy workflow


Agent execution frequency on nodes

Checking configuration (CFEngine)

By default, Rudder is configured to check and repair configurations using the CFEngine agent every 5 minutes, at 5 minutes past the hour, 10 minutes past the hour, etc.

The exact run time on each machine will be delayed by a random interval, in order to "smooth" the load across your infrastructure (also known as "splay time"). This reduces simultaneous connections on relay and root servers (both for the CFEngine server and for sending reports).

See the section called “Change the agent run schedule” Section to see how to configure it

Inventory (FusionInventory)

The FusionInventory agent collects data about the node it’s running on such as machine type, OS details, hardware, software, networks, running virtual machines, running processes, environment variables…

This inventory is scheduled once every 24 hours, and will happen in between 0:00 and 5:00 AM. The exact time is randomized across nodes to "smooth" the load across your infrastructure.