Command line help

If you have command line experience, you can troubleshoot your orchestrator installation or activation within a terminal window.

Command line resources

Your orchestrator installation comes with OpenSSL, Telnet, and the Vim text editor. OpenSSL and Telnet can help you test orchestrator connectivity or troubleshoot network issues. Vim is helpful if you need to edit files, for example if you need to configure a static IP.

Follow these links to learn more about each feature:

Operational commands

Use the following commands to troubleshoot an orchestrator using the command line:

  • systemctl start rapid7-orchestrator: start an orchestrator that is not currently running
  • systemctl stop rapid7-orchestrator: stop an orchestrator that is currently running
  • systemctl status rapid7-orchestrator: check on the status of an orchestrator
  • systemctl restart rapid7-orchestrator: stop and restart an orchestrator
  • sudo rapid7-orchestrator --print-activation: print the activation key for an orchestrator

To show an orchestrator version number, run:

  • yum info rapid7-orchestrator on a Red Hat Enterprise Linux (RHEL) machine
  • apt info rapid7-orchestrator on an Ubuntu machine

Orchestrators and InsightConnect update automatically, but if you need to manually update an orchestrator, run:

  • yum update rapid7-orchestrator to force an update on RHEL machines
  • apt-get install --only-upgrade rapid7-orchestrator to force an update on Ubuntu machines

Command shortcuts

These shortcuts make it easier for you to quickly manage an orchestrator without typing out the full command:

  • orch-logs: tails the orchestrator logs
  • orch-logs-err: tails the journalctl error log
  • orch-print-activation: prints the orchestrator activation key. If you can’t copy this from the command line, run orch-print-activation > ~/activation.txt instead and retrieve the file from the remote server to your local environment via SSH or SCP.
  • orch-start: starts the orchestrator service. This command is a shortcut for systemctl start rapid7-orchestrator
  • orch-stop: stops the orchestrator service. This command is a shortcut for systemctl stop rapid7-orchestrator
  • orch-restart: restarts the orchestrator service
  • orch-config: opens a vim editor for the orchestrator

SSH help

To access your orchestrator with SSH (secure shell):

  1. Find and record your IPv4 address for your VM (virtual machine) with the instructions in Find VM IPv4 address.
  2. From a remote console with network access to your VM, use a command-line shell to run ssh rapid7@<ipaddress> with the IP address you recorded in Step 1.
  3. When prompted for a password, type changeme. You should now have SSH access into the orchestrator VM.
  4. Change your password to something secure by running the passwd command.

SSH clients

You can use these clients to secure shell (SSH) into your virtual machine (VM).

  • Linux and MacOS: An SSH client is available natively on Linux and Mac OS operating systems.
  • Windows: There are 2 great SSH client options for Windows: the native SSH client, usually available through Chocolatey, or Putty.
    • Native SSH client: You can go to https://chocolatey.org/packages/openssh/ to install the native SSH client. With a native SSH client installed, you can open Powershell on Windows and connect to your orchestrator.
    • Putty: You can go to https://www.putty.org/ to download Putty. Open Putty and enter the IP address or hostname for your orchestrator into the Hostname(or IP address) field, then click Open. When prompted for a username, enter rapid7.

Find VM IPv4 address

To find your orchestrator virtual machine’s IPv4 address, follow the instructions for your virtual machine system.

  • VMWare Workstation: Find and open the virtualization console window for your orchestrator machine, and run ifconfig from the terminal. From the output, locate the value for inet under enp0s3. Your network interface name may vary; another common name it may be is ens32 or eth0.
  • VMWare Virtual Center: Your VM’s IP address is available in the VSphere web application in the Guest OS section. If you don’t have access to the VCenter VSphere web app, your network administrator for VCenter should be able to provide the IP address for the machine for you. See VMWare documentation for further assistance.
  • AWS EC2: Use the public IPv4 address assigned to your orchestrator EC2 instance. You can find this by visiting AWS documentation and following their provided instructions.

Unique network settings

Every network is different, and your settings may require further configuration to successfully SSH into the orchestrator VM. Check with your IT team if:

  • Following the previous steps results in any SSH error
  • The ssh command times out

You may need to check your firewalls, port forwarding settings, or set up SSH key pairs.

The virtualization service you use may also require different SSH settings. Visit these suggested resources to configure SSH for your virtualization service: