virtomate

Name

virtomate - Automate libvirt.

Synopsis

virtomate [global options] command [command options]

Description

virtomate is a command line utility to automate virtual machines with libvirt. In contrast to virsh(1), it returns JSON to be processed by other tools. Furthermore, it provides advanced commands to clone domains, run programs on domains, or import volumes. virtomate is not meant to replace virsh(1) but to complement it.

virtomate uses libvirt. As such, it can manage virtual machines on the same computer it is running on as on remote hosts. See the option -c for further information.

No matter whether a virtomate command succeeds or fails, virtomate prints JSON to standard output (stdout), if any. Standard error (stderr) is reserved for diagnostic output. To distinguish between a standard and error response, examine the exit status of virtomate.

  • A status of 0 indicates success. This means that you can expect a standard response.

  • A status of 1 indicates a Virtomate error. An error message with the following structure will be printed to standard output:

    class virtomate.ErrorMessage

    Standardised error message that will be printed in case of an error.

    message: str | None

    Human-readable message describing the error.

    type: str

    Type of error, typically the name of the raised exception.

  • A status of 2 indicates a usage error. Usage information will be printed to standard error.

Options

-c URI, --connection URI

Use URI to connect to the hypervisor instead of using the default. See the libvirt documentation for details about the hypervisor selection logic.

-h, --help

Display usage summary and exit.

-l LEVEL, --log LEVEL

Enable logging to standard error and log all messages of LEVEL and above. Valid options are: debug, info, warning, error, and critical.

-p, --pretty

Enable pretty-printing of the JSON output.

-v, --version

Display Virtomate’s version and exit.

Commands

Command

Description

domain-list

List all domains.

domain-clone

Clone a domain.

domain-iface-list

List network interfaces of a running domain.

guest-ping

Ping the QEMU Guest Agent of a running domain.

guest-run

Run a program on the running domain.

pool-list

List all storage pools.

volume-list

List all storage volumes.

volume-import

Import a local file into a storage pool.

Exit Status

virtomate exits with status 0 on success, non-zero on error.

Details about the error statuses:

1

Indicates an operation error; a JSON error message will be printed to standard output.

2

Indicates a usage error; usage information will be printed to standard error.

Subcommands may exit with additional statuses.

Environment

LIBVIRT_DEFAULT_URI

Set the URI of the hypervisor virtomate connects to. See the libvirt documentation for supported URIs.

Versions

Added in version 0.1.0.

Examples

Use the system-mode daemon qemu:///system for all further interactions in the current session:

$ export LIBVIRT_DEFAULT_URI=qemu:///system
$ virtomate domain-list
[{"name":"my-domain","state":"suspended","uuid":"476ef224-e1ca-4a54-9095-202b11655c80"}]

Connect to a remote host:

$ virtomate -c qemu+ssh://[email protected]/system domain-list
[{"name":"remote-domain","state":"running","uuid":"21daf60b-9031-40a9-8e97-37da2998a41b"}]

Pretty-print the output:

$ virtomate -p domain-list
[
  {
    "name": "my-domain",
    "state": "suspended",
    "uuid": "476ef224-e1ca-4a54-9095-202b11655c80"
  }
]

Result in case of an error:

$ virtomate domain-iface-list unknown
{"type":"NotFoundError","message":"Domain 'unknown' does not exist"}
$ echo $?
1