mirror of https://github.com/borgbackup/borg.git
build_usage
This commit is contained in:
Thomas Waldmann
parent
95d10b84c4
commit
17220e09ab
|
|
@ -11,17 +11,27 @@ currently active recursion root. You usually give the recursion root(s)
|
|||
when invoking borg and these can be either relative or absolute paths.
|
||||
|
||||
So, when you give `relative/` as root, the paths going into the matcher
|
||||
will look like `relative/.../file.ext`. When you give `/absolute/` as root,
|
||||
they will look like `/absolute/.../file.ext`. This is meant when we talk
|
||||
about "full path" below.
|
||||
will look like `relative/.../file.ext`. When you give `/absolute/` as
|
||||
root, they will look like `/absolute/.../file.ext`.
|
||||
|
||||
File paths in Borg archives are always stored normalized and relative.
|
||||
This means that e.g. ``borg create /path/to/repo ../some/path`` will
|
||||
store all files as `some/path/.../file.ext` and ``borg create
|
||||
/path/to/repo /home/user`` will store all files as
|
||||
`home/user/.../file.ext`.
|
||||
|
||||
File patterns support these styles: fnmatch, shell, regular expressions,
|
||||
path prefixes and path full-matches. By default, fnmatch is used for
|
||||
``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
|
||||
option.
|
||||
``--exclude`` patterns and shell-style is used for the experimental
|
||||
``--pattern`` option.
|
||||
|
||||
If followed by a colon (':') the first two characters of a pattern are used as a
|
||||
style selector. Explicit style selection is necessary when a
|
||||
Starting with Borg 1.2, for all but regular expression pattern matching
|
||||
styles, all paths are treated as relative, meaning that a leading path
|
||||
separator is removed after normalizing and before matching. This allows
|
||||
you to use absolute or relative patterns arbitrarily.
|
||||
|
||||
If followed by a colon (':') the first two characters of a pattern are
|
||||
used as a style selector. Explicit style selection is necessary when a
|
||||
non-default style is desired or when the desired pattern starts with
|
||||
two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
|
||||
|
||||
|
|
@ -38,14 +48,15 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
|
|||
from the start of the full path to just before a path separator. Except
|
||||
for the root path, paths will never end in the path separator when
|
||||
matching is attempted. Thus, if a given pattern ends in a path
|
||||
separator, a '\*' is appended before matching is attempted.
|
||||
separator, a '\*' is appended before matching is attempted. A leading
|
||||
path separator is always removed.
|
||||
|
||||
Shell-style patterns, selector `sh:`
|
||||
This is the default style for ``--pattern`` and ``--patterns-from``.
|
||||
Like fnmatch patterns these are similar to shell patterns. The difference
|
||||
is that the pattern may include `**/` for matching zero or more directory
|
||||
levels, `*` for matching zero or more arbitrary characters with the
|
||||
exception of any path separator.
|
||||
exception of any path separator. A leading path separator is always removed.
|
||||
|
||||
Regular expressions, selector `re:`
|
||||
Regular expressions similar to those found in Perl are supported. Unlike
|
||||
|
|
@ -59,13 +70,14 @@ Regular expressions, selector `re:`
|
|||
|
||||
Path prefix, selector `pp:`
|
||||
This pattern style is useful to match whole sub-directories. The pattern
|
||||
`pp:root/somedir` matches `root/somedir` and everything therein.
|
||||
`pp:root/somedir` matches `root/somedir` and everything therein. A leading
|
||||
path separator is always removed.
|
||||
|
||||
Path full-match, selector `pf:`
|
||||
This pattern style is (only) useful to match full paths.
|
||||
This is kind of a pseudo pattern as it can not have any variable or
|
||||
unspecified parts - the full path must be given.
|
||||
`pf:root/file.ext` matches `root/file.txt` only.
|
||||
unspecified parts - the full path must be given. `pf:root/file.ext` matches
|
||||
`root/file.txt` only. A leading path separator is always removed.
|
||||
|
||||
Implementation note: this is implemented via very time-efficient O(1)
|
||||
hashtable lookups (this means you can have huge amounts of such patterns
|
||||
|
|
@ -109,7 +121,7 @@ Examples::
|
|||
$ borg create -e '/home/*/junk' backup /
|
||||
|
||||
# Exclude the contents of '/home/user/cache' but not the directory itself:
|
||||
$ borg create -e /home/user/cache/ backup /
|
||||
$ borg create -e home/user/cache/ backup /
|
||||
|
||||
# The file '/home/user/cache/important' is *not* backed up:
|
||||
$ borg create -e /home/user/cache/ backup / /home/user/cache/important
|
||||
|
|
@ -124,8 +136,8 @@ Examples::
|
|||
/home/*/junk
|
||||
*.tmp
|
||||
fm:aa:something/*
|
||||
re:^/home/[^/]\.tmp/
|
||||
sh:/home/*/.thumbnails
|
||||
re:^home/[^/]\.tmp/
|
||||
sh:home/*/.thumbnails
|
||||
EOF
|
||||
$ borg create --exclude-from exclude.txt backup /
|
||||
|
||||
|
|
|
|||
|
|
@ -67,7 +67,11 @@ Encryption can be enabled at repository init time. It cannot be changed later.
|
|||
It is not recommended to work without encryption. Repository encryption protects
|
||||
you e.g. against the case that an attacker has access to your backup repository.
|
||||
|
||||
But be careful with the key / the passphrase:
|
||||
Borg relies on randomly generated key material and uses that for chunking, id
|
||||
generation, encryption and authentication. The key material is encrypted using
|
||||
the passphrase you give before it is stored on-disk.
|
||||
|
||||
You need to be careful with the key / the passphrase:
|
||||
|
||||
If you want "passphrase-only" security, use one of the repokey modes. The
|
||||
key will be stored inside the repository (in its "config" file). In above
|
||||
|
|
@ -105,6 +109,12 @@ the encryption/decryption key or other secrets.
|
|||
Encryption modes
|
||||
++++++++++++++++
|
||||
|
||||
You can choose from the encryption modes seen in the table below on a per-repo
|
||||
basis. The mode determines encryption algorithm, hash/MAC algorithm and also the
|
||||
key storage location.
|
||||
|
||||
Example: `borg init --encryption repokey ...`
|
||||
|
||||
.. nanorst: inline-fill
|
||||
|
||||
+----------+---------------+------------------------+--------------------------+
|
||||
|
|
@ -120,7 +130,8 @@ Encryption modes
|
|||
|
||||
.. nanorst: inline-replace
|
||||
|
||||
`Marked modes` are new in Borg 1.1 and are not backwards-compatible with Borg 1.0.x.
|
||||
Modes `marked like this` in the above table are new in Borg 1.1 and are not
|
||||
backwards-compatible with Borg 1.0.x.
|
||||
|
||||
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
|
||||
hardware-accelerated.
|
||||
|
|
@ -153,8 +164,8 @@ from the other blake2 modes.
|
|||
This mode is new and *not* compatible with Borg 1.0.x.
|
||||
|
||||
`none` mode uses no encryption and no authentication. It uses SHA256 as chunk
|
||||
ID hash. Not recommended, rather consider using an authenticated or
|
||||
authenticated/encrypted mode. This mode has possible denial-of-service issues
|
||||
ID hash. This mode is not recommended, you should rather consider using an authenticated
|
||||
or authenticated/encrypted mode. This mode has possible denial-of-service issues
|
||||
when running ``borg create`` on contents controlled by an attacker.
|
||||
Use it only for new repositories where no encryption is wanted **and** when compatibility
|
||||
with 1.0.x is important. If compatibility with 1.0.x is not important, use
|
||||
|
|
|
|||
Loading…
Reference in New Issue