sysmon-0.91.7 Configuration Documentation

Sysmon includes a versatile configuration file format.

Items covered by this document.

1. Overview
2. Global Configuration Options
3. Object Configuration Options
4. Example Configuration of each test-type
5. Example Configuration of each Object option
6. Replacement Options that can be used

1. Overview

Sysmon now allows a significant number of configuration options, and the easier addition of new features.  This also allows us to configure sysmon to detect parallel paths and outages on them properly, including ring topology as well as a number of other things.  Take the following example:

With this network topology, we can monitor each link properly.  Versions prior to 0.90 would either report multiple outages, or not have the ability to report the outages properly.

The above network topology can be represented in the following network configuration file:

 1: root=sysmon-host;
 2: 
 3: object sysmon-host {
 4:     ip "sysmon-host";
 5:     type ping;
 6:     desc "ping-sysmon-host";
 7:     dep "router1";
 8: };
 9:
10: object router1 {
11:     ip "router1.example.com";
12:     type ping;
13:     desc "router1";
14: };
15: 
16: object router2 {
17:     ip "router2.example.com";
18:     type ping;
19:     desc "router2";
20: };
21: 
22: object router3 {
23:     ip "router3.example.com";
24:     type ping;
25:     desc "router3";
26: };
27: 
28: object router1-2-link {
29:     ip "1.2.3.4";
30:     type ping;
31:     desc "link-rtr1-to-rtr2";
32:     dep "router1";
33:     dep "router2";
34: };
35: 
36: object router2-3 {
37:     ip "2.3.4.5";
38:     type ping;
39:     desc "link-rtr2-to-rtr3";
40:     dep "router2";
41:     dep "router3";
42: };
43: 
44: object rtr1-3-link {
45:     ip "3.4.5.6";
46:     type ping;
47:     desc "rtr1-3-link";
48:     dep "router1";
49:     dep "router3" 
50: };

Now, here, we declare an object, and then configure the locally dependent options. All checks require a description, and a check type, including the ip declaration. You can specify either an ip address or a hostname in this field.

When you create an object, you specify a symbolic name. The name router1 could just as easily say "swiss-cheese", it's just used internally to look up the dependencies and create the adjancies table.

2. Global Configuration Options

config showupalso;

Make sysmon show the hosts checked as up as well as the ones that are checked as down in the configuration file

config nologconnects;

Do not log connect information from the client. By default sysmond listens on port 1345 for client connections from the curses, python, java, and other clients).

config noheartbeat;

Sysmon normally sends a "heartbeat" packet when started to our registration server. This includes the hostname, version of sysmon, and the operating system you are running on. Sysmon only sends this once upon startup. Failure to send this will not affect system performance or operation.

config nosubject;

Sysmon normally sends a Subject: line in the message to the contact specified within an object. Some paging systems have problems when a subject is specified, or it does not get passed along properly when you have limited characters to be received. Specifying this option causes sysmon to omit the subject: line.

config statusfile [ text | html ] "/path/to/file";

Sysmon has the ability to specify a file to dump current status to. File type can be either html or text. This file is updated whenever there is a state change on an object.

config logging syslog [ facility | none ];

Sysmon logs various information via syslog. You can specify what service to log to, or specify "none" for no logging).

config queuetime [ integer ]; (Default: 60)

This allows you to specify how often an object is queued to be checked. This defaults to 60 seconds after the last test is over.

config dnsexpire [ integer ]; (Default: 900)

This allows you to specify how often sysmon's internal dns cache is expired. Default is 15 minutes. Time is specified in seconds.

config dnslog [ integer ]; (Defualt: 600)

This allows you to specify how often sysmon logs dnscache related data. Default is 10 minutes. Time is specified in seconds.

config pageinterval [ integer ];

This option allows you to specifiy that sysmon send a reminder e-mail/page to you. Default is to not send reminders. Time is specified in minutes.

config maxqueued [ integer ]; (Defualt: 100)

This specifies how many tests may be performed at one time. Default is 100. Because of file descriptor limits that your operating system may have, and the file descriptor intensity of sysmon, you may need to increase or decrease this depending on the size of your configuration file.

config numfailures [ integer ]; (Default: 4)

This specifies how many times a host should be checked as "down" before the contact is e-mailed/paged. Default is 4.

config pmesg " string ";

This specifies the format of the text sent in the body of the message. See replacement options for ways to display information about the test. Default is specified in config.h (grep PMESG src/config.h).

config [ from | sender ] " username@example.com";

Allows you to reset who the page/e-mail comes from instead of root@localhost.

config subject "string";

This specifies the format of the text sent in the subject of the message. See replacement options for ways to display information about the test. Default is specified in config.h grep SUBJECT src/config.h).

config upcolor "string";

This allows you to specify a color as used in HTML tags to be used for hosts that are currently UP as displayed in the configured html file.

config downcolor "stringi";

See config upcolor.

config recentcolor "string";

Hosts that are down, but have not reached the count of numfailures are this color.  See config upcolor.

config replyto "user@example.com";

Allows insertion of reply-to: header in e-mail/pages sent.

config errorsto "user@example.com";

Allows insertion of errors-to: header in e-mail/pages sent.

config header "text";

Allows insertion of header.

config pidfile "path";

Allows the PID file to be written somewhere more sensible than the default of /etc/sysmon.pid; /etc/ is readonly on some systems for security reasons.

config html refresh seconds;

Allows modification of the HTML status page refresh time (default 60 seconds).

config authkey "text";

Password/Authentication key used to restrict access to client port.

include "path";

Specify another configuration file to be included at this point.

root "object-name";

This is a required option. You specify what object in your config file is the first dependency in your monitoring, so we know where we are within the network to allow us to traverse it properly.

3. Object Configuration Options

Once you have declared an object, the following configuration options exist within it:

also-notify "text";

Not implemented yet.

contact "username@example.com";

e-mail address to send up/down messages to.

contact_on down|up|both;

Defines when this event should cause a contact. If down, notification is only sent (and programs run) after maxdown iterations of service failure. If up, notification happens only after maxdown iterations of service success. If both, notification happens after maxdown iterations of failure, and instantly on success.

dep "object";

Dependency for this object. If that host is not up, we do not get monitored.

desc "text";

Specify the description of the object

ip "[hostname | ip-address ]";

An IP address or valid dns-name of the host to be monitored.

page "text";

Not implemented yet.

password "password";

Only valid for pop3, imap and radius check.

port [ integer ];

Specify the port type for tcp and udp based checks

reverse;

Reverse the meaning of up vs down in monitoring. Useful when using to monitor other sysmonds and to take over backup monitoring.

secret "string";

Only valid for radius check.

spawn "path";

Program to execute upon monitoring failure. Can also contain replacement options that PMESG and SUBJECT can contain. up, we do not get monitored.

type "[ ping | pingv6 | pop3 | tcp | udp | dns | radius | nntp | smtp | imap | x500 | www | sysmon | snmp ]";

Specify the check type.

snmp-type "[ low | high | rate | exact | range | reboot | compare ]";

SNMP test type (required for snmp based tests)

snmp-octets;

Treat oid queried as octet(byte) counter so you can specify snmp-rate in bps instead of bytes/sec

url "string";

URL to be checked. Only valid for http check.

urltext "string-to-search-for";

String to search for within the url requested.

username "username";

Only valid for pop3, imap and radius check.

4. Example Configuration of each test-type

object gateway {
    ip "129.250.50.61";
    type ping;
    desc "fa-12-0-0.a01.clevoh02.us.ra.nether.net";
    contact "$jared-pager";
};

object v6web {
    ip "www.v6.ntt.net";
    type pingv6;
    desc "www.v6.ntt.net IPv6 Ping";
    contact "$jared-pager";
};

object pop3-mailserver {
    ip "198.88.20.7";
    type pop3;
    username "ravi";
    password "moocow";
    desc "qpopper";
    contact "admin@example.com";
};

object tcp-shoutcast {
    ip "198.88.20.7";
    type tcp;
    port 8000;
    desc "shoutcast";
    contact "admin@example.com";
};

object udp-named {
    ip "198.88.20.5";
    type udp;
    port 53;
    desc "named udp port";
    contact "admin@example.com";
};

object dns {
       ip "10.1.161.2";
       type dns;
       dns-query "example.com";
       desc "example.com-dns";
};

object radius-server {
    ip "198.88.20.7";
    type radius;
    secret "private";
    username "jared";
    password "noway";
    desc "radius server";
    contact "admin@example.com";
};

object nntp-server {
    ip "oh.news.verio.net";
    type nntp;
    desc "verio-ohio nntp server";
    contact "admin@example.com,nntp@example.com";
};

object smtp-server {
    ip "198.88.20.7";
    type smtp;
    desc "sendmail";
    contact "admin@example.com,postmaster@example.com";
};

object imap-server {
    ip "198.88.20.7";
    type imap;
    username "jared";
    password "noway";
    desc "imap server";
    contact "admin@example.com,postmaster@example.com";
};

object imap-server {
    ip "198.88.20.7";
    type x500;
    desc "x500 server";
    contact "admin@example.com";
};

object httpd {
    ip "198.88.20.7";
    type www;
    url "/index.html";
    urltext "DOCTYPE HTML PUBLIC";
    desc "apache";
    contact "admin@example.com,webmaster@example.com";
};

object sysmon-server {
    ip "puck.nether.net";
    type sysmon;
    reverse;
    desc "nether.net sysmon";
    contact "jared@example.com";
};

object c7200-router-reboot {
        ip "10.2.3.1";
        type snmp;
        snmp-type "reboot";
        desc "c7200";
        community "public";
        contact "jared@foo.example.com";
};

object cisco-Router-temp {
        ip "10.0.0.1";
        type snmp;
        snmp-type "high";
        oid ".1.3.6.1.4.1.9.9.13.1.3.1.3.1";
        desc "TEMP ALERT above 28 deg C";
        snmp-high "28";
        community "public";
        contact "admin@example.com";
        dep "cisco-Router-Ping";
};

object c7200-rate {
        ip "10.0.0.1";
        type snmp;
        snmp-type "rate";
        oid ".1.3.6.1.2.1.2.2.1.10.18";
        desc "c7200 ser2/3:0 input bitrate";
        snmp-rate "256000";
        snmp-octets;
        community "public";
        contact "user@example.com";
};

5. Example Configuration of each Object Option

object tcp-shoutcast {
    ip "198.88.20.7";
    type tcp;
    port 8000;
    desc "shoutcast";
    contact "admin@example.com";
};

6. Replacement Options

$Id: config.html,v 1.10 2003/12/10 04:39:40 jared Exp $