unix-guide
UNIX-GUIDE(1) mrtg UNIX-GUIDE(1)
NAME
unix-guide - Instructions for running MRTG 2.9.17 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
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 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 instructions 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 cre-
ate. Get a copy from
ftp://sunsite.cnlab-switch.ch/mirror/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://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 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 ftp://sunsite.cnlab-switch.ch/mirror/infozip/zlib/zlib.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.11.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.17.tar.gz | tar xvf -
cd mrtg-2.9.17
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 everything is OK, you will end up with a custom Make-
file for your system. Now type:
make
This builds the rateup binary and edits all the perl pathnames in the
scripts. You can now install mrtg by typing
make 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 avail-
able 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 configuration 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 configura-
tion 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 following:
/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 nor-
mal 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. Unfortunately, adding startup scripts
differs widely amongst different 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.17/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>
3rd Berkeley Distribution 2.9.17 UNIX-GUIDE(1)
