mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-23 08:16:54 +00:00
334 lines
8.4 KiB
Groff
334 lines
8.4 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH BORG-INIT 1 "2022-04-14" "" "borg backup tool"
|
|
.SH NAME
|
|
borg-init \- Initialize an empty repository
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH SYNOPSIS
|
|
.sp
|
|
borg [common options] init [options] [REPOSITORY]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
This command initializes an empty repository. A repository is a filesystem
|
|
directory containing the deduplicated data from zero or more archives.
|
|
.SS Encryption mode TLDR
|
|
.sp
|
|
The encryption mode can only be configured when creating a new repository \- you can
|
|
neither configure it on a per\-archive basis nor change the mode of an existing repository.
|
|
This example will likely NOT give optimum performance on your machine (performance
|
|
tips will come below):
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
borg init \-\-encryption repokey /path/to/repo
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Borg will:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
Ask you to come up with a passphrase.
|
|
.IP 2. 3
|
|
Create a borg key (which contains some random secrets. See \fIkey_files\fP).
|
|
.IP 3. 3
|
|
Derive a "key encryption key" from your passphrase
|
|
.IP 4. 3
|
|
Encrypt and sign the key with the key encryption key
|
|
.IP 5. 3
|
|
Store the encrypted borg key inside the repository directory (in the repo config).
|
|
This is why it is essential to use a secure passphrase.
|
|
.IP 6. 3
|
|
Encrypt and sign your backups to prevent anyone from reading or forging them unless they
|
|
have the key and know the passphrase. Make sure to keep a backup of
|
|
your key \fBoutside\fP the repository \- do not lock yourself out by
|
|
"leaving your keys inside your car" (see \fIborg_key_export\fP).
|
|
For remote backups the encryption is done locally \- the remote machine
|
|
never sees your passphrase, your unencrypted key or your unencrypted files.
|
|
Chunking and id generation are also based on your key to improve
|
|
your privacy.
|
|
.IP 7. 3
|
|
Use the key when extracting files to decrypt them and to verify that the contents of
|
|
the backups have not been accidentally or maliciously altered.
|
|
.UNINDENT
|
|
.SS Picking a passphrase
|
|
.sp
|
|
Make sure you use a good passphrase. Not too short, not too simple. The real
|
|
encryption / decryption key is encrypted with / locked by your passphrase.
|
|
If an attacker gets your key, he can\(aqt unlock and use it without knowing the
|
|
passphrase.
|
|
.sp
|
|
Be careful with special or non\-ascii characters in your passphrase:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Borg processes the passphrase as unicode (and encodes it as utf\-8),
|
|
so it does not have problems dealing with even the strangest characters.
|
|
.IP \(bu 2
|
|
BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
|
|
.UNINDENT
|
|
.sp
|
|
So better use a long passphrase made from simple ascii chars than one that
|
|
includes non\-ascii stuff or characters that are hard/impossible to enter on
|
|
a different keyboard layout.
|
|
.sp
|
|
You can change your passphrase for existing repos at any time, it won\(aqt affect
|
|
the encryption/decryption key or other secrets.
|
|
.SS Choosing an encryption mode
|
|
.sp
|
|
Depending on your hardware, hashing and crypto performance may vary widely.
|
|
The easiest way to find out about what\(aqs fastest is to run \fBborg benchmark cpu\fP\&.
|
|
.sp
|
|
\fIrepokey\fP modes: if you want ease\-of\-use and "passphrase" security is good enough \-
|
|
the key will be stored in the repository (in \fBrepo_dir/config\fP).
|
|
.sp
|
|
\fIkeyfile\fP modes: if you rather want "passphrase and having\-the\-key" security \-
|
|
the key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
|
|
.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
|
|
center;
|
|
|l|l|l|l|l|.
|
|
_
|
|
T{
|
|
\fBmode (* = keyfile or repokey)\fP
|
|
T} T{
|
|
\fBID\-Hash\fP
|
|
T} T{
|
|
\fBEncryption\fP
|
|
T} T{
|
|
\fBAuthentication\fP
|
|
T} T{
|
|
\fBV>=\fP
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\-blake2\-chacha20\-poly1305\fP
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
CHACHA20
|
|
T} T{
|
|
POLY1305
|
|
T} T{
|
|
1.3
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\-chacha20\-poly1305\fP
|
|
T} T{
|
|
HMAC\-SHA\-256
|
|
T} T{
|
|
CHACHA20
|
|
T} T{
|
|
POLY1305
|
|
T} T{
|
|
1.3
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\-blake2\-aes\-ocb\fP
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
AES256\-OCB
|
|
T} T{
|
|
AES256\-OCB
|
|
T} T{
|
|
1.3
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\-aes\-ocb\fP
|
|
T} T{
|
|
HMAC\-SHA\-256
|
|
T} T{
|
|
AES256\-OCB
|
|
T} T{
|
|
AES256\-OCB
|
|
T} T{
|
|
1.3
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\-blake2\fP
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
AES256\-CTR
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
1.1
|
|
T}
|
|
_
|
|
T{
|
|
\fB*\fP
|
|
T} T{
|
|
HMAC\-SHA\-256
|
|
T} T{
|
|
AES256\-CTR
|
|
T} T{
|
|
HMAC\-SHA256
|
|
T} T{
|
|
any
|
|
T}
|
|
_
|
|
T{
|
|
authenticated\-blake2
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
none
|
|
T} T{
|
|
BLAKE2b
|
|
T} T{
|
|
1.1
|
|
T}
|
|
_
|
|
T{
|
|
authenticated
|
|
T} T{
|
|
HMAC\-SHA\-256
|
|
T} T{
|
|
none
|
|
T} T{
|
|
HMAC\-SHA256
|
|
T} T{
|
|
1.1
|
|
T}
|
|
_
|
|
T{
|
|
none
|
|
T} T{
|
|
SHA\-256
|
|
T} T{
|
|
none
|
|
T} T{
|
|
none
|
|
T} T{
|
|
any
|
|
T}
|
|
_
|
|
.TE
|
|
.\" nanorst: inline-replace
|
|
.
|
|
.sp
|
|
\fInone\fP mode uses no encryption and no authentication. You\(aqre advised to NOT use this mode
|
|
as it would expose you to all sorts of issues (DoS, 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\(aqs like \fIrepokey\fP minus encryption.
|
|
.SS Key derivation functions
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fB\-\-key\-algorithm argon2\fP is the default and is recommended.
|
|
The key encryption key is derived from your passphrase via argon2\-id.
|
|
Argon2 is considered more modern and secure than pbkdf2.
|
|
.IP \(bu 2
|
|
You can use \fB\-\-key\-algorithm pbkdf2\fP if you want to access your repo via old versions of borg.
|
|
.UNINDENT
|
|
.sp
|
|
Our implementation of argon2\-based key algorithm follows the cryptographic best practices:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
It derives two separate keys from your passphrase: one to encrypt your key and another one
|
|
to sign it. \fB\-\-key\-algorithm pbkdf2\fP uses the same key for both.
|
|
.IP \(bu 2
|
|
It uses encrypt\-then\-mac instead of encrypt\-and\-mac used by \fB\-\-key\-algorithm pbkdf2\fP
|
|
.UNINDENT
|
|
.sp
|
|
Neither is inherently linked to the key derivation function, but since we were going
|
|
to break backwards compatibility anyway we took the opportunity to fix all 3 issues at once.
|
|
.SH OPTIONS
|
|
.sp
|
|
See \fIborg\-common(1)\fP for common options of Borg commands.
|
|
.SS arguments
|
|
.INDENT 0.0
|
|
.TP
|
|
.B REPOSITORY
|
|
repository to create
|
|
.UNINDENT
|
|
.SS optional arguments
|
|
.INDENT 0.0
|
|
.TP
|
|
.BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
|
|
select encryption key mode \fB(required)\fP
|
|
.TP
|
|
.B \-\-append\-only
|
|
create an append\-only mode repository. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
|
|
.TP
|
|
.BI \-\-storage\-quota \ QUOTA
|
|
Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
|
|
.TP
|
|
.B \-\-make\-parent\-dirs
|
|
create the parent directories of the repository directory, if they are missing.
|
|
.TP
|
|
.B \-\-key\-algorithm
|
|
the algorithm we use to derive a key encryption key from your passphrase. Default: argon2
|
|
.UNINDENT
|
|
.SH EXAMPLES
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# Local repository, recommended repokey AEAD crypto modes
|
|
$ borg init \-\-encryption=repokey\-aes\-ocb /path/to/repo
|
|
$ borg init \-\-encryption=repokey\-chacha20\-poly1305 /path/to/repo
|
|
$ borg init \-\-encryption=repokey\-blake2\-aes\-ocb /path/to/repo
|
|
$ borg init \-\-encryption=repokey\-blake2\-chacha20\-poly1305 /path/to/repo
|
|
|
|
# Local repository (no encryption), not recommended
|
|
$ borg init \-\-encryption=none /path/to/repo
|
|
|
|
# Remote repository (accesses a remote borg via ssh)
|
|
# repokey: stores the (encrypted) key into <REPO_DIR>/config
|
|
$ borg init \-\-encryption=repokey\-aes\-ocb user@hostname:backup
|
|
|
|
# Remote repository (accesses a remote borg via ssh)
|
|
# keyfile: stores the (encrypted) key into ~/.config/borg/keys/
|
|
$ borg init \-\-encryption=keyfile\-aes\-ocb user@hostname:backup
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
|
|
.SH AUTHOR
|
|
The Borg Collective
|
|
.\" Generated by docutils manpage writer.
|
|
.
|