Netmagis
| Topo package configuration |
The topo package is one of the most innovative parts of the Netmagis software. This document describes its configuration.
Principles of operation
The topographd daemon
The topographd daemon perform the following tasks:
- it reads the vlan list from the database (that you manage via the Admin / Modify VLANs menu) and the equipment list (that you manage via the Admin / Modify equipments menu)
- it then generates a router.db file (under the format expected by the Rancid software) and then calls this software to fetch all configuration files from your equipments
- it performs a syntactic analysis on the fetched configuration files to get a model of each equipment
- it then collects all "virtual equipments" that you have designed in order to represent equipments which either are not fetchable via Rancid (equipments not smart enough, or equipments not administered by you) or are not analyzable by the topo package
- from all these files (models from real equipments and models from virtual equipments), it builds a graph of the whole network, by joining links based on an information (link name) which must be set on each network interface
- if an error or an anomaly is detected, a mail is sent to the address you configured (via the Admin / Application parameters menu), and the error message is stored in the database (you can watch it with the Topo status menu)
- the network graph is then copied to the www server in order to present informations to users
- a sensor list is stored in the database, which will be used by the metro package to initialize SNMP polling
Each time an equipment is modified, an event is reported either to a syslog server or a Radius server. The detecteq package reports these events in the database. Other changes (such as when the equipment or vlan list is modified in the database, or a virtual equipment file is modified) are reported.
So, the network graph is rebuilt:
- each time an equipment configuration is changed
- each time the equipment list or vlan list is modified
- each time a virtual equipment file is modified
The Web application
The web application, if the topo package is enabled (via the Admin / Application parameters menu), will allow access to users based on authorizations specified in the Admin / Modify users and groups.
Informations are accessed from the network by using some specialized programs such as dumpgraph, extracteq, extractl2, etc. These informations are displayed graphically using the great Graphviz software.
The toposendd daemon
Each time a user is modifying an interface port configuration (VLAN, description or sensor) (via Topology / Equipments / Edit), an information is added to a pool of waiting modifications that you can watch by using the Topod status / Waiting changes menu).
The toposendd daemon perform the following tasks:
- it reads the queue of waiting changes
- for each equipment which must be modified, it builds the string of configuration commands (that you can specify to your local taste with the Admin / Modify configuration commands)
- it then sends the string of configuration commands to the equipment using the Rancid software (and more specifically the send* parameters of netmagis.conf.
- when the configuration is sent, the equipment reports a modification via syslog or radius, and the topographd will notice it and rebuild the network graph.
Configuring your equipments
Principles
The approach used by Netmagis differ from other software in that Netmagis does not try do discover your topology, but it uses informations that you provide via equipment configurations, between "<" and ">" in interface descriptions.
These informations are twofold:
- Connectivity between equipments: you specifiy the same link number or name on both equipment interfaces. Since each interface must have such an information, edge ports of your network (those connected to hosts or servers) are marked with a special symbol.
- Metrology sensors: you can specify a SNMP poller (and associated database) with each interface or VLAN, which will be used by the metro package.
Link numbers
Netmagis provides an easy way to get and keep track of link numbers: if a group is authorized (via the Admin / Modify users and groups / Permission to generate link numbers item), the Topology / Link number menu item generates a sequential, unique id which you can use as a link number.
Insert link numbers or names prefixed with a "L" letter, bracketed with "<" and ">", in the description of the interface on each side of the link:
Equipment Example Juniper ge-0/1/0 {
description "blah blah <L233>;
}Cisco interface GigabitEthernet0/1
description blah blah <L233>HP interface A1
name "blah blah <L233>"
Edge ports
Ports connected to individual hosts must be marked with a "<X>" to indicate a terminal node in the graph.
Metrology sensors
In addition, sensors may be added in the same way with a letter "M". Use a meaningful string. For example, you can use the link number and add the name of the equipment to mark the viewpoint on this metrology graph.
For example, on a Juniper equipment:
description "blah blah <L233 M233.this-router>"
You can add sensors on edge ports. The name of the sensor may be an port name, or another string. For example on a Cisco switch:
description blah blah <X myswitch.boss-pc>"
Metrology sensor names are kept for a certain duration. If you change the port of one host, you can use again the sensor name on the new port (provided you make it disappear from the old port since sensor names must be unique at one time). This way, you can preserve history.
Integrating your equipments into Netmagis
Enable topo
To enable the topo package, you must:
- configure the application to enable the topo package, via the Admin / Application parameters / Enable topo item). You must also provide valid email addresses for the topographd email report.
- start the topographd daemon (and optionaly the toposendd daemon if you want to change port characteristics from the Web application).
- check the Topod status page for running errors
Inserting new equipments
As described above (see topographd description), you just have to add your equipment name in the equipment list (via the Admin / Modify equipments).
Make sure that your equipments are registered as hosts in the Netmagis database.
Slow start
It this is the first time you configure the Netmagis topo package, the suggested way is to:
- modify an equipment configuration to have only edge ports (i.e. marked with "<X>")
- wait for the topographd daemon, and check the Topo / Equipment page
- change an interface for a link number, and add the remote equipment with all interfaces marked with "<X>" except the linked port.
This way, you can add the first equipments and correct errors as soon as they occur.
Adding virtual equipments
It may happen that some equipments do not fit the model described above:
- some equipments are not smart enough to have a configuration file
- some equipments are not under your responsability, so you don't have their password
- or their syntax is not recognized by the topo package
Some example virtual equipments are available in the .../share/examples/eqvirt/ directory installed with the topo package. They are heavily commented.
The .../lib/netmagis/topo/doteq script is a convenient way to graphically display the structure of a virtual (or real) equipment. It can help you build your description and find bugs.