Differences

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

--- omv8:omv8_plugins:borgbackup [2025/12/28 12:43] – [Repos tab] chente
+++ omv8:omv8_plugins:borgbackup [2026/06/04 20:53] (current) – [Step 1.2 — Create a user for the backup client to log in as] ryecoaaron
@@ Line 101: / Line 101: @@
 === Create ===
-{{ :omv7:omv7_plugins:borgbackup7-4.jpg?direct&600|Create Repo}}
+{{ :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:
@@ Line 113: / Line 113: @@
   * 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//.
@@ Line 125: / Line 126: @@
 <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;height:25px;width:380px;">
+</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>
@@ Line 137: / Line 138: @@
 ----
+=== 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 ===
@@ Line 144: / Line 158: @@
 <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;height:25px;width:380px;">
+</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.
@@ Line 159: / Line 173: @@
 <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;height:25px;width:380px;">
+</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>
@@ Line 183: / Line 197: @@
 <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;height:25px;width:380px;">
+</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>
@@ Line 198: / Line 212: @@
 <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;height:25px;width:380px;">
+</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>
@@ Line 247: / Line 261: @@
 <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;height:25px;width:380px;">
+</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.
@@ Line 272: / Line 286: @@
 <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;height:25px;width:380px;">
+</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.
@@ Line 290: / Line 304: @@
 <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;height:25px;width:380px;">
+</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>
@@ Line 322: / Line 336: @@
 <html><center>Under SERVICES > BORGBACKUP > REPOS</center></html>
 \\
-{{ :omv7:omv7_plugins:borgbackup7-5.jpg?direct&1000 |Archives tab}}
+{{ :omv8:omv8_plugins:borgbackup8-5.png?direct&1000 |Archives tab}}
 ----
@@ Line 328: / Line 342: @@
 === Create ===
-{{ :omv7:omv7_plugins:borgbackup7-6.jpg?direct&600|Create Archive}}
+{{ :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.
@@ Line 361: / Line 375: @@
   * daily jobs start at 5:30 (4 + 1 hour + 30 mins)
   * hourly start at 5 mins after the hour every hour
 ----
@@ Line 367: / Line 382: @@
 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.
+  * Press SAVE to apply changes.
 ----
@@ Line 384: / Line 399: @@
 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**.
 ----
@@ Line 410: / Line 431: @@
 <html><center>Under SERVICES > BORGBACKUP > ENVIRONMENT VARIABLES</center></html>
 \\
-{{ :omv7:omv7_plugins:borgbackup7-7.jpg?direct&1000 |Archives tab}}
+{{ :omv8:omv8_plugins:borgbackup8-7.png?direct&1000 |Archives tab}}
 ----
@@ Line 452: / Line 473: @@
 === Create a local REPOSITORY ===
-{{ :omv7:omv7_plugins:borgbackup7-4.jpg?direct&600|Create Repo}}
+{{ :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''
@@ Line 475: / Line 496: @@
 === Create a ARCHIVE ===
-{{ :omv7:omv7_plugins:borgbackup7-8.jpg?direct&600|Create Archive peter}}
+{{ :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.
@@ Line 543: / Line 564: @@
 ----
+====== Backing up one OMV server to another with BorgBackup ======
+This guide walks you through setting up an **automatic, encrypted, ransomware‑resistant backup from one OpenMediaVault server to another**, using the BorgBackup plugin's **Serve** feature.
+You will use two machines:
+^ Role ^ What it does ^ What you configure ^
+| **Backup server** | Stores the backups. Hosts the repository. | The **Serve** tab |
+| **Backup client** | The server whose data you want to protect. Pushes backups out. | The **Repos** + **Archives** tabs |
+<note tip>
+"append‑only" mode (enabled by default in this guide) means that even if the client is hacked or hit by ransomware, the attacker **cannot delete or alter the backups already stored on the backup server**. This is the single biggest reason to back up OMV‑to‑OMV this way.
+</note>
+Both machines need the **openmediavault‑borgbackup** plugin installed (version 8.2 or later, which adds the Serve tab).
+----
+===== Part 1 — On the BACKUP SERVER (the destination) =====
+This is the machine that will //receive and keep// the backups.
+==== Step 1.1 — Enable SSH ====
+  - Go to **Services → SSH**.
+  - Tick **Enable** and **Save / Apply**.
+The backup client will connect to this machine over SSH.
+==== Step 1.2 — Create a user for the backup client to log in as ====
+You can reuse an existing user, but a dedicated one is cleaner.
+  - Go to **Users → Users → Create**.
+  - Name it something like ''borgserve''.
+  - Give it a password (it won't be used for backups, but OMV requires one).
+  - Ensure the user is in the ''_ssh'' group.
+  - **Save**.
+==== Step 1.3 — Create a shared folder to hold the backups ====
+  - Go to **Storage → Shared Folders → Create**.
+  - Name it e.g. ''borg-backups'' and pick the disk/pool with room to store backups.
+  - **Save**.
+  - Select the folder, click **Permissions**, and give your ''borgserve'' user **read/write** access. (Borg needs to create and write repository files here as that user.)
+==== Step 1.4 — Add the client on the Serve tab ====
+  - Go to **Services → BorgBackup → Serve → Create**.
+  - Fill in the form:
+    * **Name** — a label for this client, e.g. ''office-nas''.
+    * **Login user** — select ''borgserve''.
+    * **Target shared folder** — select ''borg-backups''. The client will be //locked into this folder// and cannot see anything else on the server.
+    * **Append‑only** — leave **ticked** (recommended).
+    * **Storage quota** — optional, e.g. ''500G'' to cap how much this client can store. Leave blank for no limit.
+    * **Client public key** — you have two choices:
+      * **Easiest:** leave it **blank**. The plugin will generate a key pair for you.
+      * **Or** paste the client's existing public key (see the alternative in Part 2).
+  - Click **Save**, then **Apply** the pending configuration change.
+==== Step 1.5 — Download the private key (only if you left the key blank) ====
+If you let the plugin generate the key:
+  - Back on the **Serve** list, select your new ''office-nas'' row.
+  - Click **Download private key** (the download icon).
+  - Save the file — you'll move it to the backup client in Part 2.
+<note>
+The **Private key stored** column shows a check mark for clients whose key was generated here and can be downloaded. Keep this file safe; treat it like a password.
+</note>
+The backup server is now ready and listening. Note down:
+  * the server's **hostname or IP address**
+  * the **login user** (''borgserve'')
+  * the **full path of the target shared folder** — find it under **Storage → Shared Folders** (e.g. ''/srv/dev-disk-by-uuid-xxxx/borg-backups'')
+----
+===== Part 2 — On the BACKUP CLIENT (the source) =====
+This is the machine whose data you want to protect.
+==== Step 2.1 — Put the private key on the client ====
+The BorgBackup plugin runs as **root**, so the key must be readable by root.
+  - Copy the private key you downloaded to the client, for example to ''/root/.ssh/borg_omv''.
+  - Set tight permissions (from a root shell, or ''!'' in the OMV command box):
+<code bash>
+install -m 600 /path/to/downloaded-key /root/.ssh/borg_omv
+</code>
+<note>
+**Alternative (key never leaves the client):** instead of generating the key on the server, generate it here with ''ssh-keygen -t ed25519 -f /root/.ssh/borg_omv'', then paste the contents of ''/root/.ssh/borg_omv.pub'' into the **Client public key** field back in Step 1.4. This way the private key never travels between machines.
+</note>
+==== Step 2.2 — Tell Borg which key and host to use ====
+  - Go to **Services → BorgBackup → Environment Variables → Create**.
+  - Add:
+    * **Name:** ''BORG_RSH''
+    * **Value:** ''ssh -i /root/.ssh/borg_omv -o StrictHostKeyChecking=accept-new''
+    * **Repo:** you can set this after creating the repo in the next step, or choose **Repo creation** for now and revisit.
+  - **Save**.
+This tells Borg to connect using your key and to trust the server's host key on first connection.
+==== Step 2.3 — Create the remote repository ====
+  - Go to **Services → BorgBackup → Repos → Create**.
+  - Fill in:
+    * **Name** — e.g. ''offsite''.
+    * **Type** — **Remote**.
+    * **Remote path** — this points at a //new sub‑folder inside the server's target shared folder//. Use the form:<code>borgserve@SERVER-HOST:/srv/dev-disk-by-uuid-xxxx/borg-backups/office-nas</code>Replace ''SERVER-HOST'' with the server's hostname/IP and the path with the target shared folder path you noted in Part 1, plus a repo name on the end (''office-nas'' here).
+    * **Passphrase** — set a strong passphrase. **Write it down somewhere safe** — without it your backups cannot be restored.
+    * **Encryption** — tick it (recommended).
+    * **Skip init** — leave unticked (this is a brand‑new repo).
+  - Make sure your ''BORG_RSH'' environment variable from Step 2.2 is attached to this repo (edit it and set **Repo** to this repo if you used "Repo creation" earlier).
+  - **Save**. The plugin will create (initialise) the repository on the backup server.
+<note>
+If this step fails with a connection or permission error, jump to **Troubleshooting** below.
+</note>
+==== Step 2.4 — Create a backup archive (what to back up, and when) ====
+  - Go to **Services → BorgBackup → Archives → Create**.
+  - Fill in:
+    * **Name** — e.g. ''daily''.
+    * **Repo** — select the ''offsite'' repo.
+    * **Include** — the folders to back up, one per line (e.g. ''/srv/dev-disk-by-uuid-yyyy/data'').
+    * **Exclude** — anything to skip (optional).
+    * **Schedule** — pick a time, e.g. **Daily at 03:00**.
+    * Compression and other options can be left at their defaults.
+  - **Save** and **Apply**.
+==== Step 2.5 — Run it once to confirm ====
+  - Select the ''daily'' archive and click **Backup** (you can tick //dry run// first to test without writing data).
+  - Watch the live output. A successful run ends with backup statistics.
+Your OMV‑to‑OMV backup is now running automatically on the schedule you set. 🎉
+----
+===== Pruning and housekeeping (important with append‑only) =====
+Because the client connects in **append‑only** mode, it can //add// backups but **cannot delete old ones** — that's what protects you from ransomware. Old backups are therefore removed and space reclaimed **from the backup server side**:
+  * On the **backup server**, go to **Services → BorgBackup → Compact** and schedule a periodic compaction of the ''borg-backups'' repository to reclaim freed space.
+  * Retention (how many daily/weekly/monthly backups to keep) is configured per archive on the **client**, but the actual deletion is honoured on the server during compaction.
+----
+===== Troubleshooting =====
+**"Connection refused" / "Permission denied (publickey)"**
+  * Confirm SSH is enabled on the backup server (Step 1.1).
+  * Confirm the private key path in ''BORG_RSH'' is correct and the file is ''chmod 600''.
+  * Confirm the public key matches the client entry on the server's Serve tab.
+**"borg: command not found" over SSH**
+  * The BorgBackup plugin must be installed on the **backup server** too — the forced ''borg serve'' command runs there.
+**"Repository path not allowed" / restrict‑to‑path errors**
+  * The **Remote path** in Step 2.3 must be //inside// the target shared folder you chose on the Serve tab. Check the path matches exactly.
+**Permission denied writing the repository**
+  * The Serve **Login user** needs read/write permission on the target shared folder (Step 1.3, Permissions).
+**Where did the access actually get configured?**
+  * On the backup server, each Serve client becomes a single restricted line in the login user's ''~/.ssh/authorized_keys'', for example:
+<code>
+command="borg serve --restrict-to-path '/srv/.../borg-backups' --append-only",restrict ssh-ed25519 AAAA... office-nas
+</code>
+This is what confines the client to ''borg serve'', locks it to one folder, and enforces append‑only. Do **not** also add the client's key to that user's profile under **User Management**, or the restriction could be bypassed.
 ===== A Closing Note =====