Geomap shows network information on a geographical map. The map data comes from OpenStreetMap

The network is shown as colored points and lines. Each point represents a collection of netboxes; each line represents the set of connections between the netboxes in the points at either end of the line. What the colors and sizes of points/lines represent is shown below the map (this depends on the chosen variant and on the configuration).

Netboxes are combined into points by the following rules:

• All netboxes in the same room are always shown in the same point. Only rooms have geographical locations stored in the database, so the different netboxes in one room are, as far as Geomap knows, at exactly the same position.
• Rooms which would be shown very close to each other at the current zoom level of the map are combined into one point. (The exact limit for how close they can be before they are combined is chosen somewhat arbitrarily).

When clicking on a point or line, information about the corresponding objects is shown in a popup box.

The map can be manipulated in the following ways:

• Drag with mouse to move map.
• Use the zoom bar at the top left or the mouse's scroll wheel to zoom.
• Double-click on a point to center on that point and zoom in.
• Drag mouse while holding the Shift button to zoom in to an arbitrary area.

The map shows load data (unless configured to not show it) from a user-selectable time interval, by default a five minute interval which ended 5–10 minutes ago.

Five interval sizes are available: month, week, day, hour, five minutes. The intervals are always aligned to the natural boundaries (so a day always goes from midnight to midnight, a week from monday to sunday, etc.).

Navigation in the map and selection of time interval is a client-side affair which does not involve moving to a different web page. To make it possible to create links (or bookmarks) showing specific selections of map area and time, the web page contains a link called “Link to this configuration” which is continously updated to always reflect the current state of the page.

Geomap may be configured to appear in arbitrarily many variants, each of which may differ in the information shown in the popup boxes and the information indicated by the color and size of lines and points. Each variant has its own URL: /geomap/variant-name/, and the access rights required to show the map web page can thus be different for different variants.

In the default configuration there are two variants:

• normal: Shows all available information. Requires an authenticated user.
• open: Does not show information about individual netboxes. Available for everyone.

Geomap's main configuration file is the file geomap/config.py relative to the NAV configuration directory. This file defines how the style attributes (size and color) of lines and nodes being drawn depends on properties of the network entities they represent (such as link load and capacity), and references template files which control the contents of the popup boxes which appear when clicking on a node or line. It also defines which variants exist, and all configuration is specified separately for each variant.

The syntax of config.py is a form of pseudo-Python. The file has block structure indicated by colons and indentation like Python, and certain parts are Python expressions. However, it also uses Python keywords like 'def' and 'if' with somewhat different meanings than they have in Python, and unless specifically noted in the description below, everything in the file may be assumed to not be Python code. The syntax and keywords are chosen such that it is convenient to edit the file with Emacs' (and hopefully other editors') Python mode.

On the top-level, config.py contains the definitions of one or more variants. A variant definition is a block introduced by a line on the form

where URL-name and display-name are the name of the variant as it appears in URLs and in text, respectively. URL-name should be a symbol, display-name a string (display-name is evaluated as a Python expression). Example:

The variant block should contain references to template files, and should define style properties for all possible cases (by style or indicator definitions).

Template file references have the following form:

template_file(name, filename) |

where name specifies what the template should be used for (either node_popup or edge_popup) and filename is the name of the template file, relative to the geomap configuration directory. filename should be a string (it is evaluated as a Python expression). Example:

template_file(node_popup, 'node_popup.html')

Style properties of nodes and lines are specified either by style definitions, which simply set a certain property on all edges or nodes, or by indicators, which specify several choices and criteria for selecting between them.

Style definitions have the following form:

where feature-type is either edge or node, style-property is either color or size, and value a valid value for the property (value is evaluated as a Python expression). For size, the value is the width (lines) or radius (nodes) in pixels, and should be an integer. For color, the value should be a string on the form “#RRGGBB” with RGB values in hexadecimal. Examples:

style(edge, size, 10)
style(edge, color, '#C0FFEE')

An indicator is defined by a block introduced by a line

and contains two or more options on the following form:

feature-type, style-property and value have the same semantics as in style definitions. test is used to determine which of the options to use for a certain feature. For each node or edge (depending on the feature-type parameter of the indicator), the test of each option is evaluated as a Python expression, with all node/edge properties (see list in discussion of template files below) bound to their values for the node or edge in consideration; the first option for which the test evaluates to a true value is used. indicator-name and option-name are used in the legend shown together with the map (both are evaluated as Python expressions and should be strings).

The test of the last option in an indicator should always be True, to ensure that the choice of value is defined in all cases.

Template files for popups are Django template files (see syntax specification) and should produce HTML content appropriate for appearing inside a DIV element (the HTML content should conform to XHTML 1.0 Transitional).

In addition to Django's builtin tags and filters, two additional filters are available for these templates:

nan2none: Convert the NaN floating point value to None (all other values go through the filter unchanged). Since unknown values for the 'load', 'load_in' and 'load_out' parameters (see below) are coded as NaN, but None is often easier to treat as a special case (several of Django's filters, e.g. the 'default' filter, treat None specially), this may be useful before another filter.

format: Format the value using the argument as format string. Example:

{{ answer|format:"The answer is approximately %.4f" }}

If answer=42.001823, this generates “The answer is approximately 42.0018”.

The relevant feature is exposed to the template as a variable named network (for edges) or place (for nodes). These objects are dictionaries with the keys shown below.

Place:

• load: maximum CPU load for all netboxes in the place
• num_rooms: number of rooms the place consists of
• num_netboxes: total number of netboxes in all rooms
• rooms: list of rooms, each of which has the following properties:
  • id: id/name of the room (db: room.roomid)
  • descr: room description (db: room.descr)
  • load: maximum CPU load for all netboxes in the room
  • num_netboxes: number of netboxes in the room
  • netboxes: list of netbox objects, each of which has the following properties:
    • netboxid
    • sysname
    • ip
    • catid
    • up
    • type (db: type.descr)
    • roomid
    • room_descr (db: room_descr)
    • location (db: location.descr)
    • load: CPU load

(all uncommented properties correspond to fields of the same name in the netbox table in the database)

Network:

• capacity: sum of capacity for all edges this consists of
• load_{in,out}: sum of load_{in,out} for all edges this consists of
• subedges: list of original edges this consists of, each of which has the following properties:
  • capacity: link capacity in Mbps
  • {local,remote}_interface
  • {local,remote}_sysname
  • {local,remote}_{g,s}wportid
  • {local,remote}_portid
  • nettype
  • netident
  • layer
  • vlan
  • load_{in,out}: link load in Mbps

Syntax errors in the configuration file cause all requests to give 500 (internal server error) responses (which may or may not include useful information, depending on the configuration of Django and/or NAV).

Other errors cause a message of level WARNING to be logged (this should appear in Apache's error.log), and may make the nodes/lines on the map and the legend look funny.