Read-me for Setting Up rbxi

Filename: rbxi-readme.htm
Version: 2.7.2

Introduction to rbxi

The rbxi script is designed to only require a single setup, one time. Any updates to the script should only be new features, which if your system is the way you want, you should not need. But feel free to check the script homepage now and then to see if a new feature might be implemented that would be useful to you.

Please do not change anything in the FUNCTIONS section unless you are reasonably comfortable with shell scripting. If you do change something and you break the script, I will not give any support to you, unless it's an interesting problem.

Required Programs to Run rbxi

The only currently required program, aside from rsync or rdiff-backup, you need for rbxi to run is: lsof

All other tools should be standard for bash.

To see if you have lsof, simply run this command: 

which lsof

If it show the path, you have it.

rbxi Script Setup

You must customize the USER VARIABLE section and the rbxi excludes to fit your system and requirements before running this script. For most users, that should be all that is required.

See the rbxi-values setup section and rbxi excludes on how to do that.

top

rbxi.tar.bz2 Package Contents

This bzipped package should contain the following files and directories: 

  1. rbxi

    This is the main program file. Make sure to use 

    chmod +x rbxi

    to make it executable, although it should already be executable. 

  2. rbxi-data/ # main rbxi data directory

  3. rbxi-data/excludes-root.txt (for rdiff-backup)
rbxi-data/excludes-root-rsync.txt (for rsync)

    These have the standard root excludes. Do not delete any of these except for: 

    /var/cache/apt/archives/*

    And only delete that if you want to backup your deb archives. 

  4. # for rdiff-backup
rbxi-data/excludes-home.txt
rbxi-data/excludes-data-<1-10>.txt
# and for rsync
rbxi-data/excludes-home-rsync.txt
rbxi-data/excludes-data-<1-10>-rsync.txt

    These are blank files. Use them to add more excludes if required to your backup. 

  5. rbxi-data/rbxi-values

    This file contains all your user variables, use this to create your values for your backup. This replaces the old 1.x method of having these values on the actual rbxi file, so you can now easily upgrade rbxi without having to update or change anything.

    Note: you can create any number of these rbxi-values files, and load alternate values files by using the -V option. See rbxi -h for details. File must be in rbxi-data, and the name must be rbxi-values-<anything> The value for -V must be <anything>, and the file will be tested for. 

  6. rbxi-data/readme-rbxi.htm

    This HTML read-me file should help you set up rbxi. Please make sure to read it before giving up on the setup, rbxi requires some end user learning to really work as expected.

top

Script Options and Parameters

The script can be started with a variety of different options, and the same options can be used to create backup Jobs (-J).

Add/Skip Override Components and -J (Job) Preset Values

-A Add backup component. Overrides user set B_SKIP_DATA.. (d|h|hr|1-10)
   d - add all DATA; h - add HOME; r - add ROOT; add DATA 1-10
   Normal use is with -J option set to override -S rbxi-values settings
   for SKIP variables.
-B Change default backup directory (1-10).
-C (rsync only) Clone root/home. Skips all data backups. Moves files
	directly to mounted location. Sets the main mount subdirectory too,
	then transfers files directly into that directory.
   Takes parameters: (h|r|1-10). Clone root, home, or a data direcory.
-D Change default backup sub directory (1-10)
-E [1-5]:[1-5]:[1-5] - note, you can skip any number, like: -E 2:: which will
   then only run start actions. Requires user set up of actions to run rbxi
   start, finish, and rbxi error. 
-M Use alternate mount/umount set (1-10) - these are set in rbxi-values.
   They can be null, so make sure you have the right number for your selection.
-o [rb|rs] Override default backup application: use rsync/rdiff-backu
-P [1-5]:[1-5]:[1-5] - note, you can skip any number, like: -P 2:: which will
   then only run pre mount tasks. Requires user set up of functions to run
   pre mount, post mount, and post umount. 
-S Skip backup component (d|h|hr|1-10)
   d - skip all DATA; h - skip HOME; r - skip ROOT; skip DATA 1-10

In general, avoid using A, D, M, S unless you are creating a backup job -J, or if you want temporarily skip (-S) or add (-A) a specific directory.

-S and -A can be used repeatedly, like so: -S 2 -S 5 -S 9

Remember, -A should only be used to override SKIP... that has been set in rbxi-values.

-C overrides -A which overrides -S. -C will only clone the specific directory you set, directly to the destination directory, and switches off all other backup directories.

-C overrides -D, or default backup subdirectory, and sets it to null.

-D overrides default main mount backup directory, and uses that for -M

Auto Run Options

-b Runs the backup without any interactive questions. Automatically, that is.
   -b will simply create a backup based on the current month, assign it to the
   correct primary backup directory, then execute the backup.
-c Automatic backup, clean older files, for non-interactive. Cleans and runs
   normal backup.
-d First deletes the old backups, then runs the backup non-interactively
   as with -b.
   Caution: all your previous backups from that backup directory will be
   eliminated if you use this. Permanently.

-b, -c, and -d are also well suited for running the backup with a cron job, automatically, that is.

Job Option

-J Start preset backup job (1-10)

Create preset jobs, 1-10, in rbxi-values, using script arguments. Use presets like -A, -B, -o, -D to create a custom job for future use.

Miscellaneous Options

-h The help menu, these options.

-L Create symbolic link in /usr/local/bin to rbxi. You must be root to use this.
   It will check for the link and create it if it's missing.

-r Runs --dry-run option, which emulates the backup job without actually running
   any of it, including the -d delete option.
   
-R Show script readme file. Requires one of the following console browsers: 
	links2 elinks w3m links lynx

-s Runs the backup using spinning wheel progress indicators.
   Warning: in order to do this, the script puts the actual backup jobs
   in the background, so you can't kill them the normal way, with ctrl+c
   if you want to stop the backup. Keep that in mind.

   -s is useful, besides being eye candy, for letting you know that the
   script is actually doing something while it sits there working on your
   deletions or backups.

-U Update script manually from svn server. It will update it to where-ever
   you have it installed.

-v Show script version and last used information. Also shows last time you
   did a backup and which backup directory was used. This should help people
   like me who can't remember.

-V Use alternate rbxi-values file. Syntax: rbxi-values-<whatever you want>
   File must be located in rbxi-data, and must have the syntax of:
   rbxi-values-<something>

Mount/Umount

If the device is automounted, the script will check to make sure it's path is present, and if the script uses mount/unmount option, that contains a test as well for failed mounts. 

   -m Skip the mounting option. If present, the script will not use your
   preset mount/umount values, and will not try to mount anything. Only use
   if you have a good reason to do so.

top

Backup Partition Formatting

USING FAT OR FAT32 FORMATTED DRIVES MAY DESTROY YOUR SYSTEMS INTEGRITY ON RESTORE OPERATIONS!

This is because fat file systems do not allow any advanced permissions, which all unix systems rely on to maintain security and user privileges. Also fat32 has a max file size of about 4 gigabytes.

In order to preserve your file ownership and permissions, you must backup to a reasonably robust file system. I recommend either ext2 or ext3 if it's an external drive, and whatever you like internally as long as it's not a FAT type system, which has no support for advanced file ownership or permissions.

Recent developments with reiserfs (like Hans Reiser's recent conviction for murder, as well as SUSE dropping all but maintenance support for Reiserfs) suggest that reiser file systems are not a good option for long term data storage, unfortunately.

top

Script Usage

Script must be run as root, the contents of rbxi.tar.bz2 should all have been unzipped into the same directory. It doesn't matter where you put those files though, as long as you keep them together.

Make sure to have your backup drive or partition mounted before you start script unless you are using the auto mount/unmount options in the script. If the drive or partition is not present, script exits with an error telling you this.

For normal useage, when you run the script, it will check root/backup partition, then ask you if you want to run the standard backup, which either creates a new, or adds to an existing, backup directory.

If you select the delete and backup option, the script will ask you if you are sure you want to do that.

Once you set the primary variable values as indicated below, you shouldn't need to change this script much, except mayby adding some exclude items to the exclude files, or possibly adding or removing a backup option.

Rdiff-backup and Rsync Man Files

SEE THE man FILES FOR MORE INFORMATION ON HOW TO USE rdiff-backup/rsync FEATURES: man rdiff-backup OR man rsync

Unlike most man files, the rdiff-backup and rysnc man files are filled with clear explanations and examples, and can show you how to do pretty much anything you can imagine.

Things to be Careful About When Running a Backup

Close anything that might change files while you backup, like your email program, irc chat, or anything else that might change while you are doing your backup.

Remember to add the path to the backup partition to the exclude lists if your backup drive or directory is mounted somewhere else than in /media.

You don't want to create backups of your backups after all!

top

Using rsync TO or FROM Remote Machines

Backing Up TO Remote Machines

For default job, simply set, if the remote machine is the backup destination, ie, you are backing up your local machine TO the remote machine: 

BACKUP_MOUNT_POINT_RS='username@remotemachine:/path/on/remote/machine/to/backup/directory'

NOTE: you do NOT need to use: 

BACKUP_MOUNT_POINT_DIRECTORY_RS= can be blank in this case, unless you want to have it point somewhere.

Then set the backup DIR name: 

DATA_1_DIR='machine-1'

And that's it.

Backing Up FROM Remote Machines

For backing up REMOTE directories TO your local machine, you do it the other way: 

DATA_1_PATH='user@remotemachine:/path/to/directory/TO-backup/'

Note that you must also set: 

DATA_1_DIR='backup-name'

unless you use the -C clone option, in that case: 

BACKUP_MOUNT_POINT_RS='/media/backup'
BACKUP_MOUNT_POINT_DIRECTORY_RS='/backup-rs' #if you needed a subdirectory

and then 

DATA_1_PATH='user@remotemachine:/path/to/directory/TO-backup/'
DATA_1_DIR=''

Then you'd set the other directories to NOT backup using either -S skip flags or hard coding it with SKIP flags in the values file. 

B_SKIP_DATA_X...

And that's it.

Learning the Ins and Outs of Remote Backup

This isn't super easy to understand, and it takes some trial and error to get it right.

Whatever you do, MAKE SURE TO USE THE --dry-run OPTION UNTIL YOU ARE SURE THE BACKUP IS WORKING AS EXPECTED, OTHERWISE THE RESULTS COULD BE DANGEROUS!

top

Exclude File Information

The idea of exclude files is very simple, but there are some things to watch out for.

Main Points on Using Excludes

The main syntax you need to understand for creating an exclude list is this:

  1. /some/directory - Excludes any file or directory called: directory in /some and also excludes any directory or file contained in that.
  2. /some/directory/* - Backs up the directory /some/directory, but not its contents.
  3. This sequence [ note the + with a space after it preceding /some/directory/main ]: 
    + /some/directory/main
/some/directory

will backup the directory /some/directory/main and its contents, but will not back up anything else in /some/directory.

It is important to understand that rdiff-backup/rsync first accepts the + items, which means include this in the backup, then after that you add the normal exclude case. The order is important, if you put the include case after, it won't get included, if it's before it will get included.

So when you have a list and you want to include one directory in a parent directory that is excluded, the include item, with + /some/path must come first.

For more information, read: man rdiff-backup or man rsync

Backup From Outside the Running Operating System

First, if you running the backup from outside the operating system that is being backed up, the exclude file paths must reflect that.

So you need to change for example a /sys/* in /dev/hda2 in roots-excludes.txt that is currently mounted in /media/hda2 to: /media/hda2/sys/*

However, this script is designed to allow smooth, complete backups from inside your operating system, so you should rarely need this change. It's much easier after all running the backup from in the OS than having to reboot into another one.

Exclude File Syntax

NOTE: for rsync, you need to use ** for recursive rules, not *. rdiff-backup is picky about this, rsync works as you'd expect: ** is anything including /, * is a directory/file.

rdiff-backup basically only supports this: 

**/usr/* will include/exclude all directories with /usr/ in their path, period
/usr/** will include/exclude everythiung in /usr
/usr/* will include/exclude files/directories one level below usr
/usr/ will include/exclude /usr if the directory has content, and not if it's empty
/usr will include/exclude /usr

Rsync Specific Exclude Path Information

For any non root backups, you need to understand that rsync starts the exclude/include path not absolutely, but relative to the path of the thing being backed up, so for example you would NOT use: 

/home/fred/.qt

to exclude fred/.qt in the /home backup, but would rather use: 

/fred/.qt

or better 

/*/.qt

