qubes.features - Qubes VM features, services¶
Features are generic mechanism for storing key-value pairs attached to a VM. The primary use case for them is data storage for extensions (you can think of them as more flexible properties, defined by extensions), but some are also used in the qubes core itself. There is no definite list of supported features, each extension can set their own and there is no requirement of registration, but qvm-features man page contains well known ones. In addition, there is a mechanism for VM request setting a feature. This is useful for extensions to discover if its VM part is present.
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.
qubes.features.Features inherits from dict, so provide
all the standard functions to get, list and set values. Additionally provide
helper functions to check if given feature is set on the VM and default to the
value on the VM’s template or netvm. This is useful for features which nature is
inherited from other VMs, like “is package X is installed” or “is VM behind
a VPN”.
Example usage of features in extension:
import qubes.exc
import qubes.ext
class ExampleExtension(qubes.ext.Extension):
@qubes.ext.handler('domain-pre-start')
def on_domain_start(self, vm, event, **kwargs):
if vm.features.get('do-not-start', False):
raise qubes.exc.QubesVMError(vm,
'Start prohibited because of do-not-start feature')
if vm.features.check_with_template('something-installed', False):
# do something
The above extension does two things:
prevent starting a qube with
do-not-startfeature setdo something when
something-installedfeature is set on the qube, or its template
qvm-features-request, qubes.PostInstall service¶
When some package in the VM want to request feature to be set (aka advertise
support for it), it should place a shell script in /etc/qubes/post-install.d.
This script should call qvm-features-request with FEATURE=VALUE
pair(s) as arguments to request those features. It is recommended to use very
simple values here (for example 1). The script should be named in form
XX-package-name.sh where XX is two-digits number below 90 and
package-name is unique name specific to this package (preferably actual
package name). The script needs executable bit set.
qubes.PostInstall service will call all those scripts after any package
installation and also after initial template installation.
This way package have a chance to report to dom0 if any feature is
added/removed.
The features flow to dom0 according to the diagram below. Important part is that
qubes core qubes.ext.Extension is responsible for handling such
request in features-request event handler. If no extension handles given
feature request, it will be ignored. The extension should carefuly validate
requested features (ignoring those not recognized - may be for another
extension) and only then set appropriate value on VM object
(qubes.vm.BaseVM.features). It is recommended to make the
verification code as bulletproof as possible (for example allow only specific
simple values, instead of complex structures), because feature requests come
from untrusted sources. The features actually set on the VM in some cases may
not be necessary those requested. Similar for values.
Example /etc/qubes/post-install.d/20-example.sh file:
#!/bin/sh
qvm-features-request example-feature=1
Example extension handling the above:
import qubes.ext
class ExampleExtension(qubes.ext.Extension):
# the last argument must be named untrusted_features
@qubes.ext.handler('features-request')
def on_features_request(self, vm, event, untrusted_features):
# don't allow TemplateBasedVMs to request the feature - should be
# requested by the template instead
if hasattr(vm, 'template'):
return
untrusted_value = untrusted_features.get('example-feature', None)
# check if feature is advertised and verify its value
if untrusted_value != '1':
return
value = untrusted_value
# and finally set the value
vm.features['example-feature'] = value
Services¶
Qubes services are implemented
as features with service. prefix. The
qubes.ext.services.ServicesExtension enumerate all the features
in form of service.<service-name> prefix and write them to QubesDB as
/qubes-service/<service-name> and value either 0 or 1.
VM startup scripts list those entries for for each with value of 1, create
/var/run/qubes-service/<service-name> file. Then, it can be conveniently
used by other scripts to check whether dom0 wishes service to be enabled or
disabled.
VM package can advertise what services are supported. For that, it needs to
request supported-service.<service-name> feature with value 1 according
to description above. The qubes.ext.services.ServicesExtension will
handle such request and set this feature on VM object. supported-service.
features that stop being advertised with qvm-features-request call are
removed. This way, it’s enough to remove the file from
/etc/qubes/post-install.d (for example by uninstalling package providing
the service) to tell dom0 the service is no longer supported. Services
advertised by TemplateBasedVMs are currently ignored (related
supported-service. features are not set), but retrieving them may be added
in the future. Applications checking for specific service support should use
vm.features.check_with_template('supported-service.<service-name>', False)
call on desired VM object. When enumerating all supported services, application
should consider both the vm and its template (if any).
Various tools will use this information to discover if given service is
supported. The API does not enforce service being first advertised before being
enabled (means: there can be service which is enabled, but without matching
supported-service. feature). The list of well known services is in
qvm-service man page.
Example /etc/qubes/post-install.d/20-my-service.sh:
#!/bin/sh
qvm-features-request supported-service.my-service=1
Services and features can be then inspected from dom0 using qvm-features tool, for example:
$ qvm-features my-qube
supported-service.my-service 1
VM config and passing configuration values to VMs¶
Features that are prefixed with vm-config. are accessible via qubes-db
from inside the qube. This is an easy way to pass certain information from
dom0/gui domain tools to the inside of the qube.
To read a vm-config.feature_name feature, use:
$ qubesdb-read /vm-config/feature_name
value
Announcing supported features¶
For non-service features, there is similar announce mechanism to the above, but
uses supported-feature. prefix. It works like this:
1. The TemplateVM (or StandaloneVM) announces
supported-feature.FEATURE_NAME=1 (with FEATURE_NAME replaced with an
actual feature name) using qvm-features-request tool (see above how to use it).
2. core-admin extension
qubes.ext.supported_features.SupportedFeaturesExtension records
such requests as features on the same VM.
3. Any tool that wants to check if the feature support is advertised by the VM,
can look into its features. For template-based VMs it is advised to check
also its template - there is a vm.features.check_with_template()
function specifically for this.
Note that (similar to services) it is not necessary for the feature to be
advertised to enable it. In fact, many features does not need any support from
the VM side, so they will work without matching supported-feature. entry.
Whether a feature requires VM-side support, is documented on case-by-case basis
in qvm-features tool manual page.
Announcing supported RPC services¶
Each VM (including templates) can also announce supported RPC services. This is
done similar to features and qvm-services as explained above, but with
supported-rpc. prefix. Template-based VM announce only services installed
in its private image (so /usr/local/etc/qubes-rpc in Linux). To get all RPC
services supported by a given template-based VM, one needs to look at both its
template and the VM itself.
Supported RPC services can be inspected from dom0 using qvm-features tool, for example:
$ qvm-features my-template
...
supported-rpc.qubes.Gpg 1
...
Module contents¶
- class qubes.features.Features(subject, other=None, **kwargs)[source]¶
Bases:
dictManager 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 asFalse) and non-empty string, which isTrue. Anything assigned to the mapping is coerced to strings, however if you assign instances ofbool, 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.