[OpenAFS-Doc] doc updates: volume, partition and directory limits. fileserver -abortthreshold added

[Jason Edgecombe]

This is a multi-part message in MIME format.
--------------030108080708090306000302
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Here are some updates to the documentation.


I added the 2TB volume & partition limits to the fileserver, vos, 
vos_create, vos_move, and vos_copy man pages.
I added the directory limits to the fileserver man page and added an 
explanation of the -aborttheshold option.


Enjoy,
Jason

--------------030108080708090306000302
Content-Type: text/plain; x-mac-type="0"; x-mac-creator="0";
 name="docs.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="docs.diff"

Index: doc/man-pages/pod1/vos.pod
===================================================================
RCS file: /cvs/openafs/doc/man-pages/pod1/vos.pod,v
retrieving revision 1.6
diff -u -r1.6 vos.pod
--- doc/man-pages/pod1/vos.pod	29 Nov 2007 03:30:41 -0000	1.6
+++ doc/man-pages/pod1/vos.pod	19 Jan 2008 17:21:16 -0000
@@ -94,6 +94,17 @@
 
 =back
 
+=head1 CAUTIONS
+
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
+
 =head1 OPTIONS
 
 The following arguments and flags are available on many commands in the
Index: doc/man-pages/pod1/vos_copy.pod
===================================================================
RCS file: /cvs/openafs/doc/man-pages/pod1/vos_copy.pod,v
retrieving revision 1.2
diff -u -r1.2 vos_copy.pod
--- doc/man-pages/pod1/vos_copy.pod	25 Dec 2007 22:22:23 -0000	1.2
+++ doc/man-pages/pod1/vos_copy.pod	19 Jan 2008 17:21:16 -0000
@@ -25,6 +25,17 @@
 equivalent to B<vos dump> followed by B<vos restore>, but doesn't require
 the volume be stored locally by the client.
 
+=head1 CAUTIONS
+
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
+
 =head1 OPTIONS
 
 =over 4
Index: doc/man-pages/pod1/vos_create.pod
===================================================================
RCS file: /cvs/openafs/doc/man-pages/pod1/vos_create.pod,v
retrieving revision 1.5
diff -u -r1.5 vos_create.pod
--- doc/man-pages/pod1/vos_create.pod	11 Nov 2007 22:54:57 -0000	1.5
+++ doc/man-pages/pod1/vos_create.pod	19 Jan 2008 17:21:16 -0000
@@ -60,6 +60,17 @@
 The volume is empty when created. To access it via the Cache Manager,
 mount it in the file space by using the B<fs mkmount> command.
 
+=head1 CAUTIONS
+
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
+
 =head1 OPTIONS
 
 =over 4
Index: doc/man-pages/pod1/vos_move.pod
===================================================================
RCS file: /cvs/openafs/doc/man-pages/pod1/vos_move.pod,v
retrieving revision 1.6
diff -u -r1.6 vos_move.pod
--- doc/man-pages/pod1/vos_move.pod	25 Dec 2007 22:15:07 -0000	1.6
+++ doc/man-pages/pod1/vos_move.pod	19 Jan 2008 17:21:16 -0000
@@ -86,6 +86,15 @@
 To confirm termination of the operation, press Ctrl-C a second time; press
 any other key to continue the operation.
 
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
+
 =head1 OPTIONS
 
 =over 4
Index: doc/man-pages/pod8/fileserver.pod
===================================================================
RCS file: /cvs/openafs/doc/man-pages/pod8/fileserver.pod,v
retrieving revision 1.10
diff -u -r1.10 fileserver.pod
--- doc/man-pages/pod8/fileserver.pod	25 Dec 2007 22:02:19 -0000	1.10
+++ doc/man-pages/pod8/fileserver.pod	19 Jan 2008 17:21:16 -0000
@@ -7,11 +7,12 @@
 =for html
 <div class="synopsis">
 
-B<fileserver> S<<< [B<-d> <I<debug level>>] >>>
+B<fileserver> S<<< [B<-auditlog> <I<path to log file>>] >>>
+    S<<< [B<-d> <I<debug level>>] >>>
     S<<< [B<-p> <I<number of processes>>] >>>
     S<<< [B<-spare> <I<number of spare blocks>>] >>>
     S<<< [B<-pctspare> <I<percentage spare>>] >>> S<<< [B<-b> <I<buffers>>] >>>
-    S<<< [B<-l> <I<large vnodes>>] >>> S<<< [B<-s> <I<small nodes>>] >>>
+    S<<< [B<-l> <I<large vnodes>>] >>> S<<< [B<-s> <I<small vnodes>>] >>>
     S<<< [B<-vc> <I<volume cachesize>>] >>> S<<< [B<-w> <I<call back wait interval>>] >>>
     S<<< [B<-cb> <I<number of call backs>>] >>> [B<-banner>] [B<-novbc>]
     S<<< [B<-implicit> <I<admin mode bits: rlidwka>>] >>> [B<-readonly>]
@@ -27,7 +28,6 @@
     S<<< [B<-udpsize> <I<size of socket buffer in bytes>>] >>>
     S<<< [B<-sendsize> <I<size of send buffer in bytes>>] >>>
     S<<< [B<-abortthreshold> <I<abort threshold>>] >>>
-    S<<< [B<-auditlog> <I<path to log file>>] >>>
     [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
 
 =for html
@@ -188,7 +188,7 @@
 =head1 CAUTIONS
 
 Do not use the B<-k> and B<-w> arguments, which are intended for use
-by the AFS Development group only. Changing them from their default
+by the OpenAFS developers only. Changing them from their default
 values can result in unpredictable File Server behavior.  In any case,
 on many operating systems the File Server uses native threads rather
 than the LWP threads, so using the B<-k> argument to set the number of
@@ -202,6 +202,27 @@
 and B<-lock> options, appear in the output generated by the B<-help>
 option only on the relevant system type.
 
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
+
+The maximum number of directory entries is 64,000 if all of the
+entries have names that are 15 characters or less in length. A name
+that is 15 characters long requires the use of only one block in the
+directory. Additional sequential blocks are required to store entries
+with names that are longer than 15 characters. Each additional block
+provides an additional length of 32 characters for the name of the
+entry.
+
+In real world use, the maximum number of objects in an AFS directory
+is usually between 16,000 and 25,000, depending on the average name
+length.
+
 =head1 OPTIONS
 
 =over 4
@@ -389,6 +410,24 @@
 other machines. To display or otherwise access the records, use the Rx
 Monitoring API.
 
+=item B<-abortthreshold>
+
+Sets the abort threshold, which is triggered when an AFS client sends
+a number of FetchStatus requests in a row and all of them fail due to
+access control or some other error. When the abort threshold is
+reached, the file server starts to slow down the responses to the
+problem client in order to reduce the load on the file server.
+
+The throttling behaviour can cause issues especially for some versions
+of the Windows OpenAFS client. When using Windows Explorer to navigate
+the AFS directory tree, directories with only "look" access for the
+current user may load more slowly because of the throttling. This is
+because the Windows OpenAFS client sends FetchStatus calls one at a
+time instead of in bulk like the Unix Open AFS client.
+
+Setting the threshold to 0 disables the throttling behavior. This
+option is available in OpenAFS versions 1.4.1 and later.
+
 =item B<-help>
 
 Prints the online help for this command. All other valid options are

--------------030108080708090306000302--