user_VBoxManage.xml@ 73184

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

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

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

Download in other formats: