MRTG 2.8.12

Programming by	Tobias Oetiker <oetiker@ee.ethz.ch> Dave Rand <dlr@bungi.com> and a number of other people from the Global-Village
Documentation by	Tobias Oetiker <oetiker@ee.ethz.ch>
Domain Reflectors:	www.mrtg.org (by Timothy Kennedy of Erol's Internet Service), mrtg.eu.org (by Michel Renfer of LAN Services AG), mrtg.net.ru (by Andrey G. Sergeev <andris@aha.ru>).
Active WWW Mirrors:	Swiss Original, JP, USA, CZ, BR, BR, UK, TH, UK.
Not so Active WWW Mirrors:	AU, USA, RO, PL, JP, JP.
Active FTP Mirrors:	US, Poland, CZ, SE, DE, IT, US, TH, RU, UK, BR, JP, JP.
Less Active FTP Mirrors:	USA III, RO, NO.
Translations:	Japanese.

• What is the Multi Router Traffic Grapher
• Highlights of MRTG
• The History
• Release Notes
• Getting and Installing MRTG
• Configuration Tips
• Frequently Asked Questions
• MRTG on the Usenet
• The MRTG Mailing List
• Windows NT Notes

The Multi Router Traffic Grapher (MRTG) is a tool to monitor the traffic load on network-links. MRTG generates HTML pages containing GIF images which provide a LIVE visual representation of this traffic. Check http://www.ee.ethz.ch/stats/mrtg/ for an example. MRTG is based on Perl and C and works under UNIX and Windows NT. MRTG is being successfully used on many sites around the net. Check the MRTG-Site-Map.

1. Works on most UNIX platforms and Windows NT
2. Uses Perl for easy customization
3. Has a highly portable SNMP implementation written entirely in Perl thanks to Simon Leinen. There is no need to install any external SNMP package.
4. MRTG's logfiles do NOT grow. Thanks to the use of a unique data consolidation algorithm.
5. MRTG comes with a semi-automatic configuration tool.
6. MRTG's query engine checks for port reconfigurations on the router and warns the user when they occur.
7. Time critical routines are written in C thanks to the initiative of Dave Rand my Co-Author
8. Graphics are generated directly in GIF format, using the GD library by Thomas Boutell.
9. This package produces PNG or GIF format, depending on the version of GDLIB used to build MRTG. GDLIB prior to 1.3 produce LZW compressed GIFS, version 1.3-1.5 uses run-length compression and Version 1.6 and later use PNG format. Thus, users in the US should make sure they link with the right Version of GDLIB.
10. The look of the webpages produced by MRTG is highly configurable.
11. MRTG is available under the GNU General Public License.

Check the latest release notes by going to the mrtg CHANGES file.

1. Get the latest Version of MRTG from:
   http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/pub/

2. Get and compile the GD library by Thomas Boutell:
   www.boutell.com. Unless you know what you are doing, make sure you build libgd, zlib and libpng as static libraries. There are detailed instructions in the README file which comes int the MRTG archive.

3. Make sure you have Perl Version 5.004_4 or later on your system:
   http://www.perl.com/perl/info/software.html

4. type ./configure this will prepare MRTG for your system. if something is missing, configure will tell you what todo about it. (Again, see the README file for some more on this.)

5. run make to build the rateup executable and edit the perl path in mrtg and its companion tools.

6. Decide where MRTG should store the webpages it creates. Copy the images/mrtg*.png files into this directory. They will be referenced in the generated webpages.

7. The run directory contains all the files, MRTG needs to operate. This directory can be anywhere because MRTG will find its location upon startup.

8. Now create your personal mrtg.cfg file. You can find the documentation about this in the file config.html See the Configuration hints section for some further help. The difficult part in creating the configuration file is getting your router-port assignment correct. To help you with this, the cfgmaker tool will generate all the router specific parts of your configuration file.

   cfgmaker <community>@<router-host-name or IP>

   If you don't know the community of your router, try public as community name. When using cfgmaker, make sure to add the WorkDir: parameter to the resulting config file.

9. Try to start MRTG. Type ./mrtg mrtg.cfg on the command line, while you are in your MRTG run directory. MRTG will now parse your configuration file, and complain if you have introduced any unknown keywords or structures. If MRTG is happy with the cfg file, it starts gathering traffic data from the routers you have specified. With this information it will then start the rateup tool which will create a logfile and a traffic graph GIF for each Target. When you start MRTG for the very first time, rateup will complain that it can not find any logfiles and the graphs generated will look rather empty. Just ignore the complaints. If you remove the empty graphs, and run MRTG again, rateup will create new graphs which look better.

10. Integrate MRTG into your crontab. Just add the following line to your crontab file to have MRTG run every 5 minutes (The line is broken for readability only. Replace the backslash in the first line with the second line):

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

• If you are monitoring a number of links, you might want to create an overview page. For our own site I have created the indexmaker script, which you can use to create a html page containing hrefs that point to your individual traffic statistics pages. Note, that you need to edit this script for your purposes. The script you got, includes our Universities Logo (http://www.ee.ethz.ch/eth.199x32.gif) into the page.

  indexmaker <mrtg.cfg> <regexp for router-names>

• If you are monitoring many targets, use the special target names '^' and '$' to prepend or append text to any of the Keywords in the sections below. Note that the definition of the '^' and '$' targets are position dependant. They always influence the lines below in the cfg file. The special target '_' for specifying defaults may come handy as well.

• Since MRTG updates it's graphs every 5 minutes, you may experience problems with proxy caches and local Netscape browser caches. Sometimes these caches will return the old cached graphics instead of the real and updated versions from the webserver.

  If you are running the apache webserver, you can use the WriteExpire Keyword in the mrtg.cfg file. With this, mrtg will create *.meta files for each gif and html page. These files will contain 'Expire' headers which the Apache webserver can ship out together with the gif and html pages (Use to MetaDir keyword in the apache config file to enable this). With the information from the expire headers, Netscape and all the proxy caches will know when they have to fetch a new version of the file from your website and when they can use their cached version.

• Although MRTG's primary use is traffic monitoring, you can observe any SNMP variable you want. People are using it to monitor ModemBanks, ServerLoad, ErrorRates on Interfaces and many other things. If you are using MRTG for something other than traffic monitoring, please send me a short blurb to include here. Best would be with a sample URL and some hints about how you have configured MRTG ... Check the MRTG-Site-Map for other peoples work related to this.

• Some monitored devices such as routers may have cards which can be moved around inside. When this happens data that once was read from one interface index now appears on a new index. This can confuse data collection. Often MRTG will notice the change and report the following:

         -------------------------------------------------------------------
         Warning: There is something wrong with Target 1.2.3.4
        
         * Its ifDescr used to be etc4p4
         * Now it is etc3p4
       
         I will not update this graph for the moment. Maybe your Router has
         changed the port to interface mapping. This can happen when new
         Interfaces are added to the router or when it is rebooted.
      
         You should alter your 1.2.3.4.cfg file to fix the mapping and then
         remove the offending lines from your 1.2.3.4.ok file. Mrtg will
         then assume that everything is OK and create new entries representing
         the new matching.
         --------------------------------------------------------------------
        

  You can help prevent this problem by using either IP addresses or Physcial Address instead of the default Interface Indices. The program cfgmaker_phys can convert your *.cfg files to use Physical Addresses. See config.txt for more information.

Q: Why is there no "@#$%" (my native language) version of MRTG.
A: Nobody has contributed a "@#$%.pmd" file. Go into the "translate" directory and create your own translation file. When you are happy with it send it to me for inclusion with the next mrtg release.

Q: I need a script to make mrtg work with xyz.
A: Probably this has already been done. Check the stuff in the "contrib" directory. There is a file called 00INDEX in that directory which tells what you can find there.

Q: I need more documentation ...
A: Make sure you have checked the files in the doc directory of the mrtg distribution archive. Most notably 'config.html' and 'mibhelp.txt' and 'squid.txt'. Further there is a host of unsuported, contributed scripts in the 'contrib' directory of you mrtg distribution. If you need even more infos, make sure to check the mailing list archive as well. There has also been an article about SNMP and mrtg in a backissue of the Linux Journal. It's author David Guerrero has made it available on the net. Check http://www.mec.es/~david/papers/snmp

Q: The GIFs created by MRTG look very strange. Not all the grid lines are drawn and ...
A: Remove the *-{week,day,month,year}.gif files and start MRTG again. Using MRTG for the first time, you might have to do this twice. This will also help, when you introduce new routers into the cfg file.

Q: What is my Community Name?
A: Try 'public', as this is the default Community Name.

Q: I compiled your program and I get the following errors: at the command line I typed ./mrtg kirit.cfg and I get :

    Can't locate Socket.pm in @INC at /SNMP_Session.pm line 27. 
    BEGIN failed--compilation aborted at /SNMP_Session.pm line 27.
    BEGIN failed--compilation aborted at ./mrtg line 356.

Q:My graphs show a flat, nonzero line during an outage. What's up with that?

A:Well, the short answer is that when an SNMP query goes out and a response doesn't come back, MRTG has to assume something to put in the graph, and by default it assumes that the last answer we got back is probably closer to the truth than zero. This assumption is not perfect (as you have noticed), it's a trade-off that happens to fail during a total outage. If it's an unacceptable trade-off, run at least MRTG V2.8.4 and use the "unknaszero" option. You may want to know what you're trading off, so in the spirit of trade-offs, here's the long answer:

The problem is that MRTG doesn't know *why* the data didn't come back, all it knows is that it didn't come back. It has to do something, and it assumes it's a stray lost packet rather than an outage.

Why don't we always assume the circuit is down, and use zero, which will (we think) be more nearly right? Well, it turns out that you may be taking advantage of MRTG's "assume last" behaviour without being aware of it.

MRTG uses SNMP (Simple Network Management Protocol) to collect data, and SNMP uses UDP (User Datagram Protocol) to ship packets around. UDP is connectionless (not guaranteed) - unlike TCP where packets are tracked and acknowledged and, if needed, re-transmitted end-to end, UDP just throws packets at the network and hopes they arrive. Sometimes they don't.

One likely cause of lost SNMP data is congestion, another is busy routers. Other possibilities include transient telecommunications problems, router buffer overflows (which may or may not be congestion-related), "dirty lines" (links with high error rates), and acts of God. These things happen all the time, we just don't notice because many interactive services are TCP-based and the lost packets get retransmitted automatically.

In the above cases where some SNMP packets are lost but traffic is flowing, assuming zero is the wrong thing to do - you end up with a graph that looks like it's missing teeth whenever the link fills up. MRTG interpolates the lost data to produce a smoother graph which is more accurate in cases of intermittent packet loss. But with V2.8.4 and above, you can use the "unknaszero" option to produce whichever graph is best under the conditions typical of your network.

For discussion of MRTG or related topics on the UseNet, please send your posts to:

There are two mailing lists for MRTG available. One is called 'mrtg' and is a discussion list for users and developers. The other is called 'mrtg-announce' and is a low volume list for MRTG related announcements.

To subscribe to these mailing lists, send a message with the subject line subscribe to either mrtg-request@list.ee.ethz.ch or mrtg-announce-request@list.ee.ethz.ch. For posting to the mrtg list use the address mrtg@list.ee.ethz.ch.

Further information about the usage of the mailing lists is available by sending a message with the subject line 'help' to either one of the request addresses.

For past activity there is also a mailing list archive available: http://www.ee.ethz.ch/~slist/mrtg

By Stuart Schneider <SchneiS@testlab.orst.edu>

To setup mrtg on a WindowsNT system, you can follow the instructions already provided for UNIX systems with the following addition:

6.5. Change the $main::OS setting at the top of the mrtg script to equal 'NT'.

Or, for those who need a little extra help, follow these steps:

• Download and unpack mrtg-2.8.12.zip from: http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/pub/.
• Download and install the latest version of Perl 5 for Win32 from ActiveState.
• Edit the main run/mrtg script downloaded in step #1 and remove the "#" from the beginning of the line that reads "$main::OS = 'NT';".
• Use run\cfgmaker or manually configure your mrtg.cfg file. Be sure the SNMP Service is installed and running on the device/computer you are attempting to monitor. (Documentation on the structure of the file is in the file doc\config.txt and in doc\sample-mrtg.cfg.)
• Add the lines:

  RunAsDaemon: Yes
  Interval: 5
  

  To your mrtg.cfg file.
• Execute your mrtg with your mrtg.cfg file as argument.

  cd \mrtg-2.8.12
  perl mrtg mrtg.cfg
  

  At first, expect some output from the script as it creates the necessary databases. after about 15 minutes all should be quiet. If you have errors in your mrtg.cfg file Mrtg will tell you right after you try to start it.
• Might want to create a link in your autostart folder for mrtg so that it gets launched everytime your start your machine.

If you have any questions about this program, or have it up and running,
we would like to hear from you: