Homepage Back to list

An Actually Easy Guide To Borg

All the guides and documentations I saw online were very confusing to the new user, so I decided to write a real quick starters guide and some other information. Please note that this quick-start guide doesn't go over using Borg with external servers. If you want a guide on how to use Borg with external servers, check Borg's documentation on how to run specific commands with 3rd party Borg servers involved.

To create a repository: borg init -e $encryption_mode /path/to/repo. Change $encryption_format with whichever encryption mode you'd like [1].

To create archives: borg create /path/to/repo::archive_name /path/to/source. Most used flags include "-p" to show progress, "-C compression_algorithm" to compress [2]. Borg gives a list of available encryption algorithms when you press tab after typing "-C".

Dealing with keys: borg key change-passphrase /path/to/repo to change your repo passphrase, borg key export /path/to/repo /path/to/output to export your key (additional flags include "--paper" for printing and "--qr-html" for qr-scanning or printing), borg key import /path/to/repo /path/to/key to import your key (additional flags include "--paper" to import a file that was exported via the same flag).

Extracting archives: borg extract /path/to/repo::archive_name to extract an archive. You also can add a directory of content you want extracted specifically (borg extract /path/to/repo::archive_name /path/to/content). The extraction is done to the same directory as you are, so you should go to the directory you wish to have your archive extracted. If you do borg export-tar /path/to/repo::archive_name it will export that archive as a .tar archive

Repo management:

• borg list /path/to/repo::archive_name to list all the items in an archive, or you can omit the "::archive_name" to list all the archives that are in a repo.
• borg delete /path/to/repo::archive_name to delete an archive, or you can delete omit "::archive_name" to delete the whole repo.

• borg prune -$OPTIONS /path/to/repo to prune your repository. Options include:

  • "--keep-last X" to keep the last X number of archives,
  • "--keep-within Xtime" to keep all archives within X amount of time ("Xh" for hours, "Xd" for days, "Xw" for weeks, "Xm" for months and "Xy" for years),

• borg mount /path/to/repo::archive_name /path/to/mountpoint to mount an archive to a FUSE filesystem. You can omit "::archive_name" to mount the whole repository. To unmount it, borg umount /path/to/mountpoint
• borg upgrade /path/to/repo to upgrade your repository to a new version. I'd recommend reading the documentation as it is a bit picky thing to run.

That's it. This is all you will (probably) need

If you need more information, be sure to read Borg's own documentation as it has much more flexibility than what I write here as this is supposed to be a starter guide, and not a power-user guide. Be sure to also donate to Borg if you want to.

Footnotes

[1] Borg wiki about encryption modes but basically "repokey" is when your keyfile is in the repo (encrypted) [in $REPO_DIR/config] so you only need the passphrase but "keyfile" is when the keyfile seperate [in ~/.config/borg/keys/], so you need both your passphrase and your keyfile to access your repo.

[2] Compression before encryption is not recommended as it can leak important metadata about the encryption that can be exploited.