qubes-tools

My versions and modifications of the original Qubes OS CLI tools.

qvm-ls rewrite

The current qvm-ls implementation is a comprehensive Python script with many features and complex logic. The goal is to rewrite it in a more concise and ergonomic way while maintaining core functionality.

goals / approach

1. Ergonomics

   • UI

     Original qvm-ls is unwieldy, it needs autocompletion to be remotely convenient. This version is trying to make it convenient and quick to type.

     Command itself shall be short. All flags must have a short version. Flag grouping (e.g. -dvt instead of -d -v -t) shall be allowed for all flags with no arguments and in a limited fashion for flags with arguments (flag with an argument can be last in a group)

     I choose to disregard the convention and won't use qvm- prefix. The command shall be just qls.

   • UX / behaviour

     Original qvm-ls doesn't support certain features too well - mainly tree mode. This vershion shall support at least two tree modes (network tree, inheritance tree (template -> appvm -> dispvms)). Other kinds of "trees" may be added, like audiovm tree, guivm tree, etc. Maybe even overall dependency graph that creates a graph of all dependencies, but that should rather be a separate module or function for use in other programs.

     All modes that result in useful output shall take qube names as input. With tree modes specifically, giving a name to the tree mode should return path to the given qube and the tree structure that originates from the given qube.

     Maybe when taking qube name in tree mode, be able to take in a path as well (e.g. in network tree mode sys-net/sys-firewall)? This is very cool but not very useful as duplicate qube names aren't allowed.

     Another problem with the original qvm-ls is the overly verbose output that rarely (perhaps never?) fits 80 column width. In this version I selectively drop certain fields from output formats. Notably, I get rid of: - State column: if user needs specific state, they are probably going to use appropriate flag, i.e. --running, --halted, or --paused. Otherwise I assume that user doesn't care about domains' state. On the other hand, I'm not sure yet whether I should handle multiple state flags at once or not. - Class column: in my experience user is able to remember the class of their qubes (at least class of the qubes they use often); additionally, this information is not central to the task of most formats.

     In addition to that, by default it only displays qube names and nothing else. Mostly because it makes qls similar to the oh-so-familiar ls.

     Thus, we have a well-behaved cli tool. Quick to type, consice output by default fits even smallest of terminal windows, and predefined formats only print information corresponding to their name - kernel only prints qube name, kernel in use, and kernelopts, network only prints qube name, netvm, address, etc.

   • Output

     As a CLI tool, this program must be script-friendly. Original tool supports --raw-list and --raw-data flags. This tool should also support at least yaml output and possibly json and dotty formats.

2. Code quality

   • Concise.

     Avoid redundancy, avoid unnecessary elements like the spinner.

   • Consistent.

     Certain functions of the original are clearly tacked onto the existing code or don't handle their data too well. I hope to fix this.

architechture

Data gathering logic shall be separate from data-handling and output logic.

Data gathering logic shall be easy to read and maintain. This is the core of this program. No unnecessary hiding under functions.

Output logic shall be modular and easily extendable.

status

Currently I have a basic version that doesn't process any flags. It only accepts qube names as input or prints all qubes when no input is provided.

dev notes

As much as QubesArgumentParser is convenient, I'm not sure if I should use it as it intoduces 2 flags I don't want to have and 2 flags I don't know what to do with yet.

• --all - literally useless. this is the default behaviour. to disable it, use other flags and/or input to filter the output. I want it to be at least somewhat compatible; even if this flag is not implemented program should at least silently ignore attempts to use it.
• --exclude - may be used by somebody somewhere, but I'm not sure if I should keep it. Grep is installed pretty much everywhere, and people should pipe into it if they really need to exclude.
• --verbose - this command lists domains. It's logic is simple. Not sure what can be verbose about, maybe some debug messages, but only in far future if codebase gets much larger.
• --quiet - This could be useful for checking if domain exists without printing anything. Is a keeper.

Another problematic flag is --version - it prints qubesadmin version, while my software isn't technically part ot qubesadmin. I need to set up more useful version printout for a release.

pending modifications / rewrites

• qvm-start and qvm-shutdown capable of starting up / shutting down multiple qubes at once even if they are related, e.g. qvm-shutdown sys-net sys-firewall sys-whonix won't fail.
• well-behaved qubes-vm-update: comprehensible forced updates (original is very confusing around --force-update and --force-upgrade, they aren't what they seem to be); not failing if multiple domains have the same devices attached to them; readable output by default; output to a qube, not dom0; either not printing progress at all, or printing it in a way that won't break if I resize the terminal window or accidentally touch the keyboard.
• allow qvm-device commands to not throw an error when trying to assign already assigned device.