CYPHERTITE(1)

NAME
cyphertite - remote encrypting archiving client

SYNOPSIS
cyphertite -ctxV [-0AHPRXhpr] [-B ctfile] [-C tmpdir] [-D debugstring] [-E excludefile] [-F conffile] [-I includefile] [-f ctfile] [file ...]

cyphertite -m -e [-r] [-v] [-D debugstring] [-F conffile] [pattern]
cyphertite -m -t [-r] [-D debugstring] [-F conffile] [pattern]

DESCRIPTION
The cyphertite command creates, lists, or extracts files using an archive metadata file commonly known as a ctfile and remotely stored blocks of data, called “chunks”. A “chunk” is defined as a portion of a file on disk that is up to 256 KB in size. (A file that is larger than 256 KB would be split into several 256 KB chunks and one chunk that might be less than 256 KB.)

The interface is designed to be familiar to users of tar while providing a number of additional features:

DEDUPLICATION

Through the process of DEDUPLICATION, cyphertite chunks are stored only once and subsequent instances of the same data are stored as references to the existing data. Files (called " ctfiles ") reference the chunks needed to retrieve any archived file. Each chunk is identified by its SHA1 hash. Many ctfiles may reference the same chunk.

COMPRESSION

After files are split into chunks, those chunks are then compressed. The default compression algorithm is LZO because it is the fastest of the 3 algorithms available, but LZW or LZMA can be configured in cyphertite.conf(5). If a chunk increases in size on compression, the uncompressed chunk is used.

ENCRYPTION

cyphertite encrypts each chunk after compression. The encryption algorithm used is 256-bit AES-XTS with a variation on the usual disk encryption method suggested in IEEE 1619-2007: the 256-bit tweak key, K2, is normally taken as the sector number on a hard drive, here it is generated as an HMAC SHA1 of the chunk itself using a separate 256-bit key.

All locally stored ctfiles are unencrypted. ctfiles stored on a remote machine are encrypted using standard AES-XTS, with the chunk number used as the tweak key.

Network traffic is encrypted using per-user certificates signed by a 521-bit ECDSA CA key and a corresponding per-user 521-bit ECDSA key. These certificates and keys are used to setup a 256-bit AES session key for SSL. The relevant client certificates and key are provided by the remote server administrator.

The keys used to perform all the chunk-level encryption are stored in the crypto_secrets file specified in cyphertite.conf(5). The file ~/.cyphertite/ct_crypto is the default. The AES-XTS and IV keys are stored protected by PBKDF2 with a default of 256,000 rounds and a 128-byte salt. The passphrase to unlock the AES-XTS and IV keys is specified as crypto_passphrase in cyphertite.conf(5).

REALM DEDUPLICATION

If multiple machines share cyphertite.conf(5) and ct_crypto files in common, deduplication can be achieved across several machines in a realm. These machines must share an account to obtain the benefit of deduplication.

In all cases except those involving remote ctfile management ( -m ), the path to the ctfile is required:

-f ctfile
    Filename where the archive metadata is stored. For list and extract commands, this is the existing ctfile to extract from. For create commands, it is the ctfile to create. There are limitations placed on the ctfile in terms of length (128 bytes) and that it may not include certain special characters, e.g. ?, *, !, \, / etc.

One of the following flags must be present:

-c  Create new or overwrite an existing ctfile.

-t  List contents of a ctfile. If any files are named on the command line, only those files will be listed. The file arguments may be specified as glob(7) patterns (or, with the -r option, regex(3) patterns) and cyphertite will list all archive members that match that pattern.

    When used with the -m modifier cyphertite will list the remote ctfiles on the server.

-x  Extract files from archive. If any files are named on the command line, only those files will be extracted from the archive. The file arguments may be specified as glob(7) patterns (or, with the -r option, regex(3) patterns) and cyphertite will extract all archive members that match that pattern.

In addition to the flags mentioned above, the following flags may be used:

-0  Generate a level 0 (full) backup. Only applicable to remote ctfile management mode.

-A  override the config file directive ctfile_incremental_allfiles and turn that feature off. This option will cancel out -a.

-B ctfile
    Specify the archive to be used as the basis of an incremental backup. Files with a modification time (mtime) newer than the previous backup will be archived. The behavior is dump-like and helps limit the size of the ctfile and the backup window.

-C directory
    Set the current working directory. When extracting, files will be extracted into the specified directory; when creating, the specified files will be matched from the directory.

-D debugstring
    Run in debug mode. debugstring is a comma delimited list of the following types:

    socket
        low level socket routines.
    config
        configuration parsing.
    exude
        memory debugging.
    net network.
    trans
        transactions.
    sha deduplication hash calculations.
    ctfile
        generation and reading of ctfiles.
    db  Local database.
    crypto
        Cryptographical transforms and key calculations.
    file
        Filesystem access.
    xml xml messages to the server.
    vertree
        version tree calculations.
    all All of the above.

-E pattern_file
    Specify the location of a file containing a list of patterns to be ignored in list, archive and extract modes. The patterns, one per line are interpreted as glob patterns unless the -r flag is specified.

-F config
    Specify the location of the configuration file to use, overriding the default values.

-H  Follow symlinks passsed on the command line.

-I pattern_file
    Specify the location of a file containing a list of patterns to included in list, archive and extract modes. In list and extract modes it is allowed to specify a list of patterns on the command line or this option, not both. The file is interpreted as for the -E option.

-P  Do not strip leading slashes (‘/’) from pathnames. The default is to strip leading slashes.

-R  Display statistics at the end of operation. These include compression ratios, transfer speeds, byte details, etc.

-X  The option prevents cyphertite from descending into directories that have a different device number than the file from which the descent began.

-a  override the config file directive ctfile_incremental_allfiles and turn that feature on. This option will cancel out -A.

-e  Delete remote ctfiles matching pattern from the server. This option is used in conjunction with -m.

-h  Follow symbolic links as if they were a normal file or directory in archive or extract mode.

-m  Run in remote ctfile management mode. See REMOTE CTFILE MANAGEMENT MODE for an explanation.

-p  Preserve user and group ID as well as file mode regardless of the current umask(2).

-r  Enable regex(3) matching. The default is to use glob(7).

-v  Turn on verbose output.

-V  Display version information. All other options are ignored.

REMOTE CTFILE MANAGEMENT MODE
If -m is provided on the command line then cyphertite will operate on the remote ctfile store. The -t flag now operates on the remote ctfile store. Additionally -e may be used to delete remote ctfiles from the server.

-me Delete specified remote ctfiles from the server. The arguments may be specified as glob(7) patterns, (or, with the -r option, regex(3) patterns).

-mt List remote ctfiles. If any ctfiles are named on the command line, only those will be listed. The arguments may be specified as glob(7) patterns (or, with the -r option, regex(3) patterns) and cyphertite will list only the matching ctfiles.

CTFILE OPERATION MODES
Two different ctfile operation modes are supported by cyphertite: local and remote. In local mode, cyphertite operates similarly to tar(1) with the ctfiles operating analogously to the tar archive files.

In remote mode, cyphertite will instead operate on ctfiles stored on the remote server. In this case, the names provided by -f are used as tags. They are stored on the remote server with the form: YYYYMMDD-HHMMSS-tag . Extract commands will operate on the newest ctfile on the server unless the full ctfile name is provided. The cache directory defined in the cyphertite.conf(5) configuration file will be used to store local copies of the ctfiles.

BACKUP vs ARCHIVE
By default cyphertite will operate in archive mode. All data backed up will be archived forever. If a user chooses to delete old backups, this can be achieved by running the ctctl(1) command:

    $ ctctl cull

This will use the configuration setting ctfile_cull_keep_days and automatically delete any ctfile archives that are older than the specified age which are not referenced by more recent incremental backups.

For routine backup type operations, cull may be configured to be run once or twice per week, for instance using something like cron(8).

Due to how the deduplication process works, it is not recommended that cull operations be issued while backups are running. If a long running backup (eg multiple days) is running, it is highly recommended that cull operations be suspended for the duration of the long running backup.

FILES
/etc/cyphertite/cyphertite.conf
    Default configuration file.
~/.cyphertite/cyphertite.conf
    User configuration file.
~/.cyphertite/ct_crypto
    Default crypto secrets file.

EXAMPLES
Create an archive named accounting-2010.ct containing the directory /data/accounting/2010:

    $ cyphertite -cf accounting-2010.ct /data/accounting/2010

Verbosely create an archive named pictures.ct, of all files matching glob(7) pattern *.jpg:

    $ cyphertite -cvf pictures.ct *.jpg

Perform an incremental backup of an archive named htdocs-201104.ct. Files in /var/www/htdocs whose modification times (mtime) are newer than in previous backup htdocs-201104.ct will be archived.

    $ cyphertite -B htdocs-201104.ct -cf htdocs-201105.ct /var/www/htdocs

Extract files from archive backup.ct into directory restore.

    $ cyphertite -C restore -xf backup.ct

SEE ALSO
cyphertite.conf(5), glob(7), regex(3)

AUTHORS
cyphertite was written by Conformal Systems, LLC. <info@conformal.com>.

CAVEATS
Before executing the first backup on a system, run `` cyphertitectl(1) config generate'' to interactively generate an account configuration as follows:
    $ cyphertite
    cyphertite config file not found. Create one? [yes]:
    Target conf file [/root/.cyphertite/cyphertite.conf]:
    cyphertite login username: mylogin
    Save cyphertite login password to configuration file? [yes]:
    login password:
    confirm:
    Save cyphertite crypto passphrase to configuration file? [yes]:
    Automatically generate crypto passphrase? [yes]:
    Choose a ctfile operation mode (remote/local) [remote]:
    Target ctfile cache directory [/root/.cyphertite/ct_cachedir]:
    Use automatic remote incrementals? [no]:
    Configuration file created.

Using the built-in configuration file generator simplifies the install substantially.