Token-Based Installation Method

The token-based installer is the preferred method for installing the Insight Agent on your assets. This article guides you through this installation process.

Still need to download the installer?

See the Download page for instructions on how to download the proper token-based installer for the operating system of your intended asset.

Requirements

The Insight Agent supports proxies

Both the token-based and certificate package installer types support proxy definitions. If you need to direct your agents to send data through a proxy before reaching the Insight platform, see the Proxy Configuration page for instructions.

Before proceeding with the installation, verify that your intended asset is running a supported operating system and meets the connectivity requirements. If your organization also uses endpoint protection software, ensure that the Insight Agent is allowed to run when detected.

Install the Insight Agent on the Collector

As with the rest of the endpoints on your network, you must install the Insight Agent on the Collector.

The token-based installer also requires the following:

  • Your asset must be able to communicate with the Insight platform in order for the installer to download its necessary dependencies.
  • If your assets are deployed in a network with strict URL filtering rules in place, you may need to whitelist the following token resource endpoint to ensure that the installer can pull its configuration files from the Insight Platform. Substitute <REGION> with the code that applies to your data region:
 
1
https://<REGION>.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files

Installer Characteristics

Unlike the certificate package variant, the token-based installer does not include its necessary dependencies when downloaded. Instead, the installer uses a token specific to your organization to send an API request to the Insight platform. This allows the installer to download all required files at install time and place them in the appropriate directories on your asset.

When the installer runs, it downloads and installs the following dependencies on your asset. All together, these dependencies are no more than 20KB in size:

  • client.key
  • client.crt
  • config.json
  • cafile.pem

Generate a Token

The first step of any token-based Insight Agent deployment is to generate your organizational token. If you were directed to this article from the Download page, you may have done this already when you downloaded your installer.

Token Overview

Your token consists of two parts:

  • The region identifier - This portion identifies the region where your organization is located. For example, us is the region identifier for the United States, while ca is the region identifier for Canada.
  • The Universally Unique Identifier (UUID) - The UUID represents the token itself. The API request initiated by the installer sends this UUID to the Insight platform in order to retrieve the JSON document that contains all the necessary dependencies noted previously.

A fully generated token appears in the following format:

us:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

To generate a token (if you have not done so already):

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
    • If you are not directed to the Insight Platform Home page upon signing in, open the navigator in the upper left corner of the screen and click Insight Platform Home.
  2. Open the left menu and click the Data Collection Management tab, then click Agents.
  3. Click Add New in the upper right corner of the page. The Download Insight Agent page displays with a group of supported operating systems.
  4. Click any of these operating system buttons to open their respective installer download panel.
  5. On the Download tab of this panel, navigate to the Token Management section and click Generate.
    • For Windows assets, you must copy your token and enter it during the installation wizard, or format it manually in an installation command for the command prompt.
    • For Mac and Linux assets, the Download tab in this panel automatically formats your install command to include your current token.

NOTE - Does your company have multiple Rapid7 organizations?

Keep in mind that a token is specific to one organization. If your company has multiple organizations with Rapid7, make sure you select the correct organization from the "Download Insight Agent" page before you generate your token.

Agent Attributes for InsightVM

Agent attribute configuration is an optional asset labeling feature for customers using the Insight Agent for vulnerability assessment with InsightVM. Configured exclusively using the command line installation method, InsightVM imports agent attributes as asset tags that you can use to group and sort your assets in a way that is meaningful to your organization.

If you want to install your agents with attributes, check out the Agent Attributes page to review the syntax requirements before continuing with the rest of this article.

Install on Windows

Windows is the only operating system that supports installation of the agent through both a GUI-based wizard and the command line. This section covers both installation methods.

Install using the Wizard

The installation wizard guides you through the setup process and automatically downloads the configuration files to the default directories.

NOTE

If you want to store the configuration files in a custom location, you’ll need to install the agent using the command line.

To install the Insight Agent using the wizard:

  1. Run the .msi installer.
  2. Follow the prompts to install the Insight Agent.
  3. When the "Agent Pairing" screen appears, select the Pair using a token option.
  4. Enter your token in the provided field.
  5. Advance through the remaining screens to complete the installation process. The Insight Agent will be installed as a service and appear with the name "Rapid7 Insight Agent" in your service manager.

What if I wasn’t prompted to enter my token?

