From b2a70f3794673b8f8975b2b3d921bc8ac5d9b029 Mon Sep 17 00:00:00 2001 From: Peter Gerber Date: Thu, 3 May 2018 00:57:21 +0200 Subject: [PATCH] tools/qvm-firewall: improve manpage and --help output --- doc/manpages/qvm-firewall.rst | 22 ++++++++++++---------- qubesadmin/tools/qvm_firewall.py | 16 ++++++++-------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/doc/manpages/qvm-firewall.rst b/doc/manpages/qvm-firewall.rst index 470d61e..00bdd30 100644 --- a/doc/manpages/qvm-firewall.rst +++ b/doc/manpages/qvm-firewall.rst @@ -31,11 +31,11 @@ Options .. option:: --reload, -r - force reloading rules even when unchanged + force reload of rules even when unchanged .. option:: --raw - Print raw rules when listing + in combination with :option:`--list`, print raw rules Actions description @@ -45,7 +45,8 @@ Available actions: * add - add specified rule. See `Rule syntax` section below. -* del - delete specified rule. Can be selected either by rule number using :option:`--rule-no`, or specifying rule itself. +* del - delete specified rule. The rule to remove can be selected either by rule number using :option:`--rule-no` + or by specifying the rule itself using the same syntax used for adding it. * list - list all the rules for a given VM. @@ -59,8 +60,8 @@ A single rule is built from: - action - either ``drop`` or ``accept`` - zero or more matches -Selected action is applied on given packet when all specified matches do match, -further rules are not evaluated. If none of the rules match, default action +Selected action is applied to packets when all specified matches match, +further rules are not evaluated. If none of the rules match, the default action (``policy``) is applied. Supported matches: @@ -76,9 +77,9 @@ Supported matches: - ``proto`` - specific IP protocol. Supported values: ``tcp``, ``udp``, ``icmp``. - - ``dstports`` - destination port or ports range. Can be either a single port, + - ``dstports`` - destination port or ports range. Can be either a single port or a range separated by ``-``. Valid only together with ``proto=udp`` or - ``proto=tcp``. + ``proto=tcp``. - ``icmptype`` - ICMP message type, specified as numeric value. Valid only together with ``proto=icmp``. @@ -86,9 +87,10 @@ Supported matches: - ``specialtarget`` - predefined target. Currently the only supported value is ``dns``. This can be combined with other matches to narrow it down. - - ``expire`` - rule matches only until specified time and then is automatically - removed. The time can be given either as number of seconds since 1/1/1970, or - ``+seconds`` as a relative time (``+300`` means 5 minutes from now). + - ``expire`` - the rule matches only until the specified time and is then + automatically removed. The time can be given either as number of seconds + since 1/1/1970 or as ``+seconds``, a relative time (``+300`` means 5 + minutes from now). Authors ------- diff --git a/qubesadmin/tools/qvm_firewall.py b/qubesadmin/tools/qvm_firewall.py index 5dda174..b10974c 100644 --- a/qubesadmin/tools/qvm_firewall.py +++ b/qubesadmin/tools/qvm_firewall.py @@ -87,7 +87,7 @@ And as keyword arguments: Both formats, positional and keyword arguments, can be used interchangeably. -Available rules: +Available matches: action: accept or drop dst4 synonym for dsthost dst6 synonym for dsthost @@ -101,9 +101,9 @@ Available rules: specialtarget only the value dns is currently supported, it matches the configured dns servers of a VM - expire a rule is automatically removed at given time, given as - seconds since 1/1/1970, or +seconds (e.g. +300 for rule - expire in 5 minutes) + expire the rule is automatically removed at the time given as + seconds since 1/1/1970, or +seconds (e.g. +300 for a rule + to expire in 5 minutes) """ parser = qubesadmin.tools.QubesArgumentParser(vmname_nargs=1, epilog=epilog, @@ -113,20 +113,20 @@ action = parser.add_subparsers(dest='command', help='action to perform') action_add = action.add_parser('add', help='add rule') action_add.add_argument('--before', type=int, default=None, - help='Add rule before rule with given number, instead of at the end') -action_add.add_argument('rule', nargs='+', action=RuleAction, + help='Add rule before rule with given number instead at the end') +action_add.add_argument('rule', metavar='match', nargs='+', action=RuleAction, help='rule description') action_del = action.add_parser('del', help='remove rule') action_del.add_argument('--rule-no', dest='rule_no', type=int, action='store', help='rule number') -action_del.add_argument('rule', nargs='*', action=RuleAction, +action_del.add_argument('rule', metavar='match', nargs='*', action=RuleAction, help='rule to be removed') action_list = action.add_parser('list', help='list rules') parser.add_argument('--reload', '-r', action='store_true', - help='force reloading rules even when unchanged') + help='force reload of rules even when unchanged') parser.add_argument('--raw', action='store_true', help='output rules as raw strings, instead of nice table')