Skip to content

Commit

Permalink
Improve ReaR backup config examples (#404)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@tahliar
tahliar committed Aug 28, 2024
1 parent 86805ba commit 8b5c247
Showing 1 changed file with 109 additions and 77 deletions.
186 changes: 109 additions & 77 deletions xml/ha_rear.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,10 +168,12 @@

<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>
Expand Down Expand Up @@ -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>
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>
In particular, you need to define the following tasks that &rear;
should do:
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>
Expand All @@ -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>
Expand All @@ -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
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>
Expand All @@ -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">
Expand Down

0 comments on commit 8b5c247

Please sign in to comment.