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)

Bases: PropertyHolder

Base class for all VMs

Parameters:

• 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_config_file()

Create libvirt’s XML domain config file

get_provided_assignments(required_only: bool = False) → List[DeviceAssignment]

List device assignments from this VM.

init_log()

Initialise logger for this domain.

start_qdb_watch(loop=None)

Start watching QubesDB

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

watch_qdb_path(path)

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.

app

mother qubes.Qubes object

devices

DeviceManager object keeping devices that are attached to this domain

features

dictionary of features of this qube

klass

Domain class name

label

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

log

logger instance for logging messages related to this VM

name

User-specified name of the domain.

qid

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

storage

storage manager

tags

user-specified tags

uuid

UUID from libvirt.

volumes

storage volumes

Helper classes and functions

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

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>)

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

check_with_netvm(feature, default=<object object>)

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

check_with_template(feature, default=<object object>)

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>)

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.

pop(_key, _default=None)

Not implemented :raises: NotImplementedError

popitem()

Not implemented :raises: NotImplementedError

setdefault(_key, _default=None)

Not implemented :raises: NotImplementedError

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

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)

Bases: Emitter

Mixin containing network functionality

attach_network()

Attach network in this machine to it’s netvm.

detach_network()

Detach machine from it’s netvm

static get_ip6_for_vm(vm)

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)

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

has_firewall()

Return True if there are some vm specific firewall rules set

is_networked()

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

Returns:

True if is machine can reach network, False otherwise.

Return type:

bool

on_domain_pre_shutdown(event, force=False)

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

on_domain_qdb_create(event)

Fills the QubesDB with firewall entries.

on_domain_shutdown(event, **kwargs)

Cleanup network interfaces of connected, running VMs.

This will allow re-reconnecting them cleanly later.

on_domain_started(event, **kwargs)

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)

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

on_net_domain_connect(event, vm)

Reloads the firewall config for vm

on_pre_spawn(event, **kwargs)

Prepare qubesdb in netvm entries before relevant interface is created

on_property_pre_reset_netvm(event, name, oldvalue=None)

Sets the the NetVM to default NetVM

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

Run sanity checks before setting a new NetVM

on_property_reset_netvm(event, name, oldvalue=None)

Sets the the NetVM to default NetVM

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

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

reload_connected_ips()

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

reload_firewall_for_vm(vm)

Reload the firewall rules for the vm

set_mapped_ip_info_for_vm(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

DNS servers set up for this domain.

gateway

Gateway for other domains that use this domain as netvm.

gateway6

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

ip

IP address of this domain.

ip6

IPv6 address of this domain.

mac

MAC address of the NIC emulated inside VM

property netmask

Netmask for gateway address.

netvm

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

provides_network

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

visible_gateway

Default gateway of this domain as seen by the domain.

visible_gateway6

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

visible_ip

IP address of this domain as seen by the domain.

visible_ip6

IPv6 address of this domain as seen by the domain.

visible_netmask

Netmask as seen by the domain.

Particular VM classes

Main types:

• qubes.vm.qubesvm – Shared functionality
• qubes.vm.appvm – Application VM
• qubes.vm.templatevm – Template for AppVM

Special VM types:

• qubes.vm.dispvm – Disposable VM
• qubes.vm.adminvm – Dom0