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:
docutils.nodes.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:
docutils.nodes.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:
docutils.nodes.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¶
qvm-backup tool
qubesadmin.tools.qvm_backup_restore module¶
Console frontend for backup restore code
-
qubesadmin.tools.qvm_backup_restore.
handle_broken
(app, args, restore_info)[source]¶ Display information about problems with VMs selected for resetore
qubesadmin.tools.qvm_check module¶
Exits sucessfull if the provided domains exists, else returns failure
qubesadmin.tools.qvm_clone module¶
Clone a domain
qubesadmin.tools.qvm_create module¶
qvm-create tool
qubesadmin.tools.qvm_device module¶
Qubes volume and block device managment
-
class
qubesadmin.tools.qvm_device.
DeviceAction
(help='A backend & device id combination', required=True, allow_unknown=False, **kwargs)[source]¶ Bases:
qubesadmin.tools.QubesAction
Action for argument parser that gets the :py:class:
qubesadmin.device.DeviceAssignment
from a BACKEND: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 extendingqubes.tools.QubesAction
to initialized values based on the namespace.app
-
-
class
qubesadmin.tools.qvm_device.
Line
(device: qubesadmin.devices.DeviceInfo, attached_to=None)[source]¶ Bases:
object
Helper class to hold single device info for listing
-
assignments
¶ list of frontends the device is assigned to
-
-
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.
init_list_parser
(sub_parsers)[source]¶ Configures the parser for the qvm-devices list subcommand
-
qubesadmin.tools.qvm_device.
list_devices
(args)[source]¶ Called by the parser to execute the qubes-devices list subcommand.
-
qubesadmin.tools.qvm_device.
prepare_table
(dev_list)[source]¶ Converts a list of
qubes.devices.DeviceInfo
objects to a list of tupples for thequbes.tools.print_table()
.If qvm-devices is running in a TTY, it will ommit duplicate data.
Parameters: dev_list (iterable) – List of qubes.devices.DeviceInfo
objects.Returns: list of tupples
qubesadmin.tools.qvm_features module¶
qvm-features - Manage domain’s features
qubesadmin.tools.qvm_firewall module¶
qvm-firewall tool
-
class
qubesadmin.tools.qvm_firewall.
RuleAction
(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶ Bases:
argparse.Action
- Parser action for a single firewall rule. It accept syntax:
- <action> [<dsthost> [<proto> [<dstports>|<icmptype>]]]
- action=<action> [specialtarget=dns] [dsthost=<dsthost>] [proto=<proto>] [dstports=<dstports>] [icmptype=<icmptype>]
Or a mix of them.
-
qubesadmin.tools.qvm_firewall.
rules_del
(vm, args)[source]¶ Delete a rule according to args.rule/args.rule_no
qubesadmin.tools.qvm_kill module¶
qvm-kill - forceful shutdown
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: -
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:
-
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-USED': Column(head='PRIV-USED'), 'ROOT-CURR': Column(head='ROOT-CURR'), 'ROOT-MAX': Column(head='ROOT-MAX'), 'ROOT-USED': Column(head='ROOT-USED'), 'STATE': Column(head='STATE')}¶ collection of all columns
-
-
class
qubesadmin.tools.qvm_ls.
FlagsColumn
[source]¶ Bases:
qubesadmin.tools.qvm_ls.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:
qubesadmin.tools.qvm_ls.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)[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'), '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_pause module¶
qvm-pause - Pause a domain
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¶
Remove domains from the system
qubesadmin.tools.qvm_run module¶
qvm-run tool
qubesadmin.tools.qvm_service module¶
qvm-service - Manage domain’s services
qubesadmin.tools.qvm_shutdown module¶
Shutdown a qube
qubesadmin.tools.qvm_start module¶
qvm-start - start a domain
-
class
qubesadmin.tools.qvm_start.
DriveAction
(option_strings, dest='drive', prefix='cdrom:', metavar='IMAGE', required=False, help='Attach drive')[source]¶ Bases:
argparse.Action
Action for argument parser that stores drive image path.
-
qubesadmin.tools.qvm_start.
get_drive_assignment
(app, drive_str)[source]¶ Prepare
qubesadmin.devices.DeviceAssignment
object for a given drive.If running in dom0, it will also take care about creating appropriate loop device (if necessary). Otherwise, only existing block devices are supported.
Parameters: - app – Qubes() instance
- drive_str – drive argument
Returns: DeviceAssignment matching drive_str
qubesadmin.tools.qvm_start_daemon module¶
GUI/AUDIO daemon launcher tool
-
class
qubesadmin.tools.qvm_start_daemon.
DAEMONLauncher
(app: qubesadmin.app.QubesBase, vm_names=None, kde=False)[source]¶ Bases:
object
Launch GUI/AUDIO daemon for VMs
-
cleanup_guid
(xid)[source]¶ Clean up after qubes-guid. Removes the auto-generated configuration file, if any.
-
on_connection_established
(_subject, _event, **_kwargs)[source]¶ Handler of ‘connection-established’ event, used to launch GUI/AUDIO daemon for domains started before this tool.
-
on_domain_spawn
(vm, _event, **kwargs)[source]¶ Handler of ‘domain-spawn’ event, starts GUI daemon for stubdomain
-
on_domain_start
(vm, _event, **kwargs)[source]¶ Handler of ‘domain-start’ event, starts GUI/AUDIO daemon for actual VM
-
send_monitor_layout
(vm, layout=None, startup=False)[source]¶ Send monitor layout to a given VM
This function is a coroutine.
Parameters: - vm – VM to which send monitor layout
- layout – monitor layout to send; if None, fetch it from local X server.
- startup –
Returns: None
-
start_audio
(vm)[source]¶ Start AUDIO daemon regardless of start event.
This function is a coroutine.
Parameters: vm – VM for which AUDIO daemon should be started
-
start_audio_for_vm
(vm)[source]¶ Start AUDIO daemon (pacat-simple-vchan) connected directly to a VM
This function is a coroutine.
Parameters: vm – VM for which start AUDIO daemon
-
start_gui
(vm, force_stubdom=False, monitor_layout=None)[source]¶ Start GUI daemon regardless of start event.
This function is a coroutine.
Parameters: - vm – VM for which GUI daemon should be started
- force_stubdom – Force GUI daemon for stubdomain, even if the one for target AppVM is running.
- monitor_layout – monitor layout configuration
-
start_gui_for_stubdomain
(vm, force=False)[source]¶ Start GUI daemon (qubes-guid) connected to a stubdomain
This function is a coroutine.
-
-
class
qubesadmin.tools.qvm_start_daemon.
KeyboardLayout
(binary_string)[source]¶ Bases:
object
Class to store and parse X Keyboard layout data
-
class
qubesadmin.tools.qvm_start_daemon.
XWatcher
(conn, app)[source]¶ Bases:
object
Watch and react for X events related to the keyboard layout changes.
-
qubesadmin.tools.qvm_start_daemon.
escape_config_string
(value)[source]¶ Convert a string to libconfig format.
Format specification: http://www.hyperrealm.com/libconfig/libconfig_manual.html#String-Values
See dump_string() for python-libconf: https://github.com/Grk0/python-libconf/blob/master/libconf.py
-
qubesadmin.tools.qvm_start_daemon.
get_monitor_layout
()[source]¶ Get list of monitors and their size/position
qubesadmin.tools.qvm_tags module¶
qvm-features - Manage domain’s tags
Return qvm-tags tool command line parser
Main routine of qvm-tags.
Parameters: args (list) – Optional arguments to override those delivered from command line.
Add tag
Delete tag
Query/list tags
qubesadmin.tools.qvm_template module¶
qubesadmin.tools.qvm_template_postprocess module¶
Tool for importing rpm-installed template
-
qubesadmin.tools.qvm_template_postprocess.
call_postinstall_service
(vm)[source]¶ Call qubes.PostInstall service
And adjust related settings (netvm, features).
-
qubesadmin.tools.qvm_template_postprocess.
get_root_img_size
(source_dir)[source]¶ Extract size of root.img to be imported
Import appmenus settings into VM object (later: GUI VM)
Parameters: - vm – QubesVM object of just imported template
- source_dir – directory with source files
- skip_generate – do not generate actual menu entries, only set item lists
-
qubesadmin.tools.qvm_template_postprocess.
import_root_img
(vm, source_dir)[source]¶ Import root.img into VM object
-
qubesadmin.tools.qvm_template_postprocess.
import_template_config
(args, conf_path, vm)[source]¶ Parse template.conf and apply its content to the just installed TemplateVM
Parameters: - args – arguments for qvm-template-postprocess (used for –allow-pv option and possibly some other in the future)
- conf_path – path to the template.conf
- vm – Template to operate on
Returns:
-
qubesadmin.tools.qvm_template_postprocess.
main
(args=None, app=None)[source]¶ Main function of qvm-template-postprocess
-
qubesadmin.tools.qvm_template_postprocess.
parse_template_config
(path)[source]¶ Parse template.conf from template package. (KEY=VALUE format)
qubesadmin.tools.qvm_unpause module¶
qvm-unpause - Unpause a domain
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-block extend subcommand
-
qubesadmin.tools.qvm_volume.
get_parser
()[source]¶ Create
argparse.ArgumentParser
suitable for qvm-volume.
-
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-block 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
- vd_list (list) – List of
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:
argparse._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:
qubesadmin.tools.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 extendingqubes.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:
argparse.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:
argparse.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 extendingqubes.tools.QubesAction
to initialized values based on the namespace.app
-
-
class
qubesadmin.tools.
QubesArgumentParser
(vmname_nargs=None, show_forceroot=False, **kwargs)[source]¶ Bases:
argparse.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
-
error_runtime
(message, exit_code=1)[source]¶ Runtime error, without showing usage.
Parameters: message (str) – message to show
- vmname_nargs (mixed) – The number of
-
class
qubesadmin.tools.
RunningVmNameAction
(option_strings, nargs=1, dest='vmnames', help=None, **kwargs)[source]¶ Bases:
qubesadmin.tools.VmNameAction
Action for argument parser that gets a running domain from VMNAME
-
parse_qubes_app
(parser, namespace)[source]¶ This method is called by
qubes.tools.QubesArgumentParser
after the namespace.app is instantiated. Oerwrite this method when extendingqubes.tools.QubesAction
to initialized values based on the namespace.app
-
-
class
qubesadmin.tools.
SinglePropertyAction
(option_strings, dest, metavar='VALUE', const=None, nargs=None, required=False, help=None)[source]¶ Bases:
argparse.Action
Action for argument parser that stores a property.
-
class
qubesadmin.tools.
SubParsersHelpAction
(option_strings, dest='==SUPPRESS==', default='==SUPPRESS==', help=None)[source]¶ Bases:
argparse._HelpAction
Print help for all options and all subparsers
-
class
qubesadmin.tools.
VMVolumeAction
(help='A pool & volume id combination', required=True, **kwargs)[source]¶ Bases:
qubesadmin.tools.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:
qubesadmin.tools.QubesAction
Action for parsing one ore multiple domains from provided VMNAMEs
-
parse_qubes_app
(parser, namespace)[source]¶ This method is called by
qubes.tools.QubesArgumentParser
after the namespace.app is instantiated. Oerwrite this method when extendingqubes.tools.QubesAction
to initialized values based on the namespace.app
-
-
class
qubesadmin.tools.
VmNameGroup
(container, required, vm_action=<class 'qubesadmin.tools.VmNameAction'>, help=None)[source]¶ Bases:
argparse._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:
qubesadmin.tools.QubesAction
Action for argument parser that gets the :py:class:
qubes.storage.Volume
from a POOL_NAME:VOLUME_ID string.
-
qubesadmin.tools.
get_parser_for_command
(command)[source]¶ Get parser for given qvm-tool.
Parameters: command (str) – command name
Return type: Raises: - ImportError – when command’s module is not found
- AttributeError – when parser was not found