user_VBoxManage.xml@ 91693

Last change on this file since 91693 was 91617, checked in by vboxsync, 3 years ago
doc/manual,FE/VBoxManage: Document the modifynvram sub-command of VBoxManage, bugref:9580
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 192.8 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!--
3	user_VBoxManage.xml:
4	VBoxManage documentation for the user manual.
5
6	This XML document is also be used for generating the help text
7	built into VBoxManage as well as manpages (hacking in progress).
8
9	Copyright (C) 2006-2020 Oracle Corporation
10
11	This file is part of VirtualBox Open Source Edition (OSE), as
12	available from http://www.virtualbox.org. This file is free software;
13	you can redistribute it and/or modify it under the terms of the GNU
14	General Public License (GPL) as published by the Free Software
15	Foundation, in version 2 as it comes in the "COPYING" file of the
16	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18	-->
19	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
20	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
21	<!ENTITY % all.entities SYSTEM "all-entities.ent">
22	%all.entities;
23	]>
24	<chapter id="vboxmanage">
25
26	<title>VBoxManage</title>
27
28	<sect1 id="vboxmanage-intro">
29
30	<title>Introduction</title>
31
32	<para>
33	As briefly mentioned in <xref linkend="frontends" />,
34	<command>VBoxManage</command> is the command-line interface to
35	&product-name;. With it, you can completely control &product-name;
36	from the command line of your host operating system.
37	<command>VBoxManage</command> supports all the features that the
38	graphical user interface gives you access to, but it supports a
39	lot more than that. It exposes all the features of the
40	virtualization engine, even those that cannot be accessed from the
41	GUI.
42	</para>
43
44	<para>
45	You will need to use the command line if you want to do the
46	following:
47	</para>
48
49	<itemizedlist>
50
51	<listitem>
52	<para>
53	Use a different user interface than the main GUI such as the
54	VBoxHeadless server.
55	</para>
56	</listitem>
57
58	<listitem>
59	<para>
60	Control some of the more advanced and experimental
61	configuration settings for a VM.
62	</para>
63	</listitem>
64
65	</itemizedlist>
66
67	<para>
68	There are two main things to keep in mind when using
69	<command>VBoxManage</command>. First,
70	<command>VBoxManage</command> must always be used with a specific
71	subcommand, such as <command>list</command> or
72	<command>createvm</command> or <command>startvm</command>. All the
73	subcommands that <command>VBoxManage</command> supports are
74	described in detail in <xref linkend="vboxmanage" />.
75	</para>
76
77	<para>
78	Second, most of these subcommands require that you specify a
79	particular virtual machine after the subcommand. There are two
80	ways you can do this:
81	</para>
82
83	<itemizedlist>
84
85	<listitem>
86	<para>
87	You can specify the VM name, as it is shown in the
88	&product-name; GUI. Note that if that name contains spaces,
89	then you must enclose the entire name in double quotes. This
90	is always required with command line arguments that contain
91	spaces. For example:
92	</para>
93
94	<screen>VBoxManage startvm "Windows XP"</screen>
95	</listitem>
96
97	<listitem>
98	<para>
99	You can specify the UUID, which is the internal unique
100	identifier that &product-name; uses to refer to the virtual
101	machine. Assuming that the VM called "Windows XP" has the UUID
102	shown below, the following command has the same effect as the
103	previous example:
104	</para>
105
106	<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen>
107	</listitem>
108
109	</itemizedlist>
110
111	<para>
112	You can enter <command>VBoxManage list vms</command> to have all
113	currently registered VMs listed with all their settings, including
114	their respective names and UUIDs.
115	</para>
116
117	<para>
118	Some typical examples of how to control &product-name; from the
119	command line are listed below:
120	</para>
121
122	<itemizedlist>
123
124	<listitem>
125	<para>
126	To create a new virtual machine from the command line and
127	immediately register it with &product-name;, use
128	<command>VBoxManage createvm</command> with the
129	<option>--register</option> option, as follows:
130	</para>
131
132	<screen>$ VBoxManage createvm --name "SUSE 10.2" --register
133	VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
134	(C) 2005-2018 Oracle Corporation
135	All rights reserved.
136
137	Virtual machine 'SUSE 10.2' is created.
138	UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
139	Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen>
140
141	<para>
142	As can be seen from the above output, a new virtual machine
143	has been created with a new UUID and a new XML settings file.
144	</para>
145
146	<para>
147	For more details, see
148	<xref
149	linkend="vboxmanage-createvm" />.
150	</para>
151	</listitem>
152
153	<listitem>
154	<para>
155	To show the configuration of a particular VM, use
156	<command>VBoxManage showvminfo</command>. See
157	<xref
158	linkend="vboxmanage-showvminfo" /> for details
159	and an example.
160	</para>
161	</listitem>
162
163	<listitem>
164	<para>
165	To change settings while a VM is powered off, use
166	<command>VBoxManage modifyvm</command>. For example:
167	</para>
168
169	<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen>
170
171	<para>
172	See also <xref linkend="vboxmanage-modifyvm" />.
173	</para>
174	</listitem>
175
176	<listitem>
177	<para>
178	To change the storage configuration, such as to add a storage
179	controller and then a virtual disk, use <command>VBoxManage
180	storagectl</command> and <command>VBoxManage
181	storageattach</command>. See
182	<xref
183	linkend="vboxmanage-storagectl" /> and
184	<xref
185	linkend="vboxmanage-storageattach" />.
186	</para>
187	</listitem>
188
189	<listitem>
190	<para>
191	To control VM operation, use one of the following:
192	</para>
193
194	<itemizedlist>
195
196	<listitem>
197	<para>
198	To start a VM that is currently powered off, use
199	<command>VBoxManage startvm</command>. See
200	<xref
201	linkend="vboxmanage-startvm" />.
202	</para>
203	</listitem>
204
205	<listitem>
206	<para>
207	To pause or save a VM that is currently running or change
208	some of its settings, use <command>VBoxManage
209	controlvm</command>. See
210	<xref
211	linkend="vboxmanage-controlvm" />.
212	</para>
213	</listitem>
214
215	</itemizedlist>
216	</listitem>
217
218	</itemizedlist>
219
220	</sect1>
221
222	<sect1 id="vboxmanage-cmd-overview">
223
224	<title>Commands Overview</title>
225
226	<para>
227	When running <command>VBoxManage</command> without parameters or
228	when supplying an invalid command line, the following command
229	syntax list is shown. Note that the output will be slightly
230	different depending on the host platform. If in doubt, check the
231	output of <command>VBoxManage</command> for the commands available
232	on your particular host.
233	</para>
234
235	<xi:include href="user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)"
236	xmlns:xi="http://www.w3.org/2001/XInclude" />
237
238	<para>
239	Each time <command>VBoxManage</command> is invoked, only one
240	command can be executed. However, a command might support several
241	subcommands which then can be invoked in one single call. The
242	following sections provide detailed reference information on the
243	different commands.
244	</para>
245
246	</sect1>
247
248	<!-- 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.virtualbox.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	</variablelist>
3331
3332	</sect1>
3333
3334	<sect1 id="vboxmanage-usbfilter">
3335
3336	<title>VBoxManage usbfilter add/modify/remove</title>
3337
3338	<screen>VBoxManage usbfilter add <index,0-N>
3339	--target <uuid\|vmname>global
3340	--name <string>
3341	--action ignore\|hold (global filters only)
3342	[--active yes\|no (yes)]
3343	[--vendorid <XXXX> (null)]
3344	[--productid <XXXX> (null)]
3345	[--revision <IIFF> (null)]
3346	[--manufacturer <string> (null)]
3347	[--product <string> (null)]
3348	[--remote yes\|no (null, VM filters only)]
3349	[--serialnumber <string> (null)]
3350	[--maskedinterfaces <XXXXXXXX>]
3351	</screen>
3352
3353	<screen>VBoxManage usbfilter modify <index,0-N>
3354	--target <uuid\|vmname>global
3355	[--name <string>]
3356	[--action ignore\|hold (global filters only)]
3357	[--active yes\|no]
3358	[--vendorid <XXXX>]
3359	[--productid <XXXX>]
3360	[--revision <IIFF>]
3361	[--manufacturer <string>]
3362	[--product <string>]
3363	[--remote yes\|no (null, VM filters only)]
3364	[--serialnumber <string>]
3365	[--maskedinterfaces <XXXXXXXX>]
3366	</screen>
3367
3368	<screen>VBoxManage usbfilter remove <index,0-N>
3369	--target <uuid\|vmname>global
3370	</screen>
3371
3372	<para>
3373	The <command>usbfilter</command> commands are used for working
3374	with USB filters in virtual machines, or global filters which
3375	affect the whole &product-name; setup. Global filters are applied
3376	before machine-specific filters, and may be used to prevent
3377	devices from being captured by any virtual machine. Global filters
3378	are always applied in a particular order, and only the first
3379	filter which fits a device is applied. For example, if the first
3380	global filter says to hold, or make available, a particular
3381	Kingston memory stick device and the second filter says to ignore
3382	all Kingston devices. That particular Kingston memory stick will
3383	be available to any machine with the appropriate filter, but no
3384	other Kingston device will.
3385	</para>
3386
3387	<para>
3388	When creating a USB filter using <command>usbfilter add</command>,
3389	you must supply three or four mandatory parameters. The index
3390	specifies the position in the list at which the filter should be
3391	placed. If there is already a filter at that position, then it and
3392	the following ones will be shifted back one place. Otherwise, the
3393	new filter will be added onto the end of the list. The
3394	<computeroutput>target</computeroutput> parameter selects the
3395	virtual machine that the filter should be attached to or use
3396	<computeroutput>global</computeroutput> to apply it to all virtual
3397	machines. <computeroutput>name</computeroutput> is a name for the
3398	new filter. For global filters,
3399	<computeroutput>action</computeroutput> says whether to allow VMs
3400	access to devices that fit the filter description (hold) or not to
3401	give them access (ignore). In addition, you should specify
3402	parameters to filter by. You can find the parameters for devices
3403	attached to your system using <command>VBoxManage list
3404	usbhost</command>. Finally, you can specify whether the filter
3405	should be active. For local filters, whether they are for local
3406	devices, remote devices over an RDP connection, or either.
3407	</para>
3408
3409	<para>
3410	When you modify a USB filter using <command>usbfilter
3411	modify</command>, you must specify the filter by index and by
3412	target, which is either a virtual machine or
3413	<computeroutput>global</computeroutput>. See the output of
3414	<command>VBoxManage list usbfilters</command> to find global
3415	filter indexes and <command>VBoxManage showvminfo</command> to
3416	find indexes for individual machines. The properties which can be
3417	changed are the same as for <command>usbfilter add</command>. To
3418	remove a filter, use <command>usbfilter remove</command> and
3419	specify the index and the target.
3420	</para>
3421
3422	<para>
3423	The following is a list of the additional <command>usbfilter
3424	add</command> and <command>usbfilter modify</command> options,
3425	with details of how to use them.
3426	</para>
3427
3428	<itemizedlist>
3429
3430	<listitem>
3431	<para>
3432	<computeroutput>--action ignore\|hold</computeroutput>:
3433	Specifies whether devices that fit the filter description are
3434	allowed access by machines (hold), or have access denied
3435	(ignore). Applies to global filters only.
3436	</para>
3437	</listitem>
3438
3439	<listitem>
3440	<para>
3441	<computeroutput>--active yes\|no</computeroutput>: Specifies
3442	whether the USB Filter is active or temporarily disabled. For
3443	<computeroutput>usbfilter create</computeroutput> the default
3444	is active.
3445	</para>
3446	</listitem>
3447
3448	<listitem>
3449	<para>
3450	<computeroutput>--vendorid <XXXX>\|""</computeroutput>:
3451	Specifies a vendor ID filter. The string representation for an
3452	exact match has the form XXXX, where X is the hexadecimal
3453	digit, including leading zeroes.
3454	</para>
3455	</listitem>
3456
3457	<listitem>
3458	<para>
3459	<computeroutput>--productid <XXXX>\|""</computeroutput>:
3460	Specifies a product ID filter. The string representation for
3461	an exact match has the form XXXX, where X is the hexadecimal
3462	digit, including leading zeroes.
3463	</para>
3464	</listitem>
3465
3466	<listitem>
3467	<para>
3468	<computeroutput>--revision <IIFF>\|""</computeroutput>:
3469	Specifies a revision ID filter. The string representation for
3470	an exact match has the form IIFF, where I is the decimal digit
3471	of the integer part of the revision, and F is the decimal
3472	digit of its fractional part, including leading and trailing
3473	zeros. Note that for interval filters, it is best to use the
3474	hexadecimal form, because the revision is stored as a 16-bit
3475	packed BCD value. Therefore, the expression int:0x0100-0x0199
3476	will match any revision from 1.0 to 1.99 inclusive.
3477	</para>
3478	</listitem>
3479
3480	<listitem>
3481	<para>
3482	<computeroutput>--manufacturer
3483	<string>\|""</computeroutput>: Specifies a manufacturer
3484	ID filter, as a string.
3485	</para>
3486	</listitem>
3487
3488	<listitem>
3489	<para>
3490	<computeroutput>--product <string>\|""</computeroutput>:
3491	Specifies a product ID filter, as a string.
3492	</para>
3493	</listitem>
3494
3495	<listitem>
3496	<para>
3497	<computeroutput>--remote yes\|no""</computeroutput>: Specifies
3498	a remote filter, indicating whether the device is physically
3499	connected to a remote VRDE client or to a local host machine.
3500	Applies to VM filters only.
3501	</para>
3502	</listitem>
3503
3504	<listitem>
3505	<para>
3506	<computeroutput>--serialnumber
3507	<string>\|""</computeroutput>: Specifies a serial number
3508	filter, as a string.
3509	</para>
3510	</listitem>
3511
3512	<listitem>
3513	<para>
3514	<computeroutput>--maskedinterfaces
3515	<XXXXXXXX></computeroutput>: Specifies a masked
3516	interface filter, for hiding one or more USB interfaces from
3517	the guest. The value is a bit mask where the set bits
3518	correspond to the USB interfaces that should be hidden, or
3519	masked off. This feature only works on Linux hosts.
3520	</para>
3521	</listitem>
3522
3523	</itemizedlist>
3524
3525	</sect1>
3526
3527	<xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3528
3529	<sect1 id="vboxmanage-guestproperty">
3530
3531	<title>VBoxManage guestproperty</title>
3532
3533	<para>
3534	The <command>guestproperty</command> commands enable you to get or
3535	set properties of a running virtual machine. See
3536	<xref linkend="guestadd-guestprops" />. Guest properties are
3537	arbitrary keyword-value string pairs which can be written to and
3538	read from by either the guest or the host, so they can be used as
3539	a low-volume communication channel for strings, provided that a
3540	guest is running and has the Guest Additions installed. In
3541	addition, a number of values whose keywords begin with
3542	<computeroutput>/VirtualBox/</computeroutput>are automatically set
3543	and maintained by the Guest Additions.
3544	</para>
3545
3546	<para>
3547	The following subcommands are available, where
3548	<computeroutput><vm></computeroutput> can either be a VM
3549	name or a VM UUID, as with the other <command>VBoxManage</command>
3550	commands:
3551	</para>
3552
3553	<itemizedlist>
3554
3555	<listitem>
3556	<para>
3557	<computeroutput>enumerate <vm> [--patterns
3558	<pattern>]</computeroutput>: Lists all the guest
3559	properties that are available for the given VM, including the
3560	value. This list will be very limited if the guest's service
3561	process cannot be contacted, for example because the VM is not
3562	running or the Guest Additions are not installed.
3563	</para>
3564
3565	<para>
3566	If <computeroutput>--patterns <pattern></computeroutput>
3567	is specified, it acts as a filter to only list properties that
3568	match the given pattern. The pattern can contain the following
3569	wildcard characters:
3570	</para>
3571
3572	<itemizedlist>
3573
3574	<listitem>
3575	<para>
3576	<computeroutput>*</computeroutput> (asterisk): Represents
3577	any number of characters. For example,
3578	"<computeroutput>/VirtualBox*</computeroutput>" would
3579	match all properties beginning with "/VirtualBox".
3580	</para>
3581	</listitem>
3582
3583	<listitem>
3584	<para>
3585	<computeroutput>?</computeroutput> (question mark):
3586	Represents a single arbitrary character. For example,
3587	"<computeroutput>fo?</computeroutput>" would match both
3588	"foo" and "for".
3589	</para>
3590	</listitem>
3591
3592	<listitem>
3593	<para>
3594	<computeroutput>\|</computeroutput> (pipe symbol): Can be
3595	used to specify multiple alternative patterns. For
3596	example, "<computeroutput>s\|t</computeroutput>" would
3597	match anything starting with either "s" or "t".
3598	</para>
3599	</listitem>
3600
3601	</itemizedlist>
3602	</listitem>
3603
3604	<listitem>
3605	<para>
3606	<computeroutput>get <vm>
3607	<property></computeroutput>: Retrieves the value of a
3608	single property only. If the property cannot be found, for
3609	example because the guest is not running, the following
3610	message is shown:
3611	</para>
3612
3613	<screen>No value set!</screen>
3614	</listitem>
3615
3616	<listitem>
3617	<para>
3618	<computeroutput>set <vm> <property> [<value>
3619	[--flags <flags>]]</computeroutput>: Enables you to set
3620	a guest property by specifying the keyword and value. If
3621	<computeroutput><value></computeroutput> is omitted, the
3622	property is deleted. With
3623	<computeroutput>--flags</computeroutput>, you can specify
3624	additional behavior. You can combine several flags by
3625	separating them with commas.
3626	</para>
3627
3628	<itemizedlist>
3629
3630	<listitem>
3631	<para>
3632	<computeroutput>TRANSIENT</computeroutput>: The value will
3633	not be stored with the VM data when the VM exits.
3634	</para>
3635	</listitem>
3636
3637	<listitem>
3638	<para>
3639	<computeroutput>TRANSRESET</computeroutput>: The value
3640	will be deleted as soon as the VM restarts or exits.
3641	</para>
3642	</listitem>
3643
3644	<listitem>
3645	<para>
3646	<computeroutput>RDONLYGUEST</computeroutput>: The value
3647	can only be changed by the host, but the guest can only
3648	read it.
3649	</para>
3650	</listitem>
3651
3652	<listitem>
3653	<para>
3654	<computeroutput>RDONLYHOST</computeroutput>: The value can
3655	only be changed by the guest, but the host can only read
3656	it.
3657	</para>
3658	</listitem>
3659
3660	<listitem>
3661	<para>
3662	<computeroutput>READONLY</computeroutput>: The value
3663	cannot be changed at all.
3664	</para>
3665	</listitem>
3666
3667	</itemizedlist>
3668	</listitem>
3669
3670	<listitem>
3671	<para>
3672	<computeroutput>wait <vm> <pattern> --timeout
3673	<timeout></computeroutput>: Waits for a particular value
3674	described by the pattern string to change or to be deleted or
3675	created. The pattern rules are the same as for the
3676	<command>enumerate</command> subcommand.
3677	</para>
3678	</listitem>
3679
3680	<listitem>
3681	<para>
3682	<computeroutput>delete <vm>
3683	<property></computeroutput>: Deletes a guest property
3684	which has been set previously.
3685	</para>
3686	</listitem>
3687
3688	</itemizedlist>
3689
3690	</sect1>
3691
3692	<sect1 id="vboxmanage-guestcontrol">
3693
3694	<title>VBoxManage guestcontrol</title>
3695
3696	<para>
3697	The <command>guestcontrol</command> commands enable control of the
3698	guest from the host. See
3699	<xref
3700	linkend="guestadd-guestcontrol" /> for an introduction.
3701	</para>
3702
3703	<para>
3704	The <command>guestcontrol</command> command has two sets of
3705	subcommands. The first set requires guest credentials to be
3706	specified, the second does not.
3707	</para>
3708
3709	<para>
3710	The first set of subcommands is of the following form:
3711	</para>
3712
3713	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
3714	[--username <name> ]
3715	[--passwordfile <file> \| --password <password>]
3716	[--domain <domain> ]
3717	[-v\|--verbose] [-q\|quiet] ...
3718	</screen>
3719
3720	<para>
3721	The common options are as follows:
3722	</para>
3723
3724	<screen>
3725	[--username <name> ]
3726	[--passwordfile <file> \| --password <password>]
3727	[--domain <domain> ]
3728	[-v\|--verbose] [-q\|quiet]
3729	</screen>
3730
3731	<para>
3732	The common options for the first set of subcommands are explained
3733	in the following list.
3734	</para>
3735
3736	<variablelist>
3737
3738	<varlistentry>
3739	<term>
3740	<computeroutput><uuid\|vmname></computeroutput>
3741	</term>
3742
3743	<listitem>
3744	<para>
3745	Specifies the VM UUID or VM name. Mandatory.
3746	</para>
3747	</listitem>
3748	</varlistentry>
3749
3750	<varlistentry>
3751	<term>
3752	<computeroutput>--username <name></computeroutput>
3753	</term>
3754
3755	<listitem>
3756	<para>
3757	Specifies the user name on guest OS under which the process
3758	should run. This user name must already exist on the guest
3759	OS. If unspecified, the host user name is used. Optional
3760	</para>
3761	</listitem>
3762	</varlistentry>
3763
3764	<varlistentry>
3765	<term>
3766	<computeroutput>--passwordfile
3767	<file>\|--password</computeroutput>
3768	</term>
3769
3770	<listitem>
3771	<para>
3772	Specifies the absolute path on guest file system of password
3773	file containing the password for the specified user account
3774	or password for the specified user account. Optional. If
3775	both are omitted, empty password is assumed.
3776	</para>
3777	</listitem>
3778	</varlistentry>
3779
3780	<varlistentry>
3781	<term>
3782	<computeroutput>--domain <domain></computeroutput>
3783	</term>
3784
3785	<listitem>
3786	<para>
3787	User domain for Windows guests. Optional.
3788	</para>
3789	</listitem>
3790	</varlistentry>
3791
3792	<varlistentry>
3793	<term>
3794	<computeroutput>-v\|--verbose</computeroutput>
3795	</term>
3796
3797	<listitem>
3798	<para>
3799	Makes the subcommand execution more verbose. Optional
3800	</para>
3801	</listitem>
3802	</varlistentry>
3803
3804	<varlistentry>
3805	<term>
3806	<computeroutput>-q\|--quiet</computeroutput>
3807	</term>
3808
3809	<listitem>
3810	<para>
3811	Makes the subcommand execution quieter. Optional.
3812	</para>
3813	</listitem>
3814	</varlistentry>
3815
3816	</variablelist>
3817
3818	<para>
3819	The first set of subcommands are as follows:
3820	</para>
3821
3822	<itemizedlist>
3823
3824	<listitem>
3825	<para>
3826	<computeroutput>run</computeroutput>: Executes a guest
3827	program, forwarding stdout, stderr, and stdin to and from the
3828	host until it completes.
3829	</para>
3830
3831	<screen>VBoxManage guestcontrol <uuid\|vmname> run [common-options]
3832	--exe <path to executable> [--timeout <msec>]
3833	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
3834	[--ignore-operhaned-processes] [--profile]
3835	[--no-wait-stdout\|--wait-stdout]
3836	[--no-wait-stderr\|--wait-stderr]
3837	[--dos2unix] [--unix2dos]
3838	-- <program/arg0> [argument1] ... [argumentN]]
3839	</screen>
3840
3841	<variablelist>
3842
3843	<varlistentry>
3844	<term>
3845	<computeroutput><uuid\|vmname></computeroutput>
3846	</term>
3847
3848	<listitem>
3849	<para>
3850	Specifies the VM UUID or VM name. Mandatory.
3851	</para>
3852	</listitem>
3853	</varlistentry>
3854
3855	<varlistentry>
3856	<term>
3857	<computeroutput>--exe <path to
3858	executable></computeroutput>
3859	</term>
3860
3861	<listitem>
3862	<para>
3863	Specifies the absolute path of the executable on the
3864	guest OS file system. Mandatory. For example:
3865	<filename>C:\Windows\System32\calc.exe</filename>.
3866	</para>
3867	</listitem>
3868	</varlistentry>
3869
3870	<varlistentry>
3871	<term>
3872	<computeroutput>--timeout <msec></computeroutput>
3873	</term>
3874
3875	<listitem>
3876	<para>
3877	Specifies the maximum time, in microseconds, that the
3878	executable can run, during which
3879	<command>VBoxManage</command> receives its output.
3880	Optional. If unspecified, <command>VBoxManage</command>
3881	waits indefinitely for the process to end, or an error
3882	occurs.
3883	</para>
3884	</listitem>
3885	</varlistentry>
3886
3887	<varlistentry>
3888	<term>
3889	<computeroutput>-E\|--putenv
3890	<NAME>=<VALUE></computeroutput>
3891	</term>
3892
3893	<listitem>
3894	<para>
3895	Sets, modifies, and unsets environment variables in the
3896	environment in which the program will run. Optional.
3897	</para>
3898
3899	<para>
3900	The guest process is created with the standard default
3901	guest OS environment. Use this option to modify that
3902	default environment. To set or modify a variable use:
3903	<computeroutput><NAME>=<VALUE></computeroutput>.
3904	To unset a variable use:
3905	<computeroutput><NAME>=</computeroutput>
3906	</para>
3907
3908	<para>
3909	Any spaces in names and values should be enclosed by
3910	quotes.
3911	</para>
3912
3913	<para>
3914	To set, modify, and unset multiple variables, use
3915	multiple instances of the
3916	<computeroutput>--E\|--putenv</computeroutput> option.
3917	</para>
3918	</listitem>
3919	</varlistentry>
3920
3921	<varlistentry>
3922	<term>
3923	<computeroutput>--unquoted-args</computeroutput>
3924	</term>
3925
3926	<listitem>
3927	<para>
3928	Disables escaped double quoting, such as \"fred\", on
3929	arguments passed to the executed program. Optional.
3930	</para>
3931	</listitem>
3932	</varlistentry>
3933
3934	<varlistentry>
3935	<term>
3936	<computeroutput>--ignore-operhaned-processes</computeroutput>
3937	</term>
3938
3939	<listitem>
3940	<para>
3941	Ignore orphaned processes. Not yet implemented.
3942	Optional.
3943	</para>
3944	</listitem>
3945	</varlistentry>
3946
3947	<varlistentry>
3948	<term>
3949	<computeroutput>--profile</computeroutput>
3950	</term>
3951
3952	<listitem>
3953	<para>
3954	Use Profile. Not yet implemented. Optional.
3955	</para>
3956	</listitem>
3957	</varlistentry>
3958
3959	<varlistentry>
3960	<term>
3961	<computeroutput>--no-wait-stdout\|--wait-stdout</computeroutput>
3962	</term>
3963
3964	<listitem>
3965	<para>
3966	Does not wait or waits until the guest process ends and
3967	receives its exit code and reason/flags. In the case of
3968	<computeroutput>--wait-stdout</computeroutput>,
3969	<command>VBoxManage</command> receives its stdout while
3970	the process runs. Optional.
3971	</para>
3972	</listitem>
3973	</varlistentry>
3974
3975	<varlistentry>
3976	<term>
3977	<computeroutput>--no-wait-stderr\|--wait-stderr</computeroutput>
3978	</term>
3979
3980	<listitem>
3981	<para>
3982	Does not wait or waits until the guest process ends and
3983	receives its exit code, error messages, and flags. In
3984	the case of
3985	<computeroutput>--wait-stderr</computeroutput>,
3986	<command>VBoxManage</command> receives its stderr while
3987	the process runs. Optional.
3988	</para>
3989	</listitem>
3990	</varlistentry>
3991
3992	<varlistentry>
3993	<term>
3994	<computeroutput>--dos2unix</computeroutput>
3995	</term>
3996
3997	<listitem>
3998	<para>
3999	Converts output from DOS/Windows guests to
4000	UNIX/Linux-compatible line endings, CR + LF to LF. Not
4001	yet implemented. Optional.
4002	</para>
4003	</listitem>
4004	</varlistentry>
4005
4006	<varlistentry>
4007	<term>
4008	<computeroutput>--unix2dos</computeroutput>
4009	</term>
4010
4011	<listitem>
4012	<para>
4013	Converts output from a UNIX/Linux guests to
4014	DOS/Windows-compatible line endings, LF to CR + LF. Not
4015	yet implemented. Optional.
4016	</para>
4017	</listitem>
4018	</varlistentry>
4019
4020	<varlistentry>
4021	<term>
4022	<computeroutput>[-- <program/arg0>
4023	[<argument1>] ...
4024	[<argumentN>]]</computeroutput>
4025	</term>
4026
4027	<listitem>
4028	<para>
4029	Specifies the program name, followed by one or more
4030	arguments to pass to the program. Optional.
4031	</para>
4032
4033	<para>
4034	Any spaces in arguments should be enclosed by quotes.
4035	</para>
4036	</listitem>
4037	</varlistentry>
4038
4039	</variablelist>
4040
4041	<note>
4042	<para>
4043	On Windows there are certain limitations for graphical
4044	applications. See <xref linkend="KnownIssues" />.
4045	</para>
4046	</note>
4047
4048	<para>
4049	Examples of using the <command>guestcontrol run</command>
4050	command are as follows:
4051	</para>
4052
4053	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
4054	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
4055
4056	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
4057	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
4058
4059	<para>
4060	Note that the double backslashes in the second example are
4061	only required on UNIX hosts.
4062	</para>
4063
4064	<note>
4065	<para>
4066	For certain commands a user name of an existing user account
4067	on the guest must be specified. Anonymous executions are not
4068	supported for security reasons. A user account password,
4069	however, is optional and depends on the guest's OS security
4070	policy or rules. If no password is specified for a given
4071	user name, an empty password will be used. On certain OSes
4072	like Windows the security policy may needs to be adjusted in
4073	order to allow user accounts with an empty password set.
4074	Also, global domain rules might apply and therefore cannot
4075	be changed.
4076	</para>
4077	</note>
4078
4079	<para>
4080	Starting at &product-name; 4.1.2 guest process execution by
4081	default is limited to serve up to five guest processes at a
4082	time. If a new guest process gets started which would exceed
4083	this limit, the oldest not running guest process will be
4084	discarded in order to be able to run that new process. Also,
4085	retrieving output from this old guest process will not be
4086	possible anymore then. If all five guest processes are still
4087	active and running, starting a new guest process will result
4088	in an appropriate error message.
4089	</para>
4090
4091	<para>
4092	To raise or lower the guest process execution limit, either
4093	use the guest property
4094	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
4095	or <command>VBoxService</command> command line by specifying
4096	<computeroutput>--control-procs-max-kept</computeroutput>
4097	needs to be modified. A restart of the guest OS is required
4098	afterwards. To serve unlimited guest processes, a value of
4099	<computeroutput>0</computeroutput> needs to be set, but this
4100	is not recommended.
4101	</para>
4102	</listitem>
4103
4104	<listitem>
4105	<para>
4106	<computeroutput>start</computeroutput>: Executes a guest
4107	program until it completes.
4108	</para>
4109
4110	<screen>VBoxManage guestcontrol <uuid\|vmname> start [common-options]
4111	[--exe <path to executable>] [--timeout <msec>]
4112	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
4113	[--ignore-operhaned-processes] [--profile]
4114	-- <program/arg0> [argument1] ... [argumentN]]
4115	</screen>
4116
4117	<para>
4118	Where the options are as follows:
4119	</para>
4120
4121	<variablelist>
4122
4123	<varlistentry>
4124	<term>
4125	<computeroutput><uuid\|vmname></computeroutput>
4126	</term>
4127
4128	<listitem>
4129	<para>
4130	Specifies the VM UUID or VM name. Mandatory.
4131	</para>
4132	</listitem>
4133	</varlistentry>
4134
4135	<varlistentry>
4136	<term>
4137	<computeroutput>--exe <path to
4138	executable></computeroutput>
4139	</term>
4140
4141	<listitem>
4142	<para>
4143	Specifies the absolute path of the executable on the
4144	guest OS file system. Mandatory. For example:
4145	<filename>C:\Windows\System32\calc.exe</filename>
4146	</para>
4147	</listitem>
4148	</varlistentry>
4149
4150	<varlistentry>
4151	<term>
4152	<computeroutput>--timeout <msec></computeroutput>
4153	</term>
4154
4155	<listitem>
4156	<para>
4157	Specifies the maximum time, in microseconds, that the
4158	executable can run. Optional. If unspecified,
4159	<command>VBoxManage</command> waits indefinitely for the
4160	process to end, or an error occurs.
4161	</para>
4162	</listitem>
4163	</varlistentry>
4164
4165	<varlistentry>
4166	<term>
4167	<computeroutput>-E\|--putenv
4168	<NAME>=<VALUE></computeroutput>
4169	</term>
4170
4171	<listitem>
4172	<para>
4173	Sets, modifies, and unsets environment variables in the
4174	environment in which the program will run. Optional.
4175	</para>
4176
4177	<para>
4178	The guest process is created with the standard default
4179	guest OS environment. Use this option to modify that
4180	default environment. To set or modify a variable use:
4181	<computeroutput><NAME>=<VALUE></computeroutput>.
4182	To unset a variable use:
4183	<computeroutput><NAME>=</computeroutput>
4184	</para>
4185
4186	<para>
4187	Any spaces in names and values should be enclosed by
4188	quotes.
4189	</para>
4190
4191	<para>
4192	To set, modify, or unset multiple variables, use
4193	multiple instances of the
4194	<computeroutput>--E\|--putenv</computeroutput> option.
4195	</para>
4196	</listitem>
4197	</varlistentry>
4198
4199	<varlistentry>
4200	<term>
4201	<computeroutput>--unquoted-args</computeroutput>
4202	</term>
4203
4204	<listitem>
4205	<para>
4206	Disables escaped double quoting, such as \"fred\", on
4207	arguments passed to the executed program. Optional.
4208	</para>
4209	</listitem>
4210	</varlistentry>
4211
4212	<varlistentry>
4213	<term>
4214	<computeroutput>--ignore-operhaned-processes</computeroutput>
4215	</term>
4216
4217	<listitem>
4218	<para>
4219	Ignores orphaned processes. Not yet implemented.
4220	Optional.
4221	</para>
4222	</listitem>
4223	</varlistentry>
4224
4225	<varlistentry>
4226	<term>
4227	<computeroutput>--profile</computeroutput>
4228	</term>
4229
4230	<listitem>
4231	<para>
4232	Use a profile. Not yet implemented. Optional.
4233	</para>
4234	</listitem>
4235	</varlistentry>
4236
4237	<varlistentry>
4238	<term>
4239	<computeroutput>[-- <program/arg0>
4240	[<argument1>] ...
4241	[<argumentN>]]</computeroutput>
4242	</term>
4243
4244	<listitem>
4245	<para>
4246	Specifies the program name, followed by one or more
4247	arguments to pass to the program. Optional.
4248	</para>
4249
4250	<para>
4251	Any spaces in arguments should be enclosed by quotes.
4252	</para>
4253	</listitem>
4254	</varlistentry>
4255
4256	</variablelist>
4257
4258	<note>
4259	<para>
4260	On Windows there are certain limitations for graphical
4261	applications. See <xref linkend="KnownIssues" />.
4262	</para>
4263	</note>
4264
4265	<para>
4266	Examples of using the <command>guestcontrol start</command>
4267	command are as follows:
4268	</para>
4269
4270	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
4271	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
4272
4273	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
4274	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
4275
4276	<para>
4277	Note that the double backslashes in the second example are
4278	only required on UNIX hosts.
4279	</para>
4280
4281	<note>
4282	<para>
4283	For certain commands a user name of an existing user account
4284	on the guest must be specified. Anonymous executions are not
4285	supported for security reasons. A user account password,
4286	however, is optional and depends on the guest's OS security
4287	policy or rules. If no password is specified for a given
4288	user name, an empty password will be used. On certain OSes
4289	like Windows the security policy may needs to be adjusted in
4290	order to allow user accounts with an empty password set.
4291	Also, global domain rules might apply and therefore cannot
4292	be changed.
4293	</para>
4294	</note>
4295
4296	<para>
4297	Starting at &product-name; 4.1.2 guest process execution by
4298	default is limited to serve up to five guest processes at a
4299	time. If a new guest process gets started which would exceed
4300	this limit, the oldest not running guest process will be
4301	discarded in order to be able to run that new process. Also,
4302	retrieving output from this old guest process will not be
4303	possible anymore then. If all five guest processes are still
4304	active and running, starting a new guest process will result
4305	in an appropriate error message.
4306	</para>
4307
4308	<para>
4309	To raise or lower the guest process execution limit, either
4310	use the guest property
4311	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
4312	or <command>VBoxService</command> command line by specifying
4313	<computeroutput>--control-procs-max-kept</computeroutput>
4314	needs to be modified. A restart of the guest OS is required
4315	afterwards. To serve unlimited guest processes, a value of
4316	<computeroutput>0</computeroutput> needs to be set, but this
4317	is not recommended.
4318	</para>
4319	</listitem>
4320
4321	<listitem>
4322	<para>
4323	<computeroutput>copyfrom</computeroutput>: Copies files from
4324	the guest to the host file system. Only available with Guest
4325	Additions 4.0 or later installed.
4326	</para>
4327
4328	<screen>VBoxManage guestcontrol <uuid\|vmname> copyfrom [common-options]
4329	[--follow] [--R\|recursive]
4330	--target-directory <host-dst-dir>
4331	<guest-src0> [<guest-src1> [...]] </screen>
4332
4333	<para>
4334	Where the parameters are as follows:
4335	</para>
4336
4337	<variablelist>
4338
4339	<varlistentry>
4340	<term>
4341	<computeroutput><uid\|vmname></computeroutput>
4342	</term>
4343
4344	<listitem>
4345	<para>
4346	Specifies the VM UUID or VM name. Mandatory.
4347	</para>
4348	</listitem>
4349	</varlistentry>
4350
4351	<varlistentry>
4352	<term>
4353	<computeroutput>--follow</computeroutput>
4354	</term>
4355
4356	<listitem>
4357	<para>
4358	Enables symlink following on the guest file system.
4359	Optional.
4360	</para>
4361	</listitem>
4362	</varlistentry>
4363
4364	<varlistentry>
4365	<term>
4366	<computeroutput>-R\|--recursive</computeroutput>
4367	</term>
4368
4369	<listitem>
4370	<para>
4371	Enables recursive copying of files and directories from
4372	the specified guest file system directory. Optional.
4373	</para>
4374	</listitem>
4375	</varlistentry>
4376
4377	<varlistentry>
4378	<term>
4379	<computeroutput>--target-directory
4380	<host-dst-dir></computeroutput>
4381	</term>
4382
4383	<listitem>
4384	<para>
4385	Specifies the absolute path of the host file system
4386	destination directory. Mandatory. For example:
4387	<filename>C:\Temp</filename>.
4388	</para>
4389	</listitem>
4390	</varlistentry>
4391
4392	<varlistentry>
4393	<term>
4394	<computeroutput><guest-src0> [<guest-src1>
4395	[...]]</computeroutput>
4396	</term>
4397
4398	<listitem>
4399	<para>
4400	Specifies the absolute paths of guest file system files
4401	to be copied. Mandatory. For example:
4402	<filename>C:\Windows\System32\calc.exe</filename>.
4403	Wildcards can be used in the expressions. For example:
4404	<filename>C:\Windows\System\.dll</filename>.
4405	</para>
4406	</listitem>
4407	</varlistentry>
4408
4409	</variablelist>
4410	</listitem>
4411
4412	<listitem>
4413	<para>
4414	<computeroutput>copyto</computeroutput>: Copies files from the
4415	host to the guest file system. Only available with Guest
4416	Additions 4.0 or later installed.
4417	</para>
4418
4419	<screen>VBoxManage guestcontrol <uuid\|vmname> copyto [common-options]
4420	[--follow] [--R\|recursive]
4421	--target-directory <guest-dst>
4422	<host-src0> [<host-src1> [...]] </screen>
4423
4424	<para>
4425	Where the parameters are as follows:
4426	</para>
4427
4428	<variablelist>
4429
4430	<varlistentry>
4431	<term>
4432	<computeroutput><uuid\|vmname></computeroutput>
4433	</term>
4434
4435	<listitem>
4436	<para>
4437	Specifies the VM UUID or VM name. Mandatory.
4438	</para>
4439	</listitem>
4440	</varlistentry>
4441
4442	<varlistentry>
4443	<term>
4444	<computeroutput>--follow</computeroutput>
4445	</term>
4446
4447	<listitem>
4448	<para>
4449	Enables symlink following on the host file system.
4450	Optional.
4451	</para>
4452	</listitem>
4453	</varlistentry>
4454
4455	<varlistentry>
4456	<term>
4457	<computeroutput>-R\|--recursive</computeroutput>
4458	</term>
4459
4460	<listitem>
4461	<para>
4462	Enables recursive copying of files and directories from
4463	the specified host file system directory. Optional.
4464	</para>
4465	</listitem>
4466	</varlistentry>
4467
4468	<varlistentry>
4469	<term>
4470	<computeroutput>--target-directory
4471	<guest-dst></computeroutput>
4472	</term>
4473
4474	<listitem>
4475	<para>
4476	Specifies the absolute path of the guest file system
4477	destination directory. Mandatory. For example:
4478	<filename>C:\Temp</filename>.
4479	</para>
4480	</listitem>
4481	</varlistentry>
4482
4483	<varlistentry>
4484	<term>
4485	<computeroutput><host-src0> [<host-src1>
4486	[...]]</computeroutput>
4487	</term>
4488
4489	<listitem>
4490	<para>
4491	Specifies the absolute paths of host file system files
4492	to be copied. Mandatory. For example:
4493	<filename>C:\Windows\System32\calc.exe</filename>.
4494	Wildcards can be used in the expressions. For example:
4495	<filename>C:\Windows\System\.dll</filename>.
4496	</para>
4497	</listitem>
4498	</varlistentry>
4499
4500	</variablelist>
4501	</listitem>
4502
4503	<listitem>
4504	<para>
4505	<computeroutput>md\|mkdir\|createdir\|createdirectory</computeroutput>:
4506	Creates one or more directories on the guest file system. Only
4507	available with Guest Additions 4.0 or later installed.
4508	</para>
4509
4510	<screen>VBoxManage guestcontrol <uuid\|vmname> md\|mkdir\|createdir\|createdirectory [common-options]
4511	[--parents] [--mode <mode>]
4512	<guest-dir0> [<guest-dir1> [...]] </screen>
4513
4514	<para>
4515	Where the parameters are as follows:
4516	</para>
4517
4518	<variablelist>
4519
4520	<varlistentry>
4521	<term>
4522	<computeroutput><uuid\|vmname></computeroutput>
4523	</term>
4524
4525	<listitem>
4526	<para>
4527	Specifies the VM UUID or VM name. Mandatory.
4528	</para>
4529	</listitem>
4530	</varlistentry>
4531
4532	<varlistentry>
4533	<term>
4534	<computeroutput>--parents</computeroutput>
4535	</term>
4536
4537	<listitem>
4538	<para>
4539	Creates any absent parent directories of the specified
4540	directory. Optional.
4541	</para>
4542
4543	<para>
4544	For example: If specified directory is
4545	<filename>D:\Foo\Bar</filename> and
4546	<filename>D:\Foo</filename> is absent, it will be
4547	created. In such a case, had the
4548	<computeroutput>--parents</computeroutput> option not
4549	been used, this command would have failed.
4550	</para>
4551	</listitem>
4552	</varlistentry>
4553
4554	<varlistentry>
4555	<term>
4556	<computeroutput>--mode <mode></computeroutput>
4557	</term>
4558
4559	<listitem>
4560	<para>
4561	Specifies the permission mode on the specified
4562	directories, and any parents, if the
4563	<computeroutput>--parents</computeroutput> option is
4564	used. Currently octal modes only, such as.
4565	<computeroutput>0755</computeroutput>, are supported.
4566	</para>
4567	</listitem>
4568	</varlistentry>
4569
4570	<varlistentry>
4571	<term>
4572	<computeroutput><guest-dir0> [<guest-dir1>
4573	[...]]</computeroutput>
4574	</term>
4575
4576	<listitem>
4577	<para>
4578	Specifies a list of absolute paths of directories to be
4579	created on guest file system. Mandatory. For example:
4580	<filename>D:\Foo\Bar</filename>.
4581	</para>
4582
4583	<para>
4584	All parent directories must already exist unless the
4585	switch <computeroutput>--parents</computeroutput> is
4586	used. For example, in the above example
4587	<filename>D:\Foo</filename>. The specified user must
4588	have sufficient rights to create the specified
4589	directories, and any parents that need to be created.
4590	</para>
4591	</listitem>
4592	</varlistentry>
4593
4594	</variablelist>
4595	</listitem>
4596
4597	<listitem>
4598	<para>
4599	<computeroutput>rmdir\|removedir\|removedirectory</computeroutput>:
4600	Deletes specified guest file system directories. Only
4601	available with installed Guest Additions 4.3.2 and later.
4602	</para>
4603
4604	<screen>VBoxManage guestcontrol <uuid\|vmname> rmdir\|removedir\|removedirectory [common-options]
4605	[--recursive\|-R]
4606	<guest-dir0> [<guest-dir1> [...]]
4607	</screen>
4608
4609	<para>
4610	Where the parameters are as follows:
4611	</para>
4612
4613	<variablelist>
4614
4615	<varlistentry>
4616	<term>
4617	<computeroutput><uuid\|vmname></computeroutput>
4618	</term>
4619
4620	<listitem>
4621	<para>
4622	Specifies the VM UUID or VM name. Mandatory.
4623	</para>
4624	</listitem>
4625	</varlistentry>
4626
4627	<varlistentry>
4628	<term>
4629	<computeroutput>--recursive</computeroutput>
4630	</term>
4631
4632	<listitem>
4633	<para>
4634	Recursively removes directories and contents. Optional.
4635	</para>
4636	</listitem>
4637	</varlistentry>
4638
4639	<varlistentry>
4640	<term>
4641	<computeroutput><guest-dir0> [<guest-dir1>
4642	[...]]</computeroutput>
4643	</term>
4644
4645	<listitem>
4646	<para>
4647	Specifies a list of the absolute paths of directories to
4648	be deleted on guest file system. Mandatory. Wildcards
4649	are allowed. For example:
4650	<filename>D:\Foo\*Bar</filename>. The specified user
4651	must have sufficient rights to delete the specified
4652	directories.
4653	</para>
4654	</listitem>
4655	</varlistentry>
4656
4657	</variablelist>
4658	</listitem>
4659
4660	<listitem>
4661	<para>
4662	<computeroutput>rm\|removefile</computeroutput>: Deletes
4663	specified files on the guest file system. Only available with
4664	installed Guest Additions 4.3.2 and later.
4665	</para>
4666
4667	<screen>VBoxManage guestcontrol <uuid\|vmname> rm\|removefile [common-options]
4668	[-f\|--force]
4669	<guest-file0> [<guest-file1> [...]] </screen>
4670
4671	<para>
4672	Where the parameters are as follows:
4673	</para>
4674
4675	<variablelist>
4676
4677	<varlistentry>
4678	<term>
4679	<computeroutput><uuid\|vmname></computeroutput>
4680	</term>
4681
4682	<listitem>
4683	<para>
4684	Specifies the VM UUID or VM name. Mandatory.
4685	</para>
4686	</listitem>
4687	</varlistentry>
4688
4689	<varlistentry>
4690	<term>
4691	<computeroutput>-f\|--force</computeroutput>
4692	</term>
4693
4694	<listitem>
4695	<para>
4696	Enforce operation and override any requests for
4697	confirmations. Optional.
4698	</para>
4699	</listitem>
4700	</varlistentry>
4701
4702	<varlistentry>
4703	<term>
4704	<computeroutput><guest-file0> [<guest-file1>
4705	[...]]</computeroutput>
4706	</term>
4707
4708	<listitem>
4709	<para>
4710	Specifies a list of absolute paths of files to be
4711	deleted on guest file system. Mandatory. Wildcards are
4712	allowed. For example:
4713	<filename>D:\Foo\Bar\text*.txt</filename>. The specified
4714	user should have sufficient rights to delete the
4715	specified files.
4716	</para>
4717	</listitem>
4718	</varlistentry>
4719
4720	</variablelist>
4721	</listitem>
4722
4723	<listitem>
4724	<para>
4725	<computeroutput>mv\|move\|ren\|rename</computeroutput>: Renames
4726	files and/or directories on the guest file system. Only
4727	available with installed Guest Additions 4.3.2 and later.
4728	</para>
4729
4730	<screen>VBoxManage guestcontrol <uuid\|vmname> mv\|move\|ren\|rename [common-options]
4731	<guest-source0> [<guest-source1> [...]] <guest-dest></screen>
4732
4733	<para>
4734	Where the parameters are as follows:
4735	</para>
4736
4737	<variablelist>
4738
4739	<varlistentry>
4740	<term>
4741	<computeroutput><uuid\|vmname></computeroutput>
4742	</term>
4743
4744	<listitem>
4745	<para>
4746	Specifies the VM UUID or VM name. Mandatory.
4747	</para>
4748	</listitem>
4749	</varlistentry>
4750
4751	<varlistentry>
4752	<term>
4753	<computeroutput><guest-source0>
4754	[<guest-source1> [...]]</computeroutput>
4755	</term>
4756
4757	<listitem>
4758	<para>
4759	Specifies absolute paths of files or a single directory
4760	to be moved and renamed on guest file system. Mandatory.
4761	Wildcards are allowed in file names. The specified user
4762	should have sufficient rights to access the specified
4763	files.
4764	</para>
4765	</listitem>
4766	</varlistentry>
4767
4768	<varlistentry>
4769	<term>
4770	<computeroutput><dest></computeroutput>
4771	</term>
4772
4773	<listitem>
4774	<para>
4775	Specifies the absolute path of the destination file or
4776	directory to which the files are to be moved. Mandatory.
4777	If only one file to be moved, <dest> can be file
4778	or directory, else it must be a directory. The specified
4779	user must have sufficient rights to access the
4780	destination file or directory.
4781	</para>
4782	</listitem>
4783	</varlistentry>
4784
4785	</variablelist>
4786	</listitem>
4787
4788	<listitem>
4789	<para>
4790	<computeroutput>mktemp\|createtemp\|createtemporary</computeroutput>:
4791	Creates a temporary file or directory on the guest file
4792	system, to assist subsequent copying of files from the host to
4793	the guest file systems. By default, the file or directory is
4794	created in the guest's platform specific temp directory. Not
4795	currently supported. Only available with installed Guest
4796	Additions 4.2 and later.
4797	</para>
4798
4799	<screen>VBoxManage guestcontrol <uuid\|vmname> mktemp\|createtemp\|createtemporary [common-options]
4800	[--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
4801	<template>
4802	</screen>
4803
4804	<para>
4805	The parameters are as follows:
4806	</para>
4807
4808	<variablelist>
4809
4810	<varlistentry>
4811	<term>
4812	<computeroutput><uuid\|vmname></computeroutput>
4813	</term>
4814
4815	<listitem>
4816	<para>
4817	Specifies the VM UUID or VM name. Mandatory.
4818	</para>
4819	</listitem>
4820	</varlistentry>
4821
4822	<varlistentry>
4823	<term>
4824	<computeroutput>--directory</computeroutput>
4825	</term>
4826
4827	<listitem>
4828	<para>
4829	Creates a temporary directory instead of a file,
4830	specified by the <template> parameter. Optional.
4831	</para>
4832	</listitem>
4833	</varlistentry>
4834
4835	<varlistentry>
4836	<term>
4837	<computeroutput>--secure</computeroutput>
4838	</term>
4839
4840	<listitem>
4841	<para>
4842	Enforces secure file and directory creation. Optional.
4843	The permission mode is set to
4844	<computeroutput>0755</computeroutput>. Operation fails
4845	if it cannot be performed securely.
4846	</para>
4847	</listitem>
4848	</varlistentry>
4849
4850	<varlistentry>
4851	<term>
4852	<computeroutput>--mode <mode></computeroutput>
4853	</term>
4854
4855	<listitem>
4856	<para>
4857	Specifies the permission mode of the specified
4858	directory. Optional. Currently only octal modes, such as
4859	<computeroutput>0755</computeroutput>, are supported.
4860	</para>
4861	</listitem>
4862	</varlistentry>
4863
4864	<varlistentry>
4865	<term>
4866	<computeroutput>--tmpdir
4867	<directory></computeroutput>
4868	</term>
4869
4870	<listitem>
4871	<para>
4872	Specifies the absolute path of the directory on the
4873	guest file system where the file or directory specified
4874	will be created. Optional. If unspecified, the
4875	platform-specific temp directory is used.
4876	</para>
4877	</listitem>
4878	</varlistentry>
4879
4880	<varlistentry>
4881	<term>
4882	<computeroutput><template></computeroutput>
4883	</term>
4884
4885	<listitem>
4886	<para>
4887	Specifies a file name without a directory path,
4888	containing at least one sequence of three consecutive X
4889	characters, or ending in X. Mandatory.
4890	</para>
4891	</listitem>
4892	</varlistentry>
4893
4894	</variablelist>
4895	</listitem>
4896
4897	<listitem>
4898	<para>
4899	<computeroutput>stat</computeroutput>: Displays file or file
4900	system statuses on the guest.
4901	</para>
4902
4903	<screen>VBoxManage guestcontrol <uuid\|vmname> stat [common-options]
4904	<file0> [<file1> [...]]</screen>
4905
4906	<para>
4907	Where the parameters are as follows:
4908	</para>
4909
4910	<variablelist>
4911
4912	<varlistentry>
4913	<term>
4914	<computeroutput><uuid\|vmname></computeroutput>
4915	</term>
4916
4917	<listitem>
4918	<para>
4919	Specifies the VM UUID or VM name. Mandatory.
4920	</para>
4921	</listitem>
4922	</varlistentry>
4923
4924	<varlistentry>
4925	<term>
4926	<computeroutput><file0> [<file1>
4927	[...]]</computeroutput>
4928	</term>
4929
4930	<listitem>
4931	<para>
4932	Specifies absolute paths of files or file systems on the
4933	guest file system. Mandatory. For example:
4934	<filename>/home/foo/a.out</filename>. The specified user
4935	should have sufficient rights to access the specified
4936	files or file systems.
4937	</para>
4938	</listitem>
4939	</varlistentry>
4940
4941	</variablelist>
4942	</listitem>
4943
4944	</itemizedlist>
4945
4946	<para>
4947	The second set of subcommands is of the form:
4948	</para>
4949
4950	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
4951	[-v\|--verbose] [-q\|quiet] ...
4952	</screen>
4953
4954	<para>
4955	The common options are as follows:
4956	</para>
4957
4958	<screen>
4959	[-v\|--verbose] [-q\|--quiet]
4960	</screen>
4961
4962	<para>
4963	Details of the common options for the second set of subcommands
4964	are as follows:
4965	</para>
4966
4967	<variablelist>
4968
4969	<varlistentry>
4970	<term>
4971	<computeroutput>-v\|--verbose</computeroutput>
4972	</term>
4973
4974	<listitem>
4975	<para>
4976	Makes the subcommand execution more verbose. Optional.
4977	</para>
4978	</listitem>
4979	</varlistentry>
4980
4981	<varlistentry>
4982	<term>
4983	<computeroutput>-q\|--quiet</computeroutput>
4984	</term>
4985
4986	<listitem>
4987	<para>
4988	Makes the subcommand execution quieter. Optional.
4989	</para>
4990	</listitem>
4991	</varlistentry>
4992
4993	</variablelist>
4994
4995	<para>
4996	The second set of subcommands are as follows:
4997	</para>
4998
4999	<itemizedlist>
5000
5001	<listitem>
5002	<para>
5003	<computeroutput>list</computeroutput>: Lists guest control
5004	configuration and status data. For example: open guest
5005	sessions, guest processes, and files.
5006	</para>
5007
5008	<screen>VBoxManage guestcontrol <uuid\|vmname> list [common-opts]
5009	<all\|sessions\|processes\|files> </screen>
5010
5011	<para>
5012	Where the parameters are as follows:
5013	</para>
5014
5015	<variablelist>
5016
5017	<varlistentry>
5018	<term>
5019	<computeroutput><uuid\|vmname></computeroutput>
5020	</term>
5021
5022	<listitem>
5023	<para>
5024	Specifies the VM UUID or VM name. Mandatory.
5025	</para>
5026	</listitem>
5027	</varlistentry>
5028
5029	<varlistentry>
5030	<term>
5031	<computeroutput>all\|sessions\|processes\|files</computeroutput>
5032	</term>
5033
5034	<listitem>
5035	<para>
5036	Indicates whether to list all available data or guest
5037	sessions, processes or files. Mandatory.
5038	</para>
5039	</listitem>
5040	</varlistentry>
5041
5042	</variablelist>
5043	</listitem>
5044
5045	<listitem>
5046	<para>
5047	<computeroutput>closeprocess</computeroutput>: Terminates
5048	guest processes specified by PIDs running in a guest session,
5049	specified by the session ID or name.
5050	</para>
5051
5052	<screen>VBoxManage guestcontrol <uuid\|vmname> closeprocess [common-options]
5053	--session-id <ID> \| --session-name <name or pattern>
5054	<PID0> [<PID1> [...]] </screen>
5055
5056	<para>
5057	Where the parameters are as follows:
5058	</para>
5059
5060	<variablelist>
5061
5062	<varlistentry>
5063	<term>
5064	<computeroutput><uuid\|vmname></computeroutput>
5065	</term>
5066
5067	<listitem>
5068	<para>
5069	Specifies the VM UUID or VM name. Mandatory.
5070	</para>
5071	</listitem>
5072	</varlistentry>
5073
5074	<varlistentry>
5075	<term>
5076	<computeroutput>--session-id <ID></computeroutput>
5077	</term>
5078
5079	<listitem>
5080	<para>
5081	Specifies the guest session by its ID. Optional.
5082	</para>
5083	</listitem>
5084	</varlistentry>
5085
5086	<varlistentry>
5087	<term>
5088	<computeroutput>--session-name <name or
5089	pattern></computeroutput>
5090	</term>
5091
5092	<listitem>
5093	<para>
5094	Specifies the guest session by its name, or multiple
5095	sessions using a pattern containing wildcards. Optional.
5096	</para>
5097	</listitem>
5098	</varlistentry>
5099
5100	<varlistentry>
5101	<term>
5102	<computeroutput><PID0> [<PID1>
5103	[...]]</computeroutput>
5104	</term>
5105
5106	<listitem>
5107	<para>
5108	Specifies a list of process identifiers (PIDs) of guest
5109	processes to be terminated. Mandatory.
5110	</para>
5111	</listitem>
5112	</varlistentry>
5113
5114	</variablelist>
5115	</listitem>
5116
5117	<listitem>
5118	<para>
5119	<computeroutput>closesession</computeroutput>: Closes
5120	specified guest sessions, specified either by session ID or
5121	name.
5122	</para>
5123
5124	<screen>VBoxManage guestcontrol <uuid\|vmname> closesession [common-options]
5125	--session-id <ID> \| --session-name <name or pattern> \| --all </screen>
5126
5127	<para>
5128	Where the parameters are as follows:
5129	</para>
5130
5131	<variablelist>
5132
5133	<varlistentry>
5134	<term>
5135	<computeroutput><uuid\|vmname></computeroutput>
5136	</term>
5137
5138	<listitem>
5139	<para>
5140	Specifies the VM UUID or VM name. Mandatory.
5141	</para>
5142	</listitem>
5143	</varlistentry>
5144
5145	<varlistentry>
5146	<term>
5147	<computeroutput>--session-id <ID></computeroutput>
5148	</term>
5149
5150	<listitem>
5151	<para>
5152	Specifies the guest session to be closed by ID.
5153	Optional.
5154	</para>
5155	</listitem>
5156	</varlistentry>
5157
5158	<varlistentry>
5159	<term>
5160	<computeroutput>--session-name <name or
5161	pattern></computeroutput>
5162	</term>
5163
5164	<listitem>
5165	<para>
5166	Specifies the guest session to be closed by name.
5167	Optional. Multiple sessions can be specified by using a
5168	pattern containing wildcards.
5169	</para>
5170	</listitem>
5171	</varlistentry>
5172
5173	<varlistentry>
5174	<term>
5175	<computeroutput>--all</computeroutput>
5176	</term>
5177
5178	<listitem>
5179	<para>
5180	Close all guest sessions. Optional.
5181	</para>
5182	</listitem>
5183	</varlistentry>
5184
5185	</variablelist>
5186	</listitem>
5187
5188	<listitem>
5189	<para>
5190	<computeroutput>updatega\|updateadditions\|updateguestadditions</computeroutput>:
5191	Ugrades Guest Additions already installed on the guest. Only
5192	available for already installed Guest Additions 4.0 and later.
5193	</para>
5194
5195	<screen>VBoxManage guestcontrol <uuid\|vmname> updatega\|updateadditions\|updateguestadditions
5196	[common-options]
5197	[--source <New .ISO path>]
5198	[--wait-start]
5199	[-- <argument0> [<argument1> [...]]]</screen>
5200
5201	<para>
5202	Where the parameters are as follows:
5203	</para>
5204
5205	<variablelist>
5206
5207	<varlistentry>
5208	<term>
5209	<computeroutput><uuid\|vmname></computeroutput>
5210	</term>
5211
5212	<listitem>
5213	<para>
5214	Specifies the VM UUID or VM name. Mandatory.
5215	</para>
5216	</listitem>
5217	</varlistentry>
5218
5219	<varlistentry>
5220	<term>
5221	<computeroutput>--source</computeroutput> <New .ISO
5222	path>
5223	</term>
5224
5225	<listitem>
5226	<para>
5227	Specifies the absolute path on the guest file system of
5228	the .ISO file for the Guest Additions update. Mandatory.
5229	</para>
5230	</listitem>
5231	</varlistentry>
5232
5233	<varlistentry>
5234	<term>
5235	<computeroutput>--wait-start</computeroutput>
5236	</term>
5237
5238	<listitem>
5239	<para>
5240	Indicates that <command>VBoxManage</command> starts the
5241	usual updating process on the guest and then waits until
5242	the actual Guest Additions updating begins, at which
5243	point <command>VBoxManage</command> self-terminates.
5244	Optional.
5245	</para>
5246
5247	<para>
5248	Default behavior is that <command>VBoxManage</command>
5249	waits for completion of the Guest Additions update
5250	before terminating. Use of this option is sometimes
5251	necessary, as a running <command>VBoxManage</command>
5252	can affect the interaction between the installer and the
5253	guest OS.
5254	</para>
5255	</listitem>
5256	</varlistentry>
5257
5258	<varlistentry>
5259	<term>
5260	<computeroutput>[-- <argument0> [<argument1>
5261	[...]]]</computeroutput>
5262	</term>
5263
5264	<listitem>
5265	<para>
5266	Specifies optional command line arguments to be supplied
5267	to the Guest Additions updater. Useful for retrofitting
5268	features which are not currently installed.
5269	</para>
5270
5271	<para>
5272	Arguments containing spaces should be enclosed by
5273	quotes.
5274	</para>
5275	</listitem>
5276	</varlistentry>
5277
5278	</variablelist>
5279	</listitem>
5280
5281	<listitem>
5282	<para>
5283	<computeroutput>watch</computeroutput>: Prints current guest
5284	control activity.
5285	</para>
5286
5287	<screen>VBoxManage guestcontrol <uuid\|vmname> watch [common-options]
5288	</screen>
5289
5290	<para>
5291	Where the parameters are as follows:
5292	</para>
5293
5294	<variablelist>
5295
5296	<varlistentry>
5297	<term>
5298	<computeroutput><uuid\|vmname></computeroutput>
5299	</term>
5300
5301	<listitem>
5302	<para>
5303	Specifies the VM UUID or VM name. Mandatory.
5304	</para>
5305	</listitem>
5306	</varlistentry>
5307
5308	</variablelist>
5309	</listitem>
5310
5311	</itemizedlist>
5312
5313	</sect1>
5314
5315	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
5316
5317	<sect1 id="vboxmanage-metrics">
5318
5319	<title>VBoxManage metrics</title>
5320
5321	<para>
5322	This command supports monitoring the usage of system resources.
5323	Resources are represented by various metrics associated with the
5324	host system or a particular VM. For example, the host system has a
5325	<computeroutput>CPU/Load/User</computeroutput> metric that shows
5326	the percentage of time CPUs spend executing in user mode over a
5327	specific sampling period.
5328	</para>
5329
5330	<para>
5331	Metric data is collected and retained internally. It may be
5332	retrieved at any time with the <command>VBoxManage metrics
5333	query</command> subcommand. The data is available as long as the
5334	background <computeroutput>VBoxSVC</computeroutput> process is
5335	alive. That process terminates shortly after all VMs and frontends
5336	have been closed.
5337	</para>
5338
5339	<para>
5340	By default no metrics are collected at all. Metrics collection
5341	does not start until <command>VBoxManage metrics setup</command>
5342	is invoked with a proper sampling interval and the number of
5343	metrics to be retained. The interval is measured in seconds. For
5344	example, to enable collecting the host processor and memory usage
5345	metrics every second and keeping the five most current samples,
5346	the following command can be used:
5347	</para>
5348
5349	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
5350
5351	<para>
5352	Metric collection can only be enabled for started VMs. Collected
5353	data and collection settings for a particular VM will disappear as
5354	soon as it shuts down. Use the <command>VBoxManage metrics
5355	list</command> subcommand to see which metrics are currently
5356	available. You can also use the <option>--list</option> option
5357	with any subcommand that modifies metric settings to find out
5358	which metrics were affected.
5359	</para>
5360
5361	<para>
5362	Note that the <command>VBoxManage metrics setup</command>
5363	subcommand discards all samples that may have been previously
5364	collected for the specified set of objects and metrics.
5365	</para>
5366
5367	<para>
5368	To enable or disable metrics collection without discarding the
5369	data, <command>VBoxManage metrics enable</command> and
5370	<command>VBoxManage metrics disable</command> subcommands can be
5371	used. Note that these subcommands expect metrics as parameters,
5372	not submetrics such as <computeroutput>CPU/Load</computeroutput>
5373	or <computeroutput>RAM/Usage</computeroutput>. In other words
5374	enabling <computeroutput>CPU/Load/User</computeroutput> while
5375	disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not
5376	supported.
5377	</para>
5378
5379	<para>
5380	The host and VMs have different sets of associated metrics.
5381	Available metrics can be listed with <command>VBoxManage metrics
5382	list</command> subcommand.
5383	</para>
5384
5385	<para>
5386	A complete metric name may include an aggregate function. The name
5387	has the following form:
5388	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
5389	For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
5390	stands for the minimum amount of available memory over all
5391	retained data if applied to the host object.
5392	</para>
5393
5394	<para>
5395	Subcommands may apply to all objects and metrics or can be limited
5396	to one object and a list of metrics. If no objects or metrics are
5397	given in the parameters, the subcommands will apply to all
5398	available metrics of all objects. You may use an asterisk
5399	"<computeroutput>*</computeroutput>" to explicitly specify that
5400	the command should be applied to all objects or metrics. Use
5401	<computeroutput>host</computeroutput> as the object name to limit
5402	the scope of the command to host-related metrics. To limit the
5403	scope to a subset of metrics, use a metric list with names
5404	separated by commas.
5405	</para>
5406
5407	<para>
5408	For example, to query metric data on the CPU time spent in user
5409	and kernel modes by the virtual machine named
5410	<computeroutput>test</computeroutput>, use the following command:
5411	</para>
5412
5413	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
5414
5415	<para>
5416	The following list summarizes the available subcommands:
5417	</para>
5418
5419	<variablelist>
5420
5421	<varlistentry>
5422	<term>
5423	<computeroutput>list</computeroutput>
5424	</term>
5425
5426	<listitem>
5427	<para>
5428	Shows the parameters of the currently existing metrics. Note
5429	that VM-specific metrics are only available when a
5430	particular VM is running.
5431	</para>
5432	</listitem>
5433	</varlistentry>
5434
5435	<varlistentry>
5436	<term>
5437	<computeroutput>setup</computeroutput>
5438	</term>
5439
5440	<listitem>
5441	<para>
5442	Sets the interval between taking two samples of metric data
5443	and the number of samples retained internally. The retained
5444	data is available for displaying with the
5445	<command>query</command> subcommand. The
5446	<computeroutput>--list</computeroutput> option shows which
5447	metrics have been modified as the result of the command
5448	execution.
5449	</para>
5450	</listitem>
5451	</varlistentry>
5452
5453	<varlistentry>
5454	<term>
5455	<computeroutput>enable</computeroutput>
5456	</term>
5457
5458	<listitem>
5459	<para>
5460	Resumes data collection after it has been stopped with the
5461	<command>disable</command> subcommand. Note that specifying
5462	submetrics as parameters will not enable underlying metrics.
5463	Use <computeroutput>--list</computeroutput> to find out if
5464	the command worked as expected.
5465	</para>
5466	</listitem>
5467	</varlistentry>
5468
5469	<varlistentry>
5470	<term>
5471	<computeroutput>disable</computeroutput>
5472	</term>
5473
5474	<listitem>
5475	<para>
5476	Suspends data collection without affecting collection
5477	parameters or collected data. Note that specifying
5478	submetrics as parameters will not disable underlying
5479	metrics. Use <computeroutput>--list</computeroutput> to find
5480	out if the command worked as expected.
5481	</para>
5482	</listitem>
5483	</varlistentry>
5484
5485	<varlistentry>
5486	<term>
5487	<computeroutput>query</computeroutput>
5488	</term>
5489
5490	<listitem>
5491	<para>
5492	Retrieves and displays the currently retained metric data.
5493	</para>
5494
5495	<note>
5496	<para>
5497	The <command>query</command> subcommand does not remove or
5498	flush retained data. If you query often enough you will
5499	see how old samples are gradually being phased out by new
5500	samples.
5501	</para>
5502	</note>
5503	</listitem>
5504	</varlistentry>
5505
5506	<varlistentry>
5507	<term>
5508	<computeroutput>collect</computeroutput>
5509	</term>
5510
5511	<listitem>
5512	<para>
5513	Sets the interval between taking two samples of metric data
5514	and the number of samples retained internally. The collected
5515	data is displayed periodically until Ctrl+C is pressed,
5516	unless the <computeroutput>--detach</computeroutput> option
5517	is specified. With the
5518	<computeroutput>--detach</computeroutput> option, this
5519	subcommand operates the same way as
5520	<computeroutput>setup</computeroutput> does. The
5521	<computeroutput>--list</computeroutput> option shows which
5522	metrics match the specified filter.
5523	</para>
5524	</listitem>
5525	</varlistentry>
5526
5527	</variablelist>
5528
5529	</sect1>
5530
5531	<sect1 id="vboxmanage-natnetwork">
5532
5533	<title>VBoxManage natnetwork</title>
5534
5535	<para>
5536	NAT networks use the Network Address Translation (NAT) service,
5537	which works in a similar way to a home router. It groups systems
5538	using it into a network and prevents outside systems from directly
5539	accessing those inside, while letting systems inside communicate
5540	with each other and outside systems using TCP and UDP over IPv4
5541	and IPv6.
5542	</para>
5543
5544	<para>
5545	A NAT service is attached to an internal network. Virtual machines
5546	to make use of one should be attached to it. The name of an
5547	internal network is chosen when the NAT service is created, and
5548	the internal network will be created if it does not already exist.
5549	The following is an example command to create a NAT network:
5550	</para>
5551
5552	<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
5553
5554	<para>
5555	Here, <computeroutput>natnet1</computeroutput> is the name of the
5556	internal network to be used and
5557	<computeroutput>192.168.15.0/24</computeroutput> is the network
5558	address and mask of the NAT service interface. By default, in this
5559	static configuration the gateway will be assigned the address
5560	192.168.15.1, the address after the interface address, though this
5561	is subject to change.
5562	</para>
5563
5564	<para>
5565	To add a DHCP server to the NAT network after creation, run the
5566	following command:
5567	</para>
5568
5569	<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
5570
5571	<para>
5572	The subcommands for <command>VBoxManage natnetwork</command> are
5573	as follows:
5574	</para>
5575
5576	<screen>VBoxManage natnetwork add --netname <name>
5577	[--network <network>]
5578	[--enable\|--disable]
5579	[--dhcp on\|off]
5580	[--port-forward-4 <rule>]
5581	[--loopback-4 <rule>]
5582	[--ipv6 on\|off]
5583	[--port-forward-6 <rule>]
5584	[--loopback-6 <rule>]
5585	</screen>
5586
5587	<para>
5588	<command>VBoxManage natnetwork add</command>: Creates a new
5589	internal network interface, and adds a NAT network service. This
5590	command is a prerequisite for enabling attachment of VMs to the
5591	NAT network. Parameters are as follows:
5592	</para>
5593
5594	<variablelist>
5595
5596	<varlistentry>
5597	<term>
5598	<computeroutput>--netname <name></computeroutput>
5599	</term>
5600
5601	<listitem>
5602	<para>
5603	Where <name> is the name of the new internal network
5604	interface on the host OS.
5605	</para>
5606	</listitem>
5607	</varlistentry>
5608
5609	<varlistentry>
5610	<term>
5611	<computeroutput>--network <network></computeroutput>
5612	</term>
5613
5614	<listitem>
5615	<para>
5616	Where <network> specifies the static or DHCP network
5617	address and mask of the NAT service interface. The default
5618	is a static network address.
5619	</para>
5620	</listitem>
5621	</varlistentry>
5622
5623	<varlistentry>
5624	<term>
5625	<computeroutput>--enable\|--disable</computeroutput>
5626	</term>
5627
5628	<listitem>
5629	<para>
5630	Enables and disables the NAT network service.
5631	</para>
5632	</listitem>
5633	</varlistentry>
5634
5635	<varlistentry>
5636	<term>
5637	<computeroutput>--dhcp on\|off</computeroutput>
5638	</term>
5639
5640	<listitem>
5641	<para>
5642	Enables and disables a DHCP server specified by
5643	<computeroutput>--netname</computeroutput>. Use of this
5644	option also indicates that it is a DHCP server.
5645	</para>
5646	</listitem>
5647	</varlistentry>
5648
5649	<varlistentry>
5650	<term>
5651	<computeroutput>--port-forward-4 <rule></computeroutput>
5652	</term>
5653
5654	<listitem>
5655	<para>
5656	Enables IPv4 port forwarding, with a rule specified by
5657	<rule>.
5658	</para>
5659	</listitem>
5660	</varlistentry>
5661
5662	<varlistentry>
5663	<term>
5664	<computeroutput>--loopback-4 <rule></computeroutput>
5665	</term>
5666
5667	<listitem>
5668	<para>
5669	Enables the IPv4 loopback interface, with a rule specified
5670	by <rule>.
5671	</para>
5672	</listitem>
5673	</varlistentry>
5674
5675	<varlistentry>
5676	<term>
5677	<computeroutput>--ipv6 on\|off</computeroutput>
5678	</term>
5679
5680	<listitem>
5681	<para>
5682	Enables and disables IPv6. The default setting is IPv4,
5683	disabling IPv6 enables IPv4.
5684	</para>
5685	</listitem>
5686	</varlistentry>
5687
5688	<varlistentry>
5689	<term>
5690	<computeroutput>--port-forward-6 <rule></computeroutput>
5691	</term>
5692
5693	<listitem>
5694	<para>
5695	Enables IPv6 port forwarding, with a rule specified by
5696	<rule>.
5697	</para>
5698	</listitem>
5699	</varlistentry>
5700
5701	<varlistentry>
5702	<term>
5703	<computeroutput>--loopback-6 <rule></computeroutput>
5704	</term>
5705
5706	<listitem>
5707	<para>
5708	Enables the IPv6 loopback interface, with a rule specified
5709	by <rule>.
5710	</para>
5711	</listitem>
5712	</varlistentry>
5713
5714	</variablelist>
5715
5716	<screen>VBoxManage natnetwork remove --netname <name> </screen>
5717
5718	<para>
5719	<command>VBoxManage natnetwork remove</command>: Removes a NAT
5720	network service. Parameters are as follows:
5721	</para>
5722
5723	<variablelist>
5724
5725	<varlistentry>
5726	<term>
5727	<computeroutput>--netname <name></computeroutput>
5728	</term>
5729
5730	<listitem>
5731	<para>
5732	Where <name> specifies an existing NAT network
5733	service. Does not remove any DHCP server enabled on the
5734	network.
5735	</para>
5736	</listitem>
5737	</varlistentry>
5738
5739	</variablelist>
5740
5741	<screen>VBoxManage natnetwork modify --netname <name>
5742	[--network <network>]
5743	[--enable\|--disable]
5744	[--dhcp on\|off]
5745	[--port-forward-4 <rule>]
5746	[--loopback-4 <rule>]
5747	[--ipv6 on\|off]
5748	[--port-forward-6 <rule>]
5749	[--loopback-6 <rule>]
5750	</screen>
5751
5752	<para>
5753	<command>VBoxManage natnetwork modify</command>: Modifies an
5754	existing NAT network service. Parameters are as follows:
5755	</para>
5756
5757	<variablelist>
5758
5759	<varlistentry>
5760	<term>
5761	<computeroutput>--netname <name></computeroutput>
5762	</term>
5763
5764	<listitem>
5765	<para>
5766	Where <name> specifies an existing NAT network
5767	service.
5768	</para>
5769	</listitem>
5770	</varlistentry>
5771
5772	<varlistentry>
5773	<term>
5774	<computeroutput>--network <network></computeroutput>
5775	</term>
5776
5777	<listitem>
5778	<para>
5779	Where <network> specifies the new static or DHCP
5780	network address and mask of the NAT service interface. The
5781	default is a static network address.
5782	</para>
5783	</listitem>
5784	</varlistentry>
5785
5786	<varlistentry>
5787	<term>
5788	<computeroutput>--enable\|--disable</computeroutput>
5789	</term>
5790
5791	<listitem>
5792	<para>
5793	Enables and disables the NAT network service.
5794	</para>
5795	</listitem>
5796	</varlistentry>
5797
5798	<varlistentry>
5799	<term>
5800	<computeroutput>--dhcp on\|off</computeroutput>
5801	</term>
5802
5803	<listitem>
5804	<para>
5805	Enables and disables a DHCP server. If a DHCP server is not
5806	present, using enable adds a new DHCP server.
5807	</para>
5808	</listitem>
5809	</varlistentry>
5810
5811	<varlistentry>
5812	<term>
5813	<computeroutput>--port-forward-4 <rule></computeroutput>
5814	</term>
5815
5816	<listitem>
5817	<para>
5818	Enables IPv4 port forwarding, with a rule specified by
5819	<rule>.
5820	</para>
5821	</listitem>
5822	</varlistentry>
5823
5824	<varlistentry>
5825	<term>
5826	<computeroutput>--loopback-4 <rule></computeroutput>
5827	</term>
5828
5829	<listitem>
5830	<para>
5831	Enables the IPv4 loopback interface, with a rule specified
5832	by <rule>.
5833	</para>
5834	</listitem>
5835	</varlistentry>
5836
5837	<varlistentry>
5838	<term>
5839	<computeroutput>--ipv6 on\|off</computeroutput>
5840	</term>
5841
5842	<listitem>
5843	<para>
5844	Enables and disables IPv6. The default setting is IPv4,
5845	disabling IPv6 enables IPv4.
5846	</para>
5847	</listitem>
5848	</varlistentry>
5849
5850	<varlistentry>
5851	<term>
5852	<computeroutput>--port-forward-6 <rule></computeroutput>
5853	</term>
5854
5855	<listitem>
5856	<para>
5857	Enables IPv6 port forwarding, with a rule specified by
5858	<rule>.
5859	</para>
5860	</listitem>
5861	</varlistentry>
5862
5863	<varlistentry>
5864	<term>
5865	<computeroutput>--loopback-6 <rule></computeroutput>
5866	</term>
5867
5868	<listitem>
5869	<para>
5870	Enables IPv6 loopback interface, with a rule specified by
5871	<rule>.
5872	</para>
5873	</listitem>
5874	</varlistentry>
5875
5876	</variablelist>
5877
5878	<screen>VBoxManage natnetwork start --netname <name>
5879	</screen>
5880
5881	<para>
5882	<command>VBoxManage natnetwork start</command>: Starts the
5883	specified NAT network service and any associated DHCP server.
5884	Parameters are as follows:
5885	</para>
5886
5887	<variablelist>
5888
5889	<varlistentry>
5890	<term>
5891	<computeroutput>--netname <name></computeroutput>
5892	</term>
5893
5894	<listitem>
5895	<para>
5896	Where <name> specifies an existing NAT network
5897	service.
5898	</para>
5899	</listitem>
5900	</varlistentry>
5901
5902	</variablelist>
5903
5904	<screen>VBoxManage natnetwork stop --netname <name>
5905	</screen>
5906
5907	<para>
5908	<command>VBoxManage natnetwork stop</command>: Stops the specified
5909	NAT network service and any DHCP server. Parameters are as
5910	follows:
5911	</para>
5912
5913	<variablelist>
5914
5915	<varlistentry>
5916	<term>
5917	<computeroutput>--netname <name></computeroutput>
5918	</term>
5919
5920	<listitem>
5921	<para>
5922	Where <name> specifies an existing NAT network
5923	service.
5924	</para>
5925	</listitem>
5926	</varlistentry>
5927
5928	</variablelist>
5929
5930	<screen>VBoxManage natnetwork list [<pattern>] </screen>
5931
5932	<para>
5933	<command>VBoxManage natnetwork list</command>: Lists all NAT
5934	network services, with optional filtering. Parameters are as
5935	follows:
5936	</para>
5937
5938	<variablelist>
5939
5940	<varlistentry>
5941	<term>
5942	<computeroutput>[<pattern>]</computeroutput>
5943	</term>
5944
5945	<listitem>
5946	<para>
5947	Where <pattern> is an optional filtering pattern.
5948	</para>
5949	</listitem>
5950	</varlistentry>
5951
5952	</variablelist>
5953
5954	</sect1>
5955
5956	<sect1 id="vboxmanage-hostonlyif">
5957
5958	<title>VBoxManage hostonlyif</title>
5959
5960	<para>
5961	The <command>hostonlyif</command> command enables you to change
5962	the IP configuration of a host-only network interface. For a
5963	description of host-only networking, see
5964	<xref linkend="network_hostonly" />. Each host-only interface is
5965	identified by a name and can either use the internal DHCP server
5966	or a manual IP configuration, both IP4 and IP6.
5967	</para>
5968
5969	<para>
5970	The following list summarizes the available subcommands:
5971	</para>
5972
5973	<variablelist>
5974
5975	<varlistentry>
5976	<term>
5977	<computeroutput>ipconfig "<name>"</computeroutput>
5978	</term>
5979
5980	<listitem>
5981	<para>
5982	Configures a host-only interface.
5983	</para>
5984	</listitem>
5985	</varlistentry>
5986
5987	<varlistentry>
5988	<term>
5989	<computeroutput>create</computeroutput>
5990	</term>
5991
5992	<listitem>
5993	<para>
5994	Creates a new vboxnet<N> interface on the host OS.
5995	This command is essential before you can attach VMs to a
5996	host-only network.
5997	</para>
5998	</listitem>
5999	</varlistentry>
6000
6001	<varlistentry>
6002	<term>
6003	<computeroutput>remove vboxnet<N></computeroutput>
6004	</term>
6005
6006	<listitem>
6007	<para>
6008	Removes a vboxnet<N> interface from the host OS.
6009	</para>
6010	</listitem>
6011	</varlistentry>
6012
6013	</variablelist>
6014
6015	</sect1>
6016
6017	<xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
6018
6019	<sect1 id="vboxmanage-usbdevsource">
6020
6021	<title>VBoxManage usbdevsource</title>
6022
6023	<para>
6024	The <command>usbdevsource</command> commands enable you to add and
6025	remove USB devices globally.
6026	</para>
6027
6028	<para>
6029	The following command adds a USB device.
6030	</para>
6031
6032	<screen>VBoxManage usbdevsource add <source name>
6033	--backend <backend>
6034	--address <address>
6035	</screen>
6036
6037	<para>
6038	Where the command line options are as follows:
6039	</para>
6040
6041	<itemizedlist>
6042
6043	<listitem>
6044	<para>
6045	<computeroutput><source name></computeroutput>:
6046	Specifies the ID of the source USB device to be added.
6047	Mandatory.
6048	</para>
6049	</listitem>
6050
6051	<listitem>
6052	<para>
6053	<computeroutput>--backend <backend></computeroutput>:
6054	Specifies the USB proxy service backend to use. Mandatory.
6055	</para>
6056	</listitem>
6057
6058	<listitem>
6059	<para>
6060	<computeroutput> --address <address></computeroutput>:
6061	Specifies the backend specific address. Mandatory.
6062	</para>
6063	</listitem>
6064
6065	</itemizedlist>
6066
6067	<para>
6068	The following command removes a USB device.
6069	</para>
6070
6071	<screen>VBoxManage usbdevsource remove <source name>
6072	</screen>
6073
6074	<para>
6075	Where the command line options are as follows:
6076	</para>
6077
6078	<itemizedlist>
6079
6080	<listitem>
6081	<para>
6082	<computeroutput><source name></computeroutput>:
6083	Specifies the ID of the source USB device to be removed.
6084	Mandatory.
6085	</para>
6086	</listitem>
6087
6088	</itemizedlist>
6089
6090	</sect1>
6091
6092	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
6093
6094	<xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
6095
6096	<xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
6097
6098	<!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
6099	sect1, so it's not possible to have them "in place" -->
6100
6101	<xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
6102
6103	</chapter>

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

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

Download in other formats: