user_VBoxManage.xml@ 87043

Last change on this file since 87043 was 85929, checked in by vboxsync, 4 years ago
Main: bugref:9224: Main+VBoxManageDisk+doc part
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 294.8 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-2020 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.5//EN"
20	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
21	<!ENTITY % all.entities SYSTEM "all-entities.ent">
22	%all.entities;
23	]>
24	<chapter id="vboxmanage">
25
26	<title>VBoxManage</title>
27
28	<sect1 id="vboxmanage-intro">
29
30	<title>Introduction</title>
31
32	<para>
33	As briefly mentioned in <xref linkend="frontends" />,
34	<command>VBoxManage</command> is the command-line interface to
35	&product-name;. With it, you can completely control &product-name;
36	from the command line of your host operating system.
37	<command>VBoxManage</command> supports all the features that the
38	graphical user interface gives you access to, but it supports a
39	lot more than that. It exposes all the features of the
40	virtualization engine, even those that cannot be accessed from the
41	GUI.
42	</para>
43
44	<para>
45	You will need to use the command line if you want to do the
46	following:
47	</para>
48
49	<itemizedlist>
50
51	<listitem>
52	<para>
53	Use a different user interface than the main GUI such as the
54	VBoxHeadless server.
55	</para>
56	</listitem>
57
58	<listitem>
59	<para>
60	Control some of the more advanced and experimental
61	configuration settings for a VM.
62	</para>
63	</listitem>
64
65	</itemizedlist>
66
67	<para>
68	There are two main things to keep in mind when using
69	<command>VBoxManage</command>. First,
70	<command>VBoxManage</command> must always be used with a specific
71	subcommand, such as <command>list</command> or
72	<command>createvm</command> or <command>startvm</command>. All the
73	subcommands that <command>VBoxManage</command> supports are
74	described in detail in <xref linkend="vboxmanage" />.
75	</para>
76
77	<para>
78	Second, most of these subcommands require that you specify a
79	particular virtual machine after the subcommand. There are two
80	ways you can do this:
81	</para>
82
83	<itemizedlist>
84
85	<listitem>
86	<para>
87	You can specify the VM name, as it is shown in the
88	&product-name; GUI. Note that if that name contains spaces,
89	then you must enclose the entire name in double quotes. This
90	is always required with command line arguments that contain
91	spaces. For example:
92	</para>
93
94	<screen>VBoxManage startvm "Windows XP"</screen>
95	</listitem>
96
97	<listitem>
98	<para>
99	You can specify the UUID, which is the internal unique
100	identifier that &product-name; uses to refer to the virtual
101	machine. Assuming that the VM called "Windows XP" has the UUID
102	shown below, the following command has the same effect as the
103	previous example:
104	</para>
105
106	<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen>
107	</listitem>
108
109	</itemizedlist>
110
111	<para>
112	You can enter <command>VBoxManage list vms</command> to have all
113	currently registered VMs listed with all their settings, including
114	their respective names and UUIDs.
115	</para>
116
117	<para>
118	Some typical examples of how to control &product-name; from the
119	command line are listed below:
120	</para>
121
122	<itemizedlist>
123
124	<listitem>
125	<para>
126	To create a new virtual machine from the command line and
127	immediately register it with &product-name;, use
128	<command>VBoxManage createvm</command> with the
129	<option>--register</option> option, as follows:
130	</para>
131
132	<screen>$ VBoxManage createvm --name "SUSE 10.2" --register
133	VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
134	(C) 2005-2018 Oracle Corporation
135	All rights reserved.
136
137	Virtual machine 'SUSE 10.2' is created.
138	UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
139	Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen>
140
141	<para>
142	As can be seen from the above output, a new virtual machine
143	has been created with a new UUID and a new XML settings file.
144	</para>
145
146	<para>
147	For more details, see
148	<xref
149	linkend="vboxmanage-createvm" />.
150	</para>
151	</listitem>
152
153	<listitem>
154	<para>
155	To show the configuration of a particular VM, use
156	<command>VBoxManage showvminfo</command>. See
157	<xref
158	linkend="vboxmanage-showvminfo" /> for details
159	and an example.
160	</para>
161	</listitem>
162
163	<listitem>
164	<para>
165	To change settings while a VM is powered off, use
166	<command>VBoxManage modifyvm</command>. For example:
167	</para>
168
169	<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen>
170
171	<para>
172	See also <xref linkend="vboxmanage-modifyvm" />.
173	</para>
174	</listitem>
175
176	<listitem>
177	<para>
178	To change the storage configuration, such as to add a storage
179	controller and then a virtual disk, use <command>VBoxManage
180	storagectl</command> and <command>VBoxManage
181	storageattach</command>. See
182	<xref
183	linkend="vboxmanage-storagectl" /> and
184	<xref
185	linkend="vboxmanage-storageattach" />.
186	</para>
187	</listitem>
188
189	<listitem>
190	<para>
191	To control VM operation, use one of the following:
192	</para>
193
194	<itemizedlist>
195
196	<listitem>
197	<para>
198	To start a VM that is currently powered off, use
199	<command>VBoxManage startvm</command>. See
200	<xref
201	linkend="vboxmanage-startvm" />.
202	</para>
203	</listitem>
204
205	<listitem>
206	<para>
207	To pause or save a VM that is currently running or change
208	some of its settings, use <command>VBoxManage
209	controlvm</command>. See
210	<xref
211	linkend="vboxmanage-controlvm" />.
212	</para>
213	</listitem>
214
215	</itemizedlist>
216	</listitem>
217
218	</itemizedlist>
219
220	</sect1>
221
222	<sect1 id="vboxmanage-cmd-overview">
223
224	<title>Commands Overview</title>
225
226	<para>
227	When running <command>VBoxManage</command> without parameters or
228	when supplying an invalid command line, the following command
229	syntax list is shown. Note that the output will be slightly
230	different depending on the host platform. If in doubt, check the
231	output of <command>VBoxManage</command> for the commands available
232	on your particular host.
233	</para>
234
235	<xi:include href="user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)"
236	xmlns:xi="http://www.w3.org/2001/XInclude" />
237
238	<para>
239	Each time <command>VBoxManage</command> is invoked, only one
240	command can be executed. However, a command might support several
241	subcommands which then can be invoked in one single call. The
242	following sections provide detailed reference information on the
243	different commands.
244	</para>
245
246	</sect1>
247
248	<sect1 id="vboxmanage-general">
249
250	<title>General Options</title>
251
252	<itemizedlist>
253
254	<listitem>
255	<para>
256	<option>-v\|--version</option>: Show the version of this tool
257	and exit.
258	</para>
259	</listitem>
260
261	<listitem>
262	<para>
263	<option>--nologo</option>: Suppress the output of the logo
264	information. This option is useful for scripts.
265	</para>
266	</listitem>
267
268	<listitem>
269	<para>
270	<option>--settingspw</option>: Specifiy a settings password.
271	</para>
272	</listitem>
273
274	<listitem>
275	<para>
276	<option>--settingspwfile</option>: Specify a file containing
277	the settings password.
278	</para>
279	</listitem>
280
281	</itemizedlist>
282
283	<para>
284	The settings password is used for certain settings which need to
285	be stored in encrypted form for security reasons. At the moment,
286	the only encrypted setting is the iSCSI initiator secret, see
287	<xref linkend="vboxmanage-storageattach" />. As long as no
288	settings password is specified, this information is stored in
289	<emphasis>plain text</emphasis>. After using the
290	<option>--settingspw\|--settingspwfile</option> option once, it
291	must be always used. Otherwise, the encrypted setting cannot be
292	unencrypted.
293	</para>
294
295	</sect1>
296
297	<sect1 id="vboxmanage-list">
298
299	<title>VBoxManage list</title>
300
301	<para>
302	The <command>list</command> command gives relevant information
303	about your system and information about &product-name;'s current
304	settings.
305	</para>
306
307	<para>
308	The following subcommands are available with <command>VBoxManage
309	list</command>:
310	</para>
311
312	<itemizedlist>
313
314	<listitem>
315	<para>
316	<command>vms</command>: Lists all virtual machines currently
317	registered with &product-name;. By default this displays a
318	compact list with each VM's name and UUID. If you also specify
319	<option>--long</option> or <option>-l</option>, this will be a
320	detailed list as with the <command>showvminfo</command>
321	command, see <xref linkend="vboxmanage-showvminfo"/>.
322	</para>
323	</listitem>
324
325	<listitem>
326	<para>
327	<command>runningvms</command>: Lists all currently running
328	virtual machines by their unique identifiers (UUIDs) in the
329	same format as with <command>vms</command>.
330	</para>
331	</listitem>
332
333	<listitem>
334	<para>
335	<command>ostypes</command>: Lists all guest operating systems
336	presently known to &product-name;, along with the identifiers
337	used to refer to them with the <command>modifyvm</command>
338	command.
339	</para>
340	</listitem>
341
342	<listitem>
343	<para>
344	<command>hostdvds</command>, <command>hostfloppies</command>:
345	Lists the DVD, floppy, bridged networking, and host-only
346	networking interfaces on the host, along with the name used to
347	access them from within &product-name;.
348	</para>
349	</listitem>
350
351	<listitem>
352	<para>
353	<command>intnets</command>: Displays information about the
354	internal networks.
355	</para>
356	</listitem>
357
358	<listitem>
359	<para>
360	<command>bridgedifs</command>, <command>hostonlyifs</command>,
361	<command>natnets</command>, <command>dhcpservers</command>:
362	Lists the bridged network interfaces, host-only network
363	interfaces, NAT network interfaces, and DHCP servers currently
364	available on the host. See
365	<xref linkend="networkingdetails" />.
366	</para>
367	</listitem>
368
369	<listitem>
370	<para>
371	<command>hostinfo</command>: Displays information about the
372	host system, such as CPUs, memory size, and operating system
373	version.
374	</para>
375	</listitem>
376
377	<listitem>
378	<para>
379	<command>hostcpuids</command>: Lists the CPUID parameters for
380	the host CPUs. This can be used for a more fine grained
381	analyis of the host's virtualization capabilities.
382	</para>
383	</listitem>
384
385	<listitem>
386	<para>
387	<command>hddbackends</command>: Lists all known virtual disk
388	back-ends of &product-name;. For each such format, such as
389	VDI, VMDK, or RAW, this subcommand lists the back-end's
390	capabilities and configuration.
391	</para>
392	</listitem>
393
394	<listitem>
395	<para>
396	<command>hdds</command>, <command>dvds</command>,
397	<command>floppies</command>: Shows information about virtual
398	disk images currently in use by &product-name;, including all
399	their settings, the unique identifiers (UUIDs) associated with
400	them by &product-name; and all files associated with them.
401	This is the command-line equivalent of the Virtual Media
402	Manager. See <xref linkend="vdis" />.
403	</para>
404	</listitem>
405
406	<listitem>
407	<para>
408	<command>usbhost</command>: Shows information about USB
409	devices attached to the host, including information useful for
410	constructing USB filters and whether they are currently in use
411	by the host.
412	</para>
413	</listitem>
414
415	<listitem>
416	<para>
417	<command>usbfilters</command>: Lists all global USB filters
418	registered with &product-name; and displays the filter
419	parameters. Global USB filters are for devices which are
420	accessible to all virtual machines.
421	</para>
422	</listitem>
423
424	<listitem>
425	<para>
426	<command>systemproperties</command>: Displays some global
427	&product-name; settings, such as minimum and maximum guest RAM
428	and virtual hard disk size, folder settings and the current
429	authentication library in use.
430	</para>
431	</listitem>
432
433	<listitem>
434	<para>
435	<command>extpacks</command>: Displays all &product-name;
436	extension packs that are currently installed. See
437	<xref linkend="intro-installing" /> and
438	<xref linkend="vboxmanage-extpack" />.
439	</para>
440	</listitem>
441
442	<listitem>
443	<para>
444	<command>groups</command>: Displays details of the VM Groups.
445	See <xref linkend="gui-vmgroups" />.
446	</para>
447	</listitem>
448
449	<listitem>
450	<para>
451	<command>webcams</command>: Displays a list of webcams
452	attached to the running VM. The output format is a list of
453	absolute paths or aliases that were used for attaching the
454	webcams to the VM using the webcam attach command.
455	</para>
456	</listitem>
457
458	<listitem>
459	<para>
460	<command>screenshotformats</command>: Displays a list of
461	available screenshot formats.
462	</para>
463	</listitem>
464
465	<listitem>
466	<para>
467	<command>cloudproviders</command>: Displays a list of cloud
468	providers that are supported by &product-name;. &oci; is an
469	example of a cloud provider.
470	</para>
471	</listitem>
472
473	<listitem>
474	<para>
475	<command>cloudprofiles</command>: Displays a list of cloud
476	profiles that have been configured.
477	</para>
478
479	<para>
480	Cloud profiles are used when exporting VMs to a cloud service.
481	See <xref linkend="cloud-export-oci"/>.
482	</para>
483	</listitem>
484
485	<listitem>
486	<para>
487	<command>hostdrives</command>: Displays a list of host fixed
488	drives with their partitions. If you also specify
489	<option>--long</option> or <option>-l</option> the sizes and
490	offsets will be in bytes.
491	</para>
492	</listitem>
493
494	</itemizedlist>
495
496	</sect1>
497
498	<sect1 id="vboxmanage-showvminfo">
499
500	<title>VBoxManage showvminfo</title>
501
502	<para>
503	The <command>showvminfo</command> command shows information about
504	a particular virtual machine. This is the same information as
505	<command>VBoxManage list vms --long</command> would show for all
506	virtual machines.
507	</para>
508
509	<para>
510	You will see information as shown in the following example.
511	</para>
512
513	<screen>$ VBoxManage showvminfo "Windows XP"
514	VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
515	(C) 2005-2018 Oracle Corporation
516	All rights reserved.
517
518	Name: Windows XP
519	Guest OS: Other/Unknown
520	UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
521	Config file: /home/username/.config/VirtualBox/Machines/Windows XP/Windows XP.xml
522	Memory size: 512MB
523	VRAM size: 12MB
524	Number of CPUs: 2
525	Boot menu mode: message and menu
526	Boot Device (1): DVD
527	Boot Device (2): HardDisk
528	Boot Device (3): Not Assigned
529	Boot Device (4): Not Assigned
530	ACPI: on
531	IOAPIC: on
532	...
533	</screen>
534
535	<para>
536	Use the <option>--machinereadable</option> option to produce the
537	same output, but in machine readable format with a property=value
538	string on each line. For example:
539	</para>
540
541	<screen>
542	...
543	groups="/"
544	ostype="Oracle (64-bit)"
545	UUID="457af700-bc0a-4258-aa3c-13b03da171f2"
546	...
547	</screen>
548
549	</sect1>
550
551	<sect1 id="vboxmanage-registervm">
552
553	<title>VBoxManage registervm/unregistervm</title>
554
555	<para>
556	The <computeroutput>registervm</computeroutput> command enables
557	you to import a virtual machine definition in an XML file into
558	&product-name;. The machine must not conflict with one already
559	registered in &product-name; and it may not have any hard or
560	removable disks attached. It is advisable to place the definition
561	file in the machines folder before registering it.
562	</para>
563
564	<note>
565	<para>
566	When creating a new virtual machine with <command>VBoxManage
567	createvm</command>, as shown in
568	<xref linkend="vboxmanage-createvm"/>, you can directly specify
569	the <option>--register</option> option to avoid having to
570	register it separately.
571	</para>
572	</note>
573
574	<para>
575	The <command>unregistervm</command> command unregisters a virtual
576	machine. If <option>--delete</option> is also specified, the
577	following files will also be deleted automatically:
578	</para>
579
580	<itemizedlist>
581
582	<listitem>
583	<para>
584	All hard disk image files, including differencing files, which
585	are used by the machine and not shared with other machines.
586	</para>
587	</listitem>
588
589	<listitem>
590	<para>
591	Saved state files that the machine created. One if the machine
592	was in Saved state and one for each online snapshot.
593	</para>
594	</listitem>
595
596	<listitem>
597	<para>
598	The machine XML file and its backups.
599	</para>
600	</listitem>
601
602	<listitem>
603	<para>
604	The machine log files.
605	</para>
606	</listitem>
607
608	<listitem>
609	<para>
610	The machine directory, if it is empty after having deleted all
611	of the above files.
612	</para>
613	</listitem>
614
615	</itemizedlist>
616
617	</sect1>
618
619	<sect1 id="vboxmanage-createvm">
620
621	<title>VBoxManage createvm</title>
622
623	<para>
624	The <command>VBoxManage createvm</command> command creates a new
625	XML virtual machine definition file.
626	</para>
627
628	<para>
629	You must specify the name of the VM by using <option>--name
630	<replaceable>name</replaceable></option>. This name is used by
631	default as the file name of the settings file that has the
632	<filename>.xml</filename> extension and the machine folder, which
633	is a subfolder of the
634	<filename>.config/VirtualBox/Machines</filename> folder. Note that
635	the machine folder path name varies based on the OS type and the
636	&product-name; version.
637	</para>
638
639	<para>
640	Ensure that the VM name conforms to the host OS's file name
641	requirements. If you later rename the VM, the file and folder
642	names will be updated to match the new name automatically.
643	</para>
644
645	<para>
646	The <option>--basefolder <replaceable>path</replaceable></option>
647	option specifies the machine folder path name. Note that the names
648	of the file and the folder do not change if you rename the VM.
649	</para>
650
651	<para>
652	The <option>--group <replaceable>group-ID</replaceable>,
653	...</option> option assigns the VM to the specified groups. Note
654	that group IDs always start with
655	<computeroutput>/</computeroutput> so that they can be nested. By
656	default, each VM is assigned membership to the
657	<computeroutput>/</computeroutput> group.
658	</para>
659
660	<para>
661	The <option>--ostype <replaceable>ostype</replaceable></option>
662	option specifies the guest OS to run in the VM. Run the
663	<command>VBoxManage list ostypes</command> command to see the
664	available OS types.
665	</para>
666
667	<para>
668	The <option>--uuid <replaceable>uuid</replaceable></option> option
669	specifies the universal unique identifier (UUID) of the VM. The
670	UUID must be unique within the namespace of the host or of its VM
671	group memberships. By default, the <command>VBoxManage</command>
672	command automatically generates the UUID.
673	</para>
674
675	<para>
676	The <computeroutput>--default</computeroutput> option applies a
677	default hardware configuration for the specified guest OS. By
678	default, the VM is created with minimal hardware.
679	</para>
680
681	<para>
682	The <option>--register</option> option registers the VM with your
683	&product-name; installation. By default, the <command>VBoxManage
684	createvm</command> command creates only the XML configuration for
685	the VM but does not registered the VM. If you do not register the
686	VM at creation, you can run the <command>VBoxManage
687	registervm</command> command after you create the VM.
688	</para>
689
690	</sect1>
691
692	<sect1 id="vboxmanage-modifyvm">
693
694	<title>VBoxManage modifyvm</title>
695
696	<para>
697	This command changes the properties of a registered virtual
698	machine which is not running. Most of the properties that this
699	command makes available correspond to the VM settings that
700	&product-name; graphical user interface displays in each VM's
701	<emphasis role="bold">Settings</emphasis> dialog. These are
702	described in <xref linkend="BasicConcepts" />. However, some of
703	the more advanced settings are only available through the
704	<command>VBoxManage</command> interface.
705	</para>
706
707	<para>
708	These commands require that the machine is powered off, neither
709	running nor in a Saved state. Some machine settings can also be
710	changed while a machine is running. Those settings will then have
711	a corresponding subcommand with the <command>VBoxManage
712	controlvm</command> subcommand. See
713	<xref linkend="vboxmanage-controlvm" />.
714	</para>
715
716	<sect2 id="vboxmanage-modifyvm-general">
717
718	<title>General Settings</title>
719
720	<para>
721	The following general settings are available through
722	<command>VBoxManage modifyvm</command>:
723	</para>
724
725	<itemizedlist>
726
727	<listitem>
728	<para>
729	<computeroutput>--name <name></computeroutput>:
730	Changes the VM's name and can be used to rename the internal
731	virtual machine files, as described in
732	<xref linkend="vboxmanage-createvm"/>.
733	</para>
734	</listitem>
735
736	<listitem>
737	<para>
738	<computeroutput>--groups <group>,
739	...</computeroutput>: Changes the group membership of a VM.
740	Groups always start with a
741	<computeroutput>/</computeroutput> and can be nested. By
742	default VMs are in group <computeroutput>/</computeroutput>.
743	</para>
744	</listitem>
745
746	<listitem>
747	<para>
748	<computeroutput>--description <desc></computeroutput>:
749	Changes the VM's description, which is a way to record
750	details about the VM in a way which is meaningful for the
751	user. The GUI interprets HTML formatting, the command line
752	allows arbitrary strings potentially containing multiple
753	lines.
754	</para>
755	</listitem>
756
757	<listitem>
758	<para>
759	<computeroutput>--ostype <ostype></computeroutput>:
760	Specifies what guest operating system is supposed to run in
761	the VM. To learn about the various identifiers that can be
762	used here, use <command>VBoxManage list ostypes</command>.
763	</para>
764	</listitem>
765
766	<listitem>
767	<para>
768	<computeroutput>--iconfile
769	<filename></computeroutput>: Specifies the absolute
770	path on the host file system for the &product-name; icon to
771	be displayed in the VM.
772	</para>
773	</listitem>
774
775	<listitem>
776	<para>
777	<computeroutput>--memory
778	<memorysize></computeroutput>: Sets the amount of RAM,
779	in MB, that the virtual machine should allocate for itself
780	from the host. See <xref linkend="gui-createvm" />.
781	</para>
782	</listitem>
783
784	<listitem>
785	<para>
786	<computeroutput>--pagefusion on\|off</computeroutput>:
787	Enables and disables the Page Fusion feature. Page Fusion is
788	disabled by default. The Page Fusion feature minimises
789	memory duplication between VMs with similar configurations
790	running on the same host. See
791	<xref linkend="guestadd-pagefusion" />.
792	</para>
793	</listitem>
794
795	<listitem>
796	<para>
797	<computeroutput>--vram <vramsize></computeroutput>:
798	Sets the amount of RAM that the virtual graphics card should
799	have. See <xref linkend="settings-display" />.
800	</para>
801	</listitem>
802
803	<listitem>
804	<para>
805	<computeroutput>--acpi on\|off</computeroutput> and
806	<computeroutput>--ioapic on\|off</computeroutput>: Determines
807	whether the VM has ACPI and I/O APIC support. See
808	<xref linkend="settings-motherboard" />.
809	</para>
810	</listitem>
811
812	<listitem>
813	<para>
814	<computeroutput>--pciattach <host PCI address [@ guest
815	PCI bus address]></computeroutput>: Attaches a specified
816	PCI network controller on the host to a specified PCI bus on
817	the guest.
818
819	<!--See <xref linkend="pcipassthrough" />.-->
820	</para>
821	</listitem>
822
823	<listitem>
824	<para>
825	<computeroutput>--pcidetach <host PCI
826	address></computeroutput>: Detaches a specified PCI
827	network controller on the host from the attached PCI bus on
828	the guest.
829
830	<!--See <xref linkend="pcipassthrough" />.-->
831	</para>
832	</listitem>
833
834	<listitem>
835	<para>
836	<computeroutput>--hardwareuuid
837	<uuid></computeroutput>: The UUID presented to the
838	guest through memory tables (DMI/SMBIOS), hardware, and
839	guest properties. By default this is the same as the VM
840	UUID. This setting is useful when cloning a VM. Teleporting
841	takes care of this automatically.
842	</para>
843	</listitem>
844
845	<listitem>
846	<para>
847	<computeroutput>--cpus <cpucount></computeroutput>:
848	Sets the number of virtual CPUs for the virtual machine, see
849	<xref linkend="settings-processor" />. If CPU hot-plugging
850	is enabled, this then sets the <emphasis>maximum</emphasis>
851	number of virtual CPUs that can be plugged into the virtual
852	machines.
853	</para>
854	</listitem>
855
856	<listitem>
857	<para>
858	<computeroutput>--cpuhotplug on\|off</computeroutput>:
859	Enables CPU hot-plugging. When enabled, virtual CPUs can be
860	added to and removed from a virtual machine while it is
861	running. See <xref linkend="cpuhotplug" />.
862	</para>
863	</listitem>
864
865	<listitem>
866	<para>
867	<computeroutput>--plugcpu\|unplugcpu
868	<id></computeroutput>: If CPU hot-plugging is enabled,
869	this setting adds or removes a virtual CPU on the virtual
870	machine. <computeroutput><id></computeroutput>
871	specifies the index of the virtual CPU to be added or
872	removed and must be a number from 0 to the maximum number of
873	CPUs configured with the
874	<computeroutput>--cpus</computeroutput> option. CPU 0 can
875	never be removed.
876	</para>
877	</listitem>
878
879	<listitem>
880	<para>
881	<computeroutput>--cpuexecutioncap
882	<1-100></computeroutput>: Controls how much CPU time a
883	virtual CPU can use. A value of 50 implies a single virtual
884	CPU can use up to 50% of a single host CPU.
885	</para>
886	</listitem>
887
888	<listitem>
889	<para>
890	<computeroutput>--pae on\|off</computeroutput>: Enables and
891	disables PAE. See <xref linkend="settings-processor" />.
892	</para>
893	</listitem>
894
895	<listitem>
896	<para>
897	<computeroutput>--longmode on\|off</computeroutput>: Enables
898	and disables long mode. See
899	<xref linkend="settings-processor" />.
900	</para>
901	</listitem>
902
903	<listitem>
904	<para>
905	<computeroutput>--spec-ctrl on\|off</computeroutput>: Enables
906	and disables the exposure of speculation control interfaces
907	to the guest, provided they are available on the host.
908	Depending on the host CPU and workload, enabling speculation
909	control may significantly reduce performance.
910	</para>
911	</listitem>
912
913	<listitem>
914	<para>
915	<computeroutput>--cpu-profile <host\|intel
916	80[86\|286\|386]></computeroutput>: Enables specification
917	of a profile for guest CPU emulation. Specify either one
918	based on the host system CPU (host), or one from a number of
919	older Intel Micro-architectures: 8086, 80286, 80386.
920	</para>
921	</listitem>
922
923	<listitem>
924	<para>
925	<computeroutput>--hpet on\|off</computeroutput>: Enables and
926	disables a High Precision Event Timer (HPET) which can
927	replace the legacy system timers. This is turned off by
928	default. Note that Windows supports a HPET only from Vista
929	onwards.
930	</para>
931	</listitem>
932
933	<listitem>
934	<para>
935	<computeroutput>--hwvirtex on\|off</computeroutput>: Enables
936	and disables the use of hardware virtualization extensions,
937	such as Intel VT-x or AMD-V, in the processor of your host
938	system. See <xref linkend="hwvirt" />.
939	</para>
940	</listitem>
941
942	<listitem>
943	<para>
944	<computeroutput>--triplefaultreset on\|off</computeroutput>:
945	Enables resetting of the guest instead of triggering a Guru
946	Meditation. Some guests raise a triple fault to reset the
947	CPU so sometimes this is desired behavior. Works only for
948	non-SMP guests.
949	</para>
950	</listitem>
951
952	<listitem>
953	<para>
954	<computeroutput>--apic on\|off</computeroutput>: Enables and
955	disables I/O APIC. With I/O APIC, operating systems can use
956	more than 16 interrupt requests (IRQs) thus avoiding IRQ
957	sharing for improved reliability. This setting is enabled by
958	default. See <xref linkend="settings-motherboard" />.
959	</para>
960	</listitem>
961
962	<listitem>
963	<para>
964	<computeroutput>--x2apic on\|off</computeroutput>: Enables
965	and disables CPU x2APIC support. CPU x2APIC support helps
966	operating systems run more efficiently on high core count
967	configurations, and optimizes interrupt distribution in
968	virtualized environments. This setting is enabled by
969	default. Disable this setting when using host or guest
970	operating systems that are incompatible with x2APIC support.
971	</para>
972	</listitem>
973
974	<listitem>
975	<para>
976	<computeroutput>--paravirtprovider
977	none\|default\|legacy\|minimal\|hyperv\|kvm</computeroutput>:
978	Specifies which paravirtualization interface to provide to
979	the guest operating system. Specifying
980	<computeroutput>none</computeroutput> explicitly turns off
981	exposing any paravirtualization interface. The option
982	<computeroutput>default</computeroutput> selects an
983	appropriate interface when starting the VM, depending on the
984	guest OS type. This is the default option chosen when
985	creating new VMs. The
986	<computeroutput>legacy</computeroutput> option is used for
987	VMs which were created with older &product-name; versions
988	and will pick a paravirtualization interface when starting
989	the VM with &product-name; 5.0 and newer. The
990	<computeroutput>minimal</computeroutput> provider is
991	mandatory for Mac OS X guests.
992	<computeroutput>kvm</computeroutput> and
993	<computeroutput>hyperv</computeroutput> are recommended for
994	Linux and Windows guests respectively. These options are
995	explained in <xref linkend="gimproviders" />.
996	</para>
997	</listitem>
998
999	<listitem>
1000	<para>
1001	<computeroutput>--paravirtdebug <keyword=value>
1002	[,<keyword=value> ...]</computeroutput>: Specifies
1003	debugging options specific to the paravirtualization
1004	provider configured for this VM. See the provider specific
1005	options in <xref linkend="gimdebug" /> for a list of
1006	supported keyword-value pairs for each provider.
1007	</para>
1008	</listitem>
1009
1010	<listitem>
1011	<para>
1012	<computeroutput>--nestedpaging on\|off</computeroutput>: If
1013	hardware virtualization is enabled, this additional setting
1014	enables or disables the use of the nested paging feature in
1015	the processor of your host system. See
1016	<xref linkend="hwvirt" /> and
1017	<xref linkend="sec-rec-cve-2018-3646" />.
1018	</para>
1019	</listitem>
1020
1021	<listitem>
1022	<para>
1023	<computeroutput>--largepages on\|off</computeroutput>: If
1024	hardware virtualization <emphasis>and</emphasis> nested
1025	paging are enabled, for Intel VT-x only, an additional
1026	performance improvement of up to 5% can be obtained by
1027	enabling this setting. This causes the hypervisor to use
1028	large pages to reduce TLB use and overhead.
1029	</para>
1030	</listitem>
1031
1032	<listitem>
1033	<para>
1034	<computeroutput>--vtxvpid on\|off</computeroutput>: If
1035	hardware virtualization is enabled, for Intel VT-x only,
1036	this additional setting enables or disables the use of the
1037	tagged TLB (VPID) feature in the processor of your host
1038	system. See <xref linkend="hwvirt" />.
1039	</para>
1040	</listitem>
1041
1042	<listitem>
1043	<para>
1044	<computeroutput>--vtxux on\|off</computeroutput>: If hardware
1045	virtualization is enabled, for Intel VT-x only, this setting
1046	enables or disables the use of the unrestricted guest mode
1047	feature for executing your guest.
1048	</para>
1049	</listitem>
1050
1051	<listitem>
1052	<para>
1053	<computeroutput>--nested-hw-virt on\|off</computeroutput>: If
1054	hardware virtualization is enabled, this setting enables or
1055	disables passthrough of hardware virtualization features to
1056	the guest. See <xref linkend="nested-virt" />.
1057	</para>
1058	</listitem>
1059
1060	<listitem>
1061	<para>
1062	<computeroutput>--virt-vmsave-vmload on\|off</computeroutput>:
1063	If hardware virtualization is enabled, for AMD-V only, this
1064	setting enables or disables the use of the virtualized
1065	vmsave/vmload host feature while executing your guest. It is
1066	enabled by default. It is recommended to leave enabled as it
1067	has a drastic impact on performance while executing nested
1068	guests using the nested hardware virtualization feature.
1069	</para>
1070	</listitem>
1071
1072	<listitem>
1073	<para>
1074	<computeroutput>--accelerate3d on\|off</computeroutput>: If
1075	the Guest Additions are installed, this setting enables or
1076	disables hardware 3D acceleration. See
1077	<xref linkend="guestadd-3d" />.
1078	</para>
1079	</listitem>
1080
1081	<listitem>
1082	<para>
1083	<computeroutput>--accelerate2dvideo on\|off</computeroutput>:
1084	If the Guest Additions are installed, this setting enables
1085	or disables 2D video acceleration. See
1086	<xref linkend="guestadd-2d" />.
1087	</para>
1088	</listitem>
1089
1090	<listitem>
1091	<para>
1092	<computeroutput>--chipset piix3\|ich9</computeroutput>: By
1093	default, &product-name; emulates an Intel PIIX3 chipset.
1094	Usually there is no reason to change the default setting
1095	unless this is required to relax some of its constraints.
1096	See <xref linkend="settings-motherboard" />.
1097	</para>
1098	</listitem>
1099
1100	<listitem>
1101	<para>
1102	You can influence the BIOS logo that is displayed when a
1103	virtual machine starts up with a number of settings. By
1104	default, an &product-name; logo is displayed.
1105	</para>
1106
1107	<para>
1108	With <computeroutput>--bioslogofadein
1109	on\|off</computeroutput> and
1110	<computeroutput>--bioslogofadeout on\|off</computeroutput>,
1111	you can determine whether the logo should fade in and out,
1112	respectively.
1113	</para>
1114
1115	<para>
1116	With <computeroutput>--bioslogodisplaytime
1117	<msec></computeroutput> you can set how long the logo
1118	should be visible, in milliseconds.
1119	</para>
1120
1121	<para>
1122	With <computeroutput>--bioslogoimagepath
1123	<imagepath></computeroutput> you can replace the image
1124	that is shown with your own logo. The image must be an
1125	uncompressed 256 color BMP file without color space
1126	information (Windows 3.0 format). The image must not be
1127	bigger than 640 x 480.
1128	</para>
1129	</listitem>
1130
1131	<listitem>
1132	<para>
1133	<computeroutput>--biosbootmenu
1134	disabled\|menuonly\|messageandmenu</computeroutput>: Specifies
1135	whether the BIOS enables the user to select a temporary boot
1136	device. The <computeroutput>menuonly</computeroutput> option
1137	suppresses the message, but the user can still press F12 to
1138	select a temporary boot device.
1139	</para>
1140	</listitem>
1141
1142	<listitem>
1143	<para>
1144	<computeroutput>--biosapic
1145	x2apic\|apic\|disabled</computeroutput>: Specifies the
1146	firmware APIC level to be used. Options are: x2apic, apic or
1147	disabled (no apic or x2apic) respectively.
1148	</para>
1149
1150	<para>
1151	Note that if x2apic is specified and x2APIC is unsupported
1152	by the VCPU, biosapic downgrades to apic, if supported.
1153	Otherwise biosapic downgrades to disabled. Similarly, if
1154	apic is specified, and APIC is unsupported, a downgrade to
1155	disabled results.
1156	</para>
1157	</listitem>
1158
1159	<listitem>
1160	<para>
1161	<computeroutput>--biossystemtimeoffset
1162	<ms></computeroutput>: Specifies a fixed time offset,
1163	in milliseconds, of the guest relative to the host time. If
1164	the offset is positive, the guest time runs ahead of the
1165	host time.
1166	</para>
1167	</listitem>
1168
1169	<listitem>
1170	<para>
1171	<computeroutput>--biospxedebug on\|off</computeroutput>:
1172	Enables or disables additional debugging output when using
1173	the Intel PXE boot ROM. The output is written to the release
1174	log file. See <xref linkend="collect-debug-info" />.
1175	</para>
1176	</listitem>
1177
1178	<listitem>
1179	<para>
1180	<computeroutput>--system-uuid-le on\|off</computeroutput>:
1181	Enables or disables representing the system UUID in little
1182	endian form. The default value is <literal>on</literal> for
1183	new VMs. For old VMs the setting is <literal>off</literal>
1184	to keep the content of the DMI/SMBIOS table unchanged, which
1185	can be important for Windows license activation.
1186	</para>
1187	</listitem>
1188
1189	<listitem>
1190	<para>
1191	<computeroutput>--boot<1-4>
1192	none\|floppy\|dvd\|disk\|net</computeroutput>: Specifies the
1193	boot order for the virtual machine. There are four
1194	<emphasis>slots</emphasis>, which the VM will try to access
1195	from 1 to 4, and for each of which you can set a device that
1196	the VM should attempt to boot from.
1197	</para>
1198	</listitem>
1199
1200	<listitem>
1201	<para>
1202	<computeroutput>--rtcuseutc on\|off</computeroutput>: Sets
1203	the real-time clock (RTC) to operate in UTC time. See
1204	<xref linkend="settings-motherboard" />.
1205	</para>
1206	</listitem>
1207
1208	<listitem>
1209	<para>
1210	<computeroutput>--graphicscontroller
1211	none\|vboxvga\|vmsvga\|vboxsvga</computeroutput>: Specifies the
1212	use of a graphics controller, with an option to choose a
1213	specific type. See <xref linkend="settings-screen" />.
1214	</para>
1215	</listitem>
1216
1217	<listitem>
1218	<para>
1219	<computeroutput>--snapshotfolder
1220	default\|<path></computeroutput>: Specifies the folder
1221	where snapshots are kept for a virtual machine.
1222	</para>
1223	</listitem>
1224
1225	<listitem>
1226	<para>
1227	<computeroutput>--firmware
1228	bios\|efi\|efi32\|efi64</computeroutput>: Specifies the
1229	firmware to be used to boot the VM: Available options are:
1230	BIOS, or one of the EFI options: efi, efi32, or efi64. Use
1231	EFI options with care.
1232	</para>
1233	</listitem>
1234
1235	<listitem>
1236	<para>
1237	<computeroutput>--guestmemoryballoon
1238	<size></computeroutput> Sets the default size of the
1239	guest memory balloon. This is the memory allocated by the
1240	&product-name; Guest Additions from the guest operating
1241	system and returned to the hypervisor for reuse by other
1242	virtual machines.
1243	<computeroutput><size></computeroutput> must be
1244	specified in megabytes. The default size is 0 megabytes. See
1245	<xref linkend="guestadd-balloon" />.
1246	</para>
1247	</listitem>
1248
1249	<listitem>
1250	<para>
1251	<computeroutput>--defaultfrontend
1252	default\|<name></computeroutput>: Specifies the default
1253	frontend to be used when starting this VM. See
1254	<xref linkend="vboxmanage-startvm" />.
1255	</para>
1256	</listitem>
1257
1258	<listitem>
1259	<para>
1260	<computeroutput>--vm-process-priority
1261	default\|flat\|low\|normal\|high</computeroutput>: Specifies the
1262	priority scheme of the VM process to be used when starting
1263	this VM and during VM execution. See
1264	<xref linkend="vboxmanage-startvm" />.
1265	</para>
1266	</listitem>
1267
1268	</itemizedlist>
1269
1270	</sect2>
1271
1272	<sect2 id="vboxmanage-modifyvm-networking">
1273
1274	<title>Networking Settings</title>
1275
1276	<para>
1277	The following networking settings are available through
1278	<command>VBoxManage modifyvm</command>. With all these settings,
1279	the decimal number directly following the option name, 1-N in
1280	the list below, specifies the virtual network adapter whose
1281	settings should be changed.
1282	</para>
1283
1284	<itemizedlist>
1285
1286	<listitem>
1287	<para>
1288	<computeroutput>--nic<1-N>
1289	none\|null\|nat\|natnetwork\|bridged\|intnet\|hostonly\|generic</computeroutput>:
1290	Configures the type of networking for each of the VM's
1291	virtual network cards. Options are: not present
1292	(<computeroutput>none</computeroutput>), not connected to
1293	the host (<computeroutput>null</computeroutput>), use
1294	network address translation
1295	(<computeroutput>nat</computeroutput>), use the new network
1296	address translation engine
1297	(<computeroutput>natnetwork</computeroutput>), bridged
1298	networking (<computeroutput>bridged</computeroutput>), or
1299	use internal networking
1300	(<computeroutput>intnet</computeroutput>), host-only
1301	networking (<computeroutput>hostonly</computeroutput>), or
1302	access rarely used sub-modes
1303	(<computeroutput>generic</computeroutput>). These options
1304	correspond to the modes described in
1305	<xref linkend="networkingmodes" />.
1306	</para>
1307	</listitem>
1308
1309	<listitem>
1310	<para>
1311	<computeroutput>--nictype<1-N>
1312	Am79C970A\|Am79C973\|Am79C970\|82540EM\|82543GC\|82545EM\|virtio</computeroutput>:
1313	Enables you to specify the networking hardware that
1314	&product-name; presents to the guest for a specified VM
1315	virtual network card. See <xref linkend="nichardware" />.
1316	</para>
1317	</listitem>
1318
1319	<listitem>
1320	<para>
1321	<computeroutput>--cableconnected<1-N>
1322	on\|off</computeroutput>: Enables you to temporarily
1323	disconnect a virtual network interface, as if a network
1324	cable had been pulled from a real network card. This might
1325	be useful, for example for resetting certain software
1326	components in the VM.
1327	</para>
1328	</listitem>
1329
1330	<listitem>
1331	<para>
1332	With the <computeroutput>nictrace</computeroutput> options,
1333	you can optionally trace network traffic by dumping it to a
1334	file, for debugging purposes.
1335	</para>
1336
1337	<para>
1338	With <computeroutput>--nictrace<1-N>
1339	on\|off</computeroutput>, you can enable network tracing for
1340	a particular virtual network card.
1341	</para>
1342
1343	<para>
1344	If enabled, you must specify with
1345	<computeroutput>--nictracefile<1-N>
1346	<filename></computeroutput> the absolute path of the
1347	file the trace should be logged to.
1348	</para>
1349	</listitem>
1350
1351	<listitem>
1352	<para>
1353	<computeroutput>--nicproperty<1-N>
1354	<paramname>="paramvalue"</computeroutput>: This
1355	option, in combination with
1356	<computeroutput>nicgenericdrv</computeroutput> enables you
1357	to pass parameters to rarely-used network backends.
1358	</para>
1359
1360	<para>
1361	These parameters are backend engine-specific, and are
1362	different between UDP Tunnel and the VDE backend drivers.
1363	For examples, see <xref linkend="network_udp_tunnel" />.
1364	</para>
1365	</listitem>
1366
1367	<listitem>
1368	<para>
1369	<computeroutput>--nicspeed<1-N>
1370	<kbps></computeroutput>: Only has an effect if generic
1371	networking has been enabled for a particular virtual network
1372	card. See the <computeroutput>--nic</computeroutput> option.
1373	This mode enables access to rarely used networking
1374	sub-modes, such as VDE network or UDP Tunnel. This option
1375	specifies the throughput rate in KBps.
1376	</para>
1377	</listitem>
1378
1379	<listitem>
1380	<para>
1381	<computeroutput>--nicbootprio<1-N>
1382	<priority></computeroutput>: Specifies the order in
1383	which NICs are tried for booting over the network, using
1384	PXE. The priority is an integer in the 0 to 4 range.
1385	Priority 1 is the highest, priority 4 is low. Priority 0,
1386	which is the default unless otherwise specified, is the
1387	lowest.
1388	</para>
1389
1390	<para>
1391	Note that this option only has an effect when the Intel PXE
1392	boot ROM is used.
1393	</para>
1394	</listitem>
1395
1396	<listitem>
1397	<para>
1398	<computeroutput>--nicpromisc<1-N>
1399	deny\|allow-vms\|allow-all</computeroutput>: Enables you to
1400	specify how promiscuous mode is handled for the specified VM
1401	virtual network card. This setting is only relevant for
1402	bridged networking. <computeroutput>deny</computeroutput>,
1403	the default setting, hides any traffic not intended for the
1404	VM. <computeroutput>allow-vms</computeroutput> hides all
1405	host traffic from the VM, but allows the VM to see traffic
1406	to and from other VMs.
1407	<computeroutput>allow-all</computeroutput> removes this
1408	restriction completely.
1409	</para>
1410	</listitem>
1411
1412	<listitem>
1413	<para>
1414	<computeroutput>--nicbandwidthgroup<1-N>
1415	none\|<name></computeroutput>: Adds and removes an
1416	assignment of a bandwidth group for the specified virtual
1417	network interface. Specifying
1418	<computeroutput>none</computeroutput> removes any current
1419	bandwidth group assignment from the specified virtual
1420	network interface. Specifying
1421	<computeroutput><name></computeroutput> adds an
1422	assignment of a bandwidth group to the specified virtual
1423	network interface.
1424	</para>
1425
1426	<para>
1427	See <xref linkend="network_bandwidth_limit" />.
1428	</para>
1429	</listitem>
1430
1431	<listitem>
1432	<para>
1433	<computeroutput>--bridgeadapter<1-N>
1434	none\|<devicename></computeroutput>: Only has an effect
1435	if bridged networking has been enabled for a virtual network
1436	card. See the <computeroutput>--nic</computeroutput> option.
1437	Use this option to specify which host interface the given
1438	virtual network interface will use. See
1439	<xref linkend="network_bridged" />.
1440	</para>
1441	</listitem>
1442
1443	<listitem>
1444	<para>
1445	<computeroutput>--hostonlyadapter<1-N>
1446	none\|<devicename></computeroutput>: Only has an effect
1447	if host-only networking has been enabled for a virtual
1448	network card. See the <computeroutput>--nic</computeroutput>
1449	option. Use this option to specify which host-only
1450	networking interface the given virtual network interface
1451	will use. See <xref linkend="network_hostonly" />.
1452	</para>
1453	</listitem>
1454
1455	<listitem>
1456	<para>
1457	<computeroutput>--intnet<1-N>
1458	network</computeroutput>: Only has an effect if internal
1459	networking has been enabled for a virtual network card. See
1460	the <computeroutput>--nic</computeroutput> option. Use this
1461	option to specify the name of the internal network. See
1462	<xref linkend="network_internal" />.
1463	</para>
1464	</listitem>
1465
1466	<listitem>
1467	<para>
1468	<computeroutput>--nat-network<1-N> <network
1469	name></computeroutput>: If the networking type is set to
1470	<computeroutput>natnetwork</computeroutput>, not
1471	<computeroutput>nat</computeroutput>, then this setting
1472	specifies the name of the NAT network this adapter is
1473	connected to. Optional.
1474	</para>
1475	</listitem>
1476
1477	<listitem>
1478	<para>
1479	<computeroutput>--nicgenericdrv<1-N> <backend
1480	driver></computeroutput>: Only has an effect if generic
1481	networking has been enabled for a virtual network card. See
1482	the <computeroutput>--nic</computeroutput> option. This mode
1483	enables you to access rarely used networking sub-modes, such
1484	as VDE network or UDP Tunnel.
1485	</para>
1486	</listitem>
1487
1488	<listitem>
1489	<para>
1490	<computeroutput>--macaddress<1-N>
1491	auto\|<mac></computeroutput>: With this option you can
1492	set the MAC address of a particular network adapter on the
1493	VM. Normally, each network adapter is assigned a random
1494	address by &product-name; at VM creation.
1495	</para>
1496	</listitem>
1497
1498	</itemizedlist>
1499
1500	<sect3 id="vboxmanage-modifyvm-networking-nat">
1501
1502	<title>NAT Networking Settings</title>
1503
1504	<para>
1505	The following NAT networking settings are available through
1506	<command>VBoxManage modifyvm</command>. With all these
1507	settings, the decimal number directly following the option
1508	name, 1-N in the list below, specifies the virtual network
1509	adapter whose settings should be changed.
1510	</para>
1511
1512	<itemizedlist>
1513
1514	<listitem>
1515	<para>
1516	<computeroutput>--natnet<1-N>
1517	<network>\|default</computeroutput>: If the
1518	networking type is set to
1519	<computeroutput>nat</computeroutput>, not
1520	<computeroutput>natnetwork</computeroutput>, then this
1521	setting specifies the IP address range to be used for this
1522	network. See <xref linkend="changenat" />.
1523	</para>
1524	</listitem>
1525
1526	<listitem>
1527	<para>
1528	<computeroutput>--natpf<1-N>
1529	[<name>],tcp\|udp,[<hostip>],<hostport>,[<guestip>],
1530	<guestport></computeroutput>: Defines a NAT
1531	port-forwarding rule. See <xref linkend="natforward" />.
1532	</para>
1533	</listitem>
1534
1535	<listitem>
1536	<para>
1537	<computeroutput>--natpf<1-N> delete
1538	<name></computeroutput>: Deletes a NAT
1539	port-forwarding rule. See <xref linkend="natforward" />.
1540	</para>
1541	</listitem>
1542
1543	<listitem>
1544	<para>
1545	<computeroutput>--nattftpprefix<1-N>
1546	<prefix></computeroutput>: Defines a prefix for the
1547	built-in TFTP server. For example, where the boot file is
1548	located. See <xref linkend="nat-tftp" /> and
1549	<xref linkend="nat-adv-tftp" />.
1550	</para>
1551	</listitem>
1552
1553	<listitem>
1554	<para>
1555	<computeroutput>--nattftpfile<1-N>
1556	<bootfile></computeroutput>: Defines the TFT boot
1557	file. See <xref linkend="nat-adv-tftp" />.
1558	</para>
1559	</listitem>
1560
1561	<listitem>
1562	<para>
1563	<computeroutput>--nattftpserver<1-N>
1564	<tftpserver></computeroutput>: Defines the TFTP
1565	server address to boot from. See
1566	<xref linkend="nat-adv-tftp" />.
1567	</para>
1568	</listitem>
1569
1570	<listitem>
1571	<para>
1572	<computeroutput>--nattbindip<1-N>
1573	<ip;></computeroutput>: &product-name;'s NAT engine
1574	normally routes TCP/IP packets through the default
1575	interface assigned by the host's TCP/IP stack. Use this
1576	setting to instruct the NAT engine to bind to a specified
1577	IP address instead. See
1578	<xref linkend="nat-adv-settings" />.
1579	</para>
1580	</listitem>
1581
1582	<listitem>
1583	<para>
1584	<computeroutput>--natdnspassdomain<1-N>
1585	on\|off</computeroutput>: Specifies whether the built-in
1586	DHCP server passes the domain name for network name
1587	resolution.
1588	</para>
1589	</listitem>
1590
1591	<listitem>
1592	<para>
1593	<computeroutput>--natdnsproxy<1-N>
1594	on\|off</computeroutput>: Makes the NAT engine proxy all
1595	guest DNS requests to the host's DNS servers. See
1596	<xref linkend="nat-adv-dns" />.
1597	</para>
1598	</listitem>
1599
1600	<listitem>
1601	<para>
1602	<computeroutput>--natdnshostresolver<1-N>
1603	on\|off</computeroutput>: Makes the NAT engine use the
1604	host's resolver mechanisms to handle DNS requests. See
1605	<xref linkend="nat-adv-dns" />.
1606	</para>
1607	</listitem>
1608
1609	<listitem>
1610	<para>
1611	<computeroutput>--natsettings<1-N>
1612	[<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
1613	[<tcprcv>]</computeroutput>: Controls several NAT
1614	settings. See <xref linkend="nat-adv-settings" />.
1615	</para>
1616	</listitem>
1617
1618	<listitem>
1619	<para>
1620	<computeroutput>--nataliasmode<1-N>
1621	default\|[log],[proxyonly],[sameports]</computeroutput>:
1622	Defines behaviour of the NAT engine core: log - enables
1623	logging, proxyonly - switches off aliasing mode and makes
1624	NAT transparent, sameports - enforces the NAT engine to
1625	send packets through the same port as they originated on,
1626	default - disable all aliasing modes. See
1627	<xref linkend="nat-adv-alias" />.
1628	</para>
1629	</listitem>
1630
1631	</itemizedlist>
1632
1633	</sect3>
1634
1635	</sect2>
1636
1637	<sect2 id="vboxmanage-modifyvm-other">
1638
1639	<title>Miscellaneous Settings</title>
1640
1641	<para>
1642	The following hardware settings, such as serial port, audio,
1643	clipboard, drag and drop, monitor, and USB settings are
1644	available through <command>VBoxManage modifyvm</command>:
1645	</para>
1646
1647	<itemizedlist>
1648
1649	<listitem>
1650	<para>
1651	<computeroutput>--mouse
1652	<ps2\|usb\|usbtablet\|usbmultitouch></computeroutput>:
1653	Specifies the mode of the mouse to be used in the VM.
1654	Available options are: ps2, usb, usbtablet, usbmultitouch.
1655	</para>
1656	</listitem>
1657
1658	<listitem>
1659	<para>
1660	<computeroutput>--keyboard <ps2\|usb></computeroutput>:
1661	Specifies the mode of the keyboard to be used in the VM.
1662	Available options are: ps2, usb.
1663	</para>
1664	</listitem>
1665
1666	<listitem>
1667	<para>
1668	<computeroutput>--uart<1-N> off\|<I/O base>
1669	<IRQ></computeroutput>: Configures virtual serial
1670	ports for the VM. See <xref linkend="serialports" />.
1671	</para>
1672	</listitem>
1673
1674	<listitem>
1675	<para>
1676	<computeroutput>--uartmode<1-N>
1677	<arg></computeroutput>: Controls how &product-name;
1678	connects a given virtual serial port, configured with the
1679	<computeroutput>--uartX</computeroutput> setting, to the
1680	host on which the virtual machine is running. As described
1681	in <xref linkend="serialports" />, for each such port, you
1682	can specify <computeroutput><arg></computeroutput> as
1683	one of the following options:
1684	</para>
1685
1686	<itemizedlist>
1687
1688	<listitem>
1689	<para>
1690	<computeroutput>disconnected</computeroutput>: Even
1691	though the serial port is shown to the guest, it has no
1692	"other end". This is like a real COM port without a
1693	cable.
1694	</para>
1695	</listitem>
1696
1697	<listitem>
1698	<para>
1699	<computeroutput>server
1700	<pipename></computeroutput>: On a Windows host,
1701	this tells &product-name; to create a named pipe on the
1702	host named
1703	<computeroutput><pipename></computeroutput> and
1704	connect the virtual serial device to it. Note that
1705	Windows requires that the name of a named pipe begins
1706	with <filename>\\.\pipe\</filename>.
1707	</para>
1708
1709	<para>
1710	On a Linux host, instead of a named pipe, a local domain
1711	socket is used.
1712	</para>
1713	</listitem>
1714
1715	<listitem>
1716	<para>
1717	<computeroutput>client
1718	<pipename></computeroutput>: Operates as for
1719	<computeroutput>server</computeroutput>, except that the
1720	pipe, or local domain socket, is not created by
1721	&product-name; but is assumed to exist already.
1722	</para>
1723	</listitem>
1724
1725	<listitem>
1726	<para>
1727	<computeroutput>tcpserver <port></computeroutput>:
1728	Configures &product-name; to create a TCP socket on the
1729	host with TCP
1730	<computeroutput><port></computeroutput> and
1731	connect the virtual serial device to it. Note that
1732	UNIX-like systems require ports over 1024 for normal
1733	users.
1734	</para>
1735	</listitem>
1736
1737	<listitem>
1738	<para>
1739	<computeroutput>tcpclient
1740	<hostname:port></computeroutput>: Operates as for
1741	<computeroutput>tcpserver</computeroutput>, except that
1742	the TCP socket is not created by &product-name;, but is
1743	assumed to exist already.
1744	</para>
1745	</listitem>
1746
1747	<listitem>
1748	<para>
1749	<computeroutput>file <file></computeroutput>:
1750	Redirects the serial port output to a raw file
1751	<file> specified by its absolute path on the host
1752	file system.
1753	</para>
1754	</listitem>
1755
1756	<listitem>
1757	<para>
1758	<computeroutput><devicename></computeroutput>: If,
1759	instead of the above options, the device name of a
1760	physical hardware serial port of the host is specified,
1761	the virtual serial port is connected to that hardware
1762	port. On a Windows host, the device name will be a COM
1763	port such as <computeroutput>COM1</computeroutput>. On a
1764	Linux host, the device name will be
1765	<filename>/dev/ttyS0</filename> or similar. This enables
1766	you to wire up a real serial port to a virtual machine.
1767	</para>
1768	</listitem>
1769
1770	</itemizedlist>
1771	</listitem>
1772
1773	<listitem>
1774	<para>
1775	<computeroutput>uarttype <1-N>
1776	16450\|16550A\|16750</computeroutput>: Configures the UART
1777	type for a virtual serial port. The default UART type is
1778	16550A.
1779	</para>
1780	</listitem>
1781
1782	<listitem>
1783	<para>
1784	<computeroutput>--lptmode<1-N>
1785	<Device></computeroutput>: Specifies the Device Name
1786	of the parallel port that the Parallel Port feature will be
1787	using. Use this <emphasis>before</emphasis>
1788	<computeroutput>--lpt</computeroutput>. This feature depends
1789	on the host operating system. For Windows hosts, use a
1790	device name such as lpt1. On Linux hosts, use a device name
1791	such as /dev/lp0.
1792	</para>
1793	</listitem>
1794
1795	<listitem>
1796	<para>
1797	<computeroutput>--lpt<1-N> <I/O base>
1798	<IRQ></computeroutput>: Specifies the I/O address of
1799	the parallel port and the IRQ number that the Parallel Port
1800	feature will be using. Optional. Use this
1801	<emphasis>after</emphasis>
1802	<computeroutput>--lptmod</computeroutput>. I/O base address
1803	and IRQ are the values that guest sees. For example, the
1804	values avalable under guest Device Manager.
1805	</para>
1806	</listitem>
1807
1808	<listitem>
1809	<para>
1810	<computeroutput>--audio
1811	none\|null\|dsound\|oss\|alsa\|pulse\|coreaudio</computeroutput>:
1812	Specifies whether the VM should have audio support, and if
1813	so, which type. The list of supported audio types depends on
1814	the host and can be determined with <command>VBoxManage
1815	modifyvm</command>.
1816	</para>
1817	</listitem>
1818
1819	<listitem>
1820	<para>
1821	<computeroutput>--audiocontroller
1822	ac97\|hda\|sb16</computeroutput>: Specifies the audio
1823	controller to be used with the VM.
1824	</para>
1825	</listitem>
1826
1827	<listitem>
1828	<para>
1829	<computeroutput>--audiocodec
1830	stac9700\|ad1980\|stac9221\|sb16</computeroutput>: Specifies
1831	the audio codec to be used with the VM.
1832	</para>
1833	</listitem>
1834
1835	<listitem>
1836	<para>
1837	<computeroutput>--audioin on</computeroutput>: Specifies
1838	whether capturing audio from the host is enabled or
1839	disabled.
1840	</para>
1841	</listitem>
1842
1843	<listitem>
1844	<para>
1845	<computeroutput>--audioout on</computeroutput>: Specifies
1846	whether audio playback from the guest is enabled or
1847	disabled.
1848	</para>
1849	</listitem>
1850
1851	<listitem>
1852	<para>
1853	<computeroutput>--clipboard-mode
1854	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
1855	Configues how the guest or host operating system's clipboard
1856	should be shared with the host or guest. See
1857	<xref linkend="generalsettings" />. This setting requires
1858	that the Guest Additions be installed in the virtual
1859	machine.
1860	</para>
1861	</listitem>
1862
1863	<listitem>
1864	<para>
1865	<computeroutput>--clipboard-file-transfers
1866	enabled\|disabled</computeroutput>: Specifies if clipboard
1867	file transfers are allowed between host and guest OSes or
1868	not.
1869	</para>
1870	</listitem>
1871
1872	<listitem>
1873	<para>
1874	<computeroutput>--draganddrop
1875	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
1876	Specifies the drag and drop mode to use between the host and
1877	the virtual machine. See <xref linkend="guestadd-dnd" />.
1878	This requires that the Guest Additions be installed in the
1879	virtual machine.
1880	</para>
1881	</listitem>
1882
1883	<listitem>
1884	<para>
1885	<computeroutput>--monitorcount
1886	<count></computeroutput>: Enables multi-monitor
1887	support. See <xref linkend="settings-display" />.
1888	</para>
1889	</listitem>
1890
1891	<listitem>
1892	<para>
1893	<computeroutput>--usb on\|off</computeroutput>: Enables and
1894	disables the VM's virtual USB controller. See
1895	<xref linkend="settings-usb" />.
1896	</para>
1897	</listitem>
1898
1899	<listitem>
1900	<para>
1901	<computeroutput>--usbehci on\|off</computeroutput>: Enables
1902	and disables the VM's virtual USB 2.0 controller. See
1903	<xref linkend="settings-usb" />.
1904	</para>
1905	</listitem>
1906
1907	<listitem>
1908	<para>
1909	<computeroutput>--usbxhci on\|off</computeroutput>: Enables
1910	and disables the VM's virtual USB 3.0 controller. See
1911	<xref linkend="settings-usb" />.
1912	</para>
1913	</listitem>
1914
1915	<listitem>
1916	<para>
1917	<computeroutput>--usbrename <oldname>
1918	<newname></computeroutput>: Enables renaming of the
1919	VM's virtual USB controller from <oldname> to
1920	<newname>.
1921	</para>
1922	</listitem>
1923
1924	</itemizedlist>
1925
1926	</sect2>
1927
1928	<sect2 id="vboxmanage-modifyvm-recording">
1929
1930	<title>Recording Settings</title>
1931
1932	<para>
1933	The <command>VBoxManage modifyvm</command> command enables you
1934	to modify recording settings for video recording, audio
1935	recording, or both.
1936	</para>
1937
1938	<para>
1939	Use the following options to update the recording settings:
1940	</para>
1941
1942	<itemizedlist>
1943
1944	<listitem>
1945	<para>
1946	<option>--recording on\|off</option> enables or disables the
1947	recording of a VM session into a WebM/VP8 file. When this
1948	option value is <computeroutput>on</computeroutput>,
1949	recording begins when the VM session starts.
1950	</para>
1951	</listitem>
1952
1953	<listitem>
1954	<para>
1955	<option>--recordingscreens
1956	all\|<replaceable>screen-ID</replaceable>
1957	[<replaceable>screen-ID</replaceable> ...]</option> enables
1958	you to specify which VM screens to record. The recording for
1959	each screen that you specify is saved to its own file.
1960	</para>
1961	</listitem>
1962
1963	<listitem>
1964	<para>
1965	<option>--recordingfile
1966	<replaceable>filename</replaceable></option> specifies the
1967	file in which to save the recording.
1968	</para>
1969	</listitem>
1970
1971	<listitem>
1972	<para>
1973	<option>--recordingmaxsize
1974	<replaceable>MB</replaceable></option> specifies the maximum
1975	size of the recorded video file in megabytes. The recording
1976	stops when the file reaches the specified size. If this
1977	value is zero, the recording continues until you stop the
1978	recording.
1979	</para>
1980	</listitem>
1981
1982	<listitem>
1983	<para>
1984	<option>--recordingmaxtime
1985	<replaceable>seconds</replaceable></option> specifies the
1986	maximum amount time to record in seconds. The recording
1987	stops after the specified number of seconds elapses. If this
1988	value is zero, the recording continues until you stop the
1989	recording.
1990	</para>
1991	</listitem>
1992
1993	<listitem>
1994	<para>
1995	<option>--recordingopts
1996	<replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable>
1997	...]</option> specifies additional video-recording options
1998	in a comma-separated keyword-value format. For example,
1999	<computeroutput>foo=bar,a=b</computeroutput>.
2000	</para>
2001
2002	<para>
2003	Only use this option only if you are an advanced user. For
2004	information about keywords, see <emphasis>Oracle VM
2005	VirtualBox Programming Guide and Reference</emphasis>.
2006	</para>
2007	</listitem>
2008
2009	<listitem>
2010	<para>
2011	<option>--recordingvideofps
2012	<replaceable>fps</replaceable></option> specifies the
2013	maximum number of video frames per second (FPS) to record.
2014	Frames that have a higher frequency are skipped. Increasing
2015	this value reduces the number of skipped frames and
2016	increases the file size.
2017	</para>
2018	</listitem>
2019
2020	<listitem>
2021	<para>
2022	<option>--recordingvideorate
2023	<replaceable>bit-rate</replaceable></option> specifies the
2024	bit rate of the video in kilobits per second. Increasing
2025	this value improves the appearance of the video at the cost
2026	of an increased file size.
2027	</para>
2028	</listitem>
2029
2030	<listitem>
2031	<para>
2032	<option>--recordingvideores
2033	<replaceable>width</replaceable>x<replaceable>height</replaceable></option>
2034	specifies the video resolution of the recorded video in
2035	pixels.
2036	</para>
2037	</listitem>
2038
2039	</itemizedlist>
2040
2041	</sect2>
2042
2043	<sect2 id="vboxmanage-modifyvm-vrde">
2044
2045	<title>Remote Machine Settings</title>
2046
2047	<para>
2048	The following settings that affect remote machine behavior are
2049	available through <command>VBoxManage modifyvm</command>:
2050	</para>
2051
2052	<itemizedlist>
2053
2054	<listitem>
2055	<para>
2056	<computeroutput>--vrde on\|off</computeroutput>: Enables and
2057	disables the VirtualBox Remote Desktop Extension (VRDE)
2058	server.
2059	</para>
2060	</listitem>
2061
2062	<listitem>
2063	<para>
2064	<computeroutput>--vrdeproperty
2065	"TCP/Ports\|Address=<value>"</computeroutput>: Sets the
2066	port numbers and IP address on the VM that the VRDE server
2067	can bind to.
2068	</para>
2069
2070	<itemizedlist>
2071
2072	<listitem>
2073	<para>
2074	For TCP/Ports, <value> should be a port or a range
2075	of ports that the VRDE server can bind to.
2076	<computeroutput>default</computeroutput> or
2077	<computeroutput>0</computeroutput> means port 3389, the
2078	standard port for RDP. See the description for the
2079	<computeroutput>--vrdeport</computeroutput> option in
2080	<xref linkend="vboxmanage-modifyvm-vrde" />.
2081	</para>
2082	</listitem>
2083
2084	<listitem>
2085	<para>
2086	For TCP/Address, <value> should be the IP address
2087	of the host network interface that the VRDE server will
2088	bind to. If specified, the server will accept
2089	connections only on the specified host network
2090	interface. See the description for the
2091	<computeroutput>--vrdeaddress</computeroutput> option in
2092	<xref linkend="vboxmanage-modifyvm-vrde" />.
2093	</para>
2094	</listitem>
2095
2096	</itemizedlist>
2097	</listitem>
2098
2099	<listitem>
2100	<para>
2101	<computeroutput>--vrdeproperty
2102	"VideoChannel/Enabled\|Quality\|DownscaleProtection=<value>"</computeroutput>:
2103	Sets the VRDP video redirection properties.
2104	</para>
2105
2106	<itemizedlist>
2107
2108	<listitem>
2109	<para>
2110	For VideoChannel/Enabled, <value> can be set to
2111	"1", switching the VRDP video channel on. See
2112	<xref linkend="vrde-videochannel" />.
2113	</para>
2114	</listitem>
2115
2116	<listitem>
2117	<para>
2118	For VideoChannel/Quality, <value> should be set
2119	between 10 and 100% inclusive, representing a JPEG
2120	compression level on the VRDE server video channel.
2121	Lower values mean lower quality but higher compression.
2122	See <xref linkend="vrde-videochannel" />.
2123	</para>
2124	</listitem>
2125
2126	<listitem>
2127	<para>
2128	For VideoChannel/DownscaleProtection, <value> can
2129	be set to "1" to enable the videochannel downscale
2130	protection feature. When enabled, if a video's size
2131	equals the shadow buffer size, then it is regarded as a
2132	full screen video, and is displayed. But if its size is
2133	between fullscreen and the downscale threshold then it
2134	is <emphasis>not</emphasis> displayed, as it could be an
2135	application window, which would be unreadable when
2136	downscaled. When the downscale protection feature is
2137	disabled, an attempt is always made to display videos.
2138	</para>
2139	</listitem>
2140
2141	</itemizedlist>
2142	</listitem>
2143
2144	<listitem>
2145	<para>
2146	<computeroutput>--vrdeproperty
2147	"Client/DisableDisplay\|DisableInput\|DisableAudio\|DisableUSB=1"</computeroutput>:
2148	Disables one of the VRDE server features: Display, Input,
2149	Audio or USB respectively. To reenable a feature, use
2150	"Client/DisableDisplay=" for example. See
2151	<xref linkend="vrde-customization" />.
2152	</para>
2153	</listitem>
2154
2155	<listitem>
2156	<para>
2157	<computeroutput>--vrdeproperty
2158	"Client/DisableClipboard\|DisableUpstreamAudio=1"</computeroutput>:
2159	Disables one of the VRDE server features: Clipboard or
2160	UpstreamAudio respectively. To reenable a feature, use
2161	"Client/DisableClipboard=" for example. See
2162	<xref linkend="vrde-customization" />.
2163	</para>
2164	</listitem>
2165
2166	<listitem>
2167	<para>
2168	<computeroutput>--vrdeproperty
2169	"Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE
2170	server feature: RDP device redirection for smart cards. To
2171	reenable this feature, use "Client/DisableRDPR=".
2172	</para>
2173	</listitem>
2174
2175	<listitem>
2176	<para>
2177	<computeroutput>--vrdeproperty
2178	"H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE
2179	server feature: 3D redirection. To disable this feature, use
2180	"H3DRedirect/Enabled=".
2181	</para>
2182	</listitem>
2183
2184	<listitem>
2185	<para>
2186	<computeroutput>--vrdeproperty
2187	"Security/Method\|ServerCertificate\|ServerPrivateKey\|CACertificate=<value>"</computeroutput>:
2188	Sets the desired security method and path of server
2189	certificate, path of server private key, path of CA
2190	certificate, that are used for a connection.
2191	</para>
2192
2193	<itemizedlist>
2194
2195	<listitem>
2196	<para>
2197	<computeroutput>--vrdeproperty
2198	"Security/Method=<value>"</computeroutput> sets
2199	the desired security method, which is used for a
2200	connection. Valid values are:
2201	</para>
2202
2203	<itemizedlist>
2204
2205	<listitem>
2206	<para>
2207	<computeroutput>Negotiate</computeroutput>: Both
2208	Enhanced (TLS) and Standard RDP Security connections
2209	are allowed. The security method is negotiated with
2210	the client. This is the default setting.
2211	</para>
2212	</listitem>
2213
2214	<listitem>
2215	<para>
2216	<computeroutput>RDP</computeroutput>: Only Standard
2217	RDP Security is accepted.
2218	</para>
2219	</listitem>
2220
2221	<listitem>
2222	<para>
2223	<computeroutput>TLS</computeroutput>: Only Enhanced
2224	RDP Security is accepted. The client must support
2225	TLS.
2226	</para>
2227	</listitem>
2228
2229	</itemizedlist>
2230
2231	<para>
2232	See <xref linkend="vrde-crypt" />.
2233	</para>
2234	</listitem>
2235
2236	<listitem>
2237	<para>
2238	<computeroutput>--vrdeproperty
2239	"Security/ServerCertificate=<value>"</computeroutput>
2240	where <value> is the absolute path of the server
2241	certificate. See <xref linkend="vrde-crypt" />.
2242	</para>
2243	</listitem>
2244
2245	<listitem>
2246	<para>
2247	<computeroutput>--vrdeproperty
2248	"Security/ServerPrivateKey=<value>"</computeroutput>
2249	where <value> is the absolute path of the server
2250	private key. See <xref linkend="vrde-crypt" />.
2251	</para>
2252	</listitem>
2253
2254	<listitem>
2255	<para>
2256	<computeroutput>--vrdeproperty
2257	"Security/CACertificate=<value>"</computeroutput>
2258	where <value> is the absolute path of the CA self
2259	signed certificate. See <xref linkend="vrde-crypt" />.
2260	</para>
2261	</listitem>
2262
2263	</itemizedlist>
2264	</listitem>
2265
2266	<listitem>
2267	<para>
2268	<computeroutput>--vrdeproperty
2269	"Audio/RateCorrectionMode\|LogPath=<value>"</computeroutput>
2270	sets the audio connection mode, or path of the audio
2271	logfile.
2272	</para>
2273
2274	<itemizedlist>
2275
2276	<listitem>
2277	<para>
2278	<computeroutput>--vrdeproperty
2279	"Audio/RateCorrectionMode=<value>"</computeroutput>
2280	where <value> is the desired rate correction mode.
2281	Allowed values are:
2282	</para>
2283
2284	<itemizedlist>
2285
2286	<listitem>
2287	<para>
2288	<computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>:
2289	No mode specified, use to unset any Audio mode
2290	already set.
2291	</para>
2292	</listitem>
2293
2294	<listitem>
2295	<para>
2296	<computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>:
2297	Rate correction mode.
2298	</para>
2299	</listitem>
2300
2301	<listitem>
2302	<para>
2303	<computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>:
2304	Low pass filter mode.
2305	</para>
2306	</listitem>
2307
2308	<listitem>
2309	<para>
2310	<computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>:
2311	Client sync mode to prevent underflow or overflow of
2312	the client queue.
2313	</para>
2314	</listitem>
2315
2316	</itemizedlist>
2317	</listitem>
2318
2319	<listitem>
2320	<para>
2321	<computeroutput>--vrdeproperty
2322	"Audio/LogPath=<value>"</computeroutput> where
2323	<value> is the absolute path of the Audio log
2324	file.
2325	</para>
2326	</listitem>
2327
2328	</itemizedlist>
2329	</listitem>
2330
2331	<listitem>
2332	<para>
2333	<computeroutput>--vrdeextpack
2334	default\|<name></computeroutput>: Specifies the library
2335	to use for accessing the VM remotely. The default is to use
2336	the RDP code which is part of the &product-name; Extension
2337	Pack.
2338	</para>
2339	</listitem>
2340
2341	<listitem>
2342	<para>
2343	<computeroutput>--vrdeport
2344	default\|<ports></computeroutput>: A port or a range of
2345	ports the VRDE server can bind to.
2346	<computeroutput>default</computeroutput> or
2347	<computeroutput>0</computeroutput> means port 3389, the
2348	standard port for RDP. You can specify a comma-separated
2349	list of ports or ranges of ports. Use a dash between two
2350	port numbers to specify a range. The VRDE server will bind
2351	to <emphasis>one</emphasis> of the available ports from the
2352	specified list. Only one machine can use a given port at a
2353	time. For example, the option <computeroutput> --vrdeport
2354	5000,5010-5012</computeroutput> will tell the server to bind
2355	to one of following ports: 5000, 5010, 5011, or 5012.
2356	</para>
2357	</listitem>
2358
2359	<listitem>
2360	<para>
2361	<computeroutput>--vrdeaddress <IP
2362	address></computeroutput>: The IP address of the host
2363	network interface the VRDE server will bind to. If
2364	specified, the server will accept connections only on the
2365	specified host network interface.
2366	</para>
2367
2368	<para>
2369	The setting can be used to specify whether the VRDP server
2370	should accept either IPv4, IPv6, or both connections:
2371	</para>
2372
2373	<itemizedlist>
2374
2375	<listitem>
2376	<para>
2377	Only IPv4: <computeroutput>--vrdeaddress
2378	"0.0.0.0"</computeroutput>
2379	</para>
2380	</listitem>
2381
2382	<listitem>
2383	<para>
2384	Only IPv6: <computeroutput>--vrdeaddress
2385	"::"</computeroutput>
2386	</para>
2387	</listitem>
2388
2389	<listitem>
2390	<para>
2391	Both IPv6 and IPv4: <computeroutput>--vrdeaddress
2392	""</computeroutput>
2393	</para>
2394
2395	<para>
2396	This is the default setting.
2397	</para>
2398	</listitem>
2399
2400	</itemizedlist>
2401	</listitem>
2402
2403	<listitem>
2404	<para>
2405	<computeroutput>--vrdeauthtype
2406	null\|external\|guest</computeroutput>: Enables you to
2407	indicate use of authorization, and specify how authorization
2408	will be performed. See <xref linkend="vbox-auth" />.
2409	</para>
2410	</listitem>
2411
2412	<listitem>
2413	<para>
2414	<computeroutput>--vrdeauthlibrary
2415	default\|<name></computeroutput>: Specifies the library
2416	used for RDP authentication. See
2417	<xref linkend="vbox-auth" />.
2418	</para>
2419	</listitem>
2420
2421	<listitem>
2422	<para>
2423	<computeroutput>--vrdemulticon on\|off</computeroutput>:
2424	Enables multiple connections to be made to the same VRDE
2425	server, if the server supports this feature. See
2426	<xref linkend="vrde-multiconnection" />.
2427	</para>
2428	</listitem>
2429
2430	<listitem>
2431	<para>
2432	<computeroutput>--vrdereusecon on\|off</computeroutput>: This
2433	specifies the VRDE server behavior when multiple connections
2434	are disabled. When this option is enabled, the server will
2435	allow a new client to connect and will drop the existing
2436	connection. When this option is disabled, the default
2437	setting, a new connection will not be accepted if there is
2438	already a client connected to the server.
2439	</para>
2440	</listitem>
2441
2442	<listitem>
2443	<para>
2444	<computeroutput>--vrdevideochannel on\|off</computeroutput>:
2445	Enables video redirection, if it is supported by the VRDE
2446	server. See <xref linkend="vrde-videochannel" />.
2447	</para>
2448	</listitem>
2449
2450	<listitem>
2451	<para>
2452	<computeroutput>--vrdevideochannelquality
2453	<percent></computeroutput>: Specifies the image
2454	quality for video redirection. See
2455	<xref linkend="vrde-videochannel" />.
2456	</para>
2457	</listitem>
2458
2459	</itemizedlist>
2460
2461	</sect2>
2462
2463	<sect2 id="vboxmanage-modifyvm-teleport">
2464
2465	<title>Teleporting Settings</title>
2466
2467	<para>
2468	With the following commands for <command>VBoxManage
2469	modifyvm</command> you can configure a machine to be a target
2470	for teleporting. See <xref linkend="teleporting" />.
2471	</para>
2472
2473	<itemizedlist>
2474
2475	<listitem>
2476	<para>
2477	<computeroutput>--teleporter on\|off</computeroutput>:
2478	Enables and disables the teleporter feature whereby when the
2479	machine is started, it waits to receive a teleporting
2480	request from the network instead of booting normally.
2481	Teleporting requests are received on the port and address
2482	specified using the following parameters.
2483	</para>
2484	</listitem>
2485
2486	<listitem>
2487	<para>
2488	<computeroutput>--teleporterport
2489	<port></computeroutput>,
2490	<computeroutput>--teleporteraddress
2491	<address></computeroutput>: These settings must be
2492	used with <computeroutput>--teleporter</computeroutput>.
2493	They specify the port and address the virtual machine should
2494	listen to in order to receive a teleporting request sent
2495	from another virtual machine.
2496	<computeroutput><port></computeroutput> can be any
2497	free TCP/IP port number, such as 6000.
2498	<computeroutput><address></computeroutput> can be any
2499	IP address or hostname and specifies the TCP/IP socket to
2500	bind to. The default is 0.0.0.0, which means any address.
2501	</para>
2502	</listitem>
2503
2504	<listitem>
2505	<para>
2506	<computeroutput>--teleporterpassword
2507	<password></computeroutput>: If this optional setting
2508	is used, then the teleporting request will only succeed if
2509	the source machine specifies the same password as the one
2510	given with this command.
2511	</para>
2512	</listitem>
2513
2514	<listitem>
2515	<para>
2516	<computeroutput>--teleporterpasswordfile
2517	<password></computeroutput>: If this optional setting
2518	is used, then the teleporting request will only succeed if
2519	the source machine specifies the same password as the one
2520	specified in the file give with this command. Use
2521	<computeroutput>stdin</computeroutput> to read the password
2522	from stdin.
2523	</para>
2524	</listitem>
2525
2526	<listitem>
2527	<para>
2528	<computeroutput>--cpuid <leaf> <eax> <ebx>
2529	<ecx> <edx></computeroutput>: Advanced users can
2530	use this setting before a teleporting operation, to restrict
2531	the virtual CPU capabilities that &product-name; presents to
2532	the guest operating system. This must be run on both the
2533	source and the target machines involved in the teleporting
2534	and will then modify what the guest sees when it executes
2535	the <computeroutput>CPUID</computeroutput> machine
2536	instruction. This might help with misbehaving applications
2537	that wrongly assume that certain CPU capabilities are
2538	present. The meaning of the parameters is hardware
2539	dependent, refer to the AMD or Intel processor
2540	documentation.
2541	</para>
2542	</listitem>
2543
2544	</itemizedlist>
2545
2546	</sect2>
2547
2548	<sect2 id="vboxmanage-modifyvm-debugging">
2549
2550	<title>Debugging Settings</title>
2551
2552	<para>
2553	The following settings are only relevant for low-level VM
2554	debugging. Regular users will never need these settings.
2555	</para>
2556
2557	<itemizedlist>
2558
2559	<listitem>
2560	<para>
2561	<computeroutput>--tracing-enabled on\|off</computeroutput>:
2562	Enables the tracebuffer. This consumes some memory for the
2563	tracebuffer and adds extra overhead.
2564	</para>
2565	</listitem>
2566
2567	<listitem>
2568	<para>
2569	<computeroutput>--tracing-config
2570	<config-string></computeroutput>: Enables tracing
2571	configuration. In particular, this defines which group of
2572	tracepoints are enabled.
2573	</para>
2574	</listitem>
2575
2576	<listitem>
2577	<para>
2578	<computeroutput>--tracing-allow-vm-access
2579	on\|off</computeroutput>: Enables and disables VM access to
2580	the tracebuffer. By default, this setting is disabled.
2581	</para>
2582	</listitem>
2583
2584	</itemizedlist>
2585
2586	</sect2>
2587
2588	<sect2 id="vboxmanage-usbcardreader">
2589
2590	<title>USB Card Reader Settings</title>
2591
2592	<para>
2593	The following setting defines access to a USB Card Reader by the
2594	guest environment. USB card readers are typically used for
2595	accessing data on memory cards such as CompactFlash (CF), Secure
2596	Digital (SD), or MultiMediaCard (MMC).
2597	</para>
2598
2599	<itemizedlist>
2600
2601	<listitem>
2602	<para>
2603	<computeroutput>--usbcardreader on\|off</computeroutput>:
2604	Enables and disables the USB card reader interface.
2605	</para>
2606	</listitem>
2607
2608	</itemizedlist>
2609
2610	</sect2>
2611
2612	<sect2 id="vboxmanage-autostart">
2613
2614	<title>Autostarting VMs During Host System Boot</title>
2615
2616	<para>
2617	These settings configure the VM autostart feature, which
2618	automatically starts the VM at host system boot-up. Note that
2619	there are prerequisites that need to be addressed before using
2620	this feature. See <xref linkend="autostart" />.
2621	</para>
2622
2623	<itemizedlist>
2624
2625	<listitem>
2626	<para>
2627	<computeroutput>--autostart-enabled on\|off</computeroutput>:
2628	Enables and disables VM autostart at host system boot-up,
2629	using the specified user name.
2630	</para>
2631	</listitem>
2632
2633	<listitem>
2634	<para>
2635	<computeroutput>--autostart-delay
2636	<seconds></computeroutput>: Specifies a delay, in
2637	seconds, following host system boot-up, before the VM
2638	autostarts.
2639	</para>
2640	</listitem>
2641
2642	</itemizedlist>
2643
2644	</sect2>
2645
2646	</sect1>
2647
2648	<sect1 id="vboxmanage-movevm">
2649
2650	<title>VBoxManage movevm</title>
2651
2652	<para>
2653	This command moves a virtual machine to a new location on the
2654	host.
2655	</para>
2656
2657	<para>
2658	Associated files of the virtual machine, such as settings files
2659	and disk image files, are moved to the new location. The
2660	&product-name; configuration is updated automatically.
2661	</para>
2662
2663	<para>
2664	The <command>movevm</command> subcommand requires the name of the
2665	virtual machine which should be moved.
2666	</para>
2667
2668	<para>
2669	Also required is the type of move operation, specified by
2670	<computeroutput>--type basic</computeroutput>. Other types of move
2671	operation may be supported in future releases.
2672	</para>
2673
2674	<para>
2675	The <computeroutput>--folder</computeroutput> setting configures
2676	the new location on the host file system. Enter a relative
2677	pathname or a full pathname.
2678	</para>
2679
2680	</sect1>
2681
2682	<sect1 id="vboxmanage-import">
2683
2684	<title>VBoxManage import</title>
2685
2686	<para>
2687	This command imports one or more virtual machines into
2688	&product-name;. You can import from either of the following:
2689	</para>
2690
2691	<itemizedlist>
2692
2693	<listitem>
2694	<para>
2695	A virtual appliance in OVF format.
2696	</para>
2697	</listitem>
2698
2699	<listitem>
2700	<para>
2701	A cloud service, such as &oci;. Only a single cloud instance
2702	can be imported.
2703	</para>
2704	</listitem>
2705
2706	</itemizedlist>
2707
2708	<para>
2709	See <xref linkend="ovf" /> for more details on importing VMs into
2710	&product-name;.
2711	</para>
2712
2713	<sect2 id="vboxmanage-import-ovf">
2714
2715	<title>Import from OVF</title>
2716
2717	<para>
2718	The <command>import</command> subcommand takes at least the path
2719	name of an OVF file as input and expects the disk images, if
2720	needed, to be in the same directory as the OVF file. Many
2721	additional command-line options are supported. These enable you
2722	to control in detail what is being imported and to modify the
2723	import parameters, depending on the content of the OVF file.
2724	</para>
2725
2726	<para>
2727	It is therefore recommended to first run the
2728	<command>import</command> subcommand with the
2729	<computeroutput>--dry-run</computeroutput> or
2730	<computeroutput>-n</computeroutput> option. This will then print
2731	a description of the appliance's contents to the screen how it
2732	would be imported into &product-name;, together with the
2733	optional command-line options to influence the import behavior.
2734	</para>
2735
2736	<para>
2737	Use of the <computeroutput>--options
2738	keepallmacs\|keepnatmacs\|keepdisknames</computeroutput> option
2739	enables additional fine tuning of the import operation. The
2740	first two options enable you to specify how the MAC addresses of
2741	every virtual network card should be handled. They can either be
2742	reinitialized, which is the default setting, left unchanged
2743	(<computeroutput>keepallmacs</computeroutput>) or left unchanged
2744	when the network type is NAT
2745	(<computeroutput>keepnatmacs</computeroutput>). If you add
2746	<computeroutput>keepdisknames</computeroutput> all new disk
2747	images are assigned the same names as the originals, otherwise
2748	they are renamed.
2749	</para>
2750
2751	<para>
2752	As an example, the following is a screen output for a sample
2753	appliance containing a Windows XP guest:
2754	</para>
2755
2756	<screen>VBoxManage import WindowsXp.ovf --dry-run
2757	Interpreting WindowsXp.ovf...
2758	OK.
2759	Virtual system 0:
2760	0: Suggested OS type: "WindowsXP"
2761	(change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
2762	1: Suggested VM name "Windows XP Professional_1"
2763	(change with "--vsys 0 --vmname <name>")
2764	2: Suggested VM group "/"
2765	(change with "--vsys 0 --group <group>")
2766	3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox"
2767	(change with "--vsys 0 --settingsfile <filename>")
2768	4: Suggested VM base folder "/home/klaus/VirtualBox VMs"
2769	(change with "--vsys 0 --basefolder <path>")
2770	5: End-user license agreement
2771	(display with "--vsys 0 --eula show";
2772	accept with "--vsys 0 --eula accept")
2773	6: Number of CPUs: 1
2774	(change with "--vsys 0 --cpus <n>")
2775	7: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
2776	8: Sound card (appliance expects "ensoniq1371", can change on import)
2777	(disable with "--vsys 0 --unit 5 --ignore")
2778	9: USB controller
2779	(disable with "--vsys 0 --unit 6 --ignore")
2780	10: Network adapter: orig bridged, config 2, extra type=bridged
2781	11: Floppy
2782	(disable with "--vsys 0 --unit 8 --ignore")
2783	12: SCSI controller, type BusLogic
2784	(change with "--vsys 0 --unit 9 --scsitype {BusLogic\|LsiLogic}";
2785	disable with "--vsys 0 --unit 9 --ignore")
2786	13: IDE controller, type PIIX4
2787	(disable with "--vsys 0 --unit 10 --ignore")
2788	14: Hard disk image: source image=WindowsXp.vmdk,
2789	target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
2790	(change controller with "--vsys 0 --unit 11 --controller <id>";
2791	disable with "--vsys 0 --unit 11 --ignore")</screen>
2792
2793	<para>
2794	The individual configuration items are numbered, and depending
2795	on their type support different command-line options. The import
2796	subcommand can be directed to ignore many such items with a
2797	<computeroutput>--vsys X --unit Y --ignore</computeroutput>
2798	option, where X is the number of the virtual system and Y the
2799	item number, as printed on the screen. X is zero, unless there
2800	are several virtual system descriptions in the appliance.
2801	</para>
2802
2803	<para>
2804	In the above example, Item #1 specifies the name of the target
2805	machine in &product-name;. Items #12 and #13 specify hard disk
2806	controllers, respectively. Item #14 describes a hard disk image.
2807	In this case, the additional
2808	<computeroutput>--controller</computeroutput> option indicates
2809	which item the disk image should be connected to, with the
2810	default coming from the OVF file.
2811	</para>
2812
2813	<para>
2814	You can combine several items for the same virtual system using
2815	the <computeroutput>--vsys</computeroutput> option. For example,
2816	to import a machine as described in the OVF, but without the
2817	sound card and without the USB controller, and with the disk
2818	image connected to the IDE controller instead of the SCSI
2819	controller, use the following command:
2820	</para>
2821
2822	<screen>VBoxManage import WindowsXp.ovf
2823	--vsys 0 --unit 8 --ignore --unit 9 --ignore --unit 14 --controller 13</screen>
2824
2825	</sect2>
2826
2827	<sect2 id="vboxmanage-import-cloud">
2828
2829	<title>Import from &oci;</title>
2830
2831	<para>
2832	As the result of this operation, a file with the suffix
2833	<filename>.oci</filename> is downloaded to the local host. This
2834	file is a TAR archive which contains a bootable instance image
2835	in QCOW2 format and a JSON file with some metadata related to
2836	the imported instance.
2837	</para>
2838
2839	<para>
2840	The downloaded file is deleted after a successful import. If
2841	import fails, the downloaded file may not be deleted and the
2842	VBoxSVC log file may indicate the location where the file was
2843	stored.
2844	</para>
2845
2846	<para>
2847	During import the bootable image is extracted from the archive
2848	and converted into VMDK format. The JSON file is also extracted
2849	and stored in the VM machine folder.
2850	</para>
2851
2852	<para>
2853	The command syntax for importing an &oci; instance begins with
2854	<command>VBoxManage import OCI:// --cloud</command>.
2855	</para>
2856
2857	<para>
2858	You can list the available &oci; VM instances and their IDs by
2859	using the following command:
2860	</para>
2861
2862	<screen>VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen>
2863
2864	<para>
2865	To import a VM from a cloud service such as &oci;, use the
2866	<option>--cloud</option> option to specify the import from the
2867	Cloud. Some of the following options are settings for the VM,
2868	for others you must enter an Oracle Cloud Identifier (OCID) for
2869	a resource. Use the Oracle Cloud Infrastructure Console to view
2870	OCIDs.
2871	</para>
2872
2873	<para>
2874	The following parameters can be specified:
2875	</para>
2876
2877	<itemizedlist>
2878
2879	<listitem>
2880	<para>
2881	<option>--vmname</option>: Specifies a new name for the
2882	imported VM. This name is used as the VM name by
2883	&product-name;.
2884	</para>
2885	</listitem>
2886
2887	<listitem>
2888	<para>
2889	<option>--cloudinstanceid</option>: The ID of an existing
2890	instance in the Cloud.
2891	</para>
2892	</listitem>
2893
2894	<listitem>
2895	<para>
2896	<option>--cloudprofile</option>: Specifies the cloud profile
2897	that is used to connect to the cloud service provider. The
2898	cloud profile contains your &oci; account details, such as
2899	your user OCID and the fingerprint for your public key. To
2900	use a cloud profile, you must have the required permissions
2901	on &oci;.
2902	</para>
2903	</listitem>
2904
2905	<listitem>
2906	<para>
2907	<option>--cloudbucket</option>: Specifies the bucket name in
2908	which to store the object created from an instance bootable
2909	volume. In &oci;, a bucket is a logical container for
2910	storing objects.
2911	</para>
2912	</listitem>
2913
2914	</itemizedlist>
2915
2916	<para>
2917	The following import options have the same meaning as for OVF
2918	import:
2919	</para>
2920
2921	<itemizedlist>
2922
2923	<listitem>
2924	<para>
2925	<option>--ostype</option>: An OS type supported by
2926	&product-name;. Use the <command>VBoxManage list
2927	ostypes</command> command to see the whole list of supported
2928	OSes. If the type was not set, the
2929	<literal>Unknown</literal> type is used.
2930	</para>
2931	</listitem>
2932
2933	<listitem>
2934	<para>
2935	<option>--basefolder</option>: The folder where the new VM
2936	is stored.
2937	</para>
2938	</listitem>
2939
2940	<listitem>
2941	<para>
2942	<option>--description</option>: A string describing the VM.
2943	</para>
2944	</listitem>
2945
2946	<listitem>
2947	<para>
2948	<option>--memory</option>: The amount of RAM memory assigned
2949	for the VM, in MB. If this option is not set either the
2950	default memory size for the OS type is used, or the value is
2951	taken from the &oci; instance.
2952	</para>
2953	</listitem>
2954
2955	<listitem>
2956	<para>
2957	<option>--cpus</option>: the number of virtual CPUs assigned
2958	for the VM. If this option is not set, either the default
2959	virtual CPUs setting for the OS type is used, or the value
2960	is taken from the &oci; instance.
2961	</para>
2962	</listitem>
2963
2964	</itemizedlist>
2965
2966	<para>
2967	The import options <option>--disk</option>,
2968	<option>--controller</option>, <option>--scsitype</option>,
2969	<option>--unit</option>, <option>--settingsfile</option> are not
2970	valid for cloud import.
2971	</para>
2972
2973	<para>
2974	The following example shows a typical command line for importing
2975	an instance from &oci;:
2976	</para>
2977
2978	<screen># VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000
2979	--cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user"
2980	--cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen>
2981
2982	</sect2>
2983
2984	</sect1>
2985
2986	<sect1 id="vboxmanage-export">
2987
2988	<title>VBoxManage export</title>
2989
2990	<para>
2991	This command exports one or more virtual machines from
2992	&product-name;. You can export to either of the following:
2993	</para>
2994
2995	<itemizedlist>
2996
2997	<listitem>
2998	<para>
2999	A virtual appliance in OVF format, including copying their
3000	virtual disk images to compressed VMDK.
3001	</para>
3002	</listitem>
3003
3004	<listitem>
3005	<para>
3006	A cloud service, such as &oci;. A single VM can be exported in
3007	VMDK format.
3008	</para>
3009	</listitem>
3010
3011	</itemizedlist>
3012
3013	<para>
3014	See <xref linkend="ovf" /> for more details on exporting VMs from
3015	&product-name;.
3016	</para>
3017
3018	<sect2 id="vboxmanage-export-ovf">
3019
3020	<title>Export to OVF</title>
3021
3022	<para>
3023	List the machine, or the machines, that you would like to export
3024	to the same OVF file and specify the target OVF file after an
3025	additional <computeroutput>--output</computeroutput> or
3026	<computeroutput>-o</computeroutput> option. Note that the
3027	directory of the target OVF file will also receive the exported
3028	disk images in the compressed VMDK format, regardless of the
3029	original format, and should have enough disk space left for
3030	them.
3031	</para>
3032
3033	<para>
3034	Beside a simple export of a given virtual machine, you can
3035	append several product information to the appliance file. Use
3036	<computeroutput>--product</computeroutput>,
3037	<computeroutput>--producturl</computeroutput>,
3038	<computeroutput>--vendor</computeroutput>,
3039	<computeroutput>--vendorurl</computeroutput>,
3040	<computeroutput>--version</computeroutput> and
3041	<computeroutput>--description</computeroutput> to specify this
3042	additional information. For legal reasons you may add a license
3043	text or the content of a license file by using the
3044	<computeroutput>--eula</computeroutput> and
3045	<computeroutput>--eulafile</computeroutput> option respectively.
3046	</para>
3047
3048	<para>
3049	As with OVF import, you use the <computeroutput>--vsys
3050	X</computeroutput> option to apply these options to the correct
3051	virtual machine.
3052	</para>
3053
3054	<para>
3055	For virtualization products which are not fully compatible with
3056	the OVF standard 1.0 you can enable an OVF 0.9 legacy mode with
3057	the <computeroutput>--legacy09</computeroutput> option. Other
3058	options are <computeroutput>--ovf09</computeroutput>,
3059	<computeroutput>--ovf10</computeroutput>,
3060	<computeroutput>--ovf20</computeroutput>.
3061	</para>
3062
3063	<para>
3064	To specify options controlling the exact content of the
3065	appliance file, you can use <option>--options</option> to
3066	request the creation of a manifest file, which enables detection
3067	of corrupted appliances on import, the additional export of DVD
3068	images, and the exclusion of MAC addresses. You can specify a
3069	list of options, such as <option>--options
3070	manifest,nomacs</option>. For details, check the help output of
3071	<command>VBoxManage export</command>.
3072	</para>
3073
3074	</sect2>
3075
3076	<sect2 id="vboxmanage-export-cloud">
3077
3078	<title>Export to &oci;</title>
3079
3080	<para>
3081	By default, an exported disk image is converted into stream VMDK
3082	format. This ensures compatibility with &oci;.
3083	</para>
3084
3085	<para>
3086	List the machine that you want to export to &oci; and specify
3087	the target cloud service provider by using the
3088	<computeroutput>--output</computeroutput> or
3089	<computeroutput>-o</computeroutput> option.
3090	</para>
3091
3092	<para>
3093	To export a VM to a cloud service such as &oci;, use the
3094	<option>--cloud</option> option to specify the VM to export.
3095	This option works in the same way as the <option>--vsys</option>
3096	option for OVF export.
3097	</para>
3098
3099	<para>
3100	Some of the following options are settings for the VM instance.
3101	As a result, you must enter an Oracle Cloud Identifier (OCID)
3102	for a resource. Use the &oci; Console to view OCIDs.
3103	</para>
3104
3105	<itemizedlist>
3106
3107	<listitem>
3108	<para>
3109	<option>--output/-o</option>: Specifies the short name of
3110	the cloud service provider to which you export. For &oci;,
3111	enter <computeroutput>OCI://</computeroutput>.
3112	</para>
3113	</listitem>
3114
3115	<listitem>
3116	<para>
3117	<option>--cloud</option>
3118	<replaceable>number-of-virtual-system</replaceable>:
3119	Specifies a number that identifies the VM that you are
3120	exporting. Numbering starts at
3121	<computeroutput>0</computeroutput> for the first VM.
3122	</para>
3123	</listitem>
3124
3125	<listitem>
3126	<para>
3127	<option>--vmname</option> <replaceable>name</replaceable>:
3128	Specifies the name of the exported VM. This name is used as
3129	the VM instance name in &oci;.
3130	</para>
3131	</listitem>
3132
3133	<listitem>
3134	<para>
3135	<option>--cloudprofile</option>
3136	<replaceable>cloud-profile-name</replaceable>: Specifies the
3137	cloud profile that is used to connect to the cloud service
3138	provider. The cloud profile contains your &oci; account
3139	details, such as your user OCID and the fingerprint for your
3140	public key. See <xref linkend="cloud-export-oci"/>.
3141	</para>
3142
3143	<para>
3144	To use a cloud profile, you must have the required
3145	permissions on &oci;.
3146	</para>
3147	</listitem>
3148
3149	<listitem>
3150	<para>
3151	<option>--cloudshape</option>
3152	<replaceable>shape</replaceable>: Specifies the shape used
3153	for the VM instance. The shape defines the number of CPUs
3154	and the amount of memory allocated to the VM instance. The
3155	shape must be compatible with the exported image.
3156	</para>
3157	</listitem>
3158
3159	<listitem>
3160	<para>
3161	<option>--clouddomain</option>
3162	<replaceable>domain</replaceable>: Specifies the
3163	availability domain to use for the VM instance. Enter the
3164	full name of the availability domain.
3165	</para>
3166	</listitem>
3167
3168	<listitem>
3169	<para>
3170	<option>--clouddisksize</option>
3171	<replaceable>disk-size-in-GB</replaceable>: Specifies the
3172	disk size used for the exported disk image in gigabytes. The
3173	minimum value is 50 GB and the maximum value is 300 GB.
3174	</para>
3175	</listitem>
3176
3177	<listitem>
3178	<para>
3179	<option>--cloudbucket</option>
3180	<replaceable>bucket-name</replaceable>: Specifies the bucket
3181	in which to store the uploaded files. In &oci;, a bucket is
3182	a logical container for storing objects.
3183	</para>
3184	</listitem>
3185
3186	<listitem>
3187	<para>
3188	<option>--cloudocivcn</option>
3189	<replaceable>OCI-vcn-ID</replaceable>: Specifies the virtual
3190	cloud network (VCN) to use for the VM instance. Enter the
3191	OCID for the VCN.
3192	</para>
3193	</listitem>
3194
3195	<listitem>
3196	<para>
3197	<option>--cloudocisubnet</option>
3198	<replaceable>OCI-subnet-ID</replaceable>: Specifies the
3199	subnet of the VCN to use for the VM instance. Enter the OCID
3200	for the subnet.
3201	</para>
3202	</listitem>
3203
3204	<listitem>
3205	<para>
3206	<option>--cloudkeepobject true \| false</option>: Specifies
3207	whether to store the exported disk image in Oracle Object
3208	Storage.
3209	</para>
3210	</listitem>
3211
3212	<listitem>
3213	<para>
3214	<option>--cloudlaunchinstance true \| false</option>:
3215	Specifies whether to start the VM instance after the export
3216	to &oci; completes.
3217	</para>
3218	</listitem>
3219
3220	<listitem>
3221	<para>
3222	<option>--cloudpublicip true \| false</option>: Specifies
3223	whether to enable a public IP address for the VM instance.
3224	</para>
3225	</listitem>
3226
3227	</itemizedlist>
3228
3229	<para>
3230	The following example shows a typical command line for exporting
3231	a VM to &oci;.
3232	</para>
3233
3234	<screen># VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
3235	--cloudprofile "standard user" --cloudbucket myBucket \
3236	--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50 \
3237	--cloudocivcn ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet ocid1.subnet.oc1.iad.aaaa... \
3238	--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true</screen>
3239
3240	</sect2>
3241
3242	</sect1>
3243
3244	<sect1 id="vboxmanage-startvm">
3245
3246	<title>VBoxManage startvm</title>
3247
3248	<para>
3249	This command starts a virtual machine that is currently in the
3250	Powered Off or Saved states.
3251	</para>
3252
3253	<para>
3254	The optional <computeroutput>--type</computeroutput> specifier
3255	determines whether the machine will be started in a window or
3256	whether the output should go through
3257	<command>VBoxHeadless</command>, with VRDE enabled or not. See
3258	<xref linkend="vboxheadless" />. The list of types is subject to
3259	change, and it is not guaranteed that all types are accepted by
3260	any product variant.
3261	</para>
3262
3263	<para>
3264	The global or per-VM default value for the VM frontend type will
3265	be taken if the type is not explicitly specified. If none of these
3266	are set, the GUI variant will be started.
3267	</para>
3268
3269	<para>
3270	The following values are allowed:
3271	</para>
3272
3273	<variablelist>
3274
3275	<varlistentry>
3276	<term>
3277	<computeroutput>gui</computeroutput>
3278	</term>
3279
3280	<listitem>
3281	<para>
3282	Starts a VM showing a GUI window. This is the default.
3283	</para>
3284	</listitem>
3285	</varlistentry>
3286
3287	<varlistentry>
3288	<term>
3289	<computeroutput>headless</computeroutput>
3290	</term>
3291
3292	<listitem>
3293	<para>
3294	Starts a VM without a window for remote display only.
3295	</para>
3296	</listitem>
3297	</varlistentry>
3298
3299	<varlistentry>
3300	<term>
3301	<computeroutput>separate</computeroutput>
3302	</term>
3303
3304	<listitem>
3305	<para>
3306	Starts a VM with a detachable UI. Technically, it is a
3307	headless VM with user interface in a separate process. This
3308	is an experimental feature as it lacks certain
3309	functionality, such as 3D acceleration.
3310	</para>
3311	</listitem>
3312	</varlistentry>
3313
3314	</variablelist>
3315
3316	<note>
3317	<para>
3318	If you experience problems with starting virtual machines with
3319	particular frontends and there is no conclusive error
3320	information, consider starting virtual machines directly by
3321	running the respective front-end, as this can give additional
3322	error information.
3323	</para>
3324	</note>
3325
3326	</sect1>
3327
3328	<sect1 id="vboxmanage-controlvm">
3329
3330	<title>VBoxManage controlvm</title>
3331
3332	<para>
3333	The <command>controlvm</command> subcommand enables you to change
3334	the state of a virtual machine that is currently running. The
3335	following can be specified:
3336	</para>
3337
3338	<itemizedlist>
3339
3340	<listitem>
3341	<para>
3342	<command>VBoxManage controlvm <vm> pause</command>:
3343	Temporarily puts a virtual machine on hold, without
3344	permanently changing its state. The VM window is gray, to
3345	indicate that the VM is currently paused. This is equivalent
3346	to selecting the <emphasis role="bold">Pause</emphasis> item
3347	in the <emphasis role="bold">Machine</emphasis> menu of the
3348	GUI.
3349	</para>
3350	</listitem>
3351
3352	<listitem>
3353	<para>
3354	Use <command>VBoxManage controlvm <vm> resume</command>:
3355	Undoes a previous <command>pause</command> command. This is
3356	equivalent to selecting the
3357	<emphasis role="bold">Resume</emphasis> item in the
3358	<emphasis role="bold">Machine</emphasis> menu of the GUI.
3359	</para>
3360	</listitem>
3361
3362	<listitem>
3363	<para>
3364	<command>VBoxManage controlvm <vm> reset</command>: Has
3365	the same effect on a virtual machine as pressing the Reset
3366	button on a real computer. A cold reboot of the virtual
3367	machine is done, which immediately restarts and reboots the
3368	guest operating system. The state of the VM is not saved
3369	beforehand, and data may be lost. This is equivalent to
3370	selecting the <emphasis role="bold">Reset</emphasis> item in
3371	the <emphasis role="bold">Machine</emphasis> menu of the GUI.
3372	</para>
3373	</listitem>
3374
3375	<listitem>
3376	<para>
3377	<command>VBoxManage controlvm <vm> poweroff</command>:
3378	Has the same effect on a virtual machine as pulling the power
3379	cable on a real computer. The state of the VM is not saved
3380	beforehand, and data may be lost. This is equivalent to
3381	selecting the <emphasis role="bold">Close</emphasis> item in
3382	the <emphasis role="bold">Machine</emphasis> menu of the GUI,
3383	or clicking the VM window's close button, and then selecting
3384	<emphasis role="bold">Power Off the Machine</emphasis> in the
3385	displayed dialog.
3386	</para>
3387
3388	<para>
3389	After this, the VM's state will be Powered Off. From that
3390	state, it can be started again. See
3391	<xref
3392	linkend="vboxmanage-startvm" />.
3393	</para>
3394	</listitem>
3395
3396	<listitem>
3397	<para>
3398	<command>VBoxManage controlvm <vm> savestate</command>:
3399	Saves the current state of the VM to disk and then stops the
3400	VM. This is equivalent to selecting the
3401	<emphasis role="bold">Close</emphasis> item in the
3402	<emphasis role="bold">Machine</emphasis> menu of the GUI or
3403	clicking the VM window's close button, and then selecting
3404	<emphasis role="bold">Save the Machine State</emphasis> in the
3405	displayed dialog.
3406	</para>
3407
3408	<para>
3409	After this, the VM's state will be Saved. From this state, it
3410	can be started again. See
3411	<xref linkend="vboxmanage-startvm" />.
3412	</para>
3413	</listitem>
3414
3415	<listitem>
3416	<para>
3417	<command>VBoxManage controlvm <vm>
3418	acpipowerbutton</command>: Sends an ACPI shutdown signal to
3419	the VM, as if the power button on a real computer had been
3420	pressed. So long as the VM is running a fairly modern guest
3421	operating system providing ACPI support, this should trigger a
3422	proper shutdown mechanism from within the VM.
3423	</para>
3424	</listitem>
3425
3426	<listitem>
3427	<para>
3428	<command>VBoxManage controlvm <vm> keyboardputscancode
3429	<hex> [<hex>...]</command>: Sends commands using
3430	keycodes to the VM. Keycodes are documented in the public
3431	domain. For example:
3432	http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.
3433	</para>
3434	</listitem>
3435
3436	<listitem>
3437	<para>
3438	<command>VBoxManage controlvm "VM name" teleport --hostname
3439	<name> --port <port> [--passwordfile <file>
3440	\| --password <password>]</command>: Makes the machine
3441	the source of a teleporting operation and initiates a teleport
3442	to the given target. See <xref linkend="teleporting" />. If
3443	the optional password is specified, it must match the password
3444	that was given to the <command>modifyvm</command> command for
3445	the target machine. See
3446	<xref linkend="vboxmanage-modifyvm-teleport" />.
3447	</para>
3448	</listitem>
3449
3450	</itemizedlist>
3451
3452	<para>
3453	The following extra options are available with
3454	<command>controlvm</command> that do not directly affect the VM's
3455	running state:
3456	</para>
3457
3458	<itemizedlist>
3459
3460	<listitem>
3461	<para>
3462	<computeroutput>setlinkstate<1-N>
3463	on\|off</computeroutput>: Connects or disconnects virtual
3464	network cables from their network interfaces.
3465	</para>
3466	</listitem>
3467
3468	<listitem>
3469	<para>
3470	<computeroutput>nic<1-N>
3471	null\|nat\|bridged\|intnet\|hostonly\|generic\|natnetwork[<devicename>]</computeroutput>:
3472	Specifies the type of networking that should be made available
3473	on the specified VM virtual network card. They available types
3474	are: not connected to the host
3475	(<computeroutput>null</computeroutput>), use network address
3476	translation (<computeroutput>nat</computeroutput>), bridged
3477	networking (<computeroutput>bridged</computeroutput>),
3478	communicate with other virtual machines using internal
3479	networking (<computeroutput>intnet</computeroutput>),
3480	host-only networking
3481	(<computeroutput>hostonly</computeroutput>), natnetwork
3482	networking (<computeroutput>natnetwork</computeroutput>), or
3483	access to rarely used submodes
3484	(<computeroutput>generic</computeroutput>). These options
3485	correspond to the modes which are described in detail in
3486	<xref linkend="networkingmodes" />.
3487	</para>
3488	</listitem>
3489
3490	<listitem>
3491	<para>
3492	With the <computeroutput>nictrace</computeroutput> options,
3493	you can optionally trace network traffic by dumping it to a
3494	file, for debugging purposes.
3495	</para>
3496
3497	<para>
3498	<computeroutput>nictrace<1-N> on\|off</computeroutput>:
3499	Enables network tracing for a particular virtual network card.
3500	</para>
3501
3502	<para>
3503	Before enabling you should specify a file name to which the
3504	trace should be logged. This can be done with the
3505	<computeroutput>nictracefile<1-N>
3506	<filename></computeroutput> option to
3507	<command>VBoxManage controlvm</command> at runtime or with the
3508	<computeroutput><filename></computeroutput> option to
3509	<command>VBoxManage modifyvm</command> otherwise.
3510	</para>
3511	</listitem>
3512
3513	<listitem>
3514	<para>
3515	<computeroutput>nicpromisc<1-N>
3516	deny\|allow-vms\|allow-all</computeroutput>: Specifies how the
3517	promiscious mode is handled for the specified VM virtual
3518	network card. This setting is only relevant for bridged
3519	networking. The default setting of
3520	<computeroutput>deny</computeroutput> hides any traffic not
3521	intended for this VM.
3522	<computeroutput>allow-vms</computeroutput> hides all host
3523	traffic from this VM but enables the VM to see traffic to and
3524	from other VMs. <computeroutput>allow-all</computeroutput>
3525	removes this restriction completely.
3526	</para>
3527	</listitem>
3528
3529	<listitem>
3530	<para>
3531	<computeroutput>nicproperty<1-N>
3532	<paramname>="paramvalue"</computeroutput>: This option,
3533	in combination with
3534	<computeroutput>nicgenericdrv</computeroutput> enables you to
3535	pass parameters to rarely-used network backends.
3536	</para>
3537
3538	<para>
3539	Those parameters are backend engine-specific, and are
3540	different between UDP Tunnel and the VDE backend drivers. See
3541	<xref linkend="network_udp_tunnel" />.
3542	</para>
3543	</listitem>
3544
3545	<listitem>
3546	<para>
3547	<computeroutput>natpf<1-N>
3548	[<name>],tcp\|udp,[<hostip>],<hostport>,[<guestip>],
3549	<guestport></computeroutput>: Specifies a NAT
3550	port-forwarding rule. See <xref linkend="natforward"/>.
3551	</para>
3552	</listitem>
3553
3554	<listitem>
3555	<para>
3556	<computeroutput>natpf<1-N> delete
3557	<name></computeroutput>: Deletes a NAT port-forwarding
3558	rule. See <xref linkend="natforward"/>.
3559	</para>
3560	</listitem>
3561
3562	<listitem>
3563	<para>
3564	The <computeroutput>guestmemoryballoon<balloon size in
3565	MB></computeroutput>: Changes the size of the guest memory
3566	balloon. This is the memory allocated by the &product-name;
3567	Guest Additions from the guest operating system and returned
3568	to the hypervisor for reuse by other virtual machines. This
3569	must be specified in megabytes. See
3570	<xref linkend="guestadd-balloon" />.
3571	</para>
3572	</listitem>
3573
3574	<listitem>
3575	<para>
3576	<computeroutput>usbattach<uuid\|address> [--capturefile
3577	<filename>]</computeroutput>
3578	</para>
3579
3580	<para>
3581	and <computeroutput>usbdetach <uuid\|address>
3582	[--capturefile <filename>]</computeroutput>: Makes host
3583	USB devices visible or invisible to the virtual machine on the
3584	fly, without the need for creating filters first. The USB
3585	devices can be specified by UUID (unique identifier) or by
3586	address on the host system. Use the
3587	<computeroutput>--capturefile</computeroutput> option to
3588	specify the absolute path of a file for writing activity
3589	logging data.
3590	</para>
3591
3592	<para>
3593	You can use <command>VBoxManage list usbhost</command> to
3594	locate this information.
3595	</para>
3596	</listitem>
3597
3598	<listitem>
3599	<para>
3600	<computeroutput>audioin on</computeroutput>: Selects whether
3601	capturing audio from the host is enabled or disabled.
3602	</para>
3603	</listitem>
3604
3605	<listitem>
3606	<para>
3607	<computeroutput>audioout on</computeroutput>: Selects whether
3608	audio playback from the guest is enabled or disabled.
3609	</para>
3610	</listitem>
3611
3612	<listitem>
3613	<para>
3614	<computeroutput>clipboard mode
3615	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
3616	Selects how the guest or host operating system's clipboard
3617	should be shared with the host or guest. See
3618	<xref linkend="generalsettings" />. This requires that the
3619	Guest Additions be installed in the virtual machine.
3620	</para>
3621	</listitem>
3622
3623	<listitem>
3624	<para>
3625	<computeroutput>clipboard filetransfers
3626	enabled\|disabled</computeroutput>: Specifies if clipboard file
3627	transfers are allowed between host and guest OSes or not.
3628	</para>
3629	</listitem>
3630
3631	<listitem>
3632	<para>
3633	<computeroutput>draganddrop
3634	disabled\|hosttoguest\|guesttohost\|bidirectional</computeroutput>:
3635	Selects the current drag and drop mode being used between the
3636	host and the virtual machine. See
3637	<xref linkend="guestadd-dnd" />. This requires that the Guest
3638	Additions be installed in the virtual machine.
3639	</para>
3640	</listitem>
3641
3642	<listitem>
3643	<para>
3644	<computeroutput>vrde on\|off</computeroutput>: Enables and
3645	disables the VRDE server, if it is installed.
3646	</para>
3647	</listitem>
3648
3649	<listitem>
3650	<para>
3651	<computeroutput>vrdeport
3652	default\|<ports></computeroutput>: Changes the port or a
3653	range of ports that the VRDE server can bind to.
3654	<computeroutput>default</computeroutput> or
3655	<computeroutput>0</computeroutput> means port 3389, the
3656	standard port for RDP. See the description for the
3657	<computeroutput>--vrdeport</computeroutput> option in
3658	<xref
3659	linkend="vboxmanage-modifyvm-vrde" />.
3660	</para>
3661	</listitem>
3662
3663	<listitem>
3664	<para>
3665	<computeroutput>vrdeproperty
3666	"TCP/Ports\|Address=<value>"</computeroutput>: Sets the
3667	port numbers and IP address on the VM to which the VRDE server
3668	can bind.
3669	</para>
3670
3671	<itemizedlist>
3672
3673	<listitem>
3674	<para>
3675	For TCP/Ports, <value> should be a port or a range
3676	of ports to which the VRDE server can bind.
3677	<computeroutput>default</computeroutput> or
3678	<computeroutput>0</computeroutput> means port 3389, the
3679	standard port for RDP. See the description for the
3680	<computeroutput>--vrdeport</computeroutput> option in
3681	<xref
3682	linkend="vboxmanage-modifyvm-vrde" />.
3683	</para>
3684	</listitem>
3685
3686	<listitem>
3687	<para>
3688	For TCP/Address, <value>: The IP address of the host
3689	network interface that the VRDE server will bind to. If
3690	specified, the server will accept connections only on the
3691	specified host network interface. See the description for
3692	the <computeroutput>--vrdeaddress</computeroutput> option
3693	in
3694	<xref
3695	linkend="vboxmanage-modifyvm-vrde" />.
3696	</para>
3697	</listitem>
3698
3699	</itemizedlist>
3700	</listitem>
3701
3702	<listitem>
3703	<para>
3704	<computeroutput>vrdeproperty
3705	"VideoChannel/Enabled\|Quality\|DownscaleProtection=<value>"</computeroutput>:
3706	Sets the VRDP video redirection properties.
3707	</para>
3708
3709	<itemizedlist>
3710
3711	<listitem>
3712	<para>
3713	For VideoChannel/Enabled, <value> can be set to "1"
3714	switching the VRDP video channel on. See
3715	<xref linkend="vrde-videochannel" />.
3716	</para>
3717	</listitem>
3718
3719	<listitem>
3720	<para>
3721	For VideoChannel/Quality, <value> should be set
3722	between 10 and 100% inclusive, representing a JPEG
3723	compression level on the VRDE server video channel. Lower
3724	values mean lower quality but higher compression. See
3725	<xref linkend="vrde-videochannel" />.
3726	</para>
3727	</listitem>
3728
3729	<listitem>
3730	<para>
3731	For VideoChannel/DownscaleProtection, <value> can be
3732	set to "1" to enable the videochannel downscale protection
3733	feature. When enabled, if a video's size equals the shadow
3734	buffer size, then it is regarded as a full screen video,
3735	and is displayed. If its size is between fullscreen and
3736	the downscale threshold it is not displayed, as it could
3737	be an application window, which would be unreadable when
3738	downscaled. When the downscale protection feature is
3739	disabled, an attempt is always made to display videos.
3740	</para>
3741	</listitem>
3742
3743	</itemizedlist>
3744	</listitem>
3745
3746	<listitem>
3747	<para>
3748	<computeroutput>vrdeproperty
3749	"Client/DisableDisplay\|DisableInput\|DisableAudio\|DisableUSB=1"</computeroutput>:
3750	Disables one of the VRDE server features: Display, Input,
3751	Audio, or USB. To reenable a feature, use
3752	"Client/DisableDisplay=" for example. See
3753	<xref linkend="vrde-customization" />.
3754	</para>
3755	</listitem>
3756
3757	<listitem>
3758	<para>
3759	<computeroutput>vrdeproperty
3760	"Client/DisableClipboard\|DisableUpstreamAudio=1"</computeroutput>.
3761	Disables one of the VRDE server features: Clipboard or
3762	UpstreamAudio. To reenable a feature, use
3763	"Client/DisableClipboard=" for example. See
3764	<xref linkend="vrde-customization" />.
3765	</para>
3766	</listitem>
3767
3768	<listitem>
3769	<para>
3770	<computeroutput>vrdeproperty
3771	"Client/DisableRDPDR=1"</computeroutput>: Disables the VRDE
3772	server feature: RDP device redirection for smart cards. To
3773	reenable this feature, use "Client/DisableRDPR=".
3774	</para>
3775	</listitem>
3776
3777	<listitem>
3778	<para>
3779	<computeroutput>vrdeproperty
3780	"H3DRedirect/Enabled=1"</computeroutput>: Enables the VRDE
3781	server feature: 3D redirection. To disable this feature, use
3782	"H3DRedirect/Enabled=".
3783	</para>
3784	</listitem>
3785
3786	<listitem>
3787	<para>
3788	<computeroutput>vrdeproperty
3789	"Security/Method\|ServerCertificate\|ServerPrivateKey\|CACertificate=<value>"</computeroutput>:
3790	Sets the desired security method, path of the server
3791	certificate, path of the server private key, and path of CA
3792	certificate, used for a connection.
3793	</para>
3794
3795	<itemizedlist>
3796
3797	<listitem>
3798	<para>
3799	<computeroutput>vrdeproperty
3800	"Security/Method=<value>"</computeroutput>: Sets the
3801	desired security method, which is used for a connection.
3802	Valid values are as follows:
3803	</para>
3804
3805	<itemizedlist>
3806
3807	<listitem>
3808	<para>
3809	<computeroutput>Negotiate</computeroutput>: Both
3810	Enhanced (TLS) and Standard RDP Security connections
3811	are allowed. The security method is negotiated with
3812	the client. This is the default setting.
3813	</para>
3814	</listitem>
3815
3816	<listitem>
3817	<para>
3818	<computeroutput>RDP</computeroutput>: Only Standard
3819	RDP Security is accepted.
3820	</para>
3821	</listitem>
3822
3823	<listitem>
3824	<para>
3825	<computeroutput>TLS</computeroutput>: Only Enhanced
3826	RDP Security is accepted. The client must support TLS.
3827	</para>
3828	</listitem>
3829
3830	</itemizedlist>
3831
3832	<para>
3833	See <xref linkend="vrde-crypt" />.
3834	</para>
3835	</listitem>
3836
3837	<listitem>
3838	<para>
3839	<computeroutput>vrdeproperty
3840	"Security/ServerCertificate=<value>"</computeroutput>
3841	where <value> is the absolute path of the server
3842	certificate. See <xref linkend="vrde-crypt" />.
3843	</para>
3844	</listitem>
3845
3846	<listitem>
3847	<para>
3848	<computeroutput>vrdeproperty
3849	"Security/ServerPrivateKey=<value>"</computeroutput>
3850	where <value> is the absolute path of the server
3851	private key. See <xref linkend="vrde-crypt" />.
3852	</para>
3853	</listitem>
3854
3855	<listitem>
3856	<para>
3857	<computeroutput>vrdeproperty
3858	"Security/CACertificate=<value>"</computeroutput>
3859	where <value> is the absolute path of the CA self
3860	signed certificate. See <xref linkend="vrde-crypt" />.
3861	</para>
3862	</listitem>
3863
3864	</itemizedlist>
3865	</listitem>
3866
3867	<listitem>
3868	<para>
3869	<computeroutput>vrdeproperty
3870	"Audio/RateCorrectionMode\|LogPath=<value>"</computeroutput>:
3871	Sets the audio connection mode, or path of the audio logfile.
3872	</para>
3873
3874	<itemizedlist>
3875
3876	<listitem>
3877	<para>
3878	<computeroutput>vrdeproperty
3879	"Audio/RateCorrectionMode=<value>"</computeroutput>
3880	where <value> is the desired rate correction mode,
3881	allowed values are:
3882	</para>
3883
3884	<itemizedlist>
3885
3886	<listitem>
3887	<para>
3888	<computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>:
3889	No mode specified, use to unset any Audio mode already
3890	set.
3891	</para>
3892	</listitem>
3893
3894	<listitem>
3895	<para>
3896	<computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>:
3897	Rate correction mode.
3898	</para>
3899	</listitem>
3900
3901	<listitem>
3902	<para>
3903	<computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>:
3904	Low pass filter mode.
3905	</para>
3906	</listitem>
3907
3908	<listitem>
3909	<para>
3910	<computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>:
3911	Client sync mode to prevent underflow or overflow of
3912	the client queue.
3913	</para>
3914	</listitem>
3915
3916	</itemizedlist>
3917	</listitem>
3918
3919	<listitem>
3920	<para>
3921	<computeroutput>vrdeproperty
3922	"Audio/LogPath=<value>"</computeroutput> where
3923	<value> is the absolute path of the audio log file.
3924	</para>
3925	</listitem>
3926
3927	</itemizedlist>
3928	</listitem>
3929
3930	<listitem>
3931	<para>
3932	<computeroutput>vrdevideochannelquality
3933	<percent></computeroutput>: Sets the image quality for
3934	video redirection. See <xref linkend="vrde-videochannel" />.
3935	</para>
3936	</listitem>
3937
3938	<listitem>
3939	<para>
3940	<computeroutput>setvideomodehint</computeroutput>: Requests
3941	that the guest system change to a particular video mode. This
3942	requires that the Guest Additions be installed, and will not
3943	work for all guest systems.
3944	</para>
3945	</listitem>
3946
3947	<listitem>
3948	<para>
3949	<computeroutput>screenshotpng</computeroutput>: Takes a
3950	screenshot of the guest display and saves it in PNG format.
3951	</para>
3952	</listitem>
3953
3954	<listitem>
3955	<para>
3956	<computeroutput>recording on\|off</computeroutput> enables or
3957	disables the recording of a VM session into a WebM/VP8 file.
3958	When this option value is <computeroutput>on</computeroutput>,
3959	recording begins when the VM session starts.
3960	</para>
3961	</listitem>
3962
3963	<listitem>
3964	<para>
3965	<computeroutput>recordingscreens
3966	all\|<replaceable>screen-ID</replaceable>
3967	[<replaceable>screen-ID</replaceable> ...]</computeroutput>
3968	enables you to specify which VM screens to record. The
3969	recording for each screen that you specify is saved to its own
3970	file. You cannot modify this setting while recording is
3971	enabled.
3972	</para>
3973	</listitem>
3974
3975	<listitem>
3976	<para>
3977	<computeroutput>recordingfile
3978	<replaceable>filename</replaceable></computeroutput> specifies
3979	the file in which to save the recording. You cannot modify
3980	this setting while recording is enabled.
3981	</para>
3982	</listitem>
3983
3984	<listitem>
3985	<para>
3986	<computeroutput>recordingvideores
3987	<replaceable>width</replaceable>x<replaceable>height</replaceable></computeroutput>
3988	specifies the resolution of the recorded video in pixels. You
3989	cannot modify this setting while recording is enabled.
3990	</para>
3991	</listitem>
3992
3993	<listitem>
3994	<!-- @todo r=andy Clarify rate. -->
3995
3996	<para>
3997	<computeroutput>recordingvideorate
3998	<replaceable>bit-rate</replaceable></computeroutput> specifies
3999	the bit rate of the video in kilobits per second. Increasing
4000	this value improves the appearance of the video at the cost of
4001	an increased file size. You cannot modify this setting while
4002	recording is enabled.
4003	</para>
4004	</listitem>
4005
4006	<listitem>
4007	<para>
4008	<computeroutput>recordingvideofps
4009	<replaceable>fps</replaceable></computeroutput> specifies the
4010	maximum number of video frames per second (FPS) to record.
4011	Frames that have a higher frequency are skipped. Increasing
4012	this value reduces the number of skipped frames and increases
4013	the file size. You cannot modify this setting while recording
4014	is enabled.
4015	</para>
4016	</listitem>
4017
4018	<listitem>
4019	<!-- @todo r=andy Clarify time format. -->
4020
4021	<para>
4022	<computeroutput>recordingmaxtime
4023	<replaceable>seconds</replaceable></computeroutput> specifies
4024	the maximum amount time to record in seconds. The recording
4025	stops after the specified number of seconds elapses. If this
4026	value is zero, the recording continues until you stop the
4027	recording.
4028	</para>
4029	</listitem>
4030
4031	<listitem>
4032	<para>
4033	<computeroutput>recordingmaxsize
4034	<replaceable>MB</replaceable></computeroutput> specifies the
4035	maximum size of the recorded video file in megabytes. The
4036	recording stops when the file reaches the specified size. If
4037	this value is zero, the recording continues until you stop the
4038	recording. You cannot modify this setting while recording is
4039	enabled.
4040	</para>
4041	</listitem>
4042
4043	<listitem>
4044	<para>
4045	<computeroutput>recordingopts
4046	<replaceable>keyword</replaceable>=<replaceable>value</replaceable>[,<replaceable>keyword</replaceable>=<replaceable>value</replaceable>
4047	...]</computeroutput> specifies additional recording options
4048	in a comma-separated keyword-value format. For example,
4049	<computeroutput>foo=bar,a=b</computeroutput>. You cannot
4050	modify this setting while recording is enabled.
4051	</para>
4052
4053	<para>
4054	Only use this option only if you are an advanced user. For
4055	information about keywords, see <emphasis>Oracle VM VirtualBox
4056	Programming Guide and Reference</emphasis>.
4057	</para>
4058	</listitem>
4059
4060	<listitem>
4061	<para>
4062	<computeroutput>setcredentials</computeroutput>: Used for
4063	remote logins on Windows guests. See
4064	<xref linkend="autologon" />.
4065	</para>
4066	</listitem>
4067
4068	<listitem>
4069	<para>
4070	<computeroutput>teleport --host <name> --port
4071	<port></computeroutput>: Configures a VM as a target for
4072	teleporting. <name> specifies the virtual machine name.
4073	<port> specifies the port on the virtual machine which
4074	should listen for teleporting requests from other virtual
4075	machines. It can be any free TCP/IP port number, such as 6000.
4076	See <xref linkend="teleporting" />.
4077	</para>
4078
4079	<itemizedlist>
4080
4081	<listitem>
4082	<para>
4083	<computeroutput>--maxdowntime
4084	<msec></computeroutput>: Specifies the maximum
4085	downtime, in milliseconds, for the teleporting target VM.
4086	Optional.
4087	</para>
4088	</listitem>
4089
4090	<listitem>
4091	<para>
4092	<computeroutput>--password
4093	<password></computeroutput>: The teleporting request
4094	will only succeed if the source machine specifies the same
4095	password as the one given with this command. Optional.
4096	</para>
4097	</listitem>
4098
4099	<listitem>
4100	<para>
4101	<computeroutput>--passwordfile <password
4102	file></computeroutput>: The teleporting request will
4103	only succeed if the source machine specifies the same
4104	password as the one specified in the password file with
4105	the path specified with this command. Use
4106	<computeroutput>stdin</computeroutput> to read the
4107	password from stdin. Optional.
4108	</para>
4109	</listitem>
4110
4111	</itemizedlist>
4112	</listitem>
4113
4114	<listitem>
4115	<para>
4116	<computeroutput>plugcpu\|unplugcpu <id></computeroutput>:
4117	If CPU hot-plugging is enabled, this setting adds and removes
4118	a virtual CPU to the virtual machine.
4119	<computeroutput><id></computeroutput> specifies the
4120	index of the virtual CPU to be added or removed and must be a
4121	number from 0 to the maximum number of CPUs configured. CPU 0
4122	can never be removed.
4123	</para>
4124	</listitem>
4125
4126	<listitem>
4127	<para>
4128	The <computeroutput>cpuexecutioncap
4129	<1-100></computeroutput>: Controls how much CPU time a
4130	virtual CPU can use. A value of 50 implies a single virtual
4131	CPU can use up to 50% of a single host CPU.
4132	</para>
4133	</listitem>
4134
4135	<listitem>
4136	<para>
4137	<computeroutput>vm-process-priority
4138	default\|flat\|low\|normal\|high</computeroutput>: Changes the
4139	priority scheme of the VM process. See
4140	<xref linkend="vboxmanage-startvm" />.
4141	</para>
4142	</listitem>
4143
4144	<listitem>
4145	<para>
4146	<computeroutput>webcam attach <path\|alias>
4147	[<keyword=value>[;<keyword=value>...]]</computeroutput>:
4148	Attaches a webcam to a running VM. Specify the absolute path
4149	of the webcam on the host operating system, or use its alias,
4150	obtained by using the command: <command>VBoxManage list
4151	webcams</command>.
4152	</para>
4153
4154	<para>
4155	Note that alias '.0' means the default video input device on
4156	the host operating system, '.1', '.2', etc. mean first,
4157	second, etc. video input device. The device order is
4158	host-specific.
4159	</para>
4160
4161	<para>
4162	The optional settings parameter is a
4163	<computeroutput>;</computeroutput> delimited list of
4164	name-value pairs, enabling configuration of the emulated
4165	webcam device.
4166	</para>
4167
4168	<para>
4169	The following settings are supported:
4170	</para>
4171
4172	<para>
4173	MaxFramerate: Specifies the highest rate in frames per second,
4174	at which video frames are sent to the guest. Higher frame
4175	rates increase CPU load, so this setting can be useful when
4176	there is a need to reduce CPU load. The default setting is
4177	<computeroutput>no maximum limit</computeroutput>, thus
4178	enabling the guest to use all frame rates supported by the
4179	host webcam.
4180	</para>
4181
4182	<para>
4183	MaxPayloadTransferSize: Specifies the maximum number of bytes
4184	the emulated webcam can send to the guest in one buffer. The
4185	default setting is 3060 bytes, which is used by some webcams.
4186	Higher values can slightly reduce CPU load, if the guest is
4187	able to use larger buffers. Note that higher
4188	MaxPayloadTransferSize values may be not supported by some
4189	guest operating systems.
4190	</para>
4191	</listitem>
4192
4193	<listitem>
4194	<para>
4195	<computeroutput>webcam detach
4196	<path\|alias></computeroutput>: Detaches a webcam from a
4197	running VM. Specify the absolute path of the webcam on the
4198	host, or use its alias obtained from the <command>webcam
4199	list</command> command.
4200	</para>
4201
4202	<para>
4203	Please note the following points, relating to specific host
4204	operating systems:
4205	</para>
4206
4207	<itemizedlist>
4208
4209	<listitem>
4210	<para>
4211	Windows hosts: When the webcam device is detached from the
4212	host, the emulated webcam device is automatically detached
4213	from the guest.
4214	</para>
4215	</listitem>
4216
4217	<listitem>
4218	<para>
4219	Mac OS X hosts: OS X version 10.7 or newer is required.
4220	</para>
4221
4222	<para>
4223	When the webcam device is detached from the host, the
4224	emulated webcam device remains attached to the guest and
4225	must be manually detached using the <command>VBoxManage
4226	controlvm webcam detach</command> command.
4227	</para>
4228	</listitem>
4229
4230	<listitem>
4231	<para>
4232	Linux hosts: When the webcam is detached from the host,
4233	the emulated webcam device is automatically detached from
4234	the guest only if the webcam is streaming video. If the
4235	emulated webcam is inactive, it should be manually
4236	detached using the <command>VBoxManage controlvm webcam
4237	detach</command> command.
4238	</para>
4239	</listitem>
4240
4241	</itemizedlist>
4242	</listitem>
4243
4244	<listitem>
4245	<para>
4246	<computeroutput>webcam list</computeroutput>: Lists webcams
4247	attached to the running VM. The output is a list of absolute
4248	paths or aliases that were used for attaching the webcams to
4249	the VM using the <command>webcam attach</command> command.
4250	</para>
4251	</listitem>
4252
4253	<listitem>
4254	<para>
4255	<computeroutput>addencpassword <id> <password
4256	file>\|- [--removeonsuspend
4257	<yes\|no>]</computeroutput>: Supplies an encrypted VM
4258	specified by <id> with the encryption password to enable
4259	a headless start. Either specify the absolute path of a
4260	password file on the host file system: <password file>,
4261	or use <option>-</option> to instruct
4262	<command>VBoxManage</command> to prompt the user for the
4263	encryption password.
4264	</para>
4265
4266	<para>
4267	<computeroutput>--removeonsuspend
4268	<yes\|no></computeroutput>: Specifies whether to remove
4269	the passsword or keep the password in VM memory when the VM is
4270	suspended. If the VM has been suspended and the password has
4271	been removed, the user needs to resupply the password before
4272	the VM can be resumed. This feature is useful in cases where
4273	the user does not want the password to be stored in VM memory,
4274	and the VM is suspended by a host suspend event.
4275	</para>
4276
4277	<note>
4278	<para>
4279	On &product-name; versions 5.0 and later, data stored on
4280	hard disk images can be transparently encrypted for the
4281	guest. &product-name; uses the AES algorithm in XTS mode and
4282	supports 128 or 256 bit data encryption keys (DEK). The DEK
4283	is stored encrypted in the medium properties, and is
4284	decrypted during VM startup by supplying the encryption
4285	password.
4286	</para>
4287	</note>
4288
4289	<para>
4290	The <command>VBoxManage encryptmedium</command> command is
4291	used to create a DEK encrypted medium. See
4292	<xref linkend="diskencryption-encryption" />. When starting an
4293	encrypted VM from the &product-name; GUI, the user will be
4294	prompted for the encryption password.
4295	</para>
4296
4297	<para>
4298	For a headless encrypted VM start, use the following command:
4299	</para>
4300
4301	<screen>
4302	VBoxManage startvm "vmname" --type headless
4303	</screen>
4304
4305	<para>
4306	Then supply the required encryption password as follows:
4307	</para>
4308
4309	<screen>
4310	VBoxManage "vmname" controlvm "vmname" addencpassword ...
4311	</screen>
4312
4313	<para></para>
4314	</listitem>
4315
4316	<listitem>
4317	<para>
4318	<computeroutput>removeencpassword <id></computeroutput>:
4319	Removes encryption password authorization for password
4320	<id> for all encrypted media attached to the VM.
4321	</para>
4322	</listitem>
4323
4324	<listitem>
4325	<para>
4326	<computeroutput>removeallencpasswords</computeroutput>:
4327	Removes encryption password authorization for all passwords
4328	for all encrypted media attached to the VM.
4329	</para>
4330	</listitem>
4331
4332	<listitem>
4333	<para>
4334	<computeroutput>changeuartmode <1-N></computeroutput>:
4335	Changes the connection mode for a given virtual serial port.
4336	</para>
4337	</listitem>
4338
4339	</itemizedlist>
4340
4341	</sect1>
4342
4343	<sect1 id="vboxmanage-discardstate">
4344
4345	<title>VBoxManage discardstate</title>
4346
4347	<para>
4348	This command discards the saved state of a virtual machine which
4349	is not currently running. This will cause the VM's operating
4350	system to restart next time you start it. This is the equivalent
4351	of pulling out the power cable on a physical machine, and should
4352	be avoided if possible.
4353	</para>
4354
4355	</sect1>
4356
4357	<sect1 id="vboxmanage-adoptstate">
4358
4359	<title>VBoxManage adoptstate</title>
4360
4361	<para>
4362	If you have a Saved state file (<filename>.sav</filename>) that is
4363	separate from the VM configuration, you can use this command to
4364	<emphasis>adopt</emphasis> the file. This will change the VM to
4365	saved state and when you start it, &product-name; will attempt to
4366	restore it from the saved state file you indicated. This command
4367	should only be used in special setups.
4368	</para>
4369
4370	</sect1>
4371
4372	<sect1 id="vboxmanage-closemedium">
4373
4374	<title>VBoxManage closemedium</title>
4375
4376	<para>
4377	This command removes a hard disk, DVD, or floppy image from a
4378	&product-name; media registry.
4379	</para>
4380
4381	<screen>VBoxManage closemedium [disk\|dvd\|floppy] <uuid\|filename>
4382	[--delete]</screen>
4383
4384	<para>
4385	Optionally, you can request that the image be deleted. You will
4386	get appropriate diagnostics that the deletion failed, however the
4387	image will become unregistered in any case.
4388	</para>
4389
4390	</sect1>
4391
4392	<sect1 id="vboxmanage-storageattach">
4393
4394	<title>VBoxManage storageattach</title>
4395
4396	<para>
4397	This command attaches, modifies, and removes a storage medium
4398	connected to a storage controller that was previously added with
4399	the <command>storagectl</command> command. The syntax is as
4400	follows:
4401	</para>
4402
4403	<screen>VBoxManage storageattach <uuid\|vmname>
4404	--storagectl <name>
4405	[--port <number>]
4406	[--device <number>]
4407	[--type dvddrive\|hdd\|fdd]
4408	[--medium none\|emptydrive\|additions\|
4409	<uuid>\|<filename>\|host:<drive>\|iscsi]
4410	[--mtype normal\|writethrough\|immutable\|shareable
4411	readonly\|multiattach]
4412	[--comment <text>]
4413	[--setuuid <uuid>]
4414	[--setparentuuid <uuid>]
4415	[--passthrough on\|off]
4416	[--tempeject on\|off]
4417	[--nonrotational on\|off]
4418	[--discard on\|off]
4419	[--hotpluggable on\|off]
4420	[--bandwidthgroup name\|none]
4421	[--forceunmount]
4422	[--server <name>\|<ip>]
4423	[--target <target>]
4424	[--tport <port>]
4425	[--lun <lun>]
4426	[--encodedlun <lun>]
4427	[--username <username>]
4428	[--password <password>]
4429	[--passwordfile <file>]
4430	[--initiator <initiator>]
4431	[--intnet]</screen>
4432
4433	<para>
4434	A number of parameters are commonly required. Some parameters are
4435	required only for iSCSI targets.
4436	</para>
4437
4438	<para>
4439	The common parameters are as follows:
4440	</para>
4441
4442	<variablelist>
4443
4444	<varlistentry>
4445	<term>
4446	<computeroutput>uuid\|vmname</computeroutput>
4447	</term>
4448
4449	<listitem>
4450	<para>
4451	The VM UUID or VM Name. Mandatory.
4452	</para>
4453	</listitem>
4454	</varlistentry>
4455
4456	<varlistentry>
4457	<term>
4458	<computeroutput>--storagectl</computeroutput>
4459	</term>
4460
4461	<listitem>
4462	<para>
4463	Name of the storage controller. Mandatory. The list of the
4464	storage controllers currently attached to a VM can be
4465	obtained with <command>VBoxManage showvminfo</command>. See
4466	<xref linkend="vboxmanage-showvminfo" />.
4467	</para>
4468	</listitem>
4469	</varlistentry>
4470
4471	<varlistentry>
4472	<term>
4473	<computeroutput>--port</computeroutput>
4474	</term>
4475
4476	<listitem>
4477	<para>
4478	The number of the storage controller's port which is to be
4479	modified. Mandatory, unless the storage controller has only
4480	a single port.
4481	</para>
4482	</listitem>
4483	</varlistentry>
4484
4485	<varlistentry>
4486	<term>
4487	<computeroutput>--device</computeroutput>
4488	</term>
4489
4490	<listitem>
4491	<para>
4492	The number of the port's device which is to be modified.
4493	Mandatory, unless the storage controller has only a single
4494	device per port.
4495	</para>
4496	</listitem>
4497	</varlistentry>
4498
4499	<varlistentry>
4500	<term>
4501	<computeroutput>--type</computeroutput>
4502	</term>
4503
4504	<listitem>
4505	<para>
4506	Define the type of the drive to which the medium is being
4507	attached, detached, or modified. This argument can only be
4508	omitted if the type of medium can be determined from either
4509	the medium given with the
4510	<computeroutput>--medium</computeroutput> argument or from a
4511	previous medium attachment.
4512	</para>
4513	</listitem>
4514	</varlistentry>
4515
4516	<varlistentry>
4517	<term>
4518	<computeroutput>--medium</computeroutput>
4519	</term>
4520
4521	<listitem>
4522	<para>
4523	Specifies what is to be attached. The following values are
4524	supported:
4525	</para>
4526
4527	<itemizedlist>
4528
4529	<listitem>
4530	<para>
4531	<computeroutput>none</computeroutput>: Any existing
4532	device should be removed from the given slot.
4533	</para>
4534	</listitem>
4535
4536	<listitem>
4537	<para>
4538	<computeroutput>emptydrive</computeroutput>: For a
4539	virtual DVD or floppy drive only, this makes the device
4540	slot behave like a removeable drive into which no media
4541	has been inserted.
4542	</para>
4543	</listitem>
4544
4545	<listitem>
4546	<para>
4547	<computeroutput>additions</computeroutput>: For a
4548	virtual DVD drive only, this attaches the
4549	<emphasis>VirtualBox Guest Additions</emphasis> image to
4550	the given device slot.
4551	</para>
4552	</listitem>
4553
4554	<listitem>
4555	<para>
4556	If a UUID is specified, it must be the UUID of a storage
4557	medium that is already known to &product-name;. For
4558	example, because it has been attached to another virtual
4559	machine. See <xref linkend="vboxmanage-list" /> for
4560	details of how to list known media. This medium is then
4561	attached to the given device slot.
4562	</para>
4563	</listitem>
4564
4565	<listitem>
4566	<para>
4567	If a filename is specified, it must be the full path of
4568	an existing disk image in ISO, RAW, VDI, VMDK, or other
4569	format. The disk image is then attached to the given
4570	device slot.
4571	</para>
4572	</listitem>
4573
4574	<listitem>
4575	<para>
4576	<computeroutput>host:<drive></computeroutput>: For
4577	a virtual DVD or floppy drive only, this connects the
4578	given device slot to the specified DVD or floppy drive
4579	on the host computer.
4580	</para>
4581	</listitem>
4582
4583	<listitem>
4584	<para>
4585	<computeroutput>iscsi</computeroutput>: For virtual hard
4586	disks only, this is used for specifying an iSCSI target.
4587	In this case, additional parameters must be given. These
4588	are described below.
4589	</para>
4590	</listitem>
4591
4592	</itemizedlist>
4593
4594	<para>
4595	Some of the above changes, in particular for removeable
4596	media such as floppies and CDs/DVDs, can be effected while a
4597	VM is running. Others, such as device changes or changes in
4598	hard disk device slots, require the VM to be powered off.
4599	</para>
4600	</listitem>
4601	</varlistentry>
4602
4603	<varlistentry>
4604	<term>
4605	<computeroutput>--mtype</computeroutput>
4606	</term>
4607
4608	<listitem>
4609	<para>
4610	Defines how this medium behaves with respect to snapshots
4611	and write operations. See <xref linkend="hdimagewrites" />.
4612	</para>
4613	</listitem>
4614	</varlistentry>
4615
4616	<varlistentry>
4617	<term>
4618	<computeroutput>--comment</computeroutput>
4619	</term>
4620
4621	<listitem>
4622	<para>
4623	An optional description that you want to have stored with
4624	this medium. For example, for an iSCSI target, "Big storage
4625	server downstairs". This is purely descriptive and not
4626	needed for the medium to function correctly.
4627	</para>
4628	</listitem>
4629	</varlistentry>
4630
4631	<varlistentry>
4632	<term>
4633	<computeroutput>--setuuid, --setparentuuid</computeroutput>
4634	</term>
4635
4636	<listitem>
4637	<para>
4638	Modifies the UUID or parent UUID of a medium before
4639	attaching it to a VM. This is an expert option.
4640	Inappropriate use can make the medium unusable or lead to
4641	broken VM configurations if any other VM is referring to the
4642	same media already. The most frequently used variant is
4643	<computeroutput>--setuuid ""</computeroutput>, which assigns
4644	a new random UUID to an image. This option is useful for
4645	resolving duplicate UUID errors if you duplicated an image
4646	using a file copy utility.
4647	</para>
4648	</listitem>
4649	</varlistentry>
4650
4651	<varlistentry>
4652	<term>
4653	<computeroutput>--passthrough</computeroutput>
4654	</term>
4655
4656	<listitem>
4657	<para>
4658	For a virtual DVD drive only, you can enable DVD writing
4659	support. This feature is currently experimental, see
4660	<xref
4661	linkend="storage-cds" />.
4662	</para>
4663	</listitem>
4664	</varlistentry>
4665
4666	<varlistentry>
4667	<term>
4668	<computeroutput>--tempeject</computeroutput>
4669	</term>
4670
4671	<listitem>
4672	<para>
4673	For a virtual DVD drive only, you can configure the behavior
4674	for guest-triggered medium eject. If this is set to on, the
4675	eject has only a temporary effect. If the VM is powered off
4676	and restarted the originally configured medium will be still
4677	in the drive.
4678	</para>
4679	</listitem>
4680	</varlistentry>
4681
4682	<varlistentry>
4683	<term>
4684	<computeroutput>--nonrotational</computeroutput>
4685	</term>
4686
4687	<listitem>
4688	<para>
4689	Enables you to enable the non-rotational flag for virtual
4690	hard disks. Some guests, such as Windows 7 or later, treat
4691	such disks like SSDs and do not perform disk fragmentation
4692	on such media.
4693	</para>
4694	</listitem>
4695	</varlistentry>
4696
4697	<varlistentry>
4698	<term>
4699	<computeroutput>--discard</computeroutput>
4700	</term>
4701
4702	<listitem>
4703	<para>
4704	Enables the auto-discard feature for a virtual hard disks.
4705	This specifies that a VDI image will be shrunk in response
4706	to the trim command from the guest OS. The following
4707	requirements must be met:
4708	</para>
4709
4710	<itemizedlist>
4711
4712	<listitem>
4713	<para>
4714	The disk format must be VDI.
4715	</para>
4716	</listitem>
4717
4718	<listitem>
4719	<para>
4720	The size of the cleared area must be at least 1 MB.
4721	</para>
4722	</listitem>
4723
4724	<listitem>
4725	<para>
4726	&product-name; will only trim whole 1 MB blocks. The
4727	VDIs themselves are organized into 1 MB blocks, so this
4728	will only work if the space being trimmed is at least a
4729	1 MB contiguous block at a 1 MB boundary. On Windows,
4730	occasional defragmentation with <command>defrag.exe
4731	/D</command>, or on Linux running <command>btrfs
4732	filesystem defrag</command> as a background cron job may
4733	be beneficial.
4734	</para>
4735	</listitem>
4736
4737	</itemizedlist>
4738
4739	<note>
4740	<para>
4741	The Guest OS must be configured to issue the
4742	<command>trim</command> command, and typically this means
4743	that the guest OS is made to see the disk as an SSD. Ext4
4744	supports the -o discard mount flag. Mac OS X probably
4745	requires additional settings. Windows should automatically
4746	detect and support SSDs, at least in versions 7, 8, and
4747	10. The Linux exFAT driver from Samsung supports the
4748	<command>trim</command> command.
4749	</para>
4750	</note>
4751
4752	<para>
4753	It is unclear whether Microsoft's implementation of exFAT
4754	supports this feature, even though that file system was
4755	originally designed for flash.
4756	</para>
4757
4758	<para>
4759	Alternatively, there are other methods to issue trim. For
4760	example, the Linux <command>fstrim</command> command, part
4761	of the util-linux package. Earlier solutions required a user
4762	to zero out unused areas, using zerofree or similar, and to
4763	compact the disk. This is only possible when the VM is
4764	offline.
4765	</para>
4766	</listitem>
4767	</varlistentry>
4768
4769	<varlistentry>
4770	<term>
4771	<computeroutput>--bandwidthgroup</computeroutput>
4772	</term>
4773
4774	<listitem>
4775	<para>
4776	Sets the bandwidth group to use for the given device. See
4777	<xref linkend="storage-bandwidth-limit" />.
4778	</para>
4779	</listitem>
4780	</varlistentry>
4781
4782	<varlistentry>
4783	<term>
4784	<computeroutput>--forceunmount</computeroutput>
4785	</term>
4786
4787	<listitem>
4788	<para>
4789	For a virtual DVD or floppy drive only, this forcibly
4790	unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy
4791	even if the previous one is locked down by the guest for
4792	reading. See <xref linkend="storage-cds" />.
4793	</para>
4794	</listitem>
4795	</varlistentry>
4796
4797	</variablelist>
4798
4799	<para>
4800	When <computeroutput>iscsi</computeroutput> is used with the
4801	<computeroutput>--medium</computeroutput> parameter for iSCSI
4802	support, additional parameters must or can be used. See also
4803	<xref linkend="storage-iscsi" />.
4804	</para>
4805
4806	<variablelist>
4807
4808	<varlistentry>
4809	<term>
4810	<computeroutput>--server</computeroutput>
4811	</term>
4812
4813	<listitem>
4814	<para>
4815	The host name or IP address of the iSCSI target. Required.
4816	</para>
4817	</listitem>
4818	</varlistentry>
4819
4820	<varlistentry>
4821	<term>
4822	<computeroutput>--target</computeroutput>
4823	</term>
4824
4825	<listitem>
4826	<para>
4827	Target name string. This is determined by the iSCSI target
4828	and used to identify the storage resource. Required.
4829	</para>
4830	</listitem>
4831	</varlistentry>
4832
4833	<varlistentry>
4834	<term>
4835	<computeroutput>--tport</computeroutput>
4836	</term>
4837
4838	<listitem>
4839	<para>
4840	TCP/IP port number of the iSCSI service on the target.
4841	Optional.
4842	</para>
4843	</listitem>
4844	</varlistentry>
4845
4846	<varlistentry>
4847	<term>
4848	<computeroutput>--lun</computeroutput>
4849	</term>
4850
4851	<listitem>
4852	<para>
4853	Logical Unit Number of the target resource. Optional. Often,
4854	this value is zero.
4855	</para>
4856	</listitem>
4857	</varlistentry>
4858
4859	<varlistentry>
4860	<term>
4861	<computeroutput>--encodedlun</computeroutput>
4862	</term>
4863
4864	<listitem>
4865	<para>
4866	Hex-encoded Logical Unit Number of the target resource.
4867	Optional. Often, this value is zero.
4868	</para>
4869	</listitem>
4870	</varlistentry>
4871
4872	<varlistentry>
4873	<term>
4874	<computeroutput>--username, --password,
4875	--passwordfile</computeroutput>
4876	</term>
4877
4878	<listitem>
4879	<para>
4880	Username and password, called the initiator secret, for
4881	target authentication, if required. Optional.
4882	</para>
4883
4884	<note>
4885	<para>
4886	Username and password are stored without encryption, in
4887	clear text, in the XML machine configuration file if no
4888	settings password is provided. When a settings password is
4889	specified for the first time, the password is stored in
4890	encrypted form. As an alternative to providing the
4891	password on the command line, a reference to a file
4892	containing the text can be provided using the
4893	<computeroutput>passwordfile</computeroutput> option.
4894	</para>
4895	</note>
4896	</listitem>
4897	</varlistentry>
4898
4899	<varlistentry>
4900	<term>
4901	<computeroutput>--initiator</computeroutput>
4902	</term>
4903
4904	<listitem>
4905	<para>
4906	iSCSI Initiator. Optional.
4907	</para>
4908
4909	<para>
4910	Microsoft iSCSI Initiator is a system, such as a server that
4911	attaches to an IP network and initiates requests and
4912	receives responses from an iSCSI target. The SAN components
4913	in Microsoft iSCSI Initiator are largely analogous to Fibre
4914	Channel SAN components, and they include the following:
4915	</para>
4916
4917	<itemizedlist>
4918
4919	<listitem>
4920	<para>
4921	To transport blocks of iSCSI commands over the IP
4922	network, an iSCSI driver must be installed on the iSCSI
4923	host. An iSCSI driver is included with Microsoft iSCSI
4924	Initiator.
4925	</para>
4926	</listitem>
4927
4928	<listitem>
4929	<para>
4930	A gigabit Ethernet adapter that transmits 1000 megabits
4931	per second (Mbps) is recommended for the connection to
4932	an iSCSI target. Like standard 10/100 adapters, most
4933	gigabit adapters use a preexisting Category 5 or
4934	Category 6E cable. Each port on the adapter is
4935	identified by a unique IP address.
4936	</para>
4937	</listitem>
4938
4939	<listitem>
4940	<para>
4941	An iSCSI target is any device that receives iSCSI
4942	commands. The device can be an end node, such as a
4943	storage device, or it can be an intermediate device,
4944	such as a network bridge between IP and Fibre Channel
4945	devices. Each port on the storage array controller or
4946	network bridge is identified by one or more IP addresses
4947	</para>
4948	</listitem>
4949
4950	</itemizedlist>
4951	</listitem>
4952	</varlistentry>
4953
4954	<varlistentry>
4955	<term>
4956	<computeroutput>--intnet</computeroutput>
4957	</term>
4958
4959	<listitem>
4960	<para>
4961	If specified, connect to the iSCSI target using Internal
4962	Networking. This needs further configuration, see
4963	<xref linkend="iscsi-intnet" />.
4964	</para>
4965	</listitem>
4966	</varlistentry>
4967
4968	</variablelist>
4969
4970	</sect1>
4971
4972	<sect1 id="vboxmanage-storagectl">
4973
4974	<title>VBoxManage storagectl</title>
4975
4976	<para>
4977	This command attaches, modifies, and removes a storage controller.
4978	After this, virtual media can be attached to the controller with
4979	the <command>storageattach</command> command.
4980	</para>
4981
4982	<para>
4983	The syntax for this command is as follows:
4984	</para>
4985
4986	<screen>VBoxManage storagectl <uuid\|vmname>
4987	--name <name>
4988	[--add ide\|sata\|scsi\|floppy\|sas\|usb\|pcie]
4989	[--controller LSILogic\|LSILogicSAS\|BusLogic\|
4990	IntelAhci\|PIIX3\|PIIX4\|ICH6\|I82078\|
4991	USB\|NVMe\|VirtIO]
4992	[--portcount <1-30>]
4993	[--hostiocache on\|off]
4994	[--bootable on\|off]
4995	[--rename <name>]
4996	[--remove]</screen>
4997
4998	<para>
4999	The parameters are as follows:
5000	</para>
5001
5002	<variablelist>
5003
5004	<varlistentry>
5005	<term>
5006	<computeroutput>uuid\|vmname</computeroutput>
5007	</term>
5008
5009	<listitem>
5010	<para>
5011	The VM UUID or VM Name. Mandatory.
5012	</para>
5013	</listitem>
5014	</varlistentry>
5015
5016	<varlistentry>
5017	<term>
5018	<computeroutput>--name</computeroutput>
5019	</term>
5020
5021	<listitem>
5022	<para>
5023	Specifies the name of the storage controller. Mandatory.
5024	</para>
5025	</listitem>
5026	</varlistentry>
5027
5028	<varlistentry>
5029	<term>
5030	<computeroutput>--add</computeroutput>
5031	</term>
5032
5033	<listitem>
5034	<para>
5035	Specifies the type of the system bus to which the storage
5036	controller must be connected.
5037	</para>
5038	</listitem>
5039	</varlistentry>
5040
5041	<varlistentry>
5042	<term>
5043	<computeroutput>--controller</computeroutput>
5044	</term>
5045
5046	<listitem>
5047	<para>
5048	Enables a choice of chipset type being emulated for the
5049	given storage controller.
5050	</para>
5051	</listitem>
5052	</varlistentry>
5053
5054	<varlistentry>
5055	<term>
5056	<computeroutput>--portcount</computeroutput>
5057	</term>
5058
5059	<listitem>
5060	<para>
5061	This specifies the number of ports the storage controller
5062	should support.
5063	</para>
5064	</listitem>
5065	</varlistentry>
5066
5067	<varlistentry>
5068	<term>
5069	<computeroutput>--hostiocache</computeroutput>
5070	</term>
5071
5072	<listitem>
5073	<para>
5074	Configures the use of the host I/O cache for all disk images
5075	attached to this storage controller. See
5076	<xref
5077	linkend="iocaching" />.
5078	</para>
5079	</listitem>
5080	</varlistentry>
5081
5082	<varlistentry>
5083	<term>
5084	<computeroutput>--bootable</computeroutput>
5085	</term>
5086
5087	<listitem>
5088	<para>
5089	Specifies whether this controller is bootable.
5090	</para>
5091	</listitem>
5092	</varlistentry>
5093
5094	<varlistentry>
5095	<term>
5096	<computeroutput>--rename</computeroutput>
5097	</term>
5098
5099	<listitem>
5100	<para>
5101	Specifies a new name for the storage controller.
5102	</para>
5103	</listitem>
5104	</varlistentry>
5105
5106	<varlistentry>
5107	<term>
5108	<computeroutput>--remove</computeroutput>
5109	</term>
5110
5111	<listitem>
5112	<para>
5113	Removes the storage controller from the VM configuration.
5114	</para>
5115	</listitem>
5116	</varlistentry>
5117
5118	</variablelist>
5119
5120	</sect1>
5121
5122	<sect1 id="vboxmanage-bandwidthctl">
5123
5124	<title>VBoxManage bandwidthctl</title>
5125
5126	<para>
5127	This command creates, deletes, modifies, and shows bandwidth
5128	groups of the given virtual machine.
5129	</para>
5130
5131	<screen>VBoxManage bandwidthctl <uuid\|vmname>
5132	add <name> --type disk\|network --limit <MBps>[k\|m\|g\|K\|M\|G] \|
5133	set <name> --limit <MBps>[k\|m\|g\|K\|M\|G] \|
5134	remove <name> \|
5135	list [--machinereadable]</screen>
5136
5137	<para>
5138	The following subcommands are available:
5139	</para>
5140
5141	<itemizedlist>
5142
5143	<listitem>
5144	<para>
5145	<command>add</command>: Creates a new bandwidth group of a
5146	given type.
5147	</para>
5148	</listitem>
5149
5150	<listitem>
5151	<para>
5152	<command>set</command>: Modifies the limit for an existing
5153	bandwidth group.
5154	</para>
5155	</listitem>
5156
5157	<listitem>
5158	<para>
5159	<command>remove</command>: Deletes a bandwidth group.
5160	</para>
5161	</listitem>
5162
5163	<listitem>
5164	<para>
5165	<command>list</command>: Shows all bandwidth groups defined
5166	for the given VM. Use the
5167	<computeroutput>--machinereadable</computeroutput> option to
5168	produce the same output, but in machine readable format. This
5169	is of the form: name="value" on a line by line basis.
5170	</para>
5171	</listitem>
5172
5173	</itemizedlist>
5174
5175	<para>
5176	The parameters are as follows:
5177	</para>
5178
5179	<variablelist>
5180
5181	<varlistentry>
5182	<term>
5183	<computeroutput>uuid\|vmname</computeroutput>
5184	</term>
5185
5186	<listitem>
5187	<para>
5188	The VM UUID or VM Name. Mandatory.
5189	</para>
5190	</listitem>
5191	</varlistentry>
5192
5193	<varlistentry>
5194	<term>
5195	<computeroutput>--name</computeroutput>
5196	</term>
5197
5198	<listitem>
5199	<para>
5200	Name of the bandwidth group. Mandatory.
5201	</para>
5202	</listitem>
5203	</varlistentry>
5204
5205	<varlistentry>
5206	<term>
5207	<computeroutput>--type</computeroutput>
5208	</term>
5209
5210	<listitem>
5211	<para>
5212	Type of the bandwidth group. Mandatory. Two types are
5213	supported: <computeroutput>disk</computeroutput> and
5214	<computeroutput>network</computeroutput>. See
5215	<xref linkend="storage-bandwidth-limit" /> or
5216	<xref linkend="network_bandwidth_limit" /> for the
5217	description of a particular type.
5218	</para>
5219	</listitem>
5220	</varlistentry>
5221
5222	<varlistentry>
5223	<term>
5224	<computeroutput>--limit</computeroutput>
5225	</term>
5226
5227	<listitem>
5228	<para>
5229	Specifies the limit for the given bandwidth group. This can
5230	be changed while the VM is running. The default unit is
5231	megabytes per second. The unit can be changed by specifying
5232	one of the following suffixes:
5233	<computeroutput>k</computeroutput> for kilobits per second,
5234	<computeroutput>m</computeroutput> for megabits per second,
5235	<computeroutput>g</computeroutput> for gigabits per second,
5236	<computeroutput>K</computeroutput> for kilobytes per second,
5237	<computeroutput>M</computeroutput> for megabytes per second,
5238	<computeroutput>G</computeroutput> for gigabytes per second.
5239	</para>
5240	</listitem>
5241	</varlistentry>
5242
5243	</variablelist>
5244
5245	<note>
5246	<para>
5247	The network bandwidth limits apply only to the traffic being
5248	sent by virtual machines. The traffic being received by VMs is
5249	unlimited.
5250	</para>
5251	</note>
5252
5253	<note>
5254	<para>
5255	To remove a bandwidth group it must not be referenced by any
5256	disks or adapters in the running VM.
5257	</para>
5258	</note>
5259
5260	</sect1>
5261
5262	<sect1 id="vboxmanage-showmediuminfo">
5263
5264	<title>VBoxManage showmediuminfo</title>
5265
5266	<para>
5267	This command shows information about a medium, notably its size,
5268	its size on disk, its type, and the virtual machines which use it.
5269	</para>
5270
5271	<note>
5272	<para>
5273	For compatibility with earlier versions of &product-name;, the
5274	<command>showvdiinfo</command> command is also supported and
5275	mapped internally to the <command>showmediuminfo</command>
5276	command.
5277	</para>
5278	</note>
5279
5280	<screen>VBoxManage showmediuminfo [disk\|dvd\|floppy] <uuid\|filename></screen>
5281
5282	<para>
5283	The medium must be specified either by its UUID, if the medium is
5284	registered, or by its filename. Registered images can be listed
5285	using <command>VBoxManage list hdds</command>, <command>VBoxManage
5286	list dvds</command>, or <command>VBoxManage list
5287	floppies</command>, as appropriate. See
5288	<xref linkend="vboxmanage-list" />.
5289	</para>
5290
5291	</sect1>
5292
5293	<sect1 id="vboxmanage-createmedium">
5294
5295	<title>VBoxManage createmedium</title>
5296
5297	<para>
5298	This command creates a new medium. The syntax is as follows:
5299	</para>
5300
5301	<screen>VBoxManage createmedium [disk\|dvd\|floppy] --filename <filename>
5302	[--size <megabytes>\|--sizebyte <bytes>]
5303	[--diffparent <uuid>\|<filename>
5304	[--format VDI\|VMDK\|VHD] (default: VDI)
5305	[--variant Standard,Fixed,Split2G,Stream,ESX,RawDisk]
5306	[[--property <name>=<value>]
5307	--property <name>=<value>]...
5308	[[--property-file <name>=</path/to/file/with/value>]
5309	--property-file <name>=</path/to/file/with/value>]...</screen>
5310
5311	<para>
5312	The parameters are as follows:
5313	</para>
5314
5315	<variablelist>
5316
5317	<varlistentry>
5318	<term>
5319	<computeroutput>--filename <filename></computeroutput>
5320	</term>
5321
5322	<listitem>
5323	<para>
5324	Specifies a file name <filename> as an absolute path
5325	on the host file system. Mandatory.
5326	</para>
5327	</listitem>
5328	</varlistentry>
5329
5330	<varlistentry>
5331	<term>
5332	<computeroutput>--size <megabytes></computeroutput>
5333	</term>
5334
5335	<listitem>
5336	<para>
5337	Specifies the image capacity, in 1 MB units. Optional.
5338	</para>
5339	</listitem>
5340	</varlistentry>
5341
5342	<varlistentry>
5343	<term>
5344	<computeroutput>--diffparent
5345	<uuid>\|<filename></computeroutput>
5346	</term>
5347
5348	<listitem>
5349	<para>
5350	Specifies the differencing image parent, either as a UUID or
5351	by the absolute pathname of the file on the host file
5352	system. Useful for sharing a base box disk image among
5353	several VMs.
5354	</para>
5355	</listitem>
5356	</varlistentry>
5357
5358	<varlistentry>
5359	<term>
5360	<computeroutput>--format VDI\|VMDK\|VHD</computeroutput>
5361	</term>
5362
5363	<listitem>
5364	<para>
5365	Specifies the file format for the output file. Available
5366	options are VDI, VMDK, VHD. The default format is VDI.
5367	Optional.
5368	</para>
5369	</listitem>
5370	</varlistentry>
5371
5372	<varlistentry>
5373	<term>
5374	<computeroutput>--variant</computeroutput>
5375	</term>
5376
5377	<listitem>
5378	<para>
5379	Specifies any required file format variants for the output
5380	file. This is a comma-separated list of variant flags.
5381	Options are Standard,Fixed,Split2G,Stream,ESX. Not all
5382	combinations are supported, and specifying mutually
5383	incompatible flags results in an error message. Optional.
5384	</para>
5385	</listitem>
5386	</varlistentry>
5387
5388	<varlistentry>
5389	<term>
5390	<computeroutput>--property <name>=<value></computeroutput>
5391	</term>
5392
5393	<listitem>
5394	<para>
5395	Specifies any required file format dependent parameters in
5396	<literal>key=value</literal> form. Optional.
5397	</para>
5398	</listitem>
5399	</varlistentry>
5400
5401	<varlistentry>
5402	<term>
5403	<computeroutput>--property-file <name>=</path/to/file/with/value></computeroutput>
5404	</term>
5405
5406	<listitem>
5407	<para>
5408	Specifies any required file format dependent parameters in
5409	<literal>key=file/with/value</literal> form. The value is
5410	taken from the file. Optional.
5411	</para>
5412	</listitem>
5413	</varlistentry>
5414
5415	</variablelist>
5416
5417	<note>
5418	<para>
5419	For compatibility with earlier versions of &product-name;, the
5420	<command>createvdi</command> and <command>createhd</command>
5421	commands are also supported and mapped internally to the
5422	<command>createmedium</command> command.
5423	</para>
5424	</note>
5425
5426	</sect1>
5427
5428	<sect1 id="vboxmanage-modifymedium">
5429
5430	<title>VBoxManage modifymedium</title>
5431
5432	<para>
5433	With the <command>modifymedium</command> command, you can change
5434	the characteristics of a disk image after it has been created.
5435	</para>
5436
5437	<screen>VBoxManage modifymedium [disk\|dvd\|floppy] <uuid\|filename>
5438	[--type normal\|writethrough\|immutable\|shareable\|
5439	readonly\|multiattach]
5440	[--autoreset on\|off]
5441	[--property <name=[value]>]
5442	[--compact]
5443	[--resize <megabytes>\|--resizebyte <bytes>]
5444	[--move <path>]
5445	[--setlocation <path>]</screen>
5446
5447	<note>
5448	<para>
5449	For compatibility with earlier versions of &product-name;, the
5450	<command>modifyvdi</command> and <command>modifyhd</command>
5451	commands are also supported and mapped internally to the
5452	<command>modifymedium</command> command.
5453	</para>
5454	</note>
5455
5456	<para>
5457	The disk image to modify must be specified either by its UUID, if
5458	the medium is registered, or by its filename. Registered images
5459	can be listed using <command>VBoxManage list hdds</command>, see
5460	<xref linkend="vboxmanage-list" />. A filename must be specified
5461	as a valid path, either as an absolute path or as a relative path
5462	starting from the current directory.
5463	</para>
5464
5465	<para>
5466	The following options are available:
5467	</para>
5468
5469	<itemizedlist>
5470
5471	<listitem>
5472	<para>
5473	With the <computeroutput>--type</computeroutput> argument, you
5474	can change the type of an existing image between the normal,
5475	immutable, write-through and other modes. See
5476	<xref
5477	linkend="hdimagewrites" />.
5478	</para>
5479	</listitem>
5480
5481	<listitem>
5482	<para>
5483	For immutable hard disks only, the <computeroutput>--autoreset
5484	on\|off</computeroutput> option determines whether the disk is
5485	automatically reset on every VM startup. See
5486	<xref linkend="hdimagewrites" />. By default, autoreset is on.
5487	</para>
5488	</listitem>
5489
5490	<listitem>
5491	<para>
5492	The <computeroutput>--compact</computeroutput> option can be
5493	used to compact disk images. Compacting removes blocks that
5494	only contains zeroes. Using this option will shrink a
5495	dynamically allocated image. It will reduce the
5496	<emphasis>physical</emphasis> size of the image without
5497	affecting the logical size of the virtual disk. Compaction
5498	works both for base images and for differencing images created
5499	as part of a snapshot.
5500	</para>
5501
5502	<para>
5503	For this operation to be effective, it is required that free
5504	space in the guest system first be zeroed out using a suitable
5505	software tool. For Windows guests, you can use the
5506	<command>sdelete</command> tool provided by Microsoft. Run
5507	<command>sdelete -z</command> in the guest to zero the free
5508	disk space, before compressing the virtual disk image. For
5509	Linux, use the <command>zerofree</command> utility which
5510	supports ext2/ext3 filesystems. For Mac OS X guests, use the
5511	<computeroutput>diskutil secureErase freespace 0
5512	/</computeroutput> command from an elevated Terminal.
5513	</para>
5514
5515	<para>
5516	Please note that compacting is currently only available for
5517	VDI images. A similar effect can be achieved by zeroing out
5518	free blocks and then cloning the disk to any other dynamically
5519	allocated format. You can use this workaround until compacting
5520	is also supported for disk formats other than VDI.
5521	</para>
5522	</listitem>
5523
5524	<listitem>
5525	<para>
5526	The <computeroutput>--resize x</computeroutput> option, where
5527	x is the desired new total space in megabytes enables you to
5528	change the capacity of an existing image. This adjusts the
5529	<emphasis>logical</emphasis> size of a virtual disk without
5530	affecting the physical size much.
5531	</para>
5532
5533	<para>
5534	This option currently works only for VDI and VHD formats, and
5535	only for the dynamically allocated variants. It can only be
5536	used to expand, but not shrink, the capacity. For example, if
5537	you originally created a 10 GB disk which is now full, you can
5538	use the <computeroutput>--resize 15360</computeroutput>
5539	command to change the capacity to 15 GB (15,360 MB) without
5540	having to create a new image and copy all data from within a
5541	virtual machine. Note however that this only changes the drive
5542	capacity. You will typically next need to use a partition
5543	management tool inside the guest to adjust the main partition
5544	to fill the drive.
5545	</para>
5546
5547	<para>
5548	The <computeroutput>--resizebyte x</computeroutput> option
5549	does almost the same thing, except that x is expressed in
5550	bytes instead of megabytes.
5551	</para>
5552	</listitem>
5553
5554	<listitem>
5555	<para>
5556	The <computeroutput>--move <path></computeroutput>
5557	option can be used to relocate a medium to a different
5558	location <path> on the host file system. The path can be
5559	either relative to the current directory or absolute.
5560	</para>
5561	</listitem>
5562
5563	<listitem>
5564	<para>
5565	The <computeroutput>--setlocation
5566	<path></computeroutput> option can be used to set the
5567	new location <path> of the medium on the host file
5568	system if the medium has been moved for any reasons. The path
5569	can be either relative to the current directory or absolute.
5570	</para>
5571
5572	<note>
5573	<para>
5574	The new location is used as is, without any sanity checks.
5575	The user is responsible for setting the correct path.
5576	</para>
5577	</note>
5578	</listitem>
5579
5580	</itemizedlist>
5581
5582	</sect1>
5583
5584	<sect1 id="vboxmanage-clonemedium">
5585
5586	<title>VBoxManage clonemedium</title>
5587
5588	<para>
5589	This command duplicates a virtual disk, DVD, or floppy medium to a
5590	new medium, usually an image file, with a new unique identifier
5591	(UUID). The new image can be transferred to another host system or
5592	reimported into &product-name; using the Virtual Media Manager.
5593	See <xref linkend="vdis" /> and <xref linkend="cloningvdis" />.
5594	The syntax is as follows:
5595	</para>
5596
5597	<screen>VBoxManage clonemedium [disk\|dvd\|floppy] <uuid\|inputfile> <uuid\|outputfile>
5598
5599	[--format VDI\|VMDK\|VHD\|RAW\|<other>]
5600	[--variant Standard,Fixed,Split2G,Stream,ESX]
5601	[--existing]</screen>
5602
5603	<para>
5604	The medium to clone as well as the target image must be described
5605	either by its UUIDs, if the mediums are registered, or by its
5606	filename. Registered images can be listed by <command>VBoxManage
5607	list hdds</command>. See <xref linkend="vboxmanage-list" />. A
5608	filename must be specified as valid path, either as an absolute
5609	path or as a relative path starting from the current directory.
5610	</para>
5611
5612	<para>
5613	The following options are available:
5614	</para>
5615
5616	<variablelist>
5617
5618	<varlistentry>
5619	<term>
5620	<computeroutput>--format</computeroutput>
5621	</term>
5622
5623	<listitem>
5624	<para>
5625	Set a file format for the output file different from the
5626	file format of the input file.
5627	</para>
5628	</listitem>
5629	</varlistentry>
5630
5631	<varlistentry>
5632	<term>
5633	<computeroutput>--variant</computeroutput>
5634	</term>
5635
5636	<listitem>
5637	<para>
5638	Set a file format variant for the output file. This is a
5639	comma-separated list of variant flags. Not all combinations
5640	are supported, and specifying inconsistent flags will result
5641	in an error message.
5642	</para>
5643	</listitem>
5644	</varlistentry>
5645
5646	<varlistentry>
5647	<term>
5648	<computeroutput>--existing</computeroutput>
5649	</term>
5650
5651	<listitem>
5652	<para>
5653	Perform the clone operation to an already existing
5654	destination medium. Only the portion of the source medium
5655	which fits into the destination medium is copied. This means
5656	if the destination medium is smaller than the source only a
5657	part of it is copied, and if the destination medium is
5658	larger than the source the remaining part of the destination
5659	medium is unchanged.
5660	</para>
5661	</listitem>
5662	</varlistentry>
5663
5664	</variablelist>
5665
5666	<note>
5667	<para>
5668	For compatibility with earlier versions of &product-name;, the
5669	<command>clonevdi</command> and <command>clonehd</command>
5670	commands are still supported and mapped internally to the
5671	<command>clonemedium</command> command.
5672	</para>
5673	</note>
5674
5675	</sect1>
5676
5677	<sect1 id="vboxmanage-mediumproperty">
5678
5679	<title>VBoxManage mediumproperty</title>
5680
5681	<para>
5682	This command sets, gets, or deletes a medium property. The syntax
5683	is as follows:
5684	</para>
5685
5686	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] set <uuid\|filename>
5687	<property> <value></screen>
5688
5689	<itemizedlist>
5690
5691	<listitem>
5692	<para>
5693	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
5694	to optionally specify the type of medium: disk (hard drive),
5695	dvd, or floppy.
5696	</para>
5697	</listitem>
5698
5699	<listitem>
5700	<para>
5701	Use <computeroutput><uuid\|filename></computeroutput> to
5702	supply either the UUID or absolute path of the medium or
5703	image.
5704	</para>
5705	</listitem>
5706
5707	<listitem>
5708	<para>
5709	Use <computeroutput><property></computeroutput> to
5710	supply the name of the property.
5711	</para>
5712	</listitem>
5713
5714	<listitem>
5715	<para>
5716	Use <computeroutput><value></computeroutput> to supply
5717	the property value.
5718	</para>
5719	</listitem>
5720
5721	</itemizedlist>
5722
5723	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] get <uuid\|filename>
5724	<property></screen>
5725
5726	<itemizedlist>
5727
5728	<listitem>
5729	<para>
5730	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
5731	to optionally specify the type of medium: disk (hard drive),
5732	dvd, or floppy.
5733	</para>
5734	</listitem>
5735
5736	<listitem>
5737	<para>
5738	Use <computeroutput><uuid\|filename></computeroutput> to
5739	supply either the UUID or absolute path of the medium or
5740	image.
5741	</para>
5742	</listitem>
5743
5744	<listitem>
5745	<para>
5746	Use <computeroutput><property></computeroutput> to
5747	supply the name of the property.
5748	</para>
5749	</listitem>
5750
5751	</itemizedlist>
5752
5753	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] delete <uuid\|filename>
5754	<property></screen>
5755
5756	<itemizedlist>
5757
5758	<listitem>
5759	<para>
5760	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
5761	to optionally specify the type of medium: disk (hard drive),
5762	dvd, or floppy.
5763	</para>
5764	</listitem>
5765
5766	<listitem>
5767	<para>
5768	Use <computeroutput><uuid\|filename></computeroutput> to
5769	supply either the UUID or absolute path of the medium or
5770	image.
5771	</para>
5772	</listitem>
5773
5774	<listitem>
5775	<para>
5776	Use <computeroutput><property></computeroutput> to
5777	supply the name of the property.
5778	</para>
5779	</listitem>
5780
5781	</itemizedlist>
5782
5783	</sect1>
5784
5785	<sect1 id="vboxmanage-encryptmedium">
5786
5787	<title>VBoxManage encryptmedium</title>
5788
5789	<para>
5790	This command is used to create a DEK encrypted medium or image.
5791	See <xref linkend="diskencryption-encryption" />.
5792	</para>
5793
5794	<para>
5795	The syntax is as follows:
5796	</para>
5797
5798	<screen>VBoxManage encryptmedium <uuid\|filename>
5799	[--newpassword <file\|->]
5800	[--oldpassword <file\|->]
5801	[--cipher <cipher id>]
5802	[--newpasswordid <password id>]</screen>
5803
5804	<itemizedlist>
5805
5806	<listitem>
5807	<para>
5808	Use <computeroutput><uuid\|filename></computeroutput> to
5809	supply the UUID or absolute path of the medium or image to be
5810	encrypted.
5811	</para>
5812	</listitem>
5813
5814	<listitem>
5815	<para>
5816	Use <computeroutput>--newpassword
5817	<file\|-></computeroutput> to supply a new encryption
5818	password. Either specify the absolute pathname of a password
5819	file on the host operating system, or
5820	<computeroutput>-</computeroutput> to prompt you for the
5821	password on the command line. Always use the
5822	<computeroutput>--newpasswordid</computeroutput> option with
5823	this option.
5824	</para>
5825	</listitem>
5826
5827	<listitem>
5828	<para>
5829	Use <computeroutput>--oldpassword
5830	<file\|-></computeroutput> to supply any old encryption
5831	password. Either specify the absolute pathname of a password
5832	file on the host operating system, or
5833	<computeroutput>-</computeroutput> to prompt you for the old
5834	password on the command line.
5835	</para>
5836
5837	<para>
5838	Use this option to gain access to an encrypted medium or image
5839	to either change its password using
5840	<computeroutput>--newpassword</computeroutput> or change its
5841	encryption using <computeroutput>--cipher</computeroutput>.
5842	</para>
5843	</listitem>
5844
5845	<listitem>
5846	<para>
5847	Use <computeroutput>--cipher <cipher></computeroutput>
5848	to specify the cipher to use for encryption. This can be
5849	either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
5850	<computeroutput>AES-XTS256-PLAIN64</computeroutput>.
5851	</para>
5852
5853	<para>
5854	Use this option to change any existing encryption on the
5855	medium or image, or to set up new encryption on it for the
5856	first time.
5857	</para>
5858	</listitem>
5859
5860	<listitem>
5861	<para>
5862	Use <computeroutput>--newpasswordid <password
5863	id></computeroutput> to supply the new password identifier.
5864	This can be chosen by the user, and is used for correct
5865	identification when supplying multiple passwords during VM
5866	startup.
5867	</para>
5868
5869	<para>
5870	If the user uses the same password when encrypting multiple
5871	images and also the same password identifier, the user needs
5872	to supply the password only once during VM startup.
5873	</para>
5874	</listitem>
5875
5876	</itemizedlist>
5877
5878	</sect1>
5879
5880	<sect1 id="vboxmanage-checkmediumpwd">
5881
5882	<title>VBoxManage checkmediumpwd</title>
5883
5884	<para>
5885	This command is used to check the current encryption password on a
5886	DEK encrypted medium or image. See
5887	<xref linkend="diskencryption-encryption" />.
5888	</para>
5889
5890	<para>
5891	The syntax is as follows:
5892	</para>
5893
5894	<screen>VBoxManage checkmediumpwd <uuid\|filename>
5895	<pwd file\|-></screen>
5896
5897	<itemizedlist>
5898
5899	<listitem>
5900	<para>
5901	Use <computeroutput><uuid\|filename></computeroutput> to
5902	supply the UUID or absolute path of the medium or image to be
5903	checked.
5904	</para>
5905	</listitem>
5906
5907	<listitem>
5908	<para>
5909	Use <computeroutput><pwd file\|-></computeroutput> to
5910	supply the password identifier to be checked. Either specify
5911	the absolute pathname of a password file on the host operating
5912	system, or <computeroutput>-</computeroutput> to prompt you
5913	for the password on the command line.
5914	</para>
5915	</listitem>
5916
5917	</itemizedlist>
5918
5919	</sect1>
5920
5921	<sect1 id="vboxmanage-convertfromraw">
5922
5923	<title>VBoxManage convertfromraw</title>
5924
5925	<para>
5926	This command converts a raw disk image to an &product-name; Disk
5927	Image (VDI) file. The syntax is as follows:
5928	</para>
5929
5930	<screen>VBoxManage convertfromraw <filename> <outputfile>
5931	[--format VDI\|VMDK\|VHD]
5932	[--variant Standard,Fixed,Split2G,Stream,ESX]
5933	[--uuid <uuid>]
5934	VBoxManage convertfromraw stdin <outputfile> <bytes>
5935	[--format VDI\|VMDK\|VHD]
5936	[--variant Standard,Fixed,Split2G,Stream,ESX]
5937	[--uuid <uuid>]</screen>
5938
5939	<para>
5940	The parameters are as follows:
5941	</para>
5942
5943	<variablelist>
5944
5945	<varlistentry>
5946	<term>
5947	<computeroutput>--bytes</computeroutput>
5948	</term>
5949
5950	<listitem>
5951	<para>
5952	The size of the image file, in bytes, provided through
5953	stdin.
5954	</para>
5955	</listitem>
5956	</varlistentry>
5957
5958	<varlistentry>
5959	<term>
5960	<computeroutput>--format</computeroutput>
5961	</term>
5962
5963	<listitem>
5964	<para>
5965	Select the disk image format to create. The default format
5966	is VDI. Other options are VMDK and VHD.
5967	</para>
5968	</listitem>
5969	</varlistentry>
5970
5971	<varlistentry>
5972	<term>
5973	<computeroutput>--variant</computeroutput>
5974	</term>
5975
5976	<listitem>
5977	<para>
5978	Choose a file format variant for the output file. This is a
5979	comma-separated list of variant flags. Not all combinations
5980	are supported, and specifying inconsistent flags will result
5981	in an error message.
5982	</para>
5983	</listitem>
5984	</varlistentry>
5985
5986	<varlistentry>
5987	<term>
5988	<computeroutput>--uuid</computeroutput>
5989	</term>
5990
5991	<listitem>
5992	<para>
5993	Specify the UUID of the output file.
5994	</para>
5995	</listitem>
5996	</varlistentry>
5997
5998	</variablelist>
5999
6000	<para>
6001	The <command>stdin</command> form of the command forces
6002	<command>VBoxManage</command> to read the content of the disk
6003	image from standard input. This useful when using the command in a
6004	pipe.
6005	</para>
6006
6007	<note>
6008	<para>
6009	For compatibility with earlier versions of &product-name;, the
6010	<command>convertdd</command> command is also supported and
6011	mapped internally to the <command>convertfromraw</command>
6012	command.
6013	</para>
6014	</note>
6015
6016	</sect1>
6017
6018	<sect1 id="vboxmanage-extradata">
6019
6020	<title>VBoxManage getextradata/setextradata</title>
6021
6022	<para>
6023	These commands enable you to attach and retrieve string data for a
6024	virtual machine or for an &product-name; configuration, by
6025	specifying <computeroutput>global</computeroutput> instead of a
6026	virtual machine name. You must specify a keyword as a text string
6027	to associate the data with, which you can later use to retrieve
6028	it. For example:
6029	</para>
6030
6031	<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
6032	VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
6033
6034	<para>
6035	This example would associate the string "2006.01.01" with the
6036	keyword installdate for the virtual machine Fedora5, and
6037	"2006.02.02" on the machine SUSE10. You could then retrieve the
6038	information as follows:
6039	</para>
6040
6041	<screen>VBoxManage getextradata Fedora5 installdate</screen>
6042
6043	<para>
6044	This would return the following:
6045	</para>
6046
6047	<screen>VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
6048	(C) 2005-2018 Oracle Corporation
6049	All rights reserved.
6050
6051	Value: 2006.01.01</screen>
6052
6053	<para>
6054	You could retrieve the information for all keywords as follows:
6055	</para>
6056
6057	<screen>VBoxManage getextradata Fedora5 enumerate</screen>
6058
6059	<para>
6060	To remove a keyword, the <command>setextradata</command> command
6061	must be run without specifying data, only the keyword. For
6062	example:
6063	</para>
6064
6065	<screen>VBoxManage setextradata Fedora5 installdate</screen>
6066
6067	</sect1>
6068
6069	<sect1 id="vboxmanage-setproperty">
6070
6071	<title>VBoxManage setproperty</title>
6072
6073	<para>
6074	This command is used to change global settings which affect the
6075	entire &product-name; installation. Some of these correspond to
6076	the settings in the <emphasis role="bold">Global
6077	Settings</emphasis> dialog in the graphical user interface. The
6078	following properties are available:
6079	</para>
6080
6081	<variablelist>
6082
6083	<varlistentry>
6084	<term>
6085	<computeroutput>machinefolder</computeroutput>
6086	</term>
6087
6088	<listitem>
6089	<para>
6090	Specifies the default folder in which virtual machine
6091	definitions are kept. See <xref linkend="vboxconfigdata" />.
6092	</para>
6093	</listitem>
6094	</varlistentry>
6095
6096	<varlistentry>
6097	<term>
6098	<computeroutput>hwvirtexclusive</computeroutput>
6099	</term>
6100
6101	<listitem>
6102	<para>
6103	Specifies whether &product-name; will make exclusive use of
6104	the hardware virtualization extensions (Intel VT-x or AMD-V)
6105	of the host system's processor. See
6106	<xref linkend="hwvirt" />. If you wish to share these
6107	extensions with other hypervisors running at the same time,
6108	you must disable this setting. Doing so has negative
6109	performance implications.
6110	</para>
6111	</listitem>
6112	</varlistentry>
6113
6114	<varlistentry>
6115	<term>
6116	<computeroutput>vrdeauthlibrary</computeroutput>
6117	</term>
6118
6119	<listitem>
6120	<para>
6121	Specifies which library to use when external authentication
6122	has been selected for a particular virtual machine. See
6123	<xref linkend="vbox-auth" />.
6124	</para>
6125	</listitem>
6126	</varlistentry>
6127
6128	<varlistentry>
6129	<term>
6130	<computeroutput>websrvauthlibrary</computeroutput>
6131	</term>
6132
6133	<listitem>
6134	<para>
6135	Specifies which library the web service uses to authenticate
6136	users. For details about the &product-name; web service, see
6137	the &product-name; SDK reference,
6138	<xref
6139	linkend="VirtualBoxAPI" />.
6140	</para>
6141	</listitem>
6142	</varlistentry>
6143
6144	<varlistentry>
6145	<term>
6146	<computeroutput>vrdeextpack</computeroutput>
6147	</term>
6148
6149	<listitem>
6150	<para>
6151	Specifies which library implements the VirtualBox Remote
6152	Desktop Extension.
6153	</para>
6154	</listitem>
6155	</varlistentry>
6156
6157	<varlistentry>
6158	<term>
6159	<computeroutput>loghistorycount</computeroutput>
6160	</term>
6161
6162	<listitem>
6163	<para>
6164	Selects how many rotated VM logs are retained.
6165	</para>
6166	</listitem>
6167	</varlistentry>
6168
6169	<varlistentry>
6170	<term>
6171	<computeroutput>autostartdbpath</computeroutput>
6172	</term>
6173
6174	<listitem>
6175	<para>
6176	Selects the path to the autostart database. See
6177	<xref linkend="autostart" />.
6178	</para>
6179	</listitem>
6180	</varlistentry>
6181
6182	<varlistentry>
6183	<term>
6184	<computeroutput>defaultfrontend</computeroutput>
6185	</term>
6186
6187	<listitem>
6188	<para>
6189	Selects the global default VM frontend setting. See
6190	<xref linkend="vboxmanage-startvm" />.
6191	</para>
6192	</listitem>
6193	</varlistentry>
6194
6195	<varlistentry>
6196	<term>
6197	<computeroutput>logginglevel</computeroutput>
6198	</term>
6199
6200	<listitem>
6201	<para>
6202	Configures the VBoxSVC release logging details. See
6203	<ulink url="http://www.virtualbox.org/wiki/VBoxLogging" />.
6204	</para>
6205	</listitem>
6206	</varlistentry>
6207
6208	<varlistentry>
6209	<term>
6210	<computeroutput>proxymode</computeroutput>
6211	</term>
6212
6213	<listitem>
6214	<para>
6215	Configures the mode for an HTTP proxy server.
6216	</para>
6217	</listitem>
6218	</varlistentry>
6219
6220	<varlistentry>
6221	<term>
6222	<computeroutput>proxyurl</computeroutput>
6223	</term>
6224
6225	<listitem>
6226	<para>
6227	Configures the URL for an HTTP proxy server. Used when a
6228	manual proxy is configured using the
6229	<computeroutput>manual</computeroutput> setting of the
6230	<computeroutput>proxymode</computeroutput> property.
6231	</para>
6232	</listitem>
6233	</varlistentry>
6234
6235	</variablelist>
6236
6237	</sect1>
6238
6239	<sect1 id="vboxmanage-usbfilter">
6240
6241	<title>VBoxManage usbfilter add/modify/remove</title>
6242
6243	<screen>VBoxManage usbfilter add <index,0-N>
6244	--target <uuid\|vmname>global
6245	--name <string>
6246	--action ignore\|hold (global filters only)
6247	[--active yes\|no (yes)]
6248	[--vendorid <XXXX> (null)]
6249	[--productid <XXXX> (null)]
6250	[--revision <IIFF> (null)]
6251	[--manufacturer <string> (null)]
6252	[--product <string> (null)]
6253	[--remote yes\|no (null, VM filters only)]
6254	[--serialnumber <string> (null)]
6255	[--maskedinterfaces <XXXXXXXX>]
6256	</screen>
6257
6258	<screen>VBoxManage usbfilter modify <index,0-N>
6259	--target <uuid\|vmname>global
6260	[--name <string>]
6261	[--action ignore\|hold (global filters only)]
6262	[--active yes\|no]
6263	[--vendorid <XXXX>]
6264	[--productid <XXXX>]
6265	[--revision <IIFF>]
6266	[--manufacturer <string>]
6267	[--product <string>]
6268	[--remote yes\|no (null, VM filters only)]
6269	[--serialnumber <string>]
6270	[--maskedinterfaces <XXXXXXXX>]
6271	</screen>
6272
6273	<screen>VBoxManage usbfilter remove <index,0-N>
6274	--target <uuid\|vmname>global
6275	</screen>
6276
6277	<para>
6278	The <command>usbfilter</command> commands are used for working
6279	with USB filters in virtual machines, or global filters which
6280	affect the whole &product-name; setup. Global filters are applied
6281	before machine-specific filters, and may be used to prevent
6282	devices from being captured by any virtual machine. Global filters
6283	are always applied in a particular order, and only the first
6284	filter which fits a device is applied. For example, if the first
6285	global filter says to hold, or make available, a particular
6286	Kingston memory stick device and the second filter says to ignore
6287	all Kingston devices. That particular Kingston memory stick will
6288	be available to any machine with the appropriate filter, but no
6289	other Kingston device will.
6290	</para>
6291
6292	<para>
6293	When creating a USB filter using <command>usbfilter add</command>,
6294	you must supply three or four mandatory parameters. The index
6295	specifies the position in the list at which the filter should be
6296	placed. If there is already a filter at that position, then it and
6297	the following ones will be shifted back one place. Otherwise, the
6298	new filter will be added onto the end of the list. The
6299	<computeroutput>target</computeroutput> parameter selects the
6300	virtual machine that the filter should be attached to or use
6301	<computeroutput>global</computeroutput> to apply it to all virtual
6302	machines. <computeroutput>name</computeroutput> is a name for the
6303	new filter. For global filters,
6304	<computeroutput>action</computeroutput> says whether to allow VMs
6305	access to devices that fit the filter description (hold) or not to
6306	give them access (ignore). In addition, you should specify
6307	parameters to filter by. You can find the parameters for devices
6308	attached to your system using <command>VBoxManage list
6309	usbhost</command>. Finally, you can specify whether the filter
6310	should be active. For local filters, whether they are for local
6311	devices, remote devices over an RDP connection, or either.
6312	</para>
6313
6314	<para>
6315	When you modify a USB filter using <command>usbfilter
6316	modify</command>, you must specify the filter by index and by
6317	target, which is either a virtual machine or
6318	<computeroutput>global</computeroutput>. See the output of
6319	<command>VBoxManage list usbfilters</command> to find global
6320	filter indexes and <command>VBoxManage showvminfo</command> to
6321	find indexes for individual machines. The properties which can be
6322	changed are the same as for <command>usbfilter add</command>. To
6323	remove a filter, use <command>usbfilter remove</command> and
6324	specify the index and the target.
6325	</para>
6326
6327	<para>
6328	The following is a list of the additional <command>usbfilter
6329	add</command> and <command>usbfilter modify</command> options,
6330	with details of how to use them.
6331	</para>
6332
6333	<itemizedlist>
6334
6335	<listitem>
6336	<para>
6337	<computeroutput>--action ignore\|hold</computeroutput>:
6338	Specifies whether devices that fit the filter description are
6339	allowed access by machines (hold), or have access denied
6340	(ignore). Applies to global filters only.
6341	</para>
6342	</listitem>
6343
6344	<listitem>
6345	<para>
6346	<computeroutput>--active yes\|no</computeroutput>: Specifies
6347	whether the USB Filter is active or temporarily disabled. For
6348	<computeroutput>usbfilter create</computeroutput> the default
6349	is active.
6350	</para>
6351	</listitem>
6352
6353	<listitem>
6354	<para>
6355	<computeroutput>--vendorid <XXXX>\|""</computeroutput>:
6356	Specifies a vendor ID filter. The string representation for an
6357	exact match has the form XXXX, where X is the hexadecimal
6358	digit, including leading zeroes.
6359	</para>
6360	</listitem>
6361
6362	<listitem>
6363	<para>
6364	<computeroutput>--productid <XXXX>\|""</computeroutput>:
6365	Specifies a product ID filter. The string representation for
6366	an exact match has the form XXXX, where X is the hexadecimal
6367	digit, including leading zeroes.
6368	</para>
6369	</listitem>
6370
6371	<listitem>
6372	<para>
6373	<computeroutput>--revision <IIFF>\|""</computeroutput>:
6374	Specifies a revision ID filter. The string representation for
6375	an exact match has the form IIFF, where I is the decimal digit
6376	of the integer part of the revision, and F is the decimal
6377	digit of its fractional part, including leading and trailing
6378	zeros. Note that for interval filters, it is best to use the
6379	hexadecimal form, because the revision is stored as a 16-bit
6380	packed BCD value. Therefore, the expression int:0x0100-0x0199
6381	will match any revision from 1.0 to 1.99 inclusive.
6382	</para>
6383	</listitem>
6384
6385	<listitem>
6386	<para>
6387	<computeroutput>--manufacturer
6388	<string>\|""</computeroutput>: Specifies a manufacturer
6389	ID filter, as a string.
6390	</para>
6391	</listitem>
6392
6393	<listitem>
6394	<para>
6395	<computeroutput>--product <string>\|""</computeroutput>:
6396	Specifies a product ID filter, as a string.
6397	</para>
6398	</listitem>
6399
6400	<listitem>
6401	<para>
6402	<computeroutput>--remote yes\|no""</computeroutput>: Specifies
6403	a remote filter, indicating whether the device is physically
6404	connected to a remote VRDE client or to a local host machine.
6405	Applies to VM filters only.
6406	</para>
6407	</listitem>
6408
6409	<listitem>
6410	<para>
6411	<computeroutput>--serialnumber
6412	<string>\|""</computeroutput>: Specifies a serial number
6413	filter, as a string.
6414	</para>
6415	</listitem>
6416
6417	<listitem>
6418	<para>
6419	<computeroutput>--maskedinterfaces
6420	<XXXXXXXX></computeroutput>: Specifies a masked
6421	interface filter, for hiding one or more USB interfaces from
6422	the guest. The value is a bit mask where the set bits
6423	correspond to the USB interfaces that should be hidden, or
6424	masked off. This feature only works on Linux hosts.
6425	</para>
6426	</listitem>
6427
6428	</itemizedlist>
6429
6430	</sect1>
6431
6432	<sect1 id="vboxmanage-guestproperty">
6433
6434	<title>VBoxManage guestproperty</title>
6435
6436	<para>
6437	The <command>guestproperty</command> commands enable you to get or
6438	set properties of a running virtual machine. See
6439	<xref linkend="guestadd-guestprops" />. Guest properties are
6440	arbitrary keyword-value string pairs which can be written to and
6441	read from by either the guest or the host, so they can be used as
6442	a low-volume communication channel for strings, provided that a
6443	guest is running and has the Guest Additions installed. In
6444	addition, a number of values whose keywords begin with
6445	<computeroutput>/VirtualBox/</computeroutput>are automatically set
6446	and maintained by the Guest Additions.
6447	</para>
6448
6449	<para>
6450	The following subcommands are available, where
6451	<computeroutput><vm></computeroutput> can either be a VM
6452	name or a VM UUID, as with the other <command>VBoxManage</command>
6453	commands:
6454	</para>
6455
6456	<itemizedlist>
6457
6458	<listitem>
6459	<para>
6460	<computeroutput>enumerate <vm> [--patterns
6461	<pattern>]</computeroutput>: Lists all the guest
6462	properties that are available for the given VM, including the
6463	value. This list will be very limited if the guest's service
6464	process cannot be contacted, for example because the VM is not
6465	running or the Guest Additions are not installed.
6466	</para>
6467
6468	<para>
6469	If <computeroutput>--patterns <pattern></computeroutput>
6470	is specified, it acts as a filter to only list properties that
6471	match the given pattern. The pattern can contain the following
6472	wildcard characters:
6473	</para>
6474
6475	<itemizedlist>
6476
6477	<listitem>
6478	<para>
6479	<computeroutput>*</computeroutput> (asterisk): Represents
6480	any number of characters. For example,
6481	"<computeroutput>/VirtualBox*</computeroutput>" would
6482	match all properties beginning with "/VirtualBox".
6483	</para>
6484	</listitem>
6485
6486	<listitem>
6487	<para>
6488	<computeroutput>?</computeroutput> (question mark):
6489	Represents a single arbitrary character. For example,
6490	"<computeroutput>fo?</computeroutput>" would match both
6491	"foo" and "for".
6492	</para>
6493	</listitem>
6494
6495	<listitem>
6496	<para>
6497	<computeroutput>\|</computeroutput> (pipe symbol): Can be
6498	used to specify multiple alternative patterns. For
6499	example, "<computeroutput>s\|t</computeroutput>" would
6500	match anything starting with either "s" or "t".
6501	</para>
6502	</listitem>
6503
6504	</itemizedlist>
6505	</listitem>
6506
6507	<listitem>
6508	<para>
6509	<computeroutput>get <vm>
6510	<property></computeroutput>: Retrieves the value of a
6511	single property only. If the property cannot be found, for
6512	example because the guest is not running, the following
6513	message is shown:
6514	</para>
6515
6516	<screen>No value set!</screen>
6517	</listitem>
6518
6519	<listitem>
6520	<para>
6521	<computeroutput>set <vm> <property> [<value>
6522	[--flags <flags>]]</computeroutput>: Enables you to set
6523	a guest property by specifying the keyword and value. If
6524	<computeroutput><value></computeroutput> is omitted, the
6525	property is deleted. With
6526	<computeroutput>--flags</computeroutput>, you can specify
6527	additional behavior. You can combine several flags by
6528	separating them with commas.
6529	</para>
6530
6531	<itemizedlist>
6532
6533	<listitem>
6534	<para>
6535	<computeroutput>TRANSIENT</computeroutput>: The value will
6536	not be stored with the VM data when the VM exits.
6537	</para>
6538	</listitem>
6539
6540	<listitem>
6541	<para>
6542	<computeroutput>TRANSRESET</computeroutput>: The value
6543	will be deleted as soon as the VM restarts or exits.
6544	</para>
6545	</listitem>
6546
6547	<listitem>
6548	<para>
6549	<computeroutput>RDONLYGUEST</computeroutput>: The value
6550	can only be changed by the host, but the guest can only
6551	read it.
6552	</para>
6553	</listitem>
6554
6555	<listitem>
6556	<para>
6557	<computeroutput>RDONLYHOST</computeroutput>: The value can
6558	only be changed by the guest, but the host can only read
6559	it.
6560	</para>
6561	</listitem>
6562
6563	<listitem>
6564	<para>
6565	<computeroutput>READONLY</computeroutput>: The value
6566	cannot be changed at all.
6567	</para>
6568	</listitem>
6569
6570	</itemizedlist>
6571	</listitem>
6572
6573	<listitem>
6574	<para>
6575	<computeroutput>wait <vm> <pattern> --timeout
6576	<timeout></computeroutput>: Waits for a particular value
6577	described by the pattern string to change or to be deleted or
6578	created. The pattern rules are the same as for the
6579	<command>enumerate</command> subcommand.
6580	</para>
6581	</listitem>
6582
6583	<listitem>
6584	<para>
6585	<computeroutput>delete <vm>
6586	<property></computeroutput>: Deletes a guest property
6587	which has been set previously.
6588	</para>
6589	</listitem>
6590
6591	</itemizedlist>
6592
6593	</sect1>
6594
6595	<sect1 id="vboxmanage-guestcontrol">
6596
6597	<title>VBoxManage guestcontrol</title>
6598
6599	<para>
6600	The <command>guestcontrol</command> commands enable control of the
6601	guest from the host. See
6602	<xref
6603	linkend="guestadd-guestcontrol" /> for an introduction.
6604	</para>
6605
6606	<para>
6607	The <command>guestcontrol</command> command has two sets of
6608	subcommands. The first set requires guest credentials to be
6609	specified, the second does not.
6610	</para>
6611
6612	<para>
6613	The first set of subcommands is of the following form:
6614	</para>
6615
6616	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
6617	[--username <name> ]
6618	[--passwordfile <file> \| --password <password>]
6619	[--domain <domain> ]
6620	[-v\|--verbose] [-q\|quiet] ...
6621	</screen>
6622
6623	<para>
6624	The common options are as follows:
6625	</para>
6626
6627	<screen>
6628	[--username <name> ]
6629	[--passwordfile <file> \| --password <password>]
6630	[--domain <domain> ]
6631	[-v\|--verbose] [-q\|quiet]
6632	</screen>
6633
6634	<para>
6635	The common options for the first set of subcommands are explained
6636	in the following list.
6637	</para>
6638
6639	<variablelist>
6640
6641	<varlistentry>
6642	<term>
6643	<computeroutput><uuid\|vmname></computeroutput>
6644	</term>
6645
6646	<listitem>
6647	<para>
6648	Specifies the VM UUID or VM name. Mandatory.
6649	</para>
6650	</listitem>
6651	</varlistentry>
6652
6653	<varlistentry>
6654	<term>
6655	<computeroutput>--username <name></computeroutput>
6656	</term>
6657
6658	<listitem>
6659	<para>
6660	Specifies the user name on guest OS under which the process
6661	should run. This user name must already exist on the guest
6662	OS. If unspecified, the host user name is used. Optional
6663	</para>
6664	</listitem>
6665	</varlistentry>
6666
6667	<varlistentry>
6668	<term>
6669	<computeroutput>--passwordfile
6670	<file>\|--password</computeroutput>
6671	</term>
6672
6673	<listitem>
6674	<para>
6675	Specifies the absolute path on guest file system of password
6676	file containing the password for the specified user account
6677	or password for the specified user account. Optional. If
6678	both are omitted, empty password is assumed.
6679	</para>
6680	</listitem>
6681	</varlistentry>
6682
6683	<varlistentry>
6684	<term>
6685	<computeroutput>--domain <domain></computeroutput>
6686	</term>
6687
6688	<listitem>
6689	<para>
6690	User domain for Windows guests. Optional.
6691	</para>
6692	</listitem>
6693	</varlistentry>
6694
6695	<varlistentry>
6696	<term>
6697	<computeroutput>-v\|--verbose</computeroutput>
6698	</term>
6699
6700	<listitem>
6701	<para>
6702	Makes the subcommand execution more verbose. Optional
6703	</para>
6704	</listitem>
6705	</varlistentry>
6706
6707	<varlistentry>
6708	<term>
6709	<computeroutput>-q\|--quiet</computeroutput>
6710	</term>
6711
6712	<listitem>
6713	<para>
6714	Makes the subcommand execution quieter. Optional.
6715	</para>
6716	</listitem>
6717	</varlistentry>
6718
6719	</variablelist>
6720
6721	<para>
6722	The first set of subcommands are as follows:
6723	</para>
6724
6725	<itemizedlist>
6726
6727	<listitem>
6728	<para>
6729	<computeroutput>run</computeroutput>: Executes a guest
6730	program, forwarding stdout, stderr, and stdin to and from the
6731	host until it completes.
6732	</para>
6733
6734	<screen>VBoxManage guestcontrol <uuid\|vmname> run [common-options]
6735	--exe <path to executable> [--timeout <msec>]
6736	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
6737	[--ignore-operhaned-processes] [--profile]
6738	[--no-wait-stdout\|--wait-stdout]
6739	[--no-wait-stderr\|--wait-stderr]
6740	[--dos2unix] [--unix2dos]
6741	-- <program/arg0> [argument1] ... [argumentN]]
6742	</screen>
6743
6744	<variablelist>
6745
6746	<varlistentry>
6747	<term>
6748	<computeroutput><uuid\|vmname></computeroutput>
6749	</term>
6750
6751	<listitem>
6752	<para>
6753	Specifies the VM UUID or VM name. Mandatory.
6754	</para>
6755	</listitem>
6756	</varlistentry>
6757
6758	<varlistentry>
6759	<term>
6760	<computeroutput>--exe <path to
6761	executable></computeroutput>
6762	</term>
6763
6764	<listitem>
6765	<para>
6766	Specifies the absolute path of the executable on the
6767	guest OS file system. Mandatory. For example:
6768	<filename>C:\Windows\System32\calc.exe</filename>.
6769	</para>
6770	</listitem>
6771	</varlistentry>
6772
6773	<varlistentry>
6774	<term>
6775	<computeroutput>--timeout <msec></computeroutput>
6776	</term>
6777
6778	<listitem>
6779	<para>
6780	Specifies the maximum time, in microseconds, that the
6781	executable can run, during which
6782	<command>VBoxManage</command> receives its output.
6783	Optional. If unspecified, <command>VBoxManage</command>
6784	waits indefinitely for the process to end, or an error
6785	occurs.
6786	</para>
6787	</listitem>
6788	</varlistentry>
6789
6790	<varlistentry>
6791	<term>
6792	<computeroutput>-E\|--putenv
6793	<NAME>=<VALUE></computeroutput>
6794	</term>
6795
6796	<listitem>
6797	<para>
6798	Sets, modifies, and unsets environment variables in the
6799	environment in which the program will run. Optional.
6800	</para>
6801
6802	<para>
6803	The guest process is created with the standard default
6804	guest OS environment. Use this option to modify that
6805	default environment. To set or modify a variable use:
6806	<computeroutput><NAME>=<VALUE></computeroutput>.
6807	To unset a variable use:
6808	<computeroutput><NAME>=</computeroutput>
6809	</para>
6810
6811	<para>
6812	Any spaces in names and values should be enclosed by
6813	quotes.
6814	</para>
6815
6816	<para>
6817	To set, modify, and unset multiple variables, use
6818	multiple instances of the
6819	<computeroutput>--E\|--putenv</computeroutput> option.
6820	</para>
6821	</listitem>
6822	</varlistentry>
6823
6824	<varlistentry>
6825	<term>
6826	<computeroutput>--unquoted-args</computeroutput>
6827	</term>
6828
6829	<listitem>
6830	<para>
6831	Disables escaped double quoting, such as \"fred\", on
6832	arguments passed to the executed program. Optional.
6833	</para>
6834	</listitem>
6835	</varlistentry>
6836
6837	<varlistentry>
6838	<term>
6839	<computeroutput>--ignore-operhaned-processes</computeroutput>
6840	</term>
6841
6842	<listitem>
6843	<para>
6844	Ignore orphaned processes. Not yet implemented.
6845	Optional.
6846	</para>
6847	</listitem>
6848	</varlistentry>
6849
6850	<varlistentry>
6851	<term>
6852	<computeroutput>--profile</computeroutput>
6853	</term>
6854
6855	<listitem>
6856	<para>
6857	Use Profile. Not yet implemented. Optional.
6858	</para>
6859	</listitem>
6860	</varlistentry>
6861
6862	<varlistentry>
6863	<term>
6864	<computeroutput>--no-wait-stdout\|--wait-stdout</computeroutput>
6865	</term>
6866
6867	<listitem>
6868	<para>
6869	Does not wait or waits until the guest process ends and
6870	receives its exit code and reason/flags. In the case of
6871	<computeroutput>--wait-stdout</computeroutput>,
6872	<command>VBoxManage</command> receives its stdout while
6873	the process runs. Optional.
6874	</para>
6875	</listitem>
6876	</varlistentry>
6877
6878	<varlistentry>
6879	<term>
6880	<computeroutput>--no-wait-stderr\|--wait-stderr</computeroutput>
6881	</term>
6882
6883	<listitem>
6884	<para>
6885	Does not wait or waits until the guest process ends and
6886	receives its exit code, error messages, and flags. In
6887	the case of
6888	<computeroutput>--wait-stderr</computeroutput>,
6889	<command>VBoxManage</command> receives its stderr while
6890	the process runs. Optional.
6891	</para>
6892	</listitem>
6893	</varlistentry>
6894
6895	<varlistentry>
6896	<term>
6897	<computeroutput>--dos2unix</computeroutput>
6898	</term>
6899
6900	<listitem>
6901	<para>
6902	Converts output from DOS/Windows guests to
6903	UNIX/Linux-compatible line endings, CR + LF to LF. Not
6904	yet implemented. Optional.
6905	</para>
6906	</listitem>
6907	</varlistentry>
6908
6909	<varlistentry>
6910	<term>
6911	<computeroutput>--unix2dos</computeroutput>
6912	</term>
6913
6914	<listitem>
6915	<para>
6916	Converts output from a UNIX/Linux guests to
6917	DOS/Windows-compatible line endings, LF to CR + LF. Not
6918	yet implemented. Optional.
6919	</para>
6920	</listitem>
6921	</varlistentry>
6922
6923	<varlistentry>
6924	<term>
6925	<computeroutput>[-- <program/arg0>
6926	[<argument1>] ...
6927	[<argumentN>]]</computeroutput>
6928	</term>
6929
6930	<listitem>
6931	<para>
6932	Specifies the program name, followed by one or more
6933	arguments to pass to the program. Optional.
6934	</para>
6935
6936	<para>
6937	Any spaces in arguments should be enclosed by quotes.
6938	</para>
6939	</listitem>
6940	</varlistentry>
6941
6942	</variablelist>
6943
6944	<note>
6945	<para>
6946	On Windows there are certain limitations for graphical
6947	applications. See <xref linkend="KnownIssues" />.
6948	</para>
6949	</note>
6950
6951	<para>
6952	Examples of using the <command>guestcontrol run</command>
6953	command are as follows:
6954	</para>
6955
6956	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
6957	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
6958
6959	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
6960	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
6961
6962	<para>
6963	Note that the double backslashes in the second example are
6964	only required on UNIX hosts.
6965	</para>
6966
6967	<note>
6968	<para>
6969	For certain commands a user name of an existing user account
6970	on the guest must be specified. Anonymous executions are not
6971	supported for security reasons. A user account password,
6972	however, is optional and depends on the guest's OS security
6973	policy or rules. If no password is specified for a given
6974	user name, an empty password will be used. On certain OSes
6975	like Windows the security policy may needs to be adjusted in
6976	order to allow user accounts with an empty password set.
6977	Also, global domain rules might apply and therefore cannot
6978	be changed.
6979	</para>
6980	</note>
6981
6982	<para>
6983	Starting at &product-name; 4.1.2 guest process execution by
6984	default is limited to serve up to five guest processes at a
6985	time. If a new guest process gets started which would exceed
6986	this limit, the oldest not running guest process will be
6987	discarded in order to be able to run that new process. Also,
6988	retrieving output from this old guest process will not be
6989	possible anymore then. If all five guest processes are still
6990	active and running, starting a new guest process will result
6991	in an appropriate error message.
6992	</para>
6993
6994	<para>
6995	To raise or lower the guest process execution limit, either
6996	use the guest property
6997	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
6998	or <command>VBoxService</command> command line by specifying
6999	<computeroutput>--control-procs-max-kept</computeroutput>
7000	needs to be modified. A restart of the guest OS is required
7001	afterwards. To serve unlimited guest processes, a value of
7002	<computeroutput>0</computeroutput> needs to be set, but this
7003	is not recommended.
7004	</para>
7005	</listitem>
7006
7007	<listitem>
7008	<para>
7009	<computeroutput>start</computeroutput>: Executes a guest
7010	program until it completes.
7011	</para>
7012
7013	<screen>VBoxManage guestcontrol <uuid\|vmname> start [common-options]
7014	[--exe <path to executable>] [--timeout <msec>]
7015	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
7016	[--ignore-operhaned-processes] [--profile]
7017	-- <program/arg0> [argument1] ... [argumentN]]
7018	</screen>
7019
7020	<para>
7021	Where the options are as follows:
7022	</para>
7023
7024	<variablelist>
7025
7026	<varlistentry>
7027	<term>
7028	<computeroutput><uuid\|vmname></computeroutput>
7029	</term>
7030
7031	<listitem>
7032	<para>
7033	Specifies the VM UUID or VM name. Mandatory.
7034	</para>
7035	</listitem>
7036	</varlistentry>
7037
7038	<varlistentry>
7039	<term>
7040	<computeroutput>--exe <path to
7041	executable></computeroutput>
7042	</term>
7043
7044	<listitem>
7045	<para>
7046	Specifies the absolute path of the executable on the
7047	guest OS file system. Mandatory. For example:
7048	<filename>C:\Windows\System32\calc.exe</filename>
7049	</para>
7050	</listitem>
7051	</varlistentry>
7052
7053	<varlistentry>
7054	<term>
7055	<computeroutput>--timeout <msec></computeroutput>
7056	</term>
7057
7058	<listitem>
7059	<para>
7060	Specifies the maximum time, in microseconds, that the
7061	executable can run. Optional. If unspecified,
7062	<command>VBoxManage</command> waits indefinitely for the
7063	process to end, or an error occurs.
7064	</para>
7065	</listitem>
7066	</varlistentry>
7067
7068	<varlistentry>
7069	<term>
7070	<computeroutput>-E\|--putenv
7071	<NAME>=<VALUE></computeroutput>
7072	</term>
7073
7074	<listitem>
7075	<para>
7076	Sets, modifies, and unsets environment variables in the
7077	environment in which the program will run. Optional.
7078	</para>
7079
7080	<para>
7081	The guest process is created with the standard default
7082	guest OS environment. Use this option to modify that
7083	default environment. To set or modify a variable use:
7084	<computeroutput><NAME>=<VALUE></computeroutput>.
7085	To unset a variable use:
7086	<computeroutput><NAME>=</computeroutput>
7087	</para>
7088
7089	<para>
7090	Any spaces in names and values should be enclosed by
7091	quotes.
7092	</para>
7093
7094	<para>
7095	To set, modify, or unset multiple variables, use
7096	multiple instances of the
7097	<computeroutput>--E\|--putenv</computeroutput> option.
7098	</para>
7099	</listitem>
7100	</varlistentry>
7101
7102	<varlistentry>
7103	<term>
7104	<computeroutput>--unquoted-args</computeroutput>
7105	</term>
7106
7107	<listitem>
7108	<para>
7109	Disables escaped double quoting, such as \"fred\", on
7110	arguments passed to the executed program. Optional.
7111	</para>
7112	</listitem>
7113	</varlistentry>
7114
7115	<varlistentry>
7116	<term>
7117	<computeroutput>--ignore-operhaned-processes</computeroutput>
7118	</term>
7119
7120	<listitem>
7121	<para>
7122	Ignores orphaned processes. Not yet implemented.
7123	Optional.
7124	</para>
7125	</listitem>
7126	</varlistentry>
7127
7128	<varlistentry>
7129	<term>
7130	<computeroutput>--profile</computeroutput>
7131	</term>
7132
7133	<listitem>
7134	<para>
7135	Use a profile. Not yet implemented. Optional.
7136	</para>
7137	</listitem>
7138	</varlistentry>
7139
7140	<varlistentry>
7141	<term>
7142	<computeroutput>[-- <program/arg0>
7143	[<argument1>] ...
7144	[<argumentN>]]</computeroutput>
7145	</term>
7146
7147	<listitem>
7148	<para>
7149	Specifies the program name, followed by one or more
7150	arguments to pass to the program. Optional.
7151	</para>
7152
7153	<para>
7154	Any spaces in arguments should be enclosed by quotes.
7155	</para>
7156	</listitem>
7157	</varlistentry>
7158
7159	</variablelist>
7160
7161	<note>
7162	<para>
7163	On Windows there are certain limitations for graphical
7164	applications. See <xref linkend="KnownIssues" />.
7165	</para>
7166	</note>
7167
7168	<para>
7169	Examples of using the <command>guestcontrol start</command>
7170	command are as follows:
7171	</para>
7172
7173	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
7174	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
7175
7176	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
7177	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
7178
7179	<para>
7180	Note that the double backslashes in the second example are
7181	only required on UNIX hosts.
7182	</para>
7183
7184	<note>
7185	<para>
7186	For certain commands a user name of an existing user account
7187	on the guest must be specified. Anonymous executions are not
7188	supported for security reasons. A user account password,
7189	however, is optional and depends on the guest's OS security
7190	policy or rules. If no password is specified for a given
7191	user name, an empty password will be used. On certain OSes
7192	like Windows the security policy may needs to be adjusted in
7193	order to allow user accounts with an empty password set.
7194	Also, global domain rules might apply and therefore cannot
7195	be changed.
7196	</para>
7197	</note>
7198
7199	<para>
7200	Starting at &product-name; 4.1.2 guest process execution by
7201	default is limited to serve up to five guest processes at a
7202	time. If a new guest process gets started which would exceed
7203	this limit, the oldest not running guest process will be
7204	discarded in order to be able to run that new process. Also,
7205	retrieving output from this old guest process will not be
7206	possible anymore then. If all five guest processes are still
7207	active and running, starting a new guest process will result
7208	in an appropriate error message.
7209	</para>
7210
7211	<para>
7212	To raise or lower the guest process execution limit, either
7213	use the guest property
7214	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
7215	or <command>VBoxService</command> command line by specifying
7216	<computeroutput>--control-procs-max-kept</computeroutput>
7217	needs to be modified. A restart of the guest OS is required
7218	afterwards. To serve unlimited guest processes, a value of
7219	<computeroutput>0</computeroutput> needs to be set, but this
7220	is not recommended.
7221	</para>
7222	</listitem>
7223
7224	<listitem>
7225	<para>
7226	<computeroutput>copyfrom</computeroutput>: Copies files from
7227	the guest to the host file system. Only available with Guest
7228	Additions 4.0 or later installed.
7229	</para>
7230
7231	<screen>VBoxManage guestcontrol <uuid\|vmname> copyfrom [common-options]
7232	[--follow] [--R\|recursive]
7233	--target-directory <host-dst-dir>
7234	<guest-src0> [<guest-src1> [...]] </screen>
7235
7236	<para>
7237	Where the parameters are as follows:
7238	</para>
7239
7240	<variablelist>
7241
7242	<varlistentry>
7243	<term>
7244	<computeroutput><uid\|vmname></computeroutput>
7245	</term>
7246
7247	<listitem>
7248	<para>
7249	Specifies the VM UUID or VM name. Mandatory.
7250	</para>
7251	</listitem>
7252	</varlistentry>
7253
7254	<varlistentry>
7255	<term>
7256	<computeroutput>--follow</computeroutput>
7257	</term>
7258
7259	<listitem>
7260	<para>
7261	Enables symlink following on the guest file system.
7262	Optional.
7263	</para>
7264	</listitem>
7265	</varlistentry>
7266
7267	<varlistentry>
7268	<term>
7269	<computeroutput>-R\|--recursive</computeroutput>
7270	</term>
7271
7272	<listitem>
7273	<para>
7274	Enables recursive copying of files and directories from
7275	the specified guest file system directory. Optional.
7276	</para>
7277	</listitem>
7278	</varlistentry>
7279
7280	<varlistentry>
7281	<term>
7282	<computeroutput>--target-directory
7283	<host-dst-dir></computeroutput>
7284	</term>
7285
7286	<listitem>
7287	<para>
7288	Specifies the absolute path of the host file system
7289	destination directory. Mandatory. For example:
7290	<filename>C:\Temp</filename>.
7291	</para>
7292	</listitem>
7293	</varlistentry>
7294
7295	<varlistentry>
7296	<term>
7297	<computeroutput><guest-src0> [<guest-src1>
7298	[...]]</computeroutput>
7299	</term>
7300
7301	<listitem>
7302	<para>
7303	Specifies the absolute paths of guest file system files
7304	to be copied. Mandatory. For example:
7305	<filename>C:\Windows\System32\calc.exe</filename>.
7306	Wildcards can be used in the expressions. For example:
7307	<filename>C:\Windows\System\.dll</filename>.
7308	</para>
7309	</listitem>
7310	</varlistentry>
7311
7312	</variablelist>
7313	</listitem>
7314
7315	<listitem>
7316	<para>
7317	<computeroutput>copyto</computeroutput>: Copies files from the
7318	host to the guest file system. Only available with Guest
7319	Additions 4.0 or later installed.
7320	</para>
7321
7322	<screen>VBoxManage guestcontrol <uuid\|vmname> copyto [common-options]
7323	[--follow] [--R\|recursive]
7324	--target-directory <guest-dst>
7325	<host-src0> [<host-src1> [...]] </screen>
7326
7327	<para>
7328	Where the parameters are as follows:
7329	</para>
7330
7331	<variablelist>
7332
7333	<varlistentry>
7334	<term>
7335	<computeroutput><uuid\|vmname></computeroutput>
7336	</term>
7337
7338	<listitem>
7339	<para>
7340	Specifies the VM UUID or VM name. Mandatory.
7341	</para>
7342	</listitem>
7343	</varlistentry>
7344
7345	<varlistentry>
7346	<term>
7347	<computeroutput>--follow</computeroutput>
7348	</term>
7349
7350	<listitem>
7351	<para>
7352	Enables symlink following on the host file system.
7353	Optional.
7354	</para>
7355	</listitem>
7356	</varlistentry>
7357
7358	<varlistentry>
7359	<term>
7360	<computeroutput>-R\|--recursive</computeroutput>
7361	</term>
7362
7363	<listitem>
7364	<para>
7365	Enables recursive copying of files and directories from
7366	the specified host file system directory. Optional.
7367	</para>
7368	</listitem>
7369	</varlistentry>
7370
7371	<varlistentry>
7372	<term>
7373	<computeroutput>--target-directory
7374	<guest-dst></computeroutput>
7375	</term>
7376
7377	<listitem>
7378	<para>
7379	Specifies the absolute path of the guest file system
7380	destination directory. Mandatory. For example:
7381	<filename>C:\Temp</filename>.
7382	</para>
7383	</listitem>
7384	</varlistentry>
7385
7386	<varlistentry>
7387	<term>
7388	<computeroutput><host-src0> [<host-src1>
7389	[...]]</computeroutput>
7390	</term>
7391
7392	<listitem>
7393	<para>
7394	Specifies the absolute paths of host file system files
7395	to be copied. Mandatory. For example:
7396	<filename>C:\Windows\System32\calc.exe</filename>.
7397	Wildcards can be used in the expressions. For example:
7398	<filename>C:\Windows\System\.dll</filename>.
7399	</para>
7400	</listitem>
7401	</varlistentry>
7402
7403	</variablelist>
7404	</listitem>
7405
7406	<listitem>
7407	<para>
7408	<computeroutput>md\|mkdir\|createdir\|createdirectory</computeroutput>:
7409	Creates one or more directories on the guest file system. Only
7410	available with Guest Additions 4.0 or later installed.
7411	</para>
7412
7413	<screen>VBoxManage guestcontrol <uuid\|vmname> md\|mkdir\|createdir\|createdirectory [common-options]
7414	[--parents] [--mode <mode>]
7415	<guest-dir0> [<guest-dir1> [...]] </screen>
7416
7417	<para>
7418	Where the parameters are as follows:
7419	</para>
7420
7421	<variablelist>
7422
7423	<varlistentry>
7424	<term>
7425	<computeroutput><uuid\|vmname></computeroutput>
7426	</term>
7427
7428	<listitem>
7429	<para>
7430	Specifies the VM UUID or VM name. Mandatory.
7431	</para>
7432	</listitem>
7433	</varlistentry>
7434
7435	<varlistentry>
7436	<term>
7437	<computeroutput>--parents</computeroutput>
7438	</term>
7439
7440	<listitem>
7441	<para>
7442	Creates any absent parent directories of the specified
7443	directory. Optional.
7444	</para>
7445
7446	<para>
7447	For example: If specified directory is
7448	<filename>D:\Foo\Bar</filename> and
7449	<filename>D:\Foo</filename> is absent, it will be
7450	created. In such a case, had the
7451	<computeroutput>--parents</computeroutput> option not
7452	been used, this command would have failed.
7453	</para>
7454	</listitem>
7455	</varlistentry>
7456
7457	<varlistentry>
7458	<term>
7459	<computeroutput>--mode <mode></computeroutput>
7460	</term>
7461
7462	<listitem>
7463	<para>
7464	Specifies the permission mode on the specified
7465	directories, and any parents, if the
7466	<computeroutput>--parents</computeroutput> option is
7467	used. Currently octal modes only, such as.
7468	<computeroutput>0755</computeroutput>, are supported.
7469	</para>
7470	</listitem>
7471	</varlistentry>
7472
7473	<varlistentry>
7474	<term>
7475	<computeroutput><guest-dir0> [<guest-dir1>
7476	[...]]</computeroutput>
7477	</term>
7478
7479	<listitem>
7480	<para>
7481	Specifies a list of absolute paths of directories to be
7482	created on guest file system. Mandatory. For example:
7483	<filename>D:\Foo\Bar</filename>.
7484	</para>
7485
7486	<para>
7487	All parent directories must already exist unless the
7488	switch <computeroutput>--parents</computeroutput> is
7489	used. For example, in the above example
7490	<filename>D:\Foo</filename>. The specified user must
7491	have sufficient rights to create the specified
7492	directories, and any parents that need to be created.
7493	</para>
7494	</listitem>
7495	</varlistentry>
7496
7497	</variablelist>
7498	</listitem>
7499
7500	<listitem>
7501	<para>
7502	<computeroutput>rmdir\|removedir\|removedirectory</computeroutput>:
7503	Deletes specified guest file system directories. Only
7504	available with installed Guest Additions 4.3.2 and later.
7505	</para>
7506
7507	<screen>VBoxManage guestcontrol <uuid\|vmname> rmdir\|removedir\|removedirectory [common-options]
7508	[--recursive\|-R]
7509	<guest-dir0> [<guest-dir1> [...]]
7510	</screen>
7511
7512	<para>
7513	Where the parameters are as follows:
7514	</para>
7515
7516	<variablelist>
7517
7518	<varlistentry>
7519	<term>
7520	<computeroutput><uuid\|vmname></computeroutput>
7521	</term>
7522
7523	<listitem>
7524	<para>
7525	Specifies the VM UUID or VM name. Mandatory.
7526	</para>
7527	</listitem>
7528	</varlistentry>
7529
7530	<varlistentry>
7531	<term>
7532	<computeroutput>--recursive</computeroutput>
7533	</term>
7534
7535	<listitem>
7536	<para>
7537	Recursively removes directories and contents. Optional.
7538	</para>
7539	</listitem>
7540	</varlistentry>
7541
7542	<varlistentry>
7543	<term>
7544	<computeroutput><guest-dir0> [<guest-dir1>
7545	[...]]</computeroutput>
7546	</term>
7547
7548	<listitem>
7549	<para>
7550	Specifies a list of the absolute paths of directories to
7551	be deleted on guest file system. Mandatory. Wildcards
7552	are allowed. For example:
7553	<filename>D:\Foo\*Bar</filename>. The specified user
7554	must have sufficient rights to delete the specified
7555	directories.
7556	</para>
7557	</listitem>
7558	</varlistentry>
7559
7560	</variablelist>
7561	</listitem>
7562
7563	<listitem>
7564	<para>
7565	<computeroutput>rm\|removefile</computeroutput>: Deletes
7566	specified files on the guest file system. Only available with
7567	installed Guest Additions 4.3.2 and later.
7568	</para>
7569
7570	<screen>VBoxManage guestcontrol <uuid\|vmname> rm\|removefile [common-options]
7571	[-f\|--force]
7572	<guest-file0> [<guest-file1> [...]] </screen>
7573
7574	<para>
7575	Where the parameters are as follows:
7576	</para>
7577
7578	<variablelist>
7579
7580	<varlistentry>
7581	<term>
7582	<computeroutput><uuid\|vmname></computeroutput>
7583	</term>
7584
7585	<listitem>
7586	<para>
7587	Specifies the VM UUID or VM name. Mandatory.
7588	</para>
7589	</listitem>
7590	</varlistentry>
7591
7592	<varlistentry>
7593	<term>
7594	<computeroutput>-f\|--force</computeroutput>
7595	</term>
7596
7597	<listitem>
7598	<para>
7599	Enforce operation and override any requests for
7600	confirmations. Optional.
7601	</para>
7602	</listitem>
7603	</varlistentry>
7604
7605	<varlistentry>
7606	<term>
7607	<computeroutput><guest-file0> [<guest-file1>
7608	[...]]</computeroutput>
7609	</term>
7610
7611	<listitem>
7612	<para>
7613	Specifies a list of absolute paths of files to be
7614	deleted on guest file system. Mandatory. Wildcards are
7615	allowed. For example:
7616	<filename>D:\Foo\Bar\text*.txt</filename>. The specified
7617	user should have sufficient rights to delete the
7618	specified files.
7619	</para>
7620	</listitem>
7621	</varlistentry>
7622
7623	</variablelist>
7624	</listitem>
7625
7626	<listitem>
7627	<para>
7628	<computeroutput>mv\|move\|ren\|rename</computeroutput>: Renames
7629	files and/or directories on the guest file system. Only
7630	available with installed Guest Additions 4.3.2 and later.
7631	</para>
7632
7633	<screen>VBoxManage guestcontrol <uuid\|vmname> mv\|move\|ren\|rename [common-options]
7634	<guest-source0> [<guest-source1> [...]] <guest-dest></screen>
7635
7636	<para>
7637	Where the parameters are as follows:
7638	</para>
7639
7640	<variablelist>
7641
7642	<varlistentry>
7643	<term>
7644	<computeroutput><uuid\|vmname></computeroutput>
7645	</term>
7646
7647	<listitem>
7648	<para>
7649	Specifies the VM UUID or VM name. Mandatory.
7650	</para>
7651	</listitem>
7652	</varlistentry>
7653
7654	<varlistentry>
7655	<term>
7656	<computeroutput><guest-source0>
7657	[<guest-source1> [...]]</computeroutput>
7658	</term>
7659
7660	<listitem>
7661	<para>
7662	Specifies absolute paths of files or a single directory
7663	to be moved and renamed on guest file system. Mandatory.
7664	Wildcards are allowed in file names. The specified user
7665	should have sufficient rights to access the specified
7666	files.
7667	</para>
7668	</listitem>
7669	</varlistentry>
7670
7671	<varlistentry>
7672	<term>
7673	<computeroutput><dest></computeroutput>
7674	</term>
7675
7676	<listitem>
7677	<para>
7678	Specifies the absolute path of the destination file or
7679	directory to which the files are to be moved. Mandatory.
7680	If only one file to be moved, <dest> can be file
7681	or directory, else it must be a directory. The specified
7682	user must have sufficient rights to access the
7683	destination file or directory.
7684	</para>
7685	</listitem>
7686	</varlistentry>
7687
7688	</variablelist>
7689	</listitem>
7690
7691	<listitem>
7692	<para>
7693	<computeroutput>mktemp\|createtemp\|createtemporary</computeroutput>:
7694	Creates a temporary file or directory on the guest file
7695	system, to assist subsequent copying of files from the host to
7696	the guest file systems. By default, the file or directory is
7697	created in the guest's platform specific temp directory. Not
7698	currently supported. Only available with installed Guest
7699	Additions 4.2 and later.
7700	</para>
7701
7702	<screen>VBoxManage guestcontrol <uuid\|vmname> mktemp\|createtemp\|createtemporary [common-options]
7703	[--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
7704	<template>
7705	</screen>
7706
7707	<para>
7708	The parameters are as follows:
7709	</para>
7710
7711	<variablelist>
7712
7713	<varlistentry>
7714	<term>
7715	<computeroutput><uuid\|vmname></computeroutput>
7716	</term>
7717
7718	<listitem>
7719	<para>
7720	Specifies the VM UUID or VM name. Mandatory.
7721	</para>
7722	</listitem>
7723	</varlistentry>
7724
7725	<varlistentry>
7726	<term>
7727	<computeroutput>--directory</computeroutput>
7728	</term>
7729
7730	<listitem>
7731	<para>
7732	Creates a temporary directory instead of a file,
7733	specified by the <template> parameter. Optional.
7734	</para>
7735	</listitem>
7736	</varlistentry>
7737
7738	<varlistentry>
7739	<term>
7740	<computeroutput>--secure</computeroutput>
7741	</term>
7742
7743	<listitem>
7744	<para>
7745	Enforces secure file and directory creation. Optional.
7746	The permission mode is set to
7747	<computeroutput>0755</computeroutput>. Operation fails
7748	if it cannot be performed securely.
7749	</para>
7750	</listitem>
7751	</varlistentry>
7752
7753	<varlistentry>
7754	<term>
7755	<computeroutput>--mode <mode></computeroutput>
7756	</term>
7757
7758	<listitem>
7759	<para>
7760	Specifies the permission mode of the specified
7761	directory. Optional. Currently only octal modes, such as
7762	<computeroutput>0755</computeroutput>, are supported.
7763	</para>
7764	</listitem>
7765	</varlistentry>
7766
7767	<varlistentry>
7768	<term>
7769	<computeroutput>--tmpdir
7770	<directory></computeroutput>
7771	</term>
7772
7773	<listitem>
7774	<para>
7775	Specifies the absolute path of the directory on the
7776	guest file system where the file or directory specified
7777	will be created. Optional. If unspecified, the
7778	platform-specific temp directory is used.
7779	</para>
7780	</listitem>
7781	</varlistentry>
7782
7783	<varlistentry>
7784	<term>
7785	<computeroutput><template></computeroutput>
7786	</term>
7787
7788	<listitem>
7789	<para>
7790	Specifies a file name without a directory path,
7791	containing at least one sequence of three consecutive X
7792	characters, or ending in X. Mandatory.
7793	</para>
7794	</listitem>
7795	</varlistentry>
7796
7797	</variablelist>
7798	</listitem>
7799
7800	<listitem>
7801	<para>
7802	<computeroutput>stat</computeroutput>: Displays file or file
7803	system statuses on the guest.
7804	</para>
7805
7806	<screen>VBoxManage guestcontrol <uuid\|vmname> stat [common-options]
7807	<file0> [<file1> [...]]</screen>
7808
7809	<para>
7810	Where the parameters are as follows:
7811	</para>
7812
7813	<variablelist>
7814
7815	<varlistentry>
7816	<term>
7817	<computeroutput><uuid\|vmname></computeroutput>
7818	</term>
7819
7820	<listitem>
7821	<para>
7822	Specifies the VM UUID or VM name. Mandatory.
7823	</para>
7824	</listitem>
7825	</varlistentry>
7826
7827	<varlistentry>
7828	<term>
7829	<computeroutput><file0> [<file1>
7830	[...]]</computeroutput>
7831	</term>
7832
7833	<listitem>
7834	<para>
7835	Specifies absolute paths of files or file systems on the
7836	guest file system. Mandatory. For example:
7837	<filename>/home/foo/a.out</filename>. The specified user
7838	should have sufficient rights to access the specified
7839	files or file systems.
7840	</para>
7841	</listitem>
7842	</varlistentry>
7843
7844	</variablelist>
7845	</listitem>
7846
7847	</itemizedlist>
7848
7849	<para>
7850	The second set of subcommands is of the form:
7851	</para>
7852
7853	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
7854	[-v\|--verbose] [-q\|quiet] ...
7855	</screen>
7856
7857	<para>
7858	The common options are as follows:
7859	</para>
7860
7861	<screen>
7862	[-v\|--verbose] [-q\|--quiet]
7863	</screen>
7864
7865	<para>
7866	Details of the common options for the second set of subcommands
7867	are as follows:
7868	</para>
7869
7870	<variablelist>
7871
7872	<varlistentry>
7873	<term>
7874	<computeroutput>-v\|--verbose</computeroutput>
7875	</term>
7876
7877	<listitem>
7878	<para>
7879	Makes the subcommand execution more verbose. Optional.
7880	</para>
7881	</listitem>
7882	</varlistentry>
7883
7884	<varlistentry>
7885	<term>
7886	<computeroutput>-q\|--quiet</computeroutput>
7887	</term>
7888
7889	<listitem>
7890	<para>
7891	Makes the subcommand execution quieter. Optional.
7892	</para>
7893	</listitem>
7894	</varlistentry>
7895
7896	</variablelist>
7897
7898	<para>
7899	The second set of subcommands are as follows:
7900	</para>
7901
7902	<itemizedlist>
7903
7904	<listitem>
7905	<para>
7906	<computeroutput>list</computeroutput>: Lists guest control
7907	configuration and status data. For example: open guest
7908	sessions, guest processes, and files.
7909	</para>
7910
7911	<screen>VBoxManage guestcontrol <uuid\|vmname> list [common-opts]
7912	<all\|sessions\|processes\|files> </screen>
7913
7914	<para>
7915	Where the parameters are as follows:
7916	</para>
7917
7918	<variablelist>
7919
7920	<varlistentry>
7921	<term>
7922	<computeroutput><uuid\|vmname></computeroutput>
7923	</term>
7924
7925	<listitem>
7926	<para>
7927	Specifies the VM UUID or VM name. Mandatory.
7928	</para>
7929	</listitem>
7930	</varlistentry>
7931
7932	<varlistentry>
7933	<term>
7934	<computeroutput>all\|sessions\|processes\|files</computeroutput>
7935	</term>
7936
7937	<listitem>
7938	<para>
7939	Indicates whether to list all available data or guest
7940	sessions, processes or files. Mandatory.
7941	</para>
7942	</listitem>
7943	</varlistentry>
7944
7945	</variablelist>
7946	</listitem>
7947
7948	<listitem>
7949	<para>
7950	<computeroutput>closeprocess</computeroutput>: Terminates
7951	guest processes specified by PIDs running in a guest session,
7952	specified by the session ID or name.
7953	</para>
7954
7955	<screen>VBoxManage guestcontrol <uuid\|vmname> closeprocess [common-options]
7956	--session-id <ID> \| --session-name <name or pattern>
7957	<PID0> [<PID1> [...]] </screen>
7958
7959	<para>
7960	Where the parameters are as follows:
7961	</para>
7962
7963	<variablelist>
7964
7965	<varlistentry>
7966	<term>
7967	<computeroutput><uuid\|vmname></computeroutput>
7968	</term>
7969
7970	<listitem>
7971	<para>
7972	Specifies the VM UUID or VM name. Mandatory.
7973	</para>
7974	</listitem>
7975	</varlistentry>
7976
7977	<varlistentry>
7978	<term>
7979	<computeroutput>--session-id <ID></computeroutput>
7980	</term>
7981
7982	<listitem>
7983	<para>
7984	Specifies the guest session by its ID. Optional.
7985	</para>
7986	</listitem>
7987	</varlistentry>
7988
7989	<varlistentry>
7990	<term>
7991	<computeroutput>--session-name <name or
7992	pattern></computeroutput>
7993	</term>
7994
7995	<listitem>
7996	<para>
7997	Specifies the guest session by its name, or multiple
7998	sessions using a pattern containing wildcards. Optional.
7999	</para>
8000	</listitem>
8001	</varlistentry>
8002
8003	<varlistentry>
8004	<term>
8005	<computeroutput><PID0> [<PID1>
8006	[...]]</computeroutput>
8007	</term>
8008
8009	<listitem>
8010	<para>
8011	Specifies a list of process identifiers (PIDs) of guest
8012	processes to be terminated. Mandatory.
8013	</para>
8014	</listitem>
8015	</varlistentry>
8016
8017	</variablelist>
8018	</listitem>
8019
8020	<listitem>
8021	<para>
8022	<computeroutput>closesession</computeroutput>: Closes
8023	specified guest sessions, specified either by session ID or
8024	name.
8025	</para>
8026
8027	<screen>VBoxManage guestcontrol <uuid\|vmname> closesession [common-options]
8028	--session-id <ID> \| --session-name <name or pattern> \| --all </screen>
8029
8030	<para>
8031	Where the parameters are as follows:
8032	</para>
8033
8034	<variablelist>
8035
8036	<varlistentry>
8037	<term>
8038	<computeroutput><uuid\|vmname></computeroutput>
8039	</term>
8040
8041	<listitem>
8042	<para>
8043	Specifies the VM UUID or VM name. Mandatory.
8044	</para>
8045	</listitem>
8046	</varlistentry>
8047
8048	<varlistentry>
8049	<term>
8050	<computeroutput>--session-id <ID></computeroutput>
8051	</term>
8052
8053	<listitem>
8054	<para>
8055	Specifies the guest session to be closed by ID.
8056	Optional.
8057	</para>
8058	</listitem>
8059	</varlistentry>
8060
8061	<varlistentry>
8062	<term>
8063	<computeroutput>--session-name <name or
8064	pattern></computeroutput>
8065	</term>
8066
8067	<listitem>
8068	<para>
8069	Specifies the guest session to be closed by name.
8070	Optional. Multiple sessions can be specified by using a
8071	pattern containing wildcards.
8072	</para>
8073	</listitem>
8074	</varlistentry>
8075
8076	<varlistentry>
8077	<term>
8078	<computeroutput>--all</computeroutput>
8079	</term>
8080
8081	<listitem>
8082	<para>
8083	Close all guest sessions. Optional.
8084	</para>
8085	</listitem>
8086	</varlistentry>
8087
8088	</variablelist>
8089	</listitem>
8090
8091	<listitem>
8092	<para>
8093	<computeroutput>updatega\|updateadditions\|updateguestadditions</computeroutput>:
8094	Ugrades Guest Additions already installed on the guest. Only
8095	available for already installed Guest Additions 4.0 and later.
8096	</para>
8097
8098	<screen>VBoxManage guestcontrol <uuid\|vmname> updatega\|updateadditions\|updateguestadditions
8099	[common-options]
8100	[--source <New .ISO path>]
8101	[--wait-start]
8102	[-- <argument0> [<argument1> [...]]]</screen>
8103
8104	<para>
8105	Where the parameters are as follows:
8106	</para>
8107
8108	<variablelist>
8109
8110	<varlistentry>
8111	<term>
8112	<computeroutput><uuid\|vmname></computeroutput>
8113	</term>
8114
8115	<listitem>
8116	<para>
8117	Specifies the VM UUID or VM name. Mandatory.
8118	</para>
8119	</listitem>
8120	</varlistentry>
8121
8122	<varlistentry>
8123	<term>
8124	<computeroutput>--source</computeroutput> <New .ISO
8125	path>
8126	</term>
8127
8128	<listitem>
8129	<para>
8130	Specifies the absolute path on the guest file system of
8131	the .ISO file for the Guest Additions update. Mandatory.
8132	</para>
8133	</listitem>
8134	</varlistentry>
8135
8136	<varlistentry>
8137	<term>
8138	<computeroutput>--wait-start</computeroutput>
8139	</term>
8140
8141	<listitem>
8142	<para>
8143	Indicates that <command>VBoxManage</command> starts the
8144	usual updating process on the guest and then waits until
8145	the actual Guest Additions updating begins, at which
8146	point <command>VBoxManage</command> self-terminates.
8147	Optional.
8148	</para>
8149
8150	<para>
8151	Default behavior is that <command>VBoxManage</command>
8152	waits for completion of the Guest Additions update
8153	before terminating. Use of this option is sometimes
8154	necessary, as a running <command>VBoxManage</command>
8155	can affect the interaction between the installer and the
8156	guest OS.
8157	</para>
8158	</listitem>
8159	</varlistentry>
8160
8161	<varlistentry>
8162	<term>
8163	<computeroutput>[-- <argument0> [<argument1>
8164	[...]]]</computeroutput>
8165	</term>
8166
8167	<listitem>
8168	<para>
8169	Specifies optional command line arguments to be supplied
8170	to the Guest Additions updater. Useful for retrofitting
8171	features which are not currently installed.
8172	</para>
8173
8174	<para>
8175	Arguments containing spaces should be enclosed by
8176	quotes.
8177	</para>
8178	</listitem>
8179	</varlistentry>
8180
8181	</variablelist>
8182	</listitem>
8183
8184	<listitem>
8185	<para>
8186	<computeroutput>watch</computeroutput>: Prints current guest
8187	control activity.
8188	</para>
8189
8190	<screen>VBoxManage guestcontrol <uuid\|vmname> watch [common-options]
8191	</screen>
8192
8193	<para>
8194	Where the parameters are as follows:
8195	</para>
8196
8197	<variablelist>
8198
8199	<varlistentry>
8200	<term>
8201	<computeroutput><uuid\|vmname></computeroutput>
8202	</term>
8203
8204	<listitem>
8205	<para>
8206	Specifies the VM UUID or VM name. Mandatory.
8207	</para>
8208	</listitem>
8209	</varlistentry>
8210
8211	</variablelist>
8212	</listitem>
8213
8214	</itemizedlist>
8215
8216	</sect1>
8217
8218	<sect1 id="vboxmanage-metrics">
8219
8220	<title>VBoxManage metrics</title>
8221
8222	<para>
8223	This command supports monitoring the usage of system resources.
8224	Resources are represented by various metrics associated with the
8225	host system or a particular VM. For example, the host system has a
8226	<computeroutput>CPU/Load/User</computeroutput> metric that shows
8227	the percentage of time CPUs spend executing in user mode over a
8228	specific sampling period.
8229	</para>
8230
8231	<para>
8232	Metric data is collected and retained internally. It may be
8233	retrieved at any time with the <command>VBoxManage metrics
8234	query</command> subcommand. The data is available as long as the
8235	background <computeroutput>VBoxSVC</computeroutput> process is
8236	alive. That process terminates shortly after all VMs and frontends
8237	have been closed.
8238	</para>
8239
8240	<para>
8241	By default no metrics are collected at all. Metrics collection
8242	does not start until <command>VBoxManage metrics setup</command>
8243	is invoked with a proper sampling interval and the number of
8244	metrics to be retained. The interval is measured in seconds. For
8245	example, to enable collecting the host processor and memory usage
8246	metrics every second and keeping the five most current samples,
8247	the following command can be used:
8248	</para>
8249
8250	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
8251
8252	<para>
8253	Metric collection can only be enabled for started VMs. Collected
8254	data and collection settings for a particular VM will disappear as
8255	soon as it shuts down. Use the <command>VBoxManage metrics
8256	list</command> subcommand to see which metrics are currently
8257	available. You can also use the <option>--list</option> option
8258	with any subcommand that modifies metric settings to find out
8259	which metrics were affected.
8260	</para>
8261
8262	<para>
8263	Note that the <command>VBoxManage metrics setup</command>
8264	subcommand discards all samples that may have been previously
8265	collected for the specified set of objects and metrics.
8266	</para>
8267
8268	<para>
8269	To enable or disable metrics collection without discarding the
8270	data, <command>VBoxManage metrics enable</command> and
8271	<command>VBoxManage metrics disable</command> subcommands can be
8272	used. Note that these subcommands expect metrics as parameters,
8273	not submetrics such as <computeroutput>CPU/Load</computeroutput>
8274	or <computeroutput>RAM/Usage</computeroutput>. In other words
8275	enabling <computeroutput>CPU/Load/User</computeroutput> while
8276	disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not
8277	supported.
8278	</para>
8279
8280	<para>
8281	The host and VMs have different sets of associated metrics.
8282	Available metrics can be listed with <command>VBoxManage metrics
8283	list</command> subcommand.
8284	</para>
8285
8286	<para>
8287	A complete metric name may include an aggregate function. The name
8288	has the following form:
8289	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
8290	For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
8291	stands for the minimum amount of available memory over all
8292	retained data if applied to the host object.
8293	</para>
8294
8295	<para>
8296	Subcommands may apply to all objects and metrics or can be limited
8297	to one object and a list of metrics. If no objects or metrics are
8298	given in the parameters, the subcommands will apply to all
8299	available metrics of all objects. You may use an asterisk
8300	"<computeroutput>*</computeroutput>" to explicitly specify that
8301	the command should be applied to all objects or metrics. Use
8302	<computeroutput>host</computeroutput> as the object name to limit
8303	the scope of the command to host-related metrics. To limit the
8304	scope to a subset of metrics, use a metric list with names
8305	separated by commas.
8306	</para>
8307
8308	<para>
8309	For example, to query metric data on the CPU time spent in user
8310	and kernel modes by the virtual machine named
8311	<computeroutput>test</computeroutput>, use the following command:
8312	</para>
8313
8314	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
8315
8316	<para>
8317	The following list summarizes the available subcommands:
8318	</para>
8319
8320	<variablelist>
8321
8322	<varlistentry>
8323	<term>
8324	<computeroutput>list</computeroutput>
8325	</term>
8326
8327	<listitem>
8328	<para>
8329	Shows the parameters of the currently existing metrics. Note
8330	that VM-specific metrics are only available when a
8331	particular VM is running.
8332	</para>
8333	</listitem>
8334	</varlistentry>
8335
8336	<varlistentry>
8337	<term>
8338	<computeroutput>setup</computeroutput>
8339	</term>
8340
8341	<listitem>
8342	<para>
8343	Sets the interval between taking two samples of metric data
8344	and the number of samples retained internally. The retained
8345	data is available for displaying with the
8346	<command>query</command> subcommand. The
8347	<computeroutput>--list</computeroutput> option shows which
8348	metrics have been modified as the result of the command
8349	execution.
8350	</para>
8351	</listitem>
8352	</varlistentry>
8353
8354	<varlistentry>
8355	<term>
8356	<computeroutput>enable</computeroutput>
8357	</term>
8358
8359	<listitem>
8360	<para>
8361	Resumes data collection after it has been stopped with the
8362	<command>disable</command> subcommand. Note that specifying
8363	submetrics as parameters will not enable underlying metrics.
8364	Use <computeroutput>--list</computeroutput> to find out if
8365	the command worked as expected.
8366	</para>
8367	</listitem>
8368	</varlistentry>
8369
8370	<varlistentry>
8371	<term>
8372	<computeroutput>disable</computeroutput>
8373	</term>
8374
8375	<listitem>
8376	<para>
8377	Suspends data collection without affecting collection
8378	parameters or collected data. Note that specifying
8379	submetrics as parameters will not disable underlying
8380	metrics. Use <computeroutput>--list</computeroutput> to find
8381	out if the command worked as expected.
8382	</para>
8383	</listitem>
8384	</varlistentry>
8385
8386	<varlistentry>
8387	<term>
8388	<computeroutput>query</computeroutput>
8389	</term>
8390
8391	<listitem>
8392	<para>
8393	Retrieves and displays the currently retained metric data.
8394	</para>
8395
8396	<note>
8397	<para>
8398	The <command>query</command> subcommand does not remove or
8399	flush retained data. If you query often enough you will
8400	see how old samples are gradually being phased out by new
8401	samples.
8402	</para>
8403	</note>
8404	</listitem>
8405	</varlistentry>
8406
8407	<varlistentry>
8408	<term>
8409	<computeroutput>collect</computeroutput>
8410	</term>
8411
8412	<listitem>
8413	<para>
8414	Sets the interval between taking two samples of metric data
8415	and the number of samples retained internally. The collected
8416	data is displayed periodically until Ctrl+C is pressed,
8417	unless the <computeroutput>--detach</computeroutput> option
8418	is specified. With the
8419	<computeroutput>--detach</computeroutput> option, this
8420	subcommand operates the same way as
8421	<computeroutput>setup</computeroutput> does. The
8422	<computeroutput>--list</computeroutput> option shows which
8423	metrics match the specified filter.
8424	</para>
8425	</listitem>
8426	</varlistentry>
8427
8428	</variablelist>
8429
8430	</sect1>
8431
8432	<sect1 id="vboxmanage-natnetwork">
8433
8434	<title>VBoxManage natnetwork</title>
8435
8436	<para>
8437	NAT networks use the Network Address Translation (NAT) service,
8438	which works in a similar way to a home router. It groups systems
8439	using it into a network and prevents outside systems from directly
8440	accessing those inside, while letting systems inside communicate
8441	with each other and outside systems using TCP and UDP over IPv4
8442	and IPv6.
8443	</para>
8444
8445	<para>
8446	A NAT service is attached to an internal network. Virtual machines
8447	to make use of one should be attached to it. The name of an
8448	internal network is chosen when the NAT service is created, and
8449	the internal network will be created if it does not already exist.
8450	The following is an example command to create a NAT network:
8451	</para>
8452
8453	<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
8454
8455	<para>
8456	Here, <computeroutput>natnet1</computeroutput> is the name of the
8457	internal network to be used and
8458	<computeroutput>192.168.15.0/24</computeroutput> is the network
8459	address and mask of the NAT service interface. By default, in this
8460	static configuration the gateway will be assigned the address
8461	192.168.15.1, the address after the interface address, though this
8462	is subject to change.
8463	</para>
8464
8465	<para>
8466	To add a DHCP server to the NAT network after creation, run the
8467	following command:
8468	</para>
8469
8470	<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
8471
8472	<para>
8473	The subcommands for <command>VBoxManage natnetwork</command> are
8474	as follows:
8475	</para>
8476
8477	<screen>VBoxManage natnetwork add --netname <name>
8478	[--network <network>]
8479	[--enable\|--disable]
8480	[--dhcp on\|off]
8481	[--port-forward-4 <rule>]
8482	[--loopback-4 <rule>]
8483	[--ipv6 on\|off]
8484	[--port-forward-6 <rule>]
8485	[--loopback-6 <rule>]
8486	</screen>
8487
8488	<para>
8489	<command>VBoxManage natnetwork add</command>: Creates a new
8490	internal network interface, and adds a NAT network service. This
8491	command is a prerequisite for enabling attachment of VMs to the
8492	NAT network. Parameters are as follows:
8493	</para>
8494
8495	<variablelist>
8496
8497	<varlistentry>
8498	<term>
8499	<computeroutput>--netname <name></computeroutput>
8500	</term>
8501
8502	<listitem>
8503	<para>
8504	Where <name> is the name of the new internal network
8505	interface on the host OS.
8506	</para>
8507	</listitem>
8508	</varlistentry>
8509
8510	<varlistentry>
8511	<term>
8512	<computeroutput>--network <network></computeroutput>
8513	</term>
8514
8515	<listitem>
8516	<para>
8517	Where <network> specifies the static or DHCP network
8518	address and mask of the NAT service interface. The default
8519	is a static network address.
8520	</para>
8521	</listitem>
8522	</varlistentry>
8523
8524	<varlistentry>
8525	<term>
8526	<computeroutput>--enable\|--disable</computeroutput>
8527	</term>
8528
8529	<listitem>
8530	<para>
8531	Enables and disables the NAT network service.
8532	</para>
8533	</listitem>
8534	</varlistentry>
8535
8536	<varlistentry>
8537	<term>
8538	<computeroutput>--dhcp on\|off</computeroutput>
8539	</term>
8540
8541	<listitem>
8542	<para>
8543	Enables and disables a DHCP server specified by
8544	<computeroutput>--netname</computeroutput>. Use of this
8545	option also indicates that it is a DHCP server.
8546	</para>
8547	</listitem>
8548	</varlistentry>
8549
8550	<varlistentry>
8551	<term>
8552	<computeroutput>--port-forward-4 <rule></computeroutput>
8553	</term>
8554
8555	<listitem>
8556	<para>
8557	Enables IPv4 port forwarding, with a rule specified by
8558	<rule>.
8559	</para>
8560	</listitem>
8561	</varlistentry>
8562
8563	<varlistentry>
8564	<term>
8565	<computeroutput>--loopback-4 <rule></computeroutput>
8566	</term>
8567
8568	<listitem>
8569	<para>
8570	Enables the IPv4 loopback interface, with a rule specified
8571	by <rule>.
8572	</para>
8573	</listitem>
8574	</varlistentry>
8575
8576	<varlistentry>
8577	<term>
8578	<computeroutput>--ipv6 on\|off</computeroutput>
8579	</term>
8580
8581	<listitem>
8582	<para>
8583	Enables and disables IPv6. The default setting is IPv4,
8584	disabling IPv6 enables IPv4.
8585	</para>
8586	</listitem>
8587	</varlistentry>
8588
8589	<varlistentry>
8590	<term>
8591	<computeroutput>--port-forward-6 <rule></computeroutput>
8592	</term>
8593
8594	<listitem>
8595	<para>
8596	Enables IPv6 port forwarding, with a rule specified by
8597	<rule>.
8598	</para>
8599	</listitem>
8600	</varlistentry>
8601
8602	<varlistentry>
8603	<term>
8604	<computeroutput>--loopback-6 <rule></computeroutput>
8605	</term>
8606
8607	<listitem>
8608	<para>
8609	Enables the IPv6 loopback interface, with a rule specified
8610	by <rule>.
8611	</para>
8612	</listitem>
8613	</varlistentry>
8614
8615	</variablelist>
8616
8617	<screen>VBoxManage natnetwork remove --netname <name> </screen>
8618
8619	<para>
8620	<command>VBoxManage natnetwork remove</command>: Removes a NAT
8621	network service. Parameters are as follows:
8622	</para>
8623
8624	<variablelist>
8625
8626	<varlistentry>
8627	<term>
8628	<computeroutput>--netname <name></computeroutput>
8629	</term>
8630
8631	<listitem>
8632	<para>
8633	Where <name> specifies an existing NAT network
8634	service. Does not remove any DHCP server enabled on the
8635	network.
8636	</para>
8637	</listitem>
8638	</varlistentry>
8639
8640	</variablelist>
8641
8642	<screen>VBoxManage natnetwork modify --netname <name>
8643	[--network <network>]
8644	[--enable\|--disable]
8645	[--dhcp on\|off]
8646	[--port-forward-4 <rule>]
8647	[--loopback-4 <rule>]
8648	[--ipv6 on\|off]
8649	[--port-forward-6 <rule>]
8650	[--loopback-6 <rule>]
8651	</screen>
8652
8653	<para>
8654	<command>VBoxManage natnetwork modify</command>: Modifies an
8655	existing NAT network service. Parameters are as follows:
8656	</para>
8657
8658	<variablelist>
8659
8660	<varlistentry>
8661	<term>
8662	<computeroutput>--netname <name></computeroutput>
8663	</term>
8664
8665	<listitem>
8666	<para>
8667	Where <name> specifies an existing NAT network
8668	service.
8669	</para>
8670	</listitem>
8671	</varlistentry>
8672
8673	<varlistentry>
8674	<term>
8675	<computeroutput>--network <network></computeroutput>
8676	</term>
8677
8678	<listitem>
8679	<para>
8680	Where <network> specifies the new static or DHCP
8681	network address and mask of the NAT service interface. The
8682	default is a static network address.
8683	</para>
8684	</listitem>
8685	</varlistentry>
8686
8687	<varlistentry>
8688	<term>
8689	<computeroutput>--enable\|--disable</computeroutput>
8690	</term>
8691
8692	<listitem>
8693	<para>
8694	Enables and disables the NAT network service.
8695	</para>
8696	</listitem>
8697	</varlistentry>
8698
8699	<varlistentry>
8700	<term>
8701	<computeroutput>--dhcp on\|off</computeroutput>
8702	</term>
8703
8704	<listitem>
8705	<para>
8706	Enables and disables a DHCP server. If a DHCP server is not
8707	present, using enable adds a new DHCP server.
8708	</para>
8709	</listitem>
8710	</varlistentry>
8711
8712	<varlistentry>
8713	<term>
8714	<computeroutput>--port-forward-4 <rule></computeroutput>
8715	</term>
8716
8717	<listitem>
8718	<para>
8719	Enables IPv4 port forwarding, with a rule specified by
8720	<rule>.
8721	</para>
8722	</listitem>
8723	</varlistentry>
8724
8725	<varlistentry>
8726	<term>
8727	<computeroutput>--loopback-4 <rule></computeroutput>
8728	</term>
8729
8730	<listitem>
8731	<para>
8732	Enables the IPv4 loopback interface, with a rule specified
8733	by <rule>.
8734	</para>
8735	</listitem>
8736	</varlistentry>
8737
8738	<varlistentry>
8739	<term>
8740	<computeroutput>--ipv6 on\|off</computeroutput>
8741	</term>
8742
8743	<listitem>
8744	<para>
8745	Enables and disables IPv6. The default setting is IPv4,
8746	disabling IPv6 enables IPv4.
8747	</para>
8748	</listitem>
8749	</varlistentry>
8750
8751	<varlistentry>
8752	<term>
8753	<computeroutput>--port-forward-6 <rule></computeroutput>
8754	</term>
8755
8756	<listitem>
8757	<para>
8758	Enables IPv6 port forwarding, with a rule specified by
8759	<rule>.
8760	</para>
8761	</listitem>
8762	</varlistentry>
8763
8764	<varlistentry>
8765	<term>
8766	<computeroutput>--loopback-6 <rule></computeroutput>
8767	</term>
8768
8769	<listitem>
8770	<para>
8771	Enables IPv6 loopback interface, with a rule specified by
8772	<rule>.
8773	</para>
8774	</listitem>
8775	</varlistentry>
8776
8777	</variablelist>
8778
8779	<screen>VBoxManage natnetwork start --netname <name>
8780	</screen>
8781
8782	<para>
8783	<command>VBoxManage natnetwork start</command>: Starts the
8784	specified NAT network service and any associated DHCP server.
8785	Parameters are as follows:
8786	</para>
8787
8788	<variablelist>
8789
8790	<varlistentry>
8791	<term>
8792	<computeroutput>--netname <name></computeroutput>
8793	</term>
8794
8795	<listitem>
8796	<para>
8797	Where <name> specifies an existing NAT network
8798	service.
8799	</para>
8800	</listitem>
8801	</varlistentry>
8802
8803	</variablelist>
8804
8805	<screen>VBoxManage natnetwork stop --netname <name>
8806	</screen>
8807
8808	<para>
8809	<command>VBoxManage natnetwork stop</command>: Stops the specified
8810	NAT network service and any DHCP server. Parameters are as
8811	follows:
8812	</para>
8813
8814	<variablelist>
8815
8816	<varlistentry>
8817	<term>
8818	<computeroutput>--netname <name></computeroutput>
8819	</term>
8820
8821	<listitem>
8822	<para>
8823	Where <name> specifies an existing NAT network
8824	service.
8825	</para>
8826	</listitem>
8827	</varlistentry>
8828
8829	</variablelist>
8830
8831	<screen>VBoxManage natnetwork list [<pattern>] </screen>
8832
8833	<para>
8834	<command>VBoxManage natnetwork list</command>: Lists all NAT
8835	network services, with optional filtering. Parameters are as
8836	follows:
8837	</para>
8838
8839	<variablelist>
8840
8841	<varlistentry>
8842	<term>
8843	<computeroutput>[<pattern>]</computeroutput>
8844	</term>
8845
8846	<listitem>
8847	<para>
8848	Where <pattern> is an optional filtering pattern.
8849	</para>
8850	</listitem>
8851	</varlistentry>
8852
8853	</variablelist>
8854
8855	</sect1>
8856
8857	<sect1 id="vboxmanage-hostonlyif">
8858
8859	<title>VBoxManage hostonlyif</title>
8860
8861	<para>
8862	The <command>hostonlyif</command> command enables you to change
8863	the IP configuration of a host-only network interface. For a
8864	description of host-only networking, see
8865	<xref linkend="network_hostonly" />. Each host-only interface is
8866	identified by a name and can either use the internal DHCP server
8867	or a manual IP configuration, both IP4 and IP6.
8868	</para>
8869
8870	<para>
8871	The following list summarizes the available subcommands:
8872	</para>
8873
8874	<variablelist>
8875
8876	<varlistentry>
8877	<term>
8878	<computeroutput>ipconfig "<name>"</computeroutput>
8879	</term>
8880
8881	<listitem>
8882	<para>
8883	Configures a host-only interface.
8884	</para>
8885	</listitem>
8886	</varlistentry>
8887
8888	<varlistentry>
8889	<term>
8890	<computeroutput>create</computeroutput>
8891	</term>
8892
8893	<listitem>
8894	<para>
8895	Creates a new vboxnet<N> interface on the host OS.
8896	This command is essential before you can attach VMs to a
8897	host-only network.
8898	</para>
8899	</listitem>
8900	</varlistentry>
8901
8902	<varlistentry>
8903	<term>
8904	<computeroutput>remove vboxnet<N></computeroutput>
8905	</term>
8906
8907	<listitem>
8908	<para>
8909	Removes a vboxnet<N> interface from the host OS.
8910	</para>
8911	</listitem>
8912	</varlistentry>
8913
8914	</variablelist>
8915
8916	</sect1>
8917
8918	<sect1 id="vboxmanage-usbdevsource">
8919
8920	<title>VBoxManage usbdevsource</title>
8921
8922	<para>
8923	The <command>usbdevsource</command> commands enable you to add and
8924	remove USB devices globally.
8925	</para>
8926
8927	<para>
8928	The following command adds a USB device.
8929	</para>
8930
8931	<screen>VBoxManage usbdevsource add <source name>
8932	--backend <backend>
8933	--address <address>
8934	</screen>
8935
8936	<para>
8937	Where the command line options are as follows:
8938	</para>
8939
8940	<itemizedlist>
8941
8942	<listitem>
8943	<para>
8944	<computeroutput><source name></computeroutput>:
8945	Specifies the ID of the source USB device to be added.
8946	Mandatory.
8947	</para>
8948	</listitem>
8949
8950	<listitem>
8951	<para>
8952	<computeroutput>--backend <backend></computeroutput>:
8953	Specifies the USB proxy service backend to use. Mandatory.
8954	</para>
8955	</listitem>
8956
8957	<listitem>
8958	<para>
8959	<computeroutput> --address <address></computeroutput>:
8960	Specifies the backend specific address. Mandatory.
8961	</para>
8962	</listitem>
8963
8964	</itemizedlist>
8965
8966	<para>
8967	The following command removes a USB device.
8968	</para>
8969
8970	<screen>VBoxManage usbdevsource remove <source name>
8971	</screen>
8972
8973	<para>
8974	Where the command line options are as follows:
8975	</para>
8976
8977	<itemizedlist>
8978
8979	<listitem>
8980	<para>
8981	<computeroutput><source name></computeroutput>:
8982	Specifies the ID of the source USB device to be removed.
8983	Mandatory.
8984	</para>
8985	</listitem>
8986
8987	</itemizedlist>
8988
8989	</sect1>
8990
8991	<!-- TODO: Figure out how we can generate a file with the includes... The trouble is
8992	that xpointer doesn't seem to allow including multiple elements.
8993
8994	In the mean time, when adding new VBoxManage man pages to Config.kmk,
8995	don't forget to add it here too.
8996	-->
8997
8998	<xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
8999
9000	<xi:include href="user_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9001
9002	<xi:include href="user_man_VBoxManage-clonevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9003
9004	<xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9005
9006	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9007
9008	<xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9009
9010	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9011
9012	<xi:include href="user_man_VBoxManage-cloudprofile.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9013
9014	<xi:include href="user_man_VBoxManage-cloud.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9015
9016	<xi:include href="user_man_VBoxManage-signova.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9017
9018	<xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9019
9020	<!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
9021	sect1, so it's not possible to have them "in place" -->
9022
9023	<xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
9024
9025	</chapter>

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

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

Download in other formats: