Quickstart

Step 1. Install

First, download the executable (for Linux x86_64 only):

curl -Lo /tmp/hostpatrol https://github.com/vst/hostpatrol/releases/latest/download/hostpatrol-static-linux-x86_64

Then, install it to your $PATH:

sudo install /tmp/hostpatrol /usr/local/bin/hostpatrol

(or see below for how to install it using Nix profile)

Step 2. Patrol

hostpatrol compile --host my-host-1 --host my-host-2 > hostpatrol_report.json

Step 3. Render

Go to Web UI
Load your report hostpatrol_report.json

Done! Read following for more information.

Install to Nix Profile

For the current development version:

nix profile install --file https://github.com/vst/hostpatrol/archive/main.tar.gz app

For versioned release:

nix profile install --file https://github.com/vst/hostpatrol/archive/v<VERSION>.tar.gz app

Configuration File

Instead of providing hosts one-by-one, you can use a configuration file. For example given a configuration file config.yaml like this:

## List of known SSH public keys for all hosts.
knownSshKeys:
  - gh:some-github-user
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKq9bpy0IIfDnlgaTCQk0YhKyKFqInRjoqeIPlBuiFwS test-key-admin
 
## List of hosts to patrol
hosts:
  - ## Name of the host (required)
    name: somehost
    ## SSH configuration (optional)
    ssh:
      ## SSH destination (required)
      destination: [email protected]
      ## SSH options (optional)
      options: ['-i', '/keys/hebele.pri']
    ## External identifier of the host (optional)
    id: 20b88669-743f-4ae5-9823-5aacc2df7086
    ## External URL for the host (optional)
    url: https://internal.documentation/hosts/somehost
    ## List of tags for the host (optional)
    tags:
      - oranges
      - strawberries
    ## Arbitrary JSON data for the host (optional)
    data:
      owner: Client-1
      cost: 50
    ## List of known SSH public keys for the host (optional)
    knownSshKeys:
      - gh:another-github-user
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGmlBxUagOqtWcW6B77TUL8li85ZNYx0tphd3TSx4SEB test-key-tenant
  - name: otherhost
    url: https://internal.documentation/hosts/otherhost
    tags:
      - apples
      - strawberries

You can compile the report like this:

hostpatrol compile --config config.yaml > hostpatrol_report.json

The benefit of using a configuration file is to provide additional information about the hosts, such as external identifiers, URLs, tags, and arbitrary JSON data. Also, you can provide known SSH public keys for each host and/or for the whole configuration.

Furthermore, you can mix the configuration file with the command-line hosts:

hostpatrol compile --config config.yaml --host my-host-1 --host my-host-2 > hostpatrol_report.json

Host Patrol connects to hosts in parallel and ignores all failed hosts by reporting such errors in the output. To change the maximum number of threads used for concurrent patrols, use --threads option that defaults to 4. For example, to use 10 threads, run the following command:

hostpatrol compile --threads 10 --config config.yaml > hostpatrol_report.json