qubes.vm.qubesvm – Shared functionality

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

Bases: qubes.vm.mix.net.NetVMMixin, qubes.vm.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 can be asynchronous (a coroutine).

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-pre-start')

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 can be asynchronous (a coroutine).

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 can be asynchronous (a coroutine).

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-start')

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

domain-shutdown(subject, event)

Fired when domain has been shut down.

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 can be asynchronous (a coroutine).

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-pre-shutdown')
  • force – If the shutdown is to be forceful
domain-cmd-pre-run(subject, event, start_guid)

Fired at the beginning of run_service() method.

Handler for this event can be asynchronous (a coroutine).

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 can be asynchronous (a coroutine).

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 can be asynchronous (a coroutine).

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 can be asynchronous (a coroutine).

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-set (subject, event, feature, value
[, oldvalue])

A feature was changed. oldvalue is present only when there was any.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-feature-set')
  • feature – feature name
  • value – new value
  • oldvalue – old value, if any
domain-feature-delete(subject, event, feature)

A feature was removed.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-feature-delete')
  • feature – feature name
domain-tag-add(subject, event, tag)

A tag was added.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-tag-add')
  • tag – tag name
domain-tag-delete(subject, event, tag)

A feature was removed.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('domain-tag-delete')
  • tag – tag name
feature-request(subject, event, *, untrusted_features)

The domain is performing a feature request.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('feature-request')
  • untrusted_featuresdict 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.

monitor-layout-change(subject, event, monitor_layout)

Desktop layout was changed, probably because a display was plugged in or out.

Parameters:
  • subject – Event emitter (the qube object)
  • event – Event name ('monitor-layout-change')
  • monitor_layout – The new layout
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.

clone_disk_files(src, pool=None, pools=None)[source]

Clone files from other vm.

Parameters:src (qubes.vm.qubesvm.QubesVM) – source VM
create_on_disk(pool=None, pools=None)[source]

Create files needed for VM.

create_qdb_entries()[source]

Create entries in Qubes DB.

force_shutdown(*args, **kwargs)[source]

Deprecated alias for kill()

get_cputime()[source]

Get total CPU time burned by this domain since start.

Returns:CPU time usage [FIXME unit].
Return type:FIXME
get_mem()[source]

Get current memory usage from VM.

Returns:Memory usage [FIXME unit].
Return type:FIXME
get_mem_static_max()[source]

Get maximum memory available to VM.

Returns:Memory limit [FIXME unit].
Return type:FIXME
get_power_state()[source]

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 crashed and is unusable.
'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="force_shutdown()"
            URL="#qubes.vm.qubesvm.QubesVM.force_shutdown"
            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.
get_start_time()[source]

Tell when machine was started.

Return type:datetime.datetime
is_halted()[source]

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

is_paused()[source]

Check whether this domain is paused.

Returns:True if this domain is paused, False otherwise.
Return type:bool
is_qrexec_running()[source]

Check whether qrexec for this domain is available.

Returns:True if qrexec is running, False otherwise.
Return type:bool
is_running()[source]

Check whether this domain is running.

Returns:True if this domain is started, False otherwise.
Return type:bool
kill()[source]

Forcefuly shutdown (destroy) domain.

Raises:qubes.exc.QubesVMNotStartedError – when domain is already shut down.
on_domain_is_fully_usable(event)[source]

Check whether domain is running and sane.

Currently this checks for running qrexec.

on_domain_shutdown(_event, **_kwargs)[source]

Cleanup after domain shutdown

on_domain_shutdown_coro()[source]

Coroutine for executing cleanup after domain shutdown. Do not allow domain to be started again until this finishes.

pause()[source]

Pause (suspend) domain.

relative_path(path)[source]

Return path relative to py:attr:dir_path.

Parameters:path (str) – Path in question.
Returns:Relative path.
remove_from_disk()[source]

Remove domain remnants from disk.

resume()[source]

Resume suspended domain.

Raises:
run(command, user=None, **kwargs)[source]

Run a shell command inside the domain using qrexec.

This method is a coroutine.

run_for_stdio(*args, input=None, **kwargs)[source]

Run a shell command inside the domain using qubes.VMShell qrexec.

This method is a coroutine.

kwargs are passed verbatim to run_service_for_stdio(). See disclaimer there.

run_service(service, source=None, user=None, filter_esc=False, autostart=False, gui=False, **kwargs)[source]

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

run_service_for_stdio(*args, input=None, **kwargs)[source]

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.

shutdown(force=False, wait=False)[source]

Shutdown domain.

Raises:qubes.exc.QubesVMNotStartedError – when domain is already shut down.
start(start_guid=True, notify_function=None, mem_required=None)[source]

Start domain

Parameters:
static start_daemon(*command, input=None, **kwargs)[source]

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

start_qrexec_daemon()[source]

Start qrexec daemon.

Raises:OSError – when starting fails.
start_qubesdb()[source]

Start QubesDB daemon.

Raises:OSError – when starting fails.
suspend()[source]

Suspend (pause) domain.

Raises:qubes.exc.QubesVMNotRunnignError – when domain is already shut down.
unpause()[source]

Resume (unpause) a domain

autostart

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

backup_timestamp

FIXME

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

FIXME

dir_path

Root directory for files related to this domain

dir_path_prefix = 'appvms'

directory in which domains of this class will reside

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.

kernelopts

Kernel command line passed to domain.

label

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

libvirt_domain

Libvirt domain object from libvirt.

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

maxmem

Maximum amount of memory available for this VM (for the purpose of the memory balancer).

memory

Memory currently available for this VM.

name

User-specified name of the domain.

qid

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

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.

startup_lock = None

operations which shouldn’t happen simultaneously with qube startup

stubdom_mem

Memory ammount allocated for the stubdom

untrusted_qdb

QubesDB handle for this domain.

updateable

True if this machine may be updated on its own.

uuid

UUID from libvirt.

vcpus

Number of virtual CPUs for a qube

virt_mode

Virtualisation mode: full virtualisation (“hvm”), or paravirtualisation (“pv”)

xid

Xen ID.

Or not Xen, but ID.