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