doc: -afsdb uses SRV records
[openafs.git] / doc / man-pages / pod1 / fs_checkservers.pod
1 =head1 NAME
2
3 fs_checkservers - Displays the status of server machines
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs checkservers> S<<< [B<-cell> <I<cell to check>>] >>> [B<-all>] [B<-fast>]
11     S<<< [B<-interval> <I<seconds between probes>>] >>> [B<-help>]
12
13 B<fs checks> S<<< [B<-c> <I<cell to check>>] >>> [B<-a>] [B<-f>]
14     S<<< [B<-i> <I<seconds between probes>>] >>> [B<-h>]
15
16 =for html
17 </div>
18
19 =head1 DESCRIPTION
20
21 The B<fs checkservers> command reports whether certain AFS server machines
22 are accessible from the local client machine. The machines belong to one
23 of two classes, and the Cache Manager maintains a list of them in kernel
24 memory:
25
26 =over 4
27
28 =item *
29
30 The database server machines for every cell listed in the local
31 F</usr/vice/etc/CellServDB file>, plus any machines added to the memory
32 list by the B<fs newcell> command since the last reboot.
33
34 =item *
35
36 All file server machines the Cache Manager has recently contacted, and
37 which it probably needs to contact again soon. In most cases, the Cache
38 Manager holds a callback on a file or volume fetched from the machine.
39
40 =back
41
42 If the Cache Manager is unable to contact the vlserver process on a
43 database server machine or the B<fileserver> process on a file server
44 machine, it marks the machine as inaccessible. (Actually, if a file server
45 machine is multihomed, the Cache Manager attempts to contact all of the
46 machine's interfaces, and only marks the machine as down if the
47 B<fileserver> fails to reply via any of them.) The Cache Manager then
48 periodically (by default, every three minutes) sends a probe to each
49 marked machine, to see if it is still inaccessible. If a previously
50 inaccessible machine responds, the Cache Manager marks it as accessible
51 and no longer sends the periodic probes to it.
52
53 The B<fs checkservers> command updates the list of inaccessible machines
54 by having the Cache Manager probe a specified set of them:
55
56 =over 4
57
58 =item *
59
60 By default, only machines that are marked inaccessible and belong to the
61 local cell (the cell listed in the local F</usr/vice/etc/ThisCell>
62 file).
63
64 =item *
65
66 If the B<-cell> argument is included, only machines that are marked
67 inaccessible and belong to the specified cell.
68
69 =item *
70
71 If the B<-all> flag is included, all machines marked inaccessible.
72
73 =back
74
75 If the B<-fast> flag is included, the Cache Manager does not probe any
76 machines, but instead reports the results of the most recent previous
77 probe.
78
79 To set the interval between probes rather than produce a list of
80 inaccessible machines, use the B<-interval> argument. The non-default
81 setting persists until the machine reboots; to preserve it across reboots,
82 put the appropriate B<fs checkservers> command in the machine's AFS
83 initialization files.
84
85 =head1 CAUTIONS
86
87 The command can take quite a while to complete, if a number of machines do
88 not respond to the Cache Manager's probe. The Cache Manager probes
89 machines sequentially and waits a standard timeout period before marking
90 the machine as unresponsive, to allow for slow network communication. To
91 make the command shell prompt return quickly, put the command in the
92 background. It is harmless to interrupt the command by typing Ctrl-C or
93 another interrupt signal.
94
95 Note that the Cache Manager probes only server machines marked
96 inaccessible in its memory list. A server machine's absence from the
97 output does not necessarily mean that it is functioning, because it
98 possibly is not included in the memory list at all (if, for example, the
99 Cache Manager has not contacted it recently). For the same reason, the
100 output is likely to vary on different client machines.
101
102 Unlike most B<fs> commands, the fs checkservers command does not refer to
103 the AFSCELL environment variable.
104
105 =head1 OPTIONS
106
107 =over 4
108
109 =item B<-cell> <I<cell to check>>
110
111 Names each cell in which to probe server machines marked as
112 inaccessible. Provide the fully qualified domain name, or a shortened form
113 that disambiguates it from the other cells listed in the local
114 F</usr/vice/etc/CellServDB> file. Combine this argument with the B<-fast>
115 flag if desired, but not with the B<-all> flag. Omit both this argument
116 and the B<-all> flag to probe machines in the local cell only.
117
118 =item B<-all>
119
120 Probes all machines in the Cache Manager's memory list that are marked
121 inaccessible. Combine this argument with the B<-fast> flag if desired, but
122 not with the B<-cell> argument. Omit both this flag and the B<-cell>
123 argument to probe machines in the local cell only.
124
125 =item B<-fast>
126
127 Displays the Cache Manager's current list of machines that are
128 inaccessible, rather than sending new probes. The output can as old as the
129 current setting of the probe interval (by default three minutes, and
130 maximum ten minutes).
131
132 =item B<-interval> <I<seconds between probes>>
133
134 Sets or reports the number of seconds between the Cache Manager's probes
135 to machines in the memory list that are marked inaccessible:
136
137 =over 4
138
139 =item *
140
141 To set the interval, specify a value from the range between 1 and C<600>
142 (10 minutes); the default is C<180> (three minutes). The issuer must be
143 logged in as the local superuser C<root>. The altered setting persists
144 until again changed with this command, or until the machine reboots, at
145 which time the setting returns to the default.
146
147 =item *
148
149 Provide a value of C<0> (zero) to display the current interval setting. No
150 privilege is required. Do not combine this argument with any other.
151
152 =back
153
154 =item B<-help>
155
156 Prints the online help for this command. All other valid options are
157 ignored.
158
159 =back
160
161 =head1 OUTPUT
162
163 If there are no machines marked as inaccessible, or if all of them now
164 respond to the Cache Manager's probe, the output is:
165
166    All servers are running.
167
168 Note that this message does not mean that all server machines in each
169 relevant cell are running. The output indicates the status of only those
170 machines that the Cache Manager probes.
171
172 If a machine fails to respond to the probe within the timeout period, the
173 output begins with the string
174
175    These servers unavailable due to network or server problems:
176
177 and lists the hostname of each machine on its own line. The Cache Manager
178 stores machine records by Internet address, so the format of each hostname
179 (uppercase or lowercase letters, or an Internet address in dotted decimal
180 format) depends on how the local cell's name service translates it at the
181 time the command is issued. If a server machine is multihomed, the output
182 lists only one of its interfaces (usually, the currently most preferred
183 one).
184
185 If the B<-interval> argument is provided with a value between C<1> and
186 C<600>, there is no output. If the value is C<0>, the output reports the
187 probe interval as follows:
188
189    The current down server probe interval is <interval> secs
190
191 =head1 EXAMPLES
192
193 The following command displays the Cache Manager's current list of
194 unresponsive machines in the local cell, rather than probing them
195 again. The output indicates that if there were any machines marked
196 inaccessible, they all responded to the previous probe.
197
198    % fs checkservers -fast
199    All servers are running.
200
201 The following example probes machines in the Cache Manager's memory list
202 that belong to the C<stateu.edu> cell:
203
204    % fs checkservers -cell stateu.edu
205    All servers are running.
206
207 The following example probes all server machines in the Cache Manager's
208 memory list. It reports that two machines did not respond to the probe.
209
210    % fs checkservers -all
211    These servers unavailable due to network or server problems:
212    fs1.abc.com SV3.STATE.EDU.
213
214 =head1 PRIVILEGE REQUIRED
215
216 To set the probe interval, the issuer must be logged in as the local
217 superuser C<root>. Otherwise, no privilege is required.
218
219 =head1 SEE ALSO
220
221 L<CellServDB(5)>,
222 L<ThisCell(5)>,
223 L<fs_newcell(1)>
224
225 =head1 COPYRIGHT
226
227 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
228
229 This documentation is covered by the IBM Public License Version 1.0.  It was
230 converted from HTML to POD by software written by Chas Williams and Russ
231 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.