usr.sbin/rwhod/rwhod.8

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)rwhod.8     8.2 (Berkeley) 12/11/93
  29 .\" $FreeBSD: src/usr.sbin/rwhod/rwhod.8,v 1.13.2.4 2003/03/11 22:31:33 trhodes Exp $
  30 .\" $DragonFly: src/usr.sbin/rwhod/rwhod.8,v 1.7 2008/09/02 11:50:47 matthias Exp $
  31 .\"
  32 .Dd September 2, 2008
  33 .Dt RWHOD 8
  34 .Os
  35 .Sh NAME
  36 .Nm rwhod
  37 .Nd system status server
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl i
  41 .Op Fl p
  42 .Op Fl l
  43 .Op Fl g Ar time
  44 .Op Fl m Op Ar ttl
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility is the server which maintains the database used by the
  49 .Xr rwho 1
  50 and
  51 .Xr ruptime 1
  52 programs.  Its operation is predicated on the ability to
  53 .Em broadcast
  54 or
  55 .Em multicast
  56 messages on a network.
  57 .Pp
  58 The
  59 .Nm
  60 utility operates as both a producer and consumer of status information,
  61 unless the
  62 .Fl l
  63 (listen mode) option is specified, in which case
  64 it acts as a consumer only.
  65 As a producer of information it periodically
  66 queries the state of the system and constructs
  67 status messages which are broadcasted or multicasted on a network.
  68 As a consumer of information, it listens for other
  69 .Nm
  70 servers' status messages, validating them, then recording
  71 them in a collection of files located in the directory
  72 .Pa /var/rwho .
  73 .Pp
  74 The
  75 .Fl i
  76 option enables insecure mode, which causes
  77 .Nm
  78 to ignore the source port on incoming packets.
  79 .Pp
  80 The
  81 .Fl g
  82 option allows for the broadcast
  83 .Ar time
  84 for
  85 .Nm
  86 to be reduced below 3 minutes. This enables for more 'real' time statistics
  87 of the host.
  88 The
  89 .Ar time
  90 operand can be given as 30 (30 seconds) or 1m (1 minute), for example.
  91 .Pp
  92 The
  93 .Fl p
  94 option tells
  95 .Nm
  96 to ignore all
  97 .Dv POINTOPOINT
  98 interfaces.  This is useful if you do not wish to keep dial on demand
  99 interfaces permanently active.
 100 .Pp
 101 The
 102 .Fl l
 103 option enables listen mode, which causes
 104 .Nm
 105 to not broadcast any information.
 106 This allows you to monitor other machines'
 107 .Nm
 108 information, without broadcasting your own.
 109 .Pp
 110 The
 111 .Fl m
 112 option causes
 113 .Nm
 114 to use IP multicast (instead of
 115 broadcast) on all interfaces that have
 116 the IFF_MULTICAST flag set in their "ifnet" structs
 117 (excluding the loopback interface).  The multicast
 118 reports are sent with a time-to-live of 1, to prevent
 119 forwarding beyond the directly-connected subnet(s).
 120 .Pp
 121 If the optional
 122 .Ar ttl
 123 argument is supplied with the
 124 .Fl m
 125 flag,
 126 .Nm
 127 will send IP multicast datagrams with a
 128 time-to-live of
 129 .Ar ttl ,
 130 via a SINGLE interface rather
 131 than all interfaces.
 132 .Ar ttl
 133 must be between 0 and
 134 32 (or MAX_MULTICAST_SCOPE).  Note that
 135 .Fl m Ar 1
 136 is different from
 137 .Fl m ,
 138 in that
 139 .Fl m Ar 1
 140 specifies transmission on one interface only.
 141 .Pp
 142 When
 143 .Fl m
 144 is used without a
 145 .Ar ttl
 146 argument, the program accepts multicast
 147 .Nm
 148 reports from all multicast-capable interfaces.  If a
 149 .Ar ttl
 150 argument is given, it accepts multicast reports from only one interface, the
 151 one on which reports are sent (which may be controlled via the host's routing
 152 table).  Regardless of the
 153 .Fl m
 154 option, the program accepts broadcast or
 155 unicast reports from all interfaces.  Thus, this program will hear the
 156 reports of old, non-multicasting
 157 .Nm Ns s ,
 158 but, if multicasting is used,
 159 those old
 160 .Nm Ns s
 161 won't hear the reports generated by this program.
 162 .Pp
 163 The server transmits and receives messages at the port indicated
 164 in the ``who'' service specification; see
 165 .Xr services 5 .
 166 The messages sent and received, are of the form:
 167 .Bd -literal -offset indent
 168 struct  outmp {
 169         char    out_line[8];            /* tty name */
 170         char    out_name[8];            /* user id */
 171         long    out_time;               /* time on */
 172 };
 173
 174 struct  whod {
 175         char    wd_vers;
 176         char    wd_type;
 177         char    wd_fill[2];
 178         int     wd_sendtime;
 179         int     wd_recvtime;
 180         char    wd_hostname[32];
 181         int     wd_loadav[3];
 182         int     wd_boottime;
 183         struct  whoent {
 184                 struct  outmp we_utmp;
 185                 int     we_idle;
 186         } wd_we[1024 / sizeof (struct whoent)];
 187 };
 188 .Ed
 189 .Pp
 190 All fields are converted to network byte order prior to
 191 transmission.  The load averages are as calculated by the
 192 .Xr w 1
 193 program, and represent load averages over the 5, 10, and 15 minute
 194 intervals prior to a server's transmission; they are multiplied by 100
 195 for representation in an integer.  The host name
 196 included is that returned by the
 197 .Xr gethostname 3
 198 system call, with any trailing domain name omitted.
 199 The array at the end of the message contains information about
 200 the users logged in to the sending machine.  This information
 201 includes the contents of the
 202 .Xr utmp 5
 203 entry for each non-idle terminal line and a value indicating the
 204 time in seconds since a character was last received on the terminal line.
 205 .Pp
 206 Messages received by the
 207 .Nm rwho
 208 server are discarded unless they originated at an
 209 .Nm rwho
 210 server's port or the
 211 .Fl i
 212 option was specified.  In addition, if the host's name, as specified
 213 in the message, contains any unprintable
 214 .Tn ASCII
 215 characters, the
 216 message is discarded.  Valid messages received by
 217 .Nm
 218 are placed in files named
 219 .Pa whod.hostname
 220 in the directory
 221 .Pa /var/rwho .
 222 These files contain only the most recent message, in the
 223 format described above.
 224 .Pp
 225 Status messages are generated by default approximately once every
 226 3 minutes.
 227 .Nm Rwhod
 228 performs an
 229 .Xr nlist 3
 230 on
 231 .Pa /boot/kernel
 232 every 30 minutes to guard against
 233 the possibility that this file is not the system
 234 image currently operating.
 235 .Sh SEE ALSO
 236 .Xr ruptime 1 ,
 237 .Xr rwho 1
 238 .Sh HISTORY
 239 The
 240 .Nm
 241 utility appeared in
 242 .Bx 4.2 .
 243 .Sh BUGS
 244 Status information should be sent only upon request rather than continuously.
 245 People often interpret the server dying
 246 or network communication failures
 247 as a machine going down.