Certificate Package Installation Method

This article is intended for users who elect to deploy the Insight Agent with the legacy certificate package installer. Certificate packages expire after 5 years and must be refreshed to ensure new installations of the Insight Agent are able to connect to the Insight Platform.

Still need to download the installer?

See the Download page for instructions on how to download the proper certificate package installer for the operating system of your intended asset.

This article covers the following topics:

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.

Certificate Package Contents

Your certificate package ZIP file contains the following security files in addition to the installer executable:

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

IMPORTANT

These security files must be in the same directory as the installer before you start the installation process.

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

To install the Insight Agent using the certificate package on Windows assets:

  1. Fully extract the contents of your certificate package ZIP file. Make sure that the .msi installer and its dependencies are in the same directory.
  2. Run the .msi installer with Run As Administrator. The Insight Agent will be installed as a service and appear with the name "Rapid7 Insight Agent" in your service manager.

Silent Installation on Windows

NOTE - Administrator privileges required

Your command prompt must have administrator privileges in order to perform a silent installation.

If you want to perform a silent installation of the Insight Agent, you can do so by running one of the following commands on the command line according to your system architecture:

For 32-bit installers and systems: msiexec /i agentInstaller-x86.msi /quietFor 64-bit installers and systems: msiexec /i agentInstaller-x86_64.msi /quiet

Install on Mac and Linux

TIP

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

See the following procedures for Mac and Linux certificate package installation instructions:

Install the Insight Agent on Linux (Intel)

  1. Fully extract the contents of your certificate package ZIP file. Make sure that the .sh installer script and its dependencies are in the same directory.

  2. Run the following command in a terminal to modify the permissions of the installer script to allow execution:

 
1
chmod u+x agent_installer-x86_64.sh
  1. Lastly, run the following command to execute the installer script. The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager:
 
1
sudo ./agent_installer-x86_64.sh install_start
Install the Insight Agent on Linux (ARM64)

  1. Fully extract the contents of your certificate package ZIP file. Make sure that the .sh installer script and its dependencies are in the same directory.

  2. Run the following command in a terminal to modify the permissions of the installer script to allow execution:

 
1
chmod u+x agent_installer-arm64.sh
  1. Lastly, run the following command to execute the installer script. The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager:
 
1
sudo ./agent_installer-arm64.sh install_start
Install the Insight Agent on Mac (Intel)

  1. Fully extract the contents of your certificate package ZIP file. Make sure that the .sh installer script and its dependencies are in the same directory.

  2. Run the following command in a terminal to modify the permissions of the installer script to allow execution:

 
1
chmod u+x agent_installer-x86_64.sh
  1. Lastly, run the following command to execute the installer script. The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager:
 
1
sudo ./agent_installer-x86_64.sh install_start
Install the Insight Agent on Mac (ARM64)

  1. Fully extract the contents of your certificate package ZIP file. Make sure that the .sh installer script and its dependencies are in the same directory.

  2. Run the following command in a terminal to modify the permissions of the installer script to allow execution:

 
1
chmod u+x agent_installer-arm64.sh
  1. Lastly, run the following command to execute the installer script. The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager:
 
1
sudo ./agent_installer-arm64.sh install_start

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.

Expired certificates

If you use the Certificate Package Installation method to install the Insight Agent, your certificates will expire after 5 years. Insight Agents that were previously installed with a valid certificate are not impacted and will continue to update their SSL certificates. New installations of the Insight Agent using an expired certificate will not be able to fully connect to the Insight Platform to run jobs in InsightVM, InsightIDR, or InsightOps.

Refresh your certificates

If you host your certificate package on a network share, or if it is baked into a golden image for a virtual machine, redownload your certificate package within 5 years to ensure new installations of the Insight Agent run correctly.

Using the Token-Based Installation Method

We recommend using the Token-Based Installation Method for future mass deployments and deleting the expired certificate package. This method is the preferred installer type due to its ease of use and eliminates the need to redownload the certificate package after 5 years.

To reinstall the certificate package using the Certificate Package Installer, follow the steps above to Install on Windows and Install on Mac and Linux.