Dime (Distributed Monitoring Environment) is a set of daemons that perform network service checking and allow real-time failure alerts. There are three components on the dime architecture:

• Service Monitor: this daemon does the actual service checking, making connections to the specified TCP ports and testing for reachability of the monitored hosts. Any failures are reported to the observing Alert Centers (see below).
• Alert Center: this daemon is a concentrator for alert messages. It receives all alerts from the Service Monitors it is connected to, and resends them to the Alert Receivers (see below) which required notifications from the alerting host.
• Alert Receiver: this daemon is supposed to run on the Network Administrator's workstation. Upon startup, it registers itself on the configured Alert Centers, and then starts listening for incoming alerts. The alert messages are displayed on-screen, using libxosd2.

If the only notification method configured is ``email'' (see below), dime can be run on a Service Monitor-only setup.

The documentation on this website describes the current release of dime. To know about the new features that are not present on an official release yet, check the README file from CVS. A CHANGELOG is also available.

The first step is to create the ``dime'' user and group. Currently this step is needed for Alert Center and Service Monitor installations. Upon startup, these dime daemons chroot to dime's home directory and drop privileges to run as `dime'.

As there's no portable way to create UNIX users and groups, this step must be done manually. Below are the settings to be used:

User:  dime
Group: dime
Home:  /var/dime
Shell: /sbin/nologin

The install.rb script can be used to handle the installation of any of the dime components (or combinations of them, if you wish to install more than one component on the same machine):

# ruby install.rb [--prefix=path] <option(s)>

where path is by default /usr/local and an option is one of:

• ``receiver'' (to install an Alert Receiver)
• ``alertcenter'' (to install an Alert Center)
• ``monitor'' (to install a Service Monitor)

Before running dime, the chroot area must be prepared. This requires copying the libraries needed for name resolution into /var/dime/lib and the related configuration files to /var/dime/etc (usually /etc/hosts, /etc/resolv.conf, /etc/services and /etc/protocols).

Each element of the dime architecture is configured through its own YAML configuration file, and optionally via command-line flags. When a config file is said to live ``inside the chroot area'', it means that its real location on the filesystem is under the chroot directory. For example, the monitor.conf file's real path is /var/dime/etc/dime/monitor.conf, assuming that the chroot directory is /var/dime.

Alert Receiver Configuration

By default, the Alert Receiver will read its configurations from /etc/dime/receiver.conf. There are four configuration paramenters available for the Alert Receivers:

• Name: A string that identifies the Alert Receiver.
• URI: A string in the format XXXX:NNNN where XXXX is the IP address or the FQDN of the Alert Receiver and NNNN is the port where the Alert Centers will connect to send alert messages. If a port is not specified, a default of 8452 will be used.
• AlertCenters: A list of Alert Center URIs, specifying which hosts will act as Alert Centers for the Alert Receiver.
• Hosts: A list of IP addresses or host names specifying which hosts the Alert Receiver wants to receive alerts from.

Example configuration file:

Name: Receiver1
URI: 10.0.0.10:8452
AlertCenters: [ 10.0.0.1:8451 ]
Hosts: [ 10.10.0.1, 10.10.0.2, 10.10.0.3 ]

Alert Center Configuration

The default Alert Center configuration file is /etc/dime/alertcenter.conf, inside the chroot area. Is consists of three parameters:

• Name: A string that identifies the Alert Center.
• URI: A string in the same format as the Alert Receiver's URI (see above). The default port for the Alert Center is 8451.
• ServiceMonitors: A list of URIs specifying the Service Monitors being observed by the Alert Center.

Example configuration file:

Name: AlertCenter1
URI: 10.0.0.1:8451
ServiceMonitors: [ 10.10.0.100, 10.10.0.200 ]

Service Monitor Configuration

The Service Monitor reads its configuration from three files, all living in /etc/dime inside the chroot area: monitor.conf, hosts.conf and mail.conf (the latter is optional).

The monitor.conf file has four configurable parameters:

• Name: A string that identifies the Service Monitor.
• URI: A string in the same format as the Alert Receiver's URI (see above). The default port for the Service Monitor is 8450.
• Period: The period of service checking, in seconds (the default value is 300, for a five-minute period).
• Notify: A string or array specifying the notification method(s) to be used by dime. It can be set to "onscreen", "email" or both.

Example monitor.conf file:

Name: Monitor1
URI: 10.10.0.100:8450
Period: 300
Notify: [ onscreen, email ]

The hosts.conf specifies the hosts that will be monitored by the Service Monitor. It consists of one YAML document for each host. The format host entries is better explained via the example configuration file below, which includes the configuration for two hosts:

