Skip to content

Commit 20abdde

Browse files
tahliartahliar
committed
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
1 parent 7ce74e7 commit 20abdde

File tree

1 file changed

+109
-77
lines changed

1 file changed

+109
-77
lines changed

‎xml/ha_rear.xml

+109-77
Original file line numberDiff line numberDiff line change
@@ -168,10 +168,12 @@
168168

169169
<sect2 xml:id="sec-ha-rear-concept-versions">
170170
<title>&rear; version updates</title>
171+
171172
<para>
172-
&productname; &productnumber; ships with &rear; version 2.3, provided by the
173-
package <package>rear23a</package>.
173+
To see which versions of &rear; are available with &productname; &productnumber;,
174+
run the following command:
174175
</para>
176+
<screen>&prompt.root;<command>zypper search --type package --verbose rear</command></screen>
175177

176178
<note>
177179
<title>Find important information in changelogs</title>
@@ -397,38 +399,23 @@
397399
</sect1>
398400
<sect1 xml:id="sec-ha-rear-config">
399401
<title>Setting up &rear; and your backup solution</title>
400-
401402
<para>
402-
To set up &rear;, you need to edit at least the &rear;
403-
configuration file <filename>/etc/rear/local.conf</filename> and, if
404-
needed, the Bash scripts that are part of the &rear; framework.
403+
To install the latest version of &rear;, run the following command:
405404
</para>
406-
405+
<screen>&prompt.root;<command>zypper install rear</command></screen>
406+
<para>
407+
If you need to install an earlier version of &rear;, you can specify the package version.
408+
For example:
409+
</para>
410+
<screen>&prompt.root;<command>zypper install rear23a</command></screen>
407411
<para>
408-
In particular, you need to define the following tasks that &rear;
409-
should do:
412+
To configure &rear;, add your settings to the &rear; configuration file
413+
<filename>/etc/rear/local.conf</filename> and, if needed, edit the Bash
414+
scripts that are part of the &rear; framework. In particular, you need to
415+
define the following tasks that &rear; should do:
410416
</para>
411417

412418
<itemizedlist>
413-
<listitem>
414-
<formalpara>
415-
<title>When your system is booted with UEFI</title>
416-
<para>
417-
If your system boots with a UEFI boot loader, install the package
418-
<package>ebiso</package> and add the following line to
419-
<filename>/etc/rear/local.conf</filename>:
420-
</para>
421-
</formalpara>
422-
<screen>ISO_MKISOFS_BIN="/usr/bin/ebiso"</screen>
423-
<para>
424-
If your system boots with &uefisecboot;, you must also add the following line:
425-
</para>
426-
<screen>SECURE_BOOT_BOOTLOADER="/boot/efi/EFI/BOOT/shim.efi"</screen>
427-
<para>
428-
For more information about &rear; configuration variables for UEFI, see the
429-
<filename>/usr/share/rear/conf/default.conf</filename> file.
430-
</para>
431-
</listitem>
432419
<listitem>
433420
<formalpara>
434421
<title>How to back up files and how to create and store the disaster recovery system</title>
@@ -440,10 +427,10 @@
440427
</listitem>
441428
<listitem>
442429
<formalpara>
443-
<title>What to re-create exactly (partitioning, file systems, mount points, etc.)</title>
430+
<title>What to re-create (partitioning, file systems, mount points, etc.)</title>
444431
<para>
445-
This can be defined in <filename>/etc/rear/local.conf</filename> (for
446-
example, what to exclude). To re-create non-standard systems, you may
432+
This can be defined in <filename>/etc/rear/local.conf</filename>.
433+
To re-create non-standard systems, you may
447434
need to enhance the Bash scripts.
448435
</para>
449436
</formalpara>
@@ -461,73 +448,73 @@
461448
</itemizedlist>
462449

463450
<para>
464-
To configure &rear;, add your options to the
465-
<filename>/etc/rear/local.conf</filename> configuration file. (The former
466-
configuration file <filename>/etc/rear/sites.conf</filename> has been
467-
removed from the package. However, if you have such a file from your last
468-
setup, &rear; will still use it.)
469-
</para>
470-
471-
<para>
472-
All &rear; configuration variables and their default values are set in
451+
All &rear; configuration variables and their default values are explained in
473452
<filename>/usr/share/rear/conf/default.conf</filename>.
474-
Some example files (<filename>*example.conf</filename>) for user configurations
475-
(for example, what is set in <filename>/etc/rear/local.conf</filename>)
476-
are available in the <filename>examples</filename> subdirectory.
477-
Find more information in the &rear; man page.
478453
</para>
479454
<para>
480-
You should start with a matching example configuration file as template
481-
and adapt it as needed to create your particular configuration file.
482-
Copy various options from several example configuration files and paste them
483-
into your specific <filename>/etc/rear/local.conf</filename> file that
484-
matches your particular system.
485-
Do not use original example configuration files, because they provide an
486-
overview of variables that can be used for specific setups.
455+
Below are some examples of useful configuration options. You can also find example files
456+
for different scenarios in the <filename>/usr/share/rear/conf/examples/</filename> subdirectory.
457+
Use these to help you create your <filename>/etc/rear/local.conf</filename> file.
487458
</para>
488459

489460
<example xml:id="ex-ha-rear-nfs-server-backup">
490461
<title>Using an NFS server to store the file backup</title>
491-
<para>
492-
&rear; can be used in different scenarios. The following example uses
493-
an NFS server as storage for the file backup.
494-
</para>
495-
</example>
496-
497-
<procedure>
498-
<step>
462+
<orderedlist>
463+
<listitem>
499464
<para>
500465
Set up an NFS server with &yast; as described in the
501466
<link
502467
xlink:href="https://documentation.suse.com/sles-15/html/SLES-all/cha-nfs.html">
503468
&admin; for &sls; &productnumber;</link>.
504469
</para>
505-
</step>
506-
<step>
470+
</listitem>
471+
<listitem>
507472
<para>
508473
Define the configuration for your NFS server in the
509474
<filename>/etc/exports</filename> file. Make sure the directory on the
510-
NFS server (where you want the backup data to be available), has the
511-
right mount options. For example:
512-
</para>
513-
<screen><replaceable>/srv/nfs</replaceable> *([...],rw,no_root_squash,[...])</screen>
514-
<para>
515-
Replace <filename>/srv/nfs</filename> with the path to your
516-
backup data on the NFS server and adjust the mount options. You might
475+
NFS server has the right mount options. For example, you might
517476
need <literal>no_root_squash</literal> as the
518477
<command>rear mkbackup</command> command runs as &rootuser;.
478+
For more information, see <command>man exports</command>.
519479
</para>
520-
</step>
521-
<step>
480+
</listitem>
481+
<listitem>
522482
<para>
523483
Adjust the various <varname>BACKUP</varname> parameters in the
524484
configuration file <filename>/etc/rear/local.conf</filename> to make
525485
&rear; store the file backup on the respective NFS server. Find
526486
examples in your installed system under
527487
<filename>/usr/share/rear/conf/examples/SLE*-example.conf</filename>.
528488
</para>
529-
</step>
530-
</procedure>
489+
</listitem>
490+
</orderedlist>
491+
</example>
492+
493+
<example xml:id="ex-ha-rear-config-sles-btrfs">
494+
<title>Backing up Btrfs subvolumes with <command>tar</command></title>
495+
<para>
496+
Btrfs is set up with subvolumes, but <command>tar</command> creates backups with the
497+
<option>--one-file-system</option> option, which excludes subvolumes. Therefore, the
498+
mount points for the subvolumes must be explicitly included in the &rear; configuration.
499+
</para>
500+
<para>
501+
Add this configuration snippet to <filename>/etc/rear/local.conf</filename> and
502+
adjust it according to your setup. For more information and additional options, see the
503+
example files at <filename>/usr/share/rear/conf/examples/SLE*-btrfs-example.conf</filename>.
504+
</para>
505+
<screen>OUTPUT=ISO
506+
BACKUP=NETFS
507+
BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
508+
BACKUP_PROG_INCLUDE=( /root /boot/grub2/i386-pc /tmp /opt /var /boot/grub2/x86_64-efi /srv /usr/local )</screen>
509+
<tip>
510+
<title>Mount points for <literal>BACKUP_PROG_INCLUDE</literal></title>
511+
<para>
512+
You can find the mount points for the subvolumes on your specific system by running
513+
the following command:
514+
</para>
515+
<screen>&prompt.root;<command>findmnt -n -r -o TARGET -t btrfs | grep -v '^/$' | egrep -v 'snapshots|crash'</command></screen>
516+
</tip>
517+
</example>
531518

