The following sections list known troubleshooting scenarios and how to address them. If you need to run commands to control the Insight Agent service, see Agent controls:
- Run Connection Diagnostics
- View logs
- Enable enhanced logging
- Agent service is present, but won’t start
- Inconsistent assessment results on virtual assets
For product specific agent troubleshooting, see the following pages:
Run Connection Diagnostics
If any of your Insight Agents experience connection issues or other errors, you can check the connectivity of the agent to troubleshoot the problem. The Insight Agent service features a connection diagnostics command that you can run to verify several points of the connection’s journey to the Insight platform.
This connection diagnostics test consists of four to five individual checks, depending on the presence of a configured proxy for the agent or an explicit proxy command argument. These checks include:
- Socket Connection
- HTTP CONNECT (when a proxy is detected or explicitly passed)
- Agent Ping
- TLSv1.2 Handshake
- Agent Message
All checks must pass for the overall connection diagnostics test to pass.
The connection diagnostics test must execute from a terminal (Mac or Linux) or a command prompt (Windows) with the current directory set to the version subfolder of the Insight Agent installation directory. Ensure that the current directory of your terminal or command prompt is set to the correct location. Default installation directories are as follows.
Check your current directory
-diagnose command detailed below will not execute unless your command line interface is set to an Insight Agent version subfolder. Make sure your currenty directory is properly set before continuing.
Windows Default Directory
1C:\Program Files\Rapid7\Insight Agent\components\insight_agent\agent_version_number
Mac and Linux Default Directory
See the following example commands for each operating system.
Windows Example Connection Diagnostics Test
1ir_agent.exe -diagnose -region us-east-1 -proxy https://user:firstname.lastname@example.org:8443
Mac and Linux Example Connection Diagnostics Test
1./ir_agent -diagnose -region us-east-1 -proxy https://user:email@example.com:8443
The options of this command are defined as follows:
-diagnose- Required. This initiates the connection diagnostics test.
-region- Technically optional, but required if your data region is not in the United States. The
-regionoption allows you to specify your appropriate data region as a test target for the agent. If you omit this option from the command, the test target defaults to
us-east-1. If your data region is outside the United States, include the
-regionoption with one of the following region codes:
- Canada -
- Europe -
- Japan -
- Australia -
- Canada -
-proxy- Optional. The test can automatically identify and account for proxies that the agent is configured to use, but you can use the
-proxyoption to explicitly test against a proxy address of your choice. These example commands include basic authentication (
user:password@) for syntax purposes, but authentication is not required for the test to run.
agent.log file is located in your Insight Agent installation directory. The following directories are default installation locations by operating system:
1C:\Program Files\Rapid7\Insight Agent\components\insight_agent\common
Mac and Linux
Enable enhanced logging
Agent logs can be enhanced for debugging purposes if necessary. Make the following changes to enable enhanced logging:
- Browse to and open the
config.jsonfile in your agent installation directory.
- Find and replace all instances of
- Save and close the file.
- Restart the Insight Agent service.
Provide Support with your enhanced
agent.log file for further review.
Agent service is present, but won’t start
The Insight Agent service will not run if required configuration files are missing from the installation directory. These files include:
This is often caused by running the installer without fully extracting the installation package. Complete the following steps to resolve this:
- Uninstall the agent. See Agent controls for instructions.
- Fully extract the contents of the installation zip file and ensure all files are in the same location as the installer.
- Run the installer again.
Inconsistent assessment results on virtual assets
The Insight Agent uses the system’s hardware UUID as a globally unique identifier. In virtual deployments, the UUID is supplied by the virtualization software. Improperly configured VMs may lead to UUID collisions, which can cause assessment conflicts in your Insight products.
If you mass deploy the Insight Agent to several VMs, make sure you follow the special procedures outlined on our Virtualization page.