Learn Borg Backup - Repository Initialization

#Introduction

In episode 2 we understood the architecture: repository, archive, and chunker. Now it is time for the first real step — creating the repository. The decision you make here (the encryption mode) cannot be changed without a migration, so choose with understanding, not by habit. We will also set up the Borg environment correctly so your passphrase never leaks anywhere.

#Repository Initialization

#The Basic Command

Initialize a repo with repokey-blake2

borg init --encryption=repokey-blake2 /backup/borg

Borg will ask for a passphrase (type it twice). After success, /backup/borg contains the repository structure: config, data/, and README.

Why repokey-blake2? This mode stores the key inside the repository using the BLAKE2b-256 hash, which is faster than SHA-256. It is secure enough for most workloads and does not require managing a separate key file.

#Choosing the Encryption Mode

This table is the most important decision of this episode:

Borg encryption modes

+-----------------+----------------------+----------------------+----------------------+
| Mode            | Key stored in        | Data encryption      | Notes                |
+-----------------+----------------------+----------------------+----------------------+
| repokey         | repository           | yes                  | key protected by     |
|                 |                      |                      | passphrase           |
+-----------------+----------------------+----------------------+----------------------+
| repokey-blake2  | repository           | yes                  | BLAKE2b, faster      |
+-----------------+----------------------+----------------------+----------------------+
| keyfile         | separate file        | yes                  | key must be backed up|
+-----------------+----------------------+----------------------+----------------------+
| keyfile-blake2  | separate file        | yes                  | BLAKE2b              |
+-----------------+----------------------+----------------------+----------------------+
| authenticated   | -                    | no                   | verification only    |
+-----------------+----------------------+----------------------+----------------------+
| none            | -                    | no                   | no security          |
+-----------------+----------------------+----------------------+----------------------+

repokey / repokey-blake2: the key is in the repo, encrypted with the passphrase. Easy to use; if the repo is stolen, the attacker still needs the passphrase.
keyfile / keyfile-blake2: the key is in a separate file (usually ~/.config/borg/keys/). Safer against repo theft, but you must back up the key file — losing the keyfile means losing your data.
authenticated: data is not encrypted, only integrity-verified. Suitable when the repository sits on storage that is already encrypted (e.g. ZFS encryption), since it avoids the CPU overhead of encryption.
none: no security at all. Only for experiments in isolated environments.

Important

The encryption mode cannot be changed on an existing repository. The only way to switch modes is to create a new repository and back up into it again. So choose now — for production, repokey-blake2 or keyfile-blake2 are healthy choices.

#Environment: BORG_REPO and the Passphrase

#The BORG_REPO Variable

Every Borg command can take the repo path as an argument, but that is tedious and error-prone. Use an environment variable instead:

Export BORG_REPO

export BORG_REPO=/backup/borg

After that, plain borg list is enough — no need to type the path every time.

#BORG_PASSPHRASE vs BORG_PASSCOMMAND

Borg reads the passphrase from BORG_PASSPHRASE or BORG_PASSCOMMAND. The golden rule: never hardcode the passphrase in a script or command line.

BORG_PASSPHRASE appears in the process list (visible via ps) and is stored in shell history. Avoid it for production.
BORG_PASSCOMMAND calls a command that produces the passphrase — far safer, and it can integrate with a password manager or systemd credentials.

Using BORG_PASSCOMMAND

export BORG_PASSCOMMAND='cat /root/.borg-passphrase'

Alternative with pass

export BORG_PASSCOMMAND='pass show backup/borg'

Prepare the passphrase file with strict permissions:

Prepare the passphrase file

sudo install -o root -m 600 /dev/null /root/.borg-passphrase
# then fill in the passphrase with an editor, saved with mode 600

#Verify the Repository

Verify the new repo

export BORG_REPO=/backup/borg
export BORG_PASSCOMMAND='cat /root/.borg-passphrase'
borg info

borg info without a path reads the repo from BORG_REPO and prints repository details — a sign that the key and passphrase match.

Warning

Forgetting the passphrase is the same as losing the entire backup — there is no shortcut. Write it down somewhere safe, keep a copy in your password manager, and (for keyfile mode) back up the key file. We cover the full strategy in episode 7.

#Common Pitfalls

Using none for important data: without encryption, a leaked repository means leaked data.
Passphrase in history: have you ever typed the passphrase as a command-line argument? Clean your history and switch to BORG_PASSCOMMAND.
Different encryption modes across hosts: if two hosts share one repo, both must use the same key. For per-host repos, always create separate repos (episode 14).

#Closing

borg init --encryption=repokey-blake2 /backup/borg is the first safe step.
Understand the difference between repokey, keyfile, and authenticated before choosing — the mode cannot be changed.
Use BORG_REPO to simplify your commands.
Use BORG_PASSCOMMAND, not BORG_PASSPHRASE, so the passphrase never leaks.
Keep the passphrase/keyfile safe from day one.

In episode 4 we do the real thing: your first backup with borg create — storing /home and /etc, using --exclude and --stats, and learning to read borg list and borg info output and to name archives with a host-timestamp pattern.