532519
<example xml:id="ex-ha-rear-config-EMC">
533520
<title>Using third-party backup tools like EMC NetWorker</title>
@@ -541,11 +528,56 @@
541528
adjust it according to your setup:
542529
</para>
543530
<screen>BACKUP=NSR
544-
OUTPUT=ISO
545-
BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
546-
OUTPUT_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
547-
NSRSERVER=<replaceable>backupserver.&exampledomain;</replaceable>
548-
RETENTION_TIME="Month"</screen>
531+
OUTPUT=ISO
532+
BACKUP_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
533+
OUTPUT_URL=nfs://<replaceable>host.&exampledomain;/path/to/rear/backup</replaceable>
534+
NSRSERVER=<replaceable>backupserver.&exampledomain;</replaceable>
535+
RETENTION_TIME="Month"</screen>
536+
<para>
537+
For more information about supported third-party backup tools, see
538+
<command>man rear</command>, section <citetitle>BACKUP SOFTWARE INTEGRATION</citetitle>.
539+
</para>
540+
</example>
541+
542+
<example xml:id="ex-ha-rear-config-multipath">
543+
<title>Backing up multipath devices</title>
544+
<para>
545+
By default, &rear; ignores file systems on multipath devices because it assumes they are
546+
on remote storage, not part of the local system. You can make &rear; include these
547+
file systems by adding the following line to <filename>/etc/rear/local.conf</filename>:
548+
</para>
549+
<screen>AUTOEXCLUDE_MULTIPATH=n</screen>
550+
</example>
551+
552+
<example xml:id="ex-ex-ha-rear-config-UEFI">
553+
<title>Booting your system with UEFI</title>
554+
<para>
555+
If your system boots with a UEFI boot loader, additional configuration is required:
556+
</para>
557+
<orderedlist>
558+
<listitem>
559+
<para>
560+
Install the package <package>ebiso</package>:
561+
</para>
562+
<screen>&prompt.root;<command>zypper install ebiso</command></screen>
563+
</listitem>
564+
<listitem>
565+
<para>
566+
Add the following line to <filename>/etc/rear/local.conf</filename>:
567+
</para>
568+
<screen>ISO_MKISOFS_BIN="/usr/bin/ebiso"</screen>
569+
</listitem>
570+
<listitem>
571+
<para>
572+
If your system boots with &uefisecboot;, you must also add the following line:
573+
</para>
574+
<screen>SECURE_BOOT_BOOTLOADER="/boot/efi/EFI/sles/shim.efi"</screen>
575+
</listitem>
576+
</orderedlist>
577+
<para>
578+
For more information about &rear; configuration variables for UEFI, see the
579+
<filename>/usr/share/rear/conf/default.conf</filename> file.
580+
</para>
549581
</example>
550582
</sect1>
551583
<sect1 xml:id="sec-ha-rear-mkbackup">

0 commit comments

Comments
 (0)