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 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-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 otherdomain-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.
-
clone_disk_files
(src, pool=None, pools=None)[source]¶ Clone files from other vm.
Parameters: src (qubes.vm.qubesvm.QubesVM) – source VM
-
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 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.
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
()[source]¶ Check whether this domain’s state is ‘Halted’ :returns:
True
if this domain is halted,False
otherwise. :rtype: bool
-
is_memory_balancing_possible
()[source]¶ Check if memory balancing can be enabled. Reasons to not enable it:
- have PCI devices
- balloon driver not present
We don’t have reliable way to detect the second point, but good heuristic is HVM virt_mode (PV and PVH require OS support and it does include balloon driver) and lack of qrexec/meminfo-writer service support (no qubes tools installed).
-
is_paused
()[source]¶ Check whether this domain is paused.
Returns: True
if this domain is paused,False
otherwise.Return type: bool
-
is_qrexec_running
(stubdom=False)[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]¶ Forcefully 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_libvirt_domain_stopped
()[source]¶ 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.
-
relative_path
(path)[source]¶ Return path relative to py:attr:dir_path.
Parameters: path (str) – Path in question. Returns: Relative path.
-
resume
()[source]¶ Resume suspended domain.
Raises: - qubes.exc.QubesVMNotSuspendedError – when machine is not paused
- qubes.exc.QubesVMError – when machine is suspended
-
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 qrexec.
This method is a coroutine.
-
run_service
(service, source=None, user=None, stubdom=False, 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: Note
User
root
is redefined toSYSTEM
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, timeout=None)[source]¶ 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.
-
start
(start_guid=True, notify_function=None, mem_required=None)[source]¶ Start domain
Parameters: - start_guid (bool) – FIXME
- notify_function (collections.abc.Callable) – FIXME
- mem_required (int) – FIXME
-
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
- command – command to run (array for
-
start_qrexec_daemon
(stubdom=False)[source]¶ Start qrexec daemon.
Raises: OSError – when starting fails.
-
suspend
()[source]¶ Suspend (pause) domain.
Raises: qubes.exc.QubesVMNotRunnignError – when domain is already shut down.
-
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
-
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.
-
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.
-
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
-
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.
-
stubdom_mem
¶ Memory amount allocated for the stubdom
-
untrusted_qdb
¶ QubesDB handle for this domain.
-
updateable
¶ True if this machine may be updated on its own.
-
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.
-