mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2025-03-13 07:33:47 +00:00
Code Issues Releases Wiki Activity

man pages: add borg(1) master/intro page

Browse source
This commit is contained in:
Marian Beermann 2017-02-05 21:32:24 +01:00
parent 15dfaae223
commit fa24e1f38f
40 changed files with 1264 additions and 463 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/man/borg-break-lock.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BREAK-LOCK 1 "2017-02-05" "" "borg backup tool"
.TH BORG-BREAK-LOCK 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.

2
docs/man/borg-change-passphrase.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-change-passphrase \- Change repository key file passphrase
.

2
docs/man/borg-check.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2017-02-05" "" "borg backup tool"
.TH BORG-CHECK 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.

2
docs/man/borg-common.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMMON 1 "2017-02-05" "" "borg backup tool"
.TH BORG-COMMON 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.

2
docs/man/borg-compression.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2017-02-05" "" "borg backup tool"
.TH BORG-COMPRESSION 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.

13
docs/man/borg-create.1
View file

@ -100,10 +100,10 @@ read exclude patterns from EXCLUDEFILE, one per line
exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
.TP
.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files
keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
.UNINDENT
.SS Filesystem options
.INDENT 0.0
@ -216,15 +216,12 @@ $ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
.fi
.UNINDENT
.UNINDENT
.SS Notes
.INDENT 0.0
.IP \(bu 2
the \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will
.SH NOTES
.sp
The \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use \-\-exclude
\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for
more information.
.UNINDENT
.SH NOTES
.SS Item flags
.sp
\fB\-\-list\fP outputs a list of all files, directories and other

2
docs/man/borg-delete.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-DELETE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.

2
docs/man/borg-diff.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2017-02-05" "" "borg backup tool"
.TH BORG-DIFF 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.

2
docs/man/borg-extract.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-EXTRACT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.

2
docs/man/borg-info.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INFO 1 "2017-02-05" "" "borg backup tool"
.TH BORG-INFO 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.

21
docs/man/borg-init.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-INIT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.
@ -82,32 +82,33 @@ You can change your passphrase for existing repos at any time, it won\(aqt affec
the encryption/decryption key or other secrets.
.SS Encryption modes
.sp
repokey and keyfile use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
is HMAC\-SHA256 as well (with a separate key).
These modes are compatible with borg 1.0.x.
.sp
repokey\-blake2 and keyfile\-blake2 are also authenticated encryption modes,
\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
hash is a keyed BLAKE2b\-256 hash.
These modes are new and not compatible with borg 1.0.x.
These modes are new and \fInot\fP compatible with borg 1.0.x.
.sp
"authenticated" mode uses no encryption, but authenticates repository contents
\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it
as chunk ID hash). The key is stored like repokey.
This mode is new and not compatible with borg 1.0.x.
.sp
"none" mode uses no encryption and no authentication. It uses sha256 as chunk
\fInone\fP mode uses no encryption and no authentication. It uses sha256 as chunk
ID hash. Not recommended, rather consider using an authenticated or
authenticated/encrypted mode.
This mode is compatible with borg 1.0.x.
.sp
Hardware acceleration will be used automatically.
.sp
On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw
accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs.
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware\-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64bit CPUs,
which makes \fIauthenticated\fP faster than \fInone\fP\&.
.sp
On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster
On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
than BLAKE2b\-256 there.
.SH OPTIONS
.sp
@ -122,7 +123,7 @@ repository to create
.INDENT 0.0
.TP
.B \-e\fP,\fB \-\-encryption
select encryption key mode (default: "None")
select encryption key mode
.TP
.B \-a\fP,\fB \-\-append\-only
create an append\-only mode repository

2
docs/man/borg-key-change-passphrase.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.

2
docs/man/borg-key-export.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-EXPORT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-KEY-EXPORT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.

2
docs/man/borg-key-import.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-IMPORT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-KEY-IMPORT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.

2
docs/man/borg-key-migrate-to-repokey.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-05" "" "borg backup tool"
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.

47
docs/man/borg-key.1 Normal file
View file

@ -0,0 +1,47 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
borg key export ...
borg key import ...
borg key change\-passphrase ...
borg key migrate\-to\-repokey ...
.fi
.sp
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-migrate\-to\-repokey(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

2
docs/man/borg-mount.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-MOUNT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.

2
docs/man/borg-patterns.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2017-02-05" "" "borg backup tool"
.TH BORG-PATTERNS 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.

2
docs/man/borg-placeholders.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2017-02-05" "" "borg backup tool"
.TH BORG-PLACEHOLDERS 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.

2
docs/man/borg-prune.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PRUNE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-PRUNE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.

2
docs/man/borg-recreate.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RECREATE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-RECREATE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.

2
docs/man/borg-rename.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RENAME 1 "2017-02-05" "" "borg backup tool"
.TH BORG-RENAME 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.

2
docs/man/borg-serve.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-SERVE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-SERVE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.

2
docs/man/borg-umount.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UMOUNT 1 "2017-02-05" "" "borg backup tool"
.TH BORG-UMOUNT 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.

2
docs/man/borg-upgrade.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UPGRADE 1 "2017-02-05" "" "borg backup tool"
.TH BORG-UPGRADE 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.

2
docs/man/borg-with-lock.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-WITH-LOCK 1 "2017-02-05" "" "borg backup tool"
.TH BORG-WITH-LOCK 1 "2017-02-11" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.

567
docs/man/borg.1 Normal file
View file

@ -0,0 +1,567 @@
.\" Man page generated from reStructuredText.
.
.TH BORG 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
borg <command> [options] [arguments]
.SH DESCRIPTION
.\" we don't include the README.rst here since we want to keep this terse.
.
.sp
BorgBackup (short: Borg) is a deduplicating backup program.
Optionally, it supports compression and authenticated encryption.
.sp
The main goal of Borg is to provide an efficient and secure way to backup data.
The data deduplication technique used makes Borg suitable for daily backups
since only changes are stored.
The authenticated encryption technique makes it suitable for backups to not
fully trusted targets.
.sp
Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection
of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not
distinguish archives from each other in a any way other than their name,
it does not matter when or where archives where created (eg. different hosts).
.SH EXAMPLES
.SS A step\-by\-step example
.INDENT 0.0
.IP 1. 3
Before a backup can be made a repository has to be initialized:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg init \-\-encryption=repokey /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
\fIMonday\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create /path/to/repo::Monday ~/src ~/Documents
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
The next day create a new archive called \fITuesday\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This backup will be a lot quicker and a lot smaller since only new never
before seen data is stored. The \fB\-\-stats\fP option causes Borg to
output statistics about the newly created archive such as the amount of unique
data (not shared with other archives):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
Time (start): Tue, 2016\-02\-16 18:15:11
Time (end): Tue, 2016\-02\-16 18:15:11
Duration: 0.19 seconds
Number of files: 127
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Original size Compressed size Deduplicated size
This archive: 4.16 MB 4.17 MB 26.78 kB
All archives: 8.33 MB 8.34 MB 4.19 MB
Unique chunks Total chunks
Chunk index: 132 261
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
List all archives in the repository:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg list /path/to/repo
Monday Mon, 2016\-02\-15 19:14:44
Tuesday Tue, 2016\-02\-16 19:15:11
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
List the contents of the \fIMonday\fP archive:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg list /path/to/repo::Monday
drwxr\-xr\-x user group 0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
\-rw\-r\-\-r\-\- user group 7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 6. 3
Restore the \fIMonday\fP archive by extracting the files relative to the current directory:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg extract /path/to/repo::Monday
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 3
Recover disk space by manually deleting the \fIMonday\fP archive:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg delete /path/to/repo::Monday
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Borg is quiet by default (it works on WARNING log level).
You can use options like \fB\-\-progress\fP or \fB\-\-list\fP to get specific
reports during command execution. You can also add the \fB\-v\fP (or
\fB\-\-verbose\fP or \fB\-\-info\fP) option to adjust the log level to INFO to
get other informational messages.
.UNINDENT
.UNINDENT
.SH NOTES
.SS Repository URLs
.sp
\fBLocal filesystem\fP (or locally mounted network filesystem):
.sp
\fB/path/to/repo\fP \- filesystem path to repo directory, absolute path
.sp
\fBpath/to/repo\fP \- filesystem path to repo directory, relative path
.sp
Also, stuff like \fB~/path/to/repo\fP or \fB~other/path/to/repo\fP works (this is
expanded by your shell).
.sp
Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
.sp
\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
.sp
\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
.sp
\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
.sp
\fBRemote repositories with relative pathes\fP can be given using this syntax:
.sp
\fBuser@host:path/to/repo\fP \- path relative to current directory
.sp
\fBuser@host:~/path/to/repo\fP \- path relative to user\(aqs home directory
.sp
\fBuser@host:~other/path/to/repo\fP \- path relative to other\(aqs home directory
.sp
Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
\fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
.sp
\fBRemote repositories with relative pathes, alternative syntax with port\fP:
.sp
\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
.sp
\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
.sp
\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory
.sp
If you frequently need the same repo URL, it is a good idea to set the
\fBBORG_REPO\fP environment variable to set a default for the repo URL:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then just leave away the repo URL if only a repo URL is needed and you want
to use the default \- it will be read from BORG_REPO then.
.sp
Use \fB::\fP syntax to give the repo URL when syntax requires giving a positional
argument for the repo (e.g. \fBborg mount :: /mnt\fP).
.SS Repository / Archive Locations
.sp
Many commands want either a repository (just give the repo URL, see above) or
an archive location, which is a repo URL followed by \fB::archive_name\fP\&.
.sp
Archive names must not contain the \fB/\fP (slash) character. For simplicity,
maybe also avoid blanks or other characters that have special meaning on the
shell or in a filesystem (borg mount will use the archive name as directory
name).
.sp
If you have set BORG_REPO (see above) and an archive location is needed, use
\fB::archive_name\fP \- the repo URL part is then read from BORG_REPO.
.SS Type of log output
.sp
The log level of the builtin logging configuration defaults to WARNING.
This is because we want Borg to be mostly silent and only output
warnings, errors and critical messages, unless output has been requested
by supplying an option that implies output (eg, \-\-list or \-\-progress).
.sp
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
.sp
Use \fB\-\-debug\fP to set DEBUG log level \-
to get debug, info, warning, error and critical level output.
.sp
Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set INFO log level \-
to get info, warning, error and critical level output.
.sp
Use \fB\-\-warning\fP (default) to set WARNING log level \-
to get warning, error and critical level output.
.sp
Use \fB\-\-error\fP to set ERROR log level \-
to get error and critical level output.
.sp
Use \fB\-\-critical\fP to set CRITICAL log level \-
to get critical level output.
.sp
While you can set misc. log levels, do not expect that every command will
give different output on different log levels \- it\(aqs just a possibility.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Options \-\-critical and \-\-error are provided for completeness,
their usage is not recommended as you might miss important information.
.UNINDENT
.UNINDENT
.SS Return codes
.sp
Borg can exit with the following return codes (rc):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 = success (logged as INFO)
1 = warning (operation reached its normal end, but there were warnings \-
you should check the log, logged as WARNING)
2 = error (like a fatal error, a local or remote exception, the operation
did not reach its normal end, logged as ERROR)
128+N = killed by signal N (e.g. 137 == kill \-9)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
level as the last log entry.
.SS Environment Variables
.sp
Borg uses some environment variables for automation:
.INDENT 0.0
.TP
.B General:
.INDENT 7.0
.TP
.B BORG_REPO
When set, use the value to give the default repository location. If a command needs an archive
parameter, you can abbreviate as \fI::archive\fP\&. If a command needs a repository parameter, you
can either leave it away or abbreviate as \fI::\fP, if a positional parameter is required.
.TP
.B BORG_PASSPHRASE
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access a encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_NEW_PASSPHRASE
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 will be checked also.
Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
.TP
.B BORG_LOGGING_CONF
When set, use the given filename as \fI\%INI\fP\-style logging configuration.
.TP
.B BORG_RSH
When set, use this command instead of \fBssh\fP\&. This can be used to specify ssh options, such as
a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP for other options.
.TP
.B BORG_REMOTE_PATH
When set, use the given path/filename as remote path (default is "borg").
Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
.TP
.B BORG_FILES_CACHE_TTL
When set to a numeric value, this determines the maximum "time to live" for the files cache
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
The FAQ explains this more detailed in: \fIalways_chunking\fP
.TP
.B TMPDIR
where temporary files are stored (might need a lot of temporary space for some operations)
.UNINDENT
.TP
.B Some automatic "answerers" (if set, they automatically answer confirmation questions):
.INDENT 7.0
.TP
.B BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: Attempting to access a previously unknown unencrypted repository"
.TP
.B BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: The repository at location ... was previously located at ..."
.TP
.B BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "Warning: \(aqcheck \-\-repair\(aq is an experimental feature that might result in data loss."
.TP
.B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "You requested to completely DELETE the repository \fIincluding\fP all archives it contains:"
.TP
.B BORG_RECREATE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "recreate is an experimental feature."
.UNINDENT
.sp
Note: answers are case sensitive. setting an invalid answer value might either give the default
answer or ask you interactively, depending on whether retries are allowed (they by default are
allowed). So please test your scripts interactively before making them a non\-interactive script.
.TP
.B Directories and files:
.INDENT 7.0
.TP
.B BORG_KEYS_DIR
Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories.
.TP
.B BORG_KEY_FILE
When set, use the given filename as repository key file.
.TP
.B BORG_SECURITY_DIR
Default to \(aq~/.config/borg/security\(aq. This directory contains information borg uses to
track its usage of NONCES ("numbers used once" \- usually in encryption context) and other
security relevant data.
.TP
.B BORG_CACHE_DIR
Default to \(aq~/.cache/borg\(aq. This directory contains the local cache and might need a lot
of space for dealing with big repositories).
.UNINDENT
.TP
.B Building:
.INDENT 7.0
.TP
.B BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
.TP
.B BORG_LZ4_PREFIX
Adds given LZ4 header file directory to the default locations (setup.py).
.TP
.B BORG_LIBB2_PREFIX
Adds given prefix directory to the default locations. If a \(aqinclude/blake2.h\(aq is found Borg
will be linked against the system libb2 instead of a bundled implementation. (setup.py)
.UNINDENT
.UNINDENT
.sp
Please note:
.INDENT 0.0
.IP \(bu 2
be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety
.IP \(bu 2
also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions
(e.g. mode 600, root:root).
.UNINDENT
.SS File systems
.sp
We strongly recommend against using Borg (or any other database\-like
software) on non\-journaling file systems like FAT, since it is not
possible to assume any consistency in case of power failures (or a
sudden disconnect of an external drive or similar failures).
.sp
While Borg uses a data store that is resilient against these failures
when used on journaling file systems, it is not possible to guarantee
this with some hardware \-\- independent of the software used. We don\(aqt
know a list of affected hardware.
.sp
If you are suspicious whether your Borg repository is still consistent
and readable after one of the failures mentioned above occured, run
\fBborg check \-\-verify\-data\fP to make sure it is consistent.
.SS Units
.sp
To display quantities, Borg takes care of respecting the
usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so
\fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are
indicated using the \fI\%IEC binary prefixes\fP,
using powers of two (so \fBKiB\fP means 1024 bytes).
.SS Date and Time
.sp
We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and
HH:MM:SS (24h clock).
.sp
For more information about that, see: \fI\%https://xkcd.com/1179/\fP
.sp
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
.SS Resource Usage
.sp
Borg might use a lot of resources depending on the size of the data set it is dealing with.
.sp
If one uses Borg in a client/server way (with a ssh: repository),
the resource usage occurs in part on the client and in another part on the
server.
.sp
If one uses Borg as a single process (with a filesystem repo),
all the resource usage occurs in that one process, so just add up client +
server to get the approximate resource usage.
.INDENT 0.0
.TP
.B CPU client:
borg create: does chunking, hashing, compression, crypto (high CPU usage)
chunks cache sync: quite heavy on CPU, doing lots of hashtable operations.
borg extract: crypto, decompression (medium to high CPU usage)
borg check: similar to extract, but depends on options given.
borg prune / borg delete archive: low to medium CPU usage
borg delete repo: done on the server
It won\(aqt go beyond 100% of 1 core as the code is currently single\-threaded.
Especially higher zlib and lzma compression levels use significant amounts
of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
expensive (if not).
.TP
.B CPU server:
It usually doesn\(aqt need much CPU, it just deals with the key/value store
(repository) and uses the repository index for that.
.sp
borg check: the repository check computes the checksums of all chunks
(medium CPU usage)
borg delete repo: low CPU usage
.TP
.B CPU (only for client/server operation):
When using borg in a client/server way with a \fI\%ssh:\-type\fP repo, the ssh
processes used for the transport layer will need some CPU on the client and
on the server due to the crypto they are doing \- esp. if you are pumping
big amounts of data.
.TP
.B Memory (RAM) client:
The chunks index and the files index are read into memory for performance
reasons. Might need big amounts of memory (see below).
Compression, esp. lzma compression with high levels might need substantial
amounts of memory.
.TP
.B Memory (RAM) server:
The server process will load the repository index into memory. Might need
considerable amounts of memory, but less than on the client (see below).
.TP
.B Chunks index (client only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big chunks index.
It is possible to tweak the chunker params (see create options).
.TP
.B Files index (client only):
Proportional to the amount of files in your last backups. Can be switched
off (see create options), but next backup might be much slower if you do.
The speed benefit of using the files cache is proportional to file size.
.TP
.B Repository index (server only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big repository index.
It is possible to tweak the chunker params (see create options) to
influence the amount of chunks being created.
.TP
.B Temporary files (client):
Reading data and metadata from a FUSE mounted repository will consume up to
the size of all deduplicated, small chunks in the repository. Big chunks
won\(aqt be locally cached.
.TP
.B Temporary files (server):
None.
.TP
.B Cache files (client only):
Contains the chunks index and files index (plus a collection of single\-
archive chunk indexes which might need huge amounts of disk space,
depending on archive count and size \- see FAQ about how to reduce).
.TP
.B Network (only for client/server operation):
If your repository is remote, all deduplicated (and optionally compressed/
encrypted) data of course has to go over the connection (ssh: repo url).
If you use a locally mounted network filesystem, additionally some copy
operations used for transaction support also go over the connection. If
you backup multiple sources to one target repository, additional traffic
happens for cache resynchronization.
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP for common command line options
.sp
\fIborg\-init(1)\fP,
\fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,
\fIborg\-list(1)\fP, \fIborg\-info(1)\fP,
\fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP,
\fIborg\-recreate(1)\fP
.sp
\fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP
.INDENT 0.0
.IP \(bu 2
Main web site \fI\%https://borgbackup.readthedocs.org/\fP
.IP \(bu 2
Releases \fI\%https://github.com/borgbackup/borg/releases\fP
.IP \(bu 2
Changelog \fI\%https://github.com/borgbackup/borg/blob/master/docs/changes.rst\fP
.IP \(bu 2
GitHub \fI\%https://github.com/borgbackup/borg\fP
.IP \(bu 2
Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP
.UNINDENT
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

68
docs/man_intro.rst Normal file
View file

@ -0,0 +1,68 @@
====
borg
====
----------------------------------------
deduplicating and encrypting backup tool
----------------------------------------
:Author: The Borg Collective
:Date: 2017-02-05
:Manual section: 1
:Manual group: borg backup tool
SYNOPSIS
--------
borg <command> [options] [arguments]
DESCRIPTION
-----------
.. we don't include the README.rst here since we want to keep this terse.
BorgBackup (short: Borg) is a deduplicating backup program.
Optionally, it supports compression and authenticated encryption.
The main goal of Borg is to provide an efficient and secure way to backup data.
The data deduplication technique used makes Borg suitable for daily backups
since only changes are stored.
The authenticated encryption technique makes it suitable for backups to not
fully trusted targets.
Borg stores a set of files in an *archive*. A *repository* is a collection
of *archives*. The format of repositories is Borg-specific. Borg does not
distinguish archives from each other in a any way other than their name,
it does not matter when or where archives where created (eg. different hosts).
EXAMPLES
--------
A step-by-step example
~~~~~~~~~~~~~~~~~~~~~~
.. include:: quickstart_example.rst.inc
NOTES
-----
.. include:: usage/general.rst.inc
SEE ALSO
--------
`borg-common(1)` for common command line options
`borg-init(1)`,
`borg-create(1)`, `borg-mount(1)`, `borg-extract(1)`,
`borg-list(1)`, `borg-info(1)`,
`borg-delete(1)`, `borg-prune(1)`,
`borg-recreate(1)`
`borg-compression(1)`, `borg-patterns(1)`, `borg-placeholders(1)`
* Main web site https://borgbackup.readthedocs.org/
* Releases https://github.com/borgbackup/borg/releases
* Changelog https://github.com/borgbackup/borg/blob/master/docs/changes.rst
* GitHub https://github.com/borgbackup/borg
* Security contact https://borgbackup.readthedocs.io/en/latest/support.html#security-contact

63
docs/quickstart.rst
View file

@ -11,68 +11,7 @@ various use cases.
A step by step example
----------------------
1. Before a backup can be made a repository has to be initialized::
$ borg init /path/to/repo
2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
*Monday*::
$ borg create /path/to/repo::Monday ~/src ~/Documents
3. The next day create a new archive called *Tuesday*::
$ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents
This backup will be a lot quicker and a lot smaller since only new never
before seen data is stored. The ``--stats`` option causes |project_name| to
output statistics about the newly created archive such as the amount of unique
data (not shared with other archives)::
------------------------------------------------------------------------------
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
Time (start): Tue, 2016-02-16 18:15:11
Time (end): Tue, 2016-02-16 18:15:11
Duration: 0.19 seconds
Number of files: 127
------------------------------------------------------------------------------
Original size Compressed size Deduplicated size
This archive: 4.16 MB 4.17 MB 26.78 kB
All archives: 8.33 MB 8.34 MB 4.19 MB
Unique chunks Total chunks
Chunk index: 132 261
------------------------------------------------------------------------------
4. List all archives in the repository::
$ borg list /path/to/repo
Monday Mon, 2016-02-15 19:14:44
Tuesday Tue, 2016-02-16 19:15:11
5. List the contents of the *Monday* archive::
$ borg list /path/to/repo::Monday
drwxr-xr-x user group 0 Mon, 2016-02-15 18:22:30 home/user/Documents
-rw-r--r-- user group 7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
...
6. Restore the *Monday* archive by extracting the files relative to the current directory::
$ borg extract /path/to/repo::Monday
7. Recover disk space by manually deleting the *Monday* archive::
$ borg delete /path/to/repo::Monday
.. Note::
Borg is quiet by default (it works on WARNING log level).
You can use options like ``--progress`` or ``--list`` to get specific
reports during command execution. You can also add the ``-v`` (or
``--verbose`` or ``--info``) option to adjust the log level to INFO to
get other informational messages.
.. include:: quickstart_example.rst.inc
Important note about free space
-------------------------------

62
docs/quickstart_example.rst.inc Normal file
View file

@ -0,0 +1,62 @@
1. Before a backup can be made a repository has to be initialized::
$ borg init --encryption=repokey /path/to/repo
2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
*Monday*::
$ borg create /path/to/repo::Monday ~/src ~/Documents
3. The next day create a new archive called *Tuesday*::
$ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents
This backup will be a lot quicker and a lot smaller since only new never
before seen data is stored. The ``--stats`` option causes Borg to
output statistics about the newly created archive such as the amount of unique
data (not shared with other archives)::
------------------------------------------------------------------------------
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
Time (start): Tue, 2016-02-16 18:15:11
Time (end): Tue, 2016-02-16 18:15:11
Duration: 0.19 seconds
Number of files: 127
------------------------------------------------------------------------------
Original size Compressed size Deduplicated size
This archive: 4.16 MB 4.17 MB 26.78 kB
All archives: 8.33 MB 8.34 MB 4.19 MB
Unique chunks Total chunks
Chunk index: 132 261
------------------------------------------------------------------------------
4. List all archives in the repository::
$ borg list /path/to/repo
Monday Mon, 2016-02-15 19:14:44
Tuesday Tue, 2016-02-16 19:15:11
5. List the contents of the *Monday* archive::
$ borg list /path/to/repo::Monday
drwxr-xr-x user group 0 Mon, 2016-02-15 18:22:30 home/user/Documents
-rw-r--r-- user group 7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
...
6. Restore the *Monday* archive by extracting the files relative to the current directory::
$ borg extract /path/to/repo::Monday
7. Recover disk space by manually deleting the *Monday* archive::
$ borg delete /path/to/repo::Monday
.. Note::
Borg is quiet by default (it works on WARNING log level).
You can use options like ``--progress`` or ``--list`` to get specific
reports during command execution. You can also add the ``-v`` (or
``--verbose`` or ``--info``) option to adjust the log level to INFO to
get other informational messages.

335
docs/usage.rst
View file

@ -12,342 +12,13 @@ command in detail.
General
-------
Repository URLs
~~~~~~~~~~~~~~~
**Local filesystem** (or locally mounted network filesystem):
``/path/to/repo`` - filesystem path to repo directory, absolute path
``path/to/repo`` - filesystem path to repo directory, relative path
Also, stuff like ``~/path/to/repo`` or ``~other/path/to/repo`` works (this is
expanded by your shell).
Note: you may also prepend a ``file://`` to a filesystem path to get URL style.
**Remote repositories** accessed via ssh user@host:
``user@host:/path/to/repo`` - remote repo, absolute path
``ssh://user@host:port/path/to/repo`` - same, alternative syntax, port can be given
**Remote repositories with relative pathes** can be given using this syntax:
``user@host:path/to/repo`` - path relative to current directory
``user@host:~/path/to/repo`` - path relative to user's home directory
``user@host:~other/path/to/repo`` - path relative to other's home directory
Note: giving ``user@host:/./path/to/repo`` or ``user@host:/~/path/to/repo`` or
``user@host:/~other/path/to/repo`` is also supported, but not required here.
**Remote repositories with relative pathes, alternative syntax with port**:
``ssh://user@host:port/./path/to/repo`` - path relative to current directory
``ssh://user@host:port/~/path/to/repo`` - path relative to user's home directory
``ssh://user@host:port/~other/path/to/repo`` - path relative to other's home directory
If you frequently need the same repo URL, it is a good idea to set the
``BORG_REPO`` environment variable to set a default for the repo URL:
::
export BORG_REPO='ssh://user@host:port/path/to/repo'
Then just leave away the repo URL if only a repo URL is needed and you want
to use the default - it will be read from BORG_REPO then.
Use ``::`` syntax to give the repo URL when syntax requires giving a positional
argument for the repo (e.g. ``borg mount :: /mnt``).
Repository / Archive Locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many commands want either a repository (just give the repo URL, see above) or
an archive location, which is a repo URL followed by ``::archive_name``.
Archive names must not contain the ``/`` (slash) character. For simplicity,
maybe also avoid blanks or other characters that have special meaning on the
shell or in a filesystem (borg mount will use the archive name as directory
name).
If you have set BORG_REPO (see above) and an archive location is needed, use
``::archive_name`` - the repo URL part is then read from BORG_REPO.
Type of log output
~~~~~~~~~~~~~~~~~~
The log level of the builtin logging configuration defaults to WARNING.
This is because we want |project_name| to be mostly silent and only output
warnings, errors and critical messages, unless output has been requested
by supplying an option that implies output (eg, --list or --progress).
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
Use ``--debug`` to set DEBUG log level -
to get debug, info, warning, error and critical level output.
Use ``--info`` (or ``-v`` or ``--verbose``) to set INFO log level -
to get info, warning, error and critical level output.
Use ``--warning`` (default) to set WARNING log level -
to get warning, error and critical level output.
Use ``--error`` to set ERROR log level -
to get error and critical level output.
Use ``--critical`` to set CRITICAL log level -
to get critical level output.
While you can set misc. log levels, do not expect that every command will
give different output on different log levels - it's just a possibility.
.. warning:: Options --critical and --error are provided for completeness,
their usage is not recommended as you might miss important information.
Return codes
~~~~~~~~~~~~
|project_name| can exit with the following return codes (rc):
::
0 = success (logged as INFO)
1 = warning (operation reached its normal end, but there were warnings -
you should check the log, logged as WARNING)
2 = error (like a fatal error, a local or remote exception, the operation
did not reach its normal end, logged as ERROR)
128+N = killed by signal N (e.g. 137 == kill -9)
If you use ``--show-rc``, the return code is also logged at the indicated
level as the last log entry.
Environment Variables
~~~~~~~~~~~~~~~~~~~~~
|project_name| uses some environment variables for automation:
General:
BORG_REPO
When set, use the value to give the default repository location. If a command needs an archive
parameter, you can abbreviate as `::archive`. If a command needs a repository parameter, you
can either leave it away or abbreviate as `::`, if a positional parameter is required.
BORG_PASSPHRASE
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access a encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
See also BORG_NEW_PASSPHRASE.
BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE will be checked also.
Main usecase for this is to fully automate ``borg change-passphrase``.
BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
BORG_LOGGING_CONF
When set, use the given filename as INI_-style logging configuration.
BORG_RSH
When set, use this command instead of ``ssh``. This can be used to specify ssh options, such as
a custom identity file ``ssh -i /path/to/private/key``. See ``man ssh`` for other options.
BORG_REMOTE_PATH
When set, use the given path/filename as remote path (default is "borg").
Using ``--remote-path PATH`` commandline option overrides the environment variable.
BORG_FILES_CACHE_TTL
When set to a numeric value, this determines the maximum "time to live" for the files cache
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
The FAQ explains this more detailed in: :ref:`always_chunking`
TMPDIR
where temporary files are stored (might need a lot of temporary space for some operations)
Some automatic "answerers" (if set, they automatically answer confirmation questions):
BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: Attempting to access a previously unknown unencrypted repository"
BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: The repository at location ... was previously located at ..."
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "Warning: 'check --repair' is an experimental feature that might result in data loss."
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "You requested to completely DELETE the repository *including* all archives it contains:"
BORG_RECREATE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "recreate is an experimental feature."
Note: answers are case sensitive. setting an invalid answer value might either give the default
answer or ask you interactively, depending on whether retries are allowed (they by default are
allowed). So please test your scripts interactively before making them a non-interactive script.
Directories and files:
BORG_KEYS_DIR
Default to '~/.config/borg/keys'. This directory contains keys for encrypted repositories.
BORG_KEY_FILE
When set, use the given filename as repository key file.
BORG_SECURITY_DIR
Default to '~/.config/borg/security'. This directory contains information borg uses to
track its usage of NONCES ("numbers used once" - usually in encryption context) and other
security relevant data.
BORG_CACHE_DIR
Default to '~/.cache/borg'. This directory contains the local cache and might need a lot
of space for dealing with big repositories).
Building:
BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
BORG_LZ4_PREFIX
Adds given LZ4 header file directory to the default locations (setup.py).
BORG_LIBB2_PREFIX
Adds given prefix directory to the default locations. If a 'include/blake2.h' is found Borg
will be linked against the system libb2 instead of a bundled implementation. (setup.py)
Please note:
- be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data's security/safety
- also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions
(e.g. mode 600, root:root).
.. _INI: https://docs.python.org/3.4/library/logging.config.html#configuration-file-format
Resource Usage
~~~~~~~~~~~~~~
|project_name| might use a lot of resources depending on the size of the data set it is dealing with.
If one uses |project_name| in a client/server way (with a ssh: repository),
the resource usage occurs in part on the client and in another part on the
server.
If one uses |project_name| as a single process (with a filesystem repo),
all the resource usage occurs in that one process, so just add up client +
server to get the approximate resource usage.
CPU client:
borg create: does chunking, hashing, compression, crypto (high CPU usage)
chunks cache sync: quite heavy on CPU, doing lots of hashtable operations.
borg extract: crypto, decompression (medium to high CPU usage)
borg check: similar to extract, but depends on options given.
borg prune / borg delete archive: low to medium CPU usage
borg delete repo: done on the server
It won't go beyond 100% of 1 core as the code is currently single-threaded.
Especially higher zlib and lzma compression levels use significant amounts
of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
expensive (if not).
CPU server:
It usually doesn't need much CPU, it just deals with the key/value store
(repository) and uses the repository index for that.
borg check: the repository check computes the checksums of all chunks
(medium CPU usage)
borg delete repo: low CPU usage
CPU (only for client/server operation):
When using borg in a client/server way with a ssh:-type repo, the ssh
processes used for the transport layer will need some CPU on the client and
on the server due to the crypto they are doing - esp. if you are pumping
big amounts of data.
Memory (RAM) client:
The chunks index and the files index are read into memory for performance
reasons. Might need big amounts of memory (see below).
Compression, esp. lzma compression with high levels might need substantial
amounts of memory.
Memory (RAM) server:
The server process will load the repository index into memory. Might need
considerable amounts of memory, but less than on the client (see below).
Chunks index (client only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big chunks index.
It is possible to tweak the chunker params (see create options).
Files index (client only):
Proportional to the amount of files in your last backups. Can be switched
off (see create options), but next backup might be much slower if you do.
The speed benefit of using the files cache is proportional to file size.
Repository index (server only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big repository index.
It is possible to tweak the chunker params (see create options) to
influence the amount of chunks being created.
Temporary files (client):
Reading data and metadata from a FUSE mounted repository will consume up to
the size of all deduplicated, small chunks in the repository. Big chunks
won't be locally cached.
Temporary files (server):
None.
Cache files (client only):
Contains the chunks index and files index (plus a collection of single-
archive chunk indexes which might need huge amounts of disk space,
depending on archive count and size - see FAQ about how to reduce).
Network (only for client/server operation):
If your repository is remote, all deduplicated (and optionally compressed/
encrypted) data of course has to go over the connection (ssh: repo url).
If you use a locally mounted network filesystem, additionally some copy
operations used for transaction support also go over the connection. If
you backup multiple sources to one target repository, additional traffic
happens for cache resynchronization.
.. include:: usage/general.rst.inc
In case you are interested in more details (like formulas), please see
:ref:`internals`.
File systems
~~~~~~~~~~~~
We strongly recommend against using Borg (or any other database-like
software) on non-journaling file systems like FAT, since it is not
possible to assume any consistency in case of power failures (or a
sudden disconnect of an external drive or similar failures).
While Borg uses a data store that is resilient against these failures
when used on journaling file systems, it is not possible to guarantee
this with some hardware -- independent of the software used. We don't
know a list of affected hardware.
If you are suspicious whether your Borg repository is still consistent
and readable after one of the failures mentioned above occured, run
``borg check --verify-data`` to make sure it is consistent.
Units
~~~~~
To display quantities, |project_name| takes care of respecting the
usual conventions of scale. Disk sizes are displayed in `decimal
<https://en.wikipedia.org/wiki/Decimal>`_, using powers of ten (so
``kB`` means 1000 bytes). For memory usage, `binary prefixes
<https://en.wikipedia.org/wiki/Binary_prefix>`_ are used, and are
indicated using the `IEC binary prefixes
<https://en.wikipedia.org/wiki/IEC_80000-13#Prefixes_for_binary_multiples>`_,
using powers of two (so ``KiB`` means 1024 bytes).
Date and Time
~~~~~~~~~~~~~
We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
HH:MM:SS (24h clock).
For more information about that, see: https://xkcd.com/1179/
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
Common options
~~~~~~~~~~~~~~
++++++++++++++
All |project_name| commands share these options:
@ -636,6 +307,7 @@ Examples
Examples
~~~~~~~~
borg mount
++++++++++
::
@ -845,6 +517,7 @@ Here are misc. notes about topics that are maybe not covered in enough detail in
--chunker-params
~~~~~~~~~~~~~~~~
The chunker params influence how input files are cut into pieces (chunks)
which are then considered for deduplication. They also have a big impact on
resource usage (RAM and disk space) as the amount of resources needed is

62
docs/usage/create.rst.inc
View file

@ -36,10 +36,10 @@ Exclusion options
| read exclude patterns from EXCLUDEFILE, one per line
``--exclude-caches``
| exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
``--exclude-if-present FILENAME``
| exclude directories that contain the specified file
``--keep-tag-files``
| keep tag files of excluded caches/directories
``--exclude-if-present NAME``
| exclude directories that are tagged by containing a filesystem object with the given NAME
``--keep-exclude-tags``, ``--keep-tag-files``
| keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise excluded caches/directories
Filesystem options
``-x``, ``--one-file-system``
@ -58,12 +58,12 @@ Filesystem options
Archive options
``--comment COMMENT``
| add a comment text to the archive
``--timestamp yyyy-mm-ddThh:mm:ss``
| manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
``--timestamp TIMESTAMP``
| manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
``-c SECONDS``, ``--checkpoint-interval SECONDS``
| write checkpoint every SECONDS seconds (Default: 1800)
``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
| specify the chunker parameters. default: 19,23,21,4095
``--chunker-params PARAMS``
| specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
``-C COMPRESSION``, ``--compression COMPRESSION``
| select compression algorithm, see the output of the "borg help compression" command for details.
``--compression-from COMPRESSIONCONFIG``
@ -94,3 +94,49 @@ all files on these file systems.
See the output of the "borg help patterns" command for more help on exclude patterns.
See the output of the "borg help placeholders" command for more help on placeholders.
.. man NOTES
The --exclude patterns are not like tar. In tar --exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use --exclude
'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
more information.
Item flags
++++++++++
``--list`` outputs a list of all files, directories and other
file system items it considered (no matter whether they had content changes
or not). For each item, it prefixes a single-letter flag that indicates type
and/or status of the item.
If you are interested only in a subset of that output, you can give e.g.
``--filter=AME`` and it will only show regular files with A, M or E status (see
below).
A uppercase character represents the status of a regular file relative to the
"files" cache (not relative to the repo -- this is an issue if the files cache
is not used). Metadata is stored in any case and for 'A' and 'M' also new data
chunks are stored. For 'U' all data chunks refer to already existing chunks.
- 'A' = regular file, added (see also :ref:`a_status_oddity` in the FAQ)
- 'M' = regular file, modified
- 'U' = regular file, unchanged
- 'E' = regular file, an error happened while accessing/reading *this* file
A lowercase character means a file type other than a regular file,
borg usually just stores their metadata:
- 'd' = directory
- 'b' = block device
- 'c' = char device
- 'h' = regular file, hardlink (to already seen inodes)
- 's' = symlink
- 'f' = fifo
Other flags used include:
- 'i' = backup data was read from standard input (stdin)
- '-' = dry run, item was *not* backed up
- 'x' = excluded, item was *not* backed up
- '?' = missing status code (if you see this, please file a bug report!)

329
docs/usage/general.rst.inc Normal file
View file

@ -0,0 +1,329 @@
Repository URLs
~~~~~~~~~~~~~~~
**Local filesystem** (or locally mounted network filesystem):
``/path/to/repo`` - filesystem path to repo directory, absolute path
``path/to/repo`` - filesystem path to repo directory, relative path
Also, stuff like ``~/path/to/repo`` or ``~other/path/to/repo`` works (this is
expanded by your shell).
Note: you may also prepend a ``file://`` to a filesystem path to get URL style.
**Remote repositories** accessed via ssh user@host:
``user@host:/path/to/repo`` - remote repo, absolute path
``ssh://user@host:port/path/to/repo`` - same, alternative syntax, port can be given
**Remote repositories with relative pathes** can be given using this syntax:
``user@host:path/to/repo`` - path relative to current directory
``user@host:~/path/to/repo`` - path relative to user's home directory
``user@host:~other/path/to/repo`` - path relative to other's home directory
Note: giving ``user@host:/./path/to/repo`` or ``user@host:/~/path/to/repo`` or
``user@host:/~other/path/to/repo`` is also supported, but not required here.
**Remote repositories with relative pathes, alternative syntax with port**:
``ssh://user@host:port/./path/to/repo`` - path relative to current directory
``ssh://user@host:port/~/path/to/repo`` - path relative to user's home directory
``ssh://user@host:port/~other/path/to/repo`` - path relative to other's home directory
If you frequently need the same repo URL, it is a good idea to set the
``BORG_REPO`` environment variable to set a default for the repo URL:
::
export BORG_REPO='ssh://user@host:port/path/to/repo'
Then just leave away the repo URL if only a repo URL is needed and you want
to use the default - it will be read from BORG_REPO then.
Use ``::`` syntax to give the repo URL when syntax requires giving a positional
argument for the repo (e.g. ``borg mount :: /mnt``).
Repository / Archive Locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many commands want either a repository (just give the repo URL, see above) or
an archive location, which is a repo URL followed by ``::archive_name``.
Archive names must not contain the ``/`` (slash) character. For simplicity,
maybe also avoid blanks or other characters that have special meaning on the
shell or in a filesystem (borg mount will use the archive name as directory
name).
If you have set BORG_REPO (see above) and an archive location is needed, use
``::archive_name`` - the repo URL part is then read from BORG_REPO.
Type of log output
~~~~~~~~~~~~~~~~~~
The log level of the builtin logging configuration defaults to WARNING.
This is because we want Borg to be mostly silent and only output
warnings, errors and critical messages, unless output has been requested
by supplying an option that implies output (eg, --list or --progress).
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
Use ``--debug`` to set DEBUG log level -
to get debug, info, warning, error and critical level output.
Use ``--info`` (or ``-v`` or ``--verbose``) to set INFO log level -
to get info, warning, error and critical level output.
Use ``--warning`` (default) to set WARNING log level -
to get warning, error and critical level output.
Use ``--error`` to set ERROR log level -
to get error and critical level output.
Use ``--critical`` to set CRITICAL log level -
to get critical level output.
While you can set misc. log levels, do not expect that every command will
give different output on different log levels - it's just a possibility.
.. warning:: Options --critical and --error are provided for completeness,
their usage is not recommended as you might miss important information.
Return codes
~~~~~~~~~~~~
Borg can exit with the following return codes (rc):
::
0 = success (logged as INFO)
1 = warning (operation reached its normal end, but there were warnings -
you should check the log, logged as WARNING)
2 = error (like a fatal error, a local or remote exception, the operation
did not reach its normal end, logged as ERROR)
128+N = killed by signal N (e.g. 137 == kill -9)
If you use ``--show-rc``, the return code is also logged at the indicated
level as the last log entry.
Environment Variables
~~~~~~~~~~~~~~~~~~~~~
Borg uses some environment variables for automation:
General:
BORG_REPO
When set, use the value to give the default repository location. If a command needs an archive
parameter, you can abbreviate as `::archive`. If a command needs a repository parameter, you
can either leave it away or abbreviate as `::`, if a positional parameter is required.
BORG_PASSPHRASE
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access a encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
See also BORG_NEW_PASSPHRASE.
BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE will be checked also.
Main usecase for this is to fully automate ``borg change-passphrase``.
BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
BORG_LOGGING_CONF
When set, use the given filename as INI_-style logging configuration.
BORG_RSH
When set, use this command instead of ``ssh``. This can be used to specify ssh options, such as
a custom identity file ``ssh -i /path/to/private/key``. See ``man ssh`` for other options.
BORG_REMOTE_PATH
When set, use the given path/filename as remote path (default is "borg").
Using ``--remote-path PATH`` commandline option overrides the environment variable.
BORG_FILES_CACHE_TTL
When set to a numeric value, this determines the maximum "time to live" for the files cache
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
The FAQ explains this more detailed in: :ref:`always_chunking`
TMPDIR
where temporary files are stored (might need a lot of temporary space for some operations)
Some automatic "answerers" (if set, they automatically answer confirmation questions):
BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: Attempting to access a previously unknown unencrypted repository"
BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: The repository at location ... was previously located at ..."
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "Warning: 'check --repair' is an experimental feature that might result in data loss."
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "You requested to completely DELETE the repository *including* all archives it contains:"
BORG_RECREATE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "recreate is an experimental feature."
Note: answers are case sensitive. setting an invalid answer value might either give the default
answer or ask you interactively, depending on whether retries are allowed (they by default are
allowed). So please test your scripts interactively before making them a non-interactive script.
Directories and files:
BORG_KEYS_DIR
Default to '~/.config/borg/keys'. This directory contains keys for encrypted repositories.
BORG_KEY_FILE
When set, use the given filename as repository key file.
BORG_SECURITY_DIR
Default to '~/.config/borg/security'. This directory contains information borg uses to
track its usage of NONCES ("numbers used once" - usually in encryption context) and other
security relevant data.
BORG_CACHE_DIR
Default to '~/.cache/borg'. This directory contains the local cache and might need a lot
of space for dealing with big repositories).
Building:
BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
BORG_LZ4_PREFIX
Adds given LZ4 header file directory to the default locations (setup.py).
BORG_LIBB2_PREFIX
Adds given prefix directory to the default locations. If a 'include/blake2.h' is found Borg
will be linked against the system libb2 instead of a bundled implementation. (setup.py)
Please note:
- be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data's security/safety
- also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions
(e.g. mode 600, root:root).
.. _INI: https://docs.python.org/3.4/library/logging.config.html#configuration-file-format
File systems
~~~~~~~~~~~~
We strongly recommend against using Borg (or any other database-like
software) on non-journaling file systems like FAT, since it is not
possible to assume any consistency in case of power failures (or a
sudden disconnect of an external drive or similar failures).
While Borg uses a data store that is resilient against these failures
when used on journaling file systems, it is not possible to guarantee
this with some hardware -- independent of the software used. We don't
know a list of affected hardware.
If you are suspicious whether your Borg repository is still consistent
and readable after one of the failures mentioned above occured, run
``borg check --verify-data`` to make sure it is consistent.
Units
~~~~~
To display quantities, Borg takes care of respecting the
usual conventions of scale. Disk sizes are displayed in `decimal
<https://en.wikipedia.org/wiki/Decimal>`_, using powers of ten (so
``kB`` means 1000 bytes). For memory usage, `binary prefixes
<https://en.wikipedia.org/wiki/Binary_prefix>`_ are used, and are
indicated using the `IEC binary prefixes
<https://en.wikipedia.org/wiki/IEC_80000-13#Prefixes_for_binary_multiples>`_,
using powers of two (so ``KiB`` means 1024 bytes).
Date and Time
~~~~~~~~~~~~~
We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
HH:MM:SS (24h clock).
For more information about that, see: https://xkcd.com/1179/
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
Resource Usage
~~~~~~~~~~~~~~
Borg might use a lot of resources depending on the size of the data set it is dealing with.
If one uses Borg in a client/server way (with a ssh: repository),
the resource usage occurs in part on the client and in another part on the
server.
If one uses Borg as a single process (with a filesystem repo),
all the resource usage occurs in that one process, so just add up client +
server to get the approximate resource usage.
CPU client:
borg create: does chunking, hashing, compression, crypto (high CPU usage)
chunks cache sync: quite heavy on CPU, doing lots of hashtable operations.
borg extract: crypto, decompression (medium to high CPU usage)
borg check: similar to extract, but depends on options given.
borg prune / borg delete archive: low to medium CPU usage
borg delete repo: done on the server
It won't go beyond 100% of 1 core as the code is currently single-threaded.
Especially higher zlib and lzma compression levels use significant amounts
of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
expensive (if not).
CPU server:
It usually doesn't need much CPU, it just deals with the key/value store
(repository) and uses the repository index for that.
borg check: the repository check computes the checksums of all chunks
(medium CPU usage)
borg delete repo: low CPU usage
CPU (only for client/server operation):
When using borg in a client/server way with a ssh:-type repo, the ssh
processes used for the transport layer will need some CPU on the client and
on the server due to the crypto they are doing - esp. if you are pumping
big amounts of data.
Memory (RAM) client:
The chunks index and the files index are read into memory for performance
reasons. Might need big amounts of memory (see below).
Compression, esp. lzma compression with high levels might need substantial
amounts of memory.
Memory (RAM) server:
The server process will load the repository index into memory. Might need
considerable amounts of memory, but less than on the client (see below).
Chunks index (client only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big chunks index.
It is possible to tweak the chunker params (see create options).
Files index (client only):
Proportional to the amount of files in your last backups. Can be switched
off (see create options), but next backup might be much slower if you do.
The speed benefit of using the files cache is proportional to file size.
Repository index (server only):
Proportional to the amount of data chunks in your repo. Lots of chunks
in your repo imply a big repository index.
It is possible to tweak the chunker params (see create options) to
influence the amount of chunks being created.
Temporary files (client):
Reading data and metadata from a FUSE mounted repository will consume up to
the size of all deduplicated, small chunks in the repository. Big chunks
won't be locally cached.
Temporary files (server):
None.
Cache files (client only):
Contains the chunks index and files index (plus a collection of single-
archive chunk indexes which might need huge amounts of disk space,
depending on archive count and size - see FAQ about how to reduce).
Network (only for client/server operation):
If your repository is remote, all deduplicated (and optionally compressed/
encrypted) data of course has to go over the connection (ssh: repo url).
If you use a locally mounted network filesystem, additionally some copy
operations used for transaction support also go over the connection. If
you backup multiple sources to one target repository, additional traffic
happens for cache resynchronization.

19
docs/usage/init.rst.inc
View file

@ -14,7 +14,7 @@ positional arguments
optional arguments
``-e``, ``--encryption``
| select encryption key mode (default: "None")
| select encryption key mode
``-a``, ``--append-only``
| create an append-only mode repository
@ -70,30 +70,31 @@ the encryption/decryption key or other secrets.
Encryption modes
++++++++++++++++
repokey and keyfile use AES-CTR-256 for encryption and HMAC-SHA256 for
`repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for
authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash
is HMAC-SHA256 as well (with a separate key).
These modes are compatible with borg 1.0.x.
repokey-blake2 and keyfile-blake2 are also authenticated encryption modes,
`repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes,
but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID
hash is a keyed BLAKE2b-256 hash.
These modes are new and not compatible with borg 1.0.x.
These modes are new and *not* compatible with borg 1.0.x.
"authenticated" mode uses no encryption, but authenticates repository contents
`authenticated` mode uses no encryption, but authenticates repository contents
through the same keyed BLAKE2b-256 hash as the other blake2 modes (it uses it
as chunk ID hash). The key is stored like repokey.
This mode is new and not compatible with borg 1.0.x.
"none" mode uses no encryption and no authentication. It uses sha256 as chunk
`none` mode uses no encryption and no authentication. It uses sha256 as chunk
ID hash. Not recommended, rather consider using an authenticated or
authenticated/encrypted mode.
This mode is compatible with borg 1.0.x.
Hardware acceleration will be used automatically.
On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw
accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs.
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64bit CPUs,
which makes `authenticated` faster than `none`.
On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster
On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
than BLAKE2b-256 there.

22
docs/usage/key_change-passphrase.rst.inc Normal file
View file

@ -0,0 +1,22 @@
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
.. _borg_key_change-passphrase:
borg key change-passphrase
--------------------------
::
borg key change-passphrase <options> REPOSITORY
positional arguments
REPOSITORY
`Common options`_
|
Description
~~~~~~~~~~~
The key files used for repository encryption are optionally passphrase
protected. This command can be used to change this passphrase.

36
docs/usage/key_migrate-to-repokey.rst.inc Normal file
View file

@ -0,0 +1,36 @@
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
.. _borg_key_migrate-to-repokey:
borg key migrate-to-repokey
---------------------------
::
borg key migrate-to-repokey <options> REPOSITORY
positional arguments
REPOSITORY
`Common options`_
|
Description
~~~~~~~~~~~
This command migrates a repository from passphrase mode (removed in Borg 1.0)
to repokey mode.
You will be first asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase as you used to use for this repo before 1.0.
It will then derive the different secrets from this passphrase.
Then you will be asked for a new passphrase (twice, for safety). This
passphrase will be used to protect the repokey (which contains these same
secrets in encrypted form). You may use the same passphrase as you used to
use, but you may also use a different one.
After migrating to repokey mode, you can change the passphrase at any time.
But please note: the secrets will always stay the same and they could always
be derived from your (old) passphrase-mode passphrase.

7
docs/usage/list.rst.inc
View file

@ -46,6 +46,7 @@ This command lists the contents of a repository or an archive.
See the "borg help patterns" command for more help on exclude patterns.
The following keys are available for --format:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
@ -54,13 +55,15 @@ The following keys are available for --format:
- CR
- LF
-- Keys for listing repository archives:
Keys for listing repository archives:
- archive: archive name interpreted as text (might be missing non-text characters, see barchive)
- barchive: verbatim archive name, can contain any character except NUL
- time: time of creation of the archive
- id: internal ID of the archive
-- Keys for listing archive files:
Keys for listing archive files:
- type
- mode
- uid

2
docs/usage/prune.rst.inc
View file

@ -57,7 +57,7 @@ automated backup scripts wanting to keep a certain number of historic backups.
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (--keep-*).
comparing archive counts against the retention limits (--keep-X).
If a prefix is set with -P, then only archives that start with the prefix are
considered for deletion and only those archives count towards the totals

16
docs/usage/recreate.rst.inc
View file

@ -36,10 +36,10 @@ Exclusion options
| read exclude patterns from EXCLUDEFILE, one per line
``--exclude-caches``
| exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
``--exclude-if-present FILENAME``
| exclude directories that contain the specified file
``--keep-tag-files``
| keep tag files of excluded caches/directories
``--exclude-if-present NAME``
| exclude directories that are tagged by containing a filesystem object with the given NAME
``--keep-exclude-tags``, ``--keep-tag-files``
| keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise excluded caches/directories
Archive options
``--target TARGET``
@ -48,16 +48,16 @@ Archive options
| write checkpoint every SECONDS seconds (Default: 1800)
``--comment COMMENT``
| add a comment text to the archive
``--timestamp yyyy-mm-ddThh:mm:ss``
| manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
``--timestamp TIMESTAMP``
| manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
``-C COMPRESSION``, ``--compression COMPRESSION``
| select compression algorithm, see the output of the "borg help compression" command for details.
``--always-recompress``
| always recompress chunks, don't skip chunks already compressed with the same algorithm.
``--compression-from COMPRESSIONCONFIG``
| read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
| specify the chunker parameters (or "default").
``--chunker-params PARAMS``
| specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
Description
~~~~~~~~~~~

12
setup.py
View file

@ -353,6 +353,7 @@ class build_man(Command):
.. role:: ref(title)
.. |project_name| replace:: Borg
""")
def initialize_options(self):
@ -372,6 +373,7 @@ class build_man(Command):
self.generate_level('', parser, Archiver)
self.build_topic_pages(Archiver)
self.build_intro_page()
def generate_level(self, prefix, parser, Archiver):
is_subcommand = False
@ -447,6 +449,12 @@ class build_man(Command):
write(text)
self.gen_man_page(man_title, doc.getvalue())
def build_intro_page(self):
print('building man page borg(1)', file=sys.stderr)
with open('docs/man_intro.rst') as fd:
man_intro = fd.read()
self.gen_man_page('borg', self.rst_prelude + man_intro)
def new_doc(self):
doc = io.StringIO(self.rst_prelude)
doc.read()
@ -502,7 +510,9 @@ class build_man(Command):
def gen_man_page(self, name, rst):
from docutils.writers import manpage
from docutils.core import publish_string
man_page = publish_string(source=rst, writer=manpage.Writer())
# We give the source_path so that docutils can find relative includes
# as-if the document where located in the docs/ directory.
man_page = publish_string(source=rst, source_path='docs/virtmanpage.rst', writer=manpage.Writer())
with open('docs/man/%s.1' % name, 'wb') as fd:
fd.write(man_page)