core-admin/doc
Rusty Bird 1695a732b8
file-reflink, a storage driver optimized for CoW filesystems
This adds the file-reflink storage driver. It is never selected
automatically for pool creation, especially not the creation of
'varlibqubes' (though it can be used if set up manually).

The code is quite small:

               reflink.py  lvm.py      file.py + block-snapshot
    sloccount  334 lines   447 (134%)  570 (171%)

Background: btrfs and XFS (but not yet ZFS) support instant copies of
individual files through the 'FICLONE' ioctl behind 'cp --reflink'.
Which file-reflink uses to snapshot VM image files without an extra
device-mapper layer. All the snapshots are essentially freestanding;
there's no functional origin vs. snapshot distinction.

In contrast to 'file'-on-btrfs, file-reflink inherently avoids
CoW-on-CoW. Which is a bigger issue now on R4.0, where even AppVMs'
private volumes are CoW. (And turning off the lower, filesystem-level
CoW for 'file'-on-btrfs images would turn off data checksums too, i.e.
protection against bit rot.)

Also in contrast to 'file', all storage features are supported,
including

    - any number of revisions_to_keep
    - volume.revert()
    - volume.is_outdated
    - online fstrim/discard

Example tree of a file-reflink pool - *-dirty.img are connected to Xen:

    - /var/lib/testpool/appvms/foo/volatile-dirty.img
    - /var/lib/testpool/appvms/foo/root-dirty.img
    - /var/lib/testpool/appvms/foo/root.img
    - /var/lib/testpool/appvms/foo/private-dirty.img
    - /var/lib/testpool/appvms/foo/private.img
    - /var/lib/testpool/appvms/foo/private.img@2018-01-02T03:04:05Z
    - /var/lib/testpool/appvms/foo/private.img@2018-01-02T04:05:06Z
    - /var/lib/testpool/appvms/foo/private.img@2018-01-02T05:06:07Z
    - /var/lib/testpool/appvms/bar/...
    - /var/lib/testpool/appvms/...
    - /var/lib/testpool/template-vms/fedora-26/...
    - /var/lib/testpool/template-vms/...

It looks similar to a 'file' pool tree, and in fact file-reflink is
drop-in compatible:

    $ qvm-shutdown --all --wait
    $ systemctl stop qubesd
    $ sed 's/ driver="file"/ driver="file-reflink"/g' -i.bak /var/lib/qubes/qubes.xml
    $ systemctl start qubesd
    $ sudo rm -f /path/to/pool/*/*/*-cow.img*

If the user tries to create a fresh file-reflink pool on a filesystem
that doesn't support reflinks, qvm-pool will abort and mention the
'setup_check=no' option. Which can be passed to force a fallback on
regular sparse copies, with of course lots of time/space overhead. The
same fallback code is also used when initially cloning a VM from a
foreign pool, or from another file-reflink pool on a different
mountpoint.

'journalctl -fu qubesd' will show all file-reflink copy/rename/remove
operations on VM creation/startup/shutdown/etc.
2018-02-12 21:20:05 +00:00
..
_static doc: Fix docutils table column width 2015-06-29 17:39:25 +02:00
_templates doc: Fix docutils table column width 2015-06-29 17:39:25 +02:00
manpages qubespolicy: add a tool to analyze policy in form of graph 2017-07-04 04:27:36 +02:00
qubes-tools doc: remove man pages of just removed tools 2017-05-12 18:43:35 +02:00
qubes-vm doc: remove documentation for removed metaclass 2017-05-12 19:38:16 +02:00
.gitignore doc: Add autogenerated qubes.xml documentation 2015-06-29 17:39:25 +02:00
conf.py qubespolicy: add a tool to analyze policy in form of graph 2017-07-04 04:27:36 +02:00
example.xml devices: adjust XML serialization of device options 2017-05-22 17:11:20 +02:00
index.rst storage: add API documentation 2017-07-04 04:11:14 +02:00
libvirt.rst Add possibility to override libvirt config 2016-10-04 11:31:31 +02:00
Makefile fix Makefile, setup.py, spec and travis 2017-01-20 18:31:09 +01:00
qubes-backup.rst backup: add a little more usage info, include docs in main index 2017-04-21 19:58:32 +02:00
qubes-dochelpers.rst doc: add hyphens to module page titles 2015-06-29 17:39:23 +02:00
qubes-events.rst events: add support for wildcard event handlers 2018-01-06 00:40:19 +01:00
qubes-exc.rst core3: Add documentation to qubes.exc 2015-10-17 00:20:44 +02:00
qubes-ext.rst doc: include list of extensions 2017-07-28 16:32:48 +02:00
qubes-log.rst doc: add hyphens to module page titles 2015-06-29 17:39:23 +02:00
qubes-policy.rst qubespolicy: implement $dispvm:$tag: syntax 2017-09-05 02:07:27 +02:00
qubes-storage.rst file-reflink, a storage driver optimized for CoW filesystems 2018-02-12 21:20:05 +00:00
qubes-tests.rst qubes/doc: Test's documentation improvement 2015-06-29 17:39:24 +02:00
qubes.rst qubes: more documentation and doc fixes 2015-06-29 17:39:28 +02:00
requirements.txt Add requirements.txt for readthedocs.org 2016-04-22 15:51:50 +02:00
skel-manpage.py qubes/tools/qubesd-query: low-level interrogation tool 2017-02-10 23:25:45 +01:00