user_VBoxManage.xml@ 83876

Last change on this file since 83876 was 82969, checked in by vboxsync, 5 years ago
Copyright year updates - manual ones.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 297.1 KB

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

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

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

Download in other formats: