user_VBoxManage.xml@ 81007

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

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

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

Download in other formats: