qubesadmin.tools package¶
Submodules¶
qubesadmin.tools.dochelpers module¶
Documentation helpers.
This module contains classes and functions which help to maintain documentation, particularly our custom Sphinx extension.
- class qubesadmin.tools.dochelpers.CommandCheckVisitor(command, sub_commands, document)[source]¶
Bases:
SparseNodeVisitor
Checks if the visited sub command section nodes and the specified sub command args are in sync.
- check_undocumented_sub_commands()[source]¶
Call this to check if any undocumented sub_commands are left.
While the documentation talks about a ‘SparseNodeVisitor.depart_document()’ function, this function does not exists. (For details see implementation of
NodeVisitor.dispatch_departure()
) So we need to manually call this.
- visit_Text(node)[source]¶
If the visited text node starts with ‘alias: ‘, all the provided comma separted alias in this node, are removed from self.sub_commands
- visit_section(node)[source]¶
Checks if the visited sub-command section nodes exists and it options are in sync.
Uses
OptionsCheckVisitor
for checking sub-commands options
- class qubesadmin.tools.dochelpers.ManpageCheckVisitor(app, command, document)[source]¶
Bases:
SparseNodeVisitor
Checks if the sub-commands and options specified in the ‘COMMAND’ and ‘OPTIONS’ (case insensitve) sections in sync the command parser.
- class qubesadmin.tools.dochelpers.OptionsCheckVisitor(command, args, document)[source]¶
Bases:
SparseNodeVisitor
Checks if the visited option nodes and the specified args are in sync.
- check_undocumented_arguments(ignored_options=None)[source]¶
Call this to check if any undocumented arguments are left.
While the documentation talks about a ‘SparseNodeVisitor.depart_document()’ function, this function does not exists. (For details see implementation of
NodeVisitor.dispatch_departure()
) So we need to manually call this.
qubesadmin.tools.qubes_prefs module¶
Manipulate global properties.
qubesadmin.tools.qvm_backup module¶
qubesadmin.tools.qvm_backup_restore module¶
qubesadmin.tools.qvm_check module¶
qubesadmin.tools.qvm_clone module¶
qubesadmin.tools.qvm_create module¶
qubesadmin.tools.qvm_device module¶
Qubes volume and block device management
- class qubesadmin.tools.qvm_device.DeviceAction(help='A backend, port & device id combination', required=True, allow_unknown=False, only_port=False, **kwargs)[source]¶
Bases:
QubesAction
Action for argument parser that gets the :py:class:
qubesadmin.device_protocol.VirtualDevice
from a BACKEND:PORT_ID:DEVICE_ID string.
- class qubesadmin.tools.qvm_device.Line(device: DeviceInfo, assignment=False)[source]¶
Bases:
object
Helper class to hold single device info for listing
- property assignments¶
list of frontends the device is assigned to
- qubesadmin.tools.qvm_device.assign_device(args)[source]¶
Called by the parser to execute the qvm-devices assign subcommand.
- qubesadmin.tools.qvm_device.attach_device(args)[source]¶
Called by the parser to execute the qvm-devices attach subcommand.
- qubesadmin.tools.qvm_device.detach_device(args)[source]¶
Called by the parser to execute the qvm-devices detach subcommand.
- qubesadmin.tools.qvm_device.get_parser(device_class=None)[source]¶
Create
argparse.ArgumentParser
suitable for qvm-block.
- qubesadmin.tools.qvm_device.info_device(args)[source]¶
Called by the parser to execute the qvm-devices info subcommand.
- qubesadmin.tools.qvm_device.init_list_parser(sub_parsers)[source]¶
Configures the parser for the qvm-devices list subcommand
- qubesadmin.tools.qvm_device.is_on_deny_list(device, dest)[source]¶
Checks if any interface of the device is on the deny list for dest vm.
Reads a deny list from a file (see DEVICE_DENY_LIST), which contains vm names and their associated denied interfaces.
The deny list file should be formatted such that each line contains a vm name followed by a comma-separated list of denied interfaces. Interfaces can be separated by commas or spaces.
Example:
` vm1 u******, b012345 vm2 ****** `
vm1 denies USB devices and block interface 012345 vm2 denies all devices.
- qubesadmin.tools.qvm_device.list_devices(args)[source]¶
Called by the parser to execute the qubes-devices list subcommand.
- qubesadmin.tools.qvm_device.parse_ro_option_as_read_only(options)[source]¶
For backward compatibility.
Read-only option could be represented as –ro, -o read-only=yes or -o ro=True etc.
- qubesadmin.tools.qvm_device.prepare_table(dev_list, with_sbdf=False)[source]¶
Converts a list of
qubes.devices.DeviceInfo
objects to a list of tuples for thequbes.tools.print_table()
.If qvm-devices is running in a TTY, it will omit duplicate data.
- Parameters:
dev_list (iterable) – List of
qubes.devices.DeviceInfo
objects.with_sbdf (bool) – when True, include SBDF identifier of PCI device
- Returns:
list of tuples
qubesadmin.tools.qvm_features module¶
qubesadmin.tools.qvm_firewall module¶
qubesadmin.tools.qvm_kill module¶
qubesadmin.tools.qvm_ls module¶
qvm-ls - List available domains
- class qubesadmin.tools.qvm_ls.Column(head, attr=None, doc=None)[source]¶
Bases:
object
A column in qvm-ls output characterised by its head and a way to fetch a parameter describing the domain.
- Parameters:
head (str) – Column head (usually uppercase).
attr (str) – Attribute, possibly complex (containing
.
). This may also be a callable that gets as its only argument the domain.doc (str) – Description of column (will be visible in –help-columns).
- cell(vm, insertion=0)[source]¶
Format one cell.
Note
This is only for technical formatting (filling with space). If you want to subclass the
Column
class, you should overrideColumn.format()
method instead.- Parameters:
qubes.vm.qubesvm.QubesVM – Domain to get a value from.
insertion (int) – Intending to shift the value to the right.
- Returns:
string to display
- Return type:
str
- columns = {'CLASS': Column(head='CLASS'), 'DISK': Column(head='DISK'), 'FLAGS': FlagsColumn(head='FLAGS'), 'GATEWAY': Column(head='GATEWAY'), 'MEMORY': Column(head='MEMORY'), 'PRIV-CURR': Column(head='PRIV-CURR'), 'PRIV-MAX': Column(head='PRIV-MAX'), 'PRIV-POOL': Column(head='PRIV-POOL'), 'PRIV-USED': Column(head='PRIV-USED'), 'ROOT-CURR': Column(head='ROOT-CURR'), 'ROOT-MAX': Column(head='ROOT-MAX'), 'ROOT-POOL': Column(head='ROOT-POOL'), 'ROOT-USED': Column(head='ROOT-USED'), 'STATE': Column(head='STATE')}¶
collection of all columns
- class qubesadmin.tools.qvm_ls.FlagsColumn[source]¶
Bases:
Column
Some fancy flags that describe general status of the domain.
- autostart(vm)¶
If the domain is marked for autostart.
- debug(vm)¶
If the domain is being debugged.
- format(vm)[source]¶
Format one cell value.
Return value to put in a table cell.
- Parameters:
qubes.vm.qubesvm.QubesVM – Domain to get a value from.
- Returns:
Value to put, or
None
if no value.- Return type:
str or None
- classmethod get_flags()[source]¶
Get all flags as list.
Holes between flags are filled with
_no_flag()
.- Return type:
list
- installed_by_rpm(vm)¶
If the domain is installed by RPM.
- internal(vm)¶
If the domain is internal (not normally shown, no appmenus).
- power(vm)[source]¶
Current power state.
r running t transient p paused s suspended h halting d dying c crashed ? unknown
- provides_network(vm)¶
If the domain provides network.
- type(vm)[source]¶
Type of domain.
0 AdminVM (AKA Dom0) aA AppVM dD DisposableVM sS StandaloneVM tT TemplateVM
When it is HVM (optimised VM), the letter is capital.
- updateable(vm)¶
If the domain is updateable.
- class qubesadmin.tools.qvm_ls.PropertyColumn(name)[source]¶
Bases:
Column
Column that displays value from property (
property
orqubes.property
) of domain.- Parameters:
name – Name of VM property.
- class qubesadmin.tools.qvm_ls.Table(domains, colnames, spinner, *, raw_data=False, tree_sorted=False, sort_order='NAME', reverse_sort=False, ignore_case=False)[source]¶
Bases:
object
Table that is displayed to the user.
- Parameters:
domains – Domains to include in the table.
colnames (list) – Names of the columns (need not to be uppercase).
- sort_to_tree(domains)[source]¶
Sort the domains as a network tree. It returns a list of sets. Each tuple stores the insertion of the cell name and the vm object.
- Parameters:
domains (list()) – The domains which will be sorted
- Return list(tuple()) tree:
returns a list of tuple(insertion, vm)
- qubesadmin.tools.qvm_ls.flag(field)[source]¶
Mark method as flag field.
- Parameters:
field (int) – Which field to fill (counted from 1)
- qubesadmin.tools.qvm_ls.formats = {'disk': ('name', 'state', 'disk', 'priv-curr', 'priv-max', 'priv-used', 'root-curr', 'root-max', 'root-used'), 'full': ('name', 'state', 'class', 'label', 'qid', 'xid', 'uuid'), 'kernel': ('name', 'state', 'class', 'template', 'kernel', 'kernelopts'), 'network': ('name', 'state', 'netvm', 'ip', 'ipback', 'gateway'), 'prefs': ('name', 'label', 'template', 'netvm', 'vcpus', 'initialmem', 'maxmem', 'virt_mode'), 'simple': ('name', 'state', 'class', 'label', 'template', 'netvm')}¶
Available formats. Feel free to plug your own one.
- qubesadmin.tools.qvm_ls.main(args=None, app=None)[source]¶
Main routine of qvm-ls.
- Parameters:
args (list) – Optional arguments to override those delivered from command line.
app – Operate on given app object instead of instantiating new one.
- qubesadmin.tools.qvm_ls.matches_power_states(domain, **states)[source]¶
Filter domains by their power state
qubesadmin.tools.qvm_pause module¶
qubesadmin.tools.qvm_pool module¶
Manages Qubes pools and their options
- qubesadmin.tools.qvm_pool.get_parser()[source]¶
Creates
argparse.ArgumentParser
suitable for qvm-pool.
qubesadmin.tools.qvm_prefs module¶
Manipulate VM properties.
qubesadmin.tools.qvm_remove module¶
qubesadmin.tools.qvm_run module¶
qubesadmin.tools.qvm_service module¶
qubesadmin.tools.qvm_shutdown module¶
qubesadmin.tools.qvm_start module¶
qubesadmin.tools.qvm_start_daemon module¶
qubesadmin.tools.qvm_template module¶
qubesadmin.tools.qvm_template_postprocess module¶
qubesadmin.tools.qvm_unpause module¶
qubesadmin.tools.qvm_volume module¶
Qubes volume management
- class qubesadmin.tools.qvm_volume.VolumeData(volume)[source]¶
Bases:
object
Wrapper object around
qubes.storage.Volume
, mainly to track the domains a volume is attached to.
- qubesadmin.tools.qvm_volume.extend_volumes(args)[source]¶
Called by the parser to execute the qvm-volume extend subcommand
- qubesadmin.tools.qvm_volume.get_parser()[source]¶
Create
argparse.ArgumentParser
suitable for qvm-volume.
- qubesadmin.tools.qvm_volume.init_clear_parser(sub_parsers)[source]¶
Add ‘clear’ action related options
- qubesadmin.tools.qvm_volume.init_config_parser(sub_parsers)[source]¶
Add ‘info’ action related options
- qubesadmin.tools.qvm_volume.init_extend_parser(sub_parsers)[source]¶
Add ‘extend’ action related options
- qubesadmin.tools.qvm_volume.init_import_parser(sub_parsers)[source]¶
Add ‘import’ action related options
- qubesadmin.tools.qvm_volume.init_info_parser(sub_parsers)[source]¶
Add ‘info’ action related options
- qubesadmin.tools.qvm_volume.init_list_parser(sub_parsers)[source]¶
Configures the parser for the qvm-volume list subcommand
- qubesadmin.tools.qvm_volume.init_revert_parser(sub_parsers)[source]¶
Add ‘revert’ action related options
- qubesadmin.tools.qvm_volume.list_volumes(args)[source]¶
Called by the parser to execute the qvm-volume list subcommand.
- qubesadmin.tools.qvm_volume.prepare_table(vd_list, full=False)[source]¶
Converts a list of
VolumeData
objects to a list of tupples for thequbes.tools.print_table()
.If qvm-volume is running in a TTY, it will ommit duplicate data.
- Parameters:
vd_list (list) – List of
VolumeData
objects.full (bool) – If set to true duplicate data is printed even when running from TTY.
- Returns:
list of tupples
Module contents¶
Qubes’ command line tools
- class qubesadmin.tools.AliasedSubParsersAction(option_strings, prog, parser_class, dest='==SUPPRESS==', required=False, help=None, metavar=None)[source]¶
Bases:
_SubParsersAction
SubParser with support for action aliases
- class qubesadmin.tools.PoolsAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶
Bases:
QubesAction
Action for argument parser to gather multiple pools
- class qubesadmin.tools.PropertyAction(option_strings, dest, *, metavar='NAME=VALUE', required=False, help='set property to a value')[source]¶
Bases:
Action
Action for argument parser that stores a property.
- class qubesadmin.tools.QubesAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶
Bases:
Action
Interface providing a convinience method to be called, after namespace.app is instantiated.
- class qubesadmin.tools.QubesArgumentParser(vmname_nargs=None, show_forceroot=False, version=None, **kwargs)[source]¶
Bases:
ArgumentParser
Parser preconfigured for use in most of the Qubes command-line tools.
- Parameters:
vmname_nargs (mixed) – The number of
VMNAME
arguments that should be consumed. Values include: * N (an integer) consumes N arguments (and produces a list) * ‘?’ consumes zero or one arguments * ‘*’ consumes zero or more arguments (and produces a list) * ‘+’ consumes one or more arguments (and produces a list)show_forceroot – don’t hide –force-root parameter, prevent running as root unless it is given
kwargs are passed to
argparser.ArgumentParser
.- Currenty supported options:
--force-root
(optional, ignored, help is suppressed)--offline-mode
do not talk to hypervisor (help is suppressed)--verbose
and--quiet
- Calling program should set the
version
argument for--version
option The default is extracted from qubesadmin package information. Setting
version
argument to ‘’ will disable--version
option.
- error_runtime(message, exit_code=1)[source]¶
Runtime error, without showing usage.
- Parameters:
message (str) – message to show
- class qubesadmin.tools.RunningVmNameAction(option_strings, nargs=1, dest='vmnames', help=None, **kwargs)[source]¶
Bases:
VmNameAction
Action for argument parser that gets a running domain from VMNAME
- class qubesadmin.tools.SinglePropertyAction(option_strings, dest, *, metavar='VALUE', const=None, nargs=None, required=False, help=None)[source]¶
Bases:
Action
Action for argument parser that stores a property.
- class qubesadmin.tools.SubParsersHelpAction(option_strings, dest='==SUPPRESS==', default='==SUPPRESS==', help=None)[source]¶
Bases:
_HelpAction
Print help for all options and all subparsers
- class qubesadmin.tools.VMVolumeAction(help='A pool & volume id combination', required=True, **kwargs)[source]¶
Bases:
QubesAction
Action for argument parser that gets the :py:class:
qubes.storage.Volume
from a VM:VOLUME string.
- qubesadmin.tools.VM_ALL = <object object>¶
constant returned when some action should be performed on all qubes
- class qubesadmin.tools.VmNameAction(option_strings, nargs=1, dest='vmnames', help=None, **kwargs)[source]¶
Bases:
QubesAction
Action for parsing one or multiple domains from provided VMNAMEs
- class qubesadmin.tools.VmNameGroup(container, required, vm_action=<class 'qubesadmin.tools.VmNameAction'>, help=None)[source]¶
Bases:
_MutuallyExclusiveGroup
Adds an a VMNAME, –all & –exclude parameters to a :py:class:
argparse.ArgumentParser`
.
- class qubesadmin.tools.VolumeAction(help='A pool & volume id combination', required=True, **kwargs)[source]¶
Bases:
QubesAction
Action for argument parser that gets the :py:class:
qubes.storage.Volume
from a POOL_NAME:VOLUME_ID string.