omv8:omv8_plugins:borgbackup

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
omv8:omv8_plugins:borgbackup [2025/12/28 13:53] – chenteomv8: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 138: 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 === === Remove ===
Line 323: Line 336:
 <html><center>Under SERVICES > BORGBACKUP > REPOS</center></html> <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 329: Line 342:
 === Create === === 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: 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.   * ENABLE: Determines whether this schedule will run automatically or not.
Line 362: Line 375:
   * daily jobs start at 5:30 (4 + 1 hour + 30 mins)   * daily jobs start at 5:30 (4 + 1 hour + 30 mins)
   * hourly start at 5 mins after the hour every hour   * hourly start at 5 mins after the hour every hour
 +
 ---- ----
  
Line 368: Line 382:
 Allows you to edit a //ARCHIVE//. Select a //ARCHIVE// in the form and press the EDIT button: 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.   * 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 385: Line 399:
  
 Link to official documentation -> [[https://borgbackup.readthedocs.io/en/stable/usage/info.html#borg-info|borg info]] 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 411: Line 431:
 <html><center>Under SERVICES > BORGBACKUP > ENVIRONMENT VARIABLES</center></html> <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 453: Line 473:
 === Create a local REPOSITORY === === 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: 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''   * NAME: ''borg_local_repo''
Line 476: Line 496:
 === Create a ARCHIVE === === 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. 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 544: 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 ===== ===== A Closing Note =====
  • omv8/omv8_plugins/borgbackup.1766930009.txt.gz
  • Last modified: 2025/12/28 13:53
  • by chente