user_VBoxManage.xml@ 63679

Last change on this file since 63679 was 63679, checked in by vboxsync, 9 years ago
doc/manual: properly document the format of the device name for a physical parallel port on Linux and Windows (ticketref:15872)
File size: 265.9 KB

Line
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.virtualbox.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	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
20	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
21	<chapter id="vboxmanage">
22	<title>VBoxManage</title>
23
24	<sect1>
25	<title>Introduction</title>
26
27	<para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
28	the command-line interface to VirtualBox. With it, you can completely
29	control VirtualBox from the command line of your host operating system.
30	VBoxManage supports all the features that the graphical user interface
31	gives you access to, but it supports a lot more than that. It exposes
32	really all the features of the virtualization engine, even those that
33	cannot (yet) be accessed from the GUI.</para>
34
35	<para>You will need to use the command line if you want to</para>
36
37	<para><itemizedlist>
38	<listitem>
39	<para>use a different user interface than the main GUI (for example,
40	VBoxSDL or the VBoxHeadless server);</para>
41	</listitem>
42
43	<listitem>
44	<para>control some of the more advanced and experimental
45	configuration settings for a VM.</para>
46	</listitem>
47	</itemizedlist></para>
48
49	<para>There are two main things to keep in mind when using
50	<computeroutput>VBoxManage</computeroutput>: First,
51	<computeroutput>VBoxManage</computeroutput> must always be used with a
52	specific "subcommand", such as "list" or "createvm" or "startvm". All the
53	subcommands that <computeroutput>VBoxManage</computeroutput> supports are
54	described in detail in <xref linkend="vboxmanage" />.</para>
55
56	<para>Second, most of these subcommands require that you specify a
57	particular virtual machine after the subcommand. There are two ways you
58	can do this:</para>
59
60	<itemizedlist>
61	<listitem>
62	<para>You can specify the VM name, as it is shown in the VirtualBox
63	GUI. Note that if that name contains spaces, then you must enclose the
64	entire name in double quotes (as it is always required with command
65	line arguments that contain spaces).</para>
66
67	<para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
68	</listitem>
69
70	<listitem>
71	<para>You can specify the UUID, which is the internal unique
72	identifier that VirtualBox uses to refer to the virtual machine.
73	Assuming that the aforementioned VM called "Windows XP" has the UUID
74	shown below, the following command has the same effect as the
75	previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
76	</listitem>
77	</itemizedlist>
78
79	<para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
80	have all currently registered VMs listed with all their settings,
81	including their respective names and UUIDs.</para>
82
83	<para>Some typical examples of how to control VirtualBox from the command
84	line are listed below:</para>
85
86	<itemizedlist>
87	<listitem>
88	<para>To create a new virtual machine from the command line and
89	immediately register it with VirtualBox, use
90	<computeroutput>VBoxManage createvm</computeroutput> with the
91	<computeroutput>--register</computeroutput> option,<footnote>
92	<para>For details, see <xref
93	linkend="vboxmanage-createvm" />.</para>
94	</footnote> like this:</para>
95
96	<screen>$ VBoxManage createvm --name "SUSE 10.2" --register
97	VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
98	(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
99	All rights reserved.
100
101	Virtual machine 'SUSE 10.2' is created.
102	UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
103	Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen>
104
105	<para>As can be seen from the above output, a new virtual machine has
106	been created with a new UUID and a new XML settings file.</para>
107	</listitem>
108
109	<listitem>
110	<para>To show the configuration of a particular VM, use
111	<computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
112	linkend="vboxmanage-showvminfo" /> for details and an example.</para>
113	</listitem>
114
115	<listitem>
116	<para>To change settings while a VM is powered off, use
117	<computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
118	follows:<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen></para>
119
120	<para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
121	</listitem>
122
123	<listitem>
124	<para>To change the storage configuration (e.g. to add a storage
125	controller and then a virtual disk), use <computeroutput>VBoxManage
126	storagectl</computeroutput> and <computeroutput>VBoxManage
127	storageattach</computeroutput>; see <xref
128	linkend="vboxmanage-storagectl" /> and <xref
129	linkend="vboxmanage-storageattach" /> for details.</para>
130	</listitem>
131
132	<listitem>
133	<para>To control VM operation, use one of the following:<itemizedlist>
134	<listitem>
135	<para>To start a VM that is currently powered off, use
136	<computeroutput>VBoxManage startvm</computeroutput>; see <xref
137	linkend="vboxmanage-startvm" /> for details.</para>
138	</listitem>
139
140	<listitem>
141	<para>To pause or save a VM that is currently running or change
142	some of its settings, use <computeroutput>VBoxManage
143	controlvm</computeroutput>; see <xref
144	linkend="vboxmanage-controlvm" /> for details.</para>
145	</listitem>
146	</itemizedlist></para>
147	</listitem>
148	</itemizedlist>
149	</sect1>
150
151	<sect1>
152	<title>Commands overview</title>
153
154	<para>When running VBoxManage without parameters or when supplying an
155	invalid command line, the below syntax diagram will be shown. Note that
156	the output will be slightly different depending on the host platform; when
157	in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
158	for the commands available on your particular host.</para>
159
160	<xi:include href="../user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)"
161	xmlns:xi="http://www.w3.org/2001/XInclude" />
162
163	<para>Each time VBoxManage is invoked, only one command can be executed.
164	However, a command might support several subcommands which then can be
165	invoked in one single call. The following sections provide detailed
166	reference information on the different commands.</para>
167	</sect1>
168
169	<sect1 id="vboxmanage-general">
170	<title>General options</title>
171	<para>
172	<itemizedlist>
173	<listitem>
174	<para><computeroutput>-v\|--version</computeroutput>: show the version of
175	this tool and exit.</para>
176	</listitem>
177	<listitem>
178	<para><computeroutput>--nologo</computeroutput>: suppress the output
179	of the logo information (useful for scripts)</para>
180	</listitem>
181	<listitem>
182	<para><computeroutput>--settingspw</computeroutput>: specifiy a settings
183	password</para>
184	</listitem>
185	<listitem>
186	<para><computeroutput>--settingspwfile</computeroutput>: specify a file
187	containing the settings password.</para>
188	</listitem>
189	</itemizedlist>
190	The settings password is used for certain settings which need to be
191	stored encrypted for security reasons. At the moment, the only encrypted
192	setting is the iSCSI initiator secret (see
193	<xref linkend="vboxmanage-storageattach" /> for details). As long as no
194	settings password is specified, this information is stored in
195	<emphasis role="bold">plain text</emphasis>. After using the
196	<computeroutput>--settingspw\|--settingspwfile</computeroutput> option
197	once, it must be always used, otherwise the encrypted setting cannot
198	be unencrypted.
199	</para>
200	</sect1>
201
202	<sect1 id="vboxmanage-list">
203	<title>VBoxManage list</title>
204
205	<para>The <computeroutput>list</computeroutput> command gives relevant
206	information about your system and information about VirtualBox's current
207	settings.</para>
208
209	<para>The following subcommands are available with
210	<computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
211	<listitem>
212	<para><computeroutput>vms</computeroutput> lists all virtual
213	machines currently registered with VirtualBox. By default this
214	displays a compact list with each VM's name and UUID; if you also
215	specify <computeroutput>--long</computeroutput> or
216	<computeroutput>-l</computeroutput>, this will be a detailed list as
217	with the <computeroutput>showvminfo</computeroutput> command (see
218	below).</para>
219	</listitem>
220
221	<listitem>
222	<para><computeroutput>runningvms</computeroutput> lists all
223	currently running virtual machines by their unique identifiers
224	(UUIDs) in the same format as with
225	<computeroutput>vms</computeroutput>.</para>
226	</listitem>
227
228	<listitem>
229	<para><computeroutput>ostypes</computeroutput> lists all guest
230	operating systems presently known to VirtualBox, along with the
231	identifiers used to refer to them with the
232	<computeroutput>modifyvm</computeroutput> command.</para>
233	</listitem>
234
235	<listitem>
236	<para><computeroutput>hostdvds</computeroutput>,
237	<computeroutput>hostfloppies</computeroutput>, respectively, list
238	DVD, floppy, bridged networking and host-only networking interfaces
239	on the host, along with the name used to access them from within
240	VirtualBox.</para>
241	</listitem>
242
243	<listitem>
244	<para><computeroutput>intnets</computeroutput> displays information
245	about the internal networks.</para>
246	</listitem>
247
248	<listitem>
249	<para><computeroutput>bridgedifs</computeroutput>,
250	<computeroutput>hostonlyifs</computeroutput>,
251	<computeroutput>natnets</computeroutput> and
252	<computeroutput>dhcpservers</computeroutput>, respectively, list
253	bridged network interfaces, host-only network interfaces,
254	NAT network interfaces and DHCP servers currently available on the
255	host. Please see <xref
256	linkend="networkingdetails" /> for details on these.</para>
257	</listitem>
258
259	<listitem>
260	<para><computeroutput>hostinfo</computeroutput> displays information
261	about the host system, such as CPUs, memory size and operating
262	system version.</para>
263	</listitem>
264
265	<listitem>
266	<para><computeroutput>hostcpuids</computeroutput> dumps the CPUID
267	parameters for the host CPUs. This can be used for a more fine
268	grained analyis of the host's virtualization capabilities.</para>
269	</listitem>
270
271	<listitem>
272	<para><computeroutput>hddbackends</computeroutput> lists all known
273	virtual disk back-ends of VirtualBox. For each such format (such as
274	VDI, VMDK or RAW), this lists the back-end's capabilities and
275	configuration.</para>
276	</listitem>
277
278	<listitem>
279	<para><computeroutput>hdds</computeroutput>,
280	<computeroutput>dvds</computeroutput> and
281	<computeroutput>floppies</computeroutput> all give you information
282	about virtual disk images currently in use by VirtualBox, including
283	all their settings, the unique identifiers (UUIDs) associated with
284	them by VirtualBox and all files associated with them. This is the
285	command-line equivalent of the Virtual Media Manager; see <xref
286	linkend="vdis" />.</para>
287	</listitem>
288
289	<listitem>
290	<para><computeroutput>usbhost</computeroutput> supplies information
291	about USB devices attached to the host, notably information useful
292	for constructing USB filters and whether they are currently in use
293	by the host.</para>
294	</listitem>
295
296	<listitem>
297	<para><computeroutput>usbfilters</computeroutput> lists all global
298	USB filters registered with VirtualBox -- that is, filters for
299	devices which are accessible to all virtual machines -- and displays
300	the filter parameters.</para>
301	</listitem>
302
303	<listitem>
304	<para><computeroutput>systemproperties</computeroutput> displays
305	some global VirtualBox settings, such as minimum and maximum guest
306	RAM and virtual hard disk size, folder settings and the current
307	authentication library in use.</para>
308	</listitem>
309
310	<listitem>
311	<para><computeroutput>extpacks</computeroutput> displays all
312	VirtualBox extension packs currently installed; see <xref
313	linkend="intro-installing" /> and <xref
314	linkend="vboxmanage-extpack" /> for more information.</para>
315	</listitem>
316
317	<listitem>
318	<para><computeroutput>groups</computeroutput> displays
319	details of the VM Groups; see <xref linkend="gui-vmgroups" />
320	for more information.</para>
321	</listitem>
322
323	<listitem>
324	<para><computeroutput>webcams</computeroutput> displays a list of
325	webcams attached to the running VM. The output format is a list of
326	absolute paths or aliases that were used for attaching the webcams
327	to the VM using the 'webcam attach' command.</para>
328	</listitem>
329
330	<listitem>
331	<para><computeroutput>screenshotformats</computeroutput> displays a
332	list of available screenshot formats.</para>
333	</listitem>
334
335	</itemizedlist></para>
336	</sect1>
337
338	<sect1 id="vboxmanage-showvminfo">
339	<title>VBoxManage showvminfo</title>
340
341	<para>The <computeroutput>showvminfo</computeroutput> command shows
342	information about a particular virtual machine. This is the same
343	information as <computeroutput>VBoxManage list vms --long</computeroutput>
344	would show for all virtual machines.</para>
345
346	<para>You will get information that resembles the following example.</para>
347
348	<para><screen>$ VBoxManage showvminfo "Windows XP"
349	VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
350	(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
351	All rights reserved.
352
353	Name: Windows XP
354	Guest OS: Other/Unknown
355	UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
356	Config file: /home/username/.config/VirtualBox/Machines/Windows XP/Windows XP.xml
357	Memory size: 512MB
358	VRAM size: 12MB
359	Number of CPUs: 2
360	Boot menu mode: message and menu
361	Boot Device (1): DVD
362	Boot Device (2): HardDisk
363	Boot Device (3): Not Assigned
364	Boot Device (4): Not Assigned
365	ACPI: on
366	IOAPIC: on
367	...
368	</screen></para>
369	<para>Use the <computeroutput>--machinereadable</computeroutput> option
370	to produce the same output, but in machine readable format: property="value" on a
371	line by line basis, e.g.:</para>
372	<para><screen>
373	name="VBoxSDL --startvm OL7.2"
374	groups="/"
375	ostype="Oracle (64-bit)"
376	UUID="457af700-bc0a-4258-aa3c-13b03da171f2"
377	...
378	</screen></para>
379	</sect1>
380
381	<sect1 id="vboxmanage-registervm">
382	<title>VBoxManage registervm / unregistervm</title>
383
384	<para>The <computeroutput>registervm</computeroutput> command allows you
385	to import a virtual machine definition in an XML file into VirtualBox. The
386	machine must not conflict with one already registered in VirtualBox and it
387	may not have any hard or removable disks attached. It is advisable to
388	place the definition file in the machines folder before registering
389	it.<note>
390	<para>When creating a new virtual machine with
391	<computeroutput>VBoxManage createvm</computeroutput> (see below), you
392	can directly specify the <computeroutput>--register</computeroutput>
393	option to avoid having to register it separately.</para>
394	</note></para>
395
396	<para>The <computeroutput>unregistervm</computeroutput> command
397	unregisters a virtual machine. If
398	<computeroutput>--delete</computeroutput> is also specified, the following
399	files will automatically be deleted as well:<orderedlist>
400	<listitem>
401	<para>all hard disk image files, including differencing files, which
402	are used by the machine and not shared with other machines;</para>
403	</listitem>
404
405	<listitem>
406	<para>saved state files that the machine created, if any (one if the
407	machine was in "saved" state and one for each online
408	snapshot);</para>
409	</listitem>
410
411	<listitem>
412	<para>the machine XML file and its backups;</para>
413	</listitem>
414
415	<listitem>
416	<para>the machine log files, if any;</para>
417	</listitem>
418
419	<listitem>
420	<para>the machine directory, if it is empty after having deleted all
421	the above.</para>
422	</listitem>
423	</orderedlist></para>
424	</sect1>
425
426	<sect1 id="vboxmanage-createvm">
427	<title>VBoxManage createvm</title>
428
429	<para>This command creates a new XML virtual machine definition
430	file.</para>
431
432	<para>The <computeroutput>--name <name></computeroutput> parameter
433	is required and must specify the name of the machine. Since this name is
434	used by default as the file name of the settings file (with the extension
435	<computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
436	of the <computeroutput>.config/VirtualBox/Machines</computeroutput> folder
437	- this folder name may vary depending on the operating system and the
438	version of VirtualBox which you are using), it must conform to your host
439	operating system's requirements for file name specifications. If the VM
440	is later renamed, the file and folder names will change automatically.</para>
441
442	<para>However, if the <computeroutput>--basefolder
443	<path></computeroutput> option is used, the machine folder will be
444	named <computeroutput><path></computeroutput>. In this case, the
445	names of the file and the folder will not change if the virtual machine is
446	renamed.</para>
447
448	<para>If the <computeroutput>--group <group>, ...</computeroutput>
449	option is used, the machine will be assigned membership of the specified
450	VM groups in the list. Note that group ids always start with a
451	<computeroutput>/</computeroutput> and can be nested. By default,
452	VMs are always assigned membership of the group
453	<computeroutput>/</computeroutput>.</para>
454
455	<para>If the <computeroutput>--ostype <ostype></computeroutput>:
456	option is used, <ostype> specifies the guest operating system
457	to run in the VM. To learn about the available OS options,
458	run <computeroutput>VBoxManage list ostypes</computeroutput> .</para>
459
460	<para>If the <computeroutput>--uuid <uuid></computeroutput>:
461	option is used, <uuid> specifies the VM uuid. This must be
462	unique within the namespace of the host, or that of the VM Group if
463	it is assigned to a VM group membership. By default, a unique uuid
464	within the appropriate namespace is automatically generated.
465	</para>
466
467	<para>By default, this command only creates the XML file without
468	automatically registering the VM with your VirtualBox installation. To
469	register the VM instantly, use the optional
470	<computeroutput>--register</computeroutput> option, or run
471	<computeroutput>VBoxManage registervm</computeroutput> separately
472	afterwards.</para>
473
474	</sect1>
475
476	<sect1 id="vboxmanage-modifyvm">
477	<title>VBoxManage modifyvm</title>
478
479	<para>This command changes the properties of a registered virtual machine
480	which is not running. Most of the properties that this command makes
481	available correspond to the VM settings that VirtualBox graphical user
482	interface displays in each VM's "Settings" dialog; these were described in
483	<xref linkend="BasicConcepts" />. Some of the more advanced settings,
484	however, are only available through the
485	<computeroutput>VBoxManage</computeroutput> interface.</para>
486
487	<para>These commands require that the machine is powered off (neither
488	running nor in "saved" state). Some machine settings can also be changed
489	while a machine is running; those settings will then have a corresponding
490	subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
491	subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
492
493	<sect2>
494	<title>General settings</title>
495
496	<para>The following general settings are available through
497	<computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
498	<listitem>
499	<para><computeroutput>--name <name></computeroutput>: This
500	changes the VM's name and possibly renames the internal virtual
501	machine files, as described with <computeroutput>VBoxManage
502	createvm</computeroutput> above.</para>
503	</listitem>
504
505	<listitem>
506	<para><computeroutput>--groups <group>, ...</computeroutput>:
507	This changes the group membership of a VM. Groups always start with
508	a <computeroutput>/</computeroutput> and can be nested. By default
509	VMs are in group <computeroutput>/</computeroutput>.</para>
510	</listitem>
511
512	<listitem>
513	<para><computeroutput>--description <desc></computeroutput>:
514	This changes the VM's description, which is a way to record details
515	about the VM in a way which is meaningful for the user. The GUI
516	interprets HTML formatting, the command line allows arbitrary
517	strings potentially containing multiple lines.</para>
518	</listitem>
519
520	<listitem>
521	<para><computeroutput>--ostype <ostype></computeroutput>:
522	This specifies what guest operating system is supposed to run in
523	the VM. To learn about the various identifiers that can be used
524	here, use <computeroutput>VBoxManage list
525	ostypes</computeroutput>.</para>
526	</listitem>
527
528	<listitem>
529	<para><computeroutput>--iconfile <filename></computeroutput>:
530	This specifies the absolute path on the host file system for the VirtualBox
531	icon to be displayed in the VM.</para>
532	</listitem>
533
534	<listitem>
535	<para><computeroutput>--memory <memorysize></computeroutput>: This sets the amount of RAM,
536	in MB, that the virtual machine should allocate for itself from
537	the host. See the remarks in <xref linkend="gui-createvm" /> for
538	more information.</para>
539	</listitem>
540
541	<listitem>
542	<para><computeroutput>--pagefusion on\|off</computeroutput>:
543	Enables/disables (default) the Page Fusion feature.
544	The Page Fusion feature minimises memory duplication between VMs with similar
545	configurations running on the same host.
546	See <xref linkend="guestadd-pagefusion" /> for details.</para>
547	</listitem>
548
549	<listitem>
550	<para><computeroutput>--vram <vramsize></computeroutput>:
551	This sets the amount of RAM that the virtual graphics card should
552	have. See <xref linkend="settings-display" /> for details.</para>
553	</listitem>
554
555	<listitem>
556	<para><computeroutput>--acpi on\|off</computeroutput>;
557	<computeroutput>--ioapic on\|off</computeroutput>: These two
558	determine whether the VM should have ACPI and I/O APIC support,
559	respectively; see <xref linkend="settings-motherboard" /> for
560	details.</para>
561	</listitem>
562
563	<listitem>
564	<para><computeroutput>--pciattach <host PCI address [@ guest PCI bus address]></computeroutput>:
565	Attaches a specified PCI network controller on the host to a PCI bus (can specify) on the guest.
566	See <xref linkend="pcipassthrough" /> for details. </para>
567	</listitem>
568
569	<listitem>
570	<para><computeroutput>--pcidetach <host PCI address></computeroutput>:
571	Detaches a specified PCI network controller on the host from the attached PCI bus on the guest.
572	See <xref linkend="pcipassthrough" /> for details. </para>
573	</listitem>
574
575	<listitem>
576	<para><computeroutput>--hardwareuuid
577	<uuid></computeroutput>: The UUID presented to the guest via
578	memory tables (DMI/SMBIOS), hardware and guest properties. By
579	default this is the same as the VM uuid. Useful when cloning a VM.
580	Teleporting takes care of this automatically.</para>
581	</listitem>
582
583	<listitem>
584	<para><computeroutput>--cpus <cpucount></computeroutput>:
585	This sets the number of virtual CPUs for the virtual machine (see
586	<xref linkend="settings-processor" />). If CPU hot-plugging is
587	enabled (see below), this then sets the
588	<emphasis>maximum</emphasis> number of virtual CPUs that can be
589	plugged into the virtual machines.</para>
590	</listitem>
591
592	<listitem>
593	<para><computeroutput>--cpuhotplug on\|off</computeroutput>: This
594	enables CPU hot-plugging. When enabled, virtual CPUs can be added
595	to and removed from a virtual machine while it is running. See
596	<xref linkend="cpuhotplug" /> for more information.</para>
597	</listitem>
598
599	<listitem>
600	<para><computeroutput>--plugcpu\|unplugcpu
601	<id></computeroutput>: If CPU hot-plugging is enabled (see
602	above), this adds a virtual CPU to the virtual machines (or
603	removes one). <computeroutput><id></computeroutput>
604	specifies the index of the virtual CPU to be added or removed and
605	must be a number from 0 to the maximum no. of CPUs configured with
606	the <computeroutput>--cpus</computeroutput> option. CPU 0 can
607	never be removed.</para>
608	</listitem>
609
610	<listitem>
611	<para><computeroutput>--cpuexecutioncap
612	<1-100></computeroutput>: This setting controls how much cpu
613	time a virtual CPU can use. A value of 50 implies a single virtual
614	CPU can use up to 50% of a single host CPU.</para>
615	</listitem>
616
617	<listitem>
618	<para><computeroutput>--pae on\|off</computeroutput>: This
619	enables/disables PAE (see <xref
620	linkend="settings-processor" />).</para>
621	</listitem>
622
623	<listitem>
624	<para><computeroutput>--longmode on\|off</computeroutput>: This
625	enables/disables long mode (see <xref
626	linkend="settings-processor" />).</para>
627	</listitem>
628
629	<listitem>
630	<para><computeroutput>--cpu-profile <host\|intel 80[86\|286\|386]></computeroutput>:
631	Indicate the use of a profile for guest cpu emulation. Specify either one based
632	on the host system CPU (host), or one from a number of older Intel
633	Micro-architectures - 8086, 80286, 80386.</para>
634	</listitem>
635
636	<listitem>
637	<para><computeroutput>--hpet on\|off</computeroutput>: This
638	enables/disables a High Precision Event Timer (HPET) which can
639	replace the legacy system timers. This is turned off by default.
640	Note that Windows supports a HPET only from Vista onwards.</para>
641	</listitem>
642
643	<listitem>
644	<para><computeroutput>--hwvirtex on\|off</computeroutput>: This
645	enables or disables the use of hardware virtualization extensions
646	(Intel VT-x or AMD-V) in the processor of your host system; see
647	<xref linkend="hwvirt" />.</para>
648	</listitem>
649
650	<listitem>
651	<para><computeroutput>--triplefaultreset on\|off</computeroutput>:
652	This setting allows to reset the guest instead of triggering a
653	Guru Meditation. Some guests raise a triple fault to reset the
654	CPU so sometimes this is desired behavior. Works only for non-SMP
655	guests.</para>
656	</listitem>
657
658	<listitem>
659	<para><computeroutput>--apic on\|off</computeroutput>:
660	This setting enables(default)/disables IO APIC. With
661	I/O APIC, operating systems can use more than 16 interrupt
662	requests (IRQs) thus avoiding IRQ sharing for improved
663	reliability. See <xref linkend="settings-motherboard" />.</para>
664	</listitem>
665
666	<listitem>
667	<para><computeroutput>--x2apic on\|off</computeroutput>:
668	This setting enables(default)/disables CPU x2APIC support.
669	CPU x2APIC support helps operating systems run more efficiently on high
670	core count configurations, and optimizes interrupt
671	distribution in virtualized environments. Disable when using host/guest
672	operating systems incompatible with x2APIC support.</para>
673	</listitem>
674
675	<listitem>
676	<para><computeroutput>--paravirtprovider
677	none\|default\|legacy\|minimal\|hyperv\|kvm</computeroutput>: This
678	setting specifies which paravirtualization interface to provide to
679	the guest operating system. Specifying
680	<computeroutput>none</computeroutput> explicitly turns off exposing
681	any paravirtualization interface. The option
682	<computeroutput>default</computeroutput>, will pick an appropriate
683	interface depending on the guest OS type while starting the VM.
684	This is the default option chosen while creating new VMs. The
685	<computeroutput>legacy</computeroutput> option is chosen for VMs
686	which were created with older VirtualBox versions and will pick a
687	paravirtualization interface while starting the VM with VirtualBox
688	5.0 and newer. The <computeroutput>minimal</computeroutput> provider
689	is mandatory for Mac OS X guests, while
690	<computeroutput>kvm</computeroutput> and
691	<computeroutput>hyperv</computeroutput> are recommended for Linux
692	and Windows guests respectively. These options are explained in
693	detail under <xref linkend="gimproviders" />.</para>
694	</listitem>
695
696	<listitem>
697	<para><computeroutput>--paravirtdebug <key=value>
698	[,<key=value> ...]</computeroutput>: This setting specifies debugging
699	options specific to the paravirtualization provider
700	configured for this VM. Please refer to the provider specific
701	options under <xref linkend="gimdebug" /> for a list of supported
702	key-value pairs for each provider.</para>
703	</listitem>
704
705	<listitem>
706	<para><computeroutput>--nestedpaging on\|off</computeroutput>: If
707	hardware virtualization is enabled, this additional setting
708	enables or disables the use of the nested paging feature in the
709	processor of your host system; see <xref
710	linkend="hwvirt" />.</para>
711	</listitem>
712
713	<listitem>
714	<para><computeroutput>--largepages on\|off</computeroutput>: If
715	hardware virtualization <emphasis>and</emphasis> nested paging are
716	enabled, for Intel VT-x only, an additional performance
717	improvement of up to 5% can be obtained by enabling this setting.
718	This causes the hypervisor to use large pages to reduce TLB use
719	and overhead.</para>
720	</listitem>
721
722	<listitem>
723	<para><computeroutput>--vtxvpid on\|off</computeroutput>: If
724	hardware virtualization is enabled, for Intel VT-x only, this
725	additional setting enables or disables the use of the tagged TLB
726	(VPID) feature in the processor of your host system; see <xref
727	linkend="hwvirt" />.</para>
728	</listitem>
729
730	<listitem>
731	<para><computeroutput>--vtxux on\|off</computeroutput>: If
732	hardware virtualization is enabled, for Intel VT-x only, this
733	setting enables or disables the use of the unrestricted guest mode
734	feature for executing your guest.</para>
735	</listitem>
736
737	<listitem>
738	<para><computeroutput>--accelerate3d on\|off</computeroutput>: This
739	enables, if the Guest Additions are installed, whether hardware 3D
740	acceleration should be available; see <xref
741	linkend="guestadd-3d" />.</para>
742	</listitem>
743
744	<listitem>
745	<para><computeroutput>--accelerate2dvideo on\|off</computeroutput>:
746	This enables, if the Guest Additions are installed, whether 2D video
747	acceleration should be available; see <xref
748	linkend="guestadd-2d" />.</para>
749	</listitem>
750
751	<listitem>
752	<para><computeroutput>--chipset piix3\|ich9</computeroutput>:
753	By default VirtualBox emulates an Intel PIIX3 chipset. Usually there
754	is no reason to change the default setting unless it is required to
755	relax some of its constraints; see <xref
756	linkend="settings-motherboard" />.</para>
757	</listitem>
758
759	<listitem>
760	<para>You can influence the BIOS logo that is displayed when a
761	virtual machine starts up with a number of settings. Per default,
762	a VirtualBox logo is displayed.</para>
763
764	<para>With <computeroutput>--bioslogofadein
765	on\|off</computeroutput> and <computeroutput>--bioslogofadeout
766	on\|off</computeroutput>, you can determine whether the logo should
767	fade in and out, respectively.</para>
768
769	<para>With <computeroutput>--bioslogodisplaytime
770	<msec></computeroutput> you can set how long the logo should
771	be visible, in milliseconds.</para>
772
773	<para>With <computeroutput>--bioslogoimagepath
774	<imagepath></computeroutput> you can, if you are so
775	inclined, replace the image that is shown, with your own logo. The
776	image must be an uncompressed 256 color BMP file without color
777	space information (Windows 3.0 format). The image must not be
778	bigger than 640 x 480.</para>
779	</listitem>
780
781	<listitem>
782	<para><computeroutput>--biosbootmenu
783	disabled\|menuonly\|messageandmenu</computeroutput>: This specifies
784	whether the BIOS allows the user to select a temporary boot
785	device. <computeroutput>menuonly</computeroutput> suppresses the
786	message, but the user can still press F12 to select a temporary
787	boot device.</para>
788	</listitem>
789
790	<listitem>
791	<para><computeroutput>--biosapic
792	x2apic\|apic\|disabled</computeroutput>: This specifies
793	the firmware APIC level to be used. Options are: x2apic, apic or
794	disabled (no apic or x2apic) respectively.</para>
795
796	<para>Note that if x2apic is specified and x2apic is unsupported by the
797	VCPU, biosapic downgrades to apic, if supported - otherwise to 'disabled'.
798	Similarly, if apic is specified, and apic is unsupported results in a
799	downgrade to 'disabled'.</para>
800	</listitem>
801
802	<listitem>
803	<para><computeroutput>--biossystemtimeoffset <ms></computeroutput>:
804	This specifies a fixed time offset (milliseconds) of the guest relative to
805	the host time. If the offset is positive, the guest time runs ahead of the
806	host time.</para>
807	</listitem>
808
809	<listitem>
810	<para><computeroutput>--biospxedebug on\|off</computeroutput>:
811	This option enables additional debugging output when using the
812	Intel PXE boot ROM. The output will be written to the release log
813	file (<xref linkend="collect-debug-info" />.</para>
814	</listitem>
815
816	<listitem>
817	<para><computeroutput>--boot<1-4>
818	none\|floppy\|dvd\|disk\|net</computeroutput>: This specifies the boot
819	order for the virtual machine. There are four "slots", which the
820	VM will try to access from 1 to 4, and for each of which you can
821	set a device that the VM should attempt to boot from.</para>
822	</listitem>
823
824	<listitem>
825	<para><computeroutput>--rtcuseutc on\|off</computeroutput>: This
826	option lets the real-time clock (RTC) operate in UTC time (see
827	<xref linkend="settings-motherboard" />).</para>
828	</listitem>
829
830	<listitem>
831	<para><computeroutput>--graphicscontroller none\|vboxvga\|vmsvga</computeroutput>: This
832	option specifies use of a graphics controller, and type chosen from vboxvga or vmsvga.
833	<xref linkend="settings-motherboard" />).</para>
834	</listitem>
835
836	<listitem>
837	<para><computeroutput>--snapshotfolder
838	default\|<path></computeroutput>: This allows you to specify
839	the folder in which snapshots will be kept for a virtual
840	machine.</para>
841	</listitem>
842
843	<listitem>
844	<para><computeroutput>--firmware bios\|efi\|efi32\|efi64</computeroutput>:
845	Specifies which firmware to be used to boot the VM:
846	Available options are BIOS, or one of the EFI options: efi, efi32 or efi64.
847	Use EFI options with care.</para>
848	</listitem>
849
850	<listitem>
851	<para><computeroutput>--guestmemoryballoon
852	<size></computeroutput> sets the default size of the guest
853	memory balloon, that is, memory allocated by the VirtualBox Guest
854	Additions from the guest operating system and returned to the
855	hypervisor for re-use by other virtual machines.
856	<computeroutput><size></computeroutput> must be specified in
857	megabytes. The default size is 0 megabytes. For details,
858	see <xref linkend="guestadd-balloon" />.</para>
859	</listitem>
860
861	<listitem>
862	<para><computeroutput>--defaultfrontend
863	default\|<name></computeroutput>: This allows you to specify
864	the default frontend which will be used when starting this VM; see
865	<xref linkend="vboxmanage-startvm" /> for details.</para>
866	</listitem>
867	</itemizedlist></para>
868	</sect2>
869
870	<sect2>
871	<title>Networking settings</title>
872
873	<para>The following networking settings are available through
874	<computeroutput>VBoxManage modifyvm</computeroutput>. With all these
875	settings, the decimal number directly following the option name ("1-N"
876	in the list below) specifies the virtual network adapter whose settings
877	should be changed.<itemizedlist>
878	<listitem>
879	<para><computeroutput>--nic<1-N>
880	none\|null\|nat\|natnetwork\|bridged\|intnet\|hostonly\|generic</computeroutput>:
881	With this, you can set, for each of the VM's virtual network cards,
882	what type of networking should be available. They can be not
883	present (<computeroutput>none</computeroutput>), not connected to
884	the host (<computeroutput>null</computeroutput>), use network
885	address translation (<computeroutput>nat</computeroutput>),
886	use the new network address translation engine
887	(<computeroutput>natnetwork</computeroutput>),
888	bridged networking (<computeroutput>bridged</computeroutput>) or
889	communicate with other virtual machines using internal networking
890	(<computeroutput>intnet</computeroutput>), host-only networking
891	(<computeroutput>hostonly</computeroutput>), or access rarely used
892	sub-modes (<computeroutput>generic</computeroutput>).
893	These options correspond
894	to the modes which are described in detail in <xref
895	linkend="networkingmodes" />.</para>
896	</listitem>
897
898	<listitem>
899	<para><computeroutput>--nictype<1-N>
900	Am79C970A\|Am79C973\|82540EM\|82543GC\|82545EM\|virtio</computeroutput>:
901	This allows you, for each of the VM's virtual network cards, to
902	specify which networking hardware VirtualBox presents to the
903	guest; see <xref linkend="nichardware" />.</para>
904	</listitem>
905
906	<listitem>
907	<para><computeroutput>--cableconnected<1-N>
908	on\|off</computeroutput>: This allows you to temporarily disconnect
909	a virtual network interface, as if a network cable had been pulled
910	from a real network card. This might be useful for resetting
911	certain software components in the VM.</para>
912	</listitem>
913
914	<listitem>
915	<para>With the "nictrace" options, you can optionally trace
916	network traffic by dumping it to a file, for debugging
917	purposes.</para>
918
919	<para>With <computeroutput>--nictrace<1-N>
920	on\|off</computeroutput>, you can enable network tracing for a
921	particular virtual network card.</para>
922
923	<para>If enabled, you must specify with
924	<computeroutput>--nictracefile<1-N>
925	<filename></computeroutput> what file the trace should be
926	logged to.</para>
927	</listitem>
928
929	<listitem>
930	<para><computeroutput>--nicproperty<1-N>
931	<paramname>="paramvalue"</computeroutput>:
932	This option, in combination with "nicgenericdrv" allows you to
933	pass parameters to rarely-used network backends.</para>
934
935	<para>Those parameters are backend engine-specific, and are different
936	between UDP Tunnel and the VDE backend drivers. For example,
937	please see <xref linkend="network_udp_tunnel" />.
938	</para>
939	</listitem>
940
941	<listitem>
942	<para><computeroutput>--nicspeed<1-N> <kbps></computeroutput>:
943	If generic networking has been enabled for a virtual network card (see the
944	<computeroutput>--nic</computeroutput> option above; otherwise
945	this setting has no effect), this mode enables access
946	to rarely used networking sub-modes, such as VDE network or UDP Tunnel.
947	This option specifies the throughput rate in KBytes/sec.
948	</para>
949	</listitem>
950
951	<listitem>
952	<para><computeroutput>--nicbootprio<1-N>
953	<priority></computeroutput>: This specifies the order in which
954	NICs are tried for booting over the network (using PXE). The
955	priority is an integer in the 0 to 4 range. Priority 1 is the
956	highest, priority 4 is low. Priority 0, which is the default unless
957	otherwise specified, is the lowest.</para>
958
959	<para>Note that this option only has effect when the Intel PXE boot
960	ROM is used.</para>
961	</listitem>
962
963	<listitem>
964	<para><computeroutput>--nicpromisc<1-N>
965	deny\|allow-vms\|allow-all</computeroutput>:
966	This allows you, for each of the VM's virtual network cards, to
967	specify how the promiscuous mode is handled. This setting is only
968	relevant for bridged networking.
969	<computeroutput>deny</computeroutput> (default setting) hides
970	any traffic not intended for this VM.
971	<computeroutput>allow-vms</computeroutput> hides all host
972	traffic from this VM but allows the VM to see traffic from/to other
973	VMs.
974	<computeroutput>allow-all</computeroutput> removes this
975	restriction completely.</para>
976	</listitem>
977
978	<listitem>
979	<para><computeroutput>--nicbandwidthgroup<1-N>
980	none\|<name></computeroutput>: This removes/adds an assignment
981	of a bandwidth group from/to the specified virtual network interface.
982	Specifying <computeroutput>none</computeroutput> removes any current
983	bandwidth group assignment from the specified virtual network interface.
984	Specifying <computeroutput><name></computeroutput> adds an
985	assignment of a bandwidth group to the specified virtual network
986	interface.</para>
987	<para>For details, please see <xref linkend="network_bandwidth_limit" />.</para>
988	</listitem>
989
990	<listitem>
991	<para><computeroutput>--bridgeadapter<1-N>
992	none\|<devicename></computeroutput>: If bridged networking
993	has been enabled for a virtual network card (see the
994	<computeroutput>--nic</computeroutput> option above; otherwise
995	this setting has no effect), use this option to specify which host
996	interface the given virtual network interface will use. For
997	details, please see <xref linkend="network_bridged" />.</para>
998	</listitem>
999
1000	<listitem>
1001	<para><computeroutput>--hostonlyadapter<1-N>
1002	none\|<devicename></computeroutput>: If host-only networking
1003	has been enabled for a virtual network card (see the
1004	<computeroutput>--nic</computeroutput> option
1005	above; otherwise this setting has no effect), use this option to
1006	specify which host-only networking interface the given virtual
1007	network interface will use. For details, please see <xref
1008	linkend="network_hostonly" />.</para>
1009	</listitem>
1010
1011	<listitem>
1012	<para><computeroutput>--intnet<1-N>
1013	network</computeroutput>: If internal networking has been enabled
1014	for a virtual network card (see the
1015	<computeroutput>--nic</computeroutput> option above; otherwise
1016	this setting has no effect), use this option to specify the name
1017	of the internal network (see <xref
1018	linkend="network_internal" />).</para>
1019	</listitem>
1020
1021
1022	<listitem>
1023	<para><computeroutput>--nat-network<1-N> <network
1024	name></computeroutput>: If the networking type is set to
1025	<computeroutput>natnetwork</computeroutput> (not
1026	<computeroutput>nat</computeroutput>) then this setting specifies
1027	the name of the NAT network this adapter is connected to.</para>
1028	</listitem>
1029
1030	<listitem>
1031	<para><computeroutput>--nicgenericdrv<1-N>
1032	<backend driver></computeroutput>: If generic networking has been
1033	enabled for a virtual network card (see the
1034	<computeroutput>--nic</computeroutput> option above; otherwise
1035	this setting has no effect), this mode allows you to access
1036	rarely used networking sub-modes, such as VDE network or UDP Tunnel.
1037	</para>
1038	</listitem>
1039
1040	<listitem>
1041	<para><computeroutput>--macaddress<1-N>
1042	auto\|<mac></computeroutput>: With this option you can set
1043	the MAC address of a particular network adapter on the VM. Normally, each
1044	network adapter is assigned a random address by VirtualBox at
1045	VM creation.</para>
1046	</listitem>
1047	</itemizedlist></para>
1048
1049	<sect3>
1050	<title>NAT Networking settings.</title>
1051
1052	<para>The following NAT networking settings are available through
1053	<computeroutput>VBoxManage modifyvm</computeroutput>. With all these
1054	settings, the decimal number directly following the option name ("1-N"
1055	in the list below) specifies the virtual network adapter whose
1056	settings should be changed.<itemizedlist>
1057
1058	<listitem>
1059	<para><computeroutput>--natnet<1-N>
1060	<network>\|default</computeroutput>:
1061	If the networking type is set to <computeroutput>nat</computeroutput>
1062	(not <computeroutput>natnetwork</computeroutput>) then this
1063	setting specifies the IP address range to be used for
1064	this network. See <xref linkend="changenat" /> for an
1065	example.</para>
1066	</listitem>
1067
1068	<listitem>
1069	<para><computeroutput>--natpf<1-N>
1070	[<name>],tcp\|udp,[<hostip>],<hostport>,[<guestip>],
1071	<guestport></computeroutput>: This option defines a NAT
1072	port-forwarding rule (please see <xref linkend="natforward" />
1073	for details).</para>
1074	</listitem>
1075
1076	<listitem>
1077	<para><computeroutput>--natpf<1-N> delete
1078	<name></computeroutput>: This option deletes a NAT
1079	port-forwarding rule (please see <xref linkend="natforward" />
1080	for details).</para>
1081	</listitem>
1082
1083	<listitem>
1084	<para><computeroutput>--nattftpprefix<1-N>
1085	<prefix></computeroutput>: This option defines a prefix
1086	for the built-in TFTP server, i.e. where the boot file is
1087	located (please see <xref linkend="nat-tftp" /> and <xref
1088	linkend="nat-adv-tftp" /> for details).</para>
1089	</listitem>
1090
1091	<listitem>
1092	<para><computeroutput>--nattftpfile<1-N>
1093	<bootfile></computeroutput>: This option defines the TFT
1094	boot file (please see <xref linkend="nat-adv-tftp" /> for
1095	details).</para>
1096	</listitem>
1097
1098	<listitem>
1099	<para><computeroutput>--nattftpserver<1-N>
1100	<tftpserver></computeroutput>: This option defines the
1101	TFTP server address to boot from (please see <xref
1102	linkend="nat-adv-tftp" /> for details).</para>
1103	</listitem>
1104
1105	<listitem>
1106	<para><computeroutput>--nattbindip<1-N>
1107	<ip;></computeroutput>: VirtualBox's NAT engine normally routes
1108	TCP/IP packets through the default interface assigned by the host's
1109	TCP/IP stack. Use this option to instruct the NAT engine to bind
1110	to a specified IP address instead. (Please see <xref
1111	linkend="nat-adv-settings" /> for details).</para>
1112	</listitem>
1113
1114	<listitem>
1115	<para><computeroutput>--natdnspassdomain<1-N>
1116	on\|off</computeroutput>: This option specifies whether the
1117	built-in DHCP server passes the domain name for network name
1118	resolution.</para>
1119	</listitem>
1120
1121	<listitem>
1122	<para><computeroutput>--natdnsproxy<1-N>
1123	on\|off</computeroutput>: This option makes the NAT engine proxy
1124	all guest DNS requests to the host's DNS servers (please see
1125	<xref linkend="nat-adv-dns" /> for details).</para>
1126	</listitem>
1127
1128	<listitem>
1129	<para><computeroutput>--natdnshostresolver<1-N>
1130	on\|off</computeroutput>: This option makes the NAT engine use
1131	the host's resolver mechanisms to handle DNS requests (please
1132	see <xref linkend="nat-adv-dns" /> for details).</para>
1133	</listitem>
1134
1135	<listitem>
1136	<para><computeroutput>--natsettings<1-N>
1137	[<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
1138	[<tcprcv>]</computeroutput>: This option controls several
1139	NAT settings (please see <xref linkend="nat-adv-settings" /> for
1140	details).</para>
1141	</listitem>
1142
1143	<listitem>
1144	<para><computeroutput>--nataliasmode<1-N>
1145	default\|[log],[proxyonly],[sameports]</computeroutput>: This
1146	option defines behaviour of NAT engine core: log - enables
1147	logging, proxyonly - switches of aliasing mode makes NAT
1148	transparent, sameports enforces NAT engine to send packets via
1149	the same port as they originated on, default - disable all
1150	mentioned modes above . (please see <xref
1151	linkend="nat-adv-alias" /> for details).</para>
1152	</listitem>
1153	</itemizedlist></para>
1154	</sect3>
1155	</sect2>
1156
1157	<sect2 id="vboxmanage-modifyvm-other">
1158	<title>Miscellaneous settings</title>
1159
1160	<para>The following other hardware settings, such as serial port, audio,
1161	clipboard, drag and drop, monitor and USB settings are available through
1162	<computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
1163	<listitem>
1164	<para><computeroutput>--mouse <ps2\|usb\|usbtablet\|usbmultitouch></computeroutput>:
1165	Specifies the mode of the mouse to be used in the VM. Available options are: ps2, usb,
1166	usbtablet, usbmultitouch.
1167	</para>
1168	</listitem>
1169
1170	<listitem>
1171	<para><computeroutput>--keyboard <ps2\|usb></computeroutput>:
1172	Specifies the mode of the keyboard to be used in the VM. Available options are: ps2, usb.
1173	</para>
1174	</listitem>
1175	<listitem>
1176	<para><computeroutput>--uart<1-N> off\|<I/O base>
1177	<IRQ></computeroutput>: With this option you can configure
1178	virtual serial ports for the VM; see <xref
1179	linkend="serialports" /> for an introduction.</para>
1180	</listitem>
1181
1182	<listitem>
1183	<para><computeroutput>--uartmode<1-N>
1184	<arg></computeroutput>: This setting controls how VirtualBox
1185	connects a given virtual serial port (previously configured with
1186	the <computeroutput>--uartX</computeroutput> setting, see above)
1187	to the host on which the virtual machine is running. As described
1188	in detail in <xref linkend="serialports" />, for each such port,
1189	you can specify <computeroutput><arg></computeroutput> as
1190	one of the following options:<itemizedlist>
1191	<listitem>
1192	<para><computeroutput>disconnected</computeroutput>: Even
1193	though the serial port is shown to the guest, it has no
1194	"other end" -- like a real COM port without a cable.</para>
1195	</listitem>
1196
1197	<listitem>
1198	<para><computeroutput>server
1199	<pipename></computeroutput>: On a Windows host, this
1200	tells VirtualBox to create a named pipe on the host named
1201	<computeroutput><pipename></computeroutput> and
1202	connect the virtual serial device to it. Note that Windows
1203	requires that the name of a named pipe begin with
1204	<computeroutput>\\.\pipe\</computeroutput>.</para>
1205
1206	<para>On a Linux host, instead of a named pipe, a local
1207	domain socket is used.</para>
1208	</listitem>
1209
1210	<listitem>
1211	<para><computeroutput>client
1212	<pipename></computeroutput>: This operates just like
1213	<computeroutput>server ...</computeroutput>, except that the
1214	pipe (or local domain socket) is not created by VirtualBox,
1215	but assumed to exist already.</para>
1216	</listitem>
1217
1218	<listitem>
1219	<para><computeroutput>tcpserver
1220	<port></computeroutput>: This
1221	tells VirtualBox to create a TCP socket on the host with TCP
1222	<computeroutput><port></computeroutput> and
1223	connect the virtual serial device to it. Note that UNIX-like
1224	systems require ports over 1024 for normal users.</para>
1225	</listitem>
1226
1227	<listitem>
1228	<para><computeroutput>tcpclient
1229	<hostname:port></computeroutput>: This operates just like
1230	<computeroutput>tcpserver ...</computeroutput>, except that the
1231	TCP socket is not created by VirtualBox,
1232	but assumed to exist already.</para>
1233	</listitem>
1234
1235	<listitem>
1236	<para><computeroutput>file <file></computeroutput>:
1237	This redirects the serial port output to a raw file <file>
1238	specified by its absolute path on the host file system.</para>
1239	</listitem>
1240
1241	<listitem>
1242	<para><computeroutput><devicename></computeroutput>:
1243	If, instead of the above, the device name of a physical
1244	hardware serial port of the host is specified, the virtual
1245	serial port is connected to that hardware port. On a Windows
1246	host, the device name will be a COM port such as
1247	<computeroutput>COM1</computeroutput>; on a Linux host, the
1248	device name will look like
1249	<computeroutput>/dev/ttyS0</computeroutput>. This allows you
1250	to "wire" a real serial port to a virtual machine.</para>
1251	</listitem>
1252	</itemizedlist></para>
1253	</listitem>
1254
1255	<listitem>
1256	<para><computeroutput>--lptmode<1-N>
1257	<Device></computeroutput>:
1258	Specifies the Device Name of the parallel port that
1259	the Parallel Port feature will be using. Use this
1260	<emphasis>before</emphasis> <computeroutput>--lpt</computeroutput>.
1261	This feature is host operating system specific. For Windows hosts, use
1262	a device name like <emphasis>\\.\pipe\lpt1</emphasis> while on Linux
1263	hosts you have to use a device name like <emphasis>/dev/lp0</emphasis></para>
1264	</listitem>
1265
1266	<listitem>
1267	<para><computeroutput>--lpt<1-N>
1268	<I/O base> <IRQ></computeroutput>:
1269	Specifies the I/O address of the parallel port and the IRQ
1270	number that the Parallel Port feature will be using. Use this <emphasis>after</emphasis>
1271	<computeroutput>--lptmod</computeroutput>. I/O base address and IRQ are
1272	the values that guest sees i.e. the values avalable under guest Device Manager.</para>
1273	</listitem>
1274
1275	<listitem>
1276	<para><computeroutput>--audio none\|null\|oss\|alsa\|pulse</computeroutput>: With
1277	this option, you can set whether the VM should have audio
1278	support, and if so - which type.</para>
1279	</listitem>
1280
1281	<listitem>
1282	<para><computeroutput>--audiocontroller ac97\|hda\|sb16</computeroutput>: With
1283	this option, you can specify the audio controller to be used with this VM.
1284	</para>
1285	</listitem>
1286
1287	<listitem>
1288	<para><computeroutput>--audiocodec stac9700\|ad1980\|stac9221\|sb16</computeroutput>: With
1289	this option, you can specify the audio codec to be used with this VM.
1290	</para>
1291	</listitem>
1292
1293	<listitem>
1294	<para><computeroutput>--clipboard
1295	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
1296	With this setting, you can select if and how the guest or host
1297	operating system's clipboard should be shared with the host or guest;
1298	see <xref linkend="generalsettings" />. This requires that the Guest
1299	Additions be installed in the virtual machine.</para>
1300	</listitem>
1301
1302	<listitem>
1303	<para><computeroutput>--draganddrop
1304	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
1305	With this setting, you can select the current drag and drop mode
1306	being used between the host and the virtual machine;
1307	see <xref linkend="guestadd-dnd" />. This requires that the Guest
1308	Additions be installed in the virtual machine.</para>
1309	</listitem>
1310
1311	<listitem>
1312	<para><computeroutput>--monitorcount
1313	<count></computeroutput>: This enables multi-monitor
1314	support; see <xref linkend="settings-display" />.</para>
1315	</listitem>
1316
1317	<listitem>
1318	<para><computeroutput>--usb on\|off</computeroutput>: This option
1319	enables or disables the VM's virtual USB controller; see <xref
1320	linkend="settings-usb" /> for details.</para>
1321	</listitem>
1322
1323	<listitem>
1324	<para><computeroutput>--usbehci on\|off</computeroutput>: This
1325	option enables or disables the VM's virtual USB 2.0 controller;
1326	see <xref linkend="settings-usb" /> for details.</para>
1327	</listitem>
1328
1329	<listitem>
1330	<para><computeroutput>--usbxhci on\|off</computeroutput>: This
1331	option enables or disables the VM's virtual USB 3.0 controller;
1332	see <xref linkend="settings-usb" /> for details.</para>
1333	</listitem>
1334
1335	<listitem>
1336	<para><computeroutput>--usbrename
1337	<oldname> <newname></computeroutput>: This
1338	option enables renaming of the VM's virtual USB controller from <oldname>
1339	to <newname>.</para>
1340	</listitem>
1341	</itemizedlist></para>
1342
1343	</sect2>
1344
1345	<sect2 id="vboxmanage-modifyvm-videocap">
1346	<title>Video Capture settings</title>
1347
1348	<para>The following settings for changing video recording parameters are
1349	available through <computeroutput>VBoxManage modifyvm</computeroutput>.
1350	<itemizedlist>
1351	<listitem>
1352	<para><computeroutput>--videocap on\|off</computeroutput>:
1353	This option enables or disables recording a VM session into a WebM/VP8
1354	file. If this option is enabled, recording will start when the VM
1355	session is started.</para>
1356	</listitem>
1357	<listitem>
1358	<para><computeroutput>--videocapscreens all\|<screen ID>
1359	[<screen ID> ...]</computeroutput>: This option allows to specify which screens of
1360	the VM are being recorded. Each screen is recorded into a separate file.</para>
1361	</listitem>
1362	<listitem>
1363	<para><computeroutput>--videocapfile <filename></computeroutput>:
1364	This option sets the filename VirtualBox uses to save the recorded content.
1365	</para>
1366	</listitem>
1367	<listitem>
1368	<para><computeroutput>--videocapres <width>x<height></computeroutput>:
1369	This option sets the resolution (in pixels) of the recorded video.</para>
1370	</listitem>
1371	<listitem>
1372	<para><computeroutput>--videocaprate <rate></computeroutput>:
1373	This option sets the bitrate in kilobits (kb) per second. Increasing this
1374	value makes the video look better for the cost of an increased file size.</para>
1375	</listitem>
1376	<listitem>
1377	<para><computeroutput>--videocapfps <fps></computeroutput>:
1378	This option sets the maximum number of frames per second (FPS) to be
1379	recorded. Frames with a higher frequency will be skipped. Reducing this
1380	value increases the number of skipped frames and reduces the file size.</para>
1381	</listitem>
1382	<listitem>
1383	<para><computeroutput>--videocapmaxtime <ms></computeroutput>:
1384	This option sets the maximum time in milliseconds the video capturing
1385	will be enabled since activation. The capturing stops when the defined
1386	time interval has elapsed. If this value is zero the capturing is not
1387	limited by time.</para>
1388	</listitem>
1389	<listitem>
1390	<para><computeroutput>--videocapmaxsize <MB></computeroutput>:
1391	This option limits the maximum size of the captured video file (in MB).
1392	The capturing stops when the file size has reached the specified size. If
1393	this value is zero the capturing will not be limited by file size.</para>
1394	</listitem>
1395	<listitem>
1396	<para><computeroutput>--videocapopts <key=value>
1397	[,<key=value> ...]</computeroutput>:
1398	This format can be used to specify additional video capturing options.
1399	These options only are for advanced users and must be specified in a
1400	comma-separated key=value format, e.g.
1401	<computeroutput>foo=bar,a=b</computeroutput>.
1402	</para>
1403	</listitem>
1404	</itemizedlist></para>
1405
1406	</sect2>
1407
1408	<sect2 id="vboxmanage-modifyvm-vrde">
1409	<title>Remote machine settings</title>
1410
1411	<para>The following settings that affect remote machine behavior are
1412	available through <computeroutput>VBoxManage
1413	modifyvm</computeroutput>:<itemizedlist>
1414	<listitem>
1415	<para><computeroutput>--vrde on\|off</computeroutput>:
1416	This enables or disables the VirtualBox remote desktop extension
1417	(VRDE) server.</para>
1418	</listitem>
1419
1420	<listitem>
1421	<para><computeroutput>--vrdeproperty "TCP/Ports\|Address=<value>"</computeroutput>
1422	sets the port number(s) and IP address on the VM that the VRDE server can bind to.</para>
1423
1424	<itemizedlist>
1425	<listitem>
1426	<para>For TCP/Ports, <value> should be a port or a range of ports that the VRDE
1427	server can bind to; "default" or "0" means port 3389, the standard port for RDP.
1428	For details, see the description for the
1429	<computeroutput>--vrdeport</computeroutput> option in <xref
1430	linkend="vboxmanage-modifyvm-vrde" />.</para>
1431	</listitem>
1432
1433	<listitem>
1434	<para>For TCP/Address, <value> should be the IP address of the host network
1435	interface that the VRDE server will bind to. If specified, the server
1436	will accept connections only on the specified host network interface.
1437	For details, see the description for the
1438	<computeroutput>--vrdeaddress</computeroutput> option in <xref
1439	linkend="vboxmanage-modifyvm-vrde" />.</para>
1440	</listitem>
1441	</itemizedlist>
1442	</listitem>
1443
1444	<listitem>
1445	<para><computeroutput>--vrdeproperty "VideoChannel/Enabled\|Quality\|DownscaleProtection=<value>"</computeroutput>
1446	sets the VRDP video redirection properties.</para>
1447	<itemizedlist>
1448	<listitem>
1449	<para>For VideoChannel/Enabled, <value> can be set to "1" switching the VRDP video channel on.
1450	For details, see <xref linkend="vrde-videochannel" />.</para>
1451	</listitem>
1452
1453	<listitem>
1454	<para>For VideoChannel/Quality, <value> should be set between 10 and 100% inclusive,
1455	representing a JPEG compression level on the VRDE server video channel. Lower values mean lower
1456	quality but higher compression. For details, see <xref linkend="vrde-videochannel" />.</para>
1457	</listitem>
1458
1459	<listitem>
1460	<para>For VideoChannel/DownscaleProtection, <value> can be set to "1" to
1461	enable the videochannel downscale protection feature. When enabled, if a video's size equals the shadow buffer
1462	size, then it is regarded as a full screen video, and is displayed; but if its size is between fullscreen and the downscale
1463	threshold - it is NOT displayed, as it could be an application window, which would be unreadable when downscaled.
1464	When the downscale protection feature is disabled, an attempt is always made to display videos.</para>
1465	</listitem>
1466	</itemizedlist>
1467	</listitem>
1468
1469	<listitem>
1470	<para><computeroutput>--vrdeproperty "Client/DisableDisplay\|DisableInput\|DisableAudio\|DisableUSB=1"</computeroutput></para>
1471	<para>disables one of the VRDE server features: Display, Input, Audio or USB respectively.
1472	To re-enable a feature, use e.g. "Client/DisableDisplay=".
1473	For details, see <xref linkend="vrde-customization" />.</para>
1474	</listitem>
1475
1476	<listitem>
1477	<para><computeroutput>--vrdeproperty "Client/DisableClipboard\|DisableUpstreamAudio=1"</computeroutput></para>
1478	<para>disables one of the VRDE server features: Clipboard or UpstreamAudio respectively.
1479	To re-enable a feature, use e.g. "Client/DisableClipboard=".
1480	For details, see <xref linkend="vrde-customization" />.</para>
1481	</listitem>
1482
1483	<listitem>
1484	<para><computeroutput>--vrdeproperty "Client/DisableRDPDR=1"</computeroutput></para>
1485	<para>disables the VRDE server feature: RDP device redirection for smart cards.
1486	To re-enable this feature, use "Client/DisableRDPR=".</para>
1487	</listitem>
1488
1489	<listitem>
1490	<para><computeroutput>--vrdeproperty "H3DRedirect/Enabled=1"</computeroutput></para>
1491	<para>enables the VRDE server feature: 3D redirection.
1492	To re-disable this feature, use "H3DRedirect/Enabled=".</para>
1493	</listitem>
1494
1495	<listitem>
1496	<para><computeroutput>--vrdeproperty "Security/Method\|ServerCertificate\|ServerPrivateKey\|CACertificate=<value>"</computeroutput>
1497	sets the desired security method/Path of server certificate, path of server private key, path of CA certificate, used for a connection.
1498
1499	<itemizedlist>
1500	<listitem>
1501	<para><computeroutput>--vrdeproperty "Security/Method=<value>"</computeroutput>
1502	sets the desired security method, which is used for a connection. Valid values are:
1503	<itemizedlist>
1504	<listitem>
1505	<para> <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
1506	and Standard RDP Security connections are allowed. The security
1507	method is negotiated with the client. This is the default setting.</para>
1508	</listitem>
1509	<listitem>
1510	<para> <computeroutput>RDP</computeroutput> - only Standard RDP Security is accepted.</para>
1511	</listitem>
1512	<listitem>
1513	<para> <computeroutput>TLS</computeroutput> - only Enhanced RDP Security is accepted.
1514	The client must support TLS.</para>
1515	</listitem>
1516	</itemizedlist>
1517	For details, see <xref linkend="vrde-crypt" />.</para>
1518	</listitem>
1519
1520	<listitem>
1521	<para><computeroutput>--vrdeproperty "Security/ServerCertificate=<value>"</computeroutput>
1522	where <value> is the absolute path of the server certificate.
1523	For details, see <xref linkend="vrde-crypt" />.</para>
1524	</listitem>
1525
1526	<listitem>
1527	<para><computeroutput>--vrdeproperty "Security/ServerPrivateKey=<value>"</computeroutput>
1528	where <value> is the absolute path of the server private key.
1529	For details, see <xref linkend="vrde-crypt" />.</para>
1530	</listitem>
1531
1532	<listitem>
1533	<para><computeroutput>--vrdeproperty "Security/CACertificate=<value>"</computeroutput>
1534	where <value> is the absolute path of the CA self signed certificate.
1535	For details, see <xref linkend="vrde-crypt" />.</para>
1536	</listitem>
1537	</itemizedlist></para>
1538	</listitem>
1539
1540	<listitem>
1541	<para><computeroutput>--vrdeproperty "Audio/RateCorrectionMode\|LogPath=<value>"</computeroutput>
1542	sets the Audio connection mode, or Path of the audio logfile.
1543
1544	<itemizedlist>
1545	<listitem>
1546	<para><computeroutput>--vrdeproperty "Audio/RateCorrectionMode=<value>"</computeroutput>
1547	where <value> is the desired rate correction mode, allowed values are:
1548	<itemizedlist>
1549	<listitem>
1550	<para> <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput> - no mode specified, use to unset any Audio mode already set.</para>
1551	</listitem>
1552	<listitem>
1553	<para> <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput> - rate correction mode.</para>
1554	</listitem>
1555	<listitem>
1556	<para> <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput> - low pass filter mode.</para>
1557	</listitem>
1558	<listitem>
1559	<para> <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput> - client sync mode to prevent under/overflow of the client queue.</para>
1560	</listitem>
1561	</itemizedlist></para>
1562	</listitem>
1563	<listitem>
1564	<para><computeroutput>--vrdeproperty "Audio/LogPath=<value>"</computeroutput>
1565	where <value> is the absolute path of the Audio log file.</para>
1566	</listitem>
1567	</itemizedlist></para>
1568	</listitem>
1569
1570	<listitem>
1571	<para><computeroutput>--vrdeextpack default\|<name></computeroutput>:
1572	Allows to specify the library to use for to access the VM
1573	remotely. The default is to use the RDP code which is part of the
1574	Oracle VM VirtualBox Extension Pack.</para>
1575	</listitem>
1576
1577	<listitem>
1578	<para><computeroutput>--vrdeport
1579	default\|<ports></computeroutput>: A port or a range of ports
1580	the VRDE server can bind to; "default" or "0" means port 3389, the
1581	standard port for RDP. You can specify a comma-separated list of
1582	ports or ranges of ports. Use a dash between two port numbers to
1583	specify a range. The VRDE server will bind to <emphasis
1584	role="bold">one</emphasis> of available ports from the specified
1585	list. Only one machine can use a given port at a time. For
1586	example, the option <computeroutput> --vrdeport
1587	5000,5010-5012</computeroutput> will tell the server to bind to
1588	one of following ports: 5000, 5010, 5011 or 5012.</para>
1589	</listitem>
1590
1591	<listitem>
1592	<para><computeroutput>--vrdeaddress <IP
1593	address></computeroutput>: The IP address of the host network
1594	interface the VRDE server will bind to. If specified, the server
1595	will accept connections only on the specified host network
1596	interface.</para>
1597	<para>The setting can be used to specify whether the VRDP server
1598	should accept either IPv4 or IPv6 or both connections:
1599	<itemizedlist>
1600	<listitem>
1601	<para>only IPv4: <computeroutput>--vrdeaddress "0.0.0.0"
1602	</computeroutput></para>
1603	</listitem>
1604	<listitem>
1605	<para>only IPv6: <computeroutput>--vrdeaddress "::"
1606	</computeroutput></para>
1607	</listitem>
1608	<listitem>
1609	<para>both IPv6 and IPv4 (default): <computeroutput>--vrdeaddress ""
1610	</computeroutput></para>
1611	</listitem>
1612	</itemizedlist></para>
1613	</listitem>
1614
1615	<listitem>
1616	<para><computeroutput>--vrdeauthtype
1617	null\|external\|guest</computeroutput>: This allows you to choose
1618	whether and how authorization will be performed; see <xref
1619	linkend="vbox-auth" /> for details.</para>
1620	</listitem>
1621
1622	<listitem>
1623	<para><computeroutput>--vrdeauthlibrary
1624	default\|<name></computeroutput>: This allos to set the
1625	library used for RDP authentication, see <xref lang=""
1626	linkend="vbox-auth" /> for details.</para>
1627	</listitem>
1628
1629	<listitem>
1630	<para><computeroutput>--vrdemulticon on\|off</computeroutput>: This
1631	enables multiple connections to the same VRDE server, if the
1632	server supports this feature; see <xref lang=""
1633	linkend="vrde-multiconnection" />.</para>
1634	</listitem>
1635
1636	<listitem>
1637	<para><computeroutput>--vrdereusecon on\|off</computeroutput>: This
1638	specifies the VRDE server behavior when multiple connections are
1639	disabled. When this option is enabled, the server will allow a new
1640	client to connect and will drop the existing connection. When this
1641	option is disabled (this is the default setting), a new connection
1642	will not be accepted if there is already a client connected to the
1643	server.</para>
1644	</listitem>
1645
1646	<listitem>
1647	<para><computeroutput>--vrdevideochannel on\|off</computeroutput>:
1648	This enables video redirection, if it is supported by the VRDE
1649	server; see <xref lang="" linkend="vrde-videochannel" />.</para>
1650	</listitem>
1651
1652	<listitem>
1653	<para><computeroutput>--vrdevideochannelquality
1654	<percent></computeroutput>: Sets the image quality for video
1655	redirection; see <xref lang=""
1656	linkend="vrde-videochannel" />.</para>
1657	</listitem>
1658	</itemizedlist></para>
1659	</sect2>
1660
1661	<sect2 id="vboxmanage-modifyvm-teleport">
1662	<title>Teleporting settings</title>
1663
1664	<para>With the following commands for <computeroutput>VBoxManage
1665	modifyvm</computeroutput> you can configure a machine to be a target for
1666	teleporting. See <xref linkend="teleporting" /> for an
1667	introduction.<itemizedlist>
1668	<listitem>
1669	<para><computeroutput>--teleporter on\|off</computeroutput>: With
1670	this setting you turn on or off whether a machine waits for a
1671	teleporting request to come in on the network when it is started.
1672	If "on", when the machine is started, it does not boot the virtual
1673	machine as it would normally; instead, it then waits for a
1674	teleporting request to come in on the port and address listed with
1675	the next two parameters.</para>
1676	</listitem>
1677
1678	<listitem>
1679	<para><computeroutput>--teleporterport
1680	<port></computeroutput>, <computeroutput>--teleporteraddress
1681	<address></computeroutput>: these must be used with
1682	--teleporter and tell the virtual machine on which port and
1683	address it should listen for a teleporting request from another
1684	virtual machine. <computeroutput><port></computeroutput> can
1685	be any free TCP/IP port number (e.g. 6000);
1686	<computeroutput><address></computeroutput> can be any IP
1687	address or hostname and specifies the TCP/IP socket to bind to.
1688	The default is "0.0.0.0", which means any address.</para>
1689	</listitem>
1690
1691	<listitem>
1692	<para><computeroutput>--teleporterpassword
1693	<password></computeroutput>: if this optional argument is
1694	given, then the teleporting request will only succeed if the
1695	source machine specifies the same password as the one given with
1696	this command.</para>
1697	</listitem>
1698
1699	<listitem>
1700	<para><computeroutput>--teleporterpasswordfile
1701	<password></computeroutput>: if this optional argument is
1702	given, then the teleporting request will only succeed if the
1703	source machine specifies the same password as the one specified
1704	in the file give with this command. Use <computeroutput>stdin</computeroutput>
1705	to read the password from stdin.</para>
1706	</listitem>
1707
1708	<listitem>
1709	<para><computeroutput>--cpuid <leaf> <eax> <ebx>
1710	<ecx> <edx></computeroutput>: Advanced users can use
1711	this command before a teleporting operation to restrict the
1712	virtual CPU capabilities that VirtualBox presents to the guest
1713	operating system. This must be run on both the source and the
1714	target machines involved in the teleporting and will then modify
1715	what the guest sees when it executes the
1716	<computeroutput>CPUID</computeroutput> machine instruction. This
1717	might help with misbehaving applications that wrongly assume that
1718	certain CPU capabilities are present. The meaning of the
1719	parameters is hardware dependent; please refer to the AMD or Intel
1720	processor manuals.</para>
1721	</listitem>
1722	</itemizedlist></para>
1723	</sect2>
1724
1725	<sect2 id="vboxmanage-modifyvm-debugging">
1726	<title>Debugging settings</title>
1727
1728	<para>The following settings are only relevant for low-level VM
1729	debugging. Regular users will never need these settings.<itemizedlist>
1730	<listitem>
1731	<para><computeroutput>--tracing-enabled on\|off</computeroutput>:
1732	Enable the tracebuffer. This consumes some memory for the tracebuffer
1733	and adds extra overhead.</para>
1734	</listitem>
1735	<listitem>
1736	<para><computeroutput>--tracing-config <config-string></computeroutput>:
1737	Allows to configure tracing. In particular this defines which group of
1738	tracepoints are enabled.</para>
1739	</listitem>
1740	<listitem>
1741	<para><computeroutput>--tracing-allow-vm-access on\|off</computeroutput>:
1742	Enables/disables(default) VM access to the tracebuffer.</para>
1743	</listitem>
1744	</itemizedlist>
1745	</para>
1746	</sect2>
1747
1748	<sect2 id="vboxmanage-usbcardreader">
1749	<title>USB card reader settings</title>
1750
1751	<para>The following setting defines access to a USB Card Reader by the guest environment.
1752	USB card readers are typically used for accessing data on memory cards such as
1753	CompactFlash (CF), Secure Digital (SD) or MultiMediaCard (MMC).</para>
1754	<itemizedlist>
1755	<listitem>
1756	<para><computeroutput>--usbcardreader on\|off</computeroutput>:
1757	Enables/disables the USB card reader interface.</para>
1758	</listitem>
1759	</itemizedlist>
1760	</sect2>
1761
1762	<sect2 id="vboxmanage-autostart">
1763	<title>Auto starting VMs during host system boot</title>
1764
1765	<para>These settings configure the VM autostart feature,
1766	which automatically starts the VM at host system boot-up.
1767	Note that there are pre-requisites that need to be addressed before using this feature.
1768	See <xref lang="" linkend="autostart" /> for more details.</para>
1769	<itemizedlist>
1770	<listitem>
1771	<para><computeroutput>--autostart on\|off</computeroutput>:
1772	Enables/disables VM autostart at host system boot-up, using specified user name.</para>
1773	</listitem>
1774	<listitem>
1775	<para><computeroutput>--autostart-delay <seconds></computeroutput>:
1776	Specifies a delay (seconds) following host system boot-up, before VM autostarts.</para>
1777	</listitem>
1778	</itemizedlist>
1779	</sect2>
1780	</sect1>
1781
1782	<sect1 id="vboxmanage-clonevm">
1783	<title>VBoxManage clonevm</title>
1784
1785	<para>This command creates a full or linked copy of an existing virtual
1786	machine.</para>
1787
1788	<para>The <computeroutput>clonevm</computeroutput> subcommand takes at
1789	least the name of the virtual machine which should be cloned. The following
1790	additional settings can be used to further configure the clone VM
1791	operation:</para>
1792
1793	<itemizedlist>
1794	<listitem>
1795	<para><computeroutput>--snapshot <uuid>\|<name></computeroutput>:
1796	Select a specific snapshot where the clone operation should refer
1797	to. Default is referring to the current state.</para>
1798	</listitem>
1799	<listitem>
1800	<para><computeroutput>--mode machine\|machineandchildren\|all</computeroutput>:
1801	Selects the cloning mode of the operation. If
1802	<computeroutput>machine</computeroutput> is selected (the default),
1803	the current state of the VM without any snapshots is cloned. In the
1804	<computeroutput>machineandchildren</computeroutput> mode the snapshot
1805	provided by <computeroutput>--snapshot</computeroutput> and all
1806	child snapshots are cloned. If <computeroutput>all</computeroutput>
1807	is the selected mode all snapshots and the current state are cloned.
1808	</para>
1809	</listitem>
1810	<listitem>
1811	<para><computeroutput>--options link\|keepallmacs\|keepnatmacs\|keepdisknames</computeroutput>:
1812	Allows additional fine tuning of the clone operation. The first
1813	option defines that a linked clone should be created, which is
1814	only possible for a machine clone from a snapshot. The next two
1815	options allow to define how the MAC addresses of every virtual
1816	network card should be handled. They can either be reinitialized
1817	(the default), left unchanged
1818	(<computeroutput>keepallmacs</computeroutput>) or left unchanged
1819	when the network type is NAT
1820	(<computeroutput>keepnatmacs</computeroutput>). If you add
1821	<computeroutput>keepdisknames</computeroutput> all new disk images
1822	are called like the original ones, otherwise they are
1823	renamed.</para>
1824	</listitem>
1825	<listitem>
1826	<para><computeroutput>--name <name></computeroutput>: Select a
1827	new name for the new virtual machine. Default is "Original Name
1828	Clone".</para>
1829	</listitem>
1830	<listitem>
1831	<para><computeroutput>--groups <group>, ...</computeroutput>
1832	Enables the clone to be assigned membership of the specified
1833	VM groups in the list. Note that group ids always start with a
1834	<computeroutput>/</computeroutput> and can be nested. By default,
1835	clones are always assigned membership of the group
1836	<computeroutput>/</computeroutput>.</para>
1837	</listitem>
1838	<listitem>
1839	<para><computeroutput>--basefolder <basefolder></computeroutput>:
1840	Select the folder where the new virtual machine configuration should
1841	be saved in.</para>
1842	</listitem>
1843	<listitem>
1844	<para><computeroutput>--uuid <uuid></computeroutput>:
1845	Select the UUID the new VM should have. This id has to be unique in
1846	the VirtualBox instance this clone should be registered. Default is
1847	creating a new UUID.</para>
1848	</listitem>
1849	<listitem>
1850	<para><computeroutput>--register</computeroutput>:
1851	Automatically register the new clone in this VirtualBox
1852	installation. If you manually want to register the new VM later, see
1853	<xref linkend="vboxmanage-registervm" /> for instructions how to do
1854	so.</para>
1855	</listitem>
1856	</itemizedlist>
1857	</sect1>
1858
1859	<sect1 id="vboxmanage-import">
1860	<title>VBoxManage import</title>
1861
1862	<para>This command imports a virtual appliance in OVF format by copying
1863	the virtual disk images and creating virtual machines in VirtualBox. See
1864	<xref linkend="ovf" /> for an introduction to appliances.</para>
1865
1866	<para>The <computeroutput>import</computeroutput> subcommand takes at
1867	least the path name of an OVF file as input and expects the disk images,
1868	if needed, in the same directory as the OVF file. A lot of additional
1869	command-line options are supported to control in detail what is being
1870	imported and modify the import parameters, but the details depend on the
1871	content of the OVF file.</para>
1872
1873	<para>It is therefore recommended to first run the import subcommand with
1874	the <computeroutput>--dry-run</computeroutput> or
1875	<computeroutput>-n</computeroutput> option. This will then print a
1876	description of the appliance's contents to the screen how it would be
1877	imported into VirtualBox, together with the optional command-line options
1878	to influence the import behavior.</para>
1879
1880	<para>Use of the <computeroutput>--options link\|keepallmacs\|keepnatmacs\|keepdisknames</computeroutput>:
1881	option enables additional fine tuning of the clone operation. The first
1882	option defines that a linked clone should be created, which is
1883	only possible for a machine clone from a snapshot. The next two
1884	options enable specification of how the MAC addresses of every virtual
1885	network card should be handled. They can either be reinitialized
1886	(the default), left unchanged
1887	(<computeroutput>keepallmacs</computeroutput>) or left unchanged
1888	when the network type is NAT
1889	(<computeroutput>keepnatmacs</computeroutput>). If you add
1890	<computeroutput>keepdisknames</computeroutput> all new disk images
1891	are assigned the same names as the originals, otherwise they are
1892	renamed.</para>
1893
1894	<para>As an example, here is the screen output with a sample appliance
1895	containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
1896	Interpreting WindowsXp.ovf...
1897	OK.
1898	Virtual system 0:
1899	0: Suggested OS type: "WindowsXP"
1900	(change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
1901	1: Suggested VM name "Windows XP Professional_1"
1902	(change with "--vsys 0 --vmname <name>")
1903	3: Number of CPUs: 1
1904	(change with "--vsys 0 --cpus <n>")
1905	4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
1906	5: Sound card (appliance expects "ensoniq1371", can change on import)
1907	(disable with "--vsys 0 --unit 5 --ignore")
1908	6: USB controller
1909	(disable with "--vsys 0 --unit 6 --ignore")
1910	7: Network adapter: orig bridged, config 2, extra type=bridged
1911	8: Floppy
1912	(disable with "--vsys 0 --unit 8 --ignore")
1913	9: SCSI controller, type BusLogic
1914	(change with "--vsys 0 --unit 9 --scsitype {BusLogic\|LsiLogic}";
1915	disable with "--vsys 0 --unit 9 --ignore")
1916	10: IDE controller, type PIIX4
1917	(disable with "--vsys 0 --unit 10 --ignore")
1918	11: Hard disk image: source image=WindowsXp.vmdk,
1919	target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
1920	(change controller with "--vsys 0 --unit 11 --controller <id>";
1921	disable with "--vsys 0 --unit 11 --ignore")</screen></para>
1922
1923	<para>As you can see, the individual configuration items are numbered, and
1924	depending on their type support different command-line options. The import
1925	subcommand can be directed to ignore many such items with a
1926	<computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
1927	X is the number of the virtual system (zero unless there are several
1928	virtual system descriptions in the appliance) and Y the item number, as
1929	printed on the screen.</para>
1930
1931	<para>In the above example, Item #1 specifies the name of the target
1932	machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
1933	respectively. Item #11 describes a hard disk image; in this case, the
1934	additional <computeroutput>--controller</computeroutput> option indicates
1935	which item the disk image should be connected to, with the default coming
1936	from the OVF file.</para>
1937
1938	<para>You can combine several items for the same virtual system behind the
1939	same <computeroutput>--vsys</computeroutput> option. For example, to
1940	import a machine as described in the OVF, but without the sound card and
1941	without the USB controller, and with the disk image connected to the IDE
1942	controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
1943	--vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
1944	</sect1>
1945
1946	<sect1 id="vboxmanage-export">
1947	<title>VBoxManage export</title>
1948
1949	<para>This command exports one or more virtual machines from VirtualBox
1950	into a virtual appliance in OVF format, including copying their virtual
1951	disk images to compressed VMDK. See <xref linkend="ovf" /> for an
1952	introduction to appliances.</para>
1953
1954	<para>The <computeroutput>export</computeroutput> command is simple to
1955	use: list the machine (or the machines) that you would like to export to
1956	the same OVF file and specify the target OVF file after an additional
1957	<computeroutput>--output</computeroutput> or
1958	<computeroutput>-o</computeroutput> option. Note that the directory of the
1959	target OVF file will also receive the exported disk images in the
1960	compressed VMDK format (regardless of the original format) and should have
1961	enough disk space left for them.</para>
1962
1963	<para>Beside a simple export of a given virtual machine, you can append
1964	several product information to the appliance file. Use
1965	<computeroutput>--product</computeroutput>,
1966	<computeroutput>--producturl</computeroutput>,
1967	<computeroutput>--vendor</computeroutput>,
1968	<computeroutput>--vendorurl</computeroutput>,
1969	<computeroutput>--version</computeroutput> and
1970	<computeroutput>--description</computeroutput> to specify this additional
1971	information. For legal reasons you may add a license text or the content
1972	of a license file by using the <computeroutput>--eula</computeroutput> and
1973	<computeroutput>--eulafile</computeroutput> option respectively. As with
1974	OVF import, you must use the <computeroutput>--vsys X</computeroutput>
1975	option to direct the previously mentioned options to the correct virtual
1976	machine.</para>
1977
1978	<para>For virtualization products which aren't fully compatible with the
1979	OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
1980	<computeroutput>--legacy09</computeroutput> option. Other options are
1981	--ovf09, --ovf10, --ovf20.</para>
1982
1983	<para>To specify options controlling the exact content of the appliance
1984	file, you can use <computeroutput>--options</computeroutput> to request the
1985	creation of a manifest file (encouraged, allows detection of corrupted
1986	appliances on import), the additional export of DVD images, and the
1987	exclusion of MAC addresses. You can specify a list of options, e.g.
1988	<computeroutput>--options manifest,nomacs</computeroutput>. For details,
1989	check the help output of <computeroutput>VBoxManage export</computeroutput>.</para>
1990	</sect1>
1991
1992	<sect1 id="vboxmanage-startvm">
1993	<title>VBoxManage startvm</title>
1994
1995	<para>This command starts a virtual machine that is currently in the
1996	"Powered off" or "Saved" states.</para>
1997
1998	<para>The optional <computeroutput>--type</computeroutput> specifier
1999	determines whether the machine will be started in a window or whether the
2000	output should go through <computeroutput>VBoxHeadless</computeroutput>,
2001	with VRDE enabled or not; see <xref linkend="vboxheadless" /> for more
2002	information. The list of types is subject to change, and it's not
2003	guaranteed that all types are accepted by any product variant.</para>
2004
2005	<para>The global or per-VM default value for the VM frontend type will be
2006	taken if the type is not explicitly specified. If none of these are set,
2007	the GUI variant will be started.</para>
2008
2009	<para>The following values are allowed:</para>
2010
2011	<glosslist>
2012	<glossentry>
2013	<glossterm><computeroutput>gui</computeroutput></glossterm>
2014
2015	<glossdef>
2016	<para>Starts a VM showing a GUI window. This is the default.</para>
2017	</glossdef>
2018	</glossentry>
2019
2020	<glossentry>
2021	<glossterm><computeroutput>headless</computeroutput></glossterm>
2022
2023	<glossdef>
2024	<para>Starts a VM without a window for remote display only.</para>
2025	</glossdef>
2026	</glossentry>
2027
2028	<glossentry>
2029	<glossterm><computeroutput>sdl</computeroutput></glossterm>
2030
2031	<glossdef>
2032	<para>Starts a VM with a minimal GUI and limited features.</para>
2033	</glossdef>
2034	</glossentry>
2035
2036	<glossentry>
2037	<glossterm><computeroutput>separate</computeroutput></glossterm>
2038
2039	<glossdef>
2040	<para>Starts a VM with detachable UI (technically it is a headless VM
2041	with user interface in a separate process). This is an experimental
2042	feature as it lacks certain functionality at the moment (e.g. 3D
2043	acceleration will not work).</para>
2044	</glossdef>
2045	</glossentry>
2046	</glosslist>
2047
2048	<note>
2049	<para>If you experience problems with starting virtual machines with
2050	particular frontends and there is no conclusive error information,
2051	consider starting virtual machines directly by running the respective
2052	front-end, as this can give additional error information.</para>
2053	</note>
2054	</sect1>
2055
2056	<sect1 id="vboxmanage-controlvm">
2057	<title>VBoxManage controlvm</title>
2058
2059	<para>The <computeroutput>controlvm</computeroutput> subcommand allows you
2060	to change the state of a virtual machine that is currently running. The
2061	following can be specified:</para>
2062
2063	<para><itemizedlist>
2064	<listitem>
2065	<para><computeroutput>VBoxManage controlvm <vm>
2066	pause</computeroutput> temporarily puts a virtual machine on hold,
2067	without changing its state for good. The VM window will be painted
2068	in gray to indicate that the VM is currently paused. (This is
2069	equivalent to selecting the "Pause" item in the "Machine" menu of
2070	the GUI).</para>
2071	</listitem>
2072
2073	<listitem>
2074	<para>Use <computeroutput>VBoxManage controlvm <vm>
2075	resume</computeroutput> to undo a previous
2076	<computeroutput>pause</computeroutput> command. (This is equivalent
2077	to selecting the "Resume" item in the "Machine" menu of the
2078	GUI.)</para>
2079	</listitem>
2080
2081	<listitem>
2082	<para><computeroutput>VBoxManage controlvm <vm>
2083	reset</computeroutput> has the same effect on a virtual machine as
2084	pressing the "Reset" button on a real computer: a cold reboot of the
2085	virtual machine, which will restart and boot the guest operating
2086	system again immediately. The state of the VM is not saved
2087	beforehand, and data may be lost. (This is equivalent to selecting
2088	the "Reset" item in the "Machine" menu of the GUI).</para>
2089	</listitem>
2090
2091	<listitem>
2092	<para><computeroutput>VBoxManage controlvm <vm>
2093	poweroff</computeroutput> has the same effect on a virtual machine
2094	as pulling the power cable on a real computer. Again, the state of
2095	the VM is not saved beforehand, and data may be lost. (This is
2096	equivalent to selecting the "Close" item in the "Machine" menu of
2097	the GUI or pressing the window's close button, and then selecting
2098	"Power off the machine" in the dialog).</para>
2099
2100	<para>After this, the VM's state will be "Powered off". From there,
2101	it can be started again; see <xref
2102	linkend="vboxmanage-startvm" />.</para>
2103	</listitem>
2104
2105	<listitem>
2106	<para><computeroutput>VBoxManage controlvm <vm>
2107	savestate</computeroutput> will save the current state of the VM to
2108	disk and then stop the VM. (This is equivalent to selecting the
2109	"Close" item in the "Machine" menu of the GUI or pressing the
2110	window's close button, and then selecting "Save the machine state"
2111	in the dialog.)</para>
2112
2113	<para>After this, the VM's state will be "Saved". From there, it can
2114	be started again; see <xref linkend="vboxmanage-startvm" />.</para>
2115	</listitem>
2116
2117	<listitem>
2118	<para><computeroutput>VBoxManage controlvm <vm>
2119	acpipowerbutton</computeroutput> will send an ACPI shutdown signal to
2120	the VM, as if the power button on a real computer had been pressed.
2121	So long as the VM is running a fairly modern guest operating system
2122	providing ACPI support, this should trigger a proper shutdown mechanism
2123	from within the VM.</para>
2124	</listitem>
2125
2126	<listitem>
2127	<para><computeroutput>VBoxManage controlvm <vm>
2128	keyboardputscancode <hex> [<hex>...]</computeroutput>
2129	Sends commands using keycodes to the VM. Keycodes are documented in the
2130	public domain, e.g. http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.</para>
2131	</listitem>
2132
2133	<listitem>
2134	<para><computeroutput>VBoxManage controlvm "VM name" teleport
2135	--hostname <name> --port <port> [--passwordfile
2136	<file> \| --password <password>]</computeroutput> makes
2137	the machine the source of a teleporting operation and initiates a
2138	teleport to the given target. See <xref linkend="teleporting" /> for
2139	an introduction. If the optional password is specified, it must match
2140	the password that was given to the
2141	<computeroutput>modifyvm</computeroutput> command for the target
2142	machine; see <xref linkend="vboxmanage-modifyvm-teleport" /> for
2143	details.</para>
2144	</listitem>
2145	</itemizedlist></para>
2146
2147	<para>A few extra options are available with
2148	<computeroutput>controlvm</computeroutput> that do not directly affect the
2149	VM's running state:</para>
2150
2151	<itemizedlist>
2152	<listitem>
2153	<para>The <computeroutput>setlinkstate<1-N></computeroutput>
2154	operation connects or disconnects virtual network cables from their
2155	network interfaces.</para>
2156	</listitem>
2157
2158	<listitem>
2159	<para><computeroutput>nic<1-N>
2160	null\|nat\|bridged\|intnet\|hostonly\|generic\|natnetwork[<devicename>]</computeroutput>: With this, you can
2161	set, for each of the VM's virtual network cards, what type of
2162	networking should be available. They can be not connected to the host
2163	(<computeroutput>null</computeroutput>), use network address
2164	translation (<computeroutput>nat</computeroutput>), bridged networking
2165	(<computeroutput>bridged</computeroutput>) or communicate with other
2166	virtual machines using internal networking
2167	(<computeroutput>intnet</computeroutput>) or host-only networking
2168	(<computeroutput>hostonly</computeroutput>) or natnetwork networking
2169	(<computeroutput>natnetwork</computeroutput>) or access to rarely used
2170	sub-modes
2171	(<computeroutput>generic</computeroutput>).
2172	These options correspond to the modes which are described in detail in <xref
2173	linkend="networkingmodes" />.</para>
2174	</listitem>
2175
2176	<listitem>
2177	<para>With the "nictrace" options, you can optionally trace
2178	network traffic by dumping it to a file, for debugging
2179	purposes.</para>
2180
2181	<para>With <computeroutput>nictrace<1-N>
2182	on\|off</computeroutput>, you can enable network tracing for a
2183	particular virtual network card.</para>
2184
2185	<para>If enabled, you must specify with
2186	<computeroutput>--nictracefile<1-N>
2187	<filename></computeroutput> what file the trace should be
2188	logged to.</para>
2189	</listitem>
2190
2191	<listitem>
2192	<para><computeroutput>nicpromisc<1-N>
2193	deny\|allow-vms\|allow-all</computeroutput>:
2194	This allows you, for each of the VM's virtual network cards, to
2195	specify how the promiscious mode is handled. This setting is only
2196	relevant for bridged networking.
2197	<computeroutput>deny</computeroutput> (default setting) hides
2198	any traffic not intended for this VM.
2199	<computeroutput>allow-vms</computeroutput> hides all host
2200	traffic from this VM but allows the VM to see traffic from/to other
2201	VMs.
2202	<computeroutput>allow-all</computeroutput> removes this
2203	restriction completely.</para>
2204	</listitem>
2205
2206	<listitem>
2207	<para><computeroutput>nicproperty<1-N>
2208	<paramname>="paramvalue"</computeroutput>:
2209	This option, in combination with "nicgenericdrv" allows you to
2210	pass parameters to rarely-used network backends.</para><para>
2211	Those parameters are backend engine-specific, and are different
2212	between UDP Tunnel and the VDE backend drivers. For example,
2213	please see <xref linkend="network_udp_tunnel" />.
2214	</para>
2215	</listitem>
2216
2217	<listitem>
2218	<para><computeroutput>natpf<1-N>
2219	[<name>],tcp\|udp,[<hostip>],<hostport>,[<guestip>],
2220	<guestport></computeroutput>: This option defines a NAT
2221	port-forwarding rule (please see <xref linkend="natforward"/>
2222	for details).
2223	</para>
2224	</listitem>
2225
2226	<listitem>
2227	<para><computeroutput>natpf<1-N> delete
2228	<name></computeroutput>: This option deletes a NAT
2229	port-forwarding rule (please see <xref linkend="natforward"/>
2230	for details).</para>
2231	</listitem>
2232
2233	<listitem>
2234	<para>The <computeroutput>guestmemoryballoon<balloon size in MB></computeroutput>
2235	operation changes the size of the guest memory balloon, that is,
2236	memory allocated by the VirtualBox Guest Additions from the guest
2237	operating system and returned to the hypervisor for re-use by other
2238	virtual machines. This must be specified in megabytes. For details,
2239	see <xref linkend="guestadd-balloon" />.</para>
2240	</listitem>
2241
2242	<listitem>
2243	<para><computeroutput>usbattach<uuid\|address> [--capturefile <filename>]</computeroutput></para>
2244	<para>and <computeroutput>usbdetach <uuid\|address> [--capturefile <filename>]</computeroutput>
2245	make host USB devices visible/invisible to the virtual machine on the fly, without the need for
2246	creating filters first. The USB devices can be specified by UUID
2247	(unique identifier) or by address on the host system. Use the --capturefile
2248	option to specify the absolute path of a file for writing activity logging data.</para>
2249
2250	<para>You can use <computeroutput>VBoxManage list
2251	usbhost</computeroutput> to locate this information.</para>
2252	</listitem>
2253
2254	<listitem>
2255	<para><computeroutput>clipboard
2256	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
2257	With this setting, you can select if and how the guest or host
2258	operating system's clipboard should be shared with the host or guest;
2259	see <xref linkend="generalsettings" />. This requires that the Guest
2260	Additions be installed in the virtual machine.</para>
2261	</listitem>
2262
2263	<listitem>
2264	<para><computeroutput>draganddrop
2265	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
2266	With this setting, you can select the current drag and drop mode
2267	being used between the host and the virtual machine;
2268	see <xref linkend="guestadd-dnd" />. This requires that the Guest
2269	Additions be installed in the virtual machine.</para>
2270	</listitem>
2271
2272	<listitem>
2273	<para><computeroutput>vrde on\|off</computeroutput> lets you enable or
2274	disable the VRDE server, if it is installed.</para>
2275	</listitem>
2276
2277	<listitem>
2278	<para><computeroutput>vrdeport default\|<ports></computeroutput>
2279	changes the port or a range of ports that the VRDE server can bind to;
2280	"default" or "0" means port 3389, the standard port for RDP. For
2281	details, see the description for the
2282	<computeroutput>--vrdeport</computeroutput> option in <xref
2283	linkend="vboxmanage-modifyvm-vrde" />.</para>
2284	</listitem>
2285
2286	<listitem>
2287	<para><computeroutput>vrdeproperty "TCP/Ports\|Address=<value>"</computeroutput>
2288	sets the port number(s) and IP address on the VM that the VRDE server can bind to.</para>
2289
2290	<itemizedlist>
2291	<listitem>
2292	<para>For TCP/Ports, <value> should be a port or a range of ports that the VRDE
2293	server can bind to; "default" or "0" means port 3389, the standard port for RDP.
2294	For details, see the description for the
2295	<computeroutput>--vrdeport</computeroutput> option in <xref
2296	linkend="vboxmanage-modifyvm-vrde" />.</para>
2297	</listitem>
2298
2299	<listitem>
2300	<para>For TCP/Address, <value> should be the IP address of the host network
2301	interface that the VRDE server will bind to. If specified, the server
2302	will accept connections only on the specified host network interface.
2303	For details, see the description for the
2304	<computeroutput>--vrdeaddress</computeroutput> option in <xref
2305	linkend="vboxmanage-modifyvm-vrde" />.</para>
2306	</listitem>
2307	</itemizedlist>
2308	</listitem>
2309
2310	<listitem>
2311	<para><computeroutput>vrdeproperty "VideoChannel/Enabled\|Quality\|DownscaleProtection=<value>"</computeroutput>
2312	sets the VRDP video redirection properties.</para>
2313	<itemizedlist>
2314	<listitem>
2315	<para>For VideoChannel/Enabled, <value> can be set to "1" switching the VRDP video channel on.
2316	For details, see <xref linkend="vrde-videochannel" />.</para>
2317	</listitem>
2318
2319	<listitem>
2320	<para>For VideoChannel/Quality, <value> should be set between 10 and 100% inclusive,
2321	representing a JPEG compression level on the VRDE server video channel. Lower values mean lower
2322	quality but higher compression. For details, see <xref linkend="vrde-videochannel" />.</para>
2323	</listitem>
2324
2325	<listitem>
2326	<para>For VideoChannel/DownscaleProtection, <value> can be set to "1" to
2327	enable the videochannel downscale protection feature. When enabled, if a video's size equals the shadow buffer
2328	size, then it is regarded as a full screen video, and is displayed; but if its size is between fullscreen and the downscale
2329	threshold - it is NOT displayed, as it could be an application window, which would be unreadable when downscaled.
2330	When the downscale protection feature is disabled, an attempt is always made to display videos.</para>
2331	</listitem>
2332	</itemizedlist>
2333	</listitem>
2334
2335	<listitem>
2336	<para><computeroutput>vrdeproperty "Client/DisableDisplay\|DisableInput\|DisableAudio\|DisableUSB=1"</computeroutput></para>
2337	<para>disables one of the VRDE server features: Display, Input, Audio or USB respectively.
2338	To re-enable a feature, use e.g. "Client/DisableDisplay=".
2339	For details, see <xref linkend="vrde-customization" />.</para>
2340	</listitem>
2341
2342	<listitem>
2343	<para><computeroutput>vrdeproperty "Client/DisableClipboard\|DisableUpstreamAudio=1"</computeroutput></para>
2344	<para>disables one of the VRDE server features: Clipboard or UpstreamAudio respectively.
2345	To re-enable a feature, use e.g. "Client/DisableClipboard=".
2346	For details, see <xref linkend="vrde-customization" />.</para>
2347	</listitem>
2348
2349	<listitem>
2350	<para><computeroutput>vrdeproperty "Client/DisableRDPDR=1"</computeroutput></para>
2351	<para>disables the VRDE server feature: RDP device redirection for smart cards.
2352	To re-enable this feature, use "Client/DisableRDPR=".</para>
2353	</listitem>
2354
2355	<listitem>
2356	<para><computeroutput>vrdeproperty "H3DRedirect/Enabled=1"</computeroutput></para>
2357	<para>enables the VRDE server feature: 3D redirection.
2358	To re-disable this feature, use "H3DRedirect/Enabled=".</para>
2359	</listitem>
2360
2361	<listitem>
2362	<para><computeroutput>vrdeproperty "Security/Method\|ServerCertificate\|ServerPrivateKey\|CACertificate=<value>"</computeroutput>
2363	sets the desired security method/Path of server certificate, path of server private key, path of CA certificate, used for a connection.
2364
2365	<itemizedlist>
2366	<listitem>
2367	<para><computeroutput>vrdeproperty "Security/Method=<value>"</computeroutput>
2368	sets the desired security method, which is used for a connection. Valid values are:
2369	<itemizedlist>
2370	<listitem>
2371	<para> <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
2372	and Standard RDP Security connections are allowed. The security
2373	method is negotiated with the client. This is the default setting.</para>
2374	</listitem>
2375	<listitem>
2376	<para> <computeroutput>RDP</computeroutput> - only Standard RDP Security is accepted.</para>
2377	</listitem>
2378	<listitem>
2379	<para> <computeroutput>TLS</computeroutput> - only Enhanced RDP Security is accepted.
2380	The client must support TLS.</para>
2381	</listitem>
2382	</itemizedlist>
2383	For details, see <xref linkend="vrde-crypt" />.</para>
2384	</listitem>
2385
2386	<listitem>
2387	<para><computeroutput>vrdeproperty "Security/ServerCertificate=<value>"</computeroutput>
2388	where <value> is the absolute path of the server certificate.
2389	For details, see <xref linkend="vrde-crypt" />.</para>
2390	</listitem>
2391
2392	<listitem>
2393	<para><computeroutput>vrdeproperty "Security/ServerPrivateKey=<value>"</computeroutput>
2394	where <value> is the absolute path of the server private key.
2395	For details, see <xref linkend="vrde-crypt" />.</para>
2396	</listitem>
2397
2398	<listitem>
2399	<para><computeroutput>vrdeproperty "Security/CACertificate=<value>"</computeroutput>
2400	where <value> is the absolute path of the CA self signed certificate.
2401	For details, see <xref linkend="vrde-crypt" />.</para>
2402	</listitem>
2403	</itemizedlist></para>
2404	</listitem>
2405
2406	<listitem>
2407	<para><computeroutput>vrdeproperty "Audio/RateCorrectionMode\|LogPath=<value>"</computeroutput>
2408	sets the Audio connection mode, or Path of the audio logfile.
2409
2410	<itemizedlist>
2411	<listitem>
2412	<para><computeroutput>vrdeproperty "Audio/RateCorrectionMode=<value>"</computeroutput>
2413	where <value> is the desired rate correction mode, allowed values are:
2414	<itemizedlist>
2415	<listitem>
2416	<para> <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput> - no mode specified, use to unset any Audio mode already set.</para>
2417	</listitem>
2418	<listitem>
2419	<para> <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput> - rate correction mode.</para>
2420	</listitem>
2421	<listitem>
2422	<para> <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput> - low pass filter mode.</para>
2423	</listitem>
2424	<listitem>
2425	<para> <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput> - client sync mode to prevent under/overflow of the client queue.</para>
2426	</listitem>
2427	</itemizedlist></para>
2428	</listitem>
2429	<listitem>
2430	<para><computeroutput>vrdeproperty "Audio/LogPath=<value>"</computeroutput>
2431	where <value> is the absolute path of the Audio log file.</para>
2432	</listitem>
2433	</itemizedlist></para>
2434	</listitem>
2435
2436	<listitem>
2437	<para><computeroutput>vrdevideochannelquality
2438	<percent></computeroutput>: Sets the image quality for video
2439	redirection; see <xref lang=""
2440	linkend="vrde-videochannel" />.</para>
2441	</listitem>
2442
2443	<listitem>
2444	<para><computeroutput>setvideomodehint</computeroutput> requests that
2445	the guest system change to a particular video mode. This requires that
2446	the Guest Additions be installed, and will not work for all guest
2447	systems.</para>
2448	</listitem>
2449
2450	<listitem>
2451	<para><computeroutput>screenshotpng</computeroutput> takes a screenshot
2452	of the guest display and saves it in PNG format.</para>
2453	</listitem>
2454
2455	<listitem>
2456	<para><computeroutput>videocap on\|off</computeroutput> enables or disables
2457	recording a VM session into a WebM/VP8 file.</para>
2458	</listitem>
2459
2460	<listitem>
2461	<para><computeroutput>videocapscreens all\|<screen ID>
2462	[<screen ID> ...]]</computeroutput> allows to specify which screens of
2463	the VM are being recorded. This setting
2464	cannot be changed while video capturing is enabled. Each screen is recorded
2465	into a separate file.</para>
2466	</listitem>
2467
2468	<listitem>
2469	<para><computeroutput>videocapfile <file></computeroutput> sets the filename
2470	VirtualBox uses to save the recorded content. This setting cannot be changed
2471	while video capturing is enabled.</para>
2472	</listitem>
2473
2474	<listitem>
2475	<para><computeroutput>videocapres <width> <height></computeroutput>
2476	sets the resolution (in pixels) of the recorded video. This setting cannot be
2477	changed while video capturing is enabled.</para>
2478	</listitem>
2479
2480	<listitem> <!-- @todo r=andy Clarify rate. -->
2481	<para><computeroutput>videocaprate <rate></computeroutput> sets the
2482	bitrate in kilobits (kb) per second. Increasing this value makes the video
2483	look better for the cost of an increased file size. This setting cannot be
2484	changed while video capturing is enabled.</para>
2485	</listitem>
2486
2487	<listitem>
2488	<para><computeroutput>videocapfps <fps></computeroutput> sets the
2489	maximum number of frames per second (FPS) to be recorded. Frames with a
2490	higher frequency will be skipped. Reducing this value increases the number
2491	of skipped frames and reduces the file size. This setting cannot be changed
2492	while video capturing is enabled.</para>
2493	</listitem>
2494
2495	<listitem> <!-- @todo r=andy Clarify time format. -->
2496	<para><computeroutput>videocapmaxtime <ms></computeroutput> sets
2497	the maximum time in milliseconds the video capturing will be enabled
2498	since activation.
2499	The capturing stops when the defined time interval has elapsed. If this
2500	value is zero the capturing is not limited by time. This setting cannot
2501	be changed while video capturing is enabled.</para>
2502	</listitem>
2503
2504	<listitem>
2505	<para><computeroutput>videocapmaxsize <MB></computeroutput> limits
2506	the maximum size of the captured video file (in MB). The capturing stops
2507	when the file size has reached the specified size. If this value is zero
2508	the capturing will not be limited by file size. This setting cannot be
2509	changed while video capturing is enabled.</para>
2510	</listitem>
2511
2512	<listitem>
2513	<para><computeroutput>videocapopts <key=value>[,<key=value> ...]</computeroutput>
2514	can be used to specify additional video capturing options. These options
2515	only are for advanced users and must be specified in a comma-separated
2516	key=value format, e.g. <computeroutput>foo=bar,a=b</computeroutput>.
2517	This setting cannot be changed while video capturing is enabled.</para>
2518	</listitem>
2519
2520	<listitem>
2521	<para>The <computeroutput>setcredentials</computeroutput> operation is
2522	used for remote logons in Windows guests. For details, please refer to
2523	<xref linkend="autologon" />.</para>
2524	</listitem>
2525
2526	<listitem>
2527	<para><computeroutput>teleport --host <name> --port <port></computeroutput>
2528	can be used to configure a VM as a target for teleporting.
2529	<name> specifies the virtual machine name. <port> specifies the port on the
2530	virtual machine which should listen for a teleporting request from another
2531	virtual machine. It can be any free TCP/IP port number (e.g. 6000);
2532	See <xref linkend="teleporting" /> for an introduction.</para>
2533	<itemizedlist>
2534	<listitem>
2535	<para><computeroutput>--maxdowntime <msec></computeroutput>:
2536	Optional - specifies the maximum downtime (milliseconds) for the
2537	teleporting target VM.</para>
2538	</listitem>
2539
2540	<listitem>
2541	<para><computeroutput>--password
2542	<password></computeroutput>:
2543	Optional - indicates that the teleporting request will only succeed if the
2544	source machine specifies the same password as the one given with
2545	this command.</para>
2546	</listitem>
2547
2548	<listitem>
2549	<para><computeroutput>--passwordfile
2550	<password file></computeroutput>:
2551	Optional - indicates that the teleporting request will only succeed if the
2552	source machine specifies the same password as the one specified
2553	in the file given with this command. Use <computeroutput>stdin</computeroutput>
2554	to read the password from stdin.</para>
2555	</listitem>
2556	</itemizedlist>
2557	</listitem>
2558
2559	<listitem>
2560	<para><computeroutput>plugcpu\|unplugcpu
2561	<id></computeroutput>: If CPU hot-plugging is enabled, this adds
2562	a virtual CPU to the virtual machines (or removes one).
2563	<computeroutput><id></computeroutput> specifies the index of
2564	the virtual CPU to be added or removed and must be a number from 0
2565	to the maximum no. of CPUs configured. CPU 0 can never be removed.</para>
2566	</listitem>
2567
2568	<listitem>
2569	<para>The <computeroutput>cpuexecutioncap
2570	<1-100></computeroutput>: This operation controls how much cpu
2571	time a virtual CPU can use. A value of 50 implies a single virtual CPU
2572	can use up to 50% of a single host CPU.</para>
2573	</listitem>
2574
2575	<listitem>
2576	<para><computeroutput>webcam
2577	attach <path\|alias> [<key=value>[;<key=value>...]]</computeroutput>: This operation
2578	attaches a webcam to a running VM. Specify the absolute path of the
2579	webcam on the host operating system, or use its alias (obtained by using the command: VBoxManage
2580	list webcams).</para>
2581
2582	<para>Note that alias '.0' means default video input device on the host operating system, '.1', '.2',
2583	etc. mean first, second, etc. video input device. The device order is host-specific.</para>
2584
2585	<para>The optional settings parameter is a ';' delimited list of name/value pairs, enabling configuration
2586	of the emulated webcam device.</para>
2587
2588	<para>The following settings are supported:</para>
2589
2590	<para>MaxFramerate (default no maximum limit) - this specifies the highest rate (frames/sec) at which
2591	video frames are sent to the guest. Higher frame rates increase CPU load, so this setting can be useful
2592	when there is a need to reduce CPU load. Its default 'value' is 'no maximum limit', thus enabling the
2593	guest to use all frame rates supported by the host webcam.</para>
2594
2595	<para>MaxPayloadTransferSize (default 3060 bytes) - this specifies the maximum number of bytes the emulated
2596	webcam can send to the guest in one buffer. The default is used by some webcams. Higher values can
2597	slightly reduce CPU load, if the guest is able to use larger buffers.
2598	Note that higher MaxPayloadTransferSize values may be not supported by some guest operating systems.</para>
2599	</listitem>
2600
2601	<listitem>
2602	<para><computeroutput>webcam
2603	detach <path\|alias></computeroutput>: This operation
2604	detaches a webcam from a running VM. Specify the absolute path of the
2605	webcam on the host, or use its alias (obtained from webcam list below).</para>
2606	<para>Note the points below relating to specific Host Operating Systems:</para>
2607
2608	<para>Windows hosts</para>
2609
2610	<para>When the webcam device is detached from the host, the emulated webcam device
2611	is automatically detached from the guest.</para>
2612
2613	<para>Mac OS X hosts</para>
2614
2615	<para>OS X version 10.7 or newer is required.</para>
2616
2617	<para>When the webcam device is detached from the host, the emulated webcam device remains
2618	attached to the guest and must be manually detached using the
2619	VBoxManage controlvm "VM name" webcam detach command.</para>
2620
2621	<para>Linux hosts</para>
2622
2623	<para>When the webcam is detached from the host, the emulated webcam device is automatically detached
2624	from the guest only if the webcam is streaming video. If the emulated webcam is inactive, it
2625	should be manually detached using the VBoxManage controlvm "VM name" webcam detach command.</para>
2626	</listitem>
2627
2628	<listitem>
2629	<para><computeroutput>webcam list</computeroutput>: This operation
2630	lists webcams attached to the running VM.
2631	The output is a list of absolute paths or aliases that were used for attaching the webcams
2632	to the VM using the 'webcam attach' command above.
2633	</para>
2634	</listitem>
2635
2636	<listitem>
2637	<para><computeroutput>addencpassword
2638	<id> <password file>\|- [--removeonsuspend <yes\|no>]</computeroutput>: This operation
2639	supplies an encrypted VM specified by <id> with the encryption password to enable a headless start.
2640	Either specify the absolute path of a password file on the host file system: <password file>, or
2641	use a '-' to instruct VBoxManage to prompt the user for the encryption password. </para>
2642
2643	<para><computeroutput>--removeonsuspend <yes\|no></computeroutput> specifies whether to remove/keep
2644	the password from/in VM memory when the VM is suspended. If the VM has been suspended and the password has
2645	been removed, the user needs to resupply the password before the VM can be resumed. This feature is useful
2646	in cases where the user doesn't want the password to be stored in VM memory, and the VM is suspended by a
2647	host suspend event.</para>
2648
2649	<para>Note: On VirtualBox versions 5.0 and later, data stored on hard disk images can be transparently
2650	encrypted for the guest. VirtualBox uses the AES algorithm in XTS mode and supports 128 or 256
2651	bit data encryption keys (DEK). The DEK is stored encrypted in the medium properties, and is
2652	decrypted during VM startup by supplying the encryption password.</para>
2653
2654	<para>The "VBoxManage encryptmedium" operation is used to create a DEK encrypted medium.
2655	See <xref linkend="diskencryption-encryption" />" for details.
2656	When starting an encrypted VM from a VirtualBox GUI app, the user will be prompted for the
2657	encryption password.</para>
2658
2659	<para>For a headless encrypted VM start, use:</para>
2660
2661	<para>VBoxManage startvm "vmname" --type headless</para>
2662
2663	<para>followed by:</para>
2664
2665	<para>VBoxManage "vmname" controlvm "vmname" addencpassword ...</para>
2666
2667	<para>to supply the encryption password required.</para>
2668	</listitem>
2669
2670	<listitem>
2671	<para><computeroutput>removeencpassword <id></computeroutput>: This operation
2672	removes encryption password authorization for password <id> for all encrypted media
2673	attached to the VM.</para>
2674	</listitem>
2675
2676	<listitem>
2677	<para><computeroutput>removeallencpasswords</computeroutput>: This operation
2678	removes encryption password authorization for all passwords for all
2679	encrypted media attached to the VM.</para>
2680	</listitem>
2681
2682	</itemizedlist>
2683	</sect1>
2684
2685	<sect1>
2686	<title>VBoxManage discardstate</title>
2687
2688	<para>This command discards the saved state of a virtual machine which is
2689	not currently running, which will cause its operating system to restart
2690	next time you start it. This is the equivalent of pulling out the power
2691	cable on a physical machine, and should be avoided if possible.</para>
2692	</sect1>
2693
2694	<sect1>
2695	<title>VBoxManage adoptstate</title>
2696
2697	<para>If you have a saved state file (<computeroutput>.sav</computeroutput>)
2698	that is separate from the VM configuration, you can use this command to
2699	"adopt" the file. This will change the VM to saved state and when you
2700	start it, VirtualBox will attempt to restore it from the saved state file
2701	you indicated. This command should only be used in special setups.</para>
2702	</sect1>
2703
2704	<sect1>
2705	<title>VBoxManage snapshot</title>
2706
2707	<para>This command is used to control snapshots from the command line. A
2708	snapshot consists of a complete copy of the virtual machine settings,
2709	copied at the time when the snapshot was taken, and optionally a virtual
2710	machine saved state file if the snapshot was taken while the machine was
2711	running. After a snapshot has been taken, VirtualBox creates differencing
2712	hard disk for each normal hard disk associated with the machine so that
2713	when a snapshot is restored, the contents of the virtual machine's virtual
2714	hard disks can be quickly reset by simply dropping the pre-existing
2715	differencing files.</para>
2716
2717	<screen>VBoxManage snapshot <uuid\|vmname>
2718	take <name> [--description <desc>] [--live]
2719	[--uniquename Number,Timestamp,Space,Force] \|
2720	delete <uuid\|snapname> \|
2721	restore <uuid\|snapname> \|
2722	restorecurrent \|
2723	edit <uuid\|snapname>\|--current
2724	[--name <name>]
2725	[--description <desc>] \|
2726	list [--details\|--machinereadable]
2727	showvminfo <uuid\|snapname></screen>
2728
2729	<para>The <computeroutput>take</computeroutput> operation takes a snapshot
2730	of the current state of the virtual machine. You must supply a name for
2731	the snapshot and can optionally supply a description. The new snapshot is
2732	inserted into the snapshots tree as a child of the current snapshot and
2733	then becomes the new current snapshot. The
2734	<computeroutput>--description</computeroutput> parameter allows to
2735	describe the snapshot. If <computeroutput>--live</computeroutput>
2736	is specified, the VM will not be stopped during the snapshot creation
2737	(live snapshotting).</para>
2738
2739	<para>The <computeroutput>delete</computeroutput> operation deletes a
2740	snapshot (specified by name or by UUID). This can take a while to finish
2741	since the differencing images associated with the snapshot might need to
2742	be merged with their child differencing images.</para>
2743
2744	<para>The <computeroutput>restore</computeroutput> operation will restore
2745	the given snapshot (specified by name or by UUID) by resetting the virtual
2746	machine's settings and current state to that of the snapshot. The previous
2747	current state of the machine will be lost. After this, the given snapshot
2748	becomes the new "current" snapshot so that subsequent snapshots are
2749	inserted under the snapshot from which was restored.</para>
2750
2751	<para>The <computeroutput>restorecurrent</computeroutput> operation is a
2752	shortcut to restore the current snapshot (i.e. the snapshot from which the
2753	current state is derived). This subcommand is equivalent to using the
2754	"restore" subcommand with the name or UUID of the current snapshot, except
2755	that it avoids the extra step of determining that name or UUID.</para>
2756
2757	<para>With the <computeroutput>edit</computeroutput> operation, you can
2758	change the name or description of an existing snapshot.</para>
2759
2760	<para>The <computeroutput>list</computeroutput> operation shows all
2761	snapshots of a virtual machine.</para>
2762
2763	<para>With the <computeroutput>showvminfo</computeroutput> operation, you
2764	can view the virtual machine settings that were stored with an existing
2765	snapshot.</para>
2766	</sect1>
2767
2768	<sect1 id="vboxmanage-closemedium">
2769	<title>VBoxManage closemedium</title>
2770
2771	<para>This commands removes a hard disk, DVD or floppy image from a
2772	VirtualBox media registry.<footnote>
2773	<para>Before VirtualBox 4.0, it was necessary to call VBoxManage
2774	openmedium before a medium could be attached to a virtual machine;
2775	that call "registered" the medium with the global VirtualBox media
2776	registry. With VirtualBox 4.0 this is no longer necessary; media are
2777	added to media registries automatically. The "closemedium" call has
2778	been retained, however, to allow for explicitly removing a medium from
2779	a registry.</para>
2780	</footnote></para>
2781
2782	<screen>VBoxManage closemedium [disk\|dvd\|floppy] <uuid\|filename>
2783	[--delete]</screen>
2784
2785	<para>Optionally, you can request that the image be deleted. You will get
2786	appropriate diagnostics that the deletion failed, however the image will
2787	become unregistered in any case.</para>
2788	</sect1>
2789
2790	<sect1 id="vboxmanage-storageattach">
2791	<title>VBoxManage storageattach</title>
2792
2793	<para>This command attaches/modifies/removes a storage medium connected to
2794	a storage controller that was previously added with the
2795	<computeroutput>storagectl</computeroutput> command (see the previous
2796	section). The syntax is as follows:</para>
2797
2798	<screen>VBoxManage storageattach <uuid\|vmname>
2799	--storagectl <name>
2800	[--port <number>]
2801	[--device <number>]
2802	[--type dvddrive\|hdd\|fdd]
2803	[--medium none\|emptydrive\|additions\|
2804	<uuid>\|<filename>\|host:<drive>\|iscsi]
2805	[--mtype normal\|writethrough\|immutable\|shareable
2806	readonly\|multiattach]
2807	[--comment <text>]
2808	[--setuuid <uuid>]
2809	[--setparentuuid <uuid>]
2810	[--passthrough on\|off]
2811	[--tempeject on\|off]
2812	[--nonrotational on\|off]
2813	[--discard on\|off]
2814	[--hotpluggable on\|off]
2815	[--bandwidthgroup name\|none]
2816	[--forceunmount]
2817	[--server <name>\|<ip>]
2818	[--target <target>]
2819	[--tport <port>]
2820	[--lun <lun>]
2821	[--encodedlun <lun>]
2822	[--username <username>]
2823	[--password <password>]
2824	[--initiator <initiator>]
2825	[--intnet]</screen>
2826
2827	<para>A number of parameters are commonly required; the ones at the end of
2828	the list are required only for iSCSI targets (see below).</para>
2829
2830	<para>The common parameters are:<glosslist>
2831	<glossentry>
2832	<glossterm><computeroutput>uuid\|vmname</computeroutput></glossterm>
2833
2834	<glossdef>
2835	<para>The VM UUID or VM Name. Mandatory.</para>
2836	</glossdef>
2837	</glossentry>
2838
2839	<glossentry>
2840	<glossterm><computeroutput>--storagectl</computeroutput></glossterm>
2841
2842	<glossdef>
2843	<para>Name of the storage controller. Mandatory. The list of the
2844	storage controllers currently attached to a VM can be obtained
2845	with <computeroutput>VBoxManage showvminfo</computeroutput>; see
2846	<xref linkend="vboxmanage-showvminfo" />.</para>
2847	</glossdef>
2848	</glossentry>
2849
2850	<glossentry>
2851	<glossterm><computeroutput>--port</computeroutput></glossterm>
2852
2853	<glossdef>
2854	<para>The number of the storage controller's port which is to be
2855	modified. Mandatory, unless the storage controller has only a
2856	single port.</para>
2857	</glossdef>
2858	</glossentry>
2859
2860	<glossentry>
2861	<glossterm><computeroutput>--device</computeroutput></glossterm>
2862
2863	<glossdef>
2864	<para>The number of the port's device which is to be modified.
2865	Mandatory, unless the storage controller has only a single device
2866	per port.</para>
2867	</glossdef>
2868	</glossentry>
2869
2870	<glossentry>
2871	<glossterm><computeroutput>--type</computeroutput></glossterm>
2872
2873	<glossdef>
2874	<para>Define the type of the drive to which the medium is being
2875	attached/detached/modified. This argument can only be omitted if
2876	the type of medium can be determined from either the medium given
2877	with the <computeroutput>--medium</computeroutput> argument or
2878	from a previous medium attachment.</para>
2879	</glossdef>
2880	</glossentry>
2881
2882	<glossentry>
2883	<glossterm><computeroutput>--medium</computeroutput></glossterm>
2884
2885	<glossdef>
2886	<para>Specifies what is to be attached. The following values are
2887	supported:<itemizedlist>
2888	<listitem>
2889	<para>"none": Any existing device should be removed from the
2890	given slot.</para>
2891	</listitem>
2892
2893	<listitem>
2894	<para>"emptydrive": For a virtual DVD or floppy drive only,
2895	this makes the device slot behaves like a removeable drive
2896	into which no media has been inserted.</para>
2897	</listitem>
2898
2899	<listitem>
2900	<para>"additions": For a virtual DVD drive only, this
2901	attaches the <emphasis>VirtualBox Guest Additions</emphasis>
2902	image to the given device slot.</para>
2903	</listitem>
2904
2905	<listitem>
2906	<para>If a UUID is specified, it must be the UUID of a
2907	storage medium that is already known to VirtualBox (e.g.
2908	because it has been attached to another virtual machine).
2909	See <xref linkend="vboxmanage-list" /> for how to list known
2910	media. This medium is then attached to the given device
2911	slot.</para>
2912	</listitem>
2913
2914	<listitem>
2915	<para>If a filename is specified, it must be the full path
2916	of an existing disk image (ISO, RAW, VDI, VMDK or other),
2917	which is then attached to the given device slot.</para>
2918	</listitem>
2919
2920	<listitem>
2921	<para>"host:<drive>": For a virtual DVD or floppy
2922	drive only, this connects the given device slot to the
2923	specified DVD or floppy drive on the host computer.</para>
2924	</listitem>
2925
2926	<listitem>
2927	<para>"iscsi": For virtual hard disks only, this allows for
2928	specifying an iSCSI target. In this case, more parameters
2929	must be given; see below.</para>
2930	</listitem>
2931	</itemizedlist></para>
2932
2933	<para>Some of the above changes, in particular for removeable
2934	media (floppies and CDs/DVDs), can be effected while a VM is
2935	running. Others (device changes or changes in hard disk device
2936	slots) require the VM to be powered off.</para>
2937	</glossdef>
2938	</glossentry>
2939
2940	<glossentry>
2941	<glossterm><computeroutput>--mtype</computeroutput></glossterm>
2942
2943	<glossdef>
2944	<para>Defines how this medium behaves with respect to snapshots
2945	and write operations. See <xref linkend="hdimagewrites" /> for
2946	details.</para>
2947	</glossdef>
2948	</glossentry>
2949
2950	<glossentry>
2951	<glossterm><computeroutput>--comment</computeroutput></glossterm>
2952
2953	<glossdef>
2954	<para>Any description that you want to have stored with this
2955	medium (optional; for example, for an iSCSI target, "Big storage
2956	server downstairs"). This is purely descriptive and not needed for
2957	the medium to function correctly.</para>
2958	</glossdef>
2959	</glossentry>
2960
2961	<glossentry>
2962	<glossterm><computeroutput>--setuuid, --setparentuuid</computeroutput></glossterm>
2963
2964	<glossdef>
2965	<para>Modifies the UUID or parent UUID of a medium before
2966	attaching it to a VM. This is an expert option. Inappropriate use
2967	can make the medium unusable or lead to broken VM configurations
2968	if any other VM is referring to the same media already. The most
2969	frequently used variant is <code>--setuuid ""</code>, which assigns
2970	a new (random) UUID to an image. This is useful to resolve the
2971	duplicate UUID errors if one duplicated an image using file copy
2972	utilities.</para>
2973	</glossdef>
2974	</glossentry>
2975
2976	<glossentry>
2977	<glossterm><computeroutput>--passthrough</computeroutput></glossterm>
2978
2979	<glossdef>
2980	<para>For a virtual DVD drive only, you can enable DVD writing
2981	support (currently experimental; see <xref
2982	linkend="storage-cds" />).</para>
2983	</glossdef>
2984	</glossentry>
2985
2986	<glossentry>
2987	<glossterm><computeroutput>--tempeject</computeroutput></glossterm>
2988
2989	<glossdef>
2990	<para>For a virtual DVD drive only, you can configure the behavior
2991	for guest-triggered medium eject. If this is set to "on", the eject
2992	has only temporary effects. If the VM is powered off and restarted
2993	the originally configured medium will be still in the drive.</para>
2994	</glossdef>
2995	</glossentry>
2996
2997	<glossentry>
2998	<glossterm><computeroutput>--nonrotational</computeroutput></glossterm>
2999
3000	<glossdef>
3001	<para>This switch allows to enable the non-rotational flag for virtual
3002	hard disks. Some guests (i.e. Windows 7+) treat such disks like SSDs
3003	and don't perform disk fragmentation on such media.</para>
3004	</glossdef>
3005	</glossentry>
3006
3007	<glossentry>
3008	<glossterm><computeroutput>--discard</computeroutput></glossterm>
3009	<glossdef>
3010	<para>This switch enables the auto-discard feature for the virtual
3011	hard disks. This specifies that a VDI image will be shrunk in response
3012	to the trim command from the guest OS. The following requirements
3013	must be met:
3014
3015	<itemizedlist>
3016	<listitem>
3017	<para>The disk format must be VDI.</para>
3018	</listitem>
3019	<listitem>
3020	<para>The size of the cleared area must be at least 1MB.</para>
3021	</listitem>
3022	<listitem>
3023	<para>VirtualBox will only trim whole 1MB blocks. The VDIs themselves are organized
3024	into 1MB blocks, so this will only work if the space being TRIM-med is at least
3025	a 1MB contiguous block at a 1MB boundary. On Windows, occasional defrag (with "defrag.exe /D"),
3026	or under Linux running "btrfs filesystem defrag" as a background cron job may be
3027	beneficial.</para>
3028	</listitem>
3029	</itemizedlist></para>
3030
3031	<para>Notes: the Guest OS must be configured to issue trim command, and typically this
3032	means that the guest OS is made to 'see' the disk as an SSD. Ext4 supports -o discard mount flag;
3033	OSX probably requires additional settings. Windows ought to automatically detect and
3034	support SSDs - at least in versions 7, 8 and 10. Linux exFAT driver (courtesy of Samsung)
3035	supports the trim command.</para>
3036	<para>It is unclear whether Microsoft's implementation of exFAT supports this feature, even
3037	though that file system was originally designed for flash.</para>
3038	<para>Alternatively, there are ad hoc methods to issue trim, e.g. Linux fstrim command,
3039	part of util-linux package. Earlier solutions required a user to zero out unused areas,
3040	e.g. using zerofree, and explicitly compact the disk - only possible when the VM is
3041	offline.</para>
3042	</glossdef>
3043	</glossentry>
3044
3045	<glossentry>
3046	<glossterm><computeroutput>--bandwidthgroup</computeroutput></glossterm>
3047
3048	<glossdef>
3049	<para>Sets the bandwidth group to use for the given device; see
3050	<xref linkend="storage-bandwidth-limit" />.</para>
3051	</glossdef>
3052	</glossentry>
3053
3054	<glossentry>
3055	<glossterm><computeroutput>--forceunmount</computeroutput></glossterm>
3056
3057	<glossdef>
3058	<para>For a virtual DVD or floppy drive only, this forcibly
3059	unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if
3060	the previous one is locked down by the guest for reading. Again,
3061	see <xref linkend="storage-cds" /> for details.</para>
3062	</glossdef>
3063	</glossentry>
3064	</glosslist></para>
3065
3066	<para>When "iscsi" is used with the
3067	<computeroutput>--medium</computeroutput> parameter for iSCSI support --
3068	see <xref linkend="storage-iscsi" /> --, additional parameters must or can
3069	be used:<glosslist>
3070	<glossentry>
3071	<glossterm><computeroutput>--server</computeroutput></glossterm>
3072
3073	<glossdef>
3074	<para>The host name or IP address of the iSCSI target;
3075	required.</para>
3076	</glossdef>
3077	</glossentry>
3078
3079	<glossentry>
3080	<glossterm><computeroutput>--target</computeroutput></glossterm>
3081
3082	<glossdef>
3083	<para>Target name string. This is determined by the iSCSI target
3084	and used to identify the storage resource; required.</para>
3085	</glossdef>
3086	</glossentry>
3087
3088	<glossentry>
3089	<glossterm><computeroutput>--tport</computeroutput></glossterm>
3090
3091	<glossdef>
3092	<para>TCP/IP port number of the iSCSI service on the target
3093	(optional).</para>
3094	</glossdef>
3095	</glossentry>
3096
3097	<glossentry>
3098	<glossterm><computeroutput>--lun</computeroutput></glossterm>
3099
3100	<glossdef>
3101	<para>Logical Unit Number of the target resource (optional).
3102	Often, this value is zero.</para>
3103	</glossdef>
3104	</glossentry>
3105
3106	<glossentry>
3107	<glossterm><computeroutput>--encodedlun</computeroutput></glossterm>
3108
3109	<glossdef>
3110	<para>Hex encoded Logical Unit Number of the target resource (optional).
3111	Often, this value is zero.</para>
3112	</glossdef>
3113	</glossentry>
3114
3115	<glossentry>
3116	<glossterm><computeroutput>--username, --password</computeroutput></glossterm>
3117
3118	<glossdef>
3119	<para>Username and password (initiator secret) for target
3120	authentication, if required (optional).<note>
3121	<para>Username and password are stored without
3122	encryption (i.e. in clear text) in the XML machine
3123	configuration file if no settings password is provided.
3124	When a settings password was specified the first time,
3125	the password is stored encrypted.</para>
3126	</note></para>
3127	</glossdef>
3128	</glossentry>
3129
3130	<glossentry>
3131	<glossterm><computeroutput>--initiator</computeroutput></glossterm>
3132
3133	<glossdef>
3134	<para>iSCSI Initiator (optional). Note:</para>
3135
3136	<para>Microsoft iSCSI Initiator is a system, such as a server that attaches to an IP network and initiates requests and receives responses
3137	from an iSCSI target. The SAN components in Microsoft iSCSI Initiator are largely analogous to Fibre Channel SAN components, and
3138	they include the following:/</para>
3139
3140	<para>To transport blocks of iSCSI commands over the IP network, an iSCSI driver must be installed on the iSCSI host.
3141	An iSCSI driver is included with Microsoft iSCSI Initiator.</para>
3142
3143	<para>A gigabit Ethernet adapter that transmits 1000 megabits per second (Mbps) is recommended for the connection to an iSCSI target. Like
3144	standard 10/100 adapters, most gigabit adapters use a preexisting Category 5 or Category 6E cable that. Each port on the adapter is
3145	identified by a unique IP address.</para>
3146
3147	<para>An iSCSI target is any device that receives iSCSI commands. The device can be an end node, such as a storage device, or it can be an
3148	intermediate device, such as a network bridge between IP and Fibre Channel devices. Each port on the storage array controller or network
3149	bridge is identified by one or more IP addresses</para>
3150	</glossdef>
3151	</glossentry>
3152
3153	<glossentry>
3154	<glossterm><computeroutput>--intnet</computeroutput></glossterm>
3155
3156	<glossdef>
3157	<para>If specified, connect to the iSCSI target via Internal
3158	Networking. This needs further configuration which is described in
3159	<xref linkend="iscsi-intnet" />.</para>
3160	</glossdef>
3161	</glossentry>
3162	</glosslist></para>
3163	</sect1>
3164
3165	<sect1 id="vboxmanage-storagectl">
3166	<title>VBoxManage storagectl</title>
3167
3168	<para>This command attaches/modifies/removes a storage controller. After
3169	this, virtual media can be attached to the controller with the
3170	<computeroutput>storageattach</computeroutput> command (see the next
3171	section).</para>
3172
3173	<para>The syntax is as follows:</para>
3174
3175	<screen>VBoxManage storagectl <uuid\|vmname>
3176	--name <name>
3177	[--add <ide/sata/scsi/floppy>]
3178	[--controller <LsiLogic\|LSILogicSAS\|BusLogic\|
3179	IntelAhci\|PIIX3\|PIIX4\|ICH6\|I82078\|usb>]
3180	[--portcount <1-30>]
3181	[--hostiocache on\|off]
3182	[--bootable on\|off]
3183	[--rename <name>]
3184	[--remove]</screen>
3185
3186	<para>where the parameters mean: <glosslist>
3187	<glossentry>
3188	<glossterm><computeroutput>uuid\|vmname</computeroutput></glossterm>
3189
3190	<glossdef>
3191	<para>The VM UUID or VM Name. Mandatory.</para>
3192	</glossdef>
3193	</glossentry>
3194
3195	<glossentry>
3196	<glossterm><computeroutput>--name</computeroutput></glossterm>
3197
3198	<glossdef>
3199	<para>Name of the storage controller. Mandatory.</para>
3200	</glossdef>
3201	</glossentry>
3202
3203	<glossentry>
3204	<glossterm><computeroutput>--add</computeroutput></glossterm>
3205
3206	<glossdef>
3207	<para>Define the type of the system bus to which the storage
3208	controller must be connected.</para>
3209	</glossdef>
3210	</glossentry>
3211
3212	<glossentry>
3213	<glossterm><computeroutput>--controller</computeroutput></glossterm>
3214
3215	<glossdef>
3216	<para>Allows to choose the type of chipset being emulated for the
3217	given storage controller.</para>
3218	</glossdef>
3219	</glossentry>
3220
3221	<glossentry>
3222	<glossterm><computeroutput>--portcount</computeroutput></glossterm>
3223
3224	<glossdef>
3225	<para>This determines how many ports the storage controller should
3226	support.</para>
3227	</glossdef>
3228	</glossentry>
3229
3230	<glossentry>
3231	<glossterm><computeroutput>--hostiocache</computeroutput></glossterm>
3232
3233	<glossdef>
3234	<para>Configures the use of the host I/O cache for all disk images
3235	attached to this storage controller. For details, please see <xref
3236	linkend="iocaching" />.</para>
3237	</glossdef>
3238	</glossentry>
3239
3240	<glossentry>
3241	<glossterm><computeroutput>--bootable</computeroutput></glossterm>
3242
3243	<glossdef>
3244	<para>Selects whether this controller is bootable.</para>
3245	</glossdef>
3246	</glossentry>
3247
3248	<glossentry>
3249	<glossterm><computeroutput>--rename</computeroutput></glossterm>
3250
3251	<glossdef>
3252	<para>Sets the name of the storage controller.</para>
3253	</glossdef>
3254	</glossentry>
3255
3256	<glossentry>
3257	<glossterm><computeroutput>--remove</computeroutput></glossterm>
3258
3259	<glossdef>
3260	<para>Removes the storage controller from the VM config.</para>
3261	</glossdef>
3262	</glossentry>
3263	</glosslist></para>
3264	</sect1>
3265
3266	<sect1>
3267	<title>VBoxManage bandwidthctl</title>
3268
3269	<para>This command creates/deletes/modifies/shows bandwidth groups of the given
3270	virtual machine:
3271	<screen>VBoxManage bandwidthctl <uuid\|vmname>
3272	add <name> --type disk\|network --limit <megabytes per second>[k\|m\|g\|K\|M\|G] \|
3273	set <name> --limit <megabytes per second>[k\|m\|g\|K\|M\|G] \|
3274	remove <name> \|
3275	list [--machinereadable]</screen></para>
3276
3277	<para>The following subcommands are available:<itemizedlist>
3278	<listitem>
3279	<para><computeroutput>add</computeroutput>, creates a new bandwidth
3280	group of given type.</para>
3281	</listitem>
3282	<listitem>
3283	<para><computeroutput>set</computeroutput>, modifies the limit for an
3284	existing bandwidth group.</para>
3285	</listitem>
3286	<listitem>
3287	<para><computeroutput>remove</computeroutput>, destroys a bandwidth
3288	group.</para>
3289	</listitem>
3290	<listitem>
3291	<para><computeroutput>list</computeroutput>, shows all bandwidth groups
3292	defined for the given VM. Use <computeroutput>--machinereadable</computeroutput>
3293	option to produce the same output, but in machine readable format. This is of the
3294	form: name="value" on a line by line basis.</para>
3295	</listitem>
3296	</itemizedlist>
3297	</para>
3298	<para>The parameters mean:<glosslist>
3299	<glossentry>
3300	<glossterm><computeroutput>uuid\|vmname</computeroutput></glossterm>
3301
3302	<glossdef>
3303	<para>The VM UUID or VM Name. Mandatory.</para>
3304	</glossdef>
3305	</glossentry>
3306
3307	<glossentry>
3308	<glossterm><computeroutput>--name</computeroutput></glossterm>
3309
3310	<glossdef>
3311	<para>Name of the bandwidth group. Mandatory.</para>
3312	</glossdef>
3313	</glossentry>
3314
3315	<glossentry>
3316	<glossterm><computeroutput>--type</computeroutput></glossterm>
3317
3318	<glossdef>
3319	<para>Type of the bandwidth group. Mandatory. Two types are
3320	supported: <computeroutput>disk</computeroutput> and
3321	<computeroutput>network</computeroutput>. See
3322	<xref linkend="storage-bandwidth-limit" /> or
3323	<xref linkend="network_bandwidth_limit" /> for a description of a
3324	particular type.</para>
3325	</glossdef>
3326	</glossentry>
3327
3328	<glossentry>
3329	<glossterm><computeroutput>--limit</computeroutput></glossterm>
3330
3331	<glossdef>
3332	<para>Specifies the limit for the given group. Can be changed
3333	while the VM is running. The default unit is megabytes per
3334	second. The unit can be changed by specifying one of the
3335	following suffixes: <computeroutput>k</computeroutput> for kilobits/s,
3336	<computeroutput>m</computeroutput> for megabits/s,
3337	<computeroutput>g</computeroutput> for gigabits/s,
3338	<computeroutput>K</computeroutput> for kilobytes/s,
3339	<computeroutput>M</computeroutput> for megabytes/s,
3340	<computeroutput>G</computeroutput> for gigabytes/s.</para>
3341	</glossdef>
3342	</glossentry>
3343	</glosslist>
3344	<note>
3345	<para>The network bandwidth limits apply only to the traffic being sent by
3346	virtual machines. The traffic being received by VMs is unlimited.</para>
3347	</note>
3348	<note>
3349	<para>To remove a bandwidth group it must not be referenced by any disks
3350	or adapters in running VM.</para>
3351	</note>
3352	</para>
3353	</sect1>
3354
3355	<sect1>
3356	<title>VBoxManage showmediuminfo</title>
3357
3358	<para>This command shows information about a medium,
3359	notably its size, its size on disk, its type and the virtual machines
3360	which use it.<note>
3361	<para>For compatibility with earlier versions of VirtualBox, the
3362	"showvdiinfo" command is also supported and mapped internally to the
3363	"showmediuminfo" command.</para>
3364	</note></para>
3365
3366	<screen>VBoxManage showmediuminfo [disk\|dvd\|floppy] <uuid\|filename></screen>
3367
3368	<para>The medium must be specified either by its UUID (if the medium
3369	is registered) or by its filename. Registered images can be listed by
3370	<computeroutput>VBoxManage list hdds</computeroutput>,
3371	<computeroutput>VBoxManage list dvds</computeroutput>,
3372	or <computeroutput>VBoxManage list floppies</computeroutput>, as appropriate.
3373	(see <xref linkend="vboxmanage-list" />
3374	for more information).</para>
3375	</sect1>
3376
3377	<sect1 id="vboxmanage-createvdi">
3378	<title>VBoxManage createhd</title>
3379
3380	<para>This command creates a new medium. The syntax is as follows:</para>
3381
3382	<screen>VBoxManage createmedium [disk\|dvd\|floppy] --filename <filename>
3383	[--size <megabytes>\|--sizebyte <bytes>]
3384	[--diffparent <uuid>\|<filename>
3385	[--format VDI\|VMDK\|VHD] (default: VDI)
3386	[--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
3387
3388	<para>where the parameters mean:<glosslist>
3389	<glossentry>
3390	<glossterm><computeroutput>--filename <filename></computeroutput></glossterm>
3391
3392	<glossdef>
3393	<para>Specifies a file name <filename> as an absolute path on the host file
3394	system.. Mandatory.</para>
3395	</glossdef>
3396	</glossentry>
3397
3398	<glossentry>
3399	<glossterm><computeroutput>--size <megabytes></computeroutput></glossterm>
3400
3401	<glossdef>
3402	<para><megabytes> Specifies the image capacity, in 1 MB units.
3403	Optional.</para>
3404	</glossdef>
3405	</glossentry>
3406
3407	<glossentry>
3408	<glossterm><computeroutput>--diffparent <uuid>\|<filename></computeroutput></glossterm>
3409
3410	<glossdef>
3411	<para>Specifies the differencing image parent, either as a UUID or
3412	by the absolute pathname of the file on the host file system.
3413	Useful for sharing a base box disk image among several VMs.</para>
3414	</glossdef>
3415	</glossentry>
3416
3417	<glossentry>
3418	<glossterm><computeroutput>--format VDI\|VMDK\|VHD</computeroutput></glossterm>
3419
3420	<glossdef>
3421	<para>Specifies the file format for the output file. Available
3422	options are VDI, VMDK, VHD. Default is VDI. Optional. </para>
3423	</glossdef>
3424	</glossentry>
3425
3426	<glossentry>
3427	<glossterm><computeroutput>--variant Standard,Fixed,Split2G,Stream,ESX</computeroutput></glossterm>
3428
3429	<glossdef>
3430	<para>Specifies any required file format variant(s) for the output file.
3431	It is a comma-separated list of variant flags. Not all
3432	combinations are supported, and specifying mutually incompatible
3433	flags results in an error message. Optional.</para>
3434	</glossdef>
3435	</glossentry>
3436	</glosslist> <note>
3437	<para>For compatibility with earlier versions of VirtualBox, the
3438	"createvdi" command is also supported and mapped internally to the
3439	"createmedium" command.</para>
3440	</note></para>
3441	</sect1>
3442
3443	<sect1 id="vboxmanage-modifyvdi">
3444	<title>VBoxManage modifymedium</title>
3445
3446	<para>With the <computeroutput>modifymedium</computeroutput> command, you can
3447	change the characteristics of a disk image after it has been
3448	created:<screen>VBoxManage modifymedium [disk\|dvd\|floppy] <uuid\|filename>
3449	[--type normal\|writethrough\|immutable\|shareable\|
3450	readonly\|multiattach]
3451	[--autoreset on\|off]
3452	[--property <name=[value]>]
3453	[--compact]
3454	[--resize <megabytes>\|--resizebyte <bytes>]
3455	[--move <full path to a new location></screen><note>
3456	<para>For compatibility with earlier versions of VirtualBox, the "modifyvdi" and "modifyhd"
3457	commands are also supported and mapped internally to the "modifymedium" command.</para>
3458	</note></para>
3459
3460	<para>The disk image to modify must be specified either by its UUID
3461	(if the medium is registered) or by its filename. Registered images
3462	can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
3463	(see <xref linkend="vboxmanage-list" /> for more information).
3464	A filename must be specified as valid path, either as an absolute path
3465	or as a relative path starting from the current directory.</para>
3466	<para>The following options are available:<itemizedlist>
3467	<listitem>
3468	<para>With the <computeroutput>--type</computeroutput> argument, you
3469	can change the type of an existing image between the normal,
3470	immutable, write-through and other modes; see <xref
3471	linkend="hdimagewrites" /> for details.</para>
3472	</listitem>
3473
3474	<listitem>
3475	<para>For immutable (differencing) hard disks only, the
3476	<computeroutput>--autoreset on\|off</computeroutput> option
3477	determines whether the disk is automatically reset on every VM
3478	startup (again, see <xref linkend="hdimagewrites" />). The default
3479	is "on".</para>
3480	</listitem>
3481
3482	<listitem>
3483	<para>The <computeroutput>--compact</computeroutput> option,
3484	can be used to compact disk images, i.e. remove blocks that only
3485	contains zeroes. This will shrink a dynamically allocated image
3486	again; it will reduce the <emphasis>physical</emphasis> size of the
3487	image without affecting the logical size of the virtual disk.
3488	Compaction works both for base images and for diff images created as
3489	part of a snapshot.</para>
3490
3491	<para>For this operation to be effective, it is required that free
3492	space in the guest system first be zeroed out using a suitable
3493	software tool. For Windows guests, you can use the
3494	<computeroutput>sdelete</computeroutput> tool provided by Microsoft.
3495	Execute <computeroutput>sdelete -z</computeroutput> in the guest to
3496	zero the free disk space before compressing the virtual disk
3497	image. For Linux, use the <code>zerofree</code> utility which
3498	supports ext2/ext3 filesystems. For Mac OS X guests, use the
3499	<code>diskutil secureErase freespace 0 /</code> command line
3500	from an elevated Terminal.</para>
3501
3502	<para>Please note that compacting is currently only available for
3503	VDI images. A similar effect can be achieved by zeroing out free
3504	blocks and then cloning the disk to any other dynamically allocated
3505	format. You can use this workaround until compacting is also
3506	supported for disk formats other than VDI.</para>
3507	</listitem>
3508
3509	<listitem>
3510	<para>The <computeroutput>--resize x</computeroutput> option (where x
3511	is the desired new total space in <emphasis role="bold">megabytes</emphasis>)
3512	allows you to change the capacity of an existing image; this adjusts the
3513	<emphasis>logical</emphasis> size of a virtual disk without affecting
3514	the physical size much.<footnote>
3515	<para>Image resizing was added with VirtualBox 4.0.</para>
3516	</footnote> This currently works only for VDI and VHD formats, and only
3517	for the dynamically allocated variants, and can only be used to expand
3518	(not shrink) the capacity.
3519	For example, if you originally created a 10G disk which is now full,
3520	you can use the <computeroutput>--resize 15360</computeroutput>
3521	command to change the capacity to 15G (15,360MB) without having to create a new
3522	image and copy all data from within a virtual machine. Note however that
3523	this only changes the drive capacity; you will typically next need to use
3524	a partition management tool inside the guest to adjust the main partition
3525	to fill the drive.</para><para>The <computeroutput>--resizebyte x</computeroutput>
3526	option does almost the same thing, except that x is expressed in bytes
3527	instead of megabytes.</para>
3528	</listitem>
3529
3530	<listitem>
3531	<para>The <computeroutput>--move <dest></computeroutput> option
3532	can be used to move an image to a different location <dest> on the host file system,
3533	specified by either the relative path to the current directory or absolute path.</para>
3534	</listitem>
3535	</itemizedlist></para>
3536	</sect1>
3537
3538	<sect1 id="vboxmanage-clonevdi">
3539	<title>VBoxManage clonemedium</title>
3540
3541	<para>This command duplicates a virtual disk/DVD/floppy medium to a
3542	new medium (usually an image file) with a new unique identifier (UUID).
3543	The new image can be transferred to another host system or imported into
3544	VirtualBox again using the Virtual Media Manager; see <xref linkend="vdis" />
3545	and <xref linkend="cloningvdis" />. The syntax is as follows:</para>
3546
3547	<screen>VBoxManage clonemedium [disk\|dvd\|floppy] <uuid\|inputfile> <uuid\|outputfile>
3548
3549	[--format VDI\|VMDK\|VHD\|RAW\|<other>]
3550	[--variant Standard,Fixed,Split2G,Stream,ESX]
3551	[--existing]</screen>
3552
3553
3554	<para>The medium to clone as well as the target image must be described
3555	either by its UUIDs (if the mediums are registered) or by its filename.
3556	Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
3557	(see <xref linkend="vboxmanage-list" /> for more information).
3558	A filename must be specified as valid path, either as an absolute path or
3559	as a relative path starting from the current directory.</para>
3560	<para>The following options are available:<glosslist>
3561	<glossentry>
3562	<glossterm><computeroutput>--format</computeroutput></glossterm>
3563
3564	<glossdef>
3565	<para>Allow to choose a file format for the output file different
3566	from the file format of the input file.</para>
3567	</glossdef>
3568	</glossentry>
3569
3570	<glossentry>
3571	<glossterm><computeroutput>--variant</computeroutput></glossterm>
3572
3573	<glossdef>
3574	<para>Allow to choose a file format variant for the output file.
3575	It is a comma-separated list of variant flags. Not all
3576	combinations are supported, and specifying inconsistent flags will
3577	result in an error message.</para>
3578	</glossdef>
3579	</glossentry>
3580
3581	<glossentry>
3582	<glossterm><computeroutput>--existing</computeroutput></glossterm>
3583
3584	<glossdef>
3585	<para>Perform the clone operation to an already existing
3586	destination medium. Only the portion of the source medium which
3587	fits into the destination medium is copied. This means if the
3588	destination medium is smaller than the source only a part of it is
3589	copied, and if the destination medium is larger than the source
3590	the remaining part of the destination medium is unchanged.</para>
3591	</glossdef>
3592	</glossentry>
3593	</glosslist> <note>
3594	<para>For compatibility with earlier versions of VirtualBox, the
3595	"clonevdi" and "clonehd" commands are still supported and mapped
3596	internally to the "clonehd disk" command.</para>
3597	</note></para>
3598	</sect1>
3599
3600	<sect1 id="vboxmanage-mediumproperty">
3601	<title>VBoxManage mediumproperty</title>
3602
3603	<para>This command sets up, gets or deletes a medium property.
3604	The syntax is as follows:</para>
3605
3606	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] set <uuid\|filename>
3607	<property> <value></screen>
3608
3609
3610	<para><itemizedlist>
3611	<listitem>
3612	<para>Use <computeroutput><disk\|dvd\|floppy></computeroutput> to optionally specify
3613	the type of medium: disk (hard drive), dvd or floppy.</para>
3614	</listitem>
3615
3616	<listitem>
3617	<para>Use <computeroutput><uuid\|filename></computeroutput> to supply either the uuid
3618	or absolute path of the medium/image to be encrypted.</para>
3619	</listitem>
3620
3621	<listitem>
3622	<para>Use <computeroutput><property></computeroutput> to supply the name of the
3623	property.</para>
3624	</listitem>
3625
3626	<listitem>
3627	<para>Use <computeroutput><value></computeroutput> to supply the property value.</para>
3628	</listitem>
3629	</itemizedlist></para>
3630
3631	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] get <uuid\|filename>
3632	<property></screen>
3633	<para><itemizedlist>
3634	<listitem>
3635	<para>Use <computeroutput><disk\|dvd\|floppy></computeroutput> to optionally specify
3636	the type of medium: disk (hard drive), dvd or floppy.</para>
3637	</listitem>
3638
3639	<listitem>
3640	<para>Use <computeroutput><uuid\|filename></computeroutput> to supply either the uuid
3641	or absolute path of the medium/image to be encrypted.</para>
3642	</listitem>
3643
3644	<listitem>
3645	<para>Use <computeroutput><property></computeroutput> to supply the name of the
3646	property.</para>
3647	</listitem>
3648	</itemizedlist></para>
3649
3650	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] delete <uuid\|filename>
3651	<property></screen>
3652
3653
3654	<para><itemizedlist>
3655	<listitem>
3656	<para>Use <computeroutput><disk\|dvd\|floppy></computeroutput> to optionally specify
3657	the type of medium: disk (hard drive), dvd or floppy.</para>
3658	</listitem>
3659
3660	<listitem>
3661	<para>Use <computeroutput><uuid\|filename></computeroutput> to supply either the uuid
3662	or absolute path of the medium/image.</para>
3663	</listitem>
3664
3665	<listitem>
3666	<para>Use <computeroutput><property></computeroutput> to supply the name of the
3667	property.</para>
3668	</listitem>
3669	</itemizedlist></para>
3670	</sect1>
3671
3672	<sect1 id="vboxmanage-encryptmedium">
3673	<title>VBoxManage encryptmedium</title>
3674
3675	<para>This command is used to create a DEK encrypted medium/image.
3676	See <xref linkend="diskencryption-encryption" />" for details.</para>
3677
3678	<para>The syntax is as follows:</para>
3679
3680	<screen>VBoxManage encryptmedium <uuid\|filename>
3681	[--newpassword <file\|->]
3682	[--oldpassword <file\|->]
3683	[--cipher <cipher id>]
3684	[--newpasswordid <password id>]</screen>
3685
3686	<para><itemizedlist>
3687	<listitem>
3688	<para>use <computeroutput><uuid\|filename></computeroutput> to supply the
3689	uuid or absolute path of the medium/image to be encrypted.</para>
3690	</listitem>
3691
3692	<listitem>
3693	<para>Use <computeroutput>--newpassword <file\|-></computeroutput> to supply a new
3694	encryption password; either specify the absolute pathname of a password file on the host operating system,
3695	or <computeroutput>-</computeroutput> to prompt you for the password on the command line.
3696	Always use the <computeroutput>--newpasswordid</computeroutput> option with this option.</para>
3697	</listitem>
3698
3699	<listitem>
3700	<para>use <computeroutput>--oldpassword <file\|-></computeroutput> to supply any old
3701	encryption password; either specify the absolute pathname of a password file on the host operating system,
3702	or <computeroutput>-</computeroutput> to prompt you for the old password on the command line.</para>
3703
3704	<para>Use this option to gain access to an encrypted medium/image to change its password using
3705	<computeroutput>--newpassword</computeroutput> and/or change its encryption using
3706	<computeroutput>--cipher</computeroutput>.</para>
3707	</listitem>
3708
3709	<listitem>
3710	<para>Use <computeroutput>--cipher <cipher></computeroutput> to specify the cipher to use for
3711	encryption; this can be either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
3712	<computeroutput>AES-AXTS256-PLAIN64</computeroutput>.</para>
3713
3714	<para>Use this option to change any existing encryption on the medium/image, or setup new encryption on
3715	it for the 1st time.</para>
3716	</listitem>
3717
3718	<listitem>
3719	<para>Use <computeroutput>--newpasswordid <password id></computeroutput> to supply the new password identifier.
3720	This can be freely chosen by the user, and is used for correct identification when supplying multiple
3721	passwords during VM startup.</para>
3722
3723	<para>If the user uses the same password when encrypting multiple images and also the same password identifier, the
3724	user needs to supply the password only once during VM startup.</para>
3725	</listitem>
3726	</itemizedlist></para>
3727
3728	</sect1>
3729
3730	<sect1 id="vboxmanage-checkmediumpwd">
3731
3732	<title>VBoxManage checkmediumpwd</title>
3733
3734	<para>This command is used to check the current encryption password on a DEK encrypted medium/image.
3735	See <xref linkend="diskencryption-encryption" />" for details.</para>
3736
3737	<para>The syntax is as follows:</para>
3738
3739	<screen>VBoxManage checkmediumpwd <uuid\|filename>
3740	<pwd file\|-></screen>
3741	<para><itemizedlist>
3742	<listitem>
3743	<para>Use <computeroutput><uuid\|filename></computeroutput> to supply the uuid or absolute path of the
3744	medium/image to be checked.</para>
3745	</listitem>
3746
3747	<listitem>
3748	<para>Use <computeroutput><pwd file\|-></computeroutput> to supply the password identifier to be checked. Either
3749	specify the absolute pathname of a password file on the host operating system, or <computeroutput>-</computeroutput> to
3750	prompt you for the password on the command line.</para>
3751	</listitem>
3752	</itemizedlist></para>
3753
3754	</sect1>
3755
3756	<sect1>
3757	<title>VBoxManage convertfromraw</title>
3758
3759	<para>This command converts a raw disk image to a VirtualBox Disk Image
3760	(VDI) file. The syntax is as follows:</para>
3761
3762	<screen>VBoxManage convertfromraw <filename> <outputfile>
3763	[--format VDI\|VMDK\|VHD]
3764	[--variant Standard,Fixed,Split2G,Stream,ESX]
3765	[--uuid <uuid>]
3766	VBoxManage convertfromraw stdin <outputfile> <bytes>
3767	[--format VDI\|VMDK\|VHD]
3768	[--variant Standard,Fixed,Split2G,Stream,ESX]
3769	[--uuid <uuid>]</screen>
3770
3771	<para>where the parameters mean:<glosslist>
3772	<glossentry>
3773	<glossterm><computeroutput>--bytes</computeroutput></glossterm>
3774
3775	<glossdef>
3776	<para>The size of the image file, in bytes, provided through
3777	stdin.</para>
3778	</glossdef>
3779	</glossentry>
3780
3781	<glossentry>
3782	<glossterm><computeroutput>--format</computeroutput></glossterm>
3783
3784	<glossdef>
3785	<para>Select the disk image format to create. Default is
3786	VDI. Other options are VMDK and VHD.</para>
3787	</glossdef>
3788	</glossentry>
3789
3790	<glossentry>
3791	<glossterm><computeroutput>--variant</computeroutput></glossterm>
3792
3793	<glossdef>
3794	<para>Allow to choose a file format variant for the output file.
3795	It is a comma-separated list of variant flags. Not all
3796	combinations are supported, and specifying inconsistent flags will
3797	result in an error message.</para>
3798	</glossdef>
3799	</glossentry>
3800
3801	<glossentry>
3802	<glossterm><computeroutput>--uuid</computeroutput></glossterm>
3803
3804	<glossdef>
3805	<para>Allow to specifiy the UUID of the output file.</para>
3806	</glossdef>
3807	</glossentry>
3808	</glosslist> The second form forces VBoxManage to read the content for
3809	the disk image from standard input (useful for using that command in a
3810	pipe).</para>
3811
3812	<para><note>
3813	<para>For compatibility with earlier versions of VirtualBox, the
3814	"convertdd" command is also supported and mapped internally to the
3815	"convertfromraw" command.</para>
3816	</note></para>
3817	</sect1>
3818
3819	<sect1>
3820	<title>VBoxManage getextradata/setextradata</title>
3821
3822	<para>These commands let you attach and retrieve string data to a virtual
3823	machine or to a VirtualBox configuration (by specifying
3824	<computeroutput>global</computeroutput> instead of a virtual machine
3825	name). You must specify a key (as a text string) to associate the data
3826	with, which you can later use to retrieve it. For example:</para>
3827
3828	<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
3829	VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
3830
3831	<para>would associate the string "2006.01.01" with the key installdate for
3832	the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
3833	could retrieve the information as follows:</para>
3834
3835	<screen>VBoxManage getextradata Fedora5 installdate</screen>
3836
3837	<para>which would return</para>
3838
3839	<screen>VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
3840	(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
3841	All rights reserved.
3842
3843	Value: 2006.01.01</screen>
3844
3845	<para>You could retrieve the information for all keys as follows:</para>
3846
3847	<screen>VBoxManage getextradata Fedora5 enumerate</screen>
3848
3849	<para>To remove a key, the <computeroutput>setextradata</computeroutput>
3850	command must be run without specifying data (only the key), for example:
3851	</para>
3852
3853	<screen>VBoxManage setextradata Fedora5 installdate</screen>
3854
3855	</sect1>
3856
3857	<sect1 id="vboxmanage-setproperty">
3858	<title>VBoxManage setproperty</title>
3859
3860	<para>This command is used to change global settings which affect the
3861	entire VirtualBox installation. Some of these correspond to the settings
3862	in the "Global settings" dialog in the graphical user interface. The
3863	following properties are available:<glosslist>
3864	<glossentry>
3865	<glossterm><computeroutput>machinefolder</computeroutput></glossterm>
3866	<glossdef>
3867	<para>This specifies the default folder in which virtual machine
3868	definitions are kept; see <xref linkend="vboxconfigdata" /> for
3869	details.</para>
3870	</glossdef>
3871	</glossentry>
3872
3873	<glossentry>
3874	<glossterm><computeroutput>hwvirtexclusive</computeroutput></glossterm>
3875	<glossdef><para>This specifies whether VirtualBox will make exclusive use of
3876	the hardware virtualization extensions (Intel VT-x or AMD-V) of the
3877	host system's processor; see <xref linkend="hwvirt" />. If you wish to
3878	share these extensions with other hypervisors running at the same time,
3879	you must disable this setting. Doing so has negative performance implications.
3880	</para></glossdef>
3881	</glossentry>
3882
3883	<glossentry>
3884	<glossterm><computeroutput>vrdeauthlibrary</computeroutput></glossterm>
3885
3886	<glossdef>
3887	<para>This specifies which library to use when "external"
3888	authentication has been selected for a particular virtual machine;
3889	see <xref linkend="vbox-auth" /> for details.</para>
3890	</glossdef>
3891	</glossentry>
3892
3893	<glossentry>
3894	<glossterm><computeroutput>websrvauthlibrary</computeroutput></glossterm>
3895
3896	<glossdef>
3897	<para>This specifies which library the web service uses to
3898	authenticate users. For details about the VirtualBox web service,
3899	please refer to the separate VirtualBox SDK reference (see <xref
3900	linkend="VirtualBoxAPI" />).</para>
3901	</glossdef>
3902	</glossentry>
3903
3904	<glossentry>
3905	<glossterm><computeroutput>vrdeextpack</computeroutput></glossterm>
3906
3907	<glossdef>
3908	<para>This specifies which library implements the VirtualBox
3909	Remote Desktop Extension.</para>
3910	</glossdef>
3911	</glossentry>
3912
3913	<glossentry>
3914	<glossterm><computeroutput>loghistorycount</computeroutput></glossterm>
3915
3916	<glossdef>
3917	<para>This selects how many rotated (old) VM logs are kept.</para>
3918	</glossdef>
3919	</glossentry>
3920
3921	<glossentry>
3922	<glossterm><computeroutput>autostartdbpath</computeroutput></glossterm>
3923
3924	<glossdef>
3925	<para>This selects the path to the autostart database. See
3926	<xref linkend="autostart" />.</para>
3927	</glossdef>
3928	</glossentry>
3929
3930	<glossentry>
3931	<glossterm><computeroutput>defaultfrontend</computeroutput></glossterm>
3932
3933	<glossdef>
3934	<para>This selects the global default VM frontend setting. See
3935	<xref linkend="vboxmanage-startvm" />.</para>
3936	</glossdef>
3937	</glossentry>
3938
3939	<glossentry>
3940	<glossterm><computeroutput>logginglevel</computeroutput></glossterm>
3941
3942	<glossdef>
3943	<para>This configures the VBoxSVC release logging details.<footnote>
3944	<para><ulink url="http://www.virtualbox.org/wiki/VBoxLogging">http://www.virtualbox.org/wiki/VBoxLogging</ulink>.</para>
3945	</footnote>
3946	</para>
3947	</glossdef>
3948	</glossentry>
3949	</glosslist></para>
3950	</sect1>
3951
3952	<sect1>
3953	<title>VBoxManage usbfilter add/modify/remove</title>
3954
3955	<screen>VBoxManage usbfilter add <index,0-N>
3956	--target <uuid\|vmname>global
3957	--name <string>
3958	--action ignore\|hold (global filters only)
3959	[--active yes\|no (yes)]
3960	[--vendorid <XXXX> (null)]
3961	[--productid <XXXX> (null)]
3962	[--revision <IIFF> (null)]
3963	[--manufacturer <string> (null)]
3964	[--product <string> (null)]
3965	[--remote yes\|no (null, VM filters only)]
3966	[--serialnumber <string> (null)]
3967	[--maskedinterfaces <XXXXXXXX>]
3968	</screen>
3969
3970	<screen>VBoxManage usbfilter modify <index,0-N>
3971	--target <uuid\|vmname>global
3972	[--name <string>]
3973	[--action ignore\|hold (global filters only)]
3974	[--active yes\|no]
3975	[--vendorid <XXXX>]
3976	[--productid <XXXX>]
3977	[--revision <IIFF>]
3978	[--manufacturer <string>]
3979	[--product <string>]
3980	[--remote yes\|no (null, VM filters only)]
3981	[--serialnumber <string>]
3982	[--maskedinterfaces <XXXXXXXX>]
3983	</screen>
3984
3985	<screen>VBoxManage usbfilter remove <index,0-N>
3986	--target <uuid\|vmname>global
3987	</screen>
3988
3989	<para>The <computeroutput>usbfilter</computeroutput> commands are used for
3990	working with USB filters in virtual machines, or global filters which
3991	affect the whole VirtualBox setup. Global filters are applied before
3992	machine-specific filters, and may be used to prevent devices from being
3993	captured by any virtual machine. Global filters are always applied in a
3994	particular order, and only the first filter which fits a device is
3995	applied. So for example, if the first global filter says to hold (make
3996	available) a particular Kingston memory stick device and the second to
3997	ignore all Kingston devices, that memory stick will be available to any
3998	machine with an appropriate filter, but no other Kingston device
3999	will.</para>
4000
4001	<para>When creating a USB filter using <computeroutput>usbfilter
4002	add</computeroutput>, you must supply three or four mandatory parameters.
4003	The index specifies the position in the list at which the filter should be
4004	placed. If there is already a filter at that position, then it and the
4005	following ones will be shifted back one place. Otherwise the new filter
4006	will be added onto the end of the list. The
4007	<computeroutput>target</computeroutput> parameter selects the virtual
4008	machine that the filter should be attached to or use "global" to apply it
4009	to all virtual machines. <computeroutput>name</computeroutput> is a name
4010	for the new filter and for global filters,
4011	<computeroutput>action</computeroutput> says whether to allow VMs
4012	access to devices that fit the filter description ("hold") or not to give
4013	them access ("ignore"). In addition, you should specify parameters to
4014	filter by. You can find the parameters for devices attached to your system
4015	using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
4016	you can specify whether the filter should be active, and for local
4017	filters, whether they are for local devices, remote (over an RDP
4018	connection) or either.</para>
4019
4020	<para>When you modify a USB filter using <computeroutput>usbfilter
4021	modify</computeroutput>, you must specify the filter by index (see the
4022	output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
4023	find global filter indexes and that of <computeroutput>VBoxManage
4024	showvminfo</computeroutput> to find indexes for individual machines) and
4025	by target, which is either a virtual machine or "global". The properties
4026	which can be changed are the same as for <computeroutput>usbfilter
4027	add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
4028	remove</computeroutput> and specify the index and the target.</para>
4029
4030	<para>The following is a list of the additional
4031	<computeroutput>usbfilter add</computeroutput> and
4032	<computeroutput>usbfilter modify</computeroutput> options, with detailed
4033	explanations on how to use them.</para>
4034
4035	<para><itemizedlist>
4036	<listitem>
4037	<para><computeroutput>--action ignore\|hold</computeroutput>Specifies
4038	whether devices that fit the filter description are allowed access by
4039	machines ("hold"), or have access denied ("ignore"). Applies to
4040	global filters only.</para>
4041	</listitem>
4042
4043	<listitem>
4044	<para><computeroutput>--active yes\|no</computeroutput>Specifies whether
4045	the USB Filter is active or temporarily disabled. For
4046	<computeroutput>usbfilter create</computeroutput> the default is
4047	active.</para>
4048	</listitem>
4049
4050	<listitem>
4051	<para><computeroutput>--vendorid <XXXX>\|""</computeroutput>Specifies
4052	a vendor ID filter - the string representation for the exact matching
4053	has the form XXXX, where X is the hex digit (including leading zeroes).</para>
4054	</listitem>
4055
4056	<listitem>
4057	<para><computeroutput>--productid <XXXX>\|""</computeroutput>Specifies
4058	a product ID filter - The string representation for the exact matching has
4059	the form XXXX, where X is the hex digit (including leading zeroes).</para>
4060	</listitem>
4061
4062	<listitem>
4063	<para><computeroutput>--revision <IIFF>\|""</computeroutput>Specifies
4064	a revision ID filter - the string representation for the exact matching has
4065	the form IIFF, where I is the decimal digit of the integer part of the revision,
4066	and F is the decimal digit of its fractional part (including leading and trailing zeros).
4067	Note that for interval filters, it's best to use the hex form, because the revision is
4068	stored as a 16 bit packed BCD value; so the expression int:0x0100-0x0199 will match
4069	any revision from 1.0 to 1.99 inclusive.</para>
4070	</listitem>
4071
4072	<listitem>
4073	<para><computeroutput>--manufacturer <string>\|""</computeroutput>Specifies
4074	a manufacturer ID filter, as a string.</para>
4075	</listitem>
4076
4077	<listitem>
4078	<para><computeroutput>--product <string>\|""</computeroutput>Specifies
4079	a product ID filter, as a string.</para>
4080	</listitem>
4081
4082	<listitem>
4083	<para><computeroutput>--remote yes\|no""</computeroutput>Specifies
4084	a remote filter - indicating whether the device is physically connected to a
4085	remote VRDE client or to a local host machine. Applies to VM filters only.</para>
4086	</listitem>
4087
4088	<listitem>
4089	<para><computeroutput>--serialnumber <string>\|""</computeroutput>Specifies
4090	a serial number filter, as a string.</para>
4091	</listitem>
4092
4093	<listitem>
4094	<para><computeroutput>--maskedinterfaces <XXXXXXXX></computeroutput>Specifies
4095	a masked interface filter, for hiding one or more USB interfaces from the guest.
4096	The value is a bit mask where the set bits correspond to the USB interfaces that
4097	should be hidden, or masked off. This feature only works on Linux hosts.</para>
4098	</listitem>
4099	</itemizedlist></para>
4100	</sect1>
4101
4102	<sect1 id="vboxmanage-sharedfolder">
4103	<title>VBoxManage sharedfolder add/remove</title>
4104
4105	<screen>
4106	VBoxManage sharedfolder add <uuid\|vmname>
4107	--name <name> --hostpath <hostpath>
4108	[--transient] [--readonly] [--automount]
4109	</screen>
4110
4111
4112	<para>This command allows you to share folders on the host computer with
4113	guest operating systems. For this, the guest systems must have a version
4114	of the VirtualBox Guest Additions installed which supports this
4115	functionality.</para>
4116
4117	<para>Parameters are:</para>
4118
4119	<para><itemizedlist>
4120	<listitem>
4121	<para><computeroutput><uuid\|vmname></computeroutput>
4122	Specifies the UUID or name of the VM whose guest operating system will be
4123	sharing folders with the host computer. Mandatory.</para>
4124	</listitem>
4125
4126	<listitem>
4127	<para><computeroutput>--name <name></computeroutput>
4128	Specifies the name of the share. Each share has a unique name within the
4129	namespace of the host operating system. Mandatory.</para>
4130	</listitem>
4131
4132	<listitem>
4133	<para><computeroutput>-hostpath <hostpath></computeroutput>
4134	Specifies the absolute path on the host operating system of the
4135	folder/directory to be shared with the guest operating system.
4136	Mandatory.</para>
4137	</listitem>
4138
4139	<listitem>
4140	<para><computeroutput>-transient</computeroutput>
4141	Specifies that the share is 'transient', meaning that it can be added
4142	and removed at runtime and does not persist after the VM has stopped.
4143	Optional.</para>
4144	</listitem>
4145
4146	<listitem>
4147	<para><computeroutput>-readonly</computeroutput>
4148	Specifies that the share has only read-only access to files at the host path.</para>
4149
4150	<para>By default, shared folders have read/write access to the files at the host
4151	path. More specifically, on Linux distros - shared folders are mounted with
4152	770 io permissions with root user and vboxsf as the group, and using this option
4153	the io permissions change to 700. Optional.</para>
4154	</listitem>
4155
4156	<listitem>
4157	<para><computeroutput>-automount</computeroutput>
4158	Specifies that the share will be automatically mounted. On Linux distros, this will
4159	be to either /media/USER/sf_<name> or /media/sf_<name> - depending on
4160	your guest OS. Where <name> is the share name. Optional.</para>
4161	</listitem>
4162	</itemizedlist></para>
4163
4164	<screen>
4165	VBoxManage sharedfolder remove <uuid\|vmname>
4166	--name <name> [--transient]
4167
4168	</screen>
4169
4170	<para>This command allows you to delete shared folders on the host computer shares with
4171	the guest operating systems. For this, the guest systems must have a version
4172	of the VirtualBox Guest Additions installed which supports this
4173	functionality.</para>
4174
4175	<para>Parameters are:</para>
4176
4177	<para><itemizedlist>
4178	<listitem>
4179	<para><computeroutput><uuid\|vmname></computeroutput>
4180	Specifies the UUID or name of the VM whose guest operating system is
4181	sharing folders with the host computer. Mandatory.</para>
4182	</listitem>
4183
4184	<listitem>
4185	<para><computeroutput>--name <name></computeroutput>
4186	Specifies the name of the share to be removed. Each share has a unique name within the
4187	namespace of the host operating system. Mandatory.</para>
4188	</listitem>
4189
4190	<listitem>
4191	<para><computeroutput>-transient</computeroutput>
4192	Specifies that the share is 'transient', meaning that it can be added
4193	and removed at runtime and does not persist after the VM has stopped.
4194	Optional.</para>
4195	</listitem>
4196	</itemizedlist></para>
4197
4198
4199	<para>Shared folders are described in detail in <xref
4200	linkend="sharedfolders" />.</para>
4201	</sect1>
4202
4203	<sect1 id="vboxmanage-guestproperty">
4204	<title>VBoxManage guestproperty</title>
4205
4206	<para>The "guestproperty" commands allow you to get or set properties of a
4207	running virtual machine. Please see <xref linkend="guestadd-guestprops" />
4208	for an introduction. As explained there, guest properties are arbitrary
4209	key/value string pairs which can be written to and read from by either the
4210	guest or the host, so they can be used as a low-volume communication
4211	channel for strings, provided that a guest is running and has the Guest
4212	Additions installed. In addition, a number of values whose keys begin with
4213	"/VirtualBox/" are automatically set and maintained by the Guest
4214	Additions.</para>
4215
4216	<para>The following subcommands are available (where
4217	<computeroutput><vm></computeroutput>, in each case, can either be a
4218	VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
4219	<listitem>
4220	<para><computeroutput>enumerate <vm> [--patterns
4221	<pattern>]</computeroutput>: This lists all the guest
4222	properties that are available for the given VM, including the value.
4223	This list will be very limited if the guest's service process cannot
4224	be contacted, e.g. because the VM is not running or the Guest
4225	Additions are not installed.</para>
4226
4227	<para>If <computeroutput>--patterns <pattern></computeroutput>
4228	is specified, it acts as a filter to only list properties that match
4229	the given pattern. The pattern can contain the following wildcard
4230	characters:<itemizedlist>
4231	<listitem>
4232	<para><computeroutput>*</computeroutput> (asterisk):
4233	represents any number of characters; for example,
4234	"<computeroutput>/VirtualBox*</computeroutput>" would match
4235	all properties beginning with "/VirtualBox".</para>
4236	</listitem>
4237
4238	<listitem>
4239	<para><computeroutput>?</computeroutput> (question mark):
4240	represents a single arbitrary character; for example,
4241	"<computeroutput>fo?</computeroutput>" would match both "foo"
4242	and "for".</para>
4243	</listitem>
4244
4245	<listitem>
4246	<para><computeroutput>\|</computeroutput> (pipe symbol): can be
4247	used to specify multiple alternative patterns; for example,
4248	"<computeroutput>s\|t</computeroutput>" would match anything
4249	starting with either "s" or "t".</para>
4250	</listitem>
4251	</itemizedlist></para>
4252	</listitem>
4253
4254	<listitem>
4255	<para><computeroutput>get <vm> <property>
4256	</computeroutput>: This
4257	retrieves the value of a single property only. If the property
4258	cannot be found (e.g. because the guest is not running), this will
4259	print <screen>No value set!</screen></para>
4260	</listitem>
4261
4262	<listitem>
4263	<para><computeroutput>set <vm> <property> [<value>
4264	[--flags <flags>]]</computeroutput>: This allows you to set a
4265	guest property by specifying the key and value. If
4266	<computeroutput><value></computeroutput> is omitted, the
4267	property is deleted. With <computeroutput>--flags</computeroutput>
4268	you can optionally specify additional behavior (you can combine
4269	several by separating them with commas):<itemizedlist>
4270	<listitem>
4271	<para><computeroutput>TRANSIENT</computeroutput>: the value
4272	will not be stored with the VM data when the VM exits;</para>
4273	</listitem>
4274
4275	<listitem>
4276	<para><computeroutput>TRANSRESET</computeroutput>: the value
4277	will be deleted as soon as the VM restarts and/or exits;</para>
4278	</listitem>
4279
4280	<listitem>
4281	<para><computeroutput>RDONLYGUEST</computeroutput>: the value
4282	can only be changed by the host, but the guest can only read
4283	it;</para>
4284	</listitem>
4285
4286	<listitem>
4287	<para><computeroutput>RDONLYHOST</computeroutput>: reversely,
4288	the value can only be changed by the guest, but the host can
4289	only read it;</para>
4290	</listitem>
4291
4292	<listitem>
4293	<para><computeroutput>READONLY</computeroutput>: a combination
4294	of the two, the value cannot be changed at all.</para>
4295	</listitem>
4296	</itemizedlist></para>
4297	</listitem>
4298
4299	<listitem>
4300	<para><computeroutput>wait <vm> <pattern> --timeout
4301	<timeout></computeroutput>: This waits for a particular value
4302	described by "pattern" to change or to be deleted or created. The
4303	pattern rules are the same as for the "enumerate" subcommand
4304	above.</para>
4305	</listitem>
4306
4307	<listitem>
4308	<para><computeroutput>delete <vm> <property>
4309	</computeroutput>: Deletes a formerly set guest property.
4310	</para></listitem>
4311	</itemizedlist></para>
4312	</sect1>
4313
4314	<sect1 id="vboxmanage-guestcontrol">
4315	<title>VBoxManage guestcontrol</title>
4316
4317	<para>The <computeroutput>guestcontrol</computeroutput> commands enable
4318	control of the guest from the host. Please see <xref
4319	linkend="guestadd-guestcontrol" /> for an introduction.</para>
4320
4321	<para>guestcontrol has two sets of subcommands. The first set requires guest
4322	credentials to be specified, the second does not.</para>
4323
4324	<para>The first set of subcommands is of the form:</para>
4325	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
4326	[--username <name> ]
4327	[--passwordfile <file> \| --password <password>]
4328	[--domain <domain> ]
4329	[-v\|--verbose] [-q\|quiet] ...
4330	</screen>
4331
4332	<para>The "common-options" are:</para>
4333	<screen>
4334	[--username <name> ]
4335	[--passwordfile <file> \| --password <password>]
4336	[--domain <domain> ]
4337	[-v\|--verbose] [-q\|quiet]
4338	</screen>
4339
4340	<para>Where details of the common options for the first set of subcommands are:
4341	<glosslist>
4342
4343	<glossentry>
4344	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4345	<glossdef>
4346	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4347	</glossdef>
4348	</glossentry>
4349
4350	<glossentry>
4351	<glossterm><computeroutput>--username <name></computeroutput></glossterm>
4352	<glossdef><para>Specifies the user name on guest OS under which the process should run. This
4353	user name must already exist on the guest OS. If unspecified, the host user name is used. Optional</para>
4354	</glossdef>
4355	</glossentry>
4356
4357	<glossentry>
4358	<glossterm><computeroutput>--passwordfile <file>\|--password</computeroutput></glossterm>
4359	<glossdef><para>Specifies the absolute path on guest file system of password file containing the
4360	password for the specified user account or password for the specified user account. Optional.
4361	If both are omitted, empty password is assumed.</para></glossdef>
4362	</glossentry>
4363
4364	<glossentry>
4365	<glossterm><computeroutput>--domain <domain></computeroutput></glossterm>
4366	<glossdef><para>User domain for Windows guests. Optional.</para></glossdef>
4367	</glossentry>
4368
4369	<glossentry>
4370	<glossterm><computeroutput>-v\|--verbose</computeroutput></glossterm>
4371	<glossdef><para>Makes the subcommand execution more verbose. Optional</para></glossdef>
4372	</glossentry>
4373
4374	<glossentry>
4375	<glossterm><computeroutput>-q\|--quiet</computeroutput></glossterm>
4376	<glossdef><para>Makes the subcommand execution quieter. Optional.</para></glossdef>
4377	</glossentry>
4378	</glosslist>
4379	</para>
4380
4381	<para>The first set of subcommands: <itemizedlist>
4382	<listitem>
4383	<para><emphasis role="bold"><computeroutput>run</computeroutput></emphasis>
4384	Executes a guest program - forwarding stdout, stderr and stdin to/from the host
4385	until it completes.</para>
4386	<screen>VBoxManage guestcontrol <uuid\|vmname> run [common-options]
4387	--exe <path to executable> [--timeout <msec>]
4388	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
4389	[--ignore-operhaned-processes] [--profile]
4390	[--no-wait-stdout\|--wait-stdout]
4391	[--no-wait-stderr\|--wait-stderr]
4392	[--dos2unix] [--unix2dos]
4393	-- <program/arg0> [argument1] ... [argumentN]]
4394	</screen>
4395	<glosslist>
4396	<glossentry>
4397	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4398	<glossdef>
4399	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4400	</glossdef>
4401	</glossentry>
4402
4403	<glossentry>
4404	<glossterm><computeroutput>--exe <path to executable></computeroutput></glossterm>
4405	<glossdef><para>Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.:
4406	<computeroutput>C:\Windows\System32\calc.exe</computeroutput>.</para>
4407	</glossdef>
4408	</glossentry>
4409
4410	<glossentry>
4411	<glossterm><computeroutput>--timeout <msec></computeroutput></glossterm>
4412	<glossdef>
4413	<para>Specifies the maximum time (microseconds) that the executable can run,
4414	during which VBoxManage receives its output. Optional.
4415	If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.</para>
4416	</glossdef>
4417	</glossentry>
4418
4419	<glossentry>
4420	<glossterm><computeroutput>-E\|--putenv <NAME>=<VALUE>
4421	</computeroutput></glossterm>
4422	<glossdef>
4423	<para>Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.</para>
4424	<para>The guest process is created with the standard default guest OS environment.
4425	Use this option to modify that default environment. To set/modify a variable use:
4426	<computeroutput><NAME>=<VALUE></computeroutput>.
4427	To unset a variable use:
4428	<computeroutput><NAME>=</computeroutput></para>
4429	<para>Any spaces in names/values should be enclosed by quotes. </para>
4430	<para>To set/modify/unset multiple variables, use multiple instances of the
4431	<computeroutput>--E\|--putenv</computeroutput> option. </para>
4432	</glossdef>
4433	</glossentry>
4434
4435	<glossentry>
4436	<glossterm><computeroutput>--unquoted-args</computeroutput></glossterm>
4437	<glossdef>
4438	<para>Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.</para>
4439	</glossdef>
4440	</glossentry>
4441
4442	<glossentry>
4443	<glossterm><computeroutput>--ignore-operhaned-processes</computeroutput></glossterm>
4444	<glossdef>
4445	<para>Ignore orphaned processes. Not yet implemented. Optional.</para>
4446	</glossdef>
4447	</glossentry>
4448
4449	<glossentry>
4450	<glossterm><computeroutput>--profile</computeroutput></glossterm>
4451	<glossdef>
4452	<para>Use Profile. Not yet implemented. Optional.</para>
4453	</glossdef>
4454	</glossentry>
4455
4456	<glossentry>
4457	<glossterm><computeroutput>--no-wait-stdout\|--wait-stdout</computeroutput></glossterm>
4458	<glossdef>
4459	<para>Does not wait/waits until the guest process ends and receives its exit code and reason/flags.
4460	In the case of --wait-stdout - while the process runs, VBoxManage receives its stdout. Optional.</para>
4461	</glossdef>
4462	</glossentry>
4463
4464	<glossentry>
4465	<glossterm><computeroutput>--no-wait-stderr\|--wait-stderr</computeroutput></glossterm>
4466	<glossdef>
4467	<para>Does not wait/waits until the guest process ends and receives its exit code and reason/flags.
4468	In case of --wait-stderr - while the process runs, VBoxManage receives its stderr. Optional.</para>
4469	</glossdef>
4470	</glossentry>
4471
4472	<glossentry>
4473	<glossterm><computeroutput>--dos2unix</computeroutput></glossterm>
4474	<glossdef><para>
4475	Converts output from DOS/Windows guests to UNIX/Linux-compatible line endings
4476	(CR + LF → LF). Not yet implemented. Optional.</para>
4477	</glossdef>
4478	</glossentry>
4479
4480	<glossentry>
4481	<glossterm><computeroutput>--unix2dos</computeroutput></glossterm>
4482	<glossdef><para>
4483	Converts output from a UNIX/Linux guests to DOS/Windows-compatible
4484	line endings (LF → CR + LF). Not yet implemented. Optional.</para>
4485	</glossdef>
4486	</glossentry>
4487
4488	<glossentry>
4489	<glossterm><computeroutput>[-- <program/arg0> [<argument1>] ... [<argumentN>]]</computeroutput></glossterm>
4490	<glossdef>
4491	<para>Specifies program name, followed by one or more arguments to pass to the program. Optional.</para>
4492	<para>Note: Any spaces in arguments should be enclosed by quotes.</para>
4493	</glossdef>
4494	</glossentry>
4495	</glosslist>
4496
4497	<para><note>
4498	<para>On Windows there are certain limitations for graphical
4499	applications; please see <xref linkend="KnownIssues" /> for more
4500	information.</para>
4501	</note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls"
4502	--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"
4503	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
4504	the double backslashes in the second example are only required on
4505	Unix hosts.</para>
4506
4507	<para><note>
4508	<para>For certain commands a user name of an existing user account on the guest
4509	must be specified; anonymous executions are not supported for security reasons. A
4510	user account password, however, is optional and depends on the guest's OS security
4511	policy or rules. If no password is specified for a given user name, an empty password
4512	will be used. On certain OSes like Windows the security policy may needs to be adjusted
4513	in order to allow user accounts with an empty password set. Also, global domain rules might
4514	apply and therefore cannot be changed.</para>
4515	</note></para>
4516
4517	<para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
4518	to serve up to 5 guest processes at a time. If a new guest process gets started
4519	which would exceed this limit, the oldest not running guest process will be discarded
4520	in order to be able to run that new process. Also, retrieving output from this
4521	old guest process will not be possible anymore then. If all 5 guest processes
4522	are still active and running, starting a new guest process will result in an
4523	appropriate error message.</para>
4524
4525	<para>To raise or lower the guest process execution limit, either the guest
4526	property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
4527	or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
4528	needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
4529	guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
4530	</listitem>
4531
4532	<listitem>
4533	<para><emphasis role="bold"><computeroutput>start</computeroutput></emphasis>
4534	Executes a guest program until it completes.</para>
4535	<screen>VBoxManage guestcontrol <uuid\|vmname> start [common-options]
4536	[--exe <path to executable>] [--timeout <msec>]
4537	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
4538	[--ignore-operhaned-processes] [--profile]
4539	-- <program/arg0> [argument1] ... [argumentN]]
4540	</screen>
4541
4542	<para>Where the options are: <glosslist>
4543	<glossentry>
4544	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4545	<glossdef>
4546	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4547	</glossdef>
4548	</glossentry>
4549
4550	<glossentry>
4551	<glossterm><computeroutput>--exe <path to executable></computeroutput></glossterm>
4552	<glossdef><para>Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.:
4553	<computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
4554	</glossdef>
4555	</glossentry>
4556
4557	<glossentry>
4558	<glossterm><computeroutput>--timeout <msec></computeroutput></glossterm>
4559	<glossdef>
4560	<para>Specifies the maximum time (microseconds) that the executable can run. Optional.
4561	If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.</para>
4562	</glossdef>
4563	</glossentry>
4564
4565	<glossentry>
4566	<glossterm><computeroutput>-E\|--putenv <NAME>=<VALUE>
4567	</computeroutput></glossterm>
4568	<glossdef>
4569	<para>Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.</para>
4570	<para>The guest process is created with the standard default guest OS environment.
4571	Use this option to modify that default environment. To set/modify a variable use:
4572	<computeroutput><NAME>=<VALUE></computeroutput>.
4573	To unset a variable use:
4574	<computeroutput><NAME>=</computeroutput></para>
4575	<para>Any spaces in names/values should be enclosed by quotes. </para>
4576	<para>To set/modify/unset multiple variables, use multiple instances of the
4577	<computeroutput>--E\|--putenv</computeroutput> option. </para>
4578	</glossdef>
4579	</glossentry>
4580
4581	<glossentry>
4582	<glossterm><computeroutput>--unquoted-args</computeroutput></glossterm>
4583	<glossdef>
4584	<para>Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.</para>
4585	</glossdef>
4586	</glossentry>
4587
4588	<glossentry>
4589	<glossterm><computeroutput>--ignore-operhaned-processes</computeroutput></glossterm>
4590	<glossdef>
4591	<para>Ignores orphaned processes. Not yet implemented. Optional.</para>
4592	</glossdef>
4593	</glossentry>
4594
4595	<glossentry>
4596	<glossterm><computeroutput>--profile</computeroutput></glossterm>
4597	<glossdef>
4598	<para>Use a profile. Not yet implemented. Optional.</para>
4599	</glossdef>
4600	</glossentry>
4601
4602	<glossentry>
4603	<glossterm><computeroutput>[-- <program/arg0> [<argument1>] ... [<argumentN>]]</computeroutput></glossterm>
4604	<glossdef>
4605	<para>Specifies program name, followed by one or more arguments to pass to the program. Optional.</para>
4606	<para>Note: Any spaces in arguments should be enclosed by quotes.</para>
4607	</glossdef>
4608	</glossentry>
4609	</glosslist></para>
4610
4611	<para><note>
4612	<para>On Windows there are certain limitations for graphical
4613	applications; please see <xref linkend="KnownIssues" /> for more
4614	information.</para>
4615	</note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls"
4616	--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"
4617	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
4618	the double backslashes in the second example are only required on
4619	Unix hosts.</para>
4620
4621	<para><note>
4622	<para>For certain commands a user name of an existing user account on the guest
4623	must be specified; anonymous executions are not supported for security reasons. A
4624	user account password, however, is optional and depends on the guest's OS security
4625	policy or rules. If no password is specified for a given user name, an empty password
4626	will be used. On certain OSes like Windows the security policy may needs to be adjusted
4627	in order to allow user accounts with an empty password set. Also, global domain rules might
4628	apply and therefore cannot be changed.</para>
4629	</note></para>
4630
4631	<para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
4632	to serve up to 5 guest processes at a time. If a new guest process gets started
4633	which would exceed this limit, the oldest not running guest process will be discarded
4634	in order to be able to run that new process. Also, retrieving output from this
4635	old guest process will not be possible anymore then. If all 5 guest processes
4636	are still active and running, starting a new guest process will result in an
4637	appropriate error message.</para>
4638
4639	<para>To raise or lower the guest process execution limit, either the guest
4640	property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
4641	or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
4642	needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
4643	guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
4644	</listitem>
4645
4646	<listitem>
4647	<para><emphasis role="bold"><computeroutput>copyfrom</computeroutput></emphasis>
4648	Copies files from the guest to the host file system.
4649	(Note - only with Guest Additions 4.0 or later installed).</para>
4650
4651	<screen>VBoxManage guestcontrol <uuid\|vmname> copyfrom [common-options]
4652	[--dryrun] [--follow] [--R\|recursive]
4653	--target-directory <host-dst-dir>
4654	<guest-src0> [<guest-src1> [...]] </screen>
4655
4656	<para>Where the parameters are:<glosslist>
4657	<glossentry>
4658	<glossterm><computeroutput><uid\|vmname></computeroutput></glossterm>
4659	<glossdef>
4660	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4661	</glossdef>
4662	</glossentry>
4663
4664	<glossentry>
4665	<glossterm><computeroutput>--dryrun</computeroutput></glossterm>
4666	<glossdef>
4667	<para>Instructs VBoxManage to perform a dry run instead of an actual file copying
4668	operation. Optional. </para>
4669	</glossdef>
4670	</glossentry>
4671
4672	<glossentry>
4673	<glossterm><computeroutput>--follow</computeroutput></glossterm>
4674	<glossdef>
4675	<para>Enables symlink following on the guest file system. Optional.</para>
4676	</glossdef>
4677	</glossentry>
4678
4679	<glossentry>
4680	<glossterm><computeroutput>-R\|--recursive</computeroutput></glossterm>
4681	<glossdef>
4682	<para>Enables recursive copying of files/directories from the specified guest file system
4683	directory. Optional.</para>
4684	</glossdef>
4685	</glossentry>
4686
4687	<glossentry>
4688	<glossterm><computeroutput>--target-directory <host-dst-dir></computeroutput></glossterm>
4689	<glossdef>
4690	<para>Specifies the absolute path of the host file system destination directory. Mandatory. e.g.
4691	<computeroutput>C:\Temp</computeroutput>.</para>
4692	</glossdef>
4693	</glossentry>
4694
4695	<glossentry>
4696	<glossterm><computeroutput><guest-src0> [<guest-src1> [...]]</computeroutput></glossterm>
4697	<glossdef>
4698	<para>Specifies the absolute path(s) of guest file system file(s) to be copied. Mandatory. e.g.
4699	<computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
4700	Wildcards can be used in the expression(s), e.g.
4701	<computeroutput>C:\Windows\System\.dll</computeroutput>.</para>
4702	</glossdef>
4703	</glossentry>
4704	</glosslist>
4705	</para>
4706	</listitem>
4707
4708	<listitem>
4709	<para><emphasis role="bold"><computeroutput>copyto</computeroutput></emphasis>
4710	Copies files from the host to the guest file system.
4711	(Note - only with Guest Additions 4.0 or later installed).</para>
4712
4713	<screen>VBoxManage guestcontrol <uuid\|vmname> copyto [common-options]
4714	[--dryrun] [--follow] [--R\|recursive]
4715	--target-directory <guest-dst>
4716	<host-src0> [<host-src1> [...]] </screen>
4717
4718	<para>Where the parameters are:<glosslist>
4719	<glossentry>
4720	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4721	<glossdef>
4722	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4723	</glossdef>
4724	</glossentry>
4725
4726	<glossentry>
4727	<glossterm><computeroutput>--dryrun</computeroutput></glossterm>
4728	<glossdef>
4729	<para>Instructs VBoxManage to perform a dry run instead of an actual file copying
4730	operation. Optional. </para>
4731	</glossdef>
4732	</glossentry>
4733
4734	<glossentry>
4735	<glossterm><computeroutput>--follow</computeroutput></glossterm>
4736	<glossdef>
4737	<para>Enables symlink following on the host file system. Optional.</para>
4738	</glossdef>
4739	</glossentry>
4740
4741	<glossentry>
4742	<glossterm><computeroutput>-R\|--recursive</computeroutput></glossterm>
4743	<glossdef>
4744	<para>Enables recursive copying of files/directories from the specified host file system
4745	directory(ies). Optional.</para>
4746	</glossdef>
4747	</glossentry>
4748
4749	<glossentry>
4750	<glossterm><computeroutput>--target-directory <guest-dst></computeroutput></glossterm>
4751	<glossdef>
4752	<para>Specifies the absolute path of the guest file system destination directory. Mandatory. e.g.
4753	<computeroutput>C:\Temp</computeroutput>.</para>
4754	</glossdef>
4755	</glossentry>
4756
4757	<glossentry>
4758	<glossterm><computeroutput><host-src0> [<host-src1> [...]]</computeroutput></glossterm>
4759	<glossdef>
4760	<para>Specifies the absolute path(s) of host file system file(s) to be copied. Mandatory. e.g.
4761	<computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
4762	Wildcards can be used in the expression(s), e.g.
4763	<computeroutput>C:\Windows\System\.dll</computeroutput>.</para>
4764	</glossdef>
4765	</glossentry>
4766	</glosslist>
4767	</para>
4768	</listitem>
4769
4770	<listitem>
4771	<para><emphasis role="bold"><computeroutput>md\|mkdir\|createdir\|createdirectory</computeroutput></emphasis>
4772	Creates one or more directory(ies) on the guest file system.
4773	(Note - only with Guest Additions 4.0 or later installed).</para>
4774
4775	<screen>VBoxManage guestcontrol <uuid\|vmname> md\|mkdir\|createdir\|createdirectory [common-options]
4776	[--parents] [--mode <mode>]
4777	<guest-dir0> [<guest-dir1> [...]] </screen>
4778
4779	<para>Where the parameters are: <glosslist>
4780	<glossentry>
4781	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4782	<glossdef>
4783	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4784	</glossdef>
4785	</glossentry>
4786	<glossentry>
4787	<glossterm><computeroutput>--parents</computeroutput></glossterm>
4788	<glossdef>
4789	<para>Creates any absent parent directory(ies) of the specified directory. Optional.</para>
4790	<para>e.g. If specified directory is <computeroutput>D:\Foo\Bar</computeroutput>
4791	and <computeroutput>D:\Foo</computeroutput> is absent, it will
4792	be created. In such a case, had the <computeroutput>--parents</computeroutput>
4793	option not been used, this command would have failed.</para>
4794	</glossdef>
4795	</glossentry>
4796
4797	<glossentry>
4798	<glossterm><computeroutput>--mode <mode></computeroutput></glossterm>
4799	<glossdef>
4800	<para>Specifies the permission mode on the specified directory(ies) (and any parents,
4801	where <computeroutput>--parents</computeroutput> option used).
4802	Currently octal modes (e.g. <computeroutput>0755</computeroutput>) only are
4803	supported.</para>
4804	</glossdef>
4805	</glossentry>
4806
4807	<glossentry>
4808	<glossterm><computeroutput><guest-dir0> [<guest-dir1> [...]]</computeroutput></glossterm>
4809	<glossdef>
4810	<para>Specifies list of absolute path(s) of directory(ies) to be created on
4811	guest file system. Mandatory.
4812	e.g. <computeroutput>D:\Foo\Bar</computeroutput>.</para>
4813	<para>All parent directories must already exist
4814	unless switch <computeroutput>--parents</computeroutput> used.
4815	(e.g. in the above example <computeroutput>D:\Foo</computeroutput>).
4816	The specified user must have sufficient rights to create the
4817	specified directory(ies), and any parents that need
4818	to be created.</para>
4819	</glossdef>
4820	</glossentry>
4821	</glosslist>
4822	</para>
4823	</listitem>
4824
4825	<listitem>
4826	<para><emphasis role="bold"><computeroutput>rmdir\|removedir\|removedirectory</computeroutput></emphasis>
4827	Deletes specified guest file system directories. (Only with installed Guest Additions 4.3.2 and later).</para>
4828
4829	<screen>VBoxManage guestcontrol <uuid\|vmname> rmdir\|removedir\|removedirectory [common-options]
4830	[--recursive\|-R]
4831	<guest-dir0> [<guest-dir1> [...]]
4832	</screen>
4833
4834	<para>Where the parameters are: <glosslist>
4835	<glossentry>
4836	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4837	<glossdef>
4838	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4839	</glossdef>
4840	</glossentry>
4841
4842	<glossentry>
4843	<glossterm><computeroutput>--recursive</computeroutput></glossterm>
4844	<glossdef>
4845	<para>Recursively removes directories and contents. Optional.</para>
4846	</glossdef>
4847	</glossentry>
4848
4849	<glossentry>
4850	<glossterm><computeroutput><guest-dir0> [<guest-dir1> [...]]</computeroutput></glossterm>
4851	<glossdef>
4852	<para>Specifies list of the absolute path(s) of directory(ies) to be deleted on
4853	guest file system. Mandatory. Wildcards are allowed. e.g. <computeroutput>D:\Foo\*Bar</computeroutput>.
4854	The specified user must have sufficient rights to delete the
4855	specified directory(ies).</para>
4856	</glossdef>
4857	</glossentry>
4858	</glosslist></para>
4859	</listitem>
4860
4861	<listitem>
4862	<para><emphasis role="bold"><computeroutput>rm\|removefile</computeroutput></emphasis>
4863	Deletes specified files on the guest file system. (Only with installed Guest
4864	Additions 4.3.2 and later).</para>
4865
4866	<screen>VBoxManage guestcontrol <uuid\|vmname> rm\|removefile [common-options]
4867	[-f\|--force]
4868	<guest-file0> [<guest-file1> [...]] </screen>
4869
4870	<para>Where the parameters are: <glosslist>
4871	<glossentry>
4872	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4873	<glossdef>
4874	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4875	</glossdef>
4876	</glossentry>
4877
4878	<glossentry>
4879	<glossterm><computeroutput>-f\|--force</computeroutput></glossterm>
4880	<glossdef>
4881	<para>Enforce operation (override any requests for confirmations). Optional.</para>
4882	</glossdef>
4883	</glossentry>
4884
4885	<glossentry>
4886	<glossterm><computeroutput><guest-file0> [<guest-file1> [...]]</computeroutput></glossterm>
4887	<glossdef>
4888	<para>Specifies list of absolute path(s) of file(s) to be deleted on guest file system. Mandatory.
4889	Wildcards are allowed. e.g. <computeroutput>D:\Foo\Bar\text*.txt</computeroutput>.
4890	The specified user should have sufficient rights to delete the specified file(s).</para>
4891	</glossdef>
4892	</glossentry>
4893	</glosslist>
4894	</para>
4895	</listitem>
4896
4897	<listitem>
4898	<para><emphasis role="bold"><computeroutput>mv\|move\|ren\|rename</computeroutput></emphasis>
4899	This subcommand renames file(s) and/or directory(ies) on the guest file system. (Only with installed Guest
4900	Additions 4.3.2 and later).</para>
4901
4902	<screen>VBoxManage guestcontrol <uuid\|vmname> mv\|move\|ren\|rename [common-options]
4903	<guest-source0> [<guest-source1> [...]] <guest-dest></screen>
4904
4905	<para>Where the parameters are: <glosslist>
4906	<glossentry>
4907	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4908	<glossdef>
4909	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4910	</glossdef>
4911	</glossentry>
4912
4913	<glossentry>
4914	<glossterm><computeroutput><guest-source0> [<guest-source1> [...]]</computeroutput></glossterm>
4915	<glossdef>
4916	<para>Specifies absolute path(s) of file(s) and/or single directory to be moved/renamed on guest
4917	file system. Mandatory.
4918	Wildcards are allowed in file names(s). The specified user should have sufficient rights to
4919	access the specified file(s).</para>
4920	</glossdef>
4921	</glossentry>
4922
4923	<glossentry>
4924	<glossterm><computeroutput><dest></computeroutput></glossterm>
4925	<glossdef>
4926	<para>Specifies the absolute path of the destination file/directory to which the file(s)
4927	are to be moved. Mandatory. If only one file to be moved, <dest> can be file or directory,
4928	else it must be a directory.
4929	The specified user must have sufficient rights to access the destination file/directory.</para>
4930	</glossdef>
4931	</glossentry>
4932	</glosslist></para>
4933	</listitem>
4934
4935	<listitem>
4936	<para><emphasis role="bold"><computeroutput>mktemp\|createtemp\|createtemporary</computeroutput></emphasis>
4937	Creates a temporary file/directory on the guest file system, to assist subsequent
4938	copying of files from the host to the guest file systems. By default, the file/directory
4939	is created in the guest's platform specific temp directory. Not currently supported.
4940	(Only with installed Guest Additions 4.2 and later).</para>
4941
4942	<screen>VBoxManage guestcontrol <uuid\|vmname> mktemp\|createtemp\|createtemporary [common-options]
4943	[--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
4944	<template>
4945	</screen>
4946
4947	<para>The parameters are: <glosslist>
4948	<glossentry>
4949	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
4950	<glossdef>
4951	<para>Specifies the VM UUID or VM name. Mandatory.</para>
4952	</glossdef>
4953	</glossentry>
4954
4955	<glossentry>
4956	<glossterm><computeroutput>--directory</computeroutput></glossterm>
4957	<glossdef>
4958	<para>Creates a temporary directory instead of a file, specified by the <template> parameter. Optional.</para>
4959	</glossdef>
4960	</glossentry>
4961
4962	<glossentry>
4963	<glossterm><computeroutput>--secure</computeroutput></glossterm>
4964	<glossdef>
4965	<para>
4966	Enforces secure file/directory creation. Optional. The permission mode is set to
4967	<computeroutput>0755</computeroutput>. Operation fails if it cannot be performed securely.
4968	</para>
4969	</glossdef>
4970	</glossentry>
4971
4972	<glossentry>
4973	<glossterm><computeroutput>--mode <mode></computeroutput></glossterm>
4974	<glossdef>
4975	<para>Specifies the permission mode of the specified directory. Optional.
4976	Currently only octal modes (e.g. <computeroutput>0755</computeroutput>)
4977	are supported.</para>
4978	</glossdef>
4979	</glossentry>
4980
4981	<glossentry>
4982	<glossterm><computeroutput>--tmpdir <directory></computeroutput></glossterm>
4983	<glossdef>
4984	<para>
4985	Specifies the absolute path of the directory on the guest file system into which the
4986	file/directory specified in will be created. Optional.
4987	If unspecified, the platform-specific temp directory is used.
4988	</para>
4989	</glossdef>
4990	</glossentry>
4991
4992	<glossentry>
4993	<glossterm><computeroutput><template></computeroutput></glossterm>
4994	<glossdef>
4995	<para>Specifies a file name without a directory path, containing at least one sequence comprising
4996	three consecutive 'X' characters, or ending in 'X'. Mandatory.
4997	</para>
4998	</glossdef>
4999	</glossentry>
5000	</glosslist></para>
5001	</listitem>
5002
5003	<listitem>
5004	<para><emphasis role="bold"><computeroutput>stat</computeroutput></emphasis>
5005	Displays file or file system status(es) on the guest.</para>
5006
5007	<screen>VBoxManage guestcontrol <uuid\|vmname> stat [common-options]
5008	<file0> [<file1> [...]]</screen>
5009
5010	<para>Where the parameters are: <glosslist>
5011	<glossentry>
5012	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5013	<glossdef>
5014	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5015	</glossdef>
5016	</glossentry>
5017
5018	<glossentry>
5019	<glossterm><computeroutput><file0> [<file1> [...]]</computeroutput></glossterm>
5020	<glossdef>
5021	<para>Specifies absolute path(s) of file(s) and/or file system(s) on guest file system. Mandatory.
5022	e.g. <computeroutput>/home/foo/a.out</computeroutput>.
5023	The specified user should have sufficient rights to access
5024	the specified file(s)/file system(s).</para>
5025	</glossdef>
5026	</glossentry>
5027	</glosslist></para>
5028	</listitem>
5029	</itemizedlist>
5030	</para>
5031
5032	<para>The second set of subcommands is of the form:</para>
5033	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
5034	[-v\|--verbose] [-q\|quiet] ...
5035	</screen>
5036
5037	<para>The "common-options" are:</para>
5038	<screen>
5039	[-v\|--verbose] [-q\|--quiet]
5040	</screen>
5041
5042	<para>Where details of the common options for the second set of subcommands are:
5043	<glosslist>
5044
5045	<glossentry>
5046	<glossterm><computeroutput>-v\|--verbose</computeroutput></glossterm>
5047	<glossdef><para>Makes the sub-command execution more verbose. Optional.</para></glossdef>
5048	</glossentry>
5049
5050	<glossentry>
5051	<glossterm><computeroutput>-q\|--quiet</computeroutput></glossterm>
5052	<glossdef><para>Makes the sub-command execution quieter. Optional.</para></glossdef>
5053	</glossentry>
5054	</glosslist>
5055	</para>
5056
5057	<para>The second set of subcommands: <itemizedlist>
5058	<listitem>
5059	<para><emphasis role="bold"><computeroutput>list</computeroutput></emphasis>
5060	Lists guest control configuration and status data, e.g. open guest sessions,
5061	guest processes and files.</para>
5062
5063	<screen>VBoxManage guestcontrol <uuid\|vmname> list [common-opts]
5064	<all\|sessions\|processes\|files> </screen>
5065
5066	<para>Where the parameters are: <glosslist>
5067	<glossentry>
5068	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5069	<glossdef>
5070	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5071	</glossdef>
5072	</glossentry>
5073
5074	<glossentry>
5075	<glossterm><computeroutput>all\|sessions\|processes\|files</computeroutput></glossterm>
5076	<glossdef>
5077	<para>Indicates whether to list all available data or guest sessions, processes or files.
5078	Mandatory.</para>
5079	</glossdef>
5080	</glossentry>
5081
5082	</glosslist></para>
5083	</listitem>
5084
5085	<listitem>
5086	<para><emphasis role="bold"><computeroutput>closeprocess</computeroutput></emphasis>
5087	Terminates guest processes specified by PID(s))running in guest session(s),
5088	specified by the session ID or name(s).</para>
5089
5090	<screen>VBoxManage guestcontrol <uuid\|vmname> closeprocess [common-options]
5091	--session-id <ID> \| --session-name <name or pattern>
5092	<PID0> [<PID1> [...]] </screen>
5093
5094	<para>Where the parameters are: <glosslist>
5095	<glossentry>
5096	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5097	<glossdef>
5098	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5099	</glossdef>
5100	</glossentry>
5101
5102	<glossentry>
5103	<glossterm><computeroutput>--session-id <ID></computeroutput></glossterm>
5104	<glossdef>
5105	<para>Specifies the guest session by its ID. Optional.</para>
5106	</glossdef>
5107	</glossentry>
5108
5109	<glossentry>
5110	<glossterm><computeroutput>--session-name <name or pattern></computeroutput></glossterm>
5111	<glossdef>
5112	<para>Specifies the guest session by its name, or multiple sessions
5113	using a pattern containing wildcards. Optional.</para>
5114	</glossdef>
5115	</glossentry>
5116
5117	<glossentry>
5118	<glossterm><computeroutput><PID0> [<PID1> [...]]</computeroutput></glossterm>
5119	<glossdef>
5120	<para>Specifies a list of process identifiers (PIDs) of guest processes to be terminated. Mandatory.</para>
5121	</glossdef>
5122	</glossentry>
5123	</glosslist></para>
5124	</listitem>
5125
5126	<listitem>
5127	<para><emphasis role="bold"><computeroutput>closesession</computeroutput></emphasis>
5128	Closes specified guest sessions, specified either by session ID or name.</para>
5129
5130	<screen>VBoxManage guestcontrol <uuid\|vmname> closesession [common-options]
5131	--session-id <ID> \| --session-name <name or pattern> \| --all </screen>
5132
5133	<para>Where the parameters are: <glosslist>
5134	<glossentry>
5135	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5136	<glossdef>
5137	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5138	</glossdef>
5139	</glossentry>
5140
5141	<glossentry>
5142	<glossterm><computeroutput>--session-id <ID></computeroutput></glossterm>
5143	<glossdef>
5144	<para>Specifies the guest session to be closed by ID. Optional.</para>
5145	</glossdef>
5146	</glossentry>
5147
5148	<glossentry>
5149	<glossterm><computeroutput>--session-name <name or pattern></computeroutput></glossterm>
5150	<glossdef>
5151	<para>Specifies the guest session to be closed by name. Optional.
5152	Multiple sessions can be specified by using a pattern
5153	containing wildcards. </para>
5154	</glossdef>
5155	</glossentry>
5156
5157	<glossentry>
5158	<glossterm><computeroutput>--all</computeroutput></glossterm>
5159	<glossdef>
5160	<para>Close all guest sessions. Optional.</para>
5161	</glossdef>
5162	</glossentry>
5163	</glosslist></para>
5164	</listitem>
5165
5166	<listitem>
5167	<para><emphasis role="bold"><computeroutput>updatega\|updateadditions\|updateguestadditions</computeroutput></emphasis>
5168	Ugrades Guest Additions already installed on the guest.
5169	(Only already installed Guest Additions 4.0 and later).</para>
5170
5171	<screen>VBoxManage guestcontrol <uuid\|vmname> updatega\|updateadditions\|updateguestadditions [common-options]
5172	[--source <New .ISO path>]
5173	[--wait-start]
5174	[-- <argument0> [<argument1> [...]]]</screen>
5175
5176	<para>Where the parameters are: <glosslist>
5177	<glossentry>
5178	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5179	<glossdef>
5180	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5181	</glossdef>
5182	</glossentry>
5183
5184	<glossentry>
5185	<glossterm><computeroutput>--source</computeroutput> <New .ISO path></glossterm>
5186	<glossdef>
5187	<para>Specifies the absolute path on guest file system of the .ISO file for Guest Additions update. Mandatory.</para>
5188	</glossdef>
5189	</glossentry>
5190
5191	<glossentry>
5192	<glossterm><computeroutput>--wait-start</computeroutput></glossterm>
5193	<glossdef>
5194	<para>Indicates that VBoxManage starts the usual updating process on the guest and then waits
5195	until the actual Guest Additions updating begins, at which point VBoxManage self-terminates. Optional.</para>
5196	<para>Default behavior is that VBoxManage waits for completion of the Guest Additions update before
5197	terminating. Use of this option is sometimes necessary, as a running VBoxManage
5198	can affect the interaction between the installer and the guest OS.</para>
5199	</glossdef>
5200	</glossentry>
5201
5202	<glossentry>
5203	<glossterm><computeroutput>[-- <argument0> [<argument1> [...]]]</computeroutput></glossterm>
5204	<glossdef>
5205	<para>Specifies optional command line arguments to be supplied to the Guest Additions
5206	updater. Useful for retrofitting features which are not currently installed.</para>
5207	<para>Arguments containing spaces should be enclosed by quotes.</para>
5208	</glossdef>
5209	</glossentry>
5210	</glosslist></para>
5211	</listitem>
5212
5213	<listitem>
5214	<para><emphasis role="bold"><computeroutput>watch</computeroutput></emphasis>
5215	This subcommand prints current guest control activity.</para>
5216
5217	<screen>VBoxManage guestcontrol <uuid\|vmname> watch [common-options]
5218	</screen>
5219	<para>Where the parameters are: <glosslist>
5220	<glossentry>
5221	<glossterm><computeroutput><uuid\|vmname></computeroutput></glossterm>
5222	<glossdef>
5223	<para>Specifies the VM UUID or VM name. Mandatory.</para>
5224	</glossdef>
5225	</glossentry>
5226	</glosslist></para>
5227	</listitem>
5228	</itemizedlist></para>
5229	</sect1>
5230
5231	<sect1 id="metrics">
5232	<title>VBoxManage metrics</title>
5233
5234	<para>This command supports monitoring the usage of system resources.
5235	Resources are represented by various metrics associated with the host
5236	system or a particular VM. For example, the host system has a
5237	<computeroutput>CPU/Load/User</computeroutput> metric that shows the
5238	percentage of time CPUs spend executing in user mode over a specific
5239	sampling period.</para>
5240
5241	<para>Metric data is collected and retained internally; it may be
5242	retrieved at any time with the <computeroutput>VBoxManage metrics
5243	query</computeroutput> subcommand. The data is available as long as the
5244	background <computeroutput>VBoxSVC</computeroutput> process is alive. That
5245	process terminates shortly after all VMs and frontends have been
5246	closed.</para>
5247
5248	<para>By default no metrics are collected at all. Metrics collection does
5249	not start until <computeroutput>VBoxManage metrics setup</computeroutput>
5250	is invoked with a proper sampling interval and the number of metrics to be
5251	retained. The interval is measured in seconds. For example, to enable
5252	collecting the host processor and memory usage metrics every second and
5253	keeping the 5 most current samples, the following command can be
5254	used:</para>
5255
5256	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
5257
5258	<para>Metric collection can only be enabled for started VMs. Collected
5259	data and collection settings for a particular VM will disappear as soon as
5260	it shuts down. Use <computeroutput>VBoxManage metrics list
5261	</computeroutput> subcommand to see which metrics are currently available.
5262	You can also use <computeroutput>--list</computeroutput> option with any
5263	subcommand that modifies metric settings to find out which metrics were
5264	affected.</para>
5265
5266	<para>Note that the <computeroutput>VBoxManage metrics
5267	setup</computeroutput> subcommand discards all samples that may have been
5268	previously collected for the specified set of objects and metrics.</para>
5269
5270	<para>To enable or disable metrics collection without discarding the data
5271	<computeroutput>VBoxManage metrics enable</computeroutput> and
5272	<computeroutput>VBoxManage metrics disable</computeroutput> subcommands
5273	can be used. Note that these subcommands expect metrics, not submetrics,
5274	like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
5275	other words enabling <code>CPU/Load/User</code> while disabling
5276	<code>CPU/Load/Kernel</code> is not supported.</para>
5277
5278	<para>The host and VMs have different sets of associated metrics.
5279	Available metrics can be listed with <computeroutput>VBoxManage metrics
5280	list</computeroutput> subcommand.</para>
5281
5282	<para>A complete metric name may include an aggregate function. The name
5283	has the following form:
5284	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
5285	For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
5286	for the minimum amount of available memory over all retained data if
5287	applied to the host object.</para>
5288
5289	<para>Subcommands may apply to all objects and metrics or can be limited
5290	to one object or/and a list of metrics. If no objects or metrics are given
5291	in the parameters, the subcommands will apply to all available metrics of
5292	all objects. You may use an asterisk
5293	("<computeroutput>*</computeroutput>") to explicitly specify that the
5294	command should be applied to all objects or metrics. Use "host" as the
5295	object name to limit the scope of the command to host-related metrics. To
5296	limit the scope to a subset of metrics, use a metric list with names
5297	separated by commas.</para>
5298
5299	<para>For example, to query metric data on the CPU time spent in user and
5300	kernel modes by the virtual machine named "test", you can use the
5301	following command:</para>
5302
5303	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
5304
5305	<para>The following list summarizes the available subcommands:</para>
5306
5307	<glosslist>
5308	<glossentry>
5309	<glossterm><computeroutput>list</computeroutput></glossterm>
5310
5311	<glossdef>
5312	<para>This subcommand shows the parameters of the currently existing
5313	metrics. Note that VM-specific metrics are only available when a
5314	particular VM is running.</para>
5315	</glossdef>
5316	</glossentry>
5317
5318	<glossentry>
5319	<glossterm><computeroutput>setup</computeroutput></glossterm>
5320
5321	<glossdef>
5322	<para>This subcommand sets the interval between taking two samples
5323	of metric data and the number of samples retained internally. The
5324	retained data is available for displaying with the
5325	<code>query</code> subcommand. The <computeroutput>--list
5326	</computeroutput> option shows which metrics have been modified as
5327	the result of the command execution.</para>
5328	</glossdef>
5329	</glossentry>
5330
5331	<glossentry>
5332	<glossterm><computeroutput>enable</computeroutput></glossterm>
5333
5334	<glossdef>
5335	<para>This subcommand "resumes" data collection after it has been
5336	stopped with <code>disable</code> subcommand. Note that specifying
5337	submetrics as parameters will not enable underlying metrics. Use
5338	<computeroutput>--list</computeroutput> to find out if the command
5339	did what was expected.</para>
5340	</glossdef>
5341	</glossentry>
5342
5343	<glossentry>
5344	<glossterm><computeroutput>disable</computeroutput></glossterm>
5345
5346	<glossdef>
5347	<para>This subcommand "suspends" data collection without affecting
5348	collection parameters or collected data. Note that specifying
5349	submetrics as parameters will not disable underlying metrics. Use
5350	<computeroutput>--list</computeroutput> to find out if the command
5351	did what was expected.</para>
5352	</glossdef>
5353	</glossentry>
5354
5355	<glossentry>
5356	<glossterm><computeroutput>query</computeroutput></glossterm>
5357
5358	<glossdef>
5359	<para>This subcommand retrieves and displays the currently retained
5360	metric data.<note>
5361	<para>The <code>query</code> subcommand does not remove or
5362	"flush" retained data. If you query often enough you will see
5363	how old samples are gradually being "phased out" by new
5364	samples.</para>
5365	</note></para>
5366	</glossdef>
5367	</glossentry>
5368
5369	<glossentry>
5370	<glossterm><computeroutput>collect</computeroutput></glossterm>
5371
5372	<glossdef>
5373	<para>This subcommand sets the interval between taking two samples
5374	of metric data and the number of samples retained internally. The
5375	collected data is displayed periodically until Ctrl-C is pressed
5376	unless the <computeroutput>--detach</computeroutput> option is
5377	specified. With the <computeroutput>--detach</computeroutput>
5378	option, this subcommand operates the same way as <code>setup</code>
5379	does. The <computeroutput>--list</computeroutput> option shows which
5380	metrics match the specified filter.</para>
5381	</glossdef>
5382	</glossentry>
5383	</glosslist>
5384	</sect1>
5385
5386	<sect1 id="vboxmanage-natnetwork">
5387	<title>VBoxManage natnetwork</title>
5388
5389	<para>NAT networks use the Network Address Translation (NAT) service - which works in a
5390	similar way to a home router. It groups systems using it into a network and prevents
5391	outside systems from directly accessing those inside, while letting systems inside communicate
5392	with each other and outside systems using TCP and UDP over IPv4 and IPv6.</para>
5393
5394	<para>A NAT service is attached to an internal network. Virtual machines to make use of one
5395	should be attached to it. The name of an internal network is chosen when the NAT service is
5396	created, and the internal network will be created if it does not already exist.
5397	An example command to create a NAT network:</para>
5398
5399	<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
5400
5401	<para>Here, "natnet1" is the name of the internal network to be used and "192.168.15.0/24" is the
5402	network address and mask of the NAT service interface. By default, in this static configuration
5403	- the gateway will be assigned the address 192.168.15.1 (the address after the interface address),
5404	though this is subject to change.</para>
5405
5406	<para>To add a DHCP server to the NAT network after creation:</para>
5407
5408	<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
5409
5410	<para>Below are the subcommands for <emphasis role="bold"><computeroutput>VBoxManage natnetwork </computeroutput></emphasis></para>
5411
5412	<screen>VBoxManage natnetwork add --netname <name>
5413	[--network <network>]
5414	[--enable\|--disable]
5415	[--dhcp on\|off]
5416	[--port-forward-4 <rule>]
5417	[--loopback-4 <rule>]
5418	[--ipv6 on\|off]
5419	[--port-forward-6 <rule>]
5420	[--loopback-6 <rule>]
5421	</screen>
5422
5423
5424	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork add</computeroutput></emphasis>
5425	Creates a new internal network interface, and adds a NAT network service. This command is a
5426	prerequisite for enabling attachment of VMs to the NAT network. Parameters:</para>
5427
5428	<para>
5429	<glosslist>
5430	<glossentry>
5431	<glossterm><computeroutput>--netname <name></computeroutput></glossterm>
5432	<glossdef>
5433	<para>Where <name> is the name of the new internal network interface on the host OS. </para>
5434	</glossdef>
5435	</glossentry>
5436	<glossentry>
5437	<glossterm><computeroutput>--network <network></computeroutput></glossterm>
5438	<glossdef>
5439	<para>Where <network> specifies the static(default)/DHCP network address and mask of
5440	the NAT service interface.</para>
5441	</glossdef>
5442	</glossentry>
5443	<glossentry>
5444	<glossterm><computeroutput>--enable\|--disable</computeroutput></glossterm>
5445	<glossdef>
5446	<para>Enables/disables the NAT network service.</para>
5447	</glossdef>
5448	</glossentry>
5449	<glossentry>
5450	<glossterm><computeroutput>--dhcp on\|off</computeroutput></glossterm>
5451	<glossdef>
5452	<para>Enables/disables DHCP server specified by --netname; its use also indicates that it
5453	is a DHCP server.</para>
5454	</glossdef>
5455	</glossentry>
5456	<glossentry>
5457	<glossterm><computeroutput>--port-forward-4 <rule></computeroutput></glossterm>
5458	<glossdef>
5459	<para>Enables IPv4 port forwarding, rule specified by <rule>.</para>
5460	</glossdef>
5461	</glossentry>
5462	<glossentry>
5463	<glossterm><computeroutput>--loopback-4 <rule></computeroutput></glossterm>
5464	<glossdef>
5465	<para>Enables IPv4 loopback interface, rule specified by <rule>.</para>
5466	</glossdef>
5467	</glossentry>
5468	<glossentry>
5469	<glossterm><computeroutput>--ipv6 on\|off</computeroutput></glossterm>
5470	<glossdef>
5471	<para>Enables/disables IPv6 (default is IPv4, disables gives IPv4).</para>
5472	</glossdef>
5473	</glossentry>
5474	<glossentry>
5475	<glossterm><computeroutput>--port-forward-6 <rule></computeroutput></glossterm>
5476	<glossdef>
5477	<para>Enables IPv6 port forwarding, rule specified by <rule>.</para>
5478	</glossdef>
5479	</glossentry>
5480	<glossentry>
5481	<glossterm><computeroutput>--loopback-6 <rule></computeroutput></glossterm>
5482	<glossdef>
5483	<para>Enables IPv6 loopback interface, rule specified by <rule>.</para>
5484	</glossdef>
5485	</glossentry>
5486	</glosslist>
5487	</para>
5488
5489	<screen>VBoxManage natnetwork remove --netname <name> </screen>
5490
5491	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork remove</computeroutput></emphasis>
5492	Removes a NAT network service, parameters:</para>
5493
5494	<para>
5495	<glosslist>
5496	<glossentry>
5497	<glossterm><computeroutput>--netname <name></computeroutput></glossterm>
5498	<glossdef>
5499	<para>Where <name> specifies an existing NAT network service.
5500	Does not remove any DHCP server enabled on the network.</para>
5501	</glossdef>
5502	</glossentry>
5503	</glosslist>
5504	</para>
5505
5506	<screen>VBoxManage natnetwork modify --netname <name>
5507	[--network <network>]
5508	[--enable\|--disable]
5509	[--dhcp on\|off]
5510	[--port-forward-4 <rule>]
5511	[--loopback-4 <rule>]
5512	[--ipv6 on\|off]
5513	[--port-forward-6 <rule>]
5514	[--loopback-6 <rule>]
5515	</screen>
5516
5517	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork modify</computeroutput></emphasis>
5518	Modifies an existing NAT network service, parameters:</para>
5519
5520	<para>
5521	<glosslist>
5522	<glossentry>
5523	<glossterm><computeroutput>--netname <name></computeroutput></glossterm>
5524	<glossdef>
5525	<para>Where <name> specifies an existing NAT network service.</para>
5526	</glossdef>
5527	</glossentry>
5528	<glossentry>
5529	<glossterm><computeroutput>--network <network></computeroutput></glossterm>
5530	<glossdef>
5531	<para>Where <network> specifies the new static(default)/DHCP network address and mask
5532	of the NAT service interface.</para>
5533	</glossdef>
5534	</glossentry>
5535	<glossentry>
5536	<glossterm><computeroutput>--enable\|--disable</computeroutput></glossterm>
5537	<glossdef>
5538	<para>Enables/disables the NAT network service.</para>
5539	</glossdef>
5540	</glossentry>
5541	<glossentry>
5542	<glossterm><computeroutput>--dhcp on\|off</computeroutput></glossterm>
5543	<glossdef>
5544	<para>Enables (and if absent, adds)/disables (if any) DHCP server.</para>
5545	</glossdef>
5546	</glossentry>
5547	<glossentry>
5548	<glossterm><computeroutput>--port-forward-4 <rule></computeroutput></glossterm>
5549	<glossdef>
5550	<para>Enables IPv4 port forwarding, rule specified by <rule>.</para>
5551	</glossdef>
5552	</glossentry>
5553	<glossentry>
5554	<glossterm><computeroutput>--loopback-4 <rule></computeroutput></glossterm>
5555	<glossdef>
5556	<para>Enables IPv4 loopback interface, rule specified by <rule>.</para>
5557	</glossdef>
5558	</glossentry>
5559	<glossentry>
5560	<glossterm><computeroutput>--ipv6 on\|off</computeroutput></glossterm>
5561	<glossdef>
5562	<para>Enables/disables IPv6 (default is IPv4, disables gives IPv4).</para>
5563	</glossdef>
5564	</glossentry>
5565	<glossentry>
5566	<glossterm><computeroutput>--port-forward-6 <rule></computeroutput></glossterm>
5567	<glossdef>
5568	<para>Enables IPv6 port forwarding, rule specified by <rule>.</para>
5569	</glossdef>
5570	</glossentry>
5571	<glossentry>
5572	<glossterm><computeroutput>--loopback-6 <rule></computeroutput></glossterm>
5573	<glossdef>
5574	<para>Enables IPv6 loopback interface, rule specified by <rule>.</para>
5575	</glossdef>
5576	</glossentry>
5577	</glosslist>
5578	</para>
5579
5580	<screen>VBoxManage natnetwork start --netname <name>
5581	</screen>
5582
5583	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork start</computeroutput></emphasis>
5584	Starts specified NAT network service and any associated DHCP server, parameters:</para>
5585
5586	<para>
5587	<glosslist>
5588	<glossentry>
5589	<glossterm><computeroutput>--netname <name></computeroutput></glossterm>
5590	<glossdef>
5591	<para>Where <name> specifies an existing NAT network service.</para>
5592	</glossdef>
5593	</glossentry>
5594	</glosslist>
5595	</para>
5596
5597	<screen>VBoxManage natnetwork stop --netname <name>
5598	</screen>
5599
5600	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork stop</computeroutput></emphasis>
5601	Stops specified NAT network service and any DHCP server, parameters:</para>
5602
5603	<para>
5604	<glosslist>
5605	<glossentry>
5606	<glossterm><computeroutput>--netname <name></computeroutput></glossterm>
5607	<glossdef>
5608	<para>Where <name> specifies an existing NAT network service.</para>
5609	</glossdef>
5610	</glossentry>
5611	</glosslist>
5612	</para>
5613
5614	<screen>VBoxManage natnetwork list [<pattern>] </screen>
5615
5616	<para><emphasis role="bold"><computeroutput>VBoxManage natnetwork list</computeroutput></emphasis>
5617	Lists all NAT network services with optional filtering, parameters:</para>
5618
5619	<para>
5620	<glosslist>
5621	<glossentry>
5622	<glossterm><computeroutput>[<pattern>]</computeroutput></glossterm>
5623	<glossdef>
5624	<para>Where <pattern> is optional filtering pattern.</para>
5625	</glossdef>
5626	</glossentry>
5627	</glosslist>
5628	</para>
5629	</sect1>
5630
5631	<sect1 id="vboxmanage-hostonlyif">
5632	<title>VBoxManage hostonlyif</title>
5633
5634	<para>With "hostonlyif" you can change the IP configuration of a host-only
5635	network interface. For a description of host-only networking, please
5636	refer to <xref linkend="network_hostonly" />. Each host-only interface is
5637	identified by a name and can either use the internal DHCP server or a
5638	manual IP configuration (both IP4 and IP6).</para>
5639
5640	<para>The following list summarizes the available subcommands:</para>
5641
5642	<glosslist>
5643	<glossentry>
5644	<glossterm><computeroutput>ipconfig "<name>"</computeroutput></glossterm>
5645	<glossdef>
5646	<para>Configure a hostonly interface</para>
5647	</glossdef>
5648	</glossentry>
5649	<glossentry>
5650	<glossterm><computeroutput>create</computeroutput></glossterm>
5651	<glossdef>
5652	<para>Creates a new vboxnet<N> interface on the host OS.
5653	This command is essential before you can attach VMs to host-only network.</para>
5654	</glossdef>
5655	</glossentry>
5656	<glossentry>
5657	<glossterm><computeroutput>remove vboxnet<N></computeroutput></glossterm>
5658	<glossdef>
5659	<para>Removes a vboxnet<N> interface from the host OS.</para>
5660	</glossdef>
5661	</glossentry>
5662	</glosslist>
5663
5664	</sect1>
5665
5666	<sect1 id="vboxmanage-dhcpserver">
5667	<title>VBoxManage dhcpserver</title>
5668
5669	<para>The "dhcpserver" commands allow you to control the DHCP server that
5670	is built into VirtualBox. You may find this useful when using internal or
5671	host-only networking. (Theoretically, you can enable it for a bridged
5672	network as well, but that will likely cause conflicts with other DHCP
5673	servers in your physical network.)</para>
5674
5675	<para>Use the following command line options:<itemizedlist>
5676	<listitem>
5677	<para>If you use internal networking for a virtual network adapter
5678	of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
5679	--netname <network_name></computeroutput>, where
5680	<computeroutput><network_name></computeroutput> is the same
5681	network name you used with <computeroutput>VBoxManage modifyvm
5682	<vmname> --intnet<X>
5683	<network_name></computeroutput>.</para>
5684	</listitem>
5685
5686	<listitem>
5687	<para>If you use host-only networking for a virtual network adapter
5688	of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
5689	--ifname <hostonly_if_name></computeroutput> instead, where
5690	<computeroutput><hostonly_if_name></computeroutput> is the
5691	same host-only interface name you used with
5692	<computeroutput>VBoxManage modifyvm <vmname>
5693	--hostonlyadapter<X>
5694	<hostonly_if_name></computeroutput>.</para>
5695
5696	<para>Alternatively, you can also use the
5697	<computeroutput>--netname</computeroutput> option as with
5698	internal networks if you know the host-only network's name; you can
5699	see the names with <computeroutput>VBoxManage list
5700	hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
5701	above).</para>
5702	</listitem>
5703	</itemizedlist></para>
5704
5705	<para>The following additional parameters are required when first adding a
5706	DHCP server:<itemizedlist>
5707	<listitem>
5708	<para>With <computeroutput>--ip</computeroutput>, specify the IP
5709	address of the DHCP server itself.</para>
5710	</listitem>
5711
5712	<listitem>
5713	<para>With <computeroutput>--netmask</computeroutput>, specify the
5714	netmask of the network.</para>
5715	</listitem>
5716
5717	<listitem>
5718	<para>With <computeroutput>--lowerip</computeroutput> and
5719	<computeroutput>--upperip</computeroutput>, you can specify the
5720	lowest and highest IP address, respectively, that the DHCP server
5721	will hand out to clients.</para>
5722	</listitem>
5723	</itemizedlist></para>
5724
5725	<para>Finally, you must specify <computeroutput>--enable</computeroutput>
5726	or the DHCP server will be created in the disabled state, doing
5727	nothing.</para>
5728
5729	<para>After this, VirtualBox will automatically start the DHCP server for
5730	given internal or host-only network as soon as the first virtual machine
5731	which uses that network is started.</para>
5732
5733	<para>Reversely, use <computeroutput>VBoxManage dhcpserver
5734	remove</computeroutput> with the given <computeroutput>--netname
5735	<network_name></computeroutput> or <computeroutput>--ifname
5736	<hostonly_if_name></computeroutput> to remove the DHCP server again
5737	for the given internal or host-only network.</para>
5738
5739	<para>To modify the settings of a DHCP server created earlier with
5740	<computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
5741	<computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
5742	network or host-only interface name. This has the same parameters as
5743	<computeroutput>VBoxManage dhcpserver add</computeroutput>.</para>
5744	</sect1>
5745
5746	<sect1 id="vboxmanage-usbdevsource">
5747	<title>VBoxManage usbdevsource</title>
5748
5749	<para>The "usbdevsource" commands enables you to add and remove USB devices
5750	globally.</para>
5751
5752	<para>The following command adds a USB device.</para>
5753
5754	<screen>VBoxManage usbdevsource add <source name>
5755	--backend <backend>
5756	--address <address>
5757	</screen>
5758
5759	<para>Where the command line options are:<itemizedlist>
5760	<listitem>
5761	<para><source name> specifies the ID of the 'source' USB
5762	device to be added. Mandatory.</para>
5763	</listitem>
5764	<listitem>
5765	<para>--backend <backend> specifies the USB proxy service
5766	backend to use. Mandatory.</para>
5767	</listitem>
5768	<listitem>
5769	<para>--address <address> specifies the backend specific
5770	address. Mandatory.</para>
5771	</listitem>
5772	</itemizedlist></para>
5773
5774	<para>The following command removes a USB device.</para>
5775
5776	<screen>VBoxManage usbdevsource remove <source name>
5777	</screen>
5778
5779	<para>Where the command line options are:<itemizedlist>
5780	<listitem>
5781	<para><source name> specifies the ID of the 'source' USB
5782	device to be removed. Mandatory.</para>
5783	</listitem>
5784	</itemizedlist></para>
5785	</sect1>
5786
5787
5788	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)"
5789	xmlns:xi="http://www.w3.org/2001/XInclude" />
5790
5791	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)"
5792	xmlns:xi="http://www.w3.org/2001/XInclude" />
5793	</chapter>

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

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

Download in other formats: