MARS

the Monitoring Application for Resources and Servers

User's Guide, Version 1.4.1

February 27, 2001

(minor revisions to User's Guide, Version 1.4, June 7, 1999)

• What's New in 1.4.1: why a new version with no changes?
• What's New in 1.4: a guide for upgraders.
• Installing MARS
  • UNIX installation
  • Microsoft installation
• Installing SPOTS
• Introduction to MARS
  • Starting MARS
  • Initial Configuration
• MARS Reference
  • Host Display
  • Configuration
  • Warnings
• Hacking MARS

• 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.

• a Java runtime environment, version 1.1.7 or later.
  MARS has been tested with Blackdown JDK 1.1.7 for Linux, Sun JDK 1.2 for Windows, and Sun JDK 1.3 for Linux.
• 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.

1. Download the MARS distribution in .tar.gz form.
   The most current version of MARS is always available via anonymous FTP at ftp.altara.org.
2. 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

3. Set the symbolic link for runmars
   The Java 1.2 interpreter needs to be invoked differently from the Java 1.1.7 interpreter. If you're running Java 1.1, set the runmars symbolic link to point to the runmars-1.1 script. If you're running Java 1.2 or 1.3, set the runmars symbolic link to point to the runmars-1.2 script. The following command should work on most Unices:

   ln -sf runmars-version runmars

1. Download the MARS distribution in .zip form.
   The most current version of MARS is always available via anonymous FTP at ftp.altara.org.
2. Unpack the MARS distribution where you want to install it.
   You'll need PKZIP, WinZip, or some other utility capable of opening .zip files.

• 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.

1. 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.
2. 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

3. 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

4. Restart inetd
   Consult your UNIX documentation for directions on restarting inetd. On RedHat Linux systems, the following command will work:

   killall -HUP inetd

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.

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.

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.

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.

Host Display

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
  1. The host is very busy and couldn't respond before MARS timed out,
  2. The network is slow, and the host's response was not received, or,
  3. 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.

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
  • Configure: This option brings up the configuration window.
  • Quit: This option exits MARS.
• 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.

Configuration Window

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.

Warnings

MARS' three warnings

• 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

what's an fqdn?

• build builds all .class files in the source heirarchy. This is the Makefile's default target.
• jar builds all .class files in the source heirarchy, then makes a .jar file containing the system. This MARS.jar file is all that is required to run the system.
• dist builds all .class files in the source heirarchy, then makes a .jar file containing the system, then packages that .jar file along with the SPOTS daemon, a stand-alone SPOTS client, the MARS user's guide, the runmars scripts, and the GNU GPL. This target is used to build the distribution package available for user downloads.
• clean cleans up everything but source files.