mirror of https://github.com/borgbackup/borg.git
docs: use /path/to/repo, fixes #901
/mnt/backup was confusing as people like to mount their backup disk on /mnt/backup, but borg init /mnt/backup does not work if that directory already exists because it is the mountpoint. it would work, if /mnt was the mountpoint, but that is not obvious and also unusual.
This commit is contained in:
Thomas Waldmann
parent
68e870795d
commit
bc854e3e64
|
|
@ -84,12 +84,12 @@ Easy to use
|
|||
|
||||
Initialize a new backup repository and create a backup archive::
|
||||
|
||||
$ borg init /mnt/backup
|
||||
$ borg create /mnt/backup::Saturday1 ~/Documents
|
||||
$ borg init /path/to/repo
|
||||
$ borg create /path/to/repo::Saturday1 ~/Documents
|
||||
|
||||
Now doing another backup, just to show off the great deduplication::
|
||||
|
||||
$ borg create -v --stats /mnt/backup::Saturday2 ~/Documents
|
||||
$ borg create -v --stats /path/to/repo::Saturday2 ~/Documents
|
||||
-----------------------------------------------------------------------------
|
||||
Archive name: Saturday2
|
||||
Archive fingerprint: 622b7c53c...
|
||||
|
|
|
|||
|
|
@ -37,16 +37,16 @@ A step by step example
|
|||
|
||||
1. Before a backup can be made a repository has to be initialized::
|
||||
|
||||
$ borg init /mnt/backup
|
||||
$ borg init /path/to/repo
|
||||
|
||||
2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
|
||||
*Monday*::
|
||||
|
||||
$ borg create /mnt/backup::Monday ~/src ~/Documents
|
||||
$ borg create /path/to/repo::Monday ~/src ~/Documents
|
||||
|
||||
3. The next day create a new archive called *Tuesday*::
|
||||
|
||||
$ borg create -v --stats /mnt/backup::Tuesday ~/src ~/Documents
|
||||
$ borg create -v --stats /path/to/repo::Tuesday ~/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 |project_name| to
|
||||
|
|
@ -72,24 +72,24 @@ A step by step example
|
|||
|
||||
4. List all archives in the repository::
|
||||
|
||||
$ borg list /mnt/backup
|
||||
$ borg list /path/to/repo
|
||||
Monday Mon, 2016-02-15 19:14:44
|
||||
Tuesday Tue, 2016-02-16 19:15:11
|
||||
|
||||
5. List the contents of the *Monday* archive::
|
||||
|
||||
$ borg list /mnt/backup::Monday
|
||||
$ borg list /path/to/repo::Monday
|
||||
drwxr-xr-x user group 0 Mon, 2016-02-15 18:22:30 home/user/Documents
|
||||
-rw-r--r-- user group 7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
|
||||
...
|
||||
|
||||
6. Restore the *Monday* archive::
|
||||
|
||||
$ borg extract /mnt/backup::Monday
|
||||
$ borg extract /path/to/repo::Monday
|
||||
|
||||
7. Recover disk space by manually deleting the *Monday* archive::
|
||||
|
||||
$ borg delete /mnt/backup::Monday
|
||||
$ borg delete /path/to/repo::Monday
|
||||
|
||||
.. Note::
|
||||
Borg is quiet by default (it works on WARNING log level).
|
||||
|
|
@ -134,17 +134,17 @@ or high compression:
|
|||
|
||||
If you have a fast repo storage and you want some compression: ::
|
||||
|
||||
$ borg create --compression lz4 /mnt/backup::repo ~
|
||||
$ borg create --compression lz4 /path/to/repo::repo ~
|
||||
|
||||
If you have a less fast repo storage and you want a bit more compression (N=0..9,
|
||||
0 means no compression, 9 means high compression): ::
|
||||
|
||||
$ borg create --compression zlib,N /mnt/backup::repo ~
|
||||
$ borg create --compression zlib,N /path/to/repo::repo ~
|
||||
|
||||
If you have a very slow repo storage and you want high compression (N=0..9, 0 means
|
||||
low compression, 9 means high compression): ::
|
||||
|
||||
$ borg create --compression lzma,N /mnt/backup::repo ~
|
||||
$ borg create --compression lzma,N /path/to/repo::repo ~
|
||||
|
||||
You'll need to experiment a bit to find the best compression for your use case.
|
||||
Keep an eye on CPU load and throughput.
|
||||
|
|
@ -208,23 +208,23 @@ Remote repositories
|
|||
host is accessible using SSH. This is fastest and easiest when |project_name|
|
||||
is installed on the remote host, in which case the following syntax is used::
|
||||
|
||||
$ borg init user@hostname:/mnt/backup
|
||||
$ borg init user@hostname:/path/to/repo
|
||||
|
||||
or::
|
||||
|
||||
$ borg init ssh://user@hostname:port//mnt/backup
|
||||
$ borg init ssh://user@hostname:port//path/to/repo
|
||||
|
||||
Remote operations over SSH can be automated with SSH keys. You can restrict the
|
||||
use of the SSH keypair by prepending a forced command to the SSH public key in
|
||||
the remote server's `authorized_keys` file. This example will start |project_name|
|
||||
in server mode and limit it to a specific filesystem path::
|
||||
|
||||
command="borg serve --restrict-to-path /mnt/backup",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
|
||||
command="borg serve --restrict-to-path /path/to/repo",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
|
||||
|
||||
If it is not possible to install |project_name| on the remote host,
|
||||
it is still possible to use the remote host to store a repository by
|
||||
mounting the remote filesystem, for example, using sshfs::
|
||||
|
||||
$ sshfs user@hostname:/mnt /mnt
|
||||
$ borg init /mnt/backup
|
||||
$ fusermount -u /mnt
|
||||
$ sshfs user@hostname:/path/to /path/to
|
||||
$ borg init /path/to/repo
|
||||
$ fusermount -u /path/to
|
||||
|
|
|
|||
100
docs/usage.rst
100
docs/usage.rst
|
|
@ -199,10 +199,10 @@ Examples
|
|||
::
|
||||
|
||||
# Local repository (default is to use encryption in repokey mode)
|
||||
$ borg init /mnt/backup
|
||||
$ borg init /path/to/repo
|
||||
|
||||
# Local repository (no encryption)
|
||||
$ borg init --encryption=none /mnt/backup
|
||||
$ borg init --encryption=none /path/to/repo
|
||||
|
||||
# Remote repository (accesses a remote borg via ssh)
|
||||
$ borg init user@hostname:backup
|
||||
|
|
@ -257,54 +257,54 @@ Examples
|
|||
::
|
||||
|
||||
# Backup ~/Documents into an archive named "my-documents"
|
||||
$ borg create /mnt/backup::my-documents ~/Documents
|
||||
$ borg create /path/to/repo::my-documents ~/Documents
|
||||
|
||||
# same, but verbosely list all files as we process them
|
||||
$ borg create -v --list /mnt/backup::my-documents ~/Documents
|
||||
$ borg create -v --list /path/to/repo::my-documents ~/Documents
|
||||
|
||||
# Backup ~/Documents and ~/src but exclude pyc files
|
||||
$ borg create /mnt/backup::my-files \
|
||||
$ borg create /path/to/repo::my-files \
|
||||
~/Documents \
|
||||
~/src \
|
||||
--exclude '*.pyc'
|
||||
|
||||
# Backup home directories excluding image thumbnails (i.e. only
|
||||
# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails)
|
||||
$ borg create /mnt/backup::my-files /home \
|
||||
$ borg create /path/to/repo::my-files /home \
|
||||
--exclude 're:^/home/[^/]+/\.thumbnails/'
|
||||
|
||||
# Do the same using a shell-style pattern
|
||||
$ borg create /mnt/backup::my-files /home \
|
||||
$ borg create /path/to/repo::my-files /home \
|
||||
--exclude 'sh:/home/*/.thumbnails'
|
||||
|
||||
# Backup the root filesystem into an archive named "root-YYYY-MM-DD"
|
||||
# use zlib compression (good, but slow) - default is no compression
|
||||
$ borg create -C zlib,6 /mnt/backup::root-{now:%Y-%m-%d} / --one-file-system
|
||||
$ borg create -C zlib,6 /path/to/repo::root-{now:%Y-%m-%d} / --one-file-system
|
||||
|
||||
# Make a big effort in fine granular deduplication (big chunk management
|
||||
# overhead, needs a lot of RAM and disk space, see formula in internals
|
||||
# docs - same parameters as borg < 1.0 or attic):
|
||||
$ borg create --chunker-params 10,23,16,4095 /mnt/backup::small /smallstuff
|
||||
$ borg create --chunker-params 10,23,16,4095 /path/to/repo::small /smallstuff
|
||||
|
||||
# Backup a raw device (must not be active/in use/mounted at that time)
|
||||
$ dd if=/dev/sdx bs=10M | borg create /mnt/backup::my-sdx -
|
||||
$ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my-sdx -
|
||||
|
||||
# No compression (default)
|
||||
$ borg create /mnt/backup::repo ~
|
||||
$ borg create /path/to/repo::repo ~
|
||||
|
||||
# Super fast, low compression
|
||||
$ borg create --compression lz4 /mnt/backup::repo ~
|
||||
$ borg create --compression lz4 /path/to/repo::repo ~
|
||||
|
||||
# Less fast, higher compression (N = 0..9)
|
||||
$ borg create --compression zlib,N /mnt/backup::repo ~
|
||||
$ borg create --compression zlib,N /path/to/repo::repo ~
|
||||
|
||||
# Even slower, even higher compression (N = 0..9)
|
||||
$ borg create --compression lzma,N /mnt/backup::repo ~
|
||||
$ borg create --compression lzma,N /path/to/repo::repo ~
|
||||
|
||||
# Format tags available for archive name:
|
||||
# {now}, {utcnow}, {fqdn}, {hostname}, {user}, {pid}
|
||||
# add short hostname, backup username and current unixtime (seconds from epoch)
|
||||
$ borg create /mnt/backup::{hostname}-{user}-{now:%s} ~
|
||||
$ borg create /path/to/repo::{hostname}-{user}-{now:%s} ~
|
||||
|
||||
.. include:: usage/extract.rst.inc
|
||||
|
||||
|
|
@ -313,19 +313,19 @@ Examples
|
|||
::
|
||||
|
||||
# Extract entire archive
|
||||
$ borg extract /mnt/backup::my-files
|
||||
$ borg extract /path/to/repo::my-files
|
||||
|
||||
# Extract entire archive and list files while processing
|
||||
$ borg extract -v --list /mnt/backup::my-files
|
||||
$ borg extract -v --list /path/to/repo::my-files
|
||||
|
||||
# Extract the "src" directory
|
||||
$ borg extract /mnt/backup::my-files home/USERNAME/src
|
||||
$ borg extract /path/to/repo::my-files home/USERNAME/src
|
||||
|
||||
# Extract the "src" directory but exclude object files
|
||||
$ borg extract /mnt/backup::my-files home/USERNAME/src --exclude '*.o'
|
||||
$ borg extract /path/to/repo::my-files home/USERNAME/src --exclude '*.o'
|
||||
|
||||
# Restore a raw device (must not be active/in use/mounted at that time)
|
||||
$ borg extract --stdout /mnt/backup::my-sdx | dd of=/dev/sdx bs=10M
|
||||
$ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M
|
||||
|
||||
Note: currently, extract always writes into the current working directory ("."),
|
||||
so make sure you ``cd`` to the right place before calling ``borg extract``.
|
||||
|
|
@ -338,12 +338,12 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
$ borg create /mnt/backup::archivename ~
|
||||
$ borg list /mnt/backup
|
||||
$ borg create /path/to/repo::archivename ~
|
||||
$ borg list /path/to/repo
|
||||
archivename Mon, 2016-02-15 19:50:19
|
||||
|
||||
$ borg rename /mnt/backup::archivename newname
|
||||
$ borg list /mnt/backup
|
||||
$ borg rename /path/to/repo::archivename newname
|
||||
$ borg list /path/to/repo
|
||||
newname Mon, 2016-02-15 19:50:19
|
||||
|
||||
|
||||
|
|
@ -353,14 +353,14 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
$ borg list /mnt/backup
|
||||
$ borg list /path/to/repo
|
||||
Monday Mon, 2016-02-15 19:15:11
|
||||
repo Mon, 2016-02-15 19:26:54
|
||||
root-2016-02-15 Mon, 2016-02-15 19:36:29
|
||||
newname Mon, 2016-02-15 19:50:19
|
||||
...
|
||||
|
||||
$ borg list /mnt/backup::root-2016-02-15
|
||||
$ borg list /path/to/repo::root-2016-02-15
|
||||
drwxr-xr-x root root 0 Mon, 2016-02-15 17:44:27 .
|
||||
drwxrwxr-x root root 0 Mon, 2016-02-15 19:04:49 bin
|
||||
-rwxr-xr-x root root 1029624 Thu, 2014-11-13 00:08:51 bin/bash
|
||||
|
|
@ -368,7 +368,7 @@ Examples
|
|||
-rwxr-xr-x root root 2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
|
||||
...
|
||||
|
||||
$ borg list /mnt/backup::archiveA --list-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
|
||||
$ borg list /path/to/repo::archiveA --list-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
|
||||
drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 .
|
||||
drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code
|
||||
drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code/myproject
|
||||
|
|
@ -376,8 +376,8 @@ Examples
|
|||
...
|
||||
|
||||
# see what is changed between archives, based on file modification time, size and file path
|
||||
$ borg list /mnt/backup::archiveA --list-format="{mtime:%s}{TAB}{size}{TAB}{path}{LF}" |sort -n > /tmp/list.archiveA
|
||||
$ borg list /mnt/backup::archiveB --list-format="{mtime:%s}{TAB}{size}{TAB}{path}{LF}" |sort -n > /tmp/list.archiveB
|
||||
$ borg list /path/to/repo::archiveA --list-format="{mtime:%s}{TAB}{size}{TAB}{path}{LF}" |sort -n > /tmp/list.archiveA
|
||||
$ borg list /path/to/repo::archiveB --list-format="{mtime:%s}{TAB}{size}{TAB}{path}{LF}" |sort -n > /tmp/list.archiveB
|
||||
$ diff -y /tmp/list.archiveA /tmp/list.archiveB
|
||||
1422781200 0 . 1422781200 0 .
|
||||
1422781200 0 code 1422781200 0 code
|
||||
|
|
@ -393,10 +393,10 @@ Examples
|
|||
::
|
||||
|
||||
# delete a single backup archive:
|
||||
$ borg delete /mnt/backup::Monday
|
||||
$ borg delete /path/to/repo::Monday
|
||||
|
||||
# delete the whole repository and the related local cache:
|
||||
$ borg delete /mnt/backup
|
||||
$ borg delete /path/to/repo
|
||||
You requested to completely DELETE the repository *including* all archives it contains:
|
||||
repo Mon, 2016-02-15 19:26:54
|
||||
root-2016-02-15 Mon, 2016-02-15 19:36:29
|
||||
|
|
@ -424,18 +424,18 @@ will see what it would do without it actually doing anything.
|
|||
|
||||
# Keep 7 end of day and 4 additional end of week archives.
|
||||
# Do a dry-run without actually deleting anything.
|
||||
$ borg prune --dry-run --keep-daily=7 --keep-weekly=4 /mnt/backup
|
||||
$ borg prune --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
|
||||
|
||||
# Same as above but only apply to archive names starting with "foo":
|
||||
$ borg prune --keep-daily=7 --keep-weekly=4 --prefix=foo /mnt/backup
|
||||
$ borg prune --keep-daily=7 --keep-weekly=4 --prefix=foo /path/to/repo
|
||||
|
||||
# Keep 7 end of day, 4 additional end of week archives,
|
||||
# and an end of month archive for every month:
|
||||
$ borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /mnt/backup
|
||||
$ borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
|
||||
|
||||
# Keep all backups in the last 10 days, 4 additional end of week archives,
|
||||
# and an end of month archive for every month:
|
||||
$ borg prune --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /mnt/backup
|
||||
$ borg prune --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
|
||||
|
||||
|
||||
.. include:: usage/info.rst.inc
|
||||
|
|
@ -444,14 +444,14 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
$ borg info /mnt/backup::root-2016-02-15
|
||||
$ borg info /path/to/repo::root-2016-02-15
|
||||
Name: root-2016-02-15
|
||||
Fingerprint: 57c827621f21b000a8d363c1e163cc55983822b3afff3a96df595077a660be50
|
||||
Hostname: myhostname
|
||||
Username: root
|
||||
Time (start): Mon, 2016-02-15 19:36:29
|
||||
Time (end): Mon, 2016-02-15 19:39:26
|
||||
Command line: /usr/local/bin/borg create -v --list -C zlib,6 /mnt/backup::root-2016-02-15 / --one-file-system
|
||||
Command line: /usr/local/bin/borg create -v --list -C zlib,6 /path/to/repo::root-2016-02-15 / --one-file-system
|
||||
Number of files: 38100
|
||||
|
||||
Original size Compressed size Deduplicated size
|
||||
|
|
@ -468,7 +468,7 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
$ borg mount /mnt/backup::root-2016-02-15 /tmp/mymountpoint
|
||||
$ borg mount /path/to/repo::root-2016-02-15 /tmp/mymountpoint
|
||||
$ ls /tmp/mymountpoint
|
||||
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
|
||||
$ fusermount -u /tmp/mymountpoint
|
||||
|
|
@ -481,8 +481,8 @@ Examples
|
|||
::
|
||||
|
||||
# Create a key file protected repository
|
||||
$ borg init --encryption=keyfile -v /mnt/backup
|
||||
Initializing repository at "/mnt/backup"
|
||||
$ borg init --encryption=keyfile -v /path/to/repo
|
||||
Initializing repository at "/path/to/repo"
|
||||
Enter new passphrase:
|
||||
Enter same passphrase again:
|
||||
Remember your passphrase. Your data will be inaccessible without it.
|
||||
|
|
@ -493,7 +493,7 @@ Examples
|
|||
Done.
|
||||
|
||||
# Change key file passphrase
|
||||
$ borg change-passphrase -v /mnt/backup
|
||||
$ borg change-passphrase -v /path/to/repo
|
||||
Enter passphrase for key /root/.config/borg/keys/mnt_backup:
|
||||
Enter new passphrase:
|
||||
Enter same passphrase again:
|
||||
|
|
@ -516,11 +516,11 @@ forced command. That way, other options given by the client (like ``--info`` or
|
|||
|
||||
::
|
||||
|
||||
# Allow an SSH keypair to only run borg, and only have access to /mnt/backup.
|
||||
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
|
||||
# Use key options to disable unneeded and potentially dangerous SSH functionality.
|
||||
# This will help to secure an automated remote backup system.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
command="borg serve --restrict-to-path /mnt/backup",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
|
||||
command="borg serve --restrict-to-path /path/to/repo",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
|
||||
|
||||
|
||||
.. include:: usage/upgrade.rst.inc
|
||||
|
|
@ -530,11 +530,11 @@ Examples
|
|||
::
|
||||
|
||||
# Upgrade the borg repository to the most recent version.
|
||||
$ borg upgrade -v /mnt/backup
|
||||
making a hardlink copy in /mnt/backup.upgrade-2016-02-15-20:51:55
|
||||
$ borg upgrade -v /path/to/repo
|
||||
making a hardlink copy in /path/to/repo.upgrade-2016-02-15-20:51:55
|
||||
opening attic repository with borg and converting
|
||||
no key file found for repository
|
||||
converting repo index /mnt/backup/index.0
|
||||
converting repo index /path/to/repo/index.0
|
||||
converting 1 segments...
|
||||
converting borg 0.xx to borg current
|
||||
no key file found for repository
|
||||
|
|
@ -696,16 +696,16 @@ After the backup has completed, you remove the snapshots again. ::
|
|||
|
||||
$ # create snapshots here
|
||||
$ lvdisplay > lvdisplay.txt
|
||||
$ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot
|
||||
$ borg create --read-special /path/to/repo::repo lvdisplay.txt /dev/vg0/*-snapshot
|
||||
$ # remove snapshots here
|
||||
|
||||
Now, let's see how to restore some LVs from such a backup. ::
|
||||
|
||||
$ borg extract /mnt/backup::repo lvdisplay.txt
|
||||
$ borg extract /path/to/repo::repo lvdisplay.txt
|
||||
$ # create empty LVs with correct sizes here (look into lvdisplay.txt).
|
||||
$ # we assume that you created an empty root and home LV and overwrite it now:
|
||||
$ borg extract --stdout /mnt/backup::repo dev/vg0/root-snapshot > /dev/vg0/root
|
||||
$ borg extract --stdout /mnt/backup::repo dev/vg0/home-snapshot > /dev/vg0/home
|
||||
$ borg extract --stdout /path/to/repo::repo dev/vg0/root-snapshot > /dev/vg0/root
|
||||
$ borg extract --stdout /path/to/repo::repo dev/vg0/home-snapshot > /dev/vg0/home
|
||||
|
||||
|
||||
Append-only mode
|
||||
|
|
|
|||
Loading…
Reference in New Issue