chroniton.pl - interface to the chroniton backup system
This document refers to chroniton.pl version 0.02, $Revision: 95 $.
$Revision: 95 $
Before you do anything else, run chroniton.pl --configure. This will create a sample configuration file and open it in your $EDITOR of choice. After you modify this file, you can edit it again with the --configure option; it won't erase your changes.
chroniton.pl --configure
$EDITOR
--configure
For the format of the configuration file, see "CONFIGURATION".
A configuration file looks something like this:
--- archive_after: 30 remove_after: 180 backup_locations: - /Users/Shared - /Users/jon storage_directory: "/mnt/backups" exclude: - /Library/Caches - /tmp - /.cpan
This configuration file will cause chroniton to backup everything in /Users/Shared and /Users/jon, except for filenames that match any of the excludes. It will automatically archive your backups every 30 days (and then immediately do a fresh full backup). chroniton will also automatically clean up (read: delete) archive files that are older than 180 days (to conserve space on the backup device).
Keep in mind that the file format is fairly strict. Spaces, in particular, have meaning, and you'll get errors if the file isn't valid YAML. See the YAML documentation for more details about YAML. ysh is a small program included with YAML that lets you interactively play with YAML -- give it a try if you've never used YAML before.
ysh
Also remember that the excludes are ``regular expressions'', so /.cpan matches /foo/bar/.cpan/5.8.6 and /home/jon/.cpanplus/BUILD (and many other things). Please see perlre for more information on regular expressions.
/.cpan
After you've configured chroniton to your satisfaction, run
chroniton.pl
to do an initial full backup. If you're interested in exactly what chroniton is doing, try
chroniton.pl --verbose
to have chroniton print more information to your terminal.
If there are any errors (or warnings), they'll be printed to your terminal, as well as to a log file. You can review the most recent logfile by typing
chroniton.pl --log
Sometimes something Really Bad happens and chroniton has to exit immediately. In this case it saves the logfile to ~/Library/Logs/chroniton (if ~/Library/Logs exists, otherwise it just dumps the log in your home directory).
The --log option can do more than show you the most recent log -- you can review an arbitrary logfile by supplying --log with the filename of the logfile you'd like to inspect:
--log
chroniton.pl --log /path/to/the/log
The logs are YAML dumps, so they should be understandable if you cat them. In fact, there's often more information in the raw dump than what chroniton.pl --log prints, so if you're not sure exactly what's going wrong, take a look at the raw file. If you're having problems with chroniton and want to submit a bug report, please include this raw YAML file, instead of the processed output of chroniton.pl --log.
cat
Once you have an inital backup, subsequent invocations of chroniton.pl will only save the changes between your filesystem and the last backup. To force chroniton.pl to do a full backup, simply run:
chroniton.pl --backup
On the rare occasion that you'd like to perform an incremental backup against chroniton's wishes, you can run
chroniton.pl --incremental
If you don't have any other backup to increment against, though, that command will exit with an error.
After you've been using chroniton for a while, you'll probably want to check on what backups you have. To do that, just run:
chroniton.pl --history
That will print something that looks like:
--- 3: archive to /tmp/backup/archive_2006-04-20T08:24:33 20 hours and 14 minutes ago 6.1K on disk, 15K in 11 objects (6 directories and no links) --- 2: full backup to /tmp/backup/backup_2006-04-21T04:36:37 2 minutes and 21 seconds ago 6.9K in 5 objects (2 directories and no links) --- 1: full backup to /tmp/backup/backup_2006-04-21T04:37:44 1 minute and 14 seconds ago 170 bytes in 1 object (1 directory and no links) 3 errors and no warnings encountered: couldn't copy /Users/Shared/.DS_Store to /tmp/backup/backup_2006-04-21T04:37:44//Users/Shared/.DS_Store: No such file or directory couldn't copy /Users/Shared/.localized to /tmp/backup/backup_2006-04-21T04:37:44//Users/Shared/.localized: No such file or directory couldn't copy /Users/Shared/SC Info to /tmp/backup/backup_2006-04-21T04:37:44//Users/Shared/SC Info: No such file or directory --- 0: incremental backup to /tmp/backup/backup_2006-04-21T04:38:53 5 seconds ago 6.9K in 5 objects (2 directories and no links)
The most recent backup is on the bottom (0) and the oldest is at the top (3). Note that this command may take some time to run, since it's loading the backup summaries into memory in order to compute the nice statistics. If you have hundereds of backups, you might want to use this opportunity to obtain a caffeniated beverage.
To get a list of the files in the most recent backup, run:
chroniton.pl --list
After you've created a config file (and tested it by doing a non-automatic backup), just add a line that looks like:
0 3 * * * chroniton.pl --quiet
to your crontab. (See crontab(5) in you system's manual if don't understand the above syntax.)
crontab
crontab(5)
The --quiet option tells chroniton to not print any (non-error) messages. This will save you the trouble of receiving an e-mail every day informing you that chroniton ran last night. If you do get a message, you'll know that something bad happened -- check the log with chroniton.pl --log.
--quiet
After a while, it becomes almost useless to have dumps of your filesystem laying around. Archiving consolidates several backups into one compressed file, dramatically saving disk space.
You can configure chroniton to archive your backups every n days by setting the archive_after configuration directive (see "CONFIGURATION" or "SYNOPSIS/Settng up Chroniton"). If you'd like to archive things manually, run
n
archive_after
chroniton.pl --archive
Note that the restore command automatically searches archives, so you don't have to worry about losing track of old files.
Restoring from a backup is just as easy as creating the backup. To restore a single file, run
chroniton.pl --restore /the/filename
(/the/filename is the full path of the file that you want to restore). If there's only one version of /the/filename in your backups, it will automatically be restored its original location. If there are multiple versions, you'll be asked to select the version you want:
/the/filename
2 versions of /Users/Shared/.DS_Store available. 1) * /Users/Shared/.DS_Store from 21 hours ago in /tmp/backup/archive_2006-04-20T08:24:33/backup_2006-04-20T08:24:29 0) /Users/Shared/.DS_Store from 1 minute and 36 seconds ago in /tmp/backup/backup_2006-04-21T05:00:49 Enter revision to restore from, or C-c to quit. revision> _
Just type the number that corresponds to the revision you want, or Control-C to quit.
To save yourself this step and automatically restore the latest version, run
chroniton.pl --restore /the/filename 0
The 0 in the command corresponds to the 0 in the listing above.
Note that chroniton will never overwrite an existing file. If you want it to, specify --force on the commandline.
--force
Restoring directories is the same as restoring files, but versions aren't as meaningful in this case. Each backup is a considered a "version" regardless of whether or not the directory or its contents changed. Like files, they won't be restored over an exisiting directory unless you force them to be.
force
Note that directories won't be recognized if you attach a trailing slash (as in, /directory/), so don't do that.
/directory/
Chroniton is configured via a config file (config.yml) stored in a "Chroniton" directory in your "application data directory", as determined by File::HomeDir. In UNIX, this is ~/chroniton, on Mac OS X, this is ~/Library/Application Support/Chroniton.
File::HomeDir
~/chroniton
~/Library/Application Support/Chroniton
Options are (as of version 0.03):
Optional. Specifies the lifetime (in days) of non-archival backups. After this number of days has passed, all (current) full and incremental backups will be compressed and stored as an archive.
Required. A list of directories to backup.
Optional. A list of regular expressions. If a path is matched by one of these regular expressions, it is not backed up. If you're not familiar with Perl's regular expression syntax, please read perlre. If you'd like to see what matches and what doesn't, run chroniton in verbose mode -- a message is printed for every file that is skipped due to your exclude rules.
Optional. Specifies the lifetime (in days) of archives. Archives older than this will be permanently removed.
Required. Where your backups (and chroniton state information) should be stored. It must be a real directory, not a link to one. It will be created if it doesn't exist.
For more information about configuring chroniton, see Chroniton::Config.
Many people seem to insist on running software like chroniton as root without having any good reason to. Chroniton is designed to back up a user's home directory on a regular basis. If there are files in a user's home directory that he can't read, he probably won't miss them if they disappear.
If you're going to run as root, though, please keep the following points in mind:
storage_directory
If other users can write to storage_directory, they could carefully replace directories that chroniton creates with symlinks. This would result in chroniton writing to whatever directory the link targets. If you're running as root, any user with write permission to the backup target could cause Chroniton to overwrite the password file (or any other file on the filesystem).
I mention this because it's difficult to create unwritable external volumes in Mac OS X.
Example exploit: User M's home directory is backed up every night at 1:00AM by root. User M creates a directory inside his home directory (we'll call it /home/haxor/etc, and adds a file called "passwd". At 1:00, M checks ps and notes that chroniton has started. He quickly replaces /storage_directory/backup_timestamp/home/haxor/etc with a symlink to the real /etc. When chroniton copies /home/haxor/etc/passwd to the storage directory, it will instead copy the file over the existing /etc/passwd, rendering the system unusable, or worse, 0wned by User M.
/home/haxor/etc
/storage_directory/backup_timestamp/home/haxor/etc
/etc
/home/haxor/etc/passwd
/etc/passwd
All of this should be obvious to anyone with any UNIX administration experience. If you're on a multi-user system, give everyone his own storage directory, that only he can read, and have him run his own chroniton process. Better yet, use a backup solution that's designed for multi-user systems, like TSM (*shudder*).
Please do not specify more than one operation. If you do, the results are undefined, and you may lose data!
Performs a full backup, ignoring any option in the configuration file that would cause Chroniton to perform an incremental backup or archive.
If a full backup exists, creates an incremental backup against the latest full backup. Exits with an error if there is no full backup to increment against.
Archives all full and incrmental backups in the backup storage directory. Exits with an error if there are no backups to archive.
Restores the file named by file. If there are multiple revisions of file available, the user is prompted to select one (unless revision is specified, in which case the revision sepcified by the value of revision is restored). Revisions are numbered such that 0 is the most recent and -1 is the oldest.
file
revision
Opens the configuration file in $EDITOR for editing. Other options are ignored.
Prints out the most recent log, or the file specified by file.
Prints out a summary of recent backups.
Print out the name of every file in the most recent backup.
Force chroniton to do something that it shouldn't. DANGEROUS.
quiet, suppress all messages
verbose, print all messages
Prints the version number.
Prints a usage summary.
Prints this message.
Displays the manual page.
Jonathan Rockway <jrockway AT cpan.org>
<jrockway AT cpan.org>
Report to RT, http://rt.cpan.org/Public/Bug/Report.html?Queue=Chroniton.
Chroniton is Copyright (c) 2006 Jonathan Rockway.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
To install Chroniton, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Chroniton
CPAN shell
perl -MCPAN -e shell install Chroniton
For more information on module installation, please visit the detailed CPAN module installation guide.