|
|
@@ -99,40 +99,134 @@ borg help placeholders
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
- Repository (or Archive) URLs, --prefix and --remote-path values support these
|
|
|
- placeholders:
|
|
|
+Repository (or Archive) URLs, --prefix and --remote-path values support these
|
|
|
+placeholders:
|
|
|
|
|
|
- {hostname}
|
|
|
+{hostname}
|
|
|
|
|
|
- The (short) hostname of the machine.
|
|
|
+ The (short) hostname of the machine.
|
|
|
|
|
|
- {fqdn}
|
|
|
+{fqdn}
|
|
|
|
|
|
- The full name of the machine.
|
|
|
+ The full name of the machine.
|
|
|
|
|
|
- {now}
|
|
|
+{now}
|
|
|
|
|
|
- The current local date and time.
|
|
|
+ The current local date and time, by default in ISO-8601 format.
|
|
|
+ You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}
|
|
|
|
|
|
- {utcnow}
|
|
|
+{utcnow}
|
|
|
|
|
|
- The current UTC date and time.
|
|
|
+ The current UTC date and time, by default in ISO-8601 format.
|
|
|
+ You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}
|
|
|
|
|
|
- {user}
|
|
|
+{user}
|
|
|
|
|
|
- The user name (or UID, if no name is available) of the user running borg.
|
|
|
+ The user name (or UID, if no name is available) of the user running borg.
|
|
|
|
|
|
- {pid}
|
|
|
+{pid}
|
|
|
|
|
|
- The current process ID.
|
|
|
+ The current process ID.
|
|
|
|
|
|
- {borgversion}
|
|
|
+{borgversion}
|
|
|
|
|
|
- The version of borg.
|
|
|
+ The version of borg.
|
|
|
|
|
|
Examples::
|
|
|
|
|
|
- borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
|
|
|
- borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
|
|
|
- borg prune --prefix '{hostname}-' ...
|
|
|
+ borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
|
|
|
+ borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
|
|
|
+ borg prune --prefix '{hostname}-' ...
|
|
|
+
|
|
|
+.. _borg_compression:
|
|
|
+
|
|
|
+borg help compression
|
|
|
+~~~~~~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+
|
|
|
+Compression is off by default, if you want some, you have to specify what you want.
|
|
|
+
|
|
|
+Valid compression specifiers are:
|
|
|
+
|
|
|
+none
|
|
|
+
|
|
|
+ Do not compress. (default)
|
|
|
+
|
|
|
+lz4
|
|
|
+
|
|
|
+ Use lz4 compression. High speed, low compression.
|
|
|
+
|
|
|
+zlib[,L]
|
|
|
+
|
|
|
+ Use zlib ("gz") compression. Medium speed, medium compression.
|
|
|
+ If you do not explicitely give the compression level L (ranging from 0
|
|
|
+ to 9), it will use level 6.
|
|
|
+ Giving level 0 (means "no compression", but still has zlib protocol
|
|
|
+ overhead) is usually pointless, you better use "none" compression.
|
|
|
+
|
|
|
+lzma[,L]
|
|
|
+
|
|
|
+ Use lzma ("xz") compression. Low speed, high compression.
|
|
|
+ If you do not explicitely give the compression level L (ranging from 0
|
|
|
+ to 9), it will use level 6.
|
|
|
+ Giving levels above 6 is pointless and counterproductive because it does
|
|
|
+ not compress better due to the buffer size used by borg - but it wastes
|
|
|
+ lots of CPU cycles and RAM.
|
|
|
+
|
|
|
+auto,C[,L]
|
|
|
+
|
|
|
+ Use a built-in heuristic to decide per chunk whether to compress or not.
|
|
|
+ The heuristic tries with lz4 whether the data is compressible.
|
|
|
+ For incompressible data, it will not use compression (uses "none").
|
|
|
+ For compressible data, it uses the given C[,L] compression - with C[,L]
|
|
|
+ being any valid compression specifier.
|
|
|
+
|
|
|
+The decision about which compression to use is done by borg like this:
|
|
|
+
|
|
|
+1. find a compression specifier (per file):
|
|
|
+ match the path/filename against all patterns in all --compression-from
|
|
|
+ files (if any). If a pattern matches, use the compression spec given for
|
|
|
+ that pattern. If no pattern matches (and also if you do not give any
|
|
|
+ --compression-from option), default to the compression spec given by
|
|
|
+ --compression. See docs/misc/compression.conf for an example config.
|
|
|
+
|
|
|
+2. if the found compression spec is not "auto", the decision is taken:
|
|
|
+ use the found compression spec.
|
|
|
+
|
|
|
+3. if the found compression spec is "auto", test compressibility of each
|
|
|
+ chunk using lz4.
|
|
|
+ If it is compressible, use the C,[L] compression spec given within the
|
|
|
+ "auto" specifier. If it is not compressible, use no compression.
|
|
|
+
|
|
|
+Examples::
|
|
|
+
|
|
|
+ borg create --compression lz4 REPO::ARCHIVE data
|
|
|
+ borg create --compression zlib REPO::ARCHIVE data
|
|
|
+ borg create --compression zlib,1 REPO::ARCHIVE data
|
|
|
+ borg create --compression auto,lzma,6 REPO::ARCHIVE data
|
|
|
+ borg create --compression-from compression.conf --compression auto,lzma ...
|
|
|
+
|
|
|
+compression.conf has entries like::
|
|
|
+
|
|
|
+ # example config file for --compression-from option
|
|
|
+ #
|
|
|
+ # Format of non-comment / non-empty lines:
|
|
|
+ # <compression-spec>:<path/filename pattern>
|
|
|
+ # compression-spec is same format as for --compression option
|
|
|
+ # path/filename pattern is same format as for --exclude option
|
|
|
+ none:*.gz
|
|
|
+ none:*.zip
|
|
|
+ none:*.mp3
|
|
|
+ none:*.ogg
|
|
|
+
|
|
|
+General remarks:
|
|
|
+
|
|
|
+It is no problem to mix different compression methods in one repo,
|
|
|
+deduplication is done on the source data chunks (not on the compressed
|
|
|
+or encrypted data).
|
|
|
+
|
|
|
+If some specific chunk was once compressed and stored into the repo, creating
|
|
|
+another backup that also uses this chunk will not change the stored chunk.
|
|
|
+So if you use different compression specs for the backups, whichever stores a
|
|
|
+chunk first determines its compression. See also borg recreate.
|
|
|
|
Thomas Waldmann