Mac Installation

This article guides you through the installation process for the Insight Agent on your assets if you are using the Mac 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.

Install the Insight Agent on MacOS (.pkg)

See the below instructions for the .pkg installation guide. The .pkg installer supports both the Token-Based Installation Method and the Certificate Package Installation Method.

Step 1: Install the Insight Agent (.pkg)

  1. After downloading the .pkg file for the architecture of your choice, open a terminal and navigate to the directory where your download is located.
  2. Run the following commands to install the Insight Agent using .pkg package manager (ensure you substitute the {version} and {architecture} placeholder values before executing these commands):
1
installer -verbose -pkg rapid7-insight-agent-{version}-1.{architecture}.pkg -target /

Step 2: Configure the Insight Agent (.pkg)

Warning - Skip this step if you used the PKG-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 PKG-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.sh

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

Installing the Insight Agent using a token (.pkg)

This example configuration script command utilizes the token method (substitute the {token} portion with your complete token shown in your Agent Management interface), 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 Agent using the certificate package (.pkg)

  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 PKG-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 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 (.pkg)

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

How to verify the PKG signature

If you want to verify the PKG signature, you can do so with the following command:

1
pkgutil --check-signature rapid7-insight-agent-{version}-1.{architecture}.pkg

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

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

1
launchctl start com.rapid7.ir_agent

How to uninstall PKG-edition Insight Agents (.pkg)

If you need to uninstall a PKG-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/opt/rapid7/ir_agent/components/insight_agent/{version}/uninstall.sh

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

1
launchctl list com.rapid7.ir_agent

How to stop the Insight Agent service (.pkg)

1
launchctl stop com.rapid7.ir_agent

How to check which Rapid7 Insight Agents are installed (.pkg)

1
pkgutil --pkgs | grep rapid7

Advanced installation options

The Insight Agent has multiple advanced options for customization. Read more about these in our advanced installation options overview.