mrtnk is a set of scripts to:
- generate rrd databases compatible with mrtg (when mrtg is configured to use rrd format logs)
- update these databases (for the moment only with "external scripts")
- make graphics with rrdtool (a set of predesigned graphics are usable by a keyword)
- make web pages presenting the graphics
All this is done through to an easy to setup config file with a syntax quite close to mrtg's I started to write these scripts for a private usage, but they seemed to interest other people, so I decided to make them public.
NOTE FOR MRTG users: if you use rrd logformat in MRTG, you can use the rrd files generated by MRTG with mrtnk, the name of the rrd files has just to be target_name.rrd (see below for target_name definition)
You can see the results on www.linux-sottises.net/stats_mrtnk.php
[Back Table of contents]
- A linux box with bash and "something to measure"
- cut, grep, sed, bc
- RRDTOOL
- SNMP (if you plan to use it...)
- MRTNK :-)
[Back Table of contents]
I suppose that RRDTOOL and, eventually, SNMP, are installed and work.
Uncompress MRTNK archive, and put mrtnk directory somewhere like /usr/local
The general config file mrtnk.setup must be put in /etc
Edit /etc/mrtnk.setup
Give the required path
Path to MRTNK
MRTNK="/usr/local/mrtnk"
Path to "external scripts" (which send two values "in" and "out"),
the default is the directory scripts of MRTNK install directory
SCRIPTS="$MRTNK/scripts"
Path to rrd files. The default is the directory logs_rrd of install directory
LOGS="$MRTNK/logs_rrd"
Path to html files, it must be in the root directory of your web server if you
want to give acces to these files from your webserver
(look also to the definitions of IMAGES directory, and further of DIRECTORY keyword).
HTML="/webnew"
Name of the directory (relative path) where images will be stored.
If you do not use specific directories for some targets (keyword DIRECTORY, see below),
you have to create this directory as a subdirectory of HTML.
IMAGES="images_rrd"
Relative path of an images directory on you webserver (to store MRTNK et RRDTOOL logos which are provided in the images directory of the archive)
IMAGES_GENERAL=images
Path of some config files (personalization of html files) and for system.conf file
CONF=$MRTNK/conf
Path to rrdtool binary
RRD="/usr/local/rrdtool/bin/rrdtool"
Path to snmpget (if you use snmp)
SNMPGET="/usr/bin/snmpget"
[Back Table of contents]
You have to setup a config file. If you use SNMP,
a script mrtnk-confmake is provided to help the setting of the config file for snmp targets.
The manual for mrtnk-confmake is provided below.
The config file has the form:
KEYWORD[target]="VALUE"
target will be used to name rrd files, images correspondantes and html files.
Remark: Do not put any space between [ ] and the target name.
Every keyword can be capitalized or not
Remark: be careful not to use VALUES which are keywords!!!
Lines with # are treated as comments (do not use # in your VALUES)
[Back Table of contents]
This is the keywords list:
TARGET (required): external script name or SNMP
If VALUE is SNMP, then keywords
{SNMP_HOST et SNMP_COMMUNITY}
are required, and also one of:
{SNMP_IF and SNMP_NUMBER} or {SNMP_OID_IN} or {SNMP_OID_IN and SNMP_OID_OUT}
Look the examples.
TYPE (required) COUNTER (to measure increments) or GAUGE (to measure direct values) GAUGE and COUNTER have to be capitalized
ABSMAX (required) maximum authorized value in rrd base (can be negative)
ABSMIN (required) minimum authorized value in rrd base (can be negative)
GRAPH (required) preset graphic type. Available:
inout: in is shown as positive, out is shown as negative
inoutpeak: same as inout with peak values
double: two values as in mrtg
doublepeak: same as double with peak values
single: only one value shown as an "area, it is "IN" for
colors and legend)
singlepeak: same as single with peaks
doubleline: two values shown as "lines"
doublelinepeak: same as doubleline with peaks
singleline: one value shown as a line
singlelinepeak: same as singleline with peaks
LEGENDIN (required) Legend for the IN graphic
LEGENDINPEAK (required in case of a graphic with peak) Legend for peak IN graphic
LEGENDOUT (required in case of a graphic with 2 values) Legend for OUT graphic
LEGENDOUTPEAK (required in case of a graphic with 2 values and peaks) Legend for peak OUT graphix
MAX (option) shows an horizontal line with color COLORINPEAK at the given value (if scaling permits)
MIN (option) shows an horizontal line with color COLOROUTPEAK at the given value (if scaling permits it)
LOW (option) minimum value of the vertical axis (if values go lower, this mimimum value is not taken into account)
UP (option) maximum value of the vertical axis (if values go higher, this mimimum value is not taken into account)
RIGID (option, RIGID[target_name]="anything", only usable with LOW and/or UP) LOW and/or UP values are not decrease or increase if value go beyond them. If you do not want this option for a target, do not use the keyword or put an empty string "" as value
TITLE (option) Title of the graphics
UNIT (option) units (for vertical axis legend and values in the legends below the graphics)
COLORIN (option) color for IN graphic
COLORINPEAK (option) color for peak IN graphic
COLOROUT (option) coulor for OUT graphic
COLOROUTPEAK (option) coulor for peak OUT graphic
NO_LAZY (option, NOLAZY[target_name]="anything") by default, the graphic are generated only if needed according to their creation date. NO_LAZY disables this and graphics are systematically generated. If you want to this option for a target, suppress the keyword or put an empty string as value
FACTOR (option) multiply all the values in the graphics (very useful for switching from bytes to bits or from /s to /hour units)
BASE (option) coefficient between m K M G T units (default 1000, 1024 is useful for bytes quantities)
XSIZE (option, default 600) width of the graphics
YSIZE (option, default 200) heigth of the graphics
SUPPRESS (option) one or several letters from d (day) w (week) m (month)
y (year): suppresses the creation of the corresponding graphics
Example
SUPPRESS[adsl-rrd]="my"
only creates day and week graphics, only these graphics appear in html generated pages
DIRECTORY (option) relative sub directory of HTML directory (HTML is defined in conf/general.conf)
to store generated html pages
images will be stored in HTML/DIRECTORY/IMAGES where IMAGES is defined in conf/general.conf
If DIRECTORY and DIRECTORY/IMAGES do not exist, they will be created by the scripts.
But YOU HAVE TO CREATE HTML directory and HTML/IMAGES directory
NO_HOLE (option) If value is "yes", in the graphics, in case of "holes" in the data, the "holes" are filled with the "last" value before the hole. If this keyword is not present, holes are filled with zeroes.
SNMP_HOST (required if target is SNMP) Host name for snmp
SNMP_COMMUNITY (required if target is SNMP) SNMP community effectuées
SNMP_IF (no compatible with SNMP_OID_IN) Interface name for SNMP
SNMP_NUMBER (required with SNMP_IF) Internal interface number for SNMP_IF,
mrtnk-confmake will provide you this number with all interfaces names
(voir plus loin)
SNMP_OID_IN (no compatible with SNMP_IF) "first" numerical OID, for example
.1.3.6.1.2.1.2.2.1.2.1
ou text OID, for example:
ifDecsr.1
"First" means the first value for graphics.
SNMP_OID_OUT (no compatible with SNMP_IF, requires SNMP_OID_IN) "second" numerical or text OID.
There are 2 keywords that do not require a target and that can pe put at the top of the config file:
HTML_EXTENSION changes the extension of generated web pages (default is HTML). Example:
HTML_EXTENSION="php"
NO_LOGO (without = VALUE) suppresses MRTNK and RRDTOOL logos on the foot of web pages.
[Back Table of contents]
To help settig up the config file for SNMP, run from MRTNK install directory:
./mrtnk-confmake host community > foo.conf
It must be mentionned that MRTNK is far from being as rich as MRTG for SNMP.
For "standard" interfaces, host is your machine name and community is public
In foo.conf, you should have a "minimum" config file dealing with all your interfaces.
You have to edit this file for several reasons:
There are "useless" interfaces (as lo or dummy)
Somme interfaces have 0 throughputs (as ppp0) or wrong throughputs (my 100 Mbits are not recognized as 100 Mbits
by SNMP. You have to check ABSMAX
You have to add your GRAPH choice and may want to add color or legends options.
Target names are: host_number
For example, this is the result of./mrtnk-confmake yoda public on my own machine:
TARGET[yoda_1]="SNMP" SNMP_IF[yoda_1]="lo" SNMP_HOST[yoda_1]="yoda" SNMP_COMMUNITY[yoda_1]="public" SNMP_NUMBER[yoda_1]="1" TYPE[yoda_1]="COUNTER" ABSMAX[yoda_1]="1250000" ABSMIN[yoda_1]="0" TITLE[yoda_1]="lo yoda" TARGET[yoda_2]="SNMP" SNMP_IF[yoda_2]="dummy" SNMP_HOST[yoda_2]="yoda" SNMP_COMMUNITY[yoda_2]="public" SNMP_NUMBER[yoda_2]="2" TYPE[yoda_2]="COUNTER" ABSMAX[yoda_2]="1250000" ABSMIN[yoda_2]="0" TITLE[yoda_2]="dummy yoda" TARGET[yoda_3]="SNMP" SNMP_IF[yoda_3]="eth0" SNMP_HOST[yoda_3]="yoda" SNMP_COMMUNITY[yoda_3]="public" SNMP_NUMBER[yoda_3]="3" TYPE[yoda_3]="COUNTER" ABSMAX[yoda_3]="1250000" ABSMIN[yoda_3]="0" TITLE[yoda_3]="eth0 yoda" TARGET[yoda_4]="SNMP" SNMP_IF[yoda_4]="eth1" SNMP_HOST[yoda_4]="yoda" SNMP_COMMUNITY[yoda_4]="public" SNMP_NUMBER[yoda_4]="4" TYPE[yoda_4]="COUNTER" ABSMAX[yoda_4]="1250000" ABSMIN[yoda_4]="0" TITLE[yoda_4]="eth1 yoda" TARGET[yoda_5]="SNMP" SNMP_IF[yoda_5]="ppp0" SNMP_HOST[yoda_5]="yoda" SNMP_COMMUNITY[yoda_5]="public" SNMP_NUMBER[yoda_5]="5" TYPE[yoda_5]="COUNTER" ABSMAX[yoda_5]="0" ABSMIN[yoda_5]="0" TITLE[yoda_5]="ppp0 yoda"
To make it more easy to setup a config file, you can provide a config file to mrtnk-confmake.
this config file has the following form:
KEYWORD="VALUE"
For example:
DIRECTORY="toto" COLORIN="111111"
These settings will be added (with the correct target) to the config file generated by
mrtnk-confmake.
To use this functionnality, rrun from mrtnk install directory:
./mrtnk-confmake host community confmake_config_file
[Back Table of contents]
TARGET[dns_rrd]="stat.pl dnsreqs" TYPE[dns_rrd]="COUNTER" GRAPH[dns_rrd]="singlepeak" ABSMAX[dns_rrd]="30" ABSMIN[dns_rrd]="0" LOW[dns_rrd]="0" TITLE[dns_rrd]="Requêtes DNS horaires" UNIT[dns_rrd]="req/h" LEGENDIN[dns_rrd]="req/h" LEGENDINPEAK[dns_rrd]="req/h peak" COLORIN[dns_rrd]="21bda6" COLORINPEAK[dns_rrd]="1e88bd" FACTOR[dns_rrd]="3600"
Target is the external script stats.pl (which is in scripts directory of install directory)
whichi is called with syntax "webstat.pl dnsreqs". It gives DNS resquests on a bind server.
There is onlys one graphic to make, so singlepeak can be used ("area with peaks").
COUNTER provides "per second" results", and ABSMAX is set to 30, which is already a lot for my server!
FACTOR value is 3600, and permits to show "per hour" values in the graphics.
----------
TARGET[adsl_rrd]="netstat ppp0 ppp0" TYPE[adsl_rrd]="COUNTER" ABSMAX[adsl_rrd]="100000" ABSMIN[adsl_rrd]="0" GRAPH[adsl_rrd]="inoutpeak" MAX[adsl_rrd]="64000" MIN[adsl_rrd]="-16000" LOW[adsl_rrd]="-30000" UP[adsl_rrd]="65000" TITLE[adsl_rrd]="Débits ADSL netstat" UNIT[adsl_rrd]="bytes/s" LEGENDIN[adsl_rrd]="Traffic in" LEGENDINPEAK[adsl_rrd]="Traffic in Peak" LEGENDOUT[adsl_rrd]="Traffic out" LEGENDOUTPEAK[adsl_rrd]="Traffic out Peak" COLORIN[adsl_rrd]="7aafff" COLORINPEAK[adsl_rrd]="1000ff" COLOROUT[adsl_rrd]="ff00ff" COLOROUTPEAK[adsl_rrd]="ff0000" SUPPRESS[adsl_rrd]="d" DIRECTORY[adsl_rrd]="ADSL" NOLAZY[adsl_rrd]="salut" XSIZE[adsl_rrd]="400" YSIZE[adsl_rrd]="200" RIGID[adsl_rrd]="bonjour"
Target is again a script
day graphic is not created
HTML pages are created in ADSL directory which will be a subdirectory of the HTML which is set in
/etc/mrtk.setup. Images will be created in a subdirectory of ADSL (the name of this subdirectory
is set in IMAGES in /etc/mrtk.setup
NOLAZY forces the creation of images, even if it is not necessary according to their timestamp and rrd files last update.
Graphics size is modified by XSIZE et YSIZE
RIGID forces to stay between LOW and UP values in the graphics.
----------
TARGET[yoda_ppp0]="SNMP" SNMP_IF[yoda_ppp0]="ppp0" SNMP_HOST[yoda_ppp0]="yoda" SNMP_COMMUNITY[yoda_ppp0]="public" SNMP_NUMBER[yoda_ppp0]="5" TYPE[yoda_ppp0]="COUNTER" UNIT[yoda_ppp0]="bytes/s" ABSMAX[yoda_ppp0]="100000" ABSMIN[yoda_ppp0]="0" GRAPH[yoda_ppp0]="inoutpeak" TITLE[yoda_ppp0]="Débits ADSL SNMP" MAX[yoda_ppp0]="64000" MIN[yoda_ppp0]="-16000" UP[yoda_ppp0]="65000" LOW[yoda_ppp0]="-30000"
It is a SNMP target generated by mrtnk-confmake and manually modified and completed.
----------
TARGET[errors_ppp0]="SNMP" SNMP_HOST[errors_ppp0]="yoda" SNMP_COMMUNITY[errors_ppp0]="public" SNMP_OID_IN[errors_ppp0]="ifInErrors.5" SNMP_OID_OUT[errors_ppp0]="ifOutErrors.5" TYPE[errors_ppp0]="COUNTER" UNIT[errors_ppp0]="erreurs/h" ABSMAX[errors_ppp0]="10000" ABSMIN[errors_ppp0]="0" GRAPH[errors_ppp0]="inoutpeak" TITLE[errors_ppp0]="Erreurs ppp0" LEGENDIN[errors_ppp0]="Erreurs IN" LEGENDOUT[errors_ppp0]="Erreurs OUT" FACTOR[errors_ppp0]="3600"
It is a SNMP target with 2 text OIDs: IN and OUT errors numbers on interface number 5 (ppp0 for my own machine).
----------
TARGET[errors_in_ppp0]="SNMP" SNMP_HOST[errors_in_ppp0]="yoda" SNMP_COMMUNITY[errors_in_ppp0]="public" SNMP_OID_IN[errors_in_ppp0]=".1.3.6.1.2.1.2.2.1.14.5" TYPE[errors_in_ppp0]="COUNTER" UNIT[errors_in_ppp0]="erreurs/h" ABSMAX[errors_in_ppp0]="10000" ABSMIN[errors_in_ppp0]="0" GRAPH[errors_in_ppp0]="singlepeak" TITLE[errors_in_ppp0]="Erreurs ppp0 IN" LEGENDIN[errors_in_ppp0]="Erreurs IN" FACTOR[errors_in_ppp0]="3600"
It is a SNMP target with one numerical OID: IN error number on interface number 5
(use snmptranslate -IR ifInErrors.5 to get numeric OID, or the inverse)
[Back Table of Contents]
mrtnk-update script create rrd files and update them by
calling external scripts, or by SNMP calls. Syntax is:
/usr/local/mrtnk/mrtnk-update /usr/local/mrtnk/conf/your_config_file
Replace eventually /usr/local by your own settings (you can also put your config file elsewhere).
This script does not create any graphics or web pages
If "all is OK", put this command in your crontab with a 5 minutes frequency (5 minutes is mandatory).
If you change ABSMIN or ABSMAX in a target, rrd files are updated with the new values.
If you made a mistake with GAUGE and COUNTER for a target, scripts update rrd file with new values with the new type, but I strongly recommand to suppress the corresponding rrd file, as graphics may be seriously perturbed by such a change.
[Back Table of contents]
To create graphics, run:
/usr/local/mrtnk/mrtnk-graph /usr/local/mrtnk/conf/your_config_file
You have to wait three updades of rrd files before seing "something" on the graphics...
Put this command in crontab if you wish.
Simultaneoulsly, files containing images size are created (for web pages creation with right images sizes).
[back Table of contents]
First, you can choose the extension of web pages with keyword HTML_EXTENSION (see keywords list
A big difference with MRTG is that, once images have been created (after three updates of rrd files), only one run of web pages creation is needed (except if you add more targets to your config files or if you change graphics settings)
To create web pages, run:
/usr/local/mrtnk/mrtnk-html /usr/local/mrtnk/your_config_file
This command creates:
- one page per target with named according to the target name
- an index page (stats_mrtnk.html) which group all the "day" images of all targets with links to the targets graphics.
It is possible to personalize web pages.
If you create a file head_mrtnk in the directory conf, this file will be included between "head" tags of
created web pages.
If you create a file body_mrtnk (which need to begin by <body> tag) in conf directory, this file will be
included between the graphics in created web pages.
If you create a file foot_mrtnk in conf directory, this file will be included below the graphics
in the created web pages.
If you create a file index_head_mrtnk in the directory conf, this file will be included between "head" tags of
the index file.
If you create a file index_body_mrtnk (which need to begin by <body> tag) in conf directory, this file will be
included between the graphics in index file.
If you create a file index_foot_mrtnk in conf directory, this file will be included below the graphics
in the index file.
[Back Table of Contents]