LUDOC-443 stripe: Add overstriping to manual

Add overstriping to Lustre manual.

Change-Id: If092cf0276e74400527b740dbb4e5b92a9ab489d
Signed-off-by: Patrick Farrell <pfarrell@whamcloud.com>
Reviewed-on: https://review.whamcloud.com/35324
Reviewed-by: Joseph Gmitter <jgmitter@whamcloud.com>
Tested-by: jenkins <devops@whamcloud.com>

diff --git a/ManagingFileSystemIO.xml b/ManagingFileSystemIO.xml
index 1ff1dc8..7d0f9be 100644 (file)
--- a/ManagingFileSystemIO.xml
+++ b/ManagingFileSystemIO.xml
@@ -382,7 +382,8 @@ client# lfs setstripe --pool|-p pool_name
         <para>To set striping patterns, run:</para>
         <screen>
 client# lfs setstripe [--size|-s stripe_size] [--offset|-o start_ost]
-           [--count|-c stripe_count] [--pool|-p pool_name]
+           [--stripe-count|-c stripe_count] [--overstripe-count|-C stripe_count]
+           [--pool|-p pool_name]
            
 <replaceable>dir|filename</replaceable>
 </screen>

diff --git a/ManagingStripingFreeSpace.xml b/ManagingStripingFreeSpace.xml
index 8114b22..bf703bc 100644 (file)
--- a/ManagingStripingFreeSpace.xml
+++ b/ManagingStripingFreeSpace.xml
@@ -89,8 +89,7 @@
         <para>In cases like these, a file can be striped over as many OSSs as it takes to achieve
           the required peak aggregate bandwidth for that file. Striping across a larger number of
           OSSs should only be used when the file size is very large and/or is accessed by many nodes
-          at a time. Currently, Lustre files can be striped across up to 2000 OSTs, the maximum
-          stripe count for an <literal>ldiskfs</literal> file system.</para>
+          at a time. Currently, Lustre files can be striped across up to 2000 OSTs</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">Improving performance when OSS bandwidth is exceeded.</emphasis>
@@ -100,6 +99,18 @@
           the I/O rate of the clients/jobs divided by the performance per OSS.</para>
       </listitem>
       <listitem>
+        <para condition="l2D"><emphasis role="bold">Matching stripes to I/O
+        pattern.</emphasis>When writing to a single file from multiple nodes,
+        having more than one client writing to a stripe can lead to issues
+        with lock exchange, where clients contend over writing to that stripe,
+        even if their I/Os do not overlap.  This can be avoided if I/O can be
+        stripe aligned so that each stripe is accessed by only one client.
+        Since Lustre 2.13, the 'overstriping' feature is available, allowing more
+        than stripe per OST.  This is particularly helpful for the case where
+        thread count exceeds OST count, making it possible to match stripe count
+        to thread count even in this case.</para>
+      </listitem>
+      <listitem>
         <para><emphasis role="bold">Providing space for very large files.</emphasis> Striping is
           useful when a single OST does not have enough free space to hold the entire file.</para>
       </listitem>
@@ -174,7 +185,7 @@
       </indexterm>Setting the File Layout/Striping Configuration (<literal>lfs
       setstripe</literal>)</title>
     <para>Use the <literal>lfs setstripe</literal> command to create new files with a specific file layout (stripe pattern) configuration.</para>
-    <screen>lfs setstripe [--size|-s stripe_size] [--count|-c stripe_count] \
+    <screen>lfs setstripe [--size|-s stripe_size] [--count|-c stripe_count] [--overstripe-count|-C stripe_count] \
 [--index|-i start_ost] [--pool|-p pool_name] <replaceable>filename|dirname</replaceable> </screen>
     <para><emphasis role="bold">
         <literal>stripe_size</literal>
@@ -185,10 +196,15 @@
         <literal>stripe_size</literal> of 0 causes the default stripe size to be used. Otherwise,
       the <literal>stripe_size</literal> value must be a multiple of 64 KB.</para>
     <para><emphasis role="bold">
-        <literal>stripe_count</literal>
+        <literal>stripe_count (--stripe-count, --overstripe-count)</literal>
       </emphasis>
-      </para>
-    <para>The <literal>stripe_count</literal> indicates how many OSTs to use. The default <literal>stripe_count</literal> value is 1. Setting <literal>stripe_count</literal> to 0 causes the default stripe count to be used. Setting <literal>stripe_count</literal> to -1 means stripe over all available OSTs (full OSTs are skipped).</para>
+    </para>
+    <para>The <literal>stripe_count</literal> indicates how many stripes to use.
+    The default <literal>stripe_count</literal> value is 1. Setting
+    <literal>stripe_count</literal> to 0 causes the default stripe count to be
+    used. Setting <literal>stripe_count</literal> to -1 means stripe over all
+    available OSTs (full OSTs are skipped).  When --overstripe-count is used,
+    per OST if necessary.</para>
     <para><emphasis role="bold">
         <literal>start_ost</literal>
       </emphasis>

diff --git a/UserUtilities.xml b/UserUtilities.xml
index a3eb0c3..4fce6bb 100644 (file)
--- a/UserUtilities.xml
+++ b/UserUtilities.xml
@@ -38,7 +38,8 @@ lfs getstripe [--obd|-O <replaceable>ost_name</replaceable>] [--quiet|-q] [--ver
               [--mdt-index|-M] [--recursive|-r] [--raw|-R]
               [--layout|-L]
               <replaceable>dirname|filename</replaceable> ...
-lfs setstripe [--size|-s stripe_size] [--count|-c <replaceable>stripe_count</replaceable>]
+lfs setstripe [--size|-s stripe_size] [--stripe-count|-c <replaceable>stripe_count</replaceable>]
+              [--overstripe-count|-C <replaceable>stripe_count</replaceable>]
               [--stripe-index|-i <replaceable>start_ost_index</replaceable>]
               [--ost-list|-o <replaceable>ost_indicies</replaceable>]
               [--pool|-p <replaceable>pool</replaceable>]
@@ -536,7 +537,7 @@ lfs help
               </entry>
               <entry>
                 <para>
-                  <literal>--count</literal>
+                  <literal>--stripe-count</literal>
                 </para>
               </entry>
               <entry>
@@ -647,7 +648,7 @@ lfs help
               </entry>
               <entry>
                 <para>
-                  <literal>--count stripe_cnt</literal>
+                  <literal>--stripe-count stripe_cnt</literal>
                 </para>
               </entry>
               <entry>
@@ -664,6 +665,24 @@ lfs help
               </entry>
               <entry>
                 <para>
+                  <literal>--overstripe-count stripe_cnt</literal>
+                </para>
+              </entry>
+              <entry>
+                <para>The same as --stripe-count, but allows overstriping,
+                which will place more than one stripe per OST if
+                <literal>stripe_cnt</literal> is greater than the number of
+                OSTs. Overstriping is useful for matching the number of stripes
+                to the number of processes, or with very fast OSTs, where one
+                stripe per OST is not enough to get full performance.</para>
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <para>&#160;</para>
+              </entry>
+              <entry>
+                <para>
                 <literal>--size stripe_size</literal>
                 <footnote>
                   <para>The default stripe-size is 0. The default start-ost is