Improve demand-attach fileserver bos documentation
[openafs.git] / doc / man-pages / pod8 / bos_create.pod
index a0afefd..e62e00c 100644 (file)
@@ -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