diff --git a/docs/book.rst b/docs/book.rst index 679a05223..a1a1b9fee 100644 --- a/docs/book.rst +++ b/docs/book.rst @@ -4,6 +4,7 @@ Borg documentation ================== .. when you add an element here, do not forget to add it to index.rst +.. Note: Some things are in appendices (see latex_appendices in conf.py) .. toctree:: :maxdepth: 2 @@ -14,9 +15,5 @@ Borg documentation usage deployment faq - support - resources - changes internals development - authors diff --git a/docs/conf.py b/docs/conf.py index dc40f2a0c..1baf39a75 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -193,12 +193,6 @@ htmlhelp_basename = 'borgdoc' # -- Options for LaTeX output -------------------------------------------------- -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '12pt' - # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ @@ -210,6 +204,11 @@ latex_documents = [ # the title page. latex_logo = '_static/logo.pdf' +latex_elements = { + 'papersize': 'a4paper', + 'pointsize': '10pt', +} + # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False @@ -224,7 +223,12 @@ latex_show_urls = 'footnote' #latex_preamble = '' # Documents to append as an appendix to all manuals. -#latex_appendices = [] +latex_appendices = [ + 'support', + 'resources', + 'changes', + 'authors', +] # If false, no module index is generated. #latex_domain_indices = True diff --git a/docs/faq.rst b/docs/faq.rst index 44cff07f7..c251417c5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -111,24 +111,6 @@ Are there other known limitations? :ref:`borg_info` shows how large (relative to the maximum size) existing archives are. -Why is my backup bigger than with attic? ----------------------------------------- - -Attic was rather unflexible when it comes to compression, it always -compressed using zlib level 6 (no way to switch compression off or -adjust the level or algorithm). - -The default in Borg is lz4, which is fast enough to not use significant CPU time -in most cases, but can only achieve modest compression. It still compresses -easily compressed data fairly well. - -zlib compression with all levels (1-9) as well as LZMA (1-6) are available -as well, for cases where they are worth it. - -Which choice is the best option depends on a number of factors, like -bandwidth to the repository, how well the data compresses, available CPU -power and so on. - If a backup stops mid-way, does the already-backed-up data stay there? ---------------------------------------------------------------------- @@ -649,6 +631,9 @@ Borg intends to be: or without warning. allow compatibility breaking for other cases. * if major version number changes, it may have incompatible changes +Migrating from Attic +#################### + What are the differences between Attic and Borg? ------------------------------------------------ @@ -659,8 +644,9 @@ Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_". Here's a (incomplete) list of some major changes: +* lots of attic issues fixed (see `issue #5 `_), + including critical data corruption bugs and security issues. * more open, faster paced development (see `issue #1 `_) -* lots of attic issues fixed (see `issue #5 `_) * less chunk management overhead (less memory and disk usage for chunks index) * faster remote cache resync (useful when backing up multiple machines into same repo) * compression: no, lz4, zlib or lzma compression, adjustable compression levels @@ -676,4 +662,48 @@ Here's a (incomplete) list of some major changes: Please read the :ref:`changelog` (or ``docs/changes.rst`` in the source distribution) for more information. -Borg is not compatible with original attic (but there is a one-way conversion). +Borg is not compatible with original Attic (but there is a one-way conversion). + +How do I migrate from Attic to Borg? +------------------------------------ + +Use :ref:`borg_upgrade`. This is a one-way process that cannot be reversed. + +There are some caveats: + +- The upgrade can only be performed on local repositories. + It cannot be performed on remote repositories. + +- If the repository is in "keyfile" encryption mode, the keyfile must + exist locally or it must be manually moved after performing the upgrade: + + 1. Locate the repository ID, contained in the ``config`` file in the repository. + 2. Locate the attic key file at ``~/.attic/keys/``. The correct key for the + repository starts with the line ``ATTIC_KEY ``. + 3. Copy the attic key file to ``~/.config/borg/keys/`` + 4. Change the first line from ``ATTIC_KEY ...`` to ``BORG_KEY ...``. + 5. Verify that the repository is now accessible (e.g. ``borg list ``). +- Attic and Borg use different :ref:`"chunker params" `. + This means that data added by Borg won't deduplicate with the existing data + stored by Attic. The effect is lessened if the files cache is used with Borg. +- Repositories in "passphrase" mode *must* be migrated to "repokey" mode using + :ref:`borg_key_migrate-to-repokey`. Borg does not support the "passphrase" mode + any other way. + +Why is my backup bigger than with attic? +---------------------------------------- + +Attic was rather unflexible when it comes to compression, it always +compressed using zlib level 6 (no way to switch compression off or +adjust the level or algorithm). + +The default in Borg is lz4, which is fast enough to not use significant CPU time +in most cases, but can only achieve modest compression. It still compresses +easily compressed data fairly well. + +zlib compression with all levels (1-9) as well as LZMA (1-6) are available +as well, for cases where they are worth it. + +Which choice is the best option depends on a number of factors, like +bandwidth to the repository, how well the data compresses, available CPU +power and so on. diff --git a/docs/usage.rst b/docs/usage.rst index 924559b34..7997bcb0a 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -563,6 +563,8 @@ Additional Notes Here are misc. notes about topics that are maybe not covered in enough detail in the usage section. +.. _chunker-params: + --chunker-params ~~~~~~~~~~~~~~~~