Attention

Qubes OS 4.2 has reached end of life - it is no longer supported and thus will no longer receive security updates, bug fixes, or new features. We recommend to perform an in-place upgrade or perform a clean installation of Qubes 4.3! The documentation of version 4.2 will also not receive any new updates, unless bug fixes. Its state is thus archived.

Disposable implementation

Warning

This page is intended for advanced users.

Disposable behavior

A disposable template is not a disposable qube in itself, but a qube that can be used to create different disposable types: normal disposables and named disposables. This intermediary template serves different functions: first, it allows customization of the private volume of a disposable, and second, it provides a degree of inheritance that would not be possible with normal templates. It has the template_for_dispvms property enabled, being a DVMTemplateMixin.

A disposable is a qube with the DispVM class and is based on a disposable template. Every disposable type has all of its volumes configured to disable save_on_stop, therefore no changes are saved on shutdown. Normal disposables enable the property auto_cleanup by default, thus Qubes OS automatically removes the qube upon shutdown. Named disposables don’t enable auto_cleanup by default, thus the qube skeleton is not removed upon shutdown, thus allowing to keep qube settings.

Named disposables are useful for service qubes, as referencing static names is easier when the qube name is mentioned on qrexec policies (qubes.UpdatesProxy target) or as a property of another qube, such as a disposable net qube which is referenced by downstream clients in the netvm property.

Disposables are generally named according to the disp1234 scheme, where 1234 is derived from the dispid property, a random integer ranging from 0 to 9999 with a fail-safe mechanism to avoid reusing the same value in a short period. Named disposables have a user-set permanent name.

Creating disposables through qrexec

Every qube has the default_dispvm property, which defines which disposable template will be used to spawn disposables for this qube by default (when using actions such as “open in disposable”). It can have one of three values:

  • a disposable template

  • empty value

  • default system value (this will use the system-wide default_dispvm property)

In case of disposables, this property is by default set to their own disposable template, to avoid data leaks through, for example, using unintended network access paths.

This value is also used in case of qrexec policy: when policy rules use the @dispvm tag, it translates to “a disposable based on the source qube’s default_dispvm. It is most commonly used to open files and URLs, (qubes.OpenInVM and qubes.OpenURL, respectively).

If you want to allow creating disposables based on different disposable templates, you can use the disposable template name or tag as destination. In particular:

  • @dispvm:DISPOSABLE_TEMPLATE, where DISPOSABLE_TEMPLATE is the desired template;

  • @dispvm:@tag:CUSTOM_TAG, where CUSTOM_TAG is the tag of your choice.