diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 new file mode 100644 index 000000000..b5870e563 --- /dev/null +++ b/docs/man/borg-break-lock.1 @@ -0,0 +1,56 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-BREAK-LOCK 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg break\-lock REPOSITORY +.SH DESCRIPTION +.sp +This command breaks the repository and cache locks. +Please use carefully and only while no borg process (on any machine) is +trying to access the Cache or the Repository. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY +repository for which to break the locks +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1 new file mode 100644 index 000000000..fb32bfa20 --- /dev/null +++ b/docs/man/borg-change-passphrase.1 @@ -0,0 +1,52 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-change-passphrase \- Change repository key file passphrase +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg change\-passphrase REPOSITORY +.SH DESCRIPTION +.sp +The key files used for repository encryption are optionally passphrase +protected. This command can be used to change this passphrase. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.sp +REPOSITORY +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 new file mode 100644 index 000000000..6608887bc --- /dev/null +++ b/docs/man/borg-check.1 @@ -0,0 +1,148 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-CHECK 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-check \- Check repository consistency +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg check REPOSITORY_OR_ARCHIVE +.SH DESCRIPTION +.sp +The check command verifies the consistency of a repository and the corresponding archives. +.sp +First, the underlying repository data files are checked: +.INDENT 0.0 +.IP \(bu 2 +For all segments the segment magic (header) is checked +.IP \(bu 2 +For all objects stored in the segments, all metadata (e.g. crc and size) and +all data is read. The read data is checked by size and CRC. Bit rot and other +types of accidental damage can be detected this way. +.IP \(bu 2 +If we are in repair mode and a integrity error is detected for a segment, +we try to recover as many objects from the segment as possible. +.IP \(bu 2 +In repair mode, it makes sure that the index is consistent with the data +stored in the segments. +.IP \(bu 2 +If you use a remote repo server via ssh:, the repo check is executed on the +repo server without causing significant network traffic. +.IP \(bu 2 +The repository check can be skipped using the \-\-archives\-only option. +.UNINDENT +.sp +Second, the consistency and correctness of the archive metadata is verified: +.INDENT 0.0 +.IP \(bu 2 +Is the repo manifest present? If not, it is rebuilt from archive metadata +chunks (this requires reading and decrypting of all metadata and data). +.IP \(bu 2 +Check if archive metadata chunk is present. if not, remove archive from +manifest. +.IP \(bu 2 +For all files (items) in the archive, for all chunks referenced by these +files, check if chunk is present. +If a chunk is not present and we are in repair mode, replace it with a same\-size +replacement chunk of zeros. +If a previously lost chunk reappears (e.g. via a later backup) and we are in +repair mode, the all\-zero replacement chunk will be replaced by the correct chunk. +This requires reading of archive and file metadata, but not data. +.IP \(bu 2 +If we are in repair mode and we checked all the archives: delete orphaned +chunks from the repo. +.IP \(bu 2 +if you use a remote repo server via ssh:, the archive check is executed on +the client machine (because if encryption is enabled, the checks will require +decryption and this is always done client\-side, because key access will be +required). +.IP \(bu 2 +The archive checks can be time consuming, they can be skipped using the +\-\-repository\-only option. +.UNINDENT +.sp +The \-\-verify\-data option will perform a full integrity verification (as opposed to +checking the CRC32 of the segment) of data, which means reading the data from the +repository, decrypting and decompressing it. This is a cryptographic verification, +which will detect (accidental) corruption. For encrypted repositories it is +tamper\-resistant as well, unless the attacker has access to the keys. +.sp +It is also very slow. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY_OR_ARCHIVE +repository or archive to check consistency of +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-\-repository\-only +only perform repository checks +.TP +.B \-\-archives\-only +only perform archives checks +.TP +.B \-\-verify\-data +perform cryptographic archive data integrity verification (conflicts with \-\-repository\-only) +.TP +.B \-\-repair +attempt to repair any inconsistencies found +.TP +.B \-\-save\-space +work slower, but using less space +.TP +.B \-p\fP,\fB \-\-progress +show progress display while checking +.UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-sort\-by +Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 new file mode 100644 index 000000000..17afcff95 --- /dev/null +++ b/docs/man/borg-common.1 @@ -0,0 +1,87 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-COMMON 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-common \- Common options of Borg commands +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.INDENT 0.0 +.TP +.B \-h\fP,\fB \-\-help +show this help message and exit +.TP +.B \-\-critical +work on log level CRITICAL +.TP +.B \-\-error +work on log level ERROR +.TP +.B \-\-warning +work on log level WARNING (default) +.TP +.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose +work on log level INFO +.TP +.B \-\-debug +enable debug output, work on log level DEBUG +.TP +.BI \-\-debug\-topic \ TOPIC +enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. +.TP +.BI \-\-lock\-wait \ N +wait for the lock, but max. N seconds (default: 1). +.TP +.B \-\-show\-version +show/log the borg version +.TP +.B \-\-show\-rc +show/log the return code (rc) +.TP +.B \-\-no\-files\-cache +do not load/update the file metadata cache used to detect unchanged files +.TP +.BI \-\-umask \ M +set umask to M (local and remote, default: 0077) +.TP +.BI \-\-remote\-path \ PATH +set remote path to executable (default: "borg") +.TP +.BI \-\-remote\-ratelimit \ rate +set remote network upload rate limit in kiByte/s (default: 0=unlimited) +.TP +.B \-\-consider\-part\-files +treat part files like normal files (e.g. to list/extract them) +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 new file mode 100644 index 000000000..cc5fbafd7 --- /dev/null +++ b/docs/man/borg-compression.1 @@ -0,0 +1,156 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-COMPRESSION 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-compression \- Details regarding compression +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH DESCRIPTION +.sp +Compression is off by default, if you want some, you have to specify what you want. +.sp +Valid compression specifiers are: +.sp +none +.INDENT 0.0 +.INDENT 3.5 +Do not compress. (default) +.UNINDENT +.UNINDENT +.sp +lz4 +.INDENT 0.0 +.INDENT 3.5 +Use lz4 compression. High speed, low compression. +.UNINDENT +.UNINDENT +.sp +zlib[,L] +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.sp +lzma[,L] +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.sp +auto,C[,L] +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.sp +The decision about which compression to use is done by borg like this: +.INDENT 0.0 +.IP 1. 3 +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. +.IP 2. 3 +if the found compression spec is not "auto", the decision is taken: +use the found compression spec. +.IP 3. 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. +.UNINDENT +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +compression.conf has entries like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# example config file for \-\-compression\-from option +# +# Format of non\-comment / non\-empty lines: +# : +# 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 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +General remarks: +.sp +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). +.sp +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. +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 new file mode 100644 index 000000000..f3e3c9be0 --- /dev/null +++ b/docs/man/borg-create.1 @@ -0,0 +1,233 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-CREATE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-create \- Create new archive +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg create ARCHIVE PATH +.SH DESCRIPTION +.sp +This command creates a backup archive containing all files found while recursively +traversing all paths specified. When giving \(aq\-\(aq as path, borg will read data +from standard input and create a file \(aqstdin\(aq in the created archive from that +data. +.sp +The archive will consume almost no disk space for files or parts of files that +have already been stored in other archives. +.sp +The archive name needs to be unique. It must not end in \(aq.checkpoint\(aq or +\(aq.checkpoint.N\(aq (with N being a number), because these names are used for +checkpoints and treated in special ways. +.sp +In the archive name, you may use the following placeholders: +{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. +.sp +To speed up pulling backups over sshfs and similar network file systems which do +not provide correct inode information the \-\-ignore\-inode flag can be used. This +potentially decreases reliability of change detection, while avoiding always reading +all files on these file systems. +.sp +See the output of the "borg help patterns" command for more help on exclude patterns. +See the output of the "borg help placeholders" command for more help on placeholders. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B ARCHIVE +name of archive to create (must be also a valid directory name) +.TP +.B PATH +paths to archive +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-n\fP,\fB \-\-dry\-run +do not create a backup archive +.TP +.B \-s\fP,\fB \-\-stats +print statistics for the created archive +.TP +.B \-p\fP,\fB \-\-progress +show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False +.TP +.B \-\-list +output verbose list of items (files, dirs, ...) +.TP +.BI \-\-filter \ STATUSCHARS +only display items with the given status characters +.UNINDENT +.SS Exclusion options +.INDENT 0.0 +.TP +.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +exclude paths matching PATTERN +.TP +.BI \-\-exclude\-from \ EXCLUDEFILE +read exclude patterns from EXCLUDEFILE, one per line +.TP +.B \-\-exclude\-caches +exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP) +.TP +.BI \-\-exclude\-if\-present \ NAME +exclude directories that are tagged by containing a filesystem object with the given NAME +.TP +.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files +keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories +.UNINDENT +.SS Filesystem options +.INDENT 0.0 +.TP +.B \-x\fP,\fB \-\-one\-file\-system +stay in same file system, do not cross mount points +.TP +.B \-\-numeric\-owner +only store numeric user and group identifiers +.TP +.B \-\-noatime +do not store atime into archive +.TP +.B \-\-noctime +do not store ctime into archive +.TP +.B \-\-ignore\-inode +ignore inode data in the file metadata cache used to detect unchanged files. +.TP +.B \-\-read\-special +open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. +.UNINDENT +.SS Archive options +.INDENT 0.0 +.TP +.BI \-\-comment \ COMMENT +add a comment text to the archive +.TP +.BI \-\-timestamp \ TIMESTAMP +manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory. +.TP +.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS +write checkpoint every SECONDS seconds (Default: 1800) +.TP +.BI \-\-chunker\-params \ PARAMS +specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095 +.TP +.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION +select compression algorithm, see the output of the "borg help compression" command for details. +.TP +.BI \-\-compression\-from \ COMPRESSIONCONFIG +read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Backup ~/Documents into an archive named "my\-documents" +$ borg create /path/to/repo::my\-documents ~/Documents + +# same, but list all files as we process them +$ borg create \-\-list /path/to/repo::my\-documents ~/Documents + +# Backup ~/Documents and ~/src but exclude pyc files +$ borg create /path/to/repo::my\-files \e + ~/Documents \e + ~/src \e + \-\-exclude \(aq*.pyc\(aq + +# Backup home directories excluding image thumbnails (i.e. only +# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails) +$ borg create /path/to/repo::my\-files /home \e + \-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq + +# Do the same using a shell\-style pattern +$ borg create /path/to/repo::my\-files /home \e + \-\-exclude \(aqsh:/home/*/.thumbnails\(aq + +# 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 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system + +# Backup a remote host locally ("pull" style) using sshfs +$ mkdir sshfs\-mount +$ sshfs root@example.com:/ sshfs\-mount +$ cd sshfs\-mount +$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} . +$ cd .. +$ fusermount \-u sshfs\-mount + +# 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 /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 /path/to/repo::my\-sdx \- + +# No compression (default) +$ borg create /path/to/repo::arch ~ + +# Super fast, low compression +$ borg create \-\-compression lz4 /path/to/repo::arch ~ + +# Less fast, higher compression (N = 0..9) +$ borg create \-\-compression zlib,N /path/to/repo::arch ~ + +# Even slower, even higher compression (N = 0..9) +$ borg create \-\-compression lzma,N /path/to/repo::arch ~ + +# Use short hostname, user name and current time in archive name +$ borg create /path/to/repo::{hostname}\-{user}\-{now} ~ +# Similar, use the same datetime format as borg 1.1 will have as default +$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~ +# As above, but add nanoseconds +$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Notes +.INDENT 0.0 +.IP \(bu 2 +the \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will +exclude foo/.bundler/gems. In borg it will not, you need to use \-\-exclude +\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for +more information. +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 new file mode 100644 index 000000000..e3a73797a --- /dev/null +++ b/docs/man/borg-delete.1 @@ -0,0 +1,109 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-DELETE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-delete \- Delete an existing repository or archives +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg delete TARGET +.SH DESCRIPTION +.sp +This command deletes an archive from the repository or the complete repository. +Disk space is reclaimed accordingly. If you delete the complete repository, the +local cache for it (if any) is also deleted. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B TARGET +archive or repository to delete +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-p\fP,\fB \-\-progress +show progress display while deleting a single archive +.TP +.B \-s\fP,\fB \-\-stats +print statistics for the deleted archive +.TP +.B \-c\fP,\fB \-\-cache\-only +delete only the local cache for the given repository +.TP +.B \-\-force +force deletion of corrupted archives +.TP +.B \-\-save\-space +work slower, but using less space +.UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-sort\-by +Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# delete a single backup archive: +$ borg delete /path/to/repo::Monday + +# delete the whole repository and the related local cache: +$ 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 +newname Mon, 2016\-02\-15 19:50:19 +Type \(aqYES\(aq if you understand this and want to continue: YES +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 new file mode 100644 index 000000000..dc3d9be99 --- /dev/null +++ b/docs/man/borg-diff.1 @@ -0,0 +1,133 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-DIFF 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-diff \- Diff contents of two archives +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg diff REPO_ARCHIVE1 ARCHIVE2 PATH +.SH DESCRIPTION +.sp +This command finds differences (file contents, user/group/mode) between archives. +.sp +A repository location and an archive name must be specified for REPO_ARCHIVE1. +ARCHIVE2 is just another archive name in same repository (no repository location +allowed). +.sp +For archives created with Borg 1.1 or newer diff automatically detects whether +the archives are created with the same chunker params. If so, only chunk IDs +are compared, which is very fast. +.sp +For archives prior to Borg 1.1 chunk contents are compared by default. +If you did not create the archives with different chunker params, +pass \-\-same\-chunker\-params. +Note that the chunker params changed from Borg 0.xx to 1.0. +.sp +See the output of the "borg help patterns" command for more help on exclude patterns. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPO_ARCHIVE1 +repository location and ARCHIVE1 name +.TP +.B ARCHIVE2 +ARCHIVE2 name (no repository location allowed) +.TP +.B PATH +paths of items inside the archives to compare; patterns are supported +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +exclude paths matching PATTERN +.TP +.BI \-\-exclude\-from \ EXCLUDEFILE +read exclude patterns from EXCLUDEFILE, one per line +.TP +.B \-\-numeric\-owner +only consider numeric user and group identifiers +.TP +.B \-\-same\-chunker\-params +Override check of chunker parameters. +.TP +.B \-\-sort +Sort the output lines by file path. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ borg init \-e=none testrepo +$ mkdir testdir +$ cd testdir +$ echo asdf > file1 +$ dd if=/dev/urandom bs=1M count=4 > file2 +$ touch file3 +$ borg create ../testrepo::archive1 . + +$ chmod a+x file1 +$ echo "something" >> file2 +$ borg create ../testrepo::archive2 . + +$ rm file3 +$ touch file4 +$ borg create ../testrepo::archive3 . + +$ cd .. +$ borg diff testrepo::archive1 archive2 +[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1 + +135 B \-252 B file2 + +$ borg diff testrepo::archive2 archive3 +added 0 B file4 +removed 0 B file3 + +$ borg diff testrepo::archive1 archive3 +[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1 + +135 B \-252 B file2 +added 0 B file4 +removed 0 B file3 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 new file mode 100644 index 000000000..2770a5142 --- /dev/null +++ b/docs/man/borg-extract.1 @@ -0,0 +1,131 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-EXTRACT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-extract \- Extract archive contents +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg extract ARCHIVE PATH +.SH DESCRIPTION +.sp +This command extracts the contents of an archive. By default the entire +archive is extracted but a subset of files and directories can be selected +by passing a list of \fBPATHs\fP as arguments. The file selection can further +be restricted by using the \fB\-\-exclude\fP option. +.sp +See the output of the "borg help patterns" command for more help on exclude patterns. +.sp +By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the +output data: reading metadata and data chunks from the repo, checking the hash/hmac, +decrypting, decompressing. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B ARCHIVE +archive to extract +.TP +.B PATH +paths to extract; patterns are supported +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-p\fP,\fB \-\-progress +show progress while extracting (may be slower) +.TP +.B \-\-list +output verbose list of items (files, dirs, ...) +.TP +.B \-n\fP,\fB \-\-dry\-run +do not actually change any files +.TP +.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +exclude paths matching PATTERN +.TP +.BI \-\-exclude\-from \ EXCLUDEFILE +read exclude patterns from EXCLUDEFILE, one per line +.TP +.B \-\-numeric\-owner +only obey numeric user and group identifiers +.TP +.BI \-\-strip\-components \ NUMBER +Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. +.TP +.B \-\-stdout +write all extracted data to stdout +.TP +.B \-\-sparse +create holes in output sparse file from all\-zero chunks +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Extract entire archive +$ borg extract /path/to/repo::my\-files + +# Extract entire archive and list files while processing +$ borg extract \-\-list /path/to/repo::my\-files + +# Verify whether an archive could be successfully extracted, but do not write files to disk +$ borg extract \-\-dry\-run /path/to/repo::my\-files + +# Extract the "src" directory +$ borg extract /path/to/repo::my\-files home/USERNAME/src + +# Extract the "src" directory but exclude object files +$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq + +# Restore a raw device (must not be active/in use/mounted at that time) +$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Currently, extract always writes into the current working directory ("."), +so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&. +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-mount(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 new file mode 100644 index 000000000..2609912df --- /dev/null +++ b/docs/man/borg-info.1 @@ -0,0 +1,107 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-INFO 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-info \- Show archive details such as disk space used +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg info REPOSITORY_OR_ARCHIVE +.SH DESCRIPTION +.sp +This command displays detailed information about the specified archive or repository. +.sp +Please note that the deduplicated sizes of the individual archives do not add +up to the deduplicated size of the repository ("all archives"), because the two +are meaning different things: +.INDENT 0.0 +.TP +.B This archive / deduplicated size = amount of data stored ONLY for this archive += unique chunks of this archive. +.TP +.B All archives / deduplicated size = amount of data stored in the repo += all chunks in the repository. +.UNINDENT +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY_OR_ARCHIVE +archive or repository to display information about +.UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-sort\-by +Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ 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 \-\-list \-C zlib,6 /path/to/repo::root\-2016\-02\-15 / \-\-one\-file\-system +Number of files: 38100 + + Original size Compressed size Deduplicated size +This archive: 1.33 GB 613.25 MB 571.64 MB +All archives: 1.63 GB 853.66 MB 584.12 MB + + Unique chunks Total chunks +Chunk index: 36858 48844 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 new file mode 100644 index 000000000..40d8a25dd --- /dev/null +++ b/docs/man/borg-init.1 @@ -0,0 +1,157 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-INIT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-init \- Initialize an empty repository +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg init REPOSITORY +.SH DESCRIPTION +.sp +This command initializes an empty repository. A repository is a filesystem +directory containing the deduplicated data from zero or more archives. +.sp +Encryption can be enabled at repository init time. +.sp +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. +.sp +But be careful with the key / the passphrase: +.sp +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 +mentioned attack scenario, the attacker will have the key (but not the +passphrase). +.sp +If you want "passphrase and having\-the\-key" security, use one of the keyfile +modes. The key will be stored in your home directory (in .config/borg/keys). +In the attack scenario, the attacker who has just access to your repo won\(aqt +have the key (and also not the passphrase). +.sp +Make a backup copy of the key file (keyfile mode) or repo config file +(repokey mode) and keep it at a safe place, so you still have the key in +case it gets corrupted or lost. Also keep the passphrase at a safe place. +The backup that is encrypted with that key won\(aqt help you with that, of course. +.sp +Make sure you use a good passphrase. Not too short, not too simple. The real +encryption / decryption key is encrypted with / locked by your passphrase. +If an attacker gets your key, he can\(aqt unlock and use it without knowing the +passphrase. +.sp +Be careful with special or non\-ascii characters in your passphrase: +.INDENT 0.0 +.IP \(bu 2 +Borg processes the passphrase as unicode (and encodes it as utf\-8), +so it does not have problems dealing with even the strangest characters. +.IP \(bu 2 +BUT: that does not necessarily apply to your OS / VM / keyboard configuration. +.UNINDENT +.sp +So better use a long passphrase made from simple ascii chars than one that +includes non\-ascii stuff or characters that are hard/impossible to enter on +a different keyboard layout. +.sp +You can change your passphrase for existing repos at any time, it won\(aqt affect +the encryption/decryption key or other secrets. +.SS Encryption modes +.sp +repokey and keyfile use AES\-CTR\-256 for encryption and HMAC\-SHA256 for +authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash +is HMAC\-SHA256 as well (with a separate key). +These modes are compatible with borg 1.0.x. +.sp +repokey\-blake2 and keyfile\-blake2 are also authenticated encryption modes, +but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID +hash is a keyed BLAKE2b\-256 hash. +These modes are new and not compatible with borg 1.0.x. +.sp +"authenticated" mode uses no encryption, but authenticates repository contents +through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it +as chunk ID hash). The key is stored like repokey. +This mode is new and not compatible with borg 1.0.x. +.sp +"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 is compatible with borg 1.0.x. +.sp +Hardware acceleration will be used automatically. +.sp +On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw +accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs. +.sp +On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster +than BLAKE2b\-256 there. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY +repository to create +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-e\fP,\fB \-\-encryption +select encryption key mode (default: "None") +.TP +.B \-a\fP,\fB \-\-append\-only +create an append\-only mode repository +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1) +$ borg init \-\-encryption=repokey\-blake2 /path/to/repo + +# Local repository (no encryption) +$ borg init \-\-encryption=none /path/to/repo + +# Remote repository (accesses a remote borg via ssh) +$ borg init \-\-encryption=repokey\-blake2 user@hostname:backup + +# Remote repository (store the key your home dir) +$ borg init \-\-encryption=keyfile user@hostname:backup +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 new file mode 100644 index 000000000..63a58b0c5 --- /dev/null +++ b/docs/man/borg-key-change-passphrase.1 @@ -0,0 +1,52 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-key-change-passphrase \- Change repository key file passphrase +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg key change\-passphrase REPOSITORY +.SH DESCRIPTION +.sp +The key files used for repository encryption are optionally passphrase +protected. This command can be used to change this passphrase. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.sp +REPOSITORY +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 new file mode 100644 index 000000000..3a8158146 --- /dev/null +++ b/docs/man/borg-key-export.1 @@ -0,0 +1,78 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-KEY-EXPORT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-key-export \- Export the repository key for backup +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg key export REPOSITORY PATH +.SH DESCRIPTION +.sp +If repository encryption is used, the repository is inaccessible +without the key. This command allows to backup this essential key. +.sp +There are two backup formats. The normal backup format is suitable for +digital storage as a file. The \fB\-\-paper\fP backup format is optimized +for printing and typing in while importing, with per line checks to +reduce problems with manual input. +.sp +For repositories using keyfile encryption the key is saved locally +on the system that is capable of doing backups. To guard against loss +of this key, the key needs to be backed up independently of the main +data backup. +.sp +For repositories using the repokey encryption the key is saved in the +repository in the config file. A backup is thus not strictly needed, +but guards against the repository becoming inaccessible if the file +is damaged for some reason. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.sp +REPOSITORY +.INDENT 0.0 +.TP +.B PATH +where to store the backup +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-\-paper +Create an export suitable for printing and later type\-in +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-key\-import(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 new file mode 100644 index 000000000..7215df92a --- /dev/null +++ b/docs/man/borg-key-import.1 @@ -0,0 +1,67 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-KEY-IMPORT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-key-import \- Import the repository key from backup +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg key import REPOSITORY PATH +.SH DESCRIPTION +.sp +This command allows to restore a key previously backed up with the +export command. +.sp +If the \fB\-\-paper\fP option is given, the import will be an interactive +process in which each line is checked for plausibility before +proceeding to the next line. For this format PATH must not be given. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.sp +REPOSITORY +.INDENT 0.0 +.TP +.B PATH +path to the backup +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-\-paper +interactively import from a backup done with \-\-paper +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 new file mode 100644 index 000000000..c1c5e95f1 --- /dev/null +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -0,0 +1,66 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-key-migrate-to-repokey \- Migrate passphrase -> repokey +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg key migrate\-to\-repokey REPOSITORY +.SH DESCRIPTION +.sp +This command migrates a repository from passphrase mode (removed in Borg 1.0) +to repokey mode. +.sp +You will be first asked for the repository passphrase (to open it in passphrase +mode). This is the same passphrase as you used to use for this repo before 1.0. +.sp +It will then derive the different secrets from this passphrase. +.sp +Then you will be asked for a new passphrase (twice, for safety). This +passphrase will be used to protect the repokey (which contains these same +secrets in encrypted form). You may use the same passphrase as you used to +use, but you may also use a different one. +.sp +After migrating to repokey mode, you can change the passphrase at any time. +But please note: the secrets will always stay the same and they could always +be derived from your (old) passphrase\-mode passphrase. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.sp +REPOSITORY +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 new file mode 100644 index 000000000..d6e5a4ec8 --- /dev/null +++ b/docs/man/borg-list.1 @@ -0,0 +1,245 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-LIST 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-list \- List archive or repository contents +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg list REPOSITORY_OR_ARCHIVE PATH +.SH DESCRIPTION +.sp +This command lists the contents of a repository or an archive. +.sp +See the "borg help patterns" command for more help on exclude patterns. +.sp +The following keys are available for \-\-format: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +NEWLINE: OS dependent line separator +.IP \(bu 2 +NL: alias of NEWLINE +.IP \(bu 2 +NUL: NUL character for creating print0 / xargs \-0 like output, see barchive/bpath +.IP \(bu 2 +SPACE +.IP \(bu 2 +TAB +.IP \(bu 2 +CR +.IP \(bu 2 +LF +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Keys for listing repository archives: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +archive: archive name interpreted as text (might be missing non\-text characters, see barchive) +.IP \(bu 2 +barchive: verbatim archive name, can contain any character except NUL +.IP \(bu 2 +time: time of creation of the archive +.IP \(bu 2 +id: internal ID of the archive +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Keys for listing archive files: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +type +.IP \(bu 2 +mode +.IP \(bu 2 +uid +.IP \(bu 2 +gid +.IP \(bu 2 +user +.IP \(bu 2 +group +.IP \(bu 2 +path: path interpreted as text (might be missing non\-text characters, see bpath) +.IP \(bu 2 +bpath: verbatim POSIX path, can contain any character except NUL +.IP \(bu 2 +source: link target for links (identical to linktarget) +.IP \(bu 2 +linktarget +.IP \(bu 2 +flags +.IP \(bu 2 +size +.IP \(bu 2 +csize: compressed size +.IP \(bu 2 +num_chunks: number of chunks in this file +.IP \(bu 2 +unique_chunks: number of unique chunks in this file +.IP \(bu 2 +mtime +.IP \(bu 2 +ctime +.IP \(bu 2 +atime +.IP \(bu 2 +isomtime +.IP \(bu 2 +isoctime +.IP \(bu 2 +isoatime +.IP \(bu 2 +blake2b +.IP \(bu 2 +blake2s +.IP \(bu 2 +md5 +.IP \(bu 2 +sha1 +.IP \(bu 2 +sha224 +.IP \(bu 2 +sha256 +.IP \(bu 2 +sha384 +.IP \(bu 2 +sha3_224 +.IP \(bu 2 +sha3_256 +.IP \(bu 2 +sha3_384 +.IP \(bu 2 +sha3_512 +.IP \(bu 2 +sha512 +.IP \(bu 2 +shake_128 +.IP \(bu 2 +shake_256 +.IP \(bu 2 +archiveid +.IP \(bu 2 +archivename +.IP \(bu 2 +extra: prepends {source} with " \-> " for soft links and " link to " for hard links +.IP \(bu 2 +health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks) +.UNINDENT +.UNINDENT +.UNINDENT +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY_OR_ARCHIVE +repository/archive to list contents of +.TP +.B PATH +paths to list; patterns are supported +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-\-short +only print file/directory names, nothing else +.TP +.B \-\-format\fP,\fB \-\-list\-format +specify format for file listing +(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}") +.TP +.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +exclude paths matching PATTERN +.TP +.BI \-\-exclude\-from \ EXCLUDEFILE +read exclude patterns from EXCLUDEFILE, one per line +.UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-sort\-by +Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ 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 /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 +lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff +\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff +\&... + +$ 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 +\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 new file mode 100644 index 000000000..e788bdbae --- /dev/null +++ b/docs/man/borg-mount.1 @@ -0,0 +1,115 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-MOUNT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-mount \- Mount archive or an entire repository as a FUSE filesystem +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg mount REPOSITORY_OR_ARCHIVE MOUNTPOINT +.SH DESCRIPTION +.sp +This command mounts an archive as a FUSE filesystem. This can be useful for +browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP +option is given the command will run in the background until the filesystem +is \fBumounted\fP\&. +.sp +The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. This can also be +used in fstab entries: +\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0\fP +.sp +To allow a regular user to use fstab entries, add the \fBuser\fP option: +\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP +.sp +For mount options, see the fuse(8) manual page. Additional mount options +supported by borg: +.INDENT 0.0 +.IP \(bu 2 +versions: when used with a repository mount, this gives a merged, versioned +view of the files in the archives. EXPERIMENTAL, layout may change in future. +.IP \(bu 2 +allow_damaged_files: by default damaged files (where missing chunks were +replaced with runs of zeros by borg check \-\-repair) are not readable and +return EIO (I/O error). Set this option to read such files. +.UNINDENT +.sp +The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users +to tweak the performance. It sets the number of cached data chunks; additional +memory usage can be up to ~8 MiB times this number. The default is the number +of CPU cores. +.sp +When the daemonized process receives a signal or crashes, it does not unmount. +Unmounting in these cases could cause an active rsync or similar process +to unintentionally delete data. +.sp +When running in the foreground ^C/SIGINT unmounts cleanly, but other +signals or crashes do not. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY_OR_ARCHIVE +repository/archive to mount +.TP +.B MOUNTPOINT +where to mount filesystem +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-f\fP,\fB \-\-foreground +stay in foreground, do not daemonize +.TP +.B \-o +Extra mount options +.UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-sort\-by +Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 new file mode 100644 index 000000000..f814edc3c --- /dev/null +++ b/docs/man/borg-patterns.1 @@ -0,0 +1,144 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-PATTERNS 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-patterns \- Details regarding patterns +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH DESCRIPTION +.sp +Exclusion patterns support four separate styles, fnmatch, shell, regular +expressions and path prefixes. By default, fnmatch is used. If followed +by a colon (\(aq:\(aq) 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. \fIaa:something/*\fP). +.sp +\fI\%Fnmatch\fP, selector \fIfm:\fP +.INDENT 0.0 +.INDENT 3.5 +This is the default style. These patterns use a variant of shell +pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq +matching any single character, \(aq[...]\(aq matching any single +character specified, including ranges, and \(aq[!...]\(aq matching any +character not specified. For the purpose of these patterns, the +path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not +treated specially. Wrap meta\-characters in brackets for a literal +match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path +to match a pattern, it must completely match from start to end, or +must match from the start 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 \(aq*\(aq is appended before matching is attempted. +.UNINDENT +.UNINDENT +.sp +Shell\-style patterns, selector \fIsh:\fP +.INDENT 0.0 +.INDENT 3.5 +Like fnmatch patterns these are similar to shell patterns. The difference +is that the pattern may include \fI**/\fP for matching zero or more directory +levels, \fI*\fP for matching zero or more arbitrary characters with the +exception of any path separator. +.UNINDENT +.UNINDENT +.sp +Regular expressions, selector \fIre:\fP +.INDENT 0.0 +.INDENT 3.5 +Regular expressions similar to those found in Perl are supported. Unlike +shell patterns regular expressions are not required to match the complete +path and any substring match is sufficient. It is strongly recommended to +anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path +separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are +always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The +regular expression syntax is described in the \fI\%Python documentation for +the re module\fP\&. +.UNINDENT +.UNINDENT +.sp +Prefix path, selector \fIpp:\fP +.INDENT 0.0 +.INDENT 3.5 +This pattern style is useful to match whole sub\-directories. The pattern +\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein. +.UNINDENT +.UNINDENT +.sp +Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used +from within a shell the patterns should be quoted to protect them from +expansion. +.sp +The \fI\-\-exclude\-from\fP option permits loading exclusion patterns from a text +file with one pattern per line. Lines empty or starting with the number sign +(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style +selector prefix is also supported for patterns loaded from a file. Due to +whitespace removal paths with whitespace at the beginning or end can only be +excluded using regular expressions. +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq: +$ borg create \-e \(aq*.o\(aq backup / + +# Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but +# not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq: +$ borg create \-e \(aq/home/*/junk\(aq backup / + +# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself: +$ borg create \-e /home/user/cache/ backup / + +# The file \(aq/home/user/cache/important\(aq is *not* backed up: +$ borg create \-e /home/user/cache/ backup / /home/user/cache/important + +# The contents of directories in \(aq/home\(aq are not backed up when their name +# ends in \(aq.tmp\(aq +$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup / + +# Load exclusions from file +$ cat >exclude.txt < REPOSITORY +.SH DESCRIPTION +.sp +The prune command prunes a repository by deleting all archives not matching +any of the specified retention options. This command is normally used by +automated backup scripts wanting to keep a certain number of historic backups. +.sp +Also, prune automatically removes checkpoint archives (incomplete archives left +behind by interrupted backup runs) except if the checkpoint is the latest +archive (and thus still needed). Checkpoint archives are not considered when +comparing archive counts against the retention limits (\-\-keep\-X). +.sp +If a prefix is set with \-P, then only archives that start with the prefix are +considered for deletion and only those archives count towards the totals +specified by the rules. +Otherwise, \fIall\fP archives in the repository are candidates for deletion! +There is no automatic distinction between archives representing different +contents. These need to be distinguished by specifying matching prefixes. +.sp +If you have multiple sequences of archives with different data sets (e.g. +from different machines) in one shared repository, use one prune call per +data set that matches only the respective archives using the \-P option. +.sp +The "\-\-keep\-within" option takes an argument of the form "", +where char is "H", "d", "w", "m", "y". For example, "\-\-keep\-within 2d" means +to keep all archives that were created within the past 48 hours. +"1m" is taken to mean "31d". The archives kept with this option do not +count towards the totals specified by any other options. +.sp +A good procedure is to thin out more and more the older your backups get. +As an example, "\-\-keep\-daily 7" means to keep the latest backup on each day, +up to 7 most recent days with backups (days without backups do not count). +The rules are applied from secondly to yearly, and backups selected by previous +rules do not count towards those of later rules. The time that each backup +starts is used for pruning purposes. Dates and times are interpreted in +the local timezone, and weeks go from Monday to Sunday. Specifying a +negative number of archives to keep means that there is no limit. +.sp +The "\-\-keep\-last N" option is doing the same as "\-\-keep\-secondly N" (and it will +keep the last N archives under the assumption that you do not create more than one +backup archive in the same second). +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY +repository to prune +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-n\fP,\fB \-\-dry\-run +do not change repository +.TP +.B \-\-force +force pruning of corrupted archives +.TP +.B \-p\fP,\fB \-\-progress +show progress display while deleting archives +.TP +.B \-s\fP,\fB \-\-stats +print statistics for the deleted archive +.TP +.B \-\-list +output verbose list of archives it keeps/prunes +.TP +.BI \-\-keep\-within \ WITHIN +keep all archives within this time interval +.TP +.B \-\-keep\-last\fP,\fB \-\-keep\-secondly +number of secondly archives to keep +.TP +.B \-\-keep\-minutely +number of minutely archives to keep +.TP +.B \-H\fP,\fB \-\-keep\-hourly +number of hourly archives to keep +.TP +.B \-d\fP,\fB \-\-keep\-daily +number of daily archives to keep +.TP +.B \-w\fP,\fB \-\-keep\-weekly +number of weekly archives to keep +.TP +.B \-m\fP,\fB \-\-keep\-monthly +number of monthly archives to keep +.TP +.B \-y\fP,\fB \-\-keep\-yearly +number of yearly archives to keep +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix +.TP +.B \-\-save\-space +work slower, but using less space +.UNINDENT +.SH EXAMPLES +.sp +Be careful, prune is a potentially dangerous command, it will remove backup +archives. +.sp +The default of prune is to apply to \fBall archives in the repository\fP unless +you restrict its operation to a subset of the archives using \fB\-\-prefix\fP\&. +When using \fB\-\-prefix\fP, be careful to choose a good prefix \- e.g. do not use a +prefix "foo" if you do not also want to match "foobar". +.sp +It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP +first so you will see what it would do without it actually doing anything. +.sp +There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Keep 7 end of day and 4 additional end of week archives. +# Do a dry\-run without actually deleting anything. +$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo + +# Same as above but only apply to archive names starting with the hostname +# of the machine followed by a "\-" character: +$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq /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 \-v \-\-list \-\-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 \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 new file mode 100644 index 000000000..55b01cc82 --- /dev/null +++ b/docs/man/borg-recreate.1 @@ -0,0 +1,192 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-RECREATE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-recreate \- Re-create archives +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg recreate REPOSITORY_OR_ARCHIVE PATH +.SH DESCRIPTION +.sp +Recreate the contents of existing archives. +.sp +This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup. +.sp +\-\-exclude, \-\-exclude\-from and PATH have the exact same semantics +as in "borg create". If PATHs are specified the resulting archive +will only contain files from these PATHs. +.sp +Note that all paths in an archive are relative, therefore absolute patterns/paths +will \fInot\fP match (\-\-exclude, \-\-exclude\-from, \-\-compression\-from, PATHs). +.sp +\-\-compression: all chunks seen will be stored using the given method. +Due to how Borg stores compressed size information this might display +incorrect information for archives that were not recreated at the same time. +There is no risk of data loss by this. +.sp +\-\-chunker\-params will re\-chunk all files in the archive, this can be +used to have upgraded Borg 0.xx or Attic archives deduplicate with +Borg 1.x archives. +.sp +USE WITH CAUTION. +Depending on the PATHs and patterns given, recreate can be used to permanently +delete files from archives. +When in doubt, use "\-\-dry\-run \-\-verbose \-\-list" to see how patterns/PATHS are +interpreted. +.sp +The archive being recreated is only removed after the operation completes. The +archive that is built during the operation exists at the same time at +".recreate". The new archive will have a different archive ID. +.sp +With \-\-target the original archive is not replaced, instead a new archive is created. +.sp +When rechunking space usage can be substantial, expect at least the entire +deduplicated size of the archives using the previous chunker params. +When recompressing expect approx. (throughput / checkpoint\-interval) in space usage, +assuming all chunks are recompressed. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY_OR_ARCHIVE +repository/archive to recreate +.TP +.B PATH +paths to recreate; patterns are supported +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-\-list +output verbose list of items (files, dirs, ...) +.TP +.BI \-\-filter \ STATUSCHARS +only display items with the given status characters +.TP +.B \-p\fP,\fB \-\-progress +show progress display while recreating archives +.TP +.B \-n\fP,\fB \-\-dry\-run +do not change anything +.TP +.B \-s\fP,\fB \-\-stats +print statistics at end +.UNINDENT +.SS Exclusion options +.INDENT 0.0 +.TP +.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +exclude paths matching PATTERN +.TP +.BI \-\-exclude\-from \ EXCLUDEFILE +read exclude patterns from EXCLUDEFILE, one per line +.TP +.B \-\-exclude\-caches +exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP) +.TP +.BI \-\-exclude\-if\-present \ NAME +exclude directories that are tagged by containing a filesystem object with the given NAME +.TP +.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files +keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories +.UNINDENT +.SS Archive options +.INDENT 0.0 +.TP +.BI \-\-target \ TARGET +create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) +.TP +.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS +write checkpoint every SECONDS seconds (Default: 1800) +.TP +.BI \-\-comment \ COMMENT +add a comment text to the archive +.TP +.BI \-\-timestamp \ TIMESTAMP +manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory. +.TP +.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION +select compression algorithm, see the output of the "borg help compression" command for details. +.TP +.B \-\-always\-recompress +always recompress chunks, don\(aqt skip chunks already compressed with the same algorithm. +.TP +.BI \-\-compression\-from \ COMPRESSIONCONFIG +read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details. +.TP +.BI \-\-chunker\-params \ PARAMS +specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095 +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives +# Archives created with Borg 1.1+ and the default chunker params are skipped (archive ID stays the same) +$ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress + +# Create a backup with little but fast compression +$ borg create /mnt/backup::archive /some/files \-\-compression lz4 +# Then compress it \- this might take longer, but the backup has already completed, so no inconsistencies +# from a long\-running backup job. +$ borg recreate /mnt/backup::archive \-\-compression zlib,9 + +# Remove unwanted files from all archives in a repository +$ borg recreate /mnt/backup \-e /home/icke/Pictures/drunk_photos + + +# Change archive comment +$ borg create \-\-comment "This is a comment" /mnt/backup::archivename ~ +$ borg info /mnt/backup::archivename +Name: archivename +Fingerprint: ... +Comment: This is a comment +\&... +$ borg recreate \-\-comment "This is a better comment" /mnt/backup::archivename +$ borg info /mnt/backup::archivename +Name: archivename +Fingerprint: ... +Comment: This is a better comment +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 new file mode 100644 index 000000000..ee568f2f5 --- /dev/null +++ b/docs/man/borg-rename.1 @@ -0,0 +1,76 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-RENAME 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-rename \- Rename an existing archive +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg rename ARCHIVE NEWNAME +.SH DESCRIPTION +.sp +This command renames an archive in the repository. +.sp +This results in a different archive ID. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B ARCHIVE +archive to rename +.TP +.B NEWNAME +the new archive name to use +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ borg create /path/to/repo::archivename ~ +$ borg list /path/to/repo +archivename Mon, 2016\-02\-15 19:50:19 + +$ borg rename /path/to/repo::archivename newname +$ borg list /path/to/repo +newname Mon, 2016\-02\-15 19:50:19 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 new file mode 100644 index 000000000..673ae2696 --- /dev/null +++ b/docs/man/borg-serve.1 @@ -0,0 +1,80 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-SERVE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-serve \- Start in server mode. This command is usually not used manually. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg serve +.SH DESCRIPTION +.sp +This command starts a repository server process. This command is usually not used manually. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS optional arguments +.INDENT 0.0 +.TP +.BI \-\-restrict\-to\-path \ PATH +restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository. +.TP +.B \-\-append\-only +only allow appending to repository segment files +.UNINDENT +.SH EXAMPLES +.sp +borg serve has special support for ssh forced commands (see \fBauthorized_keys\fP +example below): it will detect that you use such a forced command and extract +the value of the \fB\-\-restrict\-to\-path\fP option(s). +It will then parse the original command that came from the client, makes sure +that it is also \fBborg serve\fP and enforce path restriction(s) as given by the +forced command. That way, other options given by the client (like \fB\-\-info\fP or +\fB\-\-umask\fP) are preserved (and are not fixed by the forced command). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# 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 /path/to/repo",no\-pty,no\-agent\-forwarding,no\-port\-forwarding,no\-X11\-forwarding,no\-user\-rc ssh\-rsa AAAAB3[...] +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 new file mode 100644 index 000000000..4de127a5c --- /dev/null +++ b/docs/man/borg-umount.1 @@ -0,0 +1,115 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-UMOUNT 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-umount \- un-mount the FUSE filesystem +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg umount MOUNTPOINT +.SH DESCRIPTION +.sp +This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&. +.sp +This is a convenience wrapper that just calls the platform\-specific shell +command \- usually this is either umount or fusermount \-u. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B MOUNTPOINT +mountpoint of the filesystem to umount +.UNINDENT +.SH EXAMPLES +.SS borg mount +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ 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 +$ borg umount /tmp/mymountpoint +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ borg mount \-o versions /path/to/repo /tmp/mymountpoint +$ ls \-l /tmp/mymountpoint/home/user/doc.txt/ +total 24 +\-rw\-rw\-r\-\- 1 user group 12357 Aug 26 21:19 doc.txt.cda00bc9 +\-rw\-rw\-r\-\- 1 user group 12204 Aug 26 21:04 doc.txt.fa760f28 +$ fusermount \-u /tmp/mymountpoint +.ft P +.fi +.UNINDENT +.UNINDENT +.SS borgfs +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab +$ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab +$ mount /tmp/myrepo +$ mount /tmp/myarchive +$ ls /tmp/myrepo +root\-2016\-02\-01 root\-2016\-02\-2015 +$ ls /tmp/myarchive +bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBborgfs\fP will be automatically provided if you used a distribution +package, \fBpip\fP or \fBsetup.py\fP to install Borg\&. Users of the +standalone binary will have to manually create a symlink (see +\fIpyinstaller\-binary\fP). +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-mount(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 new file mode 100644 index 000000000..d329fa885 --- /dev/null +++ b/docs/man/borg-upgrade.1 @@ -0,0 +1,170 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-UPGRADE 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-upgrade \- upgrade a repository from a previous version +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg upgrade REPOSITORY +.SH DESCRIPTION +.sp +Upgrade an existing Borg repository. +.SS Borg 1.x.y upgrades +.sp +Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication +introduced with Borg 1.0.9 to address security issues. This means +that modifying the repository after doing this with a version prior +to 1.0.9 will raise a validation error, so only perform this upgrade +after updating all clients using the repository to 1.0.9 or newer. +.sp +This upgrade should be done on each client for safety reasons. +.sp +If a repository is accidentally modified with a pre\-1.0.9 client after +this upgrade, use \fBborg upgrade \-\-tam \-\-force REPO\fP to remedy it. +.sp +If you routinely do this you might not want to enable this upgrade +(which will leave you exposed to the security issue). You can +reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&. +.sp +See +\fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP +for details. +.SS Attic and Borg 0.xx to Borg 1.x +.sp +This currently supports converting an Attic repository to Borg and also +helps with converting Borg 0.xx to 1.0. +.sp +Currently, only LOCAL repositories can be upgraded (issue #465). +.sp +It will change the magic strings in the repository\(aqs segments +to match the new Borg magic strings. The keyfiles found in +$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and +copied to $BORG_KEYS_DIR or ~/.config/borg/keys. +.sp +The cache files are converted, from $ATTIC_CACHE_DIR or +~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the +cache layout between Borg and Attic changed, so it is possible +the first backup after the conversion takes longer than expected +due to the cache resync. +.sp +Upgrade should be able to resume if interrupted, although it +will still iterate over all segments. If you want to start +from scratch, use \fIborg delete\fP over the copied repository to +make sure the cache files are also removed: +.INDENT 0.0 +.INDENT 3.5 +borg delete borg +.UNINDENT +.UNINDENT +.sp +Unless \fB\-\-inplace\fP is specified, the upgrade process first +creates a backup copy of the repository, in +REPOSITORY.upgrade\-DATETIME, using hardlinks. This takes +longer than in place upgrades, but is much safer and gives +progress information (as opposed to \fBcp \-al\fP). Once you are +satisfied with the conversion, you can safely destroy the +backup copy. +.sp +WARNING: Running the upgrade in place will make the current +copy unusable with older version, with no way of going back +to previous versions. This can PERMANENTLY DAMAGE YOUR +REPOSITORY! Attic CAN NOT READ BORG REPOSITORIES, as the +magic strings have changed. You have been warned. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY +path to the repository to be upgraded +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-p\fP,\fB \-\-progress +show progress display while upgrading the repository +.TP +.B \-n\fP,\fB \-\-dry\-run +do not change repository +.TP +.B \-i\fP,\fB \-\-inplace +rewrite repository in place, with no chance of going back to older +versions of the repository. +.TP +.B \-\-force +Force upgrade +.TP +.B \-\-tam +Enable manifest authentication (in key and cache) (Borg 1.0.9 and later) +.TP +.B \-\-disable\-tam +Disable manifest authentication (in key and cache) +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Upgrade the borg repository to the most recent version. +$ 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 /path/to/repo/index.0 +converting 1 segments... +converting borg 0.xx to borg current +no key file found for repository +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Upgrading a passphrase encrypted attic repo +.sp +attic offered a "passphrase" encryption mode, but this was removed in borg 1.0 +and replaced by the "repokey" mode (which stores the passphrase\-protected +encryption key into the repository config). +.sp +Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps +are needed, in this order: +.INDENT 0.0 +.IP \(bu 2 +borg upgrade repo +.IP \(bu 2 +borg key migrate\-to\-repokey repo +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 new file mode 100644 index 000000000..d6e19958b --- /dev/null +++ b/docs/man/borg-with-lock.1 @@ -0,0 +1,71 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-WITH-LOCK 1 "2017-02-05" "" "borg backup tool" +.SH NAME +borg-with-lock \- run a user specified command with the repository lock held +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg with\-lock REPOSITORY COMMAND ARGS +.SH DESCRIPTION +.sp +This command runs a user\-specified command while the repository lock is held. +.sp +It will first try to acquire the lock (make sure that no other operation is +running in the repo), then execute the given command as a subprocess and wait +for its termination, release the lock and return the user command\(aqs return +code as borg\(aqs return code. +.INDENT 0.0 +.TP +.B Note: if you copy a repository with the lock held, the lock will be present in +the copy, obviously. Thus, before using borg on the copy, you need to +use "borg break\-lock" on it. +.UNINDENT +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPOSITORY +repository to lock +.TP +.B COMMAND +command to run +.TP +.B ARGS +command arguments +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +.