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