Abstract
Describes the Mars network status monitor - how to install, run, and use it - and gives a brief overview of the Mars architecture for those who wish to hack it. (Version of May 8, 2001, covers Mars 2.0.0)Table of Contents
Mars is a simple services-oriented network status monitor written in Java. It monitors a network by simulating client connections to Internet services and reporting when those services are not responding. It is quick and easy to install and configure, which distinguishes it from other, more complex, more fully-featured network monitoring tools.
The Mars distribution is available at http://www.altara.org/mars.html. It comes in two flavors, binary (containing only the .jar files you need to run Mars and this manual) and source (containing the complete build system).
Mars is released under the GNU General Public License, version 2. This means you are free to modify and redistribute it, provided that you make your modifications available under the GPL. The text of the GPL is available in the COPYING file in the doc directory in the Mars distribution for details.
The Mars distribution contains JDOM beta 8, ©2000-2002 Brett McLaughlin and Jason Hunter, all rights reserved. JDOM is developed by the JDOM Project at http://www.jdom.org/. See the LICENSE-jdom file in the doc directory in the Mars distribution for details.
The Mars distribution contains Apache Xerces-J 2.0.1, ©1999-2002 The Apache Software Foundation, all rights reserved. Xerces is developed by the Apache Software Foundation at http://www.apache.org/. See the LICENSE-xerces file in the doc directory in the Mars distribution for details.
The Mars binaries are distributed in two files, mars.jar and mars-dep.jar. The difference is that mars.jar contains all the required packages to ensure that it will run on any machine with a compliant JDK, regardless of whether the required packages are installed or not. mars-dep.jar only contains Mars itself. The tradeoff is, of course, that mars.jar is huge compared to mars-dep.jar, and all the extra baggage is useless if you've already installed all the required packages into your Java runtime environment.
That having been said, once you've selected one of the two .jar files to use, Mars is quite simple to install. The entire program is self-contained in the .jar file (though this is planned to change in Mars 2.1, so be forewarned). Just copy the .jar file to the directory you'd like to run Mars from, and you're done.
Mars is a Java application, and therefore requires a Java runtime environment to be installed on your machine before running. Any J2SE runtime version 1.3 or later should do. Sun's Java runtime (the version on which Mars 2.0 was developed and tested) is available at http://java.sun.com/j2se/; a list of ports to operating systems not supported by Sun's runtime can be found at http://java.sun.com/cgi-bin/java-ports.cgi.
In addition, Mars requires:
- a JAXP-compatible XML parser (Apache Xerces is used for development and testing). Xerces is available at http://xml.apache.org/xerces2-j/
- JDOM beta8 or later, available at http://www.jdom.org/
This section will walk you through your first time running Mars. It covers the initial configuration of a new Mars installation, including adding hosts to the system and selecting services on those hosts. There is not much to actually using Mars, as it runs without intervention, automatically monitoring the hosts it knows about. After this introduction, you should have a pretty good feel for how Mars works.
Note
This section, and the rest of the document, assume that you've selected mars.jar. If, instead, all the required packages are installed into your Java runtime, substititute mars-dep.jar below.Mars can be invoked two ways, either from the command line or (in environments that support it, such as Microsoft Windows) by double-clicking the mars.jar file. To invoke Mars from the command line, type:
java -jar mars.jar
java -jar mars.jar my-config.xml
When Mars starts, you'll see the splash screen appear momentarily, then Mars itself will appear:
The Mars main window has three parts: a host/service tree, a fault list, and a service detail panel. The host/service tree displays the hosts and services Mars knows about; when Mars is actively monitoring, it also displays the status of each service. The fault list displays all current problems with monitored services. The service detail display shows relevate details about the service selected in the host/service tree. A fourth display, the service status change log, can be accessed through the History tab at the bottom of the window.
The host/service tree can be manipulated through a context menu on the tree. By right-clicking (control-clicking on machines with one-button mice) on a host or service in the tree, or on blank space within the tree, you can bring up the context menu, which allows you to access relevant tree editing operations. Since you've started with a new configuration, the host/service tree is empty; anywhere you right-click will bring up a context menu with a single option, New Host.... Select this option to bring up a host editor on a new host:
- Name is the name by which you want Mars to refer to the host; it could be the host name without the domain, or a descriptive name (e.g. "Web Server") completely unrelated to the host's actual DNS name.
- Address is the fully qualified DNS name or IP address of the host. Mars will perform a lookup of the given name before adding the host to the host/service tree, and will not allow you to continue unless the given name resolves to an address; this ensures you don't get false alarms about services being down because of a typo in the Address field.
Now that you've defined a host, you need to define a set of services to monitor on that host. Right-click on the host name to bring up the host context menu and select Add Service..., which will bring up a service editor on a new service on the selected host.
- Name is, as for a Host, simply a label by which Mars will display the service. Suggestions are the name of the service ("http"), the server software ("Tomcat"), or the user-visible application the service provides ("PR System").
- Type is the type of service - Mars uses this to know how to probe a service. Currently, the available types are http, ftp, smtp, imap, pop3, and ssh.
- Port is the TCP port (or UDP port, depending on the service type) on the host on which the service is running. Each time you select a new Type, this changes to the default port for the given service type.
- Timeout (n) sec. is the time, in seconds, Mars will wait for a service to respond before considering it timed out. The default is 3 seconds, but this may be far too long or far too short, depending on the service and your environment. If you notice a service that is up reporting back as timed out very often, consider increasing this value.
- Check each (n) sec. is minimum time Mars will delay between running probes of a service. Use longer delays here to decrease monitoring network traffic.
Repeat this process until all the hosts and services you wish to
monitor with Mars have been added to the host/service tree. At this
point, you'll probably want to save your configuration; do this by
clicking the save button
(
)
in the toolbar. This will bring up a dialog asking you for the name
of the file to save the configuration into; the configuration will
be written as an XML file, the format of which is
described below.
To begin monitoring services with Mars, click the start button
(
)
in the toolbar. Mars will begin monitoring the services you have
specified, display each service's status in the host/service
tree, and display any faults in the fault list:
Tip
To see a host's services in the host/service tree, double-click on the host's name or icon. To see detailed information for a service, click on that service to select it.Additionally, the history of each service's status will be displayed in the recent changes list.
You can only change the host/service tree while Mars is stopped.
To stop Mars from monitoring, click the stop button
(
)
in the toolbar. You'll notice when Mars is stopped, all current
faults disappear from the fault list, and the host/service tree reverts
to showing no status for each service. This provides a quick,
at-a-glance way to see if Mars is still running.
)
and open
(
)
toolbar buttons, which work pretty much as you'd expect.
Though Mars was designed to be quick and easy to set up, using the Swing user interface to configure many services on many hosts can get tedious, especially if each host has many similar services. In this case, creating a Mars configuration file directly can be useful.
The Mars congifuration file namespace is "http://www.altara.org/mars/xmlns/model/". The root element of a Mars config file is <mars:model>. This element contains a single <mars:hostlist> element. <mars:hostlist> contains a collection of <mars:host> elements, each with a name and address attribute.
Each <mars:host> element contains a collection of <mars:service> elements. <mars:service> has name, port, svctype, timeout, and period attributes. timeout and period are expressed in milliseconds.
<mars:service> may also contain <mars:parameter> (service parameter) and <mars:status> (service status) elements, though these elements are not yet used.
Mars itself is a good generator of example files; just create a simple configuration, then open up the resulting XML file in your favorite text editor.
Mars is designed along the lines of a straight MVC architecture; information about hosts and services lives in a Model, which is edited and displayed by the View (the Swing user interface), and updated by the asynchronously running Controller (the classes in the org.altara.mars.engine package). The controller is activated and deactivated by the View. The diagram below shows the general arrangement:
This list should suffice to get you started hacking away at Mars, by answering the frequent and essential question "where does feature x live?".
- org.altara.mars.MarsModel is the root of the host/service tree; it contains the host list, and distributed host/service tree change notifications to the user interface.
- org.altara.mars.Host represents a host.
- org.altara.mars.Service represents a service.
- org.altara.mars.Status represents the status of a service at a given point in time.
- org.altara.mars.ProbeFactory is an interface implemented by concrete factories that can create probes for a given service type; it also contains a registry of such factories.
- org.altara.mars.engine.Controller coordinates the activities of the engine. It distributes event notifications, and manages the queue of pending probes and probe worker threads.
- org.altara.mars.engine.Probe is the abstract superclass of all probes; classes which know how to speak a given protocol or set of protocols, and determine the status of a remote service.
- org.altara.mars.engine.ProbeWorker is the worker thread that runs Probes.
- org.altara.mars.engine.SimpleServiceProbe is currently the only concrete Probe class; it knows how to connect to a TCP port, send a string, and expect a string in return. This is sufficient for all the protocols Mars currently supports.
- The org.altara.mars.engine.*ProbeFactory classes set up SimpleServiceProbes to determine the status of the various services Mars understands.
- org.altara.mars.engine.ProbeEvent signals that a probe has been run on a specified service.
- org.altara.mars.engine.StatusChangeEvent signals that a service's status has changed.
- org.altara.mars.swingui.MarsView is the core of the Swing user interface. It sets up all the other UI components and connects them to the model and the controller. It is also currently the main entry point into Mars.
- org.altara.mars.swingui.FaultListModel and org.altara.mars.swingui.FaultListRenderer implement the fault list.
- org.altara.mars.swingui.ChangeListModel and org.altara.mars.swingui.ChangeListRenderer implement the change list on the history tab.
- org.altara.mars.swingui.DetailListModel implements the service detail view.
- org.altara.mars.swingui.ServiceTreeRenderer handles the rendering of the host/service tree.
- org.altara.mars.swingui.ServiceTreeContextMenuSupport implements the host/service tree's context-sensitive menus.
- org.altara.mars.swingui.Editor and org.altara.mars.swingui.EditorDialog provide support functions common to both the host and service editors.
- org.altara.mars.swingui.HostEditorPanel implements the host editor.
- org.altara.mars.swingui.ServiceEditorPanel implements the service editor.
- org.altara.mars.swingui.ServiceTypeComboBox implements the service type selector in the service editor.
- org.altara.mars.swingui.MarsAbstractRenderer provides look and feel support common to all renderers.
- org.altara.mars.swingui.ServiceTreeChangeAdapter translates change notifications from the model and controller into change notifications understandable by the host/service tree widget.
- org.altara.mars.swingui.ProbeThreadAdapter and org.altara.mars.swingui.StatusChangeThreadAdapter ensure that handling of events from the controller happens in the Swing event dispatch thread.
Mars 2 is a complete rewrite of Mars. The first and most noticeable change is that the user interface is completely different. The second is that the configuration file format is completely different. In addition, several Mars 1.x features have been removed, including:
- SPOTS. Mars can no longer talk to the SPOTS agent, which provides load average, memory usage, and filesystem usage information on Unix systems. SPOTS is inconsistent with a strictly services-oriented view of a host, though I may add some sort of agent support like SPOTS in future versions if enough of you really miss it. :)
- Notification of down services, via the GUI and email. These features will be supported by user-side plugins in the new modular Mars 2.1.
On the upside, Mars 2's much cleaner architecture should make debugging and maintenance much easier, and allow the development of advanced features such as the plugin framework planned for the next version.
Mars 2.0 should be seen as a work in progress, a release to get a new architecture out and tested, and to test the new user interface on an unsuspecting world. Mars 2.1 is a continuation of this work, and will (hopefully) include:
- A modular plugin framework to allow the development of new Mars features without changing the core program. These plugins will exist both on the user-side (e.g. notification, alternative user interfaces) and on the network-side (new probe packages). Mars plugins will be easy to install - presuming everything works as documented, the user will have only to drop a .jar file into a specified directory.
- New probes - the SimpleServiceProbe probe is essentially unchanged since Mars 1.x; it causes unnecessary log entries on probed machines, as it doesn't participate in full valid conversations with any service other than http. This new generic send-expect probe should allow the user configuration of new probes for text-based network services without recompiling, or even writing a network-side plugin.
- Fixes for most of the bugs that will inevitably be reported in Mars 2.0.0.