Improve demand-attach fileserver bos documentation

[openafs.git] / doc / man-pages / pod8 / fileserver.pod

diff --git a/doc/man-pages/pod8/fileserver.pod b/doc/man-pages/pod8/fileserver.pod
index 9cf1a78..285a6d4 100644 (file)
--- a/doc/man-pages/pod8/fileserver.pod
+++ b/doc/man-pages/pod8/fileserver.pod
@@ -50,6 +50,9 @@ B<fileserver> S<<< [B<-auditlog> <I<path to log file>>] >>>
     S<<< [B<-fs-state-dont-save>] >>>
     S<<< [B<-fs-state-dont-restore>] >>>
     S<<< [B<-fs-state-verify>] (none | save | restore | both)] >>>
+    S<<< [B<-vhandle-setaside> <I<fds reserved for non-cache io>>] >>>
+    S<<< [B<-vhandle-max-cachesize> <I<max open files>>] >>>
+    S<<< [B<-vhandle-initial-cachesize> <I<fds reserved for non-cache io>>] >>>
     S<<< [B<-vhashsize> <I<log(2) of number of volume hash buckets>>] >>>
     S<<< [B<-vlrudisable>] >>>
     S<<< [B<-vlruthresh> <I<minutes before eligibility for soft detach>>] >>>
@@ -217,6 +220,21 @@ suites. Provide the command name and all option names in full.
 
 =head1 CAUTIONS
 
+There are two strategies the File Server can use for attaching AFS volumes
+at startup and handling volume salvages.  The traditional method assumes
+all volumes are salvaged before the File Server starts and attaches all
+volumes at start before serving files.  The newer demand-attach method
+attaches volumes only on demand, salvaging them at that time as needed,
+and detaches volumes that are not in use.  A demand-attach File Server can
+also save state to disk for faster restarts.
+
+The choice of traditional or demand-attach File Server must be made at
+compile time, and the required setup in F<BosConfig> is different for the
+two servers.  When changing from a traditional File Server to
+demand-attach or vice versa, you will need to stop and remove the C<fs> or
+C<dafs> node in F<BosConfig> and create a new node of the appropriate
+type.  See L<bos_create(8)> for more information.
+
 Do not use the B<-k> and B<-w> arguments, which are intended for use
 by the OpenAFS developers only. Changing them from their default
 values can result in unpredictable File Server behavior.  In any case,
@@ -256,7 +274,11 @@ length.
 
 =item B<-auditlog> <I<log path>>
 
-Set and enable auditing.
+Turns on audit logging, and sets the path for the audit log.  The audit
+log records information about RPC calls, including the name of the RPC
+call, the host that submitted the call, the authenticated entity (user)
+that issued the call, the parameters for the call, and if the call
+succeeded or failed.
 
 =item B<-audit-interface> (file | sysvmq)
 
@@ -538,6 +560,18 @@ The default is C<both>.
 
 This option is only supported by the demand-attach file server.
 
+=item B<-vhandle-setaside> <I<fds reserved for non-cache io>>
+
+Number of file handles set aside for I/O not in the cache. Defaults to 128.
+
+=item B<-vhandle-max-cachesize> <I<max open files>>
+
+Maximum number of available file handles.
+
+=item B<-vhandle-initial-cachesize> <I<initial open file cache>>
+
+Number of file handles set aside for I/O in the cache. Defaults to 128.
+
 =item B<-vhashsize <I<size>>
 
 The log(2) number of of volume hash buckets.  Default is 8 (i.e., by
@@ -594,15 +628,23 @@ This option is not supported on platforms other than IRIX.
 
 =head1 EXAMPLES
 
-The following B<bos create> command creates an fs process on the file
-server machine C<fs2.abc.com> that uses the large configuration size, and
-allows volumes to exceed their quota by 10%. Type the command on a single
-line:
+The following B<bos create> command creates a traditional fs process on
+the file server machine C<fs2.abc.com> that uses the large configuration
+size, and allows volumes to exceed their quota by 10%. Type the command on
+a single line:
 
    % bos create -server fs2.abc.com -instance fs -type fs \
-                -cmd "/usr/afs/bin/fileserver -pctspare 10 \
-                -L" /usr/afs/bin/volserver /usr/afs/bin/salvager
+                -cmd "/usr/afs/bin/fileserver -pctspare 10 -L" \
+                /usr/afs/bin/volserver /usr/afs/bin/salvager
+
+The following is an equivalent B<bos create> command for a demand-attach
+File Server:
 
+   % bos create -server fs2.abc.com -instance dafs -type dafs \
+                -cmd "/usr/afs/bin/fileserver -pctspare 10 -L" \
+                /usr/afs/bin/volserver \
+                /usr/afs/bin/salvageserver \
+                /usr/afs/bin/salvager
 
 =head1 TROUBLESHOOTING
 
@@ -647,7 +689,7 @@ represents a connection that's waiting for a file server thread.
 
 If the blocked connection count is ever above 0, the server is having
 problems replying to clients in a timely fashion.  If it gets above 10,
-roughly, there will be noticable slowness by the user.  The total number of
+roughly, there will be noticeable slowness by the user.  The total number of
 connections is a mostly irrelevant number that goes essentially
 monotonically for as long as the server has been running and then goes back
 down to zero when it's restarted.
@@ -767,6 +809,8 @@ L<FileLog(5)>,
 L<bos_create(8)>,
 L<bos_getlog(8)>,
 L<fs_setacl(1)>,
+L<msgget(2)>,
+L<msgrcv(2)>,
 L<salvager(8)>,
 L<volserver(8)>,
 L<vos_examine(1)>