Differences

This shows you the differences between two versions of the page.

--- omv8:omv8_plugins:borgbackup [2025/12/22 05:11] – created chente
+++ omv8:omv8_plugins:borgbackup [2025/12/28 15:22] (current) – [Create a ARCHIVE] chente
@@ Line 9: / Line 9: @@
 \\
-=== Note ===
+===== Summary =====
-This plugin is now available for OMV8.
+  * The **openmediavault-borgbackup** plugin installs and configures BorgBackup in OpenMediaVault and provides an integrated graphical interface for management.
+  * Currently, the plugin allows configuring both local and remote backups.
-The documentation for OMV8 is still being written.
+----
-For now, you can use the documentation written for OMV7. The changes for the OMV8 version are not significant.
+=== Third-Party Software Note ===
-Go to -> [[omv7:omv7_plugins:borgbackup|BorgBackup Plugin For OMV7]]
+[[https://borgbackup.readthedocs.io/en/stable/index.html|{{ :omv8:omv8_plugins:borgbackup7-2.png?direct&200|Go to -> BorgBackup Site}}]]
+This OMV plugin uses BorgBackup, a third-party software. For detailed information and support, see the project webpage -> [[https://borgbackup.readthedocs.io/en/stable/index.html|BorgBackup]].
+----
+=== What is BorgBackup? ===
+Quote:
+//"BorgBackup (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."//
+----
+=== How does BorgBackup work? ===
+**Backup**
+The basic operation consists of:
+  * Creating a **REPOSITORY** and initializing it to receive one or more backups. Each backup is stored in an **ARCHIVE**.
+  * Running a backup of one or more files or folders packed into an **ARCHIVE** within the **REPOSITORY**.
+The result is a folder that Borg calls **REPOSITORY** containing one or more **ARCHIVES**. Each **ARCHIVE** contains a backup. Borg automatically deduplicates data: if **ARCHIVE_1** has files that also exist in **ARCHIVE_2**, those files in **ARCHIVE_2** are replaced by links to the originals in **ARCHIVE_1**. This ensures no data is duplicated (this is a simple explanation, it actually works at the block level, a little more complicated but the concept is the same).
+Borg itself does not automate backups; this is handled by the **openmediavault-borgbackup** plugin. Using the plugin GUI, you create an **ARCHIVE** and give it a name (**ARCHIVE_NAME**), define which folders/files to backup, and set a retention schedule. Automatic backups store each backup in the **REPOSITORY** within an **ARCHIVE** named **ARCHIVE_NAME_TIME**, where TIME is the creation date. The plugin also removes old backups according to the retention schedule. For example, with a daily retention of 7, the last 7 daily backups are kept and older ones deleted.
+Detailed backup configuration procedures using the plugin are provided at the end of this document.
+**Restore**
+There are two ways to restore backups:
+  * If you know the file location, restore it directly. The plugin GUI allows specifying the path.
+  * If you do not know the exact file or version, inspect the backup contents. Borg can mount an **ARCHIVE** as a filesystem, allowing inspection via CLI or file explorers (e.g., WinSCP) and copy files elsewhere. Once restored, unmount the folder.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+Beginners Info
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+Key phrase to remember:<br>
+<b>"A backup is useless if you don't know how to restore the data."</b><br>
+Always test the restoration process.
+</tr></table></body></html>
+----
+=== Index ===
+  * [[omv8:omv8_plugins:borgbackup#installation|Installation]]
+  * [[omv8:omv8_plugins:borgbackup#repos_tab|Repos Tab]]
+  * [[omv8:omv8_plugins:borgbackup#archives_tab|Archives Tab]]
+  * [[omv8:omv8_plugins:borgbackup#environment_variables_tab|Environment Variables Tab]]
+  * [[omv8:omv8_plugins:borgbackup#local_backup_configuration_procedure|Local Backup Configuration Procedure]]
+  * [[omv8:omv8_plugins:borgbackup#remote_backup_configuration_procedure|Remote Backup Configuration Procedure]]
+----
+===== Prerequisites =====
+  * [[https://wiki.omv-extras.org/doku.php?id=misc_docs:omv_extras|OMV-Extras]] must be pre-installed.
+----
+===== Installation =====
+In OMV8 GUI:
+Under **SYSTEM → Plugins**, locate **openmediavault-borgbackup 8.X** and click **Install**.
+----
+===== Repos tab =====
+In this tab we can both create and manage Borg //REPOSITORIES// and mount or dismount //ARCHIVES// for inspection or restoration of backups.
+\\
+<html><center>Under SERVICES > BORGBACKUP > REPOS</center></html>
+\\
+{{ :omv8:omv8_plugins:borgbackup8-1.png?direct&1000 |Repos tab}}
+----
+=== Create ===
+{{ :omv8:omv8_plugins:borgbackup8-2.png?direct&400|Create Repo}}
+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.
+  * STORAGE QUOTA: Set the maximum capacity of the repository. 5G, 1.5T as examples. Leave blank for no quota.
+  * 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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/create.html#borg-create|borg create]]
+----
+=== Change location ===
+Allows you to change the location of a //REPOSITORY// already configured in the plugin.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#FFB663;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+Warning
+</span></strong></td></tr><tr><td style="background-color:#FFE4A6;padding:10px;width:380px;">
+Before changing the location of a //REPOSITORY// you must move the contents of that folder to the new location.
+</tr></table></body></html>
+  * 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.
+----
+=== Change quota ===
+Allows you to change the quota of a //REPOSITORY//.
+  * TYPE
+    * NAME: Specifies the name of the repository for which you want to change the quota.
+    * CURRENT QUOTA: Current quota value.
+    * NEW QUOTA: Desired quota value.
+  * Press CHANGE to apply changes.
+----
+=== Remove ===
+Allows you to delete a //REPOSITORY// defined in the plugin. Select a //REPOSITORY// and press the REMOVE button.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Note
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+Deleting the repository will not delete the folder or its contents in the file system.<br>
+If there are ARCHIVES configured in this REPOSITORY the FILES will be removed from the plugin configuration but the files in the server file system will not be removed.
+</tr></table></body></html>
+----
+=== Delete+files ===
+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.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Note
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+When you delete an entire repository, the security information and local cache for it (if any) are also deleted.
+</tr></table></body></html>
+Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/delete.html#borg-delete|borg delete]]
+----
+=== Change passphrase ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/key.html#borg-key-change-passphrase|borg key change-passphrase]]
+----
+=== Check ===
+Allows you to check the consistency of a //REPOSITORY// and its files.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Info
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+The check command verifies the consistency of a repository and its archives. It consists of two major steps:<br>
+. Checking the consistency of the repository itself. This includes checking the segment magic headers, and both the metadata and data of all objects in the segments. The read data is checked by size and CRC. Bit rot and other types of accidental damage can be detected this way. When checking a remote repository, please note that the checks run on the server and do not cause significant network traffic.<br>
+. Checking consistency and correctness of the archive metadata and optionally archive data (requires --verify-data). This includes ensuring that the repository manifest exists, the archive metadata chunk is present, and that all chunks referencing files (items) in the archive exist. This requires reading archive and file metadata, but not data. To cryptographically verify the file (content) data integrity pass --verify-data, but keep in mind that this requires reading all data and is hence very time consuming. When checking archives of a remote repository, archive checks run on the client machine because they require decrypting data and therefore the encryption key.
+</tr></table></body></html>
+ 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.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#FFB663;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+Warning
+</span></strong></td></tr><tr><td style="background-color:#FFE4A6;padding:10px;width:380px;">
+Do not confuse data integrity of an ARCHIVE in a REPOSITORY with data integrity of the backup source (your file system on the server where the data from which the backup is made is stored).<br>
+<b>Borgbakup does not in any way guarantee the integrity or bitrot of the backup source data.</b> Only integrity checks are performed on the data backed up in the REPOSITORY. If the data is corrupted at the source, it will end up irreparably corrupted in the backup.<br>
+If you need to ensure the integrity of files on your file system, you should use other means, such as a COW file system such as ZFS or BTRFS or a parity checking system such as SnapRaid. <b>Borgbackup is not a substitute for a COW file system</b> for user data.<br>
+</tr></table></body></html>
+Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/check.html|borg check]]
+----
+=== Export ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/tar.html#borg-export-tar|borg export-tar]]
+----
+=== Extract ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/extract.html#borg-extract|borg extract]]
+----
+=== List ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/list.html#borg-list|borg list]]
+----
+=== Compact ===
+Allows you to compact a //REPOSITORY//. Select a //REPOSITORY// and press the COMPACT button:
+  * A code box will open showing the compaction result.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Note
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+Borg does not automatically compact segments in the //REPOSITORY// at commit time (at the end of each write command to the repository). This causes the repository to behave similar to if it were in add-only mode most of the time. Repository space is not immediately freed when deleting or deleting files.<br>
+<b>The user can choose when to run the compaction, it should be done periodically</b>, but not necessarily after each backup.
+</tr></table></body></html>
+Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/compact.html#borg-compact|borg compact]]
+----
+=== Info ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/info.html#borg-info|borg info]]
+----
+=== Download repo keyfile ===
+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.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Note
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+Accessing an encrypted repository requires the repository's encryption key in addition to the passphrase. By default, the plugin stores the encryption key in the /root folder. If you are forced to reinstall OMV and lose this key, you will not be able to recover the data from the repository.<br>
+<b>Download this key and keep it in a safe place along with your passphrase</b>, for example a password app like KeePassXC installed on your PC.
+</tr></table></body></html>
+Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/key.html#borg-key-export|borg key export]]
+----
+=== Mount ===
+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.
+<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;
+ Note
+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
+The plugin does not apply any permissions arguments to this command, so all files and folders will have their original permissions.
+</tr></table></body></html>
+Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/mount.html#borg-mount|borg mount]]
+----
+=== Umount ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/mount.html#borg-umount|borg umount]]
+----
+=== Docs ===
+Shows a link to the official Borgbackup documentation and another link to this document on the omv-extras wiki.
+----
+===== Archives tab =====
+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.
+\\
+<html><center>Under SERVICES > BORGBACKUP > REPOS</center></html>
+\\
+{{ :omv8:omv8_plugins:borgbackup8-5.png?direct&1000 |Archives tab}}
+----
+=== Create ===
+{{ :omv8:omv8_plugins:borgbackup8-6.png?direct&600|Create Archive}}
+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''
+Example: setting the starting hour to 4 would mean the following:
+  * yearly jobs start on January 1 at 4
+  * monthly jobs start on the first day of the month at 4:30 (4 + 30 mins)
+  * weekly jobs start on Mondays at 5 (4 + 1 hour)
+  * daily jobs start at 5:30 (4 + 1 hour + 30 mins)
+  * hourly start at 5 mins after the hour every hour
+----
+=== Edit ===
+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 SAVE to apply changes.
+----
+=== Delete ===
+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.
+----
+=== Info ===
+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 -> [[https://borgbackup.readthedocs.io/en/stable/usage/info.html#borg-info|borg info]]
+----
+=== Dry run ===
+This allows you to run a backup to see the result without making any changes. Select a ARCHIVE and press **DRY RUN**.
+----
+=== Run ===
+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.
+----
+=== Docs ===
+Shows a link to the official Borgbackup documentation and another link to this document on the omv-extras wiki.
+----
+===== Environment Variables tab =====
+Borg uses some environment variables for automation, check the official documentation to find out what they are: [[https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables|Environment Variables]]
+This tab allows you to customize those Borg environment variables.
+\\
+<html><center>Under SERVICES > BORGBACKUP > ENVIRONMENT VARIABLES</center></html>
+\\
+{{ :omv8:omv8_plugins:borgbackup8-7.png?direct&1000 |Archives tab}}
+----
+=== Create ===
+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.
+----
+=== Edit ===
+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.
+----
+=== Delete ===
+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.
+----
+===== Local backup configuration procedure =====
+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''
+----
+=== Create a local REPOSITORY ===
+{{ :omv8:omv8_plugins:borgbackup8-2.png?direct&400|Create Repo}}
+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)
+----
+=== Create a ARCHIVE ===
+{{ :omv8:omv8_plugins:borgbackup8-8.png?direct&500|Create Archive peter}}
+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''
+{{:omv7:omv7_plugins:borgbackup7-9.jpg?direct&600 |List Archives}}
+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.
+\\
+\\
+\\
+----
+===== Remote backup configuration procedure =====
+[[https://forum.openmediavault.org/index.php?thread/36602-how-to-make-backups-with-borg-using-borgbackup-plugin/|{{ :omv7:omv7_plugins:borgbackup7-10.png?direct&200|Go to -> [How-To] Make backups with Borg using borgbackup plugin}}]]
+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. --> [[https://forum.openmediavault.org/index.php?thread/36602-how-to-make-backups-with-borg-using-borgbackup-plugin/|[How-To] Make backups with Borg using borgbackup plugin]]
+Borg requires SSH connections to access remote repositories. These links may be useful to you:
+--> [[https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8|sshd(8) man page]]
+--> [[https://borgbackup.readthedocs.io/en/stable/deployment/hosting-repositories.html|Borg Hosting repositories]]
+--> [[https://borgbackup.readthedocs.io/en/stable/usage/serve.html#borg-serve|borg serve]]
+----
+===== Source Code =====
+-> [[https://github.com/OpenMediaVault-Plugin-Developers/openmediavault-borgbackup|openmediavault-borgbackup]]
+----
+===== A Closing Note =====
+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**
+\\
+<html>
+<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
+<input type="hidden" name="cmd" value="_s-xclick">
+<input type="hidden" name="hosted_button_id" value="2BQNGSC8HQJME">
+<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif" name="submit" title="PayPal - The safer, easier way to pay online!" alt="Donate with PayPal button" border="0">
+<img alt="" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1" border="0">
+</form>
+</html>
+\\
+\\
+**Venmo: ryecoaaron** \\