2024-09-08 11:18:53 -04:00
|
|
|
.. _borg_repo_create:
|
2022-06-23 19:19:19 -04:00
|
|
|
|
2024-09-08 11:18:53 -04:00
|
|
|
.. include:: repo-create.rst.inc
|
2022-06-23 19:19:19 -04:00
|
|
|
|
|
|
|
|
Examples
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
# Local repository
|
|
|
|
|
$ export BORG_REPO=/path/to/repo
|
key: unify keyfile/repokey classes, locate key independent of type byte (#9743)
Borg used to read the manifest's key-type byte and then look for the key in
exactly one place (keyfile or repokey) depending on the key class that byte
selected. As a result every crypto suite was duplicated into a keyfile class
and a repokey class that differed only in TYPE, NAME, ARG_NAME and STORAGE.
Now key *location* is independent of the type byte: detection tries keyfiles
first and repokeys afterwards until a passphrase unlocks a key. The type byte
still selects the crypto suite (id hash, MAC, cipher) to instantiate. Where a
key is stored (keyfile vs repokey) is therefore a per-key property
(self.storage), not a separate class, so a repository may even hold a mix of
keyfile- and repo-stored borg keys.
With storage decoupled from class identity, the keyfile/repokey class pairs
collapse into one class per crypto suite:
- modern AEAD: AESOCBKey, CHPOKey, Blake3AESOCBKey, Blake3CHPOKey
- legacy borg 1.x (read-only): AESCTRKey, Blake2AESCTRKey
There is now exactly one type byte per modern crypto suite (the old separate
repokey type bytes 0x11/0x21/0x31/0x41 were removed; borg2 is beta and only
needs to read repos it created). identify_key() matches on TYPES_ACCEPTABLE.
CLI: --encryption selects only the crypto suite (aes-ocb, chacha20-poly1305,
blake3-aes-ocb, blake3-chacha20-poly1305, authenticated*, none); the storage
location is chosen with the new --key-location=repokey|keyfile (default
repokey). The old combined modes (repokey-aes-ocb etc.) were removed.
borg key import also gained --key-location. borg key change-location no longer
swaps key classes or rewrites the manifest; it just re-saves the unlocked key
at the new location.
Keyfile removal (key remove, change-location) now overwrites the keyfile with
random data via secure_erase() before unlinking, consistent with save().
borg 1.x legacy read compatibility is preserved (the legacy class merge is a
behavior-preserving rename; the legacy type bytes incl. PASSPHRASE stay in
TYPES_ACCEPTABLE).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 17:07:57 -04:00
|
|
|
# Recommended AEAD cryptographic modes (key stored in the repository by default)
|
2026-06-16 08:28:03 -04:00
|
|
|
$ borg repo-create --encryption=aes256-ocb
|
key: unify keyfile/repokey classes, locate key independent of type byte (#9743)
Borg used to read the manifest's key-type byte and then look for the key in
exactly one place (keyfile or repokey) depending on the key class that byte
selected. As a result every crypto suite was duplicated into a keyfile class
and a repokey class that differed only in TYPE, NAME, ARG_NAME and STORAGE.
Now key *location* is independent of the type byte: detection tries keyfiles
first and repokeys afterwards until a passphrase unlocks a key. The type byte
still selects the crypto suite (id hash, MAC, cipher) to instantiate. Where a
key is stored (keyfile vs repokey) is therefore a per-key property
(self.storage), not a separate class, so a repository may even hold a mix of
keyfile- and repo-stored borg keys.
With storage decoupled from class identity, the keyfile/repokey class pairs
collapse into one class per crypto suite:
- modern AEAD: AESOCBKey, CHPOKey, Blake3AESOCBKey, Blake3CHPOKey
- legacy borg 1.x (read-only): AESCTRKey, Blake2AESCTRKey
There is now exactly one type byte per modern crypto suite (the old separate
repokey type bytes 0x11/0x21/0x31/0x41 were removed; borg2 is beta and only
needs to read repos it created). identify_key() matches on TYPES_ACCEPTABLE.
CLI: --encryption selects only the crypto suite (aes-ocb, chacha20-poly1305,
blake3-aes-ocb, blake3-chacha20-poly1305, authenticated*, none); the storage
location is chosen with the new --key-location=repokey|keyfile (default
repokey). The old combined modes (repokey-aes-ocb etc.) were removed.
borg key import also gained --key-location. borg key change-location no longer
swaps key classes or rewrites the manifest; it just re-saves the unlocked key
at the new location.
Keyfile removal (key remove, change-location) now overwrites the keyfile with
random data via secure_erase() before unlinking, consistent with save().
borg 1.x legacy read compatibility is preserved (the legacy class merge is a
behavior-preserving rename; the legacy type bytes incl. PASSPHRASE stay in
TYPES_ACCEPTABLE).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 17:07:57 -04:00
|
|
|
$ borg repo-create --encryption=chacha20-poly1305
|
2025-08-23 18:21:57 -04:00
|
|
|
# No encryption (not recommended)
|
2024-09-08 10:26:52 -04:00
|
|
|
$ borg repo-create --encryption=authenticated
|
|
|
|
|
$ borg repo-create --encryption=none
|
2022-06-23 19:19:19 -04:00
|
|
|
|
2026-06-16 08:28:03 -04:00
|
|
|
# --encryption (the cipher / AE algorithm) and --id-hash (the id hash function) are
|
|
|
|
|
# chosen independently. --id-hash defaults to sha256; use blake3 if it is faster on
|
|
|
|
|
# your hardware (run 'borg benchmark cpu' to find out). The 'none' encryption only
|
|
|
|
|
# supports the sha256 id hash.
|
|
|
|
|
$ borg repo-create --encryption=aes256-ocb --id-hash=blake3
|
|
|
|
|
$ borg repo-create --encryption=chacha20-poly1305 --id-hash=blake3
|
|
|
|
|
$ borg repo-create --encryption=authenticated --id-hash=blake3
|
|
|
|
|
|
|
|
|
|
# Where the key is stored (--key-location) is also chosen independently.
|
|
|
|
|
# --key-location defaults to repokey.
|
key: unify keyfile/repokey classes, locate key independent of type byte (#9743)
Borg used to read the manifest's key-type byte and then look for the key in
exactly one place (keyfile or repokey) depending on the key class that byte
selected. As a result every crypto suite was duplicated into a keyfile class
and a repokey class that differed only in TYPE, NAME, ARG_NAME and STORAGE.
Now key *location* is independent of the type byte: detection tries keyfiles
first and repokeys afterwards until a passphrase unlocks a key. The type byte
still selects the crypto suite (id hash, MAC, cipher) to instantiate. Where a
key is stored (keyfile vs repokey) is therefore a per-key property
(self.storage), not a separate class, so a repository may even hold a mix of
keyfile- and repo-stored borg keys.
With storage decoupled from class identity, the keyfile/repokey class pairs
collapse into one class per crypto suite:
- modern AEAD: AESOCBKey, CHPOKey, Blake3AESOCBKey, Blake3CHPOKey
- legacy borg 1.x (read-only): AESCTRKey, Blake2AESCTRKey
There is now exactly one type byte per modern crypto suite (the old separate
repokey type bytes 0x11/0x21/0x31/0x41 were removed; borg2 is beta and only
needs to read repos it created). identify_key() matches on TYPES_ACCEPTABLE.
CLI: --encryption selects only the crypto suite (aes-ocb, chacha20-poly1305,
blake3-aes-ocb, blake3-chacha20-poly1305, authenticated*, none); the storage
location is chosen with the new --key-location=repokey|keyfile (default
repokey). The old combined modes (repokey-aes-ocb etc.) were removed.
borg key import also gained --key-location. borg key change-location no longer
swaps key classes or rewrites the manifest; it just re-saves the unlocked key
at the new location.
Keyfile removal (key remove, change-location) now overwrites the keyfile with
random data via secure_erase() before unlinking, consistent with save().
borg 1.x legacy read compatibility is preserved (the legacy class merge is a
behavior-preserving rename; the legacy type bytes incl. PASSPHRASE stay in
TYPES_ACCEPTABLE).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 17:07:57 -04:00
|
|
|
# repokey: stores the encrypted key inside the repository
|
2026-06-16 08:28:03 -04:00
|
|
|
$ borg repo-create --encryption=aes256-ocb --key-location=repokey
|
2026-02-18 15:51:03 -05:00
|
|
|
# keyfile: stores the encrypted key in the config dir's keys/ subdir
|
|
|
|
|
# (e.g. ~/.config/borg/keys/ on Linux, ~/Library/Application Support/borg/keys/ on macOS)
|
2026-06-16 08:28:03 -04:00
|
|
|
$ borg repo-create --encryption=aes256-ocb --key-location=keyfile
|
2022-07-04 18:38:37 -04:00
|
|
|
|
