.\"
.\" Copyright (c) 2000, 2001
.\"	Gesellschaft fuer wissenschaftliche
.\"      Datenverarbeitung mbH Goettingen.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the Gesellschaft
.\"	fuer wissenschaftliche Datenverarbeitung mbH Goettingen.
.\" 4. The name of the Gesellschaft fuer wissenschaftliche Datenverarbeitung
.\"    mbH Goettingen may not be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE GESELLSCHAFT FUER WISSENSCHAFTLICHE
.\" DATENVERARBEITUNG MBH GOETTINGEN ``AS IS'' AND ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE GESELLSCHAFT FUER WISSENSCHAFTLICHE DATENVERARBEITUNG
.\" MBH GOETTINGEN BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: rmonitor.1,v 1.2 2001/07/20 15:33:50 kheuer Exp $
.\"
.Dd July 20th, 2001
.Dt RMONITOR 1 CON
.Os
.Sh NAME
.Nm rmonitor
.Nd remote system monitoring utility
.Sh SYNOPSIS
.Nm
.Op Fl h
.Pp
.Nm
.Op Fl c
.Op Fl n Ar address
.Op Fl p Ar port
.Op Fl r Ar seconds
.Op Fl t Ar ttl
.Pp
.Nm
.Op Fl l Ar file
.Op Fl n Ar address
.Op Fl p Ar port
.Op Fl q
.Op Fl r Ar seconds
.Op Fl w Ar tolerance
.Sh DESCRIPTION
The
.Nm
utility is a network-based client-server application for monitoring
remote systems.
.Pp
Each system to be monitored needs to run an
.Nm
client which periodically sends the gathered system information either
to a preferred system running the server, to a multicast group or to a
broadcast address. Depending on the destination address, the server
can be run on the preferred system only, on any system joining the
multicast group or on any system receiving the broadcast packets. In
any case, the server just collects and displays all incoming
information. Since udp is used there is no need for a reliable
connection between client and server.
.Pp
.Nm
is believed not to be a threat to system security since it does not
need a privileged mode to run. If invoked by
.Li root,
.Nm
immediately discards any privilege and changes its real and effective
user and group ID to those of the user
.Li nobody.
The clients do not receive any data; there is no additional open
server port on a host which is monitored. To be very cautious, the
.Nm
server which indeed receives and displays data may be run on a
less critical system.
.Sh OPTIONS
Available options:
.Pp
.\" New mdoc style: .Bl -tag -xwidth ".Fl w Ar tolerance"
.Bl -tag -width "-w tolerance"
.It Fl c
Invokes the
.Nm
client. There is no special flag to invoke the server since this is
done by default.
.It Fl h
Used in earlier versions of
.Nm
to print some help on standard output. Obsolete now, since this man
page has become available, and kept only for compatibility. Will cause
the newer versions of
.Nm
to call
.Xr man 1
with an appropriate argument to show the man page.
.It Fl l Ar file
Log file name; the
.Nm
server will log all incoming system status information to the
specified file. The log file format is similar to screen output (see
DISPLAY section). The only difference is that last refresh times are
not logged since they are meaningless in the log file, and instead of
these a column containing the current time is inserted. Please note
that path and file must have sufficient permissions for the user
.Li nobody
if
.Nm
has been invoked by
.Li root.
.It Fl n Ar address
By default, an
.Nm
client sends the gathered system status information to the standard
network broadcast address. A different address, in decimal dotted
notation, either a host or a broadcast address, can be given here.
Alternatively, a multicast address like 225.10.1.1 can be
specified. In the latter case, the same address has to be specified on
both clients and servers. Servers will registrate themselves in the
multicast group, and multicast servers will also monitor unicast or
broadcast clients. Specification of this flag when invoking servers is
meaningful only when using multicast.
.It Fl p Ar port
Number of port to use for transmitting data in numerical notation;
default value is 3661. Newer versions of
.Nm
allow full port reuse; thus multiple instances of the server may be
run on a single host.
.It Fl q
Quiet mode; causes the server to suppress all standard and screen
output. May be useful in combination with
.Fl l
when logging in the background is required.
.It Fl r Ar seconds
Refresh time in seconds which should be kept uniform within a coherent
client-server group. The default refresh time is 30 seconds. The
server needs to know about the refresh time of the clients to
calculate a tolerance (2.5 times refresh time per default, see
.Fl w
) used for highlighting. Hosts will be assumed not to send anymore if
the time since the last message arrived is out of this range, and the
corresponding screen line will be displayed in an emphasized mode.
.It Fl t Ar ttl
Time to live for multicast packets when using multicast, defaults to a
value of four. In general, the higher this value, the farther the
packets will travel.
.It Fl w Ar tolerance
Factor used to calculate the tolerance value used for highlighting
on the screen (see
.Fl r,
too). The default value is 2.5 which allows a single packet loss
between each two successful screen updates. Values less than or equal
to 1.0 will be not accepted here.
.El
.Sh DISPLAY
.Nm
prints one line of status information for each host monitored. The
data shown are:
.Bl -tag -width "PROCESSES "
.It HOST
Host name without domain information of the monitored system; since this
name is sent by the remote host, host name resolution is not required on
the system running the server. Host names longer than seven characters
will be truncated to seven characters before they are displayed.
.It REFRESH
Approximate time since last refresh; the more hosts are monitored,
the more accurate will this information be. The values in this
column are recalculated and redisplayed each time a packet from
any of the clients arrives. Time format is:
.Li -hh:mm:ss
(hours, minutes and seconds).
.It UPTIME
Time since last boot of the remote system. The format is:
.Li +ddd+hh:mm
(days, hours and minutes).
.It #U
Number of users currently logged in.
.It SL
Security level the kernel runs in. Although this information is rather
static, this column may help to detect an unexpected low security
level.
.It DB
Number of dirty buffers the contents of which have not yet been
written to mass storage.
.It LOADAVG
Load average over the last 1 and 5 minutes.
.It PROCESSES
Total number of processes; and relative number of processes compared to
the maximal number of processes possible, given in percent.
.It FILES
Total number of open files; and relative number of open files compared
to the maximal number of open files possible, given in percent.
For clients running on
.Fx
systems prior to 4.2-RELEASE, only quotation marks will be shown here.
.It MEM(ABW)
Memory utilization; number of megabytes in use for active and wired
pages and for the buffer cache. Additionally this number is compared
to the size of the real memory available and memory utilization is
also given in percent.
.El
.Sh EXAMPLE
An
.Nm
client is invoked which sends the gathered information to a multicast
group instead of using broadcast packets:
.Pp
.Li rmonitor -c -n 225.10.1.1
.Pp
The server for collecting and displaying the data can now be started
on the same or any other host by joining the multicast group:
.Pp
.Li rmonitor -n 225.10.1.1
.Sh FILES
.Bl -tag -width /usr/local/etc/rc.d/rmonitor.sh
.It Pa /usr/local/etc/rc.d/rmonitor.sh
.El
.Sh SEE ALSO
.Xr systat 1 ,
.Xr top 1 ,
.Xr uptime 1 ,
.Xr sysctl 8
.Sh HISTORY
.Nm
has been developed for
.Fx
4.2-STABLE. It is not part of the base system.
.Sh BUGS
.Nm
depends on a sufficient display size of at less 79 columns and two
rows more than number of hosts to monitor. There is no warning in case
of unsufficient display size.
.Pp
.Nm
should gather, transmit and show more information.
.Pp
The information displayed by
.Nm
may be incomplete or partially be incorrect for versions of
.Fx
prior to 4.2-RELEASE.
.Sh AUTHOR
.An "Konrad Heuer" Aq kheuer@gwdu60.gwdg.de