ferroin / fvirt Goto Github PK

A lightweight CLI frontend for libvirt

License: Other

Ruby 0.02% Python 96.21% Jinja 3.77%

fvirt's Introduction

fvirt - A command-line frontend for libvirt.

fvirt is a command-line frontend for libvirt that is intended to fill a similar role to the virsh frontend, but be more human-friendly and require less scripting to cover some very common use cases.

It also includes enhanced Python bindings for the libvirt API that wrap the low-level official bindings in a more Pythonic manner, making it nicer to work with libvirt from Python.

What does it do?

fvirt CLI

The fvirt CLI tool can:

List libvirt objects in much greater detail than virsh, with configurable columns and color highlighting of some values. For example, when listing domains, it can include everything that virsh list does, as well as extra info like the generation ID, the OS type, the CPU architecture, and the domain ‘title’.
Perform most common lifecycle operations on libvirt objects, including defining, starting, stopping, and undefining them.
Use a custom timeout to wait for domains to shut down. This cleanly encapsulates a relatively common use case which requires scripting to work with virsh, allowing for much simpler scripts.
Modify libvirt object XML using XSLT documents. This allows complex programmatic editing of domain configuration without needing complex scripting to extract the XML, process it, and then feed it back in to libvirt to redefine the object.
Match objects to operate on using XPath expressions and Python regexes. Special options are provided to simplify matching on commonly used properties, such as domain architecture or storage pool type. This matching works with a significant majority of commands provided by fvirt, allowing you to easily operate on groups of objects in bulk.
Generate object configurations from relatively simple YAML or JSON templates describing the object properties.
Still interoperate cleanly with virsh. fvirt stores no state client-side, so there’s nothing to get out of sync relative to what virsh would see or operate on. This means you can use fvirt as your primary frontend for libvirt, but still pop out to virsh when you need to do something fvirt doesn’t support without having to worry about it possibly causing fvirt to stop working.

fvirt.libvirt

The libvirt bindings included with fvirt provide a number of enhancements over the official bindings for Python, including:

Hypervisor connections support the context manager protocol.
Hypervisor objects provide iterator and mapping access to objects like domains and storage pools, including reference-counted automatic connection management.
Storage pools provide iterator and mapping access to their volumes.
Object states are enumerables (like they are in the C API) instead of a somewhat opaque list of integer constants (like they are in libvirt-python).
Object XML is directly accessible as lxml Element objects.
Things that should logically return an empty sequence when nothing is matched usually do so, in contrast to libvirt-python often returning None instead.
libvirt URIs are objects that can be easily modified to change things like the driver or host, as opposed to being strings you have to manipulate with regexes.
Many common properties of objects are accessible using regular attribute access instead of requiring either method calls or manual lookup in the object’s XML config. This includes writability for many of these properties (though this currently does not work for transient objects).

What doesn’t it do?

fvirt is designed first and foremost as a lightweight frontend for libvirt. libvirt provides a huge amount of functionality, much of which is actually never used by most users. fvirt does not support a lot of that less commonly used functionality, both because it’s a potential source of confusion for some users, and because it makes fvirt itself eaasier to maintain and more robust.

Currently, fvirt and fvirt.libvirt also do not support working with most libvirt objects other than domains, storage pools, and volumes. This is because that functionality is what I specifically needed for my own usage, thus it was the first thing I implemented. I plan to expand this further to at least include netowrks and network interfaces, but it’s not a priority at the moment.

Installation

fvirt is packaged on the Python Package Index with the package name fvirt. It can be easily installed using any Python packag emanagement tool that works with pypi. As usual with Python packages, use of a virtual environment is highly recommended.

The actual CLI tool is installed as a script with the name fvirt.

fvirt requires Python 3.11 or newer, and installation will also usually require the tools needed to build the libvirt-python package.

Contributing

fvirt's dependencies are managed using Poetry. Assuming you have Poetry installed and have cloned the repository, you can set up almost everything that’s needed for development by running poetry install --all-extras

In addition to the Python dependencies, a number of tests in our test suite require additional tooling, specifically a usable local install of libvirt (including virtqemud) and a working install of QEMU’s full system emulation tooling. Full details can be found in the README.md file in the tests directory of the repository.

Licensing

fvirt is licensed under a modified version of the MIT license commonly known as the ‘MIT +no-false-attribs license'. This license is a free software license and is GPL compatible, but is not formally FSF or OSI approved.

fvirt's People

Contributors

Watchers

fvirt's Issues

Add simpler alternative to XSLT for bulk modification of object configuration.

XSLT is really powerful, but it’s also really complicated, especially for large documents with complex structure such as libvirt domains.

fvirt ideally should provide some way to more easily manipulate object XML.

Consolidate code for printing operational summaries for the CLI.

Most commands will provide a summary at the end of a run indicating how many operations succeeded, how many failed, and how many resulted in other states.

Currently, this code is duplicated throughout the commands that use it.

Instead, it should be centralized in one place (probably under a new module in fvirt.util) and then called from each of the commands that uses it.

Add command to upload data to volume.

Command should be invoked as fvirt volume upload.

Will not support streaming from stdin and should size-check the file being uploaded. Possibly support a --resize option to auto-resize the volume to match the size of the uploaded image. Should automatically support sparse uploads (possibly only support sparse uploads?).

Add command to download data from volume.

Command should be invoked as fvirt volume download

Will not support direct output to stdout. Should support sparse downloads (possibly only support sparse downloads).

Add progress info for volume upload/download commands.

