README for netdraw -- 2007-12-12 Copyright (C) 2007 Grant Coady GPLv2 Homepage: http://bugsplatter.id.au/netdraw/ Designed for use with a linux gateway box facing the Internet, written and tested with Slackware-11.0. Display the most recent 24 hours of network interface activity on a simple chart. Written and tested on a Slackware-11.0 linux system, requires installation of fly (http://martin.gleeson.com/fly/), and should work on other unix-like systems if they have gd and gawk installed and some equivalent of /proc/net/dev or ifconfig from which to extract the interface activity data, see netsample script. Fly is a small program that provides a text interface to the gd library. Why bother reinventing a network monitor? ----------------------------------------- I wrote http://ironbark.bendigo.latrobe.edu.au/cp/ in 2001 for my final year project, it was written in the then fashionable server-side perl and client-side javascript. It too uses the gd library with the perl GD.pm module. I've not written many perl scripts since, currently I enjoy writing tools with bash and awk. Recently I decided to monitor my Internet connection to check if my ISP's usage records are accurate. The process ----------- 0. One configuration file, /etc/netdraw.conf, contains the settings for the 'netdraw' set of bash scripts and awk programs. 1. Five minute samples are taken which record date.time, receive bytes and transmit_bytes in the form: "2007-12-09.10:59 2289001933 69348850". This sampling is controlled by a root crontab entry and netsample. The samples are taken at 4, 9, 14, 19, 24, 29, 34, 39, 44, 49, 54, 59 minutes past the hour. As the samples are taken with seconds equal to zero or one, this results in about a minute's skew in the data stream, harmless. The decision to sample at 0..59 minutes is so that the final sample of the day is attached to that day's date. The interface sample is taken from the /proc/net/dev data, alternately it may be extracted from $(ifconfig $INTERFACE), see netsample. 2. An awk script, netdraw, reads the sample file and generates a fly script for generation of the chart image, /tmp/netdraw.fly. 3. The fly program is called to read /tmp/netdraw.fly and write out the netdraw.png image file to some directory specified in the configuration file. 4. A user cron job, netdrawmon, is called hourly to update the monthly summary image. 5. A user cron job, netdrawcopy, takes a copy of the daily image each midnight and logs the most recent snapshots for creation of a summary web page. Netdrawcopy also calls netdrawhtml to write the most recent daily snapshots to an html file. Chart generation ---------------- Twenty four hours of 5 minute samples gives a chart width of 288px, the chart height is set to 80px. An auto-calibration option self scales the chart to suit the maximum data value seen in the charting period. The fullscale value is displayed in the top left corner. As the chart data moves to the left the baseline hour pips and labels are positioned dynamically to match the data. The final image dimensions are 320x132 pixels. Chart decorations: gridlines, outline, axis labels, key, fullscale value, date and rx, tx totals for the current day. The image file size is less than 2k bytes. Shadows drawn beneath the text improve the contrast and visual rendering. The monthly summary chart shows total rx and tx bytes transferred each day of the current month as well as the monthly totals. This chart is updated hourly. Decimal scaling --------------- Netdraw uses decimal scaling, that is: 1kB = 1000 bytes, 1MB = 10^6 bytes and 1GB = 10^9 bytes. Installation ------------ Download the configuration file and scripts, there is a tarball, there is no installer. Download and compile fly: http://martin.gleeson.com/fly/dist/fly-2.0.0.tar.gz Note the patch to fly's Makefile in 'flynotes.txt' to allow compile without the unused -lttl link option. Save the configuration file to /etc and edit it to reflect which directory to be used for the output images somewhere under the web server area. Copy the sample web page, sample.shtml, as .shtml (use whatever name you like, perhaps index.shtml) into this directory. Check the .conf file reflects the interface you want to monitor, default is ppp0. Modify your web server's .conf (eg. /etc/apache/httpd.conf) to allow SSI and perhaps to show index.shtml for a directory reference. I use these options with apache 1.3): AddType text/html .shtml AddHandler server-parsed .shtml XBitHack Full DirectoryIndex index.html index.cgi index.html.gz index.shtml Save the scripts to /usr/local/bin, if you choose to save the scripts somewhere other than /usr/local/bin, edit the .conf file to reflect the scripts' location. Create a data directory under your username, for example ~/netdraw and edit the /etc/netdraw.conf file's sampledata entry to point to this data directory. Using the crontab.txt file as a guide, install the cron jobs using 'crontab -e'. Wait more than ten minutes for some data collection, check the data file (default: /home/username/netdraw/sampledata) looks something like: 2007-12-18.10:49 921878643 22190769 2007-12-18.10:54 924332925 22248544 2007-12-18.10:59 926842231 22307085 Run netrefresh to create the images, and load the web page to view them. Once you can view the images, you may change the colour scheme in the .conf file. Also play with other chart options such as axis labels and so on. End.