diff --git a/AUTHORS b/AUTHORS index 5378b3b6c..a4094a2d2 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,5 @@ -E-mail addresses listed here are not intended for support, please see -the `support section`_ instead. +Email addresses listed here are not intended for support. +Please see the `support section`_ instead. .. _support section: https://borgbackup.readthedocs.io/en/stable/support.html diff --git a/Brewfile b/Brewfile index c04f5f9b4..ef0b6e1df 100644 --- a/Brewfile +++ b/Brewfile @@ -5,8 +5,8 @@ brew 'xxhash' brew 'openssl@3.0' # osxfuse (aka macFUSE) is only required for "borg mount", -# but won't work on github actions' workers. -# it requires installing a kernel extension, so some users +# but won't work on GitHub Actions' workers. +# It requires installing a kernel extension, so some users # may want it and some won't. #cask 'osxfuse' diff --git a/MANIFEST.in b/MANIFEST.in index caf027ad9..4dff279ed 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,6 +1,6 @@ -# stuff we need to include into the sdist is handled automatically by +# The files we need to include in the sdist are handled automatically by # setuptools_scm - it includes all git-committed files. -# but we want to exclude some committed files/dirs not needed in the sdist: +# But we want to exclude some committed files/directories not needed in the sdist: exclude .editorconfig .gitattributes .gitignore .mailmap Vagrantfile prune .github include src/borg/platform/darwin.c src/borg/platform/freebsd.c src/borg/platform/linux.c src/borg/platform/posix.c diff --git a/SECURITY.md b/SECURITY.md index b8ef82755..08a78b932 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Supported Versions -These borg releases are currently supported with security updates. +These Borg releases are currently supported with security updates. | Version | Supported | |---------|--------------------| @@ -14,6 +14,6 @@ These borg releases are currently supported with security updates. ## Reporting a Vulnerability -See there: +See here: https://borgbackup.readthedocs.io/en/latest/support.html#security-contact diff --git a/Vagrantfile b/Vagrantfile index 4000b8792..300ea9315 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -1,7 +1,7 @@ # -*- mode: ruby -*- # vi: set ft=ruby : -# Automated creation of testing environments / binaries on misc. platforms +# Automated creation of testing environments/binaries on miscellaneous platforms $cpus = Integer(ENV.fetch('VMCPUS', '8')) # create VMs with that many cpus $xdistn = Integer(ENV.fetch('XDISTN', '8')) # dispatch tests to that many pytest workers diff --git a/docs/3rd_party/README b/docs/3rd_party/README index 1f7b9b6ad..de89008f3 100644 --- a/docs/3rd_party/README +++ b/docs/3rd_party/README @@ -1,5 +1,5 @@ -Here we store 3rd party documentation, licenses, etc. +Here we store third-party documentation, licenses, etc. -Please note that all files inside the "borg" package directory (except the -stuff excluded in setup.py) will be INSTALLED, so don't keep docs or licenses +Please note that all files inside the "borg" package directory (except those +excluded in setup.py) will be installed, so do not keep docs or licenses there. diff --git a/docs/Makefile b/docs/Makefile index 09be16fcb..283f9be71 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -21,7 +21,7 @@ help: @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" + @echo " htmlhelp to make HTML files and an HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html index d10f5f77f..663dfa563 100644 --- a/docs/_templates/globaltoc.html +++ b/docs/_templates/globaltoc.html @@ -1,6 +1,6 @@
- {# Restrict the sidebar toc depth to two levels while generating command usage pages. + {# Restrict the sidebar ToC depth to two levels while generating command usage pages. This avoids superfluous entries for each "Description" and "Examples" heading. #} {% if pagename.startswith("usage/") and pagename not in ( "usage/general", "usage/help", "usage/debug", "usage/notes", diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 72a08de36..15e9b98fe 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -1,6 +1,6 @@ {%- extends "basic/layout.html" %} -{# Do this so that bootstrap is included before the main css file #} +{# Do this so that Bootstrap is included before the main CSS file. #} {%- block htmltitle %} {% set script_files = script_files + ["_static/myscript.js"] %} @@ -20,7 +20,7 @@ {{ super() }} {% endblock %} -{# Displays the URL for the homepage if it's set or the master_doc if it is not #} +{# Displays the URL for the homepage if it's set, or the master_doc if it is not. #} {% macro homepage() -%} {%- if theme_homepage %} {%- if hasdoc(theme_homepage) %} @@ -33,7 +33,7 @@ {%- endif %} {%- endmacro %} -{# Displays the URL for the tospage if it's set or falls back to homepage macro #} +{# Displays the URL for the tospage if it's set, or falls back to the homepage macro. #} {% macro tospage() -%} {%- if theme_tospage %} {%- if hasdoc(theme_tospage) %} @@ -46,7 +46,7 @@ {%- endif %} {%- endmacro %} -{# Displays the URL for the projectpage if it's set or falls back to homepage macro #} +{# Displays the URL for the projectpage if it's set, or falls back to the homepage macro. #} {% macro projectlink() -%} {%- if theme_projectlink %} {%- if hasdoc(theme_projectlink) %} @@ -59,7 +59,7 @@ {%- endif %} {%- endmacro %} -{# Displays the next and previous links both before and after content #} +{# Displays the next and previous links both before and after the content. #} {% macro render_relations() -%} {% if prev or next %}
@@ -82,7 +82,7 @@
{%- if sidebars != None %} - {#- new style sidebar: explicitly include/exclude templates #} + {#- New-style sidebar: explicitly include/exclude templates. #} {%- for sidebartemplate in sidebars %} {%- include sidebartemplate %} {%- endfor %} diff --git a/docs/book.rst b/docs/book.rst index 56b724b26..1ac10b99f 100644 --- a/docs/book.rst +++ b/docs/book.rst @@ -5,8 +5,8 @@ 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) +.. 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 diff --git a/docs/changes.rst b/docs/changes.rst index e0410ce78..0f0833fde 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -17,7 +17,7 @@ borg 1.2.x/1.4.x to borg 2.0 Compatibility notes: -- this is a major "breaking" release that is not compatible with existing repos. +- This is a major "breaking" release that is not compatible with existing repositories. We tried to put all the necessary "breaking" changes into this release, so we hopefully do not need another breaking release in the near future. The changes @@ -33,24 +33,24 @@ Compatibility notes: you must have followed the upgrade instructions at top of the change log relating to manifest and archive TAMs (borg2 just requires these TAMs now). -- command line syntax was changed, scripts and wrappers will need changes: +- Command-line syntax was changed; scripts and wrappers will need changes: - - you will usually either export BORG_REPO= into your environment or + - You will usually either export BORG_REPO= into your environment or call borg like: "borg -r ". - in the docs, we usually omit "-r ..." for brevity. - - the scp-style REPO syntax was removed, please use ssh://..., #6697 - - ssh:// URLs: removed support for /~otheruser/, /~/ and /./, #6855. + In the docs, we usually omit "-r ..." for brevity. + - The scp-style REPO syntax was removed; please use ssh://..., #6697 + - ssh:// URLs: Removed support for /~otheruser/, /~/ and /./, #6855. New format: - ssh://user@host:port/relative/path - ssh://user@host:port//absolute/path - - -P / --prefix option was removed, please use the similar -a / --match-archives. - - archive names don't need to be unique anymore. to the contrary: - it is now strongly recommended to use the identical name for borg create + - -P / --prefix option was removed; please use the similar -a / --match-archives. + - Archive names don't need to be unique anymore. To the contrary: + It is now strongly recommended to use the identical name for borg create within the same series of archives to make borg work more efficiently. - the name now identifies a series of archive, to identify a single archive - please use aid:, e.g.: borg delete aid:d34db33f - - in case you do NOT want to adopt the "series name" way of naming archives + The name now identifies a series of archives; to identify a single archive, + please use aid:, e.g., borg delete aid:d34db33f + - In case you do NOT want to adopt the "series name" way of naming archives (like "myarchive") as we recommend, but keep using always-changing names (like "myserver-myarchive-20241231"), you can do that, but then you must make use of BORG_FILES_CACHE_SUFFIX and either set it to a constant suffix @@ -60,9 +60,9 @@ Compatibility notes: greater than the count of different archives series you write to that repo. Usually borg uses a different files cache suffix per archive (series) name and defaults to BORG_FILES_CACHE_TTL=2 because that is sufficient for that. - - the archive id is always given separately from the repository - (differently than with borg 1.x you must not give repo::archive). - - the series name or archive id is either given as a positional parameter, + - The archive ID is always given separately from the repository. + Unlike in borg 1.x, you must not give repo::archive. + - The series name or archive ID is either given as a positional parameter, like: - borg create documents ~/Documents diff --git a/docs/changes_0.x.rst b/docs/changes_0.x.rst index 39290a110..ecf6c0c77 100644 --- a/docs/changes_0.x.rst +++ b/docs/changes_0.x.rst @@ -11,9 +11,9 @@ Compatibility notes: - The new default logging level is WARNING. Previously, it was INFO, which was more verbose. Use -v (or --info) to show once again log level INFO messages. See the "general" section in the usage docs. -- for borg create, you need --list (additionally to -v) to see the long file +- For borg create, you need --list (in addition to -v) to see the long file list (was needed so you can have e.g. --stats alone without the long list) -- see below about BORG_DELETE_I_KNOW_WHAT_I_AM_DOING (was: +- See below about BORG_DELETE_I_KNOW_WHAT_I_AM_DOING (was: BORG_CHECK_I_KNOW_WHAT_I_AM_DOING) Bug fixes: @@ -48,7 +48,7 @@ New features: - update progress indication more often (e.g. for borg create within big files or for borg check repo), #500 - finer chunker granularity for items metadata stream, #547, #487 -- borg create --list now used (additionally to -v) to enable the verbose +- borg create --list is now used (in addition to -v) to enable the verbose file list output - display borg version below tracebacks, #532 @@ -86,17 +86,17 @@ Version 0.29.0 (2015-12-13) Compatibility notes: -- when upgrading to 0.29.0 you need to upgrade client as well as server - installations due to the locking and commandline interface changes otherwise - you'll get an error msg about a RPC protocol mismatch or a wrong commandline +- When upgrading to 0.29.0, you need to upgrade client as well as server + installations due to the locking and command-line interface changes; otherwise + you'll get an error message about an RPC protocol mismatch or a wrong command-line option. - if you run a server that needs to support both old and new clients, it is + If you run a server that needs to support both old and new clients, it is suggested that you have a "borg-0.28.2" and a "borg-0.29.0" command. clients then can choose via e.g. "borg --remote-path=borg-0.29.0 ...". -- the default waiting time for a lock changed from infinity to 1 second for a - better interactive user experience. if the repo you want to access is +- The default waiting time for a lock changed from infinity to 1 second for a + better interactive user experience. If the repo you want to access is currently locked, borg will now terminate after 1s with an error message. - if you have scripts that shall wait for the lock for a longer time, use + If you have scripts that should wait for the lock for a longer time, use --lock-wait N (with N being the maximum wait time in seconds). Bug fixes: diff --git a/docs/changes_1.x.rst b/docs/changes_1.x.rst index 714726c1c..d4cc7be88 100644 --- a/docs/changes_1.x.rst +++ b/docs/changes_1.x.rst @@ -73,7 +73,7 @@ no matter what encryption mode they use, including "none"): for normal production operations - it is only needed once to get the archives in a repository into a good state. All archives have a valid TAM now. -Vulnerability time line: +Vulnerability timeline: * 2023-06-13: Vulnerability discovered during code review by Thomas Waldmann * 2023-06-13...: Work on fixing the issue, upgrade procedure, docs. diff --git a/docs/conf.py b/docs/conf.py index 8e97b31a5..218d8dd2d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ -# documentation build configuration file, created by +# Documentation build configuration file, created by # sphinx-quickstart on Sat Sep 10 18:18:25 2011. # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its containing directory. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -74,7 +74,7 @@ exclude_patterns = ["_build"] # default_role = None # The Borg docs contain no or very little Python docs. -# Thus, the primary domain is rst. +# Thus, the primary domain is RST. primary_domain = "rst" # If true, '()' will be appended to :func: etc. cross-reference text. @@ -97,8 +97,8 @@ pygments_style = "sphinx" # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of built-in themes. import guzzle_sphinx_theme html_theme_path = guzzle_sphinx_theme.html_theme_path() diff --git a/docs/deployment/automated-local.rst b/docs/deployment/automated-local.rst index 38febbed0..137b51377 100644 --- a/docs/deployment/automated-local.rst +++ b/docs/deployment/automated-local.rst @@ -14,13 +14,13 @@ systemd and udev. Overview -------- -An udev rule is created to trigger on the addition of block devices. The rule contains a tag -that triggers systemd to start a oneshot service. The oneshot service executes a script in +A udev rule is created to trigger on the addition of block devices. The rule contains a tag +that triggers systemd to start a one-shot service. The one-shot service executes a script in the standard systemd service environment, which automatically captures stdout/stderr and logs it to the journal. -The script mounts the added block device, if it is a registered backup drive, and creates -backups on it. When done, it optionally unmounts the file system and spins the drive down, +The script mounts the added block device if it is a registered backup drive and creates +backups on it. When done, it optionally unmounts the filesystem and spins the drive down, so that it may be physically disconnected. Configuring the system @@ -29,7 +29,8 @@ Configuring the system First, create the ``/etc/backups`` directory (as root). All configuration goes into this directory. -Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz): +Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz):: + lsblk --fs -o +PTUUID /dev/sdz Then, create ``/etc/backups/80-backup.rules`` with the following content (all on one line):: @@ -46,8 +47,8 @@ launch the "automatic-backup" service, which we will create next, as the Type=oneshot ExecStart=/etc/backups/run.sh -Now, create the main backup script, ``/etc/backups/run.sh``. Below is a template, -modify it to suit your needs (e.g. more backup sets, dumping databases etc.). +Now, create the main backup script, ``/etc/backups/run.sh``. Below is a template; +modify it to suit your needs (e.g., more backup sets, dumping databases, etc.). .. code-block:: bash @@ -93,8 +94,8 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.). echo "Disk $uuid is a backup disk" partition_path=/dev/disk/by-uuid/$uuid - # Mount file system if not already done. This assumes that if something is already - # mounted at $MOUNTPOINT, it is the backup drive. It won't find the drive if + # Mount filesystem if not already done. This assumes that if something is already + # mounted at $MOUNTPOINT, it is the backup drive. It will not find the drive if # it was mounted somewhere else. findmnt $MOUNTPOINT >/dev/null || mount $partition_path $MOUNTPOINT drive=$(lsblk --inverse --noheadings --list --paths --output name $partition_path | head --lines 1) @@ -110,8 +111,8 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.). # Set BORG_PASSPHRASE or BORG_PASSCOMMAND somewhere around here, using export, # if encryption is used. - # No one can answer if Borg asks these questions, it is better to just fail quickly - # instead of hanging. + # Because no one can answer these questions non-interactively, it is better to + # fail quickly instead of hanging. export BORG_RELOCATED_REPO_ACCESS_IS_OK=no export BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no @@ -127,8 +128,8 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.). $TARGET::$DATE-$$-system \ / /boot - # /home is often a separate partition / file system. - # Even if it isn't (add --exclude /home above), it probably makes sense + # /home is often a separate partition/filesystem. + # Even if it is not (add --exclude /home above), it probably makes sense # to have /home in a separate archive. borg create $BORG_OPTS \ --exclude 'sh:home/*/.cache' \ @@ -150,17 +151,16 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.). fi Create the ``/etc/backups/autoeject`` file to have the script automatically eject the drive -after creating the backup. Rename the file to something else (e.g. ``/etc/backups/autoeject-no``) -when you want to do something with the drive after creating backups (e.g running check). +after creating the backup. Rename the file to something else (e.g., ``/etc/backups/autoeject-no``) +when you want to do something with the drive after creating backups (e.g., running checks). Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing the backup. Don't forget to disconnect the device physically before resuming, otherwise you'll enter a cycle. You can also add an option to power down instead. -Create an empty ``/etc/backups/backup.disks`` file, you'll register your backup drives -there. +Create an empty ``/etc/backups/backup.disks`` file, in which you will register your backup drives. -The last part is actually to enable the udev rules and services: +Finally, enable the udev rules and services: .. code-block:: bash @@ -173,13 +173,13 @@ Adding backup hard drives ------------------------- Connect your backup hard drive. Format it, if not done already. -Find the UUID of the file system that backups should be stored on:: +Find the UUID of the filesystem on which backups should be stored:: lsblk -o+uuid,label -Note the UUID into the ``/etc/backups/backup.disks`` file. +Record the UUID in the ``/etc/backups/backup.disks`` file. -Mount the drive to /mnt/backup. +Mount the drive at /mnt/backup. Initialize a Borg repository at the location indicated by ``TARGET``:: @@ -197,14 +197,14 @@ See backup logs using journalctl:: Security considerations ----------------------- -The script as shown above will mount any file system with an UUID listed in -``/etc/backups/backup.disks``. The UUID check is a safety / annoyance-reduction +The script as shown above will mount any filesystem with a UUID listed in +``/etc/backups/backup.disks``. The UUID check is a safety/annoyance-reduction mechanism to keep the script from blowing up whenever a random USB thumb drive is connected. -It is not meant as a security mechanism. Mounting file systems and reading repository -data exposes additional attack surfaces (kernel file system drivers, -possibly user space services and Borg itself). On the other hand, someone +It is not meant as a security mechanism. Mounting filesystems and reading repository +data exposes additional attack surfaces (kernel filesystem drivers, +possibly userspace services, and Borg itself). On the other hand, someone standing right next to your computer can attempt a lot of attacks, most of which -are easier to do than e.g. exploiting file systems (installing a physical key logger, +are easier to do than, e.g., exploiting filesystems (installing a physical keylogger, DMA attacks, stealing the machine, ...). Borg ensures that backups are not created on random drives that "just happen" diff --git a/docs/deployment/central-backup-server.rst b/docs/deployment/central-backup-server.rst index afb8c86fc..d697cce92 100644 --- a/docs/deployment/central-backup-server.rst +++ b/docs/deployment/central-backup-server.rst @@ -5,44 +5,44 @@ Central repository server with Ansible or Salt ============================================== -This section will give an example how to set up a borg repository server for multiple +This section gives an example of how to set up a Borg repository server for multiple clients. Machines -------- -There are multiple machines used in this section and will further be named by their -respective fully qualified domain name (fqdn). +This section uses multiple machines, referred to by their +respective fully qualified domain names (FQDNs). * The backup server: `backup01.srv.local` * The clients: - John Doe's desktop: `johndoe.clnt.local` - - Webserver 01: `web01.srv.local` + - Web server 01: `web01.srv.local` - Application server 01: `app01.srv.local` User and group -------------- -The repository server needs to have only one UNIX user for all the clients. +The repository server should have a single UNIX user for all the clients. Recommended user and group with additional settings: * User: `backup` * Group: `backup` -* Shell: `/bin/bash` (or other capable to run the `borg serve` command) +* Shell: `/bin/bash` (or another shell capable of running the `borg serve` command) * Home: `/home/backup` -Most clients shall initiate a backup from the root user to catch all -users, groups and permissions (e.g. when backing up `/home`). +Most clients should initiate a backup as the root user to capture all +users, groups, and permissions (e.g., when backing up `/home`). Folders ------- -The following folder tree layout is suggested on the repository server: +The following directory layout is suggested on the repository server: * User home directory, /home/backup * Repositories path (storage pool): /home/backup/repos -* Clients restricted paths (`/home/backup/repos/`): +* Clients’ restricted paths (`/home/backup/repos/`): - johndoe.clnt.local: `/home/backup/repos/johndoe.clnt.local` - web01.srv.local: `/home/backup/repos/web01.srv.local` @@ -60,10 +60,10 @@ but no other directories. You can allow a client to access several separate dire which could make sense if multiple machines belong to one person which should then have access to all the backups of their machines. -There is only one ssh key per client allowed. Keys are added for ``johndoe.clnt.local``, ``web01.srv.local`` and -``app01.srv.local``. But they will access the backup under only one UNIX user account as: +Only one SSH key per client is allowed. Keys are added for ``johndoe.clnt.local``, ``web01.srv.local`` and +``app01.srv.local``. They will access the backup under a single UNIX user account as ``backup@backup01.srv.local``. Every key in ``$HOME/.ssh/authorized_keys`` has a -forced command and restrictions applied as shown below: +forced command and restrictions applied, as shown below: :: @@ -73,19 +73,19 @@ forced command and restrictions applied as shown below: .. note:: The text shown above needs to be written on a single line! -The options which are added to the key will perform the following: +The options added to the key perform the following: 1. Change working directory 2. Run ``borg serve`` restricted to the client base path 3. Restrict ssh and do not allow stuff which imposes a security risk -Due to the ``cd`` command we use, the server automatically changes the current -working directory. Then client doesn't need to have knowledge of the absolute +Because of the ``cd`` command, the server automatically changes the current +working directory. The client then does not need to know the absolute or relative remote repository path and can directly access the repositories at ``ssh://@/./``. -.. note:: The setup above ignores all client given commandline parameters - which are normally appended to the `borg serve` command. +.. note:: The setup above ignores all client-given command line parameters + that are normally appended to the `borg serve` command. Client ------ @@ -96,15 +96,15 @@ The client needs to initialize the `pictures` repository like this: borg init ssh://backup@backup01.srv.local/./pictures -Or with the full path (should actually never be used, as only for demonstration purposes). -The server should automatically change the current working directory to the `` folder. +Or with the full path (this should not be used in practice; it is only for demonstration purposes). +The server automatically changes the current working directory to the `` directory. :: borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures -When `johndoe.clnt.local` tries to access a not restricted path the following error is raised. -John Doe tries to back up into the Web 01 path: +When `johndoe.clnt.local` tries to access a path outside its restriction, the following error is raised. +John Doe tries to back up into the web01 path: :: diff --git a/docs/deployment/hosting-repositories.rst b/docs/deployment/hosting-repositories.rst index 2f55aed2d..f225f0dc7 100644 --- a/docs/deployment/hosting-repositories.rst +++ b/docs/deployment/hosting-repositories.rst @@ -5,21 +5,21 @@ Hosting repositories ==================== -This sections shows how to provide repository storage securely for users. +This section shows how to provide repository storage securely for users. Repositories are accessed through SSH. Each user of the service should -have her own login which is only able to access the user's files. -Technically it would be possible to have multiple users share one login, +have their own login, which is only able to access that user's files. +Technically, it is possible to have multiple users share one login; however, separating them is better. Separate logins increase isolation -and are thus an additional layer of security and safety for both the +and provide an additional layer of security and safety for both the provider and the users. -For example, if a user manages to breach ``borg serve`` then she can -only damage her own data (assuming that the system does not have further +For example, if a user manages to breach ``borg serve``, they can +only damage their own data (assuming that the system does not have further vulnerabilities). Use the standard directory structure of the operating system. Each user -is assigned a home directory and repositories of the user reside in her +is assigned a home directory, and that user's repositories reside in their home directory. The following ``~user/.ssh/authorized_keys`` file is the most important @@ -47,7 +47,7 @@ and X11 forwarding, as well as disabling PTY allocation and execution of ~/.ssh/ If any future restriction capabilities are added to authorized_keys files they will be included in this set. -The ``command`` keyword forces execution of the specified command line +The ``command`` keyword forces execution of the specified command upon login. This must be ``borg serve``. The ``--restrict-to-repository`` option permits access to exactly **one** repository. It can be given multiple times to permit access to more than one repository. diff --git a/docs/deployment/image-backup.rst b/docs/deployment/image-backup.rst index 9a979c4a2..7a0c56330 100644 --- a/docs/deployment/image-backup.rst +++ b/docs/deployment/image-backup.rst @@ -6,10 +6,10 @@ Backing up entire disk images Backing up disk images can still be efficient with Borg because its `deduplication`_ technique makes sure only the modified parts of the file are stored. Borg also has -optional simple sparse file support for extract. +optional simple sparse file support for extraction. -It is of utmost importancy to pin down the disk you want to backup. -You need to use the SERIAL for that. +It is of utmost importance to pin down the disk you want to back up. +Use the disk's SERIAL for that. Use: .. code-block:: bash @@ -25,10 +25,10 @@ Use: echo "${PARTITIONS[@]}" echo "Disk Identifier: $DISK_ID" - # Use the following line to perform a borg backup for the full disk: + # Use the following line to perform a Borg backup for the full disk: # borg create --read-special disk-backup "$DISK_ID" - # Use the following to perform a borg backup for all partitions of the disk + # Use the following to perform a Borg backup for all partitions of the disk # borg create --read-special partitions-backup "${PARTITIONS[@]}" # Example output: @@ -47,7 +47,7 @@ Decreasing the size of image backups ------------------------------------ Disk images are as large as the full disk when uncompressed and might not get much -smaller post-deduplication after heavy use because virtually all file systems don't +smaller post-deduplication after heavy use because virtually all filesystems do not actually delete file data on disk but instead delete the filesystem entries referencing the data. Therefore, if a disk nears capacity and files are deleted again, the change will barely decrease the space it takes up when compressed and deduplicated. Depending @@ -115,8 +115,8 @@ Because the partitions were zeroed in place, restoration is only one command:: mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete it. This is ill-advised for the reasons mentioned in the ``zerofree`` man page: - - it is slow - - it makes the disk image (temporarily) grow to its maximal extent + - it is slow. + - it makes the disk image (temporarily) grow to its maximal extent. - it (temporarily) uses all free space on the disk, so other concurrent write actions may fail. Virtual machines @@ -129,7 +129,7 @@ regular file to Borg with the same issues as regular files when it comes to conc reading and writing from the same file. For backing up live VMs use filesystem snapshots on the VM host, which establishes -crash-consistency for the VM images. This means that with most file systems (that +crash-consistency for the VM images. This means that with most filesystems (that are journaling) the FS will always be fine in the backup (but may need a journal replay to become accessible). @@ -145,10 +145,10 @@ to reach application-consistency; it's a broad and complex issue that cannot be in entirety here. Hypervisor snapshots capturing most of the VM's state can also be used for backups and -can be a better alternative to pure file system based snapshots of the VM's disk, since +can be a better alternative to pure filesystem-based snapshots of the VM's disk, since no state is lost. Depending on the application this can be the easiest and most reliable way to create application-consistent backups. -Borg doesn't intend to address these issues due to their huge complexity and +Borg does not intend to address these issues due to their huge complexity and platform/software dependency. Combining Borg with the mechanisms provided by the platform (snapshots, hypervisor features) will be the best approach to start tackling them. diff --git a/docs/deployment/non-root-user.rst b/docs/deployment/non-root-user.rst index a3d6dad44..465e2e434 100644 --- a/docs/deployment/non-root-user.rst +++ b/docs/deployment/non-root-user.rst @@ -6,29 +6,29 @@ Backing up using a non-root user ================================ -This section describes how to run borg as a non-root user and still be able to -backup every file on the system. +This section describes how to run Borg as a non-root user and still be able to +back up every file on the system. -Normally borg is run as the root user to bypass all filesystem permissions and -be able to read all files. But in theory this also allows borg to modify or -delete files on your system, in case of a bug for example. +Normally, Borg is run as the root user to bypass all filesystem permissions and +be able to read all files. However, in theory this also allows Borg to modify or +delete files on your system (for example, in case of a bug). -To eliminate this possibility, we can run borg as a non-root user and give it read-only +To eliminate this possibility, we can run Borg as a non-root user and give it read-only permissions to all files on the system. Using Linux capabilities inside a systemd service ================================================= -One way to do so, is to use linux `capabilities +One way to do so is to use Linux `capabilities `_ within a systemd service. -Linux capabilities allow us to give parts of the privileges the root user has to -a non-root user. This works on a per-thread level and does not give the permission +Linux capabilities allow us to grant parts of the root user’s privileges to +a non-root user. This works on a per-thread level and does not grant permissions to the non-root user as a whole. -For this we need to run our backup script from a systemd service and use the `AmbientCapabilities +For this, we need to run the backup script from a systemd service and use the `AmbientCapabilities `_ option added in systemd 229. @@ -46,21 +46,21 @@ A very basic unit file would look like this: AmbientCapabilities=CAP_DAC_READ_SEARCH -The ``CAP_DAC_READ_SEARCH`` capability gives borg read-only access to all files and directories on the system. +The ``CAP_DAC_READ_SEARCH`` capability gives Borg read-only access to all files and directories on the system. This service can then be started manually using ``systemctl start``, a systemd timer or other methods. Restore considerations ====================== -When restoring files, the root user should be used. When using the non-root user, borg extract will -change all files to be owned by the non-root user. Using borg mount will not allow the non-root user -to access files that it would not have access to on the system itself. +Use the root user when restoring files. If you use the non-root user, ``borg extract`` will +change ownership of all restored files to the non-root user. Using ``borg mount`` will not allow the +non-root user to access files it would not be able to access on the system itself. -Other than that, the same restore process, that would be used when running the backup as root, can be used. +Other than that, you can use the same restore process you would use when running the backup as root. .. warning:: - When using a local repo and running borg commands as root, make sure to only use commands that do not - modify the repo itself, like extract or mount. Modifying the repo using the root user will break - the repo for the non-root user, since some files inside the repo will now be owned by root. + When using a local repository and running Borg commands as root, make sure to use only commands that do not + modify the repository itself, such as extract or mount. Modifying the repository as root will break it for the + non-root user, since some files inside the repository will then be owned by root. diff --git a/docs/deployment/pull-backup.rst b/docs/deployment/pull-backup.rst index 0809f8c83..0bc352906 100644 --- a/docs/deployment/pull-backup.rst +++ b/docs/deployment/pull-backup.rst @@ -6,12 +6,12 @@ Backing up in pull mode ======================= -Typically the borg client connects to a backup server using SSH as a transport +Typically the Borg client connects to a backup server using SSH as a transport when initiating a backup. This is referred to as push mode. -If you however require the backup server to initiate the connection or prefer +However, if you require the backup server to initiate the connection, or prefer it to initiate the backup run, one of the following workarounds is required to -allow such a pull mode setup. +allow such a pull-mode setup. A common use case for pull mode is to back up a remote server to a local personal computer. @@ -19,38 +19,38 @@ computer. SSHFS ===== -Assuming you have a pull backup system set up with borg, where a backup server -pulls the data from the target via SSHFS. In this mode, the backup client's file -system is mounted remotely on the backup server. Pull mode is even possible if +Assume you have a pull backup system set up with Borg, where a backup server +pulls data from the target via SSHFS. In this mode, the backup client's filesystem +is mounted remotely on the backup server. Pull mode is even possible if the SSH connection must be established by the client via a remote tunnel. Other network file systems like NFS or SMB could be used as well, but SSHFS is very simple to set up and probably the most secure one. There are some restrictions caused by SSHFS. For example, unless you define UID and GID mappings when mounting via ``sshfs``, owners and groups of the mounted -file system will probably change, and you may not have access to those files if -BorgBackup is not run with root privileges. +filesystem will probably change, and you may not have access to those files if +Borg is not run with root privileges. -SSHFS is a FUSE file system and uses the SFTP protocol, so there may be also -other unsupported features that the actual implementations of sshfs, libfuse and -sftp on the backup server do not support, like file name encodings, ACLs, xattrs -or flags. So there is no guarantee that you are able to restore a system +SSHFS is a FUSE filesystem and uses the SFTP protocol, so there may also be +unsupported features that the actual implementations of SSHFS, libfuse, and +SFTP on the backup server do not support, like filename encodings, ACLs, xattrs, +or flags. Therefore, there is no guarantee that you can restore a system completely in every aspect from such a backup. .. warning:: - To mount the client's root file system you will need root access to the - client. This contradicts to the usual threat model of BorgBackup, where - clients don't need to trust the backup server (data is encrypted). In pull + To mount the client's root filesystem you will need root access to the + client. This contradicts the usual threat model of Borg, where + clients do not need to trust the backup server (data is encrypted). In pull mode the server (when logged in as root) could cause unlimited damage to the - client. Therefore, pull mode should be used only from servers you do fully + client. Therefore, pull mode should be used only with servers you fully trust! .. warning:: - Additionally, while being chrooted into the client's root file system, - code from the client will be executed. Thus, you should only do that when - fully trusting the client. + Additionally, while chrooted into the client's root filesystem, + code from the client will be executed. Therefore, you should do this only when + you fully trust the client. .. warning:: diff --git a/docs/development.rst b/docs/development.rst index b9d01484e..7845bf81f 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -8,7 +8,7 @@ Development This chapter will get you started with Borg development. Borg is written in Python (with a little bit of Cython and C for -the performance critical parts). +the performance-critical parts). Contributions ------------- @@ -52,14 +52,14 @@ Borg development happens on the ``master`` branch and uses GitHub pull requests (if you don't have GitHub or don't want to use it you can send smaller patches via the borgbackup mailing list to the maintainers). -Stable releases are maintained on maintenance branches named ``x.y-maint``, eg. +Stable releases are maintained on maintenance branches named ``x.y-maint``, e.g., the maintenance branch of the 1.4.x series is ``1.4-maint``. Most PRs should be filed against the ``master`` branch. Only if an issue affects **only** a particular maintenance branch a PR should be filed against it directly. -While discussing / reviewing a PR it will be decided whether the +While discussing/reviewing a PR it will be decided whether the change should be applied to maintenance branches. Each maintenance branch has a corresponding *backport/x.y-maint* label, which will then be applied. @@ -105,8 +105,8 @@ were collected: Previously (until release 1.0.10) Borg used a `"merge upwards" `_ model where -most minor changes and fixes where committed to a maintenance branch -(eg. 1.0-maint), and the maintenance branch(es) were regularly merged +most minor changes and fixes were committed to a maintenance branch +(e.g. 1.0-maint), and the maintenance branch(es) were regularly merged back into the main development branch. This became more and more troublesome due to merges growing more conflict-heavy and error-prone. diff --git a/docs/faq.rst b/docs/faq.rst index 53017b06b..5c4c561f8 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -8,19 +8,19 @@ Frequently asked questions Usage & Limitations ################### -What is the difference between a repo on an external hard drive vs. repo on a server? -------------------------------------------------------------------------------------- +What is the difference between a repository on an external hard drive and a repository on a server? +--------------------------------------------------------------------------------------------------- If Borg is running in client/server mode, the client uses SSH as a transport to -talk to the remote agent, which is another Borg process (Borg is installed on -the server, too) started automatically by the client. The Borg server is doing -storage-related low-level repo operations (list, load and store objects), +talk to a remote agent, which is another Borg process (Borg is also installed on +the server) started automatically by the client. The Borg server performs +storage-related, low-level repository operations (list, load, and store objects), while the Borg client does the high-level stuff: deduplication, encryption, compression, dealing with archives, backups, restores, etc., which reduces the amount of data that goes over the network. -When Borg is writing to a repo on a locally mounted remote file system, e.g. -SSHFS, the Borg client only can do file system operations and has no agent +When Borg is writing to a repo on a locally mounted remote filesystem, e.g. +SSHFS, the Borg client can only perform filesystem operations and has no agent running on the remote side, so *every* operation needs to go over the network, which is slower. @@ -29,7 +29,7 @@ Can I back up from multiple servers into a single repository? Yes, you can! Even simultaneously. -Can I back up to multiple, swapped backup targets? +Can I back up to multiple swapped backup targets? -------------------------------------------------- It is possible to swap your backup disks if each backup medium is assigned its @@ -43,41 +43,41 @@ locations), the recommended way to do that is like this: - ``borg repo-create repo1 --encryption=X`` - ``borg repo-create repo2 --encryption=X --other-repo=repo1`` -- maybe do a snapshot to have stable and same input data for both borg create. +- Optionally, create a snapshot to have stable and identical input data for both borg create runs. - client machine ---borg create---> repo1 - client machine ---borg create---> repo2 -This will create distinct (different repo ID), but related repositories. +This will create distinct (different repository ID) but related repositories. Related means using the same chunker secret and the same id_key, thus producing -the same chunks / the same chunk ids if the input data is the same. +the same chunks/the same chunk IDs if the input data is the same. -The 2 independent borg create invocations mean that there is no error propagation +The two independent borg create invocations mean there is no error propagation from repo1 to repo2 when done like that. -An alternative way would be to use ``borg transfer`` to copy backup archives -from repo1 to repo2. Likely a bit more efficient and the archives would be identical, -but suffering from potential error propagation. +An alternative is to use ``borg transfer`` to copy backup archives +from repo1 to repo2. This is likely a bit more efficient and the archives would be identical, +but it may suffer from potential error propagation. -Warning: using borg with multiple repositories with identical repository ID (like when -creating 1:1 repository copies) is not supported and can lead to all sorts of issues, -like e.g. cache coherency issues, malfunction, data corruption. +Warning: Using Borg with multiple repositories that have identical repository IDs (such as +creating 1:1 repository copies) is not supported and can lead to various issues, +for example cache coherency issues, malfunction, or data corruption. "this is either an attack or unsafe" warning -------------------------------------------- About the warning: - Cache, or information obtained from the security directory is newer than - repository - this is either an attack or unsafe (multiple repos with same ID) + Cache or information obtained from the security directory is newer than the + repository — this is either an attack or unsafe (multiple repositories with the same ID) "unsafe": If not following the advice from the previous section, you can easily run into this by yourself by restoring an older copy of your repository. -"attack": maybe an attacker has replaced your repo by an older copy, trying to -trick you into AES counter reuse, trying to break your repo encryption. +"attack": An attacker may have replaced your repo with an older copy, trying to +trigger AES counter reuse and break your repo encryption. -Borg users have also reported that fs issues (like hw issues / I/O errors causing -the fs to become read-only) can cause this warning, see :issue:`7853`. +Borg users have also reported that file system (fs) issues (e.g., hardware issues or I/O errors causing +the file system to become read-only) can cause this warning, see :issue:`7853`. If you decide to ignore this and accept unsafe operation for this repository, you could delete the manifest-timestamp and the local cache: @@ -88,7 +88,7 @@ you could delete the manifest-timestamp and the local cache: rm ~/.config/borg/security/REPO_ID/manifest-timestamp borg repo-delete --cache-only -This is an unsafe and unsupported way to use borg, you have been warned. +This is an unsafe and unsupported way to use Borg. You have been warned. Which file types, attributes, etc. are *not* preserved? ------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 6fc3bb6a5..8d6ae6a15 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Borg Documentation .. include:: ../README.rst -.. when you add an element here, do not forget to add it to book.rst +.. When you add an element here, do not forget to add it to book.rst. .. toctree:: :maxdepth: 2 diff --git a/docs/installation.rst b/docs/installation.rst index cf762e246..674a0f970 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -82,9 +82,9 @@ Ubuntu `Ubuntu packages`_, `Ubuntu PPA`_ ``apt install borgbac .. _Ubuntu packages: https://launchpad.net/ubuntu/+source/borgbackup .. _Ubuntu PPA: https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup -Please ask package maintainers to build a package or, if you can package / +Please ask package maintainers to build a package or, if you can package/ submit it yourself, please help us with that! See :issue:`105` on -github to followup on packaging efforts. +GitHub to follow up on packaging efforts. **Current status of package in the repositories** @@ -106,12 +106,12 @@ Standalone Binary .. note:: Releases are signed with an OpenPGP key, see :ref:`security-contact` for more instructions. -Borg x86/x64 amd/intel compatible binaries (generated with `pyinstaller`_) +Borg x86/x64 AMD/Intel compatible binaries (generated with `pyinstaller`_) are available on the releases_ page for the following platforms: * **Linux**: glibc >= 2.28 (ok for most supported Linux releases). Older glibc releases are untested and may not work. -* **MacOS**: 10.12 or newer (To avoid signing issues download the file via +* **macOS**: 10.12 or newer (To avoid signing issues, download the file via command line **or** remove the ``quarantine`` attribute after downloading: ``$ xattr -dr com.apple.quarantine borg-macosx64.tgz``) * **FreeBSD**: 12.1 (unknown whether it works for older releases) diff --git a/docs/internals.rst b/docs/internals.rst index 3c6645c19..7bbb3f009 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -4,7 +4,7 @@ Internals ========= -The internals chapter describes and analyses most of the inner workings +The internals chapter describes and analyzes most of the inner workings of Borg. Borg uses a low-level, key-value store, the :ref:`repository`, and @@ -20,17 +20,17 @@ Deduplication is performed globally across all data in the repository (multiple backups and even multiple hosts), both on data and file metadata, using :ref:`chunks` created by the chunker using the Buzhash_ algorithm ("buzhash" and "buzhash64" chunker) or a simpler -fixed blocksize algorithm ("fixed" chunker). +fixed block size algorithm ("fixed" chunker). To perform the repository-wide deduplication, a hash of each chunk is checked against the :ref:`chunks cache `, which is a -hash-table of all chunks that already exist. +hash table of all chunks that already exist. .. figure:: internals/structure.png :figwidth: 100% :width: 100% - Layers in Borg. On the very top commands are implemented, using + Layers in Borg. At the very top, commands are implemented, using a data access layer provided by the Archive and Item classes. The "key" object provides both compression and authenticated encryption used by the data access layer. The "key" object represents diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst index b7ffccc36..f621def4e 100644 --- a/docs/internals/data-structures.rst +++ b/docs/internals/data-structures.rst @@ -63,7 +63,7 @@ Keys ~~~~ Repository object IDs (which are used as key into the key-value store) are -byte-strings of fixed length (256bit, 32 bytes), computed like this:: +byte strings of fixed length (256-bit, 32 bytes), computed like this:: key = id = id_hash(plaintext_data) # plain = not encrypted, not compressed, not obfuscated @@ -79,10 +79,10 @@ Each repository object is stored separately, under its ID into data/xx/yy/xxyy.. A repo object has a structure like this: -* 32bit meta size -* 32bit data size -* 64bit xxh64(meta) -* 64bit xxh64(data) +* 32-bit meta size +* 32-bit data size +* 64-bit xxh64(meta) +* 64-bit xxh64(data) * meta * data @@ -90,8 +90,8 @@ The size and xxh64 hashes can be used for server-side corruption checks without needing to decrypt anything (which would require the borg key). The overall size of repository objects varies from very small (a small source -file will be stored as a single repo object) to medium (big source files will -be cut into medium sized chunks of some MB). +file will be stored as a single repository object) to medium (big source files will +be cut into medium-sized chunks of some MB). Metadata and data are separately encrypted and authenticated (depending on the user's choices). @@ -102,7 +102,7 @@ encryption. Repo object metadata ~~~~~~~~~~~~~~~~~~~~ -Metadata is a msgpacked (and encrypted/authenticated) dict with: +Metadata is a MessagePack-encoded (and encrypted/authenticated) dict with: - ctype (compression type 0..255) - clevel (compression level 0..255) diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst index 2e36426a9..699adf166 100644 --- a/docs/internals/frontends.rst +++ b/docs/internals/frontends.rst @@ -11,8 +11,8 @@ but does mean that there are no release-to-release guarantees on what you might even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents. Borg does on the other hand provide an API on a command-line level. In other words, a frontend should -(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options -as needed and parse JSON output from borg. +(for example) create a backup archive by invoking :ref:`borg_create`, provide command-line parameters/options +as needed, and parse JSON output from Borg. Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8. diff --git a/docs/internals/security.rst b/docs/internals/security.rst index bcddbb2e8..f5bb5ef08 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -24,7 +24,7 @@ The attack model of Borg is that the environment of the client process attacker has any and all access to the repository, including interactive manipulation (man-in-the-middle) for remote repositories. -Furthermore the client environment is assumed to be persistent across +Furthermore, the client environment is assumed to be persistent across attacks (practically this means that the security database cannot be deleted between attacks). @@ -37,8 +37,8 @@ Under these circumstances Borg guarantees that the attacker cannot structural information such as the object graph (which archives refer to what chunks) -The attacker can always impose a denial of service per definition (he could -forbid connections to the repository, or delete it partly or entirely). +The attacker can always impose a denial of service by definition (they could +block connections to the repository, or delete it partly or entirely). .. _security_structural_auth: diff --git a/docs/introduction.rst b/docs/introduction.rst index ab8bd32c4..e26630f0d 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1,8 +1,8 @@ Introduction ============ -.. this shim is here to fix the structure in the PDF - rendering. without this stub, the elements in the toctree of - index.rst show up a level below the README file included +.. This shim is here to fix the structure in the PDF + rendering. Without this stub, the elements in the toctree of + index.rst show up a level below the README file included. .. include:: ../README.rst diff --git a/docs/man_intro.rst b/docs/man_intro.rst index 79480c918..ec3ede1b1 100644 --- a/docs/man_intro.rst +++ b/docs/man_intro.rst @@ -13,7 +13,7 @@ DESCRIPTION BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. -The main goal of Borg is to provide an efficient and secure way to back data up. +The main goal of Borg is to provide an efficient and secure way to back up data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. The authenticated encryption technique makes it suitable for backups to targets not @@ -22,7 +22,7 @@ fully trusted. Borg stores a set of files in an *archive*. A *repository* is a collection of *archives*. The format of repositories is Borg-specific. Borg does not distinguish archives from each other in any way other than their name, -it does not matter when or where archives were created (e.g. different hosts). +it does not matter when or where archives were created (e.g., different hosts). EXAMPLES -------- diff --git a/docs/misc/benchmark-crud.txt b/docs/misc/benchmark-crud.txt index f4ca363b9..d7d60b99d 100644 --- a/docs/misc/benchmark-crud.txt +++ b/docs/misc/benchmark-crud.txt @@ -1,9 +1,9 @@ borg benchmark crud =================== -Here is some example of borg benchmark crud output. +Here is an example of borg benchmark crud output. -I ran it on my laptop, Core i5-4200u, 8GB RAM, SATA SSD, Linux, ext4 fs. +I ran it on my laptop: Core i5-4200U, 8 GB RAM, SATA SSD, Linux, ext4 filesystem. "src" as well as repo is local, on this SSD. $ BORG_PASSPHRASE=secret borg init --encryption repokey-blake2 repo diff --git a/docs/misc/create_chunker-params.txt b/docs/misc/create_chunker-params.txt index f498ff03f..45e4a771e 100644 --- a/docs/misc/create_chunker-params.txt +++ b/docs/misc/create_chunker-params.txt @@ -3,53 +3,53 @@ About borg create --chunker-params --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE -CHUNK_MIN_EXP and CHUNK_MAX_EXP give the exponent N of the 2^N minimum and -maximum chunk size. Required: CHUNK_MIN_EXP < CHUNK_MAX_EXP. +CHUNK_MIN_EXP and CHUNK_MAX_EXP provide the exponent N for the 2^N minimum and +maximum chunk sizes. Required: CHUNK_MIN_EXP < CHUNK_MAX_EXP. Defaults: 19 (2^19 == 512KiB) minimum, 23 (2^23 == 8MiB) maximum. -Currently it is not supported to give more than 23 as maximum. +Currently, specifying a maximum greater than 23 is not supported. HASH_MASK_BITS is the number of least-significant bits of the rolling hash that need to be zero to trigger a chunk cut. Recommended: CHUNK_MIN_EXP + X <= HASH_MASK_BITS <= CHUNK_MAX_EXP - X, X >= 2 (this allows the rolling hash some freedom to make its cut at a place -determined by the windows contents rather than the min/max. chunk size). +determined by the window's contents rather than the minimum/maximum chunk size). -Default: 21 (statistically, chunks will be about 2^21 == 2MiB in size) +Default: 21 (statistically, chunks will be about 2^21 == 2MiB in size). HASH_WINDOW_SIZE: the size of the window used for the rolling hash computation. -Must be an odd number. Default: 4095B +Must be an odd number. Default: 4095B. Trying it out ============= I backed up a VM directory to demonstrate how different chunker parameters -influence repo size, index size / chunk count, compression, deduplication. +affect repository size, index size/chunk count, compression, and deduplication. -repo-sm: ~64kiB chunks (16 bits chunk mask), min chunk size 1kiB (2^10B) - (these are attic / borg 0.23 internal defaults) +repo-sm: ~64 KiB chunks (16 bits chunk mask), min chunk size 1 KiB (2^10B) + (these are Attic/Borg 0.23 internal defaults) -repo-lg: ~1MiB chunks (20 bits chunk mask), min chunk size 64kiB (2^16B) +repo-lg: ~1MiB chunks (20 bits chunk mask), min chunk size 64 KiB (2^16B) -repo-xl: 8MiB chunks (2^23B max chunk size), min chunk size 64kiB (2^16B). - The chunk mask bits was set to 31, so it (almost) never triggers. +repo-xl: 8MiB chunks (2^23B max chunk size), min chunk size 64 KiB (2^16B). + The chunk mask bits were set to 31, so it (almost) never triggers. This degrades the rolling hash based dedup to a fixed-offset dedup as the cutting point is now (almost) always the end of the buffer (at 2^23B == 8MiB). The repo index size is an indicator for the RAM needs of Borg. In this special case, the total RAM needs are about 2.1x the repo index size. -You see index size of repo-sm is 16x larger than of repo-lg, which corresponds +You see the index size of repo-sm is 16x larger than that of repo-lg, which corresponds to the ratio of the different target chunk sizes. Note: RAM needs were not a problem in this specific case (37GB data size). - But just imagine, you have 37TB of such data and much less than 42GB RAM, - then you should use the "lg" chunker params so you only need - 2.6GB RAM. Or even bigger chunks than shown for "lg" (see "xl"). + But imagine you have 37TB of such data and much less than 42GB RAM, + then you should use the "lg" chunker parameters so you need only + 2.6GB RAM. Or even larger chunks than shown for "lg" (see "xl"). You also see compression works better for larger chunks, as expected. -Duplication works worse for larger chunks, also as expected. +Deduplication works worse for larger chunks, also as expected. small chunks ============ diff --git a/docs/misc/internals-picture.txt b/docs/misc/internals-picture.txt index 01351a7bc..60da0865f 100644 --- a/docs/misc/internals-picture.txt +++ b/docs/misc/internals-picture.txt @@ -1,4 +1,4 @@ -BorgBackup from 10.000m +BorgBackup from 10,000 m ======================= +--------+ +--------+ +--------+ diff --git a/docs/misc/prune-example.txt b/docs/misc/prune-example.txt index af749e16f..d77451a85 100644 --- a/docs/misc/prune-example.txt +++ b/docs/misc/prune-example.txt @@ -1,9 +1,9 @@ borg prune visualized ===================== -Assume it is 2016-01-01, today's backup has not yet been made, you have +Assume it is 2016-01-01. Today's backup has not yet been made. You have created at least one backup on each day in 2015 except on 2015-12-19 (no -backup made on that day), and you started backing up with borg on +backup was made on that day), and you started backing up with Borg on 2015-01-01. This is what borg prune --keep-daily 14 --keep-monthly 6 --keep-yearly 1 @@ -91,17 +91,17 @@ The --keep-monthly 6 rule keeps Nov, Oct, Sep, Aug, Jul and Jun. December is not considered for this rule, because that backup was already kept because of the daily rule. -2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was +2015-12-17 is kept to satisfy the --keep-daily 14 rule, because no backup was made on 2015-12-19. If a backup had been made on that day, it would not keep the one from 2015-12-17. -We did not include weekly, hourly, minutely or secondly rules to keep this +We did not include weekly, hourly, minutely, or secondly rules to keep this example simple. They all work in basically the same way. The weekly rule is easy to understand roughly, but hard to understand in all -details. If interested, read "ISO 8601:2000 standard week-based year". +details. If you are interested, read "ISO 8601:2000 standard week-based year". -The 13weekly and 3monthly rules are two different strategies for keeping one +The 13weekly and 3monthly rules are two different strategies for keeping one backup every quarter of a year. There are `multiple ways` to define a quarter-year; borg prune recognizes two: @@ -113,12 +113,12 @@ borg prune recognizes two: March 31, April 1st to June 30th, July 1st to September 30th, and October 1st to December 31st form the quarters. -If the subtleties of the definition of a quarter year don't matter to you, a +If the subtleties of the definition of a quarter-year don't matter to you, a short summary of behavior is: -* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, July, +* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, Jul, and Oct. -* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sept. +* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sep. * Both strategies will have some overlap in which backups are kept. * The differences are negligible unless backups considered for deletion were created weekly or more frequently. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 667065fa8..03ea01f84 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -7,7 +7,7 @@ Quick Start This chapter will get you started with Borg and covers various use cases. -A step by step example +A step-by-step example ---------------------- .. include:: quickstart_example.rst.inc @@ -20,10 +20,10 @@ stores a snapshot of the data of the files "inside" it. One can later extract or mount an archive to restore from a backup. *Repositories* are filesystem directories acting as self-contained stores of archives. -Repositories can be accessed locally via path or remotely via ssh. Under the hood, +Repositories can be accessed locally via path or remotely via SSH. Under the hood, repositories contain data blocks and a manifest that tracks which blocks are in each archive. If some data hasn't changed between backups, Borg simply -references an already uploaded data chunk (deduplication). +references an already-uploaded data chunk (deduplication). .. _about_free_space: @@ -43,7 +43,7 @@ in your backup log files (you check them regularly anyway, right?). Also helpful: -- use `borg repo-space` to reserve some disk space that can be freed when the fs +- use `borg repo-space` to reserve some disk space that can be freed when the filesystem does not have free space any more. - if you use LVM: use a LV + a filesystem that you can resize later and have some unallocated PEs you can add to the LV. @@ -64,8 +64,8 @@ If you only back up your own files, run it as your normal user (i.e. not root). For a local repository always use the same user to invoke borg. -For a remote repository: always use e.g. ssh://borg@remote_host. You can use this -from different local users, the remote user running borg and accessing the +For a remote repository: always use e.g., ssh://borg@remote_host. You can use this +from different local users; the remote user running borg and accessing the repo will always be `borg`. If you need to access a local repository from different users, you can use the diff --git a/docs/quickstart_example.rst.inc b/docs/quickstart_example.rst.inc index 15c40a50e..44bb58dff 100644 --- a/docs/quickstart_example.rst.inc +++ b/docs/quickstart_example.rst.inc @@ -7,12 +7,12 @@ $ borg -r /path/to/repo create docs ~/src ~/Documents -3. The next day create a new archive using the same archive name:: +3. The next day, create a new archive using the same archive name:: $ borg -r /path/to/repo create --stats docs ~/src ~/Documents - This backup will be a lot quicker and a lot smaller since only new, never - before seen data is stored. The ``--stats`` option causes Borg to + This backup will be much quicker and much smaller, since only new, + never-before-seen data is stored. The ``--stats`` option causes Borg to output statistics about the newly created archive such as the deduplicated size (the amount of unique data not shared with other archives):: @@ -22,7 +22,7 @@ Time (start): Sat, 2022-06-25 20:21:43 Time (end): Sat, 2022-06-25 20:21:43 Duration: 0.07 seconds - Utilization of max. archive size: 0% + Utilization of maximum archive size: 0% Number of files: 699 Original size: 31.14 MB Deduplicated size: 502 B @@ -44,14 +44,14 @@ $ borg -r /path/to/repo extract aid:b80e24d2 -7. Delete the first archive (please note that this does **not** free repo disk space):: +7. Delete the first archive (please note that this does **not** immediately free repository disk space):: $ borg -r /path/to/repo delete aid:b80e24d2 - Be careful if you use an archive NAME (and not an archive ID), that might match multiple archives! - Always first use with ``--dry-run`` and ``--list``! + Be careful if you use an archive NAME (and not an archive ID), as it might match multiple archives. + Always use ``--dry-run`` and ``--list`` first! -8. Recover disk space by compacting the segment files in the repo:: +8. Recover disk space by compacting the segment files in the repository:: $ borg -r /path/to/repo compact -v diff --git a/docs/usage.rst b/docs/usage.rst index 6e11655e1..a07b3165b 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -9,11 +9,11 @@ Usage Redirecting...