Ten things to try with InterMapper when you're first checking it out. Learn how to create maps, make them attractive, send alerts, make strip charts, etc
This page lists ten thing you can try with InterMapper to get more familiar with it. You can also refer to the InterMapper User Guide for more information.
Install InterMapper Installation is simple - no matter what platform you use. To install InterMapper:
Building Maps There are several ways to create maps—autodiscovery, entering addresses manually, and importing a file. Before you proceed, you may want to download the Hands-on Examples because it has some files for the following steps. Things to try:
Autodiscovery InterMapper can scan a network to find devices
Manual Entry You can also add devices manually by typing or pasting a list of DNS names or IP addresses into the window that appears.
Import a file InterMapper can read a tab-delimited file to populate a map.
Geographic positioning When importing, InterMapper also can place devices on a map according to their latitude and longitude.
Create top-level map InterMapper can have top-level maps that indicate the most serious condition of a sub-map. We'll add icons for the Local Network and the Unalakleet sub-maps to the North America map.
Making Attractive Maps There are a number of techniques for making the maps look more attractive, or to convey more information. Things to try:
Probes for Various Servers In addition to simply pinging them, InterMapper can monitor dozens of different devices and display their special characteristics. Right/control-click, or Monitor > Set Probe... to select the probe for one or multiple selected devices. Things to try:
Alerts and Notifications InterMapper can put a device into one of five states: OK, Critical, Warning, Alarm, Down. Each time the device goes into a new state, InterMapper can trigger a notification/alert.
Acknowledgement After alerts/notifications have been sent, you probably want to set those problems aside so you can detect new ones. Acknowledging a device turns its icon blue (to indicate that it has been acknowledged). The device is still down, but its blue color shows that someone has taken responsibility for it. Acknowledging also helps you know who's working on the problem. Each time you ack a device, there's an opportunity to enter an ack message, that is written to the Event log. This contains the login name of the person who ack'd it.
Monitor > Acknowledge... (Ctl/Cmd-') This does three things:
Basic ack Only for duration of that state
Dependencies InterMapper will suppress notifications if it can tell that a device is unreachable because of another failure. InterMapper supports automatic dependencies—it follows the links from the vantage point through the map to the failed device. If there's an outage on that path, InterMapper won't send notifications for the dependent device.
Strip Charts Gives history of certain variables.
Edit > Server Settings The server settings shows the preferences for a server.
InterMapper RemoteAccess Allows you to have all this fun, but from anywhere on the Internet
How to import devices and have them placed in the proper location on the map using latitude and longitude information
InterMapper can import information about devices from a tab-delimited file. If that file contains latitude and longitude for the devices, InterMapper can place the icons on the proper place on the map.
In order for InterMapper to place the devices properly, you must first define two benchmarks that indicate the latitude and longitude of two points on the map. InterMapper can then interpolate the device's location onto the map.
Execute the following steps to see how to import using latitude and longitude:
Retrieve the import data file and unzip the file. This contains two files:
Create a new map (File > New Map). Name it Unalakleet
Drag the Unalakleet.gif file's icon into the Unalakleet map window. You should see the map fill the window as a background image.
Optionally, choose Window > Zoom Window to make the window size match the background image.
Create the benchmarks on the image. To do this right-click (control-click) one of the cities in the table below on the map, and choose Add Benchmark...
Enter the latitude and longitude for that city:
Add a benchmark for the other city.
Use File > Import > Map Data... to import the Unalakleet Import.tab file. You will see a confirmation that nine devices were added to the map.
That's it! Check the map to see how the icons have been placed in the correct position.
You can geocode a number of locations in a single file by following the instructions shown in the Batch geocoding devices for importing into InterMapper article in the Knowledge Base.
InterMapper 5.1 exports the following information so that Google Earth can place them in the proper location.
View a video: You can view a short tutorial video about Google Earth Integration from the Product Videos section of the Video tours page.
To be displayed in Google Earth, a device must have geographic information; devices that do not have geographic information are not displayed at all. Geographic information may be set in two ways:
In the latter case, the device's latitude and longitude are inferred from the x/y position on the map, relative to the established benchmarks; this process is inherently imprecise. In the case where both explicitly set coordinates and benchmarks are available, InterMapper uses the explicitly set coordinates and ignores the benchmarks.
Google Earth requests information from the InterMapper server using HTTP. Consequently, the InterMapper web server interface must be enabled in the Server Settings. The Google Earth connection uses the same authentication method as the web interface; you must have appropriate web access permissions for any map you wish to view in Google Earth. (Google Earth will prompt you for the username and password.) Google Earth does not need to be installed on the InterMapper server, though its machine must have appropriate access permissions established in the InterMapper web server firewall.
Google Earth uses a "Network Link" with a URL that Google Earth uses to request information from InterMapper.
The easiest way to get the URL is to use the InterMapper web interface. Go to a map's page, and click the "View this map in Google Earth" at the bottom of each page. That link returns a .kml file; assuming Google Earth has been properly installed, your browser should offer to open that link in Google Earth; if it does not, save the resulting file and open it manually in Google Earth. When everything is properly set up, you will see the status badges for your devices hovering over the surface of the Earth in appropriate locations. You may click on a device badge and see the corresponding Status Window. The map refreshes automatically every 5 minutes.
InterMapper Flows 1.1 can handle sFlow data from HP, Extreme, Foundry, Force10 and other network equipment. sFlow provides information about the traffic through the network, including the sender and recipient of the traffic flows as well as the protocols involved.
To configure InterMapper Flows to receive the sFlow data, you must first enable sFlow export on the router or switch. Most modern gear uses SNMP to enable/disable sFlow export, as described in the sFlow specification.
InterMapper Flows has an option on its Exporters tab of the Server Settings that lets you specify the exporter(s) that should send data. To use it:
Open the Flows Settings window, and click the Exporters tab.
Set the sFlow port (default is 6343) at the bottom of the window.
Click the Add sFlow exporter button. You'll see the "Enter sFlow Information" window. Enter the IP address of the exporter, the SNMP read/write community string, select the proper IP address for the collector, and the sampling rate, then click OK.
InterMapper Flows configures (via SNMP) the selected exporter to send (to "export") sFlow records for subsequent display. You should see the exporter appear in the Exporters list very soon after enabling it.
Links to helpful information on using InterMapper Flows
InterMapper Flows is an add-on to InterMapper, and is a simple installation to an existing InterMapper system.
NetFlow provides detailed information about the sources and destinations of traffic flows on their network. InterMapper Flows acts as a NetFlow collector to receive the exported flow information and display it in an attractive user interface.
Cisco has written a white paper that has a list of Cisco equipment that supports NetFlow.
The Cisco Netflow Configuration Guide gives a detailed description of configuring Cisco gear. The section on NetFlow (URLs below) gives details on configuring NetFlow:
As a quick guide, the following commands will generally configure a Cisco router or switch to send NetFlow packets to InterMapper Flows. In this example, we configure the two ethernet interfaces - Ethernet0 and Ethernet1 (eth0 & eth1) - to send NetFlow version 5 data to the default NetFlow port - 2055.
% telnet <address-of-router> Trying <address-of-router> Connected to <address-of-router> Escape character is '^]'. User Access Verification Password: Kerberos: No default realm defined for Kerberos! <== Type router password here cisco2514>enable Password: <== Type router password here, too cisco2514#configure terminal Enter configuration commands, one per line. End with CNTL/Z. cisco2514(config)#ip flow-export destination <address-of-collector> <port> cisco2514(config)#ip flow-export source <interface> <== e.g., Ethernet0 cisco2514(config)#ip flow-export version <version> <== e.g., 1, 5, or 9 cisco2514(config)#ip flow-cache timeout active 1 <== Active flows timeout in 1 minute cisco2514(config)#ip flow-cache timeout inactive 15 <== Inactive flows timeout in 15 seconds cisco2514(config)#int eth0 cisco2514(config-if)#ip route-cache flow cisco2514(config-if)#exit cisco2514(config)#int eth1 cisco2514(config-if)#ip route-cache flow cisco2514(config-if)#exit cisco2514(config)#^Z <== Type Control-Z here cisco2514#write Building configuration... [OK] cisco2514#exit Connection closed by foreign host. %
You can use the following commands to check the NetFlow configuration. The show ip flow export command shows that NetFlow version 5 records are being sent from the source address of Ethernet0 to <address-of-collector> on port 2055.
cisco2514#show ip flow export Flow export is enabled Exporting flows to <address-of-collector> (2055) Exporting using source interface Ethernet0 Version 5 flow records Cache for as aggregation: Exporting flows to <address-of-collector> (2055) 18911421 flows exported in 676473 udp datagrams 0 flows failed due to lack of export packet 357386 export packets were sent up to process level 0 export packets were dropped due to no fib 0 export packets were dropped due to adjacency issues 0 export packets were dropped due to fragmentation failures 0 export packets were dropped due to encapsulation fixup failures
The show ip cache flow command shows information about the flows themselves, including the distribution of the packet sizes, number of flows seen, lost flow packets, and other statistics.
cisco2514#show ip cache flow IP packet size distribution (55479535 total packets): 1-32 64 96 128 160 192 224 256 288 320 352 384 416 448 480 .000 .882 .017 .023 .000 .001 .000 .001 .007 .011 .000 .000 .000 .000 .000 512 544 576 1024 1536 2048 2560 3072 3584 4096 4608 .000 .000 .003 .000 .051 .000 .000 .000 .000 .000 .000 IP Flow Switching Cache, 278544 bytes 189 active, 3907 inactive, 18842664 added 428276059 ager polls, 0 flow alloc failures Active flows timeout in 1 minutes Inactive flows timeout in 15 seconds last clearing of statistics never Protocol Total Flows Packets Bytes Packets Active(Sec) Idle(Sec) -------- Flows /Sec /Flow /Pkt /Sec /Flow /Flow TCP-Telnet 23 0.0 108 40 0.0 26.0 12.3 TCP-FTP 770 0.0 12 63 0.0 0.1 6.1 TCP-WWW 40186 0.0 12 937 0.2 9.7 15.4 TCP-SMTP 2197 0.0 4 210 0.0 9.8 14.6 TCP-other 3939 0.0 956 1026 1.6 6.8 9.1 UDP-DNS 9151 0.0 1 100 0.0 2.4 15.4 UDP-NTP 380 0.0 1 76 0.0 1.3 15.5 UDP-TFTP 17768 0.0 1 70 0.0 2.2 15.5 UDP-other 1663272 0.7 2 177 1.6 2.2 15.4 ICMP 17104789 7.5 2 48 20.8 5.3 15.5 Total: 18842475 8.2 2 131 24.3 5.0 15.4 SrcIf SrcIPaddress DstIf DstIPaddress Pr SrcP DstP Pkts Et0 192.168.1.23 Null 192.168.1.255 11 F1CB 00A1 2 Et0 192.168.1.45 Et1 10.10.1.25 01 0000 0800 1 Et0 192.168.1.45 Null 10.10.1.21 01 0000 0800 2 Et0 192.168.1.45 Et1 10.10.1.23 01 0000 0800 2 ... etc...
nProbe is a software-only NetFlow exporter. You can use it to gather NetFlow traffic statistics if you don't have NetFlow-compatible routers or switches. nProbe listens to traffic on an interface, and exports NetFlow v5 & v9 flow records to a program like InterMapper Flows.
nProbe is open source software available from http://ntop.org. It has been created by the same people who make the well-known ntop network traffic probe software.
nProbe is fairly simple to use: you can install it on an old Windows, Linux, or OSX box, and configure it to send the flows to InterMapper Flows. We use it for testing here, connected to a hub between a router and the firewall.
Although Dartware cannot give support for using nProbe, we have received reports that nProbe works fine on Windows XP/2000, and on various flavors of Linux.
You can retrieve nProbe from this URL. Scroll to the bottom of the page, and look for the "demo copy" link after the Availability table. That page also has a link to their store where you can purchase a pre-built non-expiring version for your platform.
http://ntop.org/nProbe.html
This demo version has a limit of only 2000 flows exports before stopping.
On Windows, run the .exe file. I places nProbe in C:\Program Files\nProbe-Win32
On Linux/Unix/OSX, unzip the file, then chmod +x to make it executable.
Running nProbe from the command line the is easiest method, especially for a demo situation, because you can peruse the debug messages. The following options are the most important:
Thus the command line for Windows might be:
C:\Program Files\nProbe-Win32> nprobe /c -i 1 -n 192.168.2.11:2055 -b 1 -u 1 -Q 2
For Linux/Unix, the command line might be:
% nprobe -i eth0 -n 192.168.2.11:2055 -b 1 -u 1 -Q 2
Each of these commands would send flow records to InterMapper Flows at the IP address 192.168.2.11, on port 2055.
For initial setup, connect TransPort to Computer via switch or crossover cable:
Windows XP:
Linux or OS X:
ImageStream NetFlows Setup:
ImageStream Router Network Setup
Disconnect the Router from power and Network and Connect it to your Network in the appropriate location.
Don't forget to set the IP address and Subnet Mask on your computer back to their normal settings.
Open Intermapper Flows and check the Collectors for your new Collector and give it an appropriate name. It may take a couple of minutes before the first NetFlow data is sent from the ImageStream TransPort to the Intermapper Flows Server.
Note: The ImageStream TransPort router supports NetFlow v5 packets only.
Softflowd is a software-only NetFlow exporter. You can use it to gather NetFlow traffic statistics if you don't have NetFlow-compatible routers or switches. Softflowd listens to traffic on an interface, and exports NetFlow v5 & v9 flow records to a program like InterMapper Flows.
Softflowd is open source software available from http://www.mindrot.org/projects/softflowd/. It runs on Linux, FreeBSD, and Mac OS X, but you must have a compiler and development environment to compile it from the source code. If you wish to run a software exporter on Windows, you should take a look at nProbe.
If you are prepared to install software directly from the source code, softflowd is fairly simple to install and use: you can install it on an old Linux, FreeBSD, or OSX box, and configure it to send the flows to InterMapper Flows. We use it for testing here, running on the host that provides our IPv6 tunnel to the rest of the Internet.
Although Dartware cannot give support for using softflowd, we have received reports that it works fine on FreeBSD and Linux.
You can retrieve Softflowd from http://www.mindrot.org/projects/softflowd/. Scroll to the bottom of the page, and look for the "tar.gz" link under the Download heading. A cached tarball is also available.
Open a terminal window and change to the directory containing the "tar.gz" file. Before you build softflowd, verify that you have the development libraries for libpcap installed. If you don't, you can install libpcap-devel on RedHat systems using yum:
# yum install libpcap-devel
Expand the tarball and use the familiar configure; make; make install incantation:
# tar xfz softflowd-0.9.8.tar.gz # cd softflowd-0.9.8 # ./configure --prefix=/opt/softflowd # make # make install
Once the software is installed, you can access the man pages for softflowd and softflowctl:
man -M /opt/softflowd/share/man softflowd man -M /opt/softflowctl/share/man softflowctl
You must run softflowd from the command line. The following options are the most important:
The command line might be:
/opt/softflowd/sbin/softflowd -v 9 -i eth0 -n 192.168.2.11:2055
This command will send flow records to InterMapper Flows at the IP address 192.168.2.11, on port 2055.
Helpful information on custom SNMP probes
InterMapper's TCP Probes establish a connection to a remote system, exchange commands and receive responses, and then set the status of the device based on those responses.
This note describes how probe writers can use regular expressions and comparisons to parse out information from the responses.
There is an annotated FTP probe in the Developer Guide. This gives an overview of the script language and shows how it connects and logs into a FTP server, how a script can respond to error conditions, and how to set the device's status based on those conditions.
The following commands are all documented in the TCP Probe reference section of the Developer Guide.
The TCP Script Language uses the MTCH command to compare a response string to expected values. It can also use a regular expression to match on a part of a string. For example:
MTCH "A([BCD]+)E"r else goto @NOMATCH STOR "testval" "${1}"
If the incoming line contains ABDE, then the "testval" variable will contain "BD"
In the MTCH regular expression, enclosing something in parentheses turns it into a capturing subgroup. The one or more Bs, Cs or Ds that it's matching will be stored in the ${1} variable. If you have several capturing groups, they get stored in ${2}, ${3}, etc.
To perform calculations within a TCP script, you should use the EVAL command. Its argument is an expression (in quotes) that will be evaluated. It usually contains an assignment (with the ":=" operator), that sets a variable to the result of the expression. For example:
EVAL $celsius := (($fahrenheit - 32) * 5 / 9)
will set the variable $celsius to the temperature that corresponds to the $fahrenheit variable. The value of the $celsius variable can be used in subsequent statements.
You can use the EVAL statement to make comparisons between either strings or numeric (either integer or floating point) values. To do this, write an EVAL statement that compares the two values and set the result in a new variable. If the comparison was true, then the resulting variable will be set to 1, otherwise it will be zero. Here are examples of comparing numeric and string values
EVAL $x := ($val > 50.5) NBNE #$x #0 @greater @less: ... GOTO @ENDIF @greater: ... GOTO @ENDIF @ENDIF:
EVAL $x := ("dog" > "cat") NBNE #$x #0 @dog @cat: ... GOTO @ENDIF @dog: ... GOTO @ENDIF @ENDIF:
InterMapper TCP Scripts can compare two string or integer numeric values and branch based on the results. The commands below are no longer preferred as the EVAL statement described above is equally simple and more powerful.
The SBNE ("String Branch Not Equal") compares the two string values and branches if they are not equal. One or both of the arguments can be variables, expressed as ${variable-name}.
The NBNE ("Numeric Branch Not Equal") and NBGT ("Numeric Branch Greater Than") compares two numeric values, branching on the result. The arguments to these commands are strings and are expected to be within quotes. To convert a string to a numeric value, place a number sign (#) before the parameter. For example:
STOR "val1" "100" STOR "val2" "50" NBGT #${val1} #${val2} @exit
In this example, the string ${val1} will be converted to the numeric value 100, and ${val2} will be converted to the numeric value 50, and the branch will be taken, because 100 is greater than 50.
Note: The NBGT, NBNE and other TCP probe commands expect integer arguments only (with an optional + or -). A script parses up to the first non-digit character. Thus, the value of "50.5" is 50; the remaining digits are ignored. If you wish to compare against a fraction or floating point value, use the EVAL statement described above.
The following is a Custom SNMP probe file. It doesn't do anything very useful, but it shows the various sections of a custom probe file.
You can download this Example Probe File For more information, you can refer to the Developer Guide.
-- WARNING: This probe is provided as an example, of a custom probe. It is a -- tutorial and therefore is wordier than your real probe needs to be. -- You should use the "Prototype Custom SNMP Probe" as the basis -- for all new probe work. -- It's simpler, and you won't have to "rip anything out" as you begin. "type" = "custom-snmp" "package" = "com.dartware" "probe_name" = "snmp.example" "human_name" = "Example SNMP probe" "version" = "1.0" "address_type" = "IP,AT" "port_number" = "161" display_name = "Miscellaneous/Example SNMP Probe" -- none required; see the Developer Guide for the values that go here. -- The contains text that will be displayed in the probe -- configuration window. -- Describe the probe as much as necessary so that people will understand what it -- does and how it works. \GB\Example SNMP Probe\P\ This probe is an example of an InterMapper Custom SNMP probe, and many of the features that are described in the Custom Probes section of the \u2=http://dartware.com/go.php?to=intermapper.devguide\Developer Guide\P0. If you have questions about this probe, \u2=mailto:support@dartware.com\please contact us.\p0\ This probe probably isn't really useful for production work. However, it provides an example of various techniques available in custom SNMP probes. It retrieves a few SNMP values from a device by specifying their OIDs and how to display those values in the device's Status Window. The probe also has thresholds for setting the device into alarm or warning. In this example, the device has will go into alarm or warning if it has been rebooted recently (controlled by the \i\RebootAlarm\p\ and \i\RebootWarn\p\ parameters - two and three minutes, by default) or if there aren't as many interfaces as expected in the ifTable (controlled by the \i\ExpectedInterfaces\p\ parameter.) The parameters are: \b\RebootAlarm\p\ Put the device into alarm if the sysUptime is less than this many minutes. \b\RebootWarn\p\ Put the device into warning if the sysUptime is less than this many minutes. \b\ExpectedInterfaces\p\ Put the device into warning if the ifNumber is greater or equal to this value. \b\InterfaceToMonitor\p\ is the ifIndex of the interface to monitor for traffic. \b\TrafficWarn\p\ and \b\TrafficAlarm\p\ are thresholds for traffic alarms on the named interface. In addition, this probe shows: CALCULATION variables, the conversion from centi-seconds (hundredths of a second) to seconds Formatting of the Status Window, in the section> Marking up text in the \i\description\p\ and \i\snmp-device-display\p\ sections using IMML (InterMapper Markup Language) to get bold, italic, colored text, etc. IMML also allows you to create a link to a URL, using the \U2=http://xxxx\ notation shown in the \i\snmp-device-display\p\ section. -- Parameters are user-settable values that the probe uses for its comparisons. -- Specify the default values here. The customer can change them and -- they will be retained for each device. "RebootAlarm" = "2" -- 2 min = 120 seconds = 12,000 centi-seconds "RebootWarn" = "3" -- 3 min = 180 seconds = 18,000 centi-seconds "ExpectedInterfaces" = "3" -- expected number of interfaces "InterfaceToMonitor" = "1" -- Interface to monitor for traffic "TrafficWarn" = "200" -- traffic to get a warning "TrafficAlarm" = "1000" -- traffic to get an alarm -- SNMP values to be retrieved from the device, and -- Specify the variable name, its OID, a format (usually DEFAULT) and a -- short description. -- CALCULATION variables are computed from other values already retrieved -- from the device. sysDescr, 1.3.6.1.2.1.1.1.0 , DEFAULT, "System's Description" sysUptime, 1.3.6.1.2.1.1.3.0 , INTEGER, "Uptime - in centi-seconds" sysContact, 1.3.6.1.2.1.1.4.0 , DEFAULT, "Name of person to contact" sysName, 1.3.6.1.2.1.1.5.0 , DEFAULT, "Name assigned to system" sysLocation, 1.3.6.1.2.1.1.6.0 , DEFAULT, "Location of the system" ifNumber, 1.3.6.1.2.1.2.1.0 , DEFAULT, "Num. of rows in the ifTable" ifInOctets1, 1.3.6.1.2.1.2.2.1.10.$InterfaceToMonitor,PER-SECOND, "Number of received octets on interface 1" sysUptimeMinutes, ($sysUpTime / (100 * 60)), CALCULATION, "Uptime in minutes" -- Specify rules for setting the device into Alarm or Warning state alarm: $ifInOctets1 > $TrafficAlarm "Traffic above the alarm threshold" alarm: $sysUptimeMinutes < $RebootAlarm "Rebooted less than $RebootAlarm minutes ago" warning: $ifInOctets1 > $TrafficWarn "Traffic above the warning threshold" warning: $sysUptimeMinutes < $RebootWarn "Rebooted less than $RebootAlarm minutes ago" warning: $ifNumber != $ExpectedInterfaces "Not as many interfaces as expected" -- The section specifies the text that will be -- appended to the device's Staus Window. \B5\Prototype SNMP Probe\0P\ \U2=http://${deviceaddress}\Go to the device's web page\P0\ \4\ sysDescr:\0\ $sysDescr \4\ sysContact:\0\ $sysContact \4\ sysName:\0\ $sysName \4\ sysLocation:\0\ $sysLocation \4\ sysUpTime:\0\ $sysUptimeMinutes \3\minutes (\0\$sysUptime \3\ hundredths of seconds)\p\ \4\Num. of Intf:\0\ $ifNumber \3(expected $ExpectedInterfaces)\0\ \4\Input traffic:\0\ $ifInOctets1 \3(bytes/second)\0\
InterMapper can retrieve MIB variables from a device and then test them against thresholds. The section defines the OIDs of MIB variables that are to be retrieved. These values are called probe variables and can then be compared to thresholds to create alarms, warnings, etc.
Each line of the section defines a particular variable to be retrieved. The definition is composed of four comma-separated attributes: the variable's name, its OID, its Type, and an optional Chart legend. Their definitions are:
VariableName is the name used to represent the particular MIB value in this probe. A VariableName consists of letters, digits and an underscore, and must begin with a letter. VariableNames are not case-sensitive. These variable names will be represented in the probe as $VariableName. It is not necessary that a particular VariableName match the corresponding name in the MIB, although that is definitely convenient.
OID is the Object ID for the particular probe variable. Note that a scalar's OID must end in ".0" according to the SNMP specifications. Although it is common to off leave the suffix for scalar values, it is technically correct to include it and InterMapper requires the suffix to construct the proper queries. InterMapper will request the OID and wait for the response. [Technically, InterMapper issues an SNMP Get-Next-Request for the previous OID.] Currently, there is no facility for iterating across all rows of a particular table. Note: Calculation variables have a slightly different form, as described below.
Type may be one of: Default, Per-second, Per-minute, Total-value, or Hexadecimal. Default should be used for variables of type Integer and DisplayString. InterMapper will automatically determine the type an display the value properly. Per-second and Per-minute will force InterMapper to compute a rate for the particular variable by computing the difference between two successive samples and dividing by the elapsed time. Total-value displays the actual value of a counter or gauge, not a computed rate value. Hexadecimal displays the data as hex digits.
Calculation sets the variable to the result of the calculation shown in the OID field. Chart-legend is an optional field that provides a text label to be placed on any strip charts that incorporate this variable. Chart legends may contain embedded variable names in the form $VariableName. Here is a sample section.
<snmp-device-variables> --Variable-name OID --- TYPE ---- CHART LEGEND ------ ipForwDatagrams, 1.3.6.1.2.1.4.6.0, PER-SECOND, "Forwarded datagrams" ipInHdrErrors, 1.3.6.1.2.1.4.4.0, PER-MINUTE, "IP received header err" tcpCurrEstab, 1.3.6.1.2.1.6.9.0, DEFAULT, "Number of TCP conn's" sysDescr, 1.3.6.1.2.1.1.1.0, DEFAULT -- Non-polled values: -- Calculation variables are computed each poll time -- TrapVariables are updated when a trap arrives SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())" InterMapperTimeStamp, 1.3.6.1.4.1.6306.2.1.1.0,TRAPVARIABLE, "Timestamp" </snmp-device-variables>
Note: The OIDs above have a trailing ".0" to specify their full OID.
A Calculation type variable receives the result of an arithmetic expression. After all variables have been polled, InterMapper calculates the expression, and sets the value of its variable to the result. In the example above:
SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())"`
The variable "SineValue" will be set to the value of the expression (10 * sin(0.01 * time()). This gives a sine wave that makes an attractive chartable value. Use "$SineValue" to refer to the variable elsewhere in the probe.
InterMapper supports several macros that show information about a variable:
${variablename} or $variablename In a section of a probe file, an occurrence of a variable name (with or without the curly braces ({...}) will be replaced with its value, rounded to the nearest integer. For example, if a calculation variable has the value of 3.14159265, using it in the section will result in the value of "3"; if the variable had the value 4.75 it would be displayed as "5". This value will be chartable, that is, clicking it will make a new strip chart, or dragging it will add it to an existing chart. The ipForwDatagrams variable defined above could be referred to in either of these forms: ${ipForwDatagrams} or $ipForwDatagrams
${chartable: xxx : yyy} In a section of a probe file, the ${chartable: ...} macro controls the number of decimal places. There are two parameters: a formatting string that indicates the number and placement of the digits near the decimal point, and the variable to be formatted. For example, if $var is 3.14159265: ${chartable: #.## : $var } --> 3.14 ${chartable: #.####### : $var } --> 3.1415927
${variablename:legend} In a section of a probe file, the ${variablename:legend} is replaced with the legend field defined for that variable in the section. For example: ${ipForwDatagrams:legend} would result in the string "Forwarded datagrams".
${ipForwDatagrams:legend}
Custom Probes provide a mini-report of the current status of a device. InterMapper retrieves certain data values from the device being tested, then displays the results in a Status Window. In addition, you can establish thresholds, and have InterMapper send alerts when the collected data value(s) fall outside those thresholds.
Before you begin to write an InterMapper probe, you should think about your equipment and how you want to test it:
Once these answers are in hand, you've completed the design of the probe. Next, you need to retrieve the desired information from the device.
For SNMP-speaking device, you'll need to know the SNMP OIDs ("Object IDentifiers") that correspond with the desired data values. The OIDs are defined in a MIB file that you can generally get from the vendor's web site or other MIB repository. (See below for various sources of MIBs.)
You will also want a MIB browser program (see below) to make sense of the MIB. This will show the OIDs for the desired values, as well as their definitions and data formats.
Writing Custom SNMP probes for InterMapper is straightforward, and follows this basic process:
Each time you reprobe a device, InterMapper will retrieve the data values you specified (in the OIDs) and compare those values your thresholds. This will determine the status of the device (OK, warning, alarm, or critical state, etc.) Finally, InterMapper will format the data in a Status Window as specified in the probe.
Each probe file has "sections" into which you enter the kinds of information listed above.
Read more about probe sections. These sections are further defined in the online InterMapper Developer Guide.
After you've filled in these sections of the probe file, save it in the InterMapper Settings/Probes folder (be sure to change the file name to something unique), then Reload Probes to make it available to InterMapper. Use Set Info... -> Set Probe... to select your new probe.
Once you've imported the probe, you can edit it with your favorite text editor, save the changes, Reload Probes, and you should see the changes reflected.
Interactive SNMP Probe Builder You can simply enter MIB variable names or OIDs into the SNMP Probe Builder web page and it will create a complete probe that can be imported into InterMapper.
Review an Example Probe You can read the Example Probe file as an annotated example file that describes the various sections of the probe file, and shows how probes work.
Example Probe File The downloadable Example file matches the file shown above.
Prototype Probe File for download The Prototype file provides a bare-bones template that you can fill in for your purposes. Prototype Probe File
On-demand Table Maker You can easily create on-demand tables for custom probes by copying the relevant parts from a MIB and pasting them into the On-demand Table Maker page.
Using SNMPWalk to Query a Device InterMapper has an SNMP Walk facility. This is described in the Debugging with SNMPWalk section of the Developer Guide.
Additional Trap Handling Facilities You can also read additional information about creating custom SNMP probes that handle traps. The documentation is SNMP Trap Handling.
SNMP MIB Browsing Tools There are many MIB browsing tools. They make it much easier to read the MIBs and discover the OIDs you need. One good freeware tool is Mibble. There's also an on-line MIB Viewer at the SimpleWeb site.
Information about SNMP There are a number of sites devoted to disseminating information about SNMP:
Sources of MIBs You can find MIB files in lots of places:
InterMapper probes can break up a string retrieved from a device using a regular expression into separate variables. This tech note describes how to do this:
A customer had a piece of equipment that returned the following information in sysDescr.0:
FW TR6-3.1.4Rt_F213E4, 2.4GHz, 0dBi ext. antenna
They created a probe that retrieved sysDescr.0 and then parsed out those strings with the following commands in the section of the probe:
sysDescr, 1.3.6.1.2.1.1.1.0, DEFAULT, "system description" firmware, "$sysDescr" =~ "^FW ([^,]+), (.+)Hz, (.+) antenna" ;"${1}", CALCULATION, "Firmware" frequency, "${2}", CALCULATION, "Frequency" antenna, "${3}", CALCULATION, "Antenna" . . .
An enumeration in a MIB allows a designer to represent text strings as numeric values. This numeric representation is more compact, and therefore efficient, but makes it hard for humans to read. InterMapper has several techniques for displaying the enumerated values for easier interpretation.
There are several ways to do this:
if xxxx is true then return yyyy otherwise return zzzz
xxxxStr, ($xxxx == 0 ? "yyyy" : "zzzz"), CALCULATION, "replacement string for xxxx"
if aaaa is true then return bbbb else if cccc is true return dddd else if eeee is true return ffff else return gggg
aaaaStr, ($aaaa==0 ? "bbbb" : $aaaa==1 ? "dddd" : $aaaa==2 ? "ffff" : "gggg"), CALCULATION, "replacement string for aaaa"
Dartware's InterMapper software can send SNMP Traps as a notifier. It uses the following MIB variables in the messages it sends.
-- Dartware MIB
DARTWARE-MIB DEFINITIONS ::= BEGIN
IMPORTS MODULE-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE, enterprises FROM SNMPv2-SMI DisplayString FROM SNMPv2-TC; dartware MODULE-IDENTITY LAST-UPDATED "200507270000Z" ORGANIZATION "Dartware, LLC" CONTACT-INFO "Dartware, LLC Customer Service Postal: PO Box 130 Hanover, NH 03755-0130 USA Tel: +1 603 643-9600 E-mail: support@dartware.com" DESCRIPTION "This MIB module defines objects for SNMP traps sent by InterMapper." REVISION "200512150000Z" DESCRIPTION "Added intermapperDeviceAddress and intermapperProbeType." REVISION "200507270000Z" DESCRIPTION "First version of MIB in SMIv2." ::= { enterprises 6306 } notify OBJECT IDENTIFIER ::= { dartware 2 } intermapper OBJECT IDENTIFIER ::= { notify 1 } intermapperTimestamp OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The current date and time, as a string." ::= { intermapper 1 } intermapperMessage OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The type of event: DOWN, UP, ALARM, WARN, OK, or TRAP." ::= { intermapper 2 } intermapperDeviceName OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The device's DNS name, as a string." ::= { intermapper 3 } intermapperCondition OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The condition of the device, as it would be printed in the log file." ::= { intermapper 4 } intermapperDeviceAddress OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The device's network address, as a string." ::= { intermapper 5 } intermapperProbeType OBJECT-TYPE SYNTAX DisplayString (SIZE(0..255)) MAX-ACCESS read-only STATUS current DESCRIPTION "The device's probe type, as a human-readable string." ::= { intermapper 6 } -- For SMIv2, map the TRAP-TYPE macro to the corresponding NOTIFICATION-TYPE macro: -- -- -- intermapperTrap TRAP-TYPE -- ENTERPRISE dartware -- VARIABLES { intermapperTimestamp, intermapperMessage, -- intermapperDeviceName, intermapperCondition } -- DESCRIPTION -- "The SNMP trap that is generated by InterMapper as a notification option." -- ::= 1 intermapperNotifications OBJECT IDENTIFIER ::= { intermapper 0 } intermapperTrap NOTIFICATION-TYPE OBJECTS { intermapperTimestamp, intermapperMessage, intermapperDeviceName, intermapperCondition, intermapperDeviceAddress, intermapperProbeType } STATUS current DESCRIPTION "The SNMP trap that is generated by InterMapper as a notification option." ::= { intermapperNotifications 1 }
END
InterMapper supports two kinds of OID's: Numeric and Symbolic. The Symbolic OIDs become available when a MIB has been imported into InterMapper.
In addition, InterMapper supports three kinds of OID expressions: Get-Next, Trap-Conditional, and Index-Derived.
Numeric OID's contain only numbers separated by periods. Preceding periods are ignored. A trailing period is allowed if there is only one subid.
Examples:
.1 1. 1.3.6
Invalid examples:
1 (no period) 1.3.6. (trailing period but with multiple subids) 1.3.6.blah (not numeric) 1.3.6.1.2.1.system.sysUpTime.0 (not numeric)
Unlike Net-SNMP, InterMapper ascribes no special meaning to OID's that begin with a period; all numeric OID's are considered absolute.
Errors in numeric OID's are reported by the system to the Event Log when the error is in a custom probe. The error message will have the form:
Syntax error in OID "1.3.6.1..1.2"
A symbolic OID begins with a letter, after ignoring any preceding periods. InterMapper must be able to locate a MIB file that defines the symbols used.
There are three types of symbolic OID's:
Relative and scoped symbols are handy when a symbol is ambiguous, i.e. the same symbol name is defined differently in two separate MIB files. You should prefer the scoped OID form, when possible.
Symbolic names are case-sensitive.
Simple: sysUpTime sysUpTime.0 enterprises.9.2.3.4.5 Relative: system.sysUpTime system.sysUpTime.0 Scoped: SNMPv2-MIB::sysUpTime SNMPv2-MIB::system.sysUpTime.0
Invalid Examples:
Simple: sysUpTiime (misspelled; not found) sysupTime (wrong case) sys%pTime (disallowed character %) sysUpTime.0. (bad; trailing period) Relative: system.ifIndex (bad; ifIndex isn't under system) Scoped: SNMPv2-MIB.sysUpTime (bad; must use :: for scoped OID) IF-MIB::sysUpTime (bad; wrong MIB module for sysUpTime)
Errors in symbolic OID's are reported by the system to the Event Log when the error is in a custom probe. The error message will have the form:
Syntax error in OID "sys%pTime"
InterMapper has a special syntax for "get-next" style OID's - attach a + to the end of the OID.
Normally, when you specify a variable to query in a custom SNMP probe, you specify the complete OID, including the instance. For example, you might specify "sysUpTime.0" or "ifInOctets.13". For sysUpTime, the .0 specifies the (only) instance. For ifInOctets, the .13 specifies the value for ifIndex 13.
There are occasions when you want to query a variable using a preceding OID. For example, you might want to query the value of ifInOctets for the first interface, but you can't assume the ifIndex of the first interface is 1. Here's how you would specify the OID:
ifInOctets+
To retrieve the value of ifInOctets for the interface whose ifIndex follows 13, specify the OID with a plus:
ifInOctets.13+
The plus sign must immediately follow the OID. Technically, it's not part of the OID, but considered an operator in InterMapper's OID expression language.
Note: Get-Next OID expressions will not work for custom SNMP probes that specify get-request queries.
Trap-conditional OID expressions allow you to assign a variable only when it occurs in the varbind list of a certain trap. For example, you might want to set the value of your probe's "sysUpTimeCrashed" variable to value of the "sysUpTime.0" variable included in the varbind list of a "systemCrashed" trap. However, you don't want to set "sysUpTimeCrashed" when you see the sysUpTime.0 value in any other received trap. To restrict the assignment of sysUpTime.0 to only the systemCrashed trap, you need to specify both the systemCrashed trap OID and the sysUpTime.0 OID using the ?: operator. This combination is called a "Trap-Conditional" OID, or "Trap OID" for short.
systemCrashed?:sysUpTime.0 sysTrapOID?:sysContact SOMEMIB::sysTrapOID.1?:SMIv2-MIB::sysContact
Supported in 4.4, the legacy format for trap OID's is a numeric OID followed by an OID:
1.3.6.1.2.1::sysUpTime.0
The legacy format does not allow use of a symbolic name for a trap OID; this conflicts with the scoped format above. The use of :: for Trap-conditional OID expressions is deprecated. Please use ?: in the future.
When querying tables from SNMP devices, it is often useful to assign the value of a variable from a row's OID index. This technique will work even if the values used to index the row have an access of "not-accessible".
Take ipNetToMediaTable as an example. This table is indexed by two variables: ipNetToMediaIfIndex and ipNetToMediaNetAddress. The other two variables in this table are ipNetToMediaPhysAddress and ipNetToMediaType. Since the format of the table's row index is known, you only need to query ipNetToMediaPhysAddress and ipNetToMediaType; you can derive ipNetToMediaIfIndex and ipNetToMediaNetAddress from the index value.
To specify the value of an OID, derived from another OID, you can use the Index-Derived OID Expression.
ipNetToMediaType[0:1] ipNetToMediaType[1:4] ipNetToMediaType[1:]
In this example, the notation <oid>[a:b] means to fetch the OID <oid> and retrieve the value from the subid's of the index as follows:
[a:b] means to start with the a'th subid and collect b subid's. [a:] means to start with the a'th subid and collect the rest. subid's use zero-based indexes.
InterMapper 4.5 introduces a new mechanism for displaying SNMP tables on demand. To use this feature, the proper definitions must be added to a Custom-SNMP probe file. The status windows of a device using that probe will have a clickable link that opens a window showing the specified table values.
When you view a table, InterMapper retrieves the information from the device immediately and displays it instantly. The information in an on-demand display is not part of the regular polling cycle, nor is it refreshed until you specifically request it.
On-demand displays are useful for digging down into a device when you suspect there might be a problem. You can use on-demand tables to view a routing table, ARP table, or other statistics that show an important status. The data is live, and the response is immediate.
The SNMP protocol provides access to two types of variables, scalars and tables. Scalars are single values of a specific type: integer, string, counter, gauge, etc. Tables are composed of related arrays of scalars; you can visualize these related arrays as the columns. Each element in the array has a unique index that is the same for all the columns in the same table. All the elements in the table with the same index N represent row N of the table.
For example, the IP-MIB defines a table named "ipNetToMediaTable" that shows a device's ARP cache for its IPv4 interfaces. A schematic representation of ipNetToMediaTable might look like this:
+ ipNetToMediaTable + ipNetToMediaEntry [ipNetToMediaIfIndex,ipNetToMediaNetAddress] - ipNetToMediaIfIndex "Interface" - ipNetToMediaPhysAddress "MAC Address" - ipNetToMediaNetAddress "IP Address" - ipNetToMediaType "Type"
Here's how to interpret this information. Skipping over the second line for now, this "ipNetToMediaTable" has four variables, starting with ipNetToMediaIfIndex and ending with ipNetToMediaTable - these are the columns. The image in the introduction above shows the ipNetToMediaTable for a device with actual data. You'll notice that there are columns for each variable in the table. The quoted strings following the column names are human-readable labels to display instead of the formal names from the MIB.
Now that you understand the basic structure of ipNetToMediaTable and its four columns, you're probably wondering what is the role of the "ipNetToMediaEntry" line?
In SNMP, every value you retrieve has a unique ObjectID (OID). Tables are no different. With SNMP tables, the OID is formed by taking the column name and tacking on a row index that consists of one or more subid's. Every SNMP table can define its own mechanism for indexing the table, by combining values of its own columns.
In ipNetToMediaTable, the entry "ipNetToMediaEntry" indicates how this table indexes its rows. ipNetToMediaTable uses a set of subid's derived from the values of ipNetToMediaIfIndex and ipNetToMediaNetAddress. So the OID of a ipNetToMediaNetAddress is ipNetToMediaNetAddress.<ifIndex>.<ipNetToMediaNetAddress> or 1.3.6.1.2.1.4.22.1.3.<ifIndex>.<ipNetToMediaNetAddress>.
With that background, the on-demand section of a custom SNMP probe mirrors the schematic representation above. It is delimited by <snmp-device-variables-ondemand> and </snmp-device-variables-ondemand> tags. Within these tags, there are a sequence of lines of comma-separated values defining one or more tables:
<snmp-device-variables-ondemand> ipNetToMediaTable, 1.3.6.1.2.1.4.22.1, TABLE, "Maps from IP addresses to physical addresses." ipNetToMediaTable/ipNetToMediaIfIndex, ipNetToMediaTable.1, DEFAULT, "Interface" ipNetToMediaTable/ipNetToMediaPhysAddress, ipNetToMediaTable.2, HEXADECIMAL, "MAC Address" ipNetToMediaTable/ipNetToMediaNetAddress, ipNetToMediaTable.3, DEFAULT, "IP Address" ipNetToMediaTable/ipNetToMediaType, ipNetToMediaTable.4, STRING, "Type" </snmp-device-variables-ondemand>
The first line defines a table "ipNetToMediaTable" using the new TABLE type. The second field "1.3.6.1.2.1.4.22.1" is an OID assignment for use in later definitions. The third field is the type "TABLE", and the fourth field is a human-readable description to display to the client of this table.
(Astute readers will notice that 1.3.6.1.2.1.4.22.1 is not the official OID of ipNetToMediaTable, but actually the OID of ipNetToMediaEntry. This is not a typo; in this first example, we're going to construct a definition of a table that doesn't require any MIB's to be loaded into InterMapper. In this example, ipNetToMediaTable is being used as an internal variable name; we could just as well have called it UncleBob.)
The four columns of the ipNetToMediaTable are defined similar to the TABLE, but with scalar types. In addition, the column variable names all begin with "ipNetToMediaTable/..." to indicate the table to which they belong. The second field is the OID of the table column. The third field is the type for display. The fourth field is a human-readable column title (optional).
The OID's for the four columns are allowed to use the OID assigned to ipNetToMediaTable in the TABLE line as a convenient shortcut. As an alternative, the OID's could all be specified exhaustively:
<snmp-device-variables-ondemand> ipNetToMediaTable, .1 , TABLE, "Maps from IP addresses to physical addresses." ipNetToMediaTable/ipNetToMediaIfIndex, 1.3.6.1.2.1.4.22.1.1, DEFAULT, "Interface" ipNetToMediaTable/ipNetToMediaPhysAddress, 1.3.6.1.2.1.4.22.1.2, HEXADECIMAL, "MAC Address" ipNetToMediaTable/ipNetToMediaNetAddress, 1.3.6.1.2.1.4.22.1.3, DEFAULT, "IP Address" ipNetToMediaTable/ipNetToMediaType, 1.3.6.1.2.1.4.22.1.4, STRING, "Type" </snmp-device-variables-ondemand>
A valid OID is still expected for the TABLE line; we use .1 for an ignored value because the field expects valid OID syntax.
Now that InterMapper 4.5 has a MIB compiler, you can use symbolic OID's in any OID field. Here's an example of the ipNetToMediaTable defined using the definitions in IP-MIB (and renamed UncleBob):
<snmp-device-variables-ondemand> UncleBob, .1 , TABLE, "Maps from IP addresses to physical addresses." UncleBob/IfIndex, IP-MIB::ipNetToMediaIfIndex, DEFAULT, "Interface" UncleBob/PhysAddress, IP-MIB::ipNetToMediaPhysAddress, HEXADECIMAL, "MAC Address" UncleBob/NetAddress, IP-MIB::ipNetToMediaNetAddress, DEFAULT, "IP Address" UncleBob/Type, IP-MIB::ipNetToMediaType, STRING, "Type" </snmp-device-variables-ondemand>
The on-demand table feature can also be used to query non-tables. Of course, non-tables are represented as tables with a single row:
<snmp-device-variables-ondemand> sys, .1, TABLE, "System group" sys/Description, sysDescr, DEFAULT sys/Name, sysName, DEFAULT sys/Contact, sysContact, DEFAULT sys/OID, sysObjectID, DEFAULT </snmp-device-variables-ondemand>
When a column variable doesn't specify a column title (in the fourth field), the column name, without the table prefix, is used instead.
It's important to note that table syntax differs slightly from the exact syntax required in the <snmp-device-variables> section. In the <snmp-device-variables> section, you would specify the .0 instance of sysDescr.0. With column variables, you never specify an index or instance.
Since SNMP tables use the value of one of more columns in the row index, you can derive the values of these columns from the index itself. It's not necessary to explicitly query the column. In many cases, you can only derive the value of a column from the index; the column itself is not-accessible.
Here is an example of retrieving the four columns of ipNetToMediaTable using a two-variable query:
<snmp-device-variables-ondemand> ipNetToMediaTable, 1.3.6.1.2.1.4.22.1, TABLE, "Maps from IP addresses to physical addresses." ipNetToMediaTable/ipNetToMediaIfIndex, ipNetToMediaTable.4[0:1], DEFAULT, "Interface" ipNetToMediaTable/ipNetToMediaPhysAddress, ipNetToMediaTable.2, HEXADECIMAL, "MAC Address" ipNetToMediaTable/ipNetToMediaNetAddress, ipNetToMediaTable.4[1:4], DEFAULT, "IP Address" ipNetToMediaTable/ipNetToMediaType, ipNetToMediaTable.4, STRING, "Type" </snmp-device-variables-ondemand>
When InterMapper downloads this table from the table, it will retrieve only two columns: ipNetToMediaPhysAddress and ipNetToMediaType. From the index values of these two columns, the values of ipNetToMediaIfIndex and ipNetToMediaNetAddress can be derived.
In this example, the notation oid[a:b] means to fetch the OID oid and compute the value from the index:
oid[a:b]
oid
[a:b] means start with the a'th subid and collect b subids. [a:] means start with the a'th subid and collect the remaining subids
You may run across MIB's that define a table that "augments" an existing table. This simply means that the augmenting table uses the same index variables as another table. Since the index variables are the same, you can visualize an augments definition as adding columns to an existing table.
In IF-MIB, an example of an augmenting table is ifXTable. ifXTable augments ifTable, providing a number of useful additions.
InterMapper's table syntax easily supports choosing columns from one or more tables that share the same index:
<snmp-device-variables-ondemand> ifTable, .1, TABLE, "Partial ifTable & ifXTable" ifTable/ifIndex, IF-MIB::ifIndex, DEFAULT ifTable/ifDescr, IF-MIB::ifDescr, DEFAULT ifTable/ifAlias, IF-MIB::ifAlias, DEFAULT ifTable/ifName, IF-MIB::ifName, DEFAULT </snmp-device-variables-ondemand>
After you define a TABLE variable in the "ondemand" section of the probe, you can specify that variable in the <snmp-device-display> section as you would any other variable:
<snmp-device-display> ... $ipNetToMediaTable $sys $UncleBob </snmp-device-display>
When InterMapper renders the "display" section, it will display the table name as a hyperlink. People looking at the status window in InterMapper can click on the hyperlink to bring up the on-demand table window pictured in the introduction
If you want to replace the default table name displayed with your own text, you can specify the "alternate text" in the expanded variable form:
<snmp-device-display> ... $\{ipNetToMediaTable:ARP Table} </snmp-device-display>
A trap is an unsolicited packet (or Protocol Data Unit - PDU) sent from a device to InterMapper (or other SNMP management console). The trap generally contains one or more data values that give information about the device's state.
When a trap arrives, InterMapper first determines which device(s) should receive the trap. InterMapper examines the Agent Address (for relayed traps) or the Source IP address, and passes a copy of the trap packet to each device on the maps whose IP address matches. For example, if a device with the IP address is on two maps, or is present twice on the same map, each of those devices will receive a copy of the trap.
InterMapper parses out the in the variable binding list (a list of name/value pairs, also called the VarBind List), and matches the OIDs to any variables defined in the <snmp-device-variables> section, just as if those values had been polled directly with a SNMP GetRequest or GetNextRequest. InterMapper then re-evaluates the expressions in the probe, and sets the device status appropriately. If a particular trap variable is not set by an incoming trap, expressions containing that variable will not be evaluated. See the Defining Trap Variables section below for details of defining trap variables.
Finally, as a result of receiving the trap, InterMapper will re-poll the device that sent the trap. This guarantees that InterMapper has the most up-to-date information about the device's state. If another trap arrives before the final response of this new poll has returned, InterMapper will complete the current poll and initiate another round of polling to get the new state.
A TrapVariable is a variable defined in a custom probe file that is set to the value of an OID received in the VarBind list. A TrapVariable will never be polled: that is, InterMapper never sends an SNMP GetRequest or GetNextRequest to retrieve its value. The only way to set its value is to receive a trap that contains the OID in its VarBind List. The Variables section of the Developer Guide describes the file format. Here is an example:
<snmp-device-variables> InterMapperTimeStamp, 1.3.6.1.4.1.6306.2.1.1.0, TRAPVARIABLE, "Timestamp" </snmp-device-variables>
In this example, the variable $InterMapperTimeStamp will be set every time a trap arrives containing the OID 1.3.6.1.4.1.6306.2.1.1.0 in the VarBind List. Trap variables that don't have values set by an incoming trap are left undefined.
An example Trap Viewer probe is available to download. This probe will display all the values from an arriving trap in the device's Status Window. It also provides a good prototype for building your own trap probes.
By default, InterMapper's custom SNMP probes will query certain MIB-II system group items. You should use a probe type of "custom-snmp-trap" to define a probe that only receives traps. This setting means that InterMapper will not actively poll a device using SNMP GetRequest or GetNextRequest. For example, the <header> section of the file should look like this:
<header> "type" = "custom-snmp-trap" ... etc ... </header>
The contents of trap message are logged to the Event Log file at the time the trap is are received. There are two forms: Short and Verbose. (The format is controlled by the Verbose Trap Logging checkbox in the Server Settings > SNMP preference pane.)
Short Trap Format
06/08 20:50:29 TRAP TestMap:192.168.2.1 1.3.6.1.4.1.6306 (333) { "321", "456" } (via 192.168.1.233)
Verbose Trap Format:
06/08 20:50:05 TRAP TestMap:192.168.2.1 1.3.6.1.4.1.6306 (333) { 1.3.6.1.4.1.6306.99.1 : "321", 1.3.6.1.4.1.6306.99.2 : "456" } (via 192.168.1.233)
The fields of the trap entry in the log file are defined below, with examples in "[ ... ]":
InterMapper 4.5 introduces a number of special variables that can be used inside the OID field to designate fields of the received trap. These special variables include:
InterMapper can also parse values from the VarBind List by their position using variables of the form:
Note: N may be from 1 to 50.
The following example is an excerpt from the Trap Viewer probe listed above.
<snmp-device-variables> -- Variables from the trap packet itself genericTrapVar, $GenericTrap, TRAPVARIABLE, "Generic Trap" specificTrapVar, $SpecificTrap, TRAPVARIABLE, "Specific Trap" timeStampVar, $TimeStamp, TRAPVARIABLE, "Timestamp" enterpriseVar, $Enterprise, TRAPVARIABLE, "Enterprise" commStringVar, $CommunityString, TRAPVARIABLE, "Community String" trapOIDVar, $TrapOID, TRAPVARIABLE, "Trap OID" agentAdrsVar, $AgentAddress, TRAPVARIABLE, "Agent Address" senderAdrsVar, $SenderAddress, TRAPVARIABLE, "Sender Address" snmpVersionVar $SnmpVersion, TRAPVARIABLE, "SNMP Version" varbindCountVar, $VarbindCount, TRAPVARIABLE, "Varbind Count" -- first two variables from the Varbind List trap_var1, $VarbindValue1, TRAPVARIABLE, "First value" trap_var2, $VarbindValue2, TRAPVARIABLE, "Second value" </snmp-device-variables>
InterMapper uses several techniques to determine whether a device is working properly. This technical note describes the network load that these techniques place on a network for a particular device on a map. The techniques involved are:
The remainder of this note describes the number of packets/bytes of polling traffic generated by various kinds of probes. To compute the total amount of polling traffic that will be created, you must multiply the figures below by the number of each probe that's active, and also by the frequency/polling interval that you specify.
InterMapper sends 20-byte ICMP Echo requests, and expects to receive a 20-byte response. These are sent at the Poll Interval shown in the lower left corner of the map window. (You can also set an individual device's poll interval separate from the map-wide default by selecting a device and choosing Monitor > Set Poll Interval...)
InterMapper sends the ping request, then waits up to the device's Timeout (Monitor > Set Timeout...) for a response. If it doesn't hear a response, it sends a second and third ping, etc. up to the number of retries specified in the Map Settings > Device thresholds window.
InterMapper will never start a new poll (e.g., send a new ICMP Echo request) before hearing a response, or waiting the specified timeout.
When InterMapper queries a device with the SNMP MIB-II probe, several SNMP packets are exchanged with the target device to retrieve values for the desired parameters. InterMapper differentiates between two types of parameters: configuration information that changes infrequently and operational information that is updated on every poll. When InterMapper probes a device for the first time, InterMapper queries both configuration and operational parameters. On subsequent polls however, InterMapper only queries the operational parameters to minimize the network bandwidth used in polling. Periodically, every 12 hours, InterMapper re-queries the configuration information to check for changes.
InterMapper's regular polling places a minimal load on the network. This load can further be reduced by increasing the poll interval for your maps. Since InterMapper only polls data for visible interfaces, you can also reduce the polling load by hiding interfaces on devices that you do not want polled.
When polling an SNMP device, InterMapper bunches several SNMP variables (or OID's) into each SNMP request. To minimize the processing time of each target device, InterMapper maintains only one request outstanding to each device; the next request in the polling sequence is not sent until a response is received to the previous one. Upon receipt of a SNMP response, InterMapper sends the next request (unless the response is the last one in the poll.)
The number of SNMP packets required to poll with an SNMP MIB-II probe is related to the number of visible interfaces (N) on the box. Each SNMP packet (request and response) includes overhead in the form of an 8 byte UDP header and a 20 byte IPv4 header. In addition, the request has up to 260 bytes for each interface, and the response will have up to 300 bytes for each interface. Therefore, the total polling for each interface is:
(two IPv4/UDP headers at 28 bytes) + (one request of 260 bytes each) + (one responses of 300 bytes each)
Thus, each visible interface generates approximately 616 bytes of polling between the request and the response.
Due to the vagaries of different SNMP implementations, InterMapper will never poll fewer than 2 interfaces. So N is always >= 2, even for boxes that have only one visible interface.
InterMapper will never begin a fresh poll of a device before the current poll is finished. Thus, if you set the poll interval to 5 seconds, but the SNMP poll takes 9 seconds to complete, the next poll will start in 9 seconds and effectively, the poll interval is 9 seconds for that device.
InterMapper generates requests for MIB variables based on the OIDs specified in the probes. The same calculations hold as above, except that the average request size will be around 20-30 bytes. The size of the response data varies depending on what is requested. For example, an integer's response will be four bytes; a text string can be unlimited in length, and might easily be hundreds of bytes. The response will also have about 20-30 bytes of overhead. The same 28-byte packet header overheads apply.
InterMapper's TCP-based probes establish a TCP connection to the device being tested, then exchange a certain amount of information. The probe then breaks the connection.
The amount of traffic that the probe generates is determined by the nature of the probe: InterMapper does not, in general, add any overhead to the transaction.
This page allows you to create an InterMapper SNMP probe interactively. Enter the MIB variable names or OIDs. When you press TAB, the Custom Probe File text (below) automatically updates to create a valid InterMapper SNMP probe that retrieves those values.
Enter the SNMP MIB variable names or OIDs that you want to monitor, one variable per line. To use MIB variable names (instead of OIDs), you must first import the associated MIB(s) into InterMapper before using this probe file. Note: You may supply other optional fields as comma-delimited text. The order is: MIB Variable, Legend, Units, Display type, Autorecord label
MIB Variable, Legend, Units, Display type, Autorecord label
Enter the variable name, its label (for the GUI), the comparison operator, and the warn, alarm, and critical thresholds. (You may leave any of the threshold values empty.) MIB Variable, Label, Operator, Warn, Alarm, Critical
MIB Variable, Label, Operator, Warn, Alarm, Critical
Enter a description of what the probe does: what equipment it works with, what SNMP variables/OIDs it retrieves, the thresholds that it compares to, etc. The IMML probe description markup allows you to pretty-up the text.
Human-readable name for probe. (A good choice is the manufacturer or model.)
Category in Set Probe... (Default is "Experimental/")
Domain Name of your company (e.g., dartware.com or example.com)
Copy the text below and paste it into a file with the name shown at the top of the file. Then import that file (File -> Import -> Probe...) into InterMapper to make it active.
... No text yet - enter one or more MIB variables in 1) above...
The fields above fill in the corresponding fields of the InterMapper Probe. See the Custom SNMP Probes section of the Developer Guide for details on these fields:
If you have comments/questions about this tool, please send them to support@dartware.com
This page creates an on-demand table for an InterMapper custom SNMP probe. Enter the desired fields from the device's MIB below. The page will automatically generate the table declaration, so you can simply paste it into the probe file.
SEQUENCE { ... }
${tablename:text to be seen}
Paste the text below into the probe file.
empty
The ifTable if the IF-MIB shows the interfaces on a device. To create an on-demand table, you will need to review the MIB to find the table's definition.
Find the table's name (ifTable in the excerpt below), and the names for the columns of the table (everything between the { ... } in the ifEntry below). Paste those into the fields on this page, and you'll get the definition suitable for entry into the custom SNMP probe.
... ifTable OBJECT-TYPE SYNTAX SEQUENCE OF IfEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A list of interface entries. The number of entries is given by the value of ifNumber." ::= { interfaces 2 } ifEntry OBJECT-TYPE SYNTAX IfEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry containing management information applicable to a particular interface." INDEX { ifIndex } ::= { ifTable 1 } IfEntry ::= SEQUENCE { ifIndex InterfaceIndex, ifDescr DisplayString, ifType IANAifType, ifMtu Integer32, ifSpeed Gauge32, ifPhysAddress PhysAddress, ifAdminStatus INTEGER, ifOperStatus INTEGER, ifLastChange TimeTicks, ifInOctets Counter32, ifInUcastPkts Counter32, ifInNUcastPkts Counter32, -- deprecated ifInDiscards Counter32, ifInErrors Counter32, ifInUnknownProtos Counter32, ifOutOctets Counter32, ifOutUcastPkts Counter32, ifOutNUcastPkts Counter32, -- deprecated ifOutDiscards Counter32, ifOutErrors Counter32, ifOutQLen Gauge32, -- deprecated ifSpecific OBJECT IDENTIFIER -- deprecated } ...
On-demand Table Maker Version 1.0d2 — 6 February 2008
Dartware has tested InterMapper with Windows XP SP2 and Vista. Use this tech note to help you configure your system to work well with either operating system.
Windows XP SP2 and Vista both ship with significant firewalling turned on. You will need to create exceptions ("poke holes") in the firewall in order to use the remote server, web server, telnet server, or DataCenter server as well as to monitor SNMP traps. (In our testing with InterMapper server running on an XP SP2 machine, auto-discovery and monitoring appears to work fine without holes in the firewall. However, you need to adjust the firewall if you want to use InterMapper Remote or other services named below, or if you want to run on Vista.)
You can use one of two basic methods of poking holes in the firewall:
The first (by application) is the easiest way to be sure that InterMapper will work. The second (by port) may be desirable if you're not planning to use all three servers.
For either method,
Microsoft has made significant changes to the Windows Firewall in Vista to enhance security and to allow for more advanced configuration. Vista's new Windows Firewall supports firewalling for both incoming and outgoing traffic.
The default behavior of the Vista's new Windows Firewall is to:
The default rules will block returning ping packets, and thus InterMapper will not be able to ping any devices. In order to allow this ICMP traffic, a new Inbound Rule must be created in the Windows Firewall with Advanced Security settings for each service:
Some customers have asked that InterMapper not start its server automatically when the system starts up. On MacOS X and Windows, InterMapper 4.5 offers a checkbox in the InterMapper Control Center to do this.
For earlier versions, or on other platforms, It is possible to disable the InterMapper Server's automatic capability of starting when the system boots up. The method depends on the OS running the software:
Open the Services control panel. (This will always be accessible from the Administrative Tools panel in the control panels, also accessible other ways in various versions of Windows.) Right-click and choose Properties. Change Startup type to Manual. Click Ok.
On MacOS X 10.4 (Tiger), InterMapper uses the LaunchDaemon to start/stop the server. You have to remove the InterMapperServer plist from /Library/LaunchDaemons. It is also possible to add a flag to the launchd plist to turn off the automatic reboot. Run the following command in Terminal to stop InterMapper and insert the flag into the plist.
sudo launchctl unload -w /Library/LaunchDaemons/com.dartware.InterMapperServer.plist
To restart intermapperd and clear the flag, pass -w on the command to load:
sudo launchctl load -w /Library/LaunchDaemons/com.dartware.InterMapperServer.plist
Simply move the InterMapperServer item out of /Library/StartupItems. When you restart, the InterMapper server daemon will not be started.
Alternatively, the file /Library/StartupItems/InterMapperServer/InterMapperServer actually launches the daemon at boot time. You can rename that file to be "InterMapperServer/InterMapperServerDisabled".
To restore the boot-time launch of the InterMapper server, simply restore the file to its original name.
Many versions of Linux also have a way to do it in the GUI. For example:
If these facilities are not available, you should use the chkconfig command to enable or disable the automatic start. For example, turn it off using:
/sbin/chkconfig intermapperd off
This has the effect of removing both symbolic links listed below. Read the file /etc/init.d/intermapperd to find out how to recreate them.
Remove S97intermapperd from /etc/rc3.d Remove K03intermapperd from /etc/rc6.d
You must remove the proper files from two /etc/rc* directories:
Remove S97intermapperd from /etc/rc2.d Remove K03intermapperd from /etc/rc0.d
It is possible to run InterMapper in a Linux "chroot jail." This prevents the InterMapper program from accessing any resources not specified by the network administrator.
These directions assume that InterMapper is installed on a Linux system in /usr/local/bin/intermapperd. We also assume that the configuration file is located in /usr/local/etc/intermapperd.conf with only the User directive configured:
User "bfish"
First obtain the program makejail/ Create a configuration file named intermapperd.py. Replace bfish with the user name on your system of the UID that will run intermapperd (in the jail). For security reasons, this should not be the root user:
chroot="/var/chroot/intermapperd" testCommandsInsideJail=["/usr/local/bin/intermapperd -d -f /usr/local/etc intermapperd.conf"] processNames=["intermapperd", "intermapperauthd" sleepAfterStartCommand=10 users=["bfish"] groups=["bfish"]
Become root and create the directory /var/chroot/intermapperd:
cd /var mkdir -p chroot/intermapperd
Switch back to the makejail directory and execute makejail for the first time:
cd ~/makejail-0.0.5 ./makejail intermapperd.py
The makejail program will make a first stab at creating the jail. You must now refine some of the permissions on your jail manually:
cd /var/chroot/intermapperd mkdir InterMapper_Settings chown bfish:bfish InterMapper_Settings
Note: Replace bfish above with the user name on your system. The InterMapper_Settings directory will contain runtime settings for intermapperd. You must edit the jail's intermapperd.conf file to use /InterMapper_Settings for it's IM Settings directory. To do this, edit usr/local/etc/intermapperd.conf to be like:
User "bfish" SettingsFolder "/InterMapper_Settings"
You must make the jail's copy of the intermapperauthd program setuid-root. Otherwise, the jailed intermapperd will not be able to open raw-icmp sockets to send pings or other privileged sockets:
chmod u+s usr/local/bin/intermapperauthd
Run makejail a second time. Now that intermapperd can create its preferences file, makejail can check that everything is there.:
Finally, you can test the jail itself, and verify that you can connect with InterMapper Remote. You will want to start intermapperd in debug mode with the -d flag to get the best diagnostics. You also need to use -A to enable access for the remote client.:
chroot /var/chroot/intermapperd /usr/local/bin/intermapperd -d -f /usr/local/etc/intermapperd.conf -A "admin@*.*.*.*"
Once you are comfortable that the jail is set up correctly, you can run the jail with the much shorter command line:
chroot /var/chroot/intermapperd /usr/local/bin/intermapperd -f /usr/local/etc/intermapperd.conf
Known Issues:
Host name lookups always return an address of 0.0.0.0.
Dartware certifies that InterMapper 4.6.5 is compatible with Leopard. There are two problems with earlier versions of InterMapper on Leopard: Time Machine and the Leopard firewall.
Within your InterMapper Settings folder, the InterMapper Logs, Chart Data, and Temporary folders contain large, frequently updated files that will quickly fill up your backup disk. Starting with InterMapper 4.6.5, these folders in your InterMapper Settings folder have been automatically marked as “off-limits” for Time Machine backups:
Do not rely on Time Machine to back up these folders on Leopard.
If you are running an earlier version (pre-4.6.5) of InterMapper on Leopard with Time Machine enabled, Dartware recommends that you manually exclude these three folders from Time Machine backups. Installing 4.6.5 fixes this automatically.
If the Leopard firewall is enabled, you must add exceptions for intermapperd and intermapperauthd. Without these exceptions in the Leopard firewall, intermapperd will be unable to check the status of devices using UDP or ICMP-based probes; instead, all devices will be reported as unreachable and therefore down.
Earlier versions of intermapperd (pre-4.6.5) are not compatible with the Leopard firewall. When added as a firewall exception, intermapperd will run once then cease to function.
Installing 4.6.5 installs a new binary, replacing a damaged one, but does not automatically add a firewall exception. To do this, open the Security system preference and click on the Firewall tab. Click the “+” button to bring up the Open... dialog and type cmd-shift-G to show the “Go to the folder:” sheet. Type /usr/local/bin and press return. You should see the contents of the /usr/local/bin directory. Add both intermapperd and intermapperauthd from this directory to the list of firewall exceptions and set their status to “Allow incoming connections”.
Leopard includes a new application layer firewall that controls access to the network based on the program that is running instead of arcane protocol numbers. The Leopard Firewall settings lets you specify individual programs as “exceptions” that can access the network.
For InterMapper to run on a Leopard system with the firewall enabled, two of its executable files must be added as exceptions to the firewall rules: intermapperd and intermapperauthd. Without these exceptions, InterMapper cannot monitor the network.
When you add an exception to the firewall, Leopard uses a program's code-signature to authenticate it. If the program's code was not signed by its developer, Leopard temporarily signs the program for you. This process is called ad-hoc code-signing, and it's also used by other parts of the OS that need to identify programs with particular privileges (e.g. Parental Controls).
Unfortunately, the ad-hoc code-signing process on Leopard irretrievably damages the intermapperd binary. When it rewrites the executable to add the code signature, it chops off about 700 Kbytes from the original binary. From that point on, intermapperd will refuse to run.
A symptom of a damaged binary is that InterMapper will run fine when you first install it, but it won't start up again if you try to restart it or simply reboot the computer. You may see a complaint in the system.log that says, “Executable has no resource section: /usr/ local/bin/intermapperd”. There is nothing you can do at this point except re-install InterMapper.
Starting with version 4.6.5, Dartware now signs the intermapperd binary. This fix prevents Leopard from applying an ad-hoc code signature and breaking intermapperd.
Command-line Probes and Notifiers using InterMapper DataCenter
The InterMapper DataCenter has a built-in Python interpreter that is available for creating new command-line probes and command-line notifiers.
Timbuktu as a Helper Application for MacOS X
How to set up Timbuktu Pro as a Helper application in InterMapper Remote.
Xserve Probes
The operation of InterMapper's probes for the G4 and G5 Xserve from Apple.
MikroTik Winbox as a helper application
An example of using the MikroTik Winbox software as a helper application.
Sending SMS Messages
How to send Short Message System (SMS) Messages from InterMapper.
Sending SMS/Text Alerts To a Cell Phone
How to send Short Message System (SMS) Messages from InterMapper to a cell phone.
InterMapper's Wireless Probe Pack provides a number of probes for monitoring MikroTik routers. These retrieve critical statistics from the MikroTik software running on a Routerboard, or as a WDS Bridge, Radio Uplink, or the software only. For more information on these probes, see our Wireless Probe Pack.
In addition, InterMapper can invoke the MikroTik Winbox software as a helper application. That is, InterMapper can invoke the Winbox application to show detailed status for a MikroTik router, wireless access point or Customer Premise Equipment (CPE).
When you configure the Winbox application to be a helper application for InterMapper, you can right-click on a MikroTik icon and open the Winbox software already connected to the proper device.
Note: You must run your copy of InterMapper or RemoteAccess on a Windows computer, as the Winbox program only runs on Windows.
To configure the Winbox software as a helper, first download the Winbox software to your computer. This is a one-time procedure:
After you have the Winbox software on your computer, you should configure the helper application as described in the Using and Configuring Helper Applications section of the User Guide.
To do this, right-click on a device, and choose Helper Apps > Customize.... Then click Add button, and fill in the resulting window with the following information:
After entering this, the MikroTik Winbox application will be immediately available through a right-click context menu.
Stephan Habenicht sends this summary of how he uses SMS messages as a notifier from his InterMapper server. It's also a nice example of creating a command-line notifier.
You'll need:
This is how it works:
There's a small .bat file called sms.bat with one single line:
echo %1 | gammu --sndsms TEXT 017212345678
Edit the message you want to send. I have had a problem with space or linebreaks, so I avoid them. This will be something like this:
<Event>_<Timestamp>_<Device Name>
That's it. Now you will be able to be contacted directly from the InterMapper server even when your Internet connection or your mail server goes down. Or maybe get a message when you have no email client available.
InterMapper can send SMS or text messages to a cell phone. This page formerly provided a description of how to do this.
That information has been incorporated into the InterMapper User Guide. Please refer to that document for the details.
InterMapper Remote allows you to use helper applications to perform other functions. For example, you can use Timbuktu Pro to connect to a remote server and administer it.
This note describes how to set up an AppleScript on MacOS X that gives a command to Timbuktu Pro to connect to the server you have right-clicked on.
You can use the built-in osascript command to launch Timbuktu Pro using an inline AppleScript. Here are the settings for the 'Customize' dialog:
Title: Timbuktu Command Line: ${PATH} ${ARGS} Path: /usr/bin/osascript Arguments: -e "tell application \"Timbuktu Pro\" to activate" -e "tell application \"Timbuktu Pro\" to make new control session connecting to internet address {internet name:\"${ADDRESS}\", ip address:\"${ADDRESS}\"}"
Note that the "Arguments" (shown on four lines in the example above) must all be on one line. We invoke osascript with two -e options because there are two lines in the AppleScript.
InterMapper can monitor an Apple Xserve via the same facilities used by Apple's Server Monitor application. There are significant hardware differences between the various servers that require separate probes for G4 Xserve and G5 Xserve computers. The G4 Xserve also requires that the version of Mac OS X running on the machine be specified.
The probe sends a POST request via HTTPS to port 311. The response to this request is an Apple plist in XML form. The XML is then parsed by the probe to retrieve the information. Probes require an administrators name and password in order to access the information.
Monitored items:
InterMapper Database is a part of InterMapper DataCenter. It acts as a central repository for data collected from one or more InterMapper servers. This data includes historical readings from customer charts, events that are written to a log file (up/down/warn/alarm/critical events, as well as notifications and acknowledgements), and a snapshot of the current state of each server's managed elements (maps, devices, interfaces, etc).
InterMapper Database gathers this data efficiently, organizes it in a clear and logical schema, and provides a means to respond to queries using industry standard SQL statements. InterMapper Database can be operated on its own or could be part of an organization's Configuration Management Database initiative (CMDB).
See more detailed information:
Customers install InterMapper Database on a machine on their network: it need not be the same computer as an InterMapper Server. They then configure each InterMapper Server on their network to register itself with the InterMapper Database server.
Once an InterMapper Server registers, InterMapper Database begins to query each InterMapper Server to retrieve three general types of data:
When InterMapper Database retrieves snapshot data, it updates the SQL database to match that snapshot. Devices that have been removed persist in InterMapper Database to preserve relational integrity, but are specially marked as not being part of the current snapshot. Continuous data is simply accumulated in the SQL database and can be compressed, reduced according to retention policy, or moved offline.
InterMapper Database is installed as part of the InterMapper DataCenter download. To install InterMapper Database, follow the instructions for installing InterMapper DataCenter, then follow the instructions for configuring InterMapper Database.
Once InterMapper Database is installed, you will need to configure your InterMapper Server(s) to register with the database, so that it knows to retrieve data from those servers. To do so, follow the instructions for registering an InterMapper Server with InterMapper Database.
Every minute, InterMapper Database requests all the current continuous data from its InterMapper server(s). In addition, if there is historical data (from previous days, months, or years of operation by earlier InterMapper servers) InterMapper Database will progressively request that older data. It works from the current time backwards until it has all been retrieved.
The Collection Profile in the InterMapper Server Settings/Database Server pane controls how aggressively to collect the old data. “Now” retrieves the data as fast as possible, but may use 100% of the computing resources on the InterMapper Database machine. “Gradually” requests historical data between every other one-minute query. This will impose a lower processor load, but gets the data more slowly. The “Nightly” and “Weekend” profiles use the Now policy, but only during specified hours of the day/weekend.
InterMapper Database records several kinds of datasets:
InterMapper Database collects raw data at the full resolution from the InterMapper Server. If the polling rate is fast — 30 seconds or even faster — InterMapper Database will collect and preserve all the information.
InterMapper Database can summarize all the raw data samples, and average over a longer (e.g., five, ten or 15 minute) time periods. This process, called data reduction dramatically reduces the amount of data stored.
For example, it might make sense to keep raw 30-second data samples for a week, but then reduce those data values to five-minute averages for six months, and retain only hourly averages after a year. This combination of poll rates and intervals is called a data retention policy. It specifies the time periods and durations that the particular data values are retained.
The InterMapper Database web GUI allows you to create additional data retention policies. You can use this to select how long to retain any particular set of data.
By default, InterMapper Server gives all devices and interfaces the server-wide default data retention policy, which is called "24 hour". All data is kept for 24 hours, then discarded. Note: There is one exception to this; when you upgrade to InterMapper 5.0 or later from InterMapper 4.6.x or earlier, InterMapper gives existing devices or interfaces that contain charts the "Forever" policy, which means that all data is saved forever.
To set the server-wide default data retention policy, open the server settings and click on the Database Server pane. To set the map-wide default data retention policy, open the map settings and click on the Retention Policy pane. To select a different retention policy for a device, use the Set Data Retention item in the Monitor menu or right-click on the device or interface and choose Set Info...->Set Data Retention.
Until InterMapper Reports is available to complement InterMapper Database, you will need external tools to retrieve data from InterMapper Database via SQL. To get you started, we've written several short example reports in Crystal Reports and OpenRPT, as well as several example perl scripts. The perl scripts require DBI and DBD::pg.
These scripts have been packaged and zipped and placed on our downloads server, available at http://download.dartware.com/sql/sql_examples.tar.gz. Please feel free to share your own, as well.
InterMapper Database can be divided into four major components:
The Retriever is implemented as a Python application running under the InterMapper DataCenter (IMDC). It uses an encrypted HTTP-based protocol to retrieve data from an InterMapper server. We do not plan to open this protocol as an API, as it is primarily designed as a means of conveying the information from InterMapper into the SQL database. Customers should use SQL queries against the Database to retrieve data for reports.
The DBUpdater is another Python application running under the IMDC. It performs these tasks:
Insert a brand-new snapshot of all the maps, devices, interfaces, notifications, etc. on a given server into the Database.
Update already-inserted devices in response to a snapshot.
Add new devices and remove deleted devices in response to add/remove events.
Insert blocks of continuous chart or event data, and link them to the objects that produced them.
Compress, reduce or discard data as dictated by user-specified data retention policies
A snapshot is received as a list of all entries in a certain category (maps, devices, interfaces, etc). Each element across all types is guaranteed to have a unique identifying code - an InterMapper ID (IMID).
An object's IMID contains information on its parents. If an interfaces report is requested, the IMID for each indicates the device, map and server that interface belongs to. This is used to set the server_id, map_id and device_id fields, as well as the interface's own interface_id field entry in the interface table.
Chart data is a series of data points, and can be inserted into the database sequentially. Each data point is associated with a data set.
Events may be split into a start and stop event. Start events have a half-empty entry created for them. When the event is over, the stop event completes the previous entry rather than getting a new one.
An InterMapper Server only keeps times up to the second. But there may be several events happening in one second, and they need to be distinguished. As an easy solution for now, InterMapper Database simply orders the events as they arrive, by adding an extra decimal value at the end of the time; i.e. .00000, .00001, .00002, etc.
InterMapper Database initially uses a PostgreSQL database (either the default one shipped with IMDC, or an external one) for storage. On installation or first startup, it creates a new database with the name "InterMapper Database", and sets up any default values and lookup tables. Support for other database managers will be added in future releases.
The first version of InterMapper Database has a web-based admin interface. It is not designed to construct queries or create reports; its only purpose is to set configuration options. When InterMapper Database is first started, a wizard walks the customer through setup steps to get it up and running.
If IMDatabase ever shuts down uncleanly, the built-in DB (if used) process must be killed manually before IMDC can start again
With the default configuration files on MacOS X, the built-in database may not start if you have multiple applications using postgresql. In this situation, the shared memory max must be increased manually. To increase the shared memory max, follow these instructions::
OSX 10.3.9 and later -------------------------------------------- 1. Open /etc/sysctl.conf, or create it if it doesn't exist. 2. Search through the file to find lines like the following: kern.sysv.shmmax=4194304 kern.sysv.shmmin=1 kern.sysv.shmmni=32 kern.sysv.shmseg=8 kern.sysv.shmall=1024 If those lines don't exist, create them at the top of the file. 3. Change the values to these: kern.sysv.shmmax=33554432 kern.sysv.shmmin=1 kern.sysv.shmmni=128 kern.sysv.shmseg=64 kern.sysv.shmall=8192 This increases the maximum shared memory to 32MB, from the default of 4MB. It also increases the number of available shared memory handles and pages. 4. Save the file and reboot your machine.
When you upgrade InterMapper from versions earlier than 5.0, the first start can last significantly longer than you are accustomed to. All existing maps - both enabled (residing in the "Maps" folder) and disabled (present in the "Maps (Disabled)" folder) - need to be processed to prepare them for InterMapper 5.0. Any subsequent starts of the server should take a normal amount of time.
"The map" below refers to every map from the "Maps" and "Maps (Disabled)" folders, unless stated otherwise.
Every disabled map undergoes two additional actions:
When an InterMapper server 5.0 starts, first disabled maps are processed, and then enabled maps are opened. Processing disabled maps means performing all the actions listed above and creating a list of disabled maps available.
Since disabled maps are processed first, some enabled maps may be renamed to ensure the uniqueness outlined in the second point of the list above.
Several new features and enhancements to InterMapper Database have been implemented in InterMapper 5.1. This tech note contains a summary of those changes.
The automatic and manual backup and restore actions have received many bug fixes and improvements based on user feedback. Most importantly, backups no longer time out for large databases, and the restore operation is more reliable.
The automatic backup page in the web interface now shows a progress indicator. It also provides a cancel button, which will stop the current operation and automatically clean up any temporary files.
The web interface now includes a 'Disk Usage Stats' page, which provides an overview of the database's contents. This page contains charts showing the number of maps, devices, interfaces, events and data points stored in the database. It also shows how quickly these entries are being accumulated, how much disk space is required to store them, and a rough estimate of how much space they will consume in the future.
The 'Database Settings' page now includes a per-user 'Remote Login' check-box. This automatically configures the database to grant that user access from any machine on the network, removing the need to manually edit the pg_hba.conf file.
The web interface now includes a 'Maintenance Tasks' page, containing several new actions for power-users. Most notably, it provides a 'Pause Import' button, which temporarily disables import for all servers, giving time to perform maintenance on the database while it is running.
Updated 8July2008
InterMapper DataCenter ships with an embedded Python interpreter. You may use this interpreter to write command-line probe scripts and command-line notifiers. If you are writing a probe in Python that may be of use to other InterMapper users, please use this Python interpreter for maximum compatibility. In InterMapper DataCenter 4.6, the version of Python we ship is 2.4.4, with optimized system libraries.
An extensive introductory tutorial on Python is available at http://docs.python.org/tut
IMDC's Python interpreter is installed in /usr/local/imdc/core/python/bin/imdc on UNIX platforms and in c:\Program Files\InterMapper\dwf\core\python\imdc.exe on Windows.
/usr/local/imdc/core/python/bin/imdc
c:\Program Files\InterMapper\dwf\core\python\imdc.exe
As shipped, this Python interpreter requires the use of optimized and stripped mode (-OO), so the interpreter must be invoked as /usr/local/imdc/core/python/bin/imdc -OO script_name on UNIX and c:\Program Files\InterMapper\dwf\core\python\imdc.exe -OO script_name on Windows.
/usr/local/imdc/core/python/bin/imdc -OO script_name
c:\Program Files\InterMapper\dwf\core\python\imdc.exe -OO script_name
Python scripts that use this interpreter will have the following general form:
#! /usr/local/imdc/core/python/bin/imdc -OO # Sample script using the InterMapper DataCenter Python interpreter # # The first line is a Python comment, and is ignored by Python. # On a UNIX platform, it identifies the interpreter that should be # used to run the script. # # On Windows, the initial comment line is ignored, and the command # line (see below) must explicitly reference the interpreter, which is: # c:\Program Files\InterMapper\dwf\core\python\imdc.exe print "Hello from Python"
A silly sample Python script would look like this. (Save this file as sample.py in the InterMapper Settings/Tools directory.)
#! /usr/local/imdc/core/python/bin/imdc -OO # Sample probe script using the InterMapper DataCenter Python interpreter # This script is similar to the sample Perl command-line probe script # Save this text in a file named sample.py in the Tools directory import sys if (len(sys.argv) < 2): print "Usage: %s _address_" % sys.argv[0] sys.exit(0) addr = sys.argv[1] # Code to get status from device at address addr import random result = random.randrange(4) print "Pretending we got result %d from device at address %s" % (result, addr) sys.exit(result)
A matching probe that uses this script looks like this:
type="cmd-line" package="com.dartware" probe_name="python.sample" human_name="Python Sample" version="1.0" address_type="IP" display_name = "Miscellaneous/Testing/Python Sample" \GB\Python Sample Command-Line Probe\p\ A sample command line probe which executes a Python script. The Python script generates and returns a random number which sets the device status to one of four values Down/Alarm/Warning/OK. -- Unix/OSX: Empty path forces the InterMapper Settings:Tools directory path="" cmd="sample.py ${ADDRESS}" -- Windows - path must point to Python interpreter; command line program must be in Tools -- path="c:\Program Files\InterMapper\dwf\core\python" -- cmd="imdc.exe" -- arg = "-OO sample.py ${ADDRESS}" down:${EXIT_CODE}=3 alarm:${EXIT_CODE}=2 warning:${EXIT_CODE}=1 okay:${EXIT_CODE}=0
One change needs to be made for Windows: the command line (cmd=... below) needs to be altered to correctly locate the Python interpreter.
cmd=...
-- Windows - path must point to Python interpreter; command line program must be in Tools path="c:\Program Files\InterMapper\dwf\core\python" cmd="imdc.exe" arg = "-OO sample.py ${ADDRESS}"
On Unix, the #! line allows the interpreter to be placed elsewhere, and the operating system will correctly resolve the reference to it. Such a command-line notifier might look like this:
#! /usr/local/imdc/core/python/bin/imdc -OO # Sample notifier using the InterMapper DataCenter Python interpreter # For a mythical lava-lamp based notification system. import sys import lavalamp_control state=argv[1] if state == 'On': lavalamp.turn_on else: lavalamp.turn_off
The following documents are available to describe the features of InterMapper DataCenter, and its components, the InterMapper Database, the Authentication Server, and the built-in Python interpreter.
Installing the InterMapper DataCenter
The InterMapper DataCenter (IMDC) is a stand-alone collection of services used alongside InterMapper. This note describes how to install the IMDC, which also automatically installs the InterMapper Database, the Authentication Server, and the Python interpreter.
The InterMapper Database
The InterMapper Database is a PostgreSQL database that is integrated into an InterMapper system. It automatically receives historical and static information from InterMapper, and saves it for analysis by other programs.
Using the IM Authentication Server
The InterMapper Authentication Server ("AuthServer") allows you to authenticate against a number of directory servers, including LDAP, Active Directory, Open Directory, Radius, IAS, and DND. This tech note explains how to configure and use the AuthServer.
Writing InterMapper Datacenter Plugins
InterMapper Datacenter incorporates a Python 2.4 interpreter that customers may use for writing plugins, such as command line probes and command line notifiers. This tech note describes how to write these plugins and call them.
IMDB Space Estimator
This calculator estimates the amount of space that will be consumed by InterMapper Database.
Many servers these days are being shipped with Service Processors. A Service Processor is a separate processor inside the chassis (usually on the motherboard) that runs independently of the main computing system. The Service Processor has its own network identity and is connected to sensors on the motherboard and chassis. The sensors enable the Service Processor to independently monitor and manage the main computing system. As a simple "computer within the computer", the Service Processor can retrieve statistics, restart a hung system, power on/off the system, or reconfigure how the system boots.
The Intelligent Platform Management Interface (IPMI) is a vendor-independent protocol for talking to Service Processors.
InterMapper 5.0 supports IPMI v2.0 for monitoring the service processors in Apple XServes and Dell 9-series PowerEdge servers over an IPv4 LAN.
Read-only operation; no remote configuration, power on/off, or LED control.
No vendor-specific functionality. For example, we can't show everything that Apple's Server Monitor can show.
IPMI is an incredibly "chatty" protocol; there are still optimizations to be made in our polling engine.
We only support the "required" IPMIv2 authentication, integrity, and encryption algorithms (HMAC_SHA1, HMAC_SHA1_96 and AES_CBC_128). We don't support un-encrypted operation.
We don't support IPMI 1.5.
We've done preliminary testing with Apple XServe (Intel) and a Dell 9-series PowerEdge server. We have not tested any other IPMI implementations.
Losing a packet causes a device probed with the IPMI probe to go down,
Sometimes a temperature sensor shows a negative value.
InterMapper 5.2 has several new features that make it easier to build command-line probes. Here are some pointers, and a fun example that uses the new features to retrieve temperature data from the US NOAA weather feed in a particular city. How does this probe work? The customer opens the probe picker, selects the Weather Service-Temp probe (it's in the Miscellaneous/Test category). Enter the city code for the closest weather station (KLEB is at Lebanon Municipal Airport, about a half mile to the south of us.) The Status window shows the name of the weather station, and there's a chartable value for the temperature reading. Under the covers, InterMapper launches a Python program to contact the weather service, retrieve the meteorological conditions for the indicated city, and parses out the XML response to retrieve the temperature. (There's lots more information in the feed - the program could easily be extended to display more information.) Here are some of the features of this probe:
1) It's now easy to write cross-platform Python probes. The ${PYTHON} macro gives the path to the built-in python interpreter of InterMapper DataCenter no matter what platform you're using. For example, the probe can now use:
cmd = "${PYTHON} program.py"
and InterMapper will invoke Python by substituting the proper path, whether on Windows, OSX, or Linux.
NB The InterMapper DataCenter (IMDC) must be installed. This happens automatically with InterMapper 5.2 on Windows and OSX; Linux and Unix systems require a separate install for IMDC.
2) Probe writers can now include the script directly in the text of the probe file. (Earlier versions of InterMapper required that the script be saved separately in the Tools directory or elsewhere.) This makes it much easier to write scripts and keep the probe file in sync. To do this, use the new <tool:program-name> section in your probe file. The example file contains a program named noaa-weather.py.
When InterMapper loads the probe, it parses out this section and saves it in a folder within the Tools directory of InterMapper Settings. These programs may also save private files in that directory.
3) The example probe file uses a couple interesting Python libraries. First is urllib2 that makes it easy to retrieve data from web services. It's a few straightforward calls to build a url, issue it, and retrieve the results.
4) The probe also uses the xml.dom.minidom library to parse out XML data returned from the NOAA web service. This library is particularly well-explained in Chapter 9 of Dive into Python (see below)
Developer Guide: General information about building custom probes http://download.dartware.com/docs/DevGuide52/ ${PYTHON} macro: http://download.dartware.com/docs/DevGuide52/Content/02-CustomProbes/builtinvariablereference.htm#commandlinevariables Companion Scripts: Including the script directly into the probe file. http://download.dartware.com/docs/DevGuide52/Content/02-CustomProbes/Companion_Scripts.htm Python Documentation: urllib2 - http://docs.python.org/library/urllib2.html xml.dom.minidom - http://docs.python.org/library/xml.dom.minidom.html Dive into Python: A very readable chapter on XML processing in Python http://diveintopython.org/xml_processing/
To use this probe, copy the text below, save it to a text editor, then use File->Import->Probe... in InterMapper.
<!-- Weather Service Temperature - Retrieve the temperature from the NOAA weather XML (com.dartware.tool.noaa.txt) Copyright (c) 2009 Dartware, LLC. Please feel free to use this as a base for further development. --> <header> type = "cmd-line" package = "com.dartware" probe_name = "tool.noaa" human_name = "Weather Service-Temperature" version = "1.2" address_type = "IP" display_name = "Miscellaneous/Test/Weather Service-Temp" </header> <description> \GB\Retrieve the current temperature\p\ This probe retrieves the current temperature from the NOAA weather feed. To see the proper city code, visit: \u4=http://www.weather.gov/xml/current_obs/\http://www.weather.gov/xml/current_obs/\p0\ </description> <parameters> "Weather Station" = "KLEB" </parameters> <command-line> path="" cmd="${PYTHON} noaa-weather.py" arg="${Weather Station}" </command-line> <command-exit> -- These are the exit codes used by Nagios plugins down: ${EXIT_CODE}=4 critical: ${EXIT_CODE}=3 alarm: ${EXIT_CODE}=2 warn: ${EXIT_CODE}=1 okay: ${EXIT_CODE}=0 </command-exit> <command-display> \b5\ Temperature for $loc\p0\ Temperature: $temp \3g\degrees F\p0\ </command-display> <tool:noaa-weather.py> # noaa-weather.py # Scan the XML results from NOAA's XML feeds # e.g., http://www.weather.gov/xml/current_obs/KLEB.xml # for relevant weather-related information. # 25 Mar 2009 -reb import os import re import sys import getopt import urllib import urllib2 import htmllib from xml.dom import minidom # httplib.HTTPConnection.debuglevel = 1 # force debugging.... # options are: station try: opts, args = getopt.getopt(sys.argv[1:], "") except getopt.GetoptError, err: searchString = "getopt error %d" % (err) station = args[0] userAgent = "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_5; en-us) AppleWebKit/525.18 (KHTML, like Gecko) Version/3.1.2 Safari/525.20.1" noaaString = "http://www.weather.gov/xml/current_obs/%s.xml" noaaString = noaaString % (urllib.quote_plus(station)) # print noaaString; retcode = 4; try: request = urllib2.Request(noaaString) opener = urllib2.build_opener() request.add_header('User-Agent', userAgent) usock= opener.open(request) # print buf except IOError, e: if hasattr(e, 'reason'): resp = 'We failed to reach a server. ' reason = 'Reason: ' + 'Wrong host name?' # e.reason[1] elif hasattr(e, 'code'): resp = 'The server couldn\'t fulfill the request. ' reason = 'Error code: '+ str(e.code) print "\{ $temp := '%s', $loc := 'Unknown' } %s" % (0, resp + reason) sys.exit(retcode) # make it look down retcode = 0 # looks like it'll succeed xmldoc = minidom.parse(usock) tempList = xmldoc.getElementsByTagName('temp_f') tempElem = tempList[0] tempval = tempElem.firstChild.data loclist = xmldoc.getElementsByTagName('location') locval = loclist[0].firstChild.data print "\{ $temp := '%s', $loc := '%s' }%s" % (tempval, locval, tempval + ' degrees at ' + locval) sys.exit(retcode) </tool:noaa-weather.py>
Q: I get a warning that my SSL certificate has expired. What does this mean?
A: InterMapper uses a SSL certificate to encrypt the traffic between it and the InterMapper GUI client. All SSL certificates have expiration dates in them, typically one year.
You can get a new certificate by upgrading InterMapper server to the latest version, or by creating and installing your own self-signed certificate, or you may purchase a certificate from a Certificate Authority such as http://instantssl.com, http://verisign.com, or http://thawte.com
Q: I get a warning about a problem with my SSL certificate - it's for "low-security.dartware.com" What does this mean?
A: Dartware ships every version of InterMapper with a Dartware-generated SSL certificate. Because it's the same certificate for all customers, it is not secure. It does, however, trivially encrypt the traffic, so it is safe from casual snooping.
If you wish to have a more secure certificate, you can install your own self-signed certificate, or purchase a certificate from a Certificate Authority such as http://instantssl.com, http://verisign.com, or http://thawte.com
Probe Groups allow you to include multiple probes targeting the same IP address in a single icon on a map. The Probe Group shows the status of the worst status among the probes in the group. A Probe Group counts as a single device against your license count.
Probe Groups will allow you to:
Group a number of probes for an IP address into a single icon
Add new probes to an existing group
Ungroup the icons (individually, or all the members)
Poll each member probe at its own rate, with its own settings
Reflect the most serious condition of all the member probes in the icon's color
Get notifications when the entire group has a problem
Get (separate) notifications when a member probe has a problem
Handle dependencies - if the "Control Probe" is down, no notifications will be sent for any other member probes.
Show SNMP device and interface information based on the choice of the Control Probe.
Cisco Systems, Inc. has produced a set of freely available Network Topology Icons that they encourage you to use in network diagrams, documentation, etc.
Dartware has converted these icons to PNG format. The full set contains over 750 icons in three different sizes -- full size, 64-pixel icons, and 32-pixel icons. The 32-pixel icons work well with our InterMapper network monitoring software, as they are the same size as InterMapper's default icons. The other sizes are larger, and may be useful in your application or diagrams.
For ease of viewing and organization, the icons have been divided into six folders, according to their file name, matching the six pages of the Cisco Icon Library, a PDF file which provides a preview of the icon images.
We are making our versions of the Cisco icons freely available at no charge. You can get these icons as a 2.1 MByte archive containing over 750 icons by filling out the form. We will send you an e-mail containing a URL for downloading the icons.
The original icons are available from the Cisco Network Topology Icons page. Dartware, LLC disclaims any copyrights on the use of these icons. For more information, please contact support@dartware.com.
Below are links to information about previous versions:
What's New in 5.0 (Release Notes)
What's New in 4.6 (Release Notes)
What's New in 4.5 (Release Notes)
What's New in 4.4 (Release Notes)
What's New in 4.3 (Release Notes)
What's New in 4.2 (Release Notes)
What's New in 4.1 (Release Notes)
InterMapper may report that a device is down for 21 seconds or 51 seconds, or some other short interval. This occurs because the device being tested is actually unresponsive during the time that InterMapper is attempting to test it, but that it responds immediately the next time InterMapper tries.
In general, InterMapper will not consider a device to be down until it has exhausted its attempts to ping/query/connect to it. The following discussion is relevant for "packet-based devices" using pings, SNMP queries, etc. TCP-based probes, such as HTTP, IMAP, SMTP, etc., use the underlying operating system's built-in TCP connection retry mechanism, which differs from the following.
By default, InterMapper will try the packet-based probes three times, spaced three seconds apart. Thus, it takes nine seconds (3 tries, spaced three seconds apart) to determine that the device is down.
When the next poll interval starts (usually 30 seconds after the start of the previous poll), InterMapper tries again. If the device responds right away, then the outage will appear to have lasted 21 seconds (30 second poll interval, minus the nine seconds waiting to determine that the device was down.) For full details about InterMapper's polling procedure, see the User Guide.
We have found a few major causes for this:
The device is unresponsive for a moment. If the device doesn't respond within the timeout (perhaps because it or an intervening resource was busy), then InterMapper will decide the device was down, even though it had actually been operational.
High packet loss. If the packet loss on the route between InterMapper and the device is high (generally greater than 10%), then it becomes likely that all of InterMapper's queries might be dropped. This can be a symptom of a problem on the network.
InterMapper versions prior to 4.5.1 might receive ping response packets, but fail to process them in a timely manner. This could incorrectly raise packet loss statistics. We strongly recommend you upgrade to a current version if you're using InterMapper 4.5 or older.
If the packet loss is low, you can try extending InterMapper's timeout for the device. To do this, Set Info... -> Set Timeout... on the device to set a longer period. This allows more time for the device to respond.
High packet loss is always a symptom of bad network performance. If InterMapper's ping traffic experiences high loss, so will your real data packets. You should look for the cause of the packet loss, because it will lead to slow performance for all the people using that portion of the network.
You can use InterMapper's command-line probe feature to run a wide array of useful Nagios plugins. These are available from the Nagios website or from the Nagios Plugins website.
Earlier versions of InterMapper had a "Nagios Template" probe for this function.
InterMapper 5.0 renames this probe the "Nagios Plugin" probe and enhances it to interpret the results from the Nagios plugins more completely. If you are familiar with the previous version of this probe, please scroll down to "Changes" to get a quick list of changes. Otherwise, read on.
The Nagios Plugin probe lets you specify a Nagios plugin to run, along with any associated parameters. You can use the ${ADDRESS} and ${PORT} macros in the command line — InterMapper substitutes the device's IP address and the specified port. InterMapper will invoke the plugin and use the exit value to set the condition of the device to UP/Okay, UP/Alarm, UP/Critical, or DOWN.
InterMapper also interprets the information written to stdout by the plugin and formats it into the InterMapper status window. In particular, the performance data returned by the probe becomes a list of chartable variables, and the reason/condition appears as the device's condition string.
The Nagios Plugin probe expects the Nagios plugin to be in the Tools sub-directory of the InterMapper Settings directory.
Nagios and the Nagios logo are registered trademarks of Ethan Galstad. For more information, see http://www.nagios.org/.
The (earlier) Nagios Template probe mapped plugin exit code 2 as down. The Nagios Plugin probe maps plugin exit code 2 as critical, and plugin exit code of 3 as down.
The Nagios Template probe took any data written to stdout as the "condition" or "reason" for the status. The Nagios Plugin probe detects the presence of performance data ("PERFDATA") in the output, and makes a formatted and chartable display of the data.
The canonical name of the Nagios probe has not changed; any device which used the old Nagios Template will now automatically use the Nagios Plugin probe.
IP SLA uses active traffic monitoring—the generation of traffic in a continuous, reliable, and predictable manner—for measuring network performance edge-to-edge over a network. The traffic generated simulates network applications like VoIP and videoconferencing, and collects network performance information in real time. The information collected includes data about jitter (interpacket delay variance), latency, and packet loss.
Cisco IP SLA is supported on most IOS-based Cisco routers and switches. IP SLA was previously known as Service Assurance Agent (SAA).
You can easily configure your Cisco routers and switches to be IP SLA agents or IP SLA responders. An agent initiates IP SLA tests to a remote responder. A particular agent can have multiple IP SLA tests running to many remote responders. A particular router or switch can be both an agent and a responder. For each IP SLA test that has been configured the agent collects edge-to-edge network performance information and stores it in the Cisco RTTMON MIB.
The InterMapper Cisco IP SLA Jitter probe uses SNMP to collect the information from the RTTMON MIB in the agent, allowing you to alarm jitter, latency, and packet loss, and to chart these values. You can download a .zip of the probe.
The InterMapper Cisco IP SLA Probe is particularly useful for monitoring and measuring QoS for VoIP and videoconferencing applications. However, it is useful in many other contexts including:
An IP SLA Probe User Guide describes how to set up the IP SLA testing between two Cisco routers/switches and how to configure the InterMapper probe to monitor the values.
This page shows a sample Status Window for the probe. You can also see a screenshot with several graphs from a live installation.
Extensive documentation about IP SLA and how to configure IP SLA is available on the Cisco web site. Notably, they publish a Cisco IOS IP Service Level Agreements (IP SLAs) Overview (PDF) that describes the major features of IP SLA.
InterMapper DataCenter (IMDC) is a stand-alone collection of services used alongside InterMapper. Currently, this includes the InterMapper Authentication Server (IMAuth).
IMAuth allows you to authenticate users against a wide variety of directory servers, including LDAP, Active Directory, Open Directory, Radius, IAS, Kerberos and others. Read the InterMapper Authentication Server Tech Note for more details.
Install InterMapper 4.6 and, if desired, InterMapper RemoteAccess 4.6. You can retrieve them from the InterMapper Release Page..
Download the InterMapper DataCenter package for your operating system from the InterMapper Release Page.. This will install IMDC along with the IMAuth service. The package will be installed to "/usr/local/imdc" on Mac OS X and UNIX systems, and "Program Files\InterMapper\dwf" on Microsoft Windows.
The installer will automatically register IMDC as a startup service on most operating systems.
Windows: IMDC will be registered as a Windows Service, and can be controlled from the Services Control Panel. It will automatically start after installation and on system startup.
Mac OS X: IMDC will be registered as a launchd Launch Daemon. It will automatically start after installation and on system startup.
Linux/Unix: Links will be created in init.d and the proper rc runlevels. The daemon will automatically start after installation and on system startup. It can be controlled using the init.d 'imdc' script for your system, with the standard start and stop commands.
IMDC will automatically create a user and group called 'intermapper' ('intermap' on Solaris) on installation. This user is created without a shell, without a home, and unable to login. IMDC will start as this user, ensuring that it only has permission to modify a limited set of configuration files.
If you would like to view the IMDC or IMAuth log files, you can either use the IMDC web admin panel (explained further below), or you can add yourself to the intermapper group, at which point you will have read access to the files (/usr/local/imdc/log/*.log).
Windows: You can use the services control panel to start and stop IMDC.
Mac OS X: You can use the /usr/local/imdc/sbin/imdc script with 'start' and 'stop' parameters to start and stop IMDC.
Linux/Unix: You can use the /usr/local/imdc/sbin/imdc script with 'start' and 'stop' parameters to start and stop IMDC.
Before you can use IMDC, you need to configure it. To do this, open a web browser and navigate to: https://localhost:8182 while IMDC is running. On Windows you can simply go to Start Menu > All Programs > InterMapper > InterMapper DataCenter and click on Configure Server. A short wizard will walk you through the steps needed to set up IMDC.
The IMDC presents a list of services, including a wizard for configuring IMAuth. Read the InterMapper Authentication Server Tech Note for more details.
InterMapper 5.0 included a "technology preview" of InterMapper Database. We have continued to develop and test InterMapper Database, and InterMapper 5.1 includes significant improvements to it.
One visible change is that when you install and configure InterMapper Database, it will detect if InterMapper is already running on the same machine and give you the opportunity to automatically start the reporting in InterMapper.
The InterMapper Authentication Server (IMAuth) allows an InterMapper server to authenticate users against a name directory. IMAuth acts as an intermediary between an InterMapper server and the directory, and supports Kerberos, LDAP, RADIUS, ActiveDirectory, IAS and DND directories.
When an authentication request comes in from a user who has been configured as "external", the InterMapper server will forward that request to IMAuth. IMAuth translates and passes this request on to the directory server, and forwards any responses it receives back to the InterMapper server.
Note that IMAuth is not a replacement for InterMapper's local user database. Access permissions are still obtained from the local database, and if a user has not been configured as "external", InterMapper will use the local database for authenticating the user rather than contacting IMAuth. If a user has a different name on the directory server than in the internal database, a new user entry will be created. You will need to re-assign any access controls or permissions to that new user entry. New entries are also added to a group which you specify when configuring IMAuth access in InterMapper, and inherit that group's permissions.
You must first install the InterMapper DataCenter. Read the InterMapper DataCenter Tech Note for details. The IMDC presents a list of services, including one for IMAuth.
Click on the link in the IMDC to walk through a short series of steps.
Select a directory server type (LDAP, Active Directory, Radius, Open Directory, IAS, etc.)
Specify the IP address/DNS name and port for the specified server. There is a facility for testing the configuration on that page.
Open InterMapper Server settings, and tell the InterMapper server to use IMAuth.
This section gives information about configuring the AuthServer to use the following types of directory servers.
Kerberos
Kerberos is the most secure protocol supported by IMAuth. Rather than forwarding a user's name and password, IMAuth acts as a kerberized service. InterMapper Remote will obtain a Kerberos ticket (or use an existing one if the user already has one). It then sends a Kerberos service access request to IMAuth, which verifies that the ticket is valid and grants the user access.
However, if Kerberos is used, it will only apply to authentication attempts from InterMapper RemoteAccess. Authentication attempts from the web or telnet interfaces are unable to use Kerberos. If you need to authenticate from the web or telnet interfaces, you will need to select ActiveDirectory or IAS authentication instead.
Like any other kerberized service, IMAuth requires a service principal key on your Kerberos server. You will need to export this key in an MIT-Kerberos-compatible keytab file. This is done with the 'kadmin' utility in MIT Kerberos (or systems based on it, like Apple's OpenDirectory).
If you are using a Windows Server 2003 ActiveDirectory Kerberos KDC, you should use the 'ktpass' tool to export the service key as a keytab file. You must use the Service Pack 2 version of the ktpass tool, because the version distributed with Service Pack 1 has a critical flaw that prevents keytabs from being exported properly. You can download the Windows Server 2003 Support Tools for Service Pack 2, which includes a working ktpass.exe, from this page:
Windows Server 2003 Support Tools SP2
To create the keytab file, first create a user called 'imauth' in ActiveDirectory. Then, run ktpass.exe with these options:
ktpass.exe -princ imauth/hostname@NT-DNS-REALM-NAME -mapuser account -pass password -out imauth.keytab
Where hostname, NT-DNS-REALM-NAME, account and password are replaced by your AD server's host name and realm, and the username and password you created in step 1.
More detailed information can be found at this page:
Microsoft Ktpass.exe Howto
Once you have created the service principal key and exported it, you can use the IMAuth web admin panel to upload the keytab file for IMAuth to use.
Keep in mind that, due to the way service principal keys are generated, each time you export the key it will change. So whenever you create a keytab using kadmin or ktpass, you must upload this new keytab to IMAuth. Otherwise the key in the KDC's database and the key IMAuth stores will be different.
As with any other kerberized application, authentication will fail unless the system clock on the machines running InterMapper RemoteAccess are synchronized to the time on your Kerberos KDC.
RADIUS and Microsoft IAS
IMAuth acts as a RADIUS NAS, and so it must be added to the clients section of your RADIUS configuration file or, for Microsoft IAS, the clients section of the IAS configuration pane. You will be asked to specify a secret, and must then enter exactly the same secret in the IMAuth RADIUS or IAS settings.
LDAP
If you encounter any problems with LDAP, first try un-checking the Use SSL option or choosing Whenever Necessary for the Use Plaintext option in the IMAuth LDAP settings. If this works, it means your server wasn't built or configured to include SSL or SASL DIGEST-MD5 password encryption. You'll need to either stay with the lower security settings, or upgrade your LDAP server.
Another thing to look at is the LDAP Base DN specified in the IMAuth LDAP settings. This tells IMAuth where in your LDAP directory the user entries are located. This depends on how your directory was set up, but it will usually take the form: ou=people,dc=example,dc=com, where example and com correspond to the domain name your directory was set up with. IMAuth takes the Base DN and attaches the user's name; for example: cn=Jane,cn=Smith,ou=people,dc=example,dc=com.
ou=people,dc=example,dc=com
cn=Jane,cn=Smith,ou=people,dc=example,dc=com
Microsoft ActiveDirectory
ActiveDirectory is based on LDAP, but differs slightly in its default configuration. Versions included with Windows 2000 or earlier may not support all features. So if you are encountering problems in that case, try un-checking the Use SSL option or choosing Whenever Necessary for the Use Plaintext option in the IMAuth LDAP settings.
The Base DN for an ActiveDirectory server will almost always be: cn=Users,dc=example,dc=com where example and com are replaced by the name of the Windows Domain that ActiveDirectory is serving.
cn=Users,dc=example,dc=com
ActiveDirectory should almost always support SSL. Therefore, choosing the Only when using SSL option for the Use Plaintext field in the IMAuth LDAP settings will not greatly affect your security. If you do need the additional encryption, perform these steps:
Since ActiveDirectory is built around the idea of domains rather than single servers, the username you use to authenticate may be different from your Windows login name. The exact form depends on how your server is configured, and whether you are using SASL encryption or not. If you are having trouble authenticating, try these variations of the user name:
Plain username (i.e. janesmith)
User's full name (i.e. Jane M. Smith)
Username with the ActiveDirectory domain attached (i.e. janesmith@example.com)
InterMapper 5.1 exports the following information so that Google Earth can place them in the proper location:
Explicitly, through the use of the Set Info->Set Latitude and Longitude command in the InterMapper GUI, or
Implicitly, by establishing benchmarks via Insert->Map Benchmark or similar.
The easiest way to get the URL is to use the InterMapper web interface. Go to a map's page, and click the "View this map in Google Earth" at the bottom of each page. That link returns a .kml file; assuming Google Earth has been properly installed, your browser should offer to open that link in Google Earth; if it does not, save the resulting file and open it manually in Google Earth.
When everything is properly set up, you will see the status badges for your devices hovering over the surface of the Earth in appropriate locations. You may click on a device badge and see the corresponding Status Window.
The map refreshes automatically every 5 minutes.
Dartware is frequently asked for recommendations about tools that can be used to enhance our InterMapper network monitoring software. This page lists a few that we have found to be useful:
Wireshark, and its predecessor Ethereal, are open-source packet capture programs that will interpret and display all the packets sent on a particular link. These programs are known colloquially as "sniffers", and they are useful for very low-level debugging.
Wireshark is the name for the current project; Ethereal was a previously-used name for this code base. You can download and compile these packages from http://wireshark.org and http://ethereal.com, respectively. The following sites also have pre-built binaries for these platforms:
Windows The Wireshark site offers a pre-built installer for Windows.
MacOS X Andreas Fink of Fink Consulting GmbH has packaged an installer version of Wireshark for MacOS X on both PowerPC and Intel. Go to the Fink Consulting download page for Wireshark and a number of open source packages.
Unix/Linux The Wireshark site also has pre-built versions for various Unix or Linux distributions. You can also build the package from source from this site.
The open-source Mibble MIB Browser is a Java application, and thus runs on Windows, MacOS X, and Unix/Linux. It will open various MIB files, let you browse the variables defined in those MIBs, and can query a device using SNMPv1, v2c, or v3.
(Updated 16 Feb 2007) Yes. Or more precisely, current versions of InterMapper will work properly as long as the underlying operating system and Java virtual machine have been updated to handle the change of Daylight Savings Time. InterMapper and RemoteAccess always use UTC internally, but use the underlying environment's time facilities to convert to the local time that's displayed in log files and chart data.
As long as your OS/JVM have been updated, InterMapper will continue to operate properly. We have received information that the following environments have been patched and/or updated.
In the US, Daylight Savings Time will begin earlier and end later, starting in 2007 as mandated by the U.S. Energy Policy Act of 2005. Other countries are implementing similar changes. The patches above will ensure that your computer works properly with the US2007DST time changes.
Jennifer Mears wrote an interesting article on Network World that describes the interaction between network time servers and operating systems regarding the DST switch.
