The guestproperty commands enable you to get or
set properties of a running virtual machine. See
Section 4.7, “Guest Properties”. Guest properties are
arbitrary keyword-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 keywords begin with
/VirtualBox/are automatically set
and maintained by the Guest Additions.
The following subcommands are available, where
<vm> can either be a VM
name or a VM UUID, as with the other VBoxManage
commands:
enumerate <vm> [--patterns <pattern>]: 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, for example 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>: Retrieves the value of a single property only. If the property cannot be found, for example because the guest is not running, the following message is shown:No value set!
set <vm> <property> [<value> [--flags <flags>]]: Enables you to set a guest property by specifying the keyword and value. If<value>is omitted, the property is deleted. With--flags, you can specify additional behavior. You can combine several flags 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 or exits.RDONLYGUEST: The value can only be changed by the host, but the guest can only read it.RDONLYHOST: The value can only be changed by the guest, but the host can only read it.READONLY: The value cannot be changed at all.
wait <vm> <pattern> --timeout <timeout>: Waits for a particular value described by the pattern string to change or to be deleted or created. The pattern rules are the same as for the enumerate subcommand.delete <vm> <property>: Deletes a guest property which has been set previously.