MARS
the Monitoring Application for Resources and Servers
User's Guide, Version 1.4
June 7, 1999
Several things have changed in MARS 1.4.
- SPOTS has changed a lot since version 1.3. If you're upgrading
from a version of MARS older than MARS 1.4pre2, you'll need to install
the new version of SPOTS on all the machines you're monitoring. SPOTS changes
include:
- Memory reporting on Linux, Solaris, and Digital UNIX.
- Per-filesystem disk space reporting.
- More operating systems: SPOTS now has built-in support for HP/UX,
AIX and Digital UNIX in addition to Linux, Solaris, and IRIX.
- Mail notification: MARS can now notify you of problems via e-mail
or e-mail based paging systems. See the
Notification Menu in the MARS Reference for more information.
- Detailed service information: MARS can now give you detailed
information about the services it probes by displaying the last response
from the service. Just click on the service's cell in the host display.
Detailed per-filesystem information is also available by clicking on the
free disk space cell in the host display.
- New services: MARS now speaks IMAP and Secure Shell.
Before installing MARS, you should ensure that you have the following installed
on your system:
- a Java runtime environment, version 1.1.7 or later.
MARS is tested with Blackdown JDK 1.1.7 for Linux and Sun JDK 1.2 for Windows.
We have not tested MARS with any Microsoft Java implementation.
- Swing 1.1 or later.
Java 1.2 and later come with Swing, so you only have to install Swing if you're
using JDK 1.1.7.
for UNIX systems
To install MARS on a UNIX system, follow these steps:
- Download the MARS distribution in .tar.gz form.
The most current version of MARS is always available via anonymous FTP at
ftp.altara.org.
- Unpack the MARS distribution where you want to install it.
MARS will run in any directory, and installing it as root is unnecessary (and
not recommended, as you should not need to run MARS with root permissions).
We recommend unpacking MARS in your home directory. To do this using GNU
tar (the version of tar available on most Linux
systems), type the following commands:
mv mars-current.tar.gz ~
cd ~
tar xvzf mars-current.tar.gz
To do this using a version of tar that cannot automatically
uncompress archives, use the following commands:
mv mars-current.tar.gz ~
cd ~
gunzip mars-current.tar.gz
tar xvzf mars-current.tar
- Set the symbolic link for runmars (Java 1.2 systems only)
The Java 1.2 interpreter needs to be invoked differently from the Java
1.1.7 interpreter. If you're running Java 1.2, set the runmars
symbolic link to point to the runmars-1.2 script. The following
command should work on most Unices:
ln -sf runmars-1.2 runmars
You don't need to do this if you're running Java 1.1.7 - MARS ships with
runmars-1.1 as its default start script.
MARS is now ready to run!
for Microsoft systems
To install MARS on a Microsoft system (Windows 9x, Windows NT),
follow these steps:
- Download the MARS distribution in .zip form.
The most current version of MARS is always available via anonymous FTP at
ftp.altara.org.
- Unpack the MARS distribution where you want to install it.
You'll need PKZIP, WinZip, or some other utility capable of opening .zip files.
MARS is now ready to run.
SPOTS (for "Something Placed on That System", in.spotsd in the
MARS distribution directory) needs to be installed on each machine for which
you want extended information (free disk space, memory, and load average).
SPOTS currently has built-in support for Linux, Solaris, IRIX, HP/UX,
Digital UNIX, and AIX variants of UNIX. Before installing SPOTS on a system
to be monitored, ensure that the following are installed on the machine:
- Perl, version 5 or later.
Perl is free software, and can be obtained from
perl.com
- The
inetd superserver.
SPOTS will work with tcpserver or other inetd
replacements, but we have no experience with these systems and therefore
cannot write directions for them.
df and uptime commands.
Most Unices should have these. Linux additionally requires the
free command, and Solaris and Digital UNIX require
top to be installed in /usr/local/bin in order
to report on memory usage.
To install SPOTS on a machine meeting these requirements, follow these steps:
- Copy
in.spotsd to a directory on the server system.
We recommend the system path /usr/local/sbin. The rest of this installation
example will assume this is the SPOTS installation location.
- Make sure
in.spotsd has the proper permissions
in.spotsd should be world readable and executable. To ensure this,
type:
chmod 555 /usr/local/sbin/in.spotsd
- Add the following line to the server system's
/etc/inetd.conf file:
24210 stream tcp nowait nobody /usr/local/sbin/in.spotsd in.spotsd
- Restart
inetd
Consult your UNIX documentation for directions on restarting
inetd. On RedHat Linux systems, the following command will work:
killall -HUP inetd
SPOTS is now configured to give disk space and load average information to
your MARS client.
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
probing the hosts it knows about. After this introduction, you should have
a pretty good feel for how MARS works.
Starting MARS
On UNIX systems, change to the MARS installation directory and type
./runmars to start MARS.
On Microsoft systems, double-click the MARS.jar icon in the MARS installation
directory to start MARS.
Simple, isn't it?
Initial Configuration
The first time you start MARS, the host display will
contain no hosts. In order to add hosts to the system, select
Configure from the File menu.
This will bring up an empty configuration window.
To add a host to the configuration, select Add Host from the
Host menu. This will bring up a dialog box
asking you for the fully-qualified domain name
of the host to add. Enter
a host name; in this example, we'll use discworld.altara.org.
Click the OK button or press return after you have entered the host
name. This will bring up another dialog box asking you for the host's name
as it should appear in the host table. This is how the host will be displayed
in the host display and in the configuration window. Notice that
the default name is the first part of the host's fully qualified domain name;
this is usually what you want, so you can generally click OK again.
The dialog box will disappear, and the host name will now appear in the
configuration window with a row of seven checkboxes, one for each service MARS
can probe, and one for SPOTS. Check or uncheck these boxes depending on whether
the corresponding service is enabled on the system. For the
discworld example, you can check all the boxes.
NOTE: You may have to click a checkbox twice
to get it to check or uncheck. We haven't figured out what causes this; we
believe it's a bug in Swing 1.1.
You can go ahead and repeat the add host procedure for any other hosts you
want to monitor.
When you're done, close the configuration window and save your changes by selecting Save from the configuration window's
File menu. Click OK in the
confirmation dialog box that comes up. The configuration window will disappear,
and the new host(s) will be displayed in the host display.
The status bar in the main window will change momentarily to show you what
MARS is doing, and when MARS has finished probing the host(s) you specified,
it will display the status of services and SPOTS information for those hosts.
To quit MARS, you can either click the host display's close box or select
Quit from the File menu.
MARS consists of two windows, a host display and a configuration window. All
of MARS' features can be accessed via these windows.
The Host Display
The host display is the "core" of the MARS user interface. It consists of a
menu bar, a table displaying the status of all the hosts MARS is probing, and
a status bar along the bottom of the window.
Along the top of the table are the services MARS can probe, and down the left
is a list of hosts MARS has been configured to monitor. The status cells can
have one of four possible values:
- ok (green):
The service is functioning properly on the host.
- t/o (yellow):
The most recent probe on the host timed out or the host did not respond
correctly to the probe. This usually happens when
- The host is very busy and couldn't respond before MARS timed out,
- The network is slow, and the host's response was not received, or,
- The service is improperly configured.
- down (red):
The service is not running on the host.
- blank (grey):
MARS is not monitoring the service, because it has been configured not to.
The SPOTS cells will either display the load average and percentage of disk
space free, display "down" (if SPOTS could not be contacted), or be grayed out
(if SPOTS is not enabled on the host).
You can click on any service status cell to get a detailed view of the last
response received from that service. This can help you to determine which if a
"t/o" status is really a timeout, or a service configuration error. You can
also click on a host's disk space cell to get a detailed view of free space
per filesystem on the host.
Detailed Service and Filesystem Information
The status bar along the bottom of the host display tells you what MARS is
doing. Since MARS is multi-threaded, and can probe multiple services at once,
the status bar will only show the most recent action MARS started.
The following messages can be displayed in the status bar:
- MARS is starting: MARS has started up, but has not yet started
probing hosts. In reality, this is only seen when MARS is first started up
and no hosts have been added to the system yet.
- MARS is stopped: MARS is not probing any services. This appears
when you choose Stop from the
Control menu.
- host: checking service: MARS is currently probing the
specified service on the specified host.
- host: querying SPOTS: MARS is currently getting information
from SPOTS on the specified host.
- host: waiting: MARS is currently waiting to begin probing
again. By default, MARS waits 30 seconds between probing hosts.
There are two menus in the host display, File and Control.
- File Menu
- Control Menu
- Start: This option starts MARS probing again after Stop
has been selected. It is greyed out when MARS is already running.
- Stop: This option temporarily stops MARS probing. It is useful
if you wish to keep MARS from probing during a period of time, but still
want to keep the most recent information from each host available.
The Configuration Window
The configuration window allows access to every configurable aspect of MARS.
It consists of a menu bar and a host/service table.
Along the top of the table are the services MARS can probe for each host,
and down the left is a list of hosts MARS has been configured to monitor.
You can enable and disable probing of services on specific hosts by checking
and unchecking the boxes in the center of the table. Enable and disable
display of all SPOTS information by checking and unchecking the SPOTS box for
each host.
The menus allow you to modify the host table itself, and to configure other
aspects of MARS' behavior. There are three menus in the configuration window,
File, Host, Adjust, and Notification.
- File Menu
- Save: This option displays a confirmation box asking you whether
you wish to close the configuration window and save your changes to the
MARS configuration. Click Yes to close the configuration window
and save your changed. Click No to continue working in the
configuration window.
- Cancel: This option displays a confirmation box asking you
whether you wish to close the configuration window and cancel all your
changes to the MARS configuration since the window was opened. Click
Yes to close the configuration window and discard your changed.
Click No to continue working in the configuration window.
- Host Menu
- Add Host: This option will present you first with a dialog box
asking you the fully-qualified domain name of
the host to add to the system, then with a dialog box asking you how
the host's name should be displayed in MARS. A new entry for that host is
then added to the host/service table in the configuration menu.
Note that the answer to the second dialog box does not necessarily have to
be a valid host name; you can have a host appear as anything you want in
the host display. For example, if you're checking a mail server named
"quuxbazfoo.foo.bar.com" and you'd rather see "Mail Server" displayed in
the host table, go ahead.
- Delete Host: To delete a host from MARS, select that host in
the host-service table by clicking on its name, then select this option.
A dialog box will be displayed to confirm deletion of the selected host;
click Yes to delete the host or No to keep the host.
This option has no effect if no host is selected.
- Set Visible Name: To change the name a host is displayed as,
select it in the table and choose this option.Change the name in the
resulting dialog box and click OK.
This option has no effect if no host is selected.
- Set FQDN: To change a host's fully-qualified domain name (for
example, if you mistyped it when you added it to the system), select it
in the table and choose this option. Change the name in the
resulting dialog box and click OK.
This option has no effect if no host is selected.
- Move Up List: This makes the selected host appear one entry
higher in the host table.
This option has no effect if no host is selected.
- Move Down List: This makes the selected host appear one entry
lower in the host table.
This option has no effect if no host is selected.
- Adjust Menu
- Update Interval: This option allows you to control how long
MARS waits between each time it probes hosts. It presents a dialog box
with the update interval in milliseconds. Change the value and click
OK to adjust the update interval. The default value is 30000
(30 seconds); this allows you to get updates from each host twice a minute.
Increase this interval to make MARS less demanding on your network;
decrease it to get more continuous information.
- Timeout: This option allows you to control how long to wait for
a correct response to a probe before flagging a service "t/o" (timed out).
It presents a dialog box with the timeout delay in milliseconds. Change
the value and click OK to adjust the timeout delay. The default
value is 3000 (3 seconds); this seems about right for a LAN under moderate
load. Increase the delay to keep MARS from giving false alarms on slow
network links (ISDN, 56K and slower). Decreasing the delay will make MARS
run faster on faster networks.
- Max Load Threshold: This option allows you to control the
warning threshold for load average as returned by SPOTS.
It presents a dialog box with the maximum load average. Change
the value and click OK to adjust the load threshold.
The default value is 2.0.
- Min Disk Threshold: This option allows you to control the
warning threshold for free disk space as returned by SPOTS. It presents
a dialog box with the minimum percentage of disk space free. Change the
value and click OK to adjust the disk space threshold. The
default value is 10. NOTE: MARS will notify you when any
filesystem on the watched host falls below the specified limit.
- Notification Menu
- Set up mail notification...: This option allows you to have
MARS notify you of any problems it notices via e-mail. It will present
you first with a dialog box asking you the e-mail address to send
notification to, then with a dialog box asking the name of an SMTP
server to use to send the notification. NOTE 1: It is not
generally a good idea to use an SMTP server on a box you're monitoring
- if that machine happens to go down, notification will not work.
NOTE 2: If you're running MARS on a reasonably decent UNIX box,
you're probably already running SMTP on your own machine. You can just
enter your own machine's name here. MARS will then notify you via mail
every time it displays an alert until you select...
- Disable mail notification: This option disables previously
set up mail notification.
MARS' three warnings
MARS can display three types of warnings to let you know there is a problem.
- Service Down: This warning is displayed when a service's status
changes to "down". This indicates a serious problem with the host, and
should be investigated.
- Load Average: This warning is displayed when a host's load average
exceeds the maximum load threshold. This indicates a host is under heavy load;
it may be indicative of a cracked system if the system usually has no or very
light load. It may also be indicative of nothing if the system is heavily used.
If you get this warning a lot and no problems arise, you may want to increase
the maximum load threshold.
- Disk Space: This warning is displayed when the percentage of
free disk space on one or more of a host's filesystems falls below the
minimum free disk space threshold. Delete some files or buy a new disk.
:)
If you have configured mail notification,
MARS will send an e-mail message to the address you specified each time an
alert is displayed. MARS encodes relevant information about the error in
the alert message's subject; this makes the feature useful for e-mail based
paging systems. If MARS is configured to send mail notification but cannot
for some reason, it displays the following alert:
Mail notification failure warning
FQDN (Fully-Qualified Domain Name) refers to the entire domain name of a
machine. If a machine's host name is foo, and its domain is
bar.com, the FQDN is foo.bar.com. MARS needs FQDNs
to find machines; a node name or Windows (NetBIOS) name will not do.
We're always looking for more people to work on MARS, and more code. There's
javadoc for the most recent MARS available online at
http://www.altara.org/mars/javadoc. All the source code is distributed with
the system in the src/org/altara/mars directory. There are also
two utilities in the src directory:
buildmars: Execute this script from the src
directory to build a clean set of classes for MARS.
packagemars: Execute this script from the src
directory to build a clean set of classes for MARS, and package them in the
MARS.jar file in the root installation directory.
There is a mailing list for MARS development:
mars-devel@altara.org. You can
request a subscription
here.
This User's Guide is ©1999 Brian H. Trammell. Unlimited redistribution is
permitted without express consent, and encouraged. If you hack MARS and wish
for us to distribute your changes, it would be most helpful to us if you hacked
the relevant bits of this manual, too.