From 7d395f1754649b70311895c37962cd1770cb9f73 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Tue, 6 Apr 2010 17:46:13 -0700 Subject: [PATCH] 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 Tested-by: Derrick Brashear --- doc/man-pages/pod8/bos_create.pod | 66 +++++++++++++++++++++++++------ doc/man-pages/pod8/fileserver.pod | 35 +++++++++++++--- 2 files changed, 82 insertions(+), 19 deletions(-) diff --git a/doc/man-pages/pod8/bos_create.pod b/doc/man-pages/pod8/bos_create.pod index a0afefd72..e62e00c08 100644 --- 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 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 as described below will not work with +a demand-attach File Server, and a server process entry of type B +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 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 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, B, and -B, in that order. The standard binary directory is -F. If including any of an initialization command's options, -surround the entire command in double quotes (C<"">). +For the B process, provide the complete pathname of the local disk +binary file for each of the component processes: B, +B, and B, in that order. The standard binary +directory is F. If including any of an initialization +command's options, surround the entire command in double quotes (C<"">). + +For the B process, provide the complete pathname of hte local disk +binary file for each of the component processes: B, +B, B, and B, in that order. The +standard binary directory is F. 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 on the machine C: +C on the machine C: - % 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 on the machine C. It references C 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. Type the command on a single line. +The following command creates the B process C on the machine +C (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. Type the command on a single line. +The following command creates the B process C on the machine +C (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 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 and B flags for an existing +traditional File Server configuration. (Substitute the C 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 " \ + "/usr/afs/bin/volserver " \ + /usr/afs/bin/salvageserver /usr/afs/bin/salvager + +replacing and 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 file on the diff --git a/doc/man-pages/pod8/fileserver.pod b/doc/man-pages/pod8/fileserver.pod index 0b0091b3d..285a6d4ee 100644 --- 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 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 or +C node in F and create a new node of the appropriate +type. See L 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 command creates an fs process on the file -server machine C 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 command creates a traditional fs process on +the file server machine C 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 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 -- 2.39.5