qubes.vm.qubesvm – Shared functionality

class qubes.vm.qubesvm.QubesVM(app, xml, volume_config=None, **kwargs)

Bases: NetVMMixin, BaseVM

Base functionality of Qubes VM shared between all VMs.

The following events are raised on this class or its subclasses:

domain-init(subject, event)

Fired at the end of class’ constructor.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-init')

domain-load(subject, event)

Fired after the qube was loaded from qubes.xml

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-loaded')

domain-pre-start(subject, event, start_guid, mem_required)

Fired at the beginning of start() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-pre-start')

other arguments are as in :py:meth:`start`

domain-pre-spawn(subject, event, start_guid)

Fired just before creating libvirt domain. But after preparation steps - verifying storage, requesting memory, starting netvm etc.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-pre-spawn')

Handler for this event may be asynchronous.

other arguments are as in :py:meth:`start`

domain-spawn(subject, event, start_guid)

Fired after creating libvirt domain.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-spawn')

Handler for this event may be asynchronous.

other arguments are as in :py:meth:`start`

domain-start(subject, event, start_guid)

Fired at the end of start() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-start')

other arguments are as in :py:meth:`start`

domain-start-failed(subject, event, reason)

Fired when start() method fails. reason argument is a textual error message.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-start-failed')

domain-paused(subject, event)

Fired when the domain has been paused.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-paused')

domain-unpaused(subject, event)

Fired when the domain has been unpaused.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-unpaused')

domain-stopped(subject, event)

Fired when domain has been stopped.

This event is emitted before 'domain-shutdown' and will trigger the cleanup in QubesVM. So if you require that the cleanup has already run use 'domain-shutdown'.

Note that you can receive this event as soon as you received 'domain-pre-start'. This also can be emitted in case of a startup failure, before or after 'domain-start-failed'.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-stopped')

domain-shutdown(subject, event)

Fired when domain has been shut down. It is generated after 'domain-stopped'.

Note that you can receive this event as soon as you received 'domain-pre-start'. This also can be emitted in case of a startup failure, before or after 'domain-start-failed'.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-shutdown')

domain-pre-shutdown(subject, event, force)

Fired at the beginning of shutdown() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-pre-shutdown')

• force – If the shutdown is to be forceful

domain-shutdown-failed(subject, event, reason)

Fired when domain-pre-shutdown event was sent, but the actual shutdown operation failed. It can be caused by other domain-pre-shutdown handler blocking the operation with an exception, or a shutdown timeout.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-shutdown-failed')

• reason – Error message

domain-cmd-pre-run(subject, event, start_guid)

Fired at the beginning of run_service() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-cmd-pre-run')

• start_guid – If the gui daemon can be started

domain-create-on-disk(subject, event)

Fired at the end of create_on_disk() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-create-on-disk')

domain-remove-from-disk(subject, event)

Fired at the beginning of remove_from_disk() method, before the qube directory is removed.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-remove-from-disk')

domain-clone-files(subject, event, src)

Fired at the end of clone_disk_files() method.

Handler for this event may be asynchronous.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-clone-files')

• src – source qube

domain-verify-files(subject, event)

Fired at the end of clone_disk_files() method.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-verify-files')

If you think some files are missing or damaged, raise an exception.

domain-is-fully-usable(subject, event)

Fired at the end of clone_disk_files() method.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-is-fully-usable')

You may yield False from the handler if you think the qube is not fully usable. This will cause the domain to be in “transient” state in the domain lifecycle.

domain-qdb-create(subject, event)

Fired at the end of create_qdb_entries() method.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-qdb-create')

This event is a good place to add your custom entries to the qdb.

domain-qdb-change:watched-path(subject, event, path)

Fired when watched QubesDB entry is changed. See watch_qdb_path(). watched-path part of event name is what path was registered for watching, path in event argument is what actually have changed (which may be different if watching a directory, i.e. a path with / at the end).

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-qdb-change')

• path – changed QubesDB path

backup-get-files(subject, event)

Collects additional file to be included in a backup.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('backup-get-files')

Handlers should yield paths of the files.

domain-restore(subject, event)

Domain was just restored from backup, although the storage was not yet verified and the app object was not yet saved.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-restore')

domain-feature-pre-set:feature (subject, event, feature,

value [, oldvalue])

A feature will be changed. This event is fired before value is set. If any handler raises an exception, value will not be set. oldvalue is present only when there was any.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-feature-pre-set:' feature)

• feature – feature name

• value – new value

• oldvalue – old value, if any

domain-feature-set:feature (subject, event, feature, value

[, oldvalue])

A feature was changed. This event is fired before bare domain-feature-set event. oldvalue is present only when there was any.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-feature-set:' feature)

• feature – feature name

• value – new value

• oldvalue – old value, if any

domain-feature-delete:feature(subject, event, feature)

A feature was removed. This event is fired before bare domain-feature-delete event.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-feature-delete:' feature)

• feature – feature name

domain-feature-pre-delete:feature(subject, event, feature)

A feature will be removed. This event is fired before feature is removed. If any handler raises an exception,feature will not be removed.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-feature-pre-delete:' feature)

• feature – feature name

domain-tag-add:tag(subject, event, tag)

A tag was added.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-tag-add:' tag)

• tag – tag name

domain-tag-delete:tag(subject, event, tag)

A feature was removed.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('domain-tag-delete:' tag)

• tag – tag name

features-request(subject, event, *, untrusted_features)

The domain is performing a features request.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('features-request')

• untrusted_features – dict containing the feature request

The content of the untrusted_features variable is, as the name implies, UNTRUSTED. The remind this to programmer, the variable name has to be exactly as provided.

It is up to the extensions to decide, what to do with request, ranging from plainly ignoring the request to verbatim copy into features with only minimal sanitisation.

Handler for this event may be asynchronous.

firewall-changed(subject, event)

Firewall was changed.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('firewall-changed')

net-domain-connect(subject, event, vm)

Fired after connecting a domiain to this vm.

Parameters:

• subject – Event emitter (the qube object)

• event – Event name ('net-domain-connect')

• vm – The domain that was just connected.

On the vm object there was probably property-set:netvm fired earlier.

template-postinstall(subject, event)

Fired on non-template-based domain (TemplateVM, StandaloneVM) when it first reports qrexec presence. This happens at the first domain startup just after its installation and is suitable for performing various post-installation setup.

Handler for this event may be asynchronous.

async clone_disk_files(src, pool=None, pools=None)

Clone files from other vm.

Parameters:

src (qubes.vm.qubesvm.QubesVM) – source VM

async create_on_disk(pool=None, pools=None)

Create files needed for VM.

create_qdb_entries()

Create entries in Qubes DB.

get_cputime()

Get total CPU time burned by this domain since start.

Returns:

CPU time usage [FIXME unit].

Return type:

FIXME

get_mem()

Get current memory usage from VM.

Returns:

Memory usage [FIXME unit].

Return type:

FIXME

get_mem_static_max()

Get maximum memory available to VM.

Returns:

Memory limit [FIXME unit].

Return type:

FIXME

get_power_state()

Return power state description string.

Return value may be one of those:

return value	meaning
'Halted'	Machine is not active.
'Transient'	Machine is running, but does not have guid or qrexec available.
'Running'	Machine is ready and running.
'Paused'	Machine is paused.
'Suspended'	Machine is S3-suspended.
'Halting'	Machine is in process of shutting down.
'Dying'	Machine is still in process of shutting down.
'Crashed'	Machine crashed and is unusable, probably because of bug in dom0.
'NA'	Machine is in unknown state (most likely libvirt domain is undefined).

FIXME: graph below may be incomplete and wrong. Click on method name to see its documentation.

