doc/man-pages/pod8/fileserver.pod

   1 =head1 NAME
   2
   3 fileserver - Initializes the File Server component of the fs process
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fileserver> S<<< [B<-auditlog> <I<path to log file>>] >>>
  11     S<<< [B<-d> <I<debug level>>] >>>
  12     S<<< [B<-p> <I<number of processes>>] >>>
  13     S<<< [B<-spare> <I<number of spare blocks>>] >>>
  14     S<<< [B<-pctspare> <I<percentage spare>>] >>>
  15     S<<< [B<-b> <I<buffers>>] >>>
  16     S<<< [B<-l> <I<large vnodes>>] >>>
  17     S<<< [B<-s> <I<small vnodes>>] >>>
  18     S<<< [B<-vc> <I<volume cachesize>>] >>>
  19     S<<< [B<-w> <I<call back wait interval>>] >>>
  20     S<<< [B<-cb> <I<number of call backs>>] >>>
  21     S<<< [B<-banner>] >>>
  22     S<<< [B<-novbc>] >>>
  23     S<<< [B<-implicit> <I<admin mode bits: rlidwka>>] >>>
  24     S<<< [B<-readonly>] >>>
  25     S<<< [B<-hr> <I<number of hours between refreshing the host cps>>] >>>
  26     S<<< [B<-busyat> <I<< redirect clients when queue > n >>>] >>>
  27     S<<< [B<-nobusy>] >>>
  28     S<<< [B<-rxpck> <I<number of rx extra packets>>] >>>
  29     S<<< [B<-rxdbg>] >>>
  30     S<<< [B<-rxdbge>] >>>
  31     S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
  32     S<<< [B<-nojumbo> >>>
  33     S<<< [B<-jumbo> >>>
  34     S<<< [B<-rxbind> >>>
  35     S<<< [B<-allow-dotted-principals>] >>>
  36     S<<< [B<-L>] >>>
  37     S<<< [B<-S>] >>>
  38     S<<< [B<-k> <I<stack size>>] >>>
  39     S<<< [B<-realm> <I<Kerberos realm name>>] >>>
  40     S<<< [B<-udpsize> <I<size of socket buffer in bytes>>] >>>
  41     S<<< [B<-sendsize> <I<size of send buffer in bytes>>] >>>
  42     S<<< [B<-abortthreshold> <I<abort threshold>>] >>>
  43     S<<< [B<-enable_peer_stats>] >>>
  44     S<<< [B<-enable_process_stats>] >>>
  45     S<<< [B<-syslog> [<I< loglevel >>]] >>>
  46     S<<< [B<-mrafslogs>] >>>
  47     S<<< [B<-saneacls>] >>>
  48     S<<< [B<-help>] >>>
  49     S<<< [B<-fs-state-dont-save>] >>>
  50     S<<< [B<-fs-state-dont-restore>] >>>
  51     S<<< [B<-fs-state-verify>] (none | save | restore | both)] >>>
  52     S<<< [B<-vhashsize> <I<log(2) of number of volume hash buckets>>] >>>
  53     S<<< [B<-vlrudisable>] >>>
  54     S<<< [B<-vlruthresh> <I<minutes before eligibility for soft detach>>] >>>
  55     S<<< [B<-vlruinterval> <I<seconds between VLRU scans>>] >>>
  56     S<<< [B<-vlrumax> <I<max volumes to soft detach in one VLRU scan>>] >>>
  57     S<<< [B<-vattachpar> <I<number of volume attach threads>>] >>>
  58     S<<< [B<-m> <I<min percentage spare in partition>>] >>>
  59     S<<< [B<-lock>] >>>
  60
  61 =for html
  62 </div>
  63
  64 =head1 DESCRIPTION
  65
  66 The B<fileserver> command initializes the File Server component of the
  67 C<fs> process. In the conventional configuration, its binary file is
  68 located in the F</usr/afs/bin> directory on a file server machine.
  69
  70 The B<fileserver> command is not normally issued at the command shell
  71 prompt, but rather placed into a database server machine's
  72 F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
  73 ever issued at the command shell prompt, the issuer must be logged onto a
  74 file server machine as the local superuser C<root>.
  75
  76 The File Server creates the F</usr/afs/logs/FileLog> log file as it
  77 initializes, if the file does not already exist. It does not write a
  78 detailed trace by default, but the B<-d> option may be used to
  79 increase the amount of detail. Use the B<bos getlog> command to
  80 display the contents of the log file.
  81
  82 The command's arguments enable the administrator to control many aspects
  83 of the File Server's performance, as detailed in L<OPTIONS>.  By default
  84 the B<fileserver> command sets values for many arguments that are suitable
  85 for a medium-sized file server machine. To set values suitable for a small
  86 or large file server machine, use the B<-S> or B<-L> flag
  87 respectively. The following list describes the parameters and
  88 corresponding argument for which the B<fileserver> command sets default
  89 values, and the table below summarizes the setting for each of the three
  90 machine sizes.
  91
  92 =over 4
  93
  94 =item *
  95
  96 The maximum number of lightweight processes (LWPs) or pthreads
  97 the File Server uses to handle requests for data; corresponds to the
  98 B<-p> argument. The File Server always uses a minimum of 32 KB of
  99 memory for these processes.
 100
 101 =item *
 102
 103 The maximum number of directory blocks the File Server caches in memory;
 104 corresponds to the B<-b> argument. Each cached directory block (buffer)
 105 consumes 2,092 bytes of memory.
 106
 107 =item *
 108
 109 The maximum number of large vnodes the File Server caches in memory for
 110 tracking directory elements; corresponds to the B<-l> argument. Each large
 111 vnode consumes 292 bytes of memory.
 112
 113 =item *
 114
 115 The maximum number of small vnodes the File Server caches in memory for
 116 tracking file elements; corresponds to the B<-s> argument.  Each small
 117 vnode consumes 100 bytes of memory.
 118
 119 =item *
 120
 121 The maximum volume cache size, which determines how many volumes the File
 122 Server can cache in memory before having to retrieve data from disk;
 123 corresponds to the B<-vc> argument.
 124
 125 =item *
 126
 127 The maximum number of callback structures the File Server caches in
 128 memory; corresponds to the B<-cb> argument. Each callback structure
 129 consumes 16 bytes of memory.
 130
 131 =item *
 132
 133 The maximum number of Rx packets the File Server uses; corresponds to the
 134 B<-rxpck> argument. Each packet consumes 1544 bytes of memory.
 135
 136 =back
 137
 138 The default values are:
 139
 140   Parameter (Argument)               Small (-S)     Medium   Large (-L)
 141   ---------------------------------------------------------------------
 142   Number of LWPs (-p)                        6           9           12
 143   Number of cached dir blocks (-b)          70          90          120
 144   Number of cached large vnodes (-l)       200         400          600
 145   Number of cached small vnodes (-s)       200         400          600
 146   Maximum volume cache size (-vc)          200         400          600
 147   Number of callbacks (-cb)             20,000      60,000       64,000
 148   Number of Rx packets (-rxpck)            100         150          200
 149
 150 To override any of the values, provide the indicated argument (which can
 151 be combined with the B<-S> or B<-L> flag).
 152
 153 The amount of memory required for the File Server varies. The approximate
 154 default memory usage is 751 KB when the B<-S> flag is used (small
 155 configuration), 1.1 MB when all defaults are used (medium configuration),
 156 and 1.4 MB when the B<-L> flag is used (large configuration). If
 157 additional memory is available, increasing the value of the B<-cb> and
 158 B<-vc> arguments can improve File Server performance most directly.
 159
 160 By default, the File Server allows a volume to exceed its quota by 1 MB
 161 when an application is writing data to an existing file in a volume that
 162 is full. The File Server still does not allow users to create new files in
 163 a full volume. To change the default, use one of the following arguments:
 164
 165 =over 4
 166
 167 =item *
 168
 169 Set the B<-spare> argument to the number of extra kilobytes that the File
 170 Server allows as overage. A value of C<0> allows no overage.
 171
 172 =item *
 173
 174 Set the B<-pctspare> argument to the percentage of the volume's quota the
 175 File Server allows as overage.
 176
 177 =back
 178
 179 By default, the File Server implicitly grants the C<a> (administer) and
 180 C<l> (lookup) permissions to system:administrators on the access control
 181 list (ACL) of every directory in the volumes stored on its file server
 182 machine. In other words, the group's members can exercise those two
 183 permissions even when an entry for the group does not appear on an ACL. To
 184 change the set of default permissions, use the B<-implicit> argument.
 185
 186 The File Server maintains a I<host current protection subgroup> (I<host
 187 CPS>) for each client machine from which it has received a data access
 188 request. Like the CPS for a user, a host CPS lists all of the Protection
 189 Database groups to which the machine belongs, and the File Server compares
 190 the host CPS to a directory's ACL to determine in what manner users on the
 191 machine are authorized to access the directory's contents. When the B<pts
 192 adduser> or B<pts removeuser> command is used to change the groups to
 193 which a machine belongs, the File Server must recompute the machine's host
 194 CPS in order to notice the change. By default, the File Server contacts
 195 the Protection Server every two hours to recompute host CPSs, implying
 196 that it can take that long for changed group memberships to become
 197 effective. To change this frequency, use the B<-hr> argument.
 198
 199 The File Server stores volumes in partitions. A partition is a
 200 filesystem or directory on the server machine that is named C</vicepX>
 201 or C</vicepXX> where XX is "a" through "z" or "aa" though "iv". Up to
 202 255 partitions are allowed. The File Server expects that the /vicepXX
 203 directories are each on a dedicated filesystem. The File Server will
 204 only use a /vicepXX if it's a mountpoint for another filesystem,
 205 unless the file C</vicepXX/AlwaysAttach> exists. The data in the
 206 partition is a special format that can only be access using OpenAFS
 207 commands or an OpenAFS client.
 208
 209 The File Server generates the following message when a partition is nearly
 210 full:
 211
 212    No space left on device
 213
 214 This command does not use the syntax conventions of the AFS command
 215 suites. Provide the command name and all option names in full.
 216
 217 =head1 CAUTIONS
 218
 219 Do not use the B<-k> and B<-w> arguments, which are intended for use
 220 by the OpenAFS developers only. Changing them from their default
 221 values can result in unpredictable File Server behavior.  In any case,
 222 on many operating systems the File Server uses native threads rather
 223 than the LWP threads, so using the B<-k> argument to set the number of
 224 LWP threads has no effect.
 225
 226 Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so
 227 causes the File Server to exit, leaving an error message in the
 228 F</usr/afs/logs/FileLog> file.
 229
 230 Options that are available only on some system types, such as the B<-m>
 231 and B<-lock> options, appear in the output generated by the B<-help>
 232 option only on the relevant system type.
 233
 234 Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
 235 and the maximum size of a /vicepX partition on a fileserver is 2^64
 236 kilobytes. The maximum partition size in releases 1.4.7 and earlier is
 237 2 terabytes (2^31 bytes). The maximum partition size for 1.5.x
 238 releases 1.5.34 and earlier is 2 terabytes as well.
 239
 240 The maximum number of directory entries is 64,000 if all of the entries
 241 have names that are 15 octets or less in length. A name that is 15 octets
 242 long requires the use of only one block in the directory. Additional
 243 sequential blocks are required to store entries with names that are longer
 244 than 15 octets. Each additional block provides an additional length of 32
 245 octets for the name of the entry. Note that if file names use an encoding
 246 like UTF-8, a single character may be encoded into multiple octets.
 247
 248 In real world use, the maximum number of objects in an AFS directory
 249 is usually between 16,000 and 25,000, depending on the average name
 250 length.
 251
 252 =head1 OPTIONS
 253
 254 =over 4
 255
 256 =item B<-auditlog> <I<log path>>
 257
 258 Set and enable auditing.
 259
 260 =item B<-d> <I<debug level>>
 261
 262 Sets the detail level for the debugging trace written to the
 263 F</usr/afs/logs/FileLog> file. Provide one of the following values, each
 264 of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>,
 265 and C<125>. The default value of C<0> produces only a few messages.
 266
 267 =item B<-p> <I<number of processes>>
 268
 269 Sets the number of threads (or LWPs) to run. Provide a positive integer.
 270 The File Server creates and uses five threads for special purposes,
 271 in addition to the number specified (but if this argument specifies
 272 the maximum possible number, the File Server automatically uses five
 273 of the threads for its own purposes).
 274
 275 The maximum number of threads can differ in each release of OpenAFS.
 276 Consult the I<OpenAFS Release Notes> for the current release.
 277
 278 =item B<-spare> <I<number of spare blocks>>
 279
 280 Specifies the number of additional kilobytes an application can store in a
 281 volume after the quota is exceeded. Provide a positive integer; a value of
 282 C<0> prevents the volume from ever exceeding its quota. Do not combine
 283 this argument with the B<-pctspare> argument.
 284
 285 =item B<-pctspare> <I<percentage spare>>
 286
 287 Specifies the amount by which the File Server allows a volume to exceed
 288 its quota, as a percentage of the quota. Provide an integer between C<0>
 289 and C<99>. A value of C<0> prevents the volume from ever exceeding its
 290 quota. Do not combine this argument with the B<-spare> argument.
 291
 292 =item B<-b> <I<buffers>>
 293
 294 Sets the number of directory buffers. Provide a positive integer.
 295
 296 =item B<-l> <I<large vnodes>>
 297
 298 Sets the number of large vnodes available in memory for caching directory
 299 elements. Provide a positive integer.
 300
 301 =item B<-s> <I<small nodes>>
 302
 303 Sets the number of small vnodes available in memory for caching file
 304 elements. Provide a positive integer.
 305
 306 =item B<-vc> <I<volume cachesize>>
 307
 308 Sets the number of volumes the File Server can cache in memory.  Provide a
 309 positive integer.
 310
 311 =item B<-w> <I<call back wait interval>>
 312
 313 Sets the interval at which the daemon spawned by the File Server performs
 314 its maintenance tasks. Do not use this argument; changing the default
 315 value can cause unpredictable behavior.
 316
 317 =item B<-cb> <I<number of callbacks>>
 318
 319 Sets the number of callbacks the File Server can track. Provide a positive
 320 integer.
 321
 322 =item B<-banner>
 323
 324 Prints the following banner to F</dev/console> about every 10 minutes.
 325
 326    File Server is running at I<time>.
 327
 328 =item B<-novbc>
 329
 330 Prevents the File Server from breaking the callbacks that Cache Managers
 331 hold on a volume that the File Server is reattaching after the volume was
 332 offline (as a result of the B<vos restore> command, for example). Use of
 333 this flag is strongly discouraged.
 334
 335 =item B<-implicit> <I<admin mode bits>>
 336
 337 Defines the set of permissions granted by default to the
 338 system:administrators group on the ACL of every directory in a volume
 339 stored on the file server machine. Provide one or more of the standard
 340 permission letters (C<rlidwka>) and auxiliary permission letters
 341 (C<ABCDEFGH>), or one of the shorthand notations for groups of permissions
 342 (C<all>, C<none>, C<read>, and C<write>). To review the meaning of the
 343 permissions, see the B<fs setacl> reference page.
 344
 345 =item B<-readonly>
 346
 347 Don't allow writes to this fileserver.
 348
 349 =item B<-hr> <I<number of hours between refreshing the host cps>>
 350
 351 Specifies how often the File Server refreshes its knowledge of the
 352 machines that belong to protection groups (refreshes the host CPSs for
 353 machines). The File Server must update this information to enable users
 354 from machines recently added to protection groups to access data for which
 355 those machines now have the necessary ACL permissions.
 356
 357 =item B<-busyat> <I<< redirect clients when queue > n >>>
 358
 359 Defines the number of incoming RPCs that can be waiting for a response
 360 from the File Server before the File Server returns the error code
 361 C<VBUSY> to the Cache Manager that sent the latest RPC. In response, the
 362 Cache Manager retransmits the RPC after a delay. This argument prevents
 363 the accumulation of so many waiting RPCs that the File Server can never
 364 process them all. Provide a positive integer.  The default value is
 365 C<600>.
 366
 367 =item B<-rxpck> <I<number of rx extra packets>>
 368
 369 Controls the number of Rx packets the File Server uses to store data for
 370 incoming RPCs that it is currently handling, that are waiting for a
 371 response, and for replies that are not yet complete. Provide a positive
 372 integer.
 373
 374 =item B<-rxdbg>
 375
 376 Writes a trace of the File Server's operations on Rx packets to the file
 377 F</usr/afs/logs/rx_dbg>.
 378
 379 =item B<-rxdbge>
 380
 381 Writes a trace of the File Server's operations on Rx events (such as
 382 retransmissions) to the file F</usr/afs/logs/rx_dbg>.
 383
 384 =item B<-rxmaxmtu> <I<bytes>>
 385
 386 Defines the maximum size of an MTU.  The value must be between the
 387 minimum and maximum packet data sizes for Rx.
 388
 389 =item B<-jumbo>
 390
 391 Allows the server to send and receive jumbograms. A jumbogram is
 392 a large-size packet composed of 2 to 4 normal Rx data packets that share
 393 the same header. The fileserver does not use jumbograms by default, as some
 394 routers are not capable of properly breaking the jumbogram into smaller
 395 packets and reassembling them.
 396
 397 =item B<-nojumbo>
 398
 399 Deprecated; jumbograms are disabled by default.
 400
 401 =item B<-rxbind>
 402
 403 Force the fileserver to only bind to one IP address.
 404
 405 =item B<-allow-dotted-principal>
 406
 407 By default, the RXKAD security layer will disallow access by Kerberos
 408 principals with a dot in the first component of their name. This is to avoid
 409 the confusion where principals user/admin and user.admin are both mapped to the
 410 user.admin PTS entry. Sites whose Kerberos realms don't have these collisions
 411 between principal names may disable this check by starting the server
 412 with this option.
 413
 414 =item B<-L>
 415
 416 Sets values for many arguments in a manner suitable for a large file
 417 server machine. Combine this flag with any option except the B<-S> flag;
 418 omit both flags to set values suitable for a medium-sized file server
 419 machine.
 420
 421 =item B<-S>
 422
 423 Sets values for many arguments in a manner suitable for a small file
 424 server machine. Combine this flag with any option except the B<-L> flag;
 425 omit both flags to set values suitable for a medium-sized file server
 426 machine.
 427
 428 =item B<-k> <I<stack size>>
 429
 430 Sets the LWP stack size in units of 1 kilobyte. Do not use this argument,
 431 and in particular do not specify a value less than the default of C<24>.
 432
 433 =item B<-realm> <I<Kerberos realm name>>
 434
 435 Defines the Kerberos realm name for the File Server to use. If this
 436 argument is not provided, it uses the realm name corresponding to the cell
 437 listed in the local F</usr/afs/etc/ThisCell> file.
 438
 439 =item B<-udpsize> <I<size of socket buffer in bytes>>
 440
 441 Sets the size of the UDP buffer, which is 64 KB by default. Provide a
 442 positive integer, preferably larger than the default.
 443
 444 =item B<-sendsize> <I<size of send buffer in bytes>>
 445
 446 Sets the size of the send buffer, which is 16384 bytes by default.
 447
 448 =item B<-abortthreshold> <I<abort threshold>>
 449
 450 Sets the abort threshold, which is triggered when an AFS client sends
 451 a number of FetchStatus requests in a row and all of them fail due to
 452 access control or some other error. When the abort threshold is
 453 reached, the file server starts to slow down the responses to the
 454 problem client in order to reduce the load on the file server.
 455
 456 The throttling behaviour can cause issues especially for some versions
 457 of the Windows OpenAFS client. When using Windows Explorer to navigate
 458 the AFS directory tree, directories with only "look" access for the
 459 current user may load more slowly because of the throttling. This is
 460 because the Windows OpenAFS client sends FetchStatus calls one at a
 461 time instead of in bulk like the Unix Open AFS client.
 462
 463 Setting the threshold to 0 disables the throttling behavior. This
 464 option is available in OpenAFS versions 1.4.1 and later.
 465
 466 =item B<-enable_peer_stats>
 467
 468 Activates the collection of Rx statistics and allocates memory for their
 469 storage. For each connection with a specific UDP port on another machine,
 470 a separate record is kept for each type of RPC (FetchFile, GetStatus, and
 471 so on) sent or received. To display or otherwise access the records, use
 472 the Rx Monitoring API.
 473
 474 =item B<-enable_process_stats>
 475
 476 Activates the collection of Rx statistics and allocates memory for their
 477 storage. A separate record is kept for each type of RPC (FetchFile,
 478 GetStatus, and so on) sent or received, aggregated over all connections to
 479 other machines. To display or otherwise access the records, use the Rx
 480 Monitoring API.
 481
 482 =item B<-syslog [<loglevel>]
 483
 484 Use syslog instead of the normal logging location for the fileserver
 485 process.  If provided, log messages are at <loglevel> instead of the
 486 default LOG_USER.
 487
 488 =item B<-mrafslogs>
 489
 490 Use MR-AFS (Multi-Resident) style logging.  This option is deprecated.
 491
 492 =item B<-saneacls>
 493
 494 Offer the SANEACLS capability for the fileserver.  This option is
 495 currently unimplemented.
 496
 497 =item B<-help>
 498
 499 Prints the online help for this command. All other valid options are
 500 ignored.
 501
 502 =item B<-fs-state-dont-save>
 503
 504 When present, fileserver state will not be saved during shutdown.  Default
 505 is to save state.
 506
 507 This option is only supported by the demand-attach file server.
 508
 509 =item B<-fs-state-dont-restore>
 510
 511 When present, fileserver state will not be restored during startup.
 512 Default is to restore state on startup.
 513
 514 This option is only supported by the demand-attach file server.
 515
 516 =item B<-fs-state-verify> (none | save | restore | both)
 517
 518 This argument controls the behavior of the state verification mechanism.
 519 A value of C<none> turns off all verification.  A value of C<save> only
 520 performs the verification steps prior to saving state to disk.  A value
 521 of C<restore> only performs the verification steps after restoring state
 522 from disk.  A value of C<both> performs all verifications steps both
 523 prior to save and following a restore.
 524
 525 The default is C<both>.
 526
 527 This option is only supported by the demand-attach file server.
 528
 529 =item B<-vhashsize <I<size>>
 530
 531 The log(2) number of of volume hash buckets.  Default is 8 (i.e., by
 532 default, there are 2^8 = 256 volume hash buckets).
 533
 534 This option is only supported by the demand-attach file server.
 535
 536 =item B<-vlruthresh <I<minutes>>
 537
 538 The number of minutes of inactivity before a volume is eligible for soft
 539 detachment.  Default is 120 minutes.
 540
 541 This option is only supported by the demand-attach file server.
 542
 543 =item B<-vlruinterval <I<seconds>>
 544
 545 The number of seconds between VLRU candidate queue scan.  The default is
 546 120 seconds.
 547
 548 This option is only supported by the demand-attach file server.
 549
 550 =item B<-vlrumax <I<positive integer>>
 551
 552 The maximum number of volumes which can be soft detached in a single pass
 553 of the scanner.  Default is 8 volumes.
 554
 555 This option is only supported by the demand-attach file server.
 556
 557 =item B<-vattachpar> <I<number of volume attach threads>>
 558
 559 The number of threads assigned to attach and detach volumes.  The default
 560 is 1.  Warning: many of the I/O parallism features of Demand-Attach
 561 Fileserver are turned off when the number of volume attach threads is only
 562 1.
 563
 564 This option is only meaningful for a file server built with pthreads
 565 support.
 566
 567 =item B<-m> <I<min percentage spare in partition>>
 568
 569 Specifies the percentage of each AFS server partition that the AIX version
 570 of the File Server creates as a reserve. Specify an integer value between
 571 C<0> and C<30>; the default is 8%. A value of C<0> means that the
 572 partition can become completely full, which can have serious negative
 573 consequences.  This option is not supported on platforms other than AIX.
 574
 575 =item B<-lock>
 576
 577 Prevents any portion of the fileserver binary from being paged (swapped)
 578 out of memory on a file server machine running the IRIX operating system.
 579 This option is not supported on platforms other than IRIX.
 580
 581 =back
 582
 583 =head1 EXAMPLES
 584
 585 The following B<bos create> command creates an fs process on the file
 586 server machine C<fs2.abc.com> that uses the large configuration size, and
 587 allows volumes to exceed their quota by 10%. Type the command on a single
 588 line:
 589
 590    % bos create -server fs2.abc.com -instance fs -type fs \
 591                 -cmd "/usr/afs/bin/fileserver -pctspare 10 \
 592                 -L" /usr/afs/bin/volserver /usr/afs/bin/salvager
 593
 594
 595 =head1 TROUBLESHOOTING
 596
 597 Sending process signals to the File Server Process can change its
 598 behavior in the following ways:
 599
 600   Process          Signal       OS     Result
 601   ---------------------------------------------------------------------
 602
 603   File Server      XCPU        Unix    Prints a list of client IP
 604                                        Addresses.
 605
 606   File Server      USR2      Windows   Prints a list of client IP
 607                                        Addresses.
 608
 609   File Server      POLL        HPUX    Prints a list of client IP
 610                                        Addresses.
 611
 612   Any server       TSTP        Any     Increases Debug level by a power
 613                                        of 5 -- 1,5,25,125, etc.
 614                                        This has the same effect as the
 615                                        -d XXX command-line option.
 616
 617   Any Server       HUP         Any     Resets Debug level to 0
 618
 619   File Server      TERM        Any     Run minor instrumentation over
 620                                        the list of descriptors.
 621
 622   Other Servers    TERM        Any     Causes the process to quit.
 623
 624   File Server      QUIT        Any     Causes the File Server to Quit.
 625                                        Bos Server knows this.
 626
 627 The basic metric of whether an AFS file server is doing well is the number
 628 of connections waiting for a thread,
 629 which can be found by running the following command:
 630
 631    % rxdebug <server> | grep waiting_for | wc -l
 632
 633 Each line returned by C<rxdebug> that contains the text "waiting_for"
 634 represents a connection that's waiting for a file server thread.
 635
 636 If the blocked connection count is ever above 0, the server is having
 637 problems replying to clients in a timely fashion.  If it gets above 10,
 638 roughly, there will be noticable slowness by the user.  The total number of
 639 connections is a mostly irrelevant number that goes essentially
 640 monotonically for as long as the server has been running and then goes back
 641 down to zero when it's restarted.
 642
 643 The most common cause of blocked connections rising on a server is some
 644 process somewhere performing an abnormal number of accesses to that server
 645 and its volumes.  If multiple servers have a blocked connection count, the
 646 most likely explanation is that there is a volume replicated between those
 647 servers that is absorbing an abnormally high access rate.
 648
 649 To get an access count on all the volumes on a server, run:
 650
 651    % vos listvol <server> -long
 652
 653 and save the output in a file.  The results will look like a bunch of B<vos
 654 examine> output for each volume on the server.  Look for lines like:
 655
 656    40065 accesses in the past day (i.e., vnode references)
 657
 658 and look for volumes with an abnormally high number of accesses.  Anything
 659 over 10,000 is fairly high, but some volumes like root.cell and other
 660 volumes close to the root of the cell will have that many hits routinely.
 661 Anything over 100,000 is generally abnormally high.  The count resets about
 662 once a day.
 663
 664 Another approach that can be used to narrow the possibilities for a
 665 replicated volume, when multiple servers are having trouble, is to find all
 666 replicated volumes for that server.  Run:
 667
 668    % vos listvldb -server <server>
 669
 670 where <server> is one of the servers having problems to refresh the VLDB
 671 cache, and then run:
 672
 673    % vos listvldb -server <server> -part <partition>
 674
 675 to get a list of all volumes on that server and partition, including every
 676 other server with replicas.
 677
 678 Once the volume causing the problem has been identified, the best way to
 679 deal with the problem is to move that volume to another server with a low
 680 load or to stop any runaway programs that are accessing that volume
 681 unnecessarily.  Often the volume will be enough information to tell what's
 682 going on.
 683
 684 If you still need additional information about who's hitting that server,
 685 sometimes you can guess at that information from the failed callbacks in the
 686 F<FileLog> log in F</var/log/afs> on the server, or from the output of:
 687
 688    % /usr/afsws/etc/rxdebug <server> -rxstats
 689
 690 but the best way is to turn on debugging output from the file server.
 691 (Warning: This generates a lot of output into FileLog on the AFS server.)
 692 To do this, log on to the AFS server, find the PID of the fileserver
 693 process, and do:
 694
 695     kill -TSTP <pid>
 696
 697 where <pid> is the PID of the file server process.  This will raise the
 698 debugging level so that you'll start seeing what people are actually doing
 699 on the server.  You can do this up to three more times to get even more
 700 output if needed.  To reset the debugging level back to normal, use (The
 701 following command will NOT terminate the file server):
 702
 703     kill -HUP <pid>
 704
 705 The debugging setting on the File Server should be reset back to normal when
 706 debugging is no longer needed.  Otherwise, the AFS server may well fill its
 707 disks with debugging output.
 708
 709 The lines of the debugging output that are most useful for debugging load
 710 problems are:
 711
 712     SAFS_FetchStatus,  Fid = 2003828163.77154.82248, Host 171.64.15.76
 713     SRXAFS_FetchData, Fid = 2003828163.77154.82248
 714
 715 (The example above is partly truncated to highlight the interesting
 716 information).  The Fid identifies the volume and inode within the volume;
 717 the volume is the first long number.  So, for example, this was:
 718
 719    % vos examine 2003828163
 720    pubsw.matlab61                   2003828163 RW    1040060 K  On-line
 721        afssvr5.Stanford.EDU /vicepa
 722        RWrite 2003828163 ROnly 2003828164 Backup 2003828165
 723        MaxQuota    3000000 K
 724        Creation    Mon Aug  6 16:40:55 2001
 725        Last Update Tue Jul 30 19:00:25 2002
 726        86181 accesses in the past day (i.e., vnode references)
 727
 728        RWrite: 2003828163    ROnly: 2003828164    Backup: 2003828165
 729        number of sites -> 3
 730           server afssvr5.Stanford.EDU partition /vicepa RW Site
 731           server afssvr11.Stanford.EDU partition /vicepd RO Site
 732           server afssvr5.Stanford.EDU partition /vicepa RO Site
 733
 734 and from the Host information one can tell what system is accessing that
 735 volume.
 736
 737 Note that the output of L<vos_examine(1)> also includes the access count, so
 738 once the problem has been identified, vos examine can be used to see if the
 739 access count is still increasing.  Also remember that you can run vos
 740 examine on the read-only replica (e.g., pubsw.matlab61.readonly) to see the
 741 access counts on the read-only replica on all of the servers that it's
 742 located on.
 743
 744 =head1 PRIVILEGE REQUIRED
 745
 746 The issuer must be logged in as the superuser C<root> on a file server
 747 machine to issue the command at a command shell prompt.  It is conventional
 748 instead to create and start the process by issuing the B<bos create>
 749 command.
 750
 751 =head1 SEE ALSO
 752
 753 L<BosConfig(5)>,
 754 L<FileLog(5)>,
 755 L<bos_create(8)>,
 756 L<bos_getlog(8)>,
 757 L<fs_setacl(1)>,
 758 L<salvager(8)>,
 759 L<volserver(8)>,
 760 L<vos_examine(1)>
 761
 762 =head1 COPYRIGHT
 763
 764 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 765
 766 This documentation is covered by the IBM Public License Version 1.0.  It was
 767 converted from HTML to POD by software written by Chas Williams and Russ
 768 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.