user_VBoxManage.xml@ 56155

最後變更在這個檔案從56155是 56155,由 vboxsync 提交於 10 年前
VBoxManage doc hacking just started...
檔案大小: 203.7 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: