Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MRTG-REFERENCE(1)		     mrtg		     MRTG-REFERENCE(1)

       mrtg-reference -	MRTG 2.17.4 configuration reference

       The runtime behaviour of	MRTG is	governed by a configuration file.
       Run-of-the-mill configuration files can be generated with cfgmaker.
       (Check cfgmaker). But for more elaborate	configurations some hand-
       tuning is required.

       This document describes all the configuration options understood	by the
       mrtg software.

       MRTG configuration file syntax follows some simple rules:

       o   Keywords must start at the beginning	of a line.

       o   Lines which follow a	keyword	line which start with a	blank are
	   appended to the keyword line

       o   Empty Lines are ignored

       o   Lines starting with a # sign	are comments.

       o   You can add other files into	the configuration file using

	   Include: file



	   If included files are specified with	relative paths,	both the
	   current working directory and the directory containing the main
	   config file will be searched	for the	files.	The current working
	   directory will be searched first.

	   If the included filename contains an	asterisk, then this is taken
	   as a	wildcard for zero or more characters, and all matching files
	   are included.  Thus,	you can	use this statement to include all
	   files in a specified	subdirectory.


	    Include: servers/*.cfg

	   In this case, you should be very careful that your wildcard pattern
	   does	not find a match relative to the current working directory if
	   you mean it to be relative to the main config file directory, since
	   the working directory is checked for	a match	first (as with a
	   normal Include directive).  Therefore, use of something like	'*/*'
	   is discouraged.

       WorkDir specifies where the logfiles and	the webpages should be


	WorkDir: /usr/tardis/pub/www/stats/mrtg

       HtmlDir specifies the directory where the html (or shtml, but we'll get
       on to those later) lives.

       NOTE: Workdir overrides the settings for	htmldir, imagedir and logdir.


	Htmldir: /www/mrtg/

       ImageDir	specifies the directory	where the images live. They should be
       under the html directory.


	Imagedir: /www/mrtg/images

       LogDir specifies	the directory where the	logs are stored.  This need
       not be under htmldir directive.


	Logdir:	/www/mrtg/logs

   Forks (UNIX only)
       With system that	supports fork (UNIX for	example), mrtg can fork	itself
       into multiple instances while it	is acquiring data via snmp.

       For situations with high	latency	or a great number of devices this will
       speed things up considerably. It	will not make things faster, though,
       if you query a single switch sitting next door.

       As far as I know	NT can not fork	so this	option is not available	on NT.


	Forks: 4

       When set	to yes,	IPv6 support is	enabled	if the required	libraries are
       present (see the	mrtg-ipv6 manpage). When IPv6 is enabled, mrtg can
       talk to routers using SNMP over IPv6 and	targets	may be specified by
       their numeric IPv6 addresses as well as by hostname or IPv4 address.

       If IPv6 is enabled and the target is a hostname,	mrtg will try to
       resolve the hostname to an IPv6 address and, if this fails, to an IPv4
       address.	 Note that mrtg	will only use IPv4 if you specify an IPv4
       address or a hostname with no corresponding IPv6	address; it will not
       fall back to IPv4 if it simply fails to communicate with	the target
       using IPv6. This	is by design.

       Note that many routers do not currently support SNMP over IPv6. Use the
       IPv4Only	per target option for these routers.

       IPv6 is disabled	by default.


	EnableIPv6: Yes

       When set	to yes,	uses the Net::SNMP module instead of the SNMP_SESSION
       module for generating snmp queries.  This allows	the use	of SNMPv3 if
       other snmpv3 parameters are set.

       SNMPv3 is disabled by default.


	EnableSnmpV3: yes

       How many	seconds	apart should the browser (Netscape) be instructed to
       reload the page?	If this	is not defined,	the default is 300 seconds (5


	Refresh: 600

       How often do you	call mrtg? The default is 5 minutes. If	you call it
       less often, you should specify it here.	This does two things:

       o   The generated HTML page contains the	right information about	the
	   calling interval ...

       o   A META header in the	generated HTML page will instruct caches about
	   the time-to-live of this page .....

       In this example,	we tell	mrtg that we will be calling it	every 10
       minutes.	If you are calling mrtg	every 5	minutes, you can leave this
       line commented out.


	Interval: 10

       Note that unless	you are	using rrdtool you can not set Interval to less
       than 5 minutes. If you are using	rrdtool	you can	set interval in	the

	Interval: MM[:SS]

       Down to 1 second. Note though, setting the Interval for an rrdtool/mrtg
       setup will influence the	initial	creation of the	database. If you
       change the interval later, all existing databases will remain at	the
       resolution they were initially created with. Also note that you must
       make sure that your mrtg-rrd Web-frontend can deal with this kind of
       Interval	setting.

       MRTG relies heavily on the real time clock of your computer. If the
       time is set to a	wrong value, especially	if it is advanced far into the
       future, this will cause mrtg to expire lots of supposedly old data from
       the log files.

       To prevent this,	you can	add a 'reasonability' check by specifying a
       maximum age for log files. If a file seems to be	older, mrtg will not
       touch it	but complain instead, giving you a chance to investigate the


	MaxAge:	7200

       The example above will make mrtg	refuse to update log files older than
       2 hours (7200 seconds).

       With this switch	mrtg will generate .meta files for CERN	and Apache
       servers which contain Expiration	tags for the html and gif files. The
       *.meta files will be created in the same	directory as the other files,
       so you will have	to set "MetaDir	." and "MetaFiles on" in your
       apache.conf or .htaccess	file for this to work

       NOTE: If	you are	running	Apache-1.2 or later, you can use the
       mod_expire to achieve the same effect ... see the file htaccess.txt


	WriteExpires: Yes

       Normally	we ask the SNMP	device for 'sysUptime' and 'sysName'
       properties.  Some do not	have these. If you want	to avoid getting
       complaints from mrtg about these	missing	properties, specify the	nomib2

       An example of agents which do not implement base	mib2 attributes	are
       Computer	Associates - Unicenter TNG Agents.  CA relies on using the
       base OS SNMP agent in addition to its own agents	to supplement the
       management of a system.


	NoMib2:	Yes

       Some SNMP implementations can not deal with requests asking for
       multiple	snmp variables in one go. Set this in your cfg file to force
       mrtg to only ask	for one	variable per request.


	SingleRequest: Yes

       Apart from the per target timeout options, you can also configure the
       behaviour of the	snmpget	process	on a more profound level. SnmpOptions
       accepts a hash of options. The following	options	are currently

	timeout			  => $default_timeout,
	retries			  => $default_retries,
	backoff			  => $default_backoff,
	default_max_repetitions	  => $max_repetitions,
	use_16bit_request_ids	  => 1,
	lenient_source_port_matching =>	0,
	lenient_source_address_matching	=> 1

       The values behind the options indicate the current default value.  Note
       that these settings OVERRIDE the	per target timeout settings.

       A per-target SnmpOptions[] keyword will override	the global settings.
       That keyword is primarily for SNMPv3.

       The 16bit request ids are the only way to query the broken SNMP
       implementation of SMC Barricade routers.


	SnmpOptions: retries =>	2, only_ip_address_matching => 0

       Note that AS/400	snmp seems to be broken	in a way which prevents	mrtg
       from working with it unless

	SnmpOptions: lenient_source_port_matching => 1

       is set.

       If you want to keep the mrtg icons in someplace other than the working
       (or imagedir) directory,	use the	IconDir	variable for defining the url
       of the icons directory.


	IconDir: /mrtgicons/

       Load the	MIB file(s) specified and make its OIDs	available as symbolic
       names. For better efficiancy, a cache of	MIBs is	maintained in the


	LoadMIBs: /dept/net/mibs/netapp.mib,/usr/local/lib/ft100m.mib

       Switch output format to the selected Language (Check the	translate
       directory to see	which languages	are supported at the moment. In	this
       directory you can also find instructions	on how to create new

       Currently the following laguages	are supported:

       big5 brazilian bulgarian	catalan	chinese	croatian czech danish dutch
       eucjp french galician gb	gb2312 german greek hungarian icelandic
       indonesia iso2022jp italian korean lithuanian malay norwegian polish
       portuguese romanian russian russian1251 serbian slovak slovenian
       spanish swedish turkish ukrainian


	Language: danish

       Setting LogFormat to 'rrdtool' in your mrtg.cfg file enables rrdtool
       mode.  In rrdtool mode, mrtg relies on rrdtool to do its	logging. See


	LogFormat: rrdtool

       If you are using	rrdtool	mode and your rrdtool Perl module ( is
       not installed in	a location where perl can find it on its own, you can
       use LibAdd to supply an appropriate path.


	LibAdd:	/usr/local/rrdtool/lib/perl/

       If the rrdtool executable can not be found in the normal	"PATH",	you
       can use this keyword to add a suitable directory	to your	path.


	PathAdd: /usr/local/rrdtool/bin/

       If you are running RRDTool 1.4 or later with rrdcached, then you	can
       configure MRTG to take advantage	of this	for updates, either by using
       the RRDCACHED_ADDRESS environment variable, or by setting the RRDCached
       keyword in the configuration file.  Note	that, if both are set, the
       configuration file keyword will take precedence.

       Only UNIX domain	sockets	are fully supported prior to RRDTool v1.5, and
       you should note that using RRDCached mode will disable all Threshold
       checking	normally done by MRTG.	Appropriate warning messages will be
       printed if necessary.


	RRDCached: unix:/var/tmp/rrdcached.sock

	RRDCached: localhost:42217

       The RunAsDaemon keyword enables daemon mode operation. The purpose of
       daemon mode is that MRTG	is launched once and not repeatedly (as	it is
       with cron).  This behavior saves	computing resourses as loading and
       parsing of configuration	files happens only once	on startup, and	if the
       configuration file is modified.

       Using daemon mode MRTG itself is	responible for timing the measurement
       intervals. Therfore its important to set	the Interval keyword to	an
       apropiate value.

       Note that when using daemon mode	MRTG should no longer be started from
       cron as each new	process	runs forever. Instead MRTG should be started
       from the	command	prompt or by a system startup script.

       If you want mrtg	to run under a particular user and group (it is	not
       recomended to run MRTG as root) then you	can use	the --user=user_name
       and --group=group_name options on the mrtg commandline.

	mrtg --user=mrtg_user --group=mrtg_group mrtg.cfg

       Also note that in daemon	mode restarting	the process is required	in
       order to	activate changes in the	config file.

       Under UNIX, the Daemon switch causes mrtg to fork into background after
       checking	its config file. On Windows NT the MRTG	process	will detach
       from the	console, but because the NT/2000 shell waits for its children
       you have	to use this special start sequence when	you launch the

	start /b perl mrtg mrtg.cfg

       You may have to add path	information equal to what you add when you run
       mrtg from the commandline.


	RunAsDaemon: Yes
	Interval:    5

       This makes MRTG run as a	daemon beginning data collection every 5

       If you are daemontools and still	want to	run mrtg as a daemon you can
       additionally specify

	NoDetach:     Yes

       this will make mrtg run but without detaching it	from the terminal.

       If the modification date	on the configuration file changes during
       operation, then MRTG will re-read the configuration on the next polling
       cycle.  Note that sub-files which are included from the main
       configuration do	not have their modification times monitored, only the
       top-level file is so checked.

       Some devices may	produce	non-numeric values that	would nevertheless be
       useful to graph with MRTG if those values could be converted to
       numbers.	 The ConversionCode keyword specifies the path to a file
       containing Perl code to perform such conversions. The code in this file
       must consist of one or more Perl	subroutines. Each subroutine must
       accept a	single string argument and return a single numeric value. When
       RRDtool is in use, a decimal value may be returned. When	the name of
       one of these subroutines	is specified in	a target definition (see
       below), MRTG calls it twice for that target, once to convert the	the
       input value being monitored and a second	time to	convert	the output
       value. The subroutine must return an undefined value if the conversion
       fails. In case of failure, a warning may	be posted to the MRTG log file
       using Perl's warn function. MRTG	imports	the subroutines	into a
       separate	name space (package MRTGConversion), so	the user need not
       worry about pollution of	MRTG's global name space. MRTG automatically
       prepends	this package declaration to the	user-supplied code.

       Example:	Suppose	a particular OID returns a character string whose
       length is proportional to the value to be monitored. To convert this
       string to a number that can be graphed by MRTG, create a	file
       arbitrarily named "" containing the following code:

	# Return the length of the string argument
	sub Length2Int {
	  my $value = shift;
	  return length( $value	);

       Then include the	following global keyword in the	MRTG configuration
       file (assuming that the conversion code file is saved in	the mrtg/bin
       directory along with mrtg itself):


       This will cause MRTG to include the definition of the subroutine
       Length2Int in its execution environment.	Length2Int can then be invoked
       on any target by	appending "|Length2Int"	to the target definition as


       See "Extended Host Name Syntax" below for complete target definition
       syntax information.

       Each monitoring target must be identified by a unique name. This	name
       must be appended	to each	parameter belonging to the same	target.	The
       name will also be used for naming the generated webpages, logfiles and
       images for this target.

       With the	Target keyword you tell	mrtg what it should monitor. The
       Target keyword takes arguments in a wide	range of formats:

	   The most basic format is "port:community@router" This will generate
	   a traffic graph for the interface 'port' of the host	'router' (dns
	   name	or IP address) and it will use the community 'community' (snmp
	   password) for the snmp query.


	    Target[myrouter]: 2:public@wellfleet-fddi.domain

	   If your community contains a	"@" or a " " these characters must be
	   escaped with	a "\".

	    Target[bla]: 2:stu\	pi\@d@router

	   If you have a fast router you might want to try to poll the ifHC*
	   counters.  This feature gets	activated by switching to SNMPv2c.
	   Unfortunately not all devices support SNMPv2c yet. If it works,
	   this	will prevent your counters from	wraping	within the 5 minute
	   polling interval, since we now use 64 bit instead of	the normal 32


	    Target[myrouter]: 2:public@router1:::::2

	   As an alternative to	SNMPv2c, SNMPv3	provides access	to the ifHC*
	   counters, along with	encryption.  Not all devices support SNMPv3,
	   and you will	also need the perl Net::SNMP library in	order to use
	   it.	It is recommended that cfgmaker	be used	to generate
	   configurations involving SNMPv3, as it will check if	the Net::SNMP
	   library is loadable,	and will switch	to SNMPv2c if v3 is

	   SNMP	v3 requires additional authentication parameters, passed using
	   the SnmpOptions[] per-target	keyword.

	     Target[myrouter]: 2:router1:::::3
	     SnmpOptions[myrouter]: username=>'user1'

	   Not all routers that	support	SNMPv2 or SNMPv3 provide the ifHC*
	   counters on every interface.	 The noHC[] per-target keyword signals
	   that	the low-speed counters ifInOctets and ifOutOctets should be
	   queried instead.  cfgmaker will automatically insert	this tag if
	   SNMPv2 or SNMPv3 is specified but the ifHC* counters	are

	     Target[myrouter]: #Bri0:router1:::::3
	     SnmpOptions[myrouter]: username=>'user1'
	     noHC[myrouter]: yes

	   Sometimes you are sitting on	the wrong side of the link, and	you
	   would like to have mrtg report Incoming traffic as Outgoing and
	   vice	versa. This can	be achieved by adding the '-' sign in front of
	   the "Target"	description. It	flips the incoming and outgoing
	   traffic rates.


	    Target[ezci]: -1:public@ezci-ether.domain

       Explicit	OIDs
	   You can also	explicitly define which	OID to query by	using the
	   following syntax 'OID_1&OID_2:community@router' The following
	   example will	retrieve error counts for input	and output on
	   interface 1.	 MRTG needs to graph two variables, so you need	to
	   specify two OID's such as temperature and humidity or error input
	   and error output.



       MIB Variables
	   MRTG	knows a	number of symbolic SNMP	variable names.	 See the file
	   mibhelp.txt for a list of known names.  One example are the
	   ifInErrors and ifOutErrors.	This means you can specify the above


	    Target[myrouter]: ifInErrors.1&ifOutErrors.1:public@myrouter

	   It may be that you want to monitor an snmp object that is only
	   reachable by	'walking'. You can get mrtg to walk by prepending the
	   OID with the	string WaLK or if you want a particular	entry from the
	   table returned by the walk you can use WaLKx	where x	is a number
	   starting from 0 (!).


	     Target[myrouter]: WaLKstrangeOid.1&WaLKstrangeOid.2:public@myrouter

	     Target[myrouter]: WaLK3strangeOid.1&WaLK4strangeOid.2:public@myrouter

	   A special case of an	snmp object that is only reachable by
	   'walking' occurs when a single snmpgetnext will return the correct
	   value, but snmpwalk fails.  This may	occur with snmp	V2 or V3, as
	   the snmpgetbulk method is used in these versions. You can get mrtg
	   to use getnext instead of getbulk by	prepending the OID with	the
	   string GeTNEXT.


	     Target[myrouter]: GeTNEXTstrangeOid&GeTNEXTstrangeOid:public@myrouter

       Counted SNMP Walk
	   In other situations,	an snmpwalk is needed to count rows, but the
	   actual data is uninteresting.  For example, counting	the number of
	   mac-addresses in a CAM table, or the	number of simultaneous dialup
	   sessions.  You can get MRTG to count	the number of instances	by
	   prepending the OID with the string CnTWaLK.	The following will
	   retrieve the	number of simultaneous VOIP calls on some routers:


	      Target[myrouter]:	CnTWaLK1.

       Interface by IP
	   Sometimes SNMP interface index can change, like when	new interfaces
	   are added or	removed. This can cause	all Target entries in your
	   config file to become offset, causing MRTG to graphs	wrong
	   instances etc.  MRTG	supports IP address instead of ifindex in
	   target definition. Then MRTG	will query snmp	device and try to map
	   IP address to the current ifindex.  You can use IP addresses	in
	   every type of target	definition by adding IP	address	of the
	   numbered interface after OID	and separation char '/'.

	   Make	sure that the given IP address is used on your same target
	   router, especially when graphing two	different OIDs and/or
	   interface split by '&' delimiter.

	   You can tell	cfgmaker to generate such references with the option


	    Target[myrouter]: /
	    Target[ezci]: -/
	    Target[myrouter]: ifInErrors/

       Interface by Description
	   If you can not use IP addresses you might want to use the interface
	   names. This works similar to	the IP address aproach except that the
	   prefix to use is a \	instead	of a /

	   You can tell	cfgmaker to generate such references with the option


	    Target[myrouter]: \My-Interface2:public@wellfleet-fddi.domain
	    Target[ezci]: -\My-Interface2:public@ezci-ether.domain
	    Target[myrouter]: ifInErrors\My-If2&ifOutErrors\My-If3:public@myrouter

	   If your description contains	a "&", a ":", a	"@" or a " " you can
	   include them	but you	must escape with a backlash:

	    Target[myrouter]: \fun\:\ ney\&ddd:public@hello.router

       Interface by Name
	   This	is the only sensible way to reference the interfaces of	your

	   You can tell	cfgmaker to generate such references with the option


	    Target[myrouter]: #2/11:public@wellfleet-fddi.domain
	    Target[ezci]: -#2/11:public@ezci-ether.domain
	    Target[myrouter]: ifInErrors#3/7&ifOutErrors#3/7:public@myrouter

	   If your description contains	a "&", a ":", a	"@" or a " " you can
	   include them	but you	must escape with a backlash:

	    Target[myrouter]: #\:\ fun:public@hello.router

	   Note	that the # sign	will be	interpreted as a comment character if
	   it is the first non white-space character on	the line.

       Interface by Ethernet Address
	   When	the SNMP interface index changes, you can key that interface
	   by its 'Physical Address', sometimes	called a 'hard address', which
	   is the SNMP variable	'ifPhysAddress'.  Internally, MRTG matches the
	   Physical Address from the *.cfg file	to its current index, and then
	   uses	that index for the rest	of the session.

	   You can use the Physical Address in every type of target definition
	   by adding the Physical Address after	the OID	and the	separation
	   char	'!' (analogous to the IP address option).  The Physical
	   address is specified	as '-' delimited octets, such as
	   "0a-0-f1-5-23-18" (omit the double quotes). Note that some routers
	   use the same	Hardware Ethernet Address for all of their Interfaces
	   which prevents unique interface identification. Mrtg	will notice
	   such	problems and alert you.

	   You can tell	cfgmaker to generate configuration files with hardware
	   ethernet address references by using	the option --ifref=eth.


	    Target[myrouter]: !0a-0b-0c-0d:public@wellfleet-fddi.domain
	    Target[ezci]: -!0-f-bb-05-71-22:public@ezci-ether.domain
	    Target[myrouter]:!0a-00-10-23-44-51& *BREAK*!0a-00-10-23-44-51:public@myrouter
	    Target[myrouter]: ifInErrors!0a-00-10-23-44-51& *BREAK*

	   Join	the lines at *BREAK* ...

       Interface by Type
	   It seems that there are devices that	try to defy all	monitoring
	   efforts: the	interesting interfaces have neither ifName nor a
	   constant ifDescr not	to mention a persistent	ifIndex. The only way
	   to get a constant mapping is	by looking at the interface type,
	   because the interface you are interested in is unique in the	device
	   you are looking at ...

	   You can tell	cfgmaker to generate such references with the option


	    Target[myrouter]: %13:public@wellfleet-fddi.domain
	    Target[ezci]: -%13:public@ezci-ether.domain
	    Target[myrouter]: ifInErrors%13&ifOutErrors%14:public@myrouter

       Extended	positioning of ifIndex
	   There are OIDs that contain the interface index at some inner
	   position within the OID. To use the above mentioned Interface by
	   IP/Description/Name/Type methods in the target definition the
	   keyword 'IndexPOS' can be used to indicate the position of ifIndex.
	   If 'IndexPOS' is not	used the ifIndex will be appended at the end
	   of the OID.


	    Target[myrouter]: OID.IndexPOS.1/

	   Replace OID by your numeric OID.

       Extended	Host Name Syntax
	   In all places where ``community@router'' is accepted, you can add
	   additional parameters for the SNMP communication using colon-
	   separated suffixes. You can also append a pipe symbol ( | ) and the
	   name	of a numeric conversion	subroutine as described	under the
	   global keyword "ConversionCode" above. The full syntax is as


	   where the meaning of	each parameter is as follows:

	       the UDP port under which	to contact the SNMP agent (default:

	       The complete syntax of the port parameter is


	       Some machines have additional security features that only allow
	       SNMP queries to come from certain IP addresses. If the host
	       doing the query has multiple interface, it may be necessary to
	       specify the interface the query should come from.

	       The port	parameter allows the specification of the port of the
	       machine being queried. In addition, the IP address (or
	       hostname) and port of the machine doing the query may be


		somehost:161!!4000 use and port 4000 as source
		somehost:! use as source
		somehost:!!4000	use port 4000 as source

	       initial timeout for SNMP	queries, in seconds (default: 2.0)

	       number of times a timed-out request will	be retried (default:

	       factor by which the timeout is multiplied on every retry
	       (default: 1.0).

	       for SNMP	version. If you	have a fast router you might want to
	       put a '2' here.	For authenticated or encrypted SNMP, you can
	       try to put a '3'	here.  This will make mrtg try to poll the 64
	       bit counters and	thus prevent excessive counter wrapping. Not
	       all routers support this	though.	 SNMP v3 requires additional
	       setup, see SnmpOptions[]	for full details.



	       the name	of the subroutine that MRTG will call to convert the
	       input and output	values to integers. See	the complete example
	       under the global	keyword	"ConversionCode" above.


	       This would retrieve values from the OID for
	       input and .2 for	output on mydevice using UDP port 161 and SNMP
	       version 2, and would execute the	user-defined numeric
	       conversion subroutine Length2Int	to convert those values	to

	   A value that	equals the default value can be	omitted.  Trailing
	   colons can be omitted, too. The pipe	symbol followed	by the name
	   parameter, if present, must come at the end.	There must be no
	   spaces around the colons or pipe symbol.


	     Target[ezci]: 1:public@ezci-ether.domain:9161::4

	   This	would refer to the input/output	octet counters for the
	   interface with ifIndex 1 on ezci-ether.domain, as known by the SNMP
	   agent listening on UDP port 9161.  The standard initial timeout
	   (2.0	seconds) is used, but the number of retries is set to four.
	   The backoff value is	the default.

       Numeric IPv6 addresses
	   If IPv6 is enabled you may also specify a target using its IPv6
	   address. To avoid ambiguity with the	port number, numeric IPv6
	   addresses must be placed in square brackets.


	    Target[IPv6test]: 2:public@[2001:760:4::]:6161::4

       External	Monitoring Scripts
	   If you want to monitor something which does not provide data	via
	   snmp	you can	use some external program to do	the data gathering.

	   The external	command	must return 4 lines of output:

	   Line	1
	       current state of	the first variable, normally 'incoming bytes

	   Line	2
	       current state of	the second variable, normally 'outgoing	bytes

	   Line	3
	       string (in any human readable format), telling the uptime of
	       the target.

	   Line	4
	       string, telling the name	of the target.

	   Depending on	the type of data your script returns you might want to
	   use the 'gauge' or 'absolute' arguments for the Options keyword.


	    Target[myrouter]: `/usr/local/bin/df2mrtg /dev/dsk/c0t2d0s0`

	   Note	the use	of the backticks (`), not apostrophes (') around the

	   If you want to use a	backtick in the	command	name this can be done
	   but you must	escape it with a backslash ...

	   If your script does not have	any data to return but does not	want
	   mrtg	to complain about invalid data,	it can return 'UNKNOWN'
	   instead of a	number.	 Note though that only rrdtool is realy
	   equipped to handle unknown data well.

       Multi Target Syntax
	   You can also	combine	several	target definitions in a	mathematical
	   expression.	Any syntactically correct expression that the Perl
	   interpreter can evaluate to will work. An expression	could be used,
	   for example,	to aggregate both B channels in	an ISDN	connection or
	   to calculate	the percentage hard disk utilization of	a server from
	   the absolute	used space and total capacity.


	    Target[myrouter]: 2:public@wellfleetA + 1:public@wellfleetA

	    Target[myrouter]: . /
		. *	100

	   Note	that whitespace	must surround each target definition in	the
	   expression.	Target definitions themselves must not contain
	   whitespace, except in interface descriptions	and interface names,
	   where each whitespace character is escaped by a backslash.

	   MRTG	automatically rounds the result	of the expression to an
	   integer unless RRDTool logging is in	use and	the gauge option is in
	   effect for the target.  Internally MRTG uses	Perl's Math::BigFloat
	   package to calculate	the result of the expression with 40 digits of
	   precision. Even in extreme cases, where, for	example, you take the
	   difference of two 64-bit integers, the result of the	expression
	   should be accurate.

       SNMP Request Optimization
	   MRTG	is designed to economize on its	SNMP requests. Where a target
	   definition appears more than	once in	the configuration file,	MRTG
	   requests the	data from the device only once per round of data
	   collection and uses the collected data for each instance of a
	   particular target. Recognition of two target	definitions as being
	   identical is	based on a simple string match rather than any kind of
	   deeper semantic analysis.


	    Target[Targ1]: 1:public@CiscoA
	    Target[Targ2]: 2:public@CiscoA
	    Target[Targ3]: 1:public@CiscoA + 2:public@CiscoA
	    Target[Targ4]: 1:public@CISCOA

	   This	results	in a total of three SNMP requests. Data	for
	   1:public@CiscoA and 2:public@CiscoA are requested only once each,
	   and used for	Targ1, Targ2, and Targ3. Targ4 causes another SNMP
	   request for 1:public@CISCOA,	which is not recognized	as being
	   identical to	1:public@CiscoA.

       The maximum value either	of the two variables monitored are allowed to
       reach. For monitoring router traffic this is normally the bytes per
       second this interface port can carry.

       If a number higher than MaxBytes	is returned, it	is ignored.  Also read
       the section on AbsMax for further info.	The MaxBytes value is also
       used in calculating the Y range for unscaled graphs (see	the section on

       Since most links	are rated in bits per second, you need to divide their
       maximum bandwidth (in bits) by eight (8)	in order to get	bytes per
       second.	This is	very important to make your unscaled graphs display
       realistic information. T1 = 193000, 56K = 7000, 10 MB Ethernet =
       1250000,	100 MB Ethernet	= 12500000. The	MaxBytes value will be used by
       mrtg to decide whether it got a valid response from the router.

       If you need two different MaxBytes values for the two monitored
       variables, you can use MaxBytes1	and MaxBytes2 instead of MaxBytes.


	MaxBytes[myrouter]: 1250000

       Title for the HTML page which gets generated for	the graph.


	Title[myrouter]: Traffic Analysis for Our Nice Company

       Things to add to	the top	of the generated HTML page.  Note that you can
       have several lines of text as long as the first column is empty.

       Note that the continuation lines	will all end up	on the same line in
       the html	page. If you want linebreaks in	the generated html use the
       '\n' sequence.


	PageTop[myrouter]: <H1>Traffic Analysis	for ETZ	C95.1</H1>
	  Our Campus Backbone runs over	an FDDI	line\n
	  with a maximum transfer rate of 12.5 megabytes per

       In cases	where you calculate the	used bandwidth from several interfaces
       you normally don't get the router uptime	and router name	displayed on
       the web page.

       If these	interfaces are on the same router and the uptime and name
       should be displayed you have to specify its community and address again
       with the	RouterUptime keyword.

       If you want to use a special OID	for querying the router	uptime,	use
       prepend the oid.


	Target[]: 1:public@ + 2:public@
	RouterUptime[]:	public@

	RouterUptime[]:	hrSystemUptime.0:public@

       If the default name of the router is incorrect/uninformative, you can
       use RouterName to specify a different OID on either the same or a
       different host.

       A practical example: sysName on BayTech DS72 units always display
       "ds72", no matter what you set the Unit ID to be.  Instead, the Unit ID
       is stored at, so we can	have MRTG display this
       instead of sysName.



       A different OID on a different host can also be specified:


       Same as MaxBytes, for variable 1.

       Same as MaxBytes, for variable 2.

       Many IPv6 routers do not	currently support SNMP over IPv6 and must be
       monitored using IPv4. The IPv4Only option forces	mrtg to	use IPv4 when
       communicating with the target, even if IPv6 is enabled. This is useful
       if the target is	a hostname with	both IPv4 and IPv6 addresses; without
       the IPv4Only keyword, monitoring	such a router will not work if IPv6 is

       If set to no (the default), mrtg	will use IPv6 unless the target	has no
       IPv6 addresses, in which	case it	will use IPv4. If set to yes, mrtg
       will only use IPv4.

       Note that if this option	is set to yes and the target does not have an
       IPv4 address, communication with	the target will	fail.

       This option has no effect if IPv6 is not	enabled.


	Target[v4onlyrouter_1]:	1:public@v4onlyrouter
	IPv4Only[v4onlyrouter_1]: Yes

   SnmpOptions (V3)
       SNMPv3 requires a fairly	rich set of options.  This per-target keyword
       allows access to	the User Security Model	of SNMPv3.  Options are	listed
       in the same syntax as a perl hash.

       Security	Modes

       SNMPv3 has three	security modes,	defined	on the device being polled.
       For example, on Cisco routers the security mode is defined by the snmp-
       server group global configuration command.

	   Neither Authentication nor Privacy is defined.  Only	the Username
	   option is specified for this	mode.


	    SnmpOptions[myrouter]: username=>'user1'

	   Uses	a Username and a password.  The	password can be	hashed using
	   the snmpkey application, or passed in plain text along with the


	    SnmpOptions[myrouter]: username=>'user1',authpassword=>'example',

	   Both	Authentication and Privacy is defined.	The default privacy
	   protocol is des.


       snmp options

       The following option keywords are recognized:

	   The user associated with the	User Security Model

	   An SNMP agent can define multiple contexts.	This keyword allows
	   them	to be polled.

	   A unique 24-byte string identifying the snmp-agent.

	   The plaintext password for a	user in	either AuthNoPriv or Priv

	   A md5 or sha	hash of	the plain-text password, along with the
	   engineid.  Use the snmpkey commandline program to generate this
	   hash, or use	Net::SNMP::Security::USM in a script.

       authprotocol {sha|md5}
	   The hashing algorithm defined on the	SNMP client.  Defaults to md5.

	   A plaintext pre-shared key for encrypting snmp packets in Priv

	   A hash of the plain-text pre-shared key, along with the engineid.
	   Use the snmpkey commandline program to generate this	hash, or use
	   Net::SNMP::Security::USM in a script.

       privprotocol {des|3desede|aescfb128|aescfb192|aescfb256}
	   Specifies the encryption method defined on the snmp agent.  The
	   default is des.

       Things to add to	the bottom of the generated HTML page.	Note that you
       can have	several	lines of text as long as the first column is empty.

       Note that the continuation lines	will all end up	on the same line in
       the html	page. If you want linebreaks in	the generated html use the
       '\n' sequence.

       The material will be added just before the </BODY> tag:


	PageFoot[myrouter]: Contact <A HREF="mailto:peter@x.yz">Peter</A>
	 if you	have questions regarding this page

       Use this	tag like the PageTop header, but its contents will be added
       between </TITLE>	and </HEAD>.


	AddHead[myrouter]: <link rev="made" href="">

       BodyTag lets you	supply your very own <body ...>	tag for	the generated


	BodyTag[myrouter]: <BODY LEFTMARGIN="1"	TOPMARGIN="1"

       If you are monitoring a link which can handle more traffic than the
       MaxBytes	value. Eg, a line which	uses compression or some frame relay
       link, you can use the AbsMax keyword to give the	absolute maximum value
       ever to be reached. We need to know this	in order to sort out
       unrealistic values returned by the routers. If you do not set AbsMax,
       rateup will ignore values higher	than MaxBytes.


	AbsMax[myrouter]: 2500000

       By default each graph is	scaled vertically to make the actual data
       visible even when it is much lower than MaxBytes.  With the Unscaled
       variable	you can	suppress this.	It's argument is a string, containing
       one letter for each graph you don't want	to be scaled: d=day w=week
       m=month y=year.	There is also a	special	case to	unset the variable
       completely: n=none. This	could be useful	in the event you need to
       override	a global configuration.	In the example scaling for the yearly
       and the monthly graph are suppressed.


	Unscaled[myrouter]: ym

       By default the graphs only contain the average values of	the monitored
       variables - normally the	transfer rates for incoming and	outgoing
       traffic.	 The following option instructs	mrtg to	display	the peak 5
       minute values in	the [w]eekly, [m]onthly	and [y]early graph. In the
       example we define the monthly and the yearly graph to contain peak as
       well as average values.


	WithPeak[myrouter]: ym

       By default mrtg produces	4 graphs. With this option you can suppress
       the generation of selected graphs.  The option value syntax is
       analogous to the	above two options.  In this example we suppress	the
       yearly graph as it is quite empty in the	beginning.


	Suppress[myrouter]: y

       By default, mrtg	creates	.html files. Use this option to	tell mrtg to
       use a different extension. For example you could	set the	extension to
       php3, then you will be able to enclose PHP tags into the	output (useful
       for getting a router name out of	a database).


	Extension[myrouter]: phtml

       By default, mrtg	puts all the files that	it generates for each target
       (the GIFs, the HTML page, the log file, etc.) in	WorkDir.

       If the Directory	option is specified, the files are instead put into a
       directory under WorkDir or Log-,	Image- and HtmlDir).  (For example the
       Directory option	below would cause all the files	for a target myrouter
       to be put into directory	/usr/tardis/pub/www/stats/mrtg/myrouter/ .)

       The directory must already exist; mrtg will not create it.


	WorkDir: /usr/tardis/pub/www/stats/mrtg
	Directory[myrouter]: myrouter

       NOTE: the Directory option must always be 'relative' or bad things will

       If the Directory	option is specified, the Clonedirectory	option will
       copy all	the contents of	Directory to the Clonedirectory.


	WorkDir: /usr/tardis/pub/www/stats/mrtg
	Directory[myrouter]: myrouter
	Clonedirectory[myrouter]: myclonedirectory

       Optionally the target name can be changed in the	cloning	process.


	WorkDir: /usr/tardis/pub/www/stats/mrtg
	Directory[myrouter]: myrouter
	Clonedirectory[myrouter]: myclonedirectory mynewtarget

       NOTE1: The clone	directory must already exist; mrtg will	not create it.

       NOTE2: The Clonedirectory option	must also always be 'relative' or bad
       things will happen.

       NOTE3: This requires the	File::Copy module

   XSize and YSize
       By default mrtgs	graphs are 100 by 400 pixels wide (plus	some more for
       the labels. In the example we get almost	square graphs ...

       Note: XSize must	be between 20 and 600; YSize must be larger than 20


	XSize[myrouter]: 300
	YSize[myrouter]: 300

   XZoom and YZoom
       If you want your	graphs to have larger pixels, you can "Zoom" them.


	XZoom[myrouter]: 2.0
	YZoom[myrouter]: 2.0

   XScale and YScale
       If you want your	graphs to be actually scaled use XScale	and YScale.
       (Beware:	while this works, the results look ugly	(to be frank) so if
       someone wants to	fix this: patches are welcome.


	XScale[myrouter]: 1.5
	YScale[myrouter]: 1.5

   YTics and YTicsFactor
       If you want to show more	than 4 lines per graph,	use YTics.  If you
       want to scale the value used for	the YLegend of these tics, use
       YTicsFactor.  The default value for YTics is 4 and the default value
       for YTicsFactor is 1.0 .


       Suppose you get values ranging from 0 to	700.  You want to plot 7 lines
       and want	to show	0, 1, 2, 3, 4, 5, 6, 7 instead of 0, 100, 200, 300,
       400, 500, 600, 700.  You	should write then:

	 YTics[myrouter]: 7
	 YTicsFactor[myrouter]:	0.01

       If you want to multiply all numbers shown below the graph with a
       constant	factor,	use this directive to define it	..


	 Factor[as400]:	4096

       Change the default step from 5 *	60 seconds to something	else (I	have
       not tested this much ...)


	Step[myrouter]:	60

       When using rateup for graph generation, this will print the given title
       in the graph it generates.


	PNGTitle[myrouter]: WAN	Link UK-US

       The Options Keyword allows you to set some boolean switches:

	   The graph grows to the left by default.  This option	flips the
	   direction of	growth causing the current time	to be at the right
	   edge	of the graph and the history values to the left	of it.

	   All the monitored variable values are multiplied by 8 (i.e. shown
	   in bits instead of bytes) ... looks much more impressive :-)	It
	   also	affects	the 'factory default' labeling and units for the given

	   All the monitored variable values are multiplied by 60 (i.e.	shown
	   in units per	minute instead of units	per second) in case of small
	   values more accurate	graphs are displayed.  It also affects the
	   'factory default' labeling and units	for the	given target.

	   All the monitored variable values are multiplied by 3600 (i.e.
	   shown in units per hour instead of units per	second)	in case	of
	   small values	more accurate graphs are displayed.  It	also affects
	   the 'factory	default' labeling and units for	the given target.

	   Suppress the	information about uptime and device name in the
	   generated webpage.

	   Don't print usage percentages.

	   Make	the background of the generated	gifs transparent.

	   Print summary lines below graph as integers without commas.

	   The relative	percentage of IN-traffic to OUT-traffic	is calculated
	   and displayed in the	graph as an additional line.  Note: Only a
	   fixed scale is available (from 0 to 100%). Therefore	if IN-traffic
	   is greater than OUT-traffic then 100% is displayed.	If you suspect
	   that	your IN-traffic	is not always less than	or equal to your OUT-
	   traffic you are urged to not	use this options.  Note: If you	use
	   this	option in combination with the Colours options,	a fifth
	   colour-name colour-value pair is required there.

	   There are some ISPs who use the average Peak	values to bill their
	   customers.  Using this option MRTG displays these values for	each
	   graph. The value is built by	averaging the max 5 minute traffic
	   average for each 'step' shown in the	graph. For the Weekly graph
	   this	means that it builds the average of all	2 hour intervals 5
	   minute peak values. (Confused? Thought so!)

	   Treat the values gathered from target as 'current status'
	   measurements	and not	as ever	incrementing counters.	This would be
	   useful to monitor things like disk space, processor load,
	   temperature,	and the	like ...

	   In the absence of 'gauge' or	'absolute' options, MRTG treats
	   variables as	a counters and calculates the difference between the
	   current and the previous value and divides that by the elapsed time
	   between the last two	readings to get	the value to be	plotted.

	   This	is for counter type data sources which reset their value when
	   they	are read. This means that rateup does not have to build	the
	   difference between the current and the last value read from the
	   data	source.	The value obtained is still divided by the elapsed
	   time	between	the current and	the last reading, which	makes it
	   different from the 'gauge' option. Useful for external data

	   If you are using rrdtool as logger/grapher you can use a third type
	   of data source. Derive is like counter, except that it is not
	   required to go UP all the time. It is useful	for situations where
	   the change of some value should be graphed.

	   Log unknown data as zero instead of the default behaviour of
	   repeating the last value seen. Be careful with this,	often a	flat
	   line	in the graph is	much more obvious than a line at 0.

	   Normally we ignore all values which are zero	when calculating the
	   average transfer rate on a line. If this is not desirable use this

	   If you are using rateup to log data,	MRTG will create the graph
	   images.  Normally these images have a shaded	border around them. If
	   you do not want the border to be drawn, enable this option. This
	   option has no effect	if you are not using rateup.

	   As with the option above, this effects rateup graph generation
	   only. Normally rateup will generate graphs with a small arrow
	   showing the direction of the	data. If you do	not want this arrow to
	   be drawn, enable this option. This option has no effect if you are
	   not using rateup.

       noi When	using rateup for graph generation, you can use this option to
	   stop	rateup drawing a graph for the 'I' or first variable. This
	   also	removes	entries	for this variable in the HTML page MRTG
	   generates, and will remove the peaks	for this variable if they are
	   enabled. This allows	you to hide this data, or can be very useful
	   if you are only graphing one	line of	data rather than two.  This
	   option is not destructive - any data	received for the the variable
	   continued to	be logged, it just isn't shown.

       noo Same	as above, except relating to the 'O' or	second variable.

	   When	using rateup for graph generation, this	option disables	MRTG
	   adding the MRTG banner to the HTML pages it generates.

	   When	using rateup for graph generation, this	option will stop MRTG
	   from	creating a legend at the bottom	of the HTML pages it

	   When	using rateup for graph generation, this	option will print the
	   router name in the graph it generates.  This	option is overridden
	   by the value	of PNGTitle if one is given

	   When	using rateup for graph generation, this	option will print a
	   timestamp in	the graph it generates,	including a timezone if	one is
	   specified by	the 'Timezone' parameter. This is aequivalent to
	   setting TimeStrPost[x]: RU

	   The logscale	option causes rateup to	display	the data with the Y
	   axis	scaled logarithmically.	 Doing so allows the normal traffic to
	   occupy the majority of the vertical range, while still showing any
	   spikes at their full	height.

	   logscale displays all the available data and	will always produce
	   well-behaved	graphs.	 People	often consider a logarithmically
	   scaled graph	counterintuitive, however, and thus hard to interpret.

	   The expscale	option causes rateup to	display	the data with the Y
	   axis	scaled exponentially.  Doing so	emphasizes small changes at
	   the top of the scale; this can be useful when graphing values that
	   fluctuate by	a small	amount near the	top of the scale, such as line

	   expscale is essentially the inverse of logscale.

	   The secondmean option sets the maximum value	on the graph to	the
	   mean	of the data greater than the mean of all data.	This produces
	   a graph that	focuses	more on	the typical data, while	clipping large

	   Using secondmean will give a	more intutive linearly scaled graph,
	   but can result in a uselessly high or low scale in some rare
	   situations (specifically, when the data includes a large portion of
	   values far from the actual mean)

	   If a	target includes	both logscale and secondmean in	the options,
	   the secondmean takes	precedence.


	Options[myrouter]: growright, bits

       Use this	option to change the multiplier	value for building prefixes.
       Defaultvalue is 1000. This tag is for the special case that 1kB =
       1024B, 1MB = 1024kB and so far.


	kilo[myrouter]:	1024

       Change the default multiplier prefixes (,k,M,G,T,P). In the tag
       ShortLegend define only the basic units.	 Format: Comma separated list
       of prefixed. Two	consecutive commas or a	comma at start or end of the
       line gives no prefix on this item.  If you do not want prefixes,	just
       put two consecutive commas.  If you want	to skip	a magnitude select '-'
       as value.

       Example:	velocity in nm/s (nanometers per second) displayed in nm/h.

	ShortLegend[myrouter]: m/h
	kMG[myrouter]: n,u,m,,k,M,G,T,P
	options[myrouter]: perhour

       The Colours tag allows you to override the default colour scheme.
       Note: All 4 of the required colours must	be specified here. The colour
       name ('Colourx' below) is the legend name displayed, while the RGB
       value is	the real colour	used for the display, both on the graph	and in
       the html	doc.

       Format is: Col1#RRGGBB,Col2#RRGGBB,Col3#RRGGBB,Col4#RRGGBB

       Important: If you use the dorelpercent options tag a fifth colour name
       colour value pair is required:

	   First variable (normally Input) on default graph.

	   Second variable (normally Output) on	default	graph.

	   Max first variable (input).

	   Max second variable (output).

	   2 digit hex values for Red, Green and Blue.


	Colours[myrouter]: GREEN#00eb0c,BLUE#1000ff,DARK GREEN#006600,VIOLET#ff00ff

       With the	Background tag you can configure the background	colour of the
       generated HTML page.


	Background[myrouter]: #a0a0a0a

   YLegend, ShortLegend, Legend[1234]
       The following keywords allow you	to override the	text displayed for the
       various legends of the graph and	in the HTML document:

	   The Y-axis label of the graph. Note that a text which is too	long
	   to fit in the graph will be silently	ignored.

	   The units string (default 'b/s') used for Max, Average and Current

	   The strings for the colour legend.


	 YLegend[myrouter]: Bits per Second
	 ShortLegend[myrouter]:	b/s
	 Legend1[myrouter]: Incoming Traffic in	Bits per Second
	 Legend2[myrouter]: Outgoing Traffic in	Bits per Second
	 Legend3[myrouter]: Maximal 5 Minute Incoming Traffic
	 Legend4[myrouter]: Maximal 5 Minute Outgoing Traffic
	 LegendI[myrouter]: &nbsp;In:
	 LegendO[myrouter]: &nbsp;Out:

       Note, if	LegendI	or LegendO are set to an empty string with


       The corresponding line below the	graph will not be printed at all.

       If you live in an international world, you might	want to	generate the
       graphs in different timezones. This is set in the TZ variable. Under
       certain operating systems like Solaris, this will provoke the localtime
       call to give the	time in	the selected timezone.


	Timezone[myrouter]: Japan

       The Timezone is the standard timezone of	your system, ie	Japan,
       Hongkong, GMT, GMT+1 etc	etc.

       By default, mrtg	(actually rateup) uses the strftime(3) '%V' option to
       format week numbers in the monthly graphs.  The exact semantics of this
       format option vary between systems.  If you find	that the week numbers
       are wrong, and your system's strftime(3)	routine	supports it, you can
       try another format option.  The POSIX '%V' option correspond to the
       widely used ISO 8601 week numbering standard.  The week format
       character should	be specified as	a single letter; either	W, V, or U.

       The UNIX	version	of rateup uses the libc	implementation of strftime.
       On Windows, the native strftime implementation does not know about %V.
       So there	we use a different implementation of strftime that does
       support %V.


	Weekformat[myrouter]: W

       This affects the	creation of new	rrd files. By default rrds are created
       to hold about 1 day's worth of high resolution data. (plus 1 week of 30
       minute data, 2 months of	2 hour data and	2 years	of 1 day data).	 With
       this Keyword you	can change the number of base interval entries
       configured for new rrds as they get created. Note that you must take
       the interval time into account.


	RRDRowCount[myrouter]: 1600

       As per RRDRowCount, but for the RRA's -typically- used for 30 minute
       data.  Even so, you must	still take the base interval into account.
       Leaving out this	keyword	will force the old default of 800 rows.


	RRDRowCount30m[myrouter]: 800

       As per RRDRowCount, but for the RRA's -typically- used for 2 hour data.
       Even so,	you must still take the	base interval into account.  Leaving
       out this	keyword	will force the old default of 800 rows.


	RRDRowCount2h[myrouter]: 400

       As per RRDRowCount, but for the RRA's -typically- used for 1 day	data.
       Even so,	you must still take the	base interval into account.  Leaving
       out this	keyword	will force the old default of 800 rows.


	RRDRowCount1d[myrouter]: 200

       Normally	the RRDs created by MRTG will just contain the information
       gathered	directly from the respective target. With this option you can
       tap into	rrdtools advanced aberrant behaviour detection module based on
       Holt-Winters forecasting. The RRDHWRRAs property	specifies the Holt-
       Winters RRAs as described in the	rrdcreate manual page.

       Note, this setting will only affect newly created RRDs (targets).


	RRDHWRRAs[myrouter]: RRA:HWPREDICT:1440:0.1:0.0035:288

       This defines placement of the timestamp string on the image. Possible
       values are RU, LU, RL, LL (which	stand, respectively, for RightUpper,
       LeftUpper, RightLower and LeftLower corner) and NO (for no timestamp).
       By default, no timestamp	is placed on the image.


	TimeStrPos[myrouter]: RU

       Using this keyword you may specify format of the	timestamp to be	placed
       on the image (if	enabled	by the TimeStrPos keyword). Specified string
       will be used by the strftime() function - see strftime(3) documentation
       for conversion specifiers available on your system.  Default format:
       %Y-%m-%d	%H:%M


	TimeStrFmt[myrouter]: %H:%M:%S

       Through its threshold checking functionality mrtg is able to detect
       threshold problems for the various targets and can call external
       scripts to handle those problems	(e.g. send email or a page to an

       Threshold checking is configured	through	the following parameters:

   ThreshDir (GLOBAL)
       By defining ThreshDir to	point to a writable directory, MRTG will only
       alert you when a	threshold boundary has been crossed.


	ThreshDir: /var/mrtg/thresh

   ThreshHyst (GLOBAL)
       If a threshold is broken, and you have a	threshdir defined, then	mrtg
       will send mail once the threshold becomes 'unborken' to avoid
       situations where	broken and unbroken messages get sent in close
       succession, we only send	an unbroken message once the curent value is
       0.1 (10%) away from the threshold.  using the ThreshHyst	config
       variable	you can	customize this value.

       Example for 5%:

	ThreshHyst: 0.05

   ThreshMailServer (GLOBAL)
       Adderss of an SMTP server which is going	to accept mail about
       Thresholds being	broken and unbroken.

   ThreshMailSender (GLOBAL)
       What is the sender address of the threshold mail.



   ThreshMailAddress (PER TARGET)
       Email address for Threshold related Mails. This will only work if a
       mailserver has been configured.



       This would bring	threshold releaed mail to all but the target called

   ThreshMinI  (PER TARGET)
       This is the minimum acceptable value for	the Input (first) parameter.
       If the parameter	falls below this value,	the program specified in
       ThreshProgI will	be run and a mail will be sent to the
       ThreshMailAddress if specified.	If the value ends in '%' then the
       threshold is defined relative to	MaxBytes.

   ThreshMaxI (PER TARGET)
       Works the same as TheshMinI but it acts when the	value is higher	than

   ThreshDesc (PER TARGET)
       Its value will be assigned to the environment variable THRESH_DESC
       before any of the programs mentioned below are called. The programs can
       use the value of	this variable to produce more user-friendly output.

   ThreshProgI	(PER TARGET)
       This defines a program to be run	if ThreshMinI or ThreshMaxI is broken.
       MRTG passes 3 arguments:	the $router variable, the threshold value
       broken, and the current parameter value.

   ThreshProgOKI  (PER TARGET)
       This defines a program to be run	if the parameter is currently OK
       (based on ThreshMinI and	ThreshMaxI), but wasn't	OK on the previous
       running -- based	on the files found in ThreshDir. MRTG passes 3
       arguments: the $router variable the unbroken threshold value, and the
       current parameter value.

   ThreshMinO, ThreshMaxO, ThreshProgO,	and ThreshProgOKO
       These work the same as their *I counterparts, except on the Output
       (second)	parameter.

       When calling threshold scripts from within your cfg file	you might want
       to pass some data on to the script. This	can be done with the SetEnv
       configuration option which takes	a series of environment	variable
       assignments. Note that the quotes are mandatory.	This does not work for
       external	scripts. It is not possible to set environment variables per


	SetEnv[myrouter]:  EMAIL=""

   HW Failure Bassed Threshold Checking
       When using rrd based logging with HW RRAs defined. You can use the
       confidence bounds violations stored in the FAILURES RRA for threshold
       based alerts.

       There the all target specific threshold variables have a	Hold-Winters

	ThreshMailAddress -> HWThreshMailAddress
	ThreshMinI	  -> HWThreshMinI

       The global variables for	threshold checking are shared except for the

	ThreshHyst	  -> HWThreshHyst

       And HWThreshDesc	sets the HWTHRESH_DESC variable.

   Pre-	and Postfix
       To save yourself	some typing you	can define a target called '^'.	The
       text of every Keyword you define	for this target	will be	PREPENDED to
       the corresponding Keyword of all	the targets defined below this line.
       The same	goes for a Target called '$' but its text will be APPENDED.

       Note that a space is inserted between the prepended text	and the
       Keyword value, as well as between the Keyword value and the appended
       text. This works	well for text-valued Keywords, but is not very useful
       for other Keywords. See the "default" target description	below.

       The example will	make mrtg use a	common header and a common contact
       person in all the pages generated from targets defined later in this


	PageTop[^]: <H1>NoWhere	Unis Traffic Stats</H1><HR>
	PageTop[$]: Contact Peter Norton if you	have any questions<HR>

       To remove the prepend/append value, specify an empty value, e.g.:


       With PREPEND and	APPEND (see below) there is normally a space inserted
       between the local value and the PRE- or APPEND value. Sometimes this is
       not desirable. You can use the global option NoSpaceChar	to define a
       character which can be mentioned	at the end of a	$ or ^ definition in
       order to	supress	the space.


	 NoSpaceChar: ~

   Default Values
       The target name '_' specifies a default value for that Keyword. In the
       absence of explicit Keyword value, the prepended	and the	appended
       keyword value, the default value	will be	used.


	YSize[_]: 150
	Options[_]: growright,bits,nopercent
	WithPeak[_]: ymw
	Suppress[_]: y
	MaxBytes[_]: 1250000

       To remove the default value and return to the 'factory default',
       specify an empty	value, e.g.:


       There can be several instances of setting the default/prepend/append
       values in the configuration file. The later setting replaces the
       previous	one for	the rest of the	configuration file.  The
       default/prepend/append values used for a	given keyword/target pair are
       the ones	that were in effect at the point in the	configuration file
       where the target	was mentioned for the first time.


	MaxBytes[_]: 1250000
	MaxBytes[_]: 8000
	Title[]:	Traffic	Analysis for IF 2

       The default MaxBytes for	the target in the
       above example will be 1250000, which was	in effect where	the target
       name first appeared in the config file.

       --user username	and --group groupname
	   Run as the given user and/or	group. (Unix Only)

       --lock-file filename
	   Use an alternate lock-file (the default is to use the
	   configuration-file appended with "_l").

       --confcache-file	filename
	   Use an alternate confcache-file (the	default	is to use the
	   configuration-file appended with ".ok")

       --logging filename|eventlog
	   If this is set to writable filename,	all output from	mrtg
	   (warnings, debug messages, errors) will go to filename. If you are
	   running on Win32 you	can specify eventlog instead of	a filename
	   which will send all error to	the windows event log.

	   NOTE: Note, there is	no Message DLL for mrtg	included with mrtg.
	   This	has the	side effect that the windows event logger will display
	   a nice message with every entry in the event	log, complaing about
	   the fact that mrtg has no message dll. If you go to the mrtg
	   contrib download area (on the website) you will find	the	which does contain such	a thing.

	   Put MRTG into the background, running as a daemon. This works the
	   same	way as the config file option, but the switch is required for
	   proper FHS operation	(because /var/run is writable only by root)

	   Configure all mrtg paths to conform to the FHS specification;

	   Only	check the cfg file for errors. Do not do anything.

	   Define the name and path of the pid file for	mrtg running as	a

	   Enable debug	options. The argument of the debug option is a comma
	   separated list of debug values:

	    cfg	 - watch the config file reading
	    dir	 - directory mangeling
	    base - basic program flow
	    tarp - target parser
	    snpo - snmp	polling
	    coca - confcache operations
	    fork - forking view
	    time - some	timing info
	    log	 - logging of data via rateup or rrdtool
	    eval - print eval strings before evaluting them
	    prof - add hires timing info the rrd calls



       An exit code of 0 indicates that	all targets were successful.
       Generally speaking, most	codes greater than 0 indicate that there was
       an unrecoverable	problem.  One exception	to this	is code	91, which
       indicates that at least one of the targets was successful.  A partial
       listing of the codes follows:

	 0: All	targets	sucessful

	 2: Config error (can't	read, fatal error in config, etc)
	17: Another MRTG process is processing config

	91: At least one target	sucessful
	92: No targets were sucessful

   Minimal mrtg.cfg
	WorkDir: /usr/tardis/pub/www/stats/mrtg
	MaxBytes[r1]: 8000
	Title[r1]: Traffic Analysis ISDN
	PageTop[r1]: <H1>Stats for our ISDN Line</H1>

   Cfg for several Routers.
	WorkDir: /usr/tardis/pub/www/stats/mrtg
	Title[^]: Traffic Analysis for
	PageTop[^]: <H1>Stats for
	PageTop[$]: Contact The	Chief if you notice anybody<HR>
	MaxBytes[_]: 8000
	Options[_]: growright

	Title[isdn]: our ISDN Line
	PageTop[isdn]: our ISDN	Line</H1>

	Title[backb]: our Campus Backbone
	PageTop[backb]:	our Campus Backbone</H1>
	MaxBytes[backb]: 1250000

	# the following	line removes the default prepend value
	# defined above


	Title[isdn2]: Traffic for the Backup ISDN Line
	PageTop[isdn2]:	our ISDN Line</H1>

       Tobias Oetiker <>	and many contributors

2.17.4				  2012-01-12		     MRTG-REFERENCE(1)


Want to link to this manual page? Use this URL:

home | help