VirtualBox

source: vbox/trunk/doc/manual/en_US/user_VBoxManage.xml@ 44553

Last change on this file since 44553 was 44553, checked in by vboxsync, 12 years ago

Main/doc: prefer <HOME>/.config/VirtualBox over <HOME>/.VirtualBox for new users on platforms where XDG is relevant, user manual and change log changes.

File size: 156.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4<chapter id="vboxmanage">
5 <title>VBoxManage</title>
6
7 <sect1>
8 <title>Introduction</title>
9
10 <para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
11 the command-line interface to VirtualBox. With it, you can completely
12 control VirtualBox from the command line of your host operating system.
13 VBoxManage supports all the features that the graphical user interface
14 gives you access to, but it supports a lot more than that. It exposes
15 really all the features of the virtualization engine, even those that
16 cannot (yet) be accessed from the GUI.</para>
17
18 <para>You will need to use the command line if you want to</para>
19
20 <para><itemizedlist>
21 <listitem>
22 <para>use a different user interface than the main GUI (for example,
23 VBoxSDL or the VBoxHeadless server);</para>
24 </listitem>
25
26 <listitem>
27 <para>control some of the more advanced and experimental
28 configuration settings for a VM.</para>
29 </listitem>
30 </itemizedlist></para>
31
32 <para>There are two main things to keep in mind when using
33 <computeroutput>VBoxManage</computeroutput>: First,
34 <computeroutput>VBoxManage</computeroutput> must always be used with a
35 specific "subcommand", such as "list" or "createvm" or "startvm". All the
36 subcommands that <computeroutput>VBoxManage</computeroutput> supports are
37 described in detail in <xref linkend="vboxmanage" />.</para>
38
39 <para>Second, most of these subcommands require that you specify a
40 particular virtual machine after the subcommand. There are two ways you
41 can do this:</para>
42
43 <itemizedlist>
44 <listitem>
45 <para>You can specify the VM name, as it is shown in the VirtualBox
46 GUI. Note that if that name contains spaces, then you must enclose the
47 entire name in double quotes (as it is always required with command
48 line arguments that contain spaces).</para>
49
50 <para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
51 </listitem>
52
53 <listitem>
54 <para>You can specify the UUID, which is the internal unique
55 identifier that VirtualBox uses to refer to the virtual machine.
56 Assuming that the aforementioned VM called "Windows XP" has the UUID
57 shown below, the following command has the same effect as the
58 previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
59 </listitem>
60 </itemizedlist>
61
62 <para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
63 have all currently registered VMs listed with all their settings,
64 including their respective names and UUIDs.</para>
65
66 <para>Some typical examples of how to control VirtualBox from the command
67 line are listed below:</para>
68
69 <itemizedlist>
70 <listitem>
71 <para>To create a new virtual machine from the command line and
72 immediately register it with VirtualBox, use
73 <computeroutput>VBoxManage createvm</computeroutput> with the
74 <computeroutput>--register</computeroutput> option,<footnote>
75 <para>For details, see <xref
76 linkend="vboxmanage-createvm" />.</para>
77 </footnote> like this:</para>
78
79 <screen>$ VBoxManage createvm --name "SUSE 10.2" --register
80VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
81(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
82All rights reserved.
83
84Virtual machine 'SUSE 10.2' is created.
85UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
86Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'
87</screen>
88
89 <para>As can be seen from the above output, a new virtual machine has
90 been created with a new UUID and a new XML settings file.</para>
91 </listitem>
92
93 <listitem>
94 <para>To show the configuration of a particular VM, use
95 <computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
96 linkend="vboxmanage-showvminfo" /> for details and an example.</para>
97 </listitem>
98
99 <listitem>
100 <para>To change settings while a VM is powered off, use
101 <computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
102 follows:<screen>VBoxManage modifyvm "Windows XP" --memory "512MB"</screen></para>
103
104 <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
105 </listitem>
106
107 <listitem>
108 <para>To change the storage configuration (e.g. to add a storage
109 controller and then a virtual disk), use <computeroutput>VBoxManage
110 storagectl</computeroutput> and <computeroutput>VBoxManage
111 storageattach</computeroutput>; see <xref
112 linkend="vboxmanage-storagectl" /> and <xref
113 linkend="vboxmanage-storageattach" /> for details.</para>
114 </listitem>
115
116 <listitem>
117 <para>To control VM operation, use one of the following:<itemizedlist>
118 <listitem>
119 <para>To start a VM that is currently powered off, use
120 <computeroutput>VBoxManage startvm</computeroutput>; see <xref
121 linkend="vboxmanage-startvm" /> for details.</para>
122 </listitem>
123
124 <listitem>
125 <para>To pause or save a VM that is currently running or change
126 some of its settings, use <computeroutput>VBoxManage
127 controlvm</computeroutput>; see <xref
128 linkend="vboxmanage-controlvm" /> for details.</para>
129 </listitem>
130 </itemizedlist></para>
131 </listitem>
132 </itemizedlist>
133 </sect1>
134
135 <sect1>
136 <title>Commands overview</title>
137
138 <para>When running VBoxManage without parameters or when supplying an
139 invalid command line, the below syntax diagram will be shown. Note that
140 the output will be slightly different depending on the host platform; when
141 in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
142 for the commands available on your particular host.</para>
143
144 <screen>$VBOX_MANAGE_OUTPUT</screen>
145
146 <para>Each time VBoxManage is invoked, only one command can be executed.
147 However, a command might support several subcommands which then can be
148 invoked in one single call. The following sections provide detailed
149 reference information on the different commands.</para>
150 </sect1>
151
152 <sect1 id="vboxmanage-general">
153 <title>General options</title>
154 <para>
155 <itemizedlist>
156 <listitem>
157 <para><computeroutput>--version</computeroutput>: show the version of
158 this tool and exit.</para>
159 </listitem>
160 <listitem>
161 <para><computeroutput>--nologo</computeroutput>: suppress the output
162 of the logo information (useful for scripts)</para>
163 </listitem>
164 <listitem>
165 <para><computeroutput>--settingspw</computeroutput>: specifiy a settings
166 password</para>
167 </listitem>
168 <listitem>
169 <para><computeroutput>--settingspwfile</computeroutput>: specify a file
170 containing the settings password.</para>
171 </listitem>
172 </itemizedlist>
173 The settings password is used for certain settings which need to be
174 stored encrypted for security reasons. At the moment, the only encrypted
175 setting is the iSCSI initiator secret (see
176 <xref linkend="vboxmanage-storageattach" /> for details). As long as no
177 settings password is specified, this information is stored in
178 <emphasis role="bold">plain text</emphasis>. After using the
179 <computeroutput>--settingspw|--settingspwfile</computeroutput> option
180 once, it must be always used, otherwise the encrypted setting cannot
181 be unencrypted.
182 </para>
183 </sect1>
184
185 <sect1 id="vboxmanage-list">
186 <title>VBoxManage list</title>
187
188 <para>The <computeroutput>list</computeroutput> command gives relevant
189 information about your system and information about VirtualBox's current
190 settings.</para>
191
192 <para>The following subcommands are available with
193 <computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
194 <listitem>
195 <para><computeroutput>vms</computeroutput> lists all virtual
196 machines currently registered with VirtualBox. By default this
197 displays a compact list with each VM's name and UUID; if you also
198 specify <computeroutput>--long</computeroutput> or
199 <computeroutput>-l</computeroutput>, this will be a detailed list as
200 with the <computeroutput>showvminfo</computeroutput> command (see
201 below).</para>
202 </listitem>
203
204 <listitem>
205 <para><computeroutput>runningvms</computeroutput> lists all
206 currently running virtual machines by their unique identifiers
207 (UUIDs) in the same format as with
208 <computeroutput>vms</computeroutput>.</para>
209 </listitem>
210
211 <listitem>
212 <para><computeroutput>ostypes</computeroutput> lists all guest
213 operating systems presently known to VirtualBox, along with the
214 identifiers used to refer to them with the
215 <computeroutput>modifyvm</computeroutput> command.</para>
216 </listitem>
217
218 <listitem>
219 <para><computeroutput>hostdvds</computeroutput>,
220 <computeroutput>hostfloppies</computeroutput>, respectively, list
221 DVD, floppy, bridged networking and host-only networking interfaces
222 on the host, along with the name used to access them from within
223 VirtualBox.</para>
224 </listitem>
225
226 <listitem>
227 <para><computeroutput>bridgedifs</computeroutput>,
228 <computeroutput>hostonlyifs</computeroutput> and
229 <computeroutput>dhcpservers</computeroutput>, respectively, list
230 bridged network interfaces, host-only network interfaces and DHCP
231 servers currently available on the host. Please see <xref
232 linkend="networkingdetails" /> for details on these.</para>
233 </listitem>
234
235 <listitem>
236 <para><computeroutput>hostinfo</computeroutput> displays information
237 about the host system, such as CPUs, memory size and operating
238 system version.</para>
239 </listitem>
240
241 <listitem>
242 <para><computeroutput>hostcpuids</computeroutput> dumps the CPUID
243 parameters for the host CPUs. This can be used for a more fine
244 grained analyis of the host's virtualization capabilities.</para>
245 </listitem>
246
247 <listitem>
248 <para><computeroutput>hddbackends</computeroutput> lists all known
249 virtual disk back-ends of VirtualBox. For each such format (such as
250 VDI, VMDK or RAW), this lists the back-end's capabilities and
251 configuration.</para>
252 </listitem>
253
254 <listitem>
255 <para><computeroutput>hdds</computeroutput>,
256 <computeroutput>dvds</computeroutput> and
257 <computeroutput>floppies</computeroutput> all give you information
258 about virtual disk images currently in use by VirtualBox, including
259 all their settings, the unique identifiers (UUIDs) associated with
260 them by VirtualBox and all files associated with them. This is the
261 command-line equivalent of the Virtual Media Manager; see <xref
262 linkend="vdis" />.</para>
263 </listitem>
264
265 <listitem>
266 <para><computeroutput>usbhost</computeroutput> supplies information
267 about USB devices attached to the host, notably information useful
268 for constructing USB filters and whether they are currently in use
269 by the host.</para>
270 </listitem>
271
272 <listitem>
273 <para><computeroutput>usbfilters</computeroutput> lists all global
274 USB filters registered with VirtualBox -- that is, filters for
275 devices which are accessible to all virtual machines -- and displays
276 the filter parameters.</para>
277 </listitem>
278
279 <listitem>
280 <para><computeroutput>systemproperties</computeroutput> displays
281 some global VirtualBox settings, such as minimum and maximum guest
282 RAM and virtual hard disk size, folder settings and the current
283 authentication library in use.</para>
284 </listitem>
285
286 <listitem>
287 <para><computeroutput>extpacks</computeroutput> displays all
288 VirtualBox extension packs currently installed; see <xref
289 linkend="intro-installing" /> and <xref
290 linkend="vboxmanage-extpack" /> for more information.</para>
291 </listitem>
292 </itemizedlist></para>
293 </sect1>
294
295 <sect1 id="vboxmanage-showvminfo">
296 <title>VBoxManage showvminfo</title>
297
298 <para>The <computeroutput>showvminfo</computeroutput> command shows
299 information about a particular virtual machine. This is the same
300 information as <computeroutput>VBoxManage list vms --long</computeroutput>
301 would show for all virtual machines.</para>
302
303 <para>You will get information similar to the following:</para>
304
305 <para><screen>$ VBoxManage showvminfo "Windows XP"
306VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
307(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
308All rights reserved.
309
310Name: Windows XP
311Guest OS: Other/Unknown
312UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
313Config file: /home/username/.config/VirtualBox/Machines/Windows XP/Windows XP.xml
314Memory size: 512MB
315VRAM size: 12MB
316Number of CPUs: 2
317Synthetic Cpu: off
318Boot menu mode: message and menu
319Boot Device (1): DVD
320Boot Device (2): HardDisk
321Boot Device (3): Not Assigned
322Boot Device (4): Not Assigned
323ACPI: on
324IOAPIC: on
325PAE: on
326Time offset: 0 ms
327Hardw. virt.ext: on
328Hardw. virt.ext exclusive: on
329Nested Paging: on
330VT-x VPID: off
331State: powered off (since 2009-10-20T14:52:19.000000000)
332Monitor count: 1
3333D Acceleration: off
3342D Video Acceleration: off
335Teleporter Enabled: off
336Teleporter Port: 0
337Teleporter Address:
338Teleporter Password:
339Storage Controller (0): IDE Controller
340Storage Controller Type (0): PIIX4
341Storage Controller (1): Floppy Controller 1
342Storage Controller Type (1): I82078
343IDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b)
344IDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b)
345Floppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137)
346NIC 1: disabled
347NIC 2: disabled
348NIC 3: disabled
349NIC 4: disabled
350NIC 5: disabled
351NIC 6: disabled
352NIC 7: disabled
353NIC 8: disabled
354UART 1: disabled
355UART 2: disabled
356Audio: disabled (Driver: Unknown)
357Clipboard Mode: Bidirectional
358VRDE: disabled
359USB: disabled
360
361USB Device Filters:
362&lt;none&gt;
363
364Shared folders:
365&lt;none&gt;
366
367Statistics update: disabled
368</screen></para>
369 </sect1>
370
371 <sect1 id="vboxmanage-registervm">
372 <title>VBoxManage registervm / unregistervm</title>
373
374 <para>The <computeroutput>registervm</computeroutput> command allows you
375 to import a virtual machine definition in an XML file into VirtualBox. The
376 machine must not conflict with one already registered in VirtualBox and it
377 may not have any hard or removable disks attached. It is advisable to
378 place the definition file in the machines folder before registering
379 it.<note>
380 <para>When creating a new virtual machine with
381 <computeroutput>VBoxManage createvm</computeroutput> (see below), you
382 can directly specify the <computeroutput>--register</computeroutput>
383 option to avoid having to register it separately.</para>
384 </note></para>
385
386 <para>The <computeroutput>unregistervm</computeroutput> command
387 unregisters a virtual machine. If
388 <computeroutput>--delete</computeroutput> is also specified, the following
389 files will automatically be deleted as well:<orderedlist>
390 <listitem>
391 <para>all hard disk image files, including differencing files, which
392 are used by the machine and not shared with other machines;</para>
393 </listitem>
394
395 <listitem>
396 <para>saved state files that the machine created, if any (one if the
397 machine was in "saved" state and one for each online
398 snapshot);</para>
399 </listitem>
400
401 <listitem>
402 <para>the machine XML file and its backups;</para>
403 </listitem>
404
405 <listitem>
406 <para>the machine log files, if any;</para>
407 </listitem>
408
409 <listitem>
410 <para>the machine directory, if it is empty after having deleted all
411 the above.</para>
412 </listitem>
413 </orderedlist></para>
414 </sect1>
415
416 <sect1>
417 <title id="vboxmanage-createvm">VBoxManage createvm</title>
418
419 <para>This command creates a new XML virtual machine definition
420 file.</para>
421
422 <para>The <computeroutput>--name &lt;name&gt;</computeroutput> parameter
423 is required and must specify the name of the machine. Since this name is
424 used by default as the file name of the settings file (with the extension
425 <computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
426 of the <computeroutput>.config/VirtualBox/Machines</computeroutput> folder - this folder name may vary depending on the operating system and the version of VirtualBox which you are using), it
427 must conform to your host operating system's requirements for file name
428 specifications. If the VM is later renamed, the file and folder names will
429 change automatically.</para>
430
431 <para>However, if the <computeroutput>--basefolder
432 &lt;path&gt;</computeroutput> option is used, the machine folder will be
433 named <computeroutput>&lt;path&gt;</computeroutput>. In this case, the
434 names of the file and the folder will not change if the virtual machine is
435 renamed.</para>
436
437 <para>By default, this command only creates the XML file without
438 automatically registering the VM with your VirtualBox installation. To
439 register the VM instantly, use the optional
440 <computeroutput>--register</computeroutput> option, or run
441 <computeroutput>VBoxManage registervm</computeroutput> separately
442 afterwards.</para>
443 </sect1>
444
445 <sect1 id="vboxmanage-modifyvm">
446 <title>VBoxManage modifyvm</title>
447
448 <para>This command changes the properties of a registered virtual machine
449 which is not running. Most of the properties that this command makes
450 available correspond to the VM settings that VirtualBox graphical user
451 interface displays in each VM's "Settings" dialog; these were described in
452 <xref linkend="BasicConcepts" />. Some of the more advanced settings,
453 however, are only available through the
454 <computeroutput>VBoxManage</computeroutput> interface.</para>
455
456 <para>These commands require that the machine is powered off (neither
457 running nor in "saved" state). Some machine settings can also be changed
458 while a machine is running; those settings will then have a corresponding
459 subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
460 subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
461
462 <sect2>
463 <title>General settings</title>
464
465 <para>The following general settings are available through
466 <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
467 <listitem>
468 <para><computeroutput>--name &lt;name&gt;</computeroutput>: This
469 changes the VM's name and possibly renames the internal virtual
470 machine files, as described with <computeroutput>VBoxManage
471 createvm</computeroutput> above.</para>
472 </listitem>
473
474 <listitem>
475 <para><computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
476 This specifies what guest operating system is supposed to run in
477 the VM. To learn about the various identifiers that can be used
478 here, use <computeroutput>VBoxManage list
479 ostypes</computeroutput>.</para>
480 </listitem>
481
482 <listitem>
483 <para><computeroutput>--memory
484 &lt;memorysize&gt;</computeroutput>: This sets the amount of RAM,
485 in MB, that the virtual machine should allocate for itself from
486 the host. See the remarks in <xref linkend="gui-createvm" /> for
487 more information.</para>
488 </listitem>
489
490 <listitem>
491 <para><computeroutput>--vram &lt;vramsize&gt;</computeroutput>:
492 This sets the amount of RAM that the virtual graphics card should
493 have. See <xref linkend="settings-display" /> for details.</para>
494 </listitem>
495
496 <listitem>
497 <para><computeroutput>--acpi on|off</computeroutput>;
498 <computeroutput>--ioapic on|off</computeroutput>: These two
499 determine whether the VM should have ACPI and I/O APIC support,
500 respectively; see <xref linkend="settings-motherboard" /> for
501 details.</para>
502 </listitem>
503
504 <listitem>
505 <para><computeroutput>--hardwareuuid
506 &lt;uuid&gt;</computeroutput>: The UUID presented to the guest via
507 memory tables (DMI/SMBIOS), hardware and guest properties. By
508 default this is the same as the VM uuid. Useful when cloning a VM.
509 Teleporting takes care of this automatically.</para>
510 </listitem>
511
512 <listitem>
513 <para><computeroutput>--cpus &lt;cpucount&gt;</computeroutput>:
514 This sets the number of virtual CPUs for the virtual machine (see
515 <xref linkend="settings-processor" />). If CPU hot-plugging is
516 enabled (see below), this then sets the
517 <emphasis>maximum</emphasis> number of virtual CPUs that can be
518 plugged into the virtual machines.</para>
519 </listitem>
520
521 <listitem>
522 <para><computeroutput>--rtcuseutc on|off</computeroutput>: This
523 option lets the real-time clock (RTC) operate in UTC time (see
524 <xref linkend="settings-motherboard" />).</para>
525 </listitem>
526
527 <listitem>
528 <para><computeroutput>--cpuhotplug on|off</computeroutput>: This
529 enables CPU hot-plugging. When enabled, virtual CPUs can be added
530 to and removed from a virtual machine while it is running. See
531 <xref linkend="cpuhotplug" /> for more information.</para>
532 </listitem>
533
534 <listitem>
535 <para><computeroutput>--plugcpu|unplugcpu
536 &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled (see
537 above), this adds a virtual CPU to the virtual machines (or
538 removes one). <computeroutput>&lt;id&gt;</computeroutput>
539 specifies the index of the virtual CPU to be added or removed and
540 must be a number from 0 to the maximum no. of CPUs configured with
541 the <computeroutput>--cpus</computeroutput> option. CPU 0 can
542 never be removed.</para>
543 </listitem>
544
545 <listitem>
546 <para><computeroutput>--cpuexecutioncap
547 &lt;1-100&gt;</computeroutput>: This setting controls how much cpu
548 time a virtual CPU can use. A value of 50 implies a single virtual
549 CPU can use up to 50% of a single host CPU.</para>
550 </listitem>
551
552 <listitem>
553 <para><computeroutput>--synthcpu on|off</computeroutput>: This
554 setting determines whether VirtualBox will expose a synthetic CPU
555 to the guest to allow live migration between host systems that
556 differ significantly.</para>
557 </listitem>
558
559 <listitem>
560 <para><computeroutput>--pae on|off</computeroutput>: This
561 enables/disables PAE (see <xref
562 linkend="settings-processor" />).</para>
563 </listitem>
564
565 <listitem>
566 <para><computeroutput>--hpet on|off</computeroutput>: This
567 enables/disables a High Precision Event Timer (HPET) which can
568 replace the legacy system timers. This is turned off by default.
569 Note that Windows supports a HPET only from Vista onwards.</para>
570 </listitem>
571
572 <listitem>
573 <para><computeroutput>--hwvirtex on|off</computeroutput>: This
574 enables or disables the use of hardware virtualization extensions
575 (Intel VT-x or AMD-V) in the processor of your host system; see
576 <xref linkend="hwvirt" />.</para>
577 </listitem>
578
579 <listitem>
580 <para><computeroutput>--hwvirtexexcl on|off</computeroutput>: This
581 specifies whether VirtualBox will make exclusive use of the
582 hardware virtualization extensions (Intel VT-x or AMD-V) in the
583 processor of your host system; see <xref linkend="hwvirt" />. If
584 you wish to simultaneously share these extensions with other
585 hypervisors, then you must disable this setting. Doing so has
586 negative performance implications.</para>
587 </listitem>
588
589 <listitem>
590 <para><computeroutput>--nestedpaging on|off</computeroutput>: If
591 hardware virtualization is enabled, this additional setting
592 enables or disables the use of the nested paging feature in the
593 processor of your host system; see <xref
594 linkend="hwvirt" />.</para>
595 </listitem>
596
597 <listitem>
598 <para><computeroutput>--largepages on|off</computeroutput>: If
599 hardware virtualization <emphasis>and</emphasis> nested paging are
600 enabled, for Intel VT-x only, an additional performance
601 improvement of up to 5% can be obtained by enabling this setting.
602 This causes the hypervisor to use large pages to reduce TLB use
603 and overhead.</para>
604 </listitem>
605
606 <listitem>
607 <para><computeroutput>--vtxvpid on|off</computeroutput>: If
608 hardware virtualization is enabled, for Intel VT-x only, this
609 additional setting enables or disables the use of the tagged TLB
610 (VPID) feature in the processor of your host system; see <xref
611 linkend="hwvirt" />.</para>
612 </listitem>
613
614 <listitem>
615 <para><computeroutput>--accelerate3d on|off</computeroutput>: This
616 enables, if the Guest Additions are installed, whether hardware 3D
617 acceleration should be available; see <xref
618 linkend="guestadd-3d" />.</para>
619 </listitem>
620
621 <listitem>
622 <para>You can influence the BIOS logo that is displayed when a
623 virtual machine starts up with a number of settings. Per default,
624 a VirtualBox logo is displayed.</para>
625
626 <para>With <computeroutput>--bioslogofadein
627 on|off</computeroutput> and <computeroutput>--bioslogofadeout
628 on|off</computeroutput>, you can determine whether the logo should
629 fade in and out, respectively.</para>
630
631 <para>With <computeroutput>--bioslogodisplaytime
632 &lt;msec&gt;</computeroutput> you can set how long the logo should
633 be visible, in milliseconds.</para>
634
635 <para>With <computeroutput>--bioslogoimagepath
636 &lt;imagepath&gt;</computeroutput> you can, if you are so
637 inclined, replace the image that is shown, with your own logo. The
638 image must be an uncompressed 256 color BMP file.</para>
639 </listitem>
640
641 <listitem>
642 <para><computeroutput>--biosbootmenu
643 disabled|menuonly|messageandmenu</computeroutput>: This specifies
644 whether the BIOS allows the user to select a temporary boot
645 device. <computeroutput>menuonly</computeroutput> suppresses the
646 message, but the user can still press F12 to select a temporary
647 boot device.</para>
648 </listitem>
649
650 <listitem>
651 <para><computeroutput>--nicbootprio&lt;1-N&gt;
652 &lt;priority&gt;</computeroutput>: This specifies the order in which
653 NICs are tried for booting over the network (using PXE). The
654 priority is an integer in the 0 to 4 range. Priority 1 is the
655 highest, priority 4 is low. Priority 0, which is the default unless
656 otherwise specified, is the lowest.
657 </para>
658 <para> Note that this option only has effect when the Intel PXE boot
659 ROM is used.
660 </para>
661 </listitem>
662
663 <listitem>
664 <para><computeroutput>--boot&lt;1-4&gt;
665 none|floppy|dvd|disk|net</computeroutput>: This specifies the boot
666 order for the virtual machine. There are four "slots", which the
667 VM will try to access from 1 to 4, and for each of which you can
668 set a device that the VM should attempt to boot from.</para>
669 </listitem>
670
671 <listitem>
672 <para><computeroutput>--snapshotfolder
673 default|&lt;path&gt;</computeroutput>: This allows you to specify
674 the folder in which snapshots will be kept for a virtual
675 machine.</para>
676 </listitem>
677
678 <listitem>
679 <para><computeroutput>--firmware efi|bios</computeroutput>:
680 Specifies which firmware is used to boot particular virtual
681 machine: EFI or BIOS. Use EFI only if your fully understand what
682 you're doing.</para>
683 </listitem>
684
685 <listitem>
686 <para><computeroutput>--guestmemoryballoon
687 &lt;size&gt;</computeroutput> sets the default size of the guest
688 memory balloon, that is, memory allocated by the VirtualBox Guest
689 Additions from the guest operating system and returned to the
690 hypervisor for re-use by other virtual machines. &lt;size&gt; must
691 be specified in megabytes. The default size is 0 megabytes. For
692 details, see <xref linkend="guestadd-balloon" />.</para>
693 </listitem>
694
695 <listitem>
696 <para><computeroutput>--lptmode&lt;1-N&gt;
697 &lt;Device&gt;</computeroutput>
698 Specifies the Device Name of the parallel port that
699 the Parallel Port feature will be using. Use this
700 <emphasis>before</emphasis> <computeroutput>--lpt</computeroutput>.
701 This feature is host operating system specific.</para>
702 </listitem>
703
704 <listitem>
705 <para><computeroutput>--lpt&lt;1-N&gt;
706 &lt;I/O base&gt; &lt;IRQ&gt;</computeroutput>
707 Specifies the I/O address of the parallel port and the IRQ
708 number that the Parallel Port feature will be using. Use this
709 <emphasis>after</emphasis>
710 <computeroutput>--lptmod</computeroutput>. I/O base address and IRQ are
711 the values that guest sees i.e. the values avalable under guest Device Manager.</para>
712 </listitem>
713 </itemizedlist></para>
714 </sect2>
715
716 <sect2>
717 <title>Networking settings</title>
718
719 <para>The following networking settings are available through
720 <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
721 settings, the decimal number directly following the option name ("1-N"
722 in the list below) specifies the virtual network adapter whose settings
723 should be changed.<itemizedlist>
724 <listitem>
725 <para><computeroutput>--nic&lt;1-N&gt;
726 none|null|nat|bridged|intnet|hostonly|generic
727 </computeroutput>: With
728 this, you can set, for each of the VM's virtual network cards,
729 what type of networking should be available. They can be not
730 present (<computeroutput>none</computeroutput>), not connected to
731 the host (<computeroutput>null</computeroutput>), use network
732 address translation (<computeroutput>nat</computeroutput>),
733 bridged networking (<computeroutput>bridged</computeroutput>) or
734 communicate with other virtual machines using internal networking
735 (<computeroutput>intnet</computeroutput>), host-only networking
736 (<computeroutput>hostonly</computeroutput>), or access rarely used
737 sub-modes (<computeroutput>generic</computeroutput>).
738 These options correspond
739 to the modes which are described in detail in <xref
740 linkend="networkingmodes" />.</para>
741 </listitem>
742
743 <listitem>
744 <para><computeroutput>--nictype&lt;1-N&gt;
745 Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
746 This allows you, for each of the VM's virtual network cards, to
747 specify which networking hardware VirtualBox presents to the
748 guest; see <xref linkend="nichardware" />.</para>
749 </listitem>
750
751 <listitem>
752 <para><computeroutput>--cableconnected&lt;1-N&gt;
753 on|off</computeroutput>: This allows you to temporarily disconnect
754 a virtual network interface, as if a network cable had been pulled
755 from a real network card. This might be useful for resetting
756 certain software components in the VM.</para>
757 </listitem>
758
759 <listitem>
760 <para>With the "nictrace" options, you can optionally trace
761 network traffic by dumping it to a file, for debugging
762 purposes.</para>
763
764 <para>With <computeroutput>--nictrace&lt;1-N&gt;
765 on|off</computeroutput>, you can enable network tracing for a
766 particular virtual network card.</para>
767
768 <para>If enabled, you must specify with
769 <computeroutput>--nictracefile&lt;1-N&gt;
770 &lt;filename&gt;</computeroutput> what file the trace should be
771 logged to.</para>
772 </listitem>
773
774 <listitem>
775 <para><computeroutput>--bridgeadapter&lt;1-N&gt;
776 none|&lt;devicename&gt;</computeroutput>: If bridged networking
777 has been enabled for a virtual network card (see the
778 <computeroutput>--nic</computeroutput> option above; otherwise
779 this setting has no effect), use this option to specify which host
780 interface the given virtual network interface will use. For
781 details, please see <xref linkend="network_bridged" />.</para>
782 </listitem>
783
784 <listitem>
785 <para><computeroutput>--hostonlyadapter&lt;1-N&gt;
786 none|&lt;devicename&gt;</computeroutput>: If host-only networking
787 has been enabled for a virtual network card (see the --nic option
788 above; otherwise this setting has no effect), use this option to
789 specify which host-only networking interface the given virtual
790 network interface will use. For details, please see <xref
791 linkend="network_hostonly" />.</para>
792 </listitem>
793
794 <listitem>
795 <para><computeroutput>--intnet&lt;1-N&gt;
796 network</computeroutput>: If internal networking has been enabled
797 for a virtual network card (see the
798 <computeroutput>--nic</computeroutput> option above; otherwise
799 this setting has no effect), use this option to specify the name
800 of the internal network (see <xref
801 linkend="network_internal" />).</para>
802 </listitem>
803
804 <listitem>
805 <para><computeroutput>--macaddress&lt;1-N&gt;
806 auto|&lt;mac&gt;</computeroutput>: With this option you can set
807 the MAC address of the virtual network card. Normally, each
808 virtual network card is assigned a random address by VirtualBox at
809 VM creation.</para>
810 </listitem>
811
812 <listitem>
813 <para><computeroutput>--nicgenericdrv&lt;1-N&gt;
814 &lt;backend driver&gt;</computeroutput>: If generic networking has been
815 enabled for a virtual network card (see the
816 <computeroutput>--nic</computeroutput> option above; otherwise
817 this setting has no effect), this mode allows you to access
818 rarely used networking sub-modes, such as VDE network or UDP Tunnel.
819 </para>
820 </listitem>
821
822 <listitem>
823 <para><computeroutput>--nicproperty&lt;1-N&gt;
824 &lt;paramname&gt;="paramvalue"</computeroutput>:
825 This option, in combination with "nicgenericdrv" allows you to
826 pass parameters to rarely-used network backends.</para><para>
827 Those parameters are backend engine-specific, and are different
828 between UDP Tunnel and the VDE backend drivers. For example,
829 please see <xref linkend="network_udp_tunnel" />.
830 </para>
831 </listitem>
832 </itemizedlist></para>
833
834 <sect3>
835 <title>NAT Networking settings.</title>
836
837 <para>The following NAT networking settings are available through
838 <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
839 settings, the decimal number directly following the option name ("1-N"
840 in the list below) specifies the virtual network adapter whose
841 settings should be changed.<itemizedlist>
842 <listitem>
843 <para><computeroutput>--natpf&lt;1-N&gt;
844 [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
845 &lt;guestport&gt;</computeroutput>: This option defines a NAT
846 port-forwarding rule (please see <xref linkend="natforward" />
847 for details).</para>
848 </listitem>
849
850 <listitem>
851 <para><computeroutput>--natpf&lt;1-N&gt; delete
852 &lt;name&gt;</computeroutput>: This option deletes a NAT
853 port-forwarding rule (please see <xref linkend="natforward" />
854 for details).</para>
855 </listitem>
856
857 <listitem>
858 <para><computeroutput>--nattftpprefix&lt;1-N&gt;
859 &lt;prefix&gt;</computeroutput>: This option defines a prefix
860 for the built-in TFTP server, i.e. where the boot file is
861 located (please see <xref linkend="nat-tftp" /> and <xref
862 linkend="nat-adv-tftp" /> for details).</para>
863 </listitem>
864
865 <listitem>
866 <para><computeroutput>--nattftpfile&lt;1-N&gt;
867 &lt;bootfile&gt;</computeroutput>: This option defines the TFT
868 boot file (please see <xref linkend="nat-adv-tftp" /> for
869 details).</para>
870 </listitem>
871
872 <listitem>
873 <para><computeroutput>--nattftpserver&lt;1-N&gt;
874 &lt;tftpserver&gt;</computeroutput>: This option defines the
875 TFTP server address to boot from (please see <xref
876 linkend="nat-adv-tftp" /> for details).</para>
877 </listitem>
878
879 <listitem>
880 <para><computeroutput>--natdnspassdomain&lt;1-N&gt;
881 on|off</computeroutput>: This option specifies whether the
882 built-in DHCP server passes the domain name for network name
883 resolution.</para>
884 </listitem>
885
886 <listitem>
887 <para><computeroutput>--natdnsproxy&lt;1-N&gt;
888 on|off</computeroutput>: This option makes the NAT engine proxy
889 all guest DNS requests to the host's DNS servers (please see
890 <xref linkend="nat-adv-dns" /> for details).</para>
891 </listitem>
892
893 <listitem>
894 <para><computeroutput>--natdnshostresolver&lt;1-N&gt;
895 on|off</computeroutput>: This option makes the NAT engine use
896 the host's resolver mechanisms to handle DNS requests (please
897 see <xref linkend="nat-adv-dns" /> for details).</para>
898 </listitem>
899
900 <listitem>
901 <para><computeroutput>--natnatsettings&lt;1-N&gt;
902 [&lt;mtu&gt;],[&lt;socksnd&gt;],[&lt;sockrcv&gt;],[&lt;tcpsnd&gt;],
903 [&lt;tcprcv&gt;]</computeroutput>: This option controls several
904 NAT settings (please see <xref linkend="nat-adv-settings" /> for
905 details).</para>
906 </listitem>
907
908 <listitem>
909 <para><computeroutput>--nataliasmode&lt;1-N&gt;
910 default|[log],[proxyonly],[sameports]</computeroutput>: This
911 option defines behaviour of NAT engine core: log - enables
912 logging, proxyonly - switches of aliasing mode makes NAT
913 transparent, sameports enforces NAT engine to send packets via
914 the same port as they originated on, default - disable all
915 mentioned modes above . (please see <xref
916 linkend="nat-adv-alias" /> for details).</para>
917 </listitem>
918 </itemizedlist></para>
919 </sect3>
920 </sect2>
921
922 <sect2 id="vboxmanage-modifyvm-other">
923 <title>Serial port, audio, clipboard, remote desktop and USB
924 settings</title>
925
926 <para>The following other hardware settings are available through
927 <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
928 <listitem>
929 <para><computeroutput>--uart&lt;1-N&gt; off|&lt;I/O base&gt;
930 &lt;IRQ&gt;</computeroutput>: With this option you can configure
931 virtual serial ports for the VM; see <xref
932 linkend="serialports" /> for an introduction.</para>
933 </listitem>
934
935 <listitem>
936 <para><computeroutput>--uartmode&lt;1-N&gt;
937 &lt;arg&gt;</computeroutput>: This setting controls how VirtualBox
938 connects a given virtual serial port (previously configured with
939 the <computeroutput>--uartX</computeroutput> setting, see above)
940 to the host on which the virtual machine is running. As described
941 in detail in <xref linkend="serialports" />, for each such port,
942 you can specify <computeroutput>&lt;arg&gt;</computeroutput> as
943 one of the following options:<itemizedlist>
944 <listitem>
945 <para><computeroutput>disconnected</computeroutput>: Even
946 though the serial port is shown to the guest, it has no
947 "other end" -- like a real COM port without a cable.</para>
948 </listitem>
949
950 <listitem>
951 <para><computeroutput>server
952 &lt;pipename&gt;</computeroutput>: On a Windows host, this
953 tells VirtualBox to create a named pipe on the host named
954 <computeroutput>&lt;pipename&gt;</computeroutput> and
955 connect the virtual serial device to it. Note that Windows
956 requires that the name of a named pipe begin with
957 <computeroutput>\\.\pipe\</computeroutput>.</para>
958
959 <para>On a Linux host, instead of a named pipe, a local
960 domain socket is used.</para>
961 </listitem>
962
963 <listitem>
964 <para><computeroutput>client
965 &lt;pipename&gt;</computeroutput>: This operates just like
966 <computeroutput>server ...</computeroutput>, except that the
967 pipe (or local domain socket) is not created by VirtualBox,
968 but assumed to exist already.</para>
969 </listitem>
970
971 <listitem>
972 <para><computeroutput>&lt;devicename&gt;</computeroutput>:
973 If, instead of the above, the device name of a physical
974 hardware serial port of the host is specified, the virtual
975 serial port is connected to that hardware port. On a Windows
976 host, the device name will be a COM port such as
977 <computeroutput>COM1</computeroutput>; on a Linux host, the
978 device name will look like
979 <computeroutput>/dev/ttyS0</computeroutput>. This allows you
980 to "wire" a real serial port to a virtual machine.</para>
981 </listitem>
982 </itemizedlist></para>
983 </listitem>
984
985 <listitem>
986 <para><computeroutput>--audio none|null|oss</computeroutput>: With
987 this option, you can set whether the VM should have audio
988 support.</para>
989 </listitem>
990
991 <listitem>
992 <para><computeroutput>--clipboard
993 disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
994 With this setting, you can select whether the guest operating
995 system's clipboard should be shared with the host; see <xref
996 linkend="generalsettings" />. This requires that the Guest
997 Additions be installed in the virtual machine.</para>
998 </listitem>
999
1000 <listitem>
1001 <para><computeroutput>--monitorcount
1002 &lt;count&gt;</computeroutput>: This enables multi-monitor
1003 support; see <xref linkend="settings-display" />.</para>
1004 </listitem>
1005
1006 <listitem>
1007 <para><computeroutput>--usb on|off</computeroutput>: This option
1008 enables or disables the VM's virtual USB controller; see <xref
1009 linkend="settings-usb" /> for details.</para>
1010 </listitem>
1011
1012 <listitem>
1013 <para><computeroutput>--usbehci on|off</computeroutput>: This
1014 option enables or disables the VM's virtual USB 2.0 controller;
1015 see <xref linkend="settings-usb" /> for details.</para>
1016 </listitem>
1017 </itemizedlist></para>
1018 </sect2>
1019
1020 <sect2>
1021 <title>Remote machine settings</title>
1022
1023 <para>The following settings that affect remote machine behavior are
1024 available through <computeroutput>VBoxManage
1025 modifyvm</computeroutput>:<itemizedlist>
1026 <listitem>
1027 <para><computeroutput>--vrde on|off</computeroutput>: With the
1028 VirtualBox graphical user interface, this enables or disables the
1029 VirtualBox remote desktop extension (VRDE) server. Note that if
1030 you are using <computeroutput>VBoxHeadless</computeroutput> (see
1031 <xref linkend="vboxheadless" />), VRDE is enabled by
1032 default.</para>
1033 </listitem>
1034
1035 <listitem>
1036 <para><computeroutput>--vrdeport
1037 default|&lt;ports&gt;</computeroutput>: A port or a range of ports
1038 the VRDE server can bind to; "default" or "0" means port 3389, the
1039 standard port for RDP. You can specify a comma-separated list of
1040 ports or ranges of ports. Use a dash between two port numbers to
1041 specify a range. The VRDE server will bind to <emphasis
1042 role="bold">one</emphasis> of available ports from the specified
1043 list. Only one machine can use a given port at a time. For
1044 example, the option <computeroutput> --vrdeport
1045 5000,5010-5012</computeroutput> will tell the server to bind to
1046 one of following ports: 5000, 5010, 5011 or 5012.</para>
1047 </listitem>
1048
1049 <listitem>
1050 <para><computeroutput>--vrdeaddress &lt;IP
1051 address&gt;</computeroutput>: The IP address of the host network
1052 interface the VRDE server will bind to. If specified, the server
1053 will accept connections only on the specified host network
1054 interface.</para>
1055 </listitem>
1056
1057 <listitem>
1058 <para><computeroutput>--vrdeauthtype
1059 null|external|guest</computeroutput>: This allows you to choose
1060 whether and how authorization will be performed; see <xref
1061 linkend="vbox-auth" /> for details.</para>
1062 </listitem>
1063
1064 <listitem>
1065 <para><computeroutput>--vrdemulticon on|off</computeroutput>: This
1066 enables multiple connections to the same VRDE server, if the
1067 server supports this feature; see <xref lang=""
1068 linkend="vrde-multiconnection" />.</para>
1069 </listitem>
1070
1071 <listitem>
1072 <para><computeroutput>--vrdereusecon on|off</computeroutput>: This
1073 specifies the VRDE server behavior when multiple connections are
1074 disabled. When this option is enabled, the server will allow a new
1075 client to connect and will drop the existing connection. When this
1076 option is disabled (this is the default setting), a new connection
1077 will not be accepted if there is already a client connected to the
1078 server.</para>
1079 </listitem>
1080
1081 <listitem>
1082 <para><computeroutput>--vrdevideochannel on|off</computeroutput>:
1083 This enables video redirection, if it is supported by the VRDE
1084 server; see <xref lang="" linkend="vrde-videochannel" />.</para>
1085 </listitem>
1086
1087 <listitem>
1088 <para><computeroutput>--vrdevideochannelquality
1089 &lt;percent&gt;</computeroutput>: Sets the image quality for video
1090 redirection; see <xref lang=""
1091 linkend="vrde-videochannel" />.</para>
1092 </listitem>
1093 </itemizedlist></para>
1094 </sect2>
1095
1096 <sect2 id="vboxmanage-modifyvm-teleport">
1097 <title>Teleporting settings</title>
1098
1099 <para>With the following commands for <computeroutput>VBoxManage
1100 modifyvm</computeroutput> you can configure a machine to be a target for
1101 teleporting. See <xref linkend="teleporting" /> for an
1102 introduction.<itemizedlist>
1103 <listitem>
1104 <para><computeroutput>--teleporter on|off</computeroutput>: With
1105 this setting you turn on or off whether a machine waits for a
1106 teleporting request to come in on the network when it is started.
1107 If "on", when the machine is started, it does not boot the virtual
1108 machine as it would normally; instead, it then waits for a
1109 teleporting request to come in on the port and address listed with
1110 the next two parameters.</para>
1111 </listitem>
1112
1113 <listitem>
1114 <para><computeroutput>--teleporterport
1115 &lt;port&gt;</computeroutput>, <computeroutput>--teleporteraddress
1116 &lt;address&gt;</computeroutput>: these must be used with
1117 --teleporter and tell the virtual machine on which port and
1118 address it should listen for a teleporting request from another
1119 virtual machine. <computeroutput>&lt;port&gt;</computeroutput> can
1120 be any free TCP/IP port number (e.g. 6000);
1121 <computeroutput>&lt;address&gt;</computeroutput> can be any IP
1122 address or hostname and specifies the TCP/IP socket to bind to.
1123 The default is "0.0.0.0", which means any address.</para>
1124 </listitem>
1125
1126 <listitem>
1127 <para><computeroutput>--teleporterpassword
1128 &lt;password&gt;</computeroutput>: if this optional argument is
1129 given, then the teleporting request will only succeed if the
1130 source machine specifies the same password as the one given with
1131 this command.</para>
1132 </listitem>
1133
1134 <listitem>
1135 <para><computeroutput>--teleporterpasswordfile
1136 &lt;password&gt;</computeroutput>: if this optional argument is
1137 given, then the teleporting request will only succeed if the
1138 source machine specifies the same password as the one specified
1139 in the file give with this command. Use <computeroutput>stdin</computeroutput>
1140 to read the password from stdin.</para>
1141 </listitem>
1142
1143 <listitem>
1144 <para><computeroutput>--cpuid &lt;leaf&gt; &lt;eax&gt; &lt;ebx&gt;
1145 &lt;ecx&gt; &lt;edx&gt;</computeroutput>: Advanced users can use
1146 this command before a teleporting operation to restrict the
1147 virtual CPU capabilities that VirtualBox presents to the guest
1148 operating system. This must be run on both the source and the
1149 target machines involved in the teleporting and will then modify
1150 what the guest sees when it executes the
1151 <computeroutput>CPUID</computeroutput> machine instruction. This
1152 might help with misbehaving applications that wrongly assume that
1153 certain CPU capabilities are present. The meaning of the
1154 parameters is hardware dependent; please refer to the AMD or Intel
1155 processor manuals.</para>
1156 </listitem>
1157 </itemizedlist></para>
1158 </sect2>
1159 </sect1>
1160
1161 <sect1 id="vboxmanage-clonevm">
1162 <title>VBoxManage clonevm</title>
1163
1164 <para>This command creates a full or linked copy of an existing virtual
1165 machine.</para>
1166
1167 <para>The <computeroutput>clonevm</computeroutput> subcommand takes at
1168 least the name of the virtual machine which should be cloned. The following
1169 additional settings can be used to further configure the clone VM
1170 operation:</para>
1171
1172 <itemizedlist>
1173 <listitem>
1174 <para><computeroutput>--snapshot &lt;uuid&gt;|&lt;name&gt;</computeroutput>:
1175 Select a specific snapshot where the clone operation should refer
1176 to. Default is referring to the current state.</para>
1177 </listitem>
1178 <listitem>
1179 <para><computeroutput>--mode machine|machineandchildren|all</computeroutput>:
1180 Selects the cloning mode of the operation. If
1181 <computeroutput>machine</computeroutput> is selected (the default),
1182 the current state of the VM without any snapshots is cloned. In the
1183 <computeroutput>machineandchildren</computeroutput> mode the snapshot
1184 provided by <computeroutput>--snapshot</computeroutput> and all
1185 child snapshots are cloned. If <computeroutput>all</computeroutput>
1186 is the selected mode all snapshots and the current state are cloned.
1187 </para>
1188 </listitem>
1189 <listitem>
1190 <para><computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
1191 Allows additional fine tuning of the clone operation. The first
1192 option defines that a linked clone should be created, which is
1193 only possible for a machine clone from a snapshot. The next two
1194 options allow to define how the MAC addresses of every virtual
1195 network card should be handled. They can either be reinitialized
1196 (the default), left unchanged
1197 (<computeroutput>keepallmacs</computeroutput>) or left unchanged
1198 when the network type is NAT
1199 (<computeroutput>keepnatmacs</computeroutput>). If you add
1200 <computeroutput>keepdisknames</computeroutput> all new disk images
1201 are called like the original once, otherwise they are
1202 renamed.</para>
1203 </listitem>
1204 <listitem>
1205 <para><computeroutput>--name &lt;name&gt;</computeroutput>: Select a
1206 new name for the new virtual machine. Default is "Original Name
1207 Clone".</para>
1208 </listitem>
1209 <listitem>
1210 <para><computeroutput>--basefolder &lt;basefolder&gt;</computeroutput>:
1211 Select the folder where the new virtual machine configuration should
1212 be saved in.</para>
1213 </listitem>
1214 <listitem>
1215 <para><computeroutput>--uuid &lt;uuid&gt;</computeroutput>:
1216 Select the UUID the new VM should have. This id has to be unique in
1217 the VirtualBox instance this clone should be registered. Default is
1218 creating a new UUID.</para>
1219 </listitem>
1220 <listitem>
1221 <para><computeroutput>--register</computeroutput>:
1222 Automatically register the new clone in this VirtualBox
1223 installation. If you manually want register the new VM later, see
1224 <xref linkend="vboxmanage-registervm" /> for instructions how to do
1225 so.</para>
1226 </listitem>
1227 </itemizedlist>
1228 </sect1>
1229
1230 <sect1 id="vboxmanage-import">
1231 <title>VBoxManage import</title>
1232
1233 <para>This command imports a virtual appliance in OVF format by copying
1234 the virtual disk images and creating virtual machines in VirtualBox. See
1235 <xref linkend="ovf" /> for an introduction to appliances.</para>
1236
1237 <para>The <computeroutput>import</computeroutput> subcommand takes at
1238 least the path name of an OVF file as input and expects the disk images,
1239 if needed, in the same directory as the OVF file. A lot of additional
1240 command-line options are supported to control in detail what is being
1241 imported and modify the import parameters, but the details depend on the
1242 content of the OVF file.</para>
1243
1244 <para>It is therefore recommended to first run the import subcommand with
1245 the <computeroutput>--dry-run</computeroutput> or
1246 <computeroutput>-n</computeroutput> option. This will then print a
1247 description of the appliance's contents to the screen how it would be
1248 imported into VirtualBox, together with the optional command-line options
1249 to influence the import behavior.</para>
1250
1251 <para>As an example, here is the screen output with a sample appliance
1252 containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
1253Interpreting WindowsXp.ovf...
1254OK.
1255Virtual system 0:
1256 0: Suggested OS type: "WindowsXP"
1257 (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
1258 1: Suggested VM name "Windows XP Professional_1"
1259 (change with "--vsys 0 --vmname &lt;name&gt;")
1260 3: Number of CPUs: 1
1261 (change with "--vsys 0 --cpus &lt;n&gt;")
1262 4: Guest memory: 956 MB (change with "--vsys 0 --memory &lt;MB&gt;")
1263 5: Sound card (appliance expects "ensoniq1371", can change on import)
1264 (disable with "--vsys 0 --unit 5 --ignore")
1265 6: USB controller
1266 (disable with "--vsys 0 --unit 6 --ignore")
1267 7: Network adapter: orig bridged, config 2, extra type=bridged
1268 8: Floppy
1269 (disable with "--vsys 0 --unit 8 --ignore")
1270 9: SCSI controller, type BusLogic
1271 (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
1272 disable with "--vsys 0 --unit 9 --ignore")
127310: IDE controller, type PIIX4
1274 (disable with "--vsys 0 --unit 10 --ignore")
127511: Hard disk image: source image=WindowsXp.vmdk,
1276 target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
1277 (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
1278 disable with "--vsys 0 --unit 11 --ignore")</screen></para>
1279
1280 <para>As you can see, the individual configuration items are numbered, and
1281 depending on their type support different command-line options. The import
1282 subcommand can be directed to ignore many such items with a
1283 <computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
1284 X is the number of the virtual system (zero unless there are several
1285 virtual system descriptions in the appliance) and Y the item number, as
1286 printed on the screen.</para>
1287
1288 <para>In the above example, Item #1 specifies the name of the target
1289 machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
1290 respectively. Item #11 describes a hard disk image; in this case, the
1291 additional <computeroutput>--controller</computeroutput> option indicates
1292 which item the disk image should be connected to, with the default coming
1293 from the OVF file.</para>
1294
1295 <para>You can combine several items for the same virtual system behind the
1296 same <computeroutput>--vsys</computeroutput> option. For example, to
1297 import a machine as described in the OVF, but without the sound card and
1298 without the USB controller, and with the disk image connected to the IDE
1299 controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
1300 --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
1301 </sect1>
1302
1303 <sect1 id="vboxmanage-export">
1304 <title>VBoxManage export</title>
1305
1306 <para>This command exports one or more virtual machines from VirtualBox
1307 into a virtual appliance in OVF format, including copying their virtual
1308 disk images to compressed VMDK. See <xref linkend="ovf" /> for an
1309 introduction to appliances.</para>
1310
1311 <para>The <computeroutput>export</computeroutput> command is simple to
1312 use: list the machine (or the machines) that you would like to export to
1313 the same OVF file and specify the target OVF file after an additional
1314 <computeroutput>--output</computeroutput> or
1315 <computeroutput>-o</computeroutput> option. Note that the directory of the
1316 target OVF file will also receive the exported disk images in the
1317 compressed VMDK format (regardless of the original format) and should have
1318 enough disk space left for them.</para>
1319
1320 <para>Beside a simple export of a given virtual machine, you can append
1321 several product information to the appliance file. Use
1322 <computeroutput>--product</computeroutput>,
1323 <computeroutput>--producturl</computeroutput>,
1324 <computeroutput>--vendor</computeroutput>,
1325 <computeroutput>--vendorurl</computeroutput> and
1326 <computeroutput>--version</computeroutput> to specify this additional
1327 information. For legal reasons you may add a license text or the content
1328 of a license file by using the <computeroutput>--eula</computeroutput> and
1329 <computeroutput>--eulafile</computeroutput> option respectively. As with
1330 OVF import, you must use the <computeroutput>--vsys X</computeroutput>
1331 option to direct the previously mentioned options to the correct virtual
1332 machine.</para>
1333
1334 <para>For virtualization products which aren't fully compatible with the
1335 OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
1336 <computeroutput>--legacy09</computeroutput> option.</para>
1337 </sect1>
1338
1339 <sect1 id="vboxmanage-startvm">
1340 <title>VBoxManage startvm</title>
1341
1342 <para>This command starts a virtual machine that is currently in the
1343 "Powered off" or "Saved" states.</para>
1344
1345 <note>
1346 <para>This is provided for backwards compatibility only. We recommend to
1347 start virtual machines directly by running the respective front-end, as
1348 you might otherwise miss important error and state information that
1349 VirtualBox may display on the console. This is especially important for
1350 front-ends other than <computeroutput>VirtualBox</computeroutput>, our
1351 graphical user interface, because those cannot display error messages in
1352 a popup window. See <xref linkend="vboxheadless" /> for more
1353 information.</para>
1354 </note>
1355
1356 <para>The optional <computeroutput>--type</computeroutput> specifier
1357 determines whether the machine will be started in a window (GUI mode,
1358 which is the default) or whether the output should go through
1359 <computeroutput>VBoxHeadless</computeroutput>, with VRDE enabled or not;
1360 see <xref linkend="vboxheadless" /> for more information. The list of
1361 types is subject to change, and it's not guaranteed that all types are
1362 accepted by any product variant.</para>
1363
1364 <para>The following values are allowed:</para>
1365
1366 <glosslist>
1367 <glossentry>
1368 <glossterm>gui</glossterm>
1369
1370 <glossdef>
1371 <para>Starts a VM showing a GUI window. This is the default.</para>
1372 </glossdef>
1373 </glossentry>
1374
1375 <glossentry>
1376 <glossterm>headless</glossterm>
1377
1378 <glossdef>
1379 <para>Starts a VM without a window for remote display only.</para>
1380 </glossdef>
1381 </glossentry>
1382 </glosslist>
1383 </sect1>
1384
1385 <sect1 id="vboxmanage-controlvm">
1386 <title>VBoxManage controlvm</title>
1387
1388 <para>The <computeroutput>controlvm</computeroutput> subcommand allows you
1389 to change the state of a virtual machine that is currently running. The
1390 following can be specified:</para>
1391
1392 <para><itemizedlist>
1393 <listitem>
1394 <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
1395 pause</computeroutput> temporarily puts a virtual machine on hold,
1396 without changing its state for good. The VM window will be painted
1397 in gray to indicate that the VM is currently paused. (This is
1398 equivalent to selecting the "Pause" item in the "Machine" menu of
1399 the GUI.)</para>
1400 </listitem>
1401
1402 <listitem>
1403 <para>Use <computeroutput>VBoxManage controlvm &lt;vm&gt;
1404 resume</computeroutput> to undo a previous
1405 <computeroutput>pause</computeroutput> command. (This is equivalent
1406 to selecting the "Resume" item in the "Machine" menu of the
1407 GUI.)</para>
1408 </listitem>
1409
1410 <listitem>
1411 <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
1412 reset</computeroutput> has the same effect on a virtual machine as
1413 pressing the "Reset" button on a real computer: a cold reboot of the
1414 virtual machine, which will restart and boot the guest operating
1415 system again immediately. The state of the VM is not saved
1416 beforehand, and data may be lost. (This is equivalent to selecting
1417 the "Reset" item in the "Machine" menu of the GUI.)</para>
1418 </listitem>
1419
1420 <listitem>
1421 <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
1422 poweroff</computeroutput> has the same effect on a virtual machine
1423 as pulling the power cable on a real computer. Again, the state of
1424 the VM is not saved beforehand, and data may be lost. (This is
1425 equivalent to selecting the "Close" item in the "Machine" menu of
1426 the GUI or pressing the window's close button, and then selecting
1427 "Power off the machine" in the dialog.)</para>
1428
1429 <para>After this, the VM's state will be "Powered off". From there,
1430 it can be started again; see <xref
1431 linkend="vboxmanage-startvm" />.</para>
1432 </listitem>
1433
1434 <listitem>
1435 <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
1436 savestate</computeroutput> will save the current state of the VM to
1437 disk and then stop the VM. (This is equivalent to selecting the
1438 "Close" item in the "Machine" menu of the GUI or pressing the
1439 window's close button, and then selecting "Save the machine state"
1440 in the dialog.)</para>
1441
1442 <para>After this, the VM's state will be "Saved". From there, it can
1443 be started again; see <xref linkend="vboxmanage-startvm" />.</para>
1444 </listitem>
1445
1446 <listitem>
1447 <para><computeroutput>VBoxManage controlvm &lt;vm&gt; teleport
1448 --hostname &lt;name&gt; --port &lt;port&gt; [--passwordfile
1449 &lt;file&gt; | --password &lt;password&gt;]</computeroutput> makes
1450 the machine the source of a teleporting operation and initiates a
1451 teleport to the given target. See <xref linkend="teleporting" /> for
1452 an introduction. If the optional password is specified, it must match
1453 the password that was given to the
1454 <computeroutput>modifyvm</computeroutput> command for the target
1455 machine; see <xref linkend="vboxmanage-modifyvm-teleport" /> for
1456 details.</para>
1457 </listitem>
1458 </itemizedlist></para>
1459
1460 <para>A few extra options are available with
1461 <computeroutput>controlvm</computeroutput> that do not directly affect the
1462 VM's running state:</para>
1463
1464 <itemizedlist>
1465 <listitem>
1466 <para>The <computeroutput>setlinkstate&lt;1-N&gt;</computeroutput>
1467 operation connects or disconnects virtual network cables from their
1468 network interfaces.</para>
1469 </listitem>
1470
1471 <listitem>
1472 <para><computeroutput>nic&lt;1-N&gt;
1473 null|nat|bridged|intnet|hostonly|generic</computeroutput>: With this, you can
1474 set, for each of the VM's virtual network cards, what type of
1475 networking should be available. They can be not connected to the host
1476 (<computeroutput>null</computeroutput>), use network address
1477 translation (<computeroutput>nat</computeroutput>), bridged networking
1478 (<computeroutput>bridged</computeroutput>) or communicate with other
1479 virtual machines using internal networking
1480 (<computeroutput>intnet</computeroutput>) or host-only networking
1481 (<computeroutput>hostonly</computeroutput>) or access to rarely used
1482 sub-modes
1483 (<computeroutput>generic</computeroutput>). These options correspond
1484 to the modes which are described in detail in <xref
1485 linkend="networkingmodes" />.</para>
1486 </listitem>
1487
1488 <listitem>
1489 <para><computeroutput>usbattach</computeroutput> and
1490 <computeroutput>usbdettach</computeroutput> make host USB devices
1491 visible to the virtual machine on the fly, without the need for
1492 creating filters first. The USB devices can be specified by UUID
1493 (unique identifier) or by address on the host system.</para>
1494
1495 <para>You can use <computeroutput>VBoxManage list
1496 usbhost</computeroutput> to locate this information.</para>
1497 </listitem>
1498
1499 <listitem>
1500 <para><computeroutput>vrde on|off</computeroutput> lets you enable or
1501 disable the VRDE server, if it is installed.</para>
1502 </listitem>
1503
1504 <listitem>
1505 <para><computeroutput>vrdeport default|&lt;ports&gt;</computeroutput>
1506 changes the port or a range of ports that the VRDE server can bind to;
1507 "default" or "0" means port 3389, the standard port for RDP. For
1508 details, see the description for the
1509 <computeroutput>--vrdeport</computeroutput> option in <xref
1510 linkend="vboxmanage-modifyvm-other" />.</para>
1511 </listitem>
1512
1513 <listitem>
1514 <para><computeroutput>setvideomodehint</computeroutput> requests that
1515 the guest system change to a particular video mode. This requires that
1516 the Guest Additions be installed, and will not work for all guest
1517 systems.</para>
1518 </listitem>
1519
1520 <listitem>
1521 <para><computeroutput>screenshotpng</computeroutput> takes a screenshot
1522 of the guest display and saves it in PNG format.</para>
1523 </listitem>
1524
1525 <listitem>
1526 <para>The <computeroutput>setcredentials</computeroutput> operation is
1527 used for remote logons in Windows guests. For details, please refer to
1528 <xref linkend="autologon" />.</para>
1529 </listitem>
1530
1531 <listitem>
1532 <para>The <computeroutput>guestmemoryballoon</computeroutput>
1533 operation changes the size of the guest memory balloon, that is,
1534 memory allocated by the VirtualBox Guest Additions from the guest
1535 operating system and returned to the hypervisor for re-use by other
1536 virtual machines. This must be specified in megabytes. For details,
1537 see <xref linkend="guestadd-balloon" />.</para>
1538 </listitem>
1539
1540 <listitem>
1541 <para>The <computeroutput>cpuexecutioncap
1542 &lt;1-100&gt;</computeroutput>: This operation controls how much cpu
1543 time a virtual CPU can use. A value of 50 implies a single virtual CPU
1544 can use up to 50% of a single host CPU.</para>
1545 </listitem>
1546 </itemizedlist>
1547 </sect1>
1548
1549 <sect1>
1550 <title>VBoxManage discardstate</title>
1551
1552 <para>This command discards the saved state of a virtual machine which is
1553 not currently running, which will cause its operating system to restart
1554 next time you start it. This is the equivalent of pulling out the power
1555 cable on a physical machine, and should be avoided if possible.</para>
1556 </sect1>
1557
1558 <sect1>
1559 <title>VBoxManage adoptstate</title>
1560
1561 <para>If you have a saved state file (<computeroutput>.sav</computeroutput>)
1562 that is seperate from the VM configuration, you can use this command to
1563 "adopt" the file. This will change the VM to saved state and when you
1564 start it, VirtualBox will attempt to restore it from the saved state file
1565 you indicated. This command should only be used in special setups.</para>
1566 </sect1>
1567
1568 <sect1>
1569 <title>VBoxManage snapshot</title>
1570
1571 <para>This command is used to control snapshots from the command line. A
1572 snapshot consists of a complete copy of the virtual machine settings,
1573 copied at the time when the snapshot was taken, and optionally a virtual
1574 machine saved state file if the snapshot was taken while the machine was
1575 running. After a snapshot has been taken, VirtualBox creates differencing
1576 hard disk for each normal hard disk associated with the machine so that
1577 when a snapshot is restored, the contents of the virtual machine's virtual
1578 hard disks can be quickly reset by simply dropping the pre-existing
1579 differencing files.</para>
1580
1581 <para>The <computeroutput>take</computeroutput> operation takes a snapshot
1582 of the current state of the virtual machine. You must supply a name for
1583 the snapshot and can optionally supply a description. The new snapshot is
1584 inserted into the snapshots tree as a child of the current snapshot and
1585 then becomes the new current snapshot.</para>
1586
1587 <para>The <computeroutput>delete</computeroutput> operation deletes a
1588 snapshot (specified by name or by UUID). This can take a while to finish
1589 since the differencing images associated with the snapshot might need to
1590 be merged with their child differencing images.</para>
1591
1592 <para>The <computeroutput>restore</computeroutput> operation will restore
1593 the given snapshot (specified by name or by UUID) by resetting the virtual
1594 machine's settings and current state to that of the snapshot. The previous
1595 current state of the machine will be lost. After this, the given snapshot
1596 becomes the new "current" snapshot so that subsequent snapshots are
1597 inserted under the snapshot from which was restored.</para>
1598
1599 <para>The <computeroutput>restorecurrent</computeroutput> operation is a
1600 shortcut to restore the current snapshot (i.e. the snapshot from which the
1601 current state is derived). This subcommand is equivalent to using the
1602 "restore" subcommand with the name or UUID of the current snapshot, except
1603 that it avoids the extra step of determining that name or UUID.</para>
1604
1605 <para>With the <computeroutput>edit</computeroutput> operation, you can
1606 change the name or description of an existing snapshot.</para>
1607
1608 <para>With the <computeroutput>showvminfo</computeroutput> operation, you
1609 can view the virtual machine settings that were stored with an existing
1610 snapshot.</para>
1611 </sect1>
1612
1613 <sect1 id="vboxmanage-closemedium">
1614 <title>VBoxManage closemedium</title>
1615
1616 <para>This commands removes a hard disk, DVD or floppy image from a
1617 VirtualBox media registry.<footnote>
1618 <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
1619 openmedium before a medium could be attached to a virtual machine;
1620 that call "registered" the medium with the global VirtualBox media
1621 registry. With VirtualBox 4.0 this is no longer necessary; media are
1622 added to media registries automatically. The "closemedium" call has
1623 been retained, however, to allow for explicitly removing a medium from
1624 a registry.</para>
1625 </footnote></para>
1626
1627 <para>Optionally, you can request that the image be deleted. You will get
1628 appropriate diagnostics that the deletion failed, however the image will
1629 become unregistered in any case.</para>
1630 </sect1>
1631
1632 <sect1>
1633 <title id="vboxmanage-storageattach">VBoxManage storageattach</title>
1634
1635 <para>This command attaches/modifies/removes a storage medium connected to
1636 a storage controller that was previously added with the
1637 <computeroutput>storagectl</computeroutput> command (see the previous
1638 section). The syntax is as follows:</para>
1639
1640 <screen>VBoxManage storageattach &lt;uuid|vmname&gt;
1641 --storagectl &lt;name&gt;
1642 [--port &lt;number&gt;]
1643 [--device &lt;number&gt;]
1644 [--type dvddrive|hdd|fdd]
1645 [--medium none|emptydrive|
1646 &lt;uuid&gt;|&lt;filename&gt;|host:&lt;drive&gt;|iscsi]
1647 [--mtype normal|writethrough|immutable|shareable]
1648 [--comment &lt;text&gt;]
1649 [--setuuid &lt;uuid&gt;]
1650 [--setparentuuid &lt;uuid&gt;]
1651 [--passthrough on|off]
1652 [--tempeject on|off]
1653 [--nonrotational on|off]
1654 [--discard on|off]
1655 [--bandwidthgroup name|none]
1656 [--forceunmount]
1657 [--server &lt;name&gt;|&lt;ip&gt;]
1658 [--target &lt;target&gt;]
1659 [--tport &lt;port&gt;]
1660 [--lun &lt;lun&gt;]
1661 [--encodedlun &lt;lun&gt;]
1662 [--username &lt;username&gt;]
1663 [--password &lt;password&gt;]
1664 [--initiator &lt;initiator&gt;]
1665 [--intnet]
1666</screen>
1667
1668 <para>A number of parameters are commonly required; the ones at the end of
1669 the list are required only for iSCSI targets (see below).</para>
1670
1671 <para>The common parameters are:<glosslist>
1672 <glossentry>
1673 <glossterm>uuid|vmname</glossterm>
1674
1675 <glossdef>
1676 <para>The VM UUID or VM Name. Mandatory.</para>
1677 </glossdef>
1678 </glossentry>
1679
1680 <glossentry>
1681 <glossterm>storagectl</glossterm>
1682
1683 <glossdef>
1684 <para>Name of the storage controller. Mandatory. The list of the
1685 storage controllers currently attached to a VM can be obtained
1686 with <computeroutput>VBoxManage showvminfo</computeroutput>; see
1687 <xref linkend="vboxmanage-showvminfo" />.</para>
1688 </glossdef>
1689 </glossentry>
1690
1691 <glossentry>
1692 <glossterm>port</glossterm>
1693
1694 <glossdef>
1695 <para>The number of the storage controller's port which is to be
1696 modified. Mandatory, unless the storage controller has only a
1697 single port.</para>
1698 </glossdef>
1699 </glossentry>
1700
1701 <glossentry>
1702 <glossterm>device</glossterm>
1703
1704 <glossdef>
1705 <para>The number of the port's device which is to be modified.
1706 Mandatory, unless the storage controller has only a single device
1707 per port.</para>
1708 </glossdef>
1709 </glossentry>
1710
1711 <glossentry>
1712 <glossterm>type</glossterm>
1713
1714 <glossdef>
1715 <para>Define the type of the drive to which the medium is being
1716 attached/detached/modified. This argument can only be omitted if
1717 the type of medium can be determined from either the medium given
1718 with the <computeroutput>--medium</computeroutput> argument or
1719 from a previous medium attachment.</para>
1720 </glossdef>
1721 </glossentry>
1722
1723 <glossentry>
1724 <glossterm>medium</glossterm>
1725
1726 <glossdef>
1727 <para>Specifies what is to be attached. The following values are
1728 supported:<itemizedlist>
1729 <listitem>
1730 <para>"none": Any existing device should be removed from the
1731 given slot.</para>
1732 </listitem>
1733
1734 <listitem>
1735 <para>"emptydrive": For a virtual DVD or floppy drive only,
1736 this makes the device slot behaves like a removeable drive
1737 into which no media has been inserted.</para>
1738 </listitem>
1739
1740 <listitem>
1741 <para>"additions": For a virtual DVD drive only, this
1742 attaches the <emphasis>VirtualBox Guest Additions</emphasis>
1743 image to the given device slot.</para>
1744 </listitem>
1745
1746 <listitem>
1747 <para>If a UUID is specified, it must be the UUID of a
1748 storage medium that is already known to VirtualBox (e.g.
1749 because it has been attached to another virtual machine).
1750 See <xref linkend="vboxmanage-list" /> for how to list known
1751 media. This medium is then attached to the given device
1752 slot.</para>
1753 </listitem>
1754
1755 <listitem>
1756 <para>If a filename is specified, it must be the full path
1757 of an existing disk image (ISO, RAW, VDI, VMDK or other),
1758 which is then attached to the given device slot.</para>
1759 </listitem>
1760
1761 <listitem>
1762 <para>"host:&lt;drive&gt;": For a virtual DVD or floppy
1763 drive only, this connects the given device slot to the
1764 specified DVD or floppy drive on the host computer.</para>
1765 </listitem>
1766
1767 <listitem>
1768 <para>"iscsi": For virtual hard disks only, this allows for
1769 specifying an iSCSI target. In this case, more parameters
1770 must be given; see below.</para>
1771 </listitem>
1772 </itemizedlist></para>
1773
1774 <para>Some of the above changes, in particular for removeable
1775 media (floppies and CDs/DVDs), can be effected while a VM is
1776 running. Others (device changes or changes in hard disk device
1777 slots) require the VM to be powered off.</para>
1778 </glossdef>
1779 </glossentry>
1780
1781 <glossentry>
1782 <glossterm>mtype</glossterm>
1783
1784 <glossdef>
1785 <para>Defines how this medium behaves with respect to snapshots
1786 and write operations. See <xref linkend="hdimagewrites" /> for
1787 details.</para>
1788 </glossdef>
1789 </glossentry>
1790
1791 <glossentry>
1792 <glossterm>comment</glossterm>
1793
1794 <glossdef>
1795 <para>Any description that you want to have stored with this
1796 medium (optional; for example, for an iSCSI target, "Big storage
1797 server downstairs"). This is purely descriptive and not needed for
1798 the medium to function correctly.</para>
1799 </glossdef>
1800 </glossentry>
1801
1802 <glossentry>
1803 <glossterm>setuuid, setparentuuid</glossterm>
1804
1805 <glossdef>
1806 <para>Modifies the UUID or parent UUID of a medium before
1807 attaching it to a VM. This is an expert option. Inappropriate use
1808 can make the medium unusable or lead to broken VM configurations
1809 if any other VM is referring to the same media already. The most
1810 frequently used variant is <code>--setuuid ""</code>, which assigns
1811 a new (random) UUID to an image. This is useful to resolve the
1812 duplicate UUID errors if one duplicated an image using file copy
1813 utilities.</para>
1814 </glossdef>
1815 </glossentry>
1816
1817 <glossentry>
1818 <glossterm>passthrough</glossterm>
1819
1820 <glossdef>
1821 <para>For a virtual DVD drive only, you can enable DVD writing
1822 support (currently experimental; see <xref
1823 linkend="storage-cds" />).</para>
1824 </glossdef>
1825 </glossentry>
1826
1827 <glossentry>
1828 <glossterm>tempeject</glossterm>
1829
1830 <glossdef>
1831 <para>For a virtual DVD drive only, you can configure the behavior
1832 for guest-triggered medium eject. If this is set to "on", the eject
1833 has only temporary effects. If the VM is powered off and restarted
1834 the originally configured medium will be still in the drive.</para>
1835 </glossdef>
1836 </glossentry>
1837
1838 <glossentry>
1839 <glossterm>nonrotational</glossterm>
1840
1841 <glossdef>
1842 <para>This switch allows to enable the non-rotational flag for virtual
1843 hard disks. Some guests (i.e. Windows 7+) treat such disks like SSDs
1844 and don't perform disk fragmentation on such media.
1845 </para>
1846 </glossdef>
1847 </glossentry>
1848
1849 <glossentry>
1850 <glossterm>bandwidthgroup</glossterm>
1851
1852 <glossdef>
1853 <para>Sets the bandwidth group to use for the given device; see
1854 <xref linkend="storage-bandwidth-limit" />.</para>
1855 </glossdef>
1856 </glossentry>
1857
1858 <glossentry>
1859 <glossterm>forceunmount</glossterm>
1860
1861 <glossdef>
1862 <para>For a virtual DVD or floppy drive only, this forcibly
1863 unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if
1864 the previous one is locked down by the guest for reading. Again,
1865 see <xref linkend="storage-cds" /> for details.</para>
1866 </glossdef>
1867 </glossentry>
1868 </glosslist></para>
1869
1870 <para>When "iscsi" is used with the
1871 <computeroutput>--medium</computeroutput> parameter for iSCSI support --
1872 see <xref linkend="storage-iscsi" /> --, additional parameters must or can
1873 be used:<glosslist>
1874 <glossentry>
1875 <glossterm>server</glossterm>
1876
1877 <glossdef>
1878 <para>The host name or IP address of the iSCSI target;
1879 required.</para>
1880 </glossdef>
1881 </glossentry>
1882
1883 <glossentry>
1884 <glossterm>target</glossterm>
1885
1886 <glossdef>
1887 <para>Target name string. This is determined by the iSCSI target
1888 and used to identify the storage resource; required.</para>
1889 </glossdef>
1890 </glossentry>
1891
1892 <glossentry>
1893 <glossterm>tport</glossterm>
1894
1895 <glossdef>
1896 <para>TCP/IP port number of the iSCSI service on the target
1897 (optional).</para>
1898 </glossdef>
1899 </glossentry>
1900
1901 <glossentry>
1902 <glossterm>lun</glossterm>
1903
1904 <glossdef>
1905 <para>Logical Unit Number of the target resource (optional).
1906 Often, this value is zero.</para>
1907 </glossdef>
1908 </glossentry>
1909
1910 <glossentry>
1911 <glossterm>username, password</glossterm>
1912
1913 <glossdef>
1914 <para>Username and password (initiator secret) for target
1915 authentication, if required (optional).<note>
1916 <para>Username and password are stored without
1917 encryption (i.e. in clear text) in the XML machine
1918 configuration file if no settings password is provided.
1919 When a settings password was specified the first time,
1920 the password is stored encrypted.</para>
1921 </note></para>
1922 </glossdef>
1923 </glossentry>
1924
1925 <glossentry>
1926 <glossterm>intnet</glossterm>
1927
1928 <glossdef>
1929 <para>If specified, connect to the iSCSI target via Internal
1930 Networking. This needs further configuration which is described in
1931 <xref linkend="iscsi-intnet" />.</para>
1932 </glossdef>
1933 </glossentry>
1934 </glosslist></para>
1935 </sect1>
1936
1937 <sect1 id="vboxmanage-storagectl">
1938 <title>VBoxManage storagectl</title>
1939
1940 <para>This command attaches/modifies/removes a storage controller. After
1941 this, virtual media can be attached to the controller with the
1942 <computeroutput>storageattach</computeroutput> command (see the next
1943 section).</para>
1944
1945 <para>The syntax is as follows:</para>
1946
1947 <screen>VBoxManage storagectl &lt;uuid|vmname&gt;
1948 --name &lt;name&gt;
1949 [--add &lt;ide/sata/scsi/floppy&gt;]
1950 [--controller &lt;LsiLogic|LSILogicSAS|BusLogic|
1951 IntelAhci|PIIX3|PIIX4|ICH6|I82078&gt;]
1952 [--sataportcount &lt;1-30&gt;]
1953 [--hostiocache on|off]
1954 [--bootable on|off]
1955 [--remove]</screen>
1956
1957 <para>where the parameters mean: <glosslist>
1958 <glossentry>
1959 <glossterm>uuid|vmname</glossterm>
1960
1961 <glossdef>
1962 <para>The VM UUID or VM Name. Mandatory.</para>
1963 </glossdef>
1964 </glossentry>
1965
1966 <glossentry>
1967 <glossterm>name</glossterm>
1968
1969 <glossdef>
1970 <para>Name of the storage controller. Mandatory.</para>
1971 </glossdef>
1972 </glossentry>
1973
1974 <glossentry>
1975 <glossterm>add</glossterm>
1976
1977 <glossdef>
1978 <para>Define the type of the system bus to which the storage
1979 controller must be connected.</para>
1980 </glossdef>
1981 </glossentry>
1982
1983 <glossentry>
1984 <glossterm>controller</glossterm>
1985
1986 <glossdef>
1987 <para>Allows to choose the type of chipset being emulated for the
1988 given storage controller.</para>
1989 </glossdef>
1990 </glossentry>
1991
1992 <glossentry>
1993 <glossterm>sataportcount</glossterm>
1994
1995 <glossdef>
1996 <para>This determines how many ports the SATA controller should
1997 support.</para>
1998 </glossdef>
1999 </glossentry>
2000
2001 <glossentry>
2002 <glossterm>hostiocache</glossterm>
2003
2004 <glossdef>
2005 <para>Configures the use of the host I/O cache for all disk images
2006 attached to this storage controller. For details, please see <xref
2007 linkend="iocaching" />.</para>
2008 </glossdef>
2009 </glossentry>
2010
2011 <glossentry>
2012 <glossterm>bootable</glossterm>
2013
2014 <glossdef>
2015 <para>Selects whether this controller is bootable.</para>
2016 </glossdef>
2017 </glossentry>
2018
2019 <glossentry>
2020 <glossterm>remove</glossterm>
2021
2022 <glossdef>
2023 <para>Removes the storage controller from the VM config.</para>
2024 </glossdef>
2025 </glossentry>
2026 </glosslist></para>
2027 </sect1>
2028
2029 <sect1>
2030 <title>VBoxManage bandwidthctl</title>
2031
2032 <para>This command creates/deletes/modifies/shows bandwidth groups of the given
2033 virtual machine:<screen>VBoxManage bandwidthctl &lt;uuid|vmname&gt;
2034 add &lt;name&gt; --type disk|network --limit &lt;megabytes per second&gt;[k|m|g|K|M|G] |
2035 set &lt;name&gt; --limit &lt;megabytes per second&gt;[k|m|g|K|M|G] |
2036 remove &lt;name&gt; |
2037 list [--machinereadable]</screen></para>
2038
2039 <para>The following subcommands are available:<itemizedlist>
2040 <listitem>
2041 <para><computeroutput>add</computeroutput>, creates a new bandwidth
2042 group of given type.</para>
2043 </listitem>
2044 <listitem>
2045 <para><computeroutput>set</computeroutput>, modifies the limit for an
2046 existing bandwidth group.</para>
2047 </listitem>
2048 <listitem>
2049 <para><computeroutput>remove</computeroutput>, destroys a bandwidth
2050 group.</para>
2051 </listitem>
2052 <listitem>
2053 <para><computeroutput>list</computeroutput>, shows all bandwidth groups
2054 defined for the given VM.</para>
2055 </listitem>
2056 </itemizedlist>
2057 </para>
2058 <para>The parameters mean:<glosslist>
2059 <glossentry>
2060 <glossterm>uuid|vmname</glossterm>
2061
2062 <glossdef>
2063 <para>The VM UUID or VM Name. Mandatory.</para>
2064 </glossdef>
2065 </glossentry>
2066
2067 <glossentry>
2068 <glossterm>name</glossterm>
2069
2070 <glossdef>
2071 <para>Name of the bandwidth group. Mandatory.</para>
2072 </glossdef>
2073 </glossentry>
2074
2075 <glossentry>
2076 <glossterm>type</glossterm>
2077
2078 <glossdef>
2079 <para>Type of the bandwidth group. Mandatory. Two types are
2080 supported: <computeroutput>disk</computeroutput> and
2081 <computeroutput>network</computeroutput>. See
2082 <xref linkend="storage-bandwidth-limit" /> or
2083 <xref linkend="network_bandwidth_limit" /> for a description of a
2084 particular type.</para>
2085 </glossdef>
2086 </glossentry>
2087
2088 <glossentry>
2089 <glossterm>limit</glossterm>
2090
2091 <glossdef>
2092 <para>Specifies the limit for the given group. Can be changed
2093 while the VM is running. The default unit is megabytes per
2094 second. The unit can be changed by specifying one of the
2095 following suffixes: <computeroutput>k</computeroutput> for kilobits/s, <computeroutput>m</computeroutput> for megabits/s, <computeroutput>g</computeroutput> for gigabits/s, <computeroutput>K</computeroutput> for kilobytes/s, <computeroutput>M</computeroutput> for megabytes/s, <computeroutput>G</computeroutput> for gigabytes/s.</para>
2096 </glossdef>
2097 </glossentry>
2098 </glosslist>
2099 <note>
2100 <para>The network bandwidth limits apply only to the traffic being sent by
2101 virtual machines. The traffic being received by VMs is unlimited.</para>
2102 </note>
2103 <note>
2104 <para>To remove a bandwidth group it must not be referenced by any disks
2105 or adapters in running VM.</para>
2106 </note>
2107 </para>
2108 </sect1>
2109
2110 <sect1>
2111 <title>VBoxManage showhdinfo</title>
2112
2113 <para>This command shows information about a virtual hard disk image,
2114 notably its size, its size on disk, its type and the virtual machines
2115 which use it.<note>
2116 <para>For compatibility with earlier versions of VirtualBox, the
2117 "showvdiinfo" command is also supported and mapped internally to the
2118 "showhdinfo" command.</para>
2119 </note></para>
2120 <para>The disk image must be specified either by its UUID (if the medium
2121 is registered) or by its filename. Registered images can be listed by
2122 <computeroutput>VBoxManage list hdds</computeroutput> (see <xref linkend="vboxmanage-list" />
2123 for more information). A filename must be specified as valid path, either
2124 as an absolute path or as a relative path starting from the current
2125 directory.</para>
2126 </sect1>
2127
2128 <sect1 id="vboxmanage-createvdi">
2129 <title>VBoxManage createhd</title>
2130
2131 <para>This command creates a new virtual hard disk image. The syntax is as
2132 follows:</para>
2133
2134 <screen>VBoxManage createhd --filename &lt;filename&gt;
2135 --size &lt;megabytes&gt;
2136 [--format VDI|VMDK|VHD] (default: VDI)
2137 [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
2138
2139 <para>where the parameters mean:<glosslist>
2140 <glossentry>
2141 <glossterm>filename</glossterm>
2142
2143 <glossdef>
2144 <para>Allows to choose a file name. Mandatory.</para>
2145 </glossdef>
2146 </glossentry>
2147
2148 <glossentry>
2149 <glossterm>size</glossterm>
2150
2151 <glossdef>
2152 <para>Allows to define the image capacity, in 1 MiB units.
2153 Mandatory.</para>
2154 </glossdef>
2155 </glossentry>
2156
2157 <glossentry>
2158 <glossterm>format</glossterm>
2159
2160 <glossdef>
2161 <para>Allows to choose a file format for the output file different
2162 from the file format of the input file.</para>
2163 </glossdef>
2164 </glossentry>
2165
2166 <glossentry>
2167 <glossterm>variant</glossterm>
2168
2169 <glossdef>
2170 <para>Allows to choose a file format variant for the output file.
2171 It is a comma-separated list of variant flags. Not all
2172 combinations are supported, and specifying inconsistent flags will
2173 result in an error message.</para>
2174 </glossdef>
2175 </glossentry>
2176 </glosslist> <note>
2177 <para>For compatibility with earlier versions of VirtualBox, the
2178 "createvdi" command is also supported and mapped internally to the
2179 "createhd" command.</para>
2180 </note></para>
2181 </sect1>
2182
2183 <sect1 id="vboxmanage-modifyvdi">
2184 <title>VBoxManage modifyhd</title>
2185
2186 <para>With the <computeroutput>modifyhd</computeroutput> command, you can
2187 change the characteristics of a disk image after it has been
2188 created:<screen>VBoxManage modifyhd &lt;uuid&gt;|&lt;filename&gt;
2189 [--type normal|writethrough|immutable|shareable|
2190 readonly|multiattach]
2191 [--autoreset on|off]
2192 [--compact]
2193 [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]</screen><note>
2194 <para>Despite the "hd" in the subcommand name, the command works with
2195 all disk images, not only hard disks. For compatibility with earlier
2196 versions of VirtualBox, the "modifyvdi" command is also supported and
2197 mapped internally to the "modifyhd" command.</para>
2198 </note></para>
2199
2200 <para>The disk image to modify must be specified either by its UUID
2201 (if the medium is registered) or by its filename. Registered images
2202 can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
2203 (see <xref linkend="vboxmanage-list" /> for more information).
2204 A filename must be specified as valid path, either as an absolute path
2205 or as a relative path starting from the current directory.</para>
2206 <para>The following options are available:<itemizedlist>
2207 <listitem>
2208 <para>With the <computeroutput>--type</computeroutput> argument, you
2209 can change the type of an existing image between the normal,
2210 immutable, write-through and other modes; see <xref
2211 linkend="hdimagewrites" /> for details.</para>
2212 </listitem>
2213
2214 <listitem>
2215 <para>For immutable (differencing) hard disks only, the
2216 <computeroutput>--autoreset on|off</computeroutput> option
2217 determines whether the disk is automatically reset on every VM
2218 startup (again, see <xref linkend="hdimagewrites" />). The default
2219 is "on".</para>
2220 </listitem>
2221
2222 <listitem>
2223 <para>With the <computeroutput>--compact</computeroutput> option,
2224 can be used to compact disk images, i.e. remove blocks that only
2225 contains zeroes. This will shrink a dynamically allocated image
2226 again; it will reduce the <emphasis>physical</emphasis> size of the
2227 image without affecting the logical size of the virtual disk.
2228 Compaction works both for base images and for diff images created as
2229 part of a snapshot.</para>
2230
2231 <para>For this operation to be effective, it is required that free
2232 space in the guest system first be zeroed out using a suitable
2233 software tool. For Windows guests, you can use the
2234 <computeroutput>sdelete</computeroutput> tool provided by Microsoft.
2235 Execute <computeroutput>sdelete -z</computeroutput> in the guest to
2236 zero the free disk space before compressing the virtual disk
2237 image. For Linux, use the <code>zerofree</code> utility which
2238 supports ext2/ext3 filesystems. For Mac OS X guests, use the
2239 <emphasis>Erase Free Space</emphasis> feature of the built-in
2240 <emphasis>Disk Utility</emphasis>. Use
2241 <emphasis>Zero Out Data</emphasis> there.</para>
2242
2243 <para>Please note that compacting is currently only available for
2244 VDI images. A similar effect can be achieved by zeroing out free
2245 blocks and then cloning the disk to any other dynamically allocated
2246 format. You can use this workaround until compacting is also
2247 supported for disk formats other than VDI.</para>
2248 </listitem>
2249
2250 <listitem>
2251 <para>The <computeroutput>--resize x</computeroutput> option (where x
2252 is the desired new total space in <emphasis role="bold">megabytes</emphasis>)
2253 allows you to change the capacity of an existing image; this adjusts the
2254 <emphasis>logical</emphasis> size of a virtual disk without affecting
2255 the physical size much.<footnote>
2256 <para>Image resizing was added with VirtualBox 4.0.</para>
2257 </footnote> This currently works only for VDI and VHD formats, and only
2258 for the dynamically allocated variants, and can only be used to expand
2259 (not shrink) the capacity.
2260 For example, if you originally created a 10G disk which is now full,
2261 you can use the <computeroutput>--resize 15360</computeroutput>
2262 command to change the capacity to 15G (15,360MB) without having to create a new
2263 image and copy all data from within a virtual machine. Note however that
2264 this only changes the drive capacity; you will typically next need to use
2265 a partition management tool inside the guest to adjust the main partition
2266 to fill the drive.</para><para>The <computeroutput>--resizebyte x</computeroutput>
2267 option does almost the same thing, except that x is expressed in bytes
2268 instead of megabytes.</para>
2269 </listitem>
2270 </itemizedlist></para>
2271 </sect1>
2272
2273 <sect1 id="vboxmanage-clonevdi">
2274 <title>VBoxManage clonehd</title>
2275
2276 <para>This command duplicates a registered virtual hard disk image to a
2277 new image file with a new unique identifier (UUID). The new image can be
2278 transferred to another host system or imported into VirtualBox again using
2279 the Virtual Media Manager; see <xref linkend="vdis" /> and <xref
2280 linkend="cloningvdis" />. The syntax is as follows:</para>
2281
2282 <screen>VBoxManage clonehd &lt;uuid&gt;|&lt;filename&gt; &lt;outputfile&gt;
2283 [--format VDI|VMDK|VHD|RAW|&lt;other&gt;]
2284 [--variant Standard,Fixed,Split2G,Stream,ESX]
2285 [--existing]</screen>
2286
2287 <para>The disk image to clone as well as the target image must be described
2288 either by its UUIDs (if the mediums are registered) or by its filename.
2289 Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
2290 (see <xref linkend="vboxmanage-list" /> for more information).
2291 A filename must be specified as valid path, either as an absolute path or
2292 as a relative path starting from the current directory.</para>
2293 <para>The following options are available:<glosslist>
2294 <glossentry>
2295 <glossterm>format</glossterm>
2296
2297 <glossdef>
2298 <para>Allow to choose a file format for the output file different
2299 from the file format of the input file.</para>
2300 </glossdef>
2301 </glossentry>
2302
2303 <glossentry>
2304 <glossterm>variant</glossterm>
2305
2306 <glossdef>
2307 <para>Allow to choose a file format variant for the output file.
2308 It is a comma-separated list of variant flags. Not all
2309 combinations are supported, and specifying inconsistent flags will
2310 result in an error message.</para>
2311 </glossdef>
2312 </glossentry>
2313
2314 <glossentry>
2315 <glossterm>existing</glossterm>
2316
2317 <glossdef>
2318 <para>Perform the clone operation to an already existing
2319 destination medium. Only the portion of the source medium which
2320 fits into the destination medium is copied. This means if the
2321 destination medium is smaller than the source only a part of it is
2322 copied, and if the destination medium is larger than the source
2323 the remaining part of the destination medium is unchanged.</para>
2324 </glossdef>
2325 </glossentry>
2326 </glosslist> <note>
2327 <para>For compatibility with earlier versions of VirtualBox, the
2328 "clonevdi" command is also supported and mapped internally to the
2329 "clonehd" command.</para>
2330 </note></para>
2331 </sect1>
2332
2333 <sect1>
2334 <title>VBoxManage convertfromraw</title>
2335
2336 <para>This command converts a raw disk image to a VirtualBox Disk Image
2337 (VDI) file. The syntax is as follows:</para>
2338
2339 <screen>VBoxManage convertfromraw &lt;filename&gt; &lt;outputfile&gt;
2340 [--format VDI|VMDK|VHD]
2341 [--variant Standard,Fixed,Split2G,Stream,ESX]
2342 [--uuid &lt;uuid&gt;]
2343VBoxManage convertfromraw stdin &lt;outputfile&gt; &lt;bytes&gt;
2344 [--format VDI|VMDK|VHD]
2345 [--variant Standard,Fixed,Split2G,Stream,ESX]
2346 [--uuid &lt;uuid&gt;]</screen>
2347
2348 <para>where the parameters mean:<glosslist>
2349 <glossentry>
2350 <glossterm>bytes</glossterm>
2351
2352 <glossdef>
2353 <para>The size of the image file, in bytes, provided through
2354 stdin.</para>
2355 </glossdef>
2356 </glossentry>
2357
2358 <glossentry>
2359 <glossterm>format</glossterm>
2360
2361 <glossdef>
2362 <para>Select the disk image format to create. Default is
2363 VDI.</para>
2364 </glossdef>
2365 </glossentry>
2366
2367 <glossentry>
2368 <glossterm>variant</glossterm>
2369
2370 <glossdef>
2371 <para>Allow to choose a file format variant for the output file.
2372 It is a comma-separated list of variant flags. Not all
2373 combinations are supported, and specifying inconsistent flags will
2374 result in an error message.</para>
2375 </glossdef>
2376 </glossentry>
2377
2378 <glossentry>
2379 <glossterm>uuid</glossterm>
2380
2381 <glossdef>
2382 <para>Allow to specifiy the UUID of the output file.</para>
2383 </glossdef>
2384 </glossentry>
2385 </glosslist> The second form forces VBoxManage to read the content for
2386 the disk image from standard input (useful for using that command in a
2387 pipe).</para>
2388
2389 <para><note>
2390 <para>For compatibility with earlier versions of VirtualBox, the
2391 "convertdd" command is also supported and mapped internally to the
2392 "convertfromraw" command.</para>
2393 </note></para>
2394 </sect1>
2395
2396 <sect1>
2397 <title>VBoxManage getextradata/setextradata</title>
2398
2399 <para>These commands let you attach and retrieve string data to a virtual
2400 machine or to a VirtualBox configuration (by specifying
2401 <computeroutput>global</computeroutput> instead of a virtual machine
2402 name). You must specify a key (as a text string) to associate the data
2403 with, which you can later use to retrieve it. For example:</para>
2404
2405 <screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
2406VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
2407
2408 <para>would associate the string "2006.01.01" with the key installdate for
2409 the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
2410 could retrieve the information as follows:</para>
2411
2412 <screen>VBoxManage getextradata Fedora5 installdate</screen>
2413
2414 <para>which would return</para>
2415
2416 <screen>VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
2417(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
2418All rights reserved.
2419
2420Value: 2006.01.01</screen>
2421 <para>To remove a key, the <computeroutput>setextradata</computeroutput>
2422 command must be run without specifying data (only the key), for example:
2423 </para>
2424
2425 <screen>VBoxManage setextradata Fedora5 installdate</screen>
2426
2427 </sect1>
2428
2429 <sect1 id="vboxmanage-setproperty">
2430 <title>VBoxManage setproperty</title>
2431
2432 <para>This command is used to change global settings which affect the
2433 entire VirtualBox installation. Some of these correspond to the settings
2434 in the "Global settings" dialog in the graphical user interface. The
2435 following properties are available:<glosslist>
2436 <glossentry>
2437 <glossterm>machinefolder</glossterm>
2438
2439 <glossdef>
2440 <para>This specifies the default folder in which virtual machine
2441 definitions are kept; see <xref linkend="vboxconfigdata" /> for
2442 details.</para>
2443 </glossdef>
2444 </glossentry>
2445
2446 <glossentry>
2447 <glossterm>vrdeauthlibrary</glossterm>
2448
2449 <glossdef>
2450 <para>This specifies which library to use when "external"
2451 authentication has been selected for a particular virtual machine;
2452 see <xref linkend="vbox-auth" /> for details.</para>
2453 </glossdef>
2454 </glossentry>
2455
2456 <glossentry>
2457 <glossterm>websrvauthlibrary</glossterm>
2458
2459 <glossdef>
2460 <para>This specifies which library the web service uses to
2461 authenticate users. For details about the VirtualBox web service,
2462 please refer to the separate VirtualBox SDK reference (see <xref
2463 linkend="VirtualBoxAPI" />).</para>
2464 </glossdef>
2465 </glossentry>
2466
2467 <glossentry>
2468 <glossterm>vrdelibrary</glossterm>
2469
2470 <glossdef>
2471 <para>This specifies which library implements the VirtualBox
2472 Remote Desktop Extension.</para>
2473 </glossdef>
2474 </glossentry>
2475
2476 <glossentry>
2477 <glossterm>hwvirtexenabled</glossterm>
2478
2479 <glossdef>
2480 <para>This selects whether or not hardware virtualization support
2481 is enabled by default.</para>
2482 </glossdef>
2483 </glossentry>
2484 </glosslist></para>
2485 </sect1>
2486
2487 <sect1>
2488 <title>VBoxManage usbfilter add/modify/remove</title>
2489
2490 <para>The <computeroutput>usbfilter</computeroutput> commands are used for
2491 working with USB filters in virtual machines, or global filters which
2492 affect the whole VirtualBox setup. Global filters are applied before
2493 machine-specific filters, and may be used to prevent devices from being
2494 captured by any virtual machine. Global filters are always applied in a
2495 particular order, and only the first filter which fits a device is
2496 applied. So for example, if the first global filter says to hold (make
2497 available) a particular Kingston memory stick device and the second to
2498 ignore all Kingston devices, that memory stick will be available to any
2499 machine with an appropriate filter, but no other Kingston device
2500 will.</para>
2501
2502 <para>When creating a USB filter using <computeroutput>usbfilter
2503 add</computeroutput>, you must supply three or four mandatory parameters.
2504 The index specifies the position in the list at which the filter should be
2505 placed. If there is already a filter at that position, then it and the
2506 following ones will be shifted back one place. Otherwise the new filter
2507 will be added onto the end of the list. The
2508 <computeroutput>target</computeroutput> parameter selects the virtual
2509 machine that the filter should be attached to or use "global" to apply it
2510 to all virtual machines. <computeroutput>name</computeroutput> is a name
2511 for the new filter and for global filters,
2512 <computeroutput>action</computeroutput> says whether to allow machines
2513 access to devices that fit the filter description ("hold") or not to give
2514 them access ("ignore"). In addition, you should specify parameters to
2515 filter by. You can find the parameters for devices attached to your system
2516 using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
2517 you can specify whether the filter should be active, and for local
2518 filters, whether they are for local devices, remote (over an RDP
2519 connection) or either.</para>
2520
2521 <para>When you modify a USB filter using <computeroutput>usbfilter
2522 modify</computeroutput>, you must specify the filter by index (see the
2523 output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
2524 find global filter indexes and that of <computeroutput>VBoxManage
2525 showvminfo</computeroutput> to find indexes for individual machines) and
2526 by target, which is either a virtual machine or "global". The properties
2527 which can be changed are the same as for <computeroutput>usbfilter
2528 add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
2529 remove</computeroutput> and specify the index and the target.</para>
2530 </sect1>
2531
2532 <sect1 id="vboxmanage-sharedfolder">
2533 <title>VBoxManage sharedfolder add/remove</title>
2534
2535 <para>This command allows you to share folders on the host computer with
2536 guest operating systems. For this, the guest systems must have a version
2537 of the VirtualBox Guest Additions installed which supports this
2538 functionality.</para>
2539
2540 <para>Shared folders are described in detail in <xref
2541 linkend="sharedfolders" />.</para>
2542 </sect1>
2543
2544 <sect1 id="vboxmanage-guestproperty">
2545 <title>VBoxManage guestproperty</title>
2546
2547 <para>The "guestproperty" commands allow you to get or set properties of a
2548 running virtual machine. Please see <xref linkend="guestadd-guestprops" />
2549 for an introduction. As explained there, guest properties are arbitrary
2550 key/value string pairs which can be written to and read from by either the
2551 guest or the host, so they can be used as a low-volume communication
2552 channel for strings, provided that a guest is running and has the Guest
2553 Additions installed. In addition, a number of values whose keys begin with
2554 "/VirtualBox/" are automatically set and maintained by the Guest
2555 Additions.</para>
2556
2557 <para>The following subcommands are available (where
2558 <computeroutput>&lt;vm&gt;</computeroutput>, in each case, can either be a
2559 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
2560 <listitem>
2561 <para><computeroutput>enumerate &lt;vm&gt; [--patterns
2562 &lt;pattern&gt;]</computeroutput>: This lists all the guest
2563 properties that are available for the given VM, including the value.
2564 This list will be very limited if the guest's service process cannot
2565 be contacted, e.g. because the VM is not running or the Guest
2566 Additions are not installed.</para>
2567
2568 <para>If <computeroutput>--patterns &lt;pattern&gt;</computeroutput>
2569 is specified, it acts as a filter to only list properties that match
2570 the given pattern. The pattern can contain the following wildcard
2571 characters:<itemizedlist>
2572 <listitem>
2573 <para><computeroutput>*</computeroutput> (asterisk):
2574 represents any number of characters; for example,
2575 "<computeroutput>/VirtualBox*</computeroutput>" would match
2576 all properties beginning with "/VirtualBox".</para>
2577 </listitem>
2578
2579 <listitem>
2580 <para><computeroutput>?</computeroutput> (question mark):
2581 represents a single arbitrary character; for example,
2582 "<computeroutput>fo?</computeroutput>" would match both "foo"
2583 and "for".</para>
2584 </listitem>
2585
2586 <listitem>
2587 <para><computeroutput>|</computeroutput> (pipe symbol): can be
2588 used to specify multiple alternative patterns; for example,
2589 "<computeroutput>s*|t*</computeroutput>" would match anything
2590 starting with either "s" or "t".</para>
2591 </listitem>
2592 </itemizedlist></para>
2593 </listitem>
2594
2595 <listitem>
2596 <para><computeroutput>get &lt;vm&gt;</computeroutput>: This
2597 retrieves the value of a single property only. If the property
2598 cannot be found (e.g. because the guest is not running), this will
2599 print <screen>No value set!</screen></para>
2600 </listitem>
2601
2602 <listitem>
2603 <para><computeroutput>set &lt;vm&gt; &lt;property&gt; [&lt;value&gt;
2604 [--flags &lt;flags&gt;]]</computeroutput>: This allows you to set a
2605 guest property by specifying the key and value. If
2606 <computeroutput>&lt;value&gt;</computeroutput> is omitted, the
2607 property is deleted. With <computeroutput>--flags</computeroutput>
2608 you can optionally specify additional behavior (you can combine
2609 several by separating them with commas):<itemizedlist>
2610 <listitem>
2611 <para><computeroutput>TRANSIENT</computeroutput>: the value
2612 will not be stored with the VM data when the VM exits;</para>
2613 </listitem>
2614
2615 <listitem>
2616 <para><computeroutput>TRANSRESET</computeroutput>: the value
2617 will be deleted as soon as the VM restarts and/or exits;</para>
2618 </listitem>
2619
2620 <listitem>
2621 <para><computeroutput>RDONLYGUEST</computeroutput>: the value
2622 can only be changed by the host, but the guest can only read
2623 it;</para>
2624 </listitem>
2625
2626 <listitem>
2627 <para><computeroutput>RDONLYHOST</computeroutput>: reversely,
2628 the value can only be changed by the guest, but the host can
2629 only read it;</para>
2630 </listitem>
2631
2632 <listitem>
2633 <para><computeroutput>READONLY</computeroutput>: a combination
2634 of the two, the value cannot be changed at all.</para>
2635 </listitem>
2636 </itemizedlist></para>
2637 </listitem>
2638
2639 <listitem>
2640 <para><computeroutput>wait &lt;vm&gt; &lt;pattern&gt; --timeout
2641 &lt;timeout&gt;</computeroutput>: This waits for a particular value
2642 described by "pattern" to change or to be deleted or created. The
2643 pattern rules are the same as for the "enumerate" subcommand
2644 above.</para>
2645 </listitem>
2646
2647 <listitem>
2648 <para><computeroutput>delete &lt;vm&gt; &lt;property&gt;
2649 </computeroutput>: Deletes a formerly set guest property.
2650 </para></listitem>
2651 </itemizedlist></para>
2652 </sect1>
2653
2654 <sect1 id="vboxmanage-guestcontrol">
2655 <title>VBoxManage guestcontrol</title>
2656
2657 <para>The "guestcontrol" commands allow you to control certain things
2658 inside a guest from the host. Please see <xref
2659 linkend="guestadd-guestcontrol" /> for an introduction.</para>
2660
2661 <para>Generally, the syntax is as follows:</para>
2662
2663 <screen>VBoxManage guestcontrol &lt;command&gt;</screen>
2664
2665 <para>The following subcommands are available (where
2666 <computeroutput>&lt;vm&gt;</computeroutput>, in each case, can either be a
2667 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
2668 <listitem>
2669 <para><computeroutput>execute</computeroutput>, which allows for
2670 executing a program/script (process) which already is installed and
2671 runnable on the guest. This command only works while a VM is up and
2672 running and has the following syntax:</para>
2673
2674 <screen>VBoxManage guestcontrol &lt;vmname&gt;|&lt;uuid&gt; exec[ute]
2675 --image &lt;path to program&gt; --username &lt;name&gt;
2676 [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
2677 [--environment "&lt;NAME&gt;=&lt;VALUE&gt; [&lt;NAME&gt;=&lt;VALUE&gt;]"]
2678 [--verbose] [--timeout &lt;msec&gt;]
2679 [--wait-exit] [--wait-stdout] [--wait-stderr]
2680 [--dos2unix] [--unix2dos]
2681 -- [[&lt;argument1&gt;] ... [&lt;argumentN&gt;]]</screen>
2682
2683 <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>--image "&lt;path to program&gt;"</glossterm>
2694
2695 <glossdef>
2696 <para>Absolute path and process name of process to execute
2697 in the guest, e.g.
2698 <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
2699 </glossdef>
2700 </glossentry>
2701
2702 <glossentry>
2703 <glossterm>--username &lt;name&gt;</glossterm>
2704
2705 <glossdef>
2706 <para>Name of the user the process should run under. This
2707 user must exist on the guest OS.</para>
2708 </glossdef>
2709 </glossentry>
2710
2711 <glossentry>
2712 <glossterm>--passwordfile &lt;file&gt;</glossterm>
2713
2714 <glossdef>
2715 <para>Password of the user account specified to be read from
2716 the given file. If not given, an empty password is
2717 assumed.</para>
2718 </glossdef>
2719 </glossentry>
2720
2721 <glossentry>
2722 <glossterm>--password &lt;password&gt;</glossterm>
2723
2724 <glossdef>
2725 <para>Password of the user account specified with
2726 <computeroutput>--username</computeroutput>. If not given,
2727 an empty password is assumed.</para>
2728 </glossdef>
2729 </glossentry>
2730
2731 <glossentry>
2732 <glossterm>--dos2unix</glossterm>
2733
2734 <glossdef>
2735 Converts output from DOS/Windows guests to UNIX-compatible
2736 line endings (CR + LF -> LF). Not implemented yet.
2737 </glossdef>
2738 </glossentry>
2739
2740 <glossentry>
2741 <glossterm>--environment
2742 "&lt;NAME&gt;=&lt;VALUE&gt;"</glossterm>
2743
2744 <glossdef>
2745 <para>One or more environment variables to be set or
2746 unset.</para>
2747
2748 <para>By default, the new process in the guest will be
2749 created with the standard environment of the guest OS. This
2750 option allows for modifying that environment. To set/modify
2751 a variable, a pair of
2752 <computeroutput>NAME=VALUE</computeroutput> must be
2753 specified; to unset a certain variable, the name with no
2754 value must set, e.g.
2755 <computeroutput>NAME=</computeroutput>.</para>
2756
2757 <para>Arguments containing spaces must be enclosed in
2758 quotation marks. More than one
2759 <computeroutput>--environment</computeroutput> at a time can
2760 be specified to keep the command line tidy.</para>
2761 </glossdef>
2762 </glossentry>
2763
2764 <glossentry>
2765 <glossterm>--timeout &lt;msec&gt;</glossterm>
2766
2767 <glossdef>
2768 <para>Value (in milliseconds) that specifies the time how
2769 long the started process is allowed to run and how long
2770 VBoxManage waits for getting output from that process. If no
2771 timeout is specified, VBoxManage will wait forever until the
2772 started process ends or an error occured.</para>
2773 </glossdef>
2774 </glossentry>
2775
2776 <glossentry>
2777 <glossterm>--unix2dos</glossterm>
2778
2779 <glossdef>
2780 Converts output from a UNIX/Linux guests to DOS-/Windows-compatible
2781 line endings (LF -> CR + LF). Not implemented yet.
2782 </glossdef>
2783 </glossentry>
2784
2785 <glossentry>
2786 <glossterm>--verbose</glossterm>
2787
2788 <glossdef>
2789 <para>Tells VBoxManage to be more verbose.</para>
2790 </glossdef>
2791 </glossentry>
2792
2793 <glossentry>
2794 <glossterm>--wait-exit</glossterm>
2795
2796 <glossdef>
2797 <para>Waits until the process ends and outputs its
2798 exit code along with the exit reason/flags.</para>
2799 </glossdef>
2800 </glossentry>
2801
2802 <glossentry>
2803 <glossterm>--wait-stdout</glossterm>
2804
2805 <glossdef>
2806 <para>Waits until the process ends and outputs its
2807 exit code along with the exit reason/flags. While waiting
2808 VBoxManage retrieves the process output collected from stdout.</para>
2809 </glossdef>
2810 </glossentry>
2811
2812 <glossentry>
2813 <glossterm>--wait-stderr</glossterm>
2814
2815 <glossdef>
2816 <para>Waits until the process ends and outputs its
2817 exit code along with the exit reason/flags. While waiting
2818 VBoxManage retrieves the process output collected from stderr.</para>
2819 </glossdef>
2820 </glossentry>
2821
2822 <glossentry>
2823 <glossterm>[-- [&lt;argument1s&gt;] ... [&lt;argumentNs&gt;]]</glossterm>
2824
2825 <glossdef>
2826 <para>One or more arguments to pass to the process being
2827 executed.</para>
2828 <para>Arguments containing spaces must be enclosed in
2829 quotation marks.</para>
2830 </glossdef>
2831 </glossentry>
2832
2833 </glosslist></para>
2834
2835 <para><note>
2836 <para>On Windows there are certain limitations for graphical
2837 applications; please see <xref linkend="KnownIssues" /> for more
2838 information.</para>
2839 </note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls"
2840 --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "c:\\windows\\system32\\ipconfig.exe"
2841 --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
2842 the double backslashes in the second example are only required on
2843 Unix hosts.</para>
2844
2845 <para><note>
2846 <para>For certain commands a user name of an existing user account on the guest
2847 must be specified; anonymous executions are not supported for security reasons. A
2848 user account password, however, is optional and depends on the guest's OS security
2849 policy or rules. If no password is specified for a given user name, an empty password
2850 will be used. On certain OSes like Windows the security policy may needs to be adjusted
2851 in order to allow user accounts with an empty password set. Also, global domain rules might
2852 apply and therefore cannot be changed.</para>
2853 </note></para>
2854
2855 <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
2856 to serve up to 5 guest processes at a time. If a new guest process gets started
2857 which would exceed this limit, the oldest not running guest process will be discarded
2858 in order to be able to run that new process. Also, retrieving output from this
2859 old guest process will not be possible anymore then. If all 5 guest processes
2860 are still active and running, starting a new guest process will result in an
2861 appropriate error message.</para>
2862
2863 <para>To raise or lower the guest process execution limit, either the guest
2864 property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
2865 or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
2866 needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
2867 guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
2868 </listitem>
2869
2870 <listitem>
2871 <para><computeroutput>copyto</computeroutput>, which allows copying
2872 files from the host to the guest (only with installed Guest
2873 Additions 4.0 and later).</para>
2874
2875 <screen>VBoxManage guestcontrol &lt;vmname&gt;|&lt;uuid&gt; copyto|cp
2876 &lt;guest source&gt; &lt;host dest&gt; --username &lt;name&gt;
2877 [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
2878 [--dryrun] [--follow] [--recursive] [--verbose]</screen>
2879
2880 <para>where the parameters mean: <glosslist>
2881 <glossentry>
2882 <glossterm>uuid|vmname</glossterm>
2883
2884 <glossdef>
2885 <para>The VM UUID or VM name. Mandatory.</para>
2886 </glossdef>
2887 </glossentry>
2888
2889 <glossentry>
2890 <glossterm>source on host</glossterm>
2891
2892 <glossdef>
2893 <para>Absolute path of source file(s) on host to copy over
2894 to the guest, e.g.
2895 <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
2896 This also can be a wildcard expression, e.g.
2897 <computeroutput>C:\Windows\System32\*.dll</computeroutput></para>
2898 </glossdef>
2899 </glossentry>
2900
2901 <glossentry>
2902 <glossterm>destination on guest</glossterm>
2903
2904 <glossdef>
2905 <para>Absolute destination path on the guest, e.g.
2906 <computeroutput>C:\Temp</computeroutput></para>
2907 </glossdef>
2908 </glossentry>
2909
2910 <glossentry>
2911 <glossterm>--username &lt;name&gt;</glossterm>
2912
2913 <glossdef>
2914 <para>Name of the user the copy process should run under.
2915 This user must exist on the guest OS.</para>
2916 </glossdef>
2917 </glossentry>
2918
2919 <glossentry>
2920 <glossterm>--passwordfile &lt;file&gt;</glossterm>
2921
2922 <glossdef>
2923 <para>Password of the user account specified to be read from
2924 the given file. If not given, an empty password is
2925 assumed.</para>
2926 </glossdef>
2927 </glossentry>
2928
2929 <glossentry>
2930 <glossterm>--password &lt;password&gt;</glossterm>
2931
2932 <glossdef>
2933 <para>Password of the user account specified with
2934 <computeroutput>--username</computeroutput>. If not given,
2935 an empty password is assumed.</para>
2936 </glossdef>
2937 </glossentry>
2938
2939 <glossentry>
2940 <glossterm>--dryrun</glossterm>
2941
2942 <glossdef>
2943 <para>Tells VBoxManage to only perform a dry run instead of
2944 really copying files to the guest.</para>
2945 </glossdef>
2946 </glossentry>
2947
2948 <glossentry>
2949 <glossterm>--follow</glossterm>
2950
2951 <glossdef>
2952 <para>Enables following symlinks on the host's
2953 source.</para>
2954 </glossdef>
2955 </glossentry>
2956
2957 <glossentry>
2958 <glossterm>--recursive</glossterm>
2959
2960 <glossdef>
2961 <para>Recursively copies files/directories of the specified
2962 source.</para>
2963 </glossdef>
2964 </glossentry>
2965
2966 <glossentry>
2967 <glossterm>--verbose</glossterm>
2968
2969 <glossdef>
2970 <para>Tells VBoxManage to be more verbose.</para>
2971 </glossdef>
2972 </glossentry>
2973
2974 <glossentry>
2975 <glossterm>--flags &lt;flags&gt;</glossterm>
2976
2977 <glossdef>
2978 <para>Additional flags to set. This is not used at the
2979 moment.</para>
2980 </glossdef>
2981 </glossentry>
2982 </glosslist></para>
2983 </listitem>
2984
2985 <listitem>
2986 <para><computeroutput>copyfrom</computeroutput>, which allows copying
2987 files from the guest to the host (only with installed Guest
2988 Additions 4.0 and later). It has the same parameters as
2989 <computeroutput>copyto</computeroutput> above.</para>
2990 </listitem>
2991
2992 <listitem>
2993 <para><computeroutput>createdirectory</computeroutput>, which allows
2994 copying files from the host to the guest (only with installed Guest
2995 Additions 4.0 and later).</para>
2996
2997 <screen>VBoxManage guestcontrol &lt;vmname&gt;|&lt;uuid&gt; createdir[ectory]|mkdir|md
2998 &lt;guest directory&gt;... --username &lt;name&gt;
2999 [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
3000 [--parents] [--mode &lt;mode&gt;] [--verbose]</screen>
3001
3002 <para>where the parameters mean: <glosslist>
3003 <glossentry>
3004 <glossterm>uuid|vmname</glossterm>
3005
3006 <glossdef>
3007 <para>The VM UUID or VM name. Mandatory.</para>
3008 </glossdef>
3009 </glossentry>
3010
3011 <glossentry>
3012 <glossterm>directory to create on guest</glossterm>
3013
3014 <glossdef>
3015 <para>Absolute path of directory/directories to create on
3016 guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>.
3017 Parent directories need to exist (e.g. in this example
3018 <computeroutput>D:\Foo</computeroutput>) when switch
3019 <computeroutput>--parents</computeroutput> is omitted. The
3020 specified user must have appropriate rights to create the
3021 specified directory.</para>
3022 </glossdef>
3023 </glossentry>
3024
3025 <glossentry>
3026 <glossterm>--username &lt;name&gt;</glossterm>
3027
3028 <glossdef>
3029 <para>Name of the user the copy process should run under.
3030 This user must exist on the guest OS.</para>
3031 </glossdef>
3032 </glossentry>
3033
3034 <glossentry>
3035 <glossterm>--passwordfile &lt;file&gt;</glossterm>
3036
3037 <glossdef>
3038 <para>Password of the user account specified to be read from
3039 the given file. If not given, an empty password is
3040 assumed.</para>
3041 </glossdef>
3042 </glossentry>
3043
3044 <glossentry>
3045 <glossterm>--password &lt;password&gt;</glossterm>
3046
3047 <glossdef>
3048 <para>Password of the user account specified with
3049 <computeroutput>--username</computeroutput>. If not given,
3050 an empty password is assumed.</para>
3051 </glossdef>
3052 </glossentry>
3053
3054 <glossentry>
3055 <glossterm>--parents</glossterm>
3056
3057 <glossdef>
3058 <para>Also creates not yet existing parent directories of
3059 the specified directory, e.g. if the directory
3060 <computeroutput>D:\Foo</computeroutput> of
3061 <computeroutput>D:\Foo\Bar</computeroutput> does not exist
3062 yet it will be created. Without specifying
3063 <computeroutput>--parent</computeroutput> the action would
3064 have failed.</para>
3065 </glossdef>
3066 </glossentry>
3067
3068 <glossentry>
3069 <glossterm>--mode &lt;mode&gt;</glossterm>
3070
3071 <glossdef>
3072 <para>Sets the permission mode of the specified directory.
3073 Only octal modes (e.g.
3074 <computeroutput>0755</computeroutput>) are supported right
3075 now.</para>
3076 </glossdef>
3077 </glossentry>
3078
3079 <glossentry>
3080 <glossterm>--verbose</glossterm>
3081
3082 <glossdef>
3083 <para>Tells VBoxManage to be more verbose.</para>
3084 </glossdef>
3085 </glossentry>
3086 </glosslist></para>
3087 </listitem>
3088
3089 <listitem>
3090 <para><computeroutput>stat</computeroutput>, which displays file
3091 or file system status on the guest.</para>
3092
3093 <screen>VBoxManage guestcontrol &lt;vmname&gt;|&lt;uuid&gt; stat
3094 &lt;file&gt;... --username &lt;name&gt;
3095 [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
3096 [--verbose]</screen>
3097
3098 <para>where the parameters mean: <glosslist>
3099 <glossentry>
3100 <glossterm>uuid|vmname</glossterm>
3101
3102 <glossdef>
3103 <para>The VM UUID or VM name. Mandatory.</para>
3104 </glossdef>
3105 </glossentry>
3106
3107 <glossentry>
3108 <glossterm>file element(s) to check on guest</glossterm>
3109
3110 <glossdef>
3111 <para>Absolute path of directory/directories to check on
3112 guest, e.g. <computeroutput>/home/foo/a.out</computeroutput>.
3113 The specified user must have appropriate rights to access
3114 the given file element(s).</para>
3115 </glossdef>
3116 </glossentry>
3117
3118 <glossentry>
3119 <glossterm>--username &lt;name&gt;</glossterm>
3120
3121 <glossdef>
3122 <para>Name of the user the copy process should run under.
3123 This user must exist on the guest OS.</para>
3124 </glossdef>
3125 </glossentry>
3126
3127 <glossentry>
3128 <glossterm>--passwordfile &lt;file&gt;</glossterm>
3129
3130 <glossdef>
3131 <para>Password of the user account specified to be read from
3132 the given file. If not given, an empty password is
3133 assumed.</para>
3134 </glossdef>
3135 </glossentry>
3136
3137 <glossentry>
3138 <glossterm>--password &lt;password&gt;</glossterm>
3139
3140 <glossdef>
3141 <para>Password of the user account specified with
3142 <computeroutput>--username</computeroutput>. If not given,
3143 an empty password is assumed.</para>
3144 </glossdef>
3145 </glossentry>
3146
3147 <glossentry>
3148 <glossterm>--verbose</glossterm>
3149
3150 <glossdef>
3151 <para>Tells VBoxManage to be more verbose.</para>
3152 </glossdef>
3153 </glossentry>
3154 </glosslist></para>
3155 </listitem>
3156
3157 <listitem>
3158 <para><computeroutput>updateadditions</computeroutput>, which allows
3159 for updating an already installed Guest Additions version on the
3160 guest (only already installed Guest Additions 4.0 and later).</para>
3161
3162 <screen>VBoxManage guestcontrol &lt;vmname&gt;|&lt;uuid&gt; updateadditions
3163 [--source "&lt;guest additions .ISO file to use&gt;"] [--verbose]
3164 [--wait-start]</screen>
3165
3166 <para>where the parameters mean: <glosslist>
3167 <glossentry>
3168 <glossterm>uuid|vmname</glossterm>
3169
3170 <glossdef>
3171 <para>The VM UUID or VM name. Mandatory.</para>
3172 </glossdef>
3173 </glossentry>
3174
3175 <glossentry>
3176 <glossterm>--source "&lt;guest additions .ISO file to
3177 use&gt;"</glossterm>
3178
3179 <glossdef>
3180 <para>Full path to an alternative VirtualBox Guest Additions
3181 .ISO file to use for the Guest Additions update.</para>
3182 </glossdef>
3183 </glossentry>
3184
3185 <glossentry>
3186 <glossterm>--verbose</glossterm>
3187
3188 <glossdef>
3189 <para>Tells VBoxManage to be more verbose.</para>
3190 </glossdef>
3191 </glossentry>
3192
3193 <glossentry>
3194 <glossterm>--wait-start</glossterm>
3195 <glossdef>
3196 <para>Starts the regular updating process and waits until the
3197 actual Guest Additions update inside the guest was started.
3198 This can be necessary due to needed interaction with the
3199 guest OS during the installation phase.</para>
3200 <para>When omitting this flag VBoxManage will wait for the
3201 whole Guest Additions update to complete.</para>
3202 </glossdef>
3203 </glossentry>
3204 </glosslist></para>
3205 </listitem>
3206 </itemizedlist></para>
3207 </sect1>
3208
3209 <sect1 id="vboxmanage-debugvm">
3210 <title>VBoxManage debugvm</title>
3211
3212 <para>The "debugvm" commands are for experts who want to tinker with the
3213 exact details of virtual machine execution. Like the VM debugger described
3214 in <xref linkend="ts_debugger" />, these commands are only useful if you are
3215 very familiar with the details of the PC architecture and how to debug
3216 software.</para>
3217
3218 <para>The subcommands of "debugvm" all operate on a running virtual
3219 machine. The following are available:<itemizedlist>
3220 <listitem>
3221 <para>With <computeroutput>dumpguestcore --filename
3222 &lt;name&gt;</computeroutput>, you can create a system dump of the
3223 running VM, which will be written into the given file. This file
3224 will have the standard ELF core format (with custom sections); see
3225 <xref linkend="ts_guest-core-format" />.</para>
3226
3227 <para>This corresponds to the
3228 <computeroutput>writecore</computeroutput> command in the debugger.
3229 </para>
3230 </listitem>
3231
3232 <listitem>
3233 <para>The <computeroutput>info</computeroutput> command is used to
3234 display info items relating to the VMM, device emulations and
3235 associated drivers. This command takes one or two arguments: the
3236 name of the info item, optionally followed by a string containing
3237 arguments specific to the info item.
3238 The <computeroutput>help</computeroutput> info item provides a
3239 listning of the available items and hints about any optional
3240 arguments.</para>
3241
3242 <para>This corresponds to the <computeroutput>info</computeroutput>
3243 command in the debugger.</para>
3244 </listitem>
3245
3246 <listitem>
3247 <para>The <computeroutput>injectnmi</computeroutput> command causes
3248 a non-maskable interrupt (NMI) in the guest, which might be useful
3249 for certain debugging scenarios. What happens exactly is dependent
3250 on the guest operating system, but an NMI can crash the whole guest
3251 operating system. Do not use unless you know what you're
3252 doing.</para>
3253 </listitem>
3254
3255 <listitem>
3256 <para>The <computeroutput>osdetect</computeroutput> command makes the
3257 VMM's debugger facility (re-)detection the guest operation
3258 system.</para>
3259
3260 <para>This corresponds to the <computeroutput>detect</computeroutput>
3261 command in the debugger.</para>
3262 </listitem>
3263
3264 <listitem>
3265 <para>The <computeroutput>osinfo</computeroutput> command is used to
3266 display info about the operating system (OS) detected by the VMM's
3267 debugger facility.</para>
3268 </listitem>
3269
3270 <listitem>
3271 <para>The <computeroutput>getregisters</computeroutput> command is
3272 used to display CPU and device registers. The command takes a list
3273 of registers, each having one of the following forms:
3274 <itemizedlist>
3275 <listitem><computeroutput>register-set.register-name.sub-field</computeroutput></listitem>
3276 <listitem><computeroutput>register-set.register-name</computeroutput></listitem>
3277 <listitem><computeroutput>cpu-register-name.sub-field</computeroutput></listitem>
3278 <listitem><computeroutput>cpu-register-name</computeroutput></listitem>
3279 <listitem><computeroutput>all</computeroutput></listitem>
3280 </itemizedlist>
3281 The <computeroutput>all</computeroutput> form will cause all
3282 registers to be shown (no sub-fields). The registers names are
3283 case-insensitive. When requesting a CPU register the register set
3284 can be omitted, it will be selected using the value of the
3285 <computeroutput>--cpu</computeroutput> option (defaulting to 0).
3286 </para>
3287 </listitem>
3288
3289 <listitem>
3290 <para>The <computeroutput>setregisters</computeroutput> command is
3291 used to change CPU and device registers. The command takes a list
3292 of register assignments, each having one of the following forms:
3293 <itemizedlist>
3294 <listitem><computeroutput>register-set.register-name.sub-field=value</computeroutput></listitem>
3295 <listitem><computeroutput>register-set.register-name=value</computeroutput></listitem>
3296 <listitem><computeroutput>cpu-register-name.sub-field=value</computeroutput></listitem>
3297 <listitem><computeroutput>cpu-register-name=value</computeroutput></listitem>
3298 </itemizedlist>
3299 The value format should be in the same style as what
3300 <computeroutput>getregisters</computeroutput> displays, with the
3301 exception that both octal and decimal can be used instead of
3302 hexadecimal. The register naming and the default CPU register set
3303 are handled the same way as with the
3304 <computeroutput>getregisters</computeroutput> command.</para>
3305 </listitem>
3306
3307 <listitem>
3308 <para>The <computeroutput>statistics</computeroutput> command can be
3309 used to display VMM statistics on the command line. The
3310 <computeroutput>--reset</computeroutput> option will reset
3311 statistics. The affected statistics can be filtered with the
3312 <computeroutput>--pattern</computeroutput> option, which accepts
3313 DOS/NT-style wildcards (<computeroutput>?</computeroutput> and
3314 <computeroutput>*</computeroutput>).</para>
3315 </listitem>
3316 </itemizedlist></para>
3317 </sect1>
3318
3319 <sect1>
3320 <title id="metrics">VBoxManage metrics</title>
3321
3322 <para>This command supports monitoring the usage of system resources.
3323 Resources are represented by various metrics associated with the host
3324 system or a particular VM. For example, the host system has a
3325 <computeroutput>CPU/Load/User</computeroutput> metric that shows the
3326 percentage of time CPUs spend executing in user mode over a specific
3327 sampling period.</para>
3328
3329 <para>Metric data is collected and retained internally; it may be
3330 retrieved at any time with the <computeroutput>VBoxManage metrics
3331 query</computeroutput> subcommand. The data is available as long as the
3332 background <computeroutput>VBoxSVC</computeroutput> process is alive. That
3333 process terminates shortly after all VMs and frontends have been
3334 closed.</para>
3335
3336 <para>By default no metrics are collected at all. Metrics collection does
3337 not start until <computeroutput>VBoxManage metrics setup</computeroutput>
3338 is invoked with a proper sampling interval and the number of metrics to be
3339 retained. The interval is measured in seconds. For example, to enable
3340 collecting the host processor and memory usage metrics every second and
3341 keeping the 5 most current samples, the following command can be
3342 used:</para>
3343
3344 <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
3345
3346 <para>Metric collection can only be enabled for started VMs. Collected
3347 data and collection settings for a particular VM will disappear as soon as
3348 it shuts down. Use <computeroutput>VBoxManage metrics list
3349 </computeroutput> subcommand to see which metrics are currently available.
3350 You can also use <computeroutput>--list</computeroutput> option with any
3351 subcommand that modifies metric settings to find out which metrics were
3352 affected.</para>
3353
3354 <para>Note that the <computeroutput>VBoxManage metrics
3355 setup</computeroutput> subcommand discards all samples that may have been
3356 previously collected for the specified set of objects and metrics.</para>
3357
3358 <para>To enable or disable metrics collection without discarding the data
3359 <computeroutput>VBoxManage metrics enable</computeroutput> and
3360 <computeroutput>VBoxManage metrics disable</computeroutput> subcommands
3361 can be used. Note that these subcommands expect metrics, not submetrics,
3362 like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
3363 other words enabling <code>CPU/Load/User</code> while disabling
3364 <code>CPU/Load/Kernel</code> is not supported.</para>
3365
3366 <para>The host and VMs have different sets of associated metrics.
3367 Available metrics can be listed with <computeroutput>VBoxManage metrics
3368 list</computeroutput> subcommand.</para>
3369
3370 <para>A complete metric name may include an aggregate function. The name
3371 has the following form:
3372 <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
3373 For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
3374 for the minimum amount of available memory over all retained data if
3375 applied to the host object.</para>
3376
3377 <para>Subcommands may apply to all objects and metrics or can be limited
3378 to one object or/and a list of metrics. If no objects or metrics are given
3379 in the parameters, the subcommands will apply to all available metrics of
3380 all objects. You may use an asterisk
3381 ("<computeroutput>*</computeroutput>") to explicitly specify that the
3382 command should be applied to all objects or metrics. Use "host" as the
3383 object name to limit the scope of the command to host-related metrics. To
3384 limit the scope to a subset of metrics, use a metric list with names
3385 separated by commas.</para>
3386
3387 <para>For example, to query metric data on the CPU time spent in user and
3388 kernel modes by the virtual machine named "test", you can use the
3389 following command:</para>
3390
3391 <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
3392
3393 <para>The following list summarizes the available subcommands:</para>
3394
3395 <glosslist>
3396 <glossentry>
3397 <glossterm>list</glossterm>
3398
3399 <glossdef>
3400 <para>This subcommand shows the parameters of the currently existing
3401 metrics. Note that VM-specific metrics are only available when a
3402 particular VM is running.</para>
3403 </glossdef>
3404 </glossentry>
3405
3406 <glossentry>
3407 <glossterm>setup</glossterm>
3408
3409 <glossdef>
3410 <para>This subcommand sets the interval between taking two samples
3411 of metric data and the number of samples retained internally. The
3412 retained data is available for displaying with the
3413 <code>query</code> subcommand. The <computeroutput>--list
3414 </computeroutput> option shows which metrics have been modified as
3415 the result of the command execution.</para>
3416 </glossdef>
3417 </glossentry>
3418
3419 <glossentry>
3420 <glossterm>enable</glossterm>
3421
3422 <glossdef>
3423 <para>This subcommand "resumes" data collection after it has been
3424 stopped with <code>disable</code> subcommand. Note that specifying
3425 submetrics as parameters will not enable underlying metrics. Use
3426 <computeroutput>--list</computeroutput> to find out if the command
3427 did what was expected.</para>
3428 </glossdef>
3429 </glossentry>
3430
3431 <glossentry>
3432 <glossterm>disable</glossterm>
3433
3434 <glossdef>
3435 <para>This subcommand "suspends" data collection without affecting
3436 collection parameters or collected data. Note that specifying
3437 submetrics as parameters will not disable underlying metrics. Use
3438 <computeroutput>--list</computeroutput> to find out if the command
3439 did what was expected.</para>
3440 </glossdef>
3441 </glossentry>
3442
3443 <glossentry>
3444 <glossterm>query</glossterm>
3445
3446 <glossdef>
3447 <para>This subcommand retrieves and displays the currently retained
3448 metric data.<note>
3449 <para>The <code>query</code> subcommand does not remove or
3450 "flush" retained data. If you query often enough you will see
3451 how old samples are gradually being "phased out" by new
3452 samples.</para>
3453 </note></para>
3454 </glossdef>
3455 </glossentry>
3456
3457 <glossentry>
3458 <glossterm>collect</glossterm>
3459
3460 <glossdef>
3461 <para>This subcommand sets the interval between taking two samples
3462 of metric data and the number of samples retained internally. The
3463 collected data is displayed periodically until Ctrl-C is pressed
3464 unless the <computeroutput>--detach</computeroutput> option is
3465 specified. With the <computeroutput>--detach</computeroutput>
3466 option, this subcommand operates the same way as <code>setup</code>
3467 does. The <computeroutput>--list</computeroutput> option shows which
3468 metrics match the specified filter.</para>
3469 </glossdef>
3470 </glossentry>
3471 </glosslist>
3472 </sect1>
3473
3474 <sect1>
3475 <title>VBoxManage hostonlyif</title>
3476
3477 <para>With "hostonlyif" you can change the IP configuration of a host-only
3478 network interface. For a description of host-only networking, please
3479 refer to <xref linkend="network_hostonly" />. Each host-only interface is
3480 identified by a name and can either use the internal DHCP server or a
3481 manual IP configuration (both IP4 and IP6).</para>
3482 </sect1>
3483
3484 <sect1 id="vboxmanage-dhcpserver">
3485 <title>VBoxManage dhcpserver</title>
3486
3487 <para>The "dhcpserver" commands allow you to control the DHCP server that
3488 is built into VirtualBox. You may find this useful when using internal or
3489 host-only networking. (Theoretically, you can enable it for a bridged
3490 network as well, but that will likely cause conflicts with other DHCP
3491 servers in your physical network.)</para>
3492
3493 <para>Use the following command line options:<itemizedlist>
3494 <listitem>
3495 <para>If you use internal networking for a virtual network adapter
3496 of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
3497 --netname &lt;network_name&gt;</computeroutput>, where
3498 <computeroutput>&lt;network_name&gt;</computeroutput> is the same
3499 network name you used with <computeroutput>VBoxManage modifyvm
3500 &lt;vmname&gt; --intnet&lt;X&gt;
3501 &lt;network_name&gt;</computeroutput>.</para>
3502 </listitem>
3503
3504 <listitem>
3505 <para>If you use host-only networking for a virtual network adapter
3506 of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
3507 --ifname &lt;hostonly_if_name&gt;</computeroutput> instead, where
3508 <computeroutput>&lt;hostonly_if_name&gt;</computeroutput> is the
3509 same host-only interface name you used with
3510 <computeroutput>VBoxManage modifyvm &lt;vmname&gt;
3511 --hostonlyadapter&lt;X&gt;
3512 &lt;hostonly_if_name&gt;</computeroutput>.</para>
3513
3514 <para>Alternatively, you can also use the --netname option as with
3515 internal networks if you know the host-only network's name; you can
3516 see the names with <computeroutput>VBoxManage list
3517 hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
3518 above).</para>
3519 </listitem>
3520 </itemizedlist></para>
3521
3522 <para>The following additional parameters are required when first adding a
3523 DHCP server:<itemizedlist>
3524 <listitem>
3525 <para>With <computeroutput>--ip</computeroutput>, specify the IP
3526 address of the DHCP server itself.</para>
3527 </listitem>
3528
3529 <listitem>
3530 <para>With <computeroutput>--netmask</computeroutput>, specify the
3531 netmask of the network.</para>
3532 </listitem>
3533
3534 <listitem>
3535 <para>With <computeroutput>--lowerip</computeroutput> and
3536 <computeroutput>--upperip</computeroutput>, you can specify the
3537 lowest and highest IP address, respectively, that the DHCP server
3538 will hand out to clients.</para>
3539 </listitem>
3540 </itemizedlist></para>
3541
3542 <para>Finally, you must specify <computeroutput>--enable</computeroutput>
3543 or the DHCP server will be created in the disabled state, doing
3544 nothing.</para>
3545
3546 <para>After this, VirtualBox will automatically start the DHCP server for
3547 given internal or host-only network as soon as the first virtual machine
3548 which uses that network is started.</para>
3549
3550 <para>Reversely, use <computeroutput>VBoxManage dhcpserver
3551 remove</computeroutput> with the given <computeroutput>--netname
3552 &lt;network_name&gt;</computeroutput> or <computeroutput>--ifname
3553 &lt;hostonly_if_name&gt;</computeroutput> to remove the DHCP server again
3554 for the given internal or host-only network.</para>
3555
3556 <para>To modify the settings of a DHCP server created earlier with
3557 <computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
3558 <computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
3559 network or host-only interface name.</para>
3560 </sect1>
3561
3562 <sect1 id="vboxmanage-extpack">
3563 <title>VBoxManage extpack</title>
3564
3565 <para>The "extpack" command allows you to add or remove VirtualBox
3566 extension packs, as described in <xref
3567 linkend="intro-installing" />.<itemizedlist>
3568 <listitem>
3569 <para>To add a new extension pack, use <computeroutput>VBoxManage
3570 extpack install &lt;.vbox-extpack&gt;</computeroutput>. This command
3571 will fail if an older version of the same extension pack is already
3572 installed. The optional <computeroutput>--replace</computeroutput>
3573 parameter can be used to uninstall the old package before the new
3574 package is installed.</para>
3575 </listitem>
3576
3577 <listitem>
3578 <para>To remove a previously installed extension pack, use
3579 <computeroutput>VBoxManage extpack uninstall
3580 &lt;name&gt;</computeroutput>. You can use
3581 <computeroutput>VBoxManage list extpacks</computeroutput> to show
3582 the names of the extension packs which are currently installed;
3583 please see <xref linkend="vboxmanage-list" /> also. The optional
3584 <computeroutput>--force</computeroutput> parameter can be used to
3585 override the refusal of an extension pack to be uninstalled.</para>
3586 </listitem>
3587
3588 <listitem>
3589 <para>The <computeroutput>VBoxManage extpack
3590 cleanup</computeroutput> command can be used to remove temporary
3591 files and directories that may have been left behind if a previous
3592 install or uninstall command failed.</para>
3593 </listitem>
3594 </itemizedlist></para>
3595 <para>The following commands show examples how to list extension packs and
3596 remove one:<screen>
3597$ VBoxManage list extpacks
3598Extension Packs: 1
3599Pack no. 0: Oracle VM VirtualBox Extension Pack
3600Version: 4.1.12
3601Revision: 77218
3602Edition:
3603Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support.
3604VRDE Module: VBoxVRDP
3605Usable: true
3606Why unusable:
3607$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack"
36080%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
3609Successfully uninstalled "Oracle VM VirtualBox Extension Pack".</screen></para>
3610 </sect1>
3611</chapter>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette