INANNA Version 0 / Configuration File Format

This document describes the format of the configuration file that is used by the template module of the Animated Traffic Map system to generate an individual GIF file. In other words, this is the core configuration file for the system -- all of the image map parameters, arrow endpoints, etc., live in this file.

The syntax of the file is pretty simple, but the template script doesn't do much error checking at the moment, so caution is needed. In particular, if any coordinates extend beyond the limits of the overlay GIF while the image is being generated, you'll probably get a Segmentation Fault from the gd library.

The configuration file has several main sections, which are listed below. In each section, you'll find a sample configuration and an explanation of the individual parameters.

General Configuration
Scale Entries
Palette Entries
Links (Arrows)
Areas (Hotlinks)
Labels

General Configuration

Sample

  param collector    /home/abilene/traffic/bin/abilene.data
  param template     /home/abilene/public_html/traffic/blankmap.gif
  param prefix       /home/abilene/public_html/traffic/abilene
  param archive      /home/abilene/traffic/history

  param legend       lower right
  param legendtitle  Line Utilization
  param colors       10
  param scale        linear relative 10 90
  param background   0xcccc99

  param title        Abilene Network Traffic
  param time         615 10
  param clock        681 29 40 down

  param refresh      300

Explanation

Each line in this section consists of the string param, followed by the name of the parameter, followed by the arguments.

Parameters

Parameter Required? Arguments Notes
collector
yes

full path to collector script
The full path to the external collector script. This script is run by template to collect the data on the status of each link. The script is given the name of the link and the number of seconds to use for the high water mark on the command line and expects output in the following format:
  current_bandwidth total_bandwidth
  maximal percent error (for high water mark)
  percent errors now
  percent errors 5 minutes ago
  percent errors 10 minutes ago
     :       :   n    :     :
The amount of error history to return is dependent on the setting of the history parameter in the link configuration.
template yes

full path to template GIF
The template GIF is the image that is used as a basis for the traffic map. All arrows, labels, etc. are drawn on top of this image.
prefix yes

path prefix for output files
This is the initial prefix for all output files. Whenever template runs, it will create the files prefix.html and prefix.gif.
archive yes

path to archive directory
This is the directory where the archived GIF files are kept. This directory should not contain any subdirectories or any files other than the archived GIFs.
legend no

vertical location of legend (upper or lower)
horizontal location of legend (left or right)
This indicates the corner of the image where the legend should be placed.
legendtitle no

text of legend title
If a legend is displayed, this text will appear immediately above it or below it, depending on the legend location.
colors yes

number of colors in palette
This specifies the number of colors in the traffic scale. Note that if you are displaying a legend and the number of colors causes the legend to be too large for the image, you will get a Segmentation Fault.
scale
no

type of scale (linear, log, or manual)
type of scale (absolute or relative)
lower end of scale (least significant divider)
upper end of scale (most significant divider)
This determines the type of scale that will be used to gradate the different levels of traffic. The first modifier determines whether to make the scale linear (0 - 10, 10 - 20, etc.), logarithmic (10^2, 10^3, etc.), or manual. The second modifier indicates whether you want the gradations to be based on the absolute amount of traffic or on the amount of traffic in proportion to the bandwidth of the link.

The two values following the type of the scale establish the initial and final breakpoints for the scale. In a linear scale, these should be explicit values; in a logarithmic scale, these should be exponents of 10. In a manual scale, no values are supplied here. Instead, you should include a scale section in your configuration file.

For example, if you are using five colors and you want a linear relative scale, you would use the line:
  scale linear relative 20 80
This would cause the scale to be 0-20%, 20-40%, 40-60%, 60-80%, and 80-100%.

The default value is:
  scale linear relative 10 90
title yes

name of this traffic map
This name is used as the title of the Web page and also appears at the top of the page. Note that the name you assign to this traffic map is also used by the animation-generating CGI scripts, so you should confirm that the name makes good grammatical sense in the context they provide.
background no

background color of the Web page
This parameter specifies the color to use for the background on the Web page and as a backdrop for the animated movies. It is specified using the format 0xRRGGBB, where RR, GG, and BB are two-digit hexadecimal values for red, green, and blue, respectively. The default value is 0xFFFFFF.
time no

upper left x-coordinate
upper left y-coordinate
If you include this parameter, a timestamp (the output of the Unix date command) will be displayed at this location on the output image.
clock no

upper left x-coordinate
upper left y-coordinate
diameter of clock
location of PM indicator (up, left, right, down)
If you include this parameter, an analog clock will be displayed on the output image at the given location with the specified size. The local system time is used. Between noon and midnight, the letters "PM" will appear next to the clock in the specified orientation.
refresh yes

refresh time in seconds
This specifies the refresh rate for the Web page in the user's browser. It does not affect the interval at which the template script is run.

Parameter	Required?	Arguments	Notes
`collector`	yes	full path to collector script	The full path to the external collector script. This script is run by `template` to collect the data on the status of each link. The script is given the name of the link and the number of seconds to use for the high water mark on the command line and expects output in the following format: current_bandwidth total_bandwidth maximal percent error (for high water mark) percent errors now percent errors 5 minutes ago percent errors 10 minutes ago : : n : : The amount of error history to return is dependent on the setting of the `history` parameter in the link configuration.
`template`	yes	full path to template GIF	The template GIF is the image that is used as a basis for the traffic map. All arrows, labels, etc. are drawn on top of this image.
`prefix`	yes	path prefix for output files	This is the initial prefix for all output files. Whenever `template` runs, it will create the files `prefix.html` and `prefix.gif`.
`archive`	yes	path to archive directory	This is the directory where the archived GIF files are kept. This directory should not contain any subdirectories or any files other than the archived GIFs.
`legend`	no	vertical location of legend (`upper` or `lower`) horizontal location of legend (`left` or `right`)	This indicates the corner of the image where the legend should be placed.
`legendtitle`	no	text of legend title	If a legend is displayed, this text will appear immediately above it or below it, depending on the legend location.
`colors`	yes	number of colors in palette	This specifies the number of colors in the traffic scale. Note that if you are displaying a legend and the number of colors causes the legend to be too large for the image, you will get a Segmentation Fault.
`scale`	no	type of scale (`linear`, `log`, or `manual`) type of scale (`absolute` or `relative`) lower end of scale (least significant divider) upper end of scale (most significant divider)	This determines the type of scale that will be used to gradate the different levels of traffic. The first modifier determines whether to make the scale linear (0 - 10, 10 - 20, etc.), logarithmic (10^2, 10^3, etc.), or manual. The second modifier indicates whether you want the gradations to be based on the absolute amount of traffic or on the amount of traffic in proportion to the bandwidth of the link. The two values following the type of the scale establish the initial and final breakpoints for the scale. In a linear scale, these should be explicit values; in a logarithmic scale, these should be exponents of 10. In a manual scale, no values are supplied here. Instead, you should include a scale section in your configuration file. For example, if you are using five colors and you want a linear relative scale, you would use the line: scale linear relative 20 80 This would cause the scale to be 0-20%, 20-40%, 40-60%, 60-80%, and 80-100%. The default value is: scale linear relative 10 90
`title`	yes	name of this traffic map	This name is used as the title of the Web page and also appears at the top of the page. Note that the name you assign to this traffic map is also used by the animation-generating CGI scripts, so you should confirm that the name makes good grammatical sense in the context they provide.
`background`	no	background color of the Web page	This parameter specifies the color to use for the background on the Web page and as a backdrop for the animated movies. It is specified using the format `0xRRGGBB`, where `RR`, `GG`, and `BB` are two-digit hexadecimal values for red, green, and blue, respectively. The default value is `0xFFFFFF`.
`time`	no	upper left x-coordinate upper left y-coordinate	If you include this parameter, a timestamp (the output of the Unix `date` command) will be displayed at this location on the output image.
`clock`	no	upper left x-coordinate upper left y-coordinate diameter of clock location of PM indicator (`up`, `left`, `right`, `down`)	If you include this parameter, an analog clock will be displayed on the output image at the given location with the specified size. The local system time is used. Between noon and midnight, the letters "`PM`" will appear next to the clock in the specified orientation.
`refresh`	yes	refresh time in seconds	This specifies the refresh rate for the Web page in the user's browser. It does not affect the interval at which the `template` script is run.

Scale Entries

Sample

  scale 0.005
  scale 0.01
  scale 0.05
  scale 0.1
  scale 0.5
  scale 1.0
  scale 2.0
  scale 5.0
  scale 10.0
  scale 30.0
  scale 60.0
  scale 70.0
  scale 80.0
  scale 90.0

Explanation

This section is only required when you are using a manual scale. Each line in this section consists of the string scale, followed by one of the breakpoints to use for the scale.

The number of entries in this section should be equal to the number of colors minus one. The minimum and maximum values of an absolute scale are always 0 and +Infinity, and the minimum and maximum values of a relative scale are always 0 and 100.

These entries may be specified in any order; they will be sorted for you. Note that there is no default manual scale -- if you want a manual scale, this section must be present and complete.

Palette Entries

Sample

  palette  1      0 255   0
  palette  5.5  255 255   0
  palette  10   255   0   0

Explanation

Each line in this section consists of the string palette; followed by the color index affects; followed by red, green, and blue color values.

These lines determine the colors that are used in the color scale for the traffic map. Each line fixes an RGB value for a specific color index (which can be a fractional value). The color indices between specified points are linearly interpolated from the points for which data is available.

In the example, the scale will vary from green (0, 255, 0) to yellow (255, 255, 0) to red (255, 0, 0), with the spaces between these colors being interpolated.

If you do not specify the initial or ending color values, they will default to pure green (0, 255, 0) and pure red (255, 0, 0), respectively. (Note that this omits yellow, which makes for some ugly colors in the middle!)

Alternatively, you can specify a color using the format 0xRRGGBB, where RR, GG, and BB are two-digit hexadecimal code for the red, green, and blue values, respectively.

Links (Arrows)

Sample

  link STTL-to-SCRM  arrow     121 32 100 195
  link STTL-to-SCRM  percent   124 41 relative
  link STTL-to-SCRM  width     10
  link STTL-to-SCRM  style     left point
  link STTL-to-SCRM  speed     OC-12
  link STTL-to-SCRM  errormax  1
  link STTL-to-SCRM  errormin  0.001
  link STTL-to-SCRM  history   3
  link STTL-to-SCRM  highwater 3600

Explanation

Each line in this section consists of the string link, followed by the name of the link, followed by the name of the parameter, followed by the arguments.

Parameters

Parameter Required? Arguments Notes
arrow yes

x-coordinate of arrow base
y-coordinate of arrow base
x-coordinate of arrow head
y-coordinate of arrow head
These coordinates specify the location of the center of the logical arrow and the tip of the arrow head. (The "logical" arrow is the arrow with both sides drawn. Thus, the same arrow parameter can be used to draw a half arrow in the same position as a full arrow.)
percent no

upper left x-coordinate
upper left y-coordinate
measure type (relative, absolute)
If this parameter is specified, a small box containing the current bandwidth usage will be superimposed on the traffic map at the specified location.

If the measure type is relative, then the value displayed is a percentage of total bandwidth. The box shows a two-digit integer value; 100% will be displayed as "max". This box is 24 pixels wide.

If the measure type is absolute, then the value displayed is an absolute number of bits per second. The box is big enough to hold four characters; standard metric abbreviations are used for large values. (Examples are 5.7M and 36k.) This box is 32 pixels wide.

The default measure type is relative.
width no

width of the logical arrow
If this parameter is not specified, the template script will use the value of the speed parameter to determine the arrow width. If width is omitted and the speed value either isn't an integer or isn't defined, expect undesired results. (Again, the "logical" arrow is the arrow with both sides drawn.)
style no

