user_VBoxManage.xml@ 92432

最後變更在這個檔案從92432是 92432,由 vboxsync 提交於 3 年前
Main" bugref:1909: Removed translation marks form printUsage and its callees. Added missed help for "VBoxManage setproperty language"
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Id Revision`
檔案大小: 193.4 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: