tower

Tower

Network health-check tools for the command line.

Install

go install github.com/mismatched/tower@latest

Usage

All commands output JSON. Each result includes OK, Duration, Data, Warning, and Error fields.

tower [command] [args...] [flags...]

Commands

ping — ICMP ping (requires root)

sudo tower ping example.com
sudo tower ping example.com --count 3

dns — DNS resolve

tower dns example.com
tower dns example.com --from 8.8.8.8
tower dns example.com --timeout 3s

tcp — TCP port check

tower tcp example.com:443
tower tcp example.com:22 --timeout 10s

tls — TLS port check with client certificate

tower tls example.com:443
tower tls example.com:443 --cert client.crt --key client.key

http — HTTP status check

tower http https://example.com
tower http https://example.com --method HEAD
tower http https://example.com --timeout 30s

trace — HTTP trace with per-phase timing

tower trace https://example.com
tower trace https://example.com --method POST

https — TLS certificate check

tower https example.com
tower https example.com --port 8443
tower https example.com --warn 720h
tower https example.com --insecure

ws — WebSocket check

tower ws wss://example.com/ws
tower ws ws://example.com:8080/ws --timeout 10s

check — Batch checks from config file

tower check config.yml

Config File

checks:
  - type: tcp
    ip: "example.com"
    port: 443
    timeout: 5s
  - type: https
    host: "example.com"
    warn_if_expiring: 720h
    insecure_skip_verify: false
  - type: dns
    addr: "example.com"
  - type: ping
    host: "example.com"
    count: 3
  - type: http
    url: "https://example.com"
    method: GET
  - type: ws
    url: "wss://example.com/ws"

JSON Output

Every command prints a single JSON object (or array for check):

{
  "OK": true,
  "Duration": 124304875,
  "Data": null,
  "Warning": null,
  "Error": null
}

Build

go build -o bin/tower .

Test

# Non-root (all tests except ping)
go test -v ./...

# Root (includes ping tests)
sudo go test -v -race ./...

GitHub Actions

Tower can be used as a GitHub Action to run health checks in your CI pipeline. See tower-template for starter workflows.

Quick start

# .github/workflows/health-check.yml
name: health-check
on:
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: mismatched/tower@master
        with:
          tcp: 'example.com:443'
          http: 'https://example.com'
          timeout: '10s'

TLS cert expiry warnings

Cert expiry warnings require a config file (the composite action doesn't expose warn_if_expiring as an input). Create a config and use the config input:

# .github/tower/checks.yml
checks:
  - type: https
    host: "example.com"
    warn_if_expiring: 720h

# .github/workflows/health-check.yml
steps:
  - uses: actions/checkout@v4
  - uses: mismatched/tower@master
    with:
      config: '.github/tower/checks.yml'

Action inputs

The action fails if any check has "OK": false.

License

MIT