|
Packit |
667938 |
=head1 NAME
|
|
Packit |
667938 |
|
|
Packit |
667938 |
mrtg-reference - MRTG 2.17.7 configuration reference
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 OVERVIEW
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The runtime behaviour of MRTG is governed by a configuration file.
|
|
Packit |
667938 |
Run-of-the-mill configuration files can be generated with B<cfgmaker>.
|
|
Packit |
667938 |
(Check L<cfgmaker>). But for more elaborate configurations some hand-tuning
|
|
Packit |
667938 |
is required.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This document describes all the configuration options understood by
|
|
Packit |
667938 |
the mrtg software.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 SYNTAX
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MRTG configuration file syntax follows some simple rules:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Keywords must start at the beginning of a line.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Lines which follow a keyword line which start
|
|
Packit |
667938 |
with a blank are appended to the keyword line
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Empty Lines are ignored
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Lines starting with a # sign are comments.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can add other files into the configuration file using
|
|
Packit |
667938 |
|
|
Packit |
667938 |
B<Include:> I<file>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Include: base-options.inc
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If included files are specified with relative paths, both the current
|
|
Packit |
667938 |
working directory and the directory containing the main config file will
|
|
Packit |
667938 |
be searched for the files. The current working directory will be searched
|
|
Packit |
667938 |
first.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the included filename contains an asterisk, then this is taken as a
|
|
Packit |
667938 |
wildcard for zero or more characters, and all matching files are included.
|
|
Packit |
667938 |
Thus, you can use this statement to include all files in a specified
|
|
Packit |
667938 |
subdirectory.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Include: servers/*.cfg
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In this case, you should be very careful that your wildcard pattern does not
|
|
Packit |
667938 |
find a match relative to the current working directory if you mean it to be
|
|
Packit |
667938 |
relative to the main config file directory, since the working directory is
|
|
Packit |
667938 |
checked for a match first (as with a normal Include directive). Therefore,
|
|
Packit |
667938 |
use of something like '*/*' is discouraged.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 GLOBAL KEYWORDS
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 WorkDir
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir specifies where the logfiles and the webpages should
|
|
Packit |
667938 |
be created.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 OPTIONAL GLOBAL KEYWORDS
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 HtmlDir
|
|
Packit |
667938 |
|
|
Packit |
667938 |
HtmlDir specifies the directory where the html (or shtml,
|
|
Packit |
667938 |
but we'll get on to those later) lives.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE: Workdir overrides the settings for htmldir, imagedir
|
|
Packit |
667938 |
and logdir.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Htmldir: /www/mrtg/
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ImageDir
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ImageDir specifies the directory where the images live. They
|
|
Packit |
667938 |
should be under the html directory.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Imagedir: /www/mrtg/images
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 LogDir
|
|
Packit |
667938 |
|
|
Packit |
667938 |
LogDir specifies the directory where the logs are stored.
|
|
Packit |
667938 |
This need not be under htmldir directive.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Logdir: /www/mrtg/logs
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Forks (UNIX only)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
With system that supports fork (UNIX for example), mrtg can fork itself into multiple
|
|
Packit |
667938 |
instances while it is acquiring data via snmp.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
For situations with high latency or a great number of devices
|
|
Packit |
667938 |
this will speed things up considerably. It will not make things faster,
|
|
Packit |
667938 |
though, if you query a single switch sitting next door.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As far as I know NT can not fork so this option is not available on NT.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Forks: 4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 EnableIPv6
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When set to yes, IPv6 support is enabled if the required libraries are
|
|
Packit |
667938 |
present (see the L<mrtg-ipv6> manpage). When IPv6 is enabled, mrtg can talk
|
|
Packit |
667938 |
to routers using SNMP over IPv6 and targets may be specified by their
|
|
Packit |
667938 |
numeric IPv6 addresses as well as by hostname or IPv4 address.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If IPv6 is enabled and the target is a hostname, mrtg will try to resolve
|
|
Packit |
667938 |
the hostname to an IPv6 address and, if this fails, to an IPv4 address.
|
|
Packit |
667938 |
Note that mrtg will only use IPv4 if you specify an IPv4 address or a
|
|
Packit |
667938 |
hostname with no corresponding IPv6 address; it will not fall back to IPv4
|
|
Packit |
667938 |
if it simply fails to communicate with the target using IPv6. This is by
|
|
Packit |
667938 |
design.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that many routers do not currently support SNMP over IPv6. Use the
|
|
Packit |
667938 |
I<IPv4Only> per target option for these routers.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
IPv6 is disabled by default.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
EnableIPv6: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 EnableSnmpV3
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When set to yes, uses the Net::SNMP module instead of the SNMP_SESSION module for
|
|
Packit |
667938 |
generating snmp queries. This allows the use of SNMPv3 if other snmpv3 parameters
|
|
Packit |
667938 |
are set.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SNMPv3 is disabled by default.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
EnableSnmpV3: yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Refresh
|
|
Packit |
667938 |
|
|
Packit |
667938 |
How many seconds apart should the browser (Netscape) be
|
|
Packit |
667938 |
instructed to reload the page? If this is not defined, the
|
|
Packit |
667938 |
default is 300 seconds (5 minutes).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Refresh: 600
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Interval
|
|
Packit |
667938 |
|
|
Packit |
667938 |
How often do you call mrtg? The default is 5 minutes. If
|
|
Packit |
667938 |
you call it less often, you should specify it here.
|
|
Packit |
667938 |
This does two things:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The generated HTML page contains the right
|
|
Packit |
667938 |
information about the calling interval ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A META header in the generated HTML page will instruct
|
|
Packit |
667938 |
caches about the time-to-live of this page .....
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In this example, we tell mrtg that we will be calling it
|
|
Packit |
667938 |
every 10 minutes. If you are calling mrtg every 5
|
|
Packit |
667938 |
minutes, you can leave this line commented out.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Interval: 10
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that unless you are using rrdtool you can not set Interval to less
|
|
Packit |
667938 |
than 5 minutes. If you are using rrdtool you can set interval in the format
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Interval: MM[:SS]
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Down to 1 second. Note though, setting the Interval for an rrdtool/mrtg
|
|
Packit |
667938 |
setup will influence the initial creation of the database. If you change the
|
|
Packit |
667938 |
interval later, all existing databases will remain at the resolution they
|
|
Packit |
667938 |
were initially created with. Also note that you must make sure that your
|
|
Packit |
667938 |
mrtg-rrd Web-frontend can deal with this kind of Interval setting.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 MaxAge
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MRTG relies heavily on the real time clock of your computer. If the time is
|
|
Packit |
667938 |
set to a wrong value, especially if it is advanced far into the future,
|
|
Packit |
667938 |
this will cause mrtg to expire lots of supposedly old data from the log files.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
To prevent this, you can add a 'reasonability' check by specifying a maximum
|
|
Packit |
667938 |
age for log files. If a file seems to be older, mrtg will not touch it but
|
|
Packit |
667938 |
complain instead, giving you a chance to investigate the cause.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MaxAge: 7200
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The example above will make mrtg refuse to update log files older than 2
|
|
Packit |
667938 |
hours (7200 seconds).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 WriteExpires
|
|
Packit |
667938 |
|
|
Packit |
667938 |
With this switch mrtg will generate .meta files for CERN
|
|
Packit |
667938 |
and Apache servers which contain Expiration tags for the
|
|
Packit |
667938 |
html and gif files. The *.meta files will be created in
|
|
Packit |
667938 |
the same directory as the other files, so you will have
|
|
Packit |
667938 |
to set "MetaDir ." and "MetaFiles on"
|
|
Packit |
667938 |
in your apache.conf or .htaccess file for this to work
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE: If you are running Apache-1.2 or later, you can use the mod_expire
|
|
Packit |
667938 |
to achieve the same effect ... see the file htaccess.txt
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WriteExpires: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 NoMib2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Normally we ask the SNMP device for 'sysUptime' and 'sysName' properties.
|
|
Packit |
667938 |
Some do not have these. If you want to avoid getting complaints from
|
|
Packit |
667938 |
mrtg about these missing properties, specify the nomib2 option.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
An example of agents which do not implement base mib2 attributes are
|
|
Packit |
667938 |
Computer Associates - Unicenter TNG Agents. CA relies on using the base
|
|
Packit |
667938 |
OS SNMP agent in addition to its own agents to supplement the management
|
|
Packit |
667938 |
of a system.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NoMib2: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 SingleRequest
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Some SNMP implementations can not deal with requests asking for
|
|
Packit |
667938 |
multiple snmp variables in one go. Set this in your cfg file to force
|
|
Packit |
667938 |
mrtg to only ask for one variable per request.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SingleRequest: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 SnmpOptions
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Apart from the per target timeout options, you can also configure the
|
|
Packit |
667938 |
behaviour of the snmpget process on a more profound level. SnmpOptions
|
|
Packit |
667938 |
accepts a hash of options. The following options are currently supported:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
timeout => $default_timeout,
|
|
Packit |
667938 |
retries => $default_retries,
|
|
Packit |
667938 |
backoff => $default_backoff,
|
|
Packit |
667938 |
default_max_repetitions => $max_repetitions,
|
|
Packit |
667938 |
use_16bit_request_ids => 1,
|
|
Packit |
667938 |
lenient_source_port_matching => 0,
|
|
Packit |
667938 |
lenient_source_address_matching => 1
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The values behind the options indicate the current default value.
|
|
Packit |
667938 |
Note that these settings OVERRIDE the per target timeout settings.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A per-target SnmpOptions[] keyword will override the global settings.
|
|
Packit |
667938 |
That keyword is primarily for SNMPv3.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The 16bit request ids are the only way to query the broken SNMP
|
|
Packit |
667938 |
implementation of SMC Barricade routers.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SnmpOptions: retries => 2, only_ip_address_matching => 0
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that AS/400 snmp seems to be broken in a way which prevents mrtg from
|
|
Packit |
667938 |
working with it unless
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SnmpOptions: lenient_source_port_matching => 1
|
|
Packit |
667938 |
|
|
Packit |
667938 |
is set.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 IconDir
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to keep the mrtg icons in someplace other than the
|
|
Packit |
667938 |
working (or imagedir) directory, use the I<IconDir> variable for
|
|
Packit |
667938 |
defining the url of the icons directory.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
IconDir: /mrtgicons/
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 LoadMIBs
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Load the MIB file(s) specified and make its OIDs available as
|
|
Packit |
667938 |
symbolic names. For better efficiancy, a cache of MIBs is maintained
|
|
Packit |
667938 |
in the WorkDir.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
LoadMIBs: /dept/net/mibs/netapp.mib,/usr/local/lib/ft100m.mib
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Language
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Switch output format to the selected Language (Check the F<translate> directory
|
|
Packit |
667938 |
to see which languages are supported at the moment. In this directory you
|
|
Packit |
667938 |
can also find instructions on how to create new translations).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Currently the following laguages are supported:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
big5
|
|
Packit |
667938 |
brazilian
|
|
Packit |
667938 |
bulgarian
|
|
Packit |
667938 |
catalan
|
|
Packit |
667938 |
chinese
|
|
Packit |
667938 |
croatian
|
|
Packit |
667938 |
czech
|
|
Packit |
667938 |
danish
|
|
Packit |
667938 |
dutch
|
|
Packit |
667938 |
eucjp
|
|
Packit |
667938 |
french
|
|
Packit |
667938 |
galician
|
|
Packit |
667938 |
gb
|
|
Packit |
667938 |
gb2312
|
|
Packit |
667938 |
german
|
|
Packit |
667938 |
greek
|
|
Packit |
667938 |
hungarian
|
|
Packit |
667938 |
icelandic
|
|
Packit |
667938 |
indonesia
|
|
Packit |
667938 |
iso2022jp
|
|
Packit |
667938 |
italian
|
|
Packit |
667938 |
korean
|
|
Packit |
667938 |
lithuanian
|
|
Packit |
667938 |
malay
|
|
Packit |
667938 |
norwegian
|
|
Packit |
667938 |
polish
|
|
Packit |
667938 |
portuguese
|
|
Packit |
667938 |
romanian
|
|
Packit |
667938 |
russian
|
|
Packit |
667938 |
russian1251
|
|
Packit |
667938 |
serbian
|
|
Packit |
667938 |
slovak
|
|
Packit |
667938 |
slovenian
|
|
Packit |
667938 |
spanish
|
|
Packit |
667938 |
swedish
|
|
Packit |
667938 |
turkish
|
|
Packit |
667938 |
ukrainian
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Language: danish
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 LogFormat
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Setting LogFormat to 'rrdtool' in your mrtg.cfg file enables rrdtool mode.
|
|
Packit |
667938 |
In rrdtool mode, mrtg relies on B<rrdtool> to do its logging. See L<mrtg-rrd>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
LogFormat: rrdtool
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 LibAdd
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are using rrdtool mode and your B<rrdtool> Perl module (RRDs.pm)
|
|
Packit |
667938 |
is not installed in a location where perl can find it on its own, you can
|
|
Packit |
667938 |
use LibAdd to supply an appropriate path.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
LibAdd: /usr/local/rrdtool/lib/perl/
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 PathAdd
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the B<rrdtool> executable can not be found in the normal C<PATH>, you can
|
|
Packit |
667938 |
use this keyword to add a suitable directory to your path.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PathAdd: /usr/local/rrdtool/bin/
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDCached
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are running RRDTool 1.4 or later with B<rrdcached>, then you can
|
|
Packit |
667938 |
configure MRTG to take advantage of this for updates, either by using the
|
|
Packit |
667938 |
RRDCACHED_ADDRESS environment variable, or by setting the RRDCached keyword
|
|
Packit |
667938 |
in the configuration file. Note that, if both are set, the configuration file
|
|
Packit |
667938 |
keyword will take precedence.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Only UNIX domain sockets are fully supported prior to RRDTool v1.5, and
|
|
Packit |
667938 |
you should note that using RRDCached mode will disable all Threshold checking
|
|
Packit |
667938 |
normally done by MRTG. Appropriate warning messages will be printed if
|
|
Packit |
667938 |
necessary.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDCached: unix:/var/tmp/rrdcached.sock
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDCached: localhost:42217
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RunAsDaemon
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The RunAsDaemon keyword enables daemon mode operation. The purpose of daemon
|
|
Packit |
667938 |
mode is that MRTG is launched once and not repeatedly (as it is with cron).
|
|
Packit |
667938 |
This behavior saves computing resourses as loading and parsing
|
|
Packit |
667938 |
of configuration files happens only once on startup, and if the configuration
|
|
Packit |
667938 |
file is modified.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Using daemon mode MRTG itself is responible for timing the measurement
|
|
Packit |
667938 |
intervals. Therfore its important to set the Interval keyword to an
|
|
Packit |
667938 |
apropiate value.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that when using daemon mode MRTG should no longer be started from cron
|
|
Packit |
667938 |
as each new process runs forever. Instead MRTG should be
|
|
Packit |
667938 |
started from the command prompt or by a system startup script.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want mrtg to run under a particular user and group (it is not
|
|
Packit |
667938 |
recomended to run MRTG as root) then you can use the B<--user=>I<user_name>
|
|
Packit |
667938 |
and B<--group=>I<group_name> options on the mrtg commandline.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
mrtg --user=mrtg_user --group=mrtg_group mrtg.cfg
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Also note that in daemon mode restarting the process is required in order to
|
|
Packit |
667938 |
activate changes in the config file.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Under UNIX, the Daemon switch causes mrtg to fork into background after
|
|
Packit |
667938 |
checking its config file. On Windows NT the MRTG process will detach from
|
|
Packit |
667938 |
the console, but because the NT/2000 shell waits for its children you have to
|
|
Packit |
667938 |
use this special start sequence when you launch the program:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
start /b perl mrtg mrtg.cfg
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You may have to add path information equal to what you add when you run mrtg
|
|
Packit |
667938 |
from the commandline.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RunAsDaemon: Yes
|
|
Packit |
667938 |
Interval: 5
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This makes MRTG run as a daemon beginning data collection every 5 minutes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are daemontools and still want to run mrtg as a daemon you can
|
|
Packit |
667938 |
additionally specify
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NoDetach: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
this will make mrtg run but without detaching it from the terminal.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the modification date on the configuration file changes during operation,
|
|
Packit |
667938 |
then MRTG will re-read the configuration on the next polling cycle. Note that
|
|
Packit |
667938 |
sub-files which are included from the main configuration do not have their
|
|
Packit |
667938 |
modification times monitored, only the top-level file is so checked.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ConversionCode
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Some devices may produce non-numeric values that would nevertheless
|
|
Packit |
667938 |
be useful to graph with MRTG if those values could be converted to numbers.
|
|
Packit |
667938 |
The ConversionCode keyword specifies the path to a file containing Perl code
|
|
Packit |
667938 |
to perform such conversions. The code in this file must consist of one or more
|
|
Packit |
667938 |
Perl subroutines. Each subroutine must accept a single string argument and
|
|
Packit |
667938 |
return a single numeric value. When RRDtool is in use, a decimal value may
|
|
Packit |
667938 |
be returned. When the name of one of these subroutines is specified in a
|
|
Packit |
667938 |
target definition (see below), MRTG calls it twice for that target, once to
|
|
Packit |
667938 |
convert the the input value being monitored and a second time to convert the
|
|
Packit |
667938 |
output value. The subroutine must return an undefined value if the conversion
|
|
Packit |
667938 |
fails. In case of failure, a warning may be posted to the MRTG log file using
|
|
Packit |
667938 |
Perl's warn function. MRTG imports the subroutines into a separate name space
|
|
Packit |
667938 |
(package MRTGConversion), so the user need not worry about pollution of MRTG's
|
|
Packit |
667938 |
global name space. MRTG automatically prepends this package declaration to
|
|
Packit |
667938 |
the user-supplied code.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example: Suppose a particular OID returns a character string whose length is
|
|
Packit |
667938 |
proportional to the value to be monitored. To convert this string to a
|
|
Packit |
667938 |
number that can be graphed by MRTG, create a file arbitrarily named
|
|
Packit |
667938 |
"MyConversions.pl" containing the following code:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# Return the length of the string argument
|
|
Packit |
667938 |
sub Length2Int {
|
|
Packit |
667938 |
my $value = shift;
|
|
Packit |
667938 |
return length( $value );
|
|
Packit |
667938 |
}
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Then include the following global keyword in the MRTG configuration file
|
|
Packit |
667938 |
(assuming that the conversion code file is saved in the mrtg/bin directory
|
|
Packit |
667938 |
along with mrtg itself):
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ConversionCode: MyConversions.pl
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This will cause MRTG to include the definition of the subroutine Length2Int
|
|
Packit |
667938 |
in its execution environment. Length2Int can then be invoked on any target
|
|
Packit |
667938 |
by appending "|Length2Int" to the target definition as follows:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: 1.3.6.1.4.1.999.1&1.3.6.1.4.1.999.1:public@mydevice|Length2Int
|
|
Packit |
667938 |
|
|
Packit |
667938 |
See "Extended Host Name Syntax" below for complete target definition syntax
|
|
Packit |
667938 |
information.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 SendToGraphite
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to send a copy of the collected data into a Graphite database in addition
|
|
Packit |
667938 |
to storing it in the RRDfile, you can provide your Graphite database name/ip and port
|
|
Packit |
667938 |
number here.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This requires the Net::Graphite perl module which is available from CPAN.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# If your Graphite receiver is running on the same host as the MRTG daemon and using the default port
|
|
Packit |
667938 |
SendToGraphite: 127.0.0.1,2003
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# If your Graphite receiver is running on 192.168.100.50 port 5000
|
|
Packit |
667938 |
SendToGraphite: 192.168.100.50,5000
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# If your Graphite receiver is running on graphite.mydomain.com port 2003
|
|
Packit |
667938 |
SendToGraphite: graphite.mydomain.com,2003
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Graphite's namespace has a number of restrictions on what characters are
|
|
Packit |
667938 |
allowed. The SendToGraphite functionality makes an attempt to convert the MRTG
|
|
Packit |
667938 |
target name and, if specified, the Legendi and Legendo values to Graphite namespace
|
|
Packit |
667938 |
friendly values. Specifically, the following conversion rules apply:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Underscores in the target_name are converted to periods which are Graphite namespace delimiters.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Comma characters are not allowed so they are removed.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item *
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The string "m2g" for MRTG to Graphite is prepended onto the Graphite namespace variable.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example MRTG target to Graphite namespace conversion:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# Our MRTG target name from mrtg.cfg is as follows
|
|
Packit |
667938 |
Target[switch_GigabitEthernet0_5]: \GigabitEthernet0/5:public1@switch:::::2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
After the conversion you will end up with these Graphite namespace values
|
|
Packit |
667938 |
|
|
Packit |
667938 |
m2g.switch.gigabitethernet0.5.in
|
|
Packit |
667938 |
m2g.switch.gigabitethernet0.5.out
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Next is a more complicated example because Legendi and Legendo are in use to denote min and max
|
|
Packit |
667938 |
voltage values that pertain to some APC UPS SNMP OIDs
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# Target, Legendi, and Legendo are specified in mrtg.cfg as follows
|
|
Packit |
667938 |
Target[apc_minmaxline]: 1.3.6.1.4.1.318.1.1.1.3.2.3.0&1.3.6.1.4.1.318.1.1.1.3.2.2.0:public@apc:
|
|
Packit |
667938 |
LegendI[apc_minmaxline]: upsAdvInputMinLineVoltage
|
|
Packit |
667938 |
LegendO[apc_minmaxline]: upsAdvInputMaxLineVoltage
|
|
Packit |
667938 |
|
|
Packit |
667938 |
After the conversion you will end up with these Graphite namespace values
|
|
Packit |
667938 |
|
|
Packit |
667938 |
m2g.apc.minmaxline.upsAdvInputMinLineVoltage
|
|
Packit |
667938 |
m2g.apc.minmaxline.upsAdvInputMaxLineVoltage
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you don't see the data showing up in Graphite, chances are there are invalid characters in
|
|
Packit |
667938 |
the namespace. To debug this, use the DEBUG=qw(log) directive at the top of the MRTG script
|
|
Packit |
667938 |
to find out what is happening with the MRTG to Graphite namespace conversion.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
DEBUG=qw(log) will generate some output similar to what appears below
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2016-10-13 06:08:39 -- --log: RRDs::update(/var/www/mrtg/switch/switch_gigabitethernet0_5.rrd, '1476356919:2738746035:2927936327')
|
|
Packit |
667938 |
2016-10-13 06:08:39 -- --log: graphite->send(m2g.switch.gigabitethernet0.5.in,2738746035,1476356919)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2016-10-13 06:08:39 -- --log: graphite->send(m2g.switch.gigabitethernet0.5.out,2927936327,1476356919)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2016-10-13 06:09:25 -- --log: RRDs::update(/var/www/mrtg/apc/apc_minmaxline.rrd, '1476356965:122:123')
|
|
Packit |
667938 |
2016-10-13 06:09:25 -- --log: graphite->send(m2g.apc.minmaxline.upsAdvInputMinLineVoltage,122,1476356965)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2016-10-13 06:09:25 -- --log: graphite->send(m2g.apc.minmaxline.upsAdvInputMaxLineVoltage,123,1476356965)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the MRTG log output looks reasonable, then take a look at Graphite's carbon-cache logs.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 PER TARGET CONFIGURATION
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Each monitoring target must be identified by a unique name. This
|
|
Packit |
667938 |
name must be appended to each parameter belonging to the same
|
|
Packit |
667938 |
target. The name will also be used for naming the
|
|
Packit |
667938 |
generated webpages, logfiles and images for this target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Target
|
|
Packit |
667938 |
|
|
Packit |
667938 |
With the I<Target> keyword you tell mrtg what it should
|
|
Packit |
667938 |
monitor. The I<Target> keyword takes arguments in a wide
|
|
Packit |
667938 |
range of formats:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Basic
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The most basic format is "port:community@router"
|
|
Packit |
667938 |
This will generate a traffic graph for the interface 'port'
|
|
Packit |
667938 |
of the host 'router' (dns name or IP address)
|
|
Packit |
667938 |
and it will use the community 'community' (snmp password)
|
|
Packit |
667938 |
for the snmp query.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: 2:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If your community contains a "@" or a " " these characters
|
|
Packit |
667938 |
must be escaped with a "\".
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[bla]: 2:stu\ pi\@d@router
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item SNMPv2c
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you have a fast router you might want to try to poll the ifHC* counters.
|
|
Packit |
667938 |
This feature gets activated by switching to SNMPv2c. Unfortunately not all
|
|
Packit |
667938 |
devices support SNMPv2c yet. If it works, this will prevent your counters
|
|
Packit |
667938 |
from wraping within the 5 minute polling interval, since we now use 64 bit
|
|
Packit |
667938 |
instead of the normal 32 bit.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: 2:public@router1:::::2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item SNMPv3
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As an alternative to SNMPv2c, SNMPv3 provides access to the ifHC* counters,
|
|
Packit |
667938 |
along with encryption. Not all devices support SNMPv3, and you will also
|
|
Packit |
667938 |
need the perl Net::SNMP library in order to use it. It is recommended that
|
|
Packit |
667938 |
cfgmaker be used to generate configurations involving SNMPv3, as it will
|
|
Packit |
667938 |
check if the Net::SNMP library is loadable, and will switch to SNMPv2c if
|
|
Packit |
667938 |
v3 is unavailable.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SNMP v3 requires additional authentication parameters, passed using the
|
|
Packit |
667938 |
SnmpOptions[] per-target keyword.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
Target[myrouter]: 2:router1:::::3
|
|
Packit |
667938 |
SnmpOptions[myrouter]: username=>'user1'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noHC
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Not all routers that support SNMPv2 or SNMPv3 provide the ifHC* counters
|
|
Packit |
667938 |
on every interface. The noHC[] per-target keyword signals that the
|
|
Packit |
667938 |
low-speed counters ifInOctets and ifOutOctets should be queried instead.
|
|
Packit |
667938 |
cfgmaker will automatically insert this tag if SNMPv2 or SNMPv3 is specified
|
|
Packit |
667938 |
but the ifHC* counters are unavailable.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
Target[myrouter]: #Bri0:router1:::::3
|
|
Packit |
667938 |
SnmpOptions[myrouter]: username=>'user1'
|
|
Packit |
667938 |
noHC[myrouter]: yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Reversing
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Sometimes you are sitting on the wrong side of the
|
|
Packit |
667938 |
link, and you would like to have mrtg report Incoming
|
|
Packit |
667938 |
traffic as Outgoing and vice versa. This can be achieved
|
|
Packit |
667938 |
by adding the '-' sign in front of the "Target"
|
|
Packit |
667938 |
description. It flips the incoming and outgoing traffic rates.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[ezci]: -1:public@ezci-ether.domain
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Explicit OIDs
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can also explicitly define which OID to query by using the
|
|
Packit |
667938 |
following syntax 'OID_1&OID_2:community@router'
|
|
Packit |
667938 |
The following example will retrieve error counts for input and output
|
|
Packit |
667938 |
on interface 1. MRTG needs to graph two variables,
|
|
Packit |
667938 |
so you need to specify two OID's such as temperature and humidity
|
|
Packit |
667938 |
or error input and error output.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: 1.3.6.1.2.1.2.2.1.14.1&1.3.6.1.2.1.2.2.1.20.1:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item MIB Variables
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MRTG knows a number of symbolic SNMP variable names.
|
|
Packit |
667938 |
See the file mibhelp.txt for a list of known names.
|
|
Packit |
667938 |
One example are the ifInErrors and ifOutErrors.
|
|
Packit |
667938 |
This means you can specify the above as:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors.1&ifOutErrors.1:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item SnmpWalk
|
|
Packit |
667938 |
|
|
Packit |
667938 |
It may be that you want to monitor an snmp object that is only reachable by
|
|
Packit |
667938 |
'walking'. You can get mrtg to walk by prepending the OID with the string
|
|
Packit |
667938 |
B<WaLK> or if you want a particular entry from the table returned by the walk
|
|
Packit |
667938 |
you can use B<WaLK>I<x> where I<x> is a number starting from 0 (!).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: WaLKstrangeOid.1&WaLKstrangeOid.2:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: WaLK3strangeOid.1&WaLK4strangeOid.2:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item SnmpGetNext
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A special case of an snmp object that is only reachable by 'walking' occurs
|
|
Packit |
667938 |
when a single snmpgetnext will return the correct value, but snmpwalk fails.
|
|
Packit |
667938 |
This may occur with snmp V2 or V3, as the snmpgetbulk method is used in these
|
|
Packit |
667938 |
versions. You can get mrtg to use getnext instead of getbulk by prepending the
|
|
Packit |
667938 |
OID with the string B<GeTNEXT>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: GeTNEXTstrangeOid&GeTNEXTstrangeOid:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Counted SNMP Walk
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In other situations, an snmpwalk is needed to count rows, but the actual data
|
|
Packit |
667938 |
is uninteresting. For example, counting the number of mac-addresses in a CAM
|
|
Packit |
667938 |
table, or the number of simultaneous dialup sessions. You can get MRTG to count
|
|
Packit |
667938 |
the number of instances by prepending the OID with the string B<CnTWaLK>. The
|
|
Packit |
667938 |
following will retrieve the number of simultaneous VOIP calls on some routers:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: CnTWaLK1.3.6.1.4.1.9.10.55.1.1.1.1.3&CnTWaLK1.3.6.1.4.1.9.10.55.1.1.1.1.3:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Interface by IP
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Sometimes SNMP interface index can change, like when new interfaces are
|
|
Packit |
667938 |
added or removed. This can cause all Target entries in your config file
|
|
Packit |
667938 |
to become offset, causing MRTG to graphs wrong instances etc.
|
|
Packit |
667938 |
MRTG supports IP address instead of ifindex in target definition. Then
|
|
Packit |
667938 |
MRTG will query snmp device and try to map IP address to the current ifindex.
|
|
Packit |
667938 |
You can use IP addresses in every type of target definition by adding
|
|
Packit |
667938 |
IP address of the numbered interface after OID and separation char '/'.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Make sure that the given IP address is used on
|
|
Packit |
667938 |
your same target router, especially when graphing two different OIDs
|
|
Packit |
667938 |
and/or interface split by '&' delimiter.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can tell cfgmaker to generate such references with the option
|
|
Packit |
667938 |
B<--ifref=ip>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: /1.2.3.4:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
Target[ezci]: -/1.2.3.4:public@ezci-ether.domain
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors/1.2.3.4&ifOutErrors/1.2.3.4:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Interface by Description
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you can not use IP addresses you might want to use
|
|
Packit |
667938 |
the interface names. This works similar to the IP address aproach
|
|
Packit |
667938 |
except that the prefix to use is a \ instead of a /
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can tell cfgmaker to generate such references with the option
|
|
Packit |
667938 |
B<--ifref=descr>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: \My-Interface2:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
Target[ezci]: -\My-Interface2:public@ezci-ether.domain
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors\My-If2&ifOutErrors\My-If3:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If your description contains a "&", a ":", a "@" or a " " you can include
|
|
Packit |
667938 |
them but you must escape with a backlash:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: \fun\:\ ney\&ddd:public@hello.router
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Interface by Name
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This is the only sensible way to reference the interfaces of your switches.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can tell cfgmaker to generate such references with the option
|
|
Packit |
667938 |
B<--ifref=name>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: #2/11:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
Target[ezci]: -#2/11:public@ezci-ether.domain
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors#3/7&ifOutErrors#3/7:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If your description contains a "&", a ":", a "@" or a " " you can include
|
|
Packit |
667938 |
them but you must escape with a backlash:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: #\:\ fun:public@hello.router
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that the # sign will be interpreted as a comment character if
|
|
Packit |
667938 |
it is the first non white-space character on the line.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Interface by Ethernet Address
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When the SNMP interface index changes, you can key that interface by its
|
|
Packit |
667938 |
'Physical Address', sometimes called a 'hard address', which is the SNMP
|
|
Packit |
667938 |
variable 'ifPhysAddress'. Internally, MRTG matches the Physical Address from
|
|
Packit |
667938 |
the *.cfg file to its current index, and then uses that index for the rest of
|
|
Packit |
667938 |
the session.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can use the Physical Address in every type of target definition by adding
|
|
Packit |
667938 |
the Physical Address after the OID and the separation char '!' (analogous to the IP
|
|
Packit |
667938 |
address option). The Physical address is specified as '-' delimited
|
|
Packit |
667938 |
octets, such as "0a-0-f1-5-23-18" (omit the double quotes). Note that some
|
|
Packit |
667938 |
routers use the same Hardware Ethernet Address for all of their Interfaces which
|
|
Packit |
667938 |
prevents unique interface identification. Mrtg will notice such problems and alert you.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can tell cfgmaker to generate configuration files with hardware ethernet address references
|
|
Packit |
667938 |
by using the option B<--ifref=eth>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: !0a-0b-0c-0d:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
Target[ezci]: -!0-f-bb-05-71-22:public@ezci-ether.domain
|
|
Packit |
667938 |
Target[myrouter]: 1.3.6.1.2.1.2.2.1.14!0a-00-10-23-44-51& *BREAK*
|
|
Packit |
667938 |
1.3.6.1.2.1.2.2.1.14!0a-00-10-23-44-51:public@myrouter
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors!0a-00-10-23-44-51& *BREAK*
|
|
Packit |
667938 |
ifOutErrors!0a-00-10-23-44-51:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Join the lines at *BREAK* ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Interface by Type
|
|
Packit |
667938 |
|
|
Packit |
667938 |
It seems that there are devices that try to defy all monitoring efforts: the interesting interfaces have
|
|
Packit |
667938 |
neither ifName nor a constant ifDescr not to mention a persistent ifIndex. The only way to get a constant
|
|
Packit |
667938 |
mapping is by looking at the interface type, because the interface you are interested in is unique in the
|
|
Packit |
667938 |
device you are looking at ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can tell cfgmaker to generate such references with the option
|
|
Packit |
667938 |
B<--ifref=type>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: %13:public@wellfleet-fddi.domain
|
|
Packit |
667938 |
Target[ezci]: -%13:public@ezci-ether.domain
|
|
Packit |
667938 |
Target[myrouter]: ifInErrors%13&ifOutErrors%14:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Extended positioning of ifIndex
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
There are OIDs that contain the interface index at some inner position within
|
|
Packit |
667938 |
the OID. To use the above mentioned Interface by IP/Description/Name/Type methods
|
|
Packit |
667938 |
in the target definition the keyword 'IndexPOS' can be used to indicate the
|
|
Packit |
667938 |
position of ifIndex. If 'IndexPOS' is not used the ifIndex will be appended at the
|
|
Packit |
667938 |
end of the OID.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: OID.IndexPOS.1/1.2.3.4&OID.IndexPOS.1/1.2.3.4:public@myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Replace OID by your numeric OID.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Extended Host Name Syntax
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In all places where ``community@router'' is accepted, you can add
|
|
Packit |
667938 |
additional parameters for the SNMP communication using
|
|
Packit |
667938 |
colon-separated suffixes. You can also append a pipe symbol ( | ) and
|
|
Packit |
667938 |
the name of a numeric conversion subroutine as described under the global
|
|
Packit |
667938 |
keyword "ConversionCode" above. The full syntax is as follows:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
community@router[:[port][:[timeout][:[retries][:[backoff][:[version]]]]][|name]
|
|
Packit |
667938 |
|
|
Packit |
667938 |
where the meaning of each parameter is as follows:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item port
|
|
Packit |
667938 |
|
|
Packit |
667938 |
the UDP port under which to contact the SNMP agent (default: 161)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The complete syntax of the port parameter is
|
|
Packit |
667938 |
|
|
Packit |
667938 |
remote_port[!local_address[!local_port]]
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Some machines have additional security features that only allow SNMP queries
|
|
Packit |
667938 |
to come from certain IP addresses. If the host doing the query has multiple
|
|
Packit |
667938 |
interface, it may be necessary to specify the interface the query should
|
|
Packit |
667938 |
come from.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The port parameter allows the specification of the port of the machine being
|
|
Packit |
667938 |
queried. In addition, the IP address (or hostname) and port of the machine
|
|
Packit |
667938 |
doing the query may be specified.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
somehost
|
|
Packit |
667938 |
somehost:161
|
|
Packit |
667938 |
somehost:161!192.168.2.4!4000 use 192.168.2.4 and port 4000 as source
|
|
Packit |
667938 |
somehost:!192.168.2.4 use 192.168.2.4 as source
|
|
Packit |
667938 |
somehost:!!4000 use port 4000 as source
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item timeout
|
|
Packit |
667938 |
|
|
Packit |
667938 |
initial timeout for SNMP queries, in seconds (default: 2.0)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item retries
|
|
Packit |
667938 |
|
|
Packit |
667938 |
number of times a timed-out request will be retried (default: 5)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item backoff
|
|
Packit |
667938 |
|
|
Packit |
667938 |
factor by which the timeout is multiplied on every retry (default: 1.0).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item version
|
|
Packit |
667938 |
|
|
Packit |
667938 |
for SNMP version. If you have a fast router you might want to put
|
|
Packit |
667938 |
a '2' here. For authenticated or encrypted SNMP, you can try to put a
|
|
Packit |
667938 |
'3' here. This will make mrtg try to poll the 64 bit counters and thus
|
|
Packit |
667938 |
prevent excessive counter wrapping. Not all routers support this though.
|
|
Packit |
667938 |
SNMP v3 requires additional setup, see SnmpOptions[] for full details.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
3:public@router1:::::2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item name
|
|
Packit |
667938 |
|
|
Packit |
667938 |
the name of the subroutine that MRTG will call to convert the input and output
|
|
Packit |
667938 |
values to integers. See the complete example under the global keyword
|
|
Packit |
667938 |
"ConversionCode" above.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
1.3.6.1.4.1.999.1&1.3.6.1.4.1.999.2:public@mydevice:161::::2|Length2Int
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This would retrieve values from the OID 1.3.6.1.4.1.999.1 for input and .2
|
|
Packit |
667938 |
for output on mydevice using UDP port 161 and SNMP version 2, and would
|
|
Packit |
667938 |
execute the user-defined numeric conversion subroutine Length2Int to convert
|
|
Packit |
667938 |
those values to integers.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A value that equals the default value can be omitted. Trailing colons
|
|
Packit |
667938 |
can be omitted, too. The pipe symbol followed by the name parameter, if
|
|
Packit |
667938 |
present, must come at the end. There must be no spaces around the colons or
|
|
Packit |
667938 |
pipe symbol.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[ezci]: 1:public@ezci-ether.domain:9161::4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This would refer to the input/output octet counters for the interface
|
|
Packit |
667938 |
with I<ifIndex 1> on I<ezci-ether.domain>, as known
|
|
Packit |
667938 |
by the SNMP agent listening on UDP port 9161. The standard initial
|
|
Packit |
667938 |
timeout (2.0 seconds) is used, but the number of retries is set to
|
|
Packit |
667938 |
four. The backoff value is the default.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Numeric IPv6 addresses
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If IPv6 is enabled you may also specify a target using its IPv6 address. To
|
|
Packit |
667938 |
avoid ambiguity with the port number, numeric IPv6 addresses must be placed
|
|
Packit |
667938 |
in square brackets.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[IPv6test]: 2:public@[2001:760:4::]:6161::4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item External Monitoring Scripts
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to monitor something which does not provide
|
|
Packit |
667938 |
data via snmp you can use some external program to do
|
|
Packit |
667938 |
the data gathering.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The external command must return 4 lines of output:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Line 1
|
|
Packit |
667938 |
|
|
Packit |
667938 |
current state of the first variable, normally 'incoming bytes count'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Line 2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
current state of the second variable, normally 'outgoing bytes count'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Line 3
|
|
Packit |
667938 |
|
|
Packit |
667938 |
string (in any human readable format), telling the uptime of the target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Line 4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
string, telling the name of the target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Depending on the type of data your script returns you
|
|
Packit |
667938 |
might want to use the 'gauge' or 'absolute' arguments
|
|
Packit |
667938 |
for the I<Options> keyword.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: `/usr/local/bin/df2mrtg /dev/dsk/c0t2d0s0`
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note the use of the backticks (`), not apostrophes (')
|
|
Packit |
667938 |
around the command.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to use a backtick in the command name this can be done
|
|
Packit |
667938 |
but you must escape it with a backslash ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If your script does not have any data to return but does not want mrtg to
|
|
Packit |
667938 |
complain about invalid data, it can return 'UNKNOWN' instead of a number.
|
|
Packit |
667938 |
Note though that only rrdtool is realy equipped to handle unknown data well.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Multi Target Syntax
|
|
Packit |
667938 |
|
|
Packit |
667938 |
You can also combine several target definitions in a mathematical expression.
|
|
Packit |
667938 |
Any syntactically correct expression that the Perl interpreter can evaluate
|
|
Packit |
667938 |
to will work. An expression could be used, for example, to aggregate both B
|
|
Packit |
667938 |
channels in an ISDN connection or to calculate the percentage hard disk
|
|
Packit |
667938 |
utilization of a server from the absolute used space and total capacity.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: 2:public@wellfleetA + 1:public@wellfleetA
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[myrouter]: .1.3.6.1.4.1.999.1&.1.3.6.1.4.1.999.2:public@mydevice /
|
|
Packit |
667938 |
.1.3.6.1.4.1.999.3&.1.3.6.1.4.1.999.4:public@mydevice * 100
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that whitespace must surround each target definition in the expression.
|
|
Packit |
667938 |
Target definitions themselves must not contain whitespace, except in
|
|
Packit |
667938 |
interface descriptions and interface names, where each whitespace character
|
|
Packit |
667938 |
is escaped by a backslash.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MRTG automatically rounds the result of the expression to an integer unless
|
|
Packit |
667938 |
RRDTool logging is in use and the gauge option is in effect for the target.
|
|
Packit |
667938 |
Internally MRTG uses Perl's Math::BigFloat package to calculate the result
|
|
Packit |
667938 |
of the expression with 40 digits of precision. Even in extreme cases, where,
|
|
Packit |
667938 |
for example, you take the difference of two 64-bit integers, the result of
|
|
Packit |
667938 |
the expression should be accurate.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item SNMP Request Optimization
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MRTG is designed to economize on its SNMP requests. Where a target
|
|
Packit |
667938 |
definition appears more than once in the configuration file, MRTG requests
|
|
Packit |
667938 |
the data from the device only once per round of data collection and uses
|
|
Packit |
667938 |
the collected data for each instance of a particular target. Recognition of
|
|
Packit |
667938 |
two target definitions as being identical is based on a simple string match
|
|
Packit |
667938 |
rather than any kind of deeper semantic analysis.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[Targ1]: 1:public@CiscoA
|
|
Packit |
667938 |
Target[Targ2]: 2:public@CiscoA
|
|
Packit |
667938 |
Target[Targ3]: 1:public@CiscoA + 2:public@CiscoA
|
|
Packit |
667938 |
Target[Targ4]: 1:public@CISCOA
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This results in a total of three SNMP requests. Data for 1:public@CiscoA
|
|
Packit |
667938 |
and 2:public@CiscoA are requested only once each, and used for Targ1, Targ2,
|
|
Packit |
667938 |
and Targ3. Targ4 causes another SNMP request for 1:public@CISCOA, which is not
|
|
Packit |
667938 |
recognized as being identical to 1:public@CiscoA.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 MaxBytes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The maximum value either of the two variables monitored
|
|
Packit |
667938 |
are allowed to reach. For monitoring router traffic
|
|
Packit |
667938 |
this is normally the bytes per second this
|
|
Packit |
667938 |
interface port can carry.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If a number higher than I<MaxBytes> is returned, it is ignored.
|
|
Packit |
667938 |
Also read the section on I<AbsMax> for further info.
|
|
Packit |
667938 |
The I<MaxBytes> value is also used in calculating the Y range
|
|
Packit |
667938 |
for unscaled graphs (see the section on I<Unscaled>).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Since most links are rated in bits per second, you need to divide their
|
|
Packit |
667938 |
maximum bandwidth (in bits) by eight (8) in order to get bytes per second.
|
|
Packit |
667938 |
This is very important to make your unscaled graphs display realistic
|
|
Packit |
667938 |
information. T1 = 193000, 56K = 7000, 10 MB Ethernet = 1250000, 100 MB
|
|
Packit |
667938 |
Ethernet = 12500000. The I<MaxBytes> value will be used by mrtg to decide
|
|
Packit |
667938 |
whether it got a valid response from the router.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you need two different MaxBytes values for the two monitored
|
|
Packit |
667938 |
variables, you can use MaxBytes1 and MaxBytes2 instead of MaxBytes.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MaxBytes[myrouter]: 1250000
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Title
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title for the HTML page which gets generated for the graph.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title[myrouter]: Traffic Analysis for Our Nice Company
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 OPTIONAL PER TARGET KEYWORDS
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 PageTop
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Things to add to the top of the generated HTML page. Note
|
|
Packit |
667938 |
that you can have several lines of text as long as the
|
|
Packit |
667938 |
first column is empty.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that the continuation lines will all end up on the same
|
|
Packit |
667938 |
line in the html page. If you want linebreaks in the generated
|
|
Packit |
667938 |
html use the '\n' sequence.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PageTop[myrouter]: Traffic Analysis for ETZ C95.1
|
|
Packit |
667938 |
Our Campus Backbone runs over an FDDI line\n
|
|
Packit |
667938 |
with a maximum transfer rate of 12.5 megabytes per
|
|
Packit |
667938 |
Second.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RouterUptime
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In cases where you calculate the used bandwidth from
|
|
Packit |
667938 |
several interfaces you normally don't get the router uptime
|
|
Packit |
667938 |
and router name displayed on the web page.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If these interfaces are on the same router and the uptime and
|
|
Packit |
667938 |
name should be displayed you have to specify
|
|
Packit |
667938 |
its community and address again with the I<RouterUptime> keyword.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to use a special OID for querying the router uptime,
|
|
Packit |
667938 |
use prepend the oid.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[kacisco.comp.edu]: 1:public@194.64.66.250 + 2:public@194.64.66.250
|
|
Packit |
667938 |
RouterUptime[kacisco.comp.edu]: public@194.64.66.250
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RouterUptime[kacisco.comp.edu]: hrSystemUptime.0:public@194.64.66.250
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RouterName
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the default name of the router is incorrect/uninformative,
|
|
Packit |
667938 |
you can use RouterName to specify a different OID on either the
|
|
Packit |
667938 |
same or a different host.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A practical example: sysName on BayTech DS72 units always display
|
|
Packit |
667938 |
"ds72", no matter what you set the Unit ID to be. Instead, the
|
|
Packit |
667938 |
Unit ID is stored at 1.3.6.1.4.1.4779.1.1.3.0, so we can have
|
|
Packit |
667938 |
MRTG display this instead of sysName.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RouterName[kacisco.comp.edu]: 1.3.6.1.4.1.4779.1.1.3.0
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A different OID on a different host can also be specified:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RouterName[kacisco.comp.edu]: 1.3.6.1.4.1.4779.1.1.3.0:public@194.64.66.251
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 MaxBytes1
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Same as MaxBytes, for variable 1.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 MaxBytes2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Same as MaxBytes, for variable 2.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 IPv4Only
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Many IPv6 routers do not currently support SNMP over IPv6 and must
|
|
Packit |
667938 |
be monitored using IPv4. The IPv4Only option forces mrtg to use IPv4
|
|
Packit |
667938 |
when communicating with the target, even if IPv6 is enabled. This is
|
|
Packit |
667938 |
useful if the target is a hostname with both IPv4 and IPv6 addresses;
|
|
Packit |
667938 |
without the IPv4Only keyword, monitoring such a router will not work
|
|
Packit |
667938 |
if IPv6 is enabled.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If set to no (the default), mrtg will use IPv6 unless the target has
|
|
Packit |
667938 |
no IPv6 addresses, in which case it will use IPv4. If set to yes, mrtg
|
|
Packit |
667938 |
will only use IPv4.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that if this option is set to yes and the target does not have an
|
|
Packit |
667938 |
IPv4 address, communication with the target will fail.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This option has no effect if IPv6 is not enabled.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Target[v4onlyrouter_1]: 1:public@v4onlyrouter
|
|
Packit |
667938 |
IPv4Only[v4onlyrouter_1]: Yes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 SnmpOptions (V3)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SNMPv3 requires a fairly rich set of options. This per-target keyword
|
|
Packit |
667938 |
allows access to the User Security Model of SNMPv3. Options are listed
|
|
Packit |
667938 |
in the same syntax as a perl hash.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head3 Security Modes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SNMPv3 has three security modes, defined on the device being polled.
|
|
Packit |
667938 |
For example, on Cisco routers the security mode is defined by the
|
|
Packit |
667938 |
snmp-server group global configuration command.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item NoAuthNoPriv
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Neither Authentication nor Privacy is defined. Only the Username
|
|
Packit |
667938 |
option is specified for this mode.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SnmpOptions[myrouter]: username=>'user1'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item AuthNoPriv
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Uses a Username and a password. The password can be hashed using the
|
|
Packit |
667938 |
snmpkey application, or passed in plain text along with the ContextEngineID
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SnmpOptions[myrouter]: username=>'user1',authpassword=>'example',
|
|
Packit |
667938 |
contextengineid=>'80000001110000004000000'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Priv
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Both Authentication and Privacy is defined. The default privacy protocol
|
|
Packit |
667938 |
is des.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
SnmpOptions[myrouter]: authkey=>'0x1e93ab5a396e2af234c8920e61cfe2028072c0e2',
|
|
Packit |
667938 |
authprotocol=>'sha',privprotocol=>'des',username=>'user1',
|
|
Packit |
667938 |
privkey=>'0x498d74940c5872ed387201d74b9b25e2'
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head3 snmp options
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The following option keywords are recognized:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item username
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The user associated with the User Security Model
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item contextname
|
|
Packit |
667938 |
|
|
Packit |
667938 |
An SNMP agent can define multiple contexts. This keyword allows them to
|
|
Packit |
667938 |
be polled.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item contextengineid
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A unique 24-byte string identifying the snmp-agent.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item authpassword
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The plaintext password for a user in either AuthNoPriv or Priv mode.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item authkey
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A md5 or sha hash of the plain-text password, along with the engineid.
|
|
Packit |
667938 |
Use the snmpkey commandline program to generate this hash, or use
|
|
Packit |
667938 |
Net::SNMP::Security::USM in a script.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item authprotocol {sha|md5}
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The hashing algorithm defined on the SNMP client. Defaults to md5.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item privpassword
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A plaintext pre-shared key for encrypting snmp packets in Priv mode.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item privkey
|
|
Packit |
667938 |
|
|
Packit |
667938 |
A hash of the plain-text pre-shared key, along with the engineid.
|
|
Packit |
667938 |
Use the snmpkey commandline program to generate this hash, or use
|
|
Packit |
667938 |
Net::SNMP::Security::USM in a script.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item privprotocol {des|3desede|aescfb128|aescfb192|aescfb256}
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Specifies the encryption method defined on the snmp agent. The default
|
|
Packit |
667938 |
is des.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 PageFoot
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Things to add to the bottom of the generated HTML page. Note
|
|
Packit |
667938 |
that you can have several lines of text as long as the
|
|
Packit |
667938 |
first column is empty.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that the continuation lines will all end up on the same
|
|
Packit |
667938 |
line in the html page. If you want linebreaks in the generated
|
|
Packit |
667938 |
html use the '\n' sequence.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The material will be added just before the E<lt>/BODYE<gt> tag:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PageFoot[myrouter]: Contact Peter
|
|
Packit |
667938 |
if you have questions regarding this page
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 AddHead
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Use this tag like the I<PageTop> header, but its contents
|
|
Packit |
667938 |
will be added between E<lt>/TITLEE<gt> and E<lt>/HEADE<gt>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
AddHead[myrouter]: <link rev="made" href="mailto:mrtg@blabla.edu">
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 BodyTag
|
|
Packit |
667938 |
|
|
Packit |
667938 |
BodyTag lets you supply your very own E<lt>body ...E<gt> tag for the
|
|
Packit |
667938 |
generated webpages.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
BodyTag[myrouter]:
|
|
Packit |
667938 |
BACKGROUND="/stats/images/bg.neo2.gif">
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 AbsMax
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are monitoring a link which can handle more traffic than the
|
|
Packit |
667938 |
I<MaxBytes> value. Eg, a line which uses compression or some frame relay
|
|
Packit |
667938 |
link, you can use the I<AbsMax> keyword to give the absolute maximum value
|
|
Packit |
667938 |
ever to be reached. We need to know this in order to sort out unrealistic
|
|
Packit |
667938 |
values returned by the routers. If you do not set I<AbsMax>, rateup will
|
|
Packit |
667938 |
ignore values higher than I<MaxBytes>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
AbsMax[myrouter]: 2500000
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Unscaled
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default each graph is scaled vertically to make the actual data visible
|
|
Packit |
667938 |
even when it is much lower than I<MaxBytes>. With the I<Unscaled> variable
|
|
Packit |
667938 |
you can suppress this. It's argument is a string, containing one letter for
|
|
Packit |
667938 |
each graph you don't want to be scaled: d=day w=week m=month y=year. There
|
|
Packit |
667938 |
is also a special case to unset the variable completely: n=none. This could
|
|
Packit |
667938 |
be useful in the event you need to override a global configuration. In the
|
|
Packit |
667938 |
example scaling for the yearly and the monthly graph are suppressed.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Unscaled[myrouter]: ym
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 WithPeak
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default the graphs only contain the average
|
|
Packit |
667938 |
values of the monitored variables - normally the
|
|
Packit |
667938 |
transfer rates for incoming and outgoing traffic.
|
|
Packit |
667938 |
The following option instructs mrtg to display the peak
|
|
Packit |
667938 |
5 minute values in the [w]eekly, [m]onthly and
|
|
Packit |
667938 |
[y]early graph. In the example we define the monthly
|
|
Packit |
667938 |
and the yearly graph to contain peak as well as average
|
|
Packit |
667938 |
values.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Examples:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WithPeak[myrouter]: ym
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Suppress
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default mrtg produces 4 graphs. With this option
|
|
Packit |
667938 |
you can suppress the generation of selected graphs.
|
|
Packit |
667938 |
The option value syntax is analogous to the above two options.
|
|
Packit |
667938 |
In this example we suppress the yearly graph
|
|
Packit |
667938 |
as it is quite empty in the beginning.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Suppress[myrouter]: y
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Extension
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default, mrtg creates .html files. Use this option to tell mrtg to
|
|
Packit |
667938 |
use a different extension. For example you could set the extension to
|
|
Packit |
667938 |
php3, then you will be able to enclose PHP tags into the output (useful
|
|
Packit |
667938 |
for getting a router name out of a database).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Extension[myrouter]: phtml
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Directory
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default, mrtg puts all the files that it generates for each
|
|
Packit |
667938 |
target (the GIFs, the HTML page, the log file, etc.) in I<WorkDir>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the I<Directory> option is specified, the files are instead put
|
|
Packit |
667938 |
into a directory under I<WorkDir> or Log-, Image- and HtmlDir).
|
|
Packit |
667938 |
(For example the I<Directory>
|
|
Packit |
667938 |
option below would cause all the files for a target myrouter
|
|
Packit |
667938 |
to be put into directory /usr/tardis/pub/www/stats/mrtg/myrouter/ .)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The directory must already exist; mrtg will not create it.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
Directory[myrouter]: myrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE: the Directory option must always be 'relative' or bad things will happen.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Clonedirectory
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If the I<Directory> option is specified, the I<Clonedirectory> option will copy
|
|
Packit |
667938 |
all the contents of I<Directory> to the I<Clonedirectory>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
Directory[myrouter]: myrouter
|
|
Packit |
667938 |
Clonedirectory[myrouter]: myclonedirectory
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Optionally the target name can be changed in the cloning process.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
Directory[myrouter]: myrouter
|
|
Packit |
667938 |
Clonedirectory[myrouter]: myclonedirectory mynewtarget
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE1: The clone directory must already exist; mrtg will not create it.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE2: The Clonedirectory option must also always be 'relative' or bad things will happen.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NOTE3: This requires the File::Copy module
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 XSize and YSize
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default mrtgs graphs are 100 by 400 pixels wide (plus
|
|
Packit |
667938 |
some more for the labels. In the example we get almost
|
|
Packit |
667938 |
square graphs ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note: XSize must be between 20 and 600; YSize must be larger than 20
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
XSize[myrouter]: 300
|
|
Packit |
667938 |
YSize[myrouter]: 300
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 XZoom and YZoom
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want your graphs to have larger pixels, you can
|
|
Packit |
667938 |
"Zoom" them.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
XZoom[myrouter]: 2.0
|
|
Packit |
667938 |
YZoom[myrouter]: 2.0
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 XScale and YScale
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want your graphs to be actually scaled use I<XScale>
|
|
Packit |
667938 |
and I<YScale>. (Beware: while this works, the results look ugly
|
|
Packit |
667938 |
(to be frank) so if someone wants to fix this: patches are welcome.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
XScale[myrouter]: 1.5
|
|
Packit |
667938 |
YScale[myrouter]: 1.5
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 YTics and YTicsFactor
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to show more than 4 lines per graph, use YTics.
|
|
Packit |
667938 |
If you want to scale the value used for the YLegend of these
|
|
Packit |
667938 |
tics, use YTicsFactor.
|
|
Packit |
667938 |
The default value for YTics is 4 and the default value for
|
|
Packit |
667938 |
YTicsFactor is 1.0 .
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Suppose you get values ranging from 0 to 700.
|
|
Packit |
667938 |
You want to plot 7 lines and want to show
|
|
Packit |
667938 |
0, 1, 2, 3, 4, 5, 6, 7 instead of 0, 100, 200,
|
|
Packit |
667938 |
300, 400, 500, 600, 700. You should write then:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
YTics[myrouter]: 7
|
|
Packit |
667938 |
YTicsFactor[myrouter]: 0.01
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Factor
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you want to multiply all numbers shown below the graph with a constant factor, use
|
|
Packit |
667938 |
this directive to define it ..
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Factor[as400]: 4096
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Step
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Change the default step from 5 * 60 seconds to
|
|
Packit |
667938 |
something else (I have not tested this much ...)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Step[myrouter]: 60
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 PNGTitle
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, this will print the given title in the
|
|
Packit |
667938 |
graph it generates.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PNGTitle[myrouter]: WAN Link UK-US
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Options
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The I<Options> Keyword allows you to set some boolean
|
|
Packit |
667938 |
switches:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item growright
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The graph grows to the left by default.
|
|
Packit |
667938 |
This option flips the direction of growth
|
|
Packit |
667938 |
causing the current time to be at the right edge
|
|
Packit |
667938 |
of the graph and the history values to the left of it.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item bits
|
|
Packit |
667938 |
|
|
Packit |
667938 |
All the monitored variable values are multiplied by 8
|
|
Packit |
667938 |
(i.e. shown in bits instead of bytes) ... looks much more impressive :-)
|
|
Packit |
667938 |
It also affects the 'factory default' labeling and units
|
|
Packit |
667938 |
for the given target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item perminute
|
|
Packit |
667938 |
|
|
Packit |
667938 |
All the monitored variable values are multiplied by 60
|
|
Packit |
667938 |
(i.e. shown in units per minute instead of units per second) in case
|
|
Packit |
667938 |
of small values more accurate graphs are displayed.
|
|
Packit |
667938 |
It also affects the 'factory default' labeling and units
|
|
Packit |
667938 |
for the given target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item perhour
|
|
Packit |
667938 |
|
|
Packit |
667938 |
All the monitored variable values are multiplied by 3600
|
|
Packit |
667938 |
(i.e. shown in units per hour instead of units per second) in case
|
|
Packit |
667938 |
of small values more accurate graphs are displayed.
|
|
Packit |
667938 |
It also affects the 'factory default' labeling and units
|
|
Packit |
667938 |
for the given target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noinfo
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Suppress the information about uptime and
|
|
Packit |
667938 |
device name in the generated webpage.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item nopercent
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Don't print usage percentages.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item transparent
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Make the background of the generated gifs transparent.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item integer
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Print summary lines below graph as integers without commas.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item dorelpercent
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The relative percentage of IN-traffic to OUT-traffic is calculated
|
|
Packit |
667938 |
and displayed in the graph as an additional line.
|
|
Packit |
667938 |
Note: Only a fixed scale is available (from 0 to 100%). Therefore
|
|
Packit |
667938 |
if IN-traffic is greater than OUT-traffic then 100% is displayed.
|
|
Packit |
667938 |
If you suspect that your IN-traffic is not always less than or equal
|
|
Packit |
667938 |
to your OUT-traffic you are urged to not use this options.
|
|
Packit |
667938 |
Note: If you use this option in combination with the I<Colours>
|
|
Packit |
667938 |
options, a fifth colour-name colour-value pair is required there.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item avgpeak
|
|
Packit |
667938 |
|
|
Packit |
667938 |
There are some ISPs who use the average Peak values to bill their customers.
|
|
Packit |
667938 |
Using this option MRTG displays these values for each graph. The value is
|
|
Packit |
667938 |
built by averaging the max 5 minute traffic average for each 'step' shown in
|
|
Packit |
667938 |
the graph. For the Weekly graph this means that it builds the average of all
|
|
Packit |
667938 |
2 hour intervals 5 minute peak values. (Confused? Thought so!)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item gauge
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Treat the values gathered from target as 'current status' measurements
|
|
Packit |
667938 |
and not as ever incrementing counters.
|
|
Packit |
667938 |
This would be useful to monitor things like disk space,
|
|
Packit |
667938 |
processor load, temperature, and the like ...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
In the absence of 'gauge' or 'absolute' options,
|
|
Packit |
667938 |
MRTG treats variables as a counters and calculates
|
|
Packit |
667938 |
the difference between the current and the previous value
|
|
Packit |
667938 |
and divides that by the elapsed time between
|
|
Packit |
667938 |
the last two readings to get the value to be plotted.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item absolute
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This is for counter type data sources which reset their value when they are
|
|
Packit |
667938 |
read. This means that rateup does not have to build the difference between
|
|
Packit |
667938 |
the current and the last value read from the data source. The value obtained is
|
|
Packit |
667938 |
still divided by the elapsed time between the current and the last reading, which makes
|
|
Packit |
667938 |
it different from the 'gauge' option. Useful for external data gatherers.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item derive
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are using rrdtool as logger/grapher you can use a third type of data
|
|
Packit |
667938 |
source. Derive is like counter, except that it is not required to go UP all
|
|
Packit |
667938 |
the time. It is useful for situations where the change of some value should be
|
|
Packit |
667938 |
graphed.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item unknaszero
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Log unknown data as zero instead of the default behaviour of repeating the
|
|
Packit |
667938 |
last value seen. Be careful with this, often a flat line in the graph is
|
|
Packit |
667938 |
much more obvious than a line at 0.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item withzeroes
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Normally we ignore all values which are zero when calculating the average
|
|
Packit |
667938 |
transfer rate on a line. If this is not desirable use this option.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noborder
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you are using rateup to log data, MRTG will create the graph images.
|
|
Packit |
667938 |
Normally these images have a shaded border around them. If you do not want the
|
|
Packit |
667938 |
border to be drawn, enable this option. This option has no effect if you are
|
|
Packit |
667938 |
not using rateup.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noarrow
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As with the option above, this effects rateup graph generation only. Normally
|
|
Packit |
667938 |
rateup will generate graphs with a small arrow showing the direction of the
|
|
Packit |
667938 |
data. If you do not want this arrow to be drawn, enable this option. This
|
|
Packit |
667938 |
option has no effect if you are not using rateup.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noi
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, you can use this option to stop rateup
|
|
Packit |
667938 |
drawing a graph for the 'I' or first variable. This also removes entries for
|
|
Packit |
667938 |
this variable in the HTML page MRTG generates, and will remove the peaks for
|
|
Packit |
667938 |
this variable if they are enabled. This allows you to hide this data, or can
|
|
Packit |
667938 |
be very useful if you are only graphing one line of data rather than two.
|
|
Packit |
667938 |
This option is not destructive - any data received for the the variable
|
|
Packit |
667938 |
continued to be logged, it just isn't shown.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item noo
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Same as above, except relating to the 'O' or second variable.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item nobanner
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, this option disables MRTG adding the
|
|
Packit |
667938 |
MRTG banner to the HTML pages it generates.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item nolegend
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, this option will stop MRTG from creating
|
|
Packit |
667938 |
a legend at the bottom of the HTML pages it generates.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item printrouter
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, this option will print the router
|
|
Packit |
667938 |
name in the graph it generates. This option is overridden by the value of
|
|
Packit |
667938 |
PNGTitle if one is given
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item pngdate
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rateup for graph generation, this option will print a
|
|
Packit |
667938 |
timestamp in the graph it generates, including a timezone if one is specified
|
|
Packit |
667938 |
by the 'Timezone' parameter. This is aequivalent to setting TimeStrPost[x]: RU
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item logscale
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The B<logscale> option causes rateup to display the data with the Y axis
|
|
Packit |
667938 |
scaled logarithmically. Doing so allows the normal traffic to occupy
|
|
Packit |
667938 |
the majority of the vertical range, while still showing any spikes at
|
|
Packit |
667938 |
their full height.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
B<logscale> displays all the available data and will always produce
|
|
Packit |
667938 |
well-behaved graphs. People often consider a logarithmically scaled graph
|
|
Packit |
667938 |
counterintuitive, however, and thus hard to interpret.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item expscale
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The B<expscale> option causes rateup to display the data with the Y axis
|
|
Packit |
667938 |
scaled exponentially. Doing so emphasizes small changes at the top of
|
|
Packit |
667938 |
the scale; this can be useful when graphing values that fluctuate by
|
|
Packit |
667938 |
a small amount near the top of the scale, such as line voltage.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
B<expscale> is essentially the inverse of B<logscale>.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item secondmean
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The B<secondmean> option sets the maximum value on the graph to the mean
|
|
Packit |
667938 |
of the data greater than the mean of all data. This produces a graph
|
|
Packit |
667938 |
that focuses more on the typical data, while clipping large peaks.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Using B<secondmean> will give a more intutive linearly
|
|
Packit |
667938 |
scaled graph, but can result in a uselessly high or low scale in some
|
|
Packit |
667938 |
rare situations (specifically, when the data includes a large portion
|
|
Packit |
667938 |
of values far from the actual mean)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If a target includes both B<logscale> and B<secondmean> in the options, the
|
|
Packit |
667938 |
B<secondmean> takes precedence.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Options[myrouter]: growright, bits
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 kilo
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Use this option to change the multiplier value for building
|
|
Packit |
667938 |
prefixes. Defaultvalue is 1000. This tag is for the special
|
|
Packit |
667938 |
case that 1kB = 1024B, 1MB = 1024kB and so far.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
kilo[myrouter]: 1024
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 kMG
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Change the default multiplier prefixes (,k,M,G,T,P). In the tag
|
|
Packit |
667938 |
I<ShortLegend> define only the basic units.
|
|
Packit |
667938 |
Format: Comma separated list of prefixed. Two consecutive commas
|
|
Packit |
667938 |
or a comma at start or end of the line gives no prefix on this item.
|
|
Packit |
667938 |
If you do not want prefixes, just put two consecutive commas.
|
|
Packit |
667938 |
If you want to skip a magnitude select '-' as value.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example: velocity in nm/s (nanometers per second) displayed in nm/h.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ShortLegend[myrouter]: m/h
|
|
Packit |
667938 |
kMG[myrouter]: n,u,m,,k,M,G,T,P
|
|
Packit |
667938 |
options[myrouter]: perhour
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Colours
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The I<Colours> tag allows you to override the default colour
|
|
Packit |
667938 |
scheme. Note: All 4 of the required colours must be
|
|
Packit |
667938 |
specified here. The colour name ('Colourx' below) is the
|
|
Packit |
667938 |
legend name displayed, while the RGB value is the real
|
|
Packit |
667938 |
colour used for the display, both on the graph and in the
|
|
Packit |
667938 |
html doc.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Format is: Col1#RRGGBB,Col2#RRGGBB,Col3#RRGGBB,Col4#RRGGBB
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Important:
|
|
Packit |
667938 |
If you use the I<dorelpercent> options tag a fifth colour name
|
|
Packit |
667938 |
colour value pair is required:
|
|
Packit |
667938 |
Col1#RRGGBB,Col2#RRGGBB,Col3#RRGGBB,Col4#RRGGBB,Col5#RRGGBB
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over 4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Colour1
|
|
Packit |
667938 |
|
|
Packit |
667938 |
First variable (normally Input) on default graph.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Colour2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Second variable (normally Output) on default graph.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Colour3
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Max first variable (input).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Colour4
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Max second variable (output).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item RRGGBB
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2 digit hex values for Red, Green and Blue.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Colours[myrouter]: GREEN#00eb0c,BLUE#1000ff,DARK GREEN#006600,VIOLET#ff00ff
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Background
|
|
Packit |
667938 |
|
|
Packit |
667938 |
With the I<Background> tag you can configure the background
|
|
Packit |
667938 |
colour of the generated HTML page.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Background[myrouter]: #a0a0a0a
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 YLegend, ShortLegend, Legend[1234]
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The following keywords allow you to override the text
|
|
Packit |
667938 |
displayed for the various legends of the graph and in the
|
|
Packit |
667938 |
HTML document:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item YLegend
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The Y-axis label of the graph. Note that a text which is too long
|
|
Packit |
667938 |
to fit in the graph will be silently ignored.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item ShortLegend
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The units string (default 'b/s') used for Max, Average and Current
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item Legend[1234IO]
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The strings for the colour legend.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
YLegend[myrouter]: Bits per Second
|
|
Packit |
667938 |
ShortLegend[myrouter]: b/s
|
|
Packit |
667938 |
Legend1[myrouter]: Incoming Traffic in Bits per Second
|
|
Packit |
667938 |
Legend2[myrouter]: Outgoing Traffic in Bits per Second
|
|
Packit |
667938 |
Legend3[myrouter]: Maximal 5 Minute Incoming Traffic
|
|
Packit |
667938 |
Legend4[myrouter]: Maximal 5 Minute Outgoing Traffic
|
|
Packit |
667938 |
LegendI[myrouter]: In:
|
|
Packit |
667938 |
LegendO[myrouter]: Out:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note, if I<LegendI> or I<LegendO> are set to an empty string with
|
|
Packit |
667938 |
|
|
Packit |
667938 |
LegendO[myrouter]:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The corresponding line below the graph will not be printed at all.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Timezone
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If you live in an international world, you might want to
|
|
Packit |
667938 |
generate the graphs in different timezones. This is set in the
|
|
Packit |
667938 |
TZ variable. Under certain operating systems like Solaris,
|
|
Packit |
667938 |
this will provoke the localtime call to give the time in
|
|
Packit |
667938 |
the selected timezone.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Timezone[myrouter]: Japan
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The Timezone is the standard timezone of your system, ie Japan, Hongkong,
|
|
Packit |
667938 |
GMT, GMT+1 etc etc.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Weekformat
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By default, mrtg (actually rateup) uses the strftime(3) '%V' option to
|
|
Packit |
667938 |
format week numbers in the monthly graphs. The exact semantics of this
|
|
Packit |
667938 |
format option vary between systems. If you find that the week numbers are
|
|
Packit |
667938 |
wrong, and your system's strftime(3) routine supports it, you can try
|
|
Packit |
667938 |
another format option. The POSIX '%V' option correspond to the widely used
|
|
Packit |
667938 |
ISO 8601 week numbering standard. The week format character should be
|
|
Packit |
667938 |
specified as a single letter; either W, V, or U.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The UNIX version of rateup uses the libc implementation of strftime.
|
|
Packit |
667938 |
On Windows, the native strftime implementation does not know about
|
|
Packit |
667938 |
%V. So there we use a different implementation of strftime that does
|
|
Packit |
667938 |
support %V.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Weekformat[myrouter]: W
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDRowCount
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This affects the creation of new rrd files. By default rrds are created to
|
|
Packit |
667938 |
hold about 1 day's worth of high resolution data. (plus 1 week of 30 minute
|
|
Packit |
667938 |
data, 2 months of 2 hour data and 2 years of 1 day data). With this Keyword
|
|
Packit |
667938 |
you can change the number of base interval entries configured for new rrds
|
|
Packit |
667938 |
as they get created. Note that you must take the interval time into account.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDRowCount[myrouter]: 1600
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDRowCount30m
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As per RRDRowCount, but for the RRA's -typically- used for 30 minute data.
|
|
Packit |
667938 |
Even so, you must still take the base interval into account. Leaving out
|
|
Packit |
667938 |
this keyword will force the old default of 800 rows.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDRowCount30m[myrouter]: 800
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDRowCount2h
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As per RRDRowCount, but for the RRA's -typically- used for 2 hour data.
|
|
Packit |
667938 |
Even so, you must still take the base interval into account. Leaving out
|
|
Packit |
667938 |
this keyword will force the old default of 800 rows.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDRowCount2h[myrouter]: 400
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDRowCount1d
|
|
Packit |
667938 |
|
|
Packit |
667938 |
As per RRDRowCount, but for the RRA's -typically- used for 1 day data.
|
|
Packit |
667938 |
Even so, you must still take the base interval into account. Leaving out
|
|
Packit |
667938 |
this keyword will force the old default of 800 rows.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDRowCount1d[myrouter]: 200
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 RRDHWRRAs
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Normally the RRDs created by MRTG will just contain the information gathered
|
|
Packit |
667938 |
directly from the respective target. With this option you can tap into
|
|
Packit |
667938 |
rrdtools advanced aberrant behaviour detection module based on Holt-Winters
|
|
Packit |
667938 |
forecasting. The RRDHWRRAs property specifies the Holt-Winters RRAs as
|
|
Packit |
667938 |
described in the rrdcreate manual page.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note, this setting will only affect newly created RRDs (targets).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
RRDHWRRAs[myrouter]: RRA:HWPREDICT:1440:0.1:0.0035:288
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 TimeStrPos
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This defines placement of the timestamp string on the image. Possible
|
|
Packit |
667938 |
values are RU, LU, RL, LL (which stand, respectively, for RightUpper,
|
|
Packit |
667938 |
LeftUpper, RightLower and LeftLower corner) and NO (for no timestamp).
|
|
Packit |
667938 |
By default, no timestamp is placed on the image.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
TimeStrPos[myrouter]: RU
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 TimeStrFmt
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Using this keyword you may specify format of the timestamp to be placed
|
|
Packit |
667938 |
on the image (if enabled by the TimeStrPos keyword). Specified string
|
|
Packit |
667938 |
will be used by the strftime() function - see strftime(3) documentation
|
|
Packit |
667938 |
for conversion specifiers available on your system.
|
|
Packit |
667938 |
Default format: %Y-%m-%d %H:%M
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
TimeStrFmt[myrouter]: %H:%M:%S
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 THRESHOLD CHECKING
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Through its threshold checking functionality mrtg is able to detect
|
|
Packit |
667938 |
threshold problems for the various targets and can call external
|
|
Packit |
667938 |
scripts to handle those problems (e.g. send email or a page to an administrator).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Threshold checking is configured through the following parameters:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshDir (GLOBAL)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
By defining ThreshDir to point to a writable directory, MRTG will only alert
|
|
Packit |
667938 |
you when a threshold boundary has been crossed.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshDir: /var/mrtg/thresh
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshHyst (GLOBAL)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If a threshold is broken, and you have a threshdir defined, then mrtg will
|
|
Packit |
667938 |
send mail once the threshold becomes 'unborken' to avoid situations where
|
|
Packit |
667938 |
broken and unbroken messages get sent in close succession, we only send an
|
|
Packit |
667938 |
unbroken message once the curent value is 0.1 (10%) away from the threshold.
|
|
Packit |
667938 |
using the ThreshHyst config variable you can customize this value.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example for 5%:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshHyst: 0.05
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMailServer (GLOBAL)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Adderss of an SMTP server which is going to accept mail about Thresholds being broken and unbroken.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMailSender (GLOBAL)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
What is the sender address of the threshold mail.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshMailSender: mrtg@example.com
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMailAddress (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Email address for Threshold related Mails. This will only work if a mailserver has been configured.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshMailAddress[_]: admin@example.com
|
|
Packit |
667938 |
ThreshMailAddress[router]:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This would bring threshold releaed mail to all but the target called 'router'.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMinI (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This is the minimum acceptable value for the Input (first) parameter. If
|
|
Packit |
667938 |
the parameter falls below this value, the program specified in ThreshProgI
|
|
Packit |
667938 |
will be run and a mail will be sent to the ThreshMailAddress if specified.
|
|
Packit |
667938 |
If the value ends in '%' then the threshold is defined relative to MaxBytes.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMaxI (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Works the same as TheshMinI but it acts when the value is higher than ThreshMaxI.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshDesc (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Its value will be assigned to the environment variable THRESH_DESC before
|
|
Packit |
667938 |
any of the programs mentioned below are called. The programs can use the value
|
|
Packit |
667938 |
of this variable to produce more user-friendly output.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshProgI (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This defines a program to be run if ThreshMinI or ThreshMaxI is broken.
|
|
Packit |
667938 |
MRTG passes 3 arguments: the $router variable, the threshold value
|
|
Packit |
667938 |
broken, and the current parameter value.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshProgOKI (PER TARGET)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
This defines a program to be run if the parameter is currently OK (based on
|
|
Packit |
667938 |
ThreshMinI and ThreshMaxI), but wasn't OK on the previous running -- based
|
|
Packit |
667938 |
on the files found in ThreshDir. MRTG passes 3 arguments: the $router
|
|
Packit |
667938 |
variable the unbroken threshold value, and the current parameter value.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 ThreshMinO, ThreshMaxO, ThreshProgO, and ThreshProgOKO
|
|
Packit |
667938 |
|
|
Packit |
667938 |
These work the same as their *I counterparts, except on the Output (second)
|
|
Packit |
667938 |
parameter.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 SetEnv
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When calling threshold scripts from within your cfg file you might want to
|
|
Packit |
667938 |
pass some data on to the script. This can be done with the SetEnv
|
|
Packit |
667938 |
configuration option which takes a series of environment variable
|
|
Packit |
667938 |
assignments. Note that the quotes are mandatory. This does not
|
|
Packit |
667938 |
work for external scripts. It is not
|
|
Packit |
667938 |
possible to set environment variables per target.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
SetEnv[myrouter]: EMAIL="contact_email@someplace.net"
|
|
Packit |
667938 |
HOST="www.some_server.net"
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 HW Failure Bassed Threshold Checking
|
|
Packit |
667938 |
|
|
Packit |
667938 |
When using rrd based logging with HW RRAs defined. You can use the
|
|
Packit |
667938 |
confidence bounds violations stored in the FAILURES RRA for threshold based
|
|
Packit |
667938 |
alerts.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
There the all target specific threshold variables have a Hold-Winters counterpart:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshMailAddress -> HWThreshMailAddress
|
|
Packit |
667938 |
ThreshMinI -> HWThreshMinI
|
|
Packit |
667938 |
...
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The global variables for threshold checking are shared except for the
|
|
Packit |
667938 |
|
|
Packit |
667938 |
ThreshHyst -> HWThreshHyst
|
|
Packit |
667938 |
|
|
Packit |
667938 |
And HWThreshDesc sets the HWTHRESH_DESC variable.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 PER TARGET DEFAULT VALUES
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Pre- and Postfix
|
|
Packit |
667938 |
|
|
Packit |
667938 |
To save yourself some typing you can define a target
|
|
Packit |
667938 |
called '^'. The text of every Keyword you define for this
|
|
Packit |
667938 |
target will be PREPENDED to the corresponding Keyword of
|
|
Packit |
667938 |
all the targets defined below this line. The same goes for
|
|
Packit |
667938 |
a Target called '$' but its text will be APPENDED.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Note that a space is inserted between the prepended text
|
|
Packit |
667938 |
and the Keyword value, as well as between the Keyword value
|
|
Packit |
667938 |
and the appended text. This works well for text-valued Keywords,
|
|
Packit |
667938 |
but is not very useful for other Keywords. See the "default"
|
|
Packit |
667938 |
target description below.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The example will make mrtg use a common header and a
|
|
Packit |
667938 |
common contact person in all the pages generated from
|
|
Packit |
667938 |
targets defined later in this file.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PageTop[^]: NoWhere Unis Traffic Stats
|
|
Packit |
667938 |
PageTop[$]: Contact Peter Norton if you have any questions
|
|
Packit |
667938 |
|
|
Packit |
667938 |
To remove the prepend/append value, specify an empty value, e.g.:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
PageTop[^]:
|
|
Packit |
667938 |
PageTop[$]:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 NoSpaceChar
|
|
Packit |
667938 |
|
|
Packit |
667938 |
With PREPEND and APPEND (see below) there is normally a space inserted
|
|
Packit |
667938 |
between the local value and the PRE- or APPEND value. Sometimes this is not
|
|
Packit |
667938 |
desirable. You can use the global option I<NoSpaceChar> to
|
|
Packit |
667938 |
define a character which can be mentioned at the end of a $ or ^ definition
|
|
Packit |
667938 |
in order to supress the space.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
NoSpaceChar: ~
|
|
Packit |
667938 |
Target[^]: 1.3.6.1.4.1.482.50.2.4.20.0&1.3.6.1.4.1.482.50.2.4.21.0:get@~
|
|
Packit |
667938 |
Target[a]: a.tolna.net
|
|
Packit |
667938 |
Target[b]: b.tolna.net
|
|
Packit |
667938 |
Target[c]: c.tolna.net
|
|
Packit |
667938 |
Target[d]: d.tolna.net
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Default Values
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The target name '_' specifies a default value for that
|
|
Packit |
667938 |
Keyword. In the absence of explicit Keyword value, the prepended
|
|
Packit |
667938 |
and the appended keyword value, the default value will be used.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
YSize[_]: 150
|
|
Packit |
667938 |
Options[_]: growright,bits,nopercent
|
|
Packit |
667938 |
WithPeak[_]: ymw
|
|
Packit |
667938 |
Suppress[_]: y
|
|
Packit |
667938 |
MaxBytes[_]: 1250000
|
|
Packit |
667938 |
|
|
Packit |
667938 |
To remove the default value and return to the 'factory default',
|
|
Packit |
667938 |
specify an empty value, e.g.:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
YLegend[_]:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
There can be several instances of setting the default/prepend/append
|
|
Packit |
667938 |
values in the configuration file. The later setting replaces the
|
|
Packit |
667938 |
previous one for the rest of the configuration file.
|
|
Packit |
667938 |
The default/prepend/append values used for a given
|
|
Packit |
667938 |
keyword/target pair are the ones that were in effect
|
|
Packit |
667938 |
at the point in the configuration file where the target
|
|
Packit |
667938 |
was mentioned for the first time.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
MaxBytes[_]: 1250000
|
|
Packit |
667938 |
Target[myrouter.somplace.edu.2]: 2:public@myrouter.somplace.edu
|
|
Packit |
667938 |
MaxBytes[_]: 8000
|
|
Packit |
667938 |
Title[myrouter.somplace.edu.2]: Traffic Analysis for myrouter.somplace.edu IF 2
|
|
Packit |
667938 |
|
|
Packit |
667938 |
The default I<MaxBytes> for the target myrouter.someplace.edu.2
|
|
Packit |
667938 |
in the above example will be 1250000, which was in effect
|
|
Packit |
667938 |
where the target name myrouter.someplace.edu.2 first appeared
|
|
Packit |
667938 |
in the config file.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 COMMAND LINE OPTIONS
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=over
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--user> I<username> and B<--group> I<groupname>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Run as the given user and/or group. (Unix Only)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--lock-file> I<filename>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Use an alternate lock-file (the default is to use the configuration-file
|
|
Packit |
667938 |
appended with C<_l>).
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--confcache-file> I<filename>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Use an alternate confcache-file (the default is to use the
|
|
Packit |
667938 |
configuration-file appended with C<.ok>)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--logging> I<filename>|B<eventlog>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
If this is set to writable filename, all output from mrtg (warnings, debug
|
|
Packit |
667938 |
messages, errors) will go to I<filename>. If you are running on Win32 you
|
|
Packit |
667938 |
can specify B<eventlog> instead of a filename which will send all error to
|
|
Packit |
667938 |
the windows event log.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
B<NOTE:> Note, there is no Message DLL for mrtg included with mrtg. This has
|
|
Packit |
667938 |
the side effect that the windows event logger will display a nice message
|
|
Packit |
667938 |
with every entry in the event log, complaing about the fact that mrtg has no
|
|
Packit |
667938 |
message dll. If you go to the mrtg contrib download area (on the website)
|
|
Packit |
667938 |
you will find the mrtg-message-dll.zip which does contain such a thing.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--daemon>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Put MRTG into the background, running as a daemon. This works the same way as
|
|
Packit |
667938 |
the config file option, but the switch is required for proper FHS operation
|
|
Packit |
667938 |
(because /var/run is writable only by root)
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--fhs>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Configure all mrtg paths to conform to the FHS specification;
|
|
Packit |
667938 |
http://www.pathname.com/fhs/
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--check>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Only check the cfg file for errors. Do not do anything.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--pid-file=s>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Define the name and path of the pid file for mrtg running as a daemon
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=item B<--debug=s>
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Enable debug options. The argument of the debug option is a comma separated
|
|
Packit |
667938 |
list of debug values:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
cfg - watch the config file reading
|
|
Packit |
667938 |
dir - directory mangeling
|
|
Packit |
667938 |
base - basic program flow
|
|
Packit |
667938 |
tarp - target parser
|
|
Packit |
667938 |
snpo - snmp polling
|
|
Packit |
667938 |
coca - confcache operations
|
|
Packit |
667938 |
fork - forking view
|
|
Packit |
667938 |
time - some timing info
|
|
Packit |
667938 |
log - logging of data via rateup or rrdtool
|
|
Packit |
667938 |
eval - print eval strings before evaluting them
|
|
Packit |
667938 |
prof - add hires timing info the rrd calls
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Example:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
--debug="cfg,snpo"
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=back
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 EXIT CODES
|
|
Packit |
667938 |
|
|
Packit |
667938 |
An exit code of 0 indicates that all targets were successful. Generally
|
|
Packit |
667938 |
speaking, most codes greater than 0 indicate that there was an unrecoverable
|
|
Packit |
667938 |
problem. One exception to this is code 91, which indicates that at least
|
|
Packit |
667938 |
one of the targets was successful. A partial listing of the codes follows:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
0: All targets sucessful
|
|
Packit |
667938 |
|
|
Packit |
667938 |
2: Config error (can't read, fatal error in config, etc)
|
|
Packit |
667938 |
17: Another MRTG process is processing config
|
|
Packit |
667938 |
|
|
Packit |
667938 |
91: At least one target sucessful
|
|
Packit |
667938 |
92: No targets were sucessful
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 EXAMPLES
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Minimal mrtg.cfg
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
Target[r1]: 2:public@myrouter.somplace.edu
|
|
Packit |
667938 |
MaxBytes[r1]: 8000
|
|
Packit |
667938 |
Title[r1]: Traffic Analysis ISDN
|
|
Packit |
667938 |
PageTop[r1]: Stats for our ISDN Line
|
|
Packit |
667938 |
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head2 Cfg for several Routers.
|
|
Packit |
667938 |
|
|
Packit |
667938 |
WorkDir: /usr/tardis/pub/www/stats/mrtg
|
|
Packit |
667938 |
Title[^]: Traffic Analysis for
|
|
Packit |
667938 |
PageTop[^]: Stats for
|
|
Packit |
667938 |
PageTop[$]: Contact The Chief if you notice anybody
|
|
Packit |
667938 |
MaxBytes[_]: 8000
|
|
Packit |
667938 |
Options[_]: growright
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title[isdn]: our ISDN Line
|
|
Packit |
667938 |
PageTop[isdn]: our ISDN Line
|
|
Packit |
667938 |
Target[isdn]: 2:public@router.somplace.edu
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title[backb]: our Campus Backbone
|
|
Packit |
667938 |
PageTop[backb]: our Campus Backbone
|
|
Packit |
667938 |
Target[backb]: 1:public@router.somplace.edu
|
|
Packit |
667938 |
MaxBytes[backb]: 1250000
|
|
Packit |
667938 |
|
|
Packit |
667938 |
# the following line removes the default prepend value
|
|
Packit |
667938 |
# defined above
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title[^]:
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Title[isdn2]: Traffic for the Backup ISDN Line
|
|
Packit |
667938 |
PageTop[isdn2]: our ISDN Line
|
|
Packit |
667938 |
Target[isdn2]: 3:public@router.somplace.edu
|
|
Packit |
667938 |
|
|
Packit |
667938 |
=head1 AUTHOR
|
|
Packit |
667938 |
|
|
Packit |
667938 |
Tobias Oetiker E<lt>tobi@oetiker.chE<gt> and many contributors
|