NOTE: click here if you get an empty page.
CYPHERTITE(1) Bitrig Reference Manual CYPHERTITE(1)
cyphertite - remote encrypting archiving client
cyphertite -ctxV [-0AHPRXhpr] [-B ctfile] [-C tmpdir] [-D debugstring]
[-E excludefile] [-F conffile] [-I includefile] [-f ctfile]
cyphertite -m -e [-r] [-v] [-D debugstring] [-F conffile] [pattern]
cyphertite -m -t [-r] [-D debugstring] [-F conffile] [pattern]
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:
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
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.
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
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).
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
In all cases except those involving remote ctfile management ( -m ), the
path to the ctfile is required:
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
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
-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.
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.
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.
Run in debug mode. debugstring is a comma delimited list of the
socket low level socket routines.
config configuration parsing.
exude memory debugging.
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.
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
Specify the location of the configuration file to use, overriding
the default values.
-H Follow symlinks passsed on the command line.
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
-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
-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
-me Delete specified remote ctfiles from the server. The arguments
may be specified as glob(7) patterns, (or, with the -r option,
-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
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.
Default configuration file.
User configuration file.
Default crypto secrets file.
Create an archive named accounting-2010.ct containing the directory
$ 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
Extract files from archive backup.ct into directory restore.
$ cyphertite -C restore -xf backup.ct
cyphertite.conf(5), glob(7), regex(3)
cyphertite was written by Conformal Systems, LLC. <email@example.com>.
Before executing the first backup on a system, run `` cyphertitectl(1)
config generate'' to interactively generate an account configuration as
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]:
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
Bitrig 0.1 October 12, 2011 Bitrig 0.1
© 1994 Man-cgi 1.15, Panagiotis Christias <firstname.lastname@example.org>