From 3ba9c6f8d1b1506611c1b39ec1813ac3919619a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Thu, 21 Nov 2019 18:16:33 +0100 Subject: [PATCH 1/7] doc: drop moved elsewhere components --- doc/index.rst | 2 - doc/qubes-policy.rst | 95 -------------------------------------------- 2 files changed, 97 deletions(-) delete mode 100644 doc/qubes-policy.rst diff --git a/doc/index.rst b/doc/index.rst index 2311d902..dab5662f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,8 +22,6 @@ manpages and API documentation. For primary user documentation, see qubes-exc qubes-ext qubes-log - qubes-mgmt - qubes-policy qubes-backup qubes-tools/index qubes-tests diff --git a/doc/qubes-policy.rst b/doc/qubes-policy.rst deleted file mode 100644 index abb6dc63..00000000 --- a/doc/qubes-policy.rst +++ /dev/null @@ -1,95 +0,0 @@ -:py:mod:`qubes.policy` -- Qubes RPC policy -========================================== - -Every Qubes domain can trigger various RPC services, but if such call would be -allowed depends on Qubes RPC policy (qrexec policy in short). - -Qrexec policy format --------------------- - -Policy consists of a file, which is parsed line-by-line. First matching line -is used as an action. - -Each line consist of three values separated by white characters (space(s), tab(s)): - -1. Source specification, which is one of: - - - domain name - - `$anyvm` - any domain - - `$tag:some-tag` - VM having tag `some-tag` - - `$type:vm-type` - VM of `vm-type` type, available types: - AppVM, TemplateVM, StandaloneVM, DispVM - -2. Target specification, one of: - - - domain name - - `$anyvm` - any domain, excluding dom0 - - `$tag:some-tag` - domain having tag `some-tag` - - `$type:vm-type` - domain of `vm-type` type, available types: - AppVM, TemplateVM, StandaloneVM, DispVM - - `$default` - used when caller did not specified any VM - - `$dispvm:vm-name` - _new_ Disposable VM created from AppVM `vm-name` - - `$dispvm:$tag:some-tag` - _new_ Disposable VM created from AppVM tagged with `some-tag` - - `$dispvm` - _new_ Disposable VM created from AppVM pointed by caller - property `default_dispvm`, which defaults to global property `default_dispvm` - - `$adminvm` - Admin VM aka dom0 - - Dom0 can only be matched explicitly - either as `dom0` or `$adminvm` keyword. - None of `$anyvm`, `$tag:some-tag`, `$type:AdminVM` will match. - -3. Action and optional action parameters, one of: - - - `allow` - allow the call, without further questions; optional parameters: - - - `target=` - override caller provided call target - - possible values are: domain name, `$dispvm` or `$dispvm:vm-name` - - `user=` - call the service using this user, instead of the user - pointed by target VM's `default_user` property - - `deny` - deny the call, without further questions; no optional - parameters are supported - - `ask` - ask the user for confirmation; optional parameters: - - - `target=` - override user provided call target - - `user=` - call the service using this user, instead of the user - pointed by target VM's `default_user` property - - `default_target=` - suggest this target when prompting the user for - confirmation - -Alternatively, a line may consist of a single keyword `$include:` followed by a -path. This will load a given file as its content would be in place of -`$include` line. Relative paths are resolved relative to -`/etc/qubes-rpc/policy` directory. - -Evaluating `ask` action ------------------------ - -When qrexec policy specify `ask` action, the user is asked whether the call -should be allowed or denied. In addition to that, user also need to choose -target domain. User have to choose from a set of targets specified by the -policy. Such set is calculated using the algorithm below: - -1. If `ask` action have `target=` option specified, only that target is -considered. A prompt window will allow to choose only this value and it will -also be pre-filled value. - -2. If no `target=` option is specified, all rules are evaluated to see what -target domains (for a given source domain) would result in `ask` or `allow` -action. If any of them have `target=` option set, that value is used instead of -the one specified in "target" column (for this particular line). Then the user -is presented with a confirmation dialog and an option to choose from those -domains. - -3. If `default_target=` option is set, it is used as -suggested value, otherwise no suggestion is made (regardless of calling domain -specified any target or not). - - - -Module contents ---------------- - -.. automodule:: qubespolicy - :members: - :show-inheritance: - -.. vim: ts=3 sw=3 et From 0d20639cc1b5894c9e29d0a272c05a414c8309bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Sun, 17 Mar 2019 20:06:26 +0100 Subject: [PATCH 2/7] qmemmand: separate SystemState init xc and xs to a 'init' method It prevents any connection to xen when initiallizing the class notably in doc build generation. --- qubes/qmemman/__init__.py | 4 ++++ qubes/tools/qmemmand.py | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/qubes/qmemman/__init__.py b/qubes/qmemman/__init__.py index 1c7ff780..9876db4c 100644 --- a/qubes/qmemman/__init__.py +++ b/qubes/qmemman/__init__.py @@ -57,6 +57,10 @@ class SystemState(object): self.log.debug('SystemState()') self.domdict = {} + self.xc = None + self.xs = None + + def init(self): self.xc = xen.lowlevel.xc.xc() self.xs = xen.lowlevel.xs.xs() self.BALOON_DELAY = 0.1 diff --git a/qubes/tools/qmemmand.py b/qubes/tools/qmemmand.py index 640e8051..df90ca69 100644 --- a/qubes/tools/qmemmand.py +++ b/qubes/tools/qmemmand.py @@ -276,6 +276,10 @@ def main(): log.debug('instantiating server') os.umask(0) + + # Initialize the connection to Xen and to XenStore + system_state.init() + server = socketserver.UnixStreamServer(SOCK_PATH, QMemmanReqHandler) os.umask(0o077) From b4177cf7d2c51f6c501c414f3e3c23f056b92a09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 22 Nov 2019 11:18:34 +0100 Subject: [PATCH 3/7] doc: Make PEP8 happier --- doc/skel-manpage.py | 7 ++- qubes/dochelpers.py | 102 ++++++++++++++++++++++++-------------------- 2 files changed, 60 insertions(+), 49 deletions(-) diff --git a/doc/skel-manpage.py b/doc/skel-manpage.py index c650ebba..11e9a715 100755 --- a/doc/skel-manpage.py +++ b/doc/skel-manpage.py @@ -2,6 +2,7 @@ import os import sys + sys.path.insert(0, os.path.abspath('../')) import argparse @@ -9,12 +10,14 @@ import qubes.dochelpers parser = argparse.ArgumentParser(description='prepare new manpage for command') parser.add_argument('command', metavar='COMMAND', - help='program\'s command name; this should translate to ' - 'qubes.tools.') + help='program\'s command name; this should translate to ' + 'qubes.tools.') + def main(): args = parser.parse_args() sys.stdout.write(qubes.dochelpers.prepare_manpage(args.command)) + if __name__ == '__main__': main() diff --git a/qubes/dochelpers.py b/qubes/dochelpers.py index e55f9317..ee674322 100644 --- a/qubes/dochelpers.py +++ b/qubes/dochelpers.py @@ -18,11 +18,11 @@ # License along with this library; if not, see . # -'''Documentation helpers. +"""Documentation helpers. This module contains classes and functions which help to maintain documentation, particularly our custom Sphinx extension. -''' +""" import argparse import io @@ -55,14 +55,15 @@ class GithubTicket: self.summary = data['title'] self.uri = data['html_url'] + def fetch_ticket_info(app, number): - '''Fetch info about particular trac ticket given + """Fetch info about particular trac ticket given :param app: Sphinx app object :param str number: number of the ticket, without # :rtype: mapping :raises: urllib.error.HTTPError - ''' + """ response = urllib.request.urlopen(urllib.request.Request( app.config.ticket_base_uri.format(number=number), @@ -71,8 +72,9 @@ def fetch_ticket_info(app, number): 'User-agent': __name__})) return GithubTicket(json.load(response)) + def ticket(name, rawtext, text, lineno, inliner, options=None, content=None): - '''Link to qubes ticket + """Link to qubes ticket :param str name: The role name used in the document :param str rawtext: The entire markup snippet, with role @@ -82,7 +84,7 @@ def ticket(name, rawtext, text, lineno, inliner, options=None, content=None): that called this function :param options: Directive options for customisation :param content: The directive content for customisation - ''' # pylint: disable=unused-argument + """ # pylint: disable=unused-argument if options is None: options = {} @@ -117,20 +119,23 @@ class versioncheck(docutils.nodes.warning): # pylint: disable=invalid-name pass + def visit(self, node): self.visit_admonition(node, 'version') + def depart(self, node): self.depart_admonition(node) + sphinx.locale.admonitionlabels['version'] = 'Version mismatch' class VersionCheck(docutils.parsers.rst.Directive): - '''Directive versioncheck + """Directive versioncheck Check if current version (from ``conf.py``) equals version specified as - argument. If not, generate warning.''' + argument. If not, generate warning.""" has_content = True required_arguments = 1 @@ -145,16 +150,16 @@ class VersionCheck(docutils.parsers.rst.Directive): if current == version: return [] - text = ' '.join('''This manual page was written for version **{}**, but + text = ' '.join("""This manual page was written for version **{}**, but current version at the time when this page was generated is **{}**. This may or may not mean that page is outdated or has - inconsistencies.'''.format(version, current).split()) + inconsistencies.""".format(version, current).split()) node = versioncheck(text) node['classes'] = ['admonition', 'warning'] self.state.nested_parse(docutils.statemachine.StringList([text]), - self.content_offset, node) + self.content_offset, node) return [node] @@ -168,14 +173,14 @@ def prepare_manpage(command): stream.write('.. program:: {}\n\n'.format(command)) stream.write(make_rst_section( ':program:`{}` -- {}'.format(command, parser.description), '=')) - stream.write('''.. warning:: + stream.write(""".. warning:: This page was autogenerated from command-line parser. It shouldn't be 1:1 conversion, because it would add little value. Please revise it and add more descriptive help, which normally won't fit in standard ``--help`` option. - After rewrite, please remove this admonition.\n\n''') + After rewrite, please remove this admonition.\n\n""") stream.write(make_rst_section('Synopsis', '-')) usage = ' '.join(parser.format_usage().strip().split()) @@ -189,34 +194,35 @@ def prepare_manpage(command): stream.write(make_rst_section('Options', '-')) - for action in parser._actions: # pylint: disable=protected-access + for action in parser._actions: # pylint: disable=protected-access stream.write('.. option:: ') if action.metavar: stream.write(', '.join('{}{}{}'.format( - option, - '=' if option.startswith('--') else ' ', - action.metavar) - for option in sorted(action.option_strings))) + option, + '=' if option.startswith('--') else ' ', + action.metavar) + for option in sorted(action.option_strings))) else: stream.write(', '.join(sorted(action.option_strings))) stream.write('\n\n {}\n\n'.format(action.help)) stream.write(make_rst_section('Authors', '-')) - stream.write('''\ + stream.write("""\ | Joanna Rutkowska | Rafal Wojtczuk | Marek Marczykowski | Wojtek Porczyk .. vim: ts=3 sw=3 et tw=80 -''') +""") return stream.getvalue() class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): - ''' Checks if the visited option nodes and the specified args are in sync. - ''' + """ Checks if the visited option nodes and the specified args are in sync. + """ + def __init__(self, command, args, document): assert isinstance(args, set) docutils.nodes.SparseNodeVisitor.__init__(self, document) @@ -224,14 +230,13 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): self.args = args def visit_desc(self, node): - ''' Skips all but 'option' elements ''' + """ Skips all but 'option' elements """ # pylint: disable=no-self-use if not node.get('desctype', None) == 'option': raise docutils.nodes.SkipChildren - def visit_desc_name(self, node): - ''' Checks if the option is defined `self.args` ''' + """ Checks if the option is defined `self.args` """ if not isinstance(node[0], docutils.nodes.Text): raise sphinx.errors.SphinxError('first child should be Text') @@ -243,14 +248,14 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): 'No such argument for {!r}: {!r}'.format(self.command, arg)) def check_undocumented_arguments(self, ignored_options=None): - ''' Call this to check if any undocumented arguments are left. + """ 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 :py:meth:`NodeVisitor.dispatch_departure()`) So we need to manually call this. - ''' + """ if ignored_options is None: ignored_options = set() left_over_args = self.args - ignored_options @@ -261,9 +266,9 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): - ''' Checks if the visited sub command section nodes and the specified sub + """ Checks if the visited sub command section nodes and the specified sub command args are in sync. - ''' + """ def __init__(self, command, sub_commands, document): docutils.nodes.SparseNodeVisitor.__init__(self, document) @@ -271,12 +276,12 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): self.sub_commands = sub_commands def visit_section(self, node): - ''' Checks if the visited sub-command section nodes exists and it + """ Checks if the visited sub-command section nodes exists and it options are in sync. Uses :py:class:`OptionsCheckVisitor` for checking sub-commands options - ''' + """ # pylint: disable=no-self-use title = str(node[0][0]) if title.upper() == SUBCOMMANDS_TITLE: @@ -296,10 +301,10 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): 'No such sub-command {!r}'.format(sub_cmd)) def visit_Text(self, node): - ''' If the visited text node starts with 'alias: ', all the provided + """ If the visited text node starts with 'alias: ', all the provided comma separted alias in this node, are removed from `self.sub_commands` - ''' + """ # pylint: disable=invalid-name text = str(node).strip() if text.startswith('aliases:'): @@ -308,16 +313,15 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): assert alias in self.sub_commands del self.sub_commands[alias] - def check_undocumented_sub_commands(self): - ''' Call this to check if any undocumented sub_commands are left. + """ 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 :py:meth:`NodeVisitor.dispatch_departure()`) So we need to manually call this. - ''' + """ if self.sub_commands: raise sphinx.errors.SphinxError( 'Undocumented commands for {!r}: {!r}'.format( @@ -325,9 +329,10 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): - ''' Checks if the sub-commands and options specified in the 'COMMAND' and + """ Checks if the sub-commands and options specified in the 'COMMAND' and 'OPTIONS' (case insensitve) sections in sync the command parser. - ''' + """ + def __init__(self, app, command, document): docutils.nodes.SparseNodeVisitor.__init__(self, document) try: @@ -362,16 +367,16 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): self.options.update(action.option_strings) def visit_section(self, node): - ''' If section title is OPTIONS or COMMANDS dispatch the apropriate + """ If section title is OPTIONS or COMMANDS dispatch the apropriate `NodeVisitor`. - ''' + """ if self.parser is None: return section_title = str(node[0][0]).upper() if section_title == OPTIONS_TITLE: options_visitor = OptionsCheckVisitor(self.command, self.options, - self.document) + self.document) node.walkabout(options_visitor) options_visitor.check_undocumented_arguments() elif section_title == SUBCOMMANDS_TITLE: @@ -380,10 +385,11 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): node.walkabout(sub_cmd_visitor) sub_cmd_visitor.check_undocumented_sub_commands() + def check_man_args(app, doctree, docname): - ''' Checks the manpage for undocumented or obsolete sub-commands and + """ Checks the manpage for undocumented or obsolete sub-commands and options. - ''' + """ dirname, command = os.path.split(docname) if os.path.basename(dirname) != 'manpages': return @@ -398,6 +404,7 @@ def check_man_args(app, doctree, docname): event_sig_re = re.compile(r'([a-zA-Z-:<>]+)\s*\((.*)\)') + def parse_event(env, sig, signode): # pylint: disable=unused-argument m = event_sig_re.match(sig) @@ -413,6 +420,7 @@ def parse_event(env, sig, signode): signode += plist return name + # # end of codelifting # @@ -433,17 +441,17 @@ def setup(app): 'env') app.add_config_value('break_to_pdb', False, 'env') app.add_node(versioncheck, - html=(visit, depart), - man=(visit, depart)) + html=(visit, depart), + man=(visit, depart)) app.add_directive('versioncheck', VersionCheck) fdesc = sphinx.util.docfields.GroupedField('parameter', label='Parameters', - names=['param'], can_collapse=True) + names=['param'], + can_collapse=True) app.add_object_type('event', 'event', 'pair: %s; event', parse_event, doc_field_types=[fdesc]) app.connect('doctree-resolved', break_to_pdb) app.connect('doctree-resolved', check_man_args) - # vim: ts=4 sw=4 et From be1c193e3c292e57f1bf260d43dca377d8f1a9e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 22 Nov 2019 11:28:11 +0100 Subject: [PATCH 4/7] Fix Sphinx 2 new API for Fedora 31+ --- qubes/dochelpers.py | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/qubes/dochelpers.py b/qubes/dochelpers.py index ee674322..7d8becb1 100644 --- a/qubes/dochelpers.py +++ b/qubes/dochelpers.py @@ -41,12 +41,17 @@ import sphinx import sphinx.errors import sphinx.locale import sphinx.util.docfields +from sphinx.util import logging import qubes.tools SUBCOMMANDS_TITLE = 'COMMANDS' OPTIONS_TITLE = 'OPTIONS' +try: + log = logging.getLogger(__name__) +except AttributeError: + log = None class GithubTicket: # pylint: disable=too-few-public-methods @@ -338,7 +343,13 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): try: parser = qubes.tools.get_parser_for_command(command) except ImportError: - app.warn('cannot import module for command') + msg = 'cannot import module for command' + if log: + log.warning(msg) + else: + # Handle legacy + app.warn(msg) + self.parser = None return except AttributeError: @@ -394,7 +405,13 @@ def check_man_args(app, doctree, docname): if os.path.basename(dirname) != 'manpages': return - app.info('Checking arguments for {!r}'.format(command)) + msg = 'Checking arguments for {!r}'.format(command) + if log: + log.info(msg) + else: + # Handle legacy + app.info(msg) + doctree.walk(ManpageCheckVisitor(app, command, doctree)) From 3761982d90277c86e5257f29bc2c27277f4c7341 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 22 Nov 2019 14:47:23 +0100 Subject: [PATCH 5/7] spec: fix missing dependency --- rpm_spec/core-dom0.spec.in | 1 + 1 file changed, 1 insertion(+) diff --git a/rpm_spec/core-dom0.spec.in b/rpm_spec/core-dom0.spec.in index c1d2ec93..76ade37e 100644 --- a/rpm_spec/core-dom0.spec.in +++ b/rpm_spec/core-dom0.spec.in @@ -57,6 +57,7 @@ BuildRequires: python3-lxml BuildRequires: libvirt-python3 BuildRequires: python3-dbus BuildRequires: python3-PyYAML +BuildRequires: python3-xen Requires(post): systemd-units Requires(preun): systemd-units From 6624ed338367fdfde43841f34b3655308fc07eaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 22 Nov 2019 14:55:09 +0100 Subject: [PATCH 6/7] cleanup-dispvms: fix python shebang --- linux/aux-tools/cleanup-dispvms | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/aux-tools/cleanup-dispvms b/linux/aux-tools/cleanup-dispvms index 3c42781a..baceac25 100755 --- a/linux/aux-tools/cleanup-dispvms +++ b/linux/aux-tools/cleanup-dispvms @@ -1,4 +1,4 @@ -#!/usr/bin/python +#!/usr/bin/python3 from qubesadmin import Qubes From bc723b87555fd109741f653964d464cc66a2eac1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 22 Nov 2019 14:54:53 +0100 Subject: [PATCH 7/7] doc: remove useless _static generated by sphinx --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index 70ec5821..2f3e8abe 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -166,4 +166,5 @@ autoxml.rst: ../relaxng/qubes.rng example.xml .PHONY: install install: man mkdir -p $(DESTDIR)/usr/share/man/man1 + rm -rf $(BUILDDIR)/man/_static cp $(BUILDDIR)/man/* $(DESTDIR)/usr/share/man/man1/