user_VBoxManage.xml@ 34600

Last change on this file since 34600 was 34599, checked in by vboxsync, 14 years ago
Manual: guest additions updates
File size: 118.0 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
80	VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
81	(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
82	All rights reserved.
83
84	Virtual machine 'SUSE 10.2' is created.
85	UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
86	Settings file: '/home/username/.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-storage" /> for details.</para>
113	</listitem>
114
115	<listitem>
116	<para>To control VM operation, use one of the following:<itemizedlist>
117	<listitem>
118	<para>To start a VM that is currently powered off, use
119	<computeroutput>VBoxManage startvm</computeroutput>; see <xref
120	linkend="vboxmanage-startvm" /> for details.</para>
121	</listitem>
122
123	<listitem>
124	<para>To pause or save a VM that is currently running or change
125	some of its settings, use <computeroutput>VBoxManage
126	controlvm</computeroutput>; see <xref
127	linkend="vboxmanage-controlvm" /> for details.</para>
128	</listitem>
129	</itemizedlist></para>
130	</listitem>
131	</itemizedlist>
132	</sect1>
133
134	<sect1>
135	<title>Commands overview</title>
136
137	<para>When running VBoxManage without parameters or when supplying an
138	invalid command line, the below syntax diagram will be shown. Note that
139	the output will be slightly different depending on the host platform; when
140	in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
141	for the commands available on your particular host.</para>
142
143	<screen>$VBOX_MANAGE_OUTPUT</screen>
144
145	<para>Each time VBoxManage is invoked, only one command can be executed.
146	However, a command might support several subcommands which then can be
147	invoked in one single call. The following sections provide detailed
148	reference information on the different commands.</para>
149	</sect1>
150
151	<sect1 id="vboxmanage-list">
152	<title>VBoxManage list</title>
153
154	<para>The <computeroutput>list</computeroutput> command gives relevant
155	information about your system and information about VirtualBox's current
156	settings.</para>
157
158	<para>The following subcommands are available with
159	<computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
160	<listitem>
161	<para><computeroutput>vms</computeroutput> lists all virtual
162	machines currently registered with VirtualBox. By default this
163	displays a compact list with each VM's name and UUID; if you also
164	specify <computeroutput>--long</computeroutput> or
165	<computeroutput>-l</computeroutput>, this will be a detailed list as
166	with the <computeroutput>showvminfo</computeroutput> command (see
167	below).</para>
168	</listitem>
169
170	<listitem>
171	<para><computeroutput>runningvms</computeroutput> lists all
172	currently running virtual machines by their unique identifiers
173	(UUIDs) in the same format as with
174	<computeroutput>vms</computeroutput>.</para>
175	</listitem>
176
177	<listitem>
178	<para><computeroutput>hdds</computeroutput>,
179	<computeroutput>dvds</computeroutput> and
180	<computeroutput>floppies</computeroutput> all give you information
181	about virtual disk images currently registered in VirtualBox,
182	including all their settings, the unique identifiers (UUIDs)
183	associated with them by VirtualBox and all files associated with
184	them.</para>
185	</listitem>
186
187	<listitem>
188	<para><computeroutput>ostypes</computeroutput> lists all guest
189	operating systems presently known to VirtualBox, along with the
190	identifiers used to refer to them with the
191	<computeroutput>modifyvm</computeroutput> command.</para>
192	</listitem>
193
194	<listitem>
195	<para><computeroutput>hostdvds</computeroutput>,
196	<computeroutput>hostfloppies</computeroutput> and
197	<computeroutput>hostifs</computeroutput>, respectively, list DVD,
198	floppy and host networking interfaces on the host, along with the
199	name used to access them from within VirtualBox.</para>
200	</listitem>
201
202	<listitem>
203	<para><computeroutput>hostusb</computeroutput> supplies information
204	about USB devices attached to the host, notably information useful
205	for constructing USB filters and whether they are currently in use
206	by the host.</para>
207	</listitem>
208
209	<listitem>
210	<para><computeroutput>usbfilters</computeroutput> lists all global
211	USB filters registered with VirtualBox -- that is, filters for
212	devices which are accessible to all virtual machines -- and displays
213	the filter parameters.</para>
214	</listitem>
215
216	<listitem>
217	<para><computeroutput>systemproperties</computeroutput> displays
218	some global VirtualBox settings, such as minimum and maximum guest
219	RAM and virtual hard disk size, folder settings and the current
220	authentication library in use.</para>
221	</listitem>
222
223	<listitem>
224	<para><computeroutput>hddbackends</computeroutput> lists all known
225	hdd backends of VirtualBox. Beside the name of the backend itself,
226	descriptions about the capabilities, configuration and other useful
227	informations are displayed.</para>
228	</listitem>
229	</itemizedlist></para>
230	</sect1>
231
232	<sect1 id="vboxmanage-showvminfo">
233	<title>VBoxManage showvminfo</title>
234
235	<para>The <computeroutput>showvminfo</computeroutput> command shows
236	information about a particular virtual machine. This is the same
237	information as <computeroutput>VBoxManage list vms --long</computeroutput>
238	would show for all virtual machines.</para>
239
240	<para>You will get information similar to the following:</para>
241
242	<para><screen>$ VBoxManage showvminfo "Windows XP"
243	VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
244	(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
245	All rights reserved.
246
247	Name: Windows XP
248	Guest OS: Other/Unknown
249	UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
250	Config file: /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml
251	Memory size: 512MB
252	VRAM size: 12MB
253	Number of CPUs: 2
254	Synthetic Cpu: off
255	Boot menu mode: message and menu
256	Boot Device (1): DVD
257	Boot Device (2): HardDisk
258	Boot Device (3): Not Assigned
259	Boot Device (4): Not Assigned
260	ACPI: on
261	IOAPIC: on
262	PAE: on
263	Time offset: 0 ms
264	Hardw. virt.ext: on
265	Hardw. virt.ext exclusive: on
266	Nested Paging: on
267	VT-x VPID: off
268	State: powered off (since 2009-10-20T14:52:19.000000000)
269	Monitor count: 1
270	3D Acceleration: off
271	2D Video Acceleration: off
272	Teleporter Enabled: off
273	Teleporter Port: 0
274	Teleporter Address:
275	Teleporter Password:
276	Storage Controller (0): IDE Controller
277	Storage Controller Type (0): PIIX4
278	Storage Controller (1): Floppy Controller 1
279	Storage Controller Type (1): I82078
280	IDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b)
281	IDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b)
282	Floppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137)
283	NIC 1: disabled
284	NIC 2: disabled
285	NIC 3: disabled
286	NIC 4: disabled
287	NIC 5: disabled
288	NIC 6: disabled
289	NIC 7: disabled
290	NIC 8: disabled
291	UART 1: disabled
292	UART 2: disabled
293	Audio: disabled (Driver: Unknown)
294	Clipboard Mode: Bidirectional
295	VRDP: disabled
296	USB: disabled
297
298	USB Device Filters:
299	<none>
300
301	Shared folders:
302	<none>
303
304	Statistics update: disabled
305	</screen></para>
306	</sect1>
307
308	<sect1>
309	<title>VBoxManage registervm / unregistervm</title>
310
311	<para>The <computeroutput>registervm</computeroutput> command allows you
312	to import a virtual machine definition in an XML file into VirtualBox. The
313	machine must not conflict with one already registered in VirtualBox and it
314	may not have any hard or removable disks attached. It is advisable to
315	place the definition file in the machines folder before registering
316	it.<note>
317	<para>When creating a new virtual machine with
318	<computeroutput>VBoxManage createvm</computeroutput> (see below), you
319	can directly specify the <computeroutput>--register</computeroutput>
320	option to avoid having to register it separately.</para>
321	</note></para>
322
323	<para>The <computeroutput>unregistervm</computeroutput> command
324	unregisters a virtual machine. If
325	<computeroutput>--delete</computeroutput> is also specified, the following
326	files will automatically be deleted as well:<orderedlist>
327	<listitem>
328	<para>all hard disk image files, including differencing files, which
329	are used by the machine and not shared with other machines;</para>
330	</listitem>
331
332	<listitem>
333	<para>saved state files that the machine created, if any (one if the
334	machine was in "saved" state and one for each online
335	snapshot);</para>
336	</listitem>
337
338	<listitem>
339	<para>the machine XML file and its backups;</para>
340	</listitem>
341
342	<listitem>
343	<para>the machine log files, if any;</para>
344	</listitem>
345
346	<listitem>
347	<para>the machine directory, if it is empty after having deleted all
348	the above.</para>
349	</listitem>
350	</orderedlist></para>
351	</sect1>
352
353	<sect1>
354	<title id="vboxmanage-createvm">VBoxManage createvm</title>
355
356	<para>This command creates a new XML virtual machine definition
357	file.</para>
358
359	<para>The <computeroutput>--name <name></computeroutput> parameter
360	is required and must specify the name of the machine. Since this name is
361	used by default as the file name of the settings file (with the extension
362	<computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
363	of the <computeroutput>.VirtualBox/Machines</computeroutput> folder), it
364	must conform to your host operating system's requirements for file name
365	specifications. If the VM is later renamed, the file and folder names will
366	change automatically.</para>
367
368	<para>However, if the <computeroutput>--basefolder
369	<path></computeroutput> option is used, the machine folder will be
370	named <computeroutput><path></computeroutput>. In this case, the
371	names of the file and the folder will not change if the virtual machine is
372	renamed.</para>
373
374	<para>By default, this command only creates the XML file without
375	automatically registering the VM with your VirtualBox installation. To
376	register the VM instantly, use the optional
377	<computeroutput>--register</computeroutput> option, or run
378	<computeroutput>VBoxManage registervm</computeroutput> separately
379	afterwards.</para>
380	</sect1>
381
382	<sect1 id="vboxmanage-modifyvm">
383	<title>VBoxManage modifyvm</title>
384
385	<para>This command changes the properties of a registered virtual machine
386	which is not running. Most of the properties that this command makes
387	available correspond to the VM settings that VirtualBox graphical user
388	interface displays in each VM's "Settings" dialog; these were described in
389	<xref linkend="BasicConcepts" />. Some of the more advanced settings,
390	however, are only available through the
391	<computeroutput>VBoxManage</computeroutput> interface.</para>
392
393	<para>These commands require that the machine is powered off (neither
394	running nor in "saved" state). Some machine settings can also be changed
395	while a machine is running; those settings will then have a corresponding
396	subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
397	subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
398
399	<sect2>
400	<title>General settings</title>
401
402	<para>The following general settings are available through
403	<computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
404	<listitem>
405	<para><computeroutput>--name <name></computeroutput>: This
406	changes the VM's name and possibly renames the internal virtual
407	machine files, as described with <computeroutput>VBoxManage
408	createvm</computeroutput> above.</para>
409	</listitem>
410
411	<listitem>
412	<para><computeroutput>--ostype <ostype></computeroutput>:
413	This specifies what guest operating system is supposed to run in
414	the VM. To learn about the various identifiers that can be used
415	here, use <computeroutput>VBoxManage list
416	ostypes</computeroutput>.</para>
417	</listitem>
418
419	<listitem>
420	<para><computeroutput>--memory
421	<memorysize></computeroutput>: This sets the amount of RAM,
422	in MB, that the virtual machine should allocate for itself from
423	the host. See the remarks in <xref linkend="gui-createvm" /> for
424	more information.</para>
425	</listitem>
426
427	<listitem>
428	<para><computeroutput>--vram <vramsize></computeroutput>:
429	This sets the amount of RAM that the virtual graphics card should
430	have. See <xref linkend="settings-display" /> for details.</para>
431	</listitem>
432
433	<listitem>
434	<para><computeroutput>--acpi on\|off</computeroutput>;
435	<computeroutput>--ioapic on\|off</computeroutput>: These two
436	determine whether the VM should have ACPI and I/O APIC support,
437	respectively; see <xref linkend="settings-motherboard" /> for
438	details.</para>
439	</listitem>
440
441	<listitem>
442	<para><computeroutput>--hardwareuuid
443	<uuid></computeroutput>: The UUID presented to the guest via
444	memory tables (DMI/SMBIOS), hardware and guest properties. By
445	default this is the same as the VM uuid. Useful when cloning a VM.
446	Teleporting takes care of this automatically.</para>
447	</listitem>
448
449	<listitem>
450	<para><computeroutput>--cpus <cpucount></computeroutput>:
451	This sets the number of virtual CPUs for the virtual machine (see
452	<xref linkend="settings-processor" />). If CPU hot-plugging is
453	enabled (see below), this then sets the
454	<emphasis>maximum</emphasis> number of virtual CPUs that can be
455	plugged into the virtual machines.</para>
456	</listitem>
457
458	<listitem>
459	<para><computeroutput>--rtcuseutc on\|off</computeroutput>: This
460	option lets the real-time clock (RTC) operate in UTC time (see
461	<xref linkend="settings-motherboard" />).</para>
462	</listitem>
463
464	<listitem>
465	<para><computeroutput>--cpuhotplug on\|off</computeroutput>: This
466	enables CPU hot-plugging. When enabled, virtual CPUs can be added
467	to and removed from a virtual machine while it is running. See
468	<xref linkend="cpuhotplug" /> for more information.</para>
469	</listitem>
470
471	<listitem>
472	<para><computeroutput>--plugcpu\|unplugcpu
473	<id></computeroutput>: If CPU hot-plugging is enabled (see
474	above), this adds a virtual CPU to the virtual machines (or
475	removes one). <computeroutput><id></computeroutput>
476	specifies the index of the virtual CPU to be added or removed and
477	must be a number from 0 to the maximum no. of CPUs configured with
478	the <computeroutput>--cpus</computeroutput> option. CPU 0 can
479	never be removed.</para>
480	</listitem>
481
482	<listitem>
483	<para><computeroutput>--synthcpu on\|off</computeroutput>: This
484	setting determines whether VirtualBox will expose a synthetic CPU
485	to the guest to allow live migration between host systems that
486	differ significantly.</para>
487	</listitem>
488
489	<listitem>
490	<para><computeroutput>--pae on\|off</computeroutput>: This
491	enables/disables PAE (see <xref
492	linkend="settings-processor" />).</para>
493	</listitem>
494
495	<listitem>
496	<para><computeroutput>--hpet on\|off</computeroutput>: This
497	enables/disables a High Precision Event Timer (HPET) which can
498	replace the legacy system timers. This is turned off by default.
499	Note that Windows supports a HPET only from Vista onwards.</para>
500	</listitem>
501
502	<listitem>
503	<para><computeroutput>--hwvirtex on\|off</computeroutput>: This
504	enables or disables the use of hardware virtualization extensions
505	(Intel VT-x or AMD-V) in the processor of your host system; see
506	<xref linkend="hwvirt" />.</para>
507	</listitem>
508
509	<listitem>
510	<para><computeroutput>--hwvirtexexcl on\|off</computeroutput>: This
511	specifies whether VirtualBox will make exclusive use of the
512	hardware virtualization extensions (Intel VT-x or AMD-V) in the
513	processor of your host system; see <xref linkend="hwvirt" />. If
514	you wish to simultaneously share these extensions with other
515	hypervisors, then you must disable this setting. Doing so has
516	negative performance implications.</para>
517	</listitem>
518
519	<listitem>
520	<para><computeroutput>--nestedpaging on\|off</computeroutput>: If
521	hardware virtualization is enabled, this additional setting
522	enables or disables the use of the nested paging feature in the
523	processor of your host system; see <xref
524	linkend="hwvirt" />.</para>
525	</listitem>
526
527	<listitem>
528	<para><computeroutput>--largepages on\|off</computeroutput>: If
529	hardware virtualization <emphasis>and</emphasis> nested paging are
530	enabled, for Intel VT-x only, an additional performance
531	improvement of up to 5% can be obtained by enabling this setting.
532	This causes the hypervisor to use large pages to reduce TLB use
533	and overhead.</para>
534	</listitem>
535
536	<listitem>
537	<para><computeroutput>--vtxvpid on\|off</computeroutput>: If
538	hardware virtualization is enabled, for Intel VT-x only, this
539	additional setting enables or disables the use of the tagged TLB
540	(VPID) feature in the processor of your host system; see <xref
541	linkend="hwvirt" />.</para>
542	</listitem>
543
544	<listitem>
545	<para><computeroutput>--accelerate3d on\|off</computeroutput>: This
546	enables, if the Guest Additions are installed, whether hardware 3D
547	acceleration should be available; see <xref
548	linkend="guestadd-3d" />.</para>
549	</listitem>
550
551	<listitem>
552	<para>You can influence the BIOS logo that is displayed when a
553	virtual machine starts up with a number of settings. Per default,
554	a VirtualBox logo is displayed.</para>
555
556	<para>With <computeroutput>--bioslogofadein
557	on\|off</computeroutput> and <computeroutput>--bioslogofadeout
558	on\|off</computeroutput>, you can determine whether the logo should
559	fade in and out, respectively.</para>
560
561	<para>With <computeroutput>--bioslogodisplaytime
562	<msec></computeroutput> you can set how long the logo should
563	be visible, in milliseconds.</para>
564
565	<para>With <computeroutput>--bioslogoimagepath
566	<imagepath></computeroutput> you can, if you are so
567	inclined, replace the image that is shown, with your own logo. The
568	image must be an uncompressed 256 color BMP file.</para>
569	</listitem>
570
571	<listitem>
572	<para><computeroutput>--biosbootmenu
573	disabled\|menuonly\|messageandmenu</computeroutput>: This specifies
574	whether the BIOS allows the user to select a temporary boot
575	device. <computeroutput>menuonly</computeroutput> suppresses the
576	message, but the user can still press F12 to select a temporary
577	boot device.</para>
578	</listitem>
579
580	<listitem>
581	<para><computeroutput>--boot<1-4>
582	none\|floppy\|dvd\|disk\|net</computeroutput>: This specifies the boot
583	order for the virtual machine. There are four "slots", which the
584	VM will try to access from 1 to 4, and for each of which you can
585	set a device that the VM should attempt to boot from.</para>
586	</listitem>
587
588	<listitem>
589	<para><computeroutput>--snapshotfolder
590	default\|<path></computeroutput>: This allows you to specify
591	the folder in which snapshots will be kept for a virtual
592	machine.</para>
593	</listitem>
594
595	<listitem>
596	<para><computeroutput>--firmware efi\|bios</computeroutput>:
597	Specifies which firmware is used to boot particular virtual
598	machine: EFI or BIOS. Use EFI only if your fully understand what
599	you're doing.</para>
600	</listitem>
601
602	<listitem>
603	<para><computeroutput>--guestmemoryballoon
604	<size></computeroutput> sets the default size of the guest
605	memory balloon, that is, memory allocated by the VirtualBox Guest
606	Additions from the guest operating system and returned to the
607	hypervisor for re-use by other virtual machines. <size> must
608	be specified in megabytes. The default size is 0 megabytes. For
609	details, see <xref linkend="guestadd-balloon" />.</para>
610	</listitem>
611	</itemizedlist></para>
612	</sect2>
613
614	<sect2>
615	<title>Networking settings</title>
616
617	<para>The following networking settings are available through
618	<computeroutput>VBoxManage modifyvm</computeroutput>. With all these
619	settings, the decimal number directly following the option name ("1-N"
620	in the list below) specifies the virtual network adapter whose settings
621	should be changed.<itemizedlist>
622	<listitem>
623	<para><computeroutput>--nic<1-N>
624	none\|null\|nat\|bridged\|intnet\|hostonly\|vde</computeroutput>: With
625	this, you can set, for each of the VM's virtual network cards,
626	what type of networking should be available. They can be not
627	present (<computeroutput>none</computeroutput>), not connected to
628	the host (<computeroutput>null</computeroutput>), use network
629	address translation (<computeroutput>nat</computeroutput>),
630	bridged networking (<computeroutput>bridged</computeroutput>) or
631	communicate with other virtual machines using internal networking
632	(<computeroutput>intnet</computeroutput>), host-only networking
633	(<computeroutput>hostonly</computeroutput>) or on Linux and
634	FreeBSD hosts a Virtual Distributed Ethernet switch
635	(<computeroutput>vde</computeroutput>). These options correspond
636	to the modes which are described in detail in <xref
637	linkend="networkingmodes" />.</para>
638	</listitem>
639
640	<listitem>
641	<para><computeroutput>--nictype<1-N>
642	Am79C970A\|Am79C973\|82540EM\|82543GC\|82545EM\|virtio</computeroutput>:
643	This allows you, for each of the VM's virtual network cards, to
644	specify which networking hardware VirtualBox presents to the
645	guest; see <xref linkend="nichardware" />.</para>
646	</listitem>
647
648	<listitem>
649	<para><computeroutput>--cableconnected<1-N>
650	on\|off</computeroutput>: This allows you to temporarily disconnect
651	a virtual network interface, as if a network cable had been pulled
652	from a real network card. This might be useful for resetting
653	certain software components in the VM.</para>
654	</listitem>
655
656	<listitem>
657	<para>With the "nictrace" options, you can optionally trace
658	network traffic by dumping it to a file, for debugging
659	purposes.</para>
660
661	<para>With <computeroutput>--nictrace<1-N>
662	on\|off</computeroutput>, you can enable network tracing for a
663	particular virtual network card.</para>
664
665	<para>If enabled, you must specify with
666	<computeroutput>--nictracefile<1-N>
667	<filename></computeroutput> what file the trace should be
668	logged to.</para>
669	</listitem>
670
671	<listitem>
672	<para><computeroutput>--bridgeadapter<1-N>
673	none\|<devicename></computeroutput>: If bridged networking
674	has been enabled for a virtual network card (see the
675	<computeroutput>--nic</computeroutput> option above; otherwise
676	this setting has no effect), use this option to specify which host
677	interface the given virtual network interface will use. For
678	details, please see <xref linkend="network_bridged" />.</para>
679	</listitem>
680
681	<listitem>
682	<para><computeroutput>--hostonlyadapter<1-N>
683	none\|<devicename></computeroutput>: If host-only networking
684	has been enabled for a virtual network card (see the --nic option
685	above; otherwise this setting has no effect), use this option to
686	specify which host-only networking interface the given virtual
687	network interface will use. For details, please see <xref
688	linkend="network_hostonly" />.</para>
689	</listitem>
690
691	<listitem>
692	<para><computeroutput>--intnet<1-N>
693	network</computeroutput>: If internal networking has been enabled
694	for a virtual network card (see the
695	<computeroutput>--nic</computeroutput> option above; otherwise
696	this setting has no effect), use this option to specify the name
697	of the internal network (see <xref
698	linkend="network_internal" />).</para>
699	</listitem>
700
701	<listitem>
702	<para><computeroutput>--macaddress<1-N>
703	auto\|<mac></computeroutput>: With this option you can set
704	the MAC address of the virtual network card. Normally, each
705	virtual network card is assigned a random address by VirtualBox at
706	VM creation.</para>
707	</listitem>
708
709	<listitem>
710	<para><computeroutput>--vdenet<1-N>
711	network</computeroutput>: If Virtual Distributed Ethernet is
712	available on the host and has been enabled for a virtual network
713	card (see the <computeroutput>--nic</computeroutput> option above;
714	otherwise this setting has no effect). Use this option to specify
715	the name of a VDE network for the interface to connect to (see
716	<xref linkend="networkingmodes" /> and the VDE
717	documentation).</para>
718	</listitem>
719	</itemizedlist></para>
720
721	<sect3>
722	<title>NAT Networking settings.</title>
723
724	<para>The following NAT networking settings are available through
725	<computeroutput>VBoxManage modifyvm</computeroutput>. With all these
726	settings, the decimal number directly following the option name ("1-N"
727	in the list below) specifies the virtual network adapter whose
728	settings should be changed.<itemizedlist>
729	<listitem>
730	<para><computeroutput>--natpf<1-N>
731	[<name>],tcp\|udp,[<hostip>],<hostport>,[<guestip>],
732	<guestport></computeroutput>: This option defines a NAT
733	port-forwarding rule (please see <xref linkend="natforward" />
734	for details).</para>
735	</listitem>
736
737	<listitem>
738	<para><computeroutput>--natpf<1-N> delete
739	<name></computeroutput>: This option deletes a NAT
740	port-forwarding rule (please see <xref linkend="natforward" />
741	for details).</para>
742	</listitem>
743
744	<listitem>
745	<para><computeroutput>--nattftpprefix<1-N>
746	<prefix></computeroutput>: This option defines a prefix
747	for the built-in TFTP server, i.e. where the boot file is
748	located (please see <xref linkend="nat-tftp" /> and <xref
749	linkend="nat-adv-tftp" /> for details).</para>
750	</listitem>
751
752	<listitem>
753	<para><computeroutput>--nattftpfile<1-N>
754	<bootfile></computeroutput>: This option defines the TFT
755	boot file (please see <xref linkend="nat-adv-tftp" /> for
756	details).</para>
757	</listitem>
758
759	<listitem>
760	<para><computeroutput>--nattftpserver<1-N>
761	<tftpserver></computeroutput>: This option defines the
762	TFTP server address to boot from (please see <xref
763	linkend="nat-adv-tftp" /> for details).</para>
764	</listitem>
765
766	<listitem>
767	<para><computeroutput>--natdnspassdomain<1-N>
768	on\|off</computeroutput>: This option specifies whether the
769	built-in DHCP server passes the domain name for network name
770	resolution.</para>
771	</listitem>
772
773	<listitem>
774	<para><computeroutput>--natdnsproxy<1-N>
775	on\|off</computeroutput>: This option makes the NAT engine proxy
776	all guest DNS requests to the host's DNS servers (please see
777	<xref linkend="nat-adv-dns" /> for details).</para>
778	</listitem>
779
780	<listitem>
781	<para><computeroutput>--natdnshostresolver<1-N>
782	on\|off</computeroutput>: This option makes the NAT engine use
783	the host's resolver mechanisms to handle DNS requests (please
784	see <xref linkend="nat-adv-dns" /> for details).</para>
785	</listitem>
786
787	<listitem>
788	<para><computeroutput>--natnatsettings<1-N>
789	[<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
790	[<tcprcv>]</computeroutput>: This option controls several
791	NAT settings (please see <xref linkend="nat-adv-settings" /> for
792	details).</para>
793	</listitem>
794
795	<listitem>
796	<para><computeroutput>--nataliasmode<1-N>
797	default\|[log],[proxyonly],[sameports]</computeroutput>: This
798	option defines behaviour of NAT engine core: log - enables
799	logging, proxyonly - switches of aliasing mode makes NAT
800	transparent, sameports enforces NAT engine to send packets via
801	the same port as they originated on, default - disable all
802	mentioned modes above . (please see <xref
803	linkend="nat-adv-alias" /> for details).</para>
804	</listitem>
805	</itemizedlist></para>
806	</sect3>
807	</sect2>
808
809	<sect2 id="vboxmanage-modifyvm-other">
810	<title>Serial port, audio, clipboard, VRDP and USB settings</title>
811
812	<para>The following other hardware settings are available through
813	<computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
814	<listitem>
815	<para><computeroutput>--uart<1-N> off\|<I/O base>
816	<IRQ></computeroutput>: With this option you can configure
817	virtual serial ports for the VM; see <xref
818	linkend="serialports" /> for an introduction.</para>
819	</listitem>
820
821	<listitem>
822	<para><computeroutput>--uartmode<1-N>
823	<arg></computeroutput>: This setting controls how VirtualBox
824	connects a given virtual serial port (previously configured with
825	the <computeroutput>--uartX</computeroutput> setting, see above)
826	to the host on which the virtual machine is running. As described
827	in detail in <xref linkend="serialports" />, for each such port,
828	you can specify <computeroutput><arg></computeroutput> as
829	one of the following options:<itemizedlist>
830	<listitem>
831	<para><computeroutput>disconnected</computeroutput>: Even
832	though the serial port is shown to the guest, it has no
833	"other end" -- like a real COM port without a cable.</para>
834	</listitem>
835
836	<listitem>
837	<para><computeroutput>server
838	<pipename></computeroutput>: On a Windows host, this
839	tells VirtualBox to create a named pipe on the host named
840	<computeroutput><pipename></computeroutput> and
841	connect the virtual serial device to it. Note that Windows
842	requires that the name of a named pipe begin with
843	<computeroutput>\\.\pipe\</computeroutput>.</para>
844
845	<para>On a Linux host, instead of a named pipe, a local
846	domain socket is used.</para>
847	</listitem>
848
849	<listitem>
850	<para><computeroutput>client
851	<pipename></computeroutput>: This operates just like
852	<computeroutput>server ...</computeroutput>, except that the
853	pipe (or local domain socket) is not created by VirtualBox,
854	but assumed to exist already.</para>
855	</listitem>
856
857	<listitem>
858	<para><computeroutput><devicename></computeroutput>:
859	If, instead of the above, the device name of a physical
860	hardware serial port of the host is specified, the virtual
861	serial port is connected to that hardware port. On a Windows
862	host, the device name will be a COM port such as
863	<computeroutput>COM1</computeroutput>; on a Linux host, the
864	device name will look like
865	<computeroutput>/dev/ttyS0</computeroutput>. This allows you
866	to "wire" a real serial port to a virtual machine.</para>
867	</listitem>
868	</itemizedlist></para>
869	</listitem>
870
871	<listitem>
872	<para><computeroutput>--audio none\|null\|oss</computeroutput>: With
873	this option, you can set whether the VM should have audio
874	support.</para>
875	</listitem>
876
877	<listitem>
878	<para><computeroutput>--clipboard
879	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
880	With this setting, you can select whether the guest operating
881	system's clipboard should be shared with the host; see <xref
882	linkend="generalsettings" />. This requires that the Guest
883	Additions be installed in the virtual machine.</para>
884	</listitem>
885
886	<listitem>
887	<para><computeroutput>--monitorcount
888	<count></computeroutput>: This enables multi-monitor
889	support; see <xref linkend="settings-display" />.</para>
890	</listitem>
891
892	<listitem>
893	<para><computeroutput>--usb on\|off</computeroutput>: This option
894	enables or disables the VM's virtual USB controller; see <xref
895	linkend="settings-usb" /> for details.</para>
896	</listitem>
897
898	<listitem>
899	<para><computeroutput>--usbehci on\|off</computeroutput>: This
900	option enables or disables the VM's virtual USB 2.0 controller;
901	see <xref linkend="settings-usb" /> for details.</para>
902	</listitem>
903	</itemizedlist></para>
904	</sect2>
905
906	<sect2>
907	<title>Remote machine settings</title>
908
909	<para>The following settings that affect remote machine behavior are
910	available through <computeroutput>VBoxManage
911	modifyvm</computeroutput>:<itemizedlist>
912	<listitem>
913	<para><computeroutput>--vrdp on\|off</computeroutput>: With the
914	VirtualBox graphical user interface, this enables or disables the
915	built-in VRDP server. Note that if you are using
916	<computeroutput>VBoxHeadless</computeroutput> (see <xref
917	linkend="vboxheadless" />), VRDP output is always enabled.</para>
918	</listitem>
919
920	<listitem>
921	<para><computeroutput>--vrdpport
922	default\|<ports></computeroutput>: A port or a range of ports
923	the VRDP server can bind to; "default" or "0" means port 3389, the
924	standard port for RDP. You can specify a comma-separated list of
925	ports or ranges of ports. Use a dash between two port numbers to
926	specify a range. The VRDP server will bind to <emphasis
927	role="bold">one</emphasis> of available ports from the specified
928	list. Only one machine can use a given port at a time. For
929	example, the option <computeroutput> --vrdpport
930	5000,5010-5012</computeroutput> will tell the server to bind to
931	one of following ports: 5000, 5010, 5011 or 5012.</para>
932	</listitem>
933
934	<listitem>
935	<para><computeroutput>--vrdpaddress <IP
936	address></computeroutput>: The IP address of the host network
937	interface the VRDP server will bind to. If specified, the VRDP
938	server will accept connections only on the specified host network
939	interface.</para>
940	</listitem>
941
942	<listitem>
943	<para><computeroutput>--vrdeauthtype
944	null\|external\|guest</computeroutput>: This allows you to choose
945	whether and how authorization will be performed; see <xref
946	linkend="vbox-auth" /> for details.</para>
947	</listitem>
948
949	<listitem>
950	<para><computeroutput>--vrdpmulticon on\|off</computeroutput>: This
951	enables multiple VRDP connections to the same VRDP server; see
952	<xref lang="" linkend="vrdp-multiconnection" />.</para>
953	</listitem>
954
955	<listitem>
956	<para><computeroutput>--vrdpreusecon on\|off</computeroutput>: This
957	specifies the VRDP server behavior when multiple connections are
958	disabled. When this option is enabled, the VRDP server will allow
959	a new client to connect and drop the existing connection. When
960	this option is disabled (this is the default setting), a new
961	connection will not be accepted if there is already a client
962	connected to the server.</para>
963	</listitem>
964
965	<listitem>
966	<para><computeroutput>--vrdpvideochannel on\|off</computeroutput>:
967	This enables VRDP video acceleration; see <xref lang=""
968	linkend="vrdp-videochannel" />.</para>
969	</listitem>
970
971	<listitem>
972	<para><computeroutput>--vrdpvideochannelquality
973	<percent></computeroutput>: Sets the image quality for VRDP
974	video acceleration; see <xref lang=""
975	linkend="vrdp-videochannel" />.</para>
976	</listitem>
977	</itemizedlist></para>
978	</sect2>
979
980	<sect2 id="vboxmanage-modifyvm-teleport">
981	<title>Teleporting settings</title>
982
983	<para>With the following commands for <computeroutput>VBoxManage
984	modifyvm</computeroutput> you can configure a machine to be a target for
985	teleporting. See <xref linkend="teleporting" /> for an
986	introduction.<itemizedlist>
987	<listitem>
988	<para><computeroutput>--teleporter on\|off</computeroutput>: With
989	this setting you turn on or off whether a machine waits for a
990	teleporting request to come in on the network when it is started.
991	If "on", when the machine is started, it does not boot the virtual
992	machine as it would normally; instead, it then waits for a
993	teleporting request to come in on the port and address listed with
994	the next two parameters.</para>
995	</listitem>
996
997	<listitem>
998	<para><computeroutput>--teleporterport
999	<port></computeroutput>, <computeroutput>--teleporteraddress
1000	<address></computeroutput>: these must be used with
1001	--teleporter and tell the virtual machine on which port and
1002	address it should listen for a teleporting request from another
1003	virtual machine. <computeroutput><port></computeroutput> can
1004	be any free TCP/IP port number (e.g. 6000);
1005	<computeroutput><address></computeroutput> can be any IP
1006	address or hostname and specifies the TCP/IP socket to bind to.
1007	The default is "0.0.0.0", which means any address.</para>
1008	</listitem>
1009
1010	<listitem>
1011	<para><computeroutput>--teleporterpassword
1012	<password></computeroutput>: if this optional argument is
1013	given, then the teleporting request will only succeed if the
1014	source machine specifies the same password as the one given with
1015	this command.</para>
1016	</listitem>
1017
1018	<listitem>
1019	<para><computeroutput>--cpuid <leaf> <eax> <ebx>
1020	<ecx> <edx></computeroutput>: Advanced users can use
1021	this command before a teleporting operation to restrict the
1022	virtual CPU capabilities that VirtualBox presents to the guest
1023	operating system. This must be run on both the source and the
1024	target machines involved in the teleporting and will then modify
1025	what the guest sees when it executes the
1026	<computeroutput>CPUID</computeroutput> machine instruction. This
1027	might help with misbehaving applications that wrongly assume that
1028	certain CPU capabilities are present. The meaning of the
1029	parameters is hardware dependent; please refer to the AMD or Intel
1030	processor manuals.</para>
1031	</listitem>
1032	</itemizedlist></para>
1033	</sect2>
1034	</sect1>
1035
1036	<sect1 id="vboxmanage-import">
1037	<title>VBoxManage import</title>
1038
1039	<para>This command imports a virtual appliance in OVF format by copying
1040	the virtual disk images and creating virtual machines in VirtualBox. See
1041	<xref linkend="ovf" /> for an introduction to appliances.</para>
1042
1043	<para>The <computeroutput>import</computeroutput> subcommand takes at
1044	least the path name of an OVF file as input and expects the disk images,
1045	if needed, in the same directory as the OVF file. A lot of additional
1046	command-line options are supported to control in detail what is being
1047	imported and modify the import parameters, but the details depend on the
1048	content of the OVF file.</para>
1049
1050	<para>It is therefore recommended to first run the import subcommand with
1051	the <computeroutput>--dry-run</computeroutput> or
1052	<computeroutput>-n</computeroutput> option. This will then print a
1053	description of the appliance's contents to the screen how it would be
1054	imported into VirtualBox, together with the optional command-line options
1055	to influence the import behavior.</para>
1056
1057	<para>As an example, here is the screen output with a sample appliance
1058	containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
1059	Interpreting WindowsXp.ovf...
1060	OK.
1061	Virtual system 0:
1062	0: Suggested OS type: "WindowsXP"
1063	(change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
1064	1: Suggested VM name "Windows XP Professional_1"
1065	(change with "--vsys 0 --vmname <name>")
1066	3: Number of CPUs: 1
1067	(change with "--vsys 0 --cpus <n>")
1068	4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
1069	5: Sound card (appliance expects "ensoniq1371", can change on import)
1070	(disable with "--vsys 0 --unit 5 --ignore")
1071	6: USB controller
1072	(disable with "--vsys 0 --unit 6 --ignore")
1073	7: Network adapter: orig bridged, config 2, extra type=bridged
1074	8: Floppy
1075	(disable with "--vsys 0 --unit 8 --ignore")
1076	9: SCSI controller, type BusLogic
1077	(change with "--vsys 0 --unit 9 --scsitype {BusLogic\|LsiLogic}";
1078	disable with "--vsys 0 --unit 9 --ignore")
1079	10: IDE controller, type PIIX4
1080	(disable with "--vsys 0 --unit 10 --ignore")
1081	11: Hard disk image: source image=WindowsXp.vmdk,
1082	target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
1083	(change controller with "--vsys 0 --unit 11 --controller <id>";
1084	disable with "--vsys 0 --unit 11 --ignore")</screen></para>
1085
1086	<para>As you can see, the individual configuration items are numbered, and
1087	depending on their type support different command-line options. The import
1088	subcommand can be directed to ignore many such items with a
1089	<computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
1090	X is the number of the virtual system (zero unless there are several
1091	virtual system descriptions in the appliance) and Y the item number, as
1092	printed on the screen.</para>
1093
1094	<para>In the above example, Item #1 specifies the name of the target
1095	machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
1096	respectively. Item #11 describes a hard disk image; in this case, the
1097	additional <computeroutput>--controller</computeroutput> option indicates
1098	which item the disk image should be connected to, with the default coming
1099	from the OVF file.</para>
1100
1101	<para>You can combine several items for the same virtual system behind the
1102	same <computeroutput>--vsys</computeroutput> option. For example, to
1103	import a machine as described in the OVF, but without the sound card and
1104	without the USB controller, and with the disk image connected to the IDE
1105	controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
1106	--vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
1107	</sect1>
1108
1109	<sect1 id="vboxmanage-export">
1110	<title>VBoxManage export</title>
1111
1112	<para>This command exports one or more virtual machines from VirtualBox
1113	into a virtual appliance in OVF format, including copying their virtual
1114	disk images to compressed VMDK. See <xref linkend="ovf" /> for an
1115	introduction to appliances.</para>
1116
1117	<para>The <computeroutput>export</computeroutput> command is simple to
1118	use: list the machine (or the machines) that you would like to export to
1119	the same OVF file and specify the target OVF file after an additional
1120	<computeroutput>--output</computeroutput> or
1121	<computeroutput>-o</computeroutput> option. Note that the directory of the
1122	target OVF file will also receive the exported disk images in the
1123	compressed VMDK format (regardless of the original format) and should have
1124	enough disk space left for them.</para>
1125
1126	<para>Beside a simple export of a given virtual machine, you can append
1127	several product information to the appliance file. Use
1128	<computeroutput>--product</computeroutput>,
1129	<computeroutput>--producturl</computeroutput>,
1130	<computeroutput>--vendor</computeroutput>,
1131	<computeroutput>--vendorurl</computeroutput> and
1132	<computeroutput>--version</computeroutput> to specify this additional
1133	information. For legal reasons you may add a license text or the content
1134	of a license file by using the <computeroutput>--eula</computeroutput> and
1135	<computeroutput>--eulafile</computeroutput> option respectively. As with
1136	OVF import, you must use the <computeroutput>--vsys X</computeroutput>
1137	option to direct the previously mentioned options to the correct virtual
1138	machine.</para>
1139
1140	<para>For virtualization products which aren't fully compatible with the
1141	OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
1142	<computeroutput>--legacy09</computeroutput> option.</para>
1143	</sect1>
1144
1145	<sect1 id="vboxmanage-startvm">
1146	<title>VBoxManage startvm</title>
1147
1148	<para>This command starts a virtual machine that is currently in the
1149	"Powered off" or "Saved" states.</para>
1150
1151	<note>
1152	<para>This is provided for backwards compatibility only. We recommend to
1153	start virtual machines directly by running the respective front-end, as
1154	you might otherwise miss important error and state information that
1155	VirtualBox may display on the console. This is especially important for
1156	front-ends other than <computeroutput>VirtualBox</computeroutput>, our
1157	graphical user interface, because those cannot display error messages in
1158	a popup window. See <xref linkend="vboxheadless" /> for more
1159	information.</para>
1160	</note>
1161
1162	<para>The optional <computeroutput>--type</computeroutput> specifier
1163	determines whether the machine will be started in a window (GUI mode,
1164	which is the default) or whether the output should go through
1165	<computeroutput>VBoxHeadless</computeroutput>, with VRDP enabled or not;
1166	see <xref linkend="vboxheadless" /> for more information. The list of
1167	types is subject to change, and it's not guaranteed that all types are
1168	accepted by any product variant.</para>
1169
1170	<para>The following values are allowed:</para>
1171
1172	<glosslist>
1173	<glossentry>
1174	<glossterm>gui</glossterm>
1175
1176	<glossdef>
1177	<para>Starts a VM showing a GUI window. This is the default.</para>
1178	</glossdef>
1179	</glossentry>
1180
1181	<glossentry>
1182	<glossterm>vrdp</glossterm>
1183
1184	<glossdef>
1185	<para>Starts a VM showing a GUI window, with its graphics card
1186	output accessible by an RDP client.</para>
1187	</glossdef>
1188	</glossentry>
1189
1190	<glossentry>
1191	<glossterm>headless</glossterm>
1192
1193	<glossdef>
1194	<para>Starts a VM without a window for remote RDP display
1195	only.</para>
1196	</glossdef>
1197	</glossentry>
1198	</glosslist>
1199	</sect1>
1200
1201	<sect1 id="vboxmanage-controlvm">
1202	<title>VBoxManage controlvm</title>
1203
1204	<para>The <computeroutput>controlvm</computeroutput> subcommand allows you
1205	to change the state of a virtual machine that is currently running. The
1206	following can be specified:</para>
1207
1208	<para><itemizedlist>
1209	<listitem>
1210	<para><computeroutput>VBoxManage controlvm <vm>
1211	pause</computeroutput> temporarily puts a virtual machine on hold,
1212	without changing its state for good. The VM window will be painted
1213	in gray to indicate that the VM is currently paused. (This is
1214	equivalent to selecting the "Pause" item in the "Machine" menu of
1215	the GUI.)</para>
1216	</listitem>
1217
1218	<listitem>
1219	<para>Use <computeroutput>VBoxManage controlvm <vm>
1220	resume</computeroutput> to undo a previous
1221	<computeroutput>pause</computeroutput> command. (This is equivalent
1222	to selecting the "Resume" item in the "Machine" menu of the
1223	GUI.)</para>
1224	</listitem>
1225
1226	<listitem>
1227	<para><computeroutput>VBoxManage controlvm <vm>
1228	reset</computeroutput> has the same effect on a virtual machine as
1229	pressing the "Reset" button on a real computer: a cold reboot of the
1230	virtual machine, which will restart and boot the guest operating
1231	system again immediately. The state of the VM is not saved
1232	beforehand, and data may be lost. (This is equivalent to selecting
1233	the "Reset" item in the "Machine" menu of the GUI.)</para>
1234	</listitem>
1235
1236	<listitem>
1237	<para><computeroutput>VBoxManage controlvm <vm>
1238	poweroff</computeroutput> has the same effect on a virtual machine
1239	as pulling the power cable on a real computer. Again, the state of
1240	the VM is not saved beforehand, and data may be lost. (This is
1241	equivalent to selecting the "Close" item in the "Machine" menu of
1242	the GUI or pressing the window's close button, and then selecting
1243	"Power off the machine" in the dialog.)</para>
1244
1245	<para>After this, the VM's state will be "Powered off". From there,
1246	it can be started again; see <xref
1247	linkend="vboxmanage-startvm" />.</para>
1248	</listitem>
1249
1250	<listitem>
1251	<para><computeroutput>VBoxManage controlvm <vm>
1252	savestate</computeroutput> will save the current state of the VM to
1253	disk and then stop the VM. (This is equivalent to selecting the
1254	"Close" item in the "Machine" menu of the GUI or pressing the
1255	window's close button, and then selecting "Save the machine state"
1256	in the dialog.)</para>
1257
1258	<para>After this, the VM's state will be "Saved". From there, it can
1259	be started again; see <xref linkend="vboxmanage-startvm" />.</para>
1260	</listitem>
1261
1262	<listitem>
1263	<para><computeroutput>VBoxManage controlvm <vm> teleport
1264	--hostname <name> --port <port> [--password
1265	<password>]</computeroutput> makes the machine the source of a
1266	teleporting operation and initiates a teleport to the given target.
1267	See <xref linkend="teleporting" /> for an introduction. If the
1268	optional password is specified, it must match the password that was
1269	given to the <computeroutput>modifyvm</computeroutput> command for
1270	the target machine; see <xref
1271	linkend="vboxmanage-modifyvm-teleport" /> for details.</para>
1272	</listitem>
1273	</itemizedlist></para>
1274
1275	<para>A few extra options are available with
1276	<computeroutput>controlvm</computeroutput> that do not directly affect the
1277	VM's running state:</para>
1278
1279	<itemizedlist>
1280	<listitem>
1281	<para>The <computeroutput>setlinkstate<1-N></computeroutput>
1282	operation connects or disconnects virtual network cables from their
1283	network interfaces.</para>
1284	</listitem>
1285
1286	<listitem>
1287	<para><computeroutput>nic<1-N>
1288	null\|nat\|bridged\|intnet\|hostonly</computeroutput>: With this, you can
1289	set, for each of the VM's virtual network cards, what type of
1290	networking should be available. They can be not connected to the host
1291	(<computeroutput>null</computeroutput>), use network address
1292	translation (<computeroutput>nat</computeroutput>), bridged networking
1293	(<computeroutput>bridged</computeroutput>) or communicate with other
1294	virtual machines using internal networking
1295	(<computeroutput>intnet</computeroutput>) or host-only networking
1296	(<computeroutput>hostonly</computeroutput>). These options correspond
1297	to the modes which are described in detail in <xref
1298	linkend="networkingmodes" />.</para>
1299	</listitem>
1300
1301	<listitem>
1302	<para><computeroutput>usbattach</computeroutput> and
1303	<computeroutput>usbdettach</computeroutput> make host USB devices
1304	visible to the virtual machine on the fly, without the need for
1305	creating filters first. The USB devices can be specified by UUID
1306	(unique identifier) or by address on the host system.</para>
1307
1308	<para>You can use <computeroutput>VBoxManage list
1309	usbhost</computeroutput> to locate this information.</para>
1310	</listitem>
1311
1312	<listitem>
1313	<para><computeroutput>vrdp on\|off</computeroutput> lets you enable or
1314	disable the built-in VRDP server.</para>
1315	</listitem>
1316
1317	<listitem>
1318	<para><computeroutput>vrdpport default\|<ports></computeroutput>
1319	changes the port or a range of ports that the VRDP server can bind to;
1320	"default" or "0" means port 3389, the standard port for RDP. For
1321	details, see the description for the
1322	<computeroutput>--vrdpport</computeroutput> option in <xref
1323	linkend="vboxmanage-modifyvm-other" />.</para>
1324	</listitem>
1325
1326	<listitem>
1327	<para><computeroutput>setvideomodehint</computeroutput> requests that
1328	the guest system change to a particular video mode. This requires that
1329	the Guest Additions be installed, and will not work for all guest
1330	systems.</para>
1331	</listitem>
1332
1333	<listitem>
1334	<para>The <computeroutput>setcredentials</computeroutput> operation is
1335	used for remote logons in Windows guests. For details, please refer to
1336	<xref linkend="autologon" />.</para>
1337	</listitem>
1338
1339	<listitem>
1340	<para>The <computeroutput>guestmemoryballoon</computeroutput>
1341	operation changes the size of the guest memory balloon, that is,
1342	memory allocated by the VirtualBox Guest Additions from the guest
1343	operating system and returned to the hypervisor for re-use by other
1344	virtual machines. This must be specified in megabytes. For details,
1345	see <xref linkend="guestadd-balloon" />.</para>
1346	</listitem>
1347	</itemizedlist>
1348	</sect1>
1349
1350	<sect1>
1351	<title>VBoxManage discardstate</title>
1352
1353	<para>This command discards the saved state of a virtual machine which is
1354	not currently running, which will cause its operating system to restart
1355	next time you start it. This is the equivalent of pulling out the power
1356	cable on a physical machine, and should be avoided if possible.</para>
1357	</sect1>
1358
1359	<sect1>
1360	<title>VBoxManage snapshot</title>
1361
1362	<para>This command is used to control snapshots from the command line. A
1363	snapshot consists of a complete copy of the virtual machine settings,
1364	copied at the time when the snapshot was taken, and optionally a virtual
1365	machine saved state file if the snapshot was taken while the machine was
1366	running. After a snapshot has been taken, VirtualBox creates differencing
1367	hard disk for each normal hard disk associated with the machine so that
1368	when a snapshot is restored, the contents of the virtual machine's virtual
1369	hard disks can be quickly reset by simply dropping the pre-existing
1370	differencing files.</para>
1371
1372	<para>The <computeroutput>take</computeroutput> operation takes a snapshot
1373	of the current state of the virtual machine. You must supply a name for
1374	the snapshot and can optionally supply a description. The new snapshot is
1375	inserted into the snapshots tree as a child of the current snapshot and
1376	then becomes the new current snapshot.</para>
1377
1378	<para>The <computeroutput>delete</computeroutput> operation deletes a
1379	snapshot (specified by name or by UUID). This can take a while to finish
1380	since the differencing images associated with the snapshot might need to
1381	be merged with their child differencing images.</para>
1382
1383	<para>The <computeroutput>restore</computeroutput> operation will restore
1384	the given snapshot (specified by name or by UUID) by resetting the virtual
1385	machine's settings and current state to that of the snapshot. The previous
1386	current state of the machine will be lost. After this, the given snapshot
1387	becomes the new "current" snapshot so that subsequent snapshots are
1388	inserted under the snapshot from which was restored.</para>
1389
1390	<para>The <computeroutput>restorecurrent</computeroutput> operation is a
1391	shortcut to restore the current snapshot (i.e. the snapshot from which the
1392	current state is derived). This subcommand is equivalent to using the
1393	"restore" subcommand with the name or UUID of the current snapshot, except
1394	that it avoids the extra step of determining that name or UUID.</para>
1395
1396	<para>With the <computeroutput>edit</computeroutput> operation, you can
1397	change the name or description of an existing snapshot.</para>
1398
1399	<para>With the <computeroutput>showvminfo</computeroutput> operation, you
1400	can view the virtual machine settings that were stored with an existing
1401	snapshot.</para>
1402	</sect1>
1403
1404	<sect1 id="vboxmanage-storage">
1405	<title>VBoxManage storagectl / storageattach</title>
1406
1407	<para>These commands allow to attach new storage controllers to a VM,
1408	modify or remove the existing ones and also allows the user to change the
1409	hard disk, DVD or floppy images attached to them. The list of the storage
1410	controllers attached to the VM can be found by the command:</para>
1411
1412	<screen>VBoxManage showvminfo <vmname></screen>
1413
1414	<para>See also <xref linkend="vboxmanage-showvminfo" />.</para>
1415
1416	<sect2 id="vboxmanage-storagectl">
1417	<title>VBoxManage storagectl</title>
1418
1419	<para>This command attaches/modifies/removes a storage controller. The
1420	syntax is as follows:</para>
1421
1422	<screen>VBoxManage storagectl <uuid\|vmname>
1423	--name <name>
1424	[--add <ide/sata/scsi/floppy>]
1425	[--controller <LsiLogic/BusLogic/IntelAhci/PIIX3/
1426	PIIX4/ICH6/I8207>]
1427	[--sataideemulation<1-4> <1-30>]
1428	[--sataportcount <1-30>]
1429	[--hostiocache on\|off]
1430	[--remove]</screen>
1431
1432	<para>where the parameters mean: <glosslist>
1433	<glossentry>
1434	<glossterm>uuid\|vmname</glossterm>
1435
1436	<glossdef>
1437	<para>The VM UUID or VM Name. Mandatory.</para>
1438	</glossdef>
1439	</glossentry>
1440
1441	<glossentry>
1442	<glossterm>name</glossterm>
1443
1444	<glossdef>
1445	<para>Name of the storage controller. Mandatory.</para>
1446	</glossdef>
1447	</glossentry>
1448
1449	<glossentry>
1450	<glossterm>add</glossterm>
1451
1452	<glossdef>
1453	<para>Define the type of the system bus to which the storage
1454	controller must be connected.</para>
1455	</glossdef>
1456	</glossentry>
1457
1458	<glossentry>
1459	<glossterm>controller</glossterm>
1460
1461	<glossdef>
1462	<para>Allows to choose the type of chipset being emulated for
1463	the given storage controller.</para>
1464	</glossdef>
1465	</glossentry>
1466
1467	<glossentry>
1468	<glossterm>sataideemulation</glossterm>
1469
1470	<glossdef>
1471	<para>This specifies which SATA ports should operate in IDE
1472	emulation mode. As explained in <xref
1473	linkend="harddiskcontrollers" />, by default, this is the case
1474	for SATA ports 1-4; with this command, you can map four IDE
1475	channels to any of the 30 supported SATA ports.</para>
1476	</glossdef>
1477	</glossentry>
1478
1479	<glossentry>
1480	<glossterm>sataportcount</glossterm>
1481
1482	<glossdef>
1483	<para>This determines how many ports the SATA controller should
1484	support.</para>
1485	</glossdef>
1486	</glossentry>
1487
1488	<glossentry>
1489	<glossterm>hostiocache</glossterm>
1490
1491	<glossdef>
1492	<para>Configures the use of the host I/O cache for all disk
1493	images attached to this storage controller. For details, please
1494	see <xref linkend="iocaching" />.</para>
1495	</glossdef>
1496	</glossentry>
1497
1498	<glossentry>
1499	<glossterm>remove</glossterm>
1500
1501	<glossdef>
1502	<para>Removes the storage controller from the VM config.</para>
1503	</glossdef>
1504	</glossentry>
1505	</glosslist></para>
1506	</sect2>
1507
1508	<sect2>
1509	<title>VBoxManage storageattach</title>
1510
1511	<para>This command attaches/modifies/removes a storage medium connected
1512	to the storage controller named by --storagectl. The syntax is as
1513	follows:</para>
1514
1515	<screen>VBoxManage storageattach <uuid\|vmname>
1516	--storagectl <name>
1517	--port <number>
1518	--device <number>
1519	[--type dvddrive\|hdd\|fdd
1520	--medium none\|emptydrive\|uuid\|filename\|host:<drive>]
1521	[--passthrough on\|off]
1522	[--forceunmount]</screen>
1523
1524	<para>where the parameters mean: <glosslist>
1525	<glossentry>
1526	<glossterm>uuid\|vmname</glossterm>
1527
1528	<glossdef>
1529	<para>The VM UUID or VM Name. Mandatory.</para>
1530	</glossdef>
1531	</glossentry>
1532
1533	<glossentry>
1534	<glossterm>storagectl</glossterm>
1535
1536	<glossdef>
1537	<para>Name of the storage controller. Mandatory.</para>
1538	</glossdef>
1539	</glossentry>
1540
1541	<glossentry>
1542	<glossterm>port</glossterm>
1543
1544	<glossdef>
1545	<para>Port number to which the medium has to be
1546	attached/detached/modified. Mandatory.</para>
1547	</glossdef>
1548	</glossentry>
1549
1550	<glossentry>
1551	<glossterm>device</glossterm>
1552
1553	<glossdef>
1554	<para>Device Number to which the medium has to be
1555	attached/detached/modified. Mandatory.</para>
1556	</glossdef>
1557	</glossentry>
1558
1559	<glossentry>
1560	<glossterm>type</glossterm>
1561
1562	<glossdef>
1563	<para>Define the type of the drive to which the medium is being
1564	attached/detached/modified.</para>
1565	</glossdef>
1566	</glossentry>
1567
1568	<glossentry>
1569	<glossterm>medium</glossterm>
1570
1571	<glossdef>
1572	<para>Specifies what is to be attached. The following values are
1573	supported:<itemizedlist>
1574	<listitem>
1575	<para>"none": Any existing device should be removed from
1576	the given slot.</para>
1577
1578	<note>
1579	<para>DVD/floppy drives or harddisks cannot be removed
1580	while the VM is running.</para>
1581	</note>
1582	</listitem>
1583
1584	<listitem>
1585	<para>"emptydrive": This is only allowed if the given slot
1586	is a DVD or floppy drive. In this case, the slot behaves
1587	like a removeable drive into which no media has been
1588	inserted.</para>
1589	</listitem>
1590
1591	<listitem>
1592	<para>If a UUID is specified, it must be the UUID of a
1593	storage medium that is already known to VirtualBox (e.g.
1594	because it has been attached to another virtual machine).
1595	This medium is then attached to the given device
1596	slot.</para>
1597	</listitem>
1598
1599	<listitem>
1600	<para>If a filename is specified, it must be the full path
1601	of an existing disk image (ISO, RAW, VDI, VMDK or other),
1602	which is then attached to the given device slot.</para>
1603	</listitem>
1604
1605	<listitem>
1606	<para>"host:<drive>: This is only allowed if the
1607	given slot is a DVD or floppy drive, in which case the
1608	device slot is attached to the specified DVD or floppy
1609	drive on the host computer.</para>
1610	</listitem>
1611	</itemizedlist></para>
1612	</glossdef>
1613	</glossentry>
1614
1615	<glossentry>
1616	<glossterm>passthrough</glossterm>
1617
1618	<glossdef>
1619	<para>With this, you can enable DVD writing support (currently
1620	experimental; see <xref linkend="storage-write-cds" />).</para>
1621	</glossdef>
1622	</glossentry>
1623
1624	<glossentry>
1625	<glossterm>forceunmount</glossterm>
1626
1627	<glossdef>
1628	<para>If this option is specified then you can unmount the
1629	DVD/CD/Floppy or mount a new DVD/CD/Floppy even if the previous
1630	one is locked down by the guest for reading.</para>
1631	</glossdef>
1632	</glossentry>
1633	</glosslist></para>
1634	</sect2>
1635	</sect1>
1636
1637	<sect1>
1638	<title>VBoxManage showhdinfo</title>
1639
1640	<para>This command shows information about a virtual hard disk image,
1641	notably its size, its size on disk, its type and the VM it is in use
1642	by.<note>
1643	<para>For compatibility with earlier versions of VirtualBox, the
1644	"showvdiinfo" command is also supported and mapped internally to the
1645	"showhdinfo" command.</para>
1646	</note></para>
1647	</sect1>
1648
1649	<sect1 id="vboxmanage-createvdi">
1650	<title>VBoxManage createhd</title>
1651
1652	<para>This command creates a new virtual hard disk image. The syntax is as
1653	follows:</para>
1654
1655	<screen>VBoxManage createhd --filename <filename>
1656	--size <megabytes>
1657	[--format VDI\|VMDK\|VHD] (default: VDI)
1658	[--variant Standard,Fixed,Split2G,Stream,ESX]
1659	[--type normal\|writethrough] (default: normal)
1660	[--comment <comment>]
1661	[--remember]</screen>
1662
1663	<para>where the parameters mean:<glosslist>
1664	<glossentry>
1665	<glossterm>filename</glossterm>
1666
1667	<glossdef>
1668	<para>Allows to choose a file name. Mandatory.</para>
1669	</glossdef>
1670	</glossentry>
1671
1672	<glossentry>
1673	<glossterm>size</glossterm>
1674
1675	<glossdef>
1676	<para>Allows to define the image capacity, in 1 MiB units.
1677	Mandatory.</para>
1678	</glossdef>
1679	</glossentry>
1680
1681	<glossentry>
1682	<glossterm>format</glossterm>
1683
1684	<glossdef>
1685	<para>Allows to choose a file format for the output file different
1686	from the file format of the input file.</para>
1687	</glossdef>
1688	</glossentry>
1689
1690	<glossentry>
1691	<glossterm>variant</glossterm>
1692
1693	<glossdef>
1694	<para>Allows to choose a file format variant for the output file.
1695	It is a comma-separated list of variant flags. Not all
1696	combinations are supported, and specifying inconsistent flags will
1697	result in an error message.</para>
1698	</glossdef>
1699	</glossentry>
1700
1701	<glossentry>
1702	<glossterm>type</glossterm>
1703
1704	<glossdef>
1705	<para>Only honored if --remember is also specified. Defines what
1706	kind of hard disk type this image should be.</para>
1707	</glossdef>
1708	</glossentry>
1709
1710	<glossentry>
1711	<glossterm>comment</glossterm>
1712
1713	<glossdef>
1714	<para>Allows to attach a comment to the image.</para>
1715	</glossdef>
1716	</glossentry>
1717
1718	<glossentry>
1719	<glossterm>remember</glossterm>
1720
1721	<glossdef>
1722	<para>Keep the destination image registered after it was
1723	successfully written.</para>
1724	</glossdef>
1725	</glossentry>
1726	</glosslist> <note>
1727	<para>For compatibility with earlier versions of VirtualBox, the
1728	"createvdi" command is also supported and mapped internally to the
1729	"createhd" command.</para>
1730	</note></para>
1731	</sect1>
1732
1733	<sect1 id="vboxmanage-modifyvdi">
1734	<title>VBoxManage modifyhd</title>
1735
1736	<para>With the <computeroutput>modifyhd</computeroutput> command, you can
1737	change the type of an existing image between the normal, immutable and
1738	write-through modes; see <xref linkend="hdimagewrites" /> for
1739	details.<note>
1740	<para>For compatibility with earlier versions of VirtualBox, the
1741	"modifyvdi" command is also supported and mapped internally to the
1742	"modifyhd" command.</para>
1743	</note></para>
1744
1745	<para>For immutable (differencing) hard disks only, the
1746	<computeroutput>modifyhd autoreset on\|off</computeroutput> command
1747	determines whether the disk is automatically reset on every VM startup
1748	(again, see <xref linkend="hdimagewrites" />). The default is "on".</para>
1749
1750	<para>In addition, the <computeroutput>modifyhd --compact</computeroutput>
1751	command can be used to compact disk images, i.e. remove blocks that only
1752	contains zeroes. For this operation to be effective, it is required to
1753	zero out free space in the guest system using a suitable software tool.
1754	Microsoft provides the <computeroutput>sdelete</computeroutput> tool for
1755	Windows guests. Execute <computeroutput>sdelete -c</computeroutput> in the
1756	guest to zero the free disk space before compressing the virtual disk
1757	image. Compaction works both for base images and for diff images created
1758	as part of a snapshot.</para>
1759	</sect1>
1760
1761	<sect1 id="vboxmanage-clonevdi">
1762	<title>VBoxManage clonehd</title>
1763
1764	<para>This command duplicates a registered virtual hard disk image to a
1765	new image file with a new unique identifier (UUID). The new image can be
1766	transferred to another host system or imported into VirtualBox again using
1767	the Virtual Media Manager; see <xref linkend="vdis" /> and <xref
1768	linkend="cloningvdis" />. The syntax is as follows:</para>
1769
1770	<screen>VBoxManage clonehd <uuid>\|<filename> <outputfile>
1771	[--format VDI\|VMDK\|VHD\|RAW\|<other>]
1772	[--variant Standard,Fixed,Split2G,Stream,ESX]
1773	[--type normal\|writethrough\|immutable\|shareable]
1774	[--remember] [--existing]</screen>
1775
1776	<para>where the parameters mean:<glosslist>
1777	<glossentry>
1778	<glossterm>format</glossterm>
1779
1780	<glossdef>
1781	<para>Allow to choose a file format for the output file different
1782	from the file format of the input file.</para>
1783	</glossdef>
1784	</glossentry>
1785
1786	<glossentry>
1787	<glossterm>variant</glossterm>
1788
1789	<glossdef>
1790	<para>Allow to choose a file format variant for the output file.
1791	It is a comma-separated list of variant flags. Not all
1792	combinations are supported, and specifying inconsistent flags will
1793	result in an error message.</para>
1794	</glossdef>
1795	</glossentry>
1796
1797	<glossentry>
1798	<glossterm>type</glossterm>
1799
1800	<glossdef>
1801	<para>Only honored if --remember is also specified. Defines what
1802	kind of hard disk type this image should be.</para>
1803	</glossdef>
1804	</glossentry>
1805
1806	<glossentry>
1807	<glossterm>remember</glossterm>
1808
1809	<glossdef>
1810	<para>Keep the destination image registered after it was
1811	successfully written.</para>
1812	</glossdef>
1813	</glossentry>
1814
1815	<glossentry>
1816	<glossterm>existing</glossterm>
1817
1818	<glossdef>
1819	<para>Perform the clone operation to an already existing
1820	destination medium. Only the portion of the source medium which
1821	fits into the destination medium is copied. This means if the
1822	destination medium is smaller than the source only a part of it is
1823	copied, and if the destination medium is larger than the source
1824	the remaining part of the destination medium is unchanged.</para>
1825	</glossdef>
1826	</glossentry>
1827	</glosslist> <note>
1828	<para>For compatibility with earlier versions of VirtualBox, the
1829	"clonevdi" command is also supported and mapped internally to the
1830	"clonehd" command.</para>
1831	</note></para>
1832	</sect1>
1833
1834	<sect1>
1835	<title>VBoxManage convertfromraw</title>
1836
1837	<para>This command converts a raw disk image to a VirtualBox Disk Image
1838	(VDI) file. The syntax is as follows:</para>
1839
1840	<screen>VBoxManage convertfromraw <filename> <outputfile>
1841	[--format VDI\|VMDK\|VHD]
1842	[--variant Standard,Fixed,Split2G,Stream,ESX]
1843	VBoxManage convertfromraw stdin <outputfile> <bytes>
1844	[--format VDI\|VMDK\|VHD]
1845	[--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
1846
1847	<para>where the parameters mean:<glosslist>
1848	<glossentry>
1849	<glossterm>format</glossterm>
1850
1851	<glossdef>
1852	<para>Select the disk image format to create. Default is
1853	VDI.</para>
1854	</glossdef>
1855	</glossentry>
1856
1857	<glossentry>
1858	<glossterm>variant</glossterm>
1859
1860	<glossdef>
1861	<para>Allow to choose a file format variant for the output file.
1862	It is a comma-separated list of variant flags. Not all
1863	combinations are supported, and specifying inconsistent flags will
1864	result in an error message.</para>
1865	</glossdef>
1866	</glossentry>
1867	</glosslist> The second form forces VBoxManage to read the content for
1868	the disk image from standard input (useful for using that command in a
1869	pipe).</para>
1870
1871	<para><note>
1872	<para>For compatibility with earlier versions of VirtualBox, the
1873	"convertdd" command is also supported and mapped internally to the
1874	"convertfromraw" command.</para>
1875	</note></para>
1876	</sect1>
1877
1878	<sect1 id="vboxmanage-addiscsidisk">
1879	<title>VBoxManage addiscsidisk</title>
1880
1881	<para>The <computeroutput>addiscsidisk</computeroutput> command attaches
1882	an iSCSI network storage unit to VirtualBox. The iSCSI target can then be
1883	made available to and used by a virtual machine as though it were a
1884	standard write-through virtual disk image.</para>
1885
1886	<para>This command has the following syntax:<screen>VBoxManage addiscsidisk --server <name>\|<ip>
1887	--target <target>
1888	[--port <port>]
1889	[--lun <lun>]
1890	[--username <username>]
1891	[--password <password>]
1892	[--type normal\|writethrough\|immutable]
1893	[--comment <comment>]
1894	[--intnet]</screen></para>
1895
1896	<para>where the parameters mean:<glosslist>
1897	<glossentry>
1898	<glossterm>server</glossterm>
1899
1900	<glossdef>
1901	<para>The host name or IP address of the iSCSI target.</para>
1902	</glossdef>
1903	</glossentry>
1904
1905	<glossentry>
1906	<glossterm>target</glossterm>
1907
1908	<glossdef>
1909	<para>Target name string. This is determined by the iSCSI target
1910	and used to identify the storage resource.</para>
1911	</glossdef>
1912	</glossentry>
1913
1914	<glossentry>
1915	<glossterm>port</glossterm>
1916
1917	<glossdef>
1918	<para>TCP/IP port number of the iSCSI service on the target
1919	(optional).</para>
1920	</glossdef>
1921	</glossentry>
1922
1923	<glossentry>
1924	<glossterm>lun</glossterm>
1925
1926	<glossdef>
1927	<para>Logical Unit Number of the target resource (optional).
1928	Often, this value is zero.</para>
1929	</glossdef>
1930	</glossentry>
1931
1932	<glossentry>
1933	<glossterm>username, password</glossterm>
1934
1935	<glossdef>
1936	<para>Username and password for target authentication, if required
1937	(optional).<note>
1938	<para>Currently, username and password are stored without
1939	encryption (i.e. in cleartext) in the machine configuration
1940	file.</para>
1941	</note></para>
1942	</glossdef>
1943	</glossentry>
1944
1945	<glossentry>
1946	<glossterm>type</glossterm>
1947
1948	<glossdef>
1949	<para>Defines what kind of hard disk type this image should
1950	be.</para>
1951	</glossdef>
1952	</glossentry>
1953
1954	<glossentry>
1955	<glossterm>comment</glossterm>
1956
1957	<glossdef>
1958	<para>Any description that you want to have stored with this item
1959	(optional; e.g. "Big storage server downstairs"). This is stored
1960	internally only and not needed for operation.</para>
1961	</glossdef>
1962	</glossentry>
1963
1964	<glossentry>
1965	<glossterm>intnet</glossterm>
1966
1967	<glossdef>
1968	<para>Connect to the iSCSI target via Internal Networking. This
1969	needs further configuration which is described in <xref
1970	linkend="iscsi-intnet" />.</para>
1971	</glossdef>
1972	</glossentry>
1973	</glosslist></para>
1974	</sect1>
1975
1976	<sect1 id="vboxmanage-closemedium">
1977	<title>VBoxManage closemedium</title>
1978
1979	<para>This commands removes a hard disk, DVD or floppy image from a
1980	VirtualBox media registry.<footnote>
1981	<para>Before VirtualBox 4.0, it was necessary to call VBoxManage
1982	openmedium before a medium could be attached to a virtual machine;
1983	that call "registered" the medium with the global VirtualBox media
1984	registry. With VirtualBox 4.0 this is no longer necessary; media are
1985	added to media registries automatically. The "closemedium" call has
1986	been retained, however, to allow for explicitly removing a medium from
1987	a registry.</para>
1988	</footnote></para>
1989
1990	<para>Optionally, you can request that the image be deleted. You will get
1991	appropriate diagnostics that the deletion failed, however the image will
1992	become unregistered in any case.</para>
1993	</sect1>
1994
1995	<sect1>
1996	<title>VBoxManage getextradata/setextradata</title>
1997
1998	<para>These commands let you attach and retrieve string data to a virtual
1999	machine or to a VirtualBox configuration (by specifying
2000	<computeroutput>global</computeroutput> instead of a virtual machine
2001	name). You must specify a key (as a text string) to associate the data
2002	with, which you can later use to retrieve it. For example:</para>
2003
2004	<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
2005	VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
2006
2007	<para>would associate the string "2006.01.01" with the key installdate for
2008	the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
2009	could retrieve the information as follows:</para>
2010
2011	<screen>VBoxManage getextradata Fedora5 installdate</screen>
2012
2013	<para>which would return</para>
2014
2015	<screen>VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
2016	(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
2017	All rights reserved.
2018
2019	Value: 2006.01.01</screen>
2020	</sect1>
2021
2022	<sect1 id="vboxmanage-setproperty">
2023	<title>VBoxManage setproperty</title>
2024
2025	<para>This command is used to change global settings which affect the
2026	entire VirtualBox installation. Some of these correspond to the settings
2027	in the "Global settings" dialog in the graphical user interface. The
2028	following properties are available:<glosslist>
2029	<glossentry>
2030	<glossterm>machinefolder</glossterm>
2031
2032	<glossdef>
2033	<para>This specifies the default folder in which virtual machine
2034	definitions are kept; see <xref linkend="vboxconfigdata" /> for
2035	details.</para>
2036	</glossdef>
2037	</glossentry>
2038
2039	<glossentry>
2040	<glossterm>vrdeauthlibrary</glossterm>
2041
2042	<glossdef>
2043	<para>This specifies which library to use when "external"
2044	authentication has been selected for a particular virtual machine;
2045	see <xref linkend="vbox-auth" /> for details.</para>
2046	</glossdef>
2047	</glossentry>
2048
2049	<glossentry>
2050	<glossterm>websrvauthlibrary</glossterm>
2051
2052	<glossdef>
2053	<para>This specifies which library the web service uses to
2054	authenticate users. For details about the VirtualBox web service,
2055	please refer to the separate VirtualBox SDK reference (see <xref
2056	linkend="VirtualBoxAPI" />).</para>
2057	</glossdef>
2058	</glossentry>
2059
2060	<glossentry>
2061	<glossterm>vrdelibrary</glossterm>
2062
2063	<glossdef>
2064	<para>This specifies which library implements the VirtualBox
2065	Remote Desktop Extension.</para>
2066	</glossdef>
2067	</glossentry>
2068
2069	<glossentry>
2070	<glossterm>hwvirtexenabled</glossterm>
2071
2072	<glossdef>
2073	<para>This selects whether or not hardware virtualization support
2074	is enabled by default.</para>
2075	</glossdef>
2076	</glossentry>
2077	</glosslist></para>
2078	</sect1>
2079
2080	<sect1>
2081	<title>VBoxManage usbfilter add/modify/remove</title>
2082
2083	<para>The <computeroutput>usbfilter</computeroutput> commands are used for
2084	working with USB filters in virtual machines, or global filters which
2085	affect the whole VirtualBox setup. Global filters are applied before
2086	machine-specific filters, and may be used to prevent devices from being
2087	captured by any virtual machine. Global filters are always applied in a
2088	particular order, and only the first filter which fits a device is
2089	applied. So for example, if the first global filter says to hold (make
2090	available) a particular Kingston memory stick device and the second to
2091	ignore all Kingston devices, that memory stick will be available to any
2092	machine with an appropriate filter, but no other Kingston device
2093	will.</para>
2094
2095	<para>When creating a USB filter using <computeroutput>usbfilter
2096	add</computeroutput>, you must supply three or four mandatory parameters.
2097	The index specifies the position in the list at which the filter should be
2098	placed. If there is already a filter at that position, then it and the
2099	following ones will be shifted back one place. Otherwise the new filter
2100	will be added onto the end of the list. The
2101	<computeroutput>target</computeroutput> parameter selects the virtual
2102	machine that the filter should be attached to or use "global" to apply it
2103	to all virtual machines. <computeroutput>name</computeroutput> is a name
2104	for the new filter and for global filters,
2105	<computeroutput>action</computeroutput> says whether to allow machines
2106	access to devices that fit the filter description ("hold") or not to give
2107	them access ("ignore"). In addition, you should specify parameters to
2108	filter by. You can find the parameters for devices attached to your system
2109	using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
2110	you can specify whether the filter should be active, and for local
2111	filters, whether they are for local devices, remote (over an RDP
2112	connection) or either.</para>
2113
2114	<para>When you modify a USB filter using <computeroutput>usbfilter
2115	modify</computeroutput>, you must specify the filter by index (see the
2116	output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
2117	find global filter indexes and that of <computeroutput>VBoxManage
2118	showvminfo</computeroutput> to find indexes for individual machines) and
2119	by target, which is either a virtual machine or "global". The properties
2120	which can be changed are the same as for <computeroutput>usbfilter
2121	add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
2122	remove</computeroutput> and specify the index and the target.</para>
2123	</sect1>
2124
2125	<sect1 id="vboxmanage-sharedfolder">
2126	<title>VBoxManage sharedfolder add/remove</title>
2127
2128	<para>This command allows you to share folders on the host computer with
2129	guest operating systems. For this, the guest systems must have a version
2130	of the VirtualBox Guest Additions installed which supports this
2131	functionality.</para>
2132
2133	<para>Shared folders are described in detail in <xref
2134	linkend="sharedfolders" />.</para>
2135	</sect1>
2136
2137	<sect1>
2138	<title id="metrics">VBoxManage metrics</title>
2139
2140	<para>This command supports monitoring the usage of system resources.
2141	Resources are represented by various metrics associated with the host
2142	system or a particular VM. For example, the host system has a
2143	<computeroutput>CPU/Load/User</computeroutput> metric that shows the
2144	percentage of time CPUs spend executing in user mode over a specific
2145	sampling period.</para>
2146
2147	<para>Metric data is collected and retained internally; it may be
2148	retrieved at any time with the <computeroutput>VBoxManage metrics
2149	query</computeroutput> subcommand. The data is available as long as the
2150	background <computeroutput>VBoxSVC</computeroutput> process is alive. That
2151	process terminates shortly after all VMs and frontends have been
2152	closed.</para>
2153
2154	<para>By default no metrics are collected at all. Metrics collection does
2155	not start until <computeroutput>VBoxManage metrics setup</computeroutput>
2156	is invoked with a proper sampling interval and the number of metrics to be
2157	retained. The interval is measured in seconds. For example, to enable
2158	collecting the host processor and memory usage metrics every second and
2159	keeping the 5 most current samples, the following command can be
2160	used:</para>
2161
2162	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
2163
2164	<para>Metric collection can only be enabled for started VMs. Collected
2165	data and collection settings for a particular VM will disappear as soon as
2166	it shuts down. Use <computeroutput>VBoxManage metrics list
2167	</computeroutput> subcommand to see which metrics are currently available.
2168	You can also use <computeroutput>--list</computeroutput> option with any
2169	subcommand that modifies metric settings to find out which metrics were
2170	affected.</para>
2171
2172	<para>Note that the <computeroutput>VBoxManage metrics
2173	setup</computeroutput> subcommand discards all samples that may have been
2174	previously collected for the specified set of objects and metrics.</para>
2175
2176	<para>To enable or disable metrics collection without discarding the data
2177	<computeroutput>VBoxManage metrics enable</computeroutput> and
2178	<computeroutput>VBoxManage metrics disable</computeroutput> subcommands
2179	can be used. Note that these subcommands expect metrics, not submetrics,
2180	like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
2181	other words enabling <code>CPU/Load/User</code> while disabling
2182	<code>CPU/Load/Kernel</code> is not supported.</para>
2183
2184	<para>The host and VMs have different sets of associated metrics.
2185	Available metrics can be listed with <computeroutput>VBoxManage metrics
2186	list</computeroutput> subcommand.</para>
2187
2188	<para>A complete metric name may include an aggregate function. The name
2189	has the following form:
2190	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
2191	For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
2192	for the minimum amount of available memory over all retained data if
2193	applied to the host object.</para>
2194
2195	<para>Subcommands may apply to all objects and metrics or can be limited
2196	to one object or/and a list of metrics. If no objects or metrics are given
2197	in the parameters, the subcommands will apply to all available metrics of
2198	all objects. You may use an asterisk
2199	("<computeroutput>*</computeroutput>") to explicitly specify that the
2200	command should be applied to all objects or metrics. Use "host" as the
2201	object name to limit the scope of the command to host-related metrics. To
2202	limit the scope to a subset of metrics, use a metric list with names
2203	separated by commas.</para>
2204
2205	<para>For example, to query metric data on the CPU time spent in user and
2206	kernel modes by the virtual machine named "test", you can use the
2207	following command:</para>
2208
2209	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
2210
2211	<para>The following list summarizes the available subcommands:</para>
2212
2213	<glosslist>
2214	<glossentry>
2215	<glossterm>list</glossterm>
2216
2217	<glossdef>
2218	<para>This subcommand shows the parameters of the currently existing
2219	metrics. Note that VM-specific metrics are only available when a
2220	particular VM is running.</para>
2221	</glossdef>
2222	</glossentry>
2223
2224	<glossentry>
2225	<glossterm>setup</glossterm>
2226
2227	<glossdef>
2228	<para>This subcommand sets the interval between taking two samples
2229	of metric data and the number of samples retained internally. The
2230	retained data is available for displaying with the
2231	<code>query</code> subcommand. The <computeroutput>--list
2232	</computeroutput> option shows which metrics have been modified as
2233	the result of the command execution.</para>
2234	</glossdef>
2235	</glossentry>
2236
2237	<glossentry>
2238	<glossterm>enable</glossterm>
2239
2240	<glossdef>
2241	<para>This subcommand "resumes" data collection after it has been
2242	stopped with <code>disable</code> subcommand. Note that specifying
2243	submetrics as parameters will not enable underlying metrics. Use
2244	<computeroutput>--list</computeroutput> to find out if the command
2245	did what was expected.</para>
2246	</glossdef>
2247	</glossentry>
2248
2249	<glossentry>
2250	<glossterm>disable</glossterm>
2251
2252	<glossdef>
2253	<para>This subcommand "suspends" data collection without affecting
2254	collection parameters or collected data. Note that specifying
2255	submetrics as parameters will not disable underlying metrics. Use
2256	<computeroutput>--list</computeroutput> to find out if the command
2257	did what was expected.</para>
2258	</glossdef>
2259	</glossentry>
2260
2261	<glossentry>
2262	<glossterm>query</glossterm>
2263
2264	<glossdef>
2265	<para>This subcommand retrieves and displays the currently retained
2266	metric data.<note>
2267	<para>The <code>query</code> subcommand does not remove or
2268	"flush" retained data. If you query often enough you will see
2269	how old samples are gradually being "phased out" by new
2270	samples.</para>
2271	</note></para>
2272	</glossdef>
2273	</glossentry>
2274
2275	<glossentry>
2276	<glossterm>collect</glossterm>
2277
2278	<glossdef>
2279	<para>This subcommand sets the interval between taking two samples
2280	of metric data and the number of samples retained internally. The
2281	collected data is displayed periodically until Ctrl-C is pressed
2282	unless the <computeroutput>--detach</computeroutput> option is
2283	specified. With the <computeroutput>--detach</computeroutput>
2284	option, this subcommand operates the same way as <code>setup</code>
2285	does. The <computeroutput>--list</computeroutput> option shows which
2286	metrics match the specified filter.</para>
2287	</glossdef>
2288	</glossentry>
2289	</glosslist>
2290	</sect1>
2291
2292	<sect1 id="vboxmanage-guestproperty">
2293	<title>VBoxManage guestproperty</title>
2294
2295	<para>The "guestproperty" commands allow you to get or set properties of a
2296	running virtual machine. Please see <xref linkend="guestadd-guestprops" />
2297	for an introduction. As explained there, guest properties are arbitrary
2298	key/value string pairs which can be written to and read from by either the
2299	guest or the host, so they can be used as a low-volume communication
2300	channel for strings, provided that a guest is running and has the Guest
2301	Additions installed. In addition, a number of values whose keys begin with
2302	"/VirtualBox/" are automatically set and maintained by the Guest
2303	Additions.</para>
2304
2305	<para>The following subcommands are available (where
2306	<computeroutput><vm></computeroutput>, in each case, can either be a
2307	VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
2308	<listitem>
2309	<para><computeroutput>enumerate <vm> [-patterns
2310	<pattern>]</computeroutput>: This lists all the guest
2311	properties that are available for the given VM, including the value.
2312	This list will be very limited if the guest's service process cannot
2313	be contacted, e.g. because the VM is not running or the Guest
2314	Additions are not installed.</para>
2315
2316	<para>If <computeroutput>--patterns <pattern></computeroutput>
2317	is specified, it acts as a filter to only list properties that match
2318	the given pattern. The pattern can contain the following wildcard
2319	characters:<itemizedlist>
2320	<listitem>
2321	<para><computeroutput>*</computeroutput> (asterisk):
2322	represents any number of characters; for example,
2323	"<computeroutput>/VirtualBox*</computeroutput>" would match
2324	all properties beginning with "/VirtualBox".</para>
2325	</listitem>
2326
2327	<listitem>
2328	<para><computeroutput>?</computeroutput> (question mark):
2329	represents a single arbitrary character; for example,
2330	"<computeroutput>fo?</computeroutput>" would match both "foo"
2331	and "for".</para>
2332	</listitem>
2333
2334	<listitem>
2335	<para><computeroutput>\|</computeroutput> (pipe symbol): can be
2336	used to specify multiple alternative patterns; for example,
2337	"<computeroutput>s\|t</computeroutput>" would match anything
2338	starting with either "s" or "t".</para>
2339	</listitem>
2340	</itemizedlist></para>
2341	</listitem>
2342
2343	<listitem>
2344	<para><computeroutput>get <vm></computeroutput>: This
2345	retrieves the value of a single property only. If the property
2346	cannot be found (e.g. because the guest is not running), this will
2347	print "No value set!".</para>
2348	</listitem>
2349
2350	<listitem>
2351	<para><computeroutput>set <vm> <property> [<value>
2352	[-flags <flags>]]</computeroutput>: This allows you to set a
2353	guest property by specifying the key and value. If
2354	<computeroutput><value></computeroutput> is omitted, the
2355	property is deleted. With <computeroutput>--flags</computeroutput>
2356	you can optionally specify additional behavior (you can combine
2357	several by separating them with commas):<itemizedlist>
2358	<listitem>
2359	<para><computeroutput>TRANSIENT</computeroutput>: the value
2360	will not be stored with the VM data when the VM exits;</para>
2361	</listitem>
2362
2363	<listitem>
2364	<para><computeroutput>RDONLYGUEST</computeroutput>: the value
2365	can only be changed by the host, but the guest can only read
2366	it;</para>
2367	</listitem>
2368
2369	<listitem>
2370	<para><computeroutput>RDONLYHOST</computeroutput>: reversely,
2371	the value can only be changed by the guest, but the host can
2372	only read it;</para>
2373	</listitem>
2374
2375	<listitem>
2376	<para><computeroutput>READONLY</computeroutput>: a combination
2377	of the two, the value cannot be changed at all.</para>
2378	</listitem>
2379	</itemizedlist></para>
2380	</listitem>
2381
2382	<listitem>
2383	<para><computeroutput>wait <vm> <pattern> --timeout
2384	<timeout></computeroutput>: This waits for a particular value
2385	described by "pattern" to change or to be deleted or created. The
2386	pattern rules are the same as for the "enumerate" subcommand
2387	above.</para>
2388	</listitem>
2389	</itemizedlist></para>
2390	</sect1>
2391
2392	<sect1 id="vboxmanage-guestcontrol">
2393	<title>VBoxManage guestcontrol</title>
2394
2395	<para>The "guestcontrol" commands allow you to control certain things
2396	inside a guest from the host. Please see <xref
2397	linkend="guestadd-guestcontrol" /> for an introduction.</para>
2398
2399	<para>Generally, the syntax is as follows:</para>
2400
2401	<screen>VBoxManage guestcontrol <command></screen>
2402
2403	<para>The following subcommands are available (where
2404	<computeroutput><vm></computeroutput>, in each case, can either be a
2405	VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
2406	<listitem>
2407	<para><computeroutput>execute</computeroutput>, which allows for
2408	executing a program/script (process) which is already installed and
2409	runnable on the guest. This command only works while a VM is up and
2410	running and has the following syntax:</para>
2411
2412	<screen>VBoxManage guestcontrol execute <vmname>\|<uuid>
2413	<path to program>
2414	--username <name> --password <password>
2415	[--arguments "<arguments>"]
2416	[--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"]
2417	[--flags <flags>] [--timeout <msec>]
2418	[--verbose] [--wait-for exit,stdout,stderr\|\|]</screen>
2419
2420	<para>where the parameters mean: <glosslist>
2421	<glossentry>
2422	<glossterm>uuid\|vmname</glossterm>
2423
2424	<glossdef>
2425	<para>The VM UUID or VM name. Mandatory.</para>
2426	</glossdef>
2427	</glossentry>
2428
2429	<glossentry>
2430	<glossterm>path to program</glossterm>
2431
2432	<glossdef>
2433	<para>Absolute path and process name of process to execute
2434	in the guest, e.g.
2435	<computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
2436	</glossdef>
2437	</glossentry>
2438
2439	<glossentry>
2440	<glossterm>--arguments "<arguments>"</glossterm>
2441
2442	<glossdef>
2443	<para>One or more arguments to pass to the process being
2444	executed.</para>
2445
2446	<para>Arguments containing spaces must be enclosed in
2447	quotation marks. More than one
2448	<computeroutput>--arguments</computeroutput> at a time can
2449	be specified to keep the command line tidy.</para>
2450	</glossdef>
2451	</glossentry>
2452
2453	<glossentry>
2454	<glossterm>--environment
2455	"<NAME>=<VALUE>"</glossterm>
2456
2457	<glossdef>
2458	<para>One or more environment variables to be set or
2459	unset.</para>
2460
2461	<para>By default, the new process in the guest will be
2462	created with the the standard environment of the guest OS.
2463	This option allows for modifying that environment. To
2464	set/modify a variable, a pair of
2465	<computeroutput>NAME=VALUE</computeroutput> must be
2466	specified; to unset a certain variable, the name with no
2467	value must set, e.g.
2468	<computeroutput>NAME=</computeroutput>.</para>
2469
2470	<para>Arguments containing spaces must be enclosed in
2471	quotation marks. More than one
2472	<computeroutput>--environment</computeroutput> at a time can
2473	be specified to keep the command line tidy.</para>
2474	</glossdef>
2475	</glossentry>
2476
2477	<glossentry>
2478	<glossterm>--flags <flags></glossterm>
2479
2480	<glossdef>
2481	<para>Additional flags to set. This is not used at the
2482	moment.</para>
2483	</glossdef>
2484	</glossentry>
2485
2486	<glossentry>
2487	<glossterm>--timeout <msec></glossterm>
2488
2489	<glossdef>
2490	<para>Value (in milliseconds) that specifies the time how
2491	long the started process is allowed to run and how long
2492	VBoxManage waits for getting output from that process. If no
2493	timeout is specified, VBoxManage will wait forever until the
2494	started process ends or an error occured.</para>
2495	</glossdef>
2496	</glossentry>
2497
2498	<glossentry>
2499	<glossterm>--username <name></glossterm>
2500
2501	<glossdef>
2502	<para>Name of the user the process should run under. This
2503	user must exist on the guest OS.</para>
2504	</glossdef>
2505	</glossentry>
2506
2507	<glossentry>
2508	<glossterm>--password <password></glossterm>
2509
2510	<glossdef>
2511	<para>Password of the user account specified with
2512	<computeroutput>--username</computeroutput>. If not given,
2513	an empty password is assumed.</para>
2514	</glossdef>
2515	</glossentry>
2516
2517	<glossentry>
2518	<glossterm>--verbose</glossterm>
2519
2520	<glossdef>
2521	<para>Tells VBoxManage to be more verbose during the
2522	execution.</para>
2523	</glossdef>
2524	</glossentry>
2525
2526	<glossentry>
2527	<glossterm>--wait-for <action></glossterm>
2528
2529	<glossdef>
2530	<para>Tells VBoxManage to wait for a certain action to
2531	happen and react to it. The following actions are available:
2532	<glosslist>
2533	<glossentry>
2534	<glossterm>exit</glossterm>
2535
2536	<glossdef>
2537	<para>Waits until the process ends and outputs its
2538	exit code along with the exit reason/flags.</para>
2539	</glossdef>
2540	</glossentry>
2541
2542	<glossentry>
2543	<glossterm>stdout or stderr</glossterm>
2544
2545	<glossdef>
2546	<para>Waits until the process ends and outputs its
2547	exit code along with the exit reason/flags. After
2548	that VBoxManage retrieves the output collected from
2549	the guest process's stdout and stderr.</para>
2550	</glossdef>
2551	</glossentry>
2552	</glosslist></para>
2553	</glossdef>
2554	</glossentry>
2555	</glosslist></para>
2556
2557	<para><note>
2558	<para>On Windows there are certain limitations for graphical
2559	applications; please see <xref linkend="KnownIssues" /> for more
2560	information.</para>
2561	</note> Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr"
2562	--username foo --password bar --wait-for stdout</screen> <screen>VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe"
2563	--username foo --password bar --wait-for stdout</screen> Note that
2564	the double backslashes in the second example are only required on
2565	Unix hosts.</para>
2566	</listitem>
2567
2568	<listitem>
2569	<para><computeroutput>copyto</computeroutput>, which allows copying
2570	files from the host to the guest (only with installed Guest
2571	Additions 4.0 and later).</para>
2572
2573	<screen>VBoxManage copyto <vmname>\|<uuid>
2574	<source on host> <destination on guest>
2575	[--username "<name>"] [--password "<password>"]
2576	[--dryrun] [--recursive] [--verbose] [--flags <flags>]</screen>
2577
2578	<para>where the parameters mean: <glosslist>
2579	<glossentry>
2580	<glossterm>uuid\|vmname</glossterm>
2581
2582	<glossdef>
2583	<para>The VM UUID or VM name. Mandatory.</para>
2584	</glossdef>
2585	</glossentry>
2586
2587	<glossentry>
2588	<glossterm>source on host</glossterm>
2589
2590	<glossdef>
2591	<para>Absolute path of source file(s) on host to copy over
2592	to the guest, e.g.
2593	<computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
2594	This also can be a wildcard expression, e.g.
2595	<computeroutput>C:\Windows\System32\*.dll</computeroutput></para>
2596	</glossdef>
2597	</glossentry>
2598
2599	<glossentry>
2600	<glossterm>destination on guest</glossterm>
2601
2602	<glossdef>
2603	<para>Absolute destination path on the guest, e.g.
2604	<computeroutput>C:\Temp</computeroutput></para>
2605	</glossdef>
2606	</glossentry>
2607
2608	<glossentry>
2609	<glossterm>--username <name></glossterm>
2610
2611	<glossdef>
2612	<para>Name of the user the copy process should run under.
2613	This user must exist on the guest OS.</para>
2614	</glossdef>
2615	</glossentry>
2616
2617	<glossentry>
2618	<glossterm>--password <password></glossterm>
2619
2620	<glossdef>
2621	<para>Password of the user account specified with
2622	<computeroutput>--username</computeroutput>. If not given,
2623	an empty password is assumed.</para>
2624	</glossdef>
2625	</glossentry>
2626
2627	<glossentry>
2628	<glossterm>--dryrun</glossterm>
2629
2630	<glossdef>
2631	<para>Tells VBoxManage to only perform a dry run instead of
2632	really copying files to the guest.</para>
2633	</glossdef>
2634	</glossentry>
2635
2636	<glossentry>
2637	<glossterm>--recursive</glossterm>
2638
2639	<glossdef>
2640	<para>Recursively copies files/directories.</para>
2641	</glossdef>
2642	</glossentry>
2643
2644	<glossentry>
2645	<glossterm>--verbose</glossterm>
2646
2647	<glossdef>
2648	<para>Tells VBoxManage to be more verbose during the copy
2649	operation.</para>
2650	</glossdef>
2651	</glossentry>
2652
2653	<glossentry>
2654	<glossterm>--flags <flags></glossterm>
2655
2656	<glossdef>
2657	<para>Additional flags to set. This is not used at the
2658	moment.</para>
2659	</glossdef>
2660	</glossentry>
2661	</glosslist></para>
2662	</listitem>
2663
2664	<listitem>
2665	<para><computeroutput>updateadditions</computeroutput>, which allows
2666	for updating an already installed Guest Additions version on the
2667	guest (only already installed Guest Additions 4.0 and later).</para>
2668
2669	<screen>VBoxManage guestcontrol updateadditions <vmname>\|<uuid>
2670	[--source "<guest additions .ISO file to use>"] [--verbose]</screen>
2671
2672	<para>where the parameters mean: <glosslist>
2673	<glossentry>
2674	<glossterm>uuid\|vmname</glossterm>
2675
2676	<glossdef>
2677	<para>The VM UUID or VM name. Mandatory.</para>
2678	</glossdef>
2679	</glossentry>
2680
2681	<glossentry>
2682	<glossterm>--source "<guest additions .ISO file to
2683	use>"</glossterm>
2684
2685	<glossdef>
2686	<para>Full path to an alternative VirtualBox Guest Additions
2687	.ISO file to use for the Guest Additions update.</para>
2688	</glossdef>
2689	</glossentry>
2690
2691	<glossentry>
2692	<glossterm>--verbose</glossterm>
2693
2694	<glossdef>
2695	<para>Tells VBoxManage to be more verbose during the
2696	update.</para>
2697	</glossdef>
2698	</glossentry>
2699	</glosslist></para>
2700	</listitem>
2701	</itemizedlist></para>
2702	</sect1>
2703
2704	<sect1 id="vboxmanage-dhcpserver">
2705	<title>VBoxManage dhcpserver</title>
2706
2707	<para>The "dhcpserver" commands allow you to control the DHCP server that
2708	is built into VirtualBox. You may find this useful when using internal or
2709	host-only networking. (Theoretically, you can enable it for a bridged
2710	network as well, but that will likely cause conflicts with other DHCP
2711	servers in your physical network.)</para>
2712
2713	<para>Use the following command line options:<itemizedlist>
2714	<listitem>
2715	<para>If you use internal networking for a virtual network adapter
2716	of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
2717	--netname <network_name></computeroutput>, where
2718	<computeroutput><network_name></computeroutput> is the same
2719	network name you used with <computeroutput>VBoxManage modifyvm
2720	<vmname> --intnet<X>
2721	<network_name></computeroutput>.</para>
2722	</listitem>
2723
2724	<listitem>
2725	<para>If you use host-only networking for a virtual network adapter
2726	of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
2727	--ifname <hostonly_if_name></computeroutput> instead, where
2728	<computeroutput><hostonly_if_name></computeroutput> is the
2729	same host-only interface name you used with
2730	<computeroutput>VBoxManage modifyvm <vmname>
2731	--hostonlyadapter<X>
2732	<hostonly_if_name></computeroutput>.</para>
2733
2734	<para>Alternatively, you can also use the --netname option as with
2735	internal networks if you know the host-only network's name; you can
2736	see the names with <computeroutput>VBoxManage list
2737	hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
2738	above).</para>
2739	</listitem>
2740	</itemizedlist></para>
2741
2742	<para>The following additional parameters are required when first adding a
2743	DHCP server:<itemizedlist>
2744	<listitem>
2745	<para>With <computeroutput>--ip</computeroutput>, specify the IP
2746	address of the DHCP server itself.</para>
2747	</listitem>
2748
2749	<listitem>
2750	<para>With <computeroutput>--netmask</computeroutput>, specify the
2751	netmask of the network.</para>
2752	</listitem>
2753
2754	<listitem>
2755	<para>With <computeroutput>--lowerip</computeroutput> and
2756	<computeroutput>--upperip</computeroutput>, you can specify the
2757	lowest and highest IP address, respectively, that the DHCP server
2758	will hand out to clients.</para>
2759	</listitem>
2760	</itemizedlist></para>
2761
2762	<para>Finally, you must specify <computeroutput>--enable</computeroutput>
2763	or the DHCP server will be created in the disabled state, doing
2764	nothing.</para>
2765
2766	<para>After this, VirtualBox will automatically start the DHCP server for
2767	given internal or host-only network as soon as the first virtual machine
2768	which uses that network is started.</para>
2769
2770	<para>Reversely, use <computeroutput>VBoxManage dhcpserver
2771	remove</computeroutput> with the given <computeroutput>--netname
2772	<network_name></computeroutput> or <computeroutput>--ifname
2773	<hostonly_if_name></computeroutput> to remove the DHCP server again
2774	for the given internal or host-only network.</para>
2775
2776	<para>To modify the settings of a DHCP server created earlier with
2777	<computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
2778	<computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
2779	network or host-only interface name.</para>
2780	</sect1>
2781	</chapter>

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: