Add DAFS docs to the Unix Quick Start guide
authorAndrew Deason <adeason@sinenomine.net>
Tue, 3 Aug 2010 22:32:11 +0000 (17:32 -0500)
committerDerrick Brashear <shadow@dementia.org>
Wed, 4 Aug 2010 20:18:54 +0000 (13:18 -0700)
Modify the sections dealing with creating the 'fs' bnode to also
mention how to create the 'dafs' bnode, and add an appendix explaining
DAFS and the differences between DAFS and non-DAFS.

Change-Id: I026405dbc3838a9a0247b85cbdc508d6be93275d
Reviewed-on: http://gerrit.openafs.org/2508
Tested-by: Andrew Deason <adeason@sinenomine.net>
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>

doc/xml/QuickStartUnix/Makefile.in
doc/xml/QuickStartUnix/NTMakefile
doc/xml/QuickStartUnix/appendix_dafs.xml [new file with mode: 0644]
doc/xml/QuickStartUnix/auqbg000.xml
doc/xml/QuickStartUnix/auqbg005.xml
doc/xml/QuickStartUnix/auqbg006.xml

index 6d2cf24..2c2afb7 100644 (file)
@@ -21,7 +21,7 @@ include @TOP_OBJDIR@/src/config/Makefile.version
 
 BOOK     = auqbg000.xml
 SRCS     = $(BOOK) auqbg003.xml auqbg004.xml auqbg005.xml auqbg006.xml \
-          auqbg007.xml auqbg008.xml appendix.xml
+          auqbg007.xml auqbg008.xml appendix.xml appendix_dafs.xml
 HTML_XSL = @HTML_XSL@
 XSLTPROC = @XSLTPROC@
 
index 352d7e5..2f56fd3 100644 (file)
@@ -57,6 +57,7 @@ XMLSRCS = \
         auqbg007.xml \
         auqbg008.xml \
         appendix.xml \
+        appendix_dafs.xml \
         $(VERSFILE).xml
 
 index.html: $(XMLSRCS)
diff --git a/doc/xml/QuickStartUnix/appendix_dafs.xml b/doc/xml/QuickStartUnix/appendix_dafs.xml
new file mode 100644 (file)
index 0000000..0e85020
--- /dev/null
@@ -0,0 +1,243 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix id="DAFS">
+  <title>The Demand-Attach File Server</title>
+
+  <para>This chapter explains and describes the Demand-Attach File Server (DAFS
+  for short), a new feature in OpenAFS 1.6. A few things are different when
+  setting up and maintaining a DAFS fileserver vs a traditional fileserver, so
+  it is important to know which one you are running.</para>
+
+  <para>If you are trying to decide whether or not to run DAFS on a fileserver,
+  note that you can switch between DAFS and the traditional fileserver fairly
+  easily at any time. Aside from performance differences, the two fileservers
+  generally look and act similarly, so choosing one over the other in the
+  beginning should not hurt you later on. So, if you are not overly concerned
+  with performance, you can just pick one and follow the directions for it, and
+  you should be fine.</para>
+
+  <sect1 id="DAFS001">
+    <title>Justification and Background</title>
+
+    <para>DAFS changes many things with how the fileserver and other server
+    processes access volumes on disk. Most of these changes are only of concern
+    to developers, as there are no visible differences to users or
+    administrators. A few changes are only of concern to administrators while
+    debugging a problem, and only one or two changes affect the day-to-day
+    administration of a fileserver. See the sections on <link
+    linkend="DAFS002">DAFS Binaries</link> and <link
+    linkend="DAFS003">Salvaging</link> for the main functional
+    differences.</para>
+    
+    <para>Among other things, DAFS provides a new way for the fileserver and
+    other server programs to access volumes. It does not change how file data is
+    accessed inside a volume (like namei or inode do), but rather how a volume
+    as a whole is accessed by the fileserver. When a traditional fileserver is
+    started, it will locate and attach all AFS volumes it can find on all AFS
+    partitions on the server. This attachment process involves reading the
+    volume header and setting a flag to say that the volume is in use. On a
+    clean shutdown, the fileserver detach all volumes it attached by clearing
+    that flag. If the fileserver encounters a volume where the flag is already
+    set before it attached the volume, it will know that volume was not detached
+    cleanly, and that it needs to be salvaged.</para>
+
+    <para>This process of attaching and detaching at startup and shutdown takes
+    time. When fileservers start to have thousands of volumes, it can take
+    several minutes to start or cleanly shutdown. Additionally, when a
+    fileserver is shutdown uncleanly, all of the volumes on the server must be
+    salvaged before the fileserver can be brought up again. Even volumes that
+    nobody has ever accessed must be salvaged.</para>
+
+    <para>To improve this situation, DAFS does not attach all volumes on
+    startup. Instead, volumes are only attached when they are first accessed,
+    and are detached if idle for a long period of time (see the -vlru* options
+    for the fileserver; this is configurable but is generally several
+    hours).</para>
+
+    <para>Thus, after an unclean shutdown with DAFS, only the volumes in use at
+    the time of the shutdown need to be salvaged. In addition, the fileserver
+    does not need to wait for salvaging to finish before starting up. Instead of
+    salvaging everything before the fileserver starts, the fileserver causes
+    salvages to be issued on a volume when a damanged volume is accessed (called
+    "demand-salvages").</para>
+
+    <para>The result of all of this is that a fileserver running DAFS can
+    generally be started and stopped in a manner of seconds, where a traditional
+    fileserver could take dozens of minutes, or even hours in the case of an
+    unclean shutdown.</para>
+  </sect1>
+  <sect1 id="DAFS002">
+    <title>DAFS Binaries</title>
+
+    <para>OpenAFS ships with binaries for DAFS and non-DAFS alongside each
+    other. Programs that exist in both DAFS and non-DAFS variants typically have
+    a <emphasis role="bold">da</emphasis> prefix to indicate the DAFS variant.
+    For example, <emphasis role="bold">dafileserver</emphasis> is the DAFS
+    version of the traditional <emphasis role="bold">fileserver</emphasis>
+    binary. Similarly for <emphasis role="bold">davolserver</emphasis> and
+    <emphasis role="bold">volserver</emphasis>, <emphasis
+    role="bold">dasalvager</emphasis> and <emphasis
+    role="bold">salvager</emphasis>, and even some other tools like <emphasis
+    role="bold">dafssync-debug</emphasis> and <emphasis
+    role="bold">fssync-debug</emphasis>.</para>
+
+    <para>A DAFS-enabled fileserver will run the <emphasis
+    role="bold">dafs</emphasis> bnode in bosserver, instead of the traditional
+    fileserver's <emphasis role="bold">fs</emphasis> bnode. The <emphasis
+    role="bold">dafs</emphasis> bnode runs four different binaries as opposed to
+    the <emphasis role="bold">fs</emphasis> bnode's three. Three of the programs
+    in the <emphasis role="bold">dafs</emphasis> bnode are just DAFS equivalents
+    of the corresponding <emphasis role="bold">fs</emphasis> bnode programs, but
+    the fourth one is an entirely new daemon that has no non-DAFS equivalent:
+    the salvageserver.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <colspec colwidth="50*" />
+        <colspec colwidth="50*" />
+        <thead>
+          <row>
+            <entry><emphasis role="bold">Traditional binary</emphasis></entry>
+            <entry><emphasis role="bold">DAFS binary</emphasis></entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><emphasis role="bold">/usr/afs/bin/fileserver</emphasis></entry>
+            <entry><emphasis role="bold">/usr/afs/bin/dafileserver</emphasis></entry>
+          </row>
+          <row>
+            <entry><emphasis role="bold">/usr/afs/bin/volserver</emphasis></entry>
+            <entry><emphasis role="bold">/usr/afs/bin/davolserver</emphasis></entry>
+          </row>
+          <row>
+            <entry>No equivalent</entry>
+            <entry><emphasis role="bold">/usr/afs/bin/salvageserver</emphasis></entry>
+          </row>
+          <row>
+            <entry><emphasis role="bold">/usr/afs/bin/salvager</emphasis></entry>
+            <entry><emphasis role="bold">/usr/afs/bin/dasalvager</emphasis></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </sect1>
+
+  <sect1 id="DAFS003">
+    <title>Salvaging</title>
+
+    <para>With a traditional fileserver, salvages usually occur in two
+    situations:
+      <orderedlist>
+        <listitem>
+          <para>The fileserver shuts down uncleanly, and when brought back up,
+          all partitions are salvaged before the fileserver is available.</para>
+        </listitem>
+        <listitem>
+          <para>A volume experiences some corruption after it has been brought
+          online, and an administrator manually schedules a salvage for an
+          individual volume with <emphasis role="bold">bos salvage</emphasis>.
+          Usually the way you notice this is that the fileserver noticed a
+          volume has become corrupt and has taken it offline.</para>
+        </listitem>
+      </orderedlist>
+    </para>
+
+    <para>With DAFS, neither of these occur in normal operation. With DAFS, a
+    volume will be salvaged automatically when a problem is detected in a
+    volume. This occurs whether the fileserver detects the volume was not
+    detached cleanly, or if the fileserver detects corrupt volume data.</para>
+
+    <para>In normal DAFS operation, you should not need to ever run <emphasis
+    role="bold">bos salvage</emphasis>. However, if you suspect a bug, or that
+    there is corruption in a volume that the fileserver has not detected, you
+    can run <emphasis role="bold">bos salvage</emphasis> to manually issue a
+    salvage.</para>
+
+    <para>All salvages scheduled from the salvageserver will be logged in
+    <emphasis role="bold">/usr/afs/logs/SalsrvLog</emphasis>, in the same format
+    as salvages for traditional fileservers are logged. If you issue a
+    whole-partition or whole-server salvage, the logs for that will still be
+    located in <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis>.</para>
+  </sect1>
+
+  <sect1 id="DAFS004">
+    <title>Converting a Fileserver to DAFS</title>
+
+    <para>If you have an existing traditional fileserver, you can convert it to
+    DAFS fairly easily. The conversion is in-place, but there is at least a
+    small amount of downtime involved even if nothing goes wrong, since the
+    fileserver processes must be restarted. If you want to avoid any downtime,
+    move any volumes on the fileserver to another fileserver before performing
+    the conversion.</para>
+
+    <orderedlist>
+      <listitem>
+        <para>If the fileserver is currently running a version of OpenAFS
+        earlier than 1.6.0, upgrade the fileserver to a version in the 1.6
+        series or later. This is not strictly necessary, but if you encounter
+        problems here, it is helpful to catch them before converting to DAFS so
+        as to isolate the problem.</para>
+
+        <para>If you do not upgrade the fileserver before converting to DAFS,
+        install the new OpenAFS binaries somewhere on the server.</para>
+      </listitem>
+
+      <listitem>
+        <para>If the current bosserver process running on the fileserver is
+        older than OpenAFS 1.6.0, you must upgrade it first. This can be done by
+        replacing the bosserver binary and running <emphasis role="bold">bos
+        restart -bosserver</emphasis>.  This will cause <emphasis>all</emphasis>
+        AFS processes controlled by the bosserver to be restarted. You can do
+        this at the same as upgrading the fileserver in the previous step if
+        desired, to avoid restarting the fileserver twice.</para>
+      </listitem>
+
+      <listitem>
+        <para>Shutdown and stop the old <emphasis role="bold">fs</emphasis> bnode:
+          <programlisting>
+ # <emphasis role="bold">bos stop </emphasis>&lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs -wait -cell </emphasis>&lt;<replaceable>cell name</replaceable>&gt;
+          </programlisting>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>Create and start the new <emphasis role="bold">dafs</emphasis> bnode.
+          <programlisting>
+ # <emphasis role="bold">bos create  </emphasis>&lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs dafs</emphasis> \
+               <emphasis role="bold">-cmd /usr/afs/bin/dafileserver</emphasis> &lt;<replaceable>dafileserver options</replaceable>&gt; \
+               <emphasis role="bold">-cmd /usr/afs/bin/davolserver</emphasis> &lt;<replaceable>davolserver options</replaceable>&gt; \
+               <emphasis role="bold">-cmd /usr/afs/bin/salvageserver</emphasis> &lt;<replaceable>salvageserver options</replaceable>&gt; \
+               <emphasis role="bold">-cmd /usr/afs/bin/dasalvager</emphasis> &lt;<replaceable>dasalvager options</replaceable>&gt; \
+               <emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;
+          </programlisting>
+        You can use the same options for the <emphasis
+        role="bold">dafileserver</emphasis> process as you did for the <emphasis
+        role="bold">fileserver</emphasis> process, and the same options for
+        <emphasis role="bold">davolserver</emphasis> as you did for <emphasis
+        role="bold">volserver</emphasis>.</para>
+        
+        <para>You can also use most of the same options for the <emphasis
+        role="bold">salvageserver</emphasis> and <emphasis
+        role="bold">dasalvager</emphasis> processes as you did for the <emphasis
+        role="bold">salvager</emphasis> process; see their respective man pages.
+        However, if you are upgrading from the 1.4.x series of OpenAFS, be aware
+        that the <emphasis role="bold">-DontSalvage</emphasis> option does not
+        exist anymore for the salvager (with or without DAFS).</para>
+
+        <para>Also note that the <emphasis role="bold">dafileserver</emphasis>
+        process has many more options to tune dafs-specific parameters. See the
+        <emphasis role="bold">dafileserver</emphasis> man page for information
+        about them.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>After you have performed these steps, switching back and forth between
+    running a DAFS and a traditional fileserver is as simple a running <emphasis
+    role="bold">bos stop</emphasis> on one bnode, and <emphasis role="bold">bos
+    start</emphasis> on the other. Once you are confident that the DAFS
+    processes are running smoothly and you do not anticipate switching back to
+    the traditional fileserver, you can <emphasis role="bold">bos
+    delete</emphasis> the <emphasis role="bold">fs</emphasis> bnode.</para>
+  </sect1>
+</appendix>
index 30bc262..a7993c2 100644 (file)
@@ -9,6 +9,7 @@
 <!ENTITY chapter4 SYSTEM "auqbg007.xml">
 <!ENTITY appendixA SYSTEM "auqbg008.xml">
 <!ENTITY appendixB SYSTEM "appendix.xml">
