netstat.php - simple network status

netstat.php is a PHP script intended to provide a simplified, easily comprehensible and aesthetically pleasing overview of the online status of hosts and services.

Background story

We use the usual suspects when it comes to network monitoring. There is lots of very good open source software which does all the tricks. However, I always missed a simple, intuitive interface with lots of green traffic lights which I could make available to my users (and clients). Of course, I looked for simple and freely available scripts but could not find any which did the job and still pleased my eyes. Eventually, I wrote my own.

netstat.php only checks whether a specific port is open. It can be configured to check for instance whether some software is listening on port 25 (for SMTP) but it cannot tell whether this software is still working¹. Point is that we do not need more since we are running full-blown monitoring software anyway. In most cases, it is sufficient for my users to see a red light only when the network or the servers are down or the daemon is not running at all. And in general, an admin will((read should ;-) )) know before users do.

Screenshot

This screenshot shows also a tooltip which is included as mouse-over in case of errors.

For an HTML example see netstat.php's main page.

Features

• Comes in 3 variants (see below for details):
  • netstat.php 0.x: The original code as described here
  • netstat.php 1.x: Todd E. Johnson's almost completely rewritten code with some more features, available at GitHub
  • netstat-kiss.php: A reduced, even simpler version of netstat.php 0.x
• Checks for open ports²
• Can do ICMP pings³
• Supports IPv6
• Aesthetically pleasing and somewhat CSS responsive
• Can display an optional alert message
• Support for including alert messages in an RSS feed
• Timeout (network sensitivity) is adjustable
• Self-contained but supports an extra configuration file
• HTML + CSS compatible with text only browsers (tested with lynx and links)
• Shows timing diagnostics and error messages hidden in mouse-hovers or in extra rows⁴
• Free, open source, and GPL licensed
• Still sticks to the KISS principle

Instructions for use

netstat.php comes as a single PHP file. Download it, rename appropriately, edit the source code or create a configuration file to change settings, and have fun. Out of the box, the script looks for a configuration file named netstat.conf.php. It is recommended to put all settings into this file.

netstat.conf.php

Here is sort of a minimal example. For all supported settings see below.

<?php /* netstat.conf.php example */
$title = "Our network status";
$headline = $title;
$checks = array(
 'router.example.com|ping| ICMP ping (ping)',
 'www.mydomain.not  | 80 | WWW server (port 80)',
 'localhost         | 22 | SSH server (port 22)',
 '   Other checks   | headline',
 'www.example.com   | 80 | WWW server example.com' // no colon here!
)
$ping_command = '/usr/bin/ping -l3 -c3 -w1 -q';

$checks

• Basic syntax: host | port | description
• Supported variations:
  • ping: If port = "ping" or "ping6" ICMP pings are sent to host.
  • Negative ports and "-ping" can be used to temporarily disable a check.
  • Headlines: If port = "headline" description is printed as a (sub)heading.
  • Lines with no | (pipe symbol) or empty port entries are ignored.
• Notes:
  • IPv6 addresses need to be enclosed in [ ], e.g. for localhost use [::1]

netstat.txt

netstat.php can also be used to show an alert message. By default, the script looks for a file named netstat.txt and includes it. Use HTML for formatting your alert message. Example:

<p><b>Status as of 2009-10-26 11:47</b><br />
Mail services are currently down. On-site engineers are already investigating the cause
of this unexpected interruption. Further information will be provided in about 30 minutes.</p>

In order to disable the inclusion of the file either rename it or change its permissions.

All configuration variables

Here is a full example of a configuration file (except for $checks and $htmlheader):

<?php
/**
 * netstat.php - Settings example for $configfile with defaults (mostly)
 */

$configfile = 'netstat.conf.php'; // name of file where to put these variables
$error_reporting = 0; // See http://php.net/error_reporting

$title = "Our Network Status"; // page title
$headline = $title; // page headline

$alertfile = 'netstat.txt'; // extra alert file included in HTML + RSS
// $checks = allthemagic(); // See script or homepage for how to specify

$ping_command = 'ping -c3 -w1 -q'; // external command to use for ICMP ping
$ping6_command = 'ping6 -c3 -w1 -q'; // ditto for IPv6
$timeout = 4; // fsockopen timeout (sort of the sensitivity)

