Sweep-fix man page section order to match mdoc(7), part 5/5.
[dragonfly.git] / 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.