+<!ENTITY appendixC SYSTEM "appendix_dafs.xml">
 ]>
 
 <book>
@@ -46,6 +47,7 @@
   &chapter4;
   &appendixA;
   &appendixB;
+  &appendixC;
   <index></index>
 </book>
 <!-- Keep this comment at the end of the file
index 95f5a74..48fe317 100644 (file)
@@ -3677,18 +3677,42 @@ Entry for principal afs/&lt;<replaceable>cell name</replaceable>&gt; with kvno 3
   </sect1>
 
   <sect1 id="HDRWQ60">
-    <title>Starting the File Server, Volume Server, and Salvager</title>
-
-    <para>Start the <emphasis role="bold">fs</emphasis> process, which consists of the File Server, Volume Server, and Salvager
-    (<emphasis role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis> and <emphasis
-    role="bold">salvager</emphasis> processes). <orderedlist>
+    <title>Starting the File Server processes</title>
+
+    <para>Start either the <emphasis role="bold">fs</emphasis> process or, if you want to run the Demand-Attach File Server, the
+    <emphasis role="bold">dafs</emphasis> process. The <emphasis role="bold">fs</emphasis> process consists of the File Server,
+    Volume Server, and Salvager (<emphasis role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis> and
+    <emphasis role="bold">salvager</emphasis> processes). The <emphasis role="bold">dafs</emphasis> process consists of the
+    Demand-Attach File Server, Volume Server, Salvage Server, and Salvager (<emphasis role="bold">dafileserver</emphasis>,
+    <emphasis role="bold"> davolserver</emphasis>, <emphasis role="bold">salvageserver</emphasis>, and <emphasis
+    role="bold">dasalvager</emphasis> processes). For information about the Demand-Attach File Server and to see whether or not
+    you should run it, see <link linkend="DAFS">Appendix C, The Demand-Attach File Server</link>.
+     <orderedlist>
         <listitem>
           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the <emphasis role="bold">fs</emphasis>
