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.

visit_section(node)[source]

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

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.

visit_desc(node)[source]

Skips all but ‘option’ elements

visit_desc_name(node)[source]

Checks if the option is defined self.args

qubesadmin.tools.dochelpers.break_to_pdb(app, *_dummy)[source]

DEBUG

qubesadmin.tools.dochelpers.check_man_args(app, doctree, docname)[source]

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

qubesadmin.tools.dochelpers.make_rst_section(heading, char)[source]

Format a section header in rst

qubesadmin.tools.dochelpers.prepare_manpage(command)[source]

Build a man page skeleton

qubesadmin.tools.dochelpers.setup(app)[source]

Setup Sphinx extension

qubesadmin.tools.qubes_prefs module

Manipulate global properties.

qubesadmin.tools.qubes_prefs.get_parser()[source]

Prepare argument parser

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

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.

parse_qubes_app(parser, namespace)[source]

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)[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.main(args=None, app=None)[source]

Main routine of qvm-block.

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 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)[source]

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

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

get_head()[source]

Get table head data (all column heads).

get_row(vm, insertion=0)[source]

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

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)

tree_append_child(parent, level)[source]

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'>)[source]

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)[source]

Calculates the volume size in MiB

qubesadmin.tools.qvm_ls.calc_usage(vm, volume_name)[source]

Calculates the volume usage in MiB

qubesadmin.tools.qvm_ls.calc_used(vm, volume_name)[source]

Calculates the volume usage in percent

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

Create argparse.ArgumentParser suitable for qvm-ls.

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_ls.process_vm(vm)[source]

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)[source]

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)[source]

Adds a new pool

qubesadmin.tools.qvm_pool.get_parser()[source]

Creates argparse.ArgumentParser suitable for qvm-pool.

qubesadmin.tools.qvm_pool.info_pools(args)[source]

Prints info about the specified pools

qubesadmin.tools.qvm_pool.init_add_parser(sub_parsers)[source]

Adds ‘add’ action related options

qubesadmin.tools.qvm_pool.init_info_parser(sub_parsers)[source]

Adds ‘info’ action related options

qubesadmin.tools.qvm_pool.init_list_parser(sub_parsers)[source]

Adds ‘list’ action related options

qubesadmin.tools.qvm_pool.init_remove_parser(sub_parsers)[source]

Adds ‘remove’ action related options

qubesadmin.tools.qvm_pool.init_set_parser(sub_parsers)[source]

Adds ‘set’ action related options

qubesadmin.tools.qvm_pool.list_drivers(args)[source]

Lists all drivers with their options

qubesadmin.tools.qvm_pool.list_pools(args)[source]

Lists all available pools

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

Main routine of qvm-pool.

qubesadmin.tools.qvm_pool.remove_pools(args)[source]

Removes the specified pools

qubesadmin.tools.qvm_pool.set_pool(args)[source]

Modifies driver options for a pool

qubesadmin.tools.qvm_pool.uses_legacy_options(args, app)[source]

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)[source]

Return argument parser for generic property-related tool

qubesadmin.tools.qvm_prefs.main(args=None, app=None)[source]
qubesadmin.tools.qvm_prefs.process_actions(parser, args, target)[source]

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()[source]

Return qvm-tags tool command line parser

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

Main routine of qvm-tags.

Parameters:

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

qubesadmin.tools.qvm_tags.mode_add(args)[source]

Add tag

qubesadmin.tools.qvm_tags.mode_del(args)[source]

Delete tag

qubesadmin.tools.qvm_tags.mode_query(args)[source]

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)[source]

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)[source]

Clear the volume data.

qubesadmin.tools.qvm_volume.config_volume(args)[source]

Change property of selected volume

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.import_volume(args)[source]

Import a file into volume

qubesadmin.tools.qvm_volume.info_volume(args)[source]

Show info about selected 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.main(args=None, app=None)[source]

Main routine of qvm-volume.

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

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)[source]

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)[source]

Bases: _SubParsersAction

SubParser with support for action aliases

add_parser(name, **kwargs)[source]
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

parse_qubes_app(parser, namespace)[source]

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

parse_qubes_app(parser, namespace)[source]

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

static get_loglevel_from_verbosity(namespace)[source]

Return loglevel calculated from quiet and verbose arguments

parse_args(*args, **kwargs)[source]
print_error(*args, **kwargs)[source]

Print to sys.stderr

static set_qubes_verbosity(namespace)[source]

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)[source]

Bases: VmNameAction

Action for argument parser that gets a running domain from VMNAME

parse_qubes_app(parser, namespace)[source]

Set namespace.domains to values

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.

parse_qubes_app(parser, namespace)[source]

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)[source]

Bases: QubesAction

Action for parsing one or multiple domains from provided VMNAMEs

parse_qubes_app(parser, namespace)[source]

Set namespace.domains to values

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.

parse_qubes_app(parser, namespace)[source]

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

qubesadmin.tools.get_parser_for_command(command)[source]

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)[source]

Uses the unix column command to print pretty table.

Parameters:

text (str) – list of lists/sets