qubes.vm.dispvm
– Disposable VM¶
A disposable vm implementation
- class qubes.vm.dispvm.DispVM(app, xml, *args, **kwargs)[source]¶
Bases:
QubesVM
Disposable VM
Preloading¶
Preloaded disposables are started in the background and kept hidden from the user when not in use. They are interrupted (paused or suspended, as appropriate) and resumed (transparently) when a disposable qube is requested by the user.
Goals:
Fast: Usage must be always instantaneous from user perspective when requesting the use of disposables. Pause/suspend must be skipped if qube is requested before the interrupt can be performed.
Easy-to-use: Preloading requires a single qube feature (preload-dispvm-max), and its use must be transparent, indistinguishable from working with normal (non-preloaded) unnamed disposable qubes.
Reliable:
Avoid race conditions: Marking a qube as preloaded or marking the preloaded as used must be synchronous.
Recovery from failed or incomplete preload: The system must attempt to preload qubes even if previous preloading attempts failed due to errors, qubesd restart or lack of available memory, regardless of whether preloaded disposable qubes have been requested on this instance. If current qube list is invalid, it must be cleaned up before being used.
Avoid copy of invalid attributes: Qube operation (in particular cloning, renaming or creating a standalone based on a template) must not result in properties that are invalid on the target.
Full start: Preloaded disposable must only be interrupted (paused/suspended) or used after all basic services in it have been started. Autostarted applications allows user interaction before the it should, that is a bug.
Prevents accidental tampering:
Preloaded qubes have the internal feature set when they are created. This feature hides the qube from GUI tools and discourages user tampering. It is unset when the qube is marked as used. Remember to validate if all GUI applications correctly react to setting and removing the internal feature (optionally, the is_preload property can be helpful). GUI applications may react to domain-add before the internal feature is set and the qube entry may briefly appear on some GUI applications, that is a bug because features cannot be set before that event.
Preloaded qubes must be marked as used when prior to being unpaused/resumed, even if it was not requested. The goal of pause/suspend in case of preloaded disposables is mostly detecting whether a qube was used or not, and not managing resource consumption; thus, even with abundant system resources, they should not be unpaused/resumed without being requested.
Features and properties relationship on stages:
Properties indicate the runtime stage of preloaded qubes and intentionally lost on qubesd restart.
Features indicate that a preloaded qube has reached certain stage at any qubesd cycle.
Comparing the value of certain features and properties can indicate that there were qubes being preloaded or requested but qubesd restarted between the stages, interrupting the process. The only stage that should conserve the preloaded qubes is a qubes that has completed preloading but has not been requested.
Stages:
Preload: The qube is created and marked as preloaded. Qube is not visible in GUI applications.
Startup: Begins qube startup, start basic services in it and attempt to interrupt (suspend/pause).
Request: The qube is removed from the preload list. If startup has not yet reached interrupt, the latter is skipped.
Used: The qube is marked as used and may be unpaused/resumed (if applicable). Only in this phase, GUI applications treat the qube as any other unnamed disposable and the qube object is returned to the caller if requested.
Outstanding bugs:
GUI applications set to autostart can appear on the screen and be interactive for a brief moment before the qube is allowed to be used followed by a sudden freeze.
Can’t interrupt qubes before the GUI session has started if the qube’s usage will require a GUI (GUI daemon cannot handle an interrupted qube).
- async classmethod from_appvm(appvm, preload=False, **kwargs)[source]¶
Create a new instance from given AppVM
- Parameters:
appvm (qubes.vm.appvm.AppVM) – template from which the VM should be created
preload (bool) – Whether to preload a disposable
- Returns:
new disposable vm
kwargs are passed to the newly created VM
>>> import qubes.vm.dispvm.DispVM >>> dispvm = qubes.vm.dispvm.DispVM.from_appvm(appvm).start() >>> dispvm.run_service('qubes.VMShell', input='firefox') >>> dispvm.cleanup()
This method modifies
qubes.xml
file. The qube returned is not started unless thepreload
argument isTrue
.
- async cleanup()[source]¶
Clean up after the DispVM
This stops the disposable qube and removes it from the store. This method modifies
qubes.xml
file.
- on_domain_pre_unpaused(event, **kwargs)[source]¶
Mark preloaded domains as used before being unpaused.
- async on_domain_started_dispvm(event, **kwargs)[source]¶
Awaits for basic services to be started on preloaded domains and interrupts the domain if the qube has not been requested yet.
- on_property_pre_set_template(event, name, newvalue, oldvalue=None)[source]¶
Forbid changing template of running VM
- on_property_set_template(event, name, newvalue, oldvalue=None)[source]¶
Adjust root (and possibly other snap_on_start=True) volume on template change.
- async start(**kwargs)[source]¶
Start domain
- Parameters:
start_guid (bool) – FIXME
notify_function (collections.abc.Callable) – FIXME
mem_required (int) – FIXME
- auto_cleanup¶
automatically remove this VM upon shutdown
- default_dispvm¶
Default VM to be used as Disposable VM for service calls.
- dispid¶
Internal, persistent identifier of particular DispVM.
- include_in_backups¶
If this domain is to be included in default backup.
- is_preload¶
Returns True if qube is a preloaded disposable.
- template¶
AppVM, on which this DispVM is based.