$progressindicator = true; // show a simple progress indicator (req. Javascript)
$showdiagnostics = false; // print diagnostics in extra rows
$rssfeed = true; // use to enable or disable RSS feeds (see also below)

$online = 'Online'; // strings for online and offline
$offline = 'Offline'; // note that by default these are used in CSS, too

$datetime = 'l, F j, Y, H:i:s T'; // date/time format; skipped if empty

$rssfeedurl = $_SERVER['SCRIPT_NAME'].'?rss'; // URL of RSS feed
$rsstitle = "RSS alert feed of $title"; // RSS feed title
$rssheader = '<link rel="alternate" type="application/rss+xml" '
        . "title=\"$rsstitle\" href=\"$rssfeedurl\" />"; // RSS header
$rsslink = $_SERVER['SCRIPT_NAME'].'?noprogress'; // RSS alert link
$rssdatetime = 'o-m-d H:i:s T'; // RSS date and/or time format

// $htmlheader = ... see script for a full example; note that by default it
//   uses other variables, too: $title, $rssheader, $online, $offline

$htmlfooter = "</div>\n</body>\n</html>"; // well, guess what :-)

// $version ... version of script, link to homepage and author

Download & source code

There are currently 3 variants of netstat.php. Choose the one that suits you best:

• netstat-kiss.php: A simplified version without gimmicks like progress bar and RSS. If in doubt, that's the one to download.
• netstat.php 0.x: The original version: Simple, straight forward procedural code, includes optional progress bar and support for RSS.
• netstat.php 1.x: Todd E. Johnson has rewritten large parts of my original script and even added new features. His version is available at GitHub. Added features are:
  • Create config file with php netstat.php genconfig or netstat.php?genconfig
  • Set status ("edit" the alert file netstat.txt) with php netstat.php setstatus from the command-line
  • Built-in cache: Results of checks (actually the whole web page) are cached for a configurable time period

Final remarks

Requirements

For basic operation, the script mostly uses PHP's fsockopen(), which needs to be enabled. Unfortunately, some web hosting providers apparently disable this function.

For ICMP pings also exec() needs to be enabled which many providers disable, and a command line version of ping must be available.

Usage recommendations

Under certain circumstances, it might be better to not directly provide the PHP file to your users but instead create a static HTML file by means of e.g. a cronjob. Some of these situations are:

• Your $checks includes many pings or many services which are often offline. This makes operation extremely slow.
• Your status page gets a lot of hits. Running the script in real-time causes unnecessary overhead.
• You want to provide RSS feeds which are polled even more often.
• You want to know about outages before your users do.

We installed netstat.php on a remote site where a cronjob runs

php netstat.php rss >rss.xml php netstat.php noprogress >index.htm

The "noprogress" suppresses the Javascript progress indicator of netstat.php.

The actual script (shown below) does even more:

1. The old status is saved to oldstatus.
2. A static HTML version of netstat.php is saved to index.htm.
3. A plain text version of index.htm is saved to netstat.ctl.
4. If the new status is different from the old a message is sent.

#!/bin/bash
set -e
cd /directory_of_your_netstat.php_installation

# Save old status
cat index.htm >oldstatus.htm
cat netstat.ctl >oldstatus.ctl

# Retrieve or produce a static version of the netstat.php RSS alert feed
php netstat.php rss >rss.xml

# Retrieve or produce a static version of the netstat.php results
php netstat.php noprogress >index.htm

# For the control file nestat.ctl remove date+time and version
# and make error notices (in title="...") visible
sed -e '
   /^<p class="\(datetime\|version\)">/d
   /^<meta http-equiv="Refresh" /d
   /^<tr><td>/{
       s|title="\([^"][^"<>]*\)">Offline</td></tr>|>Offline: \1</td></tr>|
   }
   ' index.htm \
| lynx -dump -nolist -force_html -stdin \
> netstat.ctl

# If the file is different compared to the previous one mail it
diff -q netstat.ctl oldstatus.ctl >/dev/null \
|| mail -s "netstat as of $(date +%Y-%m-%d\ %H:%M\ %Z)" root \
< netstat.ctl