mirror of https://github.com/borgbackup/borg.git
Rewrite for quickstart
This commit is contained in:
parent
8ada680c87
commit
949dc51156
|
@ -21,22 +21,22 @@ mount an archive to restore from a backup.
|
||||||
|
|
||||||
*Repositories* are filesystem directories acting as self-contained stores of archives.
|
*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 tracking which blocks are in each
|
repositories contain data blocks and a manifest that tracks which blocks are in each
|
||||||
archive. If some data hasn't changed from one backup to another, Borg can simply
|
archive. If some data hasn't changed between backups, Borg simply
|
||||||
reference an already uploaded data chunk (deduplication).
|
references an already uploaded data chunk (deduplication).
|
||||||
|
|
||||||
.. _about_free_space:
|
.. _about_free_space:
|
||||||
|
|
||||||
Important note about free space
|
Important note about free space
|
||||||
-------------------------------
|
-------------------------------
|
||||||
|
|
||||||
Before you start creating backups, please make sure that there is *always*
|
Before you start creating backups, ensure that there is *always* plenty
|
||||||
a good amount of free space on the filesystem that has your backup repository
|
of free space on the destination filesystem that has your backup repository
|
||||||
(and also on ~/.cache). A few GB should suffice for most hard-drive sized
|
(and also on ~/.cache). A few GB should suffice for most hard-drive sized
|
||||||
repositories. See also :ref:`cache-memory-usage`.
|
repositories. See also :ref:`cache-memory-usage`.
|
||||||
|
|
||||||
Borg doesn't use space reserved for root on repository disks (even when run as root),
|
Borg doesn't use space reserved for root on repository disks (even when run as root).
|
||||||
on file systems which do not support this mechanism (e.g. XFS) we recommend to reserve
|
On file systems which do not support this mechanism (e.g. XFS) we recommend to reserve
|
||||||
some space in Borg itself just to be safe by adjusting the ``additional_free_space``
|
some space in Borg itself just to be safe by adjusting the ``additional_free_space``
|
||||||
setting (a good starting point is ``2G``)::
|
setting (a good starting point is ``2G``)::
|
||||||
|
|
||||||
|
@ -47,7 +47,7 @@ can while aborting the current operation safely, which allows the user to free m
|
||||||
by deleting/pruning archives. This mechanism is not bullet-proof in some
|
by deleting/pruning archives. This mechanism is not bullet-proof in some
|
||||||
circumstances [1]_.
|
circumstances [1]_.
|
||||||
|
|
||||||
If you *really* run out of disk space, it can be hard or impossible to free space,
|
If you do run out of disk space, it can be hard or impossible to free space,
|
||||||
because Borg needs free space to operate - even to delete backup archives.
|
because Borg needs free space to operate - even to delete backup archives.
|
||||||
|
|
||||||
You can use some monitoring process or just include the free space information
|
You can use some monitoring process or just include the free space information
|
||||||
|
@ -71,16 +71,15 @@ Also helpful:
|
||||||
Important note about permissions
|
Important note about permissions
|
||||||
--------------------------------
|
--------------------------------
|
||||||
|
|
||||||
To avoid permissions issues (in your borg repository or borg cache), **always
|
To avoid permission issues (in your borg repository or borg cache), **always
|
||||||
access the repository using the same user account**.
|
access the repository using the same user account**.
|
||||||
|
|
||||||
If you want to back up files of other users or the operating system, running
|
If you want to back up files of other users or the operating system, running
|
||||||
borg as root likely will be required (otherwise you get `Permission denied`
|
borg as root likely will be required (otherwise you get `Permission denied`
|
||||||
errors).
|
errors).
|
||||||
If you only back up your own files, you neither need nor want to run borg as
|
If you only back up your own files, run it as your normal user (no root).
|
||||||
root, just run it as your normal user.
|
|
||||||
|
|
||||||
For a local repository just always use the same user to invoke borg.
|
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
|
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
|
from different local users, the remote user running borg and accessing the
|
||||||
|
@ -116,7 +115,7 @@ common techniques to achieve this.
|
||||||
|
|
||||||
- Shut down containers before backing up their storage volumes.
|
- Shut down containers before backing up their storage volumes.
|
||||||
|
|
||||||
For some systems Borg might work well enough without these
|
For some systems, Borg might work well enough without these
|
||||||
precautions. If you are simply backing up the files on a system that
|
precautions. If you are simply backing up the files on a system that
|
||||||
isn't very active (e.g. in a typical home directory), Borg usually
|
isn't very active (e.g. in a typical home directory), Borg usually
|
||||||
works well enough without further care for consistency. Log files and
|
works well enough without further care for consistency. Log files and
|
||||||
|
@ -139,8 +138,8 @@ complete operating system) to a repository ``~/backup/main`` on a remote server
|
||||||
Some files which aren't necessarily needed in this backup are excluded. See
|
Some files which aren't necessarily needed in this backup are excluded. See
|
||||||
:ref:`borg_patterns` on how to add more exclude options.
|
:ref:`borg_patterns` on how to add more exclude options.
|
||||||
|
|
||||||
After the backup this script also uses the :ref:`borg_prune` subcommand to keep
|
After the backup, this script also uses the :ref:`borg_prune` subcommand to keep
|
||||||
only a certain number of old archives and deletes the others.
|
a certain number of old archives and deletes the others.
|
||||||
|
|
||||||
Finally, it uses the :ref:`borg_compact` subcommand to remove deleted objects
|
Finally, it uses the :ref:`borg_compact` subcommand to remove deleted objects
|
||||||
from the segment files in the repository to free disk space.
|
from the segment files in the repository to free disk space.
|
||||||
|
@ -152,8 +151,8 @@ by the root user, but not executable or readable by anyone else, i.e. root:root
|
||||||
You can use this script as a starting point and modify it where it's necessary to fit
|
You can use this script as a starting point and modify it where it's necessary to fit
|
||||||
your setup.
|
your setup.
|
||||||
|
|
||||||
Do not forget to test your created backups to make sure everything you need is being
|
Do not forget to test your created backups to make sure everything you need is
|
||||||
backed up and that the ``prune`` command is keeping and deleting the correct backups.
|
backed up and that the ``prune`` command keeps and deletes the correct backups.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
|
@ -236,7 +235,7 @@ Pitfalls with shell variables and environment variables
|
||||||
-------------------------------------------------------
|
-------------------------------------------------------
|
||||||
|
|
||||||
This applies to all environment variables you want Borg to see, not just
|
This applies to all environment variables you want Borg to see, not just
|
||||||
``BORG_PASSPHRASE``. The short explanation is: always ``export`` your variable,
|
``BORG_PASSPHRASE``. TL;DR: always ``export`` your variable,
|
||||||
and use single quotes if you're unsure of the details of your shell's expansion
|
and use single quotes if you're unsure of the details of your shell's expansion
|
||||||
behavior. E.g.::
|
behavior. E.g.::
|
||||||
|
|
||||||
|
@ -267,26 +266,27 @@ Passphrase notes
|
||||||
If you use encryption (or authentication), Borg will interactively ask you
|
If you use encryption (or authentication), Borg will interactively ask you
|
||||||
for a passphrase to encrypt/decrypt the keyfile / repokey.
|
for a passphrase to encrypt/decrypt the keyfile / repokey.
|
||||||
|
|
||||||
A passphrase should be a single line of text, a trailing linefeed will be
|
A passphrase should be a single line of text. Any trailing linefeed will be
|
||||||
stripped.
|
stripped.
|
||||||
|
|
||||||
For your own safety, you maybe want to avoid empty passphrases as well
|
Do not use empty passphrases, as these can be trivially guessed, which does not
|
||||||
extremely long passphrase (much more than 256 bits of entropy).
|
leave any encrypted data secure.
|
||||||
|
|
||||||
Also avoid passphrases containing non-ASCII characters.
|
Avoid passphrases containing non-ASCII characters.
|
||||||
Borg is technically able to process all unicode text, but you might get into
|
Borg can process any unicode text, but problems may arise at input due to text
|
||||||
trouble reproducing the same encoded utf-8 bytes or with keyboard layouts,
|
encoding or differing keyboard layouts, so best just avoid non-ASCII stuff.
|
||||||
so better just avoid non-ASCII stuff.
|
|
||||||
|
|
||||||
Alternatively, if you want to automate, you can supply the passphrase
|
See: https://xkcd.com/936/
|
||||||
directly or indirectly using some environment variables.
|
|
||||||
|
|
||||||
You can directly give a passphrase::
|
If you want to automate, you can supply the passphrase
|
||||||
|
directly or indirectly with the use of environment variables.
|
||||||
|
|
||||||
|
Supply a passphrase directly::
|
||||||
|
|
||||||
# use this passphrase (use safe permissions on the script!):
|
# use this passphrase (use safe permissions on the script!):
|
||||||
export BORG_PASSPHRASE='my super secret passphrase'
|
export BORG_PASSPHRASE='my super secret passphrase'
|
||||||
|
|
||||||
Or ask an external program to supply the passphrase::
|
Or delegate to an external program to supply the passphrase::
|
||||||
|
|
||||||
# use the "pass" password manager to get the passphrase:
|
# use the "pass" password manager to get the passphrase:
|
||||||
export BORG_PASSCOMMAND='pass show backup'
|
export BORG_PASSCOMMAND='pass show backup'
|
||||||
|
@ -424,22 +424,23 @@ be acceptable for backup usage.
|
||||||
Restoring a backup
|
Restoring a backup
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
Please note that we are only describing the most basic commands and options
|
Please note that we describe only the most basic commands and options
|
||||||
here - please refer to the command reference to see more.
|
here. Refer to the command reference to see more.
|
||||||
|
|
||||||
For restoring, you usually want to work **on the same machine as the same user**
|
To restore, work **on the same machine as the same user**
|
||||||
that was also used to create the backups of the wanted files. Doing it like
|
that was used to create the backups of the wanted files. Doing so
|
||||||
that avoids quite some issues:
|
avoids issues such as:
|
||||||
|
|
||||||
- no confusion relating to paths
|
- confusion relating to paths
|
||||||
- same mapping of user/group names to user/group IDs
|
- mapping of user/group names to user/group IDs
|
||||||
- no permission issues
|
- permissions
|
||||||
- you likely already have a working borg setup there,
|
|
||||||
|
|
||||||
- maybe including a environment variable for the key passphrase (for encrypted repos),
|
You likely already have a working borg setup there, including perhaps:
|
||||||
- maybe including a keyfile for the repo (not needed for repokey mode),
|
|
||||||
- maybe including a ssh key for the repo server (not needed for locally mounted repos),
|
- an environment variable for the key passphrase (for encrypted repos),
|
||||||
- maybe including a valid borg cache for that repo (quicker than cache rebuild).
|
- a keyfile for the repo (not needed for repokey mode),
|
||||||
|
- a ssh key for the repo server (not needed for locally mounted repos),
|
||||||
|
- a valid borg cache for that repo (quicker than cache rebuild).
|
||||||
|
|
||||||
The **user** might be:
|
The **user** might be:
|
||||||
|
|
||||||
|
@ -461,12 +462,12 @@ The **key** can be located:
|
||||||
- in the repository (**repokey** mode).
|
- in the repository (**repokey** mode).
|
||||||
|
|
||||||
Easy, this will usually "just work".
|
Easy, this will usually "just work".
|
||||||
- in the home directory of the user who did the backup (**keyfile** mode).
|
- in the home directory of the user who made the backup (**keyfile** mode).
|
||||||
|
|
||||||
This may cause a bit more effort:
|
This may cause a bit more effort:
|
||||||
|
|
||||||
- if you have just lost that home directory and you first need to restore the
|
- if you have just lost that home directory and you first need to restore the
|
||||||
borg key (e.g. from the separate backup you have made of it or from another
|
borg key (e.g. from the separate backup you made of it or from another
|
||||||
user or machine accessing the same repository).
|
user or machine accessing the same repository).
|
||||||
- if you first must find out the correct machine / user / home directory
|
- if you first must find out the correct machine / user / home directory
|
||||||
(where the borg client was run to make the backups).
|
(where the borg client was run to make the backups).
|
||||||
|
@ -483,19 +484,19 @@ There are **2 ways to restore** files from a borg backup repository:
|
||||||
|
|
||||||
- **borg mount** - use this if:
|
- **borg mount** - use this if:
|
||||||
|
|
||||||
- you don't precisely know what files you want to restore
|
- you don't know exactly which files you want to restore
|
||||||
- you don't know which archive contains the files (in the state) you want
|
- you don't know which archive contains the files (in the state) you want
|
||||||
- you need to look into files / directories before deciding what you want
|
- you need to look into files / directories before deciding what you want
|
||||||
- you need a relatively low volume of data restored
|
- you need a relatively low volume of data restored
|
||||||
- you don't care for restoring stuff that the FUSE mount is not implementing yet
|
- you don't care for restoring stuff that FUSE mount does not implement yet
|
||||||
(like special fs flags, ACLs)
|
(like special fs flags, ACLs)
|
||||||
- you have a client with good resources (RAM, CPU, temp. disk space)
|
- you have a client with good resources (RAM, CPU, temporary disk space)
|
||||||
- you want to rather use some filemanager to restore (copy) files than borg
|
- you would rather use some filemanager to restore (copy) files than borg
|
||||||
extract shell commands
|
extract shell commands
|
||||||
|
|
||||||
- **borg extract** - use this if:
|
- **borg extract** - use this if:
|
||||||
|
|
||||||
- you precisely know what you want (repo, archive, path)
|
- you know precisely what you want (repo, archive, path)
|
||||||
- you need a high volume of files restored (best speed)
|
- you need a high volume of files restored (best speed)
|
||||||
- you want a as-complete-as-it-gets reproduction of file metadata
|
- you want a as-complete-as-it-gets reproduction of file metadata
|
||||||
(like special fs flags, ACLs)
|
(like special fs flags, ACLs)
|
||||||
|
|
Loading…
Reference in New Issue