#2772 Issue `closed`: User guide: Missing info from layout configuration page¶

Labels: support / question, no-issue-activity

danboid opened issue at 2022-03-11 14:16:¶

I've yet to actually use rear but after looking at the docs I'm unclear about a few things that I would like to see made more clear in the docs, specifically the layout configuration page.

I want to use rear to backup a Ubuntu 20.04 server which uses md raid for the system disks (MDRAID 10) and ZFS for /home. /home is going to be backed up to another server using syncoid to preserve the snapshots so I want to exclude /home and also stop it backing up the systemrescuecd USB drive I've got plugged into it.

It looks like I'll need to use EXCLUDE_BACKUP=() for this but that presents a few questions not covered in the current docs:

What is the correct format for an exclude value?

EXCLUDE_BACKUP=( "fs:/home" )

or

EXCLUDE_BACKUP=( "/home" )

I have seen both formats used in the current docs.

How do I define multiple exclude paths or devices? Do I use multiple EXCLUDE_BACKUP statements, one with comma separated values or one with space separated values or...
Can I add devices to EXCLUDE_BACKUP or is it only for local fs paths / mounted disks?
I see there is also EXCLUDE_RECREATE but I don't understand what this is for? The comments / current docs say

# Exclude components during component recreation

What is 'component recreation'? It would seem this isn't just another name for restore because there is also EXCLUDE_RESTORE=() so I'm unsure if I should also use EXCLUDE_RECREATE?

danboid commented at 2022-03-12 17:59:¶

It seems like default.conf is a more comprehensive source of documentation for rear than the user guide. After having a quick skim through that, I think I should actually be using:

EXCLUDE_MOUNTPOINTS=(/home)

To stop rear backing up /home rather than EXCLUDE_BACKUP=() and it seems multiple values are separated by spaces so am I right in thinking that to stop rear backing up /home and my USB disk it would be a statement like:

EXCLUDE_MOUNTPOINTS=(/home /media/user/disk)

So, what is EXCLUDE_BACKUP=() used for and what are the 'components' it manages?

We should probably update the layout config page of the rear user guide to include EXCLUDE_MOUNTPOINTS as one of the highlighted functions as this must be a commonly used option if its what's used to prevent always connected USB drives, backup dirs etc from being backed up accidentally.

danboid commented at 2022-03-13 10:44:¶

Its OT for this issue but does rear support restoring Ubuntu or proxmox with ZFS root partitions?

~/src/rear$ grep -r zpool *
~/src/rear$

I strongly suspect that means there is currently no ZFS support in rear right?

Do I need to pass any special options to backup a md RAID10 array or will rear handle all the RAID stuff automatically when using Linux's software RAID?

jsmeix commented at 2022-03-14 12:00:¶

ReaR currently does not support ZFS,
see https://github.com/rear/rear/issues/1932
and https://github.com/rear/rear/issues/2563

jsmeix commented at 2022-03-14 12:58:¶

In general what is called "components" in ReaR is separated
from what is called "backup" in ReaR.

"Components" are basically what is stored during "rear mkrescue" in
var/lib/rear/layout/disklayout.conf
i.e. the disk layout components like disks, partitions, and filesystems.

"Backup" are the files (and directories) that are saved
via a backup method that is specified by BACKUP= ...
during "rear mkbackuponly".

"rear mkbackup" results the same as
first "rear mkrescue" and then "rear mkbackuponly"
(you may inspect what "rear -s mkrescue" shows compared
to "rear -s mkbackup" and/or "rear -s mkbackuponly").

Currently there are various EXCLUDE user config variables
in usr/share/rear/conf/default.conf for example things like

BACKUP_PROG_EXCLUDE
BACKUP_ONLY_EXCLUDE
EXCLUDE_MOUNTPOINTS
EXCLUDE_MD
EXCLUDE_VG
EXCLUDE_COMPONENTS
AUTOEXCLUDE_DISKS
AUTOEXCLUDE_MULTIPATH
AUTOEXCLUDE_AUTOFS
AUTOEXCLUDE_PATH
EXCLUDE_BACKUP
EXCLUDE_RECREATE
EXCLUDE_RESTORE

Those config variables are used by ReaR in various specific ways
and they may interact with each other in certain automated ways.

For some basic information what each one should do
see the descriptions in usr/share/rear/conf/default.conf

For exact information what each one actually does and
how each one may interact with other config variables
you would have to inspect the scripts where each one is used.
For example to find out in which scripts BACKUP_PROG_EXCLUDE
is used you may use a command like

# find usr/share/rear/ -type f -name '*.sh' | xargs grep -l 'BACKUP_PROG_EXCLUDE'

and then inspect the actual bash code in those scripts.

But in particular BACKUP_PROG_EXCLUDE is only supported
for ReaR's "internal" backup methods like "BACKUP=NETFS"
in particular with "BACKUP_PROG=tar".

For ReaR's "external" backup methods see the section
"BACKUP SOFTWARE INTEGRATION" in "man rear"
e.g. online at
https://github.com/rear/rear/blob/master/doc/rear.8.adoc

See also the section "Relax-and-Recover versus backup and restore" in
https://en.opensuse.org/SDB:Disaster_Recovery

jsmeix commented at 2022-03-14 13:04:¶

Regarding the syntax of disk layout components:

To see the exact syntax of components in your particular case
it should help to inspect after "rear mkrescue" was run
the var/lib/rear/layout/diskdeps.conf file that lists the
components for example something like

/dev/sda1 /dev/sda
/dev/sda2 /dev/sda
/dev/sda3 /dev/sda
/dev/sda5 /dev/sda
fs:/ /dev/sda5
swap:/dev/sda1 /dev/sda1

Also var/lib/rear/layout/disktodo.conf lists the components, cf.
https://github.com/rear/rear/issues/2229#issuecomment-529953810

For an example how EXCLUDE_COMPONENTS had worked for me
to exclude a particular filesystem, see
https://github.com/rear/rear/issues/1767#issuecomment-378925290

That issue https://github.com/rear/rear/issues/1767
also describes that it is currently not possible
to exclude a partition between other partitions, see
https://github.com/rear/rear/issues/1767#issuecomment-379758551
and
https://github.com/rear/rear/issues/1771

danboid commented at 2022-03-14 17:52:¶

Thanks for your comprehensive replies @jsmeix ! I've not tested a rear restore yet but I believe I've created a successful rear backup now by using EXCLUDE_COMPONENTS() to exclude my ZFS pool members and external disks.

So why does rear have both EXCLUDE_COMPONENTS() and EXCLUDE_MOUNTPOINTS()? Do these not serve the same purpose?

jsmeix commented at 2022-03-16 13:18:¶

EXCLUDE_COMPONENTS and EXCLUDE_MOUNTPOINTS behave differently:

See usr/share/rear/conf/default.conf

# Exclude filesystems by specifying their mountpoints. Will be automatically added to the
# $BACKUP_PROG_EXCLUDE array during backup to prevent the excluded filesystems' data to
# be backed up
# examples: /tmp
#           /media/bigdisk
EXCLUDE_MOUNTPOINTS=()
...
# Exclude any component from the recovery image.
# Some component types need a prefix:
# - filesystems: "fs:/var/cache"
# - physical volumes: "pv:/dev/sda2"
# - swap: "swap:/dev/mapper/system-swap"
# Volume groups look like: "/dev/system".
# If in doubt about the correct syntax, consult /var/lib/rear/layout/disktodo.conf
EXCLUDE_COMPONENTS=()

so the difference is that elements in the EXCLUDE_MOUNTPOINTS array
get automatically added to the $BACKUP_PROG_EXCLUDE array
while EXCLUDE_COMPONENTS excludes only those
disk layout components (like disks, partitions, and filesystems)
to be recreated during "rear recover".

For the actual differences inspect their actual code places:

# find usr/sbin/rear usr/share/rear/ -type f | xargs grep 'EXCLUDE_COMPONENTS'

usr/share/rear/conf/default.conf:EXCLUDE_COMPONENTS=()
usr/share/rear/layout/save/default/310_include_exclude.sh:for component in "${EXCLUDE_COMPONENTS[@]}" ; do
usr/share/rear/layout/save/default/310_include_exclude.sh:    LogPrint "Excluding component $component in EXCLUDE_COMPONENTS"

# find usr/sbin/rear usr/share/rear/ -type f | xargs grep 'EXCLUDE_MOUNTPOINTS'

usr/share/rear/conf/default.conf:# but not implicitly also all excluded mountpoints in EXCLUDE_MOUNTPOINTS:
usr/share/rear/conf/default.conf:EXCLUDE_MOUNTPOINTS=()
usr/share/rear/conf/default.conf:# You must also exclude the corresponding mountpoints in EXCLUDE_MOUNTPOINTS (see above)
usr/share/rear/conf/default.conf:# EXCLUDE_VG and EXCLUDE_MOUNTPOINTS will get populated automatically, if needed
usr/share/rear/conf/default.conf:# This is different from EXCLUDE_MOUNTPOINTS, which accepts only mountpoints.
usr/share/rear/layout/save/default/310_include_exclude.sh:# EXCLUDE_MOUNTPOINTS
usr/share/rear/layout/save/default/310_include_exclude.sh:#for mountpoint in "${EXCLUDE_MOUNTPOINTS[@]}" ; do
usr/share/rear/layout/save/default/310_include_exclude.sh:#    LogPrint "Excluding mountpoint $mountpoint in EXCLUDE_MOUNTPOINTS"
usr/share/rear/layout/save/default/320_autoexclude.sh:        if IsInArray "$mountpoint" "${EXCLUDE_MOUNTPOINTS[@]}" ; then
usr/share/rear/restore/NBU/default/300_create_nbu_restore_fs_list.sh:if [ ${#EXCLUDE_MOUNTPOINTS[@]} -gt 0 ]
usr/share/rear/restore/NBU/default/300_create_nbu_restore_fs_list.sh:    for FS in ${EXCLUDE_MOUNTPOINTS[@]}
usr/share/rear/backup/NETFS/default/400_create_include_exclude_files.sh:            if ! IsInArray "$mountpoint" "${EXCLUDE_MOUNTPOINTS[@]}" ; then
usr/share/rear/backup/NETFS/default/400_create_include_exclude_files.sh:    for excluded_mountpoint in "${EXCLUDE_MOUNTPOINTS[@]}" ; do

In particular
usr/share/rear/layout/save/default/310_include_exclude.sh
and
usr/share/rear/layout/save/default/320_autoexclude.sh
look interesting regarding EXCLUDE_MOUNTPOINTS
where the former (310_include_exclude.sh) shows that
a filesystem in EXCLUDE_MOUNTPOINTS still gets recreated because

# If a filesystem is excluded (for backup) we still may need to perform an
# mkfs on the filesystem as it may be referenced in fstab and mounted
# automatically, or is needed for a separate restore.

except its whole disk gets automatically excluded via
usr/share/rear/layout/save/default/320_autoexclude.sh

And there is also EXCLUDE_RECREATE with similar
but again somewhat different behaviour.

Personally I find the whole exclude functionality "hairy", cf.
https://github.com/rear/rear/issues/2229#issuecomment-531474858

The current state is the grown result of many contributions
by various different (mostly voluntary) contributors over a long time
which is much appreciated because without all those continuous
contributions there would be basically no ReaR at all.

We cannot "just clean it up" because each specific functionality
is used by particular users and we want to
"Maintain backward compatibility", cf.
https://github.com/rear/rear/wiki/Coding-Style#maintain-backward-compatibility
and we neither have the time nor the manpower
to clean it up in a proper backward compatible way.

danboid commented at 2022-04-26 16:38:¶

@jsmeix

Rear has the function ONLY_INCLUDE_VG=( "vg0" ) which I can use to backup the root partition / LVM VG on my server that uses LVM but rear doesn't seem to have a matching ONLY_INCLUDE_MD() to only backup specific soft RAID arrays to do a similar thing on my server that does not use LVM but does use mdadm. Is there a reason for this other than its not been implemented yet?

I want to use rear to backup /dev/md0 on a server thats not using LVM but I don't want to backup its external disks or ZFS pool. Here is the relevant bit of its /var/lib/rear/layout/disklayout.conf :

raid /dev/md0 metadata=1.2 level=raid10 raid-devices=4 uuid=a6bd74fc:af330bdc:c585f8e7:9a338b9f layout=n2 chunk=512 devices=/dev/nvme2n1p2,/dev/nvme1n1p2,/dev/nvme0n1p2,/dev/nvme3n1p2
part /dev/md0 3839413452800 1048576 rear-noname none /dev/md0p1
# Filesystems (only ext2,ext3,ext4,vfat,xfs,reiserfs,btrfs are supported).
# Format: fs <device> <mountpoint> <fstype> [uuid=<uuid>] [label=<label>] [<attributes>]
fs /dev/md0p1 / xfs uuid=be0e9e5b-d449-4f4b-969f-248b81d13222 label=  options=rw,relatime,attr2,inode64,logbufs=8,logbsize=32k,sunit=1024,swidth=2048,noquota

Can I tell rear to only backup this md raid partition or must I instead do it by excluding all the components I don't want?

jsmeix commented at 2022-04-28 12:14:¶

I don't know if someone may have tried to implement ONLY_INCLUDE_MD
some longer time ago but failed because it was impossible for some reason
but I guess there no reason other than it is not yet implemented and
I know that noone asked for such functionality since some time
so likely you are the first who asks for such functionality.

So when you need ONLY_INCLUDE_MD see the sections
"How to adapt and enhance Relax-and-Recover" and
"How to contribute to Relax-and-Recover" in
https://en.opensuse.org/SDB:Disaster_Recovery

Perhaps it is easier to explicitly exclude all unwanted components?

Because ReaR config files (in particular etc/rear/local.conf)
are executed via the bash builtin source you can run commands
within your configuration files, in particular commands to
automatically set configuration values as you need, see
https://github.com/rear/rear/blob/master/etc/rear/local.conf
So you could automatically exclude all unwanted components.

Have in mind that etc/rear/local.conf is executed
for "rear mkrescue" which runs on the original system
and also for "rear recover" which runs inside the ReaR recovery system.

So expected storage devices may not exist on new replacement hardware
or unexpected storage devices may exist on used replacement hardware
when etc/rear/local.conf is executed during "rear recover", cf. the section
"Prepare replacement hardware for disaster recovery" in
https://en.opensuse.org/SDB:Disaster_Recovery

Simply put:
Commands in ReaR config files must also work
within the recovery system on replacement hardware.

github-actions commented at 2022-06-28 03:26:¶

Stale issue message

[Export of Github issue for rear/rear.]

#2772 Issue closed: User guide: Missing info from layout configuration page¶