borg/docs/index.rst

Welcome to Darc's documentation!
================================

Darc is a Deduplicating ARChiver written in Python.
The main goal of Darc is to provide an efficient and secure way to backup data.

Features
--------
Space efficient storage
   Variable block size `deduplication <http://en.wikipedia.org/wiki/Data_deduplication>`_
   is used to reduce the number of bytes stored by detecting redundant data.
   Each file is split into a number of variable length chunks and only chunks
   that have never been seen before are compressed and added to the repository.

Secure
    All data is encrypted using `AES256 <http://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`_
    and the data integrity and authenticity is verified using
    `HMAC-SHA256 <http://en.wikipedia.org/wiki/HMAC>`_.

Remote repositories
    Darc can store data on remote hosts over SSH as long as Darc is installed on
    the remote host. The following syntax is used to specify a remote repository::

    $ darc list hostname:path
    $ darc extract hostname:path::archive-name
    $ darc extract username@hostname:path::archive-name


Definitions
-----------
Deduplication
    Deduplication is a technique for improving storage utilization by eliminating
    redundant data. 

Archive
    A Darc archive is a collection of files along with metadata that include file
    permissions, directory structure and various file attributes.

Repository
    A Darc repository is a filesystem directory storing data from zero or more archives.
    The data in a store is both deduplicated and encrypted making it both 
    efficient and safe.

Key file
    When a Darc store is initialized a key file containing a password protected
    encryption key is created. It is vital to keep this file safe since the store
    data is totally inaccessible without it.


Requirements
------------
* Python >= 3.2
* msgpack-python
* pyxattr


Installation
------------

The following instructions will install Darc in ``/usr/local/darc/`` without interfering
with the rest of the system.

1. Initialize a new python environment::

    $ virtualenv /usr/local/darc

2. Extract the source code using GIT or a release tarball::

    $ mkdir /usr/local/darc/src/
    $ cd /usr/local/darc/src/
    $ tar -xvzf darc-x.y.tar.gz
    OR
    $ git clone git://github.com/jborg/darc.git

3. Install Darc::

    $ cd darc-x.y/
    $ ../../bin/python setup.py install

4. Add /usr/local/darc/bin to $PATH


Basic Usage
===========

Initializing a store
--------------------
Before the first archive can be created a store needs to be initialized::

    $ darc init /data/my-backup.darc
    Initializing repository at "/data/my-backup.darc"
    Key file password (Leave blank for no password): *****
    Key file password again: *****
    Key file "/home/YOU/.darc/keys/data_my_backup_darc" created.
    Remember that this file (and password) is needed to access your data. Keep it safe!


Archive creation
----------------
The following command will create a new archive called ``backup-2011-09-10`` containing
all files in ``~/Documents`` and ``~/src``::

    $ darc create -v /data/my-backup.darc::backup-2011-09-10 ~/Documents ~/src

Extract an archive
------------------
The following command will extract the archive ``backup-2011-09-10``::

    $ darc extract -v /data/my-backup.darc::backup-2011-09-10

Delete an archive
-----------------
The following command will delete archive ``backup-2011-09-10``::

    $ darc delete /data/my-backup.darc::backup-2011-09-10

List store contents
-------------------
The following command will list the names of all archives in the store::

    $ darc list /data/my-backup.darc
    backup-2011-09-09
    backup-2011-09-10
    ...

List archive contents
---------------------
The following command will list the contents of the ``backup-2011-09-10`` archive::

    $ darc list /data/my-backup.darc::backup-2011-09-10
    -rw-r--r-- YOU    users       280 May 14  2010 home/YOU/Documents/something.txt
    -rw-r--r-- YOU    users       280 May 14  2010 home/YOU/Documents/something-else.pdf
    ...

Prune old archives
------------------
When performing automatic backups it is important to periodically prune old backup
archives to stop the store from growing too big.

The following command will prune old archives and only keep the
seven latest end of day archives and the five latest end of week archives::

    $ darc prune --daily=7 --weekly=5 /data/my-backup.darc


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`