The "guestproperty" commands allow you to get or set properties of a running virtual machine. Please see Section 4.6, “Guest properties” for an introduction. As explained there, guest properties are arbitrary key/value string pairs which can be written to and read from by either the guest or the host, so they can be used as a low-volume communication channel for strings, provided that a guest is running and has the Guest Additions installed. In addition, a number of values whose keys begin with "/VirtualBox/" are automatically set and maintained by the Guest Additions.
The following subcommands are available (where
<vm>
, in each case, can either be a
VM name or a VM UUID, as with the other VBoxManage commands):
enumerate <vm> [--patterns
<pattern>]
: This lists all the guest
properties that are available for the given VM, including the value.
This list will be very limited if the guest's service process cannot
be contacted, e.g. because the VM is not running or the Guest
Additions are not installed.
If --patterns <pattern>
is specified, it acts as a filter to only list properties that match
the given pattern. The pattern can contain the following wildcard
characters:
*
(asterisk):
represents any number of characters; for example,
"/VirtualBox*
" would match
all properties beginning with "/VirtualBox".
?
(question mark):
represents a single arbitrary character; for example,
"fo?
" would match both "foo"
and "for".
|
(pipe symbol): can be
used to specify multiple alternative patterns; for example,
"s*|t*
" would match anything
starting with either "s" or "t".
get <vm>
: This
retrieves the value of a single property only. If the property
cannot be found (e.g. because the guest is not running), this will
print
No value set!
set <vm> <property> [<value>
[--flags <flags>]]
: This allows you to set a
guest property by specifying the key and value. If
<value>
is omitted, the
property is deleted. With --flags
you can optionally specify additional behavior (you can combine
several by separating them with commas):
TRANSIENT
: the value
will not be stored with the VM data when the VM exits;
TRANSRESET
: the value
will be deleted as soon as the VM restarts and/or exits;
RDONLYGUEST
: the value
can only be changed by the host, but the guest can only read
it;
RDONLYHOST
: reversely,
the value can only be changed by the guest, but the host can
only read it;
READONLY
: a combination
of the two, the value cannot be changed at all.
wait <vm> <pattern> --timeout
<timeout>
: This waits for a particular value
described by "pattern" to change or to be deleted or created. The
pattern rules are the same as for the "enumerate" subcommand
above.