Learn
Documentation
Support
Community

Installing Data Enricher (classic)

Overview

To complement the information that Collectors send to your Nexthink Cloud instance, install the Data Enricher on a Windows Server (see compatible versions in the Release Notes and the appropriate hardware requirements), that has access to both the Active Directory and DNS servers within your corporate network and to your instance of Nexthink Cloud.

The following documentation applies to Data Enricher V1.2.0.

Create a dedicated AD account for the Data Enricher

To create a new AD account:

  1. Log in to the chosen Windows Server as a user with administrator privileges.

  2. Launch Active Directory Users and Computers from the Microsoft Management Console.

  3. In the left-hand side navigation pane, expand the domain tree, right-click Managed Service Accounts and select NewUser.

    1. Type in the First Name, Last Name, and User logon name of the user.

    2. Click Next.

    3. Type in the Password and repeat in Confirm Password.

    4. Click Next.

  4. Click Finish.

Because the Data Enricher runs as a Windows service, set the policy of the account to log on as a service:

  1. From Administrative Tools, open the Local Security Policy.

  2. Expand Local Policy and click User Rights Assignment.

  3. In the right-hand side pane, right-click Log on as a service.

  4. Select properties from the menu.

  5. Click Add User or Group... button to add the new user.

    1. In the Select Users or Groups dialog, select the dedicated AD account that you have just created.

    2. Click OK.

  6. Click OK in the Log on as a service Properties dialog to save the changes.

Install the Data Enricher

This is the procedure for a fresh installation of the Data Enricher. If you are currently running a previous version of the Data Enricher, refer to the next section on upgrading the Data Enricher instead.

  1. Log in to the Windows Server as a user with administrator privileges.

  2. Download the Data Enricher installer from Product Downloads (follow the link at the top right of this page).

  3. Double-click the installer file to run it.

    • If a User Account Control dialog asks you whether you want to allow the app make changes to your device, click Yes.

    • If a dialog asks whether you want to install a Visual C++ Redistributable Update, click Yes.

  4. In the dialog Service Account Setup, type in the credentials of the dedicated AD account that you created in the previous section:

    • Domain\User: Type in the name of the domain, followed by a backslash and by the name of the user.

    • Password: Type in the password of the dedicated user.

  5. Click Next.

    • If the user credentials are not valid, an error message will appear. Click OK and fix the credentials.

  6. In the dialog, Ready to Install, click Install. Another dialog shows the progress of the installation as it proceeds.

  7. In the final dialog, tick the option to Open 'config' folder to edit the configuration files of the Data Enricher after exiting setup.

  8. Click Finish.

Upgrade the Data Enricher

To upgrade an existing installation of the Data Enricher and reuse the same dedicated account and credentials supplied during the first installation:

  1. Log in to the Windows Server as a user with administrator privileges.

  2. Stop the Data Enricher service.

    1. Press the windows key.

    2. Type in Services to look for the Services App.

    3. Press Enter

    4. Right-click the Nexthink Data Enricher entry in the list of services.

    5. Select Stop from the context menu.

  3. Download the Data Enricher installer from Product Downloads (follow the link at the top right of this page).

  4. Double-click the installer file to run it.

    • If a User Account Control dialog asks you whether you want to allow the app to make changes to your device, click Yes.

    • If a dialog asks whether you want to install a Visual C++ Redistributable Update, click Yes.

    • If you already have the same or a later version of the Data Enricher installed, the upgrade process aborts.

    • If you failed to stop the Data Enricher service, as previously indicated, the upgrade process aborts.

  5. In the dialog that displays both the current and the upgraded version of the Data Enricher and asks for upgrade confirmation, click Yes.

  6. In the Ready to Install dialog, click Install. Another dialog shows the progress of the installation as it proceeds.

  7. In the final dialog, tick the option to Open 'config' folder to edit the configuration files of the Data Enricher after exiting setup.

  8. Click Finish. A backup of the previous configuration files is stored with the name nxdataenricher_bak_<yyyyMMdd_hhmmss>.

Editing the configuration files

To complete the setup of the Data Enricher, provide appropriate values to the parameters found in its associated configuration files. The configuration files are found under:

C:\ProgramData\Nexthink\nxdataenricher\

All parameters listed below in bold typeface require you to provide a value. The rest of the parameters listed may be left to their default value.

General configuration

The general configuration file general.conf sets the format and location of the log files for the Data Enricher and its connection parameters to Nexthink Cloud. It is therefore divided into two sections:

GENERAL This section holds parameters about the log mechanism.

  • log_file: Full path of the log file. Use the forward-slash as a separator for the path, with the following default value: /ProgramData/Nexthink/nxdataenricher/log/nxdataenricher.log.

  • log_level: Verbosity of the logger. By default INFO.

  • log_format: Format of the strings displayed by the logger.

NEXTHINKCLOUD This section contains the details of how to connect to Nexthink Cloud.

  • endpoint: Address of the gateway to the Enrichment API in Nexthink Cloud:

https://agora.<region>.nexthink.cloud

Where <region> must match the region of your Nexthink Cloud platform, as assigned to your organization during onboarding.

The Enrichment API is currently available for the following regions:

eu

meta

pac

us

  • oauth_client_id: The client identifier for your organization. Contact Nexthink Support to request this information. The Data Enricher uses the client ID in combination with the client secret below to get an access token from Nexthink Cloud. Encrypted upon startup of the Data Enricher.

  • oauth_client_secret: The client secret for your organization. Contact Nexthink Support to request this information. Encrypted upon startup of the Data Enricher.

  • proxy_enabled: Whether a proxy should be used to connect to Nexthink Cloud. By default False.

  • proxy_server: URL of the proxy in use. State schema, host and port. Example: https://proxy.example.org:8301

  • proxy_auth_type: Type of authentication required. Supported values:

    • Basic for HTTP Basic authentication

    • None (default) to connect to the proxy without authentication.

  • proxy_user: Username for proxy authentication. Leave empty for no authentication.

  • proxy_password: Password for proxy authentication. Leave empty for no authentication. Encrypted upon startup of the Data Enricher.

  • verify_cert: Whether the Data Enricher verifies the certificates or not when connecting to Nexthink Cloud. By default True.

  • update_batch_size: The number of maximum batches that will be sent to Nexthink Cloud to process. By default 10000.

AD configuration

The AD configuration file enricher_nxad.conf contains the details of the LDAP connection of the Data Enricher with the Active Directory servers.

  • excluded_attributes: Comma-separated value list of AD attributes that the Data Enricher must not retrieve.

  • search_batch_size: Number of entries in a batch to search for information in AD.

Repeat the following parameters for every AD server that the Data Enricher must query. If you specify multiple AD servers, the Data Enricher gets information about a user from the first server on the list that returns a valid answer for that user. Replace the letter X by the cardinal number that identifies each server:

  • server_adX.name: The name of the server.

  • server_adX.address: The IP or FQDN of the AD server.

  • server_adX.port: The port used to communicate.

  • server_adX.use_ssl: Whether it will be used SSL or not.

  • server_adX.bind_dn: The Distinguished Name of the user.

  • server_adX.password: The password to connect to the server. Encrypted upon startup of the Data Enricher.

  • server_adX.base_dn: The point in which the searches through the AD tree will begin. It must be an Organizational Unit.

  • server_adX.scope: The scope of the search. There are three possible values

    • base: Search only for entries at the base DN.

    • onelevel: Search for entries one level under the base DN, but not including the base DN nor any nodes at a deeper level.

    • subtree: Search for entries at the base DN and all levels under it.

DNS configuration

The DNS configuration file enricher_nxdns.conf holds the list of DNS servers to which the Data Enricher issues reverse DNS lookups to get the FQDN of each destination. If you specify multiple DNS servers, the Data Enricher gets the FQDN of a destination from the first server on the list that successfully resolves the IP address of the destination. Currently, the Data Enricher resolves IPv4 addresses only and gets just one FQDN per IP address (multiple domain names per address not supported).

  • servers: Comma-separated value list of DNS servers.

  • max_dns_server_timeout: The maximum time (in seconds) wait for a response from the server. By default 0.5 (half second).

  • max_perc_dns_server_errors: The maximum percentage of errors allowed (over the total number of destinations to be resolved) per DNS server before excluding it from the current search. By default 35 (representing 35%).

Common configuration parameters

The configuration files of each service include a set of parameters that indicate how the Data Enricher refreshes the retrieved information: partially or fully.

  • partial_refresh_enabled: True or False, indicates if the service will process only the objects that are missing information with respect to those that have already been updated. Only new objects added to Nexthink (and thus lacking the AD/DNS information) will be processed. By default True.

  • partial_refresh_frequency: The frequency (in minutes) for the partial refresh. It is not recommended to set it to a value lower than 60 min. By default 60.

  • full_refresh_enabled: True or False, indicates if the service will process all the possible data or not. During the full refresh, all objects of interest in Nexthink will be processed (but only those that have different information from that in Nexthink will be updated). By default False, as this refresh is more demanding in terms of time and performance. Please activate it only if strictly necessary.

  • full_refresh_time: A full refresh can potentially be more demanding, both for Nexthink and for the server of interest (AD or DNS). Therefore, this refresh can only be executed either daily or weekly. Moreover, this type of refresh is recommended to be run before the Data collection or after the Engine cleanup and maintenance nightly tasks.

    • To setup a weekly refresh, specify both the day and time of day in the format Day HH:MM. The possible values for the day of the week are: Mon, Tue, Wed, Thu, Fri, Sat and Sun (case insensitive). By default Mon 23:30.

    • To setup a daily refresh, specify only the time of the day in HH:MM format, omitting the day of the week.

Configure and start the Data Enricher service

After the setup is complete, start the Data Enricher service:

  1. Press the WinKey.

  2. Type in Services and press Enter to open the Services app.

  3. Right-click the service Nexthink Data Enricher.

  4. Select Properties from the context menu.

  5. Optional: In the Log tab, verify that the dedicated AD account previously created is in place.

  6. Optional: In the Recovery tab, specify how you want Windows to react in case of service failure.

  7. In the General tab, click the button Start to start the service:

  8. Optional: In the General tab, set Startup type to Automatic to start the service automatically on computer startup.

Do not run multiple instances of the Data Enricher simultaneously.

Encryption of sensitive data

Once you start the service, the configuration files are modified to preserve sensitive data. The following parameters are encrypted using Windows Data Protection:

In the general configuration file:

  • oauth_client_id

  • oauth_client_secret

  • proxy_password

In the AD configuration file:

  • server_adX.bind_password

File samples

General configuration file

Sample general configuration file for the Data Enricher general.conf

[GENERAL]
# Path and name for the log file.
# Default: /ProgramData/Nexthink/nxdataenricher/log/nxdataenricher.log
log_file = /ProgramData/Nexthink/nxdataenricher/log/nxdataenricher.log
 
# Setup the log level desired. For production environments is strongly recommended to setup "info" value.
# Options available:
# - CRITICAL
# - ERROR
# - WARNING
# - INFO
# - DEBUG
# More information about log levels here https://docs.python.org/3.7/library/logging.html#levels
# Default: INFO
log_level = INFO
 
# Set logging format.
# Default: %(asctime)s %(process)s %(levelname)s %(filename)s:%(lineno)d [-] %(message)s
log_format = %(asctime)s %(process)s %(levelname)s %(filename)s:%(lineno)d [-] %(message)s
 
[NEXTHINKCLOUD]
# Please refer to https://doc.nexthink.com/Documentation/Nexthink/latest/InstallationAndConfiguration/InstallingtheDataEnricher
# in order to obtain more information about the Data Enricher installation process
# and/or this file in particular.
 
# Nexthink Cloud endpoint to send and retrieve data from Nexthink.
# Example: endpoint = https://agora.[region].nexthink.cloud
endpoint = https://<host>
 
# The client ID will be used alongside the client secret to retrieve a token.
oauth_client_id = <oauth_client_id>
# The client secret will be used alongside the client ID to retrieve a token.
oauth_client_secret = <oauth_client_secret>
 
# Proxy configuration.
proxy_enabled = False
# Example: proxy_server = http://proxy.nexthink.com:3128
proxy_server = <schema>://<host>:<port>
# Only Basic Authentication or no authentication are supported. Options available:
# - None
# - Basic
proxy_auth_type = None
proxy_user =
proxy_password =
 
# Allows service to check for self signed certificate in Nexthink Cloud.
# False means the self-signed certificate or a bad certificate will be not checked.
# True means the self-signed certificate or a bad certificate will be checked.
# Default: True
verify_cert = True
 
# Maximum number of entries to be updated in Nexthink in a single request.
update_batch_size = 10000
AD configuration file

Sample configuration file for the Data Enricher enricher_nxad.conf

[NXAD]
partial_refresh_enabled = True
partial_refresh_frequency = 60
 
# Enables/disables the full refresh functionality.
# When enabled this will refresh all engine users info at the time configured in full_refresh_time parameter.
# Attention! This can be a very heavy load job, please configure the execution time accordingly.
full_refresh_enabled = False
 
# You may configure a refresh on a daily or weekly basis.
# For a daily full refresh, enter only the local time in a 24 hour format, for example 23:30.
# For a weekly full refresh, add the desired weekday before the time, for example: Sat 23:30.
# The possible values are: Mon, Tue, Wed, Thu, Fri, Sat and Sun.
# Examples:
#   Daily full refresh at 3:17 AM
#   full_refresh_time = 3:17
#   Weekly full refresh on Fridays at 4:55 PM
#   full_refresh_time = Fri 16:55
full_refresh_time = Mon 23:30
 
# Comma separated list of ActiveDirectory attributes to be excluded.
# Options available (corresponding Nexthink Finder's name in parenthesis):
# - distinguishedName (Distinguished name)
# - sAMAccountName (Name)
# - title (Job title)
# - department (Department)
# - displayName (Full name)
# - l (Locality name)
# - c (Country code)
# - ou (Organizational unit name)
# - physicalDeliveryOfficeName (Location)
# Example: excluded_attributes = title, department
excluded_attributes =
 
# Size of the search batches in AD.
search_batch_size = 1000
 
# Servers configuration:
# Use format "server_<x>.<property> = <value>", replace <x> for a number and <property> by its name,
# and <value> by the desired one, like in the following example. You can create as many servers as required.
#
# server_1.name: string (The generic name for the server. Example: if set to "nexthink.ch",
  usernames in Finder will be shown as user@nexthink.ch.)
# server_1.address: string (Server IPv4 or FQDN address)
# server_1.port: int (Server port, usually 389 used)
# server_1.bind_dn: string (Bind DN account. Example: "CN=user,CN=users,DC=company,DC=local")
# server_1.bind_password: string (Bind DN account password)
# server_1.base_dn: string (Start point for directory searches. Example: "DC=company,DC=local")
# server_1.scope: string (One of the following values: base, onelevel or subtree)
 
server_ad1.name = <name>
server_ad1.address = <ip_or_fqdn>
server_ad1.port = <port>
server_ad1.use_ssl = <True/False>
server_ad1.bind_dn = <CN=user,CN=Users,DC=company,DC=local>
server_ad1.bind_password = <pass>
server_ad1.base_dn = <DC=company,DC=local>
server_ad1.scope = <base/onelevel/subtree>
DNS configuration file

Sample configuration file for the Data Enricher enricher_nxad.conf

[NXDNS]
partial_refresh_enabled = True
partial_refresh_frequency = 60
 
# Enables/disables the full refresh functionality.
# When enabled this will refresh all engine destinations info at the time configured in full_refresh_time parameter.
# Attention! This can be a very heavy load job, please configure the execution time accordingly.
full_refresh_enabled = False
 
# You may configure a refresh on a daily or weekly basis.
# For a daily full refresh, enter only the local time in a 24 hour format, for example 23:30.
# For a weekly full refresh, add the desired weekday before the time, for example: Sat 23:30.
# The possible values are: Mon, Tue, Wed, Thu, Fri, Sat and Sun.
# Examples:
#   Daily full refresh at 3:17 AM
#   full_refresh_time = 3:17
#   Weekly full refresh on Fridays at 4:55 PM
#   full_refresh_time = Fri 16:55
full_refresh_time = Mon 23:30
 
# Comma separated list of DNS servers.
# Example: servers = 8.8.8.8, 8.8.4.4
servers = <server1>,<server2>
# Timeout for each DNS server in seconds
max_dns_server_timeout = 0.5
# Percentage of allowed DNS server errors, measured with respect to the total number of destinations
max_perc_dns_server_errors = 35

Last updated

© Nexthink

Privacy policyResponsible Disclosure Policy

#451: 2024.8-Overview of integration DOC

Change request updated