Merge lp:~serge-hallyn/ubuntu/precise/ubuntu-core-doc/serverguide-ppetrakis into lp:~peter-petrakis/ubuntu/precise/ubuntu-core-doc/serverguide

[Peter Petrakis]

[Peter Petrakis (peter-petrakis)]

Taking entire comment, will remove comment concerning config file blacklist in subsequent commit.

review: Approve

=== modified file 'serverguide/C/storage/dm-multipath/dm-multipath.xml'
--- serverguide/C/storage/dm-multipath/dm-multipath.xml	2012-03-16 14:34:18 +0000
+++ serverguide/C/storage/dm-multipath/dm-multipath.xml	2012-03-20 19:12:21 +0000
@@ -57,7 +57,7 @@
         prio    alua
 }</screen></para>
 
-        <para>See Table, <link
+        <para>See Table <link
         linkend="priority-checker-conversion-table">"Priority Checker
         Conversion"</link> for a complete listing</para>
 
@@ -134,15 +134,25 @@
     <sect2 id="multipath-overview">
       <title>Overview</title>
 
-      <para>DM-Multipath can be used to provide: Redundancy DM-Multipath can
+      <para>DM-Multipath can be used to provide:</para>
+      
+      <itemizedlist>
+      <listitem><para><emphasis> Redundancy </emphasis>
+      DM-Multipath can
       provide failover in an active/passive configuration. In an
       active/passive configuration, only half the paths are used at any time
       for I/O. If any element of an I/O path (the cable, switch, or
-      controller) fails, DM-Multipath switches to an alternate path. Improved
+      controller) fails, DM-Multipath switches to an alternate path.
+      </para>
+      </listitem>
+      
+      <listitem><para><emphasis> Improved Performance </emphasis>
       Performance DM-Multipath can be configured in active/active mode, where
       I/O is spread over the paths in a round-robin fashion. In some
       configurations, DM-Multipath can detect loading on the I/O paths and
       dynamically re-balance the load.</para>
+      </listitem>
+      </itemizedlist>
     </sect2>
 
     <sect2 id="multipath-storage-array-support">
@@ -163,8 +173,8 @@
     <sect2 id="multipath-dm-multipath-components">
       <title>&DMM; components</title>
 
-      <para>Table, “<link linkend="multipath-components-table">DM-Multipath
-      Components”</link>. describes the components of DM-Multipath.
+      <para>Table “<link linkend="multipath-components-table">DM-Multipath
+      Components”</link> describes the components of the DM-Multipath package.
       <xi:include href="multipath-components-table.xml"
       xmlns:xi="http://www.w3.org/2001/XInclude"/></para>
     </sect2>
@@ -226,9 +236,10 @@
       a multipath device is set to its WWID. Alternately, you can set the
       <emphasis role="bold"><link
       linkend="attribute-user_friendly_names">user_friendly_names</link>
-      </emphasis>option in the multipath configuration file, which sets the
-      alias to a node-unique name of the form <emphasis
-      role="bold">mpathn</emphasis>. For example, a node with two HBAs
+      </emphasis>option in the multipath configuration file,
+      which causes DM-Multipath to use a node-unique alias of the form
+      <emphasis role="bold">mpathn</emphasis> as the name.
+      For example, a node with two HBAs
       attached to a storage controller with two ports via a single unzoned FC
       switch sees four devices: <emphasis role="bold">/dev/sda</emphasis>,
       <emphasis role="bold">/dev/sdb</emphasis>, <emphasis
@@ -286,9 +297,9 @@
       nodes in the cluster. This should not cause any difficulties if you use
       LVM to create logical devices from the multipath device, but if you
       require that your multipath device names be consistent in every node it
-      is recommended that you not set the <emphasis
-      role="bold">user_friendly_names</emphasis> option to <emphasis
-      role="bold">yes</emphasis> and that you not configure aliases for the
+      is recommended that you leave the <emphasis
+      role="bold">user_friendly_names</emphasis> option set to <emphasis
+      role="bold">no</emphasis> and that you not configure aliases for the
       devices. By default, if you do not set <emphasis
       role="bold">user_friendly_names</emphasis> to yes or configure an alias
       for a device, a device name will be the WWID for the device, which is
@@ -452,9 +463,9 @@
       is also required.</para>
 
       <para>A basic <emphasis role="bold">/etc/multipath.conf </emphasis>
-      should consist at the very least a blacklist of devices you wish
-      multipath to leave alone. Some devices don't react well to multipath's
-      probing.<screen id="multipath-skel-config">blacklist {
+      should contain at the very least a blacklist of devices which
+      multipath should leave alone. Some devices don't react well to multipath's
+      probing.[SERGE ASKS: can we have a citation for this?]<screen id="multipath-skel-config">blacklist {
         devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
         devnode "^hd[a-z]"
         devnode "^dcssblk[0-9]*"

=== modified file 'serverguide/C/storage/dm-multipath/multipath-components-table.xml'
--- serverguide/C/storage/dm-multipath/multipath-components-table.xml	2012-03-16 14:04:19 +0000
+++ serverguide/C/storage/dm-multipath/multipath-components-table.xml	2012-03-20 19:12:21 +0000
@@ -33,7 +33,7 @@
         </entry>
 
         <entry>Lists and configures <emphasis role="bold">multipath</emphasis>
-        devices. Normally started up with /etc/rc.sysinit, it can also be
+        devices. Normally started up with <filename>/etc/rc.sysinit</filename>, it can also be
         started up by a udev program whenever a block device is added or it
         can be run by the initramfs file system.</entry>
       </row>
@@ -45,9 +45,8 @@
 
         <entry>Monitors paths; as paths fail and come back, it may initiate
         path group switches. Provides for interactive changes to <emphasis
-        role="bold">multipath</emphasis> devices. This must be restarted for
-        any changes to the <emphasis
-        role="bold">/etc/multipath.conf</emphasis> file.</entry>
+        role="bold">multipath</emphasis> devices. This daemon must be restarted for
+        any changes to the <filename>/etc/multipath.conf</filename> file to take effect.</entry>
       </row>
 
       <row>

=== modified file 'serverguide/C/storage/dm-multipath/multipath-config-defaults-table.xml'
--- serverguide/C/storage/dm-multipath/multipath-config-defaults-table.xml	2012-03-16 14:34:18 +0000
+++ serverguide/C/storage/dm-multipath/multipath-config-defaults-table.xml	2012-03-20 19:12:21 +0000
@@ -366,8 +366,8 @@
           <emphasis role="bold">user_friendly_names</emphasis>
         </entry>
 
-        <entry>If set to yes, specifies that the system should use the /etc/
-        <emphasis role="bold">multipath</emphasis>/bindings file to assign a
+        <entry>If set to yes, specifies that the system should use the
+	<filename>/etc/multipath/bindings</filename> file to assign a
         persistent and unique <emphasis role="bold">alias</emphasis> to the
         <emphasis role="bold">multipath</emphasis>, in the form of mpathn. If
         set to no, specifies that the system should use the WWID as the
@@ -409,7 +409,7 @@
         opened by <emphasis role="bold">multipath</emphasis> and the <emphasis
         role="bold">multipathd</emphasis> daemon. This is equivalent to the
         ulimit -n command. A value of max will set this to the system limit
-        from /proc/sys/fs/nr_open. If this is not set, the maximum number of
+        from <filename>/proc/sys/fs/nr_open</filename>. If this is not set, the maximum number of
         open file descriptors is taken from the calling process; it is usually
         1024. To be safe, this should be set to the maximum number of paths
         plus 32, if that number is greater than 1024.</entry>
@@ -422,8 +422,8 @@
 
         <entry>The timeout to use for path checkers that issue SCSI commands
         with an explicit timeout, in seconds. <para>The default value is taken
-        from sys/block/sdx/device/timeout, which is
-        <literal>30</literal>seconds as of 12.04 LTS</para></entry>
+        from </filename>/sys/block/sdx/device/timeout</filename>, which is
+        <literal>30</literal> seconds as of 12.04 LTS</para></entry>
       </row>
 
       <row>