Linux Installation

Open Preview Migration Steps

If you have previously installed the agent with either .deb or .rpm as part of our Open Preview program, complete the required migration steps.

This article guides you through the installation process for the Insight Agent on your assets if you are using the Linux Operating System.

Linux & Mac .sh Installer Deprecation

The .sh Insight Agent installer will be deprecated on November 15, 2024. It is accessible until that date through our installation guides.

Still need to download the installer? See the Download and Installation overview page for instructions on how to download the correct installer for the operating system of your intended asset.

Requirements

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.

The Insight Agent installer supports 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

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 if you want to have data on that host. The Collector is not an Agent on its own.

How to Install the Insight Agent on RedHat-based Linux (.rpm)

See the below instructions for the .rpm installation guide. The .rpm installer can be applied with both the Token-Based Installation Method and the Certificate Package Installation Method.

GPG Verification

You can verify the GPG signature for the following files by downloading Rapid7's public key

To list the public GPG key installed on the machine:

rpm -qa gpg-*

To manually import the public GPG key:

rpm --import {public-GPG-key-here}

To get details about the public GPG key installed on the machine:

rpm -qi gpg-pubkey-{version-release-here}

To verify the RPM files:

rpm -K rapid7-insight-agent-{version}-0.{architecture}.rpm.

Step 1: install the Insight Agent (.rpm)

After downloading the file for the architecture of your choice, place the installer in a directory on the host machine and navigate to it. Run the following commands to install the Insight Agent using either the RPM or DNF package managers (make sure to substitute the {version} and {architecture} placeholder values before executing these commands):

RPM installation command

1
sudo rpm -i rapid7-insight-agent-{version}-0.{architecture}.rpm

DNF installation command

1
sudo dnf -i rapid7-insight-agent-{version}-0.{architecture}.rpm

Step 2: configure the Insight Agent (.rpm)

Skip this step in the event of a version upgrade or if you used the RPM-edition installer to replace an existing .sh-edition Insight Agent

