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