UNIX-GUIDE(1)                  mrtg                 UNIX-GUIDE(1)



NAME
       unix-guide - Instructions for running MRTG 2.9.18pre7 on a
       Unix Box

SYNOPSIS
       MRTG comes to you in Source Code. This means that you have
       to compile parts of it before you can use it on a Unix
       machine. These instructions help you to do so.

PREPARATION
       In order to compile and use mrtg you need a C compiler and
       a copy of perl installed on your machine. In most cases
       this will already be available.  In case it is not, here
       are some starting points. Below I'll give you a detailed
       run through the whole compilation process.

       GCC The GNU C compiler comes pre installed on most of the
           free Unicies out there.  For commercial Derivats you
           may have to download and compile it first. If you have
           no compiler at all there is a chicken and egg problem,
           but there are also precompiled versions of gcc avail-
           able for most of the operating systems.

            http://gcc.gnu.org/


       Perl
           Larg parts of the MRTG system are written in the Perl
           scripting language.  Make sure there is a recent copy
           of perl on your machine (try perl -v).  At least ver-
           sion 5.005 is required for mrtg to work well.  You can
           get the latest perl from

            http://www.perl.com/


       MRTG generates traffic graphs in the PNG format. To be
       able todo this it needs several 3rd party libraries. When
       compiling these libraries I urge you to make sure you com-
       pile them as static libraries. There is just much less
       trouble ahead if you are doing it like this. See the
       Instructions in the next section for inspiration. Note
       that many free unices have all the required libraries
       already in place. So there is no need to install another
       copy. To check it is best to skip all the library instruc-
       tions below and go straight into the mrtg compile.

       If the first attempt fails, and you do not get a working
       version of mrtg, try compiling new copies of all libraries
       as explained below ... Do this BEFORE you send email to me
       about problems compiling mrtg.

       gd  This is a basic graph drawing library created by
           Thomas Boutell.  Note that all releases after Version
           1.3 only create PNG images. This is because a) Thomas
           got into trouble because the GIF format which it used
           to produce uses a compression technology patented by
           Unisys. b) PNG is more efficient and patent free. MRTG
           can work with old and new version of the GD library.
           You can get a recent copy of GD from:

            http://www.boutell.com/gd/


       libpng
           Is required by gd in order to produce PNG graphics
           files. Get it from:

            http://www.libpng.org/pub/png/src/


       zlib
           Finally is needed by libpng to compress the graphics
           files you create.  Get a copy from

            http://www.gzip.org/zlib


       And last but not least you also need mrtg itself. In case
       you have not yet downloaded it, you can find a copy on my
       website:

        http://people.ee.ethz.ch/~oetiker/webtools/mrtg/pub/


LIBRARY COMPILATION
       In this section I will give you step by step instructions
       on how to compile the various libraries required for the
       compilation of mrtg. Note that these libaries may already
       be installed if you have a *BSD or Linux system so that
       you can skip recompiling them. The wget programm used
       below is a simple web downloader you can also enter the
       address into your netscape if you don't have wget avail-
       able.

       First lets create a directory for the compilation. Note
       that this may already exist on your system. No Problem
       just use it.

        mkdir -p /usr/local/src
        cd /usr/local/src

       If you do not have zlib installed:

        wget http://www.gzip.org/zlib/zlib-1.1.4.tar.gz
        gunzip -c zlib.tar.gz | tar xf -
        mv zlib-?.?.?/ zlib
        cd zlib
        ./configure
        make
        cd ..

       If you don't have libpng installed

        wget http://www.libpng.org/pub/png/src/libpng-1.0.12.tar.gz
        gunzip -c libpng-*.tar.gz |tar xf -
        rm libpng-*.tar.gz
        mv libpng-* libpng
        cd libpng
        make -f scripts/makefile.std CC=gcc ZLIBLIB=../zlib ZLIBINC=../zlib
        rm *.so.* *.so
        cd ..

       And now you can compile gd




        wget http://www.boutell.com/gd/http/gd-1.8.3.tar.gz
        gunzip -c gd-1.8.3.tar.gz |tar xf -
        mv gd-1.8.3 gd
        cd gd

       The \ characters at the end of the following lines mean
       that all the following material should actually be written
       on a single line.

        make INCLUDEDIRS="-I. -I../zlib -I../libpng" \
             LIBDIRS="-L../zlib -L. -L../libpng" \
             LIBS="-lgd -lpng -lz -lm"
        cd ..


