| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="guestadd-guestprops">
|
|---|
| 4 | <title>Guest Properties</title>
|
|---|
| 5 |
|
|---|
| 6 | <body>
|
|---|
| 7 | <p>
|
|---|
| 8 | <ph conkeyref="vbox-conkeyref-phrases/product-name"/> enables requests of some properties from a running
|
|---|
| 9 | guest, provided that the <ph conkeyref="vbox-conkeyref-phrases/product-name"/> Guest Additions are
|
|---|
| 10 | installed and the VM is running. This provides the following
|
|---|
| 11 | advantages:
|
|---|
| 12 | </p>
|
|---|
| 13 | <ul>
|
|---|
| 14 | <li>
|
|---|
| 15 | <p>
|
|---|
| 16 | A number of predefined VM characteristics are automatically
|
|---|
| 17 | maintained by <ph conkeyref="vbox-conkeyref-phrases/product-name"/> and can be retrieved on the host.
|
|---|
| 18 | For example, to monitor VM performance and statistics.
|
|---|
| 19 | </p>
|
|---|
| 20 | </li>
|
|---|
| 21 | <li>
|
|---|
| 22 | <p>
|
|---|
| 23 | Arbitrary string data can be exchanged between guest and host.
|
|---|
| 24 | This works in both directions.
|
|---|
| 25 | </p>
|
|---|
| 26 | </li>
|
|---|
| 27 | </ul>
|
|---|
| 28 | <p>
|
|---|
| 29 | To accomplish this, <ph conkeyref="vbox-conkeyref-phrases/product-name"/> establishes a private
|
|---|
| 30 | communication channel between the <ph conkeyref="vbox-conkeyref-phrases/product-name"/> Guest Additions
|
|---|
| 31 | and the host, and software on both sides can use this channel to
|
|---|
| 32 | exchange string data for arbitrary purposes. Guest properties are
|
|---|
| 33 | simply string keys to which a value is attached. They can be set,
|
|---|
| 34 | or written to, by either the host and the guest. They can also be
|
|---|
| 35 | read from both sides.
|
|---|
| 36 | </p>
|
|---|
| 37 | <p>
|
|---|
| 38 | In addition to establishing the general mechanism of reading and
|
|---|
| 39 | writing values, a set of predefined guest properties is
|
|---|
| 40 | automatically maintained by the <ph conkeyref="vbox-conkeyref-phrases/product-name"/> Guest Additions to
|
|---|
| 41 | allow for retrieving interesting guest data such as the guest's
|
|---|
| 42 | exact operating system and service pack level, the installed
|
|---|
| 43 | version of the Guest Additions, users that are currently logged
|
|---|
| 44 | into the guest OS, network statistics and more. These predefined
|
|---|
| 45 | properties are all prefixed with <codeph>/VirtualBox/</codeph>
|
|---|
| 46 | and organized into a hierarchical tree of keys.
|
|---|
| 47 | </p>
|
|---|
| 48 | <p>
|
|---|
| 49 | Some of this runtime information is shown when you select
|
|---|
| 50 | <b outputclass="bold">Session Information Dialog</b> from a
|
|---|
| 51 | virtual machine's <b outputclass="bold">Machine</b> menu.
|
|---|
| 52 | </p>
|
|---|
| 53 | <p> A more flexible way to use this channel is with the <userinput>VBoxManage
|
|---|
| 54 | guestproperty</userinput> command. See <xref href="vboxmanage-guestproperty.dita"/>.
|
|---|
| 55 | For example, to have <i>all</i> the available guest properties for a given running VM
|
|---|
| 56 | listed with their respective values, use this command: </p>
|
|---|
| 57 | <pre xml:space="preserve">$ VBoxManage guestproperty enumerate "Windows Vista III"
|
|---|
| 58 | VirtualBox Command Line Management Interface Version <varname>version-number</varname>
|
|---|
| 59 | Copyright (C) 2005-2022 Oracle and/or its affiliates
|
|---|
| 60 |
|
|---|
| 61 | Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
|
|---|
| 62 | timestamp: 1229098278843087000, flags:
|
|---|
| 63 | Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
|
|---|
| 64 | timestamp: 1229098278950553000, flags:
|
|---|
| 65 | Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
|
|---|
| 66 | timestamp: 1229098279122627000, flags:
|
|---|
| 67 | Name: /VirtualBox/GuestAdd/InstallDir,
|
|---|
| 68 | value: C:/Program Files/Oracle/VirtualBox
|
|---|
| 69 | Guest Additions, timestamp: 1229098279269739000, flags:
|
|---|
| 70 | Name: /VirtualBox/GuestAdd/Revision, value: 40720,
|
|---|
| 71 | timestamp: 1229098279345664000, flags:
|
|---|
| 72 | Name: /VirtualBox/GuestAdd/Version, value: <varname>version-number</varname>,
|
|---|
| 73 | timestamp: 1229098279479515000, flags:
|
|---|
| 74 | Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <varname>version-number</varname>r40720,
|
|---|
| 75 | timestamp: 1229098279651731000, flags:
|
|---|
| 76 | Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <varname>version-number</varname>r40720,
|
|---|
| 77 | timestamp: 1229098279804835000, flags:
|
|---|
| 78 | Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <varname>version-number</varname>r40720,
|
|---|
| 79 | timestamp: 1229098279880611000, flags:
|
|---|
| 80 | Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <varname>version-number</varname>r40720,
|
|---|
| 81 | timestamp: 1229098279882618000, flags:
|
|---|
| 82 | Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <varname>version-number</varname>r40720,
|
|---|
| 83 | timestamp: 1229098279883195000, flags:
|
|---|
| 84 | Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <varname>version-number</varname>r40720,
|
|---|
| 85 | timestamp: 1229098279885027000, flags:
|
|---|
| 86 | Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <varname>version-number</varname>r40720,
|
|---|
| 87 | timestamp: 1229098279886838000, flags:
|
|---|
| 88 | Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <varname>version-number</varname>r40720,
|
|---|
| 89 | timestamp: 1229098279890600000, flags:
|
|---|
| 90 | Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <varname>version-number</varname>r40720,
|
|---|
| 91 | timestamp: 1229098279893056000, flags:
|
|---|
| 92 | Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <varname>version-number</varname>r40720,
|
|---|
| 93 | timestamp: 1229098279895767000, flags:
|
|---|
| 94 | Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
|
|---|
| 95 | timestamp: 1229099826317660000, flags:
|
|---|
| 96 | Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
|
|---|
| 97 | timestamp: 1229098455580553000, flags:
|
|---|
| 98 | Name: /VirtualBox/GuestInfo/Net/Count, value: 1,
|
|---|
| 99 | timestamp: 1229099826299785000, flags:
|
|---|
| 100 | Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
|
|---|
| 101 | timestamp: 1229098151272771000, flags:
|
|---|
| 102 | Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
|
|---|
| 103 | timestamp: 1229099826300088000, flags:
|
|---|
| 104 | Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
|
|---|
| 105 | timestamp: 1229099826300220000, flags:
|
|---|
| 106 | Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
|
|---|
| 107 | timestamp: 1229099826300350000, flags:
|
|---|
| 108 | Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
|
|---|
| 109 | timestamp: 1229099826300524000, flags:
|
|---|
| 110 | Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
|
|---|
| 111 | timestamp: 1229099826317386000, flags:</pre>
|
|---|
| 112 | <p>
|
|---|
| 113 | To query the value of a single property, use the
|
|---|
| 114 | <userinput>get</userinput> subcommand as follows:
|
|---|
| 115 | </p>
|
|---|
| 116 | <pre xml:space="preserve">$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
|
|---|
| 117 | VirtualBox Command Line Management Interface Version <varname>version-number</varname>
|
|---|
| 118 | Copyright (C) 2005-2022 Oracle and/or its affiliates
|
|---|
| 119 |
|
|---|
| 120 | Value: Windows Vista Business Edition</pre>
|
|---|
| 121 | <p>
|
|---|
| 122 | To add or change guest properties from the guest, use the tool
|
|---|
| 123 | <userinput>VBoxControl</userinput>. This tool is included in the Guest
|
|---|
| 124 | Additions. When started from a Linux guest, this tool requires
|
|---|
| 125 | root privileges for security reasons.
|
|---|
| 126 | </p>
|
|---|
| 127 | <pre xml:space="preserve">$ sudo VBoxControl guestproperty enumerate
|
|---|
| 128 | VirtualBox Guest Additions Command Line Management Interface Version <varname>version-number</varname>
|
|---|
| 129 | Copyright (C) 2005-2022 Oracle and/or its affiliates
|
|---|
| 130 |
|
|---|
| 131 | Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
|
|---|
| 132 | timestamp: 1265813265835667000, flags: <NULL>
|
|---|
| 133 | Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
|
|---|
| 134 | timestamp: 1265813265836305000, flags: <NULL>
|
|---|
| 135 | ...</pre>
|
|---|
| 136 | <p>
|
|---|
| 137 | For more complex needs, you can use the <ph conkeyref="vbox-conkeyref-phrases/product-name"/> programming
|
|---|
| 138 | interfaces. See <xref href="VirtualBoxAPI.dita"><ph conkeyref="vbox-conkeyref-phrases/product-name"/> Programming Interfaces</xref>.
|
|---|
| 139 | </p>
|
|---|
| 140 | </body>
|
|---|
| 141 | </topic>
|
|---|