digraph { node [fontname="sans-serif"]; edge [fontname="mono"]; Halted; NA; Dying; Crashed; Transient; Halting; Running; Paused [color=gray75 fontcolor=gray75]; Suspended; NA -> Halted; Halted -> NA [constraint=false]; Halted -> Transient [xlabel="start()" URL="#qubes.vm.qubesvm.QubesVM.start"]; Transient -> Running; Running -> Halting [xlabel="shutdown()" URL="#qubes.vm.qubesvm.QubesVM.shutdown" constraint=false]; Halting -> Dying -> Halted [constraint=false]; /* cosmetic, invisible edges to put rank constraint */ Dying -> Halting [style="invis"]; Halting -> Transient [style="invis"]; Running -> Halted [label="kill()" URL="#qubes.vm.qubesvm.QubesVM.kill" constraint=false]; Running -> Crashed [constraint=false]; Crashed -> Halted [constraint=false]; Running -> Paused [label="pause()" URL="#qubes.vm.qubesvm.QubesVM.pause" color=gray75 fontcolor=gray75]; Running -> Suspended [label="suspend()" URL="#qubes.vm.qubesvm.QubesVM.suspend" color=gray50 fontcolor=gray50]; Paused -> Running [label="unpause()" URL="#qubes.vm.qubesvm.QubesVM.unpause" color=gray75 fontcolor=gray75]; Suspended -> Running [label="resume()" URL="#qubes.vm.qubesvm.QubesVM.resume" color=gray50 fontcolor=gray50]; Running -> Suspended [label="suspend()" URL="#qubes.vm.qubesvm.QubesVM.suspend"]; Suspended -> Running [label="resume()" URL="#qubes.vm.qubesvm.QubesVM.resume"]; { rank=source; Halted NA }; { rank=same; Transient Halting }; { rank=same; Crashed Dying }; { rank=sink; Paused Suspended }; }

See also

http://wiki.libvirt.org/page/VM_lifecycle

Description of VM life cycle from the point of view of libvirt.

https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainState

Libvirt’s enum describing precise state of a domain.

is_halted()

Check whether this domain’s state is ‘Halted’ :returns: True if this domain is halted, False otherwise. :rtype: bool

is_kernel_from_vm()

Does the kernel is really a bootloader loading the kernel from within the VM?

is_memory_balancing_possible()

Check if memory balancing can be enabled. Reasons to not enable it:

• have PCI devices

• balloon driver not present

We don’t have a reliable way to detect the second point, but good heuristic is HVM virt_mode (PV and PVH require OS support, and it does include the balloon driver) and lack of qrexec/meminfo-writer service support (no qubes tools installed).

is_paused()

Check whether this domain is paused.

Returns:

True if this domain is paused, False otherwise.

Return type:

bool

is_qrexec_running(stubdom=False)

Check whether qrexec for this domain is available.

Returns:

True if qrexec is running, False otherwise.

Return type:

bool

is_running()

Check whether this domain is running.

Returns:

True if this domain is started, False otherwise.

Return type:

bool

async kill()

Forcefully shutdown (destroy) domain.

Raises:

qubes.exc.QubesVMNotStartedError – when domain is already shut down.

libvirt_undefine()

Undefine domain object in libvirt

on_domain_is_fully_usable(event)

Check whether domain is running and sane.

Currently this checks for running qrexec.

async on_domain_stopped(_event, **_kwargs)

Cleanup after domain was stopped

on_libvirt_domain_stopped()

Handle VIR_DOMAIN_EVENT_STOPPED events from libvirt.

This is not a Qubes event handler. Instead we do some sanity checks and synchronization with start() and then emits Qubes events.

async pause()

Pause (suspend) domain.

relative_path(path)

Return path relative to py:attr:dir_path.

Parameters:

path (str) – Path in question.

Returns:

Relative path.

async remove_from_disk()

Remove domain remnants from disk.

async resume()

Resume suspended domain.

Raises:

• qubes.exc.QubesVMNotSuspendedError – when machine is not paused

• qubes.exc.QubesVMError – when machine is suspended

async run(command, user=None, **kwargs)

Run a shell command inside the domain using qrexec.

This method is a coroutine.

async run_for_stdio(*args, input=None, **kwargs)

Run a shell command inside the domain using qrexec.

This method is a coroutine.

async run_service(service, source=None, user=None, *, stubdom=False, filter_esc=False, autostart=False, gui=False, **kwargs)

Run service on this VM

Parameters:

• service (str) – service name

• source (qubes.vm.qubesvm.QubesVM) – source domain as presented to this VM

• user (str) – username to run service as

• filter_esc (bool) – filter escape sequences to protect terminal emulator

• autostart (bool) – if True, machine will be started if it is not running

• gui (bool) – when autostarting, also start gui daemon

Return type:

asyncio.subprocess.Process

Note

User root is redefined to SYSTEM in the Windows agent code

