CONFIG(1) 14all CONFIG(1) 1144aallll CCoonnffiigguurraattiioonn FFiillee ssyynnttaaxx 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. SSyynnttaaxx The general format is: · The syntax is line-oriented, i.e. one "config" line is one config setting. · A line in the file that starts with white space (space or tab) is a continuation line and is appended to the previous line, making up on config line. · Empty (file) lines and lines that start with a # are ignored. SSeettttiinngg ffoorrmmaattss 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", "LogFor­ mat", "Language", "Interval", "IconDir", "WriteEx­ pires", "Refresh", "UseRRDTool", "14all*Columns", "14all*Background", "14all*RRDTool­ Log", "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", "Abs­ Max", "Unscaled", "WithPeak", "Suppress", "Direc­ tory", "XSize", "YSize", "Options", "Kilo", "kMG", "Background", "Ylegend", "ShortLegend", "Legend1", "Legend2", "Legend3", "Legend4", "LegendI", "Leg­ endO", "XZoom", "YZoom", "XScale", "YScale", "YTics", "YTicsFactor", "Colours", "Step", "Timezone", "Week­ format", "TreshDir", "ThreshMinI", "ThreshMaxI", "ThreshProgI", "ThreshProgOKI", "ThreshMinO", "Thresh­ MaxO", "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 []). SSoommee vvaalluuee ffoorrmmaattss 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) Numbers Most options accept only integers: "Columns", "Inter­ val", "Refresh", "MaxBytes", "MaxBytes1", "MaxBytes2", "AbsMax", "XSize", "YSize", "YTics", "Kilo", "Thresh­ MinI", "ThreshMaxI", "ThreshMinO", "ThreshMaxO". "Kilo" is special as it only accepts the values 11000000 and 11002244. 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 rela­ tive pahts depends on the setting and context. Direc­ tory paths may end with a slash. TThhee gglloobbaall sseettttiinnggss 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). Interval This setting tells MRTG how often it should poll the targets. 14all uses this value to set the eexxppiirree and rreeffrreesshh HTTP headers. The unit is minutes. Refresh Refresh specifies if a rreeffrreesshh 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 eexxppiirree line in the HTTP header. (14all v1.1 ignores this setting and emits the eexxppiirree header all the time). IconDir The directory where the MRTG icons are. Language This setting is only used by MRTG, 14all isn't inter­ nationalized (volunteers?). UseRRDTool 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 "UseRRD­ Tool[]" 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. LogFormat This option is only available for 14all v1.1. For 14all v1.0 look at the setting "UseRRDTool". This setting selects whether MRTG uses rraatteeuupp or rrrrdd­­ ttooooll to store the measured data. 14all needs this to be set to rrrrddttooooll. 14all*Columns This sets the number of columns in the index html pages. Default is 2. 14all*Background This sets the background color of the main index html page. Default is white. 14all*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. 14all*ErrorPic This setting takes a filename. When 14all encounters an error while creating a graph it displays an error picture. The default error pic­ ture contains the text "error: cannot create graph". If this option is set the given file will be sent as error picture. 14all*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 GGDD is installed a graph will be created and sent which contains a mes­ sage specifying the error. The error message might expose internal information about the installation or configuration to WWW clients. Be careful when setting this. PPeerr ttaarrggeett sseettttiinnggss 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" 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. 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" (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. 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. Default: empty. 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 respec­ tivly. Normally the graphs will be scaled automati­ cally 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 set­ ting contains the appropriate letter ([w]eekly, [m]onthly, [yearly]) the graph will contain addition­ ally 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. Suppress[] This tells 14all which graphs it should nnoott 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 overri­ den by "UseRRDTool[]: graphsize ...: ..." (only with 14all v1.0). 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 consecu­ tive 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 dis­ played 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). other settings - The strings for the colour legend. Timezone Set the timezone for this target.Accepts strings like "US/Eastern" or "Europe/Berlin". On Linux /usr/share/zoneinfo holds the list of possible set­ tings. UseRRDTool[] (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-tar­ get basis. 2. MRTG will stop if it finds any unknown config set­ tings. 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. 14all*Logarithmic[] When this is set the vertical direction of the graph will be scaled logaritmic. 14all*GraphTotal[] When this is set the graph will contain an additional line showing the sum of the two other lines. 14all*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. 14all*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). 14all*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. PPeerr--ttaarrggeett ooppttiioonnss 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 sev­ eral "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". bits As default data rates are displayed as bytes/sec. The option "bits" changes this to bits/sec. This changes the Y legend too. 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. noi, noo The first value (noi) or the second value (noo) isn't shown. nobanner The mrtg banner will no be printed at the footer of the page. nolegend The graphs will contain no legends. TThhee eexxtteennddeedd 1144aallll sseettttiinnggss:: vveerrssiioonn 11..00 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: UseRRDTool[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", "index­ graph", "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 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" doc­ umentation). The third value says how long this graph is valid (this value will be used for the expire/refresh http headers). 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 The size of graph (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 loga­ rithmic scaled y axis. errorpic If rrdtool refuses to create a graph 14all cannot dis­ play 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. TThhee eexxtteennddeedd 1144aallll sseettttiinnggss:: vveerrssiioonn 11..11 Version 1.1 of 14all uses a different way for additional configuration. The extended 14all settings all have the prefix 1144aallll** and have the same syntax as the standard MRTG settings. Look in the list of settings above. 14all 1.0p13 2002-07-13 CONFIG(1)