Installing Collector on macOS

Overview

Nexthink distributes Collector for macOS as a disk image .dmg file with the following content:

  • A package .pkg file for installing Collector from a graphical user interface.

  • The csi.app application for installing Collector from the command line interface.

  • A reporter shell application that gathers system information for troubleshooting purposes.

  • An uninstaller application to remove Collector when it is no longer needed.

After the installation, as a sanity check, optionally verify the status of the TCP connection between Collector and the Nexthink cloud platform.

Collector for macOS runs in user mode and does not need to ask the user for explicit permissions to install any kernel extension. Running in user mode comes with the added benefit of making it unnecessary to reboot your macOS devices after updates or uninstallation.

Prerequisites

Requirements

  • One or more macOS devices

  • The Nexthink Collector disk image (Nexthink_Collector_<version>.dmg file)

  • The Customer Key

  • Access to the full storage device (Full Disk Access enabled)

  • (optional) A third-party automated deployment tool

Downloads

  1. Connect to the product download website.

  2. Sign in with your customer credentials.

  3. Click the first entry of the Latest Infinity releases list.

  4. Under Latest Downloads, find the Collector section.

  5. Click to download the Collector package for macOS.

  6. (optional) Verify your download with the provided SHA-256 hash.

  7. Click the downloaded file Nexthink_Collector-<version>.dmg file.

  8. Find the package file (Nexthink_Collector-<version>.pkg) and the csi app inside the image file.

Connection details

  • The fully qualified domain name (FQDN) of your Nexthink instance.

  • TCP port number for the connection (default 443).

Full disk access permission

Nexthink Collector relies on the Apple Endpoint Security framework and follows Apple’s privacy guidelines. For this reason, the nxtsvc macOS app requires full disk access. Administrators can manually enable it using the System Preferences application utility or use the mobile device management (MDM) capabilities to configure and update settings remotely. Nexthink provides sample files you can use to create the configuration files you need for both nxtsvc.app and nxtcod.app.

Refer to the Installing Collector profile in Jamf for macOS documentation for more information.

Links:

nxtsvc (mandatory): Required by Apple Endpoint Security framework and Apple’s privacy guidelines.

nxtcod (optional): Only if remote actions need to access special folders or network shares.

Additional configuration

Refer to the Configuring Collector level anonymization for more information about additional Collector configuration for data anonymization and privacy.

Wizard installation

To install Collector on macOS using the Wizard installation:

  1. Double-click the provided disk image file to mount it into your filesystem and see its contents.

  2. Double-click the package file Nexthink_Collector_<version>.pkg and the installer will start with the introduction.

  3. Click Continue to proceed with the installation.

  4. In the step Personalization, configure first the settings of the Nexthink Appliance to which Collector will connect:

    • Name or IP address Type in the FQDN of your Nexthink instance.

    • Data over TCP Tick the option to send data over a TCP channel.

    • TCP port Port number to set to 443.

    • UDP port This feature must not be selected when using the Nexthink cloud platform.

  5. Configure the proxy settings of Collector:

    • Tick Automatic proxy for Collector to take its configuration from a proxy auto-configuration (PAC) file.

      1. In PAC address, type in the URL of the file that determines the proxy to use.

    • Tick Manual proxy for Collector to use the following proxy settings:

      1. Address Type in the FQDN of the proxy.

      2. Port Type in the port number where the proxy is listening.

  6. In a second step, configure the other settings of Collector:

    • Customer Key Copy and paste the contents of the file that holds the Customer Key.

    • Root CA Leave this field empty.

    • (optional) Collector tag Type in an integer number (0 to 2147483647) that identifies a group of Collectors. The tag is useful for defining the entities to build up hierarchies.

    • (optional) Collector string tag Type in a label (max 2048 characters) that identifies a group of Collectors. The string tag is useful for defining the entities to build up hierarchies.

    • (optional) Tick Assignment service if you activated the rule-based assignment (classic).

    • (optional) Tick Nexthink Engage to activate the features that let you send campaigns to employees.

    • (optional) Select the execution policy of scripts included in remote actions:

      • Disabled (default) Collector runs no remote action on the device.

      • Unrestricted Collector runs any remote action on the device, regardless of the digital signature of its script.

      • Trusted publisher Collector runs on the device only those remote actions with a shell script that is signed by an identified developer.

      • Trusted publisher or Nexthink Collector runs on the device only those remote actions with a shell script that is signed either by Nexthink or by an identified developer.

  7. Click Continue to proceed.

  8. In the step Destination select, the installer program shows the local paths in the system where it is going to install the different components of Collector. Keep the default paths and click Continue.

  9. The Installation Type step informs you about some details of the installation process, including the amount of disk space that the program is going to use. Click Install to begin with the installation.

  10. The installer shows the progress of the installation, and it finishes with a summary message. If the installation was successful, click Close the installer.

Command-line installation

The command-line installation lets you install Collector even when you have access to a computer only through the macOS shell. Using the command-line installation, you can install Collector either locally or remotely through an SSH connection.

Execute the csi.app application provided with the disk image. To mount the disk image into the file system:

  1. After downloading the image file from Product Downloads, pick one of the following options:

    • If you are installing Collector on a remote computer:

      1. Copy the image file to the remote computer: scp Nexthink_Collector_<version>.dmg <username>@<address>

        :

      2. Log in to the remote computer: ssh <username>@<address>

    • If you are installing Collector on the local computer:

      1. Change the directory to the one where you downloaded the image file.

  2. Mount the image file: hdiutil mount Nexthink_Collector_<version>.dmg

Once the image file has been mounted into the filesystem of the target Mac computer, install Collector from the command line:

  1. Change the directory to the path of the csi application. For example, type cd /Volumes/Nexthink_Collector_22.6.2.10\ OSX\ 10.15\ -\ 12/csi.app/Contents/MacOS/

    when version 22..6.2.10 of Collector is used.

  2. Type in the following command and provide, as arguments:

    • address FQDN of your Nexthink instance.

    • port This feature must not be selected when using the Nexthink cloud platform.

    • tcp_port Port number to set to 443.

    • rootca Not required.

    • key The path to the Customer Key file

    • (optional) engage Whether to enable the campaigns or not (the default value is disable).

    • (optional) data_over_tcp Whether to enable the sending of all data over the TCP channel (the default value is enable).

    • (optional) use_assignment Whether to enable the rule-based assignment (classic) (default is disable).

    • (optional) ra_execution_policy Whether to enable the remote actions or not with the possible options below.

      • disabled (default) Collector runs no remote action on the device.

      • unrestricted Collector runs any remote action on the device, regardless of the digital signature of the associated script.

      • signed_trusted Collector runs on the device only remote actions with a shell script signed by an identified developer.

      • signed_trusted_or_nexthink Collector runs on the device only remote actions with a shell script signed either by Nexthink or an identified developer.

    • (optional) tag Integer number (0 to 2147483647) to identify an individual or batch installation of Collectors.

    • (optional) string_tag Label (max 2048 characters) to identify an individual or batch installation of Collectors.

  3. (optional) proxy_pac_address Provide the URL of a PAC address for automatic configuration of proxy settings.

    • (optional) proxy_address Provide the FQDN of a proxy for manual configuration of proxy settings.

    • (optional) proxy_port Provide the port number where a proxy is listening for connections for manual configuration of proxy settings.

  4. For example:

    sudo ./csi -address <instance_address> -tcp_port <instance_tcp_port> -key <customer_key_file> -engage enable -proxy_pac_address <pac_URL> -proxy_address <proxy_FQDN_or_IP> -proxy_port <port_number> -tag 1000 -string_tag Preproduction

Enterprise deployment

Collector supports installations in an enterprise environment based on either:

  • Imaging

  • Mobile Device Management (MDM)

Deploying Collector within a MacOS reference image

When including Collector in a MacOS reference image, remove the UID that Collector may have generated to identify the device.

To ensure the removal of the device UID:

  1. Stop nxtcoordinator by running the following command in the Terminal: sudo launchctl unload /Library/LaunchDaemons/com.nexthink.collector.nxtcoordinator.plist

  2. Edit /Library/Application\ Support/Nexthink/config.json with nano/vim/other editor, and remove entries related to license_uid and uid, i.e.:

    • "uid": "<several characters composing the uid>",

    • "license_uid": "<several characters composing the license_uid>",

  3. If the last entry of the file was removed, ensure the JSON format remains valid by also removing the trailing comma after the last remaining entry.

  4. Start nxtcoordinator by running the following command in the Terminal:

    sudo launchctl load /Library/LaunchDaemons/com.nexthink.collector.nxtcoordinator.plist

Uninstalling Collector

To uninstall Collector, execute the uninstaller script that is provided with the .dmg file. Assuming that you have mounted the image file into the filesystem of the computer with Collector installed, type the following command in a macOS shell:

sudo /Volumes/Nexthink_Collector_22.6.2.10\ OSX\ 10.15\ -\ 12/uninstaller

The instruction above uninstalls Collector using version 22.6.2.10 of the uninstaller.

RELATED TASK

Last updated

#451: 2024.8-Overview of integration DOC

Change request updated