(as)  [sysadmin] [blog]

User Tools

Site Tools


netstat_php

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
netstat_php [2015-06-11 15:56]
127.0.0.1 external edit
netstat_php [2019-01-28 23:33] (current)
andreas Version 0.16 released 2019-01-28
Line 1: Line 1:
 +====== netstat.php - simple network status ======
 +
 +**[[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​|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 [[wp>​Comparison of network monitoring systems|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((Technically,​ **netstat.php** uses PHP's fsockopen() to create an Internet or *nix domain socket connection.)). 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 =====
 +
 +{{ https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​netstat.png }}
 +
 +This screenshot shows also a tooltip which is included as mouse-over in case of errors.
 +
 +For an HTML example see [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​|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((See [[#​Requirements]]))
 +  * Can do ICMP pings((See [[#​Requirements]]))
 +  * Supports IPv6
 +  * Aesthetically pleasing and somewhat CSS responsive
 +  * Can display an optional alert message
 +  * Support for including alert messages in an [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​rss.xml|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((Set ''​$showdiagnostics = true''​ or call ''​netstat.php''​ with ''?​diags''​.))
 +  * Free, open source, and [[https://​www.gnu.org/​licenses/​gpl.html|GPL licensed]]
 +  * Still sticks to the [[wp>​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.
 +
 +<code php>
 +<?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';
 +</​code>​
 +
 +==== $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:
 +
 +<code html>
 +<​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>​
 +</​code>​
 +
 +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''​):​
 +
 +<code php>
 +<?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
 +</​code>​
 +
 +===== 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:** [[http://​www.toddejohnson.net/​|Todd E. Johnson]] has rewritten large parts of my original script and even added new features. His version is available at [[https://​github.com/​netstat-php/​netstat_php|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
 +
 +==== ====
 +
 +^ netstat-kiss.php ​  | [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​netstat-kiss.php.txt|Download]] (~ 8 KB) | View [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​netstat-kiss.phps|source]] |  |
 +^ netstat.php v0.16  | [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​netstat.php.txt|Download]] (~12 KB) | View [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​netstat.phps|source]] | [[https://​fam.tuwien.ac.at/​~schamane/​sysadmin/​netstat/​CHANGES.txt|CHANGES.txt]] |
 +^ netstat.php v1.x | Hosted at [[https://​github.com/​netstat-php/​netstat_php|GitHub]] | View [[https://​github.com/​netstat-php/​netstat_php/​blob/​master/​netstat.php|source]] | [[https://​github.com/​netstat-php/​netstat_php/​commits/​master|Commit history]] |
 +
 +
 +===== Final remarks =====
 +
 +==== Requirements ====
 +
 +For basic operation, the script mostly uses PHP's [[http://​php.net/​fsockopen|fsockopen()]],​ which needs to be enabled. Unfortunately,​ some web hosting providers apparently disable this function.
 +
 +For ICMP pings also [[http://​php.net/​exec|exec()]] needs to be enabled which many providers disable, and a command line version of [[man>​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 ''​ping''​s 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:
 +
 +  - 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.
 +
 +<code bash>
 +#!/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
 +</​code>​
 +
  
netstat_php.txt · Last modified: 2019-01-28 23:33 by andreas