diff --git a/src/doc/mrtg-mailer.pod b/src/doc/mrtg-mailer.pod new file mode 120000 index 0000000..16c3bde --- /dev/null +++ b/src/doc/mrtg-mailer.pod @@ -0,0 +1 @@ +../bin/mrtg-mailer \ No newline at end of file diff --git a/src/doc/mrtglib.3 b/src/doc/mrtglib.3 new file mode 100644 index 0000000..1bb2def --- /dev/null +++ b/src/doc/mrtglib.3 @@ -0,0 +1,386 @@ +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "doc::mrtglib 3" +.TH doc::mrtglib 3 "2022-01-18" "2.17.9" "mrtg" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +MRTG_lib.pm \- Library for MRTG and support scripts +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 5 +\& use MRTG_lib; +\& my ($configfile, @target_names, %globalcfg, %targetcfg); +\& readcfg($configfile, \e@target_names, \e%globalcfg, \e%targetcfg); +\& my (@parsed_targets); +\& cfgcheck(\e@target_names, \e%globalcfg, \e%targetcfg, \e@parsed_targets); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +MRTG_lib is part of \s-1MRTG,\s0 the Multi Router Traffic Grapher. It was separated +from \s-1MRTG\s0 to allow other programs to easily use the same config files. The +main part of MRTG_lib is the config file parser but some other functions are +there too. +.ie n .IP "$MRTG_lib::OS" 4 +.el .IP "\f(CW$MRTG_lib::OS\fR" 4 +.IX Item "$MRTG_lib::OS" +Type of \s-1OS: WIN, UNIX, VMS\s0 +.ie n .IP "$MRTG_lib::SL" 4 +.el .IP "\f(CW$MRTG_lib::SL\fR" 4 +.IX Item "$MRTG_lib::SL" +\&\fISlash\fR in the current \s-1OS.\s0 +.ie n .IP "$MRTG_lib::PS" 4 +.el .IP "\f(CW$MRTG_lib::PS\fR" 4 +.IX Item "$MRTG_lib::PS" +Path separator in \s-1PATH\s0 variable +.ie n .IP """readcfg""" 4 +.el .IP "\f(CWreadcfg\fR" 4 +.IX Item "readcfg" +\&\f(CW\*(C`readcfg($file, \e@targets, \e%globalcfg, \e%targetcfg [, $prefix, \e%extrules])\*(C'\fR +.Sp +Reads a config file, parses it and fills some arrays and hashes. 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. +.Sp +The configuration file syntax is: +.Sp +.Vb 4 +\& globaloption: value +\& targetoption[targetname]: value +\& aprefix*extglobal: value +\& aprefix*exttarget[target2]: value +.Ve +.Sp +E.g. +.Sp +.Vb 3 +\& workdir: /var/stat/mrtg +\& target[router1]: 2:public@router1.local.net +\& 14all*columns: 2 +.Ve +.Sp +The global config hash has the structure +.Sp +.Vb 1 +\& $globalcfg{configoption} = \*(Aqvalue\*(Aq +.Ve +.Sp +The target config hash has the structure +.Sp +.Vb 1 +\& $targetcfg{configoption}{targetname} = \*(Aqvalue\*(Aq +.Ve +.Sp +See mrtg-reference for more information about the \s-1MRTG\s0 configuration syntax. +.Sp +\&\f(CW\*(C`readcfg\*(C'\fR can take two additional arguments to extend the config file +syntax. This allows programs to put their configuration into the mrtg config +file. The fifth argument is the prefix of the extension, the sixth argument +is a hash with the checkrules for these extension settings. E.g. if the +prefix is \*(L"14all\*(R" \f(CW\*(C`readcfg\*(C'\fR will check config lines that begin with +\&\*(L"14all*\*(R", i.e. all lines like +.Sp +.Vb 2 +\& 14all*columns: 2 +\& 14all*graphsize[target3]: 500 200 +.Ve +.Sp +against the rules in \f(CW%extrules\fR. The format of this hash is: +.Sp +.Vb 4 +\& $extrules{option} = [sub{$_[0] =~ m/^\ed+$/}, sub{"Error message for $_[0]"}] +\& i.e. +\& $extrules{option}[0] \-> a test expression +\& $extrules{option}[1] \-> error message if test fails +.Ve +.Sp +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 \*(L"$arg\*(R". 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 \*(L"$arg\*(R". +.Sp +Config settings with an different prefix than the one given in the \f(CW\*(C`readcfg\*(C'\fR +call are not checked but inserted into \fI\f(CI%globalcfg\fI\fR and \fI\f(CI%targetcfg\fI\fR. +Prefixed settings keep their prefix in the config hashes: +.Sp +.Vb 1 +\& $targetcfg{\*(Aq14all*graphsize\*(Aq}{\*(Aqtarget3\*(Aq} = \*(Aq500 200\*(Aq +.Ve +.ie n .IP """cfgcheck""" 4 +.el .IP "\f(CWcfgcheck\fR" 4 +.IX Item "cfgcheck" +\&\f(CW\*(C`cfgcheck(\e@target_names, \e%globalcfg, \e%targetcfg, \e@parsed_targets)\*(C'\fR +.Sp +Checks the configuration read by \f(CW\*(C`readcfg\*(C'\fR. Checks the values in the config +for syntactical and/or semantical errors. Sets defaults for some options. +Parses the \*(L"target[...]\*(R" options and files the array \f(CW@parsed_targets\fR ready +for mrtg functions. +.Sp +The first three arguments are the same as for \f(CW\*(C`readcfg\*(C'\fR. The fourth argument +is an arrayref which will be filled with the parsed target defs. +.Sp +\&\f(CW\*(C`cfgcheck\*(C'\fR converts the values of target settings \fIoptions\fR, e.g. +.Sp +.Vb 1 +\& options[router1]: bits, growright +.Ve +.Sp +to a hash: +.Sp +.Vb 2 +\& $targetcfg{\*(Aqoption\*(Aq}{\*(Aqbits\*(Aq}{\*(Aqrouter1\*(Aq} = 1 +\& $targetcfg{\*(Aqoption\*(Aq}{\*(Aqgrowright\*(Aq}{\*(Aqrouter1\*(Aq} = 1 +.Ve +.Sp +This is not done by \f(CW\*(C`readcfg\*(C'\fR so if you don't use \f(CW\*(C`cfgcheck\*(C'\fR you have to +check the scalar variable \fI\f(CI$targetcfg\fI{'option'}{'router1'}\fR (\s-1MRTG\s0 allows +options to be separated by space or ','). +.ie n .IP """ensureSL""" 4 +.el .IP "\f(CWensureSL\fR" 4 +.IX Item "ensureSL" +\&\f(CW\*(C`ensureSL(\e$pathname)\*(C'\fR +.Sp +Checks that the \fIpathname\fR does not contain double path separators and ends +with a path separator. It uses \f(CW$MRTG_lib::SL\fR as path separator which will be / +or \e depending on the \s-1OS.\s0 +.ie n .IP """log2rrd""" 4 +.el .IP "\f(CWlog2rrd\fR" 4 +.IX Item "log2rrd" +\&\f(CW\*(C`log2rrd ($router,\e%globalcfg,\e%targetcfg)\*(C'\fR +.Sp +Convert log file to rrd format. Needs rrdtool. +.ie n .IP """datestr""" 4 +.el .IP "\f(CWdatestr\fR" 4 +.IX Item "datestr" +\&\f(CW\*(C`datestr(time)\*(C'\fR +.Sp +Returns the time given in the argument as a nicely formatted date string. +The argument has to be in \s-1UNIX\s0 time format (seconds since 1970\-1\-1). +.ie n .IP """timestamp""" 4 +.el .IP "\f(CWtimestamp\fR" 4 +.IX Item "timestamp" +\&\f(CW\*(C`timestamp()\*(C'\fR +.Sp +Return a string representing the current time. +.ie n .IP """setup_loghandlers""" 4 +.el .IP "\f(CWsetup_loghandlers\fR" 4 +.IX Item "setup_loghandlers" +\&\f(CW\*(C`setup_loghandlers(filename)\*(C'\fR +.Sp +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. +.ie n .IP """expistr""" 4 +.el .IP "\f(CWexpistr\fR" 4 +.IX Item "expistr" +\&\f(CW\*(C`expistr(time)\*(C'\fR +.Sp +Returns the time given in the argument formatted suitable for \s-1HTTP\s0 +Expire-Headers. +.ie n .IP """create_pid""" 4 +.el .IP "\f(CWcreate_pid\fR" 4 +.IX Item "create_pid" +\&\f(CW\*(C`create_pid()\*(C'\fR +.Sp +Creates a pid file for the mrtg daemon +.ie n .IP """demonize_me""" 4 +.el .IP "\f(CWdemonize_me\fR" 4 +.IX Item "demonize_me" +\&\f(CW\*(C`demonize_me()\*(C'\fR +.Sp +Puts the running program into background, detaching it from the terminal. +.ie n .IP """populatecache""" 4 +.el .IP "\f(CWpopulatecache\fR" 4 +.IX Item "populatecache" +\&\f(CW\*(C`populatecache(\e%confcache, $host, $reread, $snmpoptshash)\*(C'\fR +.Sp +Reads the \s-1SNMP\s0 variables \fIifDescr\fR, \fIipAdEntIfIndex\fR, \fIifPhysAddress\fR, \fIifName\fR from +the \fIhost\fR and stores the values in \fI\f(CI%confcache\fI\fR as follows: +.Sp +.Vb 5 +\& $confcache{$host}{\*(AqDescr\*(Aq}{ifDescr}{oid} = (ifDescr or \*(AqDup\*(Aq) +\& $confcache{$host}{\*(AqIP\*(Aq}{ipAdEntIfIndex}{oid} = (ipAdEntIfIndex or \*(AqDup\*(Aq) +\& $confcache{$host}{\*(AqEth\*(Aq}{ifPhysAddress}{oid} = (ifPhysAddress or \*(AqDup\*(Aq) +\& $confcache{$host}{\*(AqName\*(Aq}{ifName}{oid} = (ifName or \*(AqDup\*(Aq) +\& $confcache{$host}{\*(AqType\*(Aq}{ifType}{oid} = (ifType or \*(AqDup\*(Aq) +.Ve +.Sp +The value (at the right side of =) is 'Dup' if a value was retrieved +multiple times, the retrieved value else. +.ie n .IP """readconfcache""" 4 +.el .IP "\f(CWreadconfcache\fR" 4 +.IX Item "readconfcache" +\&\f(CW\*(C`my $confcache = readconfcache($file)\*(C'\fR +.Sp +Preload the confcache from a file. +.ie n .IP """readfromconfcache""" 4 +.el .IP "\f(CWreadfromconfcache\fR" 4 +.IX Item "readfromconfcache" +\&\f(CW\*(C`writeconfcache($confcache,$file)\*(C'\fR +.Sp +Store the current confcache into a file. +.ie n .IP """writeconfcache""" 4 +.el .IP "\f(CWwriteconfcache\fR" 4 +.IX Item "writeconfcache" +\&\f(CW\*(C`writeconfcache($confcache,$file)\*(C'\fR +.Sp +Store the current confcache into a file. +.ie n .IP """storeincache""" 4 +.el .IP "\f(CWstoreincache\fR" 4 +.IX Item "storeincache" +\&\f(CW\*(C`storeincache($confcache,$host,$method,$key,$value)\*(C'\fR +.ie n .IP """readfromcache""" 4 +.el .IP "\f(CWreadfromcache\fR" 4 +.IX Item "readfromcache" +\&\f(CW\*(C`readfromcache($confcache,$host,$method,$key)\*(C'\fR +.ie n .IP """clearfromcache""" 4 +.el .IP "\f(CWclearfromcache\fR" 4 +.IX Item "clearfromcache" +\&\f(CW\*(C`clearfromcache($confcache,$host)\*(C'\fR +.ie n .IP """debug""" 4 +.el .IP "\f(CWdebug\fR" 4 +.IX Item "debug" +\&\f(CW\*(C`debug($type, $message)\*(C'\fR +.Sp +Prints the \fImessage\fR on \s-1STDERR\s0 if debugging is enabled for type \fItype\fR. +A debug type is enabled if \fItype\fR is in array \f(CW@main::DEBUG\fR. +.SH "AUTHORS" +.IX Header "AUTHORS" +Rainer Bawidamann +.PP +(This Manpage)