From f330b4bd2afae73fdc4cf18c10bb1ff005e66c3a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Tue, 14 Jul 2015 21:31:35 +0200 Subject: [PATCH] some doc updates, see below faq about redundancy / integrity compression is optional having borg installed on backup server is optional (but faster) cygwin installation tipps do not document passphrase encryption mode example, use keyfile mode --- docs/faq.rst | 19 +++++++++++++++++-- docs/foreword.rst | 7 +++++-- docs/index.rst | 4 ++-- docs/installation.rst | 32 ++++++++++++++++++++++++++++++-- docs/usage.rst | 4 ++-- 5 files changed, 56 insertions(+), 10 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index ddfb0c834..06ea63bd2 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -70,8 +70,9 @@ When backing up to remote encrypted repos, is encryption done locally? When backing up to remote servers, do I have to trust the remote server? Yes and No. - No, as far as data confidentiality is concerned - all your files/dirs data - and metadata are stored in their encrypted form into the repository. + No, as far as data confidentiality is concerned - if you use encryption, + all your files/dirs data and metadata are stored in their encrypted form + into the repository. Yes, as an attacker with access to the remote server could delete (or otherwise make unavailable) all your backups. @@ -90,6 +91,20 @@ If I want to run |project_name| on a ARM CPU older than ARM v6? echo "2" > /proc/cpu/alignment +Can |project_name| add redundancy to the backup data to deal with hardware malfunction? + No, it can't. While that at first sounds like a good idea to defend against some + defect HDD sectors or SSD flash blocks, dealing with this in a reliable way needs a lot + of low-level storage layout information and control which we do not have (and also can't + get, even if we wanted). + + So, if you need that, consider RAID1 or a filesystems that offers redundant storage. + +Can |project_name| verify data integrity of a backup archive? + Yes, if you want to detect accidental data damage (like bit rot), use the ``check`` + operation. It will notice corruption using CRCs and hashes. + If you want to be able to detect malicious tampering also, use a encrypted repo. + It will then be able to check using CRCs and HMACs. + Why was Borg forked from Attic? Borg was created in May 2015 in response to the difficulty of getting new code or larger changes incorporated into Attic and diff --git a/docs/foreword.rst b/docs/foreword.rst index dc81e493e..c3f70c42e 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -15,7 +15,7 @@ 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. + are added to the repository (and optionally compressed). Optional data encryption All data can be protected using 256-bit AES_ encryption and data integrity @@ -23,7 +23,10 @@ Optional data encryption Off-site backups |project_name| can store data on any remote host accessible over SSH as - long as |project_name| is installed. + long as |project_name| is installed. If you don't have |project_name| + installed there, you can use some network filesytem (sshfs, nfs, ...) + to mount a filesystem located on your remote host and use it like it was + local (but that will be slower). Backups mountable as filesystems Backup archives are :ref:`mountable ` as diff --git a/docs/index.rst b/docs/index.rst index fad266ed3..8ca4fe092 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,8 +2,8 @@ Welcome to Borg ================ -|project_name| is a deduplicating and compressing backup program. -Optionally, it also supports authenticated encryption. +|project_name| is a deduplicating backup program. +Optionally, it also supports compression and authenticated encryption. 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| diff --git a/docs/installation.rst b/docs/installation.rst index 11f13fc7a..b1a20d8f2 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -24,7 +24,7 @@ archive as a FUSE filesystem. Only FUSE >= 2.8.0 can support llfuse. You only need Cython to compile the .pyx files to the respective .c files when using |project_name| code from git. For |project_name| releases, the .c -files will be bundled. +files will be bundled, so you won't need Cython to install a release. Platform notes -------------- @@ -32,7 +32,7 @@ FreeBSD: You may need to get a recent enough OpenSSL version from FreeBSD ports. Mac OS X: You may need to get a recent enough OpenSSL version from homebrew_. -Mac OS X: A recent enough FUSE implementation might be unavailable. +Mac OS X: You need OS X FUSE >= 3.0. Debian / Ubuntu installation (from git) @@ -119,3 +119,31 @@ Some of the steps detailled below might be useful also for non-git installs. # optional: run all the tests, on all supported Python versions fakeroot -u tox + + +Cygwin (from git) +----------------- +Please note that running under cygwin is rather experimental. + +You'll need at least (use the cygwin installer to fetch/install these): + +:: + python3 + python3-setuptools + python3-cython + binutils + gcc-core + git + libopenssl + make + openssh + openssl-devel + +You can then install ``pip`` and ``virtualenv``: + +:: + + easy_install pip + pip install virtualenv + +And now continue as for Linux (see above). diff --git a/docs/usage.rst b/docs/usage.rst index a77b608e6..c13e4a158 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -78,8 +78,8 @@ Examples # Remote repository (accesses a remote borg via ssh) $ borg init user@hostname:backup - # Encrypted remote repository - $ borg init --encryption=passphrase user@hostname:backup + # Encrypted remote repository, using a local key file + $ borg init --encryption=keyfile user@hostname:backup .. include:: usage/create.rst.inc