diff --git a/attic/archiver.py b/attic/archiver.py
index 3e2f0ed76..cc8739b0e 100644
--- a/attic/archiver.py
+++ b/attic/archiver.py
@@ -46,7 +46,7 @@ class Archiver:
return RepositoryServer().serve()
def do_init(self, args):
- """Initialize a new repository
+ """Initialize an empty repository
"""
print('Initializing repository at "%s"' % args.repository.orig)
repository = self.open_repository(args.repository, create=True)
@@ -59,9 +59,9 @@ class Archiver:
return self.exit_code
def do_change_passphrase(self, args):
- """Change passphrase on repository key file
+ """Change repository key file passphrase
"""
- repository = self.open_repository(Location(args.repository))
+ repository = self.open_repository(args.repository)
manifest, key = Manifest.load(repository)
key.change_passphrase()
return self.exit_code
@@ -350,7 +350,7 @@ class Archiver:
subparser = subparsers.add_parser('init', parents=[common_parser],
description=self.do_init.__doc__)
subparser.set_defaults(func=self.do_init)
- subparser.add_argument('repository',
+ subparser.add_argument('repository', metavar='REPOSITORY',
type=location_validator(archive=False),
help='repository to create')
subparser.add_argument('--key-file', dest='keyfile',
@@ -363,7 +363,8 @@ class Archiver:
subparser = subparsers.add_parser('change-passphrase', parents=[common_parser],
description=self.do_change_passphrase.__doc__)
subparser.set_defaults(func=self.do_change_passphrase)
- subparser.add_argument('repository', type=location_validator(archive=False))
+ subparser.add_argument('repository', metavar='REPOSITORY',
+ type=location_validator(archive=False))
subparser = subparsers.add_parser('create', parents=[common_parser],
description=self.do_create.__doc__)
@@ -376,7 +377,7 @@ class Archiver:
metavar="PATTERN", help='exclude paths matching PATTERN')
subparser.add_argument('-c', '--checkpoint-interval', dest='checkpoint_interval',
type=int, default=300, metavar='SECONDS',
- help='write checkpointe ever SECONDS seconds (Default: 300)')
+ help='write checkpoint every SECONDS seconds (Default: 300)')
subparser.add_argument('--do-not-cross-mountpoints', dest='dontcross',
action='store_true', default=False,
help='do not cross mount points')
@@ -414,7 +415,7 @@ class Archiver:
subparser = subparsers.add_parser('list', parents=[common_parser],
description=self.do_list.__doc__)
subparser.set_defaults(func=self.do_list)
- subparser.add_argument('src', metavar='SRC', type=location_validator(),
+ subparser.add_argument('src', metavar='REPOSITORY_OR_ARCHIVE', type=location_validator(),
help='repository/archive to list contents of')
subparser = subparsers.add_parser('mount', parents=[common_parser],
diff --git a/docs/Makefile b/docs/Makefile
index 77369e5ab..cddb87227 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -138,5 +138,5 @@ gh-pages: html
(cd $$GH_PAGES_CLONE && git add -A && git commit -m 'Updated gh-pages' && git push) && \
rm -rf $$GH_PAGES_CLONE
-inotify:
+inotify: html
while inotifywait -r . --exclude usage.rst --exclude '_build/*' ; do make html ; done
diff --git a/docs/_static/nature.css b/docs/_static/nature.css
new file mode 100644
index 000000000..1d988b5c1
--- /dev/null
+++ b/docs/_static/nature.css
@@ -0,0 +1,283 @@
+/*
+ * nature.css_t
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- nature theme.
+ *
+ * :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+ font-family: Arial, sans-serif;
+ font-size: 100%;
+ background-color: #111;
+ color: #555;
+ margin: 0;
+ padding: 0;
+}
+
+div.documentwrapper {
+ float: left;
+ width: 100%;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 230px;
+}
+
+hr {
+ border: 1px solid #B1B4B6;
+}
+
+div.document {
+ background-color: #eee;
+}
+
+div.body {
+ background-color: #ffffff;
+ color: #3E4349;
+ padding: 0 30px 30px 30px;
+ font-size: 0.9em;
+}
+
+div.footer {
+ color: #555;
+ width: 100%;
+ padding: 13px 0;
+ text-align: center;
+ font-size: 75%;
+}
+
+div.footer a {
+ color: #444;
+ text-decoration: underline;
+}
+
+div.related {
+ background-color: #6BA81E;
+ line-height: 32px;
+ color: #fff;
+ text-shadow: 0px 1px 0 #444;
+ font-size: 0.9em;
+}
+
+div.related a {
+ color: #E2F3CC;
+}
+
+div.sphinxsidebar {
+ font-size: 0.75em;
+ line-height: 1.5em;
+}
+
+div.sphinxsidebarwrapper{
+ padding: 20px 0;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ font-family: Arial, sans-serif;
+ color: #222;
+ font-size: 1.2em;
+ font-weight: normal;
+ margin: 0;
+ padding: 5px 10px;
+ background-color: #ddd;
+ text-shadow: 1px 1px 0 white
+}
+
+div.sphinxsidebar h4{
+ font-size: 1.1em;
+}
+
+div.sphinxsidebar h3 a {
+ color: #444;
+}
+
+
+div.sphinxsidebar p {
+ color: #888;
+ padding: 5px 20px;
+}
+
+div.sphinxsidebar p.topless {
+}
+
+div.sphinxsidebar ul {
+ margin: 10px 20px;
+ padding: 0;
+ color: #000;
+}
+
+div.sphinxsidebar a {
+ color: #444;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #ccc;
+ font-family: sans-serif;
+ font-size: 1em;
+}
+
+div.sphinxsidebar input[type=text]{
+ margin-left: 20px;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+ color: #005B81;
+ text-decoration: none;
+}
+
+a:hover {
+ color: #E32E00;
+ text-decoration: underline;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+ font-family: Arial, sans-serif;
+ background-color: #BED4EB;
+ font-weight: normal;
+ color: #212224;
+ margin: 30px 0px 10px 0px;
+ padding: 5px 0 5px 10px;
+ text-shadow: 0px 1px 0 white
+}
+
+div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 150%; background-color: #C8D5E3; }
+div.body h3 { font-size: 120%; background-color: #D8DEE3; }
+div.body h4 { font-size: 110%; background-color: #D8DEE3; }
+div.body h5 { font-size: 100%; background-color: #D8DEE3; }
+div.body h6 { font-size: 100%; background-color: #D8DEE3; }
+
+a.headerlink {
+ color: #c60f0f;
+ font-size: 0.8em;
+ padding: 0 4px 0 4px;
+ text-decoration: none;
+}
+
+a.headerlink:hover {
+ background-color: #c60f0f;
+ color: white;
+}
+
+div.body p, div.body dd, div.body li {
+ line-height: 1.5em;
+}
+
+div.admonition p.admonition-title + p {
+ display: inline;
+}
+
+div.highlight{
+ background-color: white;
+}
+
+div.note {
+ background-color: #eee;
+ border: 1px solid #ccc;
+}
+
+div.seealso {
+ background-color: #ffc;
+ border: 1px solid #ff6;
+}
+
+div.topic {
+ background-color: #eee;
+}
+
+div.warning {
+ background-color: #ffe4e4;
+ border: 1px solid #f66;
+}
+
+p.admonition-title {
+ display: inline;
+}
+
+p.admonition-title:after {
+ content: ":";
+}
+
+pre {
+ padding: 10px;
+ background-color: White;
+ color: #222;
+ line-height: 1.2em;
+ border: 1px solid #C6C9CB;
+ font-size: 1.1em;
+ margin: 1.5em 0 1.5em 0;
+ -webkit-box-shadow: 1px 1px 1px #d8d8d8;
+ -moz-box-shadow: 1px 1px 1px #d8d8d8;
+}
+
+tt {
+ background-color: #ecf0f3;
+ color: #222;
+ /* padding: 1px 2px; */
+ font-size: 1.1em;
+ font-family: monospace;
+}
+
+.viewcode-back {
+ font-family: Arial, sans-serif;
+}
+
+div.viewcode-block:target {
+ background-color: #f4debf;
+ border-top: 1px solid #ac9;
+ border-bottom: 1px solid #ac9;
+}
+
+/* Customizations */
+body {
+ background-color: rgb(242, 242, 242);
+}
+div.related {
+ background-color: #0a0a0a;
+ text-shadow: none;
+}
+div.related a {
+ color: #ddd;
+}
+div.body h1,
+div.body h2,
+div.body h3 {
+ padding-left: 0;
+ background-color: inherit;
+}
+
+div.document,
+div.related {
+ width: 800px;
+ margin: 0px auto;
+}
+div.body {
+ background-color: inherit;
+ border-left: 1px solid #eee;
+}
+div.document {
+ background-color: #ffffff;
+}
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ background-color: inherit;
+}
diff --git a/docs/_themes/attic/sidebarlogo.html b/docs/_themes/attic/sidebarlogo.html
index b0c8e7363..86303c2c9 100644
--- a/docs/_themes/attic/sidebarlogo.html
+++ b/docs/_themes/attic/sidebarlogo.html
@@ -1,6 +1,5 @@
\ No newline at end of file
diff --git a/docs/_themes/attic/static/attic.css_t b/docs/_themes/attic/static/attic.css_t
index a30dd275b..9f3a119b3 100644
--- a/docs/_themes/attic/static/attic.css_t
+++ b/docs/_themes/attic/static/attic.css_t
@@ -35,10 +35,14 @@ div.sphinxsidebar {
}
h1, h2, h3 {
+ font-family: "DejaVu Serif";
font-weight: normal;
- color: #444;
+ font-style: italic;
+ color: #333;
}
-
+h1 { font-size: 200%;}
+h2 { font-size: 140%;}
+h3 { font-size: 100%;}
ul {
padding-left: 1.2em;
margin-bottom: .3em;
@@ -49,7 +53,6 @@ ul ul {
li {
margin: .1em 0;
}
-
a:link, a:visited {
color: #00608f;
text-decoration: none;
@@ -64,6 +67,9 @@ div.sphinxsidebar a:link, div.sphinxsidebar a:visited {
border-bottom: 1px dotted #555;
}
+div.sphinxsidebar input {
+ border: 1px solid #ccc;
+}
pre {
border: 1px solid #ccc;
@@ -72,17 +78,32 @@ pre {
color: #ddd;
border-radius: .4em;
box-shadow: 2px 2px #ddd;
-
+ line-height: 1.2em;
+}
+pre a:link,
+pre a:visited {
+ color: #00B0E4;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
+ border-radius: .4em;
+ box-shadow: 2px 2px #ddd;
}
div.sidebarlogo .title {
- font-size: 250%;
+ font-family: "DejaVu Serif";
+ font-style: italic;
+ font-size: 500%;
}
div.sidebarlogo .subtitle {
font-style: italic;
color: #777;
-}
\ No newline at end of file
+}
+tt span.pre {
+ font-size: 110%;
+}
+dt {
+ font-style: italic;
+ font-size: 95%;
+}
diff --git a/docs/commands.rst b/docs/commands.rst
new file mode 100644
index 000000000..794f0e7e8
--- /dev/null
+++ b/docs/commands.rst
@@ -0,0 +1,239 @@
+.. include:: global.rst.inc
+.. _detailed_usage:
+
+Commands
+========
+
+|project_name| consists of a number of commands. Each command accepts
+a number of arguments and options. The following sections will describe each
+command in detail.
+
+Quiet by default
+----------------
+
+Like most UNIX commands |project_name| is quiet by default but the ``-v`` or
+``--verbose`` option can be used to get the program to output more status
+messages as it is processing.
+
+.. _attic_init:
+
+attic init
+----------
+
+.. include:: usage/init.rst.inc
+
+This command initializes an empty :ref:`repository `.
+A repository is a filesystem directory
+containing the deduplicated data from zero or more archives.
+Encryption is enabled at repository initialization time.
+
+Examples
+~~~~~~~~
+::
+
+ # Local backup repository
+ $ attic init /data/mybackuprepo.attic
+
+ # Remote backup repository
+ $ attic init user@hostname:mybackuprepo.attic
+
+ # Encrypted remote backup repository
+ $ attic init --passphrase user@hostname:mybackuprepo.attic
+
+
+attic create
+------------
+
+.. include:: usage/create.rst.inc
+
+This command creates a backup archive containing all files found while
+recursively traversing all paths specified. The archive will consume almost
+no disk space for files or parts of files that has already been archived by
+other archives.
+
+Examples
+~~~~~~~~
+::
+
+ # Backups ~/Documents into an archive named "my-documents"
+ $ attic create /data/myrepo.attic::my-documents ~/Documents
+
+ # Backup ~/Documents and ~/src but exclude pyc files
+ $ attic create /data/myrepo.attic::my-files \
+ ~/Documents \
+ ~/src \
+ --exclude *.pyc
+
+ # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
+ NAME="root-`date +%Y-%m-%d`"
+ $ attic create /data/myrepo.attic::$NAME / --do-not-cross-mountpoints
+
+.. _attic_extract:
+
+attic extract
+-------------
+
+.. include:: usage/extract.rst.inc
+
+This command extracts the contents of an archive. By default the entire
+archive is extracted but a subset of files and directories can be selected
+by passing a list of ``PATHs`` as arguments. The file selection can further
+be restricted by using the ``--exclude`` option.
+
+Examples
+~~~~~~~~
+::
+
+ # Extract entire archive
+ $ attic extract /data/myrepo::my-files
+
+ # Extract entire archive and list files while processing
+ $ attic extract -v /data/myrepo::my-files
+
+ # Extract the "src" directory
+ $ attic extract /data/myrepo::my-files home/USERNAME/src
+
+ # Extract the "src" directory but exclude object files
+ $ attic extract /data/myrepo::my-files home/USERNAME/src --exclude *.o
+
+
+attic verify
+------------
+
+.. include:: usage/verify.rst.inc
+
+This command is similar to :ref:`attic_extract` but instead of writing any
+files to disk the command just verifies that all files are extractable and
+not corrupt. |project_name| will not compare the the archived files with the
+files on disk.
+
+
+attic delete
+------------
+
+.. include:: usage/delete.rst.inc
+
+This command deletes an archive from the repository. Any disk space not
+shared with any other existing archive is also reclaimed.
+
+
+.. _attic_list:
+
+attic list
+----------
+
+.. include:: usage/list.rst.inc
+
+This command lists the contents of a repository or an archive.
+
+Examples
+~~~~~~~~
+::
+
+ $ attic list /data/myrepo
+ my-files Thu Aug 1 23:33:22 2013
+ my-documents Thu Aug 1 23:35:43 2013
+ root-2013-08-01 Thu Aug 1 23:43:55 2013
+ root-2013-08-02 Fri Aug 2 15:18:17 2013
+ ...
+
+ $ attic list /data/myrepo::root-2013-08-02
+ drwxr-xr-x root root 0 Jun 05 12:06 .
+ lrwxrwxrwx root root 0 May 31 20:40 bin -> usr/bin
+ drwxr-xr-x root root 0 Aug 01 22:08 etc
+ drwxr-xr-x root root 0 Jul 15 22:07 etc/ImageMagick-6
+ -rw-r--r-- root root 1383 May 22 22:25 etc/ImageMagick-6/colors.xml
+ ...
+
+
+attic prune
+-----------
+
+.. include:: usage/prune.rst.inc
+
+The ``prune`` command prunes a repository by deleting archives not matching
+any of the specified retention options specified. This command is normally
+used by automated backup scripts wanting to keep a certain number of historic
+backups.
+
+Examples
+~~~~~~~~
+::
+
+ # Keep 7 end of day and 4 end of week archives
+ $ attic prune /data/myrepo --daily=7 --weekly=4
+
+ # Same as above but only apply to archive names starting with "foo"
+ $ attic prune /data/myrepo --daily=7 --weekly=4 --prefix=foo
+
+
+attic info
+----------
+
+.. include:: usage/info.rst.inc
+
+This command displays some detailed information about the specified archive.
+
+Examples
+~~~~~~~~
+::
+
+ $ attic info /data/myrepo::root-2013-08-02
+ Name: root-2013-08-02
+ Fingerprint: bc3902e2c79b6d25f5d769b335c5c49331e6537f324d8d3badcb9a0917536dbb
+ Hostname: myhostname
+ Username: root
+ Time: Fri Aug 2 15:18:17 2013
+ Command line: /usr/bin/attic create --stats /data/myrepo::root-2013-08-02 / --do-not-cross-mountpoints
+ Number of files: 147429
+ Original size: 5344169493 (4.98 GB)
+ Compressed size: 1748189642 (1.63 GB)
+ Unique data: 64805454 (61.80 MB)
+
+
+attic mount
+-----------
+
+.. include:: usage/mount.rst.inc
+
+This command mounts an archive as a FUSE filesystem. This can be useful for
+browsing an archive or restoring individual files. Unless the ``--foreground``
+option is given the command will run in the background until the filesystem
+is ``umounted``.
+
+Examples
+~~~~~~~~
+::
+
+ $ attic mount /data/myrepo::root-2013-08-02 /tmp/mymountpoint
+ $ ls /tmp/mymountpoint
+ bin boot etc lib lib64 mnt opt root sbin srv usr var
+ $ fusermount -u /tmp/mymountpoint
+
+
+attic change-passphrase
+-----------------------
+
+.. include:: usage/change-passphrase.rst.inc
+
+The key files used for repository encryption are optionally passphrase
+protected. This command can be used to change this passphrase.
+
+Examples
+~~~~~~~~
+::
+
+ # Create a key file protected repository
+ $ attic init --key-file /tmp/encrypted-repo
+ Initializing repository at "/tmp/encrypted-repo"
+ Enter passphrase (empty for no passphrase):
+ Enter same passphrase again:
+ Key file "/home/USER/.attic/keys/tmp_encrypted_repo" created.
+ Keep this file safe. Your data will be inaccessible without it.
+
+ # Change key file passphrase
+ $ attic change-passphrase /tmp/encrypted-repo
+ Enter passphrase for key file /home/USER/.attic/keys/tmp_encrypted_repo:
+ New passphrase:
+ Enter same passphrase again:
+ Key file "/home/USER/.attic/keys/tmp_encrypted_repo" updated
diff --git a/docs/conf.py b/docs/conf.py
index 335bedfff..55d63f474 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -133,7 +133,7 @@ html_static_path = ['_static']
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'index': ['sidebarlogo.html', 'sidebarusefullinks.html', 'searchbox.html'],
- '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'searchbox.html']
+ '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'sidebarusefullinks.html', 'searchbox.html']
}
# Additional templates that should be rendered to pages, maps page names to
# template names.
diff --git a/docs/detailedusage.rst b/docs/detailedusage.rst
deleted file mode 100644
index 9e0f6ecc9..000000000
--- a/docs/detailedusage.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. include:: global.rst.inc
-.. _detailed_usage:
-
-Detailed Usage
---------------
-
-|project_name| consists of a number of subcommands. Each subcommand accepts
-a number of arguments and options. The following sections will describe each
-subcommand in detail.
-
-.. include:: usage.rst
diff --git a/docs/faq.rst b/docs/faq.rst
index 106f92a0f..f4fcd2dc6 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -5,40 +5,30 @@ Frequently asked questions
==========================
Which platforms are supported?
-------------------------------
-
-Currently Linux, FreeBSD and MacOS X are supported.
+ Currently Linux, FreeBSD and MacOS X are supported.
Can I backup VM disk images?
-----------------------------
-
-Yes, the :ref:`deduplication ` technique used by |project_name|
-makes sure only the modified parts of the file are stored.
-
+ Yes, the :ref:`deduplication ` technique used by |project_name|
+ makes sure only the modified parts of the file are stored.
Which file attributes are preserved?
-------------------------------------
+ The following attributes are preserved:
-The following attributes are preserved:
-
-* Name
-* Contents
-* Time of last modification (nanosecond precision with Python >= 3.3)
-* User ID of owner
-* Group ID of owner
-* Unix Permission
-* Extended attributes (xattrs)
-
-.. Note::
- POSIX Access Control Lists (ACL_) are not yet preserved.
+ * Name
+ * Contents
+ * Time of last modification (nanosecond precision with Python >= 3.3)
+ * User ID of owner
+ * Group ID of owner
+ * Unix Permission
+ * Extended attributes (xattrs)
+ .. Note::
+ POSIX Access Control Lists (ACL_) are not yet preserved.
How can I specify the encryption passphrase programmatically?
--------------------------------------------------------------
-
-The encryption passphrase can be specified programmatically using the
-`ATTIC_PASSPHRASE` environment variable. This is convenient when setting up
-automated encrypted backups. Another option is to use
-key file based encryption with a blank passphrase. For more details see
-:ref:encrypted_repos
+ The encryption passphrase can be specified programmatically using the
+ `ATTIC_PASSPHRASE` environment variable. This is convenient when setting up
+ automated encrypted backups. Another option is to use
+ key file based encryption with a blank passphrase. See
+ :ref:`encrypted_repos` for more details.
diff --git a/docs/foreword.rst b/docs/foreword.rst
new file mode 100644
index 000000000..c8a3eb239
--- /dev/null
+++ b/docs/foreword.rst
@@ -0,0 +1,58 @@
+.. include:: global.rst.inc
+.. _foreward:
+
+Foreword
+========
+
+Features
+--------
+
+Space efficient storage
+ Variable block size `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.
+
+Optional data encryption
+ All data can be protected using 256-bit AES_ encryption and data integrity
+ and authenticity is verified using `HMAC-SHA256`_.
+
+Off-site backups
+ |project_name| can store data on any remote host accessible over SSH as
+ long as |project_name| is installed.
+
+Backups mountable as filesystems
+ Backup archives are :ref:`mountable ` as
+ `userspace filesystems`_ for easy backup verification and restores.
+
+
+Terminology
+-----------
+
+.. _deduplication_def:
+
+Deduplication
+ Deduplication is a technique for improving storage utilization by
+ eliminating redundant data.
+
+.. _archive_def:
+
+Archive
+ An archive is a collection of files along with metadata that include file
+ permissions, directory structure and various file attributes.
+ Since each archive in a repository must have a unique name a good naming
+ convention is ``hostname-YYYY-MM-DD``.
+
+.. _repository_def:
+
+Repository
+ A repository is a filesystem directory storing data from zero or more
+ archives. The data in a repository is both deduplicated and
+ optionally encrypted making it both efficient and safe. Repositories are
+ created using :ref:`attic_init` and the contents can be listed using
+ :ref:`attic_list`.
+
+Key file
+ When a repository is initialized a key file containing a password
+ protected encryption key is created. It is vital to keep this file safe
+ since the repository data is totally inaccessible without it.
diff --git a/docs/global.rst.inc b/docs/global.rst.inc
index 13eca9ea9..4254034b2 100644
--- a/docs/global.rst.inc
+++ b/docs/global.rst.inc
@@ -1,3 +1,4 @@
+.. highlight:: bash
.. |project_name| replace:: ``Attic``
.. |project_version| replace:: 0.7
.. |package_dirname| replace:: Attic-|project_version|
@@ -15,3 +16,4 @@
.. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
.. _homebrew: http://mxcl.github.io/homebrew/
.. _issue tracker: https://github.com/jborg/attic/issues
+.. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index a4dd4c985..5d9116fd2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,21 +7,6 @@ The main goal of |project_name| is to provide an efficient and secure way
to backup data. The data deduplication technique used makes |project_name|
suitable for daily backups since only actual changes are stored.
-Main Features
--------------
-Space efficient storage
- Variable block size `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.
-
-Optional data encryption
- All data can be protected using 256-bit AES_ encryption and data integrity
- and authenticity is verified using `HMAC-SHA256`_.
-
-Off-site backups
- |project_name| can store data on any remote host accessible over SSH as
- long as |project_name| is installed.
Easy to use
-----------
@@ -31,7 +16,7 @@ first backup :ref:`archive ` in two lines::
$ attic init /usbdrive/my-backup.attic
$ attic create -v /usbdrive/my-backup.attic::documents ~/Documents
-See the :ref:`generalusage` section for more detailed examples.
+See the :ref:`generalusage` section for a more detailed example.
Easy installation
-----------------
@@ -39,7 +24,7 @@ You can use pip to install |project_name| quickly and easily::
$ pip install attic
-Need more help with installing? See :ref:`installation`
+Need more help with installing? See :ref:`installation`.
User's Guide
============
@@ -47,11 +32,11 @@ User's Guide
.. toctree::
:maxdepth: 2
+ foreword
installation
- generalusage
- detailedusage
+ quickstart
+ commands
faq
- terminology
Contribute
==========
diff --git a/docs/installation.rst b/docs/installation.rst
index ad897904e..f551777bf 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -2,7 +2,7 @@
.. _installation:
Installation
-=============
+============
|project_name| requires Python_ 3.2 or above to work. Even though Python 3 is
not the default Python version on most Linux distributions it is usually
diff --git a/docs/generalusage.rst b/docs/quickstart.rst
similarity index 50%
rename from docs/generalusage.rst
rename to docs/quickstart.rst
index aab1eec9c..d8c6d80bc 100644
--- a/docs/generalusage.rst
+++ b/docs/quickstart.rst
@@ -1,51 +1,79 @@
.. include:: global.rst.inc
-.. _generalusage:
+.. _quickstart:
-General Usage
-=============
+Quick Start
+===========
-The following examples showcases how to use |project_name| to backup some
-important files from a users home directory (for more detailed information
-about each subcommand see the :ref:`detailed_usage` section).
+This chapter will get you started with |project_name|. The first section
+presents a simple example that uses |project_name| to backup data.
+The next section continues by showing how backups can be automated.
-Initialize a local :ref:`repository ` to store backup
-:ref:`archives ` in (See :ref:`encrypted_repos` and
-:ref:`remote_repos` for more details)::
+A step by step example
+----------------------
+
+1. Before any backup can be made a repository has to be initialized::
$ attic init /somewhere/my-backup.attic
-Create an archive containing the ``~/src`` and ``~/Documents`` directories::
+2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
+ *first-backup*::
$ attic create -v /somwhere/my-backup.attic::first-backup ~/src ~/Documents
-Create another archive the next day. This backup will be a lot quicker since
-only new data is stored. The ``--stats`` option tells |project_name| to print
-statistics about the newly created archive such as the amount of unique data
-(not shared with other archives)::
+3. The next day create a new archive called *second-backup*::
$ attic create -v --stats /somwhere/my-backup.attic::second-backup ~/src ~/Documents
-List all archives in the repository::
+ This backup will be a lot quicker and a lot smaller since only new never
+ before seen data is stored. The ``--stats`` causes |project_name| to output
+ statistics about the newly created archive such as the amount of unique
+ data (not shared with other archives).
+
+4. List all archives in the repository::
$ attic list /somewhere/my-backup.attic
-List the files in the *first-backup* archive::
+5. List the contents of the *first-backup* archive::
$ attic list /somewhere/my-backup.attic::first-backup
-Restore the *first-backup* archive::
+6. Restore the *first-backup* archive::
$ attic extract -v /somwhere/my-backup.attic::first-backup
-Recover disk space by manually deleting the *first-backup* archive::
+7. Recover disk space by manually deleting the *first-backup* archive::
$ attic delete /somwhere/my-backup.attic::first-backup
-Use the ``prune`` subcommand to delete all archives except a given number of
-*daily*, *weekly*, *monthly* and *yearly* archives::
- $ attic prune /somwhere/my-backup.attic --daily=7 --weekly=2 --monthly=6
+Automating backups
+------------------
+The following example script backups up ``/home`` and
+``/var/www`` to a remote server. The script also uses the
+:ref:`usage_attic_prune` subcommand to maintain a certain number
+of old archives::
+
+ #!/bin/sh
+ REPOSITORY=username@remoteserver.com:backup.attic
+
+ # Backup all of /home and /var/www except a few
+ # excluded directories
+ attic create --stats \
+ $REPOSITORY::hostname-`date +%Y-%m-%d` \
+ /home \
+ /var/www \
+ --exclude /home/*/.cache \
+ --exclude /home/Ben/Music/Justin\ Bieber \
+ --exclude *.pyc
+
+ # Use the `prune` subcommand to maintain 7 daily, 4 weekly
+ # and 6 monthly archives.
+ attic prune -v $REPOSITORY --daily=7 --weekly=4 --monthly=6
+
+.. Note::
+ This script assumes the repository has already been initalized with
+ :ref:`attic_init`.
.. _encrypted_repos:
diff --git a/docs/update_usage.sh b/docs/update_usage.sh
index 7518aac4b..a8e638190 100755
--- a/docs/update_usage.sh
+++ b/docs/update_usage.sh
@@ -1,7 +1,9 @@
#!/usr/bin/bash
-echo -n > usage.rst
-for cmd in change-passphrase create delete extract init mount prune verify; do
- LINE=`echo -n attic $cmd | tr 'a-z- ' '~'`
- echo -e ".. _usage_attic_$cmd:\n\nattic $cmd\n$LINE\n::\n" >> usage.rst
- attic $cmd -h >> usage.rst
+if [ ! -d usage ]; then
+ mkdir usage
+fi
+for cmd in change-passphrase create delete extract info init list mount prune verify; do
+ FILENAME="usage/$cmd.rst.inc"
+ echo -e "Synopsis\n~~~~~~~~\n::\n" > $FILENAME
+ attic $cmd -h | sed -e 's/^/ /' >> $FILENAME
done
diff --git a/docs/usage.rst b/docs/usage.rst
deleted file mode 100644
index 680816619..000000000
--- a/docs/usage.rst
+++ /dev/null
@@ -1,166 +0,0 @@
-.. _usage_attic_change-passphrase:
-
-attic change-passphrase
-~~~~~~~~~~~~~~~~~~~~~~~
-::
-
-usage: attic change-passphrase [-h] [-v] repository
-
-Change passphrase on repository key file
-
-positional arguments:
- repository
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
-.. _usage_attic_create:
-
-attic create
-~~~~~~~~~~~~
-::
-
-usage: attic create [-h] [-v] [-s] [-e PATTERN] [-c SECONDS]
- [--do-not-cross-mountpoints] [--numeric-owner]
- ARCHIVE PATH [PATH ...]
-
-Create new archive
-
-positional arguments:
- ARCHIVE archive to create
- PATH paths to archive
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- -s, --stats print statistics for the created archive
- -e PATTERN, --exclude PATTERN
- exclude paths matching PATTERN
- -c SECONDS, --checkpoint-interval SECONDS
- write checkpointe ever SECONDS seconds (Default: 300)
- --do-not-cross-mountpoints
- do not cross mount points
- --numeric-owner only store numeric user and group identifiers
-.. _usage_attic_delete:
-
-attic delete
-~~~~~~~~~~~~
-::
-
-usage: attic delete [-h] [-v] ARCHIVE
-
-Delete archive
-
-positional arguments:
- ARCHIVE archive to delete
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
-.. _usage_attic_extract:
-
-attic extract
-~~~~~~~~~~~~~
-::
-
-usage: attic extract [-h] [-v] [-e PATTERN] [--numeric-owner]
- ARCHIVE [PATH [PATH ...]]
-
-Extract archive contents
-
-positional arguments:
- ARCHIVE archive to extract
- PATH paths to extract
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- -e PATTERN, --exclude PATTERN
- exclude paths matching PATTERN
- --numeric-owner only obey numeric user and group identifiers
-.. _usage_attic_init:
-
-attic init
-~~~~~~~~~~
-::
-
-usage: attic init [-h] [-v] [--key-file] [--passphrase] repository
-
-Initialize a new repository
-
-positional arguments:
- repository repository to create
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- --key-file enable key file based encryption
- --passphrase enable passphrase based encryption
-.. _usage_attic_mount:
-
-attic mount
-~~~~~~~~~~~
-::
-
-usage: attic mount [-h] [-v] [-f] [-o OPTIONS] ARCHIVE MOUNTPOINT
-
-Mount archive as a FUSE fileystem
-
-positional arguments:
- ARCHIVE archive to mount
- MOUNTPOINT where to mount filesystem
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- -f, --foreground stay in foreground, do not daemonize
- -o OPTIONS Extra mount options
-.. _usage_attic_prune:
-
-attic prune
-~~~~~~~~~~~
-::
-
-usage: attic prune [-h] [-v] [-H HOURLY] [-d DAILY] [-w WEEKLY] [-m MONTHLY]
- [-y YEARLY] [-p PREFIX]
- REPOSITORY
-
-Prune repository archives according to specified rules
-
-positional arguments:
- REPOSITORY repository to prune
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- -H HOURLY, --hourly HOURLY
- number of hourly archives to keep
- -d DAILY, --daily DAILY
- number of daily archives to keep
- -w WEEKLY, --weekly WEEKLY
- number of daily archives to keep
- -m MONTHLY, --monthly MONTHLY
- number of monthly archives to keep
- -y YEARLY, --yearly YEARLY
- number of yearly archives to keep
- -p PREFIX, --prefix PREFIX
- only consider archive names starting with this prefix
-.. _usage_attic_verify:
-
-attic verify
-~~~~~~~~~~~~
-::
-
-usage: attic verify [-h] [-v] [-e PATTERN] ARCHIVE [PATH [PATH ...]]
-
-Verify archive consistency
-
-positional arguments:
- ARCHIVE archive to verity integrity of
- PATH paths to verify
-
-optional arguments:
- -h, --help show this help message and exit
- -v, --verbose verbose output
- -e PATTERN, --exclude PATTERN
- exclude paths matching PATTERN
diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc
new file mode 100644
index 000000000..03866b16a
--- /dev/null
+++ b/docs/usage/change-passphrase.rst.inc
@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic change-passphrase [-h] [-v] REPOSITORY
+
+ Change repository key file passphrase
+
+ positional arguments:
+ REPOSITORY
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
new file mode 100644
index 000000000..bc7c21d19
--- /dev/null
+++ b/docs/usage/create.rst.inc
@@ -0,0 +1,25 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic create [-h] [-v] [-s] [-e PATTERN] [-c SECONDS]
+ [--do-not-cross-mountpoints] [--numeric-owner]
+ ARCHIVE PATH [PATH ...]
+
+ Create new archive
+
+ positional arguments:
+ ARCHIVE archive to create
+ PATH paths to archive
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ -s, --stats print statistics for the created archive
+ -e PATTERN, --exclude PATTERN
+ exclude paths matching PATTERN
+ -c SECONDS, --checkpoint-interval SECONDS
+ write checkpoint every SECONDS seconds (Default: 300)
+ --do-not-cross-mountpoints
+ do not cross mount points
+ --numeric-owner only store numeric user and group identifiers
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
new file mode 100644
index 000000000..f83b44f41
--- /dev/null
+++ b/docs/usage/delete.rst.inc
@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic delete [-h] [-v] ARCHIVE
+
+ Delete archive
+
+ positional arguments:
+ ARCHIVE archive to delete
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
new file mode 100644
index 000000000..fddb85a90
--- /dev/null
+++ b/docs/usage/extract.rst.inc
@@ -0,0 +1,19 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic extract [-h] [-v] [-e PATTERN] [--numeric-owner]
+ ARCHIVE [PATH [PATH ...]]
+
+ Extract archive contents
+
+ positional arguments:
+ ARCHIVE archive to extract
+ PATH paths to extract
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ -e PATTERN, --exclude PATTERN
+ exclude paths matching PATTERN
+ --numeric-owner only obey numeric user and group identifiers
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
new file mode 100644
index 000000000..509e11c26
--- /dev/null
+++ b/docs/usage/info.rst.inc
@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic info [-h] [-v] ARCHIVE
+
+ Show archive details such as disk space used
+
+ positional arguments:
+ ARCHIVE archive to display information about
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc
new file mode 100644
index 000000000..4cb5fe228
--- /dev/null
+++ b/docs/usage/init.rst.inc
@@ -0,0 +1,16 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic init [-h] [-v] [--key-file] [--passphrase] REPOSITORY
+
+ Initialize an empty repository
+
+ positional arguments:
+ REPOSITORY repository to create
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ --key-file enable key file based encryption
+ --passphrase enable passphrase based encryption
diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc
new file mode 100644
index 000000000..4db0b914e
--- /dev/null
+++ b/docs/usage/list.rst.inc
@@ -0,0 +1,15 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic list [-h] [-v] REPOSITORY_OR_ARCHIVE
+
+ List archive or repository contents
+
+ positional arguments:
+ REPOSITORY_OR_ARCHIVE
+ repository/archive to list contents of
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc
new file mode 100644
index 000000000..0156f8ed8
--- /dev/null
+++ b/docs/usage/mount.rst.inc
@@ -0,0 +1,17 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic mount [-h] [-v] [-f] [-o OPTIONS] ARCHIVE MOUNTPOINT
+
+ Mount archive as a FUSE fileystem
+
+ positional arguments:
+ ARCHIVE archive to mount
+ MOUNTPOINT where to mount filesystem
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ -f, --foreground stay in foreground, do not daemonize
+ -o OPTIONS Extra mount options
diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc
new file mode 100644
index 000000000..e1c92892a
--- /dev/null
+++ b/docs/usage/prune.rst.inc
@@ -0,0 +1,28 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic prune [-h] [-v] [-H HOURLY] [-d DAILY] [-w WEEKLY] [-m MONTHLY]
+ [-y YEARLY] [-p PREFIX]
+ REPOSITORY
+
+ Prune repository archives according to specified rules
+
+ positional arguments:
+ REPOSITORY repository to prune
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ -H HOURLY, --hourly HOURLY
+ number of hourly archives to keep
+ -d DAILY, --daily DAILY
+ number of daily archives to keep
+ -w WEEKLY, --weekly WEEKLY
+ number of daily archives to keep
+ -m MONTHLY, --monthly MONTHLY
+ number of monthly archives to keep
+ -y YEARLY, --yearly YEARLY
+ number of yearly archives to keep
+ -p PREFIX, --prefix PREFIX
+ only consider archive names starting with this prefix
diff --git a/docs/usage/verify.rst.inc b/docs/usage/verify.rst.inc
new file mode 100644
index 000000000..d60f1c13e
--- /dev/null
+++ b/docs/usage/verify.rst.inc
@@ -0,0 +1,17 @@
+Synopsis
+~~~~~~~~
+::
+
+ usage: attic verify [-h] [-v] [-e PATTERN] ARCHIVE [PATH [PATH ...]]
+
+ Verify archive consistency
+
+ positional arguments:
+ ARCHIVE archive to verity integrity of
+ PATH paths to verify
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose verbose output
+ -e PATTERN, --exclude PATTERN
+ exclude paths matching PATTERN