Browse files

Add README from text of http://www.fam.tuwien.ac.at/~schamane/_/netst…

  • Loading branch information...
1 parent 515a3bd commit 98c76b8b75beb8061e9a0c4525655c2b922b61ab @toddejohnson toddejohnson committed Jan 3, 2012
Showing with 173 additions and 0 deletions.
  1. +173 −0 README
View
173 README
@@ -0,0 +1,173 @@
+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 working1). 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 will2) 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
+
+ Checks for open ports3)
+ Can do ICMP pings4)
+ Aesthetically pleasing
+ Can display an optional alert message
+ Support for including alert messages in an RSS feed
+ Timeout (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
+ 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" 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.
+
+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
+$timeout = 4; // fsockopen timeout (sort of the sensitivity)
+
+$progressindicator = TRUE; // show a simple progress indicator (req. Javascript)
+$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
+
+ Download current version: netstat.php.txt (~ 10 KB)
+ View source (with syntax highlighting)
+
+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
+
+php5 netstat.php rss >rss.xml
+php5 netstat.php noprogress >index.htm
+
+The "noprogress" suppresses the Javascript progress indicator of netstat.php.
+
+The actual script (shown below) does even more:
+
+ The old status is saved to oldstatus.
+ A static HTML version of netstat.php is saved to index.htm.
+ A plain text version of index.htm is saved to netstat.ctl.
+ 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
+php5 netstat.php rss >rss.xml
+
+# Retrieve or produce a static version of the netstat.php results
+php5 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
+
+

0 comments on commit 98c76b8

Please sign in to comment.