doc/man-pages/pod1/afsmonitor.pod

   1 =head1 NAME
   2
   3 afsmonitor - Monitors File Servers and Cache Managers
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<afsmonitor> [B<initcmd>] [-config <I<configuration file>>]
  11     S<<< [B<-frequency> <I<poll frequency, in seconds>>] >>>
  12     S<<< [B<-output> <I<storage file name>>] >>> [B<-detailed>]
  13     S<<< [B<-debug> <I<debug output file>>] >>>
  14     S<<< [B<-fshosts> <I<list of file servers to monitor>>+] >>>
  15     S<<< [B<-cmhosts> <I<list of cache managers to monitor>>+] >>>
  16     S<<< [B<-buffers> <I<number of buffer slots>>] >>> [B<-help>]
  17
  18 B<afsmonitor> [B<i>]  [-co <I<configuration file>>]
  19     S<<< [B<-fr> <I<poll frequency, in seconds>>] >>>
  20     S<<< [B<-o> <I<storage file name>>] >>> [B<-det>]
  21     S<<< [B<-deb> <I<debug output file>>] >>>
  22     S<<< [B<-fs> <I<list of file servers to monitor>>+] >>>
  23     S<<< [B<-cm> <I<list of cache managers to monitor>>+] >>>
  24     S<<< [B<-b> <I<number of buffer slots>>] >>> [B<-h>]
  25
  26 =for html
  27 </div>
  28
  29 =head1 DESCRIPTION
  30
  31 The afsmonitor command initializes a program that gathers and displays
  32 statistics about specified File Server and Cache Manager operations. It
  33 allows the issuer to monitor, from a single location, a wide range of File
  34 Server and Cache Manager operations on any number of machines in both
  35 local and foreign cells.
  36
  37 There are 271 available File Server statistics and 571 available Cache
  38 Manager statistics, listed in the appendix about B<afsmonitor> statistics
  39 in the I<IBM AFS Administration Guide>. By default, the command displays
  40 all of the relevant statistics for the file server machines named by the
  41 B<-fshosts> argument and the client machines named by the B<-cmhosts>
  42 argument. To limit the display to only the statistics of interest, list
  43 them in the configuration file specified by the B<-config> argument. In
  44 addition, use the configuration file for the following purposes:
  45
  46 =over 4
  47
  48 =item *
  49
  50 To set threshold values for any monitored statistic. When the value of a
  51 statistic exceeds the threshold, the B<afsmonitor> command displays it in
  52 reverse video. There are no default threshold values.
  53
  54 =item *
  55
  56 To invoke a program or script automatically when a statistic exceeds its
  57 threshold. The AFS distribution does not include any such scripts.
  58
  59 =item *
  60
  61 To list the file server and client machines to monitor, instead of using
  62 the B<-fshosts> and B<-cmhosts> arguments.
  63
  64 =back
  65
  66 For a description of the configuration file, see L<afsmonitor(5)>.
  67
  68 =head1 CAUTIONS
  69
  70 The following software must be accessible to a machine where the
  71 B<afsmonitor> program is running:
  72
  73 =over 4
  74
  75 =item *
  76
  77 The AFS xstat libraries, which the afsmonitor program uses to gather data.
  78
  79 =item *
  80
  81 The curses graphics package, which most UNIX distributions provide as a
  82 standard utility.
  83
  84 =back
  85
  86 The B<afsmonitor> screens format successfully both on so-called dumb
  87 terminals and in windowing systems that emulate terminals. For the output
  88 to looks its best, the display environment needs to support reverse video
  89 and cursor addressing. Set the TERM environment variable to the correct
  90 terminal type, or to a value that has characteristics similar to the
  91 actual terminal type. The display window or terminal must be at least 80
  92 columns wide and 12 lines long.
  93
  94 The B<afsmonitor> program must run in the foreground, and in its own
  95 separate, dedicated window or terminal. The window or terminal is
  96 unavailable for any other activity as long as the B<afsmonitor> program is
  97 running. Any number of instances of the B<afsmonitor> program can run on a
  98 single machine, as long as each instance runs in its own dedicated window
  99 or terminal. Note that it can take up to three minutes to start an
 100 additional instance.
 101
 102 =head1 OPTIONS
 103
 104 =over 4
 105
 106 =item B<initcmd>
 107
 108 Accommodates the command's use of the AFS command parser, and is optional.
 109
 110 =item B<-config> <I<file>>
 111
 112 Names the configuration file which lists the machines to monitor,
 113 statistics to display, and threshold values, if any. A partial pathname is
 114 interpreted relative to the current working directory. Provide this
 115 argument if not providing the B<-fshosts> argument, B<-cmhosts> argument,
 116 or neither. For instructions on creating this file, see the preceding
 117 B<DESCRIPTION> section, and the section on the B<afsmonitor> program in
 118 the I<IBM AFS Administration Guide>.
 119
 120 =item B<-frequency> <I<poll frequency>>
 121
 122 Specifies in seconds how often the afsmonitor program probes the File
 123 Servers and Cache Managers. Valid values range from C<1> to C<86400>
 124 (which is 24 hours); the default value is C<60>. This frequency applies to
 125 both File Servers and Cache Managers, but the B<afsmonitor> program
 126 initiates the two types of probes, and processes their results,
 127 separately. The actual interval between probes to a host is the probe
 128 frequency plus the time required for all hosts to respond.
 129
 130 =item B<-output> <I<file>>
 131
 132 Names the file to which the afsmonitor program writes all of the
 133 statistics that it collects. By default, no output file is created. See
 134 the section on the B<afsmonitor> command in the I<IBM AFS Administration
 135 Guide> for information on this file.
 136
 137 =item B<-detailed>
 138
 139 Formats the information in the output file named by B<-output> argument in
 140 a maximally readable format. Provide the B<-output> argument along with
 141 this one.
 142
 143 =item B<-fshosts> <I<host>>+
 144
 145 Names one or more machines from which to gather File Server
 146 statistics. For each machine, provide either a fully qualified host name,
 147 or an unambiguous abbreviation (the ability to resolve an abbreviation
 148 depends on the state of the cell's name service at the time the command is
 149 issued). This argument can be combined with the B<-cmhosts> argument, but
 150 not with the B<-config> argument.
 151
 152 =item B<-cmhosts> <I<host>>+
 153
 154 Names one or more machines from which to gather Cache Manager
 155 statistics. For each machine, provide either a fully qualified host name,
 156 or an unambiguous abbreviation (the ability to resolve an abbreviation
 157 depends on the state of the cell's name service at the time the command is
 158 issued). This argument can be combined with the B<-fshosts> argument, but
 159 not with the B<-config> argument.
 160
 161 =item B<-buffers> <I<slots>>
 162
 163 Is nonoperational and provided to accommodate potential future
 164 enhancements to the program.
 165
 166 =item B<-help>
 167
 168 Prints the online help for this command. All other valid options are
 169 ignored.
 170
 171 =back
 172
 173 =head1 OUTPUT
 174
 175 The afsmonitor program displays its data on three screens:
 176
 177 =over 4
 178
 179 =item System Overview
 180
 181 This screen appears automatically when the B<afsmonitor> program
 182 initializes. It summarizes separately for File Servers and Cache Managers
 183 the number of machines being monitored and how many of them have I<alerts>
 184 (statistics that have exceeded their thresholds). It then lists the
 185 hostname and number of alerts for each machine being monitored, indicating
 186 if appropriate that a process failed to respond to the last probe.
 187
 188 =item File Server
 189
 190 This screen displays File Server statistics for each file server machine
 191 being monitored. It highlights statistics that have exceeded their
 192 thresholds, and identifies machines that failed to respond to the last
 193 probe.
 194
 195 =item Cache Managers
 196
 197 This screen displays Cache Manager statistics for each client machine
 198 being monitored. It highlights statistics that have exceeded their
 199 thresholds, and identifies machines that failed to respond to the last
 200 probe.
 201
 202 =back
 203
 204 Fields at the corners of every screen display the following information:
 205
 206 =over 4
 207
 208 =item *
 209
 210 In the top left corner, the program name and version number.
 211
 212 =item *
 213
 214 In the top right corner, the screen name, current and total page numbers,
 215 and current and total column numbers. The page number (for example, C<p. 1
 216 of 3>) indicates the index of the current page and the total number of
 217 (vertical) pages over which data is displayed. The column number (for
 218 example, C<c. 1 of 235>) indicates the index of the current leftmost
 219 column and the total number of columns in which data appears. (The symbol
 220 C<<<< >>> >>>> indicates that there is additional data to the right; the
 221 symbol C<<<< <<< >>>> indicates that there is additional data to the
 222 left.)
 223
 224 =item *
 225
 226 In the bottom left corner, a list of the available commands. Enter the
 227 first letter in the command name to run that command. Only the currently
 228 possible options appear; for example, if there is only one page of data,
 229 the C<next> and C<prev> commands, which scroll the screen up and down
 230 respectively, do not appear. For descriptions of the commands, see the
 231 following section about navigating the display screens.
 232
 233 =item *
 234
 235 In the bottom right corner, the C<probes> field reports how many times the
 236 program has probed File Servers (C<fs>), Cache Managers (C<cm>), or
 237 both. The counts for File Servers and Cache Managers can differ. The
 238 C<freq> field reports how often the program sends probes.
 239
 240 =back
 241
 242 =head2 Navigating the afsmonitor Display Screens
 243
 244 As noted, the lower left hand corner of every display screen displays the
 245 names of the commands currently available for moving to alternate screens,
 246 which can either be a different type or display more statistics or
 247 machines of the current type. To execute a command, press the lowercase
 248 version of the first letter in its name. Some commands also have an
 249 uppercase version that has a somewhat different effect, as indicated in
 250 the following list.
 251
 252 =over 4
 253
 254 =item C<cm>
 255
 256 Switches to the C<Cache Managers> screen. Available only on the C<System
 257 Overview> and C<File Servers> screens.
 258
 259 =item C<fs>
 260
 261 Switches to the C<File Servers> screen. Available only on the C<System
 262 Overview> and the C<Cache Managers> screens.
 263
 264 =item C<left>
 265
 266 Scrolls horizontally to the left, to access the data columns situated to
 267 the left of the current set. Available when the C<<<< <<< >>>> symbol
 268 appears at the top left of the screen. Press uppercase C<L> to scroll
 269 horizontally all the way to the left (to display the first set of data
 270 columns).
 271
 272 =item C<next>
 273
 274 Scrolls down vertically to the next page of machine names.  Available when
 275 there are two or more pages of machines and the final page is not
 276 currently displayed. Press uppercase C<N> to scroll to the final page.
 277
 278 =item C<oview>
 279
 280 Switches to the C<System Overview> screen. Available only on the C<Cache
 281 Managers> and C<File Servers> screens.
 282
 283 =item C<prev>
 284
 285 Scrolls up vertically to the previous page of machine names.  Available
 286 when there are two or more pages of machines and the first page is not
 287 currently displayed. Press uppercase C<N> to scroll to the first page.
 288
 289 =item C<right>
 290
 291 Scrolls horizontally to the right, to access the data columns situated to
 292 the right of the current set. This command is available when the C<<<< >>>
 293 >>>> symbol appears at the upper right of the screen. Press uppercase C<R>
 294 to scroll horizontally all the way to the right (to display the final set
 295 of data columns).
 296
 297 =back
 298
 299 =head2 The System Overview Screen
 300
 301 The C<System Overview> screen appears automatically as the B<afsmonitor>
 302 program initializes. This screen displays the status of as many File
 303 Server and Cache Manager processes as can fit in the current window;
 304 scroll down to access additional information.
 305
 306 The information on this screen is split into File Server information on
 307 the left and Cache Manager information on the right. The header for each
 308 grouping reports two pieces of information:
 309
 310 =over 4
 311
 312 =item *
 313
 314 The number of machines on which the program is monitoring the indicated
 315 process.
 316
 317 =item *
 318
 319 The number of alerts and the number of machines affected by them (an
 320 I<alert> means that a statistic has exceeded its threshold or a process
 321 failed to respond to the last probe).
 322
 323 =back
 324
 325 A list of the machines being monitored follows. If there are any alerts on
 326 a machine, the number of them appears in square brackets to the left of
 327 the hostname. If a process failed to respond to the last probe, the
 328 letters C<PF> (probe failure) appear in square brackets to the left of the
 329 hostname.
 330
 331 =head2 The File Servers Screen
 332
 333 The C<File Servers> screen displays the values collected at the most
 334 recent probe for File Server statistics.
 335
 336 A summary line at the top of the screen (just below the standard program
 337 version and screen title blocks) specifies the number of monitored File
 338 Servers, the number of alerts, and the number of machines affected by the
 339 alerts.
 340
 341 The first column always displays the hostnames of the machines running the
 342 monitored File Servers.
 343
 344 To the right of the hostname column appear as many columns of statistics
 345 as can fit within the current width of the display screen or window; each
 346 column requires space for 10 characters. The name of the statistic appears
 347 at the top of each column. If the File Server on a machine did not respond
 348 to the most recent probe, a pair of dashes (C<-->) appears in each
 349 column. If a value exceeds its configured threshold, it is highlighted in
 350 reverse video. If a value is too large to fit into the allotted column
 351 width, it overflows into the next row in the same column.
 352
 353 =head2 The Cache Managers Screen
 354
 355 The C<Cache Managers> screen displays the values collected at the most
 356 recent probe for Cache Manager statistics.
 357
 358 A summary line at the top of the screen (just below the standard program
 359 version and screen title blocks) specifies the number of monitored Cache
 360 Managers, the number of alerts, and the number of machines affected by the
 361 alerts.
 362
 363 The first column always displays the hostnames of the machines running the
 364 monitored Cache Managers.
 365
 366 To the right of the hostname column appear as many columns of statistics
 367 as can fit within the current width of the display screen or window; each
 368 column requires space for 10 characters. The name of the statistic appears
 369 at the top of each column. If the Cache Manager on a machine did not
 370 respond to the most recent probe, a pair of dashes (C<-->) appears in each
 371 column. If a value exceeds its configured threshold, it is highlighted in
 372 reverse video. If a value is too large to fit into the allotted column
 373 width, it overflows into the next row in the same column.
 374
 375 =head2 Writing to an Output File
 376
 377 Include the B<-output> argument to name the file into which the
 378 B<afsmonitor> program writes all of the statistics it collects.  The
 379 output file can be useful for tracking performance over long periods of
 380 time, and enables the administrator to apply post-processing techniques
 381 that reveal system trends. The AFS distribution does not include any
 382 post-processing programs.
 383
 384 The output file is in ASCII format and records the same information as the
 385 C<File Server> and C<Cache Manager> display screens.  Each line in the
 386 file uses the following format to record the time at which the
 387 B<afsmonitor> program gathered the indicated statistic from the Cache
 388 Manager (C<CM>) or File Server (C<FS>) running on the machine called
 389 I<host_name>. If a probe failed, the error code C<-1> appears in the
 390 I<statistic> field.
 391
 392    <time>  <host_name>  CM|FS   <statistic>
 393
 394 If the administrator usually reviews the output file manually, rather than
 395 using it as input to an automated analysis program or script, including
 396 the B<-detail> flag formats the data in a more easily readable form.
 397
 398 =head1 EXAMPLES
 399
 400 For examples of commands, display screens, and configuration files, see
 401 the section about the B<afsmonitor> program in the I<IBM AFS
 402 Administration Guide>.
 403
 404 =head1 PRIVILEGE REQUIRED
 405
 406 None
 407
 408 =head1 SEE ALSO
 409
 410 L<afsmonitor(5)>
 411 L<fstrace(8)>,
 412 L<scout(1)>
 413
 414 =head1 COPYRIGHT
 415
 416 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 417
 418 This documentation is covered by the IBM Public License Version 1.0.  It was
 419 converted from HTML to POD by software written by Chas Williams and Russ
 420 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.