qubes.vm.dispvm – Disposable VM

A disposable vm implementation

class qubes.vm.dispvm.DispVM(app, xml, *args, **kwargs)

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)

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 the preload argument is True.

async cleanup()

Clean up after the DispVM

This stops the disposable qube and removes it from the store. This method modifies qubes.xml file.

create_qdb_entries()

Create entries in Qubes DB.

on_domain_loaded(event)

When domain is loaded assert that this vm has a template.

on_domain_paused(event, **kwargs)

Log preloaded domains when paused.

on_domain_pre_unpaused(event, **kwargs)

Mark preloaded domains as used before being unpaused.

async on_domain_shutdown(_event, **_kwargs)

Do auto cleanup if enabled

async on_domain_started_dispvm(event, **kwargs)

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_reset_template(event, name, oldvalue=None)

Forbid deleting template of VM

on_property_pre_set_template(event, name, newvalue, oldvalue=None)

Forbid changing template of running VM

on_property_set_template(event, name, newvalue, oldvalue=None)

Adjust root (and possibly other snap_on_start=True) volume on template change.

async start(**kwargs)

Start domain

Parameters:

• start_guid (bool) – FIXME

• notify_function (collections.abc.Callable) – FIXME

• mem_required (int) – FIXME

use_preload()

Marks preloaded DispVM as used (tainted).

Returns:

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.