== Removing expired backup archives

Tartarus is accompanied by the perl script "charon", which roams an backup site
and removes any backups archives that match a certain pattern and exceed
a specified age.

Originally a monolithic perl script designed to reap old backup files from an
FTP site, its core algorithm was moved to a separate perl module named
Tartarus::Charon::Filter so multiple "front end" scripts serving different
storage methods could be created.

All commands are configured through various command line parameters.

Charon will never remove a full backup until a incremental one depends on it;
it will only be deleted once all depending backups are expired.

= FTP

Being the original charon.pl, the perl module Tartarus::Charon::Filter and all
other scripts descended from the script which is now called "charon.ftp". Its
use can most probably best be explained by an example:

# charon.ftp --host safehaven --user john --password SECRET --dir / --maxage 7 --profile home --verbose --dry-run

This command line will try to log into the server "safehaven" using the user
name "john" and his password "SECRET" and remove backup file from the profile
"home" with are more than 7 days old. Due to the command line switch
"--dry-run", no files are actually deleted - the script will only explain its
potential actions in its output.

The script does not read tartarus backup profiles; by using hooks however it
can be called from Tartarus after completing a successfull backup run. This
way, Tartarus can pass the configuration variables to Charon:

# Hook in Charon
TARTARUS_POST_PROCESS_HOOK() {
    # pass configuration variables to charon
    # transmit the password through stdin to hide it from "ps ax"
    local CHARON="/usr/sbin/charon.ftp"
    local MAX_AGE_IN_DAYS="7"
    echo -n "$STORAGE_FTP_PASSWORD" | $CHARON \
        --host "$STORAGE_FTP_SERVER" --user "$STORAGE_FTP_USER" \
        --readpassword \
        --dir "$STORAGE_FTP_DIR" \
        --maxage "$MAX_AGE_IN_DAYS" \
        --profile "$NAME"
}

TARTARUS_POST_PROCESS_HOOK will only be executed in case of a successfull
backup, so there won't be any files removed if tartarus encounters an error
during the new backup creation.

= LOCAL

When storing tartarus backup archives in the local file system, the script
"charon.local" can be employed to remove expired files from the directory. Its
use is mostly identical to "charon.ftp", of course omitting the parameters not
suitable to a local environment:

# charon.local --dir /var/tartarus/backups/ --profile home --maxage 7 --verbose

= PIPE

For testing purposes or when using a custom storage method, the script "charon.pipe" can be used.
It does not operate on files itself, but simply reads filenames from its standard input, processing
them and writing the expired ones to the standard output. It thus can be employed in custom cleanup
scripts.

# find -maxdepth 1 -type f -printf '%f\0' | charon.local --maxage 7 --profile all | xargs -0 -- ls -l

