Version 2.5.4, October 13th, 1998

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>

• What is the Multi Router Traffic Grapher
• Highlights of MRTG
• The History
• Release Notes
• Getting and Installing MRTG
• Configuration Tips
• Frequently Asked Questions
• 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 arrond 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. The look of the webpages produced by MRTG is highly configurable.
10. MRTG is available under the GNU PUBLIC LICENSE.

Version 2.5.4

Bugfixes:diff routine in rateup.c corrected, better matching for Cisco version number matching in cfgmaker, improved regexp matchin in indexmaker, ignore whitespace in answers from external gatherers, do not complain if child rateup process has already terminated before the wait in the mrtg, better handling of stale lockfiles.

Features:Configurable SNMP parameters.

Version 2.5

Bugfixes: Skewing at log interval bounderies fixed. White space at line-endings in cfgfiles handled gracefully. MaxBytes line is only drawn if it is stricly inside the graph. Timezone handling improved. Further fighting against the overflow bug.

Features: More compatible cfgmaker (--vendor switch). Added a README about the logfile-format. Made a package in zip format available for our NT friends. Same goes for rateup.

Contribs:: PingProbe updated. Atmmaker to create cfg files for FORE ASX. Rewrite of mailstats script.

Version 2.4

Bugfixes: IconDir works now, mrtg.cfg-dist debugged and rewritten, replace int by sprintf "%.0f" to better handle large numbers, better 'external command' Target parsing, debugged BER.pm ...

Application tips for Apache-1.2 added to mrtg.cfg-dist

added nopercent option to supress display of percentage in html page.

added contrib by Philippe.Simonet@SWISSTELECOM.com: a c-program to create gifs showing the traffic distribution over time

Version 2.3

New Configuration Options: IconDir, XScale, YScale, Weekformat check 'mrtg.cfg-dist' for details.

New Pingprobe version

Improved behaviour of rateup with Unscaled Option, MaxBytes and AbsMax set. Now, the graphs will be scaled all the same as soon as the traffic goes over MaxBytes.

Several bugfixes in rateup.c

Version 2.2

Lots of new and exciting things in the contrib area.

Made graphs in indexmaker generated pages clickable

made mrtg observe order of routers in cfg file .... as suggested by Mick Ghazey

Added timezone configurable to set a timezone per router. Details in mrtg.cfg-dist as suggested by Jun (John) Wu

Added MaxBytes sanity check ....

Fixed portability problem of Makefile under IRIX

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:
   http://www.boutell.com/gd/

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

4. Edit the MRTG Makefile to fit your system. At least change the PERL and GD_LIB variables.
   Then use make rateup to create the rateup binary.
   And make substitute to insert the path of your Perl binary into the perlscripts which come with MRTG.

5. Decide where MRTG should store the webpages it creates. Copy the mrtg*.gif files into this directory. They will be referenced in the generated webpages. You may also want to move the readme.html file to this directory so that you have the docs handy whenever you need them.

6. All the other files from the MRTG distribution should go into your MRTG binary directory. This directory can be anywhere because MRTG will find its location upon startup. The following files are required to be in MRTG-bin: BER.pm, SNMP_Session.pm, mrtg, rateup.

7. Create your personal mrtg.cfg file. You can find the documentation about this in the file mrtg-conf.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.

8. If you are upgrading from any pre 2.0 version of MRTG, you need to run the convert script with your old logfiles, in order to bring them over to the mrtg-2.0 log-file-format.

9. Try to start MRTG. Type ./mrtg mrtg.cfg on the command line, while you are in your MRTG binary 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 ...

Q: I need more documentation ...
A: Make sure you have checked the files 'mrtg-conf.html' and 'mibhelp.txt' as well as the 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 recent Linux Journal.

Q: My perl complains about the SNMP_Session.pm library ...
A: If you are running a version of perl before 5.002 you should use SNMP_Session.pm-for-perl5.001 .

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.

If your questions are still not answered, make sure to check out the Official MRTG FAQ Site and browse the MRTG Mailing list Archives.

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 the latest version of mrtg from: http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/pub/.
• Download and install the latest version of Perl 5 for Win32 from Activware.
• Download the pre-compiled version of rateup from: http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/pub/
• Edit the main mrtg script downloaded in step #1 and remove the "#" from the beginning of the line that reads "$main::OS = 'NT';".
• Create a batch file with the following command: perl {path to mrtg}\mrtg {path to mrtg.cfg}\mrtg.cfg

  For example: perl c:\mrtg\mrtg c:\mrtg\mrtg.cfg

• Use cfgmaker or manually configure your mrtg.cfg file (documentation on the structure of the file is in the file mrtg.cfg-dist).
• Execute your batch file from step #6 from a command prompt to verify that there are no errors in your mrtg.cfg file and that everything is working correctly. (On the first pass it is normal to see four warnings from Rateup about your log files for each target).
• If everything looks good, configure the scheduler (AT) service to run the batch file from step #6 every 5 minutes. Alternatively you might want to use this perlscript to start mrtg every 300 seconds:

  
    $interval=300;
    while (1) {
      sleep( $interval - time() % $interval );
      system 'c:\bin\perl mrtg mrtg.cfg';
    }                               
        
  

  You may also want to check the MRTG Statistic Updater by Jason Levine. This is a VB tool which runs as a service on your NT and does take care of starting mrtg every 5 minutes.

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