= Configuration examples
:data-uri:
:doctype: article
:icons:
:iconsdir: /usr/share/asciidoc/images/icons
:lang: en
:quirks:

This document explains the various use-cases and how to configure them in
Rear. The configuration is performed by changing _/etc/rear/local.conf_ or
_/etc/rear/site.conf_.

There are two important variables that influence Rear and the Rear rescue
image. Set +OUTPUT+ to your preferred boot method and define +BACKUP+ for your
favorite +BACKUP+ strategy.

In most cases only these two settings are required.


== Rescue media (OUTPUT)
The +OUTPUT+ variable defines where the rescue image should be send to.
Possible +OUTPUT+ setting are:

OUTPUT=ISO::
Create a bootable ISO9660 image on disk as _rear-$(hostname).iso_

OUTPUT=PXE::
Create on a remote PXE/NFS server the required files (such as configuration
file, kernel and initrd image

OUTPUT=OBDR::
Create a bootable OBDR tape including the backup archive. Specify the OBDR
tape device by using +TAPE_DEVICE+.

OUTPUT=USB::
Create a bootable USB disk (using extlinux). Specify the USB storage device by
using +USB_DEVICE+.

=== Using ISO as output method
When using +OUTPUT=ISO+ you should provide the backup target location through
the +OUTPUT_URL+ variable. Possible +OUTPUT_URL+ settings are:

OUTPUT_URL=file://::
Write the ISO image to disk. The default is in _/tmp_.

OUTPUT_URL=fish//::
Write the ISO image using +lftp+ and the FISH protocol.

OUTPUT_URL=ftp://::
Write the ISO image using +lftp+ and the FTP protocol.

OUTPUT_URL=ftps://::
Write the ISO image using +lftp+ and the FTPS protocol.

OUTPUT_URL=hftp://::
Write the ISO image using +lftp+ and the HFTP protocol.

OUTPUT_URL=http://::
Write the ISO image using +lftp+ and the HTTP (PUT) procotol.

OUTPUT_URL=https://::
Write the ISO image using +lftp+ and the HTTPS (PUT) protocol.

OUTPUT_URL=sftp://::
Write the ISO image using +lftp+ and the secure FTP (SFTP) protocol.

OUTPUT_URL=rsync://::
Write the ISO image using +rsync+ and the RSYNC protocol.


== Backup/Restore strategy (BACKUP)
The +BACKUP+ setting defines our backup/restore strategy.
Possible +BACKUP+ settings are:

BACKUP=TSM::
Use IBM Tivoli Storage Manager programs

BACKUP=DP::
Use HP DataProtector programs

BACKUP=NBU::
Use Symantec NetBackup programs

BACKUP=BACULA::
Use Bacula programs

BACKUP=GALAXY::
Use CommVault Galaxy (5, probably 6)

BACKUP=GALAXY7::
Use CommVault Galaxy (7 and probably newer)

BACKUP=NETFS::
Use Rear internal backup with tar or rsync (or similar)

BACKUP=REQUESTRESTORE::
No backup, just ask user to somehow restore the filesystems

BACKUP=EXTERNAL::
Use a custom strategy by providing backup and restore commands

=== Using NETFS as backup strategy
When using +BACKUP=NETFS+ you should provide the backup target location through
the +BACKUP_URL+ variable. Possible +BACKUP_URL+ settings are:

BACKUP_URL=file://::
To backup to local disk, use +BACKUP_URL=file:///directory/path/+

BACKUP_URL=nfs://::
To backup to NFS disk, use +BACKUP_URL=nfs://nfs-server-name/share/path+

BACKUP_URL=tape://::
To backup to tape device, use +BACKUP_URL=tape:///dev/nst0+ or alternatively,
simply define +TAPE_DEVICE=/dev/nst0+

BACKUP_URL=cifs://::
To backup to a Samba share (CIFS), use
+BACKUP_URL=cifs://cifs-server-name/share/path+. To provide credentials for
CIFS mounting use a _/etc/rear/.cifs_ credentials file and define
+BACKUP_OPTIONS="cred=/etc/rear/.cifs"+ and pass along:
+
----
username=_username_
password=_secret password_
domain=_domain_
----

BACKUP_URL=usb://::
To backup to USB storage device, use +NETFS=usb:///dev/disk/by-path/REAR-000+
or use a real device node or a specific filesystem label. Alternatively, you
can specify the device using +USB_DEVICE=/dev/disk/by-path/REAR-000+.
+
If you combine this with +OUTPUT=USB+ you will end up with a bootable USB device.

Optional settings:

BACKUP_PROG=rsync::
if you want to use rsync instead of tar

NETFS_KEEP_OLD_BACKUP_COPY=y::
if you want to keep the previous backup archive

NOTE: With +USB+ we refer to all kinds of external storage devices, like USB
keys, USB disks, eSATA disks, ZIP drives, etc...


== Example: Bootable ISO
If you simply want a bootable ISO on a central server, you would do:

----
OUTPUT=ISO
OUTPUT_URL=http://server/path-to-push/
----


== Example: Bootable USB device with backup to USB
If you want a bootable USB device with a (tar) backup to USB as well, you
would use:

----
BACKUP=NETFS
OUTPUT=USB
USB_DEVICE=/dev/disk/by-label/REAR-000
----


== Example: Bootable tape drive (OBDR) with backup to tape
If you want an OBDR image and backup on tape, and use GNU tar for
backup/restore, you would use:

----
BACKUP=NETFS
OUTPUT=OBDR
TAPE_DEVICE=/dev/nst0
----


== Example: Bootable tape drive (OBDR) and Bacula restore
If you want an OBDR image on tape, and the Bacula tools to recover your
backup, use:

----
BACKUP=BACULA
OUTPUT=OBDR
TAPE_DEVICE=/dev/nst0
----
