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)

Bases: SparseNodeVisitor

Checks if the visited sub command section nodes and the specified sub command args are in sync.

check_undocumented_sub_commands()

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)

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)

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)

Bases: SparseNodeVisitor

Checks if the sub-commands and options specified in the ‘COMMAND’ and ‘OPTIONS’ (case insensitve) sections in sync the command parser.

visit_section(node)

If section title is OPTIONS or COMMANDS dispatch the apropriate NodeVisitor.

class qubesadmin.tools.dochelpers.OptionsCheckVisitor(command, args, document)

Bases: SparseNodeVisitor

Checks if the visited option nodes and the specified args are in sync.

check_undocumented_arguments(ignored_options=None)

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.

visit_desc(node)

Skips all but ‘option’ elements

visit_desc_name(node)

Checks if the option is defined self.args

qubesadmin.tools.dochelpers.break_to_pdb(app, *_dummy)

DEBUG

qubesadmin.tools.dochelpers.check_man_args(app, doctree, docname)

Checks the manpage for undocumented or obsolete sub-commands and options.

qubesadmin.tools.dochelpers.make_rst_section(heading, char)

Format a section header in rst

qubesadmin.tools.dochelpers.prepare_manpage(command)

Build a man page skeleton

qubesadmin.tools.dochelpers.setup(app)

Setup Sphinx extension

qubesadmin.tools.qubes_prefs module

Manipulate global properties.

qubesadmin.tools.qubes_prefs.get_parser()

Prepare argument parser

qubesadmin.tools.qubes_prefs.main(args=None, app=None)

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)

Bases: QubesAction

Action for argument parser that gets the :py:class:qubesadmin.device_protocol.VirtualDevice from a BACKEND:PORT_ID:DEVICE_ID string.

parse_qubes_app(parser, namespace)

This method is called by qubes.tools.QubesArgumentParser after the namespace.app is instantiated. Oerwrite this method when extending qubes.tools.QubesAction to initialized values based on the namespace.app

class qubesadmin.tools.qvm_device.Line(device: DeviceInfo, assignment=False)

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)

Called by the parser to execute the qvm-devices assign subcommand.

qubesadmin.tools.qvm_device.attach_device(args)

Called by the parser to execute the qvm-devices attach subcommand.

qubesadmin.tools.qvm_device.detach_device(args)

Called by the parser to execute the qvm-devices detach subcommand.

qubesadmin.tools.qvm_device.get_parser(device_class=None)

Create argparse.ArgumentParser suitable for qvm-block.

qubesadmin.tools.qvm_device.info_device(args)

Called by the parser to execute the qvm-devices info subcommand.

qubesadmin.tools.qvm_device.init_list_parser(sub_parsers)

Configures the parser for the qvm-devices list subcommand

qubesadmin.tools.qvm_device.is_on_deny_list(device, dest)

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)

Called by the parser to execute the qubes-devices list subcommand.

qubesadmin.tools.qvm_device.main(args=None, app=None)

Main routine of qvm-block.

qubesadmin.tools.qvm_device.parse_ro_option_as_read_only(options)

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)

Converts a list of qubes.devices.DeviceInfo objects to a list of tuples for the qubes.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_device.unassign_device(args)

Called by the parser to execute the qvm-devices unassign subcommand.

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)

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)

Format one cell.

Note

This is only for technical formatting (filling with space). If you want to subclass the Column class, you should override Column.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

format(vm)

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

class qubesadmin.tools.qvm_ls.FlagsColumn

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)

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()

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)

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)

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)

Bases: Column

Column that displays value from property (property or qubes.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)

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).

get_head()

Get table head data (all column heads).

get_row(vm, insertion=0)

Get single table row data (all columns for one domain).

sort_to_tree(domains)

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)

tree_append_child(parent, level)

Concatenate the network children of the vm to a list.

Parameters:

qubes.vm.qubesvm.QubesVM – Parent vm of the children VMs

write_table(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Sort & write whole table to file-like object.

Parameters:

stream (file) – Stream to write the table to.

qubesadmin.tools.qvm_ls.calc_size(vm, volume_name)

Calculates the volume size in MiB

qubesadmin.tools.qvm_ls.calc_usage(vm, volume_name)

Calculates the volume usage in MiB

qubesadmin.tools.qvm_ls.calc_used(vm, volume_name)

Calculates the volume usage in percent

qubesadmin.tools.qvm_ls.flag(field)

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.get_parser()

Create argparse.ArgumentParser suitable for qvm-ls.

qubesadmin.tools.qvm_ls.main(args=None, app=None)

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)

Filter domains by their power state

qubesadmin.tools.qvm_ls.process_vm(vm)

Process VM object to find all listable properties.

Parameters:

vm (qubesmgmt.vm.QubesVM) – VM object.

qubesadmin.tools.qvm_ls.simple_flag(field, letter, attr, doc=None)

Create simple, binary flag.

Parameters:

• attr (str) – Attribute name to check. If result is true, flag is fired.

• letter (str) – The letter to show.

qubesadmin.tools.qvm_pause module

qubesadmin.tools.qvm_pool module

Manages Qubes pools and their options

qubesadmin.tools.qvm_pool.add_pool(args)

Adds a new pool

qubesadmin.tools.qvm_pool.get_parser()

Creates argparse.ArgumentParser suitable for qvm-pool.

qubesadmin.tools.qvm_pool.info_pools(args)

Prints info about the specified pools

qubesadmin.tools.qvm_pool.init_add_parser(sub_parsers)

Adds ‘add’ action related options

qubesadmin.tools.qvm_pool.init_info_parser(sub_parsers)

Adds ‘info’ action related options

qubesadmin.tools.qvm_pool.init_list_parser(sub_parsers)

Adds ‘list’ action related options

qubesadmin.tools.qvm_pool.init_remove_parser(sub_parsers)

Adds ‘remove’ action related options

qubesadmin.tools.qvm_pool.init_set_parser(sub_parsers)

Adds ‘set’ action related options

qubesadmin.tools.qvm_pool.list_drivers(args)

Lists all drivers with their options

qubesadmin.tools.qvm_pool.list_pools(args)

Lists all available pools

qubesadmin.tools.qvm_pool.main(args=None, app=None)

Main routine of qvm-pool.

qubesadmin.tools.qvm_pool.remove_pools(args)

Removes the specified pools

qubesadmin.tools.qvm_pool.set_pool(args)

Modifies driver options for a pool

qubesadmin.tools.qvm_pool.uses_legacy_options(args, app)

Checks if legacy options and used, and invokes the legacy tool

qubesadmin.tools.qvm_prefs module

Manipulate VM properties.

qubesadmin.tools.qvm_prefs.get_parser(vmname_nargs=1)

Return argument parser for generic property-related tool

qubesadmin.tools.qvm_prefs.main(args=None, app=None)

qubesadmin.tools.qvm_prefs.process_actions(parser, args, target)

Handle actions for generic property-related tool

Parameters:

• parser – argument parser used to produce args

• args – arguments to handle

• target – object on which actions should be performed

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_tags module

qvm-tags - Manage domain’s tags

qubesadmin.tools.qvm_tags.get_parser()

Return qvm-tags tool command line parser

qubesadmin.tools.qvm_tags.main(args=None, app=None)

Main routine of qvm-tags.

Parameters:

args (list) – Optional arguments to override those delivered from command line.

qubesadmin.tools.qvm_tags.mode_add(args)

Add tag

qubesadmin.tools.qvm_tags.mode_del(args)

Delete tag

qubesadmin.tools.qvm_tags.mode_query(args)

Query/list tags

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)

Bases: object

Wrapper object around qubes.storage.Volume, mainly to track the domains a volume is attached to.

qubesadmin.tools.qvm_volume.clear_volume(args)

Clear the volume data.

qubesadmin.tools.qvm_volume.config_volume(args)

Change property of selected volume

qubesadmin.tools.qvm_volume.extend_volumes(args)

Called by the parser to execute the qvm-volume extend subcommand

qubesadmin.tools.qvm_volume.get_parser()

Create argparse.ArgumentParser suitable for qvm-volume.

qubesadmin.tools.qvm_volume.import_volume(args)

Import a file into volume

qubesadmin.tools.qvm_volume.info_volume(args)

Show info about selected volume

qubesadmin.tools.qvm_volume.init_clear_parser(sub_parsers)

Add ‘clear’ action related options

qubesadmin.tools.qvm_volume.init_config_parser(sub_parsers)

Add ‘info’ action related options

qubesadmin.tools.qvm_volume.init_extend_parser(sub_parsers)

Add ‘extend’ action related options

qubesadmin.tools.qvm_volume.init_import_parser(sub_parsers)

Add ‘import’ action related options