You only need to run the configuration script detailed in this step if you use the RPM-edition installer for a fresh installation. This step is unnecessary if you are replacing an existing .sh-edition of the Insight Agent. All previously set agent properties (including the agent's ID, proxy configuration, and attributes) will be automatically preserved.

After a fresh installation, run the configure_agent.sh configuration script to connect the agent to the Insight Platform. This script will make the agent fully operational. You can find this script in the following location of your agent installation directory ({version} will correspond to the agent version you have just installed):

1
/opt/rapid7/ir_agent/components/insight_agent/{version}/configure_agent.sh

With the .rpm installer, you can configure the Insight Agent by using the Token Package Installation Method or the Certificate Package Installation Method. Read more about these options in the overview page

Available arguments

The configuration script supports several arguments you can specify to configure a variety of Insight Agent options. Run configure_agent.sh help in your terminal to display an explanation of these arguments. These details are reproduced here for your convenience:

1
1
2
-a, --attributes=ATTRIBUTES: Custom attributes may be used to identify and group Insight Agents in ways that are meaningful to your organization. Use commas to specify multiple attributes. Example: --attributes=\"lab_system, managed, commercial\"
3
2
4
5
6
3
7
-c, --certificate_package_installation=PACKAGE_PATH: Supply a path to the configuration files if already downloaded or where they should be downloaded if using a token
8
4
9
10
11
5
12
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
13
6
14
15
16
7
17
-p, --https-proxy=PROXY: Supply an HTTPS proxy for the Insight Agent to use when communicating with the Insight Platform. Example: --https-proxy=example.rapid7.com:3128, with credentials --https-proxy=<username>:<password>@example.rapid7.com:3128
18
8
19
20
21
9
22
--disable-updates: Disable Platform managed updates for all Insight Agent sub-components (default: False)
23
10
24
25
26
11
27
-s, --start: Start the agent service after configuration is complete
28
12
29
30
31
13
32
-v: Prints all logs to stderr
33
14
34
35
36
15
37
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail
38
16
39
40
41
17
42
--no_version_check: If a newer version of this script is found, proceed with configuration

Installing the Insight Agent using a token (.rpm)

This example configuration script command utilizes the token method (substitute the {token} portion with your complete token shown in your Agent Management interface), specifies a proxy address (substitute the {proxy-address} portion with the IP address and port of your proxy), and configures several attributes. Finally, the script is instructed to start the agent service:

1
./configure_agent.sh --token {token} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

Installing the Insight Agent using the certificate package (.rpm)

If you need to complete your agent configuration using the certificate package method, you first need to download the necessary certificate files from the Insight Platform:

  1. Extract the contents of the package to retrieve the certificate files (do not run the installer scripts that are included alongside the certificate files as they are not used in this procedure):
  • client.key
  • client.crt
  • config.json
  • cafile.pem
  1. Relocate these certificate files to the installation directory of your RPM-edition Insight Agent.
  2. Finally, run the configuration script to finish.

This example configuration script command targets the configuration files you just downloaded (substitute the {path-to-cert-files} with the local path where the files are stored), specifies a proxy address (substitute the {proxy-address} portion with the IP address and port of your proxy), and configures several attributes. Finally, the script is instructed to start the agent service:

1
./configure_agent.sh --certificate_package_installation {path-to-cert-files} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

Other useful commands (.rpm)

View the followings section for additional commands for your Insight Agent.

How to update the Insight Agent (.rpm)

Update all Insight Agents automatically (.rpm)

Just like your other Insight Agents, your RPM-edition agents will update themselves according to the Platform update settings you have configured in your Agent Management interface. Navigate to Settings > Managed Agent Updates in Agent Management to adjust these controls.

RPM and DNF package managers may not recognize agent updates initiated by Agent Management

Due to the way the Insight Agent's component manager performs its update process, be aware that the RPM and DNF package managers might not recognize that an agent has been updated to a new version if the update was initiated by your Agent Management settings. If you allow Agent Management to update to your agents automatically, always regard the Agent Management interface as the single source of truth for the version status of your RPM-edition agents.

Update the Insight Agent manually (.rpm)

If you prefer to have manual control over your RPM-edition Insight Agent update process, you can update them with the following RPM and DNF commands (make sure to substitute the {version} and {architecture} placeholder values with the currently installed values before executing these commands):

RPM update command

1
rpm -U rapid7-insight-agent-{version}-0.{architecture}.rpm

DNF update command

If you utilize a private DNF repository, you only need to run the second command listed here. This will automatically update both packages.

1
dnf install rapid7-insight-agent-{version}-0.{architecture}.rpm

How to Uninstall the Insight Agent (.rpm)

If you need to uninstall an RPM-edition Insight Agent, you will need to uninstall both the Insight Agent component and the component manager separately. You can do so with these RPM and DNF commands:

RPM uninstall command

1
rpm -e rapid7-insight-agent

DNF uninstall command

1
dnf remove rapid7-insight-agent

How to manually start the Insight Agent service (.rpm)

The configuration script detailed in step 2 features its own attribute that you can include to start the Insight Agent service automatically, but if you need to start the agent service separately for any reason, you can do so with the following command:

1
systemctl start ir_agent.service

How to check the status of the Insight Agent service (.rpm)

1
systemctl status ir_agent.service

How to stop the Insight Agent service (.rpm)

1
systemctl stop ir_agent.service

How to check which Rapid7 packages are installed (.rpm)

1
dnf search rapid7

How to Install the Insight Agent on Debian-based Linux (.deb)

See the below instructions for the .deb installation guide. The .deb installer can be applied with both the Token-Based Installation Method and the Certificate Package Installation Method.

GPG Verification

You can verify the GPG signature for the following files by downloading Rapid7's public key

To manually import the public GPG key:

gpg --import {public-GPG-key-here}

Before you can verify the signature of the installation files, you'll need to install the dpkg-sig utility first. To install dpkg-sig:

sudo apt-get install dpkg-sig

Finally, to verify the DEB files:

dpkg-sig -c rapid7-insight-agent-{version}-1.{arch-code}.deb

Step 1: Install the Insight Agent (.deb)

Next, change the working directory of your terminal to the newly created folder produced by the extraction. Run the following commands to install the Insight Agent using the Advanced Package Tool (APT) package manager (make sure to substitute the {version} and {arch-code} placeholder values before executing these commands):

1
sudo apt-get install ./rapid7-insight-agent-{version}-1.{arch-code}.deb

Step 2: Configure the Insight Agent (.deb)

Skip this step if you used the DEB-edition installer to replace an existing .sh-edition Insight Agent

You only need to run the configuration script detailed in this step if you use the DEB-edition installer for a fresh installation. This step is unnecessary if you are replacing an existing .sh-edition of the Insight Agent. All previously set agent properties (including the agent's ID, proxy configuration, and attributes) will be automatically preserved.

After a fresh installation, run the configure_agent.sh configuration script to connect the agent to the Insight Platform. This script will make the agent fully operational. You can find this script in the following location of your agent installation directory ({version} will correspond to the agent version you have just installed):

1
/opt/rapid7/ir_agent/components/insight_agent/{version}/

With the .deb installer, you can configure the Insight Agent by using the Token Package Installation Method or the Certificate Package Installation Method. Read more about these options in the overview page

Available Arguments

The configuration script supports several arguments you can specify to configure a variety of Insight Agent options. Run configure_agent.sh help in your terminal to display an explanation of these arguments. These details are reproduced here for your convenience:

1
1
2
-a, --attributes=ATTRIBUTES: Custom attributes may be used to identify and group Insight Agents in ways that are meaningful to your organization. Use commas to specify multiple attributes. Example: --attributes=\"lab_system, managed, commercial\"
3
2
4
5
6
3
7
-c, --certificate_package_installation=PACKAGE_PATH: Supply a path to the configuration files if already downloaded or where they should be downloaded if using a token
8
4
9
10
11
5
12
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
13
6
14
15
16
7
17
-p, --https-proxy=PROXY: Supply an HTTPS proxy for the Insight Agent to use when communicating with the Insight Platform. Example: --https-proxy=example.rapid7.com:3128, with credentials --https-proxy=<username>:<password>@example.rapid7.com:3128
18
8
19
20
21
9
22
-s, --start: Start the agent service after configuration is complete
23
10
24
25
26
11
27
-v: Prints all logs to stderr
28
12
29
30
31
13
32
--disable-updates: Disable Platform managed updates for all Insight Agent sub-components (default: False)
33
14
34
35
36
15
37
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail.
38
16
39
40
41
17
42
--no_version_check: If a newer version of this script is found, proceed with configuration

Installing the Agent using a Token (.deb)

This example configuration script command utilizes the token method (substitute the {token} portion with your complete token shown in your Agent Management interface), specifies a proxy address (substitute the {proxy-address} portion with the IP address and port of your proxy), and configures several attributes. Finally, the script is instructed to start the agent service:

1
./configure_agent.sh --token {token} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

Installing the Certificate Package (.deb)

  1. Extract the contents of the package to retrieve the certificate files (do not run the installer scripts that are included alongside the certificate files as they are not used in this procedure):
  • client.key
  • client.crt
  • config.json
  • cafile.pem
  1. Relocate these certificate files to the installation directory of your DEB-edition Insight Agent.
  2. Finally, run the configuration script to finish.

This example configuration script command targets the configuration files you just downloaded (substitute the {path-to-cert-files} with the local path where the files are stored), specifies a proxy address (substitute the {proxy-address} portion with the IP address and port of your proxy), and configures several attributes. Finally, the script is instructed to start the agent service:

1
./configure_agent.sh --certificate_package_installation {path-to-cert-files} -v --https-proxy={proxy-address} --attributes "attribute1,attribute2,attribute3,attribute4" --start

Other useful commands (.deb)

View the followings section for additional commands for your Insight Agent.

How to update the Insight Agent (.deb)

This section contains instructions on how to manage the update process for your DEB-edition Insight Agents.

Update all Insight Agents automatically (.deb)

Just like your other Insight Agents, your DEB-edition agents will update themselves according to the automatic update settings you have configured in your Agent Management interface. Navigate to Settings > Automatic Agent Updates in Agent Management to adjust these controls.

The APT package manager may not recognize agent updates initiated by Agent Management

Due to the way the Insight Agent's component manager performs its update process, be aware that the APT package manager might not recognize that an agent has been updated to a new version if the update was initiated by your Agent Management settings. If you allow Agent Management to update to your agents automatically, always regard the Agent Management interface as the single source of truth for the version status of your DEB-edition agents.

Update Insight Agents manually (.deb)

If you prefer to have manual control over your DEB-edition Insight Agent update process, you can update them with the following APT commands (make sure to substitute the {version} and {arch-code} placeholder values with the currently installed values before executing these commands):

1
sudo apt-get install ./rapid7-insight-agent-{version}-1.{arch-code}.deb

You must restart the Insight Agent service after performing a manual update

When initiating a manual update of the Insight Agent, the agent service will stop to allow the process to complete. After the update finishes, you will need to restart the agent service manually as well. You can do so with this command:

systemctl restart ir_agent.service

How to uninstall Insight Agents (.deb)

If you need to uninstall a DEB-edition Insight Agent, you will need to uninstall both the Insight Agent component and the component manager separately. You can do so with these APT commands:

1
sudo apt-get remove rapid7-insight-agent

How to manually start the Insight Agent service (.deb)

The configuration script detailed in step 2 features its own attribute that you can include to start the Insight Agent service automatically, but if you need to start the agent service separately for any reason, you can do so with the following command:

1
systemctl start ir_agent.service

How to check the status of the Insight Agent service (.deb)

1
systemctl status ir_agent.service

How to stop the Insight Agent service (.deb)

1
systemctl stop ir_agent.service

Advanced Installation Options

The Insight Agent has multiple advanced options for customization. Read more about these here.