Improve demand-attach fileserver bos documentation

Add a caution to the fileserver man page explaining that traditional
and demand-attach require different configurations, and also mention
that there are two different server implementations.  Add an example
of a bos create command for creating a demand-attach File Server to
the fileserver man page.

Add a caution to the bos create man page that a traditional fs node
won't work with demand-attach and vice versa.  Document the necessary
arguments for the dafs type.  Clarify in EXAMPLES which bos create
commands are traditional and which are demand-attach.  Add an example
of changing from a traditional to a demand-attach configuration.

Change kaserver to ptserver in the example of a simple process.

Change-Id: I4077246b69edf6e1ddc7c0761ac8e1006d471c24
Reviewed-on: http://gerrit.openafs.org/1707
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>

diff --git a/doc/man-pages/pod8/bos_create.pod b/doc/man-pages/pod8/bos_create.pod
index a0afefd7259338e1fdbed1e2efbeeecf82de60a3..e62e00c08aedfbd18080df1520895444cfe3b43b 100644 (file)
--- a/doc/man-pages/pod8/bos_create.pod
+++ b/doc/man-pages/pod8/bos_create.pod
@@ -31,6 +31,16 @@ A server process's entry in the F<BosConfig> file defines its name, its
 type, the command that initializes it, and optionally, the name of a
 notifier program that runs when the process terminates.
 
+=head1 CAUTIONS
+
+A server process entry of type B<fs> as described below will not work with
+a demand-attach File Server, and a server process entry of type B<dafs>
+for a demand-attach File Server will not work with a traditional File
+Server. When switching from one File Server implementation to another,
+remove the existing server process entry and create a new one. See
+L<EXAMPLES> below for an example of switching from a traditional File
+Server to a demand-attach File Server.
+
 =head1 OPTIONS
 
 =over 4
@@ -121,7 +131,7 @@ command.
 =item dafs
 
 Use this value only for the dafs process, which combines the File Server,
-Volume Server, Salvageserver, and Salvager processes in order to operate
+Volume Server, Salvage Server, and Salvager processes in order to operate
 as a Demand Attach File Server.  If one of the component processes
 terminates, the BOS Server shuts down and restarts the process in the
 appropriate order.
@@ -156,11 +166,18 @@ options, surround the entire command in double quotes (C<"">). The
 B<upclient> process has a required argument, and the commands for all
 other processes take optional arguments.
 
-For the fs process, provide the complete pathname of the local disk binary
-file for each of the component processes: B<fileserver>, B<volserver>, and
-B<salvager>, in that order. The standard binary directory is
-F</usr/afs/bin>.  If including any of an initialization command's options,
-surround the entire command in double quotes (C<"">).
+For the B<fs> process, provide the complete pathname of the local disk
+binary file for each of the component processes: B<fileserver>,
+B<volserver>, and B<salvager>, in that order. The standard binary
+directory is F</usr/afs/bin>.  If including any of an initialization
+command's options, surround the entire command in double quotes (C<"">).
+
+For the B<dafs> process, provide the complete pathname of hte local disk
+binary file for each of the component processes: B<fileserver>,
+B<volserver>, B<salvageserver>, and B<salvager>, in that order. The
+standard binary directory is F</usr/afs/bin>.  If including any of an
+initialization command's options, surround the entire command in double
+quotes (C<"">).
 
 For a cron process, provide two parameters:
 
@@ -244,10 +261,10 @@ ignored.
 =head1 EXAMPLES
 
 The following command defines and starts the simple process
-C<kaserver> on the machine C<fs3.abc.com>:
+C<ptserver> on the machine C<fs3.abc.com>:
 
-   % bos create -server fs3.abc.com -instance kaserver -type simple \
-                -cmd /usr/afs/bin/kaserver
+   % bos create -server fs3.abc.com -instance ptserver -type simple \
+                -cmd /usr/afs/bin/ptserver
 
 The following command defines and starts the simple process C<upclientbin>
 on the machine C<fs4.abc.com>. It references C<fs1.abc.com> as the source
@@ -258,15 +275,17 @@ directory every 120 seconds.
                 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
                 /usr/afs/bin"
 
-The following command creates the fs process fs on the machine
-C<fs4.abc.com>. Type the command on a single line.
+The following command creates the B<fs> process C<fs> on the machine
+C<fs4.abc.com> (a traditional File Server with associated processes). Type
+the command on a single line.
 
    % bos create -server fs4.abc.com -instance fs -type fs \
                 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
                 /usr/afs/bin/salvager
 
-The following command creates the dafs process dafs on the machine
-C<fs4.abc.com>. Type the command on a single line.
+The following command creates the B<dafs> process C<dafs> on the machine
+C<fs4.abc.com> (a demand-attach File Server with associated processes).
+Type the command on a single line.
 
    % bos create -server fs4.abc.com -instance dafs -type dafs \
                 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
@@ -283,6 +302,27 @@ entire B<bos create> command on one line.
    % bos create -server fs5.abc.com -instance userbackup -type cron  \
        -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
 
+To switch from a traditional File Server to a demand-attach File Server,
+run:
+
+   % bos status localhost -instance fs -long
+
+to see the current B<fileserver> and B<volserver> flags for an existing
+traditional File Server configuration. (Substitute the C<dafs> instance
+for an existing demand-attach File Server.) Then, run:
+
+   % bos stop localhost fs -localauth
+   % bos delete localhost fs -localauth
+   % bos create localhost dafs dafs \
+       "/usr/afs/bin/fileserver <fileserver-flags>" \
+       "/usr/afs/bin/volserver <volserver-flags>" \
+       /usr/afs/bin/salvageserver /usr/afs/bin/salvager
+
+replacing <fileserver-flags> and <volserver-flags> with the flags from the
+previous configuration. This will stop the traditional File Server and
+start a demand-attach File Server. The binaries at the paths provided must
+already be updated to binaries built with demand-attach enabled.
+
 =head1 PRIVILEGE REQUIRED
 
 The issuer must be listed in the F</usr/afs/etc/UserList> file on the

diff --git a/doc/man-pages/pod8/fileserver.pod b/doc/man-pages/pod8/fileserver.pod
index 0b0091b3d554d011d7833e8de3caa01b7c6b2cda..285a6d4eeafe71da8f0210b99ddadc4265ed0b24 100644 (file)
--- a/doc/man-pages/pod8/fileserver.pod
+++ b/doc/man-pages/pod8/fileserver.pod
@@ -220,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,
@@ -613,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