14all Configuration File syntax

This document describes the configuration file syntax of the cgi script 14all.cgi.

14all.cgi displays web pages and graphics from rrdtool files. In most cases it will be used together with MRTG.

14all uses roughly the same configuration file syntax as MRTG. In fact in a standard installation 14all and MRTG will use the same config file. 14all version 1.1 even uses the configuration file parser of MRTG.

This file is an addition to the documentation of MRTG. Please look there first to get an overall picture.


The general format is:

Setting formats

A config line can have one of the following formats:

A global config setting
Setting: Value

This is used for global settings. This includes WorkDir, HtmlDir, ImageDir, LogDir, LogFormat, Language, Interval, IconDir, WriteExpires, Refresh, UseRRDTool,

14all*Columns, 14all*Background, 14all*RRDToolLog, 14all*ErrorPic, 14all*GraphErrorsToBrowser

A target config setting
Setting[target]: value

This is used for the target settings. This includes Target, RouterUptime, MaxBytes, MaxBytes1, MaxBytes2, Title, PageTop, AddHead, AbsMax, Unscaled, WithPeak, Suppress, Directory, XSize, YSize, Options, Kilo, kMG, Background, Ylegend, ShortLegend, Legend1, Legend2, Legend3, Legend4, LegendI, LegendO, XZoom, YZoom, XScale, YScale, YTics, YTicsFactor, Colours, Step, Timezone, Weekformat, TreshDir, ThreshMinI, ThreshMaxI, ThreshProgI, ThreshProgOKI, ThreshMinO, ThreshMaxO, ThreshProgO, ThreshProgOKO,

14all*Logarithmic, 14all*GraphTotal, 14all*DontShowIndexGraph, 14all*IndexGraphSize

To distinguish these settings from the globals they will be written as Target[] in this document (i.e. with []).

Some value formats

Some settings share the syntax of the values:

Boolean settings
This includes WriteExpires, UseRRDTool, 14all*GraphErrorsToBrowser, 14all*Logarithmic[], 14all*GraphTotal[], 14all*DontShowIndexGraphp[], 14all*stackgraph. The values ``0'' (zero) and ``no'' will be interpreted as false, every other value counts as true. If the setting isn't found in the config it defaults to 0.

(UseRRDTool is only available for 14all v1.0. Use LogFormat with version v1.1)

Most options accept only integers: Columns, Interval, Refresh, MaxBytes, MaxBytes1, MaxBytes2, AbsMax, XSize, YSize, YTics, Kilo, ThreshMinI, ThreshMaxI, ThreshMinO, ThreshMaxO.

Kilo is special as it only accepts the values 1000 and 1024.

Strings will be trimmed at the front and the end (i.e. white space removed). Sequences of white space will be replaced by one space.

Paths can be absolute or relative. The base for relative pahts depends on the setting and context. Directory paths may end with a slash.

The global settings

WorkDir, ImageDir, LogDir, HtmlDir
These settings specify where the graph files, the data files and the html files should go to. WorkDir takes precedence over the other three, they are only used when WorkDir isn't given.

