NAME

picnet - Instructions for using PICNET for MRTG


SYNOPSIS

PicNet is a small tool that gives indication on network traffic on a graphic map. It takes information from MRTG log files, and modifies the PNG image of your network so that links have colors based on the current traffic.

Then, it can generate an HTML page with this image used as an image map indexing MRTG stat pages.

PicNet can handle just one map or several maps with tree hierarchies (submaps).

The idea of PicNet was completely inspired on Rdlog2 by Philippe Simonet, <philippe.simonet@swisstelecom.com>. Anyway, it is quite different as PicNet works on raster images while Rdlog2 uses vector images.


HISTORY LIST

v 1.1, (10/27/00) :
 - You can create several maps by using prefixes '<your_map_n>*' 
before parameters.
 - You can use the new parameter 'MapColorIdx' to get the max 
color of a submap in another map. So, you can create tree 
hierarchies of maps.
 - You can make HTTP links between maps with MapRect and MapPoly.
 - The few parameters that previously used '[indexmap]'
pseudo-target have been changed. Now, they are normal parameters 
which names begin with 'Html'.
 - The doc is now written in the POD format. So, HTML, TXT and 
MAN pages are available.
 - Added a precompiled version for Win32 in a ZIP file.
v 1.0, (08/23/99) :
First version.


REFERENCE PNG IMAGE

PicNet needs a reference PNG image of your network (one per submap).

Why PNG image ?

PNG (Portable Network Graphics) is an extensible file format for the lossless, portable, well-compressed storage of raster images. PNG provides a patent-free replacement for GIF and can also replace many common uses of TIFF.

PNG is designed to work well in online viewing applications, such as the World Wide Web. Current browsers can display PNG images.

The GD library now deals with 8-bits PNG images. So this tool and MRTG generate PNG images.

How to create a reference image ?

You can use PaintShop Pro (on Windows) or any other tool to create it. You can draw your image as you want but you must respect the following rules :

- The final image must be an 8-bits PNG (256 colors).

- You must use one color (not used anywhere else in the image) per MRTG target or PicNet submap and note its index value (0<i<256).

An MRTG target is any object your MRTG monitors (data stored in log files). Usually, the MRTG targets are links (but it can be a Squid server, a mail server or a disk...).

Then you will ``tell'' PicNet (in the config file) to change these colors with the traffic rate color of these links or objects.

Note that these objects can also be PicNet maps (submaps). The color of a submap will be the max color of its objects. So, you can make a tree hierarchy of PicNet maps.

Besides, you can use your network image(s) to index MRTG stats pages, PicNet maps and other HTML pages. If you want to do it, you should note the X, Y values of the upper left and lower right corners for clickable squares or X, Y values of all the corners for clickable polygons.

Here is a tutorial for making a reference image using PaintShop Pro 5 :

the image manpage


PICNET CONFIGURATION FILE

PicNet needs a reference PNG image and a configuration file...

PicNet configuration file looks like MRTG one. So it is very easy if you are familiar to mrtg.cfg...

If you used automatic generation of your MRTG config file, you should have a look at this file to get the name of targets. Then, you can edit the PicNet config file example, ex.cfg, to meet your needs.

If you want several PicNet maps, you just have to prefix config instructions with : <name_of_map>* If you don't use such prefix, the default map name is indexmap.

Here are the different tags you have to use to configure PicNet :

the config manpage


INFORMATION FOR BUILDING PICNET

If you have a precompiled copy for Windows (ZIP file), go to the section : INSTALLING PICNET ON WINDOWS.


If you don't have time and you want to install PicNet for Unix, go to the 
next section to build PicNet.

Well, you have the GZIP TAR file with PicNet sources.

First, you must obviously use MRTG : http://www.ee.ethz.ch/~oetiker/webtools/mrtg/mrtg.html

PicNet uses the GD library. You should have installed it as MRTG needs it. http://www.boutell.com/gd/

In order to built PicNet, you must have the following files :

 def.h
 cfg.h
 loadcfg.c
 mkhtml.h
 mkpic.h
 mkhtml.c
 mkpic.c
 picnet.c
 Makefile

If you don't like the current colors for the traffic rate, you can modify it in def.h. You can also add other levels of colors (in cfg.h and def.h).

If your gd library is not in your library path, nor in /usr/local/lib, you have to edit Makefile (-L). If your gd.h is not in your include path, nor in /usr/local/include, you have to edit Makefile (-I).

You can change CC in the Makefile to your C compiler (gcc...).

You can add the following global definitions to the CFLAGS in your Makefile :

-DFR
To generate the HTML pages in french (I'm french ;-) )

-DNOJS
If you don't like JavaScript in the HTML pages...


BUILDING PICNET ON UNIX

You can type :

 make

Then copy the binary file picnet where you want.

NB: Before executing picnet, you must create a PNG image of your network(s) (the image manpage) and a config file (the config manpage).


INSTALLING PICNET ON WINDOWS

Get the latest release of PicNet for Win32 in ZIP format. It contains a precompiled copy (with CygWin and GCC). Unzip the ZIP archive and install the mandatory files where you want : picnet.exe cygwin1.dll libpng.dll libz.dll

You must set the TZ variable to your timezone (for Windows 9X, add set TZ=GMT+11 (your timezone !) to autoexec.bat).

Obviously, you must create reference image(s) and a configuration file (see above).

In the configuration file, you must set WorkDir as a Windows directory : D:\InetPub\wwwroot\MRTG (no problem with long names and spaces).


CALLING PICNET

The command-line parameters are :

 picnet <config-file>

But this command executes picnet just once. Then, you have 2 ways to run picnet regularly...

Patch MRTG for PicNet
1- Copy picnet (or picnet.exe) and patch.pm in the same directory as the mrtg file.

2- Backup mrtg (cp mrtg mrtg.bak).

3- Apply the Perl module patch.pm to mrtg on standard input (or first argument) and get patched mrtg on standard output :

 perl patch.pm mrtg.bak >mrtg

4- Now, you can use the following syntax in the call to mrtg :

 <mrtg-bin>/mrtg <mrtg-cfg>/mrtg.cfg <picnet-cfg>/picnet.cfg

and PicNet will run when mrtg updates the data.

Note that if you don't add a second parameter to the mrtg command-line, picnet will use the first one (mrtg.cfg) as its configuration file.

Use a Scheduler
You may use a scheduler to execute the picnet command whenever MRTG data is updated (usually, every 5 minutes).

You should add picnet in your crontab on Unix. I advise you to launch it after mrtg...

Example:

 0,5,10,15,20,25,30,35,40,45,50,55 * * * * \
       <mrtg-bin>/mrtg <path to mrtg-cfg>/mrtg.cfg; \
       <picnet-bin>/picnet <path to picnet-cfg>/picnet.cfg

or in Linux :

 */5 * * * *  <mrtg-bin>/mrtg <path to mrtg-cfg>/mrtg.cfg; \
       <picnet-bin>/picnet <path to picnet-cfg>/picnet.cfg


AUTHOR

Laurent Derrien, <derrien@canl.nc>

9.9.99 (last update 10.20.00)