1doc::mrtglib(3) mrtg doc::mrtglib(3)
2
6 MRTG_lib.pm - Library for MRTG and support scripts
7
9 use MRTG_lib;
10 my ($configfile, @target_names, %globalcfg, %targetcfg);
11 readcfg($configfile, \@target_names, \%globalcfg, \%targetcfg);
12 my (@parsed_targets);
13 cfgcheck(\@target_names, \%globalcfg, \%targetcfg, \@parsed_targets);
14
16 MRTG_lib is part of MRTG, the Multi Router Traffic Grapher. It was
17 separated from MRTG to allow other programs to easily use the same
18 config files. The main part of MRTG_lib is the config file parser but
19 some other functions are there too.
20 $MRTG_lib::OS
22 Type of OS: WIN, UNIX, VMS
23 $MRTG_lib::SL
25 Slash in the current OS.
26 $MRTG_lib::PS
28 Path separator in PATH variable
29 "readcfg"
31 "readcfg($file, \@targets, \%globalcfg, \%targetcfg [, $prefix,
32 \%extrules])"
33 Reads a config file, parses it and fills some arrays and hashes.
35 The mandatory arguments are: the name of the config file, a ref to
36 an array which will be filled with a list of the target names, a
37 hashref for the global configuration, a hashref for the target
38 configuration.
39 The configuration file syntax is:
41 globaloption: value
43 targetoption[targetname]: value
44 aprefix*extglobal: value
45 aprefix*exttarget[target2]: value
46 E.g.
48 workdir: /var/stat/mrtg
50 target[router1]: 2:public@router1.local.net
51 14all*columns: 2
52 The global config hash has the structure
54 $globalcfg{configoption} = 'value'
56 The target config hash has the structure
58 $targetcfg{configoption}{targetname} = 'value'
60 See mrtg-reference for more information about the MRTG
62 configuration syntax.
63 "readcfg" can take two additional arguments to extend the config
65 file syntax. This allows programs to put their configuration into
66 the mrtg config file. The fifth argument is the prefix of the
67 extension, the sixth argument is a hash with the checkrules for
68 these extension settings. E.g. if the prefix is "14all" "readcfg"
69 will check config lines that begin with "14all*", i.e. all lines
70 like
71 14all*columns: 2
73 14all*graphsize[target3]: 500 200
74 against the rules in %extrules. The format of this hash is:
76 $extrules{option} = [sub{$_[0] =~ m/^\d+$/}, sub{"Error message for $_[0]"}]
78 i.e.
79 $extrules{option}[0] -> a test expression
80 $extrules{option}[1] -> error message if test fails
81 The first part of the array is a perl expression to test the value
83 of the option. The test can access this value in the variable
84 "$arg". The second part of the array is an error message to display
85 when the test fails. The failed value can be integrated by using
86 the variable "$arg".
87 Config settings with an different prefix than the one given in the
89 "readcfg" call are not checked but inserted into %globalcfg and
90 %targetcfg. Prefixed settings keep their prefix in the config
91 hashes:
92 $targetcfg{'14all*graphsize'}{'target3'} = '500 200'
94 "cfgcheck"
96 "cfgcheck(\@target_names, \%globalcfg, \%targetcfg,
97 \@parsed_targets)"
98 Checks the configuration read by "readcfg". Checks the values in
100 the config for syntactical and/or semantical errors. Sets defaults
101 for some options. Parses the "target[...]" options and files the
102 array @parsed_targets ready for mrtg functions.
103 The first three arguments are the same as for "readcfg". The fourth
105 argument is an arrayref which will be filled with the parsed target
106 defs.
107 "cfgcheck" converts the values of target settings options, e.g.
109 options[router1]: bits, growright
111 to a hash:
113 $targetcfg{'option'}{'bits'}{'router1'} = 1
115 $targetcfg{'option'}{'growright'}{'router1'} = 1
116 This is not done by "readcfg" so if you don't use "cfgcheck" you
118 have to check the scalar variable $targetcfg{'option'}{'router1'}
119 (MRTG allows options to be separated by space or ',').
120 "ensureSL"
122 "ensureSL(\$pathname)"
123 Checks that the pathname does not contain double path separators
125 and ends with a path separator. It uses $MRTG_lib::SL as path
126 separator which will be / or \ depending on the OS.
127 "log2rrd"
129 "log2rrd ($router,\%globalcfg,\%targetcfg)"
130 Convert log file to rrd format. Needs rrdtool.
132 "datestr"
134 "datestr(time)"
135 Returns the time given in the argument as a nicely formatted date
137 string. The argument has to be in UNIX time format (seconds since
138 1970-1-1).
139 "timestamp"
141 "timestamp()"
142 Return a string representing the current time.
144 "setup_loghandlers"
146 "setup_loghandlers(filename)"
147 Install signalhandlers for __DIE__ and __WARN__ making the errors
149 go the the specified destination. If filename is 'eventlog' mrtg
150 will log to the windows event logger.
151 "expistr"
153 "expistr(time)"
154 Returns the time given in the argument formatted suitable for HTTP
156 Expire-Headers.
157 "create_pid"
159 "create_pid()"
160 Creates a pid file for the mrtg daemon
162 "demonize_me"
164 "demonize_me()"
165 Puts the running program into background, detaching it from the
167 terminal.
168 "populatecache"
170 "populatecache(\%confcache, $host, $reread, $snmpoptshash)"
171 Reads the SNMP variables ifDescr, ipAdEntIfIndex, ifPhysAddress,
173 ifName from the host and stores the values in %confcache as
174 follows:
175 $confcache{$host}{'Descr'}{ifDescr}{oid} = (ifDescr or 'Dup')
177 $confcache{$host}{'IP'}{ipAdEntIfIndex}{oid} = (ipAdEntIfIndex or 'Dup')
178 $confcache{$host}{'Eth'}{ifPhysAddress}{oid} = (ifPhysAddress or 'Dup')
179 $confcache{$host}{'Name'}{ifName}{oid} = (ifName or 'Dup')
180 $confcache{$host}{'Type'}{ifType}{oid} = (ifType or 'Dup')
181 The value (at the right side of =) is 'Dup' if a value was
183 retrieved multiple times, the retrieved value else.
184 "readconfcache"
186 "my $confcache = readconfcache($file)"
187 Preload the confcache from a file.
189 "readfromconfcache"
191 "writeconfcache($confcache,$file)"
192 Store the current confcache into a file.
194 "writeconfcache"
196 "writeconfcache($confcache,$file)"
197 Store the current confcache into a file.
199 "storeincache"
201 "storeincache($confcache,$host,$method,$key,$value)"
202 "readfromcache"
204 "readfromcache($confcache,$host,$method,$key)"
205 "clearfromcache"
207 "clearfromcache($confcache,$host)"
208 "debug"
210 "debug($type, $message)"
211 Prints the message on STDERR if debugging is enabled for type type.
213 A debug type is enabled if type is in array @main::DEBUG.
214
216 Rainer Bawidamann <Rainer.Bawidamann@rz.uni-ulm.de>
217 (This Manpage)
2192.17.10 2022-01-19 doc::mrtglib(3)