width style (left, right, full)
point style (point, stub
This parameter specifies what type of arrow is drawn and defaults to full point. "Left" and "right" in this case are defined from a perspective in which the point of the arrow is "up" and the base of the arrow is "down". A "stub" arrow does not have a point but does have wings on the sides of the head to indicate directionality.
speed no

speed of the link
This parameter is included primarily for the benefit of the person generating the configuration file. It is not used for anything unless the width parameter has been omitted.
history no

number of error values to use
This parameter controls the number of historical values for error percentage that the template script expects to receive from the collector script. If the network devices are being polled every five minutes, a history value of "3" means that a total of fifteen minutes of error history will be used in preparing the current GIF: the current value, 5 minutes ago, and 10 minutes ago. Error bars resulting from old data are drawn in shades between black and the normal color of the link.

The default value is 1, which means that only the current percentage of errors will be taken into account.
errormax no

top of scale for error percentage
When the number of errors on a link reaches this percentage reaches this level or above, the entire shaft of the arrow (excluding the head) will be rendered in black. When setting this value, recall that the error bar operates on a logarithmic scale. The default value is 1 (1% of total packets in error or dropped).

When the error rate is maximal or the link is down, the percent box will also appear in reverse video (white on black).
errormin no

bottom of scale for error percentage
When the number of errors on a link is at this level or below, there will be no visible error bar on the link. When setting this value, recall that the error bar operates on a logarithmic scale. The default value is 0.001 (0.001% of total packets in error or dropped).

highwater no

number of seconds for high-water mark
This parameter affects the number of seconds of error data taken into account when calculating the high-water value for the error level. The default value is 1800 seconds (half an hour).

Parameter	Required?	Arguments	Notes
`arrow`	yes	x-coordinate of arrow base y-coordinate of arrow base x-coordinate of arrow head y-coordinate of arrow head	These coordinates specify the location of the center of the logical arrow and the tip of the arrow head. (The "logical" arrow is the arrow with both sides drawn. Thus, the same `arrow` parameter can be used to draw a half arrow in the same position as a full arrow.)
`percent`	no	upper left x-coordinate upper left y-coordinate measure type (`relative`, `absolute`)	If this parameter is specified, a small box containing the current bandwidth usage will be superimposed on the traffic map at the specified location. If the measure type is `relative`, then the value displayed is a percentage of total bandwidth. The box shows a two-digit integer value; 100% will be displayed as "`max`". This box is 24 pixels wide. If the measure type is `absolute`, then the value displayed is an absolute number of bits per second. The box is big enough to hold four characters; standard metric abbreviations are used for large values. (Examples are `5.7M` and `36k`.) This box is 32 pixels wide. The default measure type is `relative`.
`width`	no	width of the logical arrow	If this parameter is not specified, the `template` script will use the value of the `speed` parameter to determine the arrow width. If `width` is omitted and the `speed` value either isn't an integer or isn't defined, expect undesired results. (Again, the "logical" arrow is the arrow with both sides drawn.)
`style`	no	width style (`left`, `right`, `full`) point style (`point`, `stub`	This parameter specifies what type of arrow is drawn and defaults to `full point`. "Left" and "right" in this case are defined from a perspective in which the point of the arrow is "up" and the base of the arrow is "down". A "stub" arrow does not have a point but does have wings on the sides of the head to indicate directionality.
`speed`	no	speed of the link	This parameter is included primarily for the benefit of the person generating the configuration file. It is not used for anything unless the `width` parameter has been omitted.
`history`	no	number of error values to use	This parameter controls the number of historical values for error percentage that the `template` script expects to receive from the collector script. If the network devices are being polled every five minutes, a history value of "`3`" means that a total of fifteen minutes of error history will be used in preparing the current GIF: the current value, 5 minutes ago, and 10 minutes ago. Error bars resulting from old data are drawn in shades between black and the normal color of the link. The default value is `1`, which means that only the current percentage of errors will be taken into account.
`errormax`	no	top of scale for error percentage	When the number of errors on a link reaches this percentage reaches this level or above, the entire shaft of the arrow (excluding the head) will be rendered in black. When setting this value, recall that the error bar operates on a logarithmic scale. The default value is `1` (1% of total packets in error or dropped). When the error rate is maximal or the link is down, the percent box will also appear in reverse video (white on black).
`errormin`	no	bottom of scale for error percentage	When the number of errors on a link is at this level or below, there will be no visible error bar on the link. When setting this value, recall that the error bar operates on a logarithmic scale. The default value is `0.001` (0.001% of total packets in error or dropped).
`highwater`	no	number of seconds for high-water mark	This parameter affects the number of seconds of error data taken into account when calculating the high-water value for the error level. The default value is `1800` seconds (half an hour).

Areas (Hotlinks)

Sample

  area SCRM-STTL  url      composite-link.cgi?A=SCRM&B=STTL
  area SCRM-STTL  polygon  115 30 128 34 104 194 93 193
  area SCRM-STTL  text     Seattle <-> Sacramento (OC12)

Explanation

An "area" is a polygon in the final image that is an anchor for some URL. Note that areas are completely decoupled from links -- there is no default clickable area in the image map for a link. Areas do not have to be for links; for example, you could link the legend or title to a document if you wanted to.

Each line in this section consists of the string area, followed by the area name, followed by the parameter name, followed by the arguments. The area name is used only to group related parameters.

Parameters

Parameter Required? Arguments Notes
url yes

absolute or relative URL
This is the URL the area will link to. Relative URLs are based in the directory from which the traffic map was accessed.
polygon yes

x-coordinate n
y-coordinate n
This list of points defines the limits of the clickable area on the image map. Note that an arbitrary number of points may be specified. It is not necessary to make the final coordinate the same as the first; the closing line segment is inferred.
text no

alternate text
This parameter specified text that will be stored in the ALT and TITLE attributes of this area in the image map. In most browsers, this text will be displayed in the status line.

Parameter	Required?	Arguments	Notes
`url`	yes	absolute or relative URL	This is the URL the area will link to. Relative URLs are based in the directory from which the traffic map was accessed.
`polygon`	yes	x-coordinate n y-coordinate n	This list of points defines the limits of the clickable area on the image map. Note that an arbitrary number of points may be specified. It is not necessary to make the final coordinate the same as the first; the closing line segment is inferred.
`text`	no	alternate text	This parameter specified text that will be stored in the `ALT` and `TITLE` attributes of this area in the image map. In most browsers, this text will be displayed in the status line.

Labels

Sample

  label ATL   spot     600 294 15
  label ATL   color    192 192 192
  label ATL   text     610 299
  label ATL   caption  ATL

Explanation

A "label" is a colored spot on the image with an optional caption. This is intended to represent individual network nodes, participating cities, etc.

Each line in this section consists of the string label, followed by the label name, followed by the parameter name, followed by the arguments. The label name is used only to group related parameters.

Parameters

Parameter Required? Arguments Notes
spot yes

x-coordinate of center
y-coordinate of center
diameter of spot
Note that the spots produced fall a little bit short of true roundness. This is a problem of the GD library. It shouldn't be too difficult to splice the Midpoint Ellipse Algorithm into the code in place of the call to arc().
color yes

RGB values for color
The recommended values for this parameter are (192, 192, 192) [gray] for inactive nodes and (0, 0, 255) [blue] for active notes, but any color may be used.
text no

upper left x-coordinate
upper left y-coordinate
These coordinates specify the location of the upper left corner of the caption for the label. If there is a caption, this parameter must be specified.
caption no

text of the caption
Note that the text will be rendered in black and the background of the caption is not cleared.

Parameter	Required?	Arguments	Notes
`spot`	yes	x-coordinate of center y-coordinate of center diameter of spot	Note that the spots produced fall a little bit short of true roundness. This is a problem of the `GD` library. It shouldn't be too difficult to splice the Midpoint Ellipse Algorithm into the code in place of the call to `arc()`.
`color`	yes	RGB values for color	The recommended values for this parameter are (192, 192, 192) [gray] for inactive nodes and (0, 0, 255) [blue] for active notes, but any color may be used.
`text`	no	upper left x-coordinate upper left y-coordinate	These coordinates specify the location of the upper left corner of the caption for the label. If there is a caption, this parameter must be specified.
`caption`	no	text of the caption	Note that the text will be rendered in black and the background of the caption is not cleared.

Interactive Animated Traffic Analysis (INANNA), Version 0.
Copyright 2000 by the Trustees of Indiana University.

Mark Meiss

Last modified: Fri Jul 7 14:08:51 EST 2000