Skip to content
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.

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

(WiP) zfs pool draft #289

Closed
wants to merge 6 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
18 changes: 12 additions & 6 deletions doc/qubes-storage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ properties:
with its own state of the volume, or rather a snapshot of its template volume
(pointed by a :py:attr:`~qubes.storage.Volume.source` property). This can be
set to `True` only if a domain do have `template` property (AppVM and DispVM).
TODO should `source` be folded into this arg?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm for it, but lets keep it compatible with the old API. For example: allow snap_on_start=Volume (and then assert for source not set), but also allow snap_on_start=True, and then expect source set. Alternatively add a new attribute replacing both, like snap_on_start_from.

If the domain's template is running already, the snapshot should be made out of
the template's before its startup.
- :py:attr:`~qubes.storage.Volume.save_on_stop` - should the volume state be
Expand Down Expand Up @@ -81,13 +82,18 @@ name of storage pool driver. Volume class instances should be returned by
:py:meth:`qubes.storage.Pool.init_volume` method of pool class instance.

Methods required to be implemented by the pool class:
- :py:meth:`~qubes.storage.Pool.__init__` - the named arguments to this function are listed in `qvm-pool --help-drivers`. It is called each time the Qubes management starts up, and thus must NOT make persistent changes. When a new pool is created for the first time, a subsequent call to py:meth:`~qubes.storage.Pool.setup` is issued, `__init__` must however save any arguments required to instantiate the new pool.
- :py:meth:`~qubes.storage.Pool.init_volume` - return instance of appropriate
volume class; this method should not alter any persistent disk state, it is
used to instantiate both existing volumes and create new ones
- :py:meth:`~qubes.storage.Pool.setup` - setup new storage pool
used to instantiate both existing volumes and create new ones.
The first argument is a :py:class:`qubes.vm.qubesvm.QubesVM` instance.
The second is a `volume_config` dict which contains keys like `size` and `name` (the volume's name; "private", "root", etc.)
- :py:meth:`~qubes.storage.Pool.setup` - setup new storage pool. This is called when the user instantiates a new pool with `qvm-pool -a`
- :py:meth:`~qubes.storage.Pool.destroy` - destroy storage pool
:py:attr:`~qubes.storage.Pool.config` - volume configuration `dict` containing at least keys: `name`, `revisions_to_keep`, and `driver` (reference to this py:class:`~qubes.storage.Pool`), along with any pool-specific data required to re-instantiate the pool. This dict is serialized to `qubes.xml` and the key-value pairs are passed as named arguments (e.g. `**kwargs`) of the pool `__init__` method next time this pool is instantiated.

Methods and properties required to be implemented by the volume class:
- :py:meth:`~qubes.storage.Volume.__init__` - call from :py:meth:`~qubes.storage.Pool.init_volume` each time the management stack is started. must not make any persistent changes to disk.
- :py:meth:`~qubes.storage.Volume.create` - create volume on disk
- :py:meth:`~qubes.storage.Volume.remove` - remove volume from disk
- :py:meth:`~qubes.storage.Volume.start` - prepare the volume for domain start;
Expand All @@ -96,17 +102,17 @@ Methods and properties required to be implemented by the volume class:
- :py:meth:`~qubes.storage.Volume.stop` - cleanup after domain shutdown; this
include committing changes to the volume if
:py:attr:`~qubes.storage.Volume.save_on_stop` is `True`
- :py:meth:`~qubes.storage.Volume.export` - return a path to be read to extract
volume data; for complex formats, this can be a pipe (connected to some
data-extracting process)
- :py:meth:`~qubes.storage.Volume.export` - return a file system path to be
`open()`'ed and read to extract volume data;
for complex formats this could be a named pipe for instance
- :py:meth:`~qubes.storage.Volume.import_data` - return a path the data should
be written to, to import volume data; for complex formats, this can be pipe
(connected to some data-importing process)
- :py:meth:`~qubes.storage.Volume.import_data_end` - finish data import
operation (cleanup temporary files etc); this methods is called always after
:py:meth:`~qubes.storage.Volume.import_data` regardless if operation was
successful or not
- :py:meth:`~qubes.storage.Volume.import_volume` - import data from another volume
- :py:meth:`~qubes.storage.Volume.import_volume` - import data from another volume. TODO this is used when self.snap_on_data=True and self.source exists
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No snap_on_data or snap_on_start. It is using when cloning VM or otherwise importing data between already existing volumes (not importing data from "the outside").
It may be worth noting that even if the volume is created with an intention of its data being replaced with this function, volume.create() is still called before it.

- :py:meth:`~qubes.storage.Volume.resize` - resize volume
- :py:meth:`~qubes.storage.Volume.revert` - revert volume state to a given revision
- :py:attr:`~qubes.storage.Volume.revisions` - collection of volume revisions (to use
Expand Down
Loading