From c4347a9dcecfc50114b8dbcfeac7cebb7e64c62f Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Tue, 16 Jun 2026 14:17:43 +0200 Subject: [PATCH] build usage / man --- docs/man/borg-analyze.1 | 2 +- docs/man/borg-benchmark-cpu.1 | 2 +- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 15 ++- docs/man/borg-common.1 | 5 +- docs/man/borg-compact.1 | 2 +- docs/man/borg-completion.1 | 2 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-create.1 | 19 +++- docs/man/borg-delete.1 | 2 +- docs/man/borg-diff.1 | 4 +- docs/man/borg-export-tar.1 | 2 +- docs/man/borg-extract.1 | 2 +- docs/man/borg-import-tar.1 | 2 +- docs/man/borg-info.1 | 2 +- docs/man/borg-key-add.1 | 2 +- docs/man/borg-key-change-location.1 | 6 +- docs/man/borg-key-change-passphrase.1 | 6 +- docs/man/borg-key-export.1 | 16 ++- docs/man/borg-key-import.1 | 5 +- docs/man/borg-key-list.1 | 2 +- docs/man/borg-key-remove.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 6 +- docs/man/borg-match-archives.1 | 2 +- docs/man/borg-mount.1 | 2 +- docs/man/borg-patterns.1 | 6 +- docs/man/borg-placeholders.1 | 6 +- docs/man/borg-prune.1 | 5 +- docs/man/borg-recreate.1 | 2 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-repo-create.1 | 144 +++++++------------------ docs/man/borg-repo-delete.1 | 2 +- docs/man/borg-repo-info.1 | 4 +- docs/man/borg-repo-list.1 | 7 +- docs/man/borg-repo-space.1 | 2 +- docs/man/borg-serve.1 | 32 +++--- docs/man/borg-tag.1 | 2 +- docs/man/borg-transfer.1 | 107 ++++++++++++------ docs/man/borg-umount.1 | 2 +- docs/man/borg-undelete.1 | 2 +- docs/man/borg-version.1 | 14 +-- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 26 +++-- docs/man/borgfs.1 | 2 +- docs/usage/check.rst.inc | 13 ++- docs/usage/create.rst.inc | 19 ++++ docs/usage/diff.rst.inc | 2 +- docs/usage/help.rst.inc | 8 +- docs/usage/key_change-location.rst.inc | 2 +- docs/usage/key_export.rst.inc | 42 +++++--- docs/usage/key_import.rst.inc | 29 ++--- docs/usage/list.rst.inc | 3 +- docs/usage/prune.rst.inc | 113 +++++++++---------- docs/usage/repo-list.rst.inc | 5 +- docs/usage/serve.rst.inc | 30 ++++-- docs/usage/transfer.rst.inc | 6 +- docs/usage/version.rst.inc | 12 +-- 60 files changed, 426 insertions(+), 347 deletions(-) diff --git a/docs/man/borg-analyze.1 b/docs/man/borg-analyze.1 index f07406cb05..74e7b5125f 100644 --- a/docs/man/borg-analyze.1 +++ b/docs/man/borg-analyze.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-analyze" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-analyze" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-analyze \- Analyzes archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index b155602c3d..5c272553d7 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-benchmark-cpu" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-benchmark-cpu" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-benchmark-cpu \- Benchmark CPU-bound operations. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 763ed958e2..848f3008d1 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-benchmark-crud" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-benchmark-crud" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index bf5c019f98..95670d7a9e 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-benchmark" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-benchmark" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index f907199ce5..57517a3ee2 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-break-lock" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-break-lock" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process). .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index a0b3dcf46c..a945bca409 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-check" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-check" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-check \- Checks repository consistency. .SH SYNOPSIS @@ -84,13 +84,12 @@ repository files. Enabling partial repository checks excludes archive checks for the same reason. Therefore, partial checks may be useful only with very large repositories where a full check would take too long. .sp -The \fB\-\-verify\-data\fP option will perform a full integrity verification (as -opposed to checking just the xxh64) of data, which means reading the -data from the repository, decrypting and decompressing it. It is a complete -cryptographic verification and hence very time\-consuming, but will detect any -accidental and malicious corruption. Tamper\-resistance is only guaranteed for -encrypted repositories against attackers without access to the keys. You cannot -use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&. +The \fB\-\-verify\-data\fP option will perform a full integrity verification of data, +which means reading the data from the repository, decrypting and decompressing it. +It is a complete cryptographic verification and hence very time\-consuming, but +will detect any accidental and malicious corruption. Tamper\-resistance is only +guaranteed for encrypted repositories against attackers without access to the keys. +You cannot use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&. .sp The \fB\-\-find\-lost\-archives\fP option will also scan the whole repository, but tells Borg to search for lost archive metadata. If Borg encounters any archive diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index f38ee3cd15..411b85b6ac 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-common" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-common" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-common \- Common options of Borg commands .SH SYNOPSIS @@ -91,9 +91,6 @@ Write execution profile in Borg format into FILE. For local use a Python\-compat .BI \-\-rsh \ RSH Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq) .TP -.BI \-\-socket \ PATH -Use UNIX DOMAIN (IPC) socket at PATH for client/server communication with socket: protocol. -.TP .BI \-r \ REPO\fR,\fB \ \-\-repo \ REPO repository to use .UNINDENT diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index d73f1cf94b..8b32cabd64 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-compact" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-compact" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-compact \- Collects garbage in the repository. .SH SYNOPSIS diff --git a/docs/man/borg-completion.1 b/docs/man/borg-completion.1 index 036259284e..c437d9a17d 100644 --- a/docs/man/borg-completion.1 +++ b/docs/man/borg-completion.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-completion" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-completion" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-completion \- Output shell completion script for the given shell. .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index b75c0ac111..3ce8719ef6 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-compression" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-compression" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-compression \- Details regarding compression .SH DESCRIPTION diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 973f398932..02c8b920d6 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-create" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-create" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-create \- Creates a new archive. .SH SYNOPSIS @@ -223,6 +223,9 @@ exclude directories that are tagged by containing a filesystem object with the g .TP .B \-\-keep\-exclude\-tags if tag objects are specified with \fB\-\-exclude\-if\-present\fP, do not omit the tag objects themselves from the backup archive +.TP +.B \-\-exclude\-dataless +exclude files flagged DATALESS (macOS: placeholder files whose content is not materialized locally, e.g. not\-downloaded cloud storage files) .UNINDENT .SS Filesystem options .INDENT 0.0 @@ -472,6 +475,20 @@ Other flags used include: .IP \(bu 2 \(aq?\(aq = missing status code (if you see this, please file a bug report!) .UNINDENT +.SS Errors and (incomplete) archives +.sp +If an error happens during archive creation (e.g. some file could not be read +due to a permission error or some other OS error), borg will log a warning or +an error (depending on the type of issue) and continue with the next item. +.sp +At the end of the backup, if there were any such issues, borg will exit with +a non\-zero exit code (usually 1 for warnings). +.sp +\fBThe archive is still saved even if warnings or errors occurred\fP, but it will +only contain the data borg was able to read successfully. It is like a +checkpoint (see below), but with a user\-given name. +.sp +You should always check the backup logs and the exit code of the borg command. .SS Reading backup data from stdin .sp There are two methods to read from stdin. Either specify \fB\-\fP as path and diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 09fad98310..de3bdd9162 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-delete" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-delete" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-delete \- Deletes archives. .SH SYNOPSIS diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 4cbbdf4072..8d6b08fcd8 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-diff" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-diff" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-diff \- Finds differences between two archives. .SH SYNOPSIS @@ -121,7 +121,7 @@ added 0 B file4 .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index ca1a5747fd..25e9e9a4ec 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -29,7 +29,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-export-tar" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-export-tar" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 8749fc332a..b6cd693f2c 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-extract" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-extract" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-extract \- Extracts archive contents. .SH SYNOPSIS diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 892a9cdf29..3796e8a2a2 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-import-tar" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-import-tar" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index b498903c77..8315252ef4 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-info" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-info" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-info \- Show archive details such as disk space used .SH SYNOPSIS diff --git a/docs/man/borg-key-add.1 b/docs/man/borg-key-add.1 index 98bccec3d6..b4b1470ad6 100644 --- a/docs/man/borg-key-add.1 +++ b/docs/man/borg-key-add.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-add" "1" "2026-06-13" "" "borg backup tool" +.TH "borg-key-add" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key-add \- Add a new borg key (protected by an independent passphrase) to the repository. .SH SYNOPSIS diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index 0394bcf228..cdd2009435 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -28,9 +28,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-change-location" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-key-change-location" "1" "2026-06-16" "" "borg backup tool" .SH Name -borg-key-change-location \- Changes the repository key location. +borg-key-change-location \- Changes the location of the borg key used to unlock this repository. .SH SYNOPSIS .sp borg [common options] key change\-location [options] KEY_LOCATION @@ -41,7 +41,7 @@ Change the location of a Borg key. The key can be stored at different locations: .IP \(bu 2 keyfile: locally, usually in the home directory .IP \(bu 2 -repokey: inside the repository (in the repository config) +repokey: inside the repository .UNINDENT .sp Please note: diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 54509529e8..d732ac8891 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-change-passphrase" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-key-change-passphrase" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key-change-passphrase \- Changes the repository key file passphrase. .SH SYNOPSIS @@ -52,7 +52,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .sp .EX # Create a key file protected repository -$ borg repo\-create \-\-encryption=keyfile\-aes\-ocb \-v +$ borg repo\-create \-\-encryption=aes\-ocb \-\-key\-location=keyfile \-v Initializing repository at \(dq/path/to/repo\(dq Enter new passphrase: Enter same passphrase again: @@ -100,7 +100,7 @@ Fully automated using environment variables: .INDENT 3.5 .sp .EX -$ BORG_NEW_PASSPHRASE=old borg repo\-create \-\-encryption=repokey\-aes\-ocb +$ BORG_NEW_PASSPHRASE=old borg repo\-create \-\-encryption=aes\-ocb # now \(dqold\(dq is the current passphrase. $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase # now \(dqnew\(dq is the current passphrase. diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 738454c033..c7e56b21f3 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -28,9 +28,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-export" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-key-export" "1" "2026-06-16" "" "borg backup tool" .SH Name -borg-key-export \- Exports the repository key for backup. +borg-key-export \- Exports a borg key of the repository for backup. .SH SYNOPSIS .sp borg [common options] key export [options] [PATH] @@ -58,6 +58,12 @@ Note that the backup produced does not include the passphrase itself repository, one needs both the exported key and the original passphrase. Keep the exported key and the passphrase at safe places. .sp +A repository may have more than one borg key (each protected by its own +passphrase, see \fBborg key add\fP). Select which borg key to export with +\fB\-\-label\fP or \fB\-\-key\fP (its key id or a unique prefix, see +\fBborg key list\fP). If the repository has only a single borg key, no +selector is required. +.sp There are three 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 @@ -75,6 +81,12 @@ where to store the backup .SS options .INDENT 0.0 .TP +.BI \-\-label \ LABEL +export the borg key with this label +.TP +.BI \-\-key \ ID +export the borg key with this id (or unique id prefix) +.TP .B \-\-paper Create an export suitable for printing and later type\-in .TP diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 2dd6c2e296..e31b1bfa9a 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-import" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-key-import" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key-import \- Imports the repository key from backup. .SH SYNOPSIS @@ -64,6 +64,9 @@ path to the backup (\(aq\-\(aq to read from stdin) .TP .B \-\-paper interactively import from a backup done with \fB\-\-paper\fP +.TP +.BI \-\-key\-location \ LOCATION +where to store the imported key: \(aqrepokey\(aq (in the repository, default) or \(aqkeyfile\(aq (in the local keys directory) .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-key-list.1 b/docs/man/borg-key-list.1 index 5c29f9ddb8..3fed88d17c 100644 --- a/docs/man/borg-key-list.1 +++ b/docs/man/borg-key-list.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-list" "1" "2026-06-13" "" "borg backup tool" +.TH "borg-key-list" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key-list \- List the borg keys of the repository. .SH SYNOPSIS diff --git a/docs/man/borg-key-remove.1 b/docs/man/borg-key-remove.1 index d99f4f9f64..a78e1df51d 100644 --- a/docs/man/borg-key-remove.1 +++ b/docs/man/borg-key-remove.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key-remove" "1" "2026-06-13" "" "borg backup tool" +.TH "borg-key-remove" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key-remove \- Remove a borg key from the repository. .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 60c4a7705f..15399eec84 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-key" "1" "2026-06-13" "" "borg backup tool" +.TH "borg-key" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-key \- Manage the keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index a037e23ee8..c13e1b4bce 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-list" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-list" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-list \- List archive contents. .SH SYNOPSIS @@ -123,7 +123,7 @@ $ borg list archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\( .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 @@ -219,8 +219,6 @@ sha3_512 .IP \(bu 2 sha512 .IP \(bu 2 -xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!) -.IP \(bu 2 archiveid: internal ID of the archive .IP \(bu 2 archivename: name of the archive diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1 index 157b1ce3bd..c40ae33c18 100644 --- a/docs/man/borg-match-archives.1 +++ b/docs/man/borg-match-archives.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-match-archives" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-match-archives" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-match-archives \- Details regarding match-archives .SH DESCRIPTION diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index ad158ed7ef..817aa8a534 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-mount" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-mount" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-mount \- Mounts an archive or an entire repository as a FUSE filesystem. .SH SYNOPSIS diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 74aff87a27..69fb794b14 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-patterns" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-patterns" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-patterns \- Details regarding patterns .SH DESCRIPTION @@ -71,6 +71,10 @@ start with \fBsrc\fP\&. .IP \(bu 2 On native Windows, archived absolute paths look like \fBC/Windows/System32\fP\&. .UNINDENT +.IP \(bu 2 +When using the slashdot hack, patterns match against the unstripped path, +i.e., when you back up \fB/this/gets/stripped/./this/gets/archived\fP, +patterns must match \fBthis/gets/stripped/this/gets/archived\fP\&. .UNINDENT .sp Borg supports different pattern styles. To define a non\-default diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 9b8bd5e7fb..8feda318e7 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-placeholders" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-placeholders" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-placeholders \- Details regarding placeholders .SH DESCRIPTION @@ -48,11 +48,11 @@ The full name of the machine in reverse domain name notation. .TP .B {now} The current local date and time, by default in ISO\-8601 format. -You can also supply your own format string \%, e.g. {now:%Y\-%m\-%d_%H:%M:%S} +You can also supply your own format string \%, e.g. {now:%Y\-%m\-%d_%H:%M:%S} .TP .B {utcnow} The current UTC date and time, by default in ISO\-8601 format. -You can also supply your own format string \%, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S} +You can also supply your own format string \%, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S} .TP .B {user} The user name (or UID, if no name is available) of the user running borg. diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 19ffdd7c98..0d9a4edffa 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-prune" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-prune" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-prune \- Prune archives according to specified rules. .SH SYNOPSIS @@ -128,6 +128,9 @@ output verbose list of archives it keeps .BI \-\-format \ FORMAT specify format for the archive part (default: \(dq{archive:<36} {time} [{id}]\(dq) .TP +.B \-\-json +Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. +.TP .BI \-\-keep\-within \ INTERVAL keep all archives within this time interval .TP diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index c3aeb8891a..ed369c2465 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-recreate" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-recreate" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-recreate \- Recreate archives. .SH SYNOPSIS diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 09506a5914..dc16228036 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-rename" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-rename" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-rename \- Rename an existing archive. .SH SYNOPSIS diff --git a/docs/man/borg-repo-create.1 b/docs/man/borg-repo-create.1 index 955ca8bc57..ecef7e31d4 100644 --- a/docs/man/borg-repo-create.1 +++ b/docs/man/borg-repo-create.1 @@ -1,4 +1,3 @@ -'\" t .\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . @@ -29,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-repo-create" "1" "2026-06-13" "" "borg backup tool" +.TH "borg-repo-create" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-repo-create \- Creates a new, empty repository. .SH SYNOPSIS @@ -53,7 +52,7 @@ tips will come below): .INDENT 3.5 .sp .EX -borg repo\-create \-\-encryption aes\-ocb \-\-key\-location repokey +borg repo\-create \-\-encryption aes256\-ocb \-\-key\-location repokey .EE .UNINDENT .UNINDENT @@ -106,13 +105,36 @@ a different keyboard layout. .sp You can change your passphrase for existing repositories at any time; it will not affect the encryption/decryption key or other secrets. -.SS Choosing an encryption mode +.SS Choosing a crypto suite .sp Depending on your hardware, hashing and crypto performance may vary widely. The easiest way to find out what is fastest is to run \fBborg benchmark cpu\fP\&. .sp -The encryption mode (\fB\-\-encryption\fP) only selects the crypto suite (id hash, encryption -and authentication). Where the key is stored is chosen separately with \fB\-\-key\-location\fP: +A crypto suite is selected by three orthogonal options: +.sp +\fB\-\-encryption\fP (\fBrequired\fP) selects the cipher / authenticated\-encryption algorithm: +.INDENT 0.0 +.IP \(bu 2 +\fBaes256\-ocb\fP: AES256 in OCB mode (encryption + authentication). +.IP \(bu 2 +\fBchacha20\-poly1305\fP: ChaCha20 + Poly1305 (encryption + authentication). +.IP \(bu 2 +\fBauthenticated\fP: no encryption, but still authenticates your data (tamper detection). +.IP \(bu 2 +\fBnone\fP: no encryption and no authentication (see the warning below). +.UNINDENT +.sp +\fB\-\-id\-hash\fP selects the id hash function (used for chunk ids and authentication): +.INDENT 0.0 +.IP \(bu 2 +\fBsha256\fP (default): HMAC\-SHA\-256 (or plain SHA\-256 for the \fBnone\fP encryption). +.IP \(bu 2 +\fBblake3\fP: BLAKE3. Often faster on CPUs without SHA hardware acceleration. +.UNINDENT +.sp +The \fBnone\fP encryption has no key, so it only supports the \fBsha256\fP id hash. +.sp +\fB\-\-key\-location\fP selects where the key is stored (orthogonal to the crypto suite): .INDENT 0.0 .IP \(bu 2 \fBrepokey\fP (default): the key is stored in the repository (under \fBkeys/\fP). Pick this @@ -123,108 +145,19 @@ this if you want \(dqpassphrase and having\-the\-key\(dq security. .UNINDENT .sp You can move the key between these locations later with \fBborg key change\-location\fP\&. -This also applies to the \fBauthenticated*\fP modes: they do not encrypt your data, but they -still have a key (used for the id hash and authentication), so \fB\-\-key\-location\fP selects -where that key is stored, just like for the encrypted modes. -\fB\-\-key\-location\fP is only ignored for the \fBnone\fP mode, which has no key at all. +This also applies to the \fBauthenticated\fP encryption: it does not encrypt your data, but it +still has a key (used for the id hash and authentication), so \fB\-\-key\-location\fP selects +where that key is stored, just like for the encrypted suites. +\fB\-\-key\-location\fP is only ignored for the \fBnone\fP encryption, which has no key at all. .sp -The following table is roughly sorted in order of preference, the better ones are -in the upper part of the table, in the lower part is the old and/or unsafe(r) stuff: -.\" nanorst: inline-fill -. -.TS -box center; -l|l|l|l. -T{ -Encryption mode -T} T{ -ID\-Hash -T} T{ -Encryption -T} T{ -Authentication -T} -_ -T{ -blake3\-chacha20\-poly1305 -T} T{ -BLAKE3 -T} T{ -CHACHA20 -T} T{ -POLY1305 -T} -_ -T{ -chacha20\-poly1305 -T} T{ -HMAC\-SHA\-256 -T} T{ -CHACHA20 -T} T{ -POLY1305 -T} -_ -T{ -blake3\-aes\-ocb -T} T{ -BLAKE3 -T} T{ -AES256\-OCB -T} T{ -AES256\-OCB -T} -_ -T{ -aes\-ocb -T} T{ -HMAC\-SHA\-256 -T} T{ -AES256\-OCB -T} T{ -AES256\-OCB -T} -_ -T{ -authenticated\-blake3 -T} T{ -BLAKE3 -T} T{ -none -T} T{ -BLAKE3 -T} -_ -T{ -authenticated -T} T{ -HMAC\-SHA\-256 -T} T{ -none -T} T{ -HMAC\-SHA256 -T} -_ -T{ -none -T} T{ -SHA\-256 -T} T{ -none -T} T{ -none -T} -.TE -.\" nanorst: inline-replace -. -.sp -\fInone\fP mode uses no encryption and no authentication. You are advised NOT to use this mode +\fInone\fP encryption uses no encryption and no authentication. You are advised NOT to use this as it would expose you to a Denial\-of\-Service risk (due to how the \fIinternals_hashindex\fP works) and other issues (confidentiality, tampering, ...) in case of malicious activity in the repository. .sp If you do \fBnot\fP want to encrypt the contents of your backups, but still want to detect -malicious tampering, use an \fIauthenticated\fP mode. It is like \fIrepokey\fP minus encryption. +malicious tampering, use \fB\-\-encryption authenticated\fP\&. It is like an encrypted suite +minus the data encryption. To normally work with \fBauthenticated\fP repositories, you will need the passphrase, but there is an emergency workaround; see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs. .SS Creating a related repository @@ -258,8 +191,11 @@ reuse the key material from the other repository .B \-\-from\-borg1 other repository is Borg 1.x .TP -.BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE -select encryption crypto suite \fB(required)\fP +.BI \-e \ ENCRYPTION\fR,\fB \ \-\-encryption \ ENCRYPTION +select cipher / AE algorithm: \(aqnone\(aq, \(aqauthenticated\(aq, \(aqaes256\-ocb\(aq or \(aqchacha20\-poly1305\(aq \fB(required)\fP +.TP +.BI \-i \ HASH\fR,\fB \ \-\-id\-hash \ HASH +select the id hash function: \(aqsha256\(aq (default) or \(aqblake3\(aq. The \(aqnone\(aq encryption only supports \(aqsha256\(aq. .TP .BI \-\-key\-location \ LOCATION where to store the key: \(aqrepokey\(aq (in the repository, default) or \(aqkeyfile\(aq (in the local keys directory). Ignored for the \(aqnone\(aq mode (which has no key). diff --git a/docs/man/borg-repo-delete.1 b/docs/man/borg-repo-delete.1 index b65d0d08eb..b304ea4bea 100644 --- a/docs/man/borg-repo-delete.1 +++ b/docs/man/borg-repo-delete.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-repo-delete" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-repo-delete" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-repo-delete \- Deletes a repository. .SH SYNOPSIS diff --git a/docs/man/borg-repo-info.1 b/docs/man/borg-repo-info.1 index 24708c8f0d..66da2f5e7d 100644 --- a/docs/man/borg-repo-info.1 +++ b/docs/man/borg-repo-info.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-repo-info" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-repo-info" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-repo-info \- Show repository information. .SH SYNOPSIS @@ -54,7 +54,7 @@ format output as JSON $ borg repo\-info Repository ID: 0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9 Location: /Users/tw/w/borg/path/to/repo -Encrypted: Yes (repokey AES\-OCB) +Encrypted: Yes (repokey, aes256\-ocb, sha256) Cache: /Users/tw/.cache/borg/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9 Security dir: /Users/tw/.config/borg/security/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9 Original size: 152.14 MB diff --git a/docs/man/borg-repo-list.1 b/docs/man/borg-repo-list.1 index b862faa419..d8af83cdf7 100644 --- a/docs/man/borg-repo-list.1 +++ b/docs/man/borg-repo-list.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-repo-list" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-repo-list" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-repo-list \- List the archives contained in a repository. .SH SYNOPSIS @@ -46,6 +46,9 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .B \-\-short only print the archive IDs, nothing else .TP +.B \-\-from\-borg1 +repository is Borg 1.x +.TP .BI \-\-format \ FORMAT specify format for archive listing (default: \(dq{archive:<36} {time} [{id}]{NL}\(dq) .TP @@ -101,7 +104,7 @@ ba56c4a5 Thu, 2024\-09\-26 10:12:45 +0200 src tw MacBook .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 diff --git a/docs/man/borg-repo-space.1 b/docs/man/borg-repo-space.1 index c29ae8de83..a3472506b3 100644 --- a/docs/man/borg-repo-space.1 +++ b/docs/man/borg-repo-space.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-repo-space" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-repo-space" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-repo-space \- Manages reserved space in the repository. .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index a0cd4079e8..16b33fa73c 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-serve" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-serve" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-serve \- Starts in server mode. This command is usually not used manually. .SH SYNOPSIS @@ -36,23 +36,25 @@ borg-serve \- Starts in server mode. This command is usually not used manually. borg [common options] serve [options] .SH DESCRIPTION .sp -This command starts a repository server process. +This command starts a repository server process. It is usually started automatically via +SSH by a borg client and runs until that SSH connection is terminated. .sp -\fIborg serve\fP currently supports: +It operates in one of two modes: .INDENT 0.0 .IP \(bu 2 -Being automatically started via SSH when the borg client uses an \%\&... -remote repository. In this mode, \fIborg serve\fP will run until that SSH connection -is terminated. +default (no option): serve a \fBlegacy\fP (borg 1.x / v1) repository using the legacy +RPC protocol. This is used e.g. for \fBborg transfer \-\-from\-borg1\fP and is command\-line +compatible with borg 1.x \fBborg serve\fP\&. .IP \(bu 2 -Being started by some other means (not by the borg client) as a long\-running socket -server to be used for borg clients using a socket://... repository (see the \fI\-\-socket\fP -option if you do not want to use the default path for the socket and PID file). +\fB\-\-rest\fP: serve a \fBcurrent\fP (non\-legacy) repository as the server\-side component of +a \fBrest://\fP repository, talking HTTP over stdio. The repository to serve is given via +\fB\-\-backend FILE:\fP\&. A borg client using a \fBrest://\fP repository starts this +automatically (over SSH if a host is given). .UNINDENT .sp -Please note that \fIborg serve\fP does not support providing a specific repository via the -\fI\-\-repo\fP option or the \fIBORG_REPO\fP environment variable. It is always the borg client that -specifies the repository to use when communicating with \fIborg serve\fP\&. +Please note that, in legacy mode, \fIborg serve\fP does not support providing a specific +repository via the \fI\-\-repo\fP option or the \fIBORG_REPO\fP environment variable \- it is the +borg client that specifies the repository to use. .sp The \-\-permissions option enforces repository permissions: .INDENT 0.0 @@ -76,6 +78,12 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS options .INDENT 0.0 .TP +.B \-\-rest +serve a current (non\-legacy) repository as a rest:// server (HTTP over stdio). Requires \-\-backend. Without this option, a legacy (borg 1.x) repository is served. +.TP +.BI \-\-backend \ BACKEND_URL +(with \-\-rest) backend URL of the repository to serve, e.g. \%\&. +.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 subdirectories is granted implicitly; PATH does not need to point directly to a repository. .TP diff --git a/docs/man/borg-tag.1 b/docs/man/borg-tag.1 index f2a4e68f51..76bc66228b 100644 --- a/docs/man/borg-tag.1 +++ b/docs/man/borg-tag.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-tag" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-tag" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-tag \- Manage tags. .SH SYNOPSIS diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index b09928518b..7368985c5c 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-transfer" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-transfer" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS @@ -71,15 +71,15 @@ borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run # check! .EE .UNINDENT .UNINDENT -.SS Data migration / upgrade from borg 1.x +.SS Data migration / upgrade from Borg 1.x .sp -To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar +To migrate your Borg 1.x archives into a related, new Borg 2 repository, usage is quite similar to the above, but you need the \fB\-\-from\-borg1\fP option: .INDENT 0.0 .INDENT 3.5 .sp .EX -borg \-\-repo=DST_REPO repocreate \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO \-\-from\-borg1 +borg \-\-repo=DST_REPO repo\-create \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO \-\-from\-borg1 # to continue using lz4 compression as you did in SRC_REPO: borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e @@ -150,55 +150,98 @@ consider archives older than (now \- TIMESPAN), e.g., 7d or 12m. consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m. .UNINDENT .SH EXAMPLES +.sp +To keep the following examples short and readable, we export the repository +locations and passphrases first: .INDENT 0.0 .INDENT 3.5 .sp .EX -# 0. Have Borg 2.0 installed on the client AND server; have a b12 repository copy for testing. +export BORG_REPO=ssh://borg2@borgbackup/./tests/b20 +export BORG_PASSPHRASE=\(aqyour\-borg2\-repo\-passphrase\(aq +export BORG_OTHER_REPO=ssh://borg2@borgbackup/./tests/b1x +export BORG_OTHER_PASSPHRASE=\(aqyour\-borg1\-repo\-passphrase\(aq +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +# Borg 1.x repository \-> Borg 2.0 repository (hmac\-sha256 \-> hmac\-sha256, keeping the same chunk ID algorithm) + +# 0. Have Borg 2.0 installed on the client AND server; have a Borg 1.x repository copy for testing. # 1. Create a new \(dqrelated\(dq repository: -# Here, the existing Borg 1.2 repository used repokey\-blake2 (and AES\-CTR mode), -# thus we use repokey\-blake2\-aes\-ocb for the new Borg 2.0 repository. -# Staying with the same chunk ID algorithm (BLAKE2) and with the same -# key material (via \-\-other\-repo ) will make deduplication work +# Here, the existing Borg 1.x repository used repokey (and AES\-CTR mode), +# thus we use aes256\-ocb for the new Borg 2.0 repository. +# Staying with the same chunk ID algorithm (hmac\-sha256) and with the same +# key material (via BORG_OTHER_REPO) will make deduplication work # between old archives (copied with borg transfer) and future ones. # The AEAD cipher does not matter (everything must be re\-encrypted and -# re\-authenticated anyway); you could also choose repokey\-blake2\-chacha20\-poly1305. -# In case your old Borg repository did not use BLAKE2, just remove the \(dq\-blake2\(dq. -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 repo\-create \e - \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-e repokey\-blake2\-aes\-ocb +# re\-authenticated anyway); you could also choose chacha20\-poly1305. +$ borg repo\-create \-e aes256\-ocb + +# 2. Check what and how much it would transfer: +$ borg transfer \-\-from\-borg1 \-\-dry\-run + +# 3. Transfer (copy) archives from the old repository into the new repository (takes time and space!): +$ borg transfer \-\-from\-borg1 + +# 4. Check whether we have everything (same as step 2): +$ borg transfer \-\-from\-borg1 \-\-dry\-run +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +# Borg 1.x repository \-> Borg 2.0 repository (blake2 \-> blake3, changing the chunk ID algorithm) + +# 0. Have Borg 2.0 installed on the client AND server; have a Borg 1.x repository copy for testing. + +# 1. Create a new \(dqrelated\(dq repository: +# Here, the existing Borg 1.x repository used repokey\-blake2 (and AES\-CTR mode), +# thus we use aes256\-ocb with \-\-id\-hash blake3 for the new Borg 2.0 repository. +# We need to change from blake2 to blake3, because blake2 is not supported +# for borg2 repos (blake3 is much faster). Because we change how chunk IDs are +# computed, we need to re\-chunk everything while doing the transfer. +# The chunker parameters you provide here should be the same as you will +# use for all future Borg 2.0 archives. +# The AEAD cipher does not matter (everything must be re\-encrypted and +# re\-authenticated anyway); you could also choose \-e chacha20\-poly1305 \-i blake3. +$ borg repo\-create \-e aes256\-ocb \-i blake3 +$ export CHUNKER_PARAMS=\(dqbuzhash64,19,23,21,4095\(dq # 2. Check what and how much it would transfer: -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e - \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run +$ borg transfer \-\-from\-borg1 \-\-chunker\-params=$CHUNKER_PARAMS \-\-dry\-run # 3. Transfer (copy) archives from the old repository into the new repository (takes time and space!): -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e - \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 +$ borg transfer \-\-from\-borg1 \-\-chunker\-params=$CHUNKER_PARAMS # 4. Check whether we have everything (same as step 2): -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e - \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run +$ borg transfer \-\-from\-borg1 \-\-chunker\-params=$CHUNKER_PARAMS \-\-dry\-run .EE .UNINDENT .UNINDENT -.SS Keyfile considerations when upgrading from borg 1.x +.SS Keyfile considerations when upgrading from Borg 1.x .sp -If you are using a \fBkeyfile\fP encryption mode (not \fBrepokey\fP), borg 2 -may not automatically find your borg 1.x key file, because the default +If you are using a \fBkeyfile\fP encryption mode (not \fBrepokey\fP), Borg 2 +may not automatically find your Borg 1.x key file, because the default key file directory has changed on some platforms due to the switch to the platformdirs \% library. .sp -On \fBLinux\fP, there is typically no change \-\- both borg 1.x and borg 2 +On \fBLinux\fP, there is typically no change \-\- both Borg 1.x and Borg 2 use \fB~/.config/borg/keys/\fP\&. .sp -On \fBmacOS\fP, borg 1.x stored key files in \fB~/.config/borg/keys/\fP, -but borg 2 defaults to \fB~/Library/Application Support/borg/keys/\fP\&. +On \fBmacOS\fP, Borg 1.x stored key files in \fB~/.config/borg/keys/\fP, +but Borg 2 defaults to \fB~/Library/Application Support/borg/keys/\fP\&. .sp -On \fBWindows\fP, borg 1.x used XDG\-style paths (e.g. \fB~/.config/borg/keys/\fP), -while borg 2 defaults to \fBC:\eUsers\e\eAppData\eRoaming\eborg\ekeys\e\fP\&. +On \fBWindows\fP, Borg 1.x used XDG\-style paths (e.g. \fB~/.config/borg/keys/\fP), +while Borg 2 defaults to \fBC:\eUsers\e\eAppData\eRoaming\eborg\ekeys\e\fP\&. .sp -If borg 2 cannot find your key file, you have several options: +If Borg 2 cannot find your key file, you have several options: .INDENT 0.0 .IP 1. 3 \fBCopy the key file\fP from the old location to the new one. @@ -223,8 +266,8 @@ export BORG_KEY_FILE=~/.config/borg/keys/your_key_file .UNINDENT .UNINDENT .IP 4. 3 -\fBSet BORG_BASE_DIR\fP to force borg 2 to use the same base directory -as borg 1.x: +\fBSet BORG_BASE_DIR\fP to force Borg 2 to use the same base directory +as Borg 1.x: .INDENT 3.0 .INDENT 3.5 .sp @@ -234,8 +277,8 @@ export BORG_BASE_DIR=$HOME .UNINDENT .UNINDENT .sp -This makes borg 2 use \fB$HOME/.config/borg\fP, \fB$HOME/.cache/borg\fP, -etc., matching borg 1.x behaviour on all platforms. +This makes Borg 2 use \fB$HOME/.config/borg\fP, \fB$HOME/.cache/borg\fP, +etc., matching Borg 1.x behavior on all platforms. .UNINDENT .sp See \fIenv_vars\fP for more details on directory environment variables. diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 0cdd4460f0..7a16881510 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-umount" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-umount" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-umount \- Unmounts the FUSE filesystem. .SH SYNOPSIS diff --git a/docs/man/borg-undelete.1 b/docs/man/borg-undelete.1 index a169be56e5..338e5245cb 100644 --- a/docs/man/borg-undelete.1 +++ b/docs/man/borg-undelete.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-undelete" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-undelete" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-undelete \- Undeletes archives. .SH SYNOPSIS diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1 index a38e36fd20..c3007578e1 100644 --- a/docs/man/borg-version.1 +++ b/docs/man/borg-version.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-version" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-version" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-version \- Displays the Borg client and server versions. .SH SYNOPSIS @@ -38,11 +38,11 @@ borg [common options] version [options] .sp This command displays the Borg client and server versions. .sp -If a local repository is given, the client code directly accesses the repository, -so the client version is also shown as the server version. +For current repositories the client code directly accesses the repository (also for +rest:// repositories), so the client version is shown as the server version, too. .sp -If a remote repository is given (e.g., ssh:), the remote Borg is queried, and -its version is displayed as the server version. +If a legacy (borg 1.x / v1) repository is given via ssh: together with \-\-from\-borg1, +the remote Borg is queried, and its version is displayed as the server version. .sp Examples: .INDENT 0.0 @@ -53,8 +53,8 @@ Examples: $ borg version /mnt/backup 1.4.0a / 1.4.0a -# remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release) -$ borg version ssh://borg@borgbackup:repo +# legacy remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release) +$ borg version \-\-from\-borg1 ssh://borg@borgbackup:repo 1.4.0a / 1.2.7 .EE .UNINDENT diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index e986254fda..6341088833 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg-with-lock" "1" "2026-03-15" "" "borg backup tool" +.TH "borg-with-lock" "1" "2026-06-16" "" "borg backup tool" .SH Name borg-with-lock \- Runs a user-specified command with the repository lock held. .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 155fce027d..93beb5aa7c 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -29,7 +29,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borg" "1" "2026-03-15" "" "borg backup tool" +.TH "borg" "1" "2026-06-16" "" "borg backup tool" .SH Name borg \- deduplicating and encrypting backup tool .SH SYNOPSIS @@ -61,7 +61,7 @@ Before a backup can be made, a repository has to be initialized: .INDENT 3.5 .sp .EX -$ borg \-r /path/to/repo repo\-create \-\-encryption=repokey\-aes\-ocb +$ borg \-r /path/to/repo repo\-create \-\-encryption=aes\-ocb .EE .UNINDENT .UNINDENT @@ -210,7 +210,13 @@ expanded by your shell). .sp Note: You may also prepend \fBfile://\fP to a filesystem path to use URL style. .sp -\fBRemote repositories\fP accessed via SSH \%: +\fBRemote repositories\fP accessed via SSH \% (REST http over stdio): +.sp +\fBrest://user@host:port//abs/path/to/repo\fP — absolute path +.sp +\fBrest://user@host:port/rel/path/to/repo\fP — path relative to the current directory +.sp +\fBRemote repositories\fP accessed via SSH \% (legacy borg RPC protocol): .sp \fBssh://user@host:port//abs/path/to/repo\fP — absolute path .sp @@ -410,7 +416,7 @@ If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence. When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for. This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also be checked. -Main use case for this is to fully automate \fBborg change\-passphrase\fP\&. +Main use case for this is to fully automate \fBborg key change\-passphrase\fP\&. .TP .B BORG_DISPLAY_PASSPHRASE When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories. @@ -600,8 +606,8 @@ default directory locations. This means that default paths are \fBplatform\-spec \fBLinux\fP: Uses XDG Base Directory Specification paths (e.g., \fB~/.config/borg\fP, \fB~/.cache/borg\fP, \fB~/.local/share/borg\fP). XDG env var \% variables are honoured. .IP \(bu 2 -\fBmacOS\fP: Uses native macOS directories (e.g., \fB~/Library/Application Support/borg\fP, -\fB~/Library/Caches/borg\fP). XDG env var \% variables are \fBnot\fP honoured. +\fBmacOS\fP: Uses native macOS directories by default (e.g., \fB~/Library/Application Support/borg\fP, +\fB~/Library/Caches/borg\fP). XDG env var \% variables are honoured if set. .IP \(bu 2 \fBWindows\fP: Uses Windows AppData directories (e.g., \fBC:\eUsers\e\eAppData\eRoaming\eborg\fP, \fBC:\eUsers\e\eAppData\eLocal\eborg\fP). XDG env var \% variables are \fBnot\fP honoured. @@ -698,7 +704,7 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt .B BORG_CACHE_DIR Defaults to the platform\-specific cache directory (see table above). If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. -On Linux, XDG env var \% \fBXDG_CACHE_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. +On Linux and macOS, XDG env var \% \fBXDG_CACHE_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains the local cache and might need a lot of space for dealing with big repositories. Make sure you\(aqre aware of the associated security aspects of the cache location: \fIcache_security\fP @@ -706,21 +712,21 @@ security aspects of the cache location: \fIcache_security\fP .B BORG_CONFIG_DIR Defaults to the platform\-specific config directory (see table above). If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. -On Linux, XDG env var \% \fBXDG_CONFIG_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. +On Linux and macOS, XDG env var \% \fBXDG_CONFIG_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains all borg configuration directories, see the FAQ for a security advisory about the data in this directory: \fIhome_config_borg\fP .TP .B BORG_DATA_DIR Defaults to the platform\-specific data directory (see table above). If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.local/share/borg\fP\&. -On Linux, XDG env var \% \fBXDG_DATA_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. +On Linux and macOS, XDG env var \% \fBXDG_DATA_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains all borg data directories, see the FAQ for a security advisory about the data in this directory: \fIhome_data_borg\fP .TP .B BORG_RUNTIME_DIR Defaults to the platform\-specific runtime directory (see table above). If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. -On Linux, XDG env var \% \fBXDG_RUNTIME_DIR\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. +On Linux and macOS, XDG env var \% \fBXDG_RUNTIME_DIR\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains borg runtime files, like e.g. the socket file. .TP .B BORG_SECURITY_DIR diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index 342e0b0672..358bebb82b 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "borgfs" "1" "2026-03-15" "" "borg backup tool" +.TH "borgfs" "1" "2026-06-16" "" "borg backup tool" .SH Name borgfs \- Mounts an archive or an entire repository as a FUSE filesystem. .SH SYNOPSIS diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index a1c56f94f8..c5e144e70f 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -134,13 +134,12 @@ repository files. Enabling partial repository checks excludes archive checks for the same reason. Therefore, partial checks may be useful only with very large repositories where a full check would take too long. -The ``--verify-data`` option will perform a full integrity verification (as -opposed to checking just the xxh64) of data, which means reading the -data from the repository, decrypting and decompressing it. It is a complete -cryptographic verification and hence very time-consuming, but will detect any -accidental and malicious corruption. Tamper-resistance is only guaranteed for -encrypted repositories against attackers without access to the keys. You cannot -use ``--verify-data`` with ``--repository-only``. +The ``--verify-data`` option will perform a full integrity verification of data, +which means reading the data from the repository, decrypting and decompressing it. +It is a complete cryptographic verification and hence very time-consuming, but +will detect any accidental and malicious corruption. Tamper-resistance is only +guaranteed for encrypted repositories against attackers without access to the keys. +You cannot use ``--verify-data`` with ``--repository-only``. The ``--find-lost-archives`` option will also scan the whole repository, but tells Borg to search for lost archive metadata. If Borg encounters any archive diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 096d7d89b8..27bdb7c86d 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -69,6 +69,8 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-dataless`` | exclude files flagged DATALESS (macOS: placeholder files whose content is not materialized locally, e.g. not-downloaded cloud storage files) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Filesystem options** | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. | @@ -156,6 +158,7 @@ borg create --exclude-caches exclude directories that contain a CACHEDIR.TAG file (https://www.bford.info/cachedir/spec.html) --exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive + --exclude-dataless exclude files flagged DATALESS (macOS: placeholder files whose content is not materialized locally, e.g. not-downloaded cloud storage files) Filesystem options @@ -344,6 +347,22 @@ Other flags used include: - 'i' = backup data was read from standard input (stdin) - '?' = missing status code (if you see this, please file a bug report!) +Errors and (incomplete) archives +++++++++++++++++++++++++++++++++ + +If an error happens during archive creation (e.g. some file could not be read +due to a permission error or some other OS error), borg will log a warning or +an error (depending on the type of issue) and continue with the next item. + +At the end of the backup, if there were any such issues, borg will exit with +a non-zero exit code (usually 1 for warnings). + +**The archive is still saved even if warnings or errors occurred**, but it will +only contain the data borg was able to read successfully. It is like a +checkpoint (see below), but with a user-given name. + +You should always check the backup logs and the exit code of the borg command. + Reading backup data from stdin ++++++++++++++++++++++++++++++ diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index 7eb5d353eb..7a00cdbd59 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -100,7 +100,7 @@ The FORMAT specifier syntax +++++++++++++++++++++++++++ The ``--format`` option uses Python's `format string syntax -`_. +`_. Examples: :: diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index d569db32a9..83ca221fa1 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -33,6 +33,10 @@ Be careful, your patterns must match the archived paths: start with ``src``. - On native Windows, archived absolute paths look like ``C/Windows/System32``. +- When using the slashdot hack, patterns match against the unstripped path, + i.e., when you back up ``/this/gets/stripped/./this/gets/archived``, + patterns must match ``this/gets/stripped/this/gets/archived``. + Borg supports different pattern styles. To define a non-default style for a specific pattern, prefix it with two characters followed by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``). @@ -368,11 +372,11 @@ and ``--remote-path`` values support these placeholders: {now} The current local date and time, by default in ISO-8601 format. - You can also supply your own `format string `_, e.g. {now:%Y-%m-%d_%H:%M:%S} + You can also supply your own `format string `_, e.g. {now:%Y-%m-%d_%H:%M:%S} {utcnow} The current UTC date and time, by default in ISO-8601 format. - You can also supply your own `format string `_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S} + You can also supply your own `format string `_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S} {user} The user name (or UID, if no name is available) of the user running borg. diff --git a/docs/usage/key_change-location.rst.inc b/docs/usage/key_change-location.rst.inc index 99010e90d0..443a59c213 100644 --- a/docs/usage/key_change-location.rst.inc +++ b/docs/usage/key_change-location.rst.inc @@ -53,7 +53,7 @@ Description Change the location of a Borg key. The key can be stored at different locations: - keyfile: locally, usually in the home directory -- repokey: inside the repository (in the repository config) +- repokey: inside the repository Please note: diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index 8b57196ddd..1e0d42a2ce 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -12,21 +12,25 @@ borg key export .. class:: borg-options-table - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | | ``PATH`` | where to store the backup | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | **options** | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | | ``--paper`` | Create an export suitable for printing and later type-in | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | | ``--qr-html`` | Create an HTML file suitable for printing and later type-in or QR scan | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------+------------------------------------------------------------------------+ + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | | ``PATH`` | where to store the backup | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | **options** | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | | ``--label LABEL`` | export the borg key with this label | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | | ``--key ID`` | export the borg key with this id (or unique id prefix) | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | | ``--paper`` | Create an export suitable for printing and later type-in | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | | ``--qr-html`` | Create an HTML file suitable for printing and later type-in or QR scan | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+-------------------+------------------------------------------------------------------------+ .. raw:: html @@ -43,6 +47,8 @@ borg key export options + --label LABEL export the borg key with this label + --key ID export the borg key with this id (or unique id prefix) --paper Create an export suitable for printing and later type-in --qr-html Create an HTML file suitable for printing and later type-in or QR scan @@ -75,6 +81,12 @@ Note that the backup produced does not include the passphrase itself repository, one needs both the exported key and the original passphrase. Keep the exported key and the passphrase at safe places. +A repository may have more than one borg key (each protected by its own +passphrase, see ``borg key add``). Select which borg key to export with +``--label`` or ``--key`` (its key id or a unique prefix, see +``borg key list``). If the repository has only a single borg key, no +selector is required. + There are three backup formats. The normal backup format is suitable for digital storage as a file. The ``--paper`` backup format is optimized for printing and typing in while importing, with per line checks to diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc index cd778b1a1a..07bb38ad10 100644 --- a/docs/usage/key_import.rst.inc +++ b/docs/usage/key_import.rst.inc @@ -12,19 +12,21 @@ borg key import .. class:: borg-options-table - +-------------------------------------------------------+-------------+----------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+-------------+----------------------------------------------------------+ - | | ``PATH`` | path to the backup ('-' to read from stdin) | - +-------------------------------------------------------+-------------+----------------------------------------------------------+ - | **options** | - +-------------------------------------------------------+-------------+----------------------------------------------------------+ - | | ``--paper`` | interactively import from a backup done with ``--paper`` | - +-------------------------------------------------------+-------------+----------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+-------------+----------------------------------------------------------+ + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | path to the backup ('-' to read from stdin) | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | | ``--paper`` | interactively import from a backup done with ``--paper`` | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | | ``--key-location LOCATION`` | where to store the imported key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory) | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -42,6 +44,7 @@ borg key import options --paper interactively import from a backup done with ``--paper`` + --key-location LOCATION where to store the imported key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory) :ref:`common_options` diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index c9c99f7806..e886686166 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -90,7 +90,7 @@ The FORMAT specifier syntax +++++++++++++++++++++++++++ The ``--format`` option uses Python's `format string syntax -`_. +`_. Examples: :: @@ -152,7 +152,6 @@ Keys available only when listing files in an archive: - sha3_384 - sha3_512 - sha512 -- xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!) - archiveid: internal ID of the archive - archivename: name of the archive diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 00c048a90a..0dac794787 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -12,61 +12,63 @@ borg prune .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``NAME`` | specify the archive name | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change the repository | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--list`` | output a verbose list of archives it keeps/prunes | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--short`` | use a less wide archive part format | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--list-pruned`` | output verbose list of archives it prunes | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--list-kept`` | output verbose list of archives it keeps | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--keep-within INTERVAL`` | keep all archives within this time interval | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--keep-minutely`` | number of minutely archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-d``, ``--keep-daily`` | number of daily archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ - | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. | - +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change the repository | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list`` | output a verbose list of archives it keeps/prunes | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | use a less wide archive part format | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list-pruned`` | output verbose list of archives it prunes | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list-kept`` | output verbose list of archives it keeps | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-within INTERVAL`` | keep all archives within this time interval | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-minutely`` | number of minutely archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-d``, ``--keep-daily`` | number of daily archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -89,6 +91,7 @@ borg prune --list-pruned output verbose list of archives it prunes --list-kept output verbose list of archives it keeps --format FORMAT specify format for the archive part (default: "{archive:<36} {time} [{id}]") + --json Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. --keep-within INTERVAL keep all archives within this time interval --keep-last, --keep-secondly number of secondly archives to keep --keep-minutely number of minutely archives to keep diff --git a/docs/usage/repo-list.rst.inc b/docs/usage/repo-list.rst.inc index c30ae247b4..3b2b17df21 100644 --- a/docs/usage/repo-list.rst.inc +++ b/docs/usage/repo-list.rst.inc @@ -17,6 +17,8 @@ borg repo-list +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--short`` | only print the archive IDs, nothing else | +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--from-borg1`` | repository is Borg 1.x | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") | +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--json`` | Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | @@ -60,6 +62,7 @@ borg repo-list options --short only print the archive IDs, nothing else + --from-borg1 repository is Borg 1.x --format FORMAT specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") --json Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. @@ -90,7 +93,7 @@ The FORMAT specifier syntax +++++++++++++++++++++++++++ The ``--format`` option uses Python's `format string syntax -`_. +`_. Examples: :: diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc index 1a8b7384d3..3f6cb0cf66 100644 --- a/docs/usage/serve.rst.inc +++ b/docs/usage/serve.rst.inc @@ -15,6 +15,10 @@ borg serve +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **options** | +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--rest`` | serve a current (non-legacy) repository as a rest:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served. | + +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--backend BACKEND_URL`` | (with --rest) backend URL of the repository to serve, e.g. FILE:/path/to/repo. | + +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--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 subdirectories is granted implicitly; PATH does not need to point directly to a repository. | +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--restrict-to-repository PATH`` | Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. | @@ -39,6 +43,8 @@ borg serve options + --rest serve a current (non-legacy) repository as a rest:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served. + --backend BACKEND_URL (with --rest) backend URL of the repository to serve, e.g. FILE:/path/to/repo. --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 subdirectories is granted implicitly; PATH does not need to point directly to a repository. --restrict-to-repository PATH Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. --permissions Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. @@ -50,21 +56,23 @@ borg serve Description ~~~~~~~~~~~ -This command starts a repository server process. +This command starts a repository server process. It is usually started automatically via +SSH by a borg client and runs until that SSH connection is terminated. -`borg serve` currently supports: +It operates in one of two modes: -- Being automatically started via SSH when the borg client uses an ssh://... - remote repository. In this mode, `borg serve` will run until that SSH connection - is terminated. +- default (no option): serve a **legacy** (borg 1.x / v1) repository using the legacy + RPC protocol. This is used e.g. for ``borg transfer --from-borg1`` and is command-line + compatible with borg 1.x ``borg serve``. -- Being started by some other means (not by the borg client) as a long-running socket - server to be used for borg clients using a socket://... repository (see the `--socket` - option if you do not want to use the default path for the socket and PID file). +- ``--rest``: serve a **current** (non-legacy) repository as the server-side component of + a ``rest://`` repository, talking HTTP over stdio. The repository to serve is given via + ``--backend FILE:``. A borg client using a ``rest://`` repository starts this + automatically (over SSH if a host is given). -Please note that `borg serve` does not support providing a specific repository via the -`--repo` option or the `BORG_REPO` environment variable. It is always the borg client that -specifies the repository to use when communicating with `borg serve`. +Please note that, in legacy mode, `borg serve` does not support providing a specific +repository via the `--repo` option or the `BORG_REPO` environment variable - it is the +borg client that specifies the repository to use. The --permissions option enforces repository permissions: diff --git a/docs/usage/transfer.rst.inc b/docs/usage/transfer.rst.inc index 3b52df2934..7ffa76bb7e 100644 --- a/docs/usage/transfer.rst.inc +++ b/docs/usage/transfer.rst.inc @@ -123,13 +123,13 @@ Transfer borg2 archives into a related other borg2 repository:: borg --repo=DST_REPO transfer --other-repo=SRC_REPO # do it! borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run # check! anything left? -Data migration / upgrade from borg 1.x +Data migration / upgrade from Borg 1.x ++++++++++++++++++++++++++++++++++++++ -To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar +To migrate your Borg 1.x archives into a related, new Borg 2 repository, usage is quite similar to the above, but you need the ``--from-borg1`` option:: - borg --repo=DST_REPO repocreate --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1 + borg --repo=DST_REPO repo-create --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1 # to continue using lz4 compression as you did in SRC_REPO: borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \ diff --git a/docs/usage/version.rst.inc b/docs/usage/version.rst.inc index 2d5a9c22ed..711addc4bf 100644 --- a/docs/usage/version.rst.inc +++ b/docs/usage/version.rst.inc @@ -38,11 +38,11 @@ Description This command displays the Borg client and server versions. -If a local repository is given, the client code directly accesses the repository, -so the client version is also shown as the server version. +For current repositories the client code directly accesses the repository (also for +rest:// repositories), so the client version is shown as the server version, too. -If a remote repository is given (e.g., ssh:), the remote Borg is queried, and -its version is displayed as the server version. +If a legacy (borg 1.x / v1) repository is given via ssh: together with --from-borg1, +the remote Borg is queried, and its version is displayed as the server version. Examples:: @@ -50,8 +50,8 @@ Examples:: $ borg version /mnt/backup 1.4.0a / 1.4.0a - # remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release) - $ borg version ssh://borg@borgbackup:repo + # legacy remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release) + $ borg version --from-borg1 ssh://borg@borgbackup:repo 1.4.0a / 1.2.7 Due to the version tuple format used in Borg client/server negotiation, only