How to monitor a private host with a Beacon (one plain script, your own scheduler, the same rules)

The hosts a cloud monitor cannot see

Most of what an IT team is answerable for has no public address: the intranet wiki, the file server, the printer server, the badge system, the ERP on a box in the rack, the switch's management page, the internal certificate authority. A monitor that watches from the internet refuses those on purpose (a private address is not something a shared service should be pointed at), and a VPN from the monitor into every network is a bigger security decision than the monitoring was worth.

The usual answer is an installed collector: a service on a box inside, updated by the vendor, talking home. hostnag does not ship one. What it ships instead is a Beacon: one plain script, beacon.sh for Linux and macOS or beacon.ps1 for Windows, on a box in the network, scheduled by the box's own scheduler, that runs the same checks from inside and posts what it saw. You can read every line of it before you run it, it never updates itself, and removing it is one command.

Add a group and a beacon

Beacons live on the Beacons page of the org. A beacon group is a place: an office, a plant, a rack. It alerts as one of your zones, so a box that goes quiet pages the people who own that place, or through a policy of its own if you switch Alerts to "Its own" on the group. A beacon is one box in the group. 1 on Free, 5 on Pro, 20 on Business. Two boxes in one group are failover: a check picked by the group is run by every box in it, each its own cell on the board, and any one of them reporting counts.

Each beacon has a page with its install line, its cadence (how often it checks in: 1, 5, 15 or 60 minutes, plus a grace period), what it has been heard from, and the lines it serves.

Run the one line

The beacon's page prints one line per platform. On Linux or macOS it is:

curl -fsSL https://hostnag.com/beacon.sh | sudo bash -s -- install <token>

and on Windows, in a PowerShell opened as administrator, iex "& { $(irm https://hostnag.com/beacon.ps1) } install <token>". Read the script first at https://hostnag.com/beacon.sh or https://hostnag.com/beacon.ps1; it is version 3, plain bash 3.2 or PowerShell 5.1, and nothing in it is obfuscated. The install fetches the script into place (/usr/local/bin/beacon.sh, C:\ProgramData\hostnag\beacon.ps1), writes a config with the token, makes a state directory for the cached list of checks and the last run's log, schedules run every minute under a systemd timer, cron, launchd or a hidden Task Scheduler task, and runs once. The token is the box's credential: it identifies the beacon, and nothing else is stored on the box.

Every minute, run asks hostnag what to check, runs the lines that are due with the box's own tools (curl, /dev/tcp or nc, dig, ping, openssl s_client; on Windows the .NET equivalents), and posts one reading per line: a status code and a latency, an answer, a certificate's dates and fingerprint, or an error word like timeout or refused. It never runs code it was sent and never evals a line; what to check is data, and the script validates every word of it. A body is posted only when a keyword or JSON rule needs it, capped at 256 KB, and the log on the box holds readings, never a page or a certificate.

Pick the beacon under Checked by

Add a monitor as usual: a website, a port, a DNS record, a ping, a certificate. Under Check from, beside the five places, is Checked by: pick the group (every box in it, now and later) or one box. With a beacon picked, a private address is accepted for a check that beacons alone run, so https://wiki.internal/ or 10.0.4.20:445 are fine targets. A check can also keep its cloud places and add a beacon, which is how a public site with an internal path is watched from both sides.

hostnag judges what the box saw with the same rules as a live check: the expected status, the keyword or JSON assertions, the DNS answer, the certificate's expiry and chain. The box shows as one more cell on the monitor's location board, named after itself, and a failure it reports counts like a failure from Frankfurt: 2 confirmations, a second box or a second consecutive run, before an episode opens. The board on the Beacons feature page shows what that looks like.

Three of the fed kinds go the same way: an office link's internal ping, a status report and a certificate report can each name a beacon, so the box pings for the link or posts the certificate from the CA's own disk, with no minted URL to keep anywhere.

When the box goes quiet

A beacon that stops checking in is reported as Silent once its cadence plus grace has passed, through the zone's policy or the group's own. Every check it alone ran reads as not checkable from then on, never as your host being down: silence from the box is evidence about the box. When it comes back, the next run replays its readings and the board catches up within a minute.

Two things keep a beacon from being a liability. Fencing: allow lines in its config (an IP, a CIDR or a name suffix) restrict what the box may be told to check; a served line whose host matches none is refused there and reported as not allowed, so a compromised hostnag account could not turn the box into a scanner of your network. Removal: sudo /usr/local/bin/beacon.sh uninstall (or the PowerShell equivalent) removes the schedule, the script, the config and the state directory and lists each, and deleting the beacon on its page ends its reporting.

Check it now, then watch it

Check it now: a private host cannot be reached by a public tool, which is the point. Install a beacon, pick it under Checked by on one monitor, and watch the box's cell light on the monitor's location board within a minute or two.

Watch it for good: Beacons run the checks from inside; uptime monitoring and link monitoring are what they run.