// FIXME: Original design document needs a lot of rework

= Design concepts
Schlomo Schapiro, Gratien D'haese, Dag Wieers

== The Workflow System
Relax-and-Recover is built as a modular framework. A call of +rear <command>+
will invoke the following general workflow:

  1. *Configuration:* Collect system information to assemble a correct
     configuration (default, arch, OS, OS_ARCH, OS_VER, site, local).
     See the output of +rear dump+ for an example.
     +
     Read config files for the combination of system attributes. Always
     read 'default.conf' first and 'site.conf', 'local.conf' last.

  2. Create work area in '/tmp/rear.$$/' and start logging to
     '/var/log/rear/rear-hostname.log'

  3. Run the workflow script for the specified command:
     '/usr/share/rear/lib/<command>-workflow.sh'

  4. Cleanup work area

== Workflow - Make Rescue Media
The application will have the following general workflow which is represented
by appropriately named scripts in various subdirectories:

  1. *Prep:* Prepare the build area by copying a skeleton filesystem layout.
     This can also come from various sources (FS layout for arch, OS, OS_VER,
     Backup-SW, Output, ...)

  2. *Analyse disklayout*: Analyse the system disklayout to create the '/var/lib/rear/layout/' data

  3. *Analyse (Rescue):* Analyse the system to create the rescue system
     (network, binary dependencies, ...)

  4. *Build:* Build the rescue image by copying together everything required

  5. *Pack:* Package the kernel and initrd image together

  6. *Backup:* (Optionally) run the backup software to create a current backup

  7. *Output:* Copy / Install the rescue system (kernel+initrd+(optionally)
     backups) into the target environment (e.g. PXE boot, write on tape,
     write on CD/DVD)

  8. *Cleanup:* Cleanup the build area from temporary files

The configuration must define the +BACKUP+ and +OUTPUT+ methods. Valid choices are:

|====
|NAME        | TYPE    | Description                              | Implement in Phase
|NETFS       | BACKUP  | Copy files to NFS/CIFS share             | done
|TAPE        | BACKUP  | Copy files to tape(s)                    | done
|DUPLICITY   | BACKUP  | Copy files to the Cloud                  | done
|NSR         | BACKUP  | Use Legato Networker                     | done
|TSM         | BACKUP  | Use Tivoli Storage Manager               | done
|DP          | BACKUP  | Use Micro Focus Data Protector           | done
|NBU         | BACKUP  | Use Symantec NetBackup                   | done
|BACULA      | BACKUP  | Use Bacula                               | done
|BAREOS      | BACKUP  | Use fork of Bacula                       | done
|RSYNC       | BACKUP  | Use rsync to remote location             | done
|RBME        | BACKUP  | Use Rsync Backup Made Easy               | done
|FDRUPSTREAM | BACKUP  | Use FDR/Upstream                         | done
|BORG        | BACKUP  | Use Borg                                 | done
|            |         |                                          |
|ISO         | OUTPUT  | Write result to ISO9660 image            | done
|OBDR        | OUTPUT  | Create OBDR Tape                         | done
|PXE         | OUTPUT  | Create PXE bootable files on TFTP server | done
|USB         | OUTPUT  | Create bootable USB device               | done
|====

== Workflow - Recovery
The result of the analysis is written into configuration files under
'/etc/rear/recovery/'. This directory is copied together with the other
Relax-and-Recover directories onto the rescue system where the same
framework runs a different workflow - the recovery workflow.

The recovery workflow consists of these parts (identically named modules
are indeed the same):

  1. *Config:* By utilizing the same configuration module, the same
     configuration variable are available for the recovery, too.
     This makes writing pairs of backup/restore modules much easier.

  2. *Verify:* Verify the integrity and sanity of the recovery data and
     check the hardware found to determine, whether a recovery will be
     likely to succeed. If not, then we abort the workflow so as not to
     touch the hard disks if we don't believe that we would manage to
     successfully recover the system on this hardware.

  3. *Recreate:* Recreate the FS layout (partitioning, LVM, raid,
     filesystems, ...) and mount it under /mnt/local

  4. *Restore:* Restore files and directories from the backup to '/mnt/local/'.
     This module is the analog to the Backup module

  5. *Finalize:* Install boot loader, finalize system, dump recovery log
     onto '/var/log/rear/' in the recovered system.

== FS layout
Relax-and-Recover tries to be as much LSB compliant as possible. Therefore ReaR will be
installed into the usual locations:

/etc/rear/::
    Configurations

/usr/sbin/rear::
    Main program

/usr/share/rear/::
    Internal scripts

/tmp/rear.$$/::
    Build area

=== Layout of /etc/rear
default.conf::
    Default configuration - will define EVERY variable with a sane default
    setting. Serves also as a reference for the available variables 'site.conf'
    site wide configuration (optional)

local.conf::
    local machine configuration (optional)

$(uname -s)-$(uname -i).conf::
    architecture specific configuration (optional)

$(uname -o).conf::
    OS system (e.g. GNU/Linux.conf) (optional)

$OS/$OS_VER.conf::
    OS and OS Version specific configuration (optional)

templates/::
    Directory to keep user-changeable templates for various files used
    or generated

templates/PXE_per_node_config::
    template for pxelinux.cfg per-node configurations

templates/CDROM_isolinux.cfg::
    isolinux.cfg template

templates/...::
    other templates as the need arises

recovery/...::
    Recovery information

=== Layout of /usr/share/rear
skel/default/::
    default rescue FS skeleton

skel/$(uname -i)/::
    arch specific rescue FS skeleton (optional)

skel/$OS_$OS_VER/::
    OS-specific rescue FS skeleton (optional)

skel/$BACKUP/::
    Backup-SW specific rescue FS skeleton (optional)

skel/$OUTPUT/::
    Output-Method specific rescue FS skeleton (optional)

lib/*.sh::
    function definitions, split into files by their topic

prep/default/*.sh::
prep/$(uname -i)/*.sh::
prep/$OS_$OS_VER/*.sh::
prep/$BACKUP/*.sh::
prep/$OUTPUT/*.sh::
    Prep scripts. The scripts get merged from the applicable directories
    and executed in their alphabetical order. Naming conventions are:
    +
    ##_name.sh
    +
    where 00 < ## < 99

layout/compare/default/::
layout/compare/$OS_$OS_VER/::
    Scripts to compare the saved layout (under /var/lib/rear/layout/) with the actual situation. This is used by workflow *rear checklayout* and may trigger a new run of *rear mkrescue* or *rear mkbackup*

layout/precompare/default/::
layout/precompare/$OS_$OS_VER/::

layout/prepare/default/::
layout/prepare/$OS_$OS_VER/::

layout/recreate/default/::
layout/recreate/$OS_$OS_VER/::

layout/save/default/::
layout/save/$OS_$OS_VER/::
    Scripts to capture the disk layout and write it into /var/lib/rear/layout/ directory

rescue/...::
    Analyse-Rescue scripts: ...

build/...::
    Build scripts: ...

pack/...::
    Pack scripts: ...

backup/$BACKUP/*.sh::
    Backup scripts: ...

output/$OUTPUT/*.sh::
    Output scripts: ...

verify/...::
    Verify the recovery data against the hardware found, whether we can
    successfully recover the system

recreate/...::
    Recreate file systems and their dependencies

restore/$BACKUP/...::
    Restore data from backup media

finalize/...::
    Finalization scripts

== Inter-module communication
The various stages and modules communicate via standardized environment variables:

|====
|NAME             |TYPE         |Descriptions                         |Example
|CONFIG_DIR       |STRING (RO)  |Configuration dir                    |'/etc/rear/'
|SHARE_DIR        |STRING (RO)  |Shared data dir                      |'/usr/share/rear/'
|BUILD_DIR        |STRING (RO)  |Build directory                      |'/tmp/rear.$$/'
|ROOTFS_DIR       |STRING (RO)  |Root FS directory for rescue system  |'/tmp/rear.$$/initrd/'
|TARGET_FS_ROOT   |STRING (RO)  |Directory for restore                |'/mnt/local'
|PROGS            |LIST         |Program files to copy                |+bash ip route grep ls+ ...
|MODULES          |LIST         |Modules to copy                      |+af_unix e1000 ide-cd+ ...
|COPY_AS_IS       |LIST         |Files (with path) to copy as-is      |'/etc/localtime' ...
|....
|====

RO means that the framework manages this variable and modules and methods shouldn't change it.

== Major changes compared with mkCDrec

  - No Makefiles
  - Major script called xxx that arranges all
  - Simplify the testing and configuration
  - Being less verbose
  - Better control over echo to screen, log file or debugging
  - Less color
  - Easier integration with third party software (GPL or commercial)
  - Modular and plug-ins should be easy for end-users
  - Better documentation for developers
  - Cut the overhead - less is better
  - Less choices (=> less errors)

  - **mkCDrec project is obsolete**

