Skip to content

Secondary storage Btrfs fixes #1550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Secondary storage Btrfs fixes #1550

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
27a6f31
Secondary storage: consistently capitalize Btrfs
rustybird Oct 2, 2025
c3f74ce
Secondary storage: fix mounting Btrfs with compression
rustybird Oct 2, 2025
c1fa7a7
Secondary storage: fix 'btrfs filesystem' invocation
rustybird Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 8 additions & 24 deletions user/advanced-topics/secondary-storage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ qvm-pool driver explanation:

In theory, you can still use file-based disk images (“file” pool driver), but they will lack some features: for example, you won’t be able to do backups without shutting down the qube.

Additional storage can also be added on a Btrfs filesystem. A unique feature of Btrfs is that data can be compressed transparently. The subvolume can also be backed up using snapshots for an additional layer of protection; Btrfs supports differents level of redundancy; it has parity checksum; Btrfs volumes can be expanded or shrunk. Starting or stopping a VM has less impact and less chance of causing slowdown of the system as some users have noted with LVM. Relevant information for general btrfs configuration will be provided after the section on LVM storage.
Additional storage can also be added on a Btrfs filesystem. A unique feature of Btrfs is that data can be compressed transparently. The subvolume can also be backed up using snapshots for an additional layer of protection; Btrfs supports differents level of redundancy; it has parity checksum; Btrfs volumes can be expanded or shrunk. Starting or stopping a VM has less impact and less chance of causing slowdown of the system as some users have noted with LVM. Relevant information for general Btrfs configuration will be provided after the section on LVM storage.

LVM storage
^^^^^^^^^^^
Expand All @@ -62,21 +62,21 @@ Take note of the VG and thin pool names for your second drive, then register it



BTRFS storage
Btrfs storage
^^^^^^^^^^^^^


Theses steps assume you have already created a separate Btrfs filesystem for your second drive., that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables compression and excess storage can be use for other things.
Theses steps assume you have already created a separate Btrfs filesystem for your second drive, that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables snapshotting the VM data independently of any other files that you may want to store on the filesystem.

It is possible to use an existing Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using:

.. code:: console

$ mount -t btrfs
$ btrfs show filesystem
$ sudo btrfs filesystem show


To register the storage to qubes use the following command where ``<pool_name>`` is a freely chosen pool name adn ``<dir_path>`` is the mounted path to the second btrfs storage:
To register the storage to qubes use the following command where ``<pool_name>`` is a freely chosen pool name adn ``<dir_path>`` is the mounted path to the second Btrfs storage:

.. code:: console

Expand Down Expand Up @@ -177,12 +177,12 @@ First create the physical volume:
$ sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde


Then mount the new Btrfs to a temporary path:
Then mount the new Btrfs filesystem with compression enabled if desired, where ``<compression>`` can take the values ``zlib|lzo|zstd``:

.. code:: console

$ sudo mkdir -p /mnt/new_qube_storage
$ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
$ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage -o compress=<compression>


Create a subvolume to hold the data:
Expand All @@ -192,27 +192,11 @@ Create a subvolume to hold the data:
$ sudo btrfs subvolume create /mnt/new_qube_storage/qubes



Unmount the temporary Btrfs filesystem:

.. code:: console

$ sudo umount /mnt/new_qube_storage
$ rmdir /mnt/new_qube_storage


Mount the subvolume with compression enabled if desired, where ``<compression>`` can take the values ``zlib|lzo|zstd``. ``<subvol>`` is a btrfs subvolume "qubes" in this example.

.. code:: console

$ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes


Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume:

.. code:: console

$ qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2
$ qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/mnt/new_qube_storage/qubes,revisions_to_keep=2


By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary drive do the following on a dom0 terminal:
Expand Down