Install Xprotect agents

You can install the Xprotect agent on a host from the host's GUI or CLI utility. Installing agents successfully brings the hosts under security management from Xprotect. You can manage the security of the processes and services running on the hosts from Xprotect. You can also push Xprotect Policies and see the alerts generated for Policy violations on the host.

After the agent is successfully installed, the agent sends the first heartbeat to the instance. The agent initially sends the following inventory data of the hosts; system and software package details, network connectivity details, and the details of the processes and services running on the host. The agent also sends deltas of the inventory changes when it finds changes on the host. After you push Xprotect Policies, the agent sends alerts when policy violations on the hosts, once every five minutes.

Input parameters to install

You will need the following details of the Xprotect instance as the input parameters to install the agent. The input parameters are listed on the Settings > Agents page on the Xprotect UI. These details are unique for an instance.

  • Name of the instance, for example, colortokens-testbed.

  • Fully Qualified Domain Name (FQDN) of the instance (the Spectrum URL), for example, https://colortokens-testbed-xprotect.spectrum.colortokens.com/.

  • An alphanumeric, 8 character installer key for the instance, for example, Ja1mnScU. The installer key is renewed once a year after the instance was first active.

Ways to install

You can install the Xprotect agent in the following ways:

  • From the host's GUI - download an agent installer file from the Settings > Agents page on the Xprotect UI. Copy the installer to the host and run the installer on the host. Supply the input parameters for your instance and complete the installation. The installer files vary by the OS family, Linux flavors, and Windows bit versions. See Install from GUI for more details.

  • From the host's CLI utility - copy a CLI install command from the Settings > Agents page on the Xprotect UI. Supplement the variables in the command with the input parameters for your instance. Optionally, specify the Xprotect tags and Xprotect group for the host. Run the command with your variables and complete the installation. The CLI commands vary by the OS family and Linux flavors. See Install from CLI for more details.

To install Xprotect agents successfully, you must meet some prerequisites. See Supported OSes and prerequisites for more details.

Default installation folders

You can install the Xprotect agents on Linux, macOS, and Windows hosts.

  • For Windows hosts, the agents are installed in the C:\Program Files folder.

  • For Linux and macOS hosts, the agents are installed in the /opt/colortokens/ directory.

The folder/directory where the agent is installed is fixed. You cannot install the agent in other locations.

Install from GUI

Installing the agent from the GUI (especially for multiple hosts at a time) can take longer than from the CLI.

  1. Go to Settings > Agents on the Xprotect UI.

    You will see the Agent Installation page with the input parameters of your instance and the options to download the agent installer file.

  2. Copy or make a note of the input parameters for the instance listed under Installation Instructions. Alternatively, click View Installation Instructions to see and copy the same input parameters.

    These details must be input when you run the installer on the host.

  3. From the drop-down list, select the version of the agent.

  4. Select One of Windows (bit version), macOS, or Linux (flavor).

  5. Download the installer file, copy the file to the host, and run the installer.

  • To see the commands to install the agent from the CLI, click Show Advanced (below the Download options). See Install from CLI for more details.

  • To confirm if the agent is installed successfully, see Agent installed successfully.

Install from CLI

Additional benefits associated with installing the agent from the host's CLI are:

  • You can download and install the agent with a single install command. You do not have to download the agent installer file manually.

  • You can assign the Xprotect tags and add the host to an Xprotect group by adding additional parameters to the command.

  1. Go to Settings > Agents on the Xprotect UI.

    You will see the Agent Installation page with the input parameters for your instance, and the CLI commands to install the agent.

  2. Copy or make a note of the input parameters listed under Installation Instructions.

    These details must be used in the CLI command.

  3. From the drop-down list, select the version of the agent.

  4. Click Show Advanced below the Download options.

    You will see the CLI command to install the agent. This command varies by the OS family.

  5. (Optional) Xprotect agent versions of 8.14.0.133 and later can be set to use a Web proxy server to relay communication between the agents and the Xprotect instance. To install agents with Web proxy server's parameters, select the With Proxy check box.

    The following Four proxy parameters are added to the CLI command - CT_PROXY_HOST, CT_PROXY_PORT, CT_PROXY_USER, and CT_PROXY_PASSPHRASE.

  6. Click the Copy button and paste the command to a local text editor.

  7. Substitute the sample values in the command with the input parameters for your instance.

  8. (Optional) To save time later, specify the group the host must be part of and the tags for the host. See Example: Install the agent from the CLI with Xprotect groups and tags for an example to add a group and tags in the command.

    Xprotect tags the hosts and moves them to the group as soon as the agent is installed, and the host is registered with the instance.

  9. Run the CLI command.

Example: Install the agent from the CLI with Xprotect groups and tags

The following is the CLI command to install the 8.10.0.276 version of the agent on a Windows host.  

powershell -windowstyle hidden -exec bypass -c "(New-Object System.Net.WebClient).DownloadFile('https://<name of the instance>-xprotect.spectrum.colortokens.com/portal/api/v1/agent/downloadFile/colortokens_radar_8.10.0-276_win64.msi', 'colortokens_radar_8.10.0-276_win64.msi')" && msiexec.exe /qb /i colortokens_radar_8.10.0-276_win64.msi COLORMASTER_IP=<name of the instance>-xprotect.spectrum.colortokens.com TENANT_NAME=<name of the instance> AUTH_KEY=<installer key for the instance>

To add the host to an Xprotect group and associate some Xprotect tags, append the following parameters to the command. 

HOST_GROUP_NAME=<name of the group> TAGS=<name of tag1>,<name of tag2>,<name of tag3>

Remember that you can add a host to only One Xprotect group and associate it with multiple Xprotect tags. See Create groups of hosts and Tag hosts for more details.

In this example, we add the host to a group named Database servers and associate it with the London, Primary, and eCommerce tags. 

powershell -windowstyle hidden -exec bypass -c "(New-Object System.Net.WebClient).DownloadFile('https://<name of the instance>-xprotect.spectrum.colortokens.com/portal/api/v1/agent/downloadFile/colortokens_radar_8.10.0-276_win64.msi', 'colortokens_radar_8.10.0-276_win64.msi')" && msiexec.exe /qb /i colortokens_radar_8.10.0-276_win64.msi COLORMASTER_IP=<name of the instance>-xprotect.spectrum.colortokens.com TENANT_NAME=<name of the instance> AUTH_KEY=<installer key for the instance> HOST_GROUP_NAME=Database servers TAGS=London,Primary,eCommerce.

Verification - agent installed successfully

Before you start managing the new hosts in Xprotect, you must verify if the agents were successfully installed on them.

Here are a couple of ways to verify.

1. Hosts page

You must see an entry for the host on the Hosts page. The entry for the host must show Status=Online. This also depends on the real-time connectivity status of the host with the Xprotect instance.

2. Agent services and processes on hosts

See if the services and processes of the Xprotect agent are running on the hosts.

On a Linux host

  • The logs.txt file must show Device registration successful.

  • Run the ps -aef | grep xprotect command. You must see that the xprotect and xprotect-updater processes are Running.

    .

On a macOS host

  • Run the ps -axf | grep xprotect command. You must see that the xprotect and xprotect-updater processes are Running.

On a Windows host

  • Go to Task manager > Details. The Xprotect.exe and XprotectUpdater.exe processes must be Running.

  • Go to Task manager > Services. The Xprotect and XprotectUpdater services must be Running.

Issue - agent is not installed successfully

If you cannot see the entry for the new host on the Hosts page, you can presume that the installation has failed. One of the primary reasons for failed installations is that all the prerequisites are not met. 

Ensure that you meet the prerequisites to install Xprotect agents. See Supported OSes and prerequisites for more details.

Go through the agent log file to see why the installation failed. The agent log file logs.txt is located here - Linux and macOS (/opt/colortokens/xprotect/logs) and Windows (C:\Program Files\Colortokens\xprotect\logs).

If you cannot install Xprotect agents despite meeting the prerequisites, send us an email to customer.support@colortokens.com, with the logs.txt file as the attachment.

Next steps

  • If you are managing newly added Windows hosts and want to disable the ability to uninstall agents from the hosts, enable the Self-protect feature on the hosts. This feature is only available for Windows hosts. See Manage hosts in Xprotect for more details.

  • To monitor the progress of agent installs for large deployments that span across days, use the New Installs widget on the Dashboard page to see the list of the hosts on which agents were installed in the last 24 hours. Click this widget and see the Hosts page filtered by the Installed On=Last 24 Hours filter. See Xprotect Dashboard for more details.

  • Add the new hosts to Xprotect groups. This is important because the hosts are not protected with Xprotect Policies until you add them to groups.

    Xprotect assigns and pushes the default Xprotect Policies (by the OS family) to the hosts when you add them to groups. The default Policies contain the latest, well-known rules; these rules can protect the hosts until you assign and push custom Xprotect Policies.

    See Create groups of hosts for more details.

  • Tag hosts with Xprotect tags. This can help you filter hosts by tags and use the tags to add Auto-delete rules. Auto-delete rules delete the entries of unessential, unreachable hosts from the Hosts page. See Tag hosts for more details.

  • ColorTokens often adds new features and improves the existing features in Xprotect. See the updates for Xprotect and enable and configure the features. See Xprotect Release Notes for more details.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.