Rdiff-image-boot

NAME

rdiff-image-boot - "boot" a backup created by the rdiff-image tools

SYNOPSIS

DESCRIPTION

rdiff-image-boot re-creates the restored VM environment using a chroot. This includes running the services normally started from /etc/init.d on the original VM and mounting any pseudo file systems required such as /proc. It can be put in /etc/init.d and run at boot up, or it can be run by hand to get a shell prompt in the chrooted environment.

It relies on the host machine running an operating system that is similar that used on the machine backed up. Here "similar" means a different version of the same operating system will normally work, but an entirely different operating system most definitely won't.

CHROOT CONTAINER CONTROL

Commands in this group control services running in the chroot. The resemble SysV commands, to the point that rdiff-image-boot can be used as an SysV init script.

Up to three positional arguments are read from the command line. This first argument determines what operation is performed. It is one of:

force-restart: Identical to restart.
mountsh: Spawn a root shell in within the chroot after mounting all pseudo file systems.
restart: Identical to doing a stop followed by a start.
sh: Spawn a root shell in within the chroot.
start: Start the VM environment running within the chroot. This entails mounting the pseudo file systems required by the chroot, then starting the VM's services within the chroot.
stop: Shut down the VM environment running within the chroot. This will kill all processes running in the chroot, first with SIGTERM and then with SIGKILL if they don't respond. All file systems are then unmounted.

config: This parameter determines how the configuration file is found. If not present /etc/default/rdiff-image is used to find the configuration file as described below. If this is "-" the name of the configuration file is derived from the location of this program, as described below. Otherwise this must be the path to the rdiff-image.conf(5) configuration file to use.
image-dir: If the config parameter is blank or "-" this parameter is ignored. Otherwise it is the path to the root of the VM image directory. If not present the path is derived from the supplied config path by looking in it for the strings /usr/ and /etc/ in that order, and stripping the shortest suffix starting with the first string found.

SERVICE CONTROL

Commands in this group control services running in the chroot.

start-service name...: Start a service within the chroot. This must be run within the chroot. It can start for both sysv init services (stored in /etc/init.d) and systemd services (generally found in /lib/systemd/system). If service-name starts with a / then it is assumed it is a program which is run in the background. For other services it emulates what sysv init or systemd would do, so it does not require them to be present or working. This emulation includes handling systemd instances, so for example postfix under systemd is usually started as postfix@-. It does not start related or dependent services, nor does it provide a way to stop a service once started.

CONFIGURATION USED

The location of the rdiff-image.conf(5) and the path to the directory that holds the VM directory is calculated from the config and image-dir arguments if present, as described above. Otherwise, the file /etc/default/rdiff-image is read. If it doesn't exist the name of the configuration file is derived from the location of this program, as described next.

/etc/default/rdiff-image is a shell script which can define two shell variables:

CONFIG: This shell variable is used instead of the config parameter and is handled identically.
IMAGE_DIR: This shell variable is used instead of the image-dir parameter and is handled identically. This includes ignoring it if CONFIG is blank or "-".

The final method of determining the configuration file to use and the location of the VM directory is to guess it from the location of this program. For this to work you must use a copy a this program that lies in the VM image. Symlinks are read in determining the location of the program so it can be invoked using a symlink outside of the VM image, but if so the symlink must ultimately point to inside of the VM image. These two steps are followed:

The VM root: The full path to this program is searched for the strings /usr/, /bin/ and /sbin/ in that order. Then the shortest suffix that starts with the first string found is stripped off to yield the root of the VM image directory.
The configuration file name: A search is done under the VM root for a file named rdiff-image.conf. These directories are searched in order, and first occurrence of rdiff-image.conf found is used: /etc/rdiff-image, /etc, /usr/local/etc/rdiff-image, /usr/local/etc.

CONFIGURATION FILE

The configuration file format is described in detail in rdiff-image.conf(5). In brief, the configuration options that effect the operation of this program are:

init.d: The VM services to be started and stopped by the start and stop operations.
mounts: The pseudo file systems to be mounted.

AUTHOR

Russell Stuart <russell-rdiffimage@stuart.id.au>