Changeset 34531 in vbox
- Timestamp:
- Nov 30, 2010 5:08:32 PM (14 years ago)
- Location:
- trunk/doc/manual
- Files:
-
- 4 edited
-
docbook2latex.xsl (modified) (1 diff)
-
en_US/user_AdvancedTopics.xml (modified) (1 diff)
-
en_US/user_BasicConcepts.xml (modified) (5 diffs)
-
en_US/user_VBoxManage.xml (modified) (6 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/manual/docbook2latex.xsl
r32462 r34531 414 414 415 415 <xsl:template match="tgroup"> 416 <xsl:text>

 \begin{center}
\begin{tabulary}{.9\textwidth}[]{|L|L|}
\hline
</xsl:text>417 <xsl:apply-templates /> 418 <xsl:text>
\end{tabulary}
\end{center} 
</xsl:text>416 <xsl:text>

{\small\begin{center}
\begin{tabulary}{.9\textwidth}[]{|L|L|L|}
\hline
</xsl:text> 417 <xsl:apply-templates /> 418 <xsl:text>
\end{tabulary}
\end{center}}
</xsl:text> 419 419 </xsl:template> 420 420 -
trunk/doc/manual/en_US/user_AdvancedTopics.xml
r34392 r34531 6 6 7 7 <sect1 id="vboxconfigdata"> 8 <title>VirtualBox configuration data</title> 9 10 <para>For each system user, VirtualBox stores configuration data in the 11 user's home directory, as per the conventions of the host operating 12 system:<itemizedlist> 8 <title>Where VirtualBox stores its files</title> 9 10 <para>In VirtualBox, a virtual machine and its settings are described in a 11 virtual machine settings file in XML format. In addition, most virtual 12 machine have one or more virtual hard disks, which are typically 13 represented by disk images (e.g. in VDI format). Where all these files are 14 stored depends on which version of VirtualBox created the machine.</para> 15 16 <sect2> 17 <title>Machines created by VirtualBox version 4.0 or later</title> 18 19 <para>Starting with version 4.0, by default, each virtual machine has 20 one directory on your host computer where all the files of that machine 21 are stored -- the XML settings file (with a 22 <computeroutput>.vbox</computeroutput> file extension) and its disk 23 images.</para> 24 25 <para>By default, this "machine folder" is placed in a shared folder 26 called "VirtualBox VMs", which VirtualBox creates in the current system 27 user's home directory, as per the conventions of the host operating 28 system:</para> 29 30 <itemizedlist> 13 31 <listitem> 14 32 <para>On Windows, this is 15 <computeroutput>%HOMEDRIVE%%HOMEPATH% \.VirtualBox</computeroutput>;16 typicallysomething like <computeroutput>C:\Documents and17 Settings\Username\ .VirtualBox</computeroutput>.</para>33 <computeroutput>%HOMEDRIVE%%HOMEPATH%</computeroutput>; typically 34 something like <computeroutput>C:\Documents and 35 Settings\Username\</computeroutput>.</para> 18 36 </listitem> 19 37 20 38 <listitem> 21 39 <para>On Mac OS X, this is 22 <computeroutput> $HOME/Library/VirtualBox</computeroutput>.</para>40 <computeroutput>/Users/username</computeroutput>.</para> 23 41 </listitem> 24 42 25 43 <listitem> 26 <para>On Unix-like systems (Linux, Solaris), this is27 <computeroutput> $HOME/.VirtualBox</computeroutput>.</para>44 <para>On Linux and Solaris, this is 45 <computeroutput>/home/username</computeroutput>.</para> 28 46 </listitem> 29 </itemizedlist></para> 30 31 <para>VirtualBox creates this configuration directory automatically, if 32 necessary. Optionally, you can supply an alternate configuration directory 33 by setting the 34 <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput> 35 environment variable. You can globally change some of the locations where 36 VirtualBox keeps extra configuration and data by selecting "Global 37 settings" from the "File" menu in the VirtualBox main window. Then, in the 38 window that pops up, click on the "General" tab.</para> 39 40 <para>VirtualBox stores all its global and machine-specific configuration 41 data in XML documents. We intentionally do not document the specifications 42 of these files, as we must reserve the right to modify them in the future. 43 We therefore strongly suggest that you do not edit these files manually. 44 VirtualBox provides complete access to its configuration data through its 45 the <computeroutput>VBoxManage</computeroutput> command line tool (see 46 <xref linkend="vboxmanage" />) and its API (see <xref 47 linkend="VirtualBoxAPI" />).</para> 48 49 <para>The XML files are versioned. When a new settings file is created 50 (e.g. because a new virtual machine is created), VirtualBox automatically 51 uses the settings format of the current VirtualBox version. These files 52 may not be readable if you downgrade to an earlier version of VirtualBox. 53 However, when VirtualBox encounters a settings file from an earlier 54 version (e.g. after upgrading VirtualBox), it attempts to preserve the 55 settings format as much as possible. It will only silently upgrade the 56 settings format if the current settings cannot be expressed in the old 57 format, for example because you enabled a feature that was not present in 58 an earlier version of VirtualBox.<footnote> 59 <para>As an example, before VirtualBox 3.1, it was only possible to 60 enable or disable a single DVD drive in a virtual machine. If it was 61 enabled, then it would always be visible as the secondary master of 62 the IDE controller. With VirtualBox 3.1, DVD drives can be attached to 63 arbitrary slots of arbitrary controllers, so they could be the 64 secondary slave of an IDE controller or in a SATA slot. If you have a 65 machine settings file from an earlier version and upgrade VirtualBox 66 to 3.1 and then move the DVD drive from its default position, this 67 cannot be expressed in the old settings format; the XML machine file 68 would get written in the new format, and a backup file of the old 69 format would be kept.</para> 70 </footnote> In such cases, VirtualBox backs up the old settings file in 71 the virtual machine's configuration directory. If you need to go back to 72 the earlier version of VirtualBox, then you will need to manually copy 73 these backup files back.</para> 74 75 <para>In detail, the following settings files are in use:</para> 76 77 <para><itemizedlist> 78 <listitem> 79 <para>In the configuration directory, 80 <computeroutput>VirtualBox.xml</computeroutput> is the main 81 configuration file. This includes global configuration options and 82 the media and virtual machine registry. The media registry links to 83 all CD/DVD, floppy and disk images that have been added to the 84 Virtual Media Manager. For each registered VM, there is one entry 85 which points to the VM configuration file, also in XML 86 format.</para> 87 </listitem> 88 89 <listitem> 90 <para>Virtual machine settings and files are, by default, saved as 91 XML files in a subdirectory of the 92 <computeroutput>Machines</computeroutput> directory, which 93 VirtualBox creates under the main configuration directory (see 94 above). You can change the location of this main "Machines" folder 95 in the "Global settings" dialog.</para> 96 97 <para>By default, for each virtual machine, VirtualBox uses another 98 subdirectory of the "Machines" directory that carries the same name 99 as the virtual machine. As a result, your virtual machine names must 100 conform to the conventions of your operating system for valid file 101 names. For example, a machine called "Fedora 6" would, by default, 102 have its settings saved in 103 <computeroutput>.VirtualBox/Machines/Fedora 6/Fedora 104 6.xml</computeroutput> (on a Linux or Solaris host).</para> 105 106 <para>If you would like more control over the file names used, you 107 can create the machine using <computeroutput>VBoxManage 108 createvm</computeroutput> with the 109 <computeroutput>--settingsfile</computeroutput> option; see <xref 110 linkend="vboxmanage-createvm" />.</para> 111 112 <para>The virtual machine directory will be renamed if you change 113 the machine name. If you do not wish this to happen, you can create 114 the machine using <computeroutput>VBoxManage 115 createvm</computeroutput> with the 116 <computeroutput>--basefolder</computeroutput> option. In this case, 117 the folder name will never change.</para> 118 </listitem> 119 120 <listitem> 121 <para>VirtualBox keeps snapshots and saved states in another special 122 folder for each virtual machine. By default, this is a subfolder of 123 the virtual machine folder called 124 <computeroutput>Snapshots</computeroutput> -- in our example, 125 <computeroutput>.VirtualBox/Machines/Fedora 126 6/Snapshots</computeroutput>. You can change this setting for each 127 machine using <computeroutput>VBoxManage</computeroutput> as 128 well.</para> 129 </listitem> 130 131 <listitem> 132 <para>VDI container files are, by default, created in the 133 <computeroutput>HardDisks</computeroutput> directory under the main 134 configuration directory (see above). In particular, this directory 135 is used when the "Create new virtual disk" wizard is started to 136 create a new VDI file. Changing this default is probably most useful 137 if the disk containing your home directory does not have enough room 138 to hold your VDI files, which can grow very large.</para> 139 </listitem> 140 </itemizedlist></para> 47 </itemizedlist> 48 49 <para>For simplicity, we will abbreviate this as 50 <computeroutput>$HOME</computeroutput> below. Using that convention, the 51 shared folder for all virtual machines is 52 <computeroutput>$HOME/VirtualBox VMs</computeroutput>.</para> 53 54 <para>As an example, if you have created a virtual machine called 55 "Example VM", you will find that VirtualBox has created<orderedlist> 56 <listitem> 57 <para>the folder <computeroutput>$HOME/VirtualBox VMs/Example 58 VM/</computeroutput> and, in that folder, </para> 59 </listitem> 60 61 <listitem> 62 <para>the settings file <computeroutput>Example 63 VM.vbox</computeroutput> and</para> 64 </listitem> 65 66 <listitem> 67 <para>the virtual disk image <computeroutput>Example 68 VM.vdi</computeroutput>.</para> 69 </listitem> 70 </orderedlist></para> 71 72 <para>This is the default layout if you use the "Create new virtual 73 machine" wizard as described in <xref linkend="gui-createvm" />. Once 74 you start working with the VM, additional files will show up: you will 75 find log files in a subfolder called 76 <computeroutput>Logs</computeroutput>, and once you have taken 77 snapshots, they will appear in a 78 <computeroutput>Snapshots</computeroutput> subfolder. For each VM, you 79 can change the location of its snapsnots folder in the VM 80 settings.</para> 81 82 <para>You can change the default machine folder by selecting 83 "Preferences" from the "File" menu in the VirtualBox main window. Then, 84 in the window that pops up, click on the "General" tab. Alternatively, 85 use VBoxManage setproperty machinefolder; see <xref 86 linkend="vboxmanage-setproperty" />.</para> 87 </sect2> 88 89 <sect2> 90 <title>Machines created by VirtualBox versions before 4.0</title> 91 92 <para>If you have upgraded to VirtualBox 4.0 from an earlier version of 93 VirtualBox, you probably have settings files and disks in the earlier 94 file system layout.</para> 95 96 <para>Before version 4.0, VirtualBox separated the machine settings 97 files from virtual disk images. The machine settings files had an 98 <computeroutput>.xml</computeroutput> file extension and resided in a 99 folder called "Machines" under the VirtualBox configuration directory 100 (see the next section). So, for example, on Linux, this was the hidden 101 <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> directory. 102 The default hard disks folder was called "HardDisks" and resided in the 103 <computeroutput>.VirtualBox</computeroutput> folder as well, but that 104 could be changed by the user in the global preferences. (The concept of 105 a "default hard disk folder" has been abandoned with VirtualBox 4.0, 106 since disk images now reside in each machine's folder by 107 default.)</para> 108 109 <para>The old layout had several severe disadvantages.<orderedlist> 110 <listitem> 111 <para>It was very difficult to move a virtual machine from one 112 host to another because the files involved did not reside in the 113 same folder. In addition, the virtual media of all machines were 114 registered with a global registry in the central VirtualBox 115 settings file 116 (<computeroutput>$HOME/.VirtualBox/VirtualBox.xml</computeroutput>). 117 </para> 118 119 <para>To move a machine to another host, it was therefore not 120 enough to move the XML settings file and the disk images (which 121 were in different locations), but the hard disk entries from the 122 global media registry XML had to be meticulously copied as well, 123 which was close to impossible if the machine had snapshots and 124 therefore differencing images.</para> 125 </listitem> 126 127 <listitem> 128 <para>Storing virtual disk images, which can grow very large, 129 under the hidden <computeroutput>.VirtualBox</computeroutput> 130 directory (at least on Linux and Solaris hosts) made many users 131 wonder where their disk space had gone.</para> 132 </listitem> 133 </orderedlist></para> 134 135 <para>Whereas new VMs created with VirtualBox 4.0 or later will conform 136 to the new layout, for maximum compatibility, old VMs are 137 <emphasis>not</emphasis> converted to the new layout. Otherwise machine 138 settings would be irrevocably broken if a user downgraded from 4.0 back 139 to an older version of VirtualBox.</para> 140 </sect2> 141 142 <sect2> 143 <title>Global configuration data</title> 144 145 <para>In addition to the files of the virtual machines, VirtualBox 146 maintains global configuration data. On Windows, Linux and Solaris, this 147 is <computeroutput>$HOME/.VirtualBox</computeroutput> (which makes it 148 hidden on Linux and Solaris), whereas on a Mac this resides in 149 <computeroutput>$HOME/Library/VirtualBox</computeroutput>.</para> 150 151 <para>VirtualBox creates this configuration directory automatically, if 152 necessary. Optionally, you can supply an alternate configuration 153 directory by setting the 154 <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput> 155 environment variable.</para> 156 157 <para>Most importantly, in this directory, VirtualBox stores its global 158 settings file, another XML file called 159 <computeroutput>VirtualBox.xml</computeroutput>. This includes global 160 configuration options and the list of registered virtual machines with 161 pointers to their XML settings files. (Neither the location of this file 162 nor its directory has changed with VirtualBox 4.0.)</para> 163 164 <para>Before VirtualBox 4.0, all virtual media (disk image files) were 165 also contained in a global registry in this settings file. For 166 compatibility, this media registry still exists if you upgrade 167 VirtualBox and there are media from machines which were created with a 168 version before 4.0. If you have no such machines, then there will be no 169 global media registry; with VirtualBox 4.0, each machine XML file has 170 its own media registry.</para> 171 172 <para>Also before VirtualBox 4.0, the default "Machines" folder and the 173 default "HardDisks" folder were subdirectories of the VirtualBox 174 configuration directory (e.g. 175 <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> on Linux). 176 If you are upgrading from a VirtualBox version before 4.0, files in 177 these directories are not automatically moved in order not to break 178 backwards compatibility.</para> 179 </sect2> 180 181 <sect2> 182 <title>Summary of 4.0 configuration changes</title> 183 184 <table> 185 <title>ignoreme</title> 186 187 <tgroup cols="3"> 188 <tbody> 189 <row> 190 <entry></entry> 191 192 <entry>Before 4.0</entry> 193 194 <entry>4.0 or above</entry> 195 </row> 196 197 <row> 198 <entry>Default machines folder</entry> 199 200 <entry><computeroutput>$HOME/.VirtualBox/Machines</computeroutput></entry> 201 202 <entry><computeroutput>$HOME/VirtualBox 203 VMs</computeroutput></entry> 204 </row> 205 206 <row> 207 <entry>Default disk image location</entry> 208 209 <entry><computeroutput>$HOME/.VirtualBox/HardDisks</computeroutput></entry> 210 211 <entry>In each machine's folder</entry> 212 </row> 213 214 <row> 215 <entry>Machine settings file extension</entry> 216 217 <entry><computeroutput>.xml</computeroutput></entry> 218 219 <entry><computeroutput>.vbox</computeroutput></entry> 220 </row> 221 222 <row> 223 <entry>Media registry</entry> 224 225 <entry>Global <computeroutput>VirtualBox.xml</computeroutput> 226 file</entry> 227 228 <entry>Each machine settings file</entry> 229 </row> 230 231 <row> 232 <entry>Media registration</entry> 233 234 <entry>Explicit open/close required</entry> 235 236 <entry>Automatic on attach</entry> 237 </row> 238 </tbody> 239 </tgroup> 240 </table> 241 </sect2> 242 243 <sect2> 244 <title>VirtualBox XML files</title> 245 246 <para>VirtualBox uses XML for both the machine settings files and the 247 global configuration file, 248 <computeroutput>VirtualBox.xml</computeroutput>. </para> 249 250 <para>All VirtualBox XML files are versioned. When a new settings file 251 is created (e.g. because a new virtual machine is created), VirtualBox 252 automatically uses the settings format of the current VirtualBox 253 version. These files may not be readable if you downgrade to an earlier 254 version of VirtualBox. However, when VirtualBox encounters a settings 255 file from an earlier version (e.g. after upgrading VirtualBox), it 256 attempts to preserve the settings format as much as possible. It will 257 only silently upgrade the settings format if the current settings cannot 258 be expressed in the old format, for example because you enabled a 259 feature that was not present in an earlier version of 260 VirtualBox.<footnote> 261 <para>As an example, before VirtualBox 3.1, it was only possible to 262 enable or disable a single DVD drive in a virtual machine. If it was 263 enabled, then it would always be visible as the secondary master of 264 the IDE controller. With VirtualBox 3.1, DVD drives can be attached 265 to arbitrary slots of arbitrary controllers, so they could be the 266 secondary slave of an IDE controller or in a SATA slot. If you have 267 a machine settings file from an earlier version and upgrade 268 VirtualBox to 3.1 and then move the DVD drive from its default 269 position, this cannot be expressed in the old settings format; the 270 XML machine file would get written in the new format, and a backup 271 file of the old format would be kept.</para> 272 </footnote> In such cases, VirtualBox backs up the old settings file 273 in the virtual machine's configuration directory. If you need to go back 274 to the earlier version of VirtualBox, then you will need to manually 275 copy these backup files back.</para> 276 277 <para>We intentionally do not document the specifications of the 278 VirtualBox XML files, as we must reserve the right to modify them in the 279 future. We therefore strongly suggest that you do not edit these files 280 manually. VirtualBox provides complete access to its configuration data 281 through its the <computeroutput>VBoxManage</computeroutput> command line 282 tool (see <xref linkend="vboxmanage" />) and its API (see <xref 283 linkend="VirtualBoxAPI" />).</para> 284 </sect2> 141 285 </sect1> 142 286 -
trunk/doc/manual/en_US/user_BasicConcepts.xml
r34124 r34531 16 16 this image to a guest system as if it were a physical CD-ROM. Similarly, you 17 17 can give a guest system access to the real network via its virtual network 18 card, and, if you choose, give the host system, other guests, or computers19 on the Internet access to the guest system.</para>18 card, and, if you so choose, give the host system, other guests, or 19 computers on the Internet access to the guest system.</para> 20 20 21 21 <sect1> … … 24 24 <para>Since VirtualBox is designed to provide a generic virtualization 25 25 environment for x86 systems, it may run operating systems of any kind, 26 even those that are not officially supported. However, our focus is to 27 optimize the product's performance for a select list of guest 28 systems:</para> 26 even those not listed here. However, the focus is to optimize VirtualBox 27 for the following guest systems:</para> 29 28 30 29 <para><glosslist> … … 159 158 restrictions</emphasis> that limit its use to certain hardware and 160 159 usage scenarios. It is important that you understand and obey 161 these restrictions. 160 these restrictions.</para> 162 161 163 162 <para>In particular, for most versions of Mac OS X Server, Apple … … 262 261 VirtualBox emulates a standard PS/2 keyboard and mouse. These 263 262 devices are supported by almost all past and present operating 264 systems. 263 systems.</para> 265 264 266 265 <para>In addition, VirtualBox can provide virtual USB input devices … … 787 786 <para>For virtual hard disks, a drop-down list appears on the right, 788 787 listing all the hard disk images that VirtualBox currently knows 789 about. 788 about.</para> 790 789 791 790 <para>The folder icon next to the drop-down allow you to select a -
trunk/doc/manual/en_US/user_VBoxManage.xml
r34509 r34531 2020 2020 </sect1> 2021 2021 2022 <sect1 >2022 <sect1 id="vboxmanage-setproperty"> 2023 2023 <title>VBoxManage setproperty</title> 2024 2024 … … 2027 2027 in the "Global settings" dialog in the graphical user interface. The 2028 2028 following properties are available:<glosslist> 2029 <glossentry>2030 <glossterm>hdfolder</glossterm>2031 2032 <glossdef>2033 <para>This specifies the default folder that is used to keep disk2034 image files (.vdi, .vmdk, .vhd).</para>2035 </glossdef>2036 </glossentry>2037 2038 2029 <glossentry> 2039 2030 <glossterm>machinefolder</glossterm> … … 2413 2404 <computeroutput><vm></computeroutput>, in each case, can either be a 2414 2405 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> 2415 <listitem>2416 <para><computeroutput>execute</computeroutput>, which2417 allows for executing a program/script (process) which is already installed2418 andrunnable on the guest. This command only works while a VM is up and2406 <listitem> 2407 <para><computeroutput>execute</computeroutput>, which allows for 2408 executing a program/script (process) which is already installed and 2409 runnable on the guest. This command only works while a VM is up and 2419 2410 running and has the following syntax:</para> 2420 2411 … … 2428 2419 2429 2420 <para>where the parameters mean: <glosslist> 2430 <glossentry> 2431 <glossterm>uuid|vmname</glossterm> 2432 2433 <glossdef> 2434 <para>The VM UUID or VM name. Mandatory.</para> 2435 </glossdef> 2436 </glossentry> 2437 2438 <glossentry> 2439 <glossterm>path to program</glossterm> 2440 2441 <glossdef> 2442 <para>Absolute path and process name of process to execute in the 2443 guest, e.g. 2444 <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para> 2445 </glossdef> 2446 </glossentry> 2447 2448 <glossentry> 2449 <glossterm>--arguments "<arguments>"</glossterm> 2450 2451 <glossdef> 2452 <para>One or more arguments to pass to the process being 2453 executed.</para> 2454 2455 <para>Arguments containing spaces must be enclosed in quotation 2456 marks. More than one <computeroutput>--arguments</computeroutput> 2457 at a time can be specified to keep the command line tidy.</para> 2458 </glossdef> 2459 </glossentry> 2460 2461 <glossentry> 2462 <glossterm>--environment "<NAME>=<VALUE>"</glossterm> 2463 2464 <glossdef> 2465 <para>One or more environment variables to be set or unset.</para> 2466 2467 <para>By default, the new process in the guest will be created 2468 with the the standard environment of the guest OS. This option 2469 allows for modifying that environment. To set/modify a variable, a 2470 pair of <computeroutput>NAME=VALUE</computeroutput> must be 2471 specified; to unset a certain variable, the name with no value 2472 must set, e.g. <computeroutput>NAME=</computeroutput>.</para> 2473 2474 <para>Arguments containing spaces must be enclosed in quotation 2475 marks. More than one 2476 <computeroutput>--environment</computeroutput> at a time can be 2477 specified to keep the command line tidy.</para> 2478 </glossdef> 2479 </glossentry> 2480 2481 <glossentry> 2482 <glossterm>--flags <flags></glossterm> 2483 2484 <glossdef> 2485 <para>Additional flags to set. This is not used at the 2486 moment.</para> 2487 </glossdef> 2488 </glossentry> 2489 2490 <glossentry> 2491 <glossterm>--timeout <msec></glossterm> 2492 2493 <glossdef> 2494 <para>Value (in milliseconds) that specifies the time how long the 2495 started process is allowed to run and how long VBoxManage waits 2496 for getting output from that process. If no timeout is specified, 2497 VBoxManage will wait forever until the started process ends or an 2498 error occured.</para> 2499 </glossdef> 2500 </glossentry> 2501 2502 <glossentry> 2503 <glossterm>--username <name></glossterm> 2504 2505 <glossdef> 2506 <para>Name of the user the process should run under. This user 2507 must exist on the guest OS.</para> 2508 </glossdef> 2509 </glossentry> 2510 2511 <glossentry> 2512 <glossterm>--password <password></glossterm> 2513 2514 <glossdef> 2515 <para>Password of the user account specified with 2516 <computeroutput>--username</computeroutput>. If not given, an 2517 empty password is assumed.</para> 2518 </glossdef> 2519 </glossentry> 2520 2521 <glossentry> 2522 <glossterm>--verbose</glossterm> 2523 2524 <glossdef> 2525 <para>Tells VBoxManage to be more verbose during the 2526 execution.</para> 2527 </glossdef> 2528 </glossentry> 2529 2530 <glossentry> 2531 <glossterm>--wait-for <action></glossterm> 2532 2533 <glossdef> 2534 <para>Tells VBoxManage to wait for a certain action to happen and 2535 react to it. The following actions are available: <glosslist> 2536 <glossentry> 2537 <glossterm>exit</glossterm> 2538 2539 <glossdef> 2540 <para>Waits until the process ends and outputs its exit 2541 code along with the exit reason/flags.</para> 2542 </glossdef> 2543 </glossentry> 2544 2545 <glossentry> 2546 <glossterm>stdout or stderr</glossterm> 2547 2548 <glossdef> 2549 <para>Waits until the process ends and outputs its exit 2550 code along with the exit reason/flags. After that 2551 VBoxManage retrieves the output collected from the guest 2552 process's stdout and stderr.</para> 2553 </glossdef> 2554 </glossentry> 2555 </glosslist></para> 2556 </glossdef> 2557 </glossentry> 2558 </glosslist> 2559 </para> 2560 2561 <para> 2562 <note> 2563 <para>On Windows there are certain limitations for graphical 2421 <glossentry> 2422 <glossterm>uuid|vmname</glossterm> 2423 2424 <glossdef> 2425 <para>The VM UUID or VM name. Mandatory.</para> 2426 </glossdef> 2427 </glossentry> 2428 2429 <glossentry> 2430 <glossterm>path to program</glossterm> 2431 2432 <glossdef> 2433 <para>Absolute path and process name of process to execute 2434 in the guest, e.g. 2435 <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para> 2436 </glossdef> 2437 </glossentry> 2438 2439 <glossentry> 2440 <glossterm>--arguments "<arguments>"</glossterm> 2441 2442 <glossdef> 2443 <para>One or more arguments to pass to the process being 2444 executed.</para> 2445 2446 <para>Arguments containing spaces must be enclosed in 2447 quotation marks. More than one 2448 <computeroutput>--arguments</computeroutput> at a time can 2449 be specified to keep the command line tidy.</para> 2450 </glossdef> 2451 </glossentry> 2452 2453 <glossentry> 2454 <glossterm>--environment 2455 "<NAME>=<VALUE>"</glossterm> 2456 2457 <glossdef> 2458 <para>One or more environment variables to be set or 2459 unset.</para> 2460 2461 <para>By default, the new process in the guest will be 2462 created with the the standard environment of the guest OS. 2463 This option allows for modifying that environment. To 2464 set/modify a variable, a pair of 2465 <computeroutput>NAME=VALUE</computeroutput> must be 2466 specified; to unset a certain variable, the name with no 2467 value must set, e.g. 2468 <computeroutput>NAME=</computeroutput>.</para> 2469 2470 <para>Arguments containing spaces must be enclosed in 2471 quotation marks. More than one 2472 <computeroutput>--environment</computeroutput> at a time can 2473 be specified to keep the command line tidy.</para> 2474 </glossdef> 2475 </glossentry> 2476 2477 <glossentry> 2478 <glossterm>--flags <flags></glossterm> 2479 2480 <glossdef> 2481 <para>Additional flags to set. This is not used at the 2482 moment.</para> 2483 </glossdef> 2484 </glossentry> 2485 2486 <glossentry> 2487 <glossterm>--timeout <msec></glossterm> 2488 2489 <glossdef> 2490 <para>Value (in milliseconds) that specifies the time how 2491 long the started process is allowed to run and how long 2492 VBoxManage waits for getting output from that process. If no 2493 timeout is specified, VBoxManage will wait forever until the 2494 started process ends or an error occured.</para> 2495 </glossdef> 2496 </glossentry> 2497 2498 <glossentry> 2499 <glossterm>--username <name></glossterm> 2500 2501 <glossdef> 2502 <para>Name of the user the process should run under. This 2503 user must exist on the guest OS.</para> 2504 </glossdef> 2505 </glossentry> 2506 2507 <glossentry> 2508 <glossterm>--password <password></glossterm> 2509 2510 <glossdef> 2511 <para>Password of the user account specified with 2512 <computeroutput>--username</computeroutput>. If not given, 2513 an empty password is assumed.</para> 2514 </glossdef> 2515 </glossentry> 2516 2517 <glossentry> 2518 <glossterm>--verbose</glossterm> 2519 2520 <glossdef> 2521 <para>Tells VBoxManage to be more verbose during the 2522 execution.</para> 2523 </glossdef> 2524 </glossentry> 2525 2526 <glossentry> 2527 <glossterm>--wait-for <action></glossterm> 2528 2529 <glossdef> 2530 <para>Tells VBoxManage to wait for a certain action to 2531 happen and react to it. The following actions are available: 2532 <glosslist> 2533 <glossentry> 2534 <glossterm>exit</glossterm> 2535 2536 <glossdef> 2537 <para>Waits until the process ends and outputs its 2538 exit code along with the exit reason/flags.</para> 2539 </glossdef> 2540 </glossentry> 2541 2542 <glossentry> 2543 <glossterm>stdout or stderr</glossterm> 2544 2545 <glossdef> 2546 <para>Waits until the process ends and outputs its 2547 exit code along with the exit reason/flags. After 2548 that VBoxManage retrieves the output collected from 2549 the guest process's stdout and stderr.</para> 2550 </glossdef> 2551 </glossentry> 2552 </glosslist></para> 2553 </glossdef> 2554 </glossentry> 2555 </glosslist></para> 2556 2557 <para><note> 2558 <para>On Windows there are certain limitations for graphical 2564 2559 applications; please see <xref linkend="KnownIssues" /> for more 2565 information. 2566 </para> 2567 </note> 2568 Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr" 2560 information.</para> 2561 </note> Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr" 2569 2562 --username foo --password bar --wait-for stdout</screen> <screen>VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe" 2570 2563 --username foo --password bar --wait-for stdout</screen> Note that 2571 the double backslashes in the second example are only required on Unix 2572 hosts. 2573 </para> 2574 </listitem> 2575 2576 <listitem> 2577 <para><computeroutput>copyto</computeroutput>, which 2578 allows copying files from the host to the guest 2579 (only with installed Guest Additions 4.0 and later).</para> 2564 the double backslashes in the second example are only required on 2565 Unix hosts.</para> 2566 </listitem> 2567 2568 <listitem> 2569 <para><computeroutput>copyto</computeroutput>, which allows copying 2570 files from the host to the guest (only with installed Guest 2571 Additions 4.0 and later).</para> 2580 2572 2581 2573 <screen>VBoxManage copyto <vmname>|<uuid> … … 2585 2577 2586 2578 <para>where the parameters mean: <glosslist> 2587 <glossentry> 2588 <glossterm>uuid|vmname</glossterm> 2589 2590 <glossdef> 2591 <para>The VM UUID or VM name. Mandatory.</para> 2592 </glossdef> 2593 </glossentry> 2594 2595 <glossentry> 2596 <glossterm>source on host</glossterm> 2597 2598 <glossdef> 2599 <para>Absolute path of source file(s) on host to copy over to 2600 the guest, e.g. 2601 <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. This also 2602 can be a wildcard expression, e.g. 2603 <computeroutput>C:\Windows\System32\*.dll</computeroutput> 2604 </para> 2605 </glossdef> 2606 </glossentry> 2607 2608 <glossentry> 2609 <glossterm>destination on guest</glossterm> 2610 2611 <glossdef> 2612 <para>Absolute destination path on the guest, e.g. 2613 <computeroutput>C:\Temp</computeroutput></para> 2614 </glossdef> 2615 </glossentry> 2616 2617 <glossentry> 2618 <glossterm>--username <name></glossterm> 2619 2620 <glossdef> 2621 <para>Name of the user the copy process should run under. This user 2622 must exist on the guest OS.</para> 2623 </glossdef> 2624 </glossentry> 2625 2626 <glossentry> 2627 <glossterm>--password <password></glossterm> 2628 2629 <glossdef> 2630 <para>Password of the user account specified with 2631 <computeroutput>--username</computeroutput>. If not given, an 2632 empty password is assumed.</para> 2633 </glossdef> 2634 </glossentry> 2635 2636 <glossentry> 2637 <glossterm>--dryrun</glossterm> 2638 2639 <glossdef> 2640 <para>Tells VBoxManage to only perform a dry run instead of 2641 really copying files to the guest.</para> 2642 </glossdef> 2643 </glossentry> 2644 2645 <glossentry> 2646 <glossterm>--recursive</glossterm> 2647 2648 <glossdef> 2649 <para>Recursively copies files/directories.</para> 2650 </glossdef> 2651 </glossentry> 2652 2653 <glossentry> 2654 <glossterm>--verbose</glossterm> 2655 2656 <glossdef> 2657 <para>Tells VBoxManage to be more verbose during the 2658 copy operation.</para> 2659 </glossdef> 2660 </glossentry> 2661 2662 <glossentry> 2663 <glossterm>--flags <flags></glossterm> 2664 2665 <glossdef> 2666 <para>Additional flags to set. This is not used at the 2667 moment.</para> 2668 </glossdef> 2669 </glossentry> 2670 2671 </glosslist> 2672 </para> 2673 </listitem> 2674 2675 <listitem> 2676 <para><computeroutput>updateadditions</computeroutput>, which 2677 allows for updating an already installed Guest Additions version on 2678 the guest (only already installed Guest Additions 4.0 and later).</para> 2579 <glossentry> 2580 <glossterm>uuid|vmname</glossterm> 2581 2582 <glossdef> 2583 <para>The VM UUID or VM name. Mandatory.</para> 2584 </glossdef> 2585 </glossentry> 2586 2587 <glossentry> 2588 <glossterm>source on host</glossterm> 2589 2590 <glossdef> 2591 <para>Absolute path of source file(s) on host to copy over 2592 to the guest, e.g. 2593 <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. 2594 This also can be a wildcard expression, e.g. 2595 <computeroutput>C:\Windows\System32\*.dll</computeroutput></para> 2596 </glossdef> 2597 </glossentry> 2598 2599 <glossentry> 2600 <glossterm>destination on guest</glossterm> 2601 2602 <glossdef> 2603 <para>Absolute destination path on the guest, e.g. 2604 <computeroutput>C:\Temp</computeroutput></para> 2605 </glossdef> 2606 </glossentry> 2607 2608 <glossentry> 2609 <glossterm>--username <name></glossterm> 2610 2611 <glossdef> 2612 <para>Name of the user the copy process should run under. 2613 This user must exist on the guest OS.</para> 2614 </glossdef> 2615 </glossentry> 2616 2617 <glossentry> 2618 <glossterm>--password <password></glossterm> 2619 2620 <glossdef> 2621 <para>Password of the user account specified with 2622 <computeroutput>--username</computeroutput>. If not given, 2623 an empty password is assumed.</para> 2624 </glossdef> 2625 </glossentry> 2626 2627 <glossentry> 2628 <glossterm>--dryrun</glossterm> 2629 2630 <glossdef> 2631 <para>Tells VBoxManage to only perform a dry run instead of 2632 really copying files to the guest.</para> 2633 </glossdef> 2634 </glossentry> 2635 2636 <glossentry> 2637 <glossterm>--recursive</glossterm> 2638 2639 <glossdef> 2640 <para>Recursively copies files/directories.</para> 2641 </glossdef> 2642 </glossentry> 2643 2644 <glossentry> 2645 <glossterm>--verbose</glossterm> 2646 2647 <glossdef> 2648 <para>Tells VBoxManage to be more verbose during the copy 2649 operation.</para> 2650 </glossdef> 2651 </glossentry> 2652 2653 <glossentry> 2654 <glossterm>--flags <flags></glossterm> 2655 2656 <glossdef> 2657 <para>Additional flags to set. This is not used at the 2658 moment.</para> 2659 </glossdef> 2660 </glossentry> 2661 </glosslist></para> 2662 </listitem> 2663 2664 <listitem> 2665 <para><computeroutput>updateadditions</computeroutput>, which allows 2666 for updating an already installed Guest Additions version on the 2667 guest (only already installed Guest Additions 4.0 and later).</para> 2679 2668 2680 2669 <screen>VBoxManage guestcontrol updateadditions <vmname>|<uuid> … … 2682 2671 2683 2672 <para>where the parameters mean: <glosslist> 2684 <glossentry> 2685 <glossterm>uuid|vmname</glossterm> 2686 2687 <glossdef> 2688 <para>The VM UUID or VM name. Mandatory.</para> 2689 </glossdef> 2690 </glossentry> 2691 2692 <glossentry> 2693 <glossterm>--source "<guest additions .ISO file to use>"</glossterm> 2694 2695 <glossdef> 2696 <para>Full path to an alternative VirtualBox Guest Additions .ISO file to use 2697 for the Guest Additions update.</para> 2698 </glossdef> 2699 </glossentry> 2700 2701 <glossentry> 2702 <glossterm>--verbose</glossterm> 2703 2704 <glossdef> 2705 <para>Tells VBoxManage to be more verbose during the 2706 update.</para> 2707 </glossdef> 2708 </glossentry> 2709 2710 </glosslist> 2711 </para> 2712 </listitem> 2713 2714 </itemizedlist></para> 2673 <glossentry> 2674 <glossterm>uuid|vmname</glossterm> 2675 2676 <glossdef> 2677 <para>The VM UUID or VM name. Mandatory.</para> 2678 </glossdef> 2679 </glossentry> 2680 2681 <glossentry> 2682 <glossterm>--source "<guest additions .ISO file to 2683 use>"</glossterm> 2684 2685 <glossdef> 2686 <para>Full path to an alternative VirtualBox Guest Additions 2687 .ISO file to use for the Guest Additions update.</para> 2688 </glossdef> 2689 </glossentry> 2690 2691 <glossentry> 2692 <glossterm>--verbose</glossterm> 2693 2694 <glossdef> 2695 <para>Tells VBoxManage to be more verbose during the 2696 update.</para> 2697 </glossdef> 2698 </glossentry> 2699 </glosslist></para> 2700 </listitem> 2701 </itemizedlist></para> 2715 2702 </sect1> 2716 2703
Note:
See TracChangeset
for help on using the changeset viewer.
