doc/man-pages/pod1/afsmonitor.pod

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