PORTMON(8)PORTMON(8)NAMEportmon - Network service monitoring daemon
SYNOPSISportmon [-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>]
DESCRIPTIONportmon 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 use‐
ful 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 com‐
piled 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 <time‐
out> 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 notifica‐
tion 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.
CONFIGURATIONportmon has a very flexible and configurable way of sending out notifi‐
cation 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 lan‐
guage 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 gener‐
ated 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.
AUTHORportmon was written by Nik Reiman <nik@aboleo.net>. The portmon home‐
page is located at http://www.aboleo.net/software/portmon
21 August 2003 PORTMON(8)
