Troubleshoot

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:

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.

Test Details

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.

Test Requirements

The connection diagnostics test must execute from a terminal (Mac or Linux) or a command prompt (Windows) with a 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.

Windows Default Directory

1
C:\Program Files\Rapid7\Insight Agent\components\insight_agent\agent_version_number

Mac and Linux Default Directory

1
/opt/rapid7/ir_agent/components/insight_agent/agent_version_number

Command Syntax

See the following example commands for each operating system.

Windows Example Connection Diagnostics Test

1
ir_agent.exe -diagnose -region us-east-1 -proxy https://user:password@10.1.2.3:8443

Mac and Linux Example Connection Diagnostics Test

1
./ir_agent -diagnose -region us-east-1 -proxy https://user:password@10.1.2.3:8443

Option Definitions

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 -region option 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 -region option with one of the following region codes:
  • Canada - ca-central-1
  • Europe - eu-central-1
  • Japan - ap-northeast-1
  • Australia - ap-southeast-2
  • -proxy - Optional. The test can automatically identify and account for proxies that the agent is configured to use, but you can use the -proxy option 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.

View logs

The agent.log file is located in your Insight Agent installation directory. The following directories are default installation locations by operating system:

Windows

1
C:\Program Files\Rapid7\Insight Agent\components\insight_agent\common

Mac and Linux

1
/opt/rapid7/ir_agent/components/insight_agent/common

Enable enhanced logging

Agent logs can be enhanced for debugging purposes if necessary. Make the following changes to enable enhanced logging:

  1. Browse to and open the config.json file in your agent installation directory.
  2. Find and replace all instances of INFO with DEBUG.
  3. Save and close the file.
  4. 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:

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

This is often caused by running the installer without fully extracting the installation package. Complete the following steps to resolve this:

  1. Uninstall the agent. See Agent controls for instructions.
  2. Fully extract the contents of the installation zip file and ensure all files are in the same location as the installer.
  3. 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.