


mrtg                                                UNIX-GUIDE(1)



NNNNAAAAMMMMEEEE
     unix-guide - Instructions for running MRTG 2.9.6 on a Unix
     Box

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

PPPPRRRREEEEPPPPAAAARRRRAAAATTTTIIIIOOOONNNN
     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 available 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 version
         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
     compile them as static, non shared 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
     though 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
     instructions below and go straight into the mrtg compile.

     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



2000-12-12              Last change: 2.9.6                      1






mrtg                                                UNIX-GUIDE(1)



         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/


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

          http://www.info-zip.org/pub/infozip/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://ee-staff.ethz.ch/~oetiker/webtools/mrtg/pub


LLLLIIIIBBBBRRRRAAAARRRRYYYY CCCCOOOOMMMMPPPPIIIILLLLAAAATTTTIIIIOOOONNNN
     In this section I will give you 1:1 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 _*_B_S_D or _L_i_n_u_x system. The wwwwggggeeeetttt programm used
     below is a simple web downloader you can also enter the
     address into your nnnneeeettttssssccccaaaappppeeee if you don't have wwwwggggeeeetttt available.

     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://ftp.info-zip.org/pub/infozip/zlib/zlib.tar.gz
      gunzip -c zlib.tar.gz | tar xf -
      mv zlib-?.?.?/ zlib
      cd zlib
      ./configure
      make
      cd ..



2000-12-12              Last change: 2.9.6                      2






mrtg                                                UNIX-GUIDE(1)



     If you don't have libpng installed

      wget http://www.libpng.org/pub/png/src/libpng-1.0.8.tar.gz
      gunzip -c libpng-1.0.8.tar.gz |tar xf -
      mv libpng-1.0.8 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 line 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 ..


MMMMRRRRTTTTGGGG CCCCOOOOMMMMPPPPIIIILLLLAAAATTTTIIIIOOOONNNN
     Ok now everything is ready for the mrtg compilation.

      cd /usr/local
      gunzip -c mrtg-2.9.6.tar.gz | tar xvf -
      cd mrtg-2.9.6

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

      ./configure

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

      ./configure --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.





2000-12-12              Last change: 2.9.6                      3






mrtg                                                UNIX-GUIDE(1)



     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 everything
     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
     pathnames in the scripts. All the software required by MRTG
     is now in the _r_u_n 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.

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
     The next step is now to configure mrtg for monitoring an
     network device.  This is done by creating an _m_r_t_g_._c_f_g file
     which defines what you want to monitor. Luckily you don't
     have to dive straight in and start writing your own
     configuration file all by yourself. Together with mrtg you
     also got a copy of ccccffffggggmmmmaaaakkkkeeeerrrr. 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
     _b_i_n subdirectory.

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

     This example above will create an mrtg config file in
     _/_h_o_m_e_/_h_t_t_p_d_/_m_r_t_g 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 --------iiiiffffrrrreeeeffff====iiiipppp 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.

RRRRUUUUNNNNNNNNIIIINNNNGGGG MMMMRRRRTTTTGGGG
     Once you have created a configuration file, try the
     following:

      /usr/local/mrtg-2.9.6/bin/mrtg /home/httpd/mrtg/mrtg.cfg

     This will query your router and also create your first mrtg
     trafic graphs and webpages. When you run mrtg for the first



2000-12-12              Last change: 2.9.6                      4






mrtg                                                UNIX-GUIDE(1)



     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

     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

     or like this if you use _/_e_t_c_/_c_r_o_n_t_a_b

      */5 * * * *  mrtg-user  <mrtg-bin>/mrtg <path to mrtg-cfg>/mrtg.cfg

     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. Unfortunately,
     adding startup scripts differs widely amongst different unix
     systems. The modern ones normally have a directory called
     _/_e_t_c_/_i_n_i_d_._d or _/_e_t_c_/_r_c_._d_/_i_n_i_t_._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 _/_e_t_c_/_r_c_3_._d or
     _/_e_t_c_/_r_c_._d_/_r_c_?_._d called _S_6_5_m_r_t_g (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 mmmmiiiinnnniiiimmmmaaaallll script to put into _i_n_i_t_._d might look like this:

      #! /bin/sh
      cd /usr/local/mrtg-2.9.6/bin && ./mrtg --user=mrtg-user /home/httpd/mrtg/mrtg.cfg

     Note that this will only work with RRRRuuuunnnnAAAAssssDDDDaaaaeeeemmmmoooonnnn:::: YYYYeeeessss in your
     mrtg.cfg file.

AAAAUUUUTTTTHHHHOOOORRRR
     Tobias Oetiker <oetiker@ee.ethz.ch>



2000-12-12              Last change: 2.9.6                      5



