doc::mrtglib(3)

💖 doc::mrtglib — the MRTG library page, bestie edition 💖

okay so this is a page from the mrtg manual — yes, that mrtg. it's a section 3 page, so it's all about a library. sit down, grab a strawberry 🍓, we're doing this.

---

✨ NAME ✨

MRTG_lib.pm — a whole library for MRTG and the lil support scripts that hang out with it 🫶

---

🌸 SYNOPSIS 🌸

use MRTG_lib;
my ($configfile, @target_names, %globalcfg, %targetcfg);
readcfg($configfile, \@target_names, \%globalcfg, \%targetcfg);
my (@parsed_targets);
cfgcheck(\@target_names, \%globalcfg, \%targetcfg, \@parsed_targets);

like. that's the whole vibe. pull it in, read the config, check the config. iconic behavior fr fr.

---

🦋 DESCRIPTION 🦋

MRTG_lib is part of MRTG, the Multi Router Traffic Grapher. the way it got split off from MRTG is so other programs could just... easily use the same config files?? like sharing is caring 💅. the main character of MRTG_lib is the config file parser, but there are a few other functions in there too, no cap.

💜 $MRTG_lib::OS

what kind of OS are we on: WIN, UNIX, VMS

💜 $MRTG_lib::SL

the slash in the current OS. yes it changes. it's giving adaptable ✨

💜 $MRTG_lib::PS

the path separator in the PATH variable

👑 readcfg

readcfg($file, \@targets, \%globalcfg, \%targetcfg [, $prefix, \%extrules])

this one reads a config file, parses it, and fills some arrays and hashes. slay.

the mandatory arguments are:

• the name of the config file
• a ref to an array which will be filled with a list of the target names
• a hashref for the global configuration
• a hashref for the target configuration

the configuration file syntax is:

globaloption: value
targetoption[targetname]: value
aprefix*extglobal: value
aprefix*exttarget[target2]: value

E.g.

workdir: /var/stat/mrtg
target[router1]: 2:public@router1.local.net
14all*columns: 2

the global config hash has the structure

$globalcfg{configoption} = 'value'

the target config hash has the structure

$targetcfg{configoption}{targetname} = 'value'

see mrtg-reference for more info about the MRTG configuration syntax 📚

now — readcfg can take two additional arguments to extend the config file syntax. this is the glow-up that lets programs put their own configuration into the mrtg config file. the fifth argument is the prefix of the extension, and the sixth argument is a hash with the checkrules for these extension settings. E.g. if the prefix is 14all, readcfg will check config lines that begin with 14all*, i.e. all lines like

14all*columns: 2
14all*graphsize[target3]: 500 200

against the rules in %extrules. the format of this hash is:

$extrules{option} = [sub{$_[0] =~ m/^\d+$/}, sub{"Error message for $_[0]"}]
    i.e.
$extrules{option}[0] -> a test expression
$extrules{option}[1] -> error message if test fails

the first part of the array is a perl expression to test the value of the option. the test can access this value in the variable $arg. the second part of the array is an error message to display when the test fails. the failed value can be integrated by using the variable $arg.

config settings with a different prefix than the one given in the readcfg call are not checked — they just get inserted into %globalcfg and %targetcfg. prefixed settings keep their prefix in the config hashes:

$targetcfg{'14all*graphsize'}{'target3'} = '500 200'

👑 cfgcheck

cfgcheck(\@target_names, \%globalcfg, \%targetcfg, \@parsed_targets)

checks the configuration read by readcfg. it checks the values in the config for syntactical and/or semantical errors. it sets defaults for some options. and it parses the target[...] options and files the array @parsed_targets ready for mrtg functions. multitasking queen 💅

the first three arguments are the same as for readcfg. the fourth argument is an arrayref which will be filled with the parsed target defs.

cfgcheck converts the values of target settings options, e.g.

options[router1]: bits, growright

to a hash:

$targetcfg{'option'}{'bits'}{'router1'} = 1
$targetcfg{'option'}{'growright'}{'router1'} = 1

this is not done by readcfg, so if you don't use cfgcheck you have to check the scalar variable $targetcfg{'option'}{'router1'} (MRTG allows options to be separated by space or ,). iykyk.

🌈 ensureSL

ensureSL(\$pathname)

checks that the pathname does not contain double path separators and ends with a path separator. it uses $MRTG_lib::SL as path separator, which will be / or \ depending on the OS. flexible icon.

🌈 log2rrd

log2rrd ($router,\%globalcfg,\%targetcfg)

convert log file to rrd format. needs rrdtool.

🌈 datestr

datestr(time)

returns the time given in the argument as a nicely formatted date string. the argument has to be in UNIX time format (seconds since 1970-1-1). cute AND precise ✨

🌈 timestamp

timestamp()

return a string representing the current time. it's giving right now ⏰

🌈 setup_loghandlers

setup_loghandlers(filename)

install signalhandlers for __DIE__ and __WARN__ making the errors go the the specified destination. if filename is 'eventlog' mrtg will log to the windows event logger.

🌈 expistr

expistr(time)

returns the time given in the argument formatted suitable for HTTP Expire-Headers.

🌈 create_pid

create_pid()

creates a pid file for the mrtg daemon

🌈 demonize_me

demonize_me()

puts the running program into background, detaching it from the terminal. going ghost mode 🫥 (yes, the function is spelled demonize_me, that's just the name, don't @ me)

🧚 populatecache

populatecache(\%confcache, $host, $reread, $snmpoptshash)

reads the SNMP variables ifDescr, ipAdEntIfIndex, ifPhysAddress, ifName from the host and stores the values in %confcache as follows:

$confcache{$host}{'Descr'}{ifDescr}{oid} = (ifDescr or 'Dup')
$confcache{$host}{'IP'}{ipAdEntIfIndex}{oid} = (ipAdEntIfIndex or 'Dup')
$confcache{$host}{'Eth'}{ifPhysAddress}{oid} = (ifPhysAddress or 'Dup')
$confcache{$host}{'Name'}{ifName}{oid} = (ifName or 'Dup')
$confcache{$host}{'Type'}{ifType}{oid} = (ifType or 'Dup')

the value (at the right side of =) is 'Dup' if a value was retrieved multiple times, the retrieved value else.

🧚 readconfcache

my $confcache = readconfcache($file)

preload the confcache from a file.

🧚 readfromconfcache

writeconfcache($confcache,$file)

store the current confcache into a file.

bestie. bestie look at me. yes, the page really does print writeconfcache under this heading. i'm just the messenger 🙈 keeping it exactly as it's written.

🧚 writeconfcache

writeconfcache($confcache,$file)

store the current confcache into a file.

🧚 storeincache

storeincache($confcache,$host,$method,$key,$value)

🧚 readfromcache

readfromcache($confcache,$host,$method,$key)

🧚 clearfromcache

clearfromcache($confcache,$host)

🎀 debug

debug($type, $message)

prints the message on STDERR if debugging is enabled for type type. a debug type is enabled if type is in array @main::DEBUG.

---

🌟 AUTHORS 🌟

Rainer Bawidamann <Rainer.Bawidamann@rz.uni-ulm.de>

(This Manpage)

---

and that's the whole thing, bestie, we ate and left no crumbs 💖 the page is from version 2.17.10, dated 2022-01-19 — shoutout to that exact moment in time, you were everything ✨🌸🦋