diff --git a/README.rst b/README.rst index 1da37cf6d..a5138d146 100644 --- a/README.rst +++ b/README.rst @@ -1,13 +1,13 @@ What is Attic? -------------- -Attic is a deduplicating backup program. The main goal of attic is to provide +Attic is a deduplicating backup program. The main goal of Attic is to provide an efficient and secure way to backup data. The data deduplication -technique used makes Attic suitable for daily backups since only actual changes +technique used makes Attic suitable for daily backups since only changes are stored. Easy to use ~~~~~~~~~~~ -Initialze backup repository and create a backup archive:: +Initialize backup repository and create a backup archive:: $ attic init /usbdrive/my-backup.attic $ attic create -v /usbdrive/my-backup.attic::documents ~/Documents @@ -25,8 +25,8 @@ Optional data encryption and authenticity is verified using HMAC-SHA256. Off-site backups - attic can store data on any remote host accessible over SSH as long as - attic is installed. + Attic can store data on any remote host accessible over SSH. This is + most efficient if Attic is also installed on the remote host. Backups mountable as filesystems Backup archives are mountable as userspace filesystems for easy backup @@ -34,8 +34,9 @@ Backups mountable as filesystems What do I need? --------------- -Attic requires Python 3.2 or above to work. Besides Python attic also requires +Attic requires Python 3.2 or above to work. Besides Python, Attic also requires msgpack-python and sufficiently recent OpenSSL (>= 1.0.0). +In order to mount archives as filesystems, llfuse is required. How do I install it? -------------------- @@ -45,8 +46,8 @@ How do I install it? Where are the docs? ------------------- -Go to https://pythonhosted.org/Attic/ for a prebuilt version of the docs. You -can also build them yourself form the docs folder. +Go to https://pythonhosted.org/Attic/ for a prebuilt version of the documentation. +You can also build it yourself from the docs folder. Where are the tests? -------------------- diff --git a/attic/archiver.py b/attic/archiver.py index 6ace22acc..a95a44df3 100644 --- a/attic/archiver.py +++ b/attic/archiver.py @@ -450,8 +450,22 @@ class Archiver: type=location_validator(archive=True), help='archive to display information about') + prune_epilog = '''The prune command prunes a repository by deleting archives + not matching any of the specified retention options. This command is normally + used by automated backup scripts wanting to keep a certain number of historic + backups. As an example, "-d 7" means to keep the latest backup on each day + for 7 days. Days without backups do not count towards the total. The rules + are applied from hourly to yearly, and backups selected by previous rules do + not count towards those of later rules. Dates and times are interpreted in + the local timezone, and weeks go from Monday to Sunday. Specifying a + negative number of archives to keep means that there is no limit. If a + prefix is set with -p, then only archives that start with the prefix are + considered for deletion and only those archives count towards the totals + specified by the rules.''' + subparser = subparsers.add_parser('prune', parents=[common_parser], - description=self.do_prune.__doc__) + description=self.do_prune.__doc__, + epilog=prune_epilog) subparser.set_defaults(func=self.do_prune) subparser.add_argument('-H', '--hourly', dest='hourly', type=int, default=0, help='number of hourly archives to keep') diff --git a/docs/global.rst.inc b/docs/global.rst.inc index e44762cb1..b0c6a8786 100644 --- a/docs/global.rst.inc +++ b/docs/global.rst.inc @@ -13,6 +13,7 @@ .. _OpenSSL: https://www.openssl.org/ .. _Python: http://www.python.org/ .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/ +.. _llfuse: https://pypi.python.org/pypi/llfuse/ .. _homebrew: http://mxcl.github.io/homebrew/ .. _issue tracker: https://github.com/jborg/attic/issues .. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace diff --git a/docs/index.rst b/docs/index.rst index 477fd8464..d43149e3b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ Welcome to Attic |project_name| is a deduplicating backup program written in Python. 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. +suitable for daily backups since only the changes are stored. Easy to use @@ -44,17 +44,17 @@ User's Guide Getting help ============ -If you've found a bug or have a concrete feature request you can add your bug -report or feature request directly to the project `issue tracker`_. For more -general questions or discussions a post to the mailing list is preferred. +If you've found a bug or have a concrete feature request, you can add your bug +report or feature request directly to the project's `issue tracker`_. For more +general questions or discussions, a post to the mailing list is preferred. Mailing list ------------ -There is a mailing list for Attic on librelist_ you can use for feature +There is a mailing list for Attic on librelist_ that you can use for feature requests and general discussions about Attic. A mailing list archive is available `here `_. -To subscribe to the list send an email to attic@librelist.com and reply -to the confirmation mail. Likevise To unsubscribe send an email to +To subscribe to the list, send an email to attic@librelist.com and reply +to the confirmation mail. Likewise, to unsubscribe, send an email to attic-unsubscribe@librelist.com and reply to the confirmation mail. diff --git a/docs/installation.rst b/docs/installation.rst index 3d237e370..034ffd50c 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,7 +5,7 @@ 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 +not the default Python version on most Linux distributions, it is usually available as an optional install. Other dependencies: @@ -16,6 +16,9 @@ Other dependencies: The OpenSSL version bundled with Mac OS X and FreeBSD is most likey too old. Newer versions are available from homebrew_ on OS X and from FreeBSD ports. +The llfuse_ python package is also required if you wish to mount an +archive as a FUSE filesystem. + Installing from PyPI using pip ------------------------------ :: @@ -39,5 +42,11 @@ Installing from git $ cd attic $ python setup.py install -Please not that when installing from git Cython_ is required to generate some files that +Please note that when installing from git, Cython_ is required to generate some files that are normally bundled with the release tarball. + +Packages +-------- + +|project_name| is also part of the Debian_, Ubuntu_ and `Arch Linux`_ +distributions of GNU/Linux. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 84db705cb..df179675a 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -113,13 +113,20 @@ Key file based encryption Remote repositories ------------------- -|project_name| can initialize and access repositories on remote hosts as the -host is accessible using SSH and |project_name| is installed. - -The following syntax is used to address remote repositories:: +|project_name| can initialize and access repositories on remote hosts if the +host is accessible using SSH. This is fastest and easiest when |project_name| +is installed on the remote host, in which case the following syntax is used:: $ attic init user@hostname:repository.attic or:: $ attic init ssh://user@hostname:port/repository.attic + +If it is not possible to install |project_name| on the remote host, +it is still possible to use the remote host to store a repository by +mounting the remote filesystem, for example, using sshfs:: + + $ sshfs user@hostname:/path/to/folder /tmp/mymountpoint + $ attic init /tmp/mymountpoint/repository.attic + $ fusermount -u /tmp/mymountpoint diff --git a/docs/usage.rst b/docs/usage.rst index 91d0fe0ee..e7b134afc 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -40,21 +40,21 @@ Examples 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 +no disk space for files or parts of files that have already been stored in other archives. Examples ~~~~~~~~ :: - # Backups ~/Documents into an archive named "my-documents" + # Backup ~/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 + --exclude '*.pyc' # Backup the root filesystem into an archive named "root-YYYY-MM-DD" NAME="root-`date +%Y-%m-%d`" @@ -82,7 +82,7 @@ Examples $ 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 extract /data/myrepo::my-files home/USERNAME/src --exclude '*.o' .. include:: usage/verify.rst.inc @@ -126,7 +126,7 @@ Examples .. 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 +any of the specified retention options. This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. @@ -134,12 +134,16 @@ Examples ~~~~~~~~ :: - # Keep 7 end of day and 4 end of week archives + # Keep 7 end of day and 4 additional 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 + # Keep 7 end of day, 4 additional end of week archives, and an + # end of month archive for every month: + $ attic prune /data/myrepo --daily=7 --weekly=4 --monthly=-1 + .. include:: usage/info.rst.inc diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 20463568d..fbea054eb 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -29,6 +29,18 @@ attic prune number of yearly archives to keep -p PREFIX, --prefix PREFIX only consider archive names starting with this prefix + + The prune command prunes a repository by deleting archives not matching any of + the specified retention options. This command is normally used by automated + backup scripts wanting to keep a certain number of historic backups. As an + example, "-d 7" means to keep the latest backup on each day for 7 days. Days + without backups do not count towards the total. The rules are applied from + hourly to yearly, and backups selected by previous rules do not count towards + those of later rules. Dates and times are interpreted in the local timezone, + and weeks go from Monday to Sunday. Specifying a negative number of archives + to keep means that there is no limit. If a prefix is set with -p, then only + archives that start with the prefix are considered for deletion and only those + archives count towards the totals specified by the rules. Description ~~~~~~~~~~~