virtomate guest-run¶

Name¶

virtomate guest-run - Run a program on a domain through the QEMU Guest Agent.

Synopsis¶

virtomate guest-run [options] domain program [arguments]

Description¶

virtomate guest-run runs program with the given arguments on domain. program is started by the QEMU Guest Agent running on domain on behalf of virtomate guest-run. The results of the program are returned as JSON message with the following structure:

class virtomate.guest.RunResult¶

exit_code: int | None¶: Exit code of the program if it was terminated normally.

signal: int | None¶: Signal number (Unix-like operating systems) or unhandled exception code (Windows) if the program was terminated abnormally.

stderr: str | None¶: Captured standard error of the program.

stderr_truncated: bool¶: Whether standard error was truncated.

stdout: str | None¶: Captured standard output of the program.

stdout_truncated: bool¶: Whether standard output was truncated.

virtomate guest-run waits for program to complete before returning a result.

The exit status of virtomate guest-run is unaffected by the exit status of program. virtomate guest-run will only exit with a non-zero status if it could not start program, for example, because it does not exist or the QEMU Guest Agent is not running.

program is started by the QEMU Guest Agent using an exit(3)-like function. This means no shell is involved when starting program. To use shell-builtins like | in your command to run on domain, you have to explicitly invoke a shell as program. Please see the examples below for how to do it.

While you can pass standard input to program and receive standard output as well as standard error, note that those are completely buffered in memory before being transferred back and forth between the host and the guest. Consequently, it would be very inefficient to transfer larger volumes of data between the host and the guest. Furthermore, the amount of data that can be transferred between the host and the guest is limited to a few megabytes by libvirt.

QEMU Guest Agent itself limits the size of standard output and standard error to 16 megabytes. If standard output or standard error were larger, QEMU Guest Agent would truncate them and indicate that in the result.

Options¶

-h, --help¶: Display usage summary of this command and exit.

-e, --encode¶: Encode output with Base64.

--stdin¶: Consume standard input and pass it to program. Due to way QEMU Guest Agent operates, standard input is buffered in memory before being passed to program at once.

Versions¶

Added in version 0.1.0.

Examples¶

Run echo -n "Hello World" on my-domain:

$ virtomate -p guest-run my-domain -- echo -n "Hello World"
{
  "exit_code": 0,
  "signal": null,
  "stderr": null,
  "stderr_truncated": false,
  "stdout": "Hello World",
  "stdout_truncated": false
}

Note

The double dash (--) signifies the end of command options. It is required to distinguish options meant for virtomate from those for program to be run on the guest. While the exact position of -- does not matter, it is recommended to place it directly before program.

Run echo -n "Hello World" on my-domain and return standard output and standard error encoded with Base64:

$ virtomate -p guest-run --encode my-domain -- echo -n "Hello World"
{
  "exit_code": 0,
  "signal": null,
  "stderr": null,
  "stderr_truncated": false,
  "stdout": "SGVsbG8gV29ybGQ=",
  "stdout_truncated": false
}
$ echo -n 'SGVsbG8gV29ybGQ=' | base64 -d
Hello World

If you run a program that fails, its exit status and standard error are included in the JSON message. The exit status of virtomate guest-run remains 0 because Virtomate could successfully start the program:

$ virtomate -p guest-run my-domain -- cat /does/not/exist
{
  "exit_code": 1,
  "signal": null,
  "stderr": "cat: /does/not/exist: No such file or directory\n",
  "stderr_truncated": false,
  "stdout": null,
  "stdout_truncated": false
}
$ echo $?
0

This is different from trying to run a program that cannot be started:

$ virtomate -p guest-run my-domain -- /does/not/exist
{
  "message": "internal error: unable to execute QEMU agent command 'guest-exec': Guest agent command failed, error was 'Failed to execute child process \u201c/does/not/exist\u201d (No such file or directory)'",
  "type": "libvirtError"
}
$ echo $?
1

Because the program /does/not/exist does not exist, virtomate guest-run cannot start it. Hence, it returns an error and the exit status is 1.

To run a shell command, you have to invoke the shell explicitly. For example, to count the characters in the string “Hello World”, run:

$ virtomate -p guest-run my-domain -- \
    /usr/bin/env bash -c 'printf "Hello World" | wc -m'
{
  "exit_code": 0,
  "signal": null,
  "stderr": null,
  "stderr_truncated": false,
  "stdout": "11\n",
  "stdout_truncated": false
}

You can also print “Hello World” on the guest and count the characters in the guest by passing “Hello World” via standard input to wc(1):

$ printf "Hello World" | virtomate -p guest-run --stdin my-domain -- wc -m
{
  "exit_code": 0,
  "signal": null,
  "stderr": null,
  "stderr_truncated": false,
  "stdout": "11\n",
  "stdout_truncated": false
}