Name: Host1
Services:
  10.0.0.1:
    -
      Port: http
      Protocol: tcp
    -
      Port: ftp
      Protocol: tcp

  192.168.0.1:
    -
      Port: ssh
      Protocol: tcp

---

Name: Host2
  10.0.0.2:
    -
      Port: mysql
      Protocol: tcp
    -
      Port: ssh
      Protocol: tcp

The mail.conf file is optional and is only used if email is being used as a notification method. It has seven parameters:

• Server: The IP address or name of the SMTP server.
• Auth: The SMTP authentication method being used. It can be one of the following strings: "plain", "login" or "cram_md5". If you are not using SMTP authentication, this parameter can be ommited, as well as the ``Username'' and ``Password'' parameters described below.
• Domain: The domain name of the email address.
• Username: The username of the email sender.
• Password: The password of the email sender.
• From: The email address of the email sender.
• To: A list of email addresses which will receive the notifications.
• Domain: The domain name of the email address.

Example mail.conf configuration file:

Server: smtp.mydomain.tld
Domain: mydomain.tld
Auth: plain
Username: dime
Password: mysecretpass

From: dime@mydomain.tld
To: [ admin@mydomain.tld, boss@mydomain.tld ]

ACL Configuration File

Each of the dime elements will read an ACL configuration file which specifies which hosts are allowed to establish connections to the listening services. The default location for this file is /etc/dime/acl.conf (inside the chroot area for the Service Monitor and the Alert Center).

The ACL configuration file accepts one rule per line. Rules are in the format below:

action address

where action is one of deny or allow, and address is the address of the host to which the action will be taken, or the keyword all.

Example ACL configuration file:

deny all
allow 10.10.0.1  # this is a comment
allow 10.10.0.2

Running dime

On the next subsections, follows a brief description on how to run each of the dime components. The scripts mentioned below live by default on the /usr/local/sbin directory.

Service Monitor

The Service Monitor is run with the dime_monitor script. It must be started as root but will drop its privileges to the ``dime'' quickly. The following command line options are available:

    -H, --hosts-file <file>    Use an alternative hosts file
    -a, --acl-file <file>      Use an alternative ACL file
    -d, --debug                Enable debug messages and don't daemonize
    -e, --email-file <file>    Use an alternative email configuration file
    -f, --config-file <file>   Use an alternative configuration file
    -h, --help                 Show this message
    -p, --period <seconds>     Service checking period

Aler Center

The Alert Center is run with the dime_alertcenter script. Similarly to the Service Monitor, it must be started as root and will drop its privileges. Below is the list of command line options available:

    -a, --acl-file <file>      Use an alternative ACL file
    -d, --debug                Enable debug messages and don't daemonize
    -f, --config-file <file>   Use an alternative configuration file
    -h, --help                 Show this message

Aler Receiver

The Alert Receiver is run with the dime_receiver script. This script can be run as a normal user, as long as it belongs to the ``dime'' group. The command line options available are:

    -a, --acl-file <file>      Use an alternative ACL file
    -d, --debug                Enable debug messages and don't daemonize
    -f, --config-file <file>   Use an alternative configuration file
    -h, --help                 Show this message

All dime daemons are written in pure Ruby, and make use of extensions provided in the Ruby distribution like DRb and YAML. There are two exceptions though: libxosd2-ruby, which is used on the Alert Receiver code to display the on-screen alert notifications, and starting on version 0.2, DRbFire, so that dime can be used on firewalled setups.

The Service Monitor exposes a DRb-observable object, that is observed by the connected Alert Centers. The service checks only happen when there is at least on connected Alert Center.

The Alert Center works as a forking server. The child observes each of the configured Service Monitors (one ruby thread per Service Monitor), while the parent listens for incoming Alert Agents.

The Alert Receiver registers itself on the configured Alert Centers and then listens for incoming alert notifications from them.

The Alert Center and Service Monitor daemons run as the unprivileged ``dime'' user, and use chroot to restrict their access to the rest of the system.

Dime was developed and tested on Ruby 1.8.1. There is no guarantee that it will run with older versions.

The external dependencies for dime are:

• DRbFire
• libxosd2-ruby

Only the machines running Alert Receivers need libxosd2-ruby, as it is used to display the on-screen alert messages. The use of this library requires ruby to be compiled with the ``--enable-pthread'' option.

People usually like screenshots, so here is one. Below is a picture of dime running in debug mode, with all three modules running on the same machine.

Before downloading dime, please be sure you agree with its license. Dime is distributed under a simple unrestrictive license, reproduced below:

Copyright (c) 2004 Andre Nathan <andre@digirati.com.br>

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Here you can download the current dime release: dime-0.3.tar.gz.

You can also browse dime's source code with viewcvs or download a snapshot tarball from the current code.