README
¶
netprobe
Measure your network from the places that matter, and be told when it breaks.
Documentation | Getting started | Concepts | Releases
What it is
A website can be up for you and down for a colleague in another city. netprobe puts a small program, an edge, on each machine you want to measure from. Each edge runs checks (can I open this site? does this name resolve? is this certificate about to expire?) and reports to a central, which keeps the history, opens an incident when something stays wrong, and tells Slack, Discord or your own webhook.
flowchart LR
e1[Edge: paris] & e2[Edge: tokyo] & e3[Edge: office] -->|results| central[Central]
central -->|checks to run| e1 & e2 & e3
central --> db[(TimescaleDB)]
central -->|incidents| chat[Slack, Discord, webhooks]
you[You: web UI] --> central
grafana[Grafana] --> db
Try it in two minutes
You need Docker.
docker compose up -d
docker compose logs central | grep setup_code # six digits
Open https://localhost (the proxy makes a certificate with its own authority: your browser warns once), give the code, and create the administrator. The home page then guides the first steps: register an edge, add a check, add a channel.
The full walk-through, step by step, is in Getting started.
On a real server
One command on a Linux machine, for the central or for an edge (the guide says how to read the script first):
curl -fsSL https://github.com/Arylite/netprobe/releases/download/v1.1.0/install.sh | sudo sh -s -- central --domain netprobe.example.com
curl -fsSL https://github.com/Arylite/netprobe/releases/download/v1.1.0/install.sh | sudo sh -s -- edge --central https://netprobe.example.com
What you get
| Eleven kinds of check | TCP, HTTP (status and content), DNS, TLS certificate, ICMP ping, traceroute, NTP clock, service banner, closed port, download speed, domain expiry; every second at best |
| Edges that only dial out | no open port, works behind any firewall, one revocable token each |
| Incidents and alerts | opened when a check keeps failing or an edge goes quiet; signed webhooks |
| A web UI to manage it | edges, checks, channels, users, incidents, audit log |
| Grafana to look at it | three dashboards, already connected, with image rendering |
| Storage that lasts | PostgreSQL with TimescaleDB, compressed after 7 days, kept as long as you say |
| Security by default | TLS 1.3, client certificates, argon2id, encrypted secrets, audit trail |
| Easy to diagnose | a doctor command on both sides that says what is wrong |
| Easy to ship | binaries for linux (amd64, arm64), macOS (arm64), windows (amd64); images for amd64 and arm64, scanned before they are published |
Learn more
| I want to | Read |
|---|---|
| understand the ideas first | Concepts |
| choose what to measure | Checks |
| add an edge on another machine | Edges |
| get a message in Slack | Alerts |
| put it on a server with a real name | Deploying |
| back it up and upgrade it | Operating |
| look up a setting | Configuration |
| understand how it is built | Architecture |
| know what it protects | Security |
| build and contribute | Development |
Everything is listed in the documentation home.
Status
Version 1.1.0. To report a vulnerability, see SECURITY.md.
License: Apache 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
netprobe-central
command
Command netprobe-central is the server that stores results and serves the UI.
|
Command netprobe-central is the server that stores results and serves the UI. |
|
netprobe-edge
command
Command netprobe-edge is the agent that runs probes and reports to the central.
|
Command netprobe-edge is the agent that runs probes and reports to the central. |
|
Package e2e tests the edge and the central together; it is the only package that imports both.
|
Package e2e tests the edge and the central together; it is the only package that imports both. |
|
internal
|
|
|
api
Package api defines the wire contract between the edge and the central.
|
Package api defines the wire contract between the edge and the central. |
|
central
Package central is the server: edge API, web API, storage and alerting.
|
Package central is the server: edge API, web API, storage and alerting. |
|
central/alert
Package alert opens an incident when a check keeps failing or an edge goes quiet, resolves it when it stops, and tells the channels of each event.
|
Package alert opens an incident when a check keeps failing or an edge goes quiet, resolves it when it stops, and tells the channels of each event. |
|
central/auth
Package auth hashes passwords, enforces their policy and throttles login attempts.
|
Package auth hashes passwords, enforces their policy and throttles login attempts. |
|
central/store
Package store keeps edges, checks and results in PostgreSQL with TimescaleDB.
|
Package store keeps edges, checks and results in PostgreSQL with TimescaleDB. |
|
central/store/storetest
Package storetest gives tests a throwaway database; tests skip without NETPROBE_TEST_DATABASE_URL.
|
Package storetest gives tests a throwaway database; tests skip without NETPROBE_TEST_DATABASE_URL. |
|
central/webapi
Package webapi is the JSON API the web UI talks to: accounts, sessions and the data of the central.
|
Package webapi is the JSON API the web UI talks to: accounts, sessions and the data of the central. |
|
cli
Package cli holds what both commands share: environment defaults and logging.
|
Package cli holds what both commands share: environment defaults and logging. |
|
doctor
Package doctor runs diagnostic steps in order and prints what is wrong and how to fix it.
|
Package doctor runs diagnostic steps in order and prints what is wrong and how to fix it. |
|
edge
Package edge is the agent: it polls the central, runs probes and reports results.
|
Package edge is the agent: it polls the central, runs probes and reports results. |
|
logsafe
Package logsafe cleans what a client sent before it goes in a log line.
|
Package logsafe cleans what a client sent before it goes in a log line. |
|
pkitest
Package pkitest makes a throwaway certificate authority for tests.
|
Package pkitest makes a throwaway certificate authority for tests. |
|
probe
Package probe runs network measurements and knows nothing about the central.
|
Package probe runs network measurements and knows nothing about the central. |
|
version
Package version holds the build information injected at link time.
|
Package version holds the build information injected at link time. |
Click to show internal directories.
Click to hide internal directories.