user_VBoxManage.xml@ 79060

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

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

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

Download in other formats: