qubes.vm – Different Virtual Machine types

Qubes is composed of several virtual machines that are interconnected in several ways. From now on they will be called „domains”, as they may not actually be true virtual machines – we plan to support LXC containers for example. Because of Xen-only legacy of Qubes code, it is custom to refer to them in long/plural as domains and in short/singular as vm.

Domain object

There are couple of programming objects that refer to domain. The main is the instance of qubes.vm.QubesVM. This is the main „porcelain” object, which carries other objects and supplies convenience methods like qubes.vm.qubesvm.QubesVM.start(). This class is actually divided in two, the qubes.vm.qubesvm.QubesVM cares about Qubes-specific actions, that are more or less directly related to security model. It is intended to be easily auditable by non-expert programmers (ie. we don’t use Python’s magic there). The second class is its parent, qubes.vm.BaseVM, which is concerned about technicalities like XML serialising/deserialising. It is of less concern to threat model auditors, but still relevant to overall security of the Qubes OS. It is written for programmers by programmers.

The second object is the XML node that refers to the domain. It can be accessed as Qubes.vm.BaseVM.xml attribute of the domain object. The third one is Qubes.vm.qubesvm.QubesVM.libvirt_domain object for directly interacting with libvirt. Those objects are intended to be used from core and/or plugins, but not directly by user or from qvm-tools. They are however public, so there are no restrictions.

Domain classes

There are several different types of VM, because not every Qubes domain is equal – some of them perform specific functions, like NetVM; others have different life cycle, like DisposableVM. For that, different domains have different Python classes. They are all defined in this package, generally one class per module, but some modules contain private globals that serve this particular class.

Package contents

Main public classes

class qubes.vm.BaseVM(app, xml, features=None, devices=None, tags=None, **kwargs)[source]

Bases: PropertyHolder

Base class for all VMs

  • app (qubes.Qubes) – Qubes application context

  • xml (lxml.etree._Element or None) – xml node from which to deserialise

This class is responsible for serializing and deserialising machines and provides basic framework. It contains no management logic. For that, see qubes.vm.qubesvm.QubesVM.


Create libvirt’s XML domain config file


List of persistent device assignments from this VM.


Initialise logger for this domain.


Start watching QubesDB

Calling this method in appropriate time is responsibility of child class.


Add a QubesDB path to be watched.

Each change to the path will cause domain-qdb-change:path event to be fired. You can call this method for example in response to domain-init and domain-load events.


mother qubes.Qubes object


DeviceManager object keeping devices that are attached to this domain


dictionary of features of this qube


Domain class name


Colourful label assigned to VM. This is where the colour of the padlock is set.


logger instance for logging messages related to this VM


User-specified name of the domain.


Internal, persistent identificator of particular domain. Note this is different from Xen domid.


storage manager


user-specified tags


UUID from libvirt.


storage volumes

Helper classes and functions

class qubes.features.Features(subject, other=None, **kwargs)[source]

Bases: dict

Manager of the features.

Features can have three distinct values: no value (not present in mapping, which is closest thing to None), empty string (which is interpreted as False) and non-empty string, which is True. Anything assigned to the mapping is coerced to strings, however if you assign instances of bool, they are converted as described above. Be aware that assigning the number 0 (which is considered false in Python) will result in string ‘0’, which is considered true.

This class inherits from dict, but has most of the methods that manipulate the item disarmed (they raise NotImplementedError). The ones that are left fire appropriate events on the qube that owns an instance of this class.

check_with_adminvm(feature, default=<object object>)[source]

Check for the specified feature; if this VM does not have it, it checks with the AdminVM.

check_with_netvm(feature, default=<object object>)[source]

Check for the specified feature; if this VM does not have it, it checks with its netvm.

check_with_template(feature, default=<object object>)[source]

Check for the specified feature; if this VM does not have it, it checks with its template.

check_with_template_and_adminvm(feature, default=<object object>)[source]

Check for the specified feature; if this VM does not have it, it checks with its template. If the template does not have it, it checks with the AdminVM.

clear() None.  Remove all items from D.[source]
pop(_key, _default=None)[source]

Not implemented :raises: NotImplementedError


Not implemented :raises: NotImplementedError

setdefault(_key, _default=None)[source]

Not implemented :raises: NotImplementedError

update([E, ]**F) None.  Update D from dict/iterable E and F.[source]

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

class qubes.vm.mix.net.NetVMMixin(*args, **kwargs)[source]

Bases: Emitter

Mixin containing network functionality


Attach network in this machine to it’s netvm.


Detach machine from it’s netvm

static get_ip6_for_vm(vm)[source]

Get IPv6 address for (appvm) domain connected to this (netvm) domain.

Default address is constructed with Qubes-specific site-local prefix, and IPv4 suffix (0xa89 is 10.137.).

static get_ip_for_vm(vm)[source]

Get IP address for (appvm) domain connected to this (netvm) domain.


Return True if there are some vm specific firewall rules set


Check whether this VM can reach network (firewall notwithstanding).


True if is machine can reach network, False otherwise.

Return type:


on_domain_pre_shutdown(event, force=False)[source]

Checks before NetVM shutdown if any connected domains are running. If force is True tries to detach network interfaces of connected vms


Fills the QubesDB with firewall entries.

on_domain_shutdown(event, **kwargs)[source]

Cleanup network interfaces of connected, running VMs.

This will allow re-reconnecting them cleanly later.

on_domain_started(event, **kwargs)[source]

Connect this domain to its downstream domains. Also reload firewall in its netvm.

This is needed when starting netvm after its connected domains.

on_firewall_changed(event, **kwargs)[source]

Reloads the firewall if vm is running and has a NetVM assigned

on_net_domain_connect(event, vm)[source]

Reloads the firewall config for vm

on_property_pre_reset_netvm(event, name, oldvalue=None)[source]

Sets the the NetVM to default NetVM

on_property_pre_set_netvm(event, name, newvalue, oldvalue=None)[source]

Run sanity checks before setting a new NetVM

on_property_reset_netvm(event, name, oldvalue=None)[source]

Sets the the NetVM to default NetVM

on_property_set_netvm(event, name, newvalue, oldvalue=None)[source]

Replaces the current NetVM with a new one and fires net-domain-connect event


Update list of IPs possibly connected to this machine. This is used by qubes-firewall to implement anti-spoofing.


Reload the firewall rules for the vm


Set configuration to possibly hide real IP from the VM. This needs to be done before executing ‘script’ (/etc/xen/scripts/vif-route-qubes) in network providing VM

property connected_vms

Return a generator containing all domains connected to the current NetVM.


DNS servers set up for this domain.


Gateway for other domains that use this domain as netvm.


Gateway (IPv6) for other domains that use this domain as netvm.


IP address of this domain.


IPv6 address of this domain.


MAC address of the NIC emulated inside VM

property netmask

Netmask for gateway address.


VM that provides network connection to this domain. When None, machine is disconnected. When absent, domain uses default NetVM.


If this domain can act as network provider (formerly known as NetVM or ProxyVM)


Default gateway of this domain as seen by the domain.


Default (IPv6) gateway of this domain as seen by the domain.


IP address of this domain as seen by the domain.


IPv6 address of this domain as seen by the domain.


Netmask as seen by the domain.

Particular VM classes

Main types:

Special VM types: