/ 
Chroniton-0.03
/ chroniton.pl

NAME

chroniton.pl - interface to the chroniton backup system

VERSION

This document refers to chroniton.pl version 0.02, $Revision: 95 $.

SYNOPSIS

Setting up Chroniton

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.

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.

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.

Backing up your data

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:

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.

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.

Seeing what backups you have

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

Scheduling automatic backups

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.)

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.

Archiving data

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

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 data

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:

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.

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.

Note that directories won't be recognized if you attach a trailing slash (as in, /directory/), so don't do that.

CONFIGURATION

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.

Options are (as of version 0.03):

archive_after

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.

backup_locations

Required. A list of directories to backup.

exclude

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.

remove_after

Optional. Specifies the lifetime (in days) of archives. Archives older than this will be permanently removed.

storage_directory

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.

SECURITY CONSIDERATIONS

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:

Writable 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.

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*).

OPTIONS

Please do not specify more than one operation. If you do, the results are undefined, and you may lose data!

--backup

Performs a full backup, ignoring any option in the configuration file that would cause Chroniton to perform an incremental backup or archive.

--incremental

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.

--archive

Archives all full and incrmental backups in the backup storage directory. Exits with an error if there are no backups to archive.

--restore [<file>] [<revision>]

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.

--config[ure]

Opens the configuration file in $EDITOR for editing. Other options are ignored.

--log [<file>]

Prints out the most recent log, or the file specified by file.

--history

Prints out a summary of recent backups.

--list

Print out the name of every file in the most recent backup.

--force

Force chroniton to do something that it shouldn't. DANGEROUS.

-[-]q[uiet]

quiet, suppress all messages

-[-]v[erbose]

verbose, print all messages

--version

Prints the version number.

--usage

Prints a usage summary.

--help

Prints this message.

--man

Displays the manual page.

AUTHOR

Jonathan Rockway <jrockway AT cpan.org>

BUGS

Report to RT, http://rt.cpan.org/Public/Bug/Report.html?Queue=Chroniton.

COPYRIGHT

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.