Linux Installation

Open Preview migration steps

If you have previously installed the Insight Agent with either .deb or .rpm as part of our Open Preview program, complete the required migration steps. You do not need to do anything if you have not taken part in our Open Preview program.

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

Linux and 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.

Installation permissions

To run the commands listed in this article, you will require sudo permissions.

The Insight Agent installer supports proxy definitions. If you need to direct your Insight 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.

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

The .rpm installer can be applied with both the Token installation option and the Certificate Package installation option and will automatically upgrade your Insight Agents to from the previous .sh installer.

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)

With a Linux installation of the Insight Agent, you must configure the Insight Agent by using either the Token installation option or the Certificate Package installation option. Read more about these options in the overview page.

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

Run the configuration script only if you use the .rpm installer for a fresh installation. This step is unnecessary if you are replacing an existing .sh installation of the Insight Agent. All previously set Insight Agent properties (including the Insight Agent's ID, proxy configuration, and attributes) will be automatically preserved.

You must run the configure_agent.sh configuration script to connect the Insight Agent to the Insight Platform.

You can find this script in the following location of your Insight Agent installation directory ({version} will correspond to the Insight Agent version you have just installed):

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

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:

Available arguments for Linux configuration
 
1
-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\"
2
-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
3
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
4
-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
5
--disable-updates:  Disable Insight Platform managed updates for all Insight Agent sub-components (default: False)
6
-s, --start: Start the Insight Agent service after configuration is complete
7
-v: Prints all logs to stderr
8
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail
9
--no_version_check: If a newer version of this script is found, proceed with configuration

Configure the Insight Agent using a Token (.rpm)

Note for this configuration option you will need to locate (or generate, if necessary) your organization's token by navigating to insight.rapid7.com > Data Collection > Agents > Agent Installer > Token Management.

Use the following configuration command, substituting {token} with your orgnization's token and {proxy-address} with the IP address and port of your proxy. This example command also configures several attributes and starts the Insight Agent service:

 
1
 sudo -i
2


3
cd /opt/rapid7/ir_agent/components/insight_agent/{version}/

Run one of the following based on whether you have proxy and attributes:

  • Without proxy and attributes: ./configure_agent.sh --token={token} -v --start
  • With proxy and attributes: 
     
    1
    ./configure_agent.sh --token {token} -v --https-proxy={proxy-address} --attributes
    2
    "attribute1,attribute2,attribute3,attribute4" --start

Configure the Insight Agent using the Certificate Package (.rpm)

Note for this configuration option you will need to locate (or generate, if necessary) your organization's token by navigating to insight.rapid7.com > Data Collection > Agents > Agent Installer > Install the Insight Agent using the Certificate Package > Download Certificate..

  1. Extract the contents of the ZIP file to retrieve the following files:
  • client.key
  • client.crt
  • config.json
  • cafile.pem

When configuring the installation of the Insight Agent for Mac, do not use the additional scripts that are included alongside these files, as they are not used in this procedure.

  1. Relocate these certificate files to the installation directory of your installer Insight Agent.
  2. Finally, run the configuration script:
    • 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 Insight 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.

Update the Insight Agent (.rpm)

Update all Insight Agents automatically (.rpm)

Just like your other Insight Agents, your RPM-edition Insight Agents will update themselves according to the Insight 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 Insight 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 Insight 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 Insight Agents automatically, always regard the Agent Management interface as the single source of truth for the version status of your RPM-edition Insight 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

Uninstall the Insight Agent (.rpm)

Use the system's package manager to uninstall the Insight Agent, for example:

  • For RPM: rpm -e rapid7-insight-agent
  • For DNF: dnf remove rapid7-insight-agent

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, however if you need to start the Insight Agent service separately for any reason, you can do so with the following command:

 
1
systemctl start ir_agent.service

Check the status of the Insight Agent service (.rpm)

 
1
systemctl status ir_agent.service

Stop the Insight Agent service (.rpm)

 
1
systemctl stop ir_agent.service

Check which Rapid7 packages are installed (.rpm)

 
1
dnf search rapid7

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

The .deb installer can be applied with both the Token installation option and the Certificate Package installation option.

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)

OS Architecture code legend

The architecture codes contained in each DEB installer filename indicate the OS architecture that the installer is intended for:

  • amd64 = x86-64
  • arm64 = ARM64

After downloading the file for the architecture of your choice, you will need to 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` installer to replace an existing `.sh` Insight Agent

Run the configuration script only if you use the .deb installer for a fresh installation. This step is unnecessary if you are replacing an existing .sh installation of the Insight Agent. All previously set Insight Agent properties (including the Insight Agent's ID, proxy configuration, and attributes) will be automatically preserved.

You must run the configure_agent.sh configuration script to connect the Insight Agent to the Insight Platform.

You can find this script in the following location of your Insight Agent installation directory ({version} will correspond to the Insight Agent version you have just installed):

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

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:

Available arguments for Linux configuration
 
1
-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\"
2
-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
3
-t, --token=TOKEN: Supply a token generated by the server in place of the config files
4
-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
5
--disable-updates:  Disable Insight Platform managed updates for all Insight Agent sub-components (default: False)
6
-s, --start: Start the Insight Agent service after configuration is complete
7
-v: Prints all logs to stderr
8
--no_connectivity_check: Continue configuring the Insight Agent when any connectivity checks fail
9
--no_version_check: If a newer version of this script is found, proceed with configuration

Configure the Insight Agent using a Token (.deb)

Note for this configuration option you will need to locate (or generate, if necessary) your organization's token by navigating to insight.rapid7.com > Data Collection > Agents > Agent Installer > Token Management.

Use the following configuration command, substituting {token} with your orgnization's token and {proxy-address} with the IP address and port of your proxy. This example command also configures several attributes and starts the Insight Agent service:

 
1
 sudo -i
2


3
cd /opt/rapid7/ir_agent/components/insight_agent/{version}/

Run one of the following based on whether you have proxy and attributes:

  • Without proxy and attributes: ./configure_agent.sh --token={token} -v --start
  • With proxy and attributes: 
     
    1
    ./configure_agent.sh --token {token} -v --https-proxy={proxy-address} --attributes
    2
    "attribute1,attribute2,attribute3,attribute4" --start

Configure the Insight Agent using a Certificate Package (.deb)

Note for this configuration option you will need to locate (or generate, if necessary) your organization's token by navigating to insight.rapid7.com > Data Collection > Agents > Agent Installer > Install the Insight Agent using the Certificate Package > Download Certificate..

  1. Extract the contents of the ZIP file to retrieve the following files:
  • client.key
  • client.crt
  • config.json
  • cafile.pem

When configuring the installation of the Insight Agent for Mac, do not use the additional scripts that are included alongside these files, as they are not used in this procedure.

  1. Relocate these certificate files to the installation directory of your installer Insight Agent.
  2. Finally, run the configuration script:
    • 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 Insight 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.

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 Insight 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 Insight 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 Insight 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 Insight Agents automatically, always regard the Agent Management interface as the single source of truth for the version status of your DEB-edition Insight 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 Insight Agent service will stop to allow the process to complete. After the update finishes, you will need to restart the Insight Agent service manually as well. You can do so with this command:

systemctl restart ir_agent.service

Uninstall the Insight Agent (.deb)

Use the system's package manager to uninstall the Insight Agent, for example:

  • For DEB: sudo apt-get remove rapid7-insight-agent

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 Insight Agent service separately for any reason, you can do so with the following command:

 
1
systemctl start ir_agent.service

Check the status of the Insight Agent service (.deb)

 
1
systemctl status ir_agent.service

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 in our advanced installation options overview.