-          process. The command appears here on multiple lines only for legibility. <programlisting>
+          process or the <emphasis role="bold">dafs</emphasis> process. The commands appear here on multiple lines only for legibility.
+
+           <itemizedlist>
+             <listitem>
+               <para>If you are not planning on running the Demand-Attach File Server, create the <emphasis role="bold">fs</emphasis>
+               process:
+                 <programlisting>
    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs fs /usr/afs/bin/fileserver</emphasis>   \
                    <emphasis role="bold">/usr/afs/bin/volserver /usr/afs/bin/salvager</emphasis>  \
                    <emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis role="bold">-noauth</emphasis>   
 </programlisting></para>
+             </listitem>
+            <listitem>
+              <para>If you are planning on running the Demand-Attach File Server, create the <emphasis
+              role="bold">dafs</emphasis> process:
+                 <programlisting>
+   # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs fs /usr/afs/bin/dafileserver</emphasis>   \
+                   <emphasis role="bold">/usr/afs/bin/davolserver /usr/afs/bin/salvageserver</emphasis> \
+                   <emphasis role="bold">/usr/afs/bin/salvager -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis role="bold">-noauth</emphasis>   
+</programlisting></para>
+             </listitem>
+           </itemizedlist>
+          </para>
 
           <para>Sometimes a message about Volume Location Database (VLDB) initialization appears, along with one or more instances
           of an error message similar to the following:</para>