qubesadmin.tools.qvm_volume.init_info_parser(sub_parsers)

Add ‘info’ action related options

qubesadmin.tools.qvm_volume.init_list_parser(sub_parsers)

Configures the parser for the qvm-volume list subcommand

qubesadmin.tools.qvm_volume.init_revert_parser(sub_parsers)

Add ‘revert’ action related options

qubesadmin.tools.qvm_volume.list_volumes(args)

Called by the parser to execute the qvm-volume list subcommand.

qubesadmin.tools.qvm_volume.main(args=None, app=None)

Main routine of qvm-volume.

qubesadmin.tools.qvm_volume.prepare_table(vd_list, full=False)

Converts a list of VolumeData objects to a list of tupples for the qubes.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

qubesadmin.tools.qvm_volume.revert_volume(args)

Revert volume to previous state

Module contents

Qubes’ command line tools

class qubesadmin.tools.AliasedSubParsersAction(option_strings, prog, parser_class, dest='==SUPPRESS==', required=False, help=None, metavar=None)

Bases: _SubParsersAction

SubParser with support for action aliases

add_parser(name, **kwargs)

class qubesadmin.tools.PoolsAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: QubesAction

Action for argument parser to gather multiple pools

parse_qubes_app(parser, namespace)

This method is called by qubes.tools.QubesArgumentParser after the namespace.app is instantiated. Oerwrite this method when extending qubes.tools.QubesAction to initialized values based on the namespace.app

class qubesadmin.tools.PropertyAction(option_strings, dest, *, metavar='NAME=VALUE', required=False, help='set property to a value')

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)

Bases: Action

Interface providing a convinience method to be called, after namespace.app is instantiated.

parse_qubes_app(parser, namespace)

This method is called by qubes.tools.QubesArgumentParser after the namespace.app is instantiated. Oerwrite this method when extending qubes.tools.QubesAction to initialized values based on the namespace.app

class qubesadmin.tools.QubesArgumentParser(vmname_nargs=None, show_forceroot=False, version=None, **kwargs)

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)

Runtime error, without showing usage.

Parameters:

message (str) – message to show

static get_loglevel_from_verbosity(namespace)

Return loglevel calculated from quiet and verbose arguments

parse_args(*args, **kwargs)

print_error(*args, **kwargs)

Print to sys.stderr

static set_qubes_verbosity(namespace)

Apply a verbosity setting.

This is done by configuring global logging. :param argparse.Namespace args: args as parsed by parser

class qubesadmin.tools.RunningVmNameAction(option_strings, nargs=1, dest='vmnames', help=None, **kwargs)

Bases: VmNameAction

Action for argument parser that gets a running domain from VMNAME

parse_qubes_app(parser, namespace)

Set namespace.domains to values

class qubesadmin.tools.SinglePropertyAction(option_strings, dest, *, metavar='VALUE', const=None, nargs=None, required=False, help=None)

Bases: Action

Action for argument parser that stores a property.

class qubesadmin.tools.SubParsersHelpAction(option_strings, dest='==SUPPRESS==', default='==SUPPRESS==', help=None)

Bases: _HelpAction

Print help for all options and all subparsers

class qubesadmin.tools.VMVolumeAction(help='A pool & volume id combination', required=True, **kwargs)

Bases: QubesAction

Action for argument parser that gets the :py:class:qubes.storage.Volume from a VM:VOLUME string.

parse_qubes_app(parser, namespace)

Acquire the :py:class:qubes.storage.Volume object from namespace.app.

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)

Bases: QubesAction

Action for parsing one or multiple domains from provided VMNAMEs

parse_qubes_app(parser, namespace)

Set namespace.domains to values

class qubesadmin.tools.VmNameGroup(container, required, vm_action=<class 'qubesadmin.tools.VmNameAction'>, help=None)

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)

Bases: QubesAction

Action for argument parser that gets the :py:class:qubes.storage.Volume from a POOL_NAME:VOLUME_ID string.

parse_qubes_app(parser, namespace)

Acquire the :py:class:qubes.storage.Volume object from namespace.app.

qubesadmin.tools.get_parser_for_command(command)

Get parser for given qvm-tool.

Parameters:

command (str) – command name

Return type:

argparse.ArgumentParser

Raises:

• ImportError – when command’s module is not found

• AttributeError – when parser was not found

qubesadmin.tools.print_table(table, stream=None)

Uses the unix column command to print pretty table.

Parameters:

text (str) – list of lists/sets