man-page-fileserver-update-20080311
authorSteven Jenkins <steven.jenkins@gmail.com>
Wed, 12 Mar 2008 01:28:00 +0000 (01:28 +0000)
committerRuss Allbery <rra@stanford.edu>
Wed, 12 Mar 2008 01:28:00 +0000 (01:28 +0000)
LICENSE IPL10

Update the fileserver documentation for demand-attach and add documentation
of other missing options and notes where some options are only applicable
with particular builds.

doc/man-pages/pod8/fileserver.pod

index 50f3463..b3813ec 100644 (file)
@@ -11,25 +11,51 @@ 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 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>]
+    S<<< [B<-pctspare> <I<percentage spare>>] >>>
+    S<<< [B<-b> <I<buffers>>] >>>
+    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>>] >>>
+    S<<< [B<-banner>] >>>
+    S<<< [B<-novbc>] >>>
+    S<<< [B<-implicit> <I<admin mode bits: rlidwka>>] >>>
+    S<<< [B<-readonly>] >>>
     S<<< [B<-hr> <I<number of hours between refreshing the host cps>>] >>>
     S<<< [B<-busyat> <I<< redirect clients when queue > n >>>] >>>
-    [B<-nobusy>] S<<< [B<-rxpck> <I<number of rx extra packets>>] >>>
-    [B<-rxdbg>] [B<-rxdbge>] S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
-    [B<-allow-dotted-principal>]
-    S<<< [B<-rxbind> <I<address to bind the Rx socket to>>] >>>
-    S<<< [B<-vattachpar> <I<number of volume attach threads>>] >>>
-    S<<< [B<-m> <I<min percentage spare in partition>>] >>>
-    [B<-lock>] [B<-L>] [B<-S>] S<<< [B<-k> <I<stack size>>] >>>
+    S<<< [B<-nobusy>] >>>
+    S<<< [B<-rxpck> <I<number of rx extra packets>>] >>>
+    S<<< [B<-rxdbg>] >>>
+    S<<< [B<-rxdbge>] >>>
+    S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
+    S<<< [B<-nojumbo> >>>
+    S<<< [B<-rxbind> >>>
+    S<<< [B<-allow-dotted-principals>] >>>
+    S<<< [B<-L>] >>>
+    S<<< [B<-S>] >>>
+    S<<< [B<-k> <I<stack size>>] >>>
     S<<< [B<-realm> <I<Kerberos realm name>>] >>>
     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>>] >>>
-    [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
+    S<<< [B<-enable_peer_stats>] >>>
+    S<<< [B<-enable_process_stats>] >>>
+    S<<< [B<-syslog> [<I< loglevel >>]] >>>
+    S<<< [B<-mrafslogs>] >>>
+    S<<< [B<-saneacls>] >>>
+    S<<< [B<-help>] >>>
+    S<<< [B<-fs-state-dont-save>] >>>
+    S<<< [B<-fs-state-dont-restore>] >>>
+    S<<< [B<-fs-state-verify>] (none | save | restore | both)] >>>
+    S<<< [B<-vhashsize> <I<log(2) of number of volume hash buckets>>] >>>
+    S<<< [B<-vlrudisable>] >>>
+    S<<< [B<-vlruthresh> <I<minutes before unused volumes become eligible for soft detach>>] >>>
+    S<<< [B<-vlruinterval> <I<seconds between VLRU scans>>] >>>
+    S<<< [B<-vlrumax> <I<max volumes to soft detach in one VLRU scan>>] >>>
+    S<<< [B<-vattachpar> <I<number of volume attach threads>>] >>>
+    S<<< [B<-m> <I<min percentage spare in partition>>] >>>
+    S<<< [B<-lock>] >>>
 
 =for html
 </div>
@@ -66,9 +92,10 @@ machine sizes.
 
 =item *
 
-The maximum number of lightweight processes (LWPs) the File Server uses to
-handle requests for data; corresponds to the B<-p> argument. The File
-Server always uses a minimum of 32 KB of memory for these processes.
+The maximum number of lightweight processes (LWPs) or pthreads 
+the File Server uses to handle requests for data; corresponds to the 
+B<-p> argument. The File Server always uses a minimum of 32 KB of 
+memory for these processes.
 
 =item *
 
@@ -204,13 +231,13 @@ 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
+and the maximum size of a /vicepX partition on a fileserver is 2^64 
+kilobytes. The fileserver will not report an error when it has access
+to a partition larger than 2^64 kilobytes, but it will probably fail if
+the administrator attempts to use more than 2^64 kilobytes 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.
+partitions larger than 2^64 kilobytes.
 
 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
@@ -241,11 +268,11 @@ and C<125>. The default value of C<0> produces only a few messages.
 
 =item B<-p> <I<number of processes>>
 
-Sets the number of threads to run. Provide a positive integer. The File
-Server creates and uses five threads for special purposes, in addition to
-the number specified (but if this argument specifies the maximum possible
-number, the File Server automatically uses five of the threads for its own
-purposes).
+Sets the number of threads (or LWPs) to run. Provide a positive integer. 
+The File Server creates and uses five threads for special purposes, 
+in addition to the number specified (but if this argument specifies 
+the maximum possible number, the File Server automatically uses five 
+of the threads for its own purposes).
 
 The maximum number of threads can differ in each release of AFS.  Consult
 the I<IBM AFS Release Notes> for the current release.
@@ -317,6 +344,10 @@ permission letters (C<rlidwka>) and auxiliary permission letters
 (C<all>, C<none>, C<read>, and C<write>). To review the meaning of the
 permissions, see the B<fs setacl> reference page.
 
+=item B<-readonly>
+
+Don't allow writes to this fileserver.
+
 =item B<-hr> <I<number of hours between refreshing the host cps>>
 
 Specifies how often the File Server refreshes its knowledge of the
@@ -347,11 +378,24 @@ integer.
 Writes a trace of the File Server's operations on Rx packets to the file
 F</usr/afs/logs/rx_dbg>.
 
-=item F<-rxdbge>
+=item B<-rxdbge>
 
 Writes a trace of the File Server's operations on Rx events (such as
 retransmissions) to the file F</usr/afs/logs/rx_dbg>.
 
+=item B<-rxmaxmtu> <I<bytes>>
+
+Defines the maximum size of an MTU.  The value must be between the
+minimum and maximum packet data sizes for Rx.
+
+=item B<-nojumbo>
+
+Do not send, and do not accept, jumbograms.
+
+=item B<-rxbind>
+
+Force the fileserver to only bind to one IP address.
+
 =item B<-allow-dotted-principal>
 
 By default, the RXKAD security layer will disallow access by Kerberos
@@ -361,19 +405,6 @@ user.admin PTS entry. Sites whose Kerberos realms don't have these collisions
 between principal names may disable this check by starting the server
 with this option.
 
-=item F<-m> <I<min percentage spare in partition>>
-
-Specifies the percentage of each AFS server partition that the AIX version
-of the File Server creates as a reserve. Specify an integer value between
-C<0> and C<30>; the default is 8%. A value of C<0> means that the
-partition can become completely full, which can have serious negative
-consequences.
-
-=item B<-lock>
-
-Prevents any portion of the fileserver binary from being paged (swapped)
-out of memory on a file server machine running the IRIX operating system.
-
 =item B<-L>
 
 Sets values for many arguments in a manner suitable for a large file
@@ -404,21 +435,9 @@ listed in the local F</usr/afs/etc/ThisCell> file.
 Sets the size of the UDP buffer, which is 64 KB by default. Provide a
 positive integer, preferably larger than the default.
 
-=item B<-enable_peer_stats>
-
-Activates the collection of Rx statistics and allocates memory for their
-storage. For each connection with a specific UDP port on another machine,
-a separate record is kept for each type of RPC (FetchFile, GetStatus, and
-so on) sent or received. To display or otherwise access the records, use
-the Rx Monitoring API.
-
-=item B<-enable_process_stats>
+=item B<-sendsize> <I<size of send buffer in bytes>>
 