@@ -3709,13 +3733,25 @@ Entry for principal afs/&lt;<replaceable>cell name</replaceable>&gt; with kvno 3
               <secondary>status</secondary>
             </indexterm></para>
 
-          <para>You can verify that the <emphasis role="bold">fs</emphasis> process has started successfully by issuing the
-          <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
+          <para>You can verify that the <emphasis role="bold">fs</emphasis> or <emphasis role="bold">dafs</emphasis> process has started
+         successfully by issuing the <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
           starts</computeroutput>.</para>
 
+         <itemizedlist>
+           <listitem>
+             <para>If you are not running the Demand-Attach File Server:
+
           <programlisting>
    # <emphasis role="bold">./bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs -long -noauth</emphasis>
-</programlisting>
+</programlisting></para></listitem>
+
+            <listitem>
+             <para>If you are running the Demand-Attach File Server:
+          <programlisting>
+   # <emphasis role="bold">./bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs -long -noauth</emphasis>
+</programlisting></para></listitem>
+          </itemizedlist>
+
         </listitem>
 
         <listitem>
index 392d623..c90a9c6 100644 (file)
           </listitem>
 
           <listitem>
-            <para>Start the <emphasis role="bold">fs</emphasis> process, which binds together the File Server, Volume Server, and
+            <para>Issue the <emphasis role="bold">bos create</emphasis> command
+            to start the <emphasis role="bold">fs</emphasis> process or the
+            <emphasis role="bold">dafs</emphasis> process, depending on if you
+            want to run the Demand-Attach File Server or not. See <link
+            linkend="DAFS">Appendix C, The Demand-Attach File Server</link> for
+            more information on whether you want to run it or not.
+
+           <itemizedlist>
+              <listitem>
+
+            <para>If you do not want to run the Demand-Attach File Server, start the <emphasis role="bold">fs</emphasis> process, which binds together the File Server, Volume Server, and
             Salvager. <programlisting>
    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs fs</emphasis>   \ 
          <emphasis role="bold">/usr/afs/bin/fileserver /usr/afs/bin/volserver</emphasis>  \ 
                   role="bold">-noauth</emphasis>
 </programlisting></para>
           </listitem>
+
+          <listitem>
+
+            <para>If you want to run the Demand-Attach File Server, start the
+            <emphasis role="bold">dafs</emphasis> process, which binds together
+            the File Server, Volume Server, Salvage Server, and Salvager.
+            <programlisting>
+   # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs dafs</emphasis>   \ 
+         <emphasis role="bold">/usr/afs/bin/dafileserver /usr/afs/bin/davolserver</emphasis>  \ 
+         <emphasis role="bold">/usr/afs/bin/salvageserver</emphasis>  \ 
+         <emphasis role="bold">/usr/afs/bin/dasalvager -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
+                  role="bold">-noauth</emphasis>
+</programlisting></para>
+          </listitem>
+
+          </itemizedlist>
+
+          </para>
+          </listitem>
         </orderedlist></para>
 
       <indexterm>