NAME

portmon - Network service monitoring daemon

SYNOPSIS

portmon [-dhvV] [-n, --sleep=<time>] [-c, --config=<file>] [-s, severe=<number>] [-l, --logfile=<file>] [-e, --error=<command>] [-t, --timeout=<time>] [-g, --lag=<time>] [-p, --probe=<number>] [-r, --report=<format>]

DESCRIPTION

portmon is a daemon designed to periodically attempt to connect to a number of remote hosts and see if they are down. This can be very useful for monitoring a large number of workstations, servers, and so forth. If a host is down, portmon will send out a notification (by default, mailing to root).

OPTIONS

-c, --config=<file>: The name of the host file to be used (default is ./hosts). The host file must contain one host per line, with the hostname and port separated by some whitespace. Either proper hostnames or IP addresses may be listed in the host file. Any line starting with the '#' character is taken to be a comment.
-d, --daemon: If -d is used, portmon will daemonize and run in the background. Otherwise, portmon runs as a foreground process.
-e, --error=<command>: Run <command> instead of using the default error handler compiled in portmon. The following format strings will be replaced in the string argument:

%h: The hostname
%t: The current date
%m: The error message thrown

-g, --lag=<timeout>: If the host is up, but the response time is greater than <timeout> milliseconds, then notification will be given. Use of this feature with the "probe" flag set to 3 or higher is recommended, as an average ping time is much more reliable.
-h, --help: Display a brief help message. Note that if your system does not support getopt_long(), only short options will be displayed.
-l, --logfile=<file>: File in which portmon will log error messages. If no filename is specified, all messages will be sent to /dev/null.
-n, --sleep=<minutes>: Specifies the amount of time to sleep between contacting hosts. Default time is one hour.
-p, --probes=<number>: Number of connection attempts per port.
-r, --report=<format>: If used, portmon will run in "report mode", cycling through the host list once and printing a report to standard output. Useful for CGI scripts and such. An optional report format can be given, which accepts the following parameters:

%h: Hostname
%p: Port
%l: Lag amount (in ms)
%s: One character status flag for down (!), normal (-), or lagged (+).
%w: Status of the host (the string "down", "normal", or "lagged").

: The default format is the string "%s Service on %h:%p is %w (%lms)". Any number of these flags may be combined in a format. For example:

: portmon --report='The host %h:%p is %w'

-s, --severe=<number>: How many failed connect iterations (length specified by -n ) until sending "severe" notification. By default, portmon will wait 12 iterations (12 hours with the default timeout) before sending out severe notification. If a host is down, portmon will not send notification every consecutive time it finds this host to be down. If this option is set to 0, severe notification is disabled.
-t, --timeout=<seconds>: Number of seconds to wait before giving up on contacting a host.
-v, --verbose: Show extra information during a scan.
-V, --version: Display version information about portmon.

CONFIGURATION

portmon has a very flexible and configurable way of sending out notification when a host is down. Earlier releases of portmon allowed one to specify the default notification on the command line, but this proved to be too limiting. As of v0.3, an object file written in the C language is used as the default notifier. To change the notification method (which is by default, to send a generic email message to root@localhost), one must edit the file action.c in portmon's source directory, and rebuild portmon. A simple and well-commented example for the action.c file is included with the distribution of portmon. portmon places no restrictions on what action handlers may do, but it is probably not wise to use any exec(3) or system(3) calls, as they do not return. The err_action() function (located inside of action.c) must be prototyped as follows:

int err_action(char *hostname, char *err_msg);

Where cur_time will be the time when the error occurred (as is generated by time(NULL); see man time(2)). hostname is a pointer to a string containing the hostname of the host that is down, and err_msg is a pointer to a string containing the particular error message. Though this approach is quite flexible, it does not lend itself well to non-programmers. For this reason, the -e option was added in version 1.7, which allows the user to simply run a script specified on the command line in place of the compiled-in notification. For example, running "portmon -c /usr/local/etc/portmon.hosts -e 'wall -n'" would send a global message to every user on the system in the event of a host being found to be down.

BUGS

- Ping support is broken on Solaris as of v1.4.

AUTHOR

portmon was written by Nik Reiman <nik@aboleo.net>. The portmon homepage is located at http://www.aboleo.net/software/portmon