


PICNET(1)                     picnet                    PICNET(1)


NNNNAAAAMMMMEEEE
       picnet - Instructions for using PICNET for MRTG

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
       PicNet is a small tool that gives indication on network
       traffic on a graphic map. It takes information from MMMMRRRRTTTTGGGG
       lllloooogggg or RRRRRRRRDDDD 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.

HHHHIIIISSSSTTTTOOOORRRRYYYY LLLLIIIISSSSTTTT
       v 1.2, (02/22/01) :
            - New installation with configure (autoconf).
            - New parameter 'Grapher' to specify the MRTG images directory
           or the CGI program (14all.cgi) for displaying the MRTG graphs.
            - Support for RRD files (Round Robin Database Tool).
            - Small bug corrected.


       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.

RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEE PPPPNNNNGGGG IIIIMMMMAAAAGGGGEEEE
       PicNet needs a reference PNG image of your network (one
       per submap).






2001-02-23                     1.2                              1





PICNET(1)                     picnet                    PICNET(1)


       WWWWhhhhyyyy PPPPNNNNGGGG iiiimmmmaaaaggggeeee ????

       PPPPNNNNGGGG (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 GGGGDDDD lllliiiibbbbrrrraaaarrrryyyy now deals with 8-bits PNG images. So this
       tool and MRTG generate PNG images.

       HHHHoooowwww ttttoooo ccccrrrreeeeaaaatttteeee aaaa rrrreeeeffffeeeerrrreeeennnncccceeee iiiimmmmaaaaggggeeee ????

       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888----bbbbiiiittttssss PPPPNNNNGGGG (256 colors).

       - You must use oooonnnneeee ccccoooolllloooorrrr (not used anywhere else in the
       image) ppppeeeerrrr MMMMRRRRTTTTGGGG ttttaaaarrrrggggeeeetttt oooorrrr PPPPiiiiccccNNNNeeeetttt ssssuuuubbbbmmmmaaaapppp and note its iiiinnnnddddeeeexxxx
       vvvvaaaalllluuuueeee (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 _i_m_a_g_e(s) ttttoooo iiiinnnnddddeeeexxxx MMMMRRRRTTTTGGGG
       ssssttttaaaattttssss ppppaaaaggggeeeessss, 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.

       HHHHeeeerrrreeee iiiissss aaaa ttttuuuuttttoooorrrriiiiaaaallll ffffoooorrrr mmmmaaaakkkkiiiinnnngggg aaaa rrrreeeeffffeeeerrrreeeennnncccceeee iiiimmmmaaaaggggeeee uuuussssiiiinnnngggg
       PPPPaaaaiiiinnnnttttSSSShhhhoooopppp PPPPrrrroooo 5555 ::::

       the image manpage

PPPPIIIICCCCNNNNEEEETTTT CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRAAAATTTTIIIIOOOONNNN FFFFIIIILLLLEEEE
       PicNet needs a _r_e_f_e_r_e_n_c_e _P_N_G _i_m_a_g_e and a _c_o_n_f_i_g_u_r_a_t_i_o_n
       _f_i_l_e...




2001-02-23                     1.2                              2





PICNET(1)                     picnet                    PICNET(1)


       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, _e_x_._c_f_g, 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 _i_n_d_e_x_m_a_p.

       HHHHeeeerrrreeee aaaarrrreeee tttthhhheeee ddddiiiiffffffffeeeerrrreeeennnntttt ttttaaaaggggssss yyyyoooouuuu hhhhaaaavvvveeee ttttoooo uuuusssseeee ttttoooo ccccoooonnnnffffiiiigggguuuurrrreeee
       PPPPiiiiccccNNNNeeeetttt ::::

       the config manpage

BBBBEEEEFFFFOOOORRRREEEE BBBBUUUUIIIILLLLDDDDIIIINNNNGGGG PPPPIIIICCCCNNNNEEEETTTT
       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 install PicNet.

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

       First, you must obviously use MMMMRRRRTTTTGGGG :
        http://www.ee.ethz.ch/~oetiker/webtools/mrtg/

       PicNet uses the GGGGDDDD lllliiiibbbbrrrraaaarrrryyyy. You should have installed it
       as MRTG needs it.
        http://www.boutell.com/gd/

       You can optionaly use RRRRRRRRDDDDTTTTOOOOOOOOLLLL. So, PicNet will work with
       RRD files.
        http://www.ee.ethz.ch/~oetiker/webtools/rrdtool/

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

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

       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).




2001-02-23                     1.2                              3





PICNET(1)                     picnet                    PICNET(1)


IIIINNNNSSSSTTTTAAAALLLLLLLLIIIINNNNGGGG PPPPIIIICCCCNNNNEEEETTTT OOOONNNN UUUUNNNNIIIIXXXX
       NB : Before executing picnet, you must create a PPPPNNNNGGGG iiiimmmmaaaaggggeeee
       ooooffff yyyyoooouuuurrrr _nn_ee_tt_ww_oo_rr_kk((((ssss)))) (the image manpage) and a ccccoooonnnnffffiiiigggg ffffiiiilllleeee
       (the config manpage).

       If everything is okay (no pb with paths), you should be
       able to install PicNet this way :

        ./configure
        make install

       Then, you must use the following syntax in the call to
       mrtg :

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

       TTTThhhhaaaatttt''''ssss aaaallllllll !!!!

       But if you have to specify paths or select options, here
       it is...

       You can specify many arguments to ./configure.  Check
       ....////ccccoooonnnnffffiiiigggguuuurrrreeee --------hhhheeeellllpppp.

       Here are the main arguments :

        --prefix=<path to MRTG>
        --with-gd=<path to GD>
        --with-rrd=<path to RRDTool>
        --enable-fr
        --disable-js

       If _c_o_n_f_i_g_u_r_e fails to find MRTG, you won't be able to use
       'mmmmaaaakkkkeeee iiiinnnnssssttttaaaallllllll' to patch MRTG for PicNet. However, you can
       use 'mmmmaaaakkkkeeee' to create _p_i_c_n_e_t file and patch _m_r_t_g later (see
       the chapter "CALLING PICNET").

       If _c_o_n_f_i_g_u_r_e finds RRDTool, PicNet will use RRD files,
       else it will use log files.

       _-_-_e_n_a_b_l_e_-_f_r configures PicNet for HTML pages in french
       (I'm french ;-) )

       _-_-_d_i_s_a_b_l_e_-_j_s for those who don't like JavaScript in the
       HTML pages...

IIIINNNNSSSSTTTTAAAALLLLLLLLIIIINNNNGGGG PPPPIIIICCCCNNNNEEEETTTT OOOONNNN WWWWIIIINNNNDDDDOOOOWWWWSSSS
       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



2001-02-23                     1.2                              4





PICNET(1)                     picnet                    PICNET(1)


        libz.dll

       You must set the TZ variable to your timezone (for Windows
       9X, add _s_e_t _T_Z_=_G_M_T_+_1_1 (your timezone !) to _a_u_t_o_e_x_e_c_._b_a_t).

       Obviously, you must create rrrreeeeffffeeeerrrreeeennnncccceeee _ii_mm_aa_gg_ee((((ssss)))) and a
       ccccoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn ffffiiiilllleeee (see above).

       In the configuration file, you must set WWWWoooorrrrkkkkDDDDiiiirrrr as a
       Windows directory : _D_:_\_I_n_e_t_P_u_b_\_w_w_w_r_o_o_t_\_M_R_T_G (no problem
       with long names and spaces).

CCCCAAAALLLLLLLLIIIINNNNGGGG PPPPIIIICCCCNNNNEEEETTTT
       NB: If you have succeeded in installing PicNet on Unix
       with 'make install', MRTG is already patched for 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 _p_i_c_n_e_t (or _p_i_c_n_e_t_._e_x_e) and _p_a_t_c_h_._p_m in the
           same directory as the _m_r_t_g file.

           2- Backup _m_r_t_g (_c_p _m_r_t_g _m_r_t_g_._b_a_k).

           3- Apply the Perl module _p_a_t_c_h_._p_m 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
           (_m_r_t_g_._c_f_g) as its configuration file.

       Use a Scheduler
           You may use a sssscccchhhheeeedddduuuulllleeeerrrr to execute the _p_i_c_n_e_t 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...




2001-02-23                     1.2                              5





PICNET(1)                     picnet                    PICNET(1)


           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


AAAAUUUUTTTTHHHHOOOORRRR
       Laurent Derrien, <derrien@canl.nc>

       9.9.99 (last update 02.22.01)









































2001-02-23                     1.2                              6


