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

Mac and Linux Example Connection Diagnostics Test

 
1
./ir_agent -diagnose -region us-east-1

Agent with a proxy

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

Mac and Linux with Proxy Example Connection Diagnostics Test

 
1
./ir_agent -diagnose -region us-east-1 -proxy https://user:password@10.1.2.3:8443
Sample Linux Output 
 
1
root@apac-vp:/opt/rapid7/ir_agent/components/insight_agent/4.0.4.14# ./ir_agent -diagnose -region us-east-1
2
-- Starting linux agent --
3
------------------ TEST STARTED ------------------
4
Running connectivity test for the insight agent in region: us-east-1, using proxy: None. 
5
Using SSL certificates under: /opt/rapid7/ir_agent/components/bootstrap/common/ssl.
6
[proxy.Provider.readConfigFileProxy]: proxy configuration file not present: /opt/rapid7/ir_agent/components/bootstrap/common/proxy.config
7
Couldn't discover proxy since No proxy found, runcmd returned value 1.
8
[Direct endpoint.ingress.rapid7.com:443] [Socket Connect] ... PASSED
9
[Direct endpoint.ingress.rapid7.com:443] [Agent Ping] ... PASSED
10
[Direct endpoint.ingress.rapid7.com:443] [TLSv1.2 Handshake] ... PASSED
11
[Direct endpoint.ingress.rapid7.com:443] [Agent Message] ... PASSED
12
------------------ TEST PASSED ------------------
13
root@apac-vp:/opt/rapid7/ir_agent/components/insight_agent/4.0.4.14#
Sample Mac Output 
 
1
Air:4.0.10.72 root# ./ir_agent -diagnose -region us-east-2
2


3
-- Starting darwin agent --
4


5


6
------------------ TEST STARTED ------------------
7


8
Running connectivity test for the insight agent in region: us-east-2, using proxy: None. 
9


10
Using SSL certificates under: /opt/rapid7/ir_agent/components/bootstrap/common/ssl.
11


12
[proxy.Provider.readConfigFileProxy]: proxy configuration file not present: /opt/rapid7/ir_agent/components/bootstrap/common/proxy.config
13


14
[proxy.Provider.readDarwinNetworkSettingProxy]: https proxy is not enabled.
15


16
Couldn't discover proxy since No proxy found, runcmd returned value 1.
17


18
[Direct us2.endpoint.ingress.rapid7.com:443] [Socket Connect] ... PASSED
19


20
[Direct us2.endpoint.ingress.rapid7.com:443] [Agent Ping] ... PASSED
21


22
[Direct us2.endpoint.ingress.rapid7.com:443] [TLSv1.2 Handshake] ... FAILED
23


24
Cause: [SSL: TLSV1_ALERT_INTERNAL_ERROR] tlsv1 alert internal error (_ssl.c:1006)
25


26
[Direct us2.endpoint.ingress.rapid7.com:443] [Agent Message] ... FAILED
27


28
Cause: [SSL: TLSV1_ALERT_INTERNAL_ERROR] tlsv1 alert internal error (_ssl.c:1006)
29


30
------------------ TEST FAILED ------------------

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.