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 .\"
  34 .Dd December 11, 1993
  35 .Dt RWHOD 8
  36 .Os BSD 4.2
  37 .Sh NAME
  38 .Nm rwhod
  39 .Nd system status server
  40 .Sh SYNOPSIS
  41 .Nm rwhod
  42 .Op Fl i
  43 .Op Fl l
  44 .Op Fl m Op Ar ttl
  45 .Sh DESCRIPTION
  46 .Nm Rwhod
  47 is the server which maintains the database used by the
  48 .Xr rwho 1
  49 and
  50 .Xr ruptime 1
  51 programs.  Its operation is predicated on the ability to
  52 .Em broadcast
  53 or
  54 .Em multicast
  55 messages on a network.
  56 .Pp
  57 .Nm Rwhod
  58 operates as both a producer and consumer of status information,
  59 unless the
  60 .Fl l
  61 (listen mode) option is specified, in which case
  62 it acts as a consumer only.
  63 As a producer of information it periodically
  64 queries the state of the system and constructs
  65 status messages which are broadcasted or multicasted on a network.
  66 As a consumer of information, it listens for other
  67 .Nm
  68 servers' status messages, validating them, then recording
  69 them in a collection of files located in the directory
  70 .Pa /var/rwho .
  71 .Pp
  72 The
  73 .Fl i
  74 option enables insecure mode, which causes
  75 .Nm
  76 to ignore the source port on incoming packets.
  77 .Pp
  78 The
  79 .Fl l
  80 option enables listen mode, which causes
  81 .Nm
  82 to not broadcast any information.
  83 This allows you to monitor other machines'
  84 .Nm
  85 information, without broadcasting your own.
  86 .Pp
  87 The
  88 .Fl m
  89 option causes
  90 .Nm
  91 to use IP multicast (instead of
  92 broadcast) on all interfaces that have
  93 the IFF_MULTICAST flag set in their "ifnet" structs
  94 (excluding the loopback interface).  The multicast
  95 reports are sent with a time-to-live of 1, to prevent
  96 forwarding beyond the directly-connected subnet(s).
  97 .Pp
  98 If the optional
  99 .Ar ttl
 100 argument is supplied with the
 101 .Fl m
 102 flag,
 103 .Nm
 104 will send IP multicast datagrams with a
 105 time-to-live of
 106 .Ar ttl ,
 107 via a SINGLE interface rather
 108 than all interfaces.
 109 .Ar ttl
 110 must be between 0 and
 111 32 (or MAX_MULTICAST_SCOPE).  Note that
 112 .Fl m Ar 1
 113 is different than
 114 .Fl m ,
 115 in that
 116 .Fl m Ar 1
 117 specifies transmission on one interface only.
 118 .Pp
 119 When
 120 .Fl m
 121 is used without a
 122 .Ar ttl
 123 argument, the program accepts multicast
 124 .Nm
 125 reports from all multicast-capable interfaces.  If a
 126 .Ar ttl
 127 argument is given, it accepts multicast reports from only one interface, the
 128 one on which reports are sent (which may be controlled via the host's routing
 129 table).  Regardless of the
 130 .Fl m
 131 option, the program accepts broadcast or
 132 unicast reports from all interfaces.  Thus, this program will hear the
 133 reports of old, non-multicasting
 134 .Nm rwhod Ns s ,
 135 but, if multicasting is used,
 136 those old
 137 .Nm rwhod Ns s
 138 won't hear the reports generated by this program.
 139 .Pp
 140 The server transmits and receives messages at the port indicated
 141 in the ``who'' service specification; see
 142 .Xr services 5 .
 143 The messages sent and received, are of the form:
 144 .Bd -literal -offset indent
 145 struct  outmp {
 146         char    out_line[8];            /* tty name */
 147         char    out_name[8];            /* user id */
 148         long    out_time;               /* time on */
 149 };
 150
 151 struct  whod {
 152         char    wd_vers;
 153         char    wd_type;
 154         char    wd_fill[2];
 155         int     wd_sendtime;
 156         int     wd_recvtime;
 157         char    wd_hostname[32];
 158         int     wd_loadav[3];
 159         int     wd_boottime;
 160         struct  whoent {
 161                 struct  outmp we_utmp;
 162                 int     we_idle;
 163         } wd_we[1024 / sizeof (struct whoent)];
 164 };
 165 .Ed
 166 .Pp
 167 All fields are converted to network byte order prior to
 168 transmission.  The load averages are as calculated by the
 169 .Xr w 1
 170 program, and represent load averages over the 5, 10, and 15 minute
 171 intervals prior to a server's transmission; they are multiplied by 100
 172 for representation in an integer.  The host name
 173 included is that returned by the
 174 .Xr gethostname 3
 175 system call, with any trailing domain name omitted.
 176 The array at the end of the message contains information about
 177 the users logged in to the sending machine.  This information
 178 includes the contents of the
 179 .Xr utmp 5
 180 entry for each non-idle terminal line and a value indicating the
 181 time in seconds since a character was last received on the terminal line.
 182 .Pp
 183 Messages received by the
 184 .Nm rwho
 185 server are discarded unless they originated at an
 186 .Nm rwho
 187 server's port or the
 188 .Fl i
 189 option was specified.  In addition, if the host's name, as specified
 190 in the message, contains any unprintable
 191 .Tn ASCII
 192 characters, the
 193 message is discarded.  Valid messages received by
 194 .Nm
 195 are placed in files named
 196 .Pa whod.hostname
 197 in the directory
 198 .Pa /var/rwho .
 199 These files contain only the most recent message, in the
 200 format described above.
 201 .Pp
 202 Status messages are generated approximately once every
 203 3 minutes.
 204 .Nm Rwhod
 205 performs an
 206 .Xr nlist 3
 207 on
 208 .Pa /kernel
 209 every 30 minutes to guard against
 210 the possibility that this file is not the system
 211 image currently operating.
 212 .Sh SEE ALSO
 213 .Xr ruptime 1 ,
 214 .Xr rwho 1
 215 .Sh BUGS
 216 Status information should be sent only upon request rather than continuously.
 217 People often interpret the server dying
 218 or network communication failures
 219 as a machine going down.
 220 .Sh HISTORY
 221 The
 222 .Nm
 223 command appeared in
 224 .Bx 4.2 .