Simple System Thermometer (systher)

Karel Kubat, e-tunity

e-tunity

2006

Table of Contents

1: Introduction

1.1: Prerequisites

1.2: Legalese

2: Obtaining and Installing Systher

3: Running Systher

3.1: Stand-Alone Mode

3.2: Daemon Mode

3.3: CGI-BIN Mode

4: Technical Information

4.1: Availability of Unix tools

4.2: Coping with Unix Flavors

---

1: Introduction

Systher is a small Perl tool that collects system information and presents it as an XML document. The information is collected using standard Unix tools, such as netstat, uptime and lsof.

Systher can be used in many ways:

• When invoked from the command line, Systher simply shows the state of the system where it was invoked.

• Systher can be run as a stand-alone daemon, listening to an arbitrary TCP port, so that callers can remotely obtain the system information.

• Systher can be run as a cgi-bin script, so that browsers can connect to it.

In order to make the obtained information readable for humans, Systher is equipped with an XSLT processing stylesheet to convert the XML information into HTML. That way, the information can be made visible in a browser.

1.1: Prerequisites

In order to succesfully use Systher, you'll need:

• Perl 5.8 (5.6 might work too, but is untested; 5.0 isn't sufficient);

• A Unix box in one of the flavors: Linux, Darwin, SunOS. Other Unices may or may not work out of the box; though Systher can easily be configured to work with more Unix flavors (see section 4.2);

• Standard utilities on the Unix box, such as df, netstat, top, lsof, uptime, hostname, uname. Systher uses these utilities to collect system information;

• On the client side: a web browser to view the status of your system, or any utility that can parse XML and extract information that is then further processed.

1.2: Legalese

Systher is distributed under the GNU "copyleft" licence, as-is, without assumption of usability, and without guarantee. Which basically means that you can use Systher without restrictions, and you may redistribute it in any form you want, provided that you make sure that the source of Systher remains available to the public and and provided that you make sure that this copyright notice remains intact.

You're even free to modify Systher in any way you like. Though I'd very much like to see your modifications (especially if they are bug fixes!); I'll then incorporate your changes in the next release, stating full credits.

2: Obtaining and Installing Systher

Systher can be obtained from e-tunity's site http://public.e-tunity.com. The distribution comes as an archive systher-X.YY.tar.gz, where X.YY is a version number like 1.00. Alternatively you may find systher-latest.tar.gz.

To install Systher, follow these steps:

• Change-dir to a suitable directory. In the remainder of the document we'll use /Users/e/src/e in the description; please supply a path that's appropriate for you.

• Unpack the archive. It spills its contents into a subdirectory systher/.

3: Running Systher

There are basically three methods of running Systher:

3.1: Stand-Alone Mode

The first method is stand-alone mode. Change-dir to the systher/bin (relative to the path where you installed Systher) and type ./systher.

If all goes well, you should see an XML document onscreen that shows the system state. If not, stop right here, fix the error condition, or contact me (e.g. as mailto:karel@e-tunity.com).

3.2: Daemon Mode

The daemon mode can be run either as a plain XML daemon, which returns just an XML document representing the system status, or as an HTTP daemon that responds to the browser. The HTTP daemon mode can optionally include a reference to an XSLT sheet to render XML as human-readable HTML.

• To run Systher in plain XML daemon mode, try the following command line:

  systher -d 6666

  This starts up Systher to bind to port 6666 and to respond to requests by sending an XML document that represents the system status. To test the daemon, try from the commandline:

  telnet myserver 6666

  The XML respons should appear once Telnet connects to the daemon.

• To run Systher as an HTTP daemon, try:

  systher -h -d 6666

  The flag -h makes sure that responses are prefixed with appropriate HTTP headers, and that the daemon expects an HTTP GET header. To test this, point your browser at http://myserver:6666/. The XML document should appear in your browser.

• To run Systher as an HTTP daemon that renders XML as viewable HTML, try:

  systher -h -d 6666 -x systher-xml2html.xslt

  This starts the HTTP daemon, and inserts a reference to systher-xml2html.xslt in the generated XML document. To test this, point your browser at http://myserver:6666/. If your browser supports client-side XML transformations, then you'll see the system state as nicely formatted HTML.

When running Systher as daemon, only one request is served at a time. The daemon is designed in that way; the reason being that querying the state shouldn't add to the load of a system. The daemon mode is a very lightweight way of enabling remote system state querying: not even a webserver is needed.

3.3: CGI-BIN Mode

To run Systher in CGI-BIN mode under supervision of a webserver, follow these steps:

• Edit your webserver's configuration file and add the following lines (we're assuming an Apache configuration here):

  # Definition of a virtual host on port 6666 (for Systher)
  Listen 6666
  <VirtualHost            *:6666>
  
      # The document root, closes all. Opened up further below on a
      # per-directory basis.
      DocumentRoot        /Users/e/src/e/systher
      <Location           />
          Order           deny,allow
          Deny from       all
      </Location>
  
      # The CGI-BIN directory.
      ScriptAlias         /systher /Users/e/src/e/systher/bin
      <Location           /systher>
          Order           allow,deny
          Allow from      all
      </Location>
  
      # The XSLT directory.
      Alias               /systherxslt /Users/e/src/e/systher/xslt
      <Location           /systherxslt>
          Order           allow,deny
          Allow from      all
      </Location>
  
      # This virtual server logs to specific logfiles.
      CustomLog           /tmp/systher.custom.log common
      ErrorLog            /tmp/systher.error.log
  
      # Incase someone accesses http://thishost:6666/, they will be
      # forwarded to http://thishost:6666/systher/systher.cgi.
      RewriteEngine       on
      RewriteRule         ^/$ /systher/systher.cgi [R,L]
  
  </VirtualHost>
  

