1doc::mrtglib(3)                      mrtg                      doc::mrtglib(3)
2
3
4

NAME

6       MRTG_lib.pm - Library for MRTG and support scripts
7

SYNOPSIS

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

DESCRIPTION

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
21       $MRTG_lib::OS
22           Type of OS: WIN, UNIX, VMS
23
24       $MRTG_lib::SL
25           Slash in the current OS.
26
27       $MRTG_lib::PS
28           Path separator in PATH variable
29
30       "readcfg"
31           "readcfg($file, \@targets, \%globalcfg, \%targetcfg [, $prefix,
32           \%extrules])"
33
34           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
40           The configuration file syntax is:
41
42            globaloption: value
43            targetoption[targetname]: value
44            aprefix*extglobal: value
45            aprefix*exttarget[target2]: value
46
47           E.g.
48
49            workdir: /var/stat/mrtg
50            target[router1]: 2:public@router1.local.net
51            14all*columns: 2
52
53           The global config hash has the structure
54
55            $globalcfg{configoption} = 'value'
56
57           The target config hash has the structure
58
59            $targetcfg{configoption}{targetname} = 'value'
60
61           See mrtg-reference for more information about the MRTG
62           configuration syntax.
63
64           "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
72            14all*columns: 2
73            14all*graphsize[target3]: 500 200
74
75           against the rules in %extrules. The format of this hash is:
76
77            $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
82           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
88           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
93            $targetcfg{'14all*graphsize'}{'target3'} = '500 200'
94
95       "cfgcheck"
96           "cfgcheck(\@target_names, \%globalcfg, \%targetcfg,
97           \@parsed_targets)"
98
99           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
104           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
108           "cfgcheck" converts the values of target settings options, e.g.
109
110            options[router1]: bits, growright
111
112           to a hash:
113
114            $targetcfg{'option'}{'bits'}{'router1'} = 1
115            $targetcfg{'option'}{'growright'}{'router1'} = 1
116
117           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
121       "ensureSL"
122           "ensureSL(\$pathname)"
123
124           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
128       "log2rrd"
129           "log2rrd ($router,\%globalcfg,\%targetcfg)"
130
131           Convert log file to rrd format. Needs rrdtool.
132
133       "datestr"
134           "datestr(time)"
135
136           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
140       "timestamp"
141           "timestamp()"
142
143           Return a string representing the current time.
144
145       "setup_loghandlers"
146           "setup_loghandlers(filename)"
147
148           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
152       "expistr"
153           "expistr(time)"
154
155           Returns the time given in the argument formatted suitable for HTTP
156           Expire-Headers.
157
158       "create_pid"
159           "create_pid()"
160
161           Creates a pid file for the mrtg daemon
162
163       "demonize_me"
164           "demonize_me()"
165
166           Puts the running program into background, detaching it from the
167           terminal.
168
169       "populatecache"
170           "populatecache(\%confcache, $host, $reread, $snmpoptshash)"
171
172           Reads the SNMP variables ifDescr, ipAdEntIfIndex, ifPhysAddress,
173           ifName from the host and stores the values in %confcache as
174           follows:
175
176            $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
182           The value (at the right side of =) is 'Dup' if a value was
183           retrieved multiple times, the retrieved value else.
184
185       "readconfcache"
186           "my $confcache = readconfcache($file)"
187
188           Preload the confcache from a file.
189
190       "readfromconfcache"
191           "writeconfcache($confcache,$file)"
192
193           Store the current confcache into a file.
194
195       "writeconfcache"
196           "writeconfcache($confcache,$file)"
197
198           Store the current confcache into a file.
199
200       "storeincache"
201           "storeincache($confcache,$host,$method,$key,$value)"
202
203       "readfromcache"
204           "readfromcache($confcache,$host,$method,$key)"
205
206       "clearfromcache"
207           "clearfromcache($confcache,$host)"
208
209       "debug"
210           "debug($type, $message)"
211
212           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

AUTHORS

216       Rainer Bawidamann <Rainer.Bawidamann@rz.uni-ulm.de>
217
218       (This Manpage)
219
220
221
2222.17.10                           2022-01-19                   doc::mrtglib(3)
Impressum