async run_service_for_stdio(*args, input=None, **kwargs)

Run a service, pass an optional input and return (stdout, stderr).

Raises an exception if return code != 0.

args and kwargs are passed verbatim to run_service().

Warning

There are some combinations if stdio-related kwargs, which are not filtered for problems originating between the keyboard and the chair.

async shutdown(force=False, wait=False, timeout=None)

Shutdown domain.

Parameters:

• force – ignored

• wait – wait for shutdown to complete

• timeout – shutdown wait timeout (for *wait*=True), defaults to

shutdown_timeout :raises qubes.exc.QubesVMNotStartedError: when domain is already shut down.

async start(start_guid=True, notify_function=None, mem_required=None)

Start domain

Parameters:

• start_guid (bool) – FIXME

• notify_function (collections.abc.Callable) – FIXME

• mem_required (int) – FIXME

async static start_daemon(*command, input=None, **kwargs)

Start a daemon for the VM

This function take care to run it as appropriate user.

Parameters:

• command – command to run (array for subprocess.check_call())

• kwargs – args for subprocess.check_call()

Returns:

None

async start_qrexec_daemon(stubdom=False)

Start qrexec daemon.

Raises:

OSError – when starting fails.

async start_qubesdb()

Start QubesDB daemon.

Raises:

OSError – when starting fails.

async suspend()

Suspend (pause) domain.

Raises:

qubes.exc.QubesVMNotRunnignError – when domain is already shut down.

async unpause()

Resume (unpause) a domain

audiovm

VM used for Audio

autostart

Setting this to True means that VM should be autostarted on dom0 boot.

backup_timestamp

Time of last backup of the qube, in seconds since unix epoch

property block_devices

Return all qubes.storage.BlockDevice for current domain for serialization in the libvirt XML template as <disk>.

debug

Turns on debugging features.

default_dispvm

Default VM to be used as Disposable VM for service calls.

default_user

Default user to start applications as. TemplateBasedVMs use its template’s value by default.

property dir_path

Root directory for files related to this domain

dir_path_prefix = 'appvms'

directory in which domains of this class will reside

guivm

VM used for Gui

icon

freedesktop icon name, suitable for use in PyQt4.QtGui.QIcon.fromTheme()

include_in_backups

If this domain is to be included in default backup.

installed_by_rpm

If this domain’s image was installed from package tracked by package manager.

kernel

Kernel used by this domain. TemplateBasedVMs use its template’s value by default.

kernelopts

Kernel command line passed to domain. TemplateBasedVMs use its template’s value by default.

property kernelopts_common

Kernel options which should be used in addition to kernelopts property.

This is specific to kernel (and initrd if any)

keyboard_layout

Keyboard layout for this VM

property libvirt_domain

Libvirt domain object from libvirt.

May be None, if libvirt knows nothing about this domain.

management_dispvm

Default DVM template for Disposable VM for managing this VM.

maxmem

Maximum amount of memory available for this VM (for the purpose of the memory balancer). Set to 0 to disable memory balancing for this qube. TemplateBasedVMs use its template’s value by default (unless memory balancing not supported for this qube).

memory

Memory currently available for this VM. TemplateBasedVMs use its template’s value by default.

qrexec_timeout

Time in seconds after which qrexec connection attempt is deemed failed. Operating system inside VM should be able to boot in this time.

shutdown_timeout

Time in seconds for shutdown of the VM, after which VM may be forcefully powered off. Operating system inside VM should be able to fully shutdown in this time.

start_time

Tell when machine was started.

Return type:

float or None

stubdom_mem

Memory amount allocated for the stubdom

property untrusted_qdb

QubesDB handle for this domain.

updateable

True if this machine may be updated on its own.

property use_memory_hotplug

Use memory hotplug for memory balancing. This is preferred if supported, because it has less initial overhead and reduces Xen’s attack surface. This needs to be supported by the VM’s kernel.

vcpus

Number of virtual CPUs for a qube. TemplateBasedVMs use its template’s value by default.

virt_mode

Virtualisation mode: full virtualisation (“HVM”), or paravirtualisation (“PV”), or hybrid (“PVH”).

TemplateBasedVMs use its template’s value by default.

xid

Xen ID.

Or not Xen, but ID.