-Activates the collection of Rx statistics and allocates memory for their
-storage. A separate record is kept for each type of RPC (FetchFile,
-GetStatus, and so on) sent or received, aggregated over all connections to
-other machines. To display or otherwise access the records, use the Rx
-Monitoring API.
+Sets the size of the send buffer, which is 16384 bytes by default.
 
 =item B<-abortthreshold> <I<abort threshold>>
 
@@ -438,11 +457,121 @@ 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<-enable_peer_stats>
+
+Activates the collection of Rx statistics and allocates memory for their
+storage. For each connection with a specific UDP port on another machine,
+a separate record is kept for each type of RPC (FetchFile, GetStatus, and
+so on) sent or received. To display or otherwise access the records, use
+the Rx Monitoring API.
+
+=item B<-enable_process_stats>
+
+Activates the collection of Rx statistics and allocates memory for their
+storage. A separate record is kept for each type of RPC (FetchFile,
+GetStatus, and so on) sent or received, aggregated over all connections to
+other machines. To display or otherwise access the records, use the Rx
+Monitoring API.
+
+=item B<-syslog [<loglevel>]
+
+Use syslog instead of the normal logging location for the fileserver
+process.  If provided, log messages are at <loglevel> instead of the
+default LOG_USER.
+
+=item B<-mrafslogs>
+
+Use MR-AFS (Multi-Resident) style logging.  This option is deprecated.
+
+=item B<-saneacls>
+
+Offer the SANEACLS capability for the fileserver.  This option is
+currently unimplemented.
+
 =item B<-help>
 
 Prints the online help for this command. All other valid options are
 ignored.
 
+=item B<-fs-state-dont-save>
+
+When present, fileserver state will not be saved during shutdown.  Default
+is to save state.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-fs-state-dont-restore>
+
+When present, fileserver state will not be restored during startup.
+Default is to restore state on startup.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-fs-state-verify> (none | save | restore | both)
+
+This argument controls the behavior of the state verification mechanism.
+A value of C<none> turns off all verification.  A value of C<save> only
+performs the verification steps prior to saving state to disk.  A value
+of C<restore> only performs the verification steps after restoring state
+from disk.  A value of C<both> performs all verifications steps both
+prior to save and following a restore.
+
+The default is C<both>.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-vhashsize <I<size>>
+
+The log(2) number of of volume hash buckets.  Default is 8 (i.e., by
+default, there are 2^8 = 256 volume hash buckets).
+
+This option is only supported by the demand-attach file server.
+
+=item B<-vlruthresh <I<minutes>>
+
+The number of minutes of inactivity before a volume is eligible for soft
+detachment.  Default is 120 minutes.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-vlruinterval <I<seconds>>
+
+The number of seconds between VLRU candidate queue scan default is 120  s.
+The second                                                              s.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-vlrumax <I<positive integer>>
+
+The maximum number of volumes which can be soft detached in a single pass
+of the scanner.  Default is 8 volumes.
+
+This option is only supported by the demand-attach file server.
+
+=item B<-vattachpar> <I<number of volume attach threads>>
+
+The number of threads assigned to attach and detach volumes.  The default
+is 1.  Warning: many of the I/O parallism features of Demand-Attach
+Fileserver are turned off when the number of volume attach threads is only
+1.
+
+This option is only meaningful for a file server built with pthreads
+support.
+
+=item B<-m> <I<min percentage spare in partition>>
+
+Specifies the percentage of each AFS server partition that the AIX version
+of the File Server creates as a reserve. Specify an integer value between
+C<0> and C<30>; the default is 8%. A value of C<0> means that the
+partition can become completely full, which can have serious negative
+consequences.  This option is not supported on platforms other than AIX.
+
+=item B<-lock>
+
+Prevents any portion of the fileserver binary from being paged (swapped)
+out of memory on a file server machine running the IRIX operating system.
+This option is not supported on platforms other than IRIX.
+
 =back
 
 =head1 EXAMPLES