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