Set up automatic agent enrollment
To automatically enroll agents, create a rule and let NXLog Platform enroll the matching agents when they connect.
Compatibility
NXLog Platform currently supports the following NXLog Agent versions:
-
NXLog Agent 5.10 or later.
-
NXLog Agent 6.2 or later.
|
Consider regularly updating your agents, as each NXLog Agent version provides new features that improve the compatibility with NXLog Platform. For example, NXLog Agent 6.4 and later versions support auto-enrollment to NXLog Platform on installation, greatly simplifying the agent enrollment process. |
Prerequisites
NXLog Platform can only auto-enroll agents if NXLog Agent is installed and configured for the initial contact. We recommend using a software configuration management tool to deploy the agents and configure them for first contact.
Adding an auto-enroll rule
To enable automatic agent enrollment, you must add an auto-enroll rule that matches one or more host properties like the hostname or IP address.
Follow these steps to add an auto-enroll rule:
-
Navigate to Agents > Auto enroll.
-
Click Add Rule. The new empty rule appears at the bottom of the list with the lowest priority.
-
Fill in the rule details:
-
In the Selector field, type the expression that matches the hosts to auto-enroll. See Rule selector examples to learn how to write selectors.
-
Enter a Filter name to identify the rule. For example, All Windows hosts. Filter names do not need to be unique, but we recommend choosing names that allow you to distinguish rules easily.
-
In the Comment field, enter an optional rule description.
-
-
Optionally, click Select configuration to assign a configuration template to the auto-enrolled agents.
-
Consider changing the rule’s priority by rearranging its position. A lower number and higher position on the list denote a higher priority. Use the rule handle to drag the rule to its new position.
-
Click Save to apply changes made to all rules.
When saving an auto-enroll rule, NXLog Platform automatically adds the enrolled == falsecondition to ensure that the rule is only applied when agents connect. You can change this behavior by updating the condition toenrolled == true. Although the Auto enroll feature never includes enrolled agents when matching rules, manually running the enroll-by-rules API endpoint targets all agents and matches all rules, including auto-enroll rules unless you apply a filter. -
Optionally, use the switch to turn rules on or off. NXLog Platform ignores rules that are turned off and does not process them in any auto-enroll actions.
After saving the rule, you can start the agents you want to auto-enroll. NXLog Platform attempts to enroll them when they connect for the first time or on every connection after that as long as the agent is not enrolled.
Rule selector examples
You can use one or more agent properties in a rule selector to match a subset of agents. NXLog Agent sends some of these properties when connecting, while NXLog Platform adds others.
The following selector compares the agent machine’s hostname to a fixed value using the equality (=) operator.
This selector matches either a single host, or multiple hosts if the same hostname is available in multiple domains.
hostname = fedora03 AND enrolled = falseHowever, comparing the hostname to a single value is not always useful.
Assume your organization encodes the OS type in the hostname, such as WIN-4S38UE5G81L.
In cases where you want to define a partial match, you can use the LIKE operator with the % wildcard.
For example, the following selector matches all hostnames that start with WIN-:
hostname LIKE WIN-% AND enrolled = falseAnother way to match multiple hostnames is through the use of regular expressions.
The REGEX operator accepts a Rust-style regular expression.
The following selector matches agents whose hostname is in the <8-character username><YYYY> format, such as JMSMITH2024:
hostname REGEX "(?i)[a-z]{8}(?-i)\d{4}" AND enrolled = falseYou can define multiple properties in a single selector.
The following example uses the AND operator, which means both property values must match to auto enroll the agent.
hostname LIKE fedora AND os-release="Fedora Linux 39 (Workstation Edition)" AND enrolled = falseThe address property contains the IP address of the agent.
To aid the auto enrolling of multiple agents by IP, it supports testing against network values in CIDR format in addition to a single IP address.
The following selector matches agents with IPs in the 172.16.120.1 to 172.16.123.254 range.
address = 172.16.120.0/22 AND enrolled = falseThe following selector uses the inequality operator to match any IP address that is NOT 172.16.120.1 at port 8081.
address != 172.16.120.1:8081 AND enrolled = false