Deploy the Insight Agent

Token-Based Installer (Preferred)

The token-based installer is the newer Insight Agent installer type and eliminates much of the configuration complexity inherent to its certificate package counterpart. In almost all situations, it is the preferred installer type due to its ease of use.

How the Token Works

The token-based installer is a single executable file formatted for your intended operating system. At the time of execution, the installer uses a token that you specify to pull all the necessary certificates from the Insight Platform that pertain to your organization. Since this installer automatically downloads and locates its dependencies for you, it significantly reduces the number of steps involved for any Insight Agent deployment.

Certificate Package Installer (Legacy)

The certificate package installer predates the token-based variant and relies on the user to properly locate all dependencies during deployment. It is considered a legacy installer type because the token-based installer achieves the exact same purpose with reduced complexity. However, some deployment situations may be more suited to the certificate package installer type. For example, the certificate package installer type is often the only option if you need to deploy the Insight Agent on restricted or firewalled systems.

How the Certificate Package Works

The certificate package installer comes in the form of a ZIP file that also contains the necessary certificates that pertain to your organization. Since these dependencies come in the ZIP file itself, the installer does not rely on the Insight Platform to retrieve them. However, this also means that you must properly locate the installer with its dependencies in order for the installation to complete successfully.

Installer requirements

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.
  • As long as you verify the network connectivity requirements noted previously, this communication channel will be available for use.
• 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

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

1. Open a terminal and change the execute permissions of the installer script:

 
1
chmod u+x agent_installer-x86_64.sh

2. 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.

1. Open a terminal and change the execute permissions of the installer script:

 
1
chmod u+x agent_installer-arm64.sh

2. 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.

1. Open a terminal and change the execute permissions of the installer script:

 
1
chmod u+x agent_installer-x86_64.sh

2. 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.

1. Open a terminal and change the execute permissions of the installer script:

 
1
chmod u+x agent_installer-arm64.sh

2. 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.