doc/man-pages/pod/fs_checkservers.pod

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