// This document describes all aspects of the system disk layout generation in
// Relax-and-Recover.

= Layout configuration
Jeroen Hoekx <jeroen.hoekx@hamok.be>
2011-09-10

== General overview
The disk layout generation code in Relax-and-Recover is responsible for the
faithful recreation of the disk layout of the original system. It gathers
information about any component in the system layout. Components supported in
Relax-and-Recover include:

- Partitions
- Logical volume management (LVM)
- Software RAID (MD)
- Encrypted volumes (LUKS)
- Multipath disks
- Swap
- Filesystems
- Btrfs Volumes
- DRBD
- HP SmartArray controllers

Relax-and-Recover detects dependencies between these components.

During the rescue media creation phase, Relax-and-Recover centralizes all
information in one file. During recovery, that file is used to generate the
actual commands to recreate the components. Relax-and-Recover allows
customizations and manual editing in all these phases.

== Layout information gathered during rescue image creation
Layout information is stored in +/var/lib/rear/layout/disklayout.conf+. The term 'layout file' in this document refers to this particular file.

Consider the information from the following system as an example:
----------------------------------
disk /dev/sda 160041885696 msdos
# disk /dev/sdb 320072933376 msdos
# disk /dev/sdc 1999696297984 msdos
part /dev/sda 209682432 32768 primary boot /dev/sda1
part /dev/sda 128639303680 209719296 primary lvm /dev/sda2
part /dev/sda 31192862720 128849022976 primary none /dev/sda3
# part /dev/sdb 162144912384 32256 primary none /dev/sdb1
# part /dev/sdb 152556666880 162144944640 primary none /dev/sdb2
# part /dev/sdb 5371321856 314701611520 primary boot /dev/sdb3
# part /dev/sdc 1073741824000 1048576 primary boot /dev/sdc1
# part /dev/sdc 925953425408 1073742872576 primary lvm /dev/sdc2
# lvmdev /dev/backup /dev/sdc2 cJp4Mt-Vkgv-hVlr-wTMb-0qeA-FX7j-3C60p5 1808502784
lvmdev /dev/system /dev/mapper/disk N4Hpdc-DkBP-Hdm6-Z6FH-VixZ-7tTb-LiRt0w 251244544
# lvmgrp /dev/backup 4096 220764 904249344
lvmgrp /dev/system 4096 30669 125620224
# lvmvol /dev/backup backup 12800 104857600 
# lvmvol /dev/backup externaltemp 38400 314572800 
lvmvol /dev/system root 2560 20971520 
lvmvol /dev/system home 5120 41943040 
lvmvol /dev/system var 2560 20971520 
lvmvol /dev/system swap 512 4194304 
lvmvol /dev/system vmxfs 7680 62914560 
lvmvol /dev/system kvm 5000 40960000 
fs /dev/mapper/system-root / ext4 uuid=dbb0c0d4-7b9a-40e2-be83-daafa14eff6b label= blocksize=4096 reserved_blocks=131072 max_mounts=21 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-home /home ext4 uuid=e9310015-6043-48cd-a37d-78dbfdba1e3b label= blocksize=4096 reserved_blocks=262144 max_mounts=38 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-var /var ext4 uuid=a12bb95f-99f2-42c6-854f-1cb3f144d662 label= blocksize=4096 reserved_blocks=131072 max_mounts=23 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-vmxfs /vmware xfs uuid=7457d2ab-8252-4f41-bab6-607316259975 label=  options=rw,noatime
fs /dev/mapper/system-kvm /kvm ext4 uuid=173ab1f7-8450-4176-8cf7-c09b47f5e3cc label= blocksize=4096 reserved_blocks=256000 max_mounts=21 check_interval=180d options=rw,noatime,commit=0
fs /dev/sda1 /boot ext3 uuid=f6b08566-ea5e-46f9-8f73-5e8ffdaa7be6 label= blocksize=1024 reserved_blocks=10238 max_mounts=35 check_interval=180d options=rw,commit=0
swap /dev/mapper/system-swap uuid=9f347fc7-1605-4788-98fd-fca828beedf1 label=
crypt /dev/mapper/disk /dev/sda2 cipher=aes-xts-plain hash=sha1 uuid=beafe67c-d9a4-4992-80f1-e87791a543bb
----------------------------------
This document will continue to use this example to explore the various options
available in Relax-and-Recover. The exact syntax of the layout file is
described in a later section. It is already clear that this file is human
readable and thus human editable. It is also machine readable and all
information necessary to restore a system is listed.

It's easy to see that there are 3 disks attached to the system. +/dev/sda+ is the internal disk of the system. Its filesystems are normally mounted. The other devices are external disks. One of them has just normal partitions. The other one has a physical volume on one of the partitions.

== Excluding components

=== Autoexcludes

Relax-and-Recover has reasonable defaults when creating the recovery
information. It has commented out the two external disks and any
component that's part of it. The reason is that no mounted filesystem
uses these two disks. After all, you don't want to recreate your
backup disk when you're recovering your system.

If we mount the filesystem on +/dev/mapper/backup-backup+ on +/backup+,
Relax-and-Recover will think that it's necessary to recreate the filesystem:
----------------------------------
disk /dev/sda 160041885696 msdos
# disk /dev/sdb 320072933376 msdos
disk /dev/sdc 1999696297984 msdos
part /dev/sda 209682432 32768 primary boot /dev/sda1
part /dev/sda 128639303680 209719296 primary lvm /dev/sda2
part /dev/sda 31192862720 128849022976 primary none /dev/sda3
# part /dev/sdb 162144912384 32256 primary none /dev/sdb1
# part /dev/sdb 152556666880 162144944640 primary none /dev/sdb2
# part /dev/sdb 5371321856 314701611520 primary boot /dev/sdb3
part /dev/sdc 1073741824000 1048576 primary boot /dev/sdc1
part /dev/sdc 925953425408 1073742872576 primary lvm /dev/sdc2
lvmdev /dev/backup /dev/sdc2 cJp4Mt-Vkgv-hVlr-wTMb-0qeA-FX7j-3C60p5 1808502784
lvmdev /dev/system /dev/mapper/disk N4Hpdc-DkBP-Hdm6-Z6FH-VixZ-7tTb-LiRt0w 251244544
lvmgrp /dev/backup 4096 220764 904249344
lvmgrp /dev/system 4096 30669 125620224
lvmvol /dev/backup backup 12800 104857600 
lvmvol /dev/backup externaltemp 38400 314572800 
lvmvol /dev/system root 2560 20971520 
lvmvol /dev/system home 5120 41943040 
lvmvol /dev/system var 2560 20971520 
lvmvol /dev/system swap 512 4194304 
lvmvol /dev/system vmxfs 7680 62914560 
lvmvol /dev/system kvm 5000 40960000 
fs /dev/mapper/system-root / ext4 uuid=dbb0c0d4-7b9a-40e2-be83-daafa14eff6b label= blocksize=4096 reserved_blocks=131072 max_mounts=21 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-home /home ext4 uuid=e9310015-6043-48cd-a37d-78dbfdba1e3b label= blocksize=4096 reserved_blocks=262144 max_mounts=38 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-var /var ext4 uuid=a12bb95f-99f2-42c6-854f-1cb3f144d662 label= blocksize=4096 reserved_blocks=131072 max_mounts=23 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-vmxfs /vmware xfs uuid=7457d2ab-8252-4f41-bab6-607316259975 label=  options=rw,noatime
fs /dev/mapper/system-kvm /kvm ext4 uuid=173ab1f7-8450-4176-8cf7-c09b47f5e3cc label= blocksize=4096 reserved_blocks=256000 max_mounts=21 check_interval=180d options=rw,noatime,commit=0
fs /dev/sda1 /boot ext3 uuid=f6b08566-ea5e-46f9-8f73-5e8ffdaa7be6 label= blocksize=1024 reserved_blocks=10238 max_mounts=35 check_interval=180d options=rw,commit=0
fs /dev/mapper/backup-backup /backup ext4 uuid=da20354a-dc4c-4bef-817c-1c92894bb002 label= blocksize=4096 reserved_blocks=655360 max_mounts=24 check_interval=180d options=rw
swap /dev/mapper/system-swap uuid=9f347fc7-1605-4788-98fd-fca828beedf1 label=
crypt /dev/mapper/disk /dev/sda2 cipher=aes-xts-plain hash=sha1 uuid=beafe67c-d9a4-4992-80f1-e87791a543bb
----------------------------------

This behavior is controlled by the +AUTOEXCLUDE_DISKS=y+ parameter in
+default.conf+. If we unset it in the local configuration, Relax-and-Recover
will no longer exclude it automatically.

A similar mechanism exists for multipath disks. The +AUTOEXCLUDE_MULTIPATH=y+
variable in +default.conf+ prevents Relax-and-Recover from overwriting
multipath disks. Typically, they are part of the SAN disaster recovery
strategy. However, there can be cases where you want to recover them. The
information is retained in +disklayout.conf+.

Some filesystems are excluded from the layout file by default if their
mountpoints are located under certain directories. This behavior is
controlled by the +AUTOEXCLUDE_PATH+ variable. It is an array of
paths. If a mountpoint of a filesystem is under one of the paths, the
filesystem is excluded. The default value includes +/media+, +/mnt+
and +/tmp+. See +default.conf+ for the full list. Note that if one of
the paths is itself a mountpoint, the filesystem is not excluded. So,
if +/media+ is a mounted filesystem, it will not be excluded, but if
we mount the +/dev/mapper/backup-backup+ filesystem on
+/media/backup+, it will get excluded, as the mountpoint is under
+/media+.

=== Manual excludes
It seems prudent to prevent the external drives from ever being backed-up or overwritten. The default configuration contains these lines:
----------------------------------
# Exclude components from being backed up, recreation information is active
EXCLUDE_BACKUP=()

# Exclude components during component recreation
# will be added to EXCLUDE_BACKUP (it is not backed up)
# recreation information gathered, but commented out
EXCLUDE_RECREATE=()

# Exclude components during the backup restore phase
# only used to exclude files from the restore.
EXCLUDE_RESTORE=()
----------------------------------

To prevent an inadvertently mounted backup filesystem being added to the restore list, the easiest way is to add the filesystem to the +EXCLUDE_RECREATE+ array.
----------------------------------
EXCLUDE_RECREATE+=( "fs:/backup" )
----------------------------------

The layout file is as expected:
----------------------------------
disk /dev/sda 160041885696 msdos
# disk /dev/sdb 320072933376 msdos
# disk /dev/sdc 1999696297984 msdos
part /dev/sda 209682432 32768 primary boot /dev/sda1
part /dev/sda 128639303680 209719296 primary lvm /dev/sda2
part /dev/sda 31192862720 128849022976 primary none /dev/sda3
# part /dev/sdb 162144912384 32256 primary none /dev/sdb1
# part /dev/sdb 152556666880 162144944640 primary none /dev/sdb2
# part /dev/sdb 5371321856 314701611520 primary boot /dev/sdb3
# part /dev/sdc 1073741824000 1048576 primary boot /dev/sdc1
# part /dev/sdc 925953425408 1073742872576 primary lvm /dev/sdc2
# lvmdev /dev/backup /dev/sdc2 cJp4Mt-Vkgv-hVlr-wTMb-0qeA-FX7j-3C60p5 1808502784
lvmdev /dev/system /dev/mapper/disk N4Hpdc-DkBP-Hdm6-Z6FH-VixZ-7tTb-LiRt0w 251244544
# lvmgrp /dev/backup 4096 220764 904249344
lvmgrp /dev/system 4096 30669 125620224
# lvmvol /dev/backup backup 12800 104857600 
# lvmvol /dev/backup externaltemp 38400 314572800 
lvmvol /dev/system root 2560 20971520 
lvmvol /dev/system home 5120 41943040 
lvmvol /dev/system var 2560 20971520 
lvmvol /dev/system swap 512 4194304 
lvmvol /dev/system vmxfs 7680 62914560 
lvmvol /dev/system kvm 5000 40960000 
fs /dev/mapper/system-root / ext4 uuid=dbb0c0d4-7b9a-40e2-be83-daafa14eff6b label= blocksize=4096 reserved_blocks=131072 max_mounts=21 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-home /home ext4 uuid=e9310015-6043-48cd-a37d-78dbfdba1e3b label= blocksize=4096 reserved_blocks=262144 max_mounts=38 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-var /var ext4 uuid=a12bb95f-99f2-42c6-854f-1cb3f144d662 label= blocksize=4096 reserved_blocks=131072 max_mounts=23 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-vmxfs /vmware xfs uuid=7457d2ab-8252-4f41-bab6-607316259975 label=  options=rw,noatime
fs /dev/mapper/system-kvm /kvm ext4 uuid=173ab1f7-8450-4176-8cf7-c09b47f5e3cc label= blocksize=4096 reserved_blocks=256000 max_mounts=21 check_interval=180d options=rw,noatime,commit=0
fs /dev/sda1 /boot ext3 uuid=f6b08566-ea5e-46f9-8f73-5e8ffdaa7be6 label= blocksize=1024 reserved_blocks=10238 max_mounts=35 check_interval=180d options=rw,commit=0
# fs /dev/mapper/backup-backup /backup ext4 uuid=da20354a-dc4c-4bef-817c-1c92894bb002 label= blocksize=4096 reserved_blocks=655360 max_mounts=24 check_interval=180d options=rw
swap /dev/mapper/system-swap uuid=9f347fc7-1605-4788-98fd-fca828beedf1 label=
crypt /dev/mapper/disk /dev/sda2 cipher=aes-xts-plain hash=sha1 uuid=beafe67c-d9a4-4992-80f1-e87791a543bb
----------------------------------

Another approach would be to exclude the backup volume group. This is achieved by adding this line to the local configuration:
----------------------------------
EXCLUDE_RECREATE+=( "/dev/backup" )
----------------------------------

== Restore to the same hardware
Restoring the system to the same hardware is simple. Type +rear recover+ in
the rescue system prompt. Relax-and-Recover will detect that it's restoring to
the same system and will make sure things like UUIDs match. It also asks for
your LUKS encryption password.

Once the restore of the backup has completed, Relax-and-Recover will install
the bootloader and the system is back in working order.
----------------------------------
RESCUE firefly:~ # rear recover
Relax-and-Recover 0.0.0 / $Date$
NOTICE: Will do driver migration
Comparing disks.
Disk configuration is identical, proceeding with restore.
Start system layout restoration.
Creating partitions for disk /dev/sda (msdos)
Please enter the password for disk(/dev/sda2):
Enter LUKS passphrase: 
Please re-enter the password for disk(/dev/sda2):
Enter passphrase for /dev/sda2: 
Creating LVM PV /dev/mapper/disk
Restoring LVM VG system
Creating ext4-filesystem / on /dev/mapper/system-root
Mounting filesystem /
Creating ext4-filesystem /home on /dev/mapper/system-home
Mounting filesystem /home
Creating ext4-filesystem /var on /dev/mapper/system-var
Mounting filesystem /var
Creating xfs-filesystem /vmware on /dev/mapper/system-vmxfs
meta-data=/dev/mapper/system-vmxfs isize=256    agcount=4, agsize=1966080 blks
         =                       sectsz=512   attr=2, projid32bit=0
data     =                       bsize=4096   blocks=7864320, imaxpct=25
         =                       sunit=0      swidth=0 blks
naming   =version 2              bsize=4096   ascii-ci=0
log      =internal log           bsize=4096   blocks=3840, version=2
         =                       sectsz=512   sunit=0 blks, lazy-count=1
realtime =none                   extsz=4096   blocks=0, rtextents=0
Mounting filesystem /vmware
Creating ext4-filesystem /kvm on /dev/mapper/system-kvm
Mounting filesystem /kvm
Creating ext3-filesystem /boot on /dev/sda1
Mounting filesystem /boot
Creating swap on /dev/mapper/system-swap
Disk layout created.
Please start the restore process on your backup host.

Make sure that you restore the data into '/mnt/local' instead of '/' because the
hard disks of the recovered system are mounted there.

Please restore your backup in the provided shell and, when finished, type exit
in the shell to continue recovery.

Welcome to Relax-and-Recover. Run "rear recover" to restore your system !

rear>
----------------------------------
== Restore to different hardware
There are two ways to deal with different hardware. One is being lazy and dealing with problems when you encounter them. The second option is to plan in advance. Both are valid approaches. The lazy approach works fine when you are in control of the restore and you have good knowledge of the components in your system. The second approach is preferable in disaster recovery situations or migrations where you know the target hardware in advance and the actual restore can be carried out by less knowledgeable people.

=== The Ad-Hoc Way
Relax-and-Recover will assist you somewhat in case it notices different disk
sizes. It will ask you to map each differently sized disk to a disk in the
target system. Partitions will be resized. Relax-and-Recover is careful not to
resize your boot partition, since this is often the one with the most
stringent sizing constraints. In fact, it only resizes LVM and RAID
partitions.

Let's try to restore our system to a different system. Instead of one 160G
disk, there is now one 5G and one 10G disk. That's not enough space to restore
the complete system, but for purposes of this demonstration, we do not care
about that. We're also not going to use the first disk, but we just want to
show that Relax-and-Recover handles the renaming automatically.

----------------------------------
RESCUE firefly:~ # rear recover
Relax-and-Recover 0.0.0 / $Date$
NOTICE: Will do driver migration
Comparing disks.
Device sda has size 5242880000, 160041885696 expected
Switching to manual disk layout configuration.
Disk sda does not exist in the target system. Please choose the appropriate replacement.
1) sda
2) sdb
3) Do not map disk.
#? 2
2011-09-10 16:17:10 Disk sdb chosen as replacement for sda.
Disk sdb chosen as replacement for sda.
This is the disk mapping table:
    /dev/sda /dev/sdb
Please confirm that '/var/lib/rear/layout/disklayout.conf' is as you expect.

1) View disk layout (disklayout.conf)  4) Go to Relax-and-Recover shell
2) Edit disk layout (disklayout.conf)  5) Continue recovery
3) View original disk space usage      6) Abort Relax-and-Recover
----------------------------------

Ok, mapping the disks was not that hard. If Relax-and-Recover insists on us
checking the disklayout file, we'd better do that.

----------------------------------
#? 1
disk /dev/sdb 160041885696 msdos
# disk _REAR1_ 320072933376 msdos
# disk /dev/sdc 1999696297984 msdos
part /dev/sdb 209682432 32768 primary boot /dev/sdb1
part /dev/sdb -20916822016 209719296 primary lvm /dev/sdb2
part /dev/sdb 31192862720 128849022976 primary none /dev/sdb3
# part _REAR1_ 162144912384 32256 primary none _REAR1_1
# part _REAR1_ 152556666880 162144944640 primary none _REAR1_2
# part _REAR1_ 5371321856 314701611520 primary boot _REAR1_3
# part /dev/sdc 1073741824000 1048576 primary boot /dev/sdc1
# part /dev/sdc 925953425408 1073742872576 primary lvm /dev/sdc2
# lvmdev /dev/backup /dev/sdc2 cJp4Mt-Vkgv-hVlr-wTMb-0qeA-FX7j-3C60p5 1808502784
lvmdev /dev/system /dev/mapper/disk N4Hpdc-DkBP-Hdm6-Z6FH-VixZ-7tTb-LiRt0w 251244544
# lvmgrp /dev/backup 4096 220764 904249344
lvmgrp /dev/system 4096 30669 125620224
# lvmvol /dev/backup backup 12800 104857600 
# lvmvol /dev/backup externaltemp 38400 314572800 
lvmvol /dev/system root 2560 20971520 
lvmvol /dev/system home 5120 41943040 
lvmvol /dev/system var 2560 20971520 
lvmvol /dev/system swap 512 4194304 
lvmvol /dev/system vmxfs 7680 62914560 
lvmvol /dev/system kvm 5000 40960000 
fs /dev/mapper/system-root / ext4 uuid=dbb0c0d4-7b9a-40e2-be83-daafa14eff6b label= blocksize=4096 reserved_blocks=131072 max_mounts=21 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-home /home ext4 uuid=e9310015-6043-48cd-a37d-78dbfdba1e3b label= blocksize=4096 reserved_blocks=262144 max_mounts=38 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-var /var ext4 uuid=a12bb95f-99f2-42c6-854f-1cb3f144d662 label= blocksize=4096 reserved_blocks=131072 max_mounts=23 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-vmxfs /vmware xfs uuid=7457d2ab-8252-4f41-bab6-607316259975 label=  options=rw,noatime
fs /dev/mapper/system-kvm /kvm ext4 uuid=173ab1f7-8450-4176-8cf7-c09b47f5e3cc label= blocksize=4096 reserved_blocks=256000 max_mounts=21 check_interval=180d options=rw,noatime,commit=0
fs /dev/sdb1 /boot ext3 uuid=f6b08566-ea5e-46f9-8f73-5e8ffdaa7be6 label= blocksize=1024 reserved_blocks=10238 max_mounts=35 check_interval=180d options=rw,commit=0
# fs /dev/mapper/backup-backup /backup ext4 uuid=da20354a-dc4c-4bef-817c-1c92894bb002 label= blocksize=4096 reserved_blocks=655360 max_mounts=24 check_interval=180d options=rw
swap /dev/mapper/system-swap uuid=9f347fc7-1605-4788-98fd-fca828beedf1 label=
crypt /dev/mapper/disk /dev/sdb2 cipher=aes-xts-plain hash=sha1 uuid=beafe67c-d9a4-4992-80f1-e87791a543bb

1) View disk layout (disklayout.conf)
2) Edit disk layout (disklayout.conf)
3) View original disk space usage
4) Go to Relax-and-Recover shell
5) Continue recovery
6) Abort Relax-and-Recover
#? 
----------------------------------
The renaming operation was successful.

On the other hand, we can already see quite a few problems. A partition with negative sizes. I do not think any tool would like to create that. Still, we don't care at this moment. Do you like entering partition sizes in bytes? Neither do I. There has to be a better way to handle it. We will show it during the next step.

The /kvm and /vmware filesystems are quite big. We don't care about them, so just put some nice comments on them and their logical volumes.

The resulting layout file looks like this:
----------------------------------
disk /dev/sdb 160041885696 msdos
# disk _REAR1_ 320072933376 msdos
# disk /dev/sdc 1999696297984 msdos
part /dev/sdb 209682432 32768 primary boot /dev/sdb1
part /dev/sdb -20916822016 209719296 primary lvm /dev/sdb2
part /dev/sdb 31192862720 128849022976 primary none /dev/sdb3
# part _REAR1_ 162144912384 32256 primary none _REAR1_1
# part _REAR1_ 152556666880 162144944640 primary none _REAR1_2
# part _REAR1_ 5371321856 314701611520 primary boot _REAR1_3
# part /dev/sdc 1073741824000 1048576 primary boot /dev/sdc1
# part /dev/sdc 925953425408 1073742872576 primary lvm /dev/sdc2
# lvmdev /dev/backup /dev/sdc2 cJp4Mt-Vkgv-hVlr-wTMb-0qeA-FX7j-3C60p5 1808502784
lvmdev /dev/system /dev/mapper/disk N4Hpdc-DkBP-Hdm6-Z6FH-VixZ-7tTb-LiRt0w 251244544
# lvmgrp /dev/backup 4096 220764 904249344
lvmgrp /dev/system 4096 30669 125620224
# lvmvol /dev/backup backup 12800 104857600 
# lvmvol /dev/backup externaltemp 38400 314572800 
lvmvol /dev/system root 2560 20971520 
lvmvol /dev/system home 5120 41943040 
lvmvol /dev/system var 2560 20971520 
lvmvol /dev/system swap 512 4194304 
#lvmvol /dev/system vmxfs 7680 62914560 
#lvmvol /dev/system kvm 5000 40960000 
fs /dev/mapper/system-root / ext4 uuid=dbb0c0d4-7b9a-40e2-be83-daafa14eff6b label= blocksize=4096 reserved_blocks=131072 max_mounts=21 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-home /home ext4 uuid=e9310015-6043-48cd-a37d-78dbfdba1e3b label= blocksize=4096 reserved_blocks=262144 max_mounts=38 check_interval=180d options=rw,commit=0
fs /dev/mapper/system-var /var ext4 uuid=a12bb95f-99f2-42c6-854f-1cb3f144d662 label= blocksize=4096 reserved_blocks=131072 max_mounts=23 check_interval=180d options=rw,commit=0
#fs /dev/mapper/system-vmxfs /vmware xfs uuid=7457d2ab-8252-4f41-bab6-607316259975 label=  options=rw,noatime
#fs /dev/mapper/system-kvm /kvm ext4 uuid=173ab1f7-8450-4176-8cf7-c09b47f5e3cc label= blocksize=4096 reserved_blocks=256000 max_mounts=21 check_interval=180d options=rw,noatime,commit=0
fs /dev/sdb1 /boot ext3 uuid=f6b08566-ea5e-46f9-8f73-5e8ffdaa7be6 label= blocksize=1024 reserved_blocks=10238 max_mounts=35 check_interval=180d options=rw,commit=0
# fs /dev/mapper/backup-backup /backup ext4 uuid=da20354a-dc4c-4bef-817c-1c92894bb002 label= blocksize=4096 reserved_blocks=655360 max_mounts=24 check_interval=180d options=rw
swap /dev/mapper/system-swap uuid=9f347fc7-1605-4788-98fd-fca828beedf1 label=
crypt /dev/mapper/disk /dev/sdb2 cipher=aes-xts-plain hash=sha1 uuid=beafe67c-d9a4-4992-80f1-e87791a543bb
----------------------------------

Let's continue recovery.

----------------------------------
1) View disk layout (disklayout.conf)
2) Edit disk layout (disklayout.conf)
3) View original disk space usage
4) Go to Relax-and-Recover shell
5) Continue recovery
6) Abort Relax-and-Recover
#? 5
Partition /dev/sdb3 size reduced to fit on disk.
Please confirm that '/var/lib/rear/layout/diskrestore.sh' is as you expect.

1) View restore script (diskrestore.sh)
2) Edit restore script (diskrestore.sh)
3) View original disk space usage
4) Go to Relax-and-Recover shell
5) Continue recovery
6) Abort Relax-and-Recover
#? 
----------------------------------

Now, this is where human friendly resizes are possible. Edit the file. Find the partition creation code.

----------------------------------
if create_component "/dev/sdb" "disk" ; then
# Create /dev/sdb (disk)
LogPrint "Creating partitions for disk /dev/sdb (msdos)"
parted -s /dev/sdb mklabel msdos >&2
parted -s /dev/sdb mkpart primary 32768B 209715199B >&2
parted -s /dev/sdb set 1 boot on >&2
parted -s /dev/sdb mkpart primary 209719296B -20707102721B >&2
parted -s /dev/sdb set 2 lvm on >&2
parted -s /dev/sdb mkpart primary 18446744053002452992B 10485759999B >&2
# Wait some time before advancing
sleep 10
----------------------------------
It's simple bash code. Change it to use better values. Parted is happy to accept partitions in Megabytes.
----------------------------------
if create_component "/dev/sdb" "disk" ; then
# Create /dev/sdb (disk)
LogPrint "Creating partitions for disk /dev/sdb (msdos)"
parted -s /dev/sdb mklabel msdos >&2
parted -s /dev/sdb mkpart primary 1M 200M >&2
parted -s /dev/sdb set 1 boot on >&2
parted -s /dev/sdb mkpart primary 200M 10485759999B >&2
parted -s /dev/sdb set 2 lvm on >&2
# Wait some time before advancing
sleep 10
----------------------------------
The same action should be done for the remaining logical volumes. We would like them to fit on the disk.
----------------------------------
if create_component "/dev/mapper/system-root" "lvmvol" ; then
# Create /dev/mapper/system-root (lvmvol)
LogPrint "Creating LVM volume system/root"
lvm lvcreate -l 2560 -n root system >&2
component_created "/dev/mapper/system-root" "lvmvol"
else
    LogPrint "Skipping /dev/mapper/system-root (lvmvol) as it has already been created."
fi
----------------------------------
No-one but a computer likes to think in extents, so we size it a comfortable 5G.
----------------------------------
if create_component "/dev/mapper/system-root" "lvmvol" ; then
# Create /dev/mapper/system-root (lvmvol)
LogPrint "Creating LVM volume system/root"
lvm lvcreate -L 5G -n root system >&2
component_created "/dev/mapper/system-root" "lvmvol"
else
    LogPrint "Skipping /dev/mapper/system-root (lvmvol) as it has already been created."
fi
----------------------------------
Do the same thing for the other logical volumes and choose number 5, continue.
----------------------------------
1) View restore script (diskrestore.sh)
2) Edit restore script (diskrestore.sh)
3) View original disk space usage
4) Go to Relax-and-Recover shell
5) Continue recovery
6) Abort Relax-and-Recover
#? 5
Start system layout restoration.
Creating partitions for disk /dev/sdb (msdos)
Please enter the password for disk(/dev/sdb2):
Enter LUKS passphrase: 
Please re-enter the password for disk(/dev/sdb2):
Enter passphrase for /dev/sdb2: 
Creating LVM PV /dev/mapper/disk
Creating LVM VG system
Creating LVM volume system/root
Creating LVM volume system/home
Creating LVM volume system/var
Creating LVM volume system/swap
Creating ext4-filesystem / on /dev/mapper/system-root
Mounting filesystem /
Creating ext4-filesystem /home on /dev/mapper/system-home
An error occurred during layout recreation.

1) View Relax-and-Recover log
2) View original disk space usage
3) Go to Relax-and-Recover shell
4) Edit restore script (diskrestore.sh)
5) Continue restore script
6) Abort Relax-and-Recover
#?
----------------------------------
An error... Did you expect it? I didn't.

Relax-and-Recover produces exceptionally good logs. Let's check them.
----------------------------------
+++ tune2fs -r 262144 -c 38 -i 180d /dev/mapper/system-home
tune2fs: reserved blocks count is too big (262144)
tune2fs 1.41.14 (22-Dec-2010)
Setting maximal mount count to 38
Setting interval between checks to 15552000 seconds
2011-09-10 16:27:35 An error occurred during layout recreation.
----------------------------------
Yes, we resized the home partition from 20GB to 2G in the previous step. The root user wants more reserved blocks than the total number of available blocks.

Fixing it is simple. Edit the restore script, option 4. Find the code responsible for filesystem creation.

----------------------------------
if create_component "fs:/home" "fs" ; then
# Create fs:/home (fs)
LogPrint "Creating ext4-filesystem /home on /dev/mapper/system-home"
mkfs -t ext4 -b 4096 /dev/mapper/system-home >&2
tune2fs -U e9310015-6043-48cd-a37d-78dbfdba1e3b /dev/mapper/system-home >&2
tune2fs -r 262144 -c 38 -i 180d /dev/mapper/system-home >&2
LogPrint "Mounting filesystem /home"
mkdir -p /mnt/local/home
mount /dev/mapper/system-home /mnt/local/home
component_created "fs:/home" "fs"
else
    LogPrint "Skipping fs:/home (fs) as it has already been created."
fi
----------------------------------
The +-r+ parameter is causing the error. We just remove it and do the same for the other filesystems.
----------------------------------
if create_component "fs:/home" "fs" ; then
# Create fs:/home (fs)
LogPrint "Creating ext4-filesystem /home on /dev/mapper/system-home"
mkfs -t ext4 -b 4096 /dev/mapper/system-home >&2
tune2fs -U e9310015-6043-48cd-a37d-78dbfdba1e3b /dev/mapper/system-home >&2
tune2fs -c 38 -i 180d /dev/mapper/system-home >&2
LogPrint "Mounting filesystem /home"
mkdir -p /mnt/local/home
mount /dev/mapper/system-home /mnt/local/home
component_created "fs:/home" "fs"
else
    LogPrint "Skipping fs:/home (fs) as it has already been created."
fi
----------------------------------
Continue the restore script.
----------------------------------
1) View Relax-and-Recover log
2) View original disk space usage
3) Go to Relax-and-Recover shell
4) Edit restore script (diskrestore.sh)
5) Continue restore script
6) Abort Relax-and-Recover
#? 5
Start system layout restoration.
Skipping /dev/sdb (disk) as it has already been created.
Skipping /dev/sdb1 (part) as it has already been created.
Skipping /dev/sdb2 (part) as it has already been created.
Skipping /dev/sdb3 (part) as it has already been created.
Skipping /dev/mapper/disk (crypt) as it has already been created.
Skipping pv:/dev/mapper/disk (lvmdev) as it has already been created.
Skipping /dev/system (lvmgrp) as it has already been created.
Skipping /dev/mapper/system-root (lvmvol) as it has already been created.
Skipping /dev/mapper/system-home (lvmvol) as it has already been created.
Skipping /dev/mapper/system-var (lvmvol) as it has already been created.
Skipping /dev/mapper/system-swap (lvmvol) as it has already been created.
Skipping fs:/ (fs) as it has already been created.
Creating ext4-filesystem /home on /dev/mapper/system-home
Mounting filesystem /home
Creating ext4-filesystem /var on /dev/mapper/system-var
Mounting filesystem /var
Creating ext3-filesystem /boot on /dev/sdb1
Mounting filesystem /boot
Creating swap on /dev/mapper/system-swap
Disk layout created.
----------------------------------
That looks the way we want it. Notice how Relax-and-Recover detected that it
had already created quite a few components and did not try to recreate them
anymore.

=== Planning In Advance ===
Relax-and-Recover makes it possible to define the layout on the target system
even before the backup is taken. All one has to do is to move the
+/var/lib/rear/layout/disklayout.conf+ file to +/etc/rear/disklayout.conf+ and
edit it. This won't be overwritten on future backup runs. During recovery,
Relax-and-Recover will use that file instead of the snapshot of the original
system.

== Disk layout file syntax ==

This section describes the syntax of all components in the Relax-and-Recover
layout file /var/lib/rear/layout/disklayout.conf

One cannot rely on backward compatibility between ReaR versions.
Normally the layout file /var/lib/rear/layout/disklayout.conf is created from scratch
for each run of "rear mkrescue/mkbackup" so a newer ReaR version creates it anew
with the right syntax for this ReaR version which is the exact same ReaR
that gets included in the ReaR recovery system together with this layout file
to recreate the disk layout during "rear recover".
Only when a selfmade /etc/rear/disklayout.conf is used then it must be adapted
by the user when he upgrades to a newer ReaR version.

The syntax is of the form
----------------------------------
keyword value1 value2 value3 ...
----------------------------------
where keyword denotes one kind of component (disk, partition, filesystem, ...)
and keyword and all the values are separated by single space characters
(which means spaces in values are forbidden - there is neither quoting nor escaping)
so that one can get the lines that belong to a particular component
with particular value1 and value2 via simple commands like
----------------------------------
grep "^keyword value1 value2 " /var/lib/rear/layout/disklayout.conf
----------------------------------
(provided there is a value3 after value2 so there is a space after value2).

No whitespace is allowed at the beginning of lines in the disklayout.conf file.
Lines that start with a # (number sign, hash, or pound sign) are comments.
All other lines start with a component keyword.

None of the component keywords is a leading substring of another component keyword
(e.g. disk is not a leading substring of raiddisk) so that one could even get
only those lines that belong to a particular component via sloppy commands like
----------------------------------
grep ^keyword /var/lib/rear/layout/disklayout.conf
----------------------------------
regardless that the proper command (in particular for scripts) is
----------------------------------
grep "^keyword " /var/lib/rear/layout/disklayout.conf
----------------------------------
with a single space after the keyword as delimiter.

For most component keywords the values are positional parameters
(if there is no value a dummy value like 'none' must be used)
so empty values in between are invalid syntax
which can result arbitrarily bad failures during "rear recover".

For some component keywords the parameters have a form like
----------------------------------
keyword value1 value2 optionA=valueA optionB=valueB ...
----------------------------------
where the first ones are positional parameters but not the option=value parameters
so empty option=value parameters are allowed, for example see the 'raidarray' keyword.

For details the matching scripts need to be inspected how things actually work
for a particular component keyword (i.e. what is implemented in the code).

Syntax of the individual component keyword descriptions below:

Normal text has to be present verbatim.
Angle brackets "<" and ">" delimit a value that can be edited.
Quotes " inside the angle brackets indicate a verbatim option,
often used together with a / to indicate multiple options.
Parenthesis "(" ")" inside explain the expected unit.
No unit suffix should be present, unless specifically indicated.
Square brackets "[" and "]" indicate an optional parameter.
They can be excluded when hand-crafting a layout file line.

=== Disks ===
----------------------------------
disk <name> <size(B)> <partition label> 
----------------------------------

=== Partitions ===
----------------------------------
part <disk name> <size(B)> <start(B)> <partition name/type> <flags/"none"> <partition name>
----------------------------------

=== Software RAID arrays ===
----------------------------------
raidarray /dev/<kernel RAID device> level=<RAID level> raid-devices=<nr of active devices> devices=<component device1,component device2,...> [name=<array name>] [metadata=<metadata style>] [uuid=<UUID>] [layout=<data layout>] [chunk=<chunk size>] [spare-devices=<nr of spare devices>] [size=<container size>]
----------------------------------

=== Software RAID disks ===
----------------------------------
raiddisk <devname> <size(bytes)> <partition label type>
----------------------------------

=== Multipath ===
----------------------------------
multipath /dev/<name> <size(B)> <partition label> <slave1,slave2,...>
----------------------------------

=== Physical Volumes ===
----------------------------------
lvmdev /dev/<volume_group> <device> [<uuid>] [<size(bytes)>]
----------------------------------

=== Volume Groups ===
----------------------------------
lvmgrp <volume_group> <extentsize> [<size(extents)>] [<size(bytes)>]
----------------------------------

=== Logical Volumes ===
----------------------------------
lvmvol <volume_group> <name> <size(bytes)> <layout> [key:value ...]
----------------------------------

=== LUKS Devices ===
----------------------------------
crypt /dev/mapper/<name> <device> [type=<type>] [cipher=<cipher>] [key_size=<key size>] [hash=<hash function>] [uuid=<uuid>] [keyfile=<keyfile>] [password=<password>]
----------------------------------

=== DRBD ===
----------------------------------
drbd /dev/drbd<nr> <drbd resource name> <device>
----------------------------------

=== Filesystems ===
----------------------------------
fs <device> <mountpoint> <filesystem type> [uuid=<uuid>] [label=<label>] [blocksize=<block size(B)>] [<reserved_blocks=<nr of reserved blocks>] [max_mounts=<nr>] [check_interval=<number of days>d] [options=<filesystem options>]
----------------------------------

=== Btrfs Default SubVolumes ===
----------------------------------
btrfsdefaultsubvol <device> <mountpoint> <btrfs_subvolume_ID> <btrfs_subvolume_path>
----------------------------------

=== Btrfs Normal SubVolumes ===
----------------------------------
btrfsnormalsubvol <device> <mountpoint> <btrfs_subvolume_ID> <btrfs_subvolume_path>
----------------------------------

=== Btrfs Mounted SubVolumes ===
----------------------------------
btrfsmountedsubvol <device> <subvolume_mountpoint> <mount_options> <btrfs_subvolume_path>
----------------------------------

=== Swap ===
----------------------------------
swap <device> [uuid=<uuid>] [label=<label>]
----------------------------------

=== HP SmartArray Controllers ===
----------------------------------
smartarray <slot number>
----------------------------------

=== HP SmartArray Logical Drives ===
----------------------------------
logicaldrive <device> <slot nr>|<array name>|<logical drive name> raid=<raid level> drives=<drive1,drive2> [spares=<spare1,spare2>] [sectors=<sectors>] [stripesize=<stripe size>]
----------------------------------

=== TCG Opal 2-compliant Self-Encrypting Disks ===
----------------------------------
opaldisk <device> [boot=<[yn]>] [password=<password>]
----------------------------------


== Disk Restore Script (recover mode) ==

The +/var/lib/rear/layout/disklayout.conf+ file is being used as input
during +rear recover+ to create on-the-fly a script called +/var/lib/rear/layout/diskrestore.sh+.

When something goes wrong during the recreation of partitions, volume groups, ...
you will be thrown in edit mode and you can make the modification needed.
However, it is desirable to have a preview mode before doing the recovery
so you can review the +diskrestore.sh+ script before doing any recovery.
It is better to find mistakes, obsolete arguments and so on before then later, right?

Gratien wrote a script to accomplish this (script is not part of ReaR)
and is meant for debugging reasons only.
For more details see http://www.it3.be/2016/06/08/rear-diskrestore/

