Local backup and restore iocages and jails on FreeBSD, FreeNAS, and TrueNAS systems
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
![Product Name Screen Shot][product-screenshot]
This project is a BASH shell script for creating and restoring local backups of iocage jails on FreeBSD, FreeNAS, and TrueNAS systems.
- Rosettacode: Read a configuration file
- Othneil Drew: Best-README-Template
- NasKar2: Freenas-Backup-Jails
- Raze42: FreeNAS: Backup Jails Automatically Using IOCAGE Import and Export
To get a local copy up and running follow these simple steps.
Make sure you have the Bourne Again Shell (BASH) installed on your system.
- Download the zip fileS:
- Unzip it
- Edit the configuration file (cageback_rc.sh) as instructed
- Install the directory in the appropriate place on your FreeBSD/FreeNAS/TrueNAS system
backcage.sh [options] [explicit_cage_names...]
All options have defaults, so no option must be specified.
{-B or -b} Backup (default) -- cage(s) will be backed up
-R or -r Restore -- cage(s) will be restored
-C [configuration file path] or -c [configuration file path]; default is "backcage.cfg" in the same folder as backcage.sh. This option requires the path to the configuration file as its argument. See Configuration, below.
-M or -m Menu -- use a menu of available cage(s) to select candidate(s) for backup or restoration.[^1]] [^1]]:Currently only one cage at a time can be selected from a menu. A future modification might allow the user to select multiple cages from a menu.
-S or -s Secure -- Implements an extra level of security by prohibiting evaluation of configuration statements. This option also has several disadvantages. See the Configuration section below.
Backup and restore are two mutually exclusive actions. During a single invocation BackCage can either backup or restore, but not both.
Backcage operates in one of three modes, depending on the explicit cage names given in the argument list. The modes are:
- Implicit
- No arguments (explicit names) are given in the argument list. If backup is in effect, all available cages will be backed up. If restore is in effect, the latest backed up iocage jails available will be restored.
- Explicit
- One or more arguments (explicit names) are in the argument list. Only these cage(s) will be backed up or restored. If more than one backup exists for an individual cage, the latest will be use unless **Select** is in effect.
- Menu
- The list of explicit cage names is treated as a _selection list_ from which a cage may be chosen for backup or restoration. If no explicit cage names are specified, then all cages available will be used to populate the selection list.
BackCage has built-in configuration variables with default values, which may be overridden by values in a configuration file. By default this file is named "backcage.cfg," and if it does not exist the built-in values are used instead. An alternative configuration file name can be specified using the -C option.
BackCage uses Rosetta Code's configuration file format. Blank lines are ignored, as are lines beginning with a hash (#) or semicolon (;), either of which is usually used for comments.
Other lines consist of the configuration variable name, followed by its assigned value. The name is case insensitive and separated from its value by either a blank or equals sign. The values are case sensitive, and a single option name may be assigned multiple values separated by commas. Other whitespace is ignored. The configuration format does not allow for values containing commas, but other values with embedded blanks and special characters do not require enclosing quotation marks because the entire value is assigned to the option.
Configuration file processing has been modified to allow "cascading" values. A value assigned to a configuration variable may be used in the values of subsequent configuration variables simply by using the earlier option's name enclosed in curly brackets ("{" and "}") and preceeded by a dollar sign ("$") (see the examples). NasKar2 uses this approach for configuraion options, and it has some important advantages:
- It requires less typing
- It is less error prone because earlier values are automatically produced exactly in subsequent assignments
- It allows easier modification because changing an earlier value automatically results in appropriate changes to subsequent values.
Its main disadvantage is it is less secure. NasKar2 includes configuration statements in the backup/restore script itself, so the user has to be able to edit the script. Since the script itself may be executed with root or other high security status, this can be a security risk. Moving configuration statements to a separate file conforms to good programming practices, such as "encapsulating what changes". But even then if configuration assignments are executable shell commands read and executed by a shell "source" command, as is commonly done, executable statements in the configuration file can compromise security. Deliberately parsing a configuration file, as Rosetta Code and BackCage do, avoids this threat (but may not eliminate it entirely) because the configuration statements themselves need not be executable (which is why separating option names from values with a space is preferable to using an equals sign), and the parsing can check for a legal, secure format.
Nonetheless, the "cascading" values feature, in which the name of an option assigned a value early in the configuration file can be used to insert the earlier value in subsequent value assignment statements, is implemented here by using the shell script "eval" command, which executes the assigned value as shell statement. While I believe the security risk is less than most alternatives, it is still greater than not evaluating the option value at all.
Therefore, BackCage has a "Secure" option (-S or -s) that turns off such evaluation. If set, then the configuration file must "manually expand" all values to their final values by explicitly typing them in the settings. Note that this option disables the cascading timestamp in the configuration file and instead the BackCage code inserts it in the value from the manually expanded configuration file; this makes file-naming more secure but a bit less flexible than the cascading version.
If the "Secure" option is not used, all configuration assignment statements will be individually evaluated.
The configuration variables identify locations in the file system where iocages, jails, and backup-related files reside. The following table describes the variables and their default values.
| Variable | Description | Default Cascading Values |
|---|---|---|
| POOL_DIR | Path to the ZFS pool that contains the jails | /mnt/v1 |
| LOGS_DIR | Path to the directory where BackCage stores log files | ${POOL_DIR}/backups/jails/logs |
| LOG_FN | Name used for individual log files | JAIL.LOG |
| JAILS_DIR | Path to the directory where jails reside | ${POOL_DIR}/iocage/jails |
| JAILS_IMAGES | Path to the directory where jail images are stored | ${POOL_DIR}/iocage/images |
| BACKUPS_DIR | Path to where backup jails are stored | ${POOL_DIR}/backups/Jails |
| STAMP | Template, including a time stamp, for the name assigned to the individual backup directory | "IOCAGE_"$(date +'%F%H%M') |
| FULL_LOG_FN | Absolute path to the backup file | ${BACKUP_DIR}/${FILE_NAME} |
| MAX_BACKUPS | Maximum number of backups to be kept. (When set to 0, all backups are kept.) | 2 |
-
Backup all existing jails:
-
backcage.sh- This also works:
backcage.sh -b - So does this:
backcage.sh -B
- This also works:
-
Backup two specific cages:
backcage.sh foo bar -
Select cage to backup from a list:
backcage.sh -M foo bar bas -
Restore from the latest backups of all cages for which backups exist:
backcage.sh -r -
Restore one or more specific cages:
backcage.sh -r foo bar -
Select which cage to restore from a menu of all backed up cages:
backcage.sh -rm -
Select which cage to restore from a menu of explicitly named cages:
backcage.sh -R -M foo bar bas
[ ] Add Help command to display usage [ ] Allow selection of multiple cages
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Your Name - [@I don't use Twitter](https://twitter.com/I don't use Twitter) - Need private email alias
Project Link: https://github.com/Gnossos/BackCage