-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On Thu, Jan 19, 2023 at 07:12:32AM +0100, jmake2 via qubes-devel wrote: > Proposal 2: Make Qubes OS tools (qvm- and qubes-) consistent with flags and > other arguments > ---------------------------------------------------------------------------------- > > There are a room of improvements for qvm- and qubes- tools about what > arguments do they support, how they react to them, how consistent the syntax > of calling is across different tools. > > Some proposals to discuss: > > > * All tools must support --help (and preferably -h) arguments. > And nothing should happen in the system if user calls any Qubes OS tool this > argument. > Currently some tools run something and die with python exception after being > called with `--help`. > Note: almost all qvm- tools already do support those, so probably there was a > plan so already.
Yes, that (theoretically) should be the case already. Which of them don't? > * All tools are advised to support --verbose and --quite arguments (including > -v and -q). > Even if this arguments does not change the behavior of the tool at all at > this moment, it can be used in the future.. > Note: almost all qvm- tools already do support those, so probably there was a > plan so already. Same question as above. > * All tools that produce output should support --raw-data attribute for > machine-readable format or some alternative. > Tools, like `qvm-block`, `qvm-pool` and others should also support it. It not always makes sense, but indeed the above examples are helpful. > * When --raw argument is used the output should have no header for tables > (output target should be irrelevant) > E.g. currently `qvm-pool` always outputs header line whilst `qvm-device` > outputs header depending on output target: terminal and pipe act differently. > > > * Approach for delimiter of fields (columns) should be the same for all tools. > Currently '|' is used as a delimiter for `qvm-ls --raw-data`. > qvm-firewall has different type of raw output format. - --raw, as the name suggests, shows actual format it speaks with: https://www.qubes-os.org/doc/vm-interface/#firewall-rules-in-4x > This should should be discussed. Maybe in some outputs, like for `qvm-pci` > the device names can already contain '|' char, cannot they? PCI device description theoretically can include any of those, but it seems '|' (currently) isn't used in any device description: [marmarek@dom0 ~]$ grep '|' /usr/share/hwdata/pci.ids [marmarek@dom0 ~]$ So, we can enforce it still being the case - and for example remove '|' if ever found (which would not affect any devices for now). For block devices, '|' is explicitly not allowed (only alhanumeric + ()+,-.:=_/ and a space are allowed). > I see three options: > 1) Fix delimiter as '|' and sanitize all strings with '|' by either escaping > them (e.g. with slash or another '|') or dropping it (ugly). The details > should be added to the docs. This format should be easy to parse, escaping like \| or || may not be so. But fortunately, we don't need to worry about it :) > 2) Provide --raw-delimiter= argument that allows to set delimiter. The > drawback is that caller knows nothing in advance about the chars that are > going to be used. All he can is to check that everything is OK by counting > the delimiters. Escaping of delimiter is still an option in this case. > 3) Fix delimiter to something really unique and use some new --raw-output > argument for all tools, keeping existing --raw-data as a legacy option for > compatibility. Downsides are obvious - another arg, not obvious what a better > delimiter should be. > > > * The order of arguments should be strict and consistent. Currently some > tools allow moving arguments before or after the first standalone parameters, > some do not (as they should). Can you provide specific examples? One is probably qvm-device (and related qvm-pci, qvm-block, qvm-usb etc), where you have arguments to specific actions, not a command as a whole. That's intentional, as 'qvm-device usb attach' is the same as 'qvm-usb attach', so options are for the 'attach' part not 'qvm-device' nor 'usb' part (the former isn't even visible if called as qvm-usb). > * Each tool should provide some information about arguments without actual > qubes name being required. > E.g. `qvm-prefs --help-properties` requires VMNAME and the lists properties > help only for the qube. There is no way to list all properties for user nor > get them from scripts, because dom0 has only limited of properties and names > of other qubes can be different on any Qubes OS instance. I think in this > case VMNAME should be optional, without it the tool should output all > possible properties. The issue here is that different VM types may not only different allowed properties, but even different meanings of the same property. See for example 'template' property for AppVM and DispVM. We can probably collect them for all classes and then annotate differences, but I'm not sure how helpful that would be. > * Make the format of arguments providing lists consistent across tools. > E.g. `qvm-ls` has `--tags` with list separated with spaces, not consistent > with --fields and other cases with comma separation. Why not commas? Theoretically it would allow using tags with arbitrary names, including comas. But we don't allow them anyway, so yes, can be comas. Any other places where you found it inconsistent? > * Make tools faster with output, if possible. > E.g. `qvm-volume list` takes ten times more time than `lvs` to provide > similar output for some reason. Up to several seconds in my case. It slows > down every automation process that uses these tools. We did some optimization for qvm-ls before, I guess it's time for qvm-volume now. Thanks for all the comments! - -- Best Regards, Marek Marczykowski-Górecki Invisible Things Lab -----BEGIN PGP SIGNATURE----- iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmPPuJYACgkQ24/THMrX 1ywItQf/cc7bJ4RaZR1N6x+hKtysdWGH8Oei2G1vZypYIePtUIOC+kYxdsykVb6Z g2QNN2MO8Av1Dipumtk6OU6lPQWjiGnyyTR9IdvY7PfZjEcPS3XcldVo6To76xzd 7QkE3RZcRbA53fTqc0UJHp5QuxZqP20G+irqSUYg6yrI+1bgCdu3xsddai3h+hpk KqPyWCze2Bwp11sIQWHLcgT4GgNJvQ/jUUhnh3SrGOfeWAXQ1O/K6K1xbSM5iwhq c3dfL2zUL2LFGyP6v6MNNbsrrUKBHboV7XsJkgWV7A78yVI1ew7G2wnWOs8hlspw LyenXMB0sOVVlH7KAKikOM1NL+yFdg== =WorB -----END PGP SIGNATURE----- -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/Y8%2B4lpaBKOSBdb1G%40mail-itl.
