Node management

Node inventory

Rudder integrates a node inventory tool which harvests useful information about the nodes. This information is used by Rudder to handle the nodes, and you can use the inventory information for Configuration Management purposes: search Nodes, create Groups of Nodes, determine some configuration management variables.

In the Rudder Web Interface, each time you see a Node name, you can click on it and display the collection of information about this Node. The inventory is organized as following: first tab is a 'summary' of administrative information about the Node; other tabs are specialized for 'hardware', 'network' interfaces, and 'software' for every Node; tabs for 'reports' and 'logs' are added on Rudder managed Nodes.

The 'Node Summary' presents administrative information like the Node 'Hostname', 'Operating System', 'Rudder Client name', 'Rudder ID' and 'Date' when the inventory was 'last received'. When the Node has been validated, some more information is displayed like the Node 'Name' and the 'Date first accepted in Rudder'.

The 'hardware' information is organized as following: 'General', 'File systems', 'Bios', 'Controllers', 'Memory', 'Port', 'Processor', 'Slot', 'Sound', 'Storage', 'Video'.

'Network' connections are detailed as following: 'Name' of the interface on the system, 'IP address', 'Network Mask', usage of 'DHCP' or static configuration, 'MAC address', 'Type' of connection, 'Speed' of the connection and 'Status'.

And finally, you get the list of every 'software' package present on the system, including version and description.

On Nodes managed by Rudder, the 'Compliance Reports' tab displays information about the status of the latest run of Rudder Agent, whereas the 'Technical Logs' tab displays information about changes for the Node.

Accept new nodes

At the starting point, the Rudder Server doesn’t know anything about the Nodes. After the installation of the Rudder Agent, each Node registers itself to the Rudder Server, and sends a first inventory. Every new Node must be manually validated in the Rudder Web Interface to become part of Rudder Managed Nodes. This task is performed in the Node Management → Accept new Nodes section of the application. You can select Nodes waiting for an approval, and determine whether you consider them as valid or not. Click on each Node name to display the extended inventory. Click on the magnifying glass icon to display the policies which will be applied after the validation.

Example 1. Accept the new Node debian-node.example.com

Install and configure the Rudder Agent on the new Node debian-node.example.com
Wait a few minutes for the first run of the Rudder Agent.
Navigate to Node Management → Accept new Nodes.
Select the new Node in the list.
Validate the Node.
The Node is now integrated in Rudder, you can search it using the search tools.

Search nodes

You can navigate to Node Management → Search Nodes to display information about the Nodes which have been already validated, and are managed by Rudder.

General behavior

In the Advanced Search tool, you can create complex searches based on Node Inventory information. The benefit of the Advanced Search tool is to save the query and create a Group of Nodes based on the search criteria.

Select a field

The selection of the field upon which the criteria will apply is a two step process. The list of fields is not displayed unordered and extensively. Fields have been grouped in the same way they are displayed when you look at information about a Node. First you choose among these groups: 'Node', 'Network Interface', 'Filesystem', 'Machine', 'RAM', 'Storage', 'BIOS', 'Controller', 'Port', 'Processor', 'Sound Card', 'Video Card', 'Software', 'Environment Variable', 'Processes', 'Virtual Machines'; then you choose among the list of fields concerning this theme.

Select the matching rule

The matching rule can be selected between following possibilities: 'Is defined', 'Is not defined', '=', '≠' or 'Regex' followed by the term you are searching for presence or absence. Depending on the field, the list of searchable terms is either an free text field, either the list of available terms.

Add another rule

You can select only one term for each matching rule. If you want to create more complex search, then you can add another rule using the '+' icon. All rules are using the same operand, either 'AND' or 'OR'. More complex searches mixing 'AND' and 'OR' operands are not available at the moment.

Example 2. Advanced search for Linux Nodes with ssh.

Assuming you want to search all Linux Nodes having ssh installed. You will create this 2 lines request:

Operator: AND.
First search line: 'Node', 'Operating System', =, 'Linux'.
Second search line: 'Software', 'Name', =, ssh.

Search numbers with units

Some parameters for the advanced search tool allow using units. For example, in the search criterion for RAM size, you can type 512MB instead of a value in bytes. This paragraph describes supported units by parameter type.

Bytes and multiples

All criteria using a memory size (RAM, hard disk capacity, etc) is by default expected in bytes. If no other unit is specified, all values will be assumed to be in bytes.

Convenience notation

All memory sizes can be written using spaces or underscores (_) to make the numbers easier to read. Numbers must begin with a digit. For example, the following numbers are all valid and all worth 1234:

The following number is not valid:

_1234

Supported units

Units used are non binary units, and a multiplication factor of 1024 is applied between each unit.

Units prefix are case-insensitive. Therefore, MB is identical to mB. B is actually a byte - we cannot search on bit size, and b is thus not an authorized value to avoid confusion.

In detail, the following units are supported:

Table 1. Units supported by Rudder search engine
Notation	Value
B	bytes (equivalent to not specifying a unit)
kB	1024 bytes
MB	1024^2 bytes
GB	1024^3 bytes
TB	1024^4 bytes
PB	1024^5 bytes
EB	1024^6 bytes
ZB	1024^7 bytes
YB	1024^8 bytes

Regex matching rule

You can use regular expressions to find whatever you want in Node inventories. A search request using a regexp will look for every node that match the pattern you entered.

Those regexps follow Java Pattern rules. See https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html for more details.

Example 3. Search node having an ip address matching 192.168.x.y

Assuming you want to search every node using an ip address match 192.168.x.y, where x<10 and y could be everything. You will to add that line to your search request:

'Node summary', 'Ip address', Regex, '192\ .168\ .\d\ . .*'

Composite search (name=value)

Some fields allow you to look for more than one piece of information at a time. That’s the case for environment variable. For those fields you have to enter the first element then the separator then following elements. The name of the fields tells you about what is expected. It would look like firstelement<sep>secondelement assuming that <sep> is the separator.

Example 4. Search Environment Variable LANG=C.

Assuming you want to search every node having the environment variable LANG set to C. You will have to add that search line to your request:

'Environment variable', 'Name=Value', =, 'LANG=C'.

Node properties search

Node properties are special because they support both key=value and key=JSON content. There are three search operators available:

Check for property existence: [Name equals]

The Name equals operator allows to find all nodes which have the property with the given name defined. That operator only look for the property name and don’t care if the value is a string or a JSON one.

Example 5. Search for nodes with the property datacenter defined

'Environment variable', 'Name=Value', Name equals, 'datacenter'.

Lookup node by property name=value pair

If you want to lookup nodes by a property name and its value, you can use the "name=value" operator, as explained in paragraph "composite search" above.

Please note that if the value is JSON, you will need to use the exact serialization of the JSON value (in a compact formatting: no spaces, etc). It is generally not what you want to do with JSON value, and for them it is better to use JSON path query (see below).

Example 6. Search for the node property "datacenter" with value "Paris"

'Properties', 'Name=Value', =, 'datacenter=Paris'.

Lookup node by property name=value pair with regex

You can also use regex on node properties name and value. The regex can be done on each part, so the following examples allow to fill different purposes:

Example 7. Search for nodes with a property whose value is "Paris" whatever its name

'Properties', 'Name=Value', regex, '.*=Paris'.

Example 8. Search for nodes with a property whose name is "datacenter" and value contains "Paris"

'Properties', 'Name=Value', regex, 'datacenter=.Paris.'.

Example 9. Search for nodes with a property whose name starts with "datacenter" and value contains "Paris"

'Properties', 'Name=Value', regex, 'datacenter.=.*Paris.'.

JSON Path queries on Node Properties

You can use a JSON path query to lookup nodes based of specific feature of the JSON value of a node property.

The operator is Name:JSON Path and the general usage is:

Example 10. Search for nodes with a property by JSON path query

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:json-path-query'.

Where json-path-query is JSON path selector from https://github.com/json-path/JsonPath. Nodes are selected if the JSON path selector result is not empty, i.e if the JSON value contains selected elements.

For example, let’s say you have a node with a property whose name is datacenter and value is:

{ "id": "xxxxxx", "accepted": true, "location": { "name": "Paris-03", "address": { "continent": "Europe", "city": "Paris", } }, "environments": ["prod","dev"] }

The following query would all select the node:

Example 11. Example of JSON path queries

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:$.[?(@.accepted==true)]'

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:$.location.address[?(@.city=='Paris')]'

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:$.location.address.city'

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:$.location[?(@.name=~/Paris-[0-9]+/)]'

'Properties', 'Name=Value', Name:JSON Path, 'datacenter:$.[?(@.environements subsetof ['prod', 'qa', 'dev'])]'

Group of Nodes

You can create Group of Nodes based on search criteria to ease attribution of Rules in Configuration Management. The creation of groups can be done from the Node Management → Search Nodes page, or directly from the Groups list in Node Management → Groups. A group can be either Dynamic or Static.

Dynamic group: Group of Nodes based on search criteria. The search is replayed every time the group is queried. The list will always contain the nodes that match the criteria, even if the data nodes have changed since the group was created.
Static group: Group of Nodes based on search criteria. The search is performed once and the resulting list of Nodes is stored. Once declared, the list of nodes will not change, except manual change.

Example 12. Create a dynamic group for Linux Nodes with ssh having an ip address in 192.18.42.x.

To create that dynamic group like described above, You first have to create a new group with group type set to Dynamic. Then you have to set its search request to:

Operator: AND.
First search line: 'Node', 'Operating System', =, 'Linux'.
Second search line: 'Software', 'Name', =, ssh.
Third search line: 'Node summary', 'Ip address', Regex, '192\ .168\ .\d\ . .*' .

Finally, you have to click on Search to populate the group and click on Save to actually save it.

← Web interface usage Advanced node management →