BorgBackup Plugin For OMV7

• The openmediavault-borgbackup plugin installs and configures borgbackup in openmediavault and provides an integrated graphical user interface for its management.
• In the current state, the plugin allows configuring local or remote backups.

This OMV plugin uses BorgBackup, which was created by a third party. See the project web page → BorgBackup for more detailed information and support.

Quote:

“BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption.

The main goal of Borg is to provide an efficient and secure way to backup data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. The authenticated encryption technique makes it suitable for backups to not fully trusted targets.”

Backup

The basic standard operation of Borg consists of:

• Create a REPOSITORY and initialize it to receive a backup or more than one. Each backup will be stored in a ARCHIVE.
• Run a backup of one or more files or folders packed into a ARCHIVE within the REPOSITORY.

The result of the above will be a folder that Borg calls REPOSITORY in which there will be what Borg calls one or more ARCHIVES. Each ARCHIVE contains a backup inside. When a backup is made, Borg is responsible for automatically deduplicating it. That is, if in ARCHIVE_1 there are three files that are also in ARCHIVE_2 those three files will be replaced in ARCHIVE_2 by links to those existing files in ARCHIVE_1, in this way the information is not duplicated (this is a simple explanation, it actually works at the block level, a little more complicated but the concept is the same).

Borg does not have automation tools to run backups, it is the openmediavault-borgbackup plugin that does the automation. To do this, in the plugin's GUI we create a ARCHIVE to which we give a name like ARCHIVE_NAME, that is equivalent to defining what folders/files we want to backup in that ARCHIVE and at the same time a retention schedule. If we activate this programming, the plugin will be in charge of making automatic backups. Each backup will be stored in the REPOSITORY within an ARCHIVE whose name will be ARCHIVE_NAME_TIME, with TIME being a label with the creation date of that backup. At the same time, every time a backup is made, the plugin is responsible for deleting the oldest backups that we no longer want according to the scheduled retention schedule. For example, if the daily retention period is 7, a daily backup of the last 7 days will be saved and the previous ones will be deleted.

You can consult a detailed procedure for configuring a backup using the openmediavault-borgbackup plugin at the end of this document.

Restore

There are two ways to restore a backup.

• If you know the location of the file you want to restore, you can do it directly. The plugin's GUI allows us to define the path where the file you want to restore is located.
• If you do not know the exact location or version of the file or files you want to restore you need to inspect the contents of the backup. Borg allows you to mount a ARCHIVE in a server folder as if it were a standard file system. This allows us to inspect the content from the CLI or from any file explorer (such as WinSCP) and copy the files we need to another place. Once the files we need have been restored, we can unmount that folder.

• Installation.
• Repos tab.
• Archives tab.
• Environment Variables tab.
• Local backup configuration procedure.
• Remote backup configuration procedure.

• OMV-Extras must be pre-installed.

In OMV7's GUI:
Under SYSTEM > PLUGINS, find and highlight openmediavault-borgbackup 7.X, and click the INSTALL button.

In this tab we can both create and manage Borg REPOSITORIES and mount or dismount ARCHIVES for inspection or restoration of backups.

Allows you to create and initialize a Borg REPOSITORY or import an existing one. Pressing the button will open a dialog box with the following fields:

• NAME: Defines the name of the REPOSITORY here.
• TYPE: Choose whether you are creating a local or remote REPOSITORY.
  • LOCAL: For repositories located on the same server.
    • SHARED FOLDER: Choose a shared folder to store the REPOSITORY on your server. You can press the +CREATE button on the right to create a new shared folder.
  • REMOTE: For repositories located on a remote server.
    • REMOTE PATH: Defines the path to the REPOSITORY, it must have the format: user@hostname:path For it to work you must have the ssh keys configured.
• PASSPHRASE: Defines a password to access the REPOSITORY. Do not use spaces or special symbols, they may not be interpreted correctly and create conflicts.
• ENCRYPTION. Check this box if you want the REPOSITORY to be encrypted.
• SKIP INIT. If you are trying to import an already created REPOSITORY, check this box, this way the REPOSITORY initialization processes will not be carried out since said REPOSITORY is already initialized.
• Press the SAVE button. You will return to the REPOS form where a line should appear with the values ​​of your new REPOSITORY.

Link to official documentation → borg create

Allows you to change the location of a REPOSITORY already configured in the plugin.

• TYPE
  • LOCAL: Select LOCAL if you want to move the REPOSITORY to a folder on the same server.
    • SHARED FOLDER: Select the shared folder where you are going to move the REPOSITORY.
  • REMOTE: Select REMOTE if you want to move the REPOSITORY to a remote server.
    • REMOTE PATH: Defines the path to the REPOSITORY, it must have the format: user@hostname:path For it to work you must have the ssh keys configured.
• Press the CHANGE button to apply the changes.

Allows you to delete a REPOSITORY defined in the plugin. Select a REPOSITORY and press the REMOVE button.

Allows you to delete a REPOSITORY defined in the plugin while deleting the folder in the file system and all its contents. Select a REPOSITORY and press the REMOVE button.

• In order to delete a REPOSITORY and its contents you must first delete the ARCHIVES that point to this REPOSITORY in the ARCHIVE tab.
• After deleting the REPOSITORY remember to also delete the shared folder that the REPOSITORY was in.

Link to official documentation → borg delete

Allows you to change the password for accessing the REPOSITORY. Select a REPOSITORY in the form and press the CHANGE PASSPHRASE button:

• PASSPHRASE: Enter the new password. Do not use spaces or special symbols, they may not be interpreted correctly and create conflicts.
• Press the CHANGE button and apply the changes.

Link to official documentation → borg key change-passphrase

Allows you to check the consistency of a REPOSITORY and its files.

If it is a remote REPOSITORY the checks will be executed on the remote server without causing massive traffic. The plugin offers several levels of checking:

• ALL: borg check path_to_repo It will check the consistency of REPOSITORIES and ARCHIVES.
• REPOS ONLY: borg check --repository-only path_to_repo It will check the consistency of REPOSITORIES only.
• ARCHIVES ONLY: borg check --archives-only path_to_repo It will check the consistency of ARCHIVES only.
• VERIFY: borg check --verify-data path_to_repo The same verification will be done as with the ALL option, it will verify the consistency of REPOSITORIES and ARCHIVES. But it is also applied with the --verify-data parameter which causes a verification of the integrity of the cryptographic file data to be carried out at the same time.

Link to official documentation → borg check

Allows you to create a tar-compressed file that contains all the files in the ARCHIVE. The export file will be created in the chosen shared folder with the same name as the file and with the extension .tar.gz. Select a REPOSITORY and press the EXPORT button:

• ARCHIVE: Select a ARCHIVE to export from the list of existing ARCHIVES in the REPOSITORY.
• SHARED FOLDER: Select a shared folder where to place the export ARCHIVE.
• Press the EXPORT button to execute the export.

Link to official documentation → borg export-tar

Allows you to extract all files from an ARCHIVE to a shared folder. Select a REPOSITORY and press the EXTRACT button:

• ARCHIVE: Select a ARCHIVE to extract from those existing in the REPOSITORY.
• ORIGINAL LOCATION: Activate this button if you want to extract all the contents of the ARCHIVE to its original location.
• SHARED FOLDER: If you do not press the previous button, you must choose a shared folder as the extraction destination. In this shared folder the tree of existing folders within the ARCHIVE will be reproduced and all existing files will be extracted in their corresponding position.
• Press the EXTRACT button to start execution.

Link to official documentation → borg extract

Allows you to list existing ARCHIVES in a REPOSITORY. Select a REPOSITORY and press the LIST button:

• A code box will be displayed with the list of ARCHIVES.

Link to official documentation → borg list

Allows you to compact a REPOSITORY. Select a REPOSITORY and press the COMPACT button:

• A code box will open showing the compaction result.

Link to official documentation → borg compact

Allows you to view detailed information about a REPOSITORY. Select a REPOSITORY and press the INFO button:

• A code box will open showing the information of the selected REPOSITORY.

Link to official documentation → borg info

Allows you to download the encryption key of a REPOSITORY to your PC if the REPOSITORY is encrypted. Select an REPOSITORY and press the DOWNLOAD REPO KEYFILE button:

• The file with the key will be downloaded to your browser.

Link to official documentation → borg key export

Allows you to mount all the ARCHIVES of a REPOSITORY in a shared folder, a subfolder will be created for each ARCHIVE labeled with the date and time of its creation. You can navigate through the folder tree to inspect all existing versions of the files contained in the REPOSITORY and copy the files you need to restore elsewhere using a terminal or any file explorer such as WinSCP. Select a REPOSITORY and press the MOUNT button:

• SHARED FOLDER: Select a shared folder in which to mount the REPOSITORY.
• VERSIONS: If you activate this button, a montage will be made so that a subfolder will be created for each file that will contain the different versions of that file. This assembly procedure is experimental, the design may change in the future.
• Press the MOUNT button to mount. Remember to umount it when you are done.

Link to official documentation → borg mount

Allows you to unmount a previously mounted REPOSITORY. Select the mounted REPOSITORY and press the UMOUNT button.

• The REPOSITORY will be unmounted and the subfolder created for the mount will still be deleted.

Link to official documentation → borg umount

Shows a link to the official Borgbackup documentation and another link to this document on the omv-extras wiki.

In this tab we can manage ARCHIVES to define the backups that we want to generate.

By generating a ARCHIVE in the plugin we define what the backup sources are and at the same time we define a schedule to execute the backups as well as the retention policy for the backup versions. In each execution of a backup the plugin will generate a new ARCHIVE and add a suffix to it with the date and time of its creation.

Allows you to create a ARCHIVE. This tab is a custom feature of the plugin that allows automatic backup scheduling, please read the Summary at the beginning of this document for more details. You must previously have created a REPOSITORY in the REPOS tab. Press the CREATE button:

• ENABLE: Determines whether this schedule will run automatically or not.
• NAME/PREFIX: This is the name that will be given to each backup executed, to which the date and time of creation will be added as a suffix. Don't use spaces or special characters.
• REPO: Choose one of the repositories created with the plugin to store backups of this ARCHIVE.
• COMPRESSION TYPE: Optional. You can choose whether or not you want to compress the backups and the type of compression.
• COMPRESSION RATIO: The compression ratio applied if you have chosen to compress. From 0 for lower compression and higher speed to 9 for higher compression and lower speed.
• ONE FILESYSTEM ONLY: Enable this to exclude the contents of other mounted file systems.
• NO ATIME: Enable this to exclude the last access time of each file.
• INCLUDES: Write the absolute paths of the folders or files that you want to include in the backup. If you establish more than one route you must separate them with a comma. If a path contains spaces, enclose it in quotes.
• EXCLUDES: Optional, you can write paths to exclude from the backup.
• RETENTION PERIODS: → RETAIN HOURLY, RETAIN DAILY, RETAIN WEEKLY, RETAIN MONTHLY, RETAIN YEARLY. These are the retention periods for backups that at the same time establish the backup execution schedule:
  • Backups will be executed regularly according to the first value other than 0, that is, if you want to make a backup every day, set the hourly value equal to 0 and the daily value with a value other than 0.
  • The value established in each field will determine how many versions are maintained during that period; the oldest versions that exceed that total will be deleted after the next backup is executed.
• RATE LIMIT: Optional. This value will limit the upload bandwidth. Set a value (in KB/s) if you need it to not saturate the bandwidth of a remote server. Set the value 0 for unlimited speed.
• LIST: Activating this button will generate a list of backup files and directories on each run.
• EMAIL: Activating this option will cause you to receive an email with the result of each backup. If you do not activate it, you will receive an email only in case an error occurs. To receive emails you must previously configure notifications in the OMV GUI.
• PRE-SCRIPT: Allows you to run a script before executing the backup. To do this you must define the absolute path where the script is located.
• POST-SCRIPT: Allows you to execute a script after the backup has been executed. To do this you must define the absolute path where the script is located.
• Press the SAVE button to apply the changes. A line will appear in the form with the name of the ARCHIVE you just created.

The OMV_BORGBACKUP_STARTING_HOUR environment variable determines the start time for annual and monthly cron tasks and start time +1 for weekly and daily cron tasks. Defaults to 2.00 a.m. Change OMV_BORGBACKUP_STARTING_HOUR in /etc/default/openmediavault to the start time you want. Then run:

sudo omv-salt stage run prepare

sudo omv-salt deploy run borgbackup

Allows you to edit a ARCHIVE. Select a ARCHIVE in the form and press the EDIT button:

• A dialog box will open with all the ARCHIVE settings and you can edit them.
• Press the SAVE button to apply the changes.

Allows you to delete a ARCHIVE. Select a ARCHIVE in the form and press the DELETE button:

• The selected programming ARCHIVE will be deleted and all existing backups of this ARCHIVE in the REPOSITORY will also be deleted.

Allows you to list information about all backups executed with the selected ARCHIVE. Select a ARCHIVE and press the INFO button:

• A code box will open showing the list of execution information for each backup.

Link to official documentation → borg info

Allows you to manually run a backup from the existing schedule to a ARCHIVE. Select a ARCHIVE and press the RUN button:

• A code box will open showing the backup execution command.

Shows a link to the official Borgbackup documentation and another link to this document on the omv-extras wiki.

Borg uses some environment variables for automation, check the official documentation to find out what they are: Environment Variables

This tab allows you to customize those Borg environment variables.

Allows you to add a Borg environment variable. Press the CREATE button, a dialog box will open with the following fields:

• NAME: The name of the Borg environment variable you want to customize.
• VALUE: The value of the Borg environment variable.
• REPO: The REPOSITORY to which this environment variable will be applied.
• Press the SAVE button to apply the changes.

Allows you to edit a Borg environment variable already created in the plugin. Select an environment variable in the form and press the EDIT button, a dialog box will open allowing you to edit the values ​​of the selected environment variable.

Allows you to delete a Borg environment variable already created in the plugin. Select an environment variable in the form and press the DELETE button, confirm the deletion and apply the changes to delete it.

Below is a simple example with the necessary steps to configure a backup and store it on the same server. The requirements for this backup are:

• We want to make a backup of the contents of the users Mary and Peter's folders.
• We want to be able to restore at any time versions of the last 8 hours of Mary's folder, daily versions of the last week, weekly versions of the last month and monthly versions of the last year. In Peter's folder we do not need versions from the last 8 hours, daily versions are enough.
• We want to store the backup on a disk that we have installed on our server dedicated to backups.
• We want the backup to be compressed and encrypted.

In our server environment we have:

• The absolute path of the mary folder is /srv/dev-disk-by-uuid-eb24d436-abba-4190-a343-4741b86fd2a7/data/documents/mary
• The absolute path of the peter folder is /srv/dev-disk-by-uuid-eb24d436-abba-4190-a343-4741b86fd2a7/data/documents/peter

The first step is to create the REPOSITORY where we are going to store the backups. In the SERVICES > BORGBACKUP > REPOS tab, press the CREATE button:

• NAME: borg_local_repo
• TYPE: Local
• SHARED FOLDER:
  • We create a shared folder in STORAGE > SHARED FOLDERS with the name borg_local_repo. To do this we can press the +CREATE button to the right of this field. We must choose the hard drive dedicated to our server backups for this shared folder.
  • We select the shared folder borg_local_repo that we just created.
• PASSPHRASE: z6n7WdqxFhtKSRoi29zdgHs9eSUycdvKbrqUEYuV (we write a strong password without spaces or special characters)
• ENCRYPTION: We activate this button so that the REPOSITORY is encrypted.
• SKIP INIT: We deactivate this button since we are creating a new REPOSITORY.
• We press the SAVE button and apply the changes.

The REPOSITORY has already been created and initialized by the plugin. If we go to the shared folder borg_local_repo we will see inside the necessary configuration files that Borg has created. The REPOSITORY is ready to receive backups.

To access this REPOSITORY in the future we will need the access password that we just wrote but also the encryption key that Borg has generated since we have decided to encrypt the REPOSITORY. This encryption key is stored in the /root folder on the server. To ensure that we can access the REPOSITORY if something were to happen to our operating system drive we download the encryption key.

• We select the newly created REPOSITORY in the form and press the DOWNLOAD REPO KEYFILE button.

Our browser should have received a file with the encryption key from the REPOSITORY. We save this file along with the access key to the REPOSITORY in a safe place (for example a password application like KeepassXC)

The second step is to create a ARCHIVE. Since we have different timing needs for Mary's and Peter's folders we will need to create two separate ARCHIVES that will be stored in the same REPOSITORY. Each of them defines where the content we want to back up is, how often and how many versions we want to maintain.

We start with the ARCHIVE in the mary folder. In the SERVICES > BORGBACKUP > REPOS tab, press the CREATE button and establish the following configuration:

• ENABLE: We activate this button so that the programming is active.
• NAME/PREFIX: mary
• REPO: We select the REPOSITORY that we have created, borg_local_repo
• COMPRESSION TYPE: lz4 (to compress the backup content)
• COMPRESSION RATIO: 9 (highest compression value)
• ONE FILESYSTEM ONLY: We activate this button since we only want to backup a folder in a single file system.
• NO ATIME: We activate this button to avoid backing up versions with different access times.
• INCLUDES: /srv/dev-disk-by-uuid-eb24d436-abba-4190-a343-4741b86fd2a7/data/documents/mary
• EXCLUDES: (We leave it blank, we don't want to exclude anything from the mary folder)
• RETAIN HOURLY: 8 (the value 8, non-zero, determines that backups are made every hour since it is the first non-zero value and the backups of the last 8 hours will also be kept)
• RETAIN DAILY: 7 (the value 7 determines that the last 7 daily backups will be retained)
• RETAIN WEEKLY: 4 (the value 4 determines that the last 4 weekly backups will be retained)
• RETAIN MONTHLY: 12 (the value 12 determines that the last 12 monthly backups will be retained)
• RETAIN YEARLY: 0
• RATE LIMIT: 0 (unlimited rate since this is a local REPOSITORY)
• LIST: We activate this button to have a list of backup files and directories in each execution.
• EMAIL: We deactivate this button, this way we will only receive an email if there is an error during the execution of a backup.
• PRE-SCRIPT: (we leave it blank, we do not need to run any script before the backup)
• POST-SCRIPT: (we leave it blank, we do not need to execute any script after the backup)
• We press the SAVE button and apply changes.

At this moment, a line will appear in the form with the name mary corresponding to the ARCHIVE that we just created. If we press the RUN button we can check its execution when making the first backup.

The next step would be to create another ARCHIVE for the peter folder. We repeat the steps but in this case we change the location of the folder:

• INCLUDES: /srv/dev-disk-by-uuid-eb24d436-abba-4190-a343-4741b86fd2a7/data/documents/peter

and we also change the programming:

• RETAIN HOURLY: 0 (value 0 will prevent copies from being made every hour)
• RETAIN DAILY: 7 (the value 7, non-zero, determines that backups are made every day since it is the first non-zero value and the backups of the last 7 days will also be kept)
• RETAIN WEEKLY: 4 (the value 4 determines that the last 4 weekly backups will be retained)
• RETAIN MONTHLY: 12 (the value 12 determines that the last 12 monthly backups will be retained)
• RETAIN YEARLY: 0

The rest of the values ​​will be the same as those we established in the mary ARCHIVE. We already have our backup working.

At any time we can mount the REPOSITORY to inspect the backed up files in all their versions. Simply go to the SERVICES > BORGBACKUP > REPOS tab, select the REPOSITORY and press the MOUNT button. Choose a shared folder to create the mount and save your changes. Now you can browse the mounted folder structure and copy any file or folder to another place if you need to restore something. You can do it from the CLI or through a file explorer like WinSCP. Then unmount the REPOSITORY.

To see the versions of the backups generated so far, select the REPOSITORY and press the LIST button.

In the guides section of the Openmediavault forum there is an excellent guide to performing remote backups masterfully written by forum member auanasgheps, whom we thank for taking the time to write and maintain it. You can consult that guide if you need this type of configuration. –> [How-To] Make backups with Borg using borgbackup plugin

Borg requires SSH connections to access remote repositories. These links may be useful to you:

–> sshd(8) man page

–> Borg Hosting repositories

–> borg serve

→ openmediavault-borgbackup

We, who support the openmediavault project, hope you've found this guide to be useful and that you'll find your openmediavault server to be efficient, easy to use, and enjoyable.

If you found this plugin guide to be helpful, please consider a modest donation to support the hosting costs of this server.

OMV-Extras.org