Starting with version 2.1, VirtualBox allows for requesting certain properties from a running guest, provided that the VirtualBox Guest Additions are installed and the VM is running. This is good for two things:
-
A number of predefined VM characteristics are automatically maintained by VirtualBox and can be retrieved on the host, e.g. to monitor VM performance and statistics.
-
In addition, arbitrary string data can be exchanged between guest and host. This works in both directions.
To accomplish this, VirtualBox establishes a private communication channel between the VirtualBox Guest Additions and the host, and software on both sides can use this channel to exchange string data for arbitrary purposes. Guest properties are simply string keys to which a value is attached. They can be set (written to) by either the host and the guest, and they can also be read from both sides.
In addition to establishing the general mechanism of reading and
writing values, a set of predefined guest properties is automatically
maintained by the VirtualBox Guest Additions to allow for retrieving
interesting guest data such as the guest's exact operating system and
service pack level, the installed version of the Guest Additions, users
that are currently logged into the guest OS, network statistics and more.
These predefined properties are all prefixed with
/VirtualBox/ and organized into a
hierarchical tree of keys.
Some of this runtime information is shown when you select "Session Information Dialog" from a virtual machine's "Machine" menu.
A more flexible way to use this channel is via the
VBoxManage guestproperty command set; see
Section 8.33, “VBoxManage guestproperty” for details. For example, to
have all the available guest properties for a given
running VM listed with their respective values, use this:
$ VBoxManage guestproperty enumerate "Windows Vista III"
VirtualBox Command Line Management Interface Version 5.2.4
(C) 2005-2017 Oracle Corporation
All rights reserved.
Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
timestamp: 1229098278843087000, flags:
Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
timestamp: 1229098278950553000, flags:
Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
timestamp: 1229098279122627000, flags:
Name: /VirtualBox/GuestAdd/InstallDir,
value: C:/Program Files/Oracle/VirtualBox
Guest Additions, timestamp: 1229098279269739000, flags:
Name: /VirtualBox/GuestAdd/Revision, value: 40720,
timestamp: 1229098279345664000, flags:
Name: /VirtualBox/GuestAdd/Version, value: 5.2.4,
timestamp: 1229098279479515000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: 5.2.4r40720,
timestamp: 1229098279651731000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: 5.2.4r40720,
timestamp: 1229098279804835000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: 5.2.4r40720,
timestamp: 1229098279880611000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: 5.2.4r40720,
timestamp: 1229098279882618000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: 5.2.4r40720,
timestamp: 1229098279883195000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: 5.2.4r40720,
timestamp: 1229098279885027000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: 5.2.4r40720,
timestamp: 1229098279886838000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: 5.2.4r40720,
timestamp: 1229098279890600000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: 5.2.4r40720,
timestamp: 1229098279893056000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: 5.2.4r40720,
timestamp: 1229098279895767000, flags:
Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
timestamp: 1229099826317660000, flags:
Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
timestamp: 1229098455580553000, flags:
Name: /VirtualBox/GuestInfo/Net/Count, value: 1,
timestamp: 1229099826299785000, flags:
Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
timestamp: 1229098151272771000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
timestamp: 1229099826300088000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
timestamp: 1229099826300220000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
timestamp: 1229099826300350000, flags:
Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
timestamp: 1229099826300524000, flags:
Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
timestamp: 1229099826317386000, flags:
To query the value of a single property, use the "get" subcommand like this:
$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" VirtualBox Command Line Management Interface Version 5.2.4 (C) 2005-2017 Oracle Corporation All rights reserved. Value: Windows Vista Business Edition
To add or change guest properties from the guest, use the tool
VBoxControl. This tool is included in the
Guest Additions of VirtualBox 2.2 or later. When started from a Linux
guest, this tool requires root privileges for security reasons:
$ sudo VBoxControl guestproperty enumerate
VirtualBox Guest Additions Command Line Management Interface Version 5.2.4
(C) 2009-2017 Oracle Corporation
All rights reserved.
Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
timestamp: 1265813265835667000, flags: <NULL>
Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
timestamp: 1265813265836305000, flags: <NULL>
...
For more complex needs, you can use the VirtualBox programming interfaces; see Chapter 11, VirtualBox programming interfaces.