PORTMON(8) System Manager's Manual PORTMON(8) NAME portmon - Network service monitoring daemon SYNOPSIS portmon [-dhvV] [-n, --sleep=<time>] [-c, --config=<file>] [-s, se- vere=<number>] [-l, --logfile=<file>] [-e, --error=<command>] [-t, --time- out=<time>] [-g, --lag=<time>] [-p, --probe=<number>] [-r, --report=<for- mat>] 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 mon- itoring 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 sep- arated 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 aver- age 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. De- fault 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 ac- cepts 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 it- erations (12 hours with the default timeout) before sending out se- vere notification. If a host is down, portmon will not send notifi- cation 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 notifica- tion when a host is down. Earlier releases of portmon allowed one to spec- ify 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 de- fault, 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 sys- tem(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 rea- son, the -e option was added in version 1.7, which allows the user to sim- ply run a script specified on the command line in place of the compiled-in notification. For example, running "portmon -c /usr/local/etc/port- mon.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 21 August 2003 PORTMON(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION | BUGS | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=portmon&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>