• Modify this example to your likings. E.g., you might not want to use port 6666, or your installation directory might not be /Users/e/src/e, or you might not want to use separate logging to files under /tmp. Please view bin/systher.cgi if you want to see what flags are supplied to Systher by this wrapper.

• Restart the webserver.

Next, point your browser at http://myserver:6666/ to see the result. Note also that the XML output is now rendered as HTML. That's caused by the fact that sister.cgi, the called script, calls systher with a flag -x and an href to the XSLT sheet xslt/systher-xml2html.xslt.

4: Technical Information

This section describes some concepts of the technical implementation of Systher

4.1: Availability of Unix tools

In order to collect system statistics, Systher needs to run standard Unix tools such as df, netstat. These utilities are searched for in the following order:

• In the current directory (where Systher is started from);
• In the current directory, but postfixed with the uname. E.g., to start df, Systher will try df.SunOS on a Sun, df.HPUX on a HP UX, and so on;
• In the base directory of the Systher script;
• In the base directory of the Systher script, but postfixed with the uname;
• In the standard paths /bin, /usr/bin and so on; this is configured at the top of the systher script.

When no utility can be found, a fatal error occurs. This will show up as a <failure> element in the generated XML.

4.2: Coping with Unix Flavors

The above mentioned Unix utilities unfortunately report their output in different formats given different Unix flavors. Here's an example.

TCP network connections are reported in the following ways:

• On Linux, the command is netstat -nt. The fields that are shown are protocol, receive-queue, send-queue, local IP address, remote IP address and state.

• On Darwin (Mac OSX), the command is netstat -np tcp. The order of the fields is the same as for Linux.

• On SunOS, the command is netstat -nP tcp. The order of the fields is the local and remote IP addresses, the send-window, the send-queue, the receive-window, the receive-queue, and the state.

In order to cope with such differences, the script systher has a map %helpermap (defined at the top of the script). This map defines per Unix flavor (actually: what uname reports): the command to run, the order of fields, if applicable: the number of initial lines to skip in the helper program output, and if applicable: the lines to take from the helper program output (other lines are then ignored). That way, systher can be easily configured for other Unix flavors than the ones already known in this version.

If you have such tweaks, please don't hesitate to contact me with the specific configuration. That way, Systher becomes more widely usable.