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.

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

The .pkg installer supports both the Token installation option and the Certificate Package installation option.

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)

After a fresh installation, run the configure_agent.sh configuration script to connect the Insight Agent to the Insight Platform. This script will make the Insight Agent fully operational. 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

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

 
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 Insight 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

Configure the Insight Agent using a Token (.pkg)

This example configuration script command utilizes the Token option (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 Insight Agent service:

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

Configure the Insight 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 installer 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.

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

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

Uninstall .pkg installer Insight Agents (.pkg)

If you need to uninstall a .pkg installer 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

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

 
1
launchctl list com.rapid7.ir_agent

Stop the Insight Agent service (.pkg)

 
1
launchctl stop com.rapid7.ir_agent

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.