Home BorgBackup How To Backup And Restore Files Using BorgBackup In Linux

How To Backup And Restore Files Using BorgBackup In Linux

Borg Backup Tutorial

By Karthick
Published: Updated: 25.4K views

In Linux, there are multiple backup tools providing functionality for system-level backup as well as user data backup. In this comprehensive article, we are going to look into what is BorgBackup and how to backup and restore files using Borg in Linux and Unix-like systems.

1. Introduction

When I am dealing with a lot of data in my work, the obvious questions that comes to my mind at first are: 1. What if I lose my data? 2. How well my data is secured?

The same scenario will be applied to the personal machine. You should always backup your data depending upon its importance and protect your data against illegal access.

Whether it is your personal data or official data, you should always plan a good backup strategy and use robust backup tools that will help you to backup your important data. One of the most recommended and widely used opensource backup application is "Borg".

2. What is Borg?

BorgBackup, shortly borg, is a backup tool that is created to provide an efficient way to backup your data using the deduplicating technique.

Some of the unique features of borg are listed below.

  • Deduplication - Deduplicating technique stores only the incremental copies of the data which is perfect to take daily backups.
  • Cross-platform - Borg can be installed and used in Linux, Mac OS X, and FreeBSD.
  • Secure - Supports data encryption using AES encryption (256-bit), to verify the authenticity HMAC-SHA256 is used.
  • Compression - Data can be compressed using the following compression methods:
    • LZ4 -> Super Fast, Low Compression.
    • ZSTD -> High Speed and Low Compression to Low Speed and High Compression.
    • ZLIB -> Medium Speed, Medium Compression.
    • LZMA -> Low Speed, High Compression.
  • Remote backup - Data can be backed up to remote machines over SSH protocol.

3. Install Borg in Linux

Borg is available in the default repositories of most Linux distributions. So, It can be installed using the distribution-specific package manager.

To Install borg in Alpine Linux, run the following command:

$ sudo apk add borgbackup

To Install borg in Arch Linux and its variants such as EndeavourOS and Manjaro Linux, run the following command:

$ sudo pacman -S borg

Install borg in Debian/Ubuntu-based distribution:

$ sudo apt install borgbackup -y

Install borg in Fedora, RHEL, CentOS, AlmaLinux and Rocky Linux:

$ sudo dnf install borgbackup -y

Install Borg in openSUSE:

$ sudo zypper install borgbackup -y

Since borg is written in Python, you can use the python package manager PiP to install borg. Depending upon installed pip version, you can run either of the following commands.

$ pip install borgbackup


$ pip3 install borgbackup

Once installed, you can verify the Borg installation by running the version and help commands:

$ borg --version
$ borg --help
Display borg version and help section
Display borg version and help section

4. Take your first backup using Borg

You have to understand two important terms before taking your first backup.

  • Archives - Backup copy (Snapshots) of your data will be referred to as an archive.
  • Repositories - Directories in your local or remote file system where archives are stored.

First Initialize a repository (directory) where the archives will be stored.

I have a list of files in a directory named "source" and created a new directory named "backup" which will act as my repository for storing archives.

Backup directory
Backup directory

5. Initialize repository

Run the borg init command to initialize the backup directory. The backup directory can be in a local machine or a remote machine. In my case, I am initializing the directory (i.e. backup) which I already created.

$ borg init --encryption=none /home/karthick/borg/backup
$ borg init --encryption=repokey /home/karthick/borg/backup
$ borg init --encryption=keyfile /home/karthick/borg/backup

When you initialize a repository you can choose the type of encryption. When you use encryption type as "None", no encryption will be applied. When you use "repokey" and "keyfile" as encryption types it uses AES-CTR-256 for encryption.

Choose any one encryption type and run the init command. In my case, I am choosing encryption type as none for demonstration purposes.

6. Backup files using Borg

6.1. Create first backup

Once the repository is initialized, you can create backup archives by running the following command:

$ borg create --stats --progress /home/karthick/borg/backup::25-11-2021 /home/karthick/borg/source/

Here, I am giving the archive name in date format "25-11-2021" simulating daily backups. Without --stats and --progress flags, the output of create command will be quiet.

Create Borg archive
Create Borg archive

6.2. Display files when creating backups

You can also combine the --list and -v flag to display the list of files in the archive while running borg create command.

$ borg create --list -v /home/karthick/borg/backup/::27-11-2021 /home/karthick/borg/source/
Create command - List and verbose
Create command - List and verbose

6.3. Create compressed backups

By default, borg uses the lz4 compression algorithm. The lz4 compression algorithm is very fast and has a low compression ratio. In case if you want to use a different compression algorithm, you can use the --compression flag and pass the type along with the compression level.

For example, if I wish to use the zstd algorithm, then my command will be as follows.

$ borg create --compression zstd,1 /home/karthick/borg/backup/::27-11-2021 /home/karthick/borg/source/

You can take a look at different compression algorithms and its level from the Borg official documentation.

6.4. Get archive information

You can use the info command to get information about a specific archive.

$ borg info /home/karthick/borg/backup/::25-11-2021
View Borg archive information
View Borg archive information

7. List backups

Using the borg list command, you can query your repository to find the list of archives and what files are there inside the archives.

To get the list of archives alone, run the following command.

$ borg list /home/karthick/borg/backup

Sample output:

25-11-2021 Thu, 2021-11-25 13:16:53 [653d952301fc70ab9f2f74794361359144e05f5534e668ef4a4957d2c7f67937]
26-11-2021 Thu, 2021-11-25 13:19:51 [473bbe30fbe8597b63910310d567e69b501b2fb7127f04a78da76ab59d90114f]
27-11-2021 Thu, 2021-11-25 13:20:01 [0e6813f1a05246d43d196de9d28034d0397b4ae50cd20ee50163e347efee3e2a]

You can also use the --json flag which will give more information about the repository and list of archives in the json format.

$ borg list --json /home/karthick/borg/backup
List borg backups in json format
List borg backups in json format

7.1. List files in archives

To get the list of files inside an archive, run the following command. Here I am listing files from the archive "25-11-2021".

$ borg list /home/karthick/borg/backup::25-11-2021

Sample output:

drwxrwxr-x karthick karthick 0 Thu, 2021-11-25 12:48:58 home/karthick/borg/source
-rw-r--r-- karthick karthick 807 Mon, 2021-11-22 13:35:51 home/karthick/borg/source/project_profile.txt
-rw------- karthick karthick 2301 Mon, 2021-11-22 13:35:51 home/karthick/borg/source/hist.txt
-rw-r--r-- karthick karthick 220 Mon, 2021-11-22 13:35:51 home/karthick/borg/source/external.txt
-rw-r--r-- karthick karthick 3895 Mon, 2021-11-22 13:35:51 home/karthick/borg/source/config.txt

You can also use the --json-lines flag to list the archive contents in JSON format.

Output in json format
Output in json format

7.2. Exclude files and directories from backup

You can exclude files and directories using the -e or --exclude flag.

$ borg list /home/karthick/borg/backup::25-11-2021 --exclude "hist"
Exclude files from backup
Exclude files from backup

8. Find the difference between archives

You can use the diff command to compare two archives.

I am creating a new file named datafile.txt under the source directory. I have also created one more archive named 28-11-2021.

Now I can compare the new archive and the old archive like below:

$ borg diff /home/karthick/borg/backup/::27-11-2021 28-11-2021
added 2.89 kB home/karthick/borg/source/datafile.txt
Borg diff command
Borg diff command

9. Rename archives

Once an archive is created and if you wish to rename it you can do it using the borg rename command.

Let’s say if I wish to rename the archive "27-11-2021" to "29-11-2021", I can do this by running the following command.

$ borg rename /home/karthick/borg/backup/::27-11-2021 29-11-2021
Rename an archive
Rename an archive

10. Restore files using borg (Extract the data from archive)

The prime focus of backing up the data is to restore it whenever needed. So you can use the borg extract command to retrieve the data from the archives. When you run the extract command, it will extract the data to the current working directory from where you are running the extract command from.

Run the following command to extract an archive to the current working directory. With the -v and --list flag added, it will show you the list of extracted files.

$ borg extract -v --list backup/::25-11-2021
Extract borg archive
Extract borg archive

You can also use --dry-run flag which will just display what is going to be extracted instead of extracting it.

$ borg extract --dry-run -v --list backup/::25-11-2021

You can extract a particular directory from the archive by passing the directory name. Since I have only one directory in my archive it will retrieve that.

$ borg extract -v --list backup/::25-11-2021 home/karthick/borg/source/

10.1. Exclude files from restore

You can also add --exclude to omit files when extracting a directory. Here I am extracting all files excluding any file with hist.

$ borg extract -v --list backup/::25-11-2021 home/karthick/borg/source/ --exclude "hist"
Excluding files
Excluding files

11. Mount and unmount repository and archives

You can mount the repository or a particular archive as a fuse file system. You can then restore files using the mounted archive.

To mount the entire repository, run the following commands:

$ mkdir /tmp/borg/
$ borg mount /home/karthick/borg/backup/ /tmp/borg/
$ ls -l /tmp/borg/

Sample output:

drwxr-xr-x 1 karthick karthick 0 Nov 25 16:31 25-11-2021
drwxr-xr-x 1 karthick karthick 0 Nov 25 16:31 26-11-2021
drwxr-xr-x 1 karthick karthick 0 Nov 25 16:31 27-11-2021
drwxr-xr-x 1 karthick karthick 0 Nov 25 16:31 28-11-2021
drwxr-xr-x 1 karthick karthick 0 Nov 25 16:32 29-11-2021

You can see from the above output all my archives are mounted as a directory and now I can just simply restore by copying the files.

To mount particular archives, just add the archive name along with the repository.

$ borg mount /home/karthick/borg/backup/::25-11-2021 /tmp/borg/

To unmount the mounted repository or archives, use the borg umount command.

$ borg umount /tmp/borg
$ ls -l /tmp/borg

12. Prune archives

The borg prune command will be very useful when you are automating your backups and just want to maintain only certain copies and clean the remaining copies.

Borg prune command options
Borg prune command options

The options in the above table decide how many archive copies to be held in your repository. For example, if I wish to keep just 2 copies from my weekly backup, then my command will be as follows.

$ borg prune -v --list --keep-weekly=2 /home/karthick/borg/backup/

You can also apply the above-said condition to certain archives alone. For example, let’s say I have 10 archives in my repository and I wish to apply the retention rule for archive7 then I can use the --prefix flag to set the condition.

$ borg prune -v --list --keep-weekly=2 --prefix='{archive name}' /home/karthick/borg/backup/

Before running the prune command, do a dry run by using the --dry-run flag.

13. Delete repository and archive

You can delete an archive or the entire repository using the borg delete command.

To delete a single archive, you have to provide the archive name.

$ borg delete /home/karthick/borg/backup/::26-11-2021
Delete single archive
Delete single archive

To delete the entire archive, just provide the repository path. When deleting the entire directory, you will be prompted to provide confirmation.

$ borg delete /home/karthick/borg/backup/
Delete repository
Delete repository

14. Change key passphrase

Till now I have shown my example without applying any encryption to the repository. As foretold in the initial section, you can initialize a directory with encryption enabled and if repokey or keyfile is used, it will ask you to set passphrase optionally.

$ borg init --encryption=repokey /home/karthick/borg/bkup/

From now on, whenever I try to do any operation over this repository, I should to provide the passphrase every time. Take a look at the below image, I am trying to list the repository and I have to provide a passphrase for it.

List repository
List repository

Now let’s say you wish to change the passphrase, then you can do that using the borg change-passphrase command.

$ borg key change-passphrase -v /home/karthick/borg/bkup
Change passphrase
Change passphrase

You can also set the passphrase using environment variables.

$ BORG_PASSPHRASE="old password" BORG_NEW_PASSPHRASE="new password" borg key change-passphrase /home/karthick/borg/bkup

15. Export and import key

You can backup the repository key by exporting it and later import it if needed.

To export the key, run the following command:

$ borg key export bkup/ ./key
$ cat ./key

To import the key to the same repository, run the following command:

$ borg key import bkup/ ./key
Key export and import
Key export and import

16. Working with remote repositories

Whatever we have seen till now is backing up your data in the same machine. Borg also supports remote repositories where you can backup your data in any remote machine. The remote host should be accessible through SSH.


$ borg init user@hostname:/path/to/repo


$ borg init karthick@ostechnix:/home/karthick/borg/bkup

You can do all kinds of similar operations that you can do with local backup. For example, to restore the backup you can use extract and you can also use the mount command to mount a remote repository.

Here when pointing to the remote directory you have to point the ssh protocol as "ssh://username@hostname:port/path/to/repo".

$ borg mount ssh://karthick@ostechnix:2222/home/karthick/borg/bkup /tmp/borg
$ borg extract ssh://karthick@ostechnix:2222/home/karthick/borg/bkup

17. Borg GUI desktop clients

Since BorgBackup is purely a commandline tool, it is nearly impossible to remember all the commands. Some of you might prefer a nice graphical application that allows you to backup data via a graphical interface. Worry not!

Vorta is a GUI desktop client for BorgBackup. Using Vorta, you can easily integrate the Borg application to your favorite desktop environment. No need to memorize the commands. Everything can be done via a simple graphical interface!

For more details on how to install and use Vorta, refer the following guide.

18. Conclusion

In this article, we have seen how to use borg to backup and restore your data in Linux. Borg has so many features which you can understand by testing the tool. A good alternative for borg will be Timeshift to take system-level backup and rsync to take user files and directories.


You May Also Like

1 comment

Jalal Hajigholamali December 2, 2021 - 10:40 am

Thanks a lot
very useful article


Leave a Comment

* By using this form you agree with the storage and handling of your data by this website.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

This website uses cookies to improve your experience. By using this site, we will assume that you're OK with it. Accept Read More