14all uses LogDir to look for the rrd files. It writes the graph files to ImageDir (or /tmp if this isn't writeable).

This setting tells MRTG how often it should poll the targets. 14all uses this value to set the expire and refresh HTTP headers. The unit is minutes.

Refresh specifies if a refresh line should appear in the HTTP header, telling the browser to reload the pages / graphs automatically. '0' or 'no' will turn this off. '1' or 'yes' will turn it on, the value for the refresh line will be fetched from the Interval setting. If Refresh is set to a number (that value will be used as refresh interval (unit: seconds)).

This expects a boolean value: if set 14all will emit an expire line in the HTTP header.

(14all v1.1 ignores this setting and emits the expire header all the time).

The directory where the MRTG icons are.

This setting is only used by MRTG, 14all isn't internationalized (volunteers?).

This option is only available for 14all v1.0. For 14all v1.1 look at the setting LogFormat.

This tells MRTG to use rrdtool instead of it's own rateup program to log the data. MRTG won't create any graphs or web pages any more with this option set.

If you want to test rrdtoll/14all on some targets first please check the per-target setting UseRRDTool[]

The global option UseRRDTool can have the value columns: 2 where the number confiures how many columns will be used for the group (directory) pages.

This option is only available for 14all v1.1. For 14all v1.0 look at the setting UseRRDTool.

This setting selects whether MRTG uses rateup or rrdtool to store the measured data. 14all needs this to be set to rrdtool.

  • all*Columns
    This sets the number of columns in the index html pages. Default is 2.

  • all*Background
    This sets the background color of the main index html page. Default is white.

  • all*RRDToolLog
    This setting takes a filename. 14all will log every rrdtool call to this file. You can replay these calls by executing this log file.

    This file can get very big - only enable it if you want to debug 14all or find out why something doesn't work.

  • all*ErrorPic
    This setting takes a filename.

    When 14all encounters an error while creating a graph it displays an error picture. The default error picture contains the text ``error: cannot create graph''. If this option is set the given file will be sent as error picture.

  • all*GraphErrorsToBrowser
    Normally when an error occurs while creating a graph a default error picture is sent to the browser. If this option is set and the perl module GD is installed a graph will be created and sent which contains a message specifying the error.

    The error message might expose internal information about the installation or configuration to WWW clients. Be careful when setting this.

  • Per target settings

    The targets have to be specified between the brackets []

    An upper bound of the data to log. This helps MRTG/rrdtool to recognize counter wraps. Look in the MRTG documentation to read more about this.

    14all uses this setting (and MaxBytes1, MaxBytes2, AbsMax) to calculate the usage percentage (if option nopercent isn't set) and to set the upper bound of the graph if unscaled is set.

    MaxBytes1[], MaxBytes2[]
    Like MaxBytes but only for the first or sceond data source of the target.

    E.g. on serial lines with compression the traffic rate can sometimes be higher than the nominal rate. AbsMax sets an absolut upper bound.

    This will be displayed as the title / name of the device in the web pages.

    If you have many targets you can group some targets into directories. The value of this setting is a directory relative to WorkDir (ImageDir/LogDir) where MRTG will store the log files. 14all will group the targets of one directory in one web page. The start page will contain links to the directories.

    A text (html) to display at the top of the web page. If empty a default header line will be used.

    A text to display at the end of the web page. Default: empty.

    The value of this setting (arbitrary text) will be added in the HTML header.

    This setting can be a string of any of the characters 'd', 'w', 'm', 'y' for Day, Week, Month, Year respectivly. Normally the graphs will be scaled automatically to make the actual data visible even when it is much lower than MaxBytes. The given graphs will be displayed unscaled.

    By default the graphs only contain the average values of the monitored variables - normally the transfer rates for incoming and outgoing traffic. If this setting contains the appropriate letter ([w]eekly, [m]onthly, [yearly]) the graph will contain additionally two lines for the peak values.

    MRTG allows this to be set to 'd' too but you will get strange graphs so don't do it.

    This tells 14all which graphs it should not display at all. The syntax is the same as for Unscaled.

    XSize[], YSixe[]
    With this option you can change the graph size. By default the graphs are 100 by 400 pixels plus some pixels for the legends. These settings will be overriden by UseRRDTool[]: graphsize ...: ... (only with 14all v1.0).

    Specifies the background colour of the html pages. Use a string like ``white'' or a numerical value like ``#00ff55''.

    Use this option to change the multiplier value for building prefixes. Default value is 1000. Use 1024 if 1k == 1024 e.g. when graphing memory utilization. Only 1000 or 1024 is allowed (by MRTG).

    Change the default multiplier prefixes (,k,M,G,T,P). Format: Comma seperated list of prefixed. Two consecutive commas or a comma at start or end of the line gives no prefix on this item.

    YLegend[], ShortLegend[], Legend1, Legend2[], Legend3[], Legend4[], LegendI[], Legendo[]
    These settings allow you to override the text displayed for the various legends of the graph.

    YLegend[] - The Y-axis lable of the graph.

    ShortLegend[] - The unit string used for Max, Average and Current (default

    other settings - The strings for the colour legend.

    Set the timezone for this target.Accepts strings like ``US/Eastern'' or ``Europe/Berlin''. On Linux /usr/share/zoneinfo holds the list of possible settings.

    (yes, there is a global option with the same name)

    This setting is only available for 14all v1.0!

    This setting has two purposes:

    1. You can configure MRTG to use rrdtool on a per-target basis.

    2. MRTG will stop if it finds any unknown config settings. UseRRDTool is a
    workaround to provide additional settings for 14all without the need to
    change MRTG every now and then.

    See below for syntax and options.

  • all*Logarithmic[]
    When this is set the vertical direction of the graph will be scaled logaritmic.

  • all*GraphTotal[]
    When this is set the graph will contain an additional line showing the sum of the two other lines.

  • all*DontShowIndexGraph[]
    Index pages can show index graphs of the targets. If this option is set for a target there won't be an index graph for it.

  • all*IndexGraphSize[]
    This setting takes two numbers representing the horixontal and vertical size of the index graph for this target (use the traget _ to set the size for all index graphs).

  • all*stackgraph[]
    When this is set the two graphed values will be shown stacked. The second value ('in') will be on top of the first value ('in').

    Target[], RouterUptime[], Colours[], WeekFormat[], Step[], YTics[], YTicsFactor[], TimeZone[] XZoom[], YZoom[], XScale[], YScale[], Thresh*[]
    These MRTG settings are ignored by 14all. Read the MRTG documentation if you use MRTG with 14all.

  • Per-target options

    14all recognizes several mrtg options. Please look into the MRTG documentation if you want to find more about all of these. The options are separated by comma or space. An example:

     Options[target]: bits, perminute

    14all v1.0 makes one difference to MRTG: If there are several Options lines MRTG uses only the options from the last and ignores the rest (the last line overrides the other). 14all merges the options from all of the options lines.

    The options recognized by 14all are:

    perminute, perhour
    The default is to display values per second (e.g. bytes/sec). This can be changed with this options. The default legends change from ``Bytes per Second'' to ``Bytes per Minute'' or ``Bytes per Hour''.

    As default data rates are displayed as bytes/sec. The option bits changes this to bits/sec. This changes the Y legend too.

    Sometimes a measured device is down so there is no data for some time. rrdtool logs ``unknown'' in this case. Normally a graph will show a gap for the unknown values. With unknaszero the graph will show a zero (0) value for unknown values.

    When this option is not present the graph legend (the legend, not the graph!) will contain an estimation of the usage percentage.

    noi, noo
    The first value (noi) or the second value (noo) isn't shown.

    The mrtg banner will no be printed at the footer of the page.

    The graphs will contain no legends.

    The extended 14all settings: version 1.0

    This paragraph applies to 14all v1.0 only!

    The settings UseRRDTool[] can have additional settings with a special syntax. The main difference is that every ``file line'' is now a ``config line''.

    An example:

           #     name     start    end   maxage
           graph daily:   -2000m   now    300
           # index pictures: size and range
           graphsize daily.s: 250 100
           graph daily.s: -1250m   now    300
           indexgraph: daily.s
           logarithmic: yes

    In the example are six (6) settings: ``showgrahs'', ``graph daily'', ``graphsize daily.s'', ``graph daily.s'', ``indexgraph'', ``logarithmic''. Option and value are separated with a ``:''. You cannot break a 14all extended option into several lines.

    The possible settings:

    The index graph is as default a small version of the daily graph without legends. With this option you can use any defined graph as index graph.

    graph <graphname>
    With this option you can configure the graphs. A graph is defined by the time it shows - the start time and the end time. The first value of this option is the start time, the second the end time (separated by space(s), for the value syntax see the rrdgraph documentation). The third value says how long this graph is valid (this value will be used for the expire/refresh http headers).

    <graphname> is any name you like. 14all only uses the graphs ``daily'', ``weekly'', ``monthly'', ``yearly'' in the html target pages and ``daily.s'' as indexgraph. 14all will happily create any other graph if someone calls it with appropriate ``png='' cgi parameter.

    graphsize <graphname>
    The size of graph <graphname> (x and y size). Two integer values separated by space(s). The graph will be somewhat bigger because of the legends. E.g.
     graphsize daily: 500 150

    The default graph size if none is given for a graph. E.g.
     graphsize: 400 100

    A boolean option: if true all graphs will have a logarithmic scaled y axis.

    If rrdtool refuses to create a graph 14all cannot display some text as the browser loads the graph through a ``IMG'' tag. This option holds a path to a png which will be shown on error. If this is not set a builtin picture will be used.

    The extended 14all settings: version 1.1

    Version 1.1 of 14all uses a different way for additional configuration. The extended 14all settings all have the prefix 14all* and have the same syntax as the standard MRTG settings. Look in the list of settings above.