2018 December 13

I’ve being searching some time for a tool to allow me to do backups from large data, that works kinda like a git repository and with secure backups on mind. It should be nice also to have deduplication, so that it optimizes the storage space to me. I’ve heard too many times on a tool named borg, that ticks all those boxes and that I have been using for some time now. The main idea is that you have a “repository”, where each one of them has a logical set of data you want to backup - e.g., your home folder. To have secure access to this repository, you have a key protected by a safe password. Let’s see how to create a backup repository on a remote machine. On my case, I use arch linux as my linux distro and I have installed borg to both my local machine and the remote one: $ yay -S borg –noconfirm Then, I created my repository: $ borg init -v –show-rc -e keyfile tiago@home_server:/backups/borg/freelances As a safe measure, I exported my repository key (remember to keep it somewhere safe for obvious reasons): $ borg key export -v –show-rc tiago@home_server:/backups/borg/freelances borg.freelances.key Just copying a repository contents (which have a structure that is analog to a git one) is not enough to access it. You will need its key and the key password in order to access it completely. The borg configuration, and its keys, are at $HOME/.config/borg. You need to copy the keys at $HOME/.config/borg/keys of the server you want to access and have their password in order to access the backup on a remote server or to backup a repository to access somewhere else.


  • List all backups on a repository:
borg list -v --show-rc tiago@home_server:/backups/borg/freelances
  • See contents of a specific backup (known as “archive”):
borg list -v --show-rc /mnt/s3fs/borg::freelances-20181213_0702_1544691735
  • See the difference between archives:
borg diff -v --show-rc /mnt/s3fs/borg::freelances-20181213_0702_1544691735 freelances-20181212_0700_1544691345
  • Export a tar.bz2 from a specific archive:
borg export-tar -v --show-rc --progress /mnt/s3fs/borg::freelances-20181213_0702_1544691735 /storage/temp/borg.freelances-20181213_0702_1544691735.tar.bz2

IMPORTANT: that is a lossy conversion: BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported. Timestamp resolution is limited to whole seconds, not the nanosecond resolution otherwise supported by Borg.

  • Extract all files of a specific archive:
# CAUTION: create and enter an EMPTY DIRECTORY where the archive contents will be stored at
borg extract -v --show-rc /mnt/s3fs/borg::freelances-20181213_0702_1544691735
  • Extract file of a specific archive:
# CAUTION: create and enter an EMPTY DIRECTORY where the file will be stored at
borg extract -v --show-rc /mnt/s3fs/borg::freelances-20181213_0702_1544691735 home/tiago/tmp/my_file.txt
# (the file will be at the current directory, with its path preserved on the same original filesystem tree)
  • How to break the lock (in case you are receiving lock.exclusive errors):
borg break-lock -v --show-rc /mnt/s3fs
  • How to check a repository integrity:
borg check -vp --show-rc /mnt/s3fs
  • How to repair a repository integrity:
borg check -vp --show-rc --repair /mnt/s3fs


https://blog.andrewkeech.com/posts/170718_borg.html https://handyman.dulare.com/safe-and-efficient-backups-with-borg/