MRTG COMPILATION
       Ok now everything is ready for the mrtg compilation.

        cd /usr/local/src
        gunzip -c mrtg-2.9.18pre7.tar.gz | tar xvf -
        cd mrtg-2.9.18pre7

       If you all the libraries have been preinstalled on your
       system you can configure mrtg by doing a simple:

        ./configure --prefix=/usr/local/mrtg-2

       Otherwise you may have to give some hints on where to find
       the various libraries required to compile mrtg:

        ./configure --prefix=/usr/local/mrtg-2       \
                    --with-gd=/usr/local/src/gd      \
                    --with-z=/usr/local/src/zlib     \
                    --with-png=/usr/local/src/libpng

       If you have RRDtool available you might want to tell mrtg
       about it so that you can opt to use rrdtool with mrtg.
       Check the mrtg-rrd manpage.

       Configure will make sure your environment is fit for
       building mrtg.  If it finds a problem, it will tell you so
       and it will also tell you what todo about it. If every-
       thing is OK, you will end up with a custom Makefile for
       your system. Now type:

        make

       This builds the rateup binary and edits all the perl path-
       names in the scripts. You can now install mrtg by typing

        make install   (requires gnu install)

       All the software required by MRTG is now installed under
       in the /usr/local/mrtg-2 subdirectory.

       You can now safely delete the libraries we compiled above.
       But then again you might want to keep them around so that
       you have them available when compiling the next version of
       mrtg.

CONFIGURATION
       The next step is now to configure mrtg for monitoring an
       network device.  This is done by creating an mrtg.cfg file
       which defines what you want to monitor. Luckily you don't
       have to dive straight in and start writing your own con-
       figuration file all by yourself. Together with mrtg you
       also got a copy of cfgmaker. This is a script you can
       point at a router of your choice; and it will create a
       mrtg configuration file for you. You can find the script
       in the bin subdirectory.

        cfgmaker --global 'WorkDir: /home/httpd/mrtg'  \
                 --global 'Options[_]: bits,growright' \
                 --output /home/mrtg/cfg/mrtg.cfg    \
                  community@router.abc.xyz

       This example above will create an mrtg config file in
       /home/mrtg/cfg assuming this is a directory visible on
       your webserver. You can read all about cfgmaker in the
       cfgmaker manpage. One area you might want to look at is
       the possibility of using --ifref=ip to prevent interface
       renumbering troubles from catching you.

       If you want to start rolling your own mrtg configuration
       files, make sure you read the reference manpage to learn
       all about the possible configuration options.

RUNNING MRTG
       Once you have created a configuration file, try the fol-
       lowing:

        /usr/local/mrtg-2/bin/mrtg /home/mrtg/cfg/mrtg.cfg

       This will query your router and also create your first
       mrtg trafic graphs and webpages. When you run mrtg for the
       first time there will be a lot of complaints about missing
       log files. Don't worry, this is normal for the first 2
       times you start mrtg. If it keeps complaining after this
       time you might want to look into the problem.

       Starting mrtg by hand is not ideal in the long run. So
       when you are sattisfied with the results you must automate
       the process of running mrtg in regular intervals (this
       means every 5 minutes by default).

       You can either add mrtg to your crontab with a line like
       this:

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

       or if you live in Linux Land the line may look like this
       if you are using "crontab -e"

        */5 * * * *  <mrtg-bin>/mrtg <path to mrtg-cfg>/mrtg.cfg \
                              --logging /var/log/mrtg.log

       or like this if you use /etc/crontab

        */5 * * * *  mrtg-user  <mrtg-bin>/mrtg <path to mrtg-cfg>/mrtg.cfg \
                                        --logging /var/log/mrtg.log

       You can also run mrtg as a daemon process by adding the
       line

        RunAsDaemon: Yes

       to your mrtg configuration file and then creating a
       startup script in your system startup sequence. Unfortu-
       nately, adding startup scripts differs widely amongst dif-
       ferent unix systems. The modern ones normally have a
       directory called /etc/init.d or /etc/rc.d/init.d where you
       put scripts which starts the process you want to run when
       the system boots. Further you must create a symbolic link
       in /etc/rc3.d or /etc/rc.d/rc?.d called S65mrtg (this is
       just a sample name ... it is just important that it starts
       with S followed by a two digit number). If you are not
       sure about this, make sure you consult the documentation
       of your system to make sure you get this right.

       A minimal script to put into init.d might look like this:

        #! /bin/sh
        cd /usr/local/mrtg-2.9.18pre7/bin && ./mrtg --user=mrtg-user \
              /home/httpd/mrtg/mrtg.cfg  --logging /var/log/mrtg.log

       Note that this will only work with RunAsDaemon: Yes in
       your mrtg.cfg file.

AUTHOR
       Tobias Oetiker <oetiker@ee.ethz.ch>



2002-04-15                  2.9.18pre7              UNIX-GUIDE(1)
