user_VBoxManage.xml@ 77790

Last change on this file since 77790 was 77777, checked in by vboxsync, 6 years ago
bugref:9312. The command 'VBoxManage cloudprofile' was implemented. It uses new style of help and documentation.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 302.9 KB

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

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

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

Download in other formats: