Installing the Data Enricher

Contents

Installing the Data Enricher

Cloud The following content applies exclusively to the Nexthink Cloud offering.

Overview

To complement the information that Collectors send to your Nexthink Cloud instance, install the Data Enricher on a Windows Server, with 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.1.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 dialogue, 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

  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.
    DataEnricherSetup.png
    • If the user credentials are not valid, an error message shows up. 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.

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 listed parameters 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 the Nexthink Cloud. It is therefore divided into two sections:

GENERAL
This section holds parameters about the log mechanism.
  • log_file: Full path of the the log file. Use the forward slash as 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 sections contains the details on how to connect to the Nexthink Cloud.
  • endpoint: Address of the gateway to the Enrichment API in the 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
    • pac
    • us
  • oauth_client_id: The client identifier that your organization received during onboarding. The Data Enricher uses the client ID in combination with the client secret below to get an access token from the Nexthink Cloud. Encrypted upon startup of the Data Enricher.
  • oauth_client_secret: The client secret that your organization received during onboarding. 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 the 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. Threescopeoption.png

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 amount of destinations to be resolved) per DNS server before excluding it from the current search. By default 35 (representing a 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 already 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 the day of and the time of the 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:
    StartDataEnricher.png
  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