The "guestproperty" commands allow you to get or set properties of a running virtual machine. Please see Section 4.7, “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> <property>: 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 printNo 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--flagsyou 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. -
delete <vm> <property>: Deletes a formerly set guest property.