At minimum a rough percentage estimate should be provided. Ideally we should also provide info about effective transfer rate.

Add support for manipulating libvirt secrets.

We already support referencing them in a couple of places, so we should support management too.

Add option to connect to domain console immediately after starting a domain.

This is surprisingly useful functionality to help ensure that early console messages are not lost.

Add command to create domain from template.

Command should be invoked as fvirt domain new.

Internally, this should use a Jinja2 template together with click prompting to request information from the user to fill out individual properties. Support should also exist for setting properties via the command line. Custom templates should be supported.

Improve error handling to better differentiate libvirt errors.

In most places where we catch libvirt errors, we blindly assume a certain failure case that triggered the error instead of properly investigating what happened. We should instead be checking what, exactly, went wrong so that we can raise an appropriate error instead.

Domain create command appears to not be working correctly.

Not sure if it’s a failure in how it is invoking the operation, or in the code that’s checking the result.

Add commands to manipulate domain parameters for live transient domains.

Should be easy to add, and we currently have no way to do it from the CLI.

Provide better handling of storage pool hosts and devices.

Depending on the type and possibly format of a storage pool, it may have more than one associated host or device. We should provide read-access to these properties as lists of entries instead of single entries to properly accommodate this case.

Add command to create volume from template.

Command should be invoked as fvirt volume new.

Add support for hypervisor URI aliases.

Libvirt supports aliases for hypervisor URIs to simplify access of commonly reused URIs. We should support this as well.

Add command to create transient storage pools.

Command should be invoked as fvirt pool create and should follow the syntax used by fvirt domain create.

Accept mappings instead of models for `new_config` methods.

This would greatly simplify usage of the methods.

The models should still be used internally to validate the mappings that are passed in.

Add workflow to automate publishing releases to PyPI.

Should be triggered on the GitHub release being published.

Add domain power management commands.

To allow guest-mediated suspend/resume functionality triggered from the host.

Add proper live testing for domains.

Should likely use qemu:///embed URL for connection. Will need some baseline test image to work with for domains so that they can be booted and shut down (Alpine install image perhaps?).

This ultimately will let us test our CLI functionality much more readily than we currently can.

Formally document versioning and public API.

Needs to happen before public release.

Provide custom libvirt event loop implementation.

The default libvirt event loop implementation works for our purposes, but a custom implementation would allow for:

Introspection of registered events.
Signaled conditional shutdown.
Debug logging of events being fired.
No need to populate a dummy event prior to actually starting just to make sure everything works correctly.

Add command to print detailed host information

Command should be invoked as fvirt host info

The provided information should be similar to that provided by virsh nodeinfo, plus SEV support status, max number of VCPUs per guest, hostname, and possibly more.

Add command to connect to domain console

Command should be invoked as fvirt domain console

General behavior should mirror virsh console behavior when possible, though ideally with better handling of he local terminal window (IOW, don’t leave things in a state where we’re stuck printing only 80x25 output).

Add command to create volume directly from local file.

Command should be invoked as fvirt volume create-from-file

This should combine defining the volume (with the size being inferred automatically from the source file) and uploading the file data.

Add command to perform XSLT transformations on volumes.

Backend code exists to support it, we just don’t have an actual command hooked up in the CLI to do it.

Add support for matching on multiple criteria at once.

By specifying multiple --match arguments.

Add domain snapshot support.

Will need new commands and new backend code in the libvirt wrappers.

Add command to print detailed domain information.

Command should be invoked as fvirt domain info

It should print out a nice, human-friendly, rundown of various domain properties (the same things the list command supports, plus stuff like the number of VCPUs, amount of memory, what disks are attached, etc).

Tests that depend on a working libvirt daemon should fail fast if one is not found.

Without this, the test suite takes a long time to run on systems without libvirtd, because each test that needs a libvirt daemon sits around for the full 30 second timeout trying to connect before it gets killed for timing out.

Ideally we should have the checks in the fixtures themselves that provide the Hypervisor instances, so that all tests that need this get it automatically.

Domain console handling is horribly broken.

Not entirely sure what, exactly, is going wrong here, but it’s likely an issue with how we’re trying to use the non-blocking libvirt streams API.

Add commands to open object XML in an editor.

Equivalent to virsh edit and related commands. Should use click.edit() internally.

Add command to clone volumes.

Command should be invoked as fvirt volume clone.

Should take a name and path for the new volume instead of requiring an XML volume description.

Add command to print detailed storage pool information.

Command should be invoked as fvirt pool info.

Provided information should match up with what is supported by fvirt pool list, possibly plus some extra info.

Add domain migration support.

This is one of the major missing pieces for working with libvirt domains. It’s likely to be rather involved to add, but it’s something we do want long-term.

Restructure fvirt.util.tables to allow proper testing.

Currently it has almost no test coverage, and is almost impossible to test because it interacts heavily with click in cases where it should not.

Add command to create storage pool from template.

Command should be invoked as fvirt pool new.

Support integers on input for properties of fvirt.libvirt.domain.models.PCIAddress.

This would allow for slightly easier instantiation. Instead of needing:

PCIAddress(bus='0x00', slot='0x01', function='0xa')

One could instead use:

PCIAddress(bus=0x00, slot=0x01, function=0xa)

Input ranges need to be clamped appropriately, and the internal representation should remain as a string (as that is what is expected when rendering templates).

Add libvirt event handling interface to fvirt API.

This should cover:

Timers
File handle events
Stream events
Lifecycle events for entities that provide them.