Rdiff-image-tarutil

NAME

rdiff-image-tarutil - do things with tar backups

SYNOPSIS

rdiff-images-tarutil diff file1.tar file2.tar
rdiff-images-tarutil times-get times.out [file-in.tar [file-in.tar]]
rdiff-images-tarutil times-pipe times.in times.out [file-in.tar [file-out.tar]]
rdiff-images-tarutil times-set times.in [file-in.tar [file-out.tar]]

DESCRIPTION

rdiff-image-tarutil diff compares two tar files that should be nearly identical but aren't. This is useful because the rdiff-image backup system relies on backups (which are tar files) being substantially similar. If two backups are very different the differences file sent to S3 grows quickly, thus making S3's storage costs large. Thus rdiff-image-tarutil diff is typically used to compare successive backups to find out why the differences have grown.

The rdiff-image-tarutil times-... invocations are used by rdiff-image-backup(1) to record and set the creation, modification and access times of files within a tar backup. On special file types (eg, directories and device files) these times are essentially meaningless - for example a directories modification time is mangled by tar during a restore. Nonetheless, these time stamps typically change rapidly, and those changes cause the differences between backups to grow quickly. rdiff-image-backup(1) uses this tool to force these time stamps in the differential backups to be the same as they are in the full backup so they don't cause the differences file to grow unnecessarily.

The diff operation

rdiff-image-tarutil diff compares two tar files and prints out there differences like this:

: ! size=123450 path/to/filename
  mtime 1=1234456789 2=1234456789
  size 1=123450 2=123459
  uname 1=root 2=nobody
  uid 1=0 2=65535
+ size=4321 1.name=path/to/filenameX
+ size=4321 2.name=path/to/filenameX.old

The meanings of the various lines are:

! size=123450 path/to/filename: The file named path/to/filename changed. The changes are then listed, showing what attributes changes and their values on both files. Notice the data in the files isn't compared, so modifications that only change the data and not say the modification time as well will go unnoticed.
+ size=4321 1.name=path/to/filenameX: This file appears in file1.tar only.
+ size=4321 2.name=path/to/filenameX.old: This file appears in file2.tar only.

Tar files suitable for comparison are typically produced using the --tar option of rdiff-image-get(1).

The times-... operations

All these commands look for all non regular files in a tar archives (eg directories, device files, pipes, symlinks) and record or modify (or both) their time stamps. In all cases the command functions as a filter, reading its data from file-in.tar, or stdin if not supplied or "-", and writing the possibly modified output to file-out.tar, or stdout if not supplied or "-". If file-out.tar is "." the output tar file is not written. In all cases if times are recorded they are read from the times.in argument, and if being set they are written to the times.out argument. Times.in is assumed to the times.out of another run.

The operations supported are:

times-get: Record the time stamps in file-in.tar to times.out, and write the unmodified file-in.tar to file-out.tar.
times-pipe: Record the time stamps in file-in.tar to times.out, then set time stamps according to times-in, and write the resulting tar file to file-out.tar.
times-set: Set the time stamps in file-in.tar according to times-in, and write the resulting tar file to file-out.tar.

EXAMPLE

To reconstitute two tar archives already in the rdiff-image-get cache and compare them:

: rdiff-image-get \
    --no-secret --backup=20100123 \
    --tar=backup-20100123.tar
rdiff-image-get \
    --no-secret --backup=20100124 \
    --tar=backup-20100124.tar
rdiff-image-tarutil diff \
    backup-20100123.tar backup-20100124.tar

AUTHOR

Russell Stuart <russell-rdiffimage@stuart.id.au>