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

The -diagnose command detailed below will not execute unless your command line interface is set to an Insight Agent version subfolder. Make sure your current directory is properly set before continuing.

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 - Required if your data region is not United States - 1. 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 not United States - 1, include the -region option with one of the following region codes:
    • United States - 2 - us-east-2
    • United States - 3 - us-west-2
    • 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.