If the "Agent Pairing" screen does not appear during the wizard, the installer may have detected existing dependencies for the Insight Agent on your asset. To resolve this issue, delete any of those files manually and try running the installer again.

Install Using the Command Line

Running the Windows installer from the command line allows you to specify a custom path for the agent’s dependencies, configure any agent attributes for InsightVM, and perform a silent installation.

The following example command utilizes these flags:

  • CUSTOMCONFIGPATH - The absolute path where the installer downloads its dependencies.
    • If you specify this path as a network share, the installer must have write access in order to place the files. Additionally, any local folder specified here must be a writable location that already exists.
  • CUSTOMTOKEN - The token you generated and copied from the Insight Agent download panel.
    • Note that the token flag is always required. If the token is not specified, the installer will have no way to download the necessary dependencies.

REMINDER

Unlike its usage with the certificate package installer, the CUSTOMCONFIGPATH flag has a different function when used with the token-based installer. In this example, the path you specify establishes the target directory where the installer will download and place its necessary configuration files.

If you omit this flag from your command line operation, all configuration files will download to the current directory of the installer.

To perform a silent installation of a token-based installer with a custom path, run the following command in a command prompt. Substitute <target-directory-for-dependencies> and <regionalID:UUID> with your custom path and token, respectively:

 
1
msiexec /i agentInstaller-x86_64.msi /l*v insight_agent_install_log.log CUSTOMCONFIGPATH=<target-directory-for-dependencies> CUSTOMTOKEN=<regionalID:UUID> /quiet

The Insight Agent will be installed as a service and appear with the name "Rapid7 Insight Agent" in your service manager.

Install on Mac and Linux

TIP

All Mac and Linux installations of the Insight Agent are silent by default.

Running the Mac or Linux installer from the terminal allows you to specify a custom path for the agent’s dependencies and configure any agent attributes for InsightVM.

The following example command utilizes these flags:

  • --config_path - The absolute path where the installer downloads its dependencies.
    • Note that if you specify this path as a network share, the installer must have write access in order to place the files. Additionally, any local folder specified here must be a writable location that already exists.
  • --token - The token you generated and copied from the Insight Agent download panel.
    • Note that the token flag is always required. If the token is not specified, the installer will have no way to download the necessary dependencies.

REMINDER

Unlike its usage with the certificate package installer, the --config_path flag has a different function when used with the token-based installer. In this example, the path you specify establishes the target directory where the installer will download and place its necessary configuration files.

If you omit this flag from your command line operation, all configuration files will download to the current directory of the installer.

Install the Insight Agent on Linux (Intel)

  1. Open a terminal and change the execute permissions of the installer script:
 
1
chmod u+x agent_installer-x86_64.sh
  1. Copy and run the command that was formatted for you in the Linux download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
 
1
sudo ./agent_installer-x86_64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

 
1
sudo ./agent_installer-x86_64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

 
1
sudo ./agent_installer-x86_64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Linux (ARM64)

  1. Open a terminal and change the execute permissions of the installer script:
 
1
chmod u+x agent_installer-arm64.sh
  1. Copy and run the command that was formatted for you in the Linux download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
 
1
sudo ./agent_installer-arm64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

 
1
sudo ./agent_installer-arm64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

 
1
sudo ./agent_installer-arm64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Mac (Intel)

  1. Open a terminal and change the execute permissions of the installer script:
 
1
chmod u+x agent_installer-x86_64.sh
  1. Copy and run the command that was formatted for you in the Mac download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
 
1
sudo ./agent_installer-x86_64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

 
1
sudo ./agent_installer-x86_64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

 
1
sudo ./agent_installer-x86_64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Mac (ARM64)

  1. Open a terminal and change the execute permissions of the installer script:
 
1
chmod u+x agent_installer-arm64.sh
  1. Copy and run the command that was formatted for you in the Mac download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
 
1
sudo ./agent_installer-arm64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

 
1
sudo ./agent_installer-arm64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

 
1
sudo ./agent_installer-arm64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.


How to Uninstall

If you want to uninstall the Insight Agent from your assets, see the Agent Controls page for instructions.

NOTE - Agent directory retention after uninstalling

In order to quicken agent uninstalls and streamline any potential reinstalls, be aware that agent uninstallation procedures still retain portions of the agent directory on the asset.

If you need to remove all remaining portions of the agent directory, you must do so manually.