user_VBoxManage.xml@ 81589

Last change on this file since 81589 was 81295, checked in by vboxsync, 5 years ago
VBoxManage/Docs: Update for clipboard file transfers.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 296.6 KB

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

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

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

Download in other formats: