omv8:omv8_plugins:timeshift [omv-extras.org]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
\\
<html><center><b>Timeshift Plugin For OMV8</b></center></html>

====== Timeshift Plugin For OMV8 ======
\\
\\

===== Summary =====

  * **openmediavault-timeshift** provides a GUI for [[https://github.com/linuxmint/timeshift|Timeshift]], a tool that takes **incremental snapshots of the operating system** at regular intervals, similar to System Restore on Windows or Time Machine on macOS.
  * If an update, a configuration change or an experiment breaks the system, you can **revert the OS to an earlier snapshot** from the OMV GUI.
  * Timeshift is meant to protect the **operating system**, not your data. By default, the data drives (mounted under ''/srv''), ''/home'' and ''/root'' are excluded. Use a proper backup solution (for example [[omv8:omv8_plugins:borgbackup|BorgBackup]]) for your data.
  * The plugin supports two modes:
    * **RSYNC mode** (default): snapshots are copied with rsync and hard links to a **separate backup device**. This also protects you if the OS drive fails.
    * **BTRFS mode**: when the OS root filesystem is BTRFS, native BTRFS snapshots are created **on the same device**. They are nearly instant and use very little space, but they **do not** protect you if the OS drive fails.

----

===== Prerequisites =====

  * [[https://wiki.omv-extras.org/doku.php?id=misc_docs:omv_extras|OMV-Extras]] must be pre-installed.
  * **RSYNC mode:** a backup device with a Linux filesystem (ext4, xfs, btrfs, ...). A separate drive from the OS drive is recommended.
  * **BTRFS mode:** the OS must be installed on BTRFS with the Ubuntu-style subvolume layout (see [[#btrfs_mode|BTRFS mode]] below).

----

===== Installation =====

In OMV8's GUI:\\
Under **System**, **Plugins**, find and highlight **openmediavault-timeshift 8.X**, and click the **Install** button.

----

===== Using the Timeshift plugin =====

<html><center>Under <b>Services</b> > <b>Timeshift</b></center></html>
\\
The plugin has three tabs:
  * **Settings** - backup device, mode, schedule, retention and excludes.
  * **Scheduled snapshots** - snapshots on the configured backup device.
  * **On-demand snapshots** - create snapshots manually, and browse snapshots on any device Timeshift can use.

----

=== Settings ===

  * **Backup device** - the device where snapshots are stored. Each entry shows the device name, UUID and filesystem type. Swap, vfat, LVM, ZFS member and zram devices are not listed. This field is disabled in BTRFS mode, because snapshots always go to the root filesystem's device.
  * **BTRFS mode** - enable only when the OS root filesystem (''/'') is BTRFS and you want native BTRFS snapshots on that same device. See [[#btrfs_mode|BTRFS mode]] below.
  * **Include @home subvolume** - only available in BTRFS mode. See [[#btrfs_mode|BTRFS mode]] below.
  * **Stop cron email** - stops the emails cron sends each time the scheduled Timeshift job runs.
  * **Monthly / Weekly / Daily / Hourly / Boot** - how many snapshots of each type to keep. Set a value to **0** to disable that schedule. When the limit is reached, the oldest snapshot of that type is removed.
  * **Excludes** - paths excluded from snapshots, in rsync filter syntax. Separate entries with '','', '';'' or a new line; they are saved as a comma separated list.
    * Default: ''/srv/**,/home/**,/root/**''
    * A trailing ''%%**%%'' matches anything, including slashes (the contents of a folder).
    * A trailing ''%%***%%'' matches both the folder and everything in it.
    * See the [[https://linux.die.net/man/1/rsync|rsync manual]] for more about filters.
    * **Excludes are ignored in BTRFS mode**, because the whole subvolume is snapshotted.
  * Press **Save** and **apply** the pending changes. The snapshot tabs won't work until a backup device has been set and applied.

\\
<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;">
Do not remove <b>/srv/**</b> from the excludes unless you know what you are doing.<br>
<b>/srv</b> is where OMV mounts your data drives. Without this exclude, Timeshift will try to copy all of your data into every snapshot, and reverting a snapshot will overwrite files on your data drives.
</tr></table></body></html>

----

=== Scheduled snapshots ===

  * Lists the snapshots on the configured backup device (or on the root device in BTRFS mode).
  * The **Tags** column shows what created each snapshot:
    * **O** - on-demand, **B** - boot, **H** - hourly, **D** - daily, **W** - weekly, **M** - monthly.
  * In BTRFS mode, the **Description** starts with **@** (only the root subvolume) or **@@h** (root and ''@home'' subvolumes).
  * **Delete snapshot** - select a snapshot and press the delete button.
  * **Revert to snapshot** - select a snapshot and press the revert button, confirm, then press **Start** in the dialog. See [[#reverting_a_snapshot|Reverting a snapshot]].

----

=== On-demand snapshots ===

  * Lists every device Timeshift can use for snapshots, and the snapshots on each of them. Each device has a **create** row at the top (''use to create a snapshot on /dev/...'').
  * In BTRFS mode, only the device holding the root filesystem is listed.
  * **Create snapshot** - select the **create** row (or any snapshot) of the device you want, and press the **+** button. The snapshot is tagged **O** and gets the comment ''manually created from plugin''.
  * **Delete** and **Revert** work the same as on the **Scheduled snapshots** tab. They are disabled on the **create** rows.
  * Taking an on-demand snapshot is a good habit **before a system upgrade** or any big configuration change.

----

=== Reverting a snapshot ===

  * Reverting replaces the current system files with the ones in the snapshot. Anything changed since the snapshot was taken (except excluded paths) is lost.
  * The system must be **rebooted** to finish the restore.
  * If the system no longer boots, you can still restore from the command line or from a live Linux USB with Timeshift installed. For example:
<code>
sudo timeshift --list
sudo timeshift --restore --snapshot '2026-09-24_10-00-01'
</code>

----

===== BTRFS mode =====

BTRFS mode uses native BTRFS snapshots of the root subvolume. Snapshots are stored on the root device under ''timeshift-btrfs/snapshots''.

When BTRFS mode is enabled and saved, the plugin checks that:
  * The root filesystem (''/'') is **BTRFS**.
  * ''/'' is mounted as the **@** subvolume (''subvol=@'' or ''subvol=/@'' in ''/etc/fstab'').
  * The BTRFS **default subvolume is the top level (ID 5)**. If it isn't, fix it with:
<code>
sudo btrfs subvolume set-default 5 /
</code>

If any check fails, the settings are not saved and an error explains what is wrong.

=== Include @home subvolume ===

  * Only applies when ''/home'' is a separate **@home** subvolume (mounted with ''subvol=@home'').
  * **Enabled** - ''@home'' is included in snapshots and restored together with ''@''.
  * **Disabled** - only ''@'' is snapshotted and reverted. User data in ''@home'' is left untouched.
  * If this option is enabled, the plugin refuses to revert a snapshot that doesn't contain ''@home'' (description **@** instead of **@@h**), because ''/home'' could fail to mount after the reboot. Either disable **Include @home subvolume** or pick a snapshot that contains it.

\\
<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;">
BTRFS snapshots live on the <b>same drive</b> as the operating system.<br>
They protect against bad updates and configuration mistakes, but <b>not against a failed OS drive</b>. For that, leave BTRFS mode disabled and use RSYNC mode with a separate backup device.
</tr></table></body></html>

----

===== Troubleshooting =====

  * **"Backup device needs to be set and applied!"** - select a backup device in **Settings**, press **Save** and apply the changes.
  * **"BTRFS mode requires the root filesystem (/) to be formatted as BTRFS."** - the OS is not on BTRFS. Use RSYNC mode.
  * **"BTRFS mode requires the root filesystem to be mounted as the '@' subvolume ..."** - the OS was not installed with the ''@'' subvolume layout Timeshift needs. Use RSYNC mode.
  * **"BTRFS mode requires the default subvolume to be the top level (ID 5) ..."** - run ''sudo btrfs subvolume set-default 5 /'' and save again.
  * **"Settings require the '@home' subvolume, but this snapshot doesn't contain it ..."** - see [[#include_home_subvolume|Include @home subvolume]].
  * Timeshift writes its logs to ''/var/log/timeshift/''.

----

===== Source Code =====

-> [[https://github.com/OpenMediaVault-Plugin-Developers/openmediavault-timeshift|openmediavault-timeshift]]

----