.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MRTG-UNIX-GUIDE 1"
.TH MRTG-UNIX-GUIDE 1 "2022-01-19" "2.17.10" "mrtg"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
mrtg\-unix\-guide \- The MRTG 2.17.10 Linux/Unix Installation Guide
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1MRTG\s0 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.
.SH "PREPARATION"
.IX Header "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.
.IP "\s-1GCC\s0" 4
.IX Item "GCC"
The \s-1GNU C\s0 compiler comes preinstalled on most of the free Unices out
there.  For commercial derivatives 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 operating systems.
.Sp
.Vb 1
\& http://gcc.gnu.org/
.Ve
.IP "Perl" 4
.IX Item "Perl"
Large parts of the \s-1MRTG\s0 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. If you use \s-1SNMPV3\s0 and
other new features you should use at least 5.8.
.Sp
You can get the latest perl from
.Sp
.Vb 1
\& http://www.perl.com/
.Ve
.PP
\&\s-1MRTG\s0 generates traffic graphs in the \s-1PNG\s0 format. To be able to do this it
needs several 3rd party libraries. When compiling these libraries I urge you
to make sure you compile them as \fBstatic\fR 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.
.PP
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
\&\fB\s-1BEFORE\s0\fR you send email to me about problems compiling mrtg.
.IP "gd" 4
.IX Item "gd"
This is a basic graph drawing library created by Thomas Boutell.
Note that all releases after Version 1.3 only create
\&\s-1PNG\s0 images. This is because a) Thomas got into trouble because the \s-1GIF\s0
format which it used to produce uses a compression technology patented
by Unisys. b) \s-1PNG\s0 is more efficient and patent free. \s-1MRTG\s0 can work
with old and new version of the \s-1GD\s0 library. You can get a recent copy
of \s-1GD\s0 from:
.Sp
.Vb 1
\& http://www.boutell.com/gd/
.Ve
.IP "libpng" 4
.IX Item "libpng"
Is required by gd in order to produce \s-1PNG\s0 graphics files. Get it from:
.Sp
.Vb 1
\& http://www.libpng.org/pub/png/libpng.html
.Ve
.IP "zlib" 4
.IX Item "zlib"
Is needed by libpng to compress the graphics files you create.
Get a copy from
.Sp
.Vb 1
\& http://www.gzip.org/zlib
.Ve
.PP
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:
.PP
.Vb 1
\& http://oss.oetiker.ch/mrtg/pub
.Ve
.SH "LIBRARY COMPILATION"
.IX Header "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
libraries may already be installed if you have a \fI*BSD\fR or \fILinux\fR system
so you can skip recompiling them. The \fBwget\fR program used below is a
simple web downloader. You can also enter the address into your \fBnetscape\fR
if you don't have \fBwget\fR available.
.PP
First let's create a directory for the compilation. Note that this may
already exist on your system. No problem, just use it.
.PP
.Vb 2
\& mkdir \-p /usr/local/src
\& cd /usr/local/src
.Ve
.PP
If you do not have zlib installed:
.PP
.Vb 8
\& wget http://www.zlib.net/zlib\-1.2.3.tar.gz
\& gunzip \-c zlib\-*.tar.gz | tar xf \-
\& rm zlib\-*.tar.gz
\& mv zlib\-* zlib
\& cd zlib
\& ./configure
\& make
\& cd ..
.Ve
.PP
If you don't have libpng installed
.PP
.Vb 8
\& wget ftp://ftp.simplesystems.org/pub/libpng/png/src/libpng\-1.2.40.tar.gz
\& gunzip \-c libpng\-1.2.34.tar.gz | tar xf \-
\& mv libpng\-* libpng
\& cd libpng
\& env CFLAGS="\-O3 \-fPIC" ./configure \-\-prefix=$INSTALL_DIR 
\& make
\& rm *.so.* *.so
\& cd ..
.Ve
.PP
And now you can compile gd
.PP
For versions up to 1.8.4, try:
.PP
.Vb 5
\& wget http://www.boutell.com/gd/http/gd\-1.8.4.tar.gz
\& gunzip \-c gd\-*.tar.gz |tar xf \-
\& rm gd\-*.tar.gz
\& mv gd\-* gd
\& cd gd
.Ve
.PP
The \e characters at the end of the following lines mean that all the
following material should actually be written on a single line.
.PP
.Vb 6
\& perl \-i~ \-p \-e s/gd_jpeg.o//g Makefile            
\& make INCLUDEDIRS="\-I. \-I../zlib \-I../libpng" \e
\&      LIBDIRS="\-L../zlib \-L. \-L../libpng" \e
\&      LIBS="\-lgd \-lpng \-lz \-lm" \e
\&      CFLAGS="\-O \-DHAVE_LIBPNG"
\& cd ..
.Ve
.PP
For versions starting around 2.0.11, try:
.PP
.Vb 8
\& wget http://www.boutell.com/gd/http/gd\-2.0.33.tar.gz
\& gunzip \-c gd\-2.0.33.tar.gz |tar xf \-
\& mv gd\-2.0.33 gd
\& cd gd
\& env CPPFLAGS="\-I../zlib \-I../libpng" LDFLAGS="\-L../zlib \-L../libpng" \e
\&     ./configure \-\-disable\-shared \-\-without\-freetype \-\-without\-jpeg
\& make
\& cp .libs/* .
.Ve
.SH "MRTG COMPILATION"
.IX Header "MRTG COMPILATION"
Ok, now everything is ready for the mrtg compilation.
.PP
.Vb 3
\& cd /usr/local/src
\& gunzip \-c mrtg\-2.17.10.tar.gz | tar xvf \-
\& cd mrtg\-2.17.10
.Ve
.PP
If all the libraries have been preinstalled on your system you can
configure mrtg by doing a simple:
.PP
.Vb 1
\& ./configure \-\-prefix=/usr/local/mrtg\-2
.Ve
.PP
Otherwise you may have to give some hints on where to find the
various libraries required to compile mrtg:
.PP
.Vb 4
\& ./configure \-\-prefix=/usr/local/mrtg\-2       \e
\&             \-\-with\-gd=/usr/local/src/gd      \e
\&             \-\-with\-z=/usr/local/src/zlib     \e
\&             \-\-with\-png=/usr/local/src/libpng
.Ve
.PP
If you have RRDtool available you might want to tell mrtg about it
so that you can opt to use rrdtool with mrtg. Check mrtg-rrd.
.PP
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 to do about it. If everything is \s-1OK,\s0 you will end up with
a custom Makefile for your system. Now type:
.PP
.Vb 1
\& make
.Ve
.PP
This builds the rateup binary and edits all the perl pathnames in
the scripts. You can now install mrtg by typing
.PP
.Vb 1
\& make install   (requires gnu install)
.Ve
.PP
All the software required by \s-1MRTG\s0 is now installed under
the \fI/usr/local/mrtg\-2\fR subdirectory.
.PP
You can now safely delete the libraries we compiled above. Then
again, you might want to keep them around so that you have them
available when compiling the next version of mrtg.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The next step is to configure mrtg for monitoring a network
device.  This is done by creating an \fImrtg.cfg\fR 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 \fBcfgmaker\fR. This
is a script you can point at a router of your choice; it will
create a mrtg configuration file for you. You can find the script in
the \fIbin\fR subdirectory.
.PP
.Vb 4
\& cfgmaker \-\-global \*(AqWorkDir: /home/httpd/mrtg\*(Aq  \e
\&          \-\-global \*(AqOptions[_]: bits,growright\*(Aq \e
\&          \-\-output /home/mrtg/cfg/mrtg.cfg    \e
\&           community@router.abc.xyz
.Ve
.PP
This example above will create an mrtg config file in
\&\fI/home/mrtg/cfg\fR assuming this is a directory visible on your
webserver. You can read all about cfgmaker in cfgmaker. One area you might
want to look at is the possibility of using \fB\-\-ifref=ip\fR to prevent
interface renumbering troubles from catching you.
.PP
If you want to start rolling your own mrtg configuration files, make sure
you read mrtg-reference to learn all about the possible configuration options.
.SH "RUNNING MRTG"
.IX Header "RUNNING MRTG"
Once you have created a configuration file, try the following:
.PP
.Vb 1
\& /usr/local/mrtg\-2/bin/mrtg /home/mrtg/cfg/mrtg.cfg
.Ve
.PP
This will query your router and also create your first mrtg traffic
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.
.PP
Starting mrtg by hand is not ideal in the long run. So when you are
satisfied with the results you can automate the process of running mrtg in
regular intervals (this means every 5 minutes by default).
.PP
You can either add mrtg to your crontab with a line like this:
.PP
.Vb 3
\& 0,5,10,15,20,25,30,35,40,45,50,55 * * * * \e
\&       <mrtg\-bin>/mrtg <path to mrtg\-cfg>/mrtg.cfg \e
\&                \-\-logging /var/log/mrtg.log
.Ve
.PP
or if you live in Linux Land the line may look like this if you are
using \f(CW\*(C`crontab \-e\*(C'\fR
.PP
.Vb 2
\& */5 * * * *  <mrtg\-bin>/mrtg <path to mrtg\-cfg>/mrtg.cfg \e
\&                       \-\-logging /var/log/mrtg.log
.Ve
.PP
or like this if you use \fI/etc/crontab\fR
.PP
.Vb 2
\& */5 * * * *  mrtg\-user  <mrtg\-bin>/mrtg <path to mrtg\-cfg>/mrtg.cfg \e
\&                                 \-\-logging /var/log/mrtg.log
.Ve
.PP
You can also run mrtg as a daemon process by adding the line
.PP
.Vb 1
\& RunAsDaemon: Yes
.Ve
.PP
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 \fI/etc/init.d\fR or \fI/etc/rc.d/init.d\fR where you
put scripts which starts the process you want to run when the system
boots. Further you must create a symbolic link in \fI/etc/rc3.d\fR or
\&\fI/etc/rc.d/rc?.d\fR called \fIS65mrtg\fR (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.
.PP
A \fBminimal\fR script to put into \fIinit.d\fR might look like this:
.PP
.Vb 3
\& #! /bin/sh
\& cd /usr/local/mrtg\-2.17.10/bin && ./mrtg \-\-user=mrtg\-user \e
\&       /home/httpd/mrtg/mrtg.cfg  \-\-logging /var/log/mrtg.log
.Ve
.PP
Note that this will only work with \fBRunAsDaemon: Yes\fR in your
mrtg.cfg file.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker <tobi@oetiker.ch>