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.


Syntax

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, Columns, Interval, IconDir, WriteExpires, Refresh, UseRRDTool, Language

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

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


Some value formats

Some settings share the syntax of the values:

Boolean settings

This includes WriteExpires, UseRRDTool. The values ``0'' (zero) and ``no'' will be interpreted as false, every other value counts as true.

Numbers

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

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

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

Workdir specifies where the logfiles and the web pages are. It is the base for the Directory setting. With 14all MRTG creates only the log files, the web pages are created on demand and not written to disk.

Interval

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

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).

WriteExpires

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

IconDir

The directory where the MRTG icons are.

Language

This setting is only used by MRTG, 14all ignores it.

LoadMibs

A list of MIBs which should be loaded by MRTG. 14all ignores this setting.

UseRRDTool

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.


Per target settings

The targets have to be specified between the brackets []

MaxBytes[]

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 not set) and to set the upper bound of the graph if unscaled set.

MaxBytes1[], MaxBytes2[]

Like MaxBytes but only for the first or sceond data source of the target.

AbsMax[]

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

Title[]

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

Directory[]

If you have many targets you can group some targets into directories. The value of this setting is a directory relative to WorkDir 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.

PageTop[]

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

PageFoot[]

A text to display at the end of the web page.

AddHead[]

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

Unscaled[]

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.

WithPeak[]

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.

Suppress[]

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 ...: ....

Background[]

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

kilo[]

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).

kMG[]

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 b/s)

Legend1234IO[] - The strings for the colour legend

UseRRDTool[]

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

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.

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

Currently 14all 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.

bits

As default data rates are displayed as bytes/sec. The option bits changes this to bits/sec.

unknaszero

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.

nopercent

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


The extended 14all settings

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:

 UseRRDTool[example]:
       showgraphs: daily,weekly,monthly,yearly
       #     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:

indexgraph

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 ltgraphnamegt

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. Use this name with showgraphs or indexgraph.

graphsize ltgraphnamegt

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
graphsize

The default graph size if none is given for a graph. E.g.

 graphsize: 400 100
logarithmic

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

error pic

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.