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