LIBDIA - A PHP library for manipulating network diagram files created using DIA (http://www.gnome.org/projects/dia/) 1. APPLICATION 2. REQUIREMENTS 3. TYPICAL USAGE 4. THE MAP FILE 5. AVAILABLE FUNCTIONS 6. OTHER REMARKS 7. LICENSE 8. AUTHOR 1. APPLICATION This library was developed specifically solely for the purpose of displayin a live (or almost-live - updated every few minutes) map of a small backbone network consisting of few Cisco Catalyst switches. In short: - a network map is drawn using "dia"; the connections and devices on the map are marked appropiately (see below), - a PHP script using libdia loads the pre-drawn static map and inserts live network monitoring data information onto the map, outputting a PNG file that can be displayed on your Network Operations Center monitors. The live network data (eg. link utilization, packet loss, etc.) can be inserted as: - connection colors (eg. some connections on the map are changed to green, red, etc), - strings describing the connections, - strings describing the devices, - background colors of the connections' and devices' descriptions. 2. REQUIREMENTS libdia has been tested under PHP 4.4.2-1.1 (from Debian). Your PHP must support XML. The version of dia used in the author's environment is 0.95. Little effort needed in correcting the code is expected in case further versions of dia and/or PHP introduce any incompatibility with libdia. 3. TYPICAL USAGE require "libxml.php"; require "libdia.php"; $dia = new DiaGraph; // Initialize the library $dia->Load("maps/catalysts.dia"); // Load a diagram $dia->SetDeviceLabel("mesh", "mesh\nNot responding", "#ff0000"); // Set some device label to "mesh\nNot responding" // Set the background color to red $dia->SetLinkLabel("mesh-chikai", "100%", "#ff0000"); // Display some packet loss on a link and set the link // color to red $dia->SetLayerVisibility("Clients", false); // Disable displaying of some layer on the map header("Content-type: image/png"); $dia->SavePNG(); // Output PNG to standard output 4. THE MAP FILE libdia makes some assumptions about the dia map files that it is processing. A sample map is provided together with the libdia package (example.dia). Your static map must follow these guidelines: a. The map files are UNCOMPRESSED (if they are not, gzip -d them or uncheck "Compress diagram files" when saving diagrams in dia). b. A device is defined using any symbol (eg. from "Cisco" libraries) AND a "Flowchart - Box" object attached to the device symbol with a standard line. The "Flowchart - Box" object should contain the device name. Its contents is replaced with whatever is set using the SetDeviceLabel() function. Consult the example map. c. All connections between devices are defined using STANDARD lines (Bezier, PolyLine or just standard straight line). The lines have to be connected directly to the symbols representing devices. The lines representing a connection MUST have a defined color, ie. they CAN'T BE BLACK. d. If you want to set some texts describing links (this is optional), you need to create a "Flowchart - Box" object for every link and type "device1-device2" in the box (omitting the quotes); device1 and device2 are device names provided in the flowchart boxes describing the devices (see a.). The link descriptions set using libdia will substitute the link descriptions (device1-device2) in the box. Actually, these constraints are related to the process of opening a file by libdia. After doing the XML parsing, libdia: - Searches for all flowchart boxes in the diagram file. - Finds all lines connected to these boxes on one end, and to something else on the other end. The symbols that the lines are connected to on the other ends are understood to be DEVICES. The devices' names are taken from the flowchart boxes. - Finds all lines connecting two devices. These lines are considered to be links between the devices. - For every two device names, searches for a flowchart box containing only "name1-name2" or "name2-name1". These boxes are understood to be link labels. 5. AVAILABLE FUNCTIONS - $dia = new DiaGraph (Constructor - no arguments) Creates a DiaGraph object, used for manipulating the graph. You may load only one graph into a DiaGraph object. - $dia->Load(file) Loads a DIA file into the object. The file may not be compressed and must follow guidelines mentioned in (4). - $dia->Save(file) Saves a DIA file loaded into the object under the given name. - $dia->SavePNG([file]) Generates a PNG file from the DIA graph loaded into the object. Warning: the dia executable is called to perform this task. Thus this will not work in PHP safe mode (system()). The path to "dia" is hardcoded in the code ("/usr/bin/dia"). If no file name is given, the image is outputted to stdout (remember to set Content-type). - $dia->ListDevices() Returns an associative array containing the names of devices found in the file as keys. - $dia->ListLayers() Returns an associative array containing the names of layers found in the file (as keys). - $dia->ListLinks() As above - list of links is returned in keys of an associative array (the link names are in form "device1-device2", eg. "ergsun-mesh"). - $dia->SetLayerVisibility(layername, visible) Makes a graph layer visible (visible = true) or not (visible = false). - $dia->SetDeviceLabel(device name, string, [background], [foreground]) Replaces text in the "Flowchart Box" describing device named "device name" with given string (UTF8). If "background" and/or "foreground" arguments are provided, the flowchart box background color and/or the text color is changed as well (use HTML-like hex-triplet notation eg. "#ff0000"). - $dia->SetLinkLabel(link name, string, [linkcolor], [background], [foreground]) Similar to above - updates a link label. The link name should be given in the form "device1-device2" (it may be swapped - libdia will try both variants). If the 3rd argument is provided, the color of the line representing link is set to [linkcolor]. Link labels are optional in the map file and to change a link's line color you do not need to have it labeled. (the "string" argument is ignored if no label is found). 6. OTHER REMARKS All text is encoded using UTF-8. If you want to use PNG output (which is probably the case), you need to have dia installed on your server. If PNG output does not work, please see libdia.php around line 212 and check if the path to dia executable is correct for your system: system("/usr/bin/dia >/dev/null -e \"" . $outname . "\" -t png " . $tmpfile); 7. LICENSE This package is distributed under terms of GNU General Public License. See http://www.gnu.org/copyleft/gpl.html for the license text. 8. AUTHOR Mateusz Golicz . Any feedback is appreciated. Please note that the author is not a native English speaker and is aware of the fact that his language is far from perfect. Reports on mistakes in this text are also welcome. The simple XML parsing code in libxml.php was based on code included in a user comment at www.php.net submitted by .