Improve ReaR backup config examples (#404)

* Update rear version number

* Improve flow of rear config section

* Add Btrfs example to rear config section

bsc#1204927
jsc#DOCTEAM-787

* Add multipath example and warning

* Move and improve UEFI example

* Add important symbol to multipath example

* Typo fix

* Review updates round 1

* Updates from tech review

* Replace hard-coded version with search command

* Fix bootloader path

* Formatting

* Tech review updates

Author: tahliar

xml/ha_rear.xml

@@ -8,11 +8,11 @@
 <!-- toms 2014-02-26:
   - rear-SUSE is not available anymore in SLE12 Beta1
   - No YaST module for Rear
-  - 2014-05-14: Btrfs and Rear: 
+  - 2014-05-14: Btrfs and Rear:
     http://en.opensuse.org/SDB:Disaster_Recovery#All_filesystems_are_equal.2C_but_some_are_more_equal_than_others
 -->
 <!--Fates #310991, 312336-->
-<!--taroth 2011-09-19: information sources: 
+<!--taroth 2011-09-19: information sources:
   /usr/share/doc/packages/rear/README
   /usr/share/doc/packages/rear-SUSE
   http://sourceforge.net/projects/rear/files/documentation/
@@ -164,14 +164,16 @@
     </para>
    </warning>
   </sect2>
-  
-  
+
+
   <sect2 xml:id="sec-ha-rear-concept-versions">
    <title>&rear; version updates</title>
+
    <para>
-    &productname; &productnumber; ships with &rear; version 2.3, provided by the
-    package <package>rear23a</package>.
+    To see which versions of &rear; are available with &productname; &productnumber;,
+    run the following command:
    </para>
+<screen>&prompt.root;<command>zypper search --type package --verbose rear</command></screen>
 
    <note>
     <title>Find important information in changelogs</title>
@@ -397,38 +399,23 @@
  </sect1>
  <sect1 xml:id="sec-ha-rear-config">
   <title>Setting up &rear; and your backup solution</title>
-
   <para>
-   To set up &rear;, you need to edit at least the &rear;
-   configuration file <filename>/etc/rear/local.conf</filename> and, if
-   needed, the Bash scripts that are part of the &rear; framework.
+   To install the latest version of &rear;, run the following command:
   </para>
-
+<screen>&prompt.root;<command>zypper install rear</command></screen>
   <para>
-   In particular, you need to define the following tasks that &rear;
-   should do:
+    If you need to install an earlier version of &rear;, you can specify the package version.
+    For example:
+  </para>
+<screen>&prompt.root;<command>zypper install rear23a</command></screen>
+  <para>
+   To configure &rear;, add your settings to the &rear; configuration file
+   <filename>/etc/rear/local.conf</filename> and, if needed, edit the Bash
+   scripts that are part of the &rear; framework. In particular, you need to
+   define the following tasks that &rear; should do:
   </para>
 
   <itemizedlist>
-   <listitem>
-    <formalpara>
-     <title>When your system is booted with UEFI</title>
-     <para>
-      If your system boots with a UEFI boot loader, install the package
-      <package>ebiso</package> and add the following line to
-      <filename>/etc/rear/local.conf</filename>:
-     </para>
-    </formalpara>
-    <screen>ISO_MKISOFS_BIN="/usr/bin/ebiso"</screen>
-    <para>
-     If your system boots with &uefisecboot;, you must also add the following line:
-    </para>
-<screen>SECURE_BOOT_BOOTLOADER="/boot/efi/EFI/BOOT/shim.efi"</screen>
-    <para>
-     For more information about &rear; configuration variables for UEFI, see the
-     <filename>/usr/share/rear/conf/default.conf</filename> file.
-    </para>
-   </listitem>
    <listitem>
     <formalpara>
      <title>How to back up files and how to create and store the disaster recovery system</title>
@@ -440,10 +427,10 @@
    </listitem>
    <listitem>
     <formalpara>
-     <title>What to re-create exactly (partitioning, file systems, mount points, etc.)</title>
+     <title>What to re-create (partitioning, file systems, mount points, etc.)</title>
      <para>
-      This can be defined in <filename>/etc/rear/local.conf</filename> (for
-      example, what to exclude). To re-create non-standard systems, you may
+      This can be defined in <filename>/etc/rear/local.conf</filename>.
+      To re-create non-standard systems, you may
       need to enhance the Bash scripts.
      </para>
     </formalpara>
@@ -461,73 +448,73 @@
   </itemizedlist>
 
   <para>
-   To configure &rear;, add your options to the
-   <filename>/etc/rear/local.conf</filename> configuration file. (The former
-   configuration file <filename>/etc/rear/sites.conf</filename> has been
-   removed from the package. However, if you have such a file from your last
-   setup, &rear; will still use it.)
-  </para>
-
-  <para>
-   All &rear; configuration variables and their default values are set in
+   All &rear; configuration variables and their default values are explained in
    <filename>/usr/share/rear/conf/default.conf</filename>.
-   Some example files (<filename>*example.conf</filename>) for user configurations
-   (for example, what is set in <filename>/etc/rear/local.conf</filename>)
-   are available in the <filename>examples</filename> subdirectory.
-   Find more information in the &rear; man page.
   </para>
   <para>
-   You should start with a matching example configuration file as template
-   and adapt it as needed to create your particular configuration file.
-   Copy various options from several example configuration files and paste them
-   into your specific <filename>/etc/rear/local.conf</filename> file that
-   matches your particular system.
-   Do not use original example configuration files, because they provide an
-   overview of variables that can be used for specific setups.
+   Below are some examples of useful configuration options. You can also find example files
+   for different scenarios in the <filename>/usr/share/rear/conf/examples/</filename> subdirectory.
+   Use these to help you create your <filename>/etc/rear/local.conf</filename> file.
   </para>
 
   <example xml:id="ex-ha-rear-nfs-server-backup">
    <title>Using an NFS server to store the file backup</title>
-   <para>
-    &rear; can be used in different scenarios. The following example uses
-    an NFS server as storage for the file backup.
-   </para>
-  </example>
-
-  <procedure>
-   <step>
+  <orderedlist>
+   <listitem>
     <para>
      Set up an NFS server with &yast; as described in the
      <link
       xlink:href="https://documentation.suse.com/sles-15/html/SLES-all/cha-nfs.html">
       &admin; for &sls; &productnumber;</link>.
     </para>
-   </step>
-   <step>
+   </listitem>
+   <listitem>
     <para>
      Define the configuration for your NFS server in the
      <filename>/etc/exports</filename> file. Make sure the directory on the
-     NFS server (where you want the backup data to be available), has the
-     right mount options. For example:
-    </para>
-<screen><replaceable>/srv/nfs</replaceable> *([...],rw,no_root_squash,[...])</screen>
-    <para>
-     Replace <filename>/srv/nfs</filename> with the path to your
-     backup data on the NFS server and adjust the mount options. You might
+     NFS server has the right mount options. For example, you might
      need <literal>no_root_squash</literal> as the
      <command>rear mkbackup</command> command runs as &rootuser;.
+     For more information, see <command>man exports</command>.
     </para>
-   </step>
-   <step>
+   </listitem>
+   <listitem>
     <para>
      Adjust the various <varname>BACKUP</varname> parameters in the
      configuration file <filename>/etc/rear/local.conf</filename> to make
-     &rear; store the file backup on the respective NFS server. Find 
+     &rear; store the file backup on the respective NFS server. Find
      examples in your installed system under
      <filename>/usr/share/rear/conf/examples/SLE*-example.conf</filename>.
     </para>
-   </step>
-  </procedure>
+   </listitem>
+  </orderedlist>
+  </example>
+
+  <example xml:id="ex-ha-rear-config-sles-btrfs">
+    <title>Backing up Btrfs subvolumes with <command>tar</command></title>
+    <para>
+     Btrfs is set up with subvolumes, but <command>tar</command> creates backups with the
+     <option>--one-file-system</option> option, which excludes subvolumes. Therefore, the
+     mount points for the subvolumes must be explicitly included in the &rear; configuration.
+    </para>
+    <para>
+     Add this configuration snippet to <filename>/etc/rear/local.conf</filename> and
+     adjust it according to your setup. For more information and additional options, see the
+     example files at <filename>/usr/share/rear/conf/examples/SLE*-btrfs-example.conf</filename>.
+    </para>
+<screen>OUTPUT=ISO
+BACKUP=NETFS
+BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
+BACKUP_PROG_INCLUDE=( /root /boot/grub2/i386-pc /tmp /opt /var /boot/grub2/x86_64-efi /srv /usr/local )</screen>
+    <tip>
+      <title>Mount points for <literal>BACKUP_PROG_INCLUDE</literal></title>
+      <para>
+        You can find the mount points for the subvolumes on your specific system by running
+        the following command:
+      </para>
+<screen>&prompt.root;<command>findmnt -n -r -o TARGET -t btrfs | grep -v '^/$' | egrep -v 'snapshots|crash'</command></screen>
+    </tip>
+  </example>
 
   <example xml:id="ex-ha-rear-config-EMC">
    <title>Using third-party backup tools like EMC NetWorker</title>
@@ -541,11 +528,56 @@
     adjust it according to your setup:
    </para>
 <screen>BACKUP=NSR
-    OUTPUT=ISO
-    BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
-    OUTPUT_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
-    NSRSERVER=<replaceable>backupserver.&exampledomain;</replaceable>
-    RETENTION_TIME="Month"</screen>
+OUTPUT=ISO
+BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
+OUTPUT_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
+NSRSERVER=<replaceable>backupserver.&exampledomain;</replaceable>
+RETENTION_TIME="Month"</screen>
+   <para>
+    For more information about supported third-party backup tools, see
+    <command>man rear</command>, section <citetitle>BACKUP SOFTWARE INTEGRATION</citetitle>.
+   </para>
+  </example>
+
+  <example xml:id="ex-ha-rear-config-multipath">
+    <title>Backing up multipath devices</title>
+    <para>
+     By default, &rear; ignores file systems on multipath devices because it assumes they are
+     on remote storage, not part of the local system. You can make &rear; include these
+     file systems by adding the following line to <filename>/etc/rear/local.conf</filename>:
+    </para>
+    <screen>AUTOEXCLUDE_MULTIPATH=n</screen>
+  </example>
+
+  <example xml:id="ex-ex-ha-rear-config-UEFI">
+    <title>Booting your system with UEFI</title>
+    <para>
+      If your system boots with a UEFI boot loader, additional configuration is required:
+    </para>
+    <orderedlist>
+      <listitem>
+        <para>
+          Install the package <package>ebiso</package>:
+        </para>
+<screen>&prompt.root;<command>zypper install ebiso</command></screen>
+      </listitem>
+      <listitem>
+        <para>
+          Add the following line to <filename>/etc/rear/local.conf</filename>:
+        </para>
+<screen>ISO_MKISOFS_BIN="/usr/bin/ebiso"</screen>
+      </listitem>
+      <listitem>
+        <para>
+          If your system boots with &uefisecboot;, you must also add the following line:
+        </para>
+<screen>SECURE_BOOT_BOOTLOADER="/boot/efi/EFI/sles/shim.efi"</screen>
+      </listitem>
+    </orderedlist>
+    <para>
+     For more information about &rear; configuration variables for UEFI, see the
+     <filename>/usr/share/rear/conf/default.conf</filename> file.
+    </para>
   </example>
  </sect1>
  <sect1 xml:id="sec-ha-rear-mkbackup">