Rule-based Collector assignment (classic)

Overview

The rule-based Collector assignment requires a single installer that uses the fully qualified domain name (FQDN) of the Nexthink instance for all Collectors. Upon first connection, each Collector receives the address of its assigned Nexthink V6 Engine. Thereafter Collector can start sending information to the Engine as usual. In subsequent connections to Nexthink, each Collector checks whether it is assigned to the same or to another Engine, and switches Engines accordingly.

Nexthink manages the assignment process using a set of rules. By adjusting them, you can dynamically reassign Collectors to different Engines. The rules define the assignment of Collectors not only to Engines but also to entities. They form the base to organize your devices in hierarchies. The entity assignment specified by the same rules is valid for any version of both Windows and Mac Collector installations.

Support for rule-based Collector assignment

The rule-based assignment supports rules with conditions on the following device fields:

• Last IP address

• Last local IP address

• Name

• Distinguished name reported by Collector

• AD site

• Collector tag number

• Collector string tag

Ensure that you do not have any roaming devices that switch between Engines and whose assignment is based exclusively on the Last IP address of the device. Starting from V6.24, using the last local IP address of the device instead solves the issue.

When the conditions depend on the IP address of the device, the rule-based Collector assignment is incompatible with the local IP address beta feature, which is deprecated from V6.24 and superseded by the last local IP address field.

Writing the assignment rules

Define the rules for Collector assignment using a CSV file with a tabular structure.

entity_rule (case sensitive)
When set to no, the rule assigns the device to both an Engine and an entity.
When set to yes, the rule assigns the device to an entity, filtered by Engine.

Engine (case insensitive)
The hostname of the target Engine.

Entity (case sensitive)
The name of the target entity.

Field1
The name of the first device field used for the assignment.

Pattern1
The pattern that the first specified field must match to assign the designated Engine and entity to the device.

Field2
The name of the second device field on which to base the assignment.

Pattern2
The pattern that the second specified field must match to assign the designated Engine and entity to the device.

The columns Field1 and Field2 support the following values:

ip

The last IP address of the device. As a pattern for the field, specify either:

- A single IP address in dot-decimal notation, for example 192.168.10.1

- A subnet in CIDR notation, for example 192.168.10.0/24

local_ip

The last local IP address of the device corresponds to the IP address on the local network. Specify patterns in the same way as for the ip field.

name (case insensitive)

The hostname of the device.

collector_tag

The tag number assigned to Collector during its installation. Only the exact number is matched.

collector_string_tag

The label assigned to Collector during its installation This value supports pattern matching.

dn

The distinguished name of the device, as reported by Collector. The device must be part of an Active Directory domain.

The format of the distinguished name reported by Collector is the standard sequence of attribute=value elements connected by commas, from the most specific to the most general attribute. For example CN=ex01,OU=Computers,DC=example,DC=org

In contrast, when retrieved from Active Directory, the distinguished name field of a device (or user) uses a similar sequence, but in reverse order, with elements connected by a forward slash. For example /DC=org/DC=example/OU=Computers/CN=ex01

ad_site

The Active Directory site in which the device is located. A site represents one or more TCP/IP subnets.

The name, collector_string_tag, dn and ad_site fields support character pattern matching. To define the associated string pattern, use the following wildcards:

- The ? character substitutes a single character.

- The * character substitutes zero or more characters.

To write the CSV file for the rules, use UTF-8 text encoding and limit the size to 20 MB. Avoid writing the rules on text editors that create a BOM character at the beginning of the file (for example, Notepad on Windows). Such additional characters trigger a header error when parsed by the configuration wizard.

After the header, write each rule on a new line. Optionally enclose each item in double quotes to make sure the system escapes special characters and use the semicolon as a delimiter. For example, a CSV file for a small company with branch offices in various timezones:

"entity_rule";"Engine";"Entity";"Field1";"Pattern1";"Field2";"Pattern2"
"no";"Engine-2";"BOSTON";"local_ip";"10.102.0.0/16";"name";"DESKTOP-*"
"no";"Engine-3";"DUBAI";"local_ip";"10.103.0.0/16";"name";"DESKTOP-*"
"no";"Engine-4";"BRISBANE";"local_ip";"10.104.0.0/16";"name";"DESKTOP-*"
"no";"Engine-5";"ZURICH";"local_ip";"10.107.0.0/16";"name";"DESKTOP-*"
"no";"Engine-1";"REMOTE";"name";"LAPTOP-*"

For a rule to be satisfied, conditions on both Field1 and Field2 must be fulfilled, so both patterns must match. The rule precedence is established from top to bottom. Entity-only rules allow catch-all default cases to prevent assignments to the empty - entity from occurring, especially for sticky, roaming or VPN devices.

To upload a CSV file:

1. Log in to the Nexthink web interface with an account with a central administrator profile.

2. From the Administration menu in the main navigation bar, select Collectors under System configuration.

3. Click on the Add new ruleset button.

   1. Fill in the fields in the dialog box.

      

      • For RULESET NAME type in a unique name for the rule.

      • For DESCRIPTION explain the purpose of the rule.

      • Under CSV FILE, click Upload new file and select your previously created CSV file.

Simulating Collector assignment

For a seamless transition from one ruleset to another, Nexthink strongly advises first simulating your rules. The simulation of Collector assignment rules lets you see the effect of applying the rules without actually changing the currently assigned Engines and entities.

To activate simulation mode:

1. Log in to the Nexthink web interface with an account with a central administrator profile.

2. From the Administration menu in the main navigation bar, select Collectors under System configuration.

3. Click on simulate to trigger the process.

   

4. The results are stored in a CSV file that your web browser automatically downloads. It lists all the devices linked with your instance and some of their properties, organized in columns. The last ones contain the simulated values.

Example of part of a CSV downloaded following a simulation.

Discovering your Collectors

Check the list of Collectors connecting to your instance.

1. Log in to the Nexthink web interface with an account with a central administrator profile.

2. From the Administration menu in the main navigation bar, select Collectors under System configuration.

3. See the list of devices associated with the instance under Devices.

4. Click on Export them all to get the full list.

The columns of the table offer you the current information about the assignment status of Collectors. These columns include the following properties: 

1. Device name

2. Collector version

3. IP address (the last one)

4. AD Site

5. Distinguished name

6. Collector tag number

In addition, the following additional columns can be found:

Last seen (UTC)

The time of the last assignment request received from Collector.

Last seen on

The IP address and port of Appliance on which Collector was last seen.

Assigned Engine

Engine to which Collector is configured to send data.

Assigned entity

The entity to which Collector currently belongs.

Roaming since (UTC)

Time at which the device started roaming.

Error message

Last error in the assignment of Collector.

Reassignment

Once the Nexthink instance has successfully assigned an Engine to a Collector, Collector receives new assignment information from its assigned Engine, which in turn receives it from the Nexthink instance. Collector asks for new assignment information every time its TCP connection is interrupted.

In addition, Collectors can be dynamically reassigned to another Engine every time that the assignment rules change. The distribution of reassignment messages to Collectors may take up to 60 minutes.

On the other hand, to limit the number of undesired Engine switches, the reassignment of a device that changes its properties (for example IP address) is delayed for a default of 10 days after a new rule takes over. This is especially important for devices that change their subnet frequently, such as the laptops of roaming users.

Assignment failure scenario

When a Collector gets a new assignment, Collector tries to establish a TCP connection to its assigned Engine using the first FQDN as the destination. If Collector is unable to reach it after three retries, Collector resorts to its previously assigned Engine to report the failure. It then waits for a new assignment. While on standby, Collector sends no traffic.

To see if any assignment failed:

1. Log in to the Nexthink web interface with an account with a central administrator profile.

2. From the Administration menu in the main navigation bar, select Collectors under System configuration.

3. See the list of devices associated with the instance under Devices.

4. In the column Error message, look for list entries with a value similar to the following:
   Last assignment failed: engine [IP address] tcp port [number]: ...

5. By default, only 100 devices are displayed. Click on Export them all to get the full list.