which would exclude all users in /home

*/ only stays within the directory it's in, but ** includes / as a super wildcard, so, again, say, for /home: 

**/.qt

would exclude /home/fred/.qt AND /home/fred/blogs/.qt, but 

/*/.qt

would exclude only /home/usernames/.qt

Things to be Aware Of

All rules not starting with ** must start with /, otherwise you get an error.

Rules can contain either ** or *, but with ** especially, make sure to test it well before you stay with it.

I like to start excludes with: 

- /*/.qt

and include rules with 

+ /*/.qt

Just to make it clear, but in the excludes files, the - is optional.

When you use either - or +, they must be followed by a space then the rule.

Rdiff-backup Specific Exclude Path Information

Paths work as expected, for example 

- /home/username/.qt

will exclude that directory in /home

Everything else above applies however except for the path oddities.

top

How to Setup rbxi-values Variables and Data

You will need to set the paths in rbxi USER SPECIFIC VARIABLES section, using the file rbxi-data/rbxi-values. That overrides anything in the main script, and if you update rbxi, you will not need to change anything at all.

I will run down the variables one by one to explain how to set them correctly.

Path Variables in Main Script

Only set these in the main script if things will not work any other way.

You have to reset these every time the script updates. 

# set this as absolute path for cron jobs if you need to, you'll have to
# update this manually every time you update the script:
LSOF='lsof'

# http://forums.macosxhints.com/archive/index.php/t-73839.html
# note, no other method works reliably to get the true script path, not dirname $0.
if type $LSOF &>/dev/null;then
	SCRIPT_PATH=$( dirname $( $LSOF -p $$ | grep 'REG' | grep -oE "/.*$(basename $0)$" ) )
# checking if the dirname method works
elif [ -d $( dirname $0 )/rbxi-data ];then
	SCRIPT_PATH=$( dirname $0 )
fi

# in worst cases, you can manually set the script directory path here, uncomment
# and make the path explicit. Must not end with /, and must be the full path of
# the rbxi directory rbxi came with.
# You'll have to update this manually every time you update the script:
# example:  SCRIPT_PATH='/home/fred/scripts/rbxi'
# SCRIPT_PATH=''

top

User Specific Variables - Change as Required

These should be the only variables you need to change. I will go down the list and explain what each group is and how to change it for your system and needs.

Please note: some of these have default values already, make sure that the defaults match your backup needs if you leave them unchanged.

Application Paths and Data

########################################################################
#### RSYNC/RDIFF-BACKUP DATA, REQUIRED APPLICATION PATHS ###############
########################################################################

BACKUP_APP='rsync'

Set to either rdiff-backup or rsync. Can be overridden with r/R option. Default is rsync.

Change these to the true system paths if you are going to run this as a cron job like so: 

RDIFF_PATH='/usr/bin/rdiff-backup'

or this: 

RSYNC_PATH='/usr/bin/rsync'

Use'which rdiff-backup' OR 'which rsync' (no quotes) to find the true path. 

RDIFF_PATH='rdiff-backup'
RSYNC_PATH='rsync'

top

Rsync/Rdiff-backup Extra Arguments

# For remote, via ssh, include the ssh option
# ie: RSYNC_EXTRA_OPTIONS=' --rsh=ssh '

# ie: RDIFF_EXTRA_OPTIONS=' --terminal-verbosity 5 '
# Only set if you want custom options for either rdiff-backup or rsync,
# otherwise make null: RSYNC_EXTRA_OPTIONS=''
# Defaults are below, to let you see what's going on at least the first time.
# Once rsync works, remove the --dry-run and the backup will actually occur.
RSYNC_EXTRA_OPTIONS=' --dry-run -v '
RDIFF_EXTRA_OPTIONS=' --terminal-verbosity 5 '

# see man rdiff-backup for proper syntax for time. This is set to remove older
# than 60 days incremental backupsThe time  interval  is  an integer followed
# by the character s, m, h, D, W, M, or Y, indicating seconds, minutes,
# hours, days, weeks, months, or years respectively, or a number of these
# concatenated.
# For example, 32m  means  32  minutes, and  3W2D10h7s means
# 3 weeks, 2 days, 10 hours, and 7 seconds.
RDIFF_REMOVE_TIME='60D'

top

Primary Destination Directory for Backup

########################################################################
#### BACKUP (DESTINATION) DIRECTORY PATHS AND INFORMATION ##############
########################################################################

This is your backup mount location, the mount name that you have created for your backup drive or network mount.

Remote machines must be in this form: username@machine:/path/to/backup/destination 

BACKUP_MOUNT_POINT='/media/usbdisk'
BACKUP_MOUNT_POINT_1=''
BACKUP_MOUNT_POINT_2=''
BACKUP_MOUNT_POINT_3=''
BACKUP_MOUNT_POINT_4=''
BACKUP_MOUNT_POINT_5=''
BACKUP_MOUNT_POINT_6=''
BACKUP_MOUNT_POINT_7=''
BACKUP_MOUNT_POINT_8=''
BACKUP_MOUNT_POINT_9=''
BACKUP_MOUNT_POINT_10=''

If you are using rsync, and want a different backup directory, set this to different, otherwise make it the same as above. 

BACKUP_MOUNT_POINT_RS='/media/usbdisk'
BACKUP_MOUNT_POINT_1_RS=''
BACKUP_MOUNT_POINT_2_RS=''
BACKUP_MOUNT_POINT_3_RS=''
BACKUP_MOUNT_POINT_4_RS=''
BACKUP_MOUNT_POINT_5_RS=''
BACKUP_MOUNT_POINT_6_RS=''
BACKUP_MOUNT_POINT_7_RS=''
BACKUP_MOUNT_POINT_8_RS=''
BACKUP_MOUNT_POINT_9_RS=''
BACKUP_MOUNT_POINT_10_RS=''

This is the mounted location of your backup disk or partition. The default assumes that it is a external drive with the label of 'usbdisk'. Change to your requirements. Please make sure this does not end with a /, but just the actual partition mount directory name.

NOTE: it is extremely bad practice to backup to the same partition that is being backed up so if you want to do that don't look here for help or advice.

Do not use the /dev/sda1 type names, use the mounted name, like /media/sda1

top

Primary Backup Job Directories in Destination Directory

Primary backup job directories, these will be located inside of the BACKUP_MOUNT_POINT I strongly recommend you use these, because that can help avoid accidently writing the backup to a directory that did not get mounted, for example: /media/backup prior to mounting the actual drive to /media/backup. This is an easy mistake to make.

These directories will be found INSIDE your primary mount directory, in the Network or Local drive mount directory, that is. In other words, these directories will be in the mounted backup partition or network drive.

DO NOT END the destination directory names below with a '/' START them with a / 

BACKUP_MOUNT_POINT_DIRECTORY='/backup'
BACKUP_MOUNT_POINT_DIRECTORY_1=''
BACKUP_MOUNT_POINT_DIRECTORY_2=''
BACKUP_MOUNT_POINT_DIRECTORY_3=''
BACKUP_MOUNT_POINT_DIRECTORY_4=''
BACKUP_MOUNT_POINT_DIRECTORY_5=''
BACKUP_MOUNT_POINT_DIRECTORY_6=''
BACKUP_MOUNT_POINT_DIRECTORY_7=''
BACKUP_MOUNT_POINT_DIRECTORY_8=''
BACKUP_MOUNT_POINT_DIRECTORY_9=''
BACKUP_MOUNT_POINT_DIRECTORY_10=''

If you are using rsync, set this path to the actual sub directory used in the main backup directory. 

BACKUP_MOUNT_POINT_DIRECTORY_RS='/backup-rs'
BACKUP_MOUNT_POINT_DIRECTORY_1_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_2_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_3_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_4_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_5_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_6_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_7_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_8_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_9_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_10_RS=''

This is the actual directory name of where the backup will go, inside the primary, generally mounted, or remote ssh/rsh drive.

rbxi will test all local directories to see if they exist, and if they don't, will exit with errors.

top

Backup Destination Sub Directories

####--------------------------------------------------------------------
#### BACKUP JOB DESTINATION SUB DIRECTORIES ----------------------------
####--------------------------------------------------------------------

These directory names are the names your backup job will create for each part you want to run, like home, root, data directories. rsync/rdiff-backup will create these as needed.

Do not begin any of the following 4 directory names with a /, just put the name itself you want rdiff-backup/rsync to create for that particular backup. You do not need to manually create these sub-directories, rsync or rdiff-backup do it automatically.

Important: if any one of these is left blank, no backup of that component will be created. 

HOME_DIR='home'

This is the name of the directory that your /home partition will get backed up to inside of the above primary backup directories. 

ROOT_DIR='root-hda1'

This is the name of the directory that your / [root] partition will get backed up to inside of the above primary backup directories.

These are optional backup subdirectories, if these are used the script will backup these as well as / and /home autumatically.

Blank '' means the script does not try to back that item up. This is the backup sub directory name, not the actual data file path

Remote machines must be in this form: username@machine:/path/to/backup/source 

DATA_1_DIR=''
DATA_2_DIR=''
DATA_3_DIR=''
DATA_4_DIR=''
DATA_5_DIR=''
DATA_6_DIR=''
DATA_7_DIR=''
DATA_8_DIR=''
DATA_9_DIR=''
DATA_10_DIR=''

If used, these are data directory names. Default is blank.

top

Script Backup Directory Output Descriptions

########################################################################
#### SCRIPT BACKUP OUTPUT DESCRIPTIONS #################################
########################################################################

These variables are simply what the script will print out to you when it runs. They do not affect what actually is backed up. 

DATA_1_DESC='' # for example: DATA_1_DESC='web'
DATA_2_DESC='' # for example: DATA_2_DESC='email'
DATA_3_DESC=''
DATA_4_DESC=''
DATA_5_DESC=''
DATA_6_DESC=''
DATA_7_DESC=''
DATA_8_DESC=''
DATA_9_DESC=''
DATA_10_DESC=''

This is a one or more word description of what is being backed up. Like this: DATA_1_DESC='my emails'. This is what rbxi will print out to you as it backs up that directory.

This is for DATA_x_DIR and DATA_x_PATH 

ROOT_DESC='/dev/hda1'

This just tells you which actual physical partition root is. Change to your own setup. This is not a path, it's just information for you.

top

Backup Source Paths

########################################################################
#### SYSTEM BACKUP SOURCE PATH INFORMATION #############################
########################################################################

These are the actual paths to be used for the backups. Whatever path you enter here is what will get backed up.

Note: if you leave off the ending /, rsync will create a directory of the last name in the path, which you probably don't want, so make sure to end these paths with /.

All xx_PATH directories are the SOURCE directory, not not the destination. 

HOME_PATH='/home/'

Only change this if you are running the backup from outside of the Operating system that is being backed up. For example, if /home is on /dev/sda3, then you'd change this to /media/sda3 if you were backing up from example a live cd.

SPECIAL NOTE: If you are using any /home excludes, and if you are running the backup from outside of the operating system/ home partition you are backing up, you must change the paths in home-excludes.txt to reflect this actual path, for example: 

/home/username/somedata/*

would become 

/media/hda3/username/somedata/*

[assuming that your home directory is mounted in a separate partition that is. This path must be the unmounted true path to the /home you are backing up when it's run from outside the OS.

Normal useage: do not change

Root Path
ROOT_PATH='/'

If backing up from within OS, do not change. If from outside, same as above.

SPECIAL NOTE: If you run the script from outside the operating system to be backed up, you will need to change the root-excludes.txt paths to reflect that. for exampple, say / in this case is on /dev/hda2, and the partition is mounted in /media/hda2: 

/sys/*

would be 

/media/hda2/sys/*

and so on

Data Paths
DATA_1_PATH=''
DATA_2_PATH=''
DATA_3_PATH=''
DATA_4_PATH=''
DATA_5_PATH=''
DATA_6_PATH=''
DATA_7_PATH=''
DATA_8_PATH=''
DATA_9_PATH=''
DATA_10_PATH=''

If you are creating more than the default / and /home backups, use this. This must correspond to the DATA_XX_DIR item above. Set to path of item you want backed up separately.

Note: normally, you will exclude this in either /home or / depending on where the data is mounted. Just add this path to the relevant home-excludes.txt or root-excludes.txt To backup the directory name but not it's contents, do this: 

/data/*

in the exclude file.

If DATA_XX_DIR is blank, this will not get backed up unless you are using the -C, Clone, option. In all cases however, if you want the backup to occur, the PATHs here must be real and exist on your system if it is a local path.

top

Mount / Umount Data

########################################################################
#### PARTITION MOUNT/UMOUNT ############################################
########################################################################

Note that MOUNT/UNMOUNT 1-10 are triggered by the -M option, and that $BACKUP_MOUNT_POINT will be set dynamically from rdiff/rsync BACKUP_MOUNT_POINT set in rbxi based on the values you used in the config file.

If you want the script to automatically mount/umount your backup drive / partition, use this. If you don't want this, just leave the variables with a blank value.

For cron jobs, put the full system path to mount/umount in the command. 

MOUNT_BU_DISK='/usr/bin/mount -L backup-disk-1 $BACKUP_MOUNT_POINT'
UNMOUNT_BU_DISK='/usr/bin/umount $BACKUP_MOUNT_POINT'

Use'which mount' OR 'which umount' (no quotes) to find the true path.

EXCEPTION: if you want to use a custom DIRECTORY from above, do it like this: 

MOUNT_BU_DISK="mount -L backup-disk-1 $BACKUP_MOUNT_POINT_3"
UNMOUNT_BU_DISK="umount $BACKUP_MOUNT_POINT_3"

This will then use the directory you list. This requires double quotes, "", not single, ''. Of course you can also just hard code in the entire thing if you want, but it's easier to avoid errors if you just type it in time I find.

If you are just needing to change the BACKUP_MOUNT_POINT, just use -B <bu directory number> instead and rbxi will change that automatically for you, but if you need to put actually different mount/umount information, then use an alternate MOUNT/UNMOUNT number 

MOUNT_BU_DISK='mount -L backup-disk-1 $BACKUP_MOUNT_POINT'
UNMOUNT_BU_DISK='umount $BACKUP_MOUNT_POINT'
MOUNT_BU_DISK_1=''
UNMOUNT_BU_DISK_1=''
MOUNT_BU_DISK_2=''
UNMOUNT_BU_DISK_2=''
MOUNT_BU_DISK_3=''
UNMOUNT_BU_DISK_3=''
MOUNT_BU_DISK_4=''
UNMOUNT_BU_DISK_4=''
MOUNT_BU_DISK_5=''
UNMOUNT_BU_DISK_5=''
MOUNT_BU_DISK_6=''
UNMOUNT_BU_DISK_6=''
MOUNT_BU_DISK_7=''
UNMOUNT_BU_DISK_7=''
MOUNT_BU_DISK_8=''
UNMOUNT_BU_DISK_8=''
MOUNT_BU_DISK_9=''
UNMOUNT_BU_DISK_9=''
MOUNT_BU_DISK_10=''
UNMOUNT_BU_DISK_10=''

Otherwise, set the full command for mount/umount like these samples. I recommend using either UUID or LABEL mounting to make sure the disk is correctly mounted, since /dev/sdd can change depending on what you have plugged into your system at that moment.

Mount Command Examples

For these examples, the disk has the following: 

label:		backup-disk-1
uuid:			b833d2c1-b824-4d93-a8c9-74e84226rc9c
standard:	/dev/sdc1

For LABEL mounting: 

MOUNT_BU_DISK="mount -L backup-disk-1 $BACKUP_MOUNT_POINT"

For UUID mounting 

MOUNT_BU_DISK="mount -U b833d2c1-b824-4d93-a8c9-74e84226rc9c $BACKUP_MOUNT_POINT"

For standard mounting: 

MOUNT_BU_DISK="mount /dev/sdc1 $BACKUP_MOUNT_POINT"

For network disk mounting 

MOUNT_BU_DISK="mount backupmachine:/dev/sdc1 $BACKUP_MOUNT_POINT"

Unmounting command, should not need to be changed:

UNMOUNT_BU_DISK="umount $BACKUP_MOUNT_POINT"

Complex Example

This will mount/umount 2 drives, source and destination, and echoes success messages after each operation. 

MOUNT_BU_DISK_10='mount -L audio-bu-1 $BACKUP_MOUNT_POINT && \
echo "Mounted backup directory $BACKUP_MOUNT_POINT..." && \
mount musicbox:/home/username/mm $DATA_10_PATH && \
echo "mounted source directory $DATA_10_PATH..."'
UNMOUNT_BU_DISK_10='umount $BACKUP_MOUNT_POINT && \
echo "Unmounted $BACKUP_MOUNT_POINT..." && \
umount $DATA_10_PATH && \
echo "Unmounted $DATA_10_PATH"'

top

Backup Job Preset Section

########################################################################
#### JOB PRESETS #######################################################
########################################################################

Set with whatever arguments you want to start script with, script will restart with those options automatically, then run whatever job you set.

Jobs consist of <job name> plus ':' plus <sets of rbxi options>

This would use mount/umount 3, and skip home/root backup: 

BACKUP_JOB_1='system-b-bu: -M 3 -S rh '

This would use mount/umount 2, skip home/root backup and Add the normally turned off DATA_8: 

BACKUP_JOB_2='system-c-bu: -M 2 -S rh -A 8'

This is triggered by the -J <1-10> option. 

syntax: BACKUP_JOB_2='job-display-name: <job options>'

BACKUP_JOB_1=':'
BACKUP_JOB_2=':'
BACKUP_JOB_3=':'
BACKUP_JOB_4=':'
BACKUP_JOB_5=':'
BACKUP_JOB_6=':'
BACKUP_JOB_7=':'
BACKUP_JOB_8=':'
BACKUP_JOB_9=':'
BACKUP_JOB_10=':'
Backup Job Examples
BACKUP_JOB_9=' -C 9 -B 10 -M 9 '

This sets Clone job 9, using main backup destination directory 10, using Mount / Umount set 9 

BACKUP_JOB_10=' -c -B 2 -D 2 -M 2 '

This sets standard delete obsolete, autorun backup, using main backup destination directory 2, with backup destination sub directory 2, using Mount / Umount set 2.

top

rbxi-values-user-actions

User Defined Pre/Post Mount/Umount Functions Section

########################################################################
#### ADVANCED USER SET FUNCTIONS/ACTIONS ###############################
########################################################################

# The following allow for user customization of rbxi actions using a simple
# api that will run either pre-defined functions or actions when desired.

####--------------------------------------------------------------------
#### PRE/POST MOUNT/UMOUNT FUNCTIONS -----------------------------------
####--------------------------------------------------------------------

Since nobody can anticipate everything you might need to get done, rbxi also includes the option to set and run functions you create and define in this section, and triggered by the -P option unless you set these here in the default variables, PRE_MOUNT_FUNCTION, POST_MOUNT_FUNCTION, POST_UMOUNT_FUNCTION, which will make them run always unless overridden by a specific -P value. 

# launches function: pre_mount_tasks()
PRE_MOUNT_FUNCTION=''
PRE_MOUNT_FUNCTION_1=''
PRE_MOUNT_FUNCTION_2=''
PRE_MOUNT_FUNCTION_3=''
PRE_MOUNT_FUNCTION_4=''
PRE_MOUNT_FUNCTION_5=''
PRE_MOUNT_FUNCTION_6=''
PRE_MOUNT_FUNCTION_7=''
PRE_MOUNT_FUNCTION_8=''
PRE_MOUNT_FUNCTION_9=''
PRE_MOUNT_FUNCTION_10=''

# launches function post_mount_tasks()
POST_MOUNT_FUNCTION=''
POST_MOUNT_FUNCTION_1=''
POST_MOUNT_FUNCTION_2=''
POST_MOUNT_FUNCTION_3=''
POST_MOUNT_FUNCTION_4=''
POST_MOUNT_FUNCTION_5=''
POST_MOUNT_FUNCTION_6=''
POST_MOUNT_FUNCTION_7=''
POST_MOUNT_FUNCTION_8=''
POST_MOUNT_FUNCTION_9=''
POST_MOUNT_FUNCTION_10=''

# launches function post_umount_tasks()
POST_UMOUNT_FUNCTION=''
POST_UMOUNT_FUNCTION_1=''
POST_UMOUNT_FUNCTION_2=''
POST_UMOUNT_FUNCTION_3=''
POST_UMOUNT_FUNCTION_4=''
POST_UMOUNT_FUNCTION_5=''
POST_UMOUNT_FUNCTION_6=''
POST_UMOUNT_FUNCTION_7=''
POST_UMOUNT_FUNCTION_8=''
POST_UMOUNT_FUNCTION_9=''
POST_UMOUNT_FUNCTION_10=''

Note a few things: If the first, non numbered variable contains the function, rbxi will always execute that every time it runs, unless overridden by -P 3::2 for example would override or run PRE_MOUNT_FUNCTION_3 and POST_UMOUNT_FUNCTION_2.

The argument for -P is constructed like this: [1-10]:[1-10]:[1-10] where 1-10 is optional, ie, you can skip any or all, or run them all, like for example: -P 2:: or -P 2:2:2

Note that each function must return 0 for success, and > 0 for failure. rbxi error handling requires this to properly exit and halt on failure. If no error handling is required, then simply return 0 at the end of the function. Functions must be written in Bash. The functions must be named as follows:

Sample: 

PRE_MOUNT_FUNCTION_1='pre_mount_tasks(){
	mount -L some-external-drive /data/drive/mount/point || return 1
	return 0
}'

Note two things here: first, the main feature has a return value of > 0 on failure, and if nothing fails, the function returns 0, success. If you want rbxi to do error handling on your functions, they must return > 0 error codes to rbxi, but less than 255 (that's a bash limitation), which will then report the error number using the rbxi error handler. You can have as many tests and error returns as you want in this function, this is just a very simple sample case, for instance, this would be with echoes so you know it's running (highly recommended), you can even use rbxi colors if you want, but I'll leave that up to you to figure out: 

PRE_MOUNT_FUNCTION_1='pre_mount_tasks(){
	echo "Mounting some-drive now..."
	mount -L some-drive /data/drive/mount/point || return 1
	echo "Testing test-file exists in mount point: /data/drive/mount/point/..."
	[ -f /data/drive/mount/point/test-file ] || return 2
	echo "Mounting another-drive now..."
	mount -L another-drive /data/drive/mount/point2 || return 3
	echo "Testing test-file exists in mount point: /data/drive/mount/point2/..."
	[ -f /data/drive/mount/point2/test-file ] || return 4
	return 0
}'

Note that the interior echoes use "" whereas the main variable function declaration is used single quotes. Make sure to do that too if you need to use quotes inside the function, or escape any single quote like this: echo "it\'s going to work!"

And here you'd just run this command: rbxi -P 1::
in order to trigger this extra function before the first mount runs.

Things to remember: these pre/post mount and post umount functions do not depend on anything being mounted, that's just where they will be run physically in the script, ie, before the main mount backup drive function, after the mount main backup drive function, and after the umount backup drive function. If you are skipping mounting the backup drive, with -m, then they will still run.

Important! If you use variables in your functions, make sure to either make them local, like: local variablename='', or by starting the variables with a prefix: like: ppmm_ that is unique. Otherwise you might accidently overwrite a script variable.

top

User Defined Start/Finish/Error Actions (emails)

####--------------------------------------------------------------------
#### EMAILER ACTIONS ---------------------------------------------------
####--------------------------------------------------------------------

These work much the same as above, only they do NOT use a function, just a scripted action, which will for most people be emailing the sys admin, but you can put any actions you want in here as well that you want done that rbxi doesn't do already. Errors from the action cannot be handled unless you make your action scripting itself process it.

You can get rbxi error handling by using the following in your action code, triggered by whatever error condition you want. Error 31 is a generic User Action error code for this feature. Sample: 

some email sending procedure || error_handler 31 "your error data"

Note that you need to use quotes for your actual error message "your error data", for example: 

error_handler 31 "Script Emailer (method 2) Error on step: finish"

Actions must be written in Bash, or any other language you can call directly on the system that is running the backup.

These actions will be triggered in a function that will have access to the following data, called with "$data" (" quotes are NOT optional). $data is time stamped always for start/finish/error.

Actions can be any Bash command your system supports, of any complexity, including but not limited to sending emails using system emailers like exim4 or mail or whatever you want. The Action will execute when the script starts, when it finishes, and if error occurs, if you select these options, depending on how you use these options. 

# Alerts to start of backup operation
EMAIL_START_ACTION=''
EMAIL_START_ACTION_1=''
EMAIL_START_ACTION_2=''
EMAIL_START_ACTION_3=''
EMAIL_START_ACTION_4=''
EMAIL_START_ACTION_5=''
EMAIL_START_ACTION_6=''
EMAIL_START_ACTION_7=''
EMAIL_START_ACTION_8=''
EMAIL_START_ACTION_9=''
EMAIL_START_ACTION_10=''

# Alerts to finish of backup operation
EMAIL_FINISH_ACTION=''
EMAIL_FINISH_ACTION_1=''
EMAIL_FINISH_ACTION_2=''
EMAIL_FINISH_ACTION_3=''
EMAIL_FINISH_ACTION_4=''
EMAIL_FINISH_ACTION_5=''
EMAIL_FINISH_ACTION_6=''
EMAIL_FINISH_ACTION_7=''
EMAIL_FINISH_ACTION_8=''
EMAIL_FINISH_ACTION_9=''
EMAIL_FINISH_ACTION_10=''

# Alerts to backup error, should include error data.
EMAIL_ERROR_ACTION=''
EMAIL_ERROR_ACTION_1=''
EMAIL_ERROR_ACTION_2=''
EMAIL_ERROR_ACTION_3=''
EMAIL_ERROR_ACTION_4=''
EMAIL_ERROR_ACTION_5=''
EMAIL_ERROR_ACTION_6=''
EMAIL_ERROR_ACTION_7=''
EMAIL_ERROR_ACTION_8=''
EMAIL_ERROR_ACTION_9=''
EMAIL_ERROR_ACTION_10=''

Note a few things: If the first, non numbered variable contains the action, rbxi will always execute that every time it runs, unless overridden by -E 3::2 for example would override or run EMAIL_START_ACTION_3 and EMAIL_FINISH_ACTION_2.

The argument for -E is constructed like this: [1-10]:[1-10]:[1-10] where 1-10 is optional, ie, you can skip any or all, or run them all, like for example: -P 2:: or -P 2:2:2

Rbxi does not do error handling on your commands, so make sure to debug them completely before you rely on this for production use.

Sample (I'm not sure you can use <<< "$data" with nail, this is just a sample, always test your code before putting it live): 

EMAIL_ERROR_ACTION_1='nail -r "myaddress@something.com" -s "Backup Error on Raven" -S smtp=some.smtp.server info@company.com <<< "$data"'

If you prefer, you can also just write a separate function, then include it, say you create a file: rbxi-extra-functions
put it in rbxi-data, which let's say is in /usr/local/bin, then, above: # Alerts to start of backup operation
you would add this line: source /usr/local/bin/rbxi-data/rbxi-extra-functions
then you could simply call your function like so (let's say your function is called: email_processing. Remember that the $data variable must always be in double quotes: "$data". 

EMAIL_ERROR_ACTION_1='email_processing startup "$data"'

top

Clean Delete Backup Skip Section

########################################################################
#### CLEAN / DELETE / BACKUP / SKIP ####################################
########################################################################

These are for options, used in case of cron or option run backups/deletes if you want to hard set any option just set the variable to true. trigger rdiff/rsync cleeanup, either older than x, or remove deleted files 

B_CLEAN_OLDER='false' # -c :clean old backup files, then do backup
B_DELETE_BACKUP='false' # -d :delete old backup, then do backup
B_DO_BACKUP='false' # -b :automatic backup

Skip home/root/data can be overridden by -A <r|h|number> when you are creating a separate job (-J <number>). 

B_SKIP_DATA_FULL='false' # -C [..] or -S d - skips all data partition backups
B_SKIP_DATA_1='false' # -S 1
B_SKIP_DATA_2='false' # -S 2
B_SKIP_DATA_3='false' # -S 3
B_SKIP_DATA_4='false' # -S 4
B_SKIP_DATA_5='false' # -S 5
B_SKIP_DATA_6='false' # -S 6
B_SKIP_DATA_7='false' # -S 7
B_SKIP_DATA_8='false' # -S 8
B_SKIP_DATA_9='false' # -S 9
B_SKIP_DATA_10='false' # -S 10
B_SKIP_HOME='false' # -S h
B_SKIP_ROOT='false' # -S r

top

Miscellaneous Script Options Section

########################################################################
#### MISCELLANEOUS SCRIPT OPTIONS ######################################
########################################################################
Miscellaneous Script Booleans (true/false)

B_SKIP_MOUNT='false' # -m :do not mount backup drive, or umount it
B_SPINNING_WHEEL='false' # -s :use spinning wheel option
B_TESTING_1='false' # -! 1 :testing flag 1
B_TESTING_2='false' # -! 2 :testing flag 2

If you want rbxi to notify you of newer versions when it runs, set to true. Default is false, no checking for latest versions. 

B_UPDATE_NOTIFIER='false'
Script Color Schemes
0 - no colors
1 - default, for dark on light or light on dark, red warning/error, simple highlights
2 - fancy dark on light, red warning/error, more colors for questions, highlights
3 - basic light on dark, red warning, yellow error, simple colored highlights
4 - fancy light on dark, red warning, yellow error, fancy colored highlights
5 - smxi style, for light on dark, green text, otherwise same as 3
Try each one and see which works best for your terminal colors using -j <0-5>, then set it here.
COLOR_SCHEME='1' # -j [0-5]
Set console browser

Uncomment then set only if you want to override the default console browser rbxi selects to show readme-rbxi.htm with -R option. 

# CONSOLE_BROWSER=''
Logging options

Default is logging on. To turn off, change to 'false'. If you want to override a false, use -l option when starting rbxi and it will use logging for just that session. 

B_LOGGING='true'

You can manually override the default logfile directory location here if you want (must end with /). Uncomment if you want to change rbxi default location to somewhere else in your system. 

# LOGFILE_DIR='/var/log/'

Log file max size, in kB. Must be an integer, for example: LOGFILE_SIZE=500
Overrides script default size of 100kB. Uncomment to use override. Rbxi will automatically rotate the file one time, to rbxi.1.log in the logfile directory once it hits the size in kB given. 

# LOGFILE_SIZE=100
Sleep Times

These sleep times are all in seconds. 

SLEEP_TIME_SPINNER='0.5'

If you started the script with the -s option, a small spinning wheel will run as each part of the operation is carried out. This lets you know that something is happening, that is.

I found that setting this to a lower number tended to boost the cpu useage, but you can play with it to see for yourself. Anything less then 0.1 would be pointless. I find that 0.5 is fine, and doesn't consume much cpu. The lower the number, the faster the wheel spins. 

SLEEP_TIME_BACKUP='3'

Time between backup operations, make integer, number of seconds 

SLEEP_TIME_UMOUNT='5'

Time forced exit allows for disk write syncs before umount occurs. If umount fails with busy error on forced or premature exit, set this integer to be higher.

top

Final Configuration Step

########################################################################
#### FINAL STEP - DO NOT SKIP! #########################################
########################################################################

And last but not least, set this to 'true' once you are done updating all the variables here. Failure to do this will make rbxi exit without running, since you can't run it without having completed the user variables in the file: rbxi-data/rbxi-values 

B_VARIABLES_SET='false'

top

Static Variables :: Should Not Require Changes

These variables should not be changed unless you have some particularly good reason to do that, such as needing to reset the script or lsof path.

Do not change any of these, these are simply initializing variables. 

#### INITIALIZE VARIABLES TO BE SET ELSEWHERE
B_CLONE_HOME='false'
B_CLONE_ROOT='false'
B_CLONE_DATA_1='false'
B_CLONE_DATA_2='false'
B_CLONE_DATA_3='false'
B_CLONE_DATA_4='false'
B_CLONE_DATA_5='false'
B_CLONE_DATA_6='false'
B_CLONE_DATA_7='false'
B_CLONE_DATA_8='false'
B_CLONE_DATA_9='false'
B_CLONE_DATA_10='false'
B_DELETE_STATUS='false'
B_IS_CLONE='false'
HOME_BACKUP=''
ROOT_BACKUP=''
DATA_1_BACKUP=''
DATA_2_BACKUP=''
DATA_3_BACKUP=''
DATA_4_BACKUP=''
DATA_5_BACKUP=''
DATA_6_BACKUP=''
DATA_7_BACKUP=''
DATA_8_BACKUP=''
DATA_9_BACKUP=''
DATA_10_BACKUP=''
HOME_BU_COMMAND=''
ROOT_BU_COMMAND=''
DATA_1_BU_COMMAND=''
DATA_2_BU_COMMAND=''
DATA_3_BU_COMMAND=''
DATA_4_BU_COMMAND=''
DATA_5_BU_COMMAND=''
DATA_6_BU_COMMAND=''
DATA_7_BU_COMMAND=''
DATA_8_BU_COMMAND=''
DATA_9_BU_COMMAND=''
DATA_10_BU_COMMAND=''
ENDING_1='...'
ENDING_2='...'
START_TIME=$( date +%s )
BACKUP_CLEAR=''
BACKUP_DURATION=''
BACKUP_JOB_NU='none'
DELETION_TEXT=''
GET_PID=''
RSYNC_DELETE=''

top

Rbxi Functions

PLEASE ONLY CHANGE IF YOU CAN DO SOME BASH SCRIPTING

top

OK, THAT'S IT, HAVE FUN!