user_VBoxManage.xml@ 94171

Last change on this file since 94171 was 94171, checked in by vboxsync, 3 years ago
doc/manual,FE/VBoxManage: Convert discardstate command to refentry documentation, bugref:9186
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 155.0 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	<xi:include href="user_man_VBoxManage-startvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
334
335	<xi:include href="user_man_VBoxManage-controlvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
336
337	<xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
338
339	<xi:include href="user_man_VBoxManage-discardstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
340
341	<sect1 id="vboxmanage-adoptstate">
342
343	<title>VBoxManage adoptstate</title>
344
345	<para>
346	If you have a Saved state file (<filename>.sav</filename>) that is
347	separate from the VM configuration, you can use this command to
348	<emphasis>adopt</emphasis> the file. This will change the VM to
349	saved state and when you start it, &product-name; will attempt to
350	restore it from the saved state file you indicated. This command
351	should only be used in special setups.
352	</para>
353
354	</sect1>
355
356	<xi:include href="user_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
357
358	<sect1 id="vboxmanage-closemedium">
359
360	<title>VBoxManage closemedium</title>
361
362	<para>
363	This command removes a hard disk, DVD, or floppy image from a
364	&product-name; media registry.
365	</para>
366
367	<screen>VBoxManage closemedium [disk\|dvd\|floppy] <uuid\|filename>
368	[--delete]</screen>
369
370	<para>
371	Optionally, you can request that the image be deleted. You will
372	get appropriate diagnostics that the deletion failed, however the
373	image will become unregistered in any case.
374	</para>
375
376	</sect1>
377
378	<sect1 id="vboxmanage-storageattach">
379
380	<title>VBoxManage storageattach</title>
381
382	<para>
383	This command attaches, modifies, and removes a storage medium
384	connected to a storage controller that was previously added with
385	the <command>storagectl</command> command. The syntax is as
386	follows:
387	</para>
388
389	<screen>VBoxManage storageattach <uuid\|vmname>
390	--storagectl <name>
391	[--port <number>]
392	[--device <number>]
393	[--type dvddrive\|hdd\|fdd]
394	[--medium none\|emptydrive\|additions\|
395	<uuid>\|<filename>\|host:<drive>\|iscsi]
396	[--mtype normal\|writethrough\|immutable\|shareable
397	readonly\|multiattach]
398	[--comment <text>]
399	[--setuuid <uuid>]
400	[--setparentuuid <uuid>]
401	[--passthrough on\|off]
402	[--tempeject on\|off]
403	[--nonrotational on\|off]
404	[--discard on\|off]
405	[--hotpluggable on\|off]
406	[--bandwidthgroup name\|none]
407	[--forceunmount]
408	[--server <name>\|<ip>]
409	[--target <target>]
410	[--tport <port>]
411	[--lun <lun>]
412	[--encodedlun <lun>]
413	[--username <username>]
414	[--password <password>]
415	[--passwordfile <file>]
416	[--initiator <initiator>]
417	[--intnet]</screen>
418
419	<para>
420	A number of parameters are commonly required. Some parameters are
421	required only for iSCSI targets.
422	</para>
423
424	<para>
425	The common parameters are as follows:
426	</para>
427
428	<variablelist>
429
430	<varlistentry>
431	<term>
432	<computeroutput>uuid\|vmname</computeroutput>
433	</term>
434
435	<listitem>
436	<para>
437	The VM UUID or VM Name. Mandatory.
438	</para>
439	</listitem>
440	</varlistentry>
441
442	<varlistentry>
443	<term>
444	<computeroutput>--storagectl</computeroutput>
445	</term>
446
447	<listitem>
448	<para>
449	Name of the storage controller. Mandatory. The list of the
450	storage controllers currently attached to a VM can be
451	obtained with <command>VBoxManage showvminfo</command>. See
452	<xref linkend="vboxmanage-showvminfo" />.
453	</para>
454	</listitem>
455	</varlistentry>
456
457	<varlistentry>
458	<term>
459	<computeroutput>--port</computeroutput>
460	</term>
461
462	<listitem>
463	<para>
464	The number of the storage controller's port which is to be
465	modified. Mandatory, unless the storage controller has only
466	a single port.
467	</para>
468	</listitem>
469	</varlistentry>
470
471	<varlistentry>
472	<term>
473	<computeroutput>--device</computeroutput>
474	</term>
475
476	<listitem>
477	<para>
478	The number of the port's device which is to be modified.
479	Mandatory, unless the storage controller has only a single
480	device per port.
481	</para>
482	</listitem>
483	</varlistentry>
484
485	<varlistentry>
486	<term>
487	<computeroutput>--type</computeroutput>
488	</term>
489
490	<listitem>
491	<para>
492	Define the type of the drive to which the medium is being
493	attached, detached, or modified. This argument can only be
494	omitted if the type of medium can be determined from either
495	the medium given with the
496	<computeroutput>--medium</computeroutput> argument or from a
497	previous medium attachment.
498	</para>
499	</listitem>
500	</varlistentry>
501
502	<varlistentry>
503	<term>
504	<computeroutput>--medium</computeroutput>
505	</term>
506
507	<listitem>
508	<para>
509	Specifies what is to be attached. The following values are
510	supported:
511	</para>
512
513	<itemizedlist>
514
515	<listitem>
516	<para>
517	<computeroutput>none</computeroutput>: Any existing
518	device should be removed from the given slot.
519	</para>
520	</listitem>
521
522	<listitem>
523	<para>
524	<computeroutput>emptydrive</computeroutput>: For a
525	virtual DVD or floppy drive only, this makes the device
526	slot behave like a removeable drive into which no media
527	has been inserted.
528	</para>
529	</listitem>
530
531	<listitem>
532	<para>
533	<computeroutput>additions</computeroutput>: For a
534	virtual DVD drive only, this attaches the
535	<emphasis>VirtualBox Guest Additions</emphasis> image to
536	the given device slot.
537	</para>
538	</listitem>
539
540	<listitem>
541	<para>
542	If a UUID is specified, it must be the UUID of a storage
543	medium that is already known to &product-name;. For
544	example, because it has been attached to another virtual
545	machine. See <xref linkend="vboxmanage-list" /> for
546	details of how to list known media. This medium is then
547	attached to the given device slot.
548	</para>
549	</listitem>
550
551	<listitem>
552	<para>
553	If a filename is specified, it must be the full path of
554	an existing disk image in ISO, RAW, VDI, VMDK, or other
555	format. The disk image is then attached to the given
556	device slot.
557	</para>
558	</listitem>
559
560	<listitem>
561	<para>
562	<computeroutput>host:<drive></computeroutput>: For
563	a virtual DVD or floppy drive only, this connects the
564	given device slot to the specified DVD or floppy drive
565	on the host computer.
566	</para>
567	</listitem>
568
569	<listitem>
570	<para>
571	<computeroutput>iscsi</computeroutput>: For virtual hard
572	disks only, this is used for specifying an iSCSI target.
573	In this case, additional parameters must be given. These
574	are described below.
575	</para>
576	</listitem>
577
578	</itemizedlist>
579
580	<para>
581	Some of the above changes, in particular for removeable
582	media such as floppies and CDs/DVDs, can be effected while a
583	VM is running. Others, such as device changes or changes in
584	hard disk device slots, require the VM to be powered off.
585	</para>
586	</listitem>
587	</varlistentry>
588
589	<varlistentry>
590	<term>
591	<computeroutput>--mtype</computeroutput>
592	</term>
593
594	<listitem>
595	<para>
596	Defines how this medium behaves with respect to snapshots
597	and write operations. See <xref linkend="hdimagewrites" />.
598	</para>
599	</listitem>
600	</varlistentry>
601
602	<varlistentry>
603	<term>
604	<computeroutput>--comment</computeroutput>
605	</term>
606
607	<listitem>
608	<para>
609	An optional description that you want to have stored with
610	this medium. For example, for an iSCSI target, "Big storage
611	server downstairs". This is purely descriptive and not
612	needed for the medium to function correctly.
613	</para>
614	</listitem>
615	</varlistentry>
616
617	<varlistentry>
618	<term>
619	<computeroutput>--setuuid, --setparentuuid</computeroutput>
620	</term>
621
622	<listitem>
623	<para>
624	Modifies the UUID or parent UUID of a medium before
625	attaching it to a VM. This is an expert option.
626	Inappropriate use can make the medium unusable or lead to
627	broken VM configurations if any other VM is referring to the
628	same media already. The most frequently used variant is
629	<computeroutput>--setuuid ""</computeroutput>, which assigns
630	a new random UUID to an image. This option is useful for
631	resolving duplicate UUID errors if you duplicated an image
632	using a file copy utility.
633	</para>
634	</listitem>
635	</varlistentry>
636
637	<varlistentry>
638	<term>
639	<computeroutput>--passthrough</computeroutput>
640	</term>
641
642	<listitem>
643	<para>
644	For a virtual DVD drive only, you can enable DVD writing
645	support. This feature is currently experimental, see
646	<xref
647	linkend="storage-cds" />.
648	</para>
649	</listitem>
650	</varlistentry>
651
652	<varlistentry>
653	<term>
654	<computeroutput>--tempeject</computeroutput>
655	</term>
656
657	<listitem>
658	<para>
659	For a virtual DVD drive only, you can configure the behavior
660	for guest-triggered medium eject. If this is set to on, the
661	eject has only a temporary effect. If the VM is powered off
662	and restarted the originally configured medium will be still
663	in the drive.
664	</para>
665	</listitem>
666	</varlistentry>
667
668	<varlistentry>
669	<term>
670	<computeroutput>--nonrotational</computeroutput>
671	</term>
672
673	<listitem>
674	<para>
675	Enables you to enable the non-rotational flag for virtual
676	hard disks. Some guests, such as Windows 7 or later, treat
677	such disks like SSDs and do not perform disk fragmentation
678	on such media.
679	</para>
680	</listitem>
681	</varlistentry>
682
683	<varlistentry>
684	<term>
685	<computeroutput>--discard</computeroutput>
686	</term>
687
688	<listitem>
689	<para>
690	Enables the auto-discard feature for a virtual hard disks.
691	This specifies that a VDI image will be shrunk in response
692	to the trim command from the guest OS. The following
693	requirements must be met:
694	</para>
695
696	<itemizedlist>
697
698	<listitem>
699	<para>
700	The disk format must be VDI.
701	</para>
702	</listitem>
703
704	<listitem>
705	<para>
706	The size of the cleared area must be at least 1 MB.
707	</para>
708	</listitem>
709
710	<listitem>
711	<para>
712	&product-name; will only trim whole 1 MB blocks. The
713	VDIs themselves are organized into 1 MB blocks, so this
714	will only work if the space being trimmed is at least a
715	1 MB contiguous block at a 1 MB boundary. On Windows,
716	occasional defragmentation with <command>defrag.exe
717	/D</command>, or on Linux running <command>btrfs
718	filesystem defrag</command> as a background cron job may
719	be beneficial.
720	</para>
721	</listitem>
722
723	</itemizedlist>
724
725	<note>
726	<para>
727	The Guest OS must be configured to issue the
728	<command>trim</command> command, and typically this means
729	that the guest OS is made to see the disk as an SSD. Ext4
730	supports the -o discard mount flag. Mac OS X probably
731	requires additional settings. Windows should automatically
732	detect and support SSDs, at least in versions 7, 8, and
733	10. The Linux exFAT driver from Samsung supports the
734	<command>trim</command> command.
735	</para>
736	</note>
737
738	<para>
739	It is unclear whether Microsoft's implementation of exFAT
740	supports this feature, even though that file system was
741	originally designed for flash.
742	</para>
743
744	<para>
745	Alternatively, there are other methods to issue trim. For
746	example, the Linux <command>fstrim</command> command, part
747	of the util-linux package. Earlier solutions required a user
748	to zero out unused areas, using zerofree or similar, and to
749	compact the disk. This is only possible when the VM is
750	offline.
751	</para>
752	</listitem>
753	</varlistentry>
754
755	<varlistentry>
756	<term>
757	<computeroutput>--bandwidthgroup</computeroutput>
758	</term>
759
760	<listitem>
761	<para>
762	Sets the bandwidth group to use for the given device. See
763	<xref linkend="storage-bandwidth-limit" />.
764	</para>
765	</listitem>
766	</varlistentry>
767
768	<varlistentry>
769	<term>
770	<computeroutput>--forceunmount</computeroutput>
771	</term>
772
773	<listitem>
774	<para>
775	For a virtual DVD or floppy drive only, this forcibly
776	unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy
777	even if the previous one is locked down by the guest for
778	reading. See <xref linkend="storage-cds" />.
779	</para>
780	</listitem>
781	</varlistentry>
782
783	</variablelist>
784
785	<para>
786	When <computeroutput>iscsi</computeroutput> is used with the
787	<computeroutput>--medium</computeroutput> parameter for iSCSI
788	support, additional parameters must or can be used. See also
789	<xref linkend="storage-iscsi" />.
790	</para>
791
792	<variablelist>
793
794	<varlistentry>
795	<term>
796	<computeroutput>--server</computeroutput>
797	</term>
798
799	<listitem>
800	<para>
801	The host name or IP address of the iSCSI target. Required.
802	</para>
803	</listitem>
804	</varlistentry>
805
806	<varlistentry>
807	<term>
808	<computeroutput>--target</computeroutput>
809	</term>
810
811	<listitem>
812	<para>
813	Target name string. This is determined by the iSCSI target
814	and used to identify the storage resource. Required.
815	</para>
816	</listitem>
817	</varlistentry>
818
819	<varlistentry>
820	<term>
821	<computeroutput>--tport</computeroutput>
822	</term>
823
824	<listitem>
825	<para>
826	TCP/IP port number of the iSCSI service on the target.
827	Optional.
828	</para>
829	</listitem>
830	</varlistentry>
831
832	<varlistentry>
833	<term>
834	<computeroutput>--lun</computeroutput>
835	</term>
836
837	<listitem>
838	<para>
839	Logical Unit Number of the target resource. Optional. Often,
840	this value is zero.
841	</para>
842	</listitem>
843	</varlistentry>
844
845	<varlistentry>
846	<term>
847	<computeroutput>--encodedlun</computeroutput>
848	</term>
849
850	<listitem>
851	<para>
852	Hex-encoded Logical Unit Number of the target resource.
853	Optional. Often, this value is zero.
854	</para>
855	</listitem>
856	</varlistentry>
857
858	<varlistentry>
859	<term>
860	<computeroutput>--username, --password,
861	--passwordfile</computeroutput>
862	</term>
863
864	<listitem>
865	<para>
866	Username and password, called the initiator secret, for
867	target authentication, if required. Optional.
868	</para>
869
870	<note>
871	<para>
872	Username and password are stored without encryption, in
873	clear text, in the XML machine configuration file if no
874	settings password is provided. When a settings password is
875	specified for the first time, the password is stored in
876	encrypted form. As an alternative to providing the
877	password on the command line, a reference to a file
878	containing the text can be provided using the
879	<computeroutput>passwordfile</computeroutput> option.
880	</para>
881	</note>
882	</listitem>
883	</varlistentry>
884
885	<varlistentry>
886	<term>
887	<computeroutput>--initiator</computeroutput>
888	</term>
889
890	<listitem>
891	<para>
892	iSCSI Initiator. Optional.
893	</para>
894
895	<para>
896	Microsoft iSCSI Initiator is a system, such as a server that
897	attaches to an IP network and initiates requests and
898	receives responses from an iSCSI target. The SAN components
899	in Microsoft iSCSI Initiator are largely analogous to Fibre
900	Channel SAN components, and they include the following:
901	</para>
902
903	<itemizedlist>
904
905	<listitem>
906	<para>
907	To transport blocks of iSCSI commands over the IP
908	network, an iSCSI driver must be installed on the iSCSI
909	host. An iSCSI driver is included with Microsoft iSCSI
910	Initiator.
911	</para>
912	</listitem>
913
914	<listitem>
915	<para>
916	A gigabit Ethernet adapter that transmits 1000 megabits
917	per second (Mbps) is recommended for the connection to
918	an iSCSI target. Like standard 10/100 adapters, most
919	gigabit adapters use a preexisting Category 5 or
920	Category 6E cable. Each port on the adapter is
921	identified by a unique IP address.
922	</para>
923	</listitem>
924
925	<listitem>
926	<para>
927	An iSCSI target is any device that receives iSCSI
928	commands. The device can be an end node, such as a
929	storage device, or it can be an intermediate device,
930	such as a network bridge between IP and Fibre Channel
931	devices. Each port on the storage array controller or
932	network bridge is identified by one or more IP addresses
933	</para>
934	</listitem>
935
936	</itemizedlist>
937	</listitem>
938	</varlistentry>
939
940	<varlistentry>
941	<term>
942	<computeroutput>--intnet</computeroutput>
943	</term>
944
945	<listitem>
946	<para>
947	If specified, connect to the iSCSI target using Internal
948	Networking. This needs further configuration, see
949	<xref linkend="iscsi-intnet" />.
950	</para>
951	</listitem>
952	</varlistentry>
953
954	</variablelist>
955
956	</sect1>
957
958	<sect1 id="vboxmanage-storagectl">
959
960	<title>VBoxManage storagectl</title>
961
962	<para>
963	This command attaches, modifies, and removes a storage controller.
964	After this, virtual media can be attached to the controller with
965	the <command>storageattach</command> command.
966	</para>
967
968	<para>
969	The syntax for this command is as follows:
970	</para>
971
972	<screen>VBoxManage storagectl <uuid\|vmname>
973	--name <name>
974	[--add ide\|sata\|scsi\|floppy\|sas\|usb\|pcie]
975	[--controller LSILogic\|LSILogicSAS\|BusLogic\|
976	IntelAhci\|PIIX3\|PIIX4\|ICH6\|I82078\|
977	USB\|NVMe\|VirtIO]
978	[--portcount <1-30>]
979	[--hostiocache on\|off]
980	[--bootable on\|off]
981	[--rename <name>]
982	[--remove]</screen>
983
984	<para>
985	The parameters are as follows:
986	</para>
987
988	<variablelist>
989
990	<varlistentry>
991	<term>
992	<computeroutput>uuid\|vmname</computeroutput>
993	</term>
994
995	<listitem>
996	<para>
997	The VM UUID or VM Name. Mandatory.
998	</para>
999	</listitem>
1000	</varlistentry>
1001
1002	<varlistentry>
1003	<term>
1004	<computeroutput>--name</computeroutput>
1005	</term>
1006
1007	<listitem>
1008	<para>
1009	Specifies the name of the storage controller. Mandatory.
1010	</para>
1011	</listitem>
1012	</varlistentry>
1013
1014	<varlistentry>
1015	<term>
1016	<computeroutput>--add</computeroutput>
1017	</term>
1018
1019	<listitem>
1020	<para>
1021	Specifies the type of the system bus to which the storage
1022	controller must be connected.
1023	</para>
1024	</listitem>
1025	</varlistentry>
1026
1027	<varlistentry>
1028	<term>
1029	<computeroutput>--controller</computeroutput>
1030	</term>
1031
1032	<listitem>
1033	<para>
1034	Enables a choice of chipset type being emulated for the
1035	given storage controller.
1036	</para>
1037	</listitem>
1038	</varlistentry>
1039
1040	<varlistentry>
1041	<term>
1042	<computeroutput>--portcount</computeroutput>
1043	</term>
1044
1045	<listitem>
1046	<para>
1047	This specifies the number of ports the storage controller
1048	should support.
1049	</para>
1050	</listitem>
1051	</varlistentry>
1052
1053	<varlistentry>
1054	<term>
1055	<computeroutput>--hostiocache</computeroutput>
1056	</term>
1057
1058	<listitem>
1059	<para>
1060	Configures the use of the host I/O cache for all disk images
1061	attached to this storage controller. See
1062	<xref
1063	linkend="iocaching" />.
1064	</para>
1065	</listitem>
1066	</varlistentry>
1067
1068	<varlistentry>
1069	<term>
1070	<computeroutput>--bootable</computeroutput>
1071	</term>
1072
1073	<listitem>
1074	<para>
1075	Specifies whether this controller is bootable.
1076	</para>
1077	</listitem>
1078	</varlistentry>
1079
1080	<varlistentry>
1081	<term>
1082	<computeroutput>--rename</computeroutput>
1083	</term>
1084
1085	<listitem>
1086	<para>
1087	Specifies a new name for the storage controller.
1088	</para>
1089	</listitem>
1090	</varlistentry>
1091
1092	<varlistentry>
1093	<term>
1094	<computeroutput>--remove</computeroutput>
1095	</term>
1096
1097	<listitem>
1098	<para>
1099	Removes the storage controller from the VM configuration.
1100	</para>
1101	</listitem>
1102	</varlistentry>
1103
1104	</variablelist>
1105
1106	</sect1>
1107
1108	<sect1 id="vboxmanage-bandwidthctl">
1109
1110	<title>VBoxManage bandwidthctl</title>
1111
1112	<para>
1113	This command creates, deletes, modifies, and shows bandwidth
1114	groups of the given virtual machine.
1115	</para>
1116
1117	<screen>VBoxManage bandwidthctl <uuid\|vmname>
1118	add <name> --type disk\|network --limit <MBps>[k\|m\|g\|K\|M\|G] \|
1119	set <name> --limit <MBps>[k\|m\|g\|K\|M\|G] \|
1120	remove <name> \|
1121	list [--machinereadable]</screen>
1122
1123	<para>
1124	The following subcommands are available:
1125	</para>
1126
1127	<itemizedlist>
1128
1129	<listitem>
1130	<para>
1131	<command>add</command>: Creates a new bandwidth group of a
1132	given type.
1133	</para>
1134	</listitem>
1135
1136	<listitem>
1137	<para>
1138	<command>set</command>: Modifies the limit for an existing
1139	bandwidth group.
1140	</para>
1141	</listitem>
1142
1143	<listitem>
1144	<para>
1145	<command>remove</command>: Deletes a bandwidth group.
1146	</para>
1147	</listitem>
1148
1149	<listitem>
1150	<para>
1151	<command>list</command>: Shows all bandwidth groups defined
1152	for the given VM. Use the
1153	<computeroutput>--machinereadable</computeroutput> option to
1154	produce the same output, but in machine readable format. This
1155	is of the form: name="value" on a line by line basis.
1156	</para>
1157	</listitem>
1158
1159	</itemizedlist>
1160
1161	<para>
1162	The parameters are as follows:
1163	</para>
1164
1165	<variablelist>
1166
1167	<varlistentry>
1168	<term>
1169	<computeroutput>uuid\|vmname</computeroutput>
1170	</term>
1171
1172	<listitem>
1173	<para>
1174	The VM UUID or VM Name. Mandatory.
1175	</para>
1176	</listitem>
1177	</varlistentry>
1178
1179	<varlistentry>
1180	<term>
1181	<computeroutput>--name</computeroutput>
1182	</term>
1183
1184	<listitem>
1185	<para>
1186	Name of the bandwidth group. Mandatory.
1187	</para>
1188	</listitem>
1189	</varlistentry>
1190
1191	<varlistentry>
1192	<term>
1193	<computeroutput>--type</computeroutput>
1194	</term>
1195
1196	<listitem>
1197	<para>
1198	Type of the bandwidth group. Mandatory. Two types are
1199	supported: <computeroutput>disk</computeroutput> and
1200	<computeroutput>network</computeroutput>. See
1201	<xref linkend="storage-bandwidth-limit" /> or
1202	<xref linkend="network_bandwidth_limit" /> for the
1203	description of a particular type.
1204	</para>
1205	</listitem>
1206	</varlistentry>
1207
1208	<varlistentry>
1209	<term>
1210	<computeroutput>--limit</computeroutput>
1211	</term>
1212
1213	<listitem>
1214	<para>
1215	Specifies the limit for the given bandwidth group. This can
1216	be changed while the VM is running. The default unit is
1217	megabytes per second. The unit can be changed by specifying
1218	one of the following suffixes:
1219	<computeroutput>k</computeroutput> for kilobits per second,
1220	<computeroutput>m</computeroutput> for megabits per second,
1221	<computeroutput>g</computeroutput> for gigabits per second,
1222	<computeroutput>K</computeroutput> for kilobytes per second,
1223	<computeroutput>M</computeroutput> for megabytes per second,
1224	<computeroutput>G</computeroutput> for gigabytes per second.
1225	</para>
1226	</listitem>
1227	</varlistentry>
1228
1229	</variablelist>
1230
1231	<note>
1232	<para>
1233	The network bandwidth limits apply only to the traffic being
1234	sent by virtual machines. The traffic being received by VMs is
1235	unlimited.
1236	</para>
1237	</note>
1238
1239	<note>
1240	<para>
1241	To remove a bandwidth group it must not be referenced by any
1242	disks or adapters in the running VM.
1243	</para>
1244	</note>
1245
1246	</sect1>
1247
1248	<sect1 id="vboxmanage-showmediuminfo">
1249
1250	<title>VBoxManage showmediuminfo</title>
1251
1252	<para>
1253	This command shows information about a medium, notably its size,
1254	its size on disk, its type, and the virtual machines which use it.
1255	</para>
1256
1257	<note>
1258	<para>
1259	For compatibility with earlier versions of &product-name;, the
1260	<command>showvdiinfo</command> command is also supported and
1261	mapped internally to the <command>showmediuminfo</command>
1262	command.
1263	</para>
1264	</note>
1265
1266	<screen>VBoxManage showmediuminfo [disk\|dvd\|floppy] <uuid\|filename></screen>
1267
1268	<para>
1269	The medium must be specified either by its UUID, if the medium is
1270	registered, or by its filename. Registered images can be listed
1271	using <command>VBoxManage list hdds</command>, <command>VBoxManage
1272	list dvds</command>, or <command>VBoxManage list
1273	floppies</command>, as appropriate. See
1274	<xref linkend="vboxmanage-list" />.
1275	</para>
1276
1277	</sect1>
1278
1279	<sect1 id="vboxmanage-createmedium">
1280
1281	<title>VBoxManage createmedium</title>
1282
1283	<para>
1284	This command creates a new medium. The syntax is as follows:
1285	</para>
1286
1287	<screen>VBoxManage createmedium [disk\|dvd\|floppy] --filename <filename>
1288	[--size <megabytes>\|--sizebyte <bytes>]
1289	[--diffparent <uuid>\|<filename>
1290	[--format VDI\|VMDK\|VHD] (default: VDI)
1291	[--variant Standard,Fixed,Split2G,Stream,ESX,RawDisk]
1292	[[--property <name>=<value>]
1293	--property <name>=<value>]...
1294	[[--property-file <name>=</path/to/file/with/value>]
1295	--property-file <name>=</path/to/file/with/value>]...</screen>
1296
1297	<para>
1298	The parameters are as follows:
1299	</para>
1300
1301	<variablelist>
1302
1303	<varlistentry>
1304	<term>
1305	<computeroutput>--filename <filename></computeroutput>
1306	</term>
1307
1308	<listitem>
1309	<para>
1310	Specifies a file name <filename> as an absolute path
1311	on the host file system. Mandatory.
1312	</para>
1313	</listitem>
1314	</varlistentry>
1315
1316	<varlistentry>
1317	<term>
1318	<computeroutput>--size <megabytes></computeroutput>
1319	</term>
1320
1321	<listitem>
1322	<para>
1323	Specifies the image capacity, in 1 MB units. Optional.
1324	</para>
1325	</listitem>
1326	</varlistentry>
1327
1328	<varlistentry>
1329	<term>
1330	<computeroutput>--diffparent
1331	<uuid>\|<filename></computeroutput>
1332	</term>
1333
1334	<listitem>
1335	<para>
1336	Specifies the differencing image parent, either as a UUID or
1337	by the absolute pathname of the file on the host file
1338	system. Useful for sharing a base box disk image among
1339	several VMs.
1340	</para>
1341	</listitem>
1342	</varlistentry>
1343
1344	<varlistentry>
1345	<term>
1346	<computeroutput>--format VDI\|VMDK\|VHD</computeroutput>
1347	</term>
1348
1349	<listitem>
1350	<para>
1351	Specifies the file format for the output file. Available
1352	options are VDI, VMDK, VHD. The default format is VDI.
1353	Optional.
1354	</para>
1355	</listitem>
1356	</varlistentry>
1357
1358	<varlistentry>
1359	<term>
1360	<computeroutput>--variant</computeroutput>
1361	</term>
1362
1363	<listitem>
1364	<para>
1365	Specifies any required file format variants for the output
1366	file. This is a comma-separated list of variant flags.
1367	Options are Standard,Fixed,Split2G,Stream,ESX,RawDisk. Not all
1368	combinations are supported, and specifying mutually
1369	incompatible flags results in an error message. Optional.
1370	</para>
1371	</listitem>
1372	</varlistentry>
1373
1374	<varlistentry>
1375	<term>
1376	<computeroutput>--property <name>=<value></computeroutput>
1377	</term>
1378
1379	<listitem>
1380	<para>
1381	Specifies any required file format dependent parameters in
1382	<literal>key=value</literal> form. Optional.
1383	</para>
1384	</listitem>
1385	</varlistentry>
1386
1387	<varlistentry>
1388	<term>
1389	<computeroutput>--property-file <name>=</path/to/file/with/value></computeroutput>
1390	</term>
1391
1392	<listitem>
1393	<para>
1394	Specifies any required file format dependent parameters in
1395	<literal>key=file/with/value</literal> form. The value is
1396	taken from the file. Optional.
1397	</para>
1398	</listitem>
1399	</varlistentry>
1400
1401	</variablelist>
1402
1403	<note>
1404	<para>
1405	For compatibility with earlier versions of &product-name;, the
1406	<command>createvdi</command> and <command>createhd</command>
1407	commands are also supported and mapped internally to the
1408	<command>createmedium</command> command.
1409	</para>
1410	</note>
1411
1412	</sect1>
1413
1414	<sect1 id="vboxmanage-modifymedium">
1415
1416	<title>VBoxManage modifymedium</title>
1417
1418	<para>
1419	With the <command>modifymedium</command> command, you can change
1420	the characteristics of a disk image after it has been created.
1421	</para>
1422
1423	<screen>VBoxManage modifymedium [disk\|dvd\|floppy] <uuid\|filename>
1424	[--type normal\|writethrough\|immutable\|shareable\|
1425	readonly\|multiattach]
1426	[--autoreset on\|off]
1427	[--property <name=[value]>]
1428	[--compact]
1429	[--resize <megabytes>\|--resizebyte <bytes>]
1430	[--move <path>]
1431	[--setlocation <path>]</screen>
1432
1433	<note>
1434	<para>
1435	For compatibility with earlier versions of &product-name;, the
1436	<command>modifyvdi</command> and <command>modifyhd</command>
1437	commands are also supported and mapped internally to the
1438	<command>modifymedium</command> command.
1439	</para>
1440	</note>
1441
1442	<para>
1443	The disk image to modify must be specified either by its UUID, if
1444	the medium is registered, or by its filename. Registered images
1445	can be listed using <command>VBoxManage list hdds</command>, see
1446	<xref linkend="vboxmanage-list" />. A filename must be specified
1447	as a valid path, either as an absolute path or as a relative path
1448	starting from the current directory.
1449	</para>
1450
1451	<para>
1452	The following options are available:
1453	</para>
1454
1455	<itemizedlist>
1456
1457	<listitem>
1458	<para>
1459	With the <computeroutput>--type</computeroutput> argument, you
1460	can change the type of an existing image between the normal,
1461	immutable, write-through and other modes. See
1462	<xref
1463	linkend="hdimagewrites" />.
1464	</para>
1465	</listitem>
1466
1467	<listitem>
1468	<para>
1469	For immutable hard disks only, the <computeroutput>--autoreset
1470	on\|off</computeroutput> option determines whether the disk is
1471	automatically reset on every VM startup. See
1472	<xref linkend="hdimagewrites" />. By default, autoreset is on.
1473	</para>
1474	</listitem>
1475
1476	<listitem>
1477	<para>
1478	The <computeroutput>--compact</computeroutput> option can be
1479	used to compact disk images. Compacting removes blocks that
1480	only contains zeroes. Using this option will shrink a
1481	dynamically allocated image. It will reduce the
1482	<emphasis>physical</emphasis> size of the image without
1483	affecting the logical size of the virtual disk. Compaction
1484	works both for base images and for differencing images created
1485	as part of a snapshot.
1486	</para>
1487
1488	<para>
1489	For this operation to be effective, it is required that free
1490	space in the guest system first be zeroed out using a suitable
1491	software tool. For Windows guests, you can use the
1492	<command>sdelete</command> tool provided by Microsoft. Run
1493	<command>sdelete -z</command> in the guest to zero the free
1494	disk space, before compressing the virtual disk image. For
1495	Linux, use the <command>zerofree</command> utility which
1496	supports ext2/ext3 filesystems. For Mac OS X guests, use the
1497	<computeroutput>diskutil secureErase freespace 0
1498	/</computeroutput> command from an elevated Terminal.
1499	</para>
1500
1501	<para>
1502	Please note that compacting is currently only available for
1503	VDI images. A similar effect can be achieved by zeroing out
1504	free blocks and then cloning the disk to any other dynamically
1505	allocated format. You can use this workaround until compacting
1506	is also supported for disk formats other than VDI.
1507	</para>
1508	</listitem>
1509
1510	<listitem>
1511	<para>
1512	The <computeroutput>--resize x</computeroutput> option, where
1513	x is the desired new total space in megabytes enables you to
1514	change the capacity of an existing image. This adjusts the
1515	<emphasis>logical</emphasis> size of a virtual disk without
1516	affecting the physical size much.
1517	</para>
1518
1519	<para>
1520	This option currently works only for VDI and VHD formats, and
1521	only for the dynamically allocated variants. It can only be
1522	used to expand, but not shrink, the capacity. For example, if
1523	you originally created a 10 GB disk which is now full, you can
1524	use the <computeroutput>--resize 15360</computeroutput>
1525	command to change the capacity to 15 GB (15,360 MB) without
1526	having to create a new image and copy all data from within a
1527	virtual machine. Note however that this only changes the drive
1528	capacity. You will typically next need to use a partition
1529	management tool inside the guest to adjust the main partition
1530	to fill the drive.
1531	</para>
1532
1533	<para>
1534	The <computeroutput>--resizebyte x</computeroutput> option
1535	does almost the same thing, except that x is expressed in
1536	bytes instead of megabytes.
1537	</para>
1538	</listitem>
1539
1540	<listitem>
1541	<para>
1542	The <computeroutput>--move <path></computeroutput>
1543	option can be used to relocate a medium to a different
1544	location <path> on the host file system. The path can be
1545	either relative to the current directory or absolute.
1546	</para>
1547	</listitem>
1548
1549	<listitem>
1550	<para>
1551	The <computeroutput>--setlocation
1552	<path></computeroutput> option can be used to set the
1553	new location <path> of the medium on the host file
1554	system if the medium has been moved for any reasons. The path
1555	can be either relative to the current directory or absolute.
1556	</para>
1557
1558	<note>
1559	<para>
1560	The new location is used as is, without any sanity checks.
1561	The user is responsible for setting the correct path.
1562	</para>
1563	</note>
1564	</listitem>
1565
1566	</itemizedlist>
1567
1568	</sect1>
1569
1570	<sect1 id="vboxmanage-clonemedium">
1571
1572	<title>VBoxManage clonemedium</title>
1573
1574	<para>
1575	This command duplicates a virtual disk, DVD, or floppy medium to a
1576	new medium, usually an image file, with a new unique identifier
1577	(UUID). The new image can be transferred to another host system or
1578	reimported into &product-name; using the Virtual Media Manager.
1579	See <xref linkend="vdis" /> and <xref linkend="cloningvdis" />.
1580	The syntax is as follows:
1581	</para>
1582
1583	<screen>VBoxManage clonemedium [disk\|dvd\|floppy] <uuid\|inputfile> <uuid\|outputfile>
1584
1585	[--format VDI\|VMDK\|VHD\|RAW\|<other>]
1586	[--variant Standard,Fixed,Split2G,Stream,ESX]
1587	[--existing]</screen>
1588
1589	<para>
1590	The medium to clone as well as the target image must be described
1591	either by its UUIDs, if the mediums are registered, or by its
1592	filename. Registered images can be listed by <command>VBoxManage
1593	list hdds</command>. See <xref linkend="vboxmanage-list" />. A
1594	filename must be specified as valid path, either as an absolute
1595	path or as a relative path starting from the current directory.
1596	</para>
1597
1598	<para>
1599	The following options are available:
1600	</para>
1601
1602	<variablelist>
1603
1604	<varlistentry>
1605	<term>
1606	<computeroutput>--format</computeroutput>
1607	</term>
1608
1609	<listitem>
1610	<para>
1611	Set a file format for the output file different from the
1612	file format of the input file.
1613	</para>
1614	</listitem>
1615	</varlistentry>
1616
1617	<varlistentry>
1618	<term>
1619	<computeroutput>--variant</computeroutput>
1620	</term>
1621
1622	<listitem>
1623	<para>
1624	Set a file format variant for the output file. This is a
1625	comma-separated list of variant flags. Not all combinations
1626	are supported, and specifying inconsistent flags will result
1627	in an error message.
1628	</para>
1629	</listitem>
1630	</varlistentry>
1631
1632	<varlistentry>
1633	<term>
1634	<computeroutput>--existing</computeroutput>
1635	</term>
1636
1637	<listitem>
1638	<para>
1639	Perform the clone operation to an already existing
1640	destination medium. Only the portion of the source medium
1641	which fits into the destination medium is copied. This means
1642	if the destination medium is smaller than the source only a
1643	part of it is copied, and if the destination medium is
1644	larger than the source the remaining part of the destination
1645	medium is unchanged.
1646	</para>
1647	</listitem>
1648	</varlistentry>
1649
1650	</variablelist>
1651
1652	<note>
1653	<para>
1654	For compatibility with earlier versions of &product-name;, the
1655	<command>clonevdi</command> and <command>clonehd</command>
1656	commands are still supported and mapped internally to the
1657	<command>clonemedium</command> command.
1658	</para>
1659	</note>
1660
1661	</sect1>
1662
1663	<sect1 id="vboxmanage-mediumproperty">
1664
1665	<title>VBoxManage mediumproperty</title>
1666
1667	<para>
1668	This command sets, gets, or deletes a medium property. The syntax
1669	is as follows:
1670	</para>
1671
1672	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] set <uuid\|filename>
1673	<property> <value></screen>
1674
1675	<itemizedlist>
1676
1677	<listitem>
1678	<para>
1679	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
1680	to optionally specify the type of medium: disk (hard drive),
1681	dvd, or floppy.
1682	</para>
1683	</listitem>
1684
1685	<listitem>
1686	<para>
1687	Use <computeroutput><uuid\|filename></computeroutput> to
1688	supply either the UUID or absolute path of the medium or
1689	image.
1690	</para>
1691	</listitem>
1692
1693	<listitem>
1694	<para>
1695	Use <computeroutput><property></computeroutput> to
1696	supply the name of the property.
1697	</para>
1698	</listitem>
1699
1700	<listitem>
1701	<para>
1702	Use <computeroutput><value></computeroutput> to supply
1703	the property value.
1704	</para>
1705	</listitem>
1706
1707	</itemizedlist>
1708
1709	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] get <uuid\|filename>
1710	<property></screen>
1711
1712	<itemizedlist>
1713
1714	<listitem>
1715	<para>
1716	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
1717	to optionally specify the type of medium: disk (hard drive),
1718	dvd, or floppy.
1719	</para>
1720	</listitem>
1721
1722	<listitem>
1723	<para>
1724	Use <computeroutput><uuid\|filename></computeroutput> to
1725	supply either the UUID or absolute path of the medium or
1726	image.
1727	</para>
1728	</listitem>
1729
1730	<listitem>
1731	<para>
1732	Use <computeroutput><property></computeroutput> to
1733	supply the name of the property.
1734	</para>
1735	</listitem>
1736
1737	</itemizedlist>
1738
1739	<screen>VBoxManage mediumproperty [disk\|dvd\|floppy] delete <uuid\|filename>
1740	<property></screen>
1741
1742	<itemizedlist>
1743
1744	<listitem>
1745	<para>
1746	Use <computeroutput><disk\|dvd\|floppy></computeroutput>
1747	to optionally specify the type of medium: disk (hard drive),
1748	dvd, or floppy.
1749	</para>
1750	</listitem>
1751
1752	<listitem>
1753	<para>
1754	Use <computeroutput><uuid\|filename></computeroutput> to
1755	supply either the UUID or absolute path of the medium or
1756	image.
1757	</para>
1758	</listitem>
1759
1760	<listitem>
1761	<para>
1762	Use <computeroutput><property></computeroutput> to
1763	supply the name of the property.
1764	</para>
1765	</listitem>
1766
1767	</itemizedlist>
1768
1769	</sect1>
1770
1771	<sect1 id="vboxmanage-encryptmedium">
1772
1773	<title>VBoxManage encryptmedium</title>
1774
1775	<para>
1776	This command is used to create a DEK encrypted medium or image.
1777	See <xref linkend="diskencryption-encryption" />.
1778	</para>
1779
1780	<para>
1781	The syntax is as follows:
1782	</para>
1783
1784	<screen>VBoxManage encryptmedium <uuid\|filename>
1785	[--newpassword <file\|->]
1786	[--oldpassword <file\|->]
1787	[--cipher <cipher id>]
1788	[--newpasswordid <password id>]</screen>
1789
1790	<itemizedlist>
1791
1792	<listitem>
1793	<para>
1794	Use <computeroutput><uuid\|filename></computeroutput> to
1795	supply the UUID or absolute path of the medium or image to be
1796	encrypted.
1797	</para>
1798	</listitem>
1799
1800	<listitem>
1801	<para>
1802	Use <computeroutput>--newpassword
1803	<file\|-></computeroutput> to supply a new encryption
1804	password. Either specify the absolute pathname of a password
1805	file on the host operating system, or
1806	<computeroutput>-</computeroutput> to prompt you for the
1807	password on the command line. Always use the
1808	<computeroutput>--newpasswordid</computeroutput> option with
1809	this option.
1810	</para>
1811	</listitem>
1812
1813	<listitem>
1814	<para>
1815	Use <computeroutput>--oldpassword
1816	<file\|-></computeroutput> to supply any old encryption
1817	password. Either specify the absolute pathname of a password
1818	file on the host operating system, or
1819	<computeroutput>-</computeroutput> to prompt you for the old
1820	password on the command line.
1821	</para>
1822
1823	<para>
1824	Use this option to gain access to an encrypted medium or image
1825	to either change its password using
1826	<computeroutput>--newpassword</computeroutput> or change its
1827	encryption using <computeroutput>--cipher</computeroutput>.
1828	</para>
1829	</listitem>
1830
1831	<listitem>
1832	<para>
1833	Use <computeroutput>--cipher <cipher></computeroutput>
1834	to specify the cipher to use for encryption. This can be
1835	either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
1836	<computeroutput>AES-XTS256-PLAIN64</computeroutput>.
1837	</para>
1838
1839	<para>
1840	Use this option to change any existing encryption on the
1841	medium or image, or to set up new encryption on it for the
1842	first time.
1843	</para>
1844	</listitem>
1845
1846	<listitem>
1847	<para>
1848	Use <computeroutput>--newpasswordid <password
1849	id></computeroutput> to supply the new password identifier.
1850	This can be chosen by the user, and is used for correct
1851	identification when supplying multiple passwords during VM
1852	startup.
1853	</para>
1854
1855	<para>
1856	If the user uses the same password when encrypting multiple
1857	images and also the same password identifier, the user needs
1858	to supply the password only once during VM startup.
1859	</para>
1860	</listitem>
1861
1862	</itemizedlist>
1863
1864	</sect1>
1865
1866	<sect1 id="vboxmanage-checkmediumpwd">
1867
1868	<title>VBoxManage checkmediumpwd</title>
1869
1870	<para>
1871	This command is used to check the current encryption password on a
1872	DEK encrypted medium or image. See
1873	<xref linkend="diskencryption-encryption" />.
1874	</para>
1875
1876	<para>
1877	The syntax is as follows:
1878	</para>
1879
1880	<screen>VBoxManage checkmediumpwd <uuid\|filename>
1881	<pwd file\|-></screen>
1882
1883	<itemizedlist>
1884
1885	<listitem>
1886	<para>
1887	Use <computeroutput><uuid\|filename></computeroutput> to
1888	supply the UUID or absolute path of the medium or image to be
1889	checked.
1890	</para>
1891	</listitem>
1892
1893	<listitem>
1894	<para>
1895	Use <computeroutput><pwd file\|-></computeroutput> to
1896	supply the password identifier to be checked. Either specify
1897	the absolute pathname of a password file on the host operating
1898	system, or <computeroutput>-</computeroutput> to prompt you
1899	for the password on the command line.
1900	</para>
1901	</listitem>
1902
1903	</itemizedlist>
1904
1905	</sect1>
1906
1907	<sect1 id="vboxmanage-convertfromraw">
1908
1909	<title>VBoxManage convertfromraw</title>
1910
1911	<para>
1912	This command converts a raw disk image to an &product-name; Disk
1913	Image (VDI) file. The syntax is as follows:
1914	</para>
1915
1916	<screen>VBoxManage convertfromraw <filename> <outputfile>
1917	[--format VDI\|VMDK\|VHD]
1918	[--variant Standard,Fixed,Split2G,Stream,ESX]
1919	[--uuid <uuid>]
1920	VBoxManage convertfromraw stdin <outputfile> <bytes>
1921	[--format VDI\|VMDK\|VHD]
1922	[--variant Standard,Fixed,Split2G,Stream,ESX]
1923	[--uuid <uuid>]</screen>
1924
1925	<para>
1926	The parameters are as follows:
1927	</para>
1928
1929	<variablelist>
1930
1931	<varlistentry>
1932	<term>
1933	<computeroutput>--bytes</computeroutput>
1934	</term>
1935
1936	<listitem>
1937	<para>
1938	The size of the image file, in bytes, provided through
1939	stdin.
1940	</para>
1941	</listitem>
1942	</varlistentry>
1943
1944	<varlistentry>
1945	<term>
1946	<computeroutput>--format</computeroutput>
1947	</term>
1948
1949	<listitem>
1950	<para>
1951	Select the disk image format to create. The default format
1952	is VDI. Other options are VMDK and VHD.
1953	</para>
1954	</listitem>
1955	</varlistentry>
1956
1957	<varlistentry>
1958	<term>
1959	<computeroutput>--variant</computeroutput>
1960	</term>
1961
1962	<listitem>
1963	<para>
1964	Choose a file format variant for the output file. This is a
1965	comma-separated list of variant flags. Not all combinations
1966	are supported, and specifying inconsistent flags will result
1967	in an error message.
1968	</para>
1969	</listitem>
1970	</varlistentry>
1971
1972	<varlistentry>
1973	<term>
1974	<computeroutput>--uuid</computeroutput>
1975	</term>
1976
1977	<listitem>
1978	<para>
1979	Specify the UUID of the output file.
1980	</para>
1981	</listitem>
1982	</varlistentry>
1983
1984	</variablelist>
1985
1986	<para>
1987	The <command>stdin</command> form of the command forces
1988	<command>VBoxManage</command> to read the content of the disk
1989	image from standard input. This useful when using the command in a
1990	pipe.
1991	</para>
1992
1993	<note>
1994	<para>
1995	For compatibility with earlier versions of &product-name;, the
1996	<command>convertdd</command> command is also supported and
1997	mapped internally to the <command>convertfromraw</command>
1998	command.
1999	</para>
2000	</note>
2001
2002	</sect1>
2003
2004	<xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
2005
2006	<sect1 id="vboxmanage-extradata">
2007
2008	<title>VBoxManage getextradata/setextradata</title>
2009
2010	<para>
2011	These commands enable you to attach and retrieve string data for a
2012	virtual machine or for an &product-name; configuration, by
2013	specifying <computeroutput>global</computeroutput> instead of a
2014	virtual machine name. You must specify a keyword as a text string
2015	to associate the data with, which you can later use to retrieve
2016	it. For example:
2017	</para>
2018
2019	<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
2020	VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
2021
2022	<para>
2023	This example would associate the string "2006.01.01" with the
2024	keyword installdate for the virtual machine Fedora5, and
2025	"2006.02.02" on the machine SUSE10. You could then retrieve the
2026	information as follows:
2027	</para>
2028
2029	<screen>VBoxManage getextradata Fedora5 installdate</screen>
2030
2031	<para>
2032	This would return the following:
2033	</para>
2034
2035	<screen>VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
2036	(C) 2005-2018 Oracle Corporation
2037	All rights reserved.
2038
2039	Value: 2006.01.01</screen>
2040
2041	<para>
2042	You could retrieve the information for all keywords as follows:
2043	</para>
2044
2045	<screen>VBoxManage getextradata Fedora5 enumerate</screen>
2046
2047	<para>
2048	To remove a keyword, the <command>setextradata</command> command
2049	must be run without specifying data, only the keyword. For
2050	example:
2051	</para>
2052
2053	<screen>VBoxManage setextradata Fedora5 installdate</screen>
2054
2055	</sect1>
2056
2057	<sect1 id="vboxmanage-setproperty">
2058
2059	<title>VBoxManage setproperty</title>
2060
2061	<para>
2062	This command is used to change global settings which affect the
2063	entire &product-name; installation. Some of these correspond to
2064	the settings in the <emphasis role="bold">Preferences</emphasis>
2065	dialog in the VirtualBox Manager. The following properties are
2066	available:
2067	</para>
2068
2069	<variablelist>
2070
2071	<varlistentry>
2072	<term>
2073	<computeroutput>machinefolder</computeroutput>
2074	</term>
2075
2076	<listitem>
2077	<para>
2078	Specifies the default folder in which virtual machine
2079	definitions are kept. See <xref linkend="vboxconfigdata" />.
2080	</para>
2081	</listitem>
2082	</varlistentry>
2083
2084	<varlistentry>
2085	<term>
2086	<computeroutput>hwvirtexclusive</computeroutput>
2087	</term>
2088
2089	<listitem>
2090	<para>
2091	Specifies whether &product-name; will make exclusive use of
2092	the hardware virtualization extensions (Intel VT-x or AMD-V)
2093	of the host system's processor. See
2094	<xref linkend="hwvirt" />. If you wish to share these
2095	extensions with other hypervisors running at the same time,
2096	you must disable this setting. Doing so has negative
2097	performance implications.
2098	</para>
2099	</listitem>
2100	</varlistentry>
2101
2102	<varlistentry>
2103	<term>
2104	<computeroutput>vrdeauthlibrary</computeroutput>
2105	</term>
2106
2107	<listitem>
2108	<para>
2109	Specifies which library to use when external authentication
2110	has been selected for a particular virtual machine. See
2111	<xref linkend="vbox-auth" />.
2112	</para>
2113	</listitem>
2114	</varlistentry>
2115
2116	<varlistentry>
2117	<term>
2118	<computeroutput>websrvauthlibrary</computeroutput>
2119	</term>
2120
2121	<listitem>
2122	<para>
2123	Specifies which library the web service uses to authenticate
2124	users. For details about the &product-name; web service, see
2125	the &product-name; SDK reference,
2126	<xref
2127	linkend="VirtualBoxAPI" />.
2128	</para>
2129	</listitem>
2130	</varlistentry>
2131
2132	<varlistentry>
2133	<term>
2134	<computeroutput>vrdeextpack</computeroutput>
2135	</term>
2136
2137	<listitem>
2138	<para>
2139	Specifies which library implements the VirtualBox Remote
2140	Desktop Extension.
2141	</para>
2142	</listitem>
2143	</varlistentry>
2144
2145	<varlistentry>
2146	<term>
2147	<computeroutput>loghistorycount</computeroutput>
2148	</term>
2149
2150	<listitem>
2151	<para>
2152	Selects how many rotated VM logs are retained.
2153	</para>
2154	</listitem>
2155	</varlistentry>
2156
2157	<varlistentry>
2158	<term>
2159	<computeroutput>autostartdbpath</computeroutput>
2160	</term>
2161
2162	<listitem>
2163	<para>
2164	Selects the path to the autostart database. See
2165	<xref linkend="autostart" />.
2166	</para>
2167	</listitem>
2168	</varlistentry>
2169
2170	<varlistentry>
2171	<term>
2172	<computeroutput>defaultfrontend</computeroutput>
2173	</term>
2174
2175	<listitem>
2176	<para>
2177	Selects the global default VM frontend setting. See
2178	<xref linkend="vboxmanage-startvm" />.
2179	</para>
2180	</listitem>
2181	</varlistentry>
2182
2183	<varlistentry>
2184	<term>
2185	<computeroutput>logginglevel</computeroutput>
2186	</term>
2187
2188	<listitem>
2189	<para>
2190	Configures the VBoxSVC release logging details. See
2191	<ulink url="http://www.virtualbox.org/wiki/VBoxLogging" />.
2192	</para>
2193	</listitem>
2194	</varlistentry>
2195
2196	<varlistentry>
2197	<term>
2198	<computeroutput>proxymode</computeroutput>
2199	</term>
2200
2201	<listitem>
2202	<para>
2203	Configures the mode for an HTTP proxy server.
2204	</para>
2205	</listitem>
2206	</varlistentry>
2207
2208	<varlistentry>
2209	<term>
2210	<computeroutput>proxyurl</computeroutput>
2211	</term>
2212
2213	<listitem>
2214	<para>
2215	Configures the URL for an HTTP proxy server. Used when a
2216	manual proxy is configured using the
2217	<computeroutput>manual</computeroutput> setting of the
2218	<computeroutput>proxymode</computeroutput> property.
2219	</para>
2220	</listitem>
2221	</varlistentry>
2222
2223	<varlistentry>
2224	<term>
2225	<computeroutput>language</computeroutput>
2226	</term>
2227
2228	<listitem>
2229	<para>
2230	Specifies the user language used to translate API messages.
2231	Valid values are <literal>C</literal>, which means no
2232	translation or language code in form either <literal>ll</literal>
2233	or <literal>ll_CC</literal>, where <literal>ll</literal> is
2234	language 2 letters code in lower case and
2235	<literal>CC</literal> is country 2 letter code in upper case.
2236	</para>
2237	</listitem>
2238	</varlistentry>
2239
2240	</variablelist>
2241
2242	</sect1>
2243
2244	<sect1 id="vboxmanage-usbfilter">
2245
2246	<title>VBoxManage usbfilter add/modify/remove</title>
2247
2248	<screen>VBoxManage usbfilter add <index,0-N>
2249	--target <uuid\|vmname>global
2250	--name <string>
2251	--action ignore\|hold (global filters only)
2252	[--active yes\|no (yes)]
2253	[--vendorid <XXXX> (null)]
2254	[--productid <XXXX> (null)]
2255	[--revision <IIFF> (null)]
2256	[--manufacturer <string> (null)]
2257	[--product <string> (null)]
2258	[--remote yes\|no (null, VM filters only)]
2259	[--serialnumber <string> (null)]
2260	[--maskedinterfaces <XXXXXXXX>]
2261	</screen>
2262
2263	<screen>VBoxManage usbfilter modify <index,0-N>
2264	--target <uuid\|vmname>global
2265	[--name <string>]
2266	[--action ignore\|hold (global filters only)]
2267	[--active yes\|no]
2268	[--vendorid <XXXX>]
2269	[--productid <XXXX>]
2270	[--revision <IIFF>]
2271	[--manufacturer <string>]
2272	[--product <string>]
2273	[--remote yes\|no (null, VM filters only)]
2274	[--serialnumber <string>]
2275	[--maskedinterfaces <XXXXXXXX>]
2276	</screen>
2277
2278	<screen>VBoxManage usbfilter remove <index,0-N>
2279	--target <uuid\|vmname>global
2280	</screen>
2281
2282	<para>
2283	The <command>usbfilter</command> commands are used for working
2284	with USB filters in virtual machines, or global filters which
2285	affect the whole &product-name; setup. Global filters are applied
2286	before machine-specific filters, and may be used to prevent
2287	devices from being captured by any virtual machine. Global filters
2288	are always applied in a particular order, and only the first
2289	filter which fits a device is applied. For example, if the first
2290	global filter says to hold, or make available, a particular
2291	Kingston memory stick device and the second filter says to ignore
2292	all Kingston devices. That particular Kingston memory stick will
2293	be available to any machine with the appropriate filter, but no
2294	other Kingston device will.
2295	</para>
2296
2297	<para>
2298	When creating a USB filter using <command>usbfilter add</command>,
2299	you must supply three or four mandatory parameters. The index
2300	specifies the position in the list at which the filter should be
2301	placed. If there is already a filter at that position, then it and
2302	the following ones will be shifted back one place. Otherwise, the
2303	new filter will be added onto the end of the list. The
2304	<computeroutput>target</computeroutput> parameter selects the
2305	virtual machine that the filter should be attached to or use
2306	<computeroutput>global</computeroutput> to apply it to all virtual
2307	machines. <computeroutput>name</computeroutput> is a name for the
2308	new filter. For global filters,
2309	<computeroutput>action</computeroutput> says whether to allow VMs
2310	access to devices that fit the filter description (hold) or not to
2311	give them access (ignore). In addition, you should specify
2312	parameters to filter by. You can find the parameters for devices
2313	attached to your system using <command>VBoxManage list
2314	usbhost</command>. Finally, you can specify whether the filter
2315	should be active. For local filters, whether they are for local
2316	devices, remote devices over an RDP connection, or either.
2317	</para>
2318
2319	<para>
2320	When you modify a USB filter using <command>usbfilter
2321	modify</command>, you must specify the filter by index and by
2322	target, which is either a virtual machine or
2323	<computeroutput>global</computeroutput>. See the output of
2324	<command>VBoxManage list usbfilters</command> to find global
2325	filter indexes and <command>VBoxManage showvminfo</command> to
2326	find indexes for individual machines. The properties which can be
2327	changed are the same as for <command>usbfilter add</command>. To
2328	remove a filter, use <command>usbfilter remove</command> and
2329	specify the index and the target.
2330	</para>
2331
2332	<para>
2333	The following is a list of the additional <command>usbfilter
2334	add</command> and <command>usbfilter modify</command> options,
2335	with details of how to use them.
2336	</para>
2337
2338	<itemizedlist>
2339
2340	<listitem>
2341	<para>
2342	<computeroutput>--action ignore\|hold</computeroutput>:
2343	Specifies whether devices that fit the filter description are
2344	allowed access by machines (hold), or have access denied
2345	(ignore). Applies to global filters only.
2346	</para>
2347	</listitem>
2348
2349	<listitem>
2350	<para>
2351	<computeroutput>--active yes\|no</computeroutput>: Specifies
2352	whether the USB Filter is active or temporarily disabled. For
2353	<computeroutput>usbfilter create</computeroutput> the default
2354	is active.
2355	</para>
2356	</listitem>
2357
2358	<listitem>
2359	<para>
2360	<computeroutput>--vendorid <XXXX>\|""</computeroutput>:
2361	Specifies a vendor ID filter. The string representation for an
2362	exact match has the form XXXX, where X is the hexadecimal
2363	digit, including leading zeroes.
2364	</para>
2365	</listitem>
2366
2367	<listitem>
2368	<para>
2369	<computeroutput>--productid <XXXX>\|""</computeroutput>:
2370	Specifies a product ID filter. The string representation for
2371	an exact match has the form XXXX, where X is the hexadecimal
2372	digit, including leading zeroes.
2373	</para>
2374	</listitem>
2375
2376	<listitem>
2377	<para>
2378	<computeroutput>--revision <IIFF>\|""</computeroutput>:
2379	Specifies a revision ID filter. The string representation for
2380	an exact match has the form IIFF, where I is the decimal digit
2381	of the integer part of the revision, and F is the decimal
2382	digit of its fractional part, including leading and trailing
2383	zeros. Note that for interval filters, it is best to use the
2384	hexadecimal form, because the revision is stored as a 16-bit
2385	packed BCD value. Therefore, the expression int:0x0100-0x0199
2386	will match any revision from 1.0 to 1.99 inclusive.
2387	</para>
2388	</listitem>
2389
2390	<listitem>
2391	<para>
2392	<computeroutput>--manufacturer
2393	<string>\|""</computeroutput>: Specifies a manufacturer
2394	ID filter, as a string.
2395	</para>
2396	</listitem>
2397
2398	<listitem>
2399	<para>
2400	<computeroutput>--product <string>\|""</computeroutput>:
2401	Specifies a product ID filter, as a string.
2402	</para>
2403	</listitem>
2404
2405	<listitem>
2406	<para>
2407	<computeroutput>--remote yes\|no""</computeroutput>: Specifies
2408	a remote filter, indicating whether the device is physically
2409	connected to a remote VRDE client or to a local host machine.
2410	Applies to VM filters only.
2411	</para>
2412	</listitem>
2413
2414	<listitem>
2415	<para>
2416	<computeroutput>--serialnumber
2417	<string>\|""</computeroutput>: Specifies a serial number
2418	filter, as a string.
2419	</para>
2420	</listitem>
2421
2422	<listitem>
2423	<para>
2424	<computeroutput>--maskedinterfaces
2425	<XXXXXXXX></computeroutput>: Specifies a masked
2426	interface filter, for hiding one or more USB interfaces from
2427	the guest. The value is a bit mask where the set bits
2428	correspond to the USB interfaces that should be hidden, or
2429	masked off. This feature only works on Linux hosts.
2430	</para>
2431	</listitem>
2432
2433	</itemizedlist>
2434
2435	</sect1>
2436
2437	<xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
2438
2439	<sect1 id="vboxmanage-guestproperty">
2440
2441	<title>VBoxManage guestproperty</title>
2442
2443	<para>
2444	The <command>guestproperty</command> commands enable you to get or
2445	set properties of a running virtual machine. See
2446	<xref linkend="guestadd-guestprops" />. Guest properties are
2447	arbitrary keyword-value string pairs which can be written to and
2448	read from by either the guest or the host, so they can be used as
2449	a low-volume communication channel for strings, provided that a
2450	guest is running and has the Guest Additions installed. In
2451	addition, a number of values whose keywords begin with
2452	<computeroutput>/VirtualBox/</computeroutput>are automatically set
2453	and maintained by the Guest Additions.
2454	</para>
2455
2456	<para>
2457	The following subcommands are available, where
2458	<computeroutput><vm></computeroutput> can either be a VM
2459	name or a VM UUID, as with the other <command>VBoxManage</command>
2460	commands:
2461	</para>
2462
2463	<itemizedlist>
2464
2465	<listitem>
2466	<para>
2467	<computeroutput>enumerate <vm> [--patterns
2468	<pattern>]</computeroutput>: Lists all the guest
2469	properties that are available for the given VM, including the
2470	value. This list will be very limited if the guest's service
2471	process cannot be contacted, for example because the VM is not
2472	running or the Guest Additions are not installed.
2473	</para>
2474
2475	<para>
2476	If <computeroutput>--patterns <pattern></computeroutput>
2477	is specified, it acts as a filter to only list properties that
2478	match the given pattern. The pattern can contain the following
2479	wildcard characters:
2480	</para>
2481
2482	<itemizedlist>
2483
2484	<listitem>
2485	<para>
2486	<computeroutput>*</computeroutput> (asterisk): Represents
2487	any number of characters. For example,
2488	"<computeroutput>/VirtualBox*</computeroutput>" would
2489	match all properties beginning with "/VirtualBox".
2490	</para>
2491	</listitem>
2492
2493	<listitem>
2494	<para>
2495	<computeroutput>?</computeroutput> (question mark):
2496	Represents a single arbitrary character. For example,
2497	"<computeroutput>fo?</computeroutput>" would match both
2498	"foo" and "for".
2499	</para>
2500	</listitem>
2501
2502	<listitem>
2503	<para>
2504	<computeroutput>\|</computeroutput> (pipe symbol): Can be
2505	used to specify multiple alternative patterns. For
2506	example, "<computeroutput>s\|t</computeroutput>" would
2507	match anything starting with either "s" or "t".
2508	</para>
2509	</listitem>
2510
2511	</itemizedlist>
2512	</listitem>
2513
2514	<listitem>
2515	<para>
2516	<computeroutput>get <vm>
2517	<property></computeroutput>: Retrieves the value of a
2518	single property only. If the property cannot be found, for
2519	example because the guest is not running, the following
2520	message is shown:
2521	</para>
2522
2523	<screen>No value set!</screen>
2524	</listitem>
2525
2526	<listitem>
2527	<para>
2528	<computeroutput>set <vm> <property> [<value>
2529	[--flags <flags>]]</computeroutput>: Enables you to set
2530	a guest property by specifying the keyword and value. If
2531	<computeroutput><value></computeroutput> is omitted, the
2532	property is deleted. With
2533	<computeroutput>--flags</computeroutput>, you can specify
2534	additional behavior. You can combine several flags by
2535	separating them with commas.
2536	</para>
2537
2538	<itemizedlist>
2539
2540	<listitem>
2541	<para>
2542	<computeroutput>TRANSIENT</computeroutput>: The value will
2543	not be stored with the VM data when the VM exits.
2544	</para>
2545	</listitem>
2546
2547	<listitem>
2548	<para>
2549	<computeroutput>TRANSRESET</computeroutput>: The value
2550	will be deleted as soon as the VM restarts or exits.
2551	</para>
2552	</listitem>
2553
2554	<listitem>
2555	<para>
2556	<computeroutput>RDONLYGUEST</computeroutput>: The value
2557	can only be changed by the host, but the guest can only
2558	read it.
2559	</para>
2560	</listitem>
2561
2562	<listitem>
2563	<para>
2564	<computeroutput>RDONLYHOST</computeroutput>: The value can
2565	only be changed by the guest, but the host can only read
2566	it.
2567	</para>
2568	</listitem>
2569
2570	<listitem>
2571	<para>
2572	<computeroutput>READONLY</computeroutput>: The value
2573	cannot be changed at all.
2574	</para>
2575	</listitem>
2576
2577	</itemizedlist>
2578	</listitem>
2579
2580	<listitem>
2581	<para>
2582	<computeroutput>wait <vm> <pattern> --timeout
2583	<timeout></computeroutput>: Waits for a particular value
2584	described by the pattern string to change or to be deleted or
2585	created. The pattern rules are the same as for the
2586	<command>enumerate</command> subcommand.
2587	</para>
2588	</listitem>
2589
2590	<listitem>
2591	<para>
2592	<computeroutput>delete <vm>
2593	<property></computeroutput>: Deletes a guest property
2594	which has been set previously.
2595	</para>
2596	</listitem>
2597
2598	</itemizedlist>
2599
2600	</sect1>
2601
2602	<sect1 id="vboxmanage-guestcontrol">
2603
2604	<title>VBoxManage guestcontrol</title>
2605
2606	<para>
2607	The <command>guestcontrol</command> commands enable control of the
2608	guest from the host. See
2609	<xref
2610	linkend="guestadd-guestcontrol" /> for an introduction.
2611	</para>
2612
2613	<para>
2614	The <command>guestcontrol</command> command has two sets of
2615	subcommands. The first set requires guest credentials to be
2616	specified, the second does not.
2617	</para>
2618
2619	<para>
2620	The first set of subcommands is of the following form:
2621	</para>
2622
2623	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
2624	[--username <name> ]
2625	[--passwordfile <file> \| --password <password>]
2626	[--domain <domain> ]
2627	[-v\|--verbose] [-q\|quiet] ...
2628	</screen>
2629
2630	<para>
2631	The common options are as follows:
2632	</para>
2633
2634	<screen>
2635	[--username <name> ]
2636	[--passwordfile <file> \| --password <password>]
2637	[--domain <domain> ]
2638	[-v\|--verbose] [-q\|quiet]
2639	</screen>
2640
2641	<para>
2642	The common options for the first set of subcommands are explained
2643	in the following list.
2644	</para>
2645
2646	<variablelist>
2647
2648	<varlistentry>
2649	<term>
2650	<computeroutput><uuid\|vmname></computeroutput>
2651	</term>
2652
2653	<listitem>
2654	<para>
2655	Specifies the VM UUID or VM name. Mandatory.
2656	</para>
2657	</listitem>
2658	</varlistentry>
2659
2660	<varlistentry>
2661	<term>
2662	<computeroutput>--username <name></computeroutput>
2663	</term>
2664
2665	<listitem>
2666	<para>
2667	Specifies the user name on guest OS under which the process
2668	should run. This user name must already exist on the guest
2669	OS. If unspecified, the host user name is used. Optional
2670	</para>
2671	</listitem>
2672	</varlistentry>
2673
2674	<varlistentry>
2675	<term>
2676	<computeroutput>--passwordfile
2677	<file>\|--password</computeroutput>
2678	</term>
2679
2680	<listitem>
2681	<para>
2682	Specifies the absolute path on guest file system of password
2683	file containing the password for the specified user account
2684	or password for the specified user account. Optional. If
2685	both are omitted, empty password is assumed.
2686	</para>
2687	</listitem>
2688	</varlistentry>
2689
2690	<varlistentry>
2691	<term>
2692	<computeroutput>--domain <domain></computeroutput>
2693	</term>
2694
2695	<listitem>
2696	<para>
2697	User domain for Windows guests. Optional.
2698	</para>
2699	</listitem>
2700	</varlistentry>
2701
2702	<varlistentry>
2703	<term>
2704	<computeroutput>-v\|--verbose</computeroutput>
2705	</term>
2706
2707	<listitem>
2708	<para>
2709	Makes the subcommand execution more verbose. Optional
2710	</para>
2711	</listitem>
2712	</varlistentry>
2713
2714	<varlistentry>
2715	<term>
2716	<computeroutput>-q\|--quiet</computeroutput>
2717	</term>
2718
2719	<listitem>
2720	<para>
2721	Makes the subcommand execution quieter. Optional.
2722	</para>
2723	</listitem>
2724	</varlistentry>
2725
2726	</variablelist>
2727
2728	<para>
2729	The first set of subcommands are as follows:
2730	</para>
2731
2732	<itemizedlist>
2733
2734	<listitem>
2735	<para>
2736	<computeroutput>run</computeroutput>: Executes a guest
2737	program, forwarding stdout, stderr, and stdin to and from the
2738	host until it completes.
2739	</para>
2740
2741	<screen>VBoxManage guestcontrol <uuid\|vmname> run [common-options]
2742	--exe <path to executable> [--timeout <msec>]
2743	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
2744	[--ignore-operhaned-processes] [--profile]
2745	[--no-wait-stdout\|--wait-stdout]
2746	[--no-wait-stderr\|--wait-stderr]
2747	[--dos2unix] [--unix2dos]
2748	-- <program/arg0> [argument1] ... [argumentN]]
2749	</screen>
2750
2751	<variablelist>
2752
2753	<varlistentry>
2754	<term>
2755	<computeroutput><uuid\|vmname></computeroutput>
2756	</term>
2757
2758	<listitem>
2759	<para>
2760	Specifies the VM UUID or VM name. Mandatory.
2761	</para>
2762	</listitem>
2763	</varlistentry>
2764
2765	<varlistentry>
2766	<term>
2767	<computeroutput>--exe <path to
2768	executable></computeroutput>
2769	</term>
2770
2771	<listitem>
2772	<para>
2773	Specifies the absolute path of the executable on the
2774	guest OS file system. Mandatory. For example:
2775	<filename>C:\Windows\System32\calc.exe</filename>.
2776	</para>
2777	</listitem>
2778	</varlistentry>
2779
2780	<varlistentry>
2781	<term>
2782	<computeroutput>--timeout <msec></computeroutput>
2783	</term>
2784
2785	<listitem>
2786	<para>
2787	Specifies the maximum time, in microseconds, that the
2788	executable can run, during which
2789	<command>VBoxManage</command> receives its output.
2790	Optional. If unspecified, <command>VBoxManage</command>
2791	waits indefinitely for the process to end, or an error
2792	occurs.
2793	</para>
2794	</listitem>
2795	</varlistentry>
2796
2797	<varlistentry>
2798	<term>
2799	<computeroutput>-E\|--putenv
2800	<NAME>=<VALUE></computeroutput>
2801	</term>
2802
2803	<listitem>
2804	<para>
2805	Sets, modifies, and unsets environment variables in the
2806	environment in which the program will run. Optional.
2807	</para>
2808
2809	<para>
2810	The guest process is created with the standard default
2811	guest OS environment. Use this option to modify that
2812	default environment. To set or modify a variable use:
2813	<computeroutput><NAME>=<VALUE></computeroutput>.
2814	To unset a variable use:
2815	<computeroutput><NAME>=</computeroutput>
2816	</para>
2817
2818	<para>
2819	Any spaces in names and values should be enclosed by
2820	quotes.
2821	</para>
2822
2823	<para>
2824	To set, modify, and unset multiple variables, use
2825	multiple instances of the
2826	<computeroutput>--E\|--putenv</computeroutput> option.
2827	</para>
2828	</listitem>
2829	</varlistentry>
2830
2831	<varlistentry>
2832	<term>
2833	<computeroutput>--unquoted-args</computeroutput>
2834	</term>
2835
2836	<listitem>
2837	<para>
2838	Disables escaped double quoting, such as \"fred\", on
2839	arguments passed to the executed program. Optional.
2840	</para>
2841	</listitem>
2842	</varlistentry>
2843
2844	<varlistentry>
2845	<term>
2846	<computeroutput>--ignore-operhaned-processes</computeroutput>
2847	</term>
2848
2849	<listitem>
2850	<para>
2851	Ignore orphaned processes. Not yet implemented.
2852	Optional.
2853	</para>
2854	</listitem>
2855	</varlistentry>
2856
2857	<varlistentry>
2858	<term>
2859	<computeroutput>--profile</computeroutput>
2860	</term>
2861
2862	<listitem>
2863	<para>
2864	Use Profile. Not yet implemented. Optional.
2865	</para>
2866	</listitem>
2867	</varlistentry>
2868
2869	<varlistentry>
2870	<term>
2871	<computeroutput>--no-wait-stdout\|--wait-stdout</computeroutput>
2872	</term>
2873
2874	<listitem>
2875	<para>
2876	Does not wait or waits until the guest process ends and
2877	receives its exit code and reason/flags. In the case of
2878	<computeroutput>--wait-stdout</computeroutput>,
2879	<command>VBoxManage</command> receives its stdout while
2880	the process runs. Optional.
2881	</para>
2882	</listitem>
2883	</varlistentry>
2884
2885	<varlistentry>
2886	<term>
2887	<computeroutput>--no-wait-stderr\|--wait-stderr</computeroutput>
2888	</term>
2889
2890	<listitem>
2891	<para>
2892	Does not wait or waits until the guest process ends and
2893	receives its exit code, error messages, and flags. In
2894	the case of
2895	<computeroutput>--wait-stderr</computeroutput>,
2896	<command>VBoxManage</command> receives its stderr while
2897	the process runs. Optional.
2898	</para>
2899	</listitem>
2900	</varlistentry>
2901
2902	<varlistentry>
2903	<term>
2904	<computeroutput>--dos2unix</computeroutput>
2905	</term>
2906
2907	<listitem>
2908	<para>
2909	Converts output from DOS/Windows guests to
2910	UNIX/Linux-compatible line endings, CR + LF to LF. Not
2911	yet implemented. Optional.
2912	</para>
2913	</listitem>
2914	</varlistentry>
2915
2916	<varlistentry>
2917	<term>
2918	<computeroutput>--unix2dos</computeroutput>
2919	</term>
2920
2921	<listitem>
2922	<para>
2923	Converts output from a UNIX/Linux guests to
2924	DOS/Windows-compatible line endings, LF to CR + LF. Not
2925	yet implemented. Optional.
2926	</para>
2927	</listitem>
2928	</varlistentry>
2929
2930	<varlistentry>
2931	<term>
2932	<computeroutput>[-- <program/arg0>
2933	[<argument1>] ...
2934	[<argumentN>]]</computeroutput>
2935	</term>
2936
2937	<listitem>
2938	<para>
2939	Specifies the program name, followed by one or more
2940	arguments to pass to the program. Optional.
2941	</para>
2942
2943	<para>
2944	Any spaces in arguments should be enclosed by quotes.
2945	</para>
2946	</listitem>
2947	</varlistentry>
2948
2949	</variablelist>
2950
2951	<note>
2952	<para>
2953	On Windows there are certain limitations for graphical
2954	applications. See <xref linkend="KnownIssues" />.
2955	</para>
2956	</note>
2957
2958	<para>
2959	Examples of using the <command>guestcontrol run</command>
2960	command are as follows:
2961	</para>
2962
2963	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
2964	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
2965
2966	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
2967	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
2968
2969	<para>
2970	Note that the double backslashes in the second example are
2971	only required on UNIX hosts.
2972	</para>
2973
2974	<note>
2975	<para>
2976	For certain commands a user name of an existing user account
2977	on the guest must be specified. Anonymous executions are not
2978	supported for security reasons. A user account password,
2979	however, is optional and depends on the guest's OS security
2980	policy or rules. If no password is specified for a given
2981	user name, an empty password will be used. On certain OSes
2982	like Windows the security policy may needs to be adjusted in
2983	order to allow user accounts with an empty password set.
2984	Also, global domain rules might apply and therefore cannot
2985	be changed.
2986	</para>
2987	</note>
2988
2989	<para>
2990	Starting at &product-name; 4.1.2 guest process execution by
2991	default is limited to serve up to five guest processes at a
2992	time. If a new guest process gets started which would exceed
2993	this limit, the oldest not running guest process will be
2994	discarded in order to be able to run that new process. Also,
2995	retrieving output from this old guest process will not be
2996	possible anymore then. If all five guest processes are still
2997	active and running, starting a new guest process will result
2998	in an appropriate error message.
2999	</para>
3000
3001	<para>
3002	To raise or lower the guest process execution limit, either
3003	use the guest property
3004	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
3005	or <command>VBoxService</command> command line by specifying
3006	<computeroutput>--control-procs-max-kept</computeroutput>
3007	needs to be modified. A restart of the guest OS is required
3008	afterwards. To serve unlimited guest processes, a value of
3009	<computeroutput>0</computeroutput> needs to be set, but this
3010	is not recommended.
3011	</para>
3012	</listitem>
3013
3014	<listitem>
3015	<para>
3016	<computeroutput>start</computeroutput>: Executes a guest
3017	program until it completes.
3018	</para>
3019
3020	<screen>VBoxManage guestcontrol <uuid\|vmname> start [common-options]
3021	[--exe <path to executable>] [--timeout <msec>]
3022	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
3023	[--ignore-operhaned-processes] [--profile]
3024	-- <program/arg0> [argument1] ... [argumentN]]
3025	</screen>
3026
3027	<para>
3028	Where the options are as follows:
3029	</para>
3030
3031	<variablelist>
3032
3033	<varlistentry>
3034	<term>
3035	<computeroutput><uuid\|vmname></computeroutput>
3036	</term>
3037
3038	<listitem>
3039	<para>
3040	Specifies the VM UUID or VM name. Mandatory.
3041	</para>
3042	</listitem>
3043	</varlistentry>
3044
3045	<varlistentry>
3046	<term>
3047	<computeroutput>--exe <path to
3048	executable></computeroutput>
3049	</term>
3050
3051	<listitem>
3052	<para>
3053	Specifies the absolute path of the executable on the
3054	guest OS file system. Mandatory. For example:
3055	<filename>C:\Windows\System32\calc.exe</filename>
3056	</para>
3057	</listitem>
3058	</varlistentry>
3059
3060	<varlistentry>
3061	<term>
3062	<computeroutput>--timeout <msec></computeroutput>
3063	</term>
3064
3065	<listitem>
3066	<para>
3067	Specifies the maximum time, in microseconds, that the
3068	executable can run. Optional. If unspecified,
3069	<command>VBoxManage</command> waits indefinitely for the
3070	process to end, or an error occurs.
3071	</para>
3072	</listitem>
3073	</varlistentry>
3074
3075	<varlistentry>
3076	<term>
3077	<computeroutput>-E\|--putenv
3078	<NAME>=<VALUE></computeroutput>
3079	</term>
3080
3081	<listitem>
3082	<para>
3083	Sets, modifies, and unsets environment variables in the
3084	environment in which the program will run. Optional.
3085	</para>
3086
3087	<para>
3088	The guest process is created with the standard default
3089	guest OS environment. Use this option to modify that
3090	default environment. To set or modify a variable use:
3091	<computeroutput><NAME>=<VALUE></computeroutput>.
3092	To unset a variable use:
3093	<computeroutput><NAME>=</computeroutput>
3094	</para>
3095
3096	<para>
3097	Any spaces in names and values should be enclosed by
3098	quotes.
3099	</para>
3100
3101	<para>
3102	To set, modify, or unset multiple variables, use
3103	multiple instances of the
3104	<computeroutput>--E\|--putenv</computeroutput> option.
3105	</para>
3106	</listitem>
3107	</varlistentry>
3108
3109	<varlistentry>
3110	<term>
3111	<computeroutput>--unquoted-args</computeroutput>
3112	</term>
3113
3114	<listitem>
3115	<para>
3116	Disables escaped double quoting, such as \"fred\", on
3117	arguments passed to the executed program. Optional.
3118	</para>
3119	</listitem>
3120	</varlistentry>
3121
3122	<varlistentry>
3123	<term>
3124	<computeroutput>--ignore-operhaned-processes</computeroutput>
3125	</term>
3126
3127	<listitem>
3128	<para>
3129	Ignores orphaned processes. Not yet implemented.
3130	Optional.
3131	</para>
3132	</listitem>
3133	</varlistentry>
3134
3135	<varlistentry>
3136	<term>
3137	<computeroutput>--profile</computeroutput>
3138	</term>
3139
3140	<listitem>
3141	<para>
3142	Use a profile. Not yet implemented. Optional.
3143	</para>
3144	</listitem>
3145	</varlistentry>
3146
3147	<varlistentry>
3148	<term>
3149	<computeroutput>[-- <program/arg0>
3150	[<argument1>] ...
3151	[<argumentN>]]</computeroutput>
3152	</term>
3153
3154	<listitem>
3155	<para>
3156	Specifies the program name, followed by one or more
3157	arguments to pass to the program. Optional.
3158	</para>
3159
3160	<para>
3161	Any spaces in arguments should be enclosed by quotes.
3162	</para>
3163	</listitem>
3164	</varlistentry>
3165
3166	</variablelist>
3167
3168	<note>
3169	<para>
3170	On Windows there are certain limitations for graphical
3171	applications. See <xref linkend="KnownIssues" />.
3172	</para>
3173	</note>
3174
3175	<para>
3176	Examples of using the <command>guestcontrol start</command>
3177	command are as follows:
3178	</para>
3179
3180	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
3181	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
3182
3183	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
3184	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
3185
3186	<para>
3187	Note that the double backslashes in the second example are
3188	only required on UNIX hosts.
3189	</para>
3190
3191	<note>
3192	<para>
3193	For certain commands a user name of an existing user account
3194	on the guest must be specified. Anonymous executions are not
3195	supported for security reasons. A user account password,
3196	however, is optional and depends on the guest's OS security
3197	policy or rules. If no password is specified for a given
3198	user name, an empty password will be used. On certain OSes
3199	like Windows the security policy may needs to be adjusted in
3200	order to allow user accounts with an empty password set.
3201	Also, global domain rules might apply and therefore cannot
3202	be changed.
3203	</para>
3204	</note>
3205
3206	<para>
3207	Starting at &product-name; 4.1.2 guest process execution by
3208	default is limited to serve up to five guest processes at a
3209	time. If a new guest process gets started which would exceed
3210	this limit, the oldest not running guest process will be
3211	discarded in order to be able to run that new process. Also,
3212	retrieving output from this old guest process will not be
3213	possible anymore then. If all five guest processes are still
3214	active and running, starting a new guest process will result
3215	in an appropriate error message.
3216	</para>
3217
3218	<para>
3219	To raise or lower the guest process execution limit, either
3220	use the guest property
3221	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
3222	or <command>VBoxService</command> command line by specifying
3223	<computeroutput>--control-procs-max-kept</computeroutput>
3224	needs to be modified. A restart of the guest OS is required
3225	afterwards. To serve unlimited guest processes, a value of
3226	<computeroutput>0</computeroutput> needs to be set, but this
3227	is not recommended.
3228	</para>
3229	</listitem>
3230
3231	<listitem>
3232	<para>
3233	<computeroutput>copyfrom</computeroutput>: Copies files from
3234	the guest to the host file system. Only available with Guest
3235	Additions 4.0 or later installed.
3236	</para>
3237
3238	<screen>VBoxManage guestcontrol <uuid\|vmname> copyfrom [common-options]
3239	[--follow] [--R\|recursive]
3240	--target-directory <host-dst-dir>
3241	<guest-src0> [<guest-src1> [...]] </screen>
3242
3243	<para>
3244	Where the parameters are as follows:
3245	</para>
3246
3247	<variablelist>
3248
3249	<varlistentry>
3250	<term>
3251	<computeroutput><uid\|vmname></computeroutput>
3252	</term>
3253
3254	<listitem>
3255	<para>
3256	Specifies the VM UUID or VM name. Mandatory.
3257	</para>
3258	</listitem>
3259	</varlistentry>
3260
3261	<varlistentry>
3262	<term>
3263	<computeroutput>--follow</computeroutput>
3264	</term>
3265
3266	<listitem>
3267	<para>
3268	Enables symlink following on the guest file system.
3269	Optional.
3270	</para>
3271	</listitem>
3272	</varlistentry>
3273
3274	<varlistentry>
3275	<term>
3276	<computeroutput>-R\|--recursive</computeroutput>
3277	</term>
3278
3279	<listitem>
3280	<para>
3281	Enables recursive copying of files and directories from
3282	the specified guest file system directory. Optional.
3283	</para>
3284	</listitem>
3285	</varlistentry>
3286
3287	<varlistentry>
3288	<term>
3289	<computeroutput>--target-directory
3290	<host-dst-dir></computeroutput>
3291	</term>
3292
3293	<listitem>
3294	<para>
3295	Specifies the absolute path of the host file system
3296	destination directory. Mandatory. For example:
3297	<filename>C:\Temp</filename>.
3298	</para>
3299	</listitem>
3300	</varlistentry>
3301
3302	<varlistentry>
3303	<term>
3304	<computeroutput><guest-src0> [<guest-src1>
3305	[...]]</computeroutput>
3306	</term>
3307
3308	<listitem>
3309	<para>
3310	Specifies the absolute paths of guest file system files
3311	to be copied. Mandatory. For example:
3312	<filename>C:\Windows\System32\calc.exe</filename>.
3313	Wildcards can be used in the expressions. For example:
3314	<filename>C:\Windows\System\.dll</filename>.
3315	</para>
3316	</listitem>
3317	</varlistentry>
3318
3319	</variablelist>
3320	</listitem>
3321
3322	<listitem>
3323	<para>
3324	<computeroutput>copyto</computeroutput>: Copies files from the
3325	host to the guest file system. Only available with Guest
3326	Additions 4.0 or later installed.
3327	</para>
3328
3329	<screen>VBoxManage guestcontrol <uuid\|vmname> copyto [common-options]
3330	[--follow] [--R\|recursive]
3331	--target-directory <guest-dst>
3332	<host-src0> [<host-src1> [...]] </screen>
3333
3334	<para>
3335	Where the parameters are as follows:
3336	</para>
3337
3338	<variablelist>
3339
3340	<varlistentry>
3341	<term>
3342	<computeroutput><uuid\|vmname></computeroutput>
3343	</term>
3344
3345	<listitem>
3346	<para>
3347	Specifies the VM UUID or VM name. Mandatory.
3348	</para>
3349	</listitem>
3350	</varlistentry>
3351
3352	<varlistentry>
3353	<term>
3354	<computeroutput>--follow</computeroutput>
3355	</term>
3356
3357	<listitem>
3358	<para>
3359	Enables symlink following on the host file system.
3360	Optional.
3361	</para>
3362	</listitem>
3363	</varlistentry>
3364
3365	<varlistentry>
3366	<term>
3367	<computeroutput>-R\|--recursive</computeroutput>
3368	</term>
3369
3370	<listitem>
3371	<para>
3372	Enables recursive copying of files and directories from
3373	the specified host file system directory. Optional.
3374	</para>
3375	</listitem>
3376	</varlistentry>
3377
3378	<varlistentry>
3379	<term>
3380	<computeroutput>--target-directory
3381	<guest-dst></computeroutput>
3382	</term>
3383
3384	<listitem>
3385	<para>
3386	Specifies the absolute path of the guest file system
3387	destination directory. Mandatory. For example:
3388	<filename>C:\Temp</filename>.
3389	</para>
3390	</listitem>
3391	</varlistentry>
3392
3393	<varlistentry>
3394	<term>
3395	<computeroutput><host-src0> [<host-src1>
3396	[...]]</computeroutput>
3397	</term>
3398
3399	<listitem>
3400	<para>
3401	Specifies the absolute paths of host file system files
3402	to be copied. Mandatory. For example:
3403	<filename>C:\Windows\System32\calc.exe</filename>.
3404	Wildcards can be used in the expressions. For example:
3405	<filename>C:\Windows\System\.dll</filename>.
3406	</para>
3407	</listitem>
3408	</varlistentry>
3409
3410	</variablelist>
3411	</listitem>
3412
3413	<listitem>
3414	<para>
3415	<computeroutput>md\|mkdir\|createdir\|createdirectory</computeroutput>:
3416	Creates one or more directories on the guest file system. Only
3417	available with Guest Additions 4.0 or later installed.
3418	</para>
3419
3420	<screen>VBoxManage guestcontrol <uuid\|vmname> md\|mkdir\|createdir\|createdirectory [common-options]
3421	[--parents] [--mode <mode>]
3422	<guest-dir0> [<guest-dir1> [...]] </screen>
3423
3424	<para>
3425	Where the parameters are as follows:
3426	</para>
3427
3428	<variablelist>
3429
3430	<varlistentry>
3431	<term>
3432	<computeroutput><uuid\|vmname></computeroutput>
3433	</term>
3434
3435	<listitem>
3436	<para>
3437	Specifies the VM UUID or VM name. Mandatory.
3438	</para>
3439	</listitem>
3440	</varlistentry>
3441
3442	<varlistentry>
3443	<term>
3444	<computeroutput>--parents</computeroutput>
3445	</term>
3446
3447	<listitem>
3448	<para>
3449	Creates any absent parent directories of the specified
3450	directory. Optional.
3451	</para>
3452
3453	<para>
3454	For example: If specified directory is
3455	<filename>D:\Foo\Bar</filename> and
3456	<filename>D:\Foo</filename> is absent, it will be
3457	created. In such a case, had the
3458	<computeroutput>--parents</computeroutput> option not
3459	been used, this command would have failed.
3460	</para>
3461	</listitem>
3462	</varlistentry>
3463
3464	<varlistentry>
3465	<term>
3466	<computeroutput>--mode <mode></computeroutput>
3467	</term>
3468
3469	<listitem>
3470	<para>
3471	Specifies the permission mode on the specified
3472	directories, and any parents, if the
3473	<computeroutput>--parents</computeroutput> option is
3474	used. Currently octal modes only, such as.
3475	<computeroutput>0755</computeroutput>, are supported.
3476	</para>
3477	</listitem>
3478	</varlistentry>
3479
3480	<varlistentry>
3481	<term>
3482	<computeroutput><guest-dir0> [<guest-dir1>
3483	[...]]</computeroutput>
3484	</term>
3485
3486	<listitem>
3487	<para>
3488	Specifies a list of absolute paths of directories to be
3489	created on guest file system. Mandatory. For example:
3490	<filename>D:\Foo\Bar</filename>.
3491	</para>
3492
3493	<para>
3494	All parent directories must already exist unless the
3495	switch <computeroutput>--parents</computeroutput> is
3496	used. For example, in the above example
3497	<filename>D:\Foo</filename>. The specified user must
3498	have sufficient rights to create the specified
3499	directories, and any parents that need to be created.
3500	</para>
3501	</listitem>
3502	</varlistentry>
3503
3504	</variablelist>
3505	</listitem>
3506
3507	<listitem>
3508	<para>
3509	<computeroutput>rmdir\|removedir\|removedirectory</computeroutput>:
3510	Deletes specified guest file system directories. Only
3511	available with installed Guest Additions 4.3.2 and later.
3512	</para>
3513
3514	<screen>VBoxManage guestcontrol <uuid\|vmname> rmdir\|removedir\|removedirectory [common-options]
3515	[--recursive\|-R]
3516	<guest-dir0> [<guest-dir1> [...]]
3517	</screen>
3518
3519	<para>
3520	Where the parameters are as follows:
3521	</para>
3522
3523	<variablelist>
3524
3525	<varlistentry>
3526	<term>
3527	<computeroutput><uuid\|vmname></computeroutput>
3528	</term>
3529
3530	<listitem>
3531	<para>
3532	Specifies the VM UUID or VM name. Mandatory.
3533	</para>
3534	</listitem>
3535	</varlistentry>
3536
3537	<varlistentry>
3538	<term>
3539	<computeroutput>--recursive</computeroutput>
3540	</term>
3541
3542	<listitem>
3543	<para>
3544	Recursively removes directories and contents. Optional.
3545	</para>
3546	</listitem>
3547	</varlistentry>
3548
3549	<varlistentry>
3550	<term>
3551	<computeroutput><guest-dir0> [<guest-dir1>
3552	[...]]</computeroutput>
3553	</term>
3554
3555	<listitem>
3556	<para>
3557	Specifies a list of the absolute paths of directories to
3558	be deleted on guest file system. Mandatory. Wildcards
3559	are allowed. For example:
3560	<filename>D:\Foo\*Bar</filename>. The specified user
3561	must have sufficient rights to delete the specified
3562	directories.
3563	</para>
3564	</listitem>
3565	</varlistentry>
3566
3567	</variablelist>
3568	</listitem>
3569
3570	<listitem>
3571	<para>
3572	<computeroutput>rm\|removefile</computeroutput>: Deletes
3573	specified files on the guest file system. Only available with
3574	installed Guest Additions 4.3.2 and later.
3575	</para>
3576
3577	<screen>VBoxManage guestcontrol <uuid\|vmname> rm\|removefile [common-options]
3578	[-f\|--force]
3579	<guest-file0> [<guest-file1> [...]] </screen>
3580
3581	<para>
3582	Where the parameters are as follows:
3583	</para>
3584
3585	<variablelist>
3586
3587	<varlistentry>
3588	<term>
3589	<computeroutput><uuid\|vmname></computeroutput>
3590	</term>
3591
3592	<listitem>
3593	<para>
3594	Specifies the VM UUID or VM name. Mandatory.
3595	</para>
3596	</listitem>
3597	</varlistentry>
3598
3599	<varlistentry>
3600	<term>
3601	<computeroutput>-f\|--force</computeroutput>
3602	</term>
3603
3604	<listitem>
3605	<para>
3606	Enforce operation and override any requests for
3607	confirmations. Optional.
3608	</para>
3609	</listitem>
3610	</varlistentry>
3611
3612	<varlistentry>
3613	<term>
3614	<computeroutput><guest-file0> [<guest-file1>
3615	[...]]</computeroutput>
3616	</term>
3617
3618	<listitem>
3619	<para>
3620	Specifies a list of absolute paths of files to be
3621	deleted on guest file system. Mandatory. Wildcards are
3622	allowed. For example:
3623	<filename>D:\Foo\Bar\text*.txt</filename>. The specified
3624	user should have sufficient rights to delete the
3625	specified files.
3626	</para>
3627	</listitem>
3628	</varlistentry>
3629
3630	</variablelist>
3631	</listitem>
3632
3633	<listitem>
3634	<para>
3635	<computeroutput>mv\|move\|ren\|rename</computeroutput>: Renames
3636	files and/or directories on the guest file system. Only
3637	available with installed Guest Additions 4.3.2 and later.
3638	</para>
3639
3640	<screen>VBoxManage guestcontrol <uuid\|vmname> mv\|move\|ren\|rename [common-options]
3641	<guest-source0> [<guest-source1> [...]] <guest-dest></screen>
3642
3643	<para>
3644	Where the parameters are as follows:
3645	</para>
3646
3647	<variablelist>
3648
3649	<varlistentry>
3650	<term>
3651	<computeroutput><uuid\|vmname></computeroutput>
3652	</term>
3653
3654	<listitem>
3655	<para>
3656	Specifies the VM UUID or VM name. Mandatory.
3657	</para>
3658	</listitem>
3659	</varlistentry>
3660
3661	<varlistentry>
3662	<term>
3663	<computeroutput><guest-source0>
3664	[<guest-source1> [...]]</computeroutput>
3665	</term>
3666
3667	<listitem>
3668	<para>
3669	Specifies absolute paths of files or a single directory
3670	to be moved and renamed on guest file system. Mandatory.
3671	Wildcards are allowed in file names. The specified user
3672	should have sufficient rights to access the specified
3673	files.
3674	</para>
3675	</listitem>
3676	</varlistentry>
3677
3678	<varlistentry>
3679	<term>
3680	<computeroutput><dest></computeroutput>
3681	</term>
3682
3683	<listitem>
3684	<para>
3685	Specifies the absolute path of the destination file or
3686	directory to which the files are to be moved. Mandatory.
3687	If only one file to be moved, <dest> can be file
3688	or directory, else it must be a directory. The specified
3689	user must have sufficient rights to access the
3690	destination file or directory.
3691	</para>
3692	</listitem>
3693	</varlistentry>
3694
3695	</variablelist>
3696	</listitem>
3697
3698	<listitem>
3699	<para>
3700	<computeroutput>mktemp\|createtemp\|createtemporary</computeroutput>:
3701	Creates a temporary file or directory on the guest file
3702	system, to assist subsequent copying of files from the host to
3703	the guest file systems. By default, the file or directory is
3704	created in the guest's platform specific temp directory. Not
3705	currently supported. Only available with installed Guest
3706	Additions 4.2 and later.
3707	</para>
3708
3709	<screen>VBoxManage guestcontrol <uuid\|vmname> mktemp\|createtemp\|createtemporary [common-options]
3710	[--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
3711	<template>
3712	</screen>
3713
3714	<para>
3715	The parameters are as follows:
3716	</para>
3717
3718	<variablelist>
3719
3720	<varlistentry>
3721	<term>
3722	<computeroutput><uuid\|vmname></computeroutput>
3723	</term>
3724
3725	<listitem>
3726	<para>
3727	Specifies the VM UUID or VM name. Mandatory.
3728	</para>
3729	</listitem>
3730	</varlistentry>
3731
3732	<varlistentry>
3733	<term>
3734	<computeroutput>--directory</computeroutput>
3735	</term>
3736
3737	<listitem>
3738	<para>
3739	Creates a temporary directory instead of a file,
3740	specified by the <template> parameter. Optional.
3741	</para>
3742	</listitem>
3743	</varlistentry>
3744
3745	<varlistentry>
3746	<term>
3747	<computeroutput>--secure</computeroutput>
3748	</term>
3749
3750	<listitem>
3751	<para>
3752	Enforces secure file and directory creation. Optional.
3753	The permission mode is set to
3754	<computeroutput>0755</computeroutput>. Operation fails
3755	if it cannot be performed securely.
3756	</para>
3757	</listitem>
3758	</varlistentry>
3759
3760	<varlistentry>
3761	<term>
3762	<computeroutput>--mode <mode></computeroutput>
3763	</term>
3764
3765	<listitem>
3766	<para>
3767	Specifies the permission mode of the specified
3768	directory. Optional. Currently only octal modes, such as
3769	<computeroutput>0755</computeroutput>, are supported.
3770	</para>
3771	</listitem>
3772	</varlistentry>
3773
3774	<varlistentry>
3775	<term>
3776	<computeroutput>--tmpdir
3777	<directory></computeroutput>
3778	</term>
3779
3780	<listitem>
3781	<para>
3782	Specifies the absolute path of the directory on the
3783	guest file system where the file or directory specified
3784	will be created. Optional. If unspecified, the
3785	platform-specific temp directory is used.
3786	</para>
3787	</listitem>
3788	</varlistentry>
3789
3790	<varlistentry>
3791	<term>
3792	<computeroutput><template></computeroutput>
3793	</term>
3794
3795	<listitem>
3796	<para>
3797	Specifies a file name without a directory path,
3798	containing at least one sequence of three consecutive X
3799	characters, or ending in X. Mandatory.
3800	</para>
3801	</listitem>
3802	</varlistentry>
3803
3804	</variablelist>
3805	</listitem>
3806
3807	<listitem>
3808	<para>
3809	<computeroutput>stat</computeroutput>: Displays file or file
3810	system statuses on the guest.
3811	</para>
3812
3813	<screen>VBoxManage guestcontrol <uuid\|vmname> stat [common-options]
3814	<file0> [<file1> [...]]</screen>
3815
3816	<para>
3817	Where the parameters are as follows:
3818	</para>
3819
3820	<variablelist>
3821
3822	<varlistentry>
3823	<term>
3824	<computeroutput><uuid\|vmname></computeroutput>
3825	</term>
3826
3827	<listitem>
3828	<para>
3829	Specifies the VM UUID or VM name. Mandatory.
3830	</para>
3831	</listitem>
3832	</varlistentry>
3833
3834	<varlistentry>
3835	<term>
3836	<computeroutput><file0> [<file1>
3837	[...]]</computeroutput>
3838	</term>
3839
3840	<listitem>
3841	<para>
3842	Specifies absolute paths of files or file systems on the
3843	guest file system. Mandatory. For example:
3844	<filename>/home/foo/a.out</filename>. The specified user
3845	should have sufficient rights to access the specified
3846	files or file systems.
3847	</para>
3848	</listitem>
3849	</varlistentry>
3850
3851	</variablelist>
3852	</listitem>
3853
3854	</itemizedlist>
3855
3856	<para>
3857	The second set of subcommands is of the form:
3858	</para>
3859
3860	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
3861	[-v\|--verbose] [-q\|quiet] ...
3862	</screen>
3863
3864	<para>
3865	The common options are as follows:
3866	</para>
3867
3868	<screen>
3869	[-v\|--verbose] [-q\|--quiet]
3870	</screen>
3871
3872	<para>
3873	Details of the common options for the second set of subcommands
3874	are as follows:
3875	</para>
3876
3877	<variablelist>
3878
3879	<varlistentry>
3880	<term>
3881	<computeroutput>-v\|--verbose</computeroutput>
3882	</term>
3883
3884	<listitem>
3885	<para>
3886	Makes the subcommand execution more verbose. Optional.
3887	</para>
3888	</listitem>
3889	</varlistentry>
3890
3891	<varlistentry>
3892	<term>
3893	<computeroutput>-q\|--quiet</computeroutput>
3894	</term>
3895
3896	<listitem>
3897	<para>
3898	Makes the subcommand execution quieter. Optional.
3899	</para>
3900	</listitem>
3901	</varlistentry>
3902
3903	</variablelist>
3904
3905	<para>
3906	The second set of subcommands are as follows:
3907	</para>
3908
3909	<itemizedlist>
3910
3911	<listitem>
3912	<para>
3913	<computeroutput>list</computeroutput>: Lists guest control
3914	configuration and status data. For example: open guest
3915	sessions, guest processes, and files.
3916	</para>
3917
3918	<screen>VBoxManage guestcontrol <uuid\|vmname> list [common-opts]
3919	<all\|sessions\|processes\|files> </screen>
3920
3921	<para>
3922	Where the parameters are as follows:
3923	</para>
3924
3925	<variablelist>
3926
3927	<varlistentry>
3928	<term>
3929	<computeroutput><uuid\|vmname></computeroutput>
3930	</term>
3931
3932	<listitem>
3933	<para>
3934	Specifies the VM UUID or VM name. Mandatory.
3935	</para>
3936	</listitem>
3937	</varlistentry>
3938
3939	<varlistentry>
3940	<term>
3941	<computeroutput>all\|sessions\|processes\|files</computeroutput>
3942	</term>
3943
3944	<listitem>
3945	<para>
3946	Indicates whether to list all available data or guest
3947	sessions, processes or files. Mandatory.
3948	</para>
3949	</listitem>
3950	</varlistentry>
3951
3952	</variablelist>
3953	</listitem>
3954
3955	<listitem>
3956	<para>
3957	<computeroutput>closeprocess</computeroutput>: Terminates
3958	guest processes specified by PIDs running in a guest session,
3959	specified by the session ID or name.
3960	</para>
3961
3962	<screen>VBoxManage guestcontrol <uuid\|vmname> closeprocess [common-options]
3963	--session-id <ID> \| --session-name <name or pattern>
3964	<PID0> [<PID1> [...]] </screen>
3965
3966	<para>
3967	Where the parameters are as follows:
3968	</para>
3969
3970	<variablelist>
3971
3972	<varlistentry>
3973	<term>
3974	<computeroutput><uuid\|vmname></computeroutput>
3975	</term>
3976
3977	<listitem>
3978	<para>
3979	Specifies the VM UUID or VM name. Mandatory.
3980	</para>
3981	</listitem>
3982	</varlistentry>
3983
3984	<varlistentry>
3985	<term>
3986	<computeroutput>--session-id <ID></computeroutput>
3987	</term>
3988
3989	<listitem>
3990	<para>
3991	Specifies the guest session by its ID. Optional.
3992	</para>
3993	</listitem>
3994	</varlistentry>
3995
3996	<varlistentry>
3997	<term>
3998	<computeroutput>--session-name <name or
3999	pattern></computeroutput>
4000	</term>
4001
4002	<listitem>
4003	<para>
4004	Specifies the guest session by its name, or multiple
4005	sessions using a pattern containing wildcards. Optional.
4006	</para>
4007	</listitem>
4008	</varlistentry>
4009
4010	<varlistentry>
4011	<term>
4012	<computeroutput><PID0> [<PID1>
4013	[...]]</computeroutput>
4014	</term>
4015
4016	<listitem>
4017	<para>
4018	Specifies a list of process identifiers (PIDs) of guest
4019	processes to be terminated. Mandatory.
4020	</para>
4021	</listitem>
4022	</varlistentry>
4023
4024	</variablelist>
4025	</listitem>
4026
4027	<listitem>
4028	<para>
4029	<computeroutput>closesession</computeroutput>: Closes
4030	specified guest sessions, specified either by session ID or
4031	name.
4032	</para>
4033
4034	<screen>VBoxManage guestcontrol <uuid\|vmname> closesession [common-options]
4035	--session-id <ID> \| --session-name <name or pattern> \| --all </screen>
4036
4037	<para>
4038	Where the parameters are as follows:
4039	</para>
4040
4041	<variablelist>
4042
4043	<varlistentry>
4044	<term>
4045	<computeroutput><uuid\|vmname></computeroutput>
4046	</term>
4047
4048	<listitem>
4049	<para>
4050	Specifies the VM UUID or VM name. Mandatory.
4051	</para>
4052	</listitem>
4053	</varlistentry>
4054
4055	<varlistentry>
4056	<term>
4057	<computeroutput>--session-id <ID></computeroutput>
4058	</term>
4059
4060	<listitem>
4061	<para>
4062	Specifies the guest session to be closed by ID.
4063	Optional.
4064	</para>
4065	</listitem>
4066	</varlistentry>
4067
4068	<varlistentry>
4069	<term>
4070	<computeroutput>--session-name <name or
4071	pattern></computeroutput>
4072	</term>
4073
4074	<listitem>
4075	<para>
4076	Specifies the guest session to be closed by name.
4077	Optional. Multiple sessions can be specified by using a
4078	pattern containing wildcards.
4079	</para>
4080	</listitem>
4081	</varlistentry>
4082
4083	<varlistentry>
4084	<term>
4085	<computeroutput>--all</computeroutput>
4086	</term>
4087
4088	<listitem>
4089	<para>
4090	Close all guest sessions. Optional.
4091	</para>
4092	</listitem>
4093	</varlistentry>
4094
4095	</variablelist>
4096	</listitem>
4097
4098	<listitem>
4099	<para>
4100	<computeroutput>updatega\|updateadditions\|updateguestadditions</computeroutput>:
4101	Ugrades Guest Additions already installed on the guest. Only
4102	available for already installed Guest Additions 4.0 and later.
4103	</para>
4104
4105	<screen>VBoxManage guestcontrol <uuid\|vmname> updatega\|updateadditions\|updateguestadditions
4106	[common-options]
4107	[--source <New .ISO path>]
4108	[--wait-start]
4109	[-- <argument0> [<argument1> [...]]]</screen>
4110
4111	<para>
4112	Where the parameters are as follows:
4113	</para>
4114
4115	<variablelist>
4116
4117	<varlistentry>
4118	<term>
4119	<computeroutput><uuid\|vmname></computeroutput>
4120	</term>
4121
4122	<listitem>
4123	<para>
4124	Specifies the VM UUID or VM name. Mandatory.
4125	</para>
4126	</listitem>
4127	</varlistentry>
4128
4129	<varlistentry>
4130	<term>
4131	<computeroutput>--source</computeroutput> <New .ISO
4132	path>
4133	</term>
4134
4135	<listitem>
4136	<para>
4137	Specifies the absolute path on the guest file system of
4138	the .ISO file for the Guest Additions update. Mandatory.
4139	</para>
4140	</listitem>
4141	</varlistentry>
4142
4143	<varlistentry>
4144	<term>
4145	<computeroutput>--wait-start</computeroutput>
4146	</term>
4147
4148	<listitem>
4149	<para>
4150	Indicates that <command>VBoxManage</command> starts the
4151	usual updating process on the guest and then waits until
4152	the actual Guest Additions updating begins, at which
4153	point <command>VBoxManage</command> self-terminates.
4154	Optional.
4155	</para>
4156
4157	<para>
4158	Default behavior is that <command>VBoxManage</command>
4159	waits for completion of the Guest Additions update
4160	before terminating. Use of this option is sometimes
4161	necessary, as a running <command>VBoxManage</command>
4162	can affect the interaction between the installer and the
4163	guest OS.
4164	</para>
4165	</listitem>
4166	</varlistentry>
4167
4168	<varlistentry>
4169	<term>
4170	<computeroutput>[-- <argument0> [<argument1>
4171	[...]]]</computeroutput>
4172	</term>
4173
4174	<listitem>
4175	<para>
4176	Specifies optional command line arguments to be supplied
4177	to the Guest Additions updater. Useful for retrofitting
4178	features which are not currently installed.
4179	</para>
4180
4181	<para>
4182	Arguments containing spaces should be enclosed by
4183	quotes.
4184	</para>
4185	</listitem>
4186	</varlistentry>
4187
4188	</variablelist>
4189	</listitem>
4190
4191	<listitem>
4192	<para>
4193	<computeroutput>watch</computeroutput>: Prints current guest
4194	control activity.
4195	</para>
4196
4197	<screen>VBoxManage guestcontrol <uuid\|vmname> watch [common-options]
4198	</screen>
4199
4200	<para>
4201	Where the parameters are as follows:
4202	</para>
4203
4204	<variablelist>
4205
4206	<varlistentry>
4207	<term>
4208	<computeroutput><uuid\|vmname></computeroutput>
4209	</term>
4210
4211	<listitem>
4212	<para>
4213	Specifies the VM UUID or VM name. Mandatory.
4214	</para>
4215	</listitem>
4216	</varlistentry>
4217
4218	</variablelist>
4219	</listitem>
4220
4221	</itemizedlist>
4222
4223	</sect1>
4224
4225	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
4226
4227	<sect1 id="vboxmanage-metrics">
4228
4229	<title>VBoxManage metrics</title>
4230
4231	<para>
4232	This command supports monitoring the usage of system resources.
4233	Resources are represented by various metrics associated with the
4234	host system or a particular VM. For example, the host system has a
4235	<computeroutput>CPU/Load/User</computeroutput> metric that shows
4236	the percentage of time CPUs spend executing in user mode over a
4237	specific sampling period.
4238	</para>
4239
4240	<para>
4241	Metric data is collected and retained internally. It may be
4242	retrieved at any time with the <command>VBoxManage metrics
4243	query</command> subcommand. The data is available as long as the
4244	background <computeroutput>VBoxSVC</computeroutput> process is
4245	alive. That process terminates shortly after all VMs and frontends
4246	have been closed.
4247	</para>
4248
4249	<para>
4250	By default no metrics are collected at all. Metrics collection
4251	does not start until <command>VBoxManage metrics setup</command>
4252	is invoked with a proper sampling interval and the number of
4253	metrics to be retained. The interval is measured in seconds. For
4254	example, to enable collecting the host processor and memory usage
4255	metrics every second and keeping the five most current samples,
4256	the following command can be used:
4257	</para>
4258
4259	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
4260
4261	<para>
4262	Metric collection can only be enabled for started VMs. Collected
4263	data and collection settings for a particular VM will disappear as
4264	soon as it shuts down. Use the <command>VBoxManage metrics
4265	list</command> subcommand to see which metrics are currently
4266	available. You can also use the <option>--list</option> option
4267	with any subcommand that modifies metric settings to find out
4268	which metrics were affected.
4269	</para>
4270
4271	<para>
4272	Note that the <command>VBoxManage metrics setup</command>
4273	subcommand discards all samples that may have been previously
4274	collected for the specified set of objects and metrics.
4275	</para>
4276
4277	<para>
4278	To enable or disable metrics collection without discarding the
4279	data, <command>VBoxManage metrics enable</command> and
4280	<command>VBoxManage metrics disable</command> subcommands can be
4281	used. Note that these subcommands expect metrics as parameters,
4282	not submetrics such as <computeroutput>CPU/Load</computeroutput>
4283	or <computeroutput>RAM/Usage</computeroutput>. In other words
4284	enabling <computeroutput>CPU/Load/User</computeroutput> while
4285	disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not
4286	supported.
4287	</para>
4288
4289	<para>
4290	The host and VMs have different sets of associated metrics.
4291	Available metrics can be listed with <command>VBoxManage metrics
4292	list</command> subcommand.
4293	</para>
4294
4295	<para>
4296	A complete metric name may include an aggregate function. The name
4297	has the following form:
4298	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
4299	For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
4300	stands for the minimum amount of available memory over all
4301	retained data if applied to the host object.
4302	</para>
4303
4304	<para>
4305	Subcommands may apply to all objects and metrics or can be limited
4306	to one object and a list of metrics. If no objects or metrics are
4307	given in the parameters, the subcommands will apply to all
4308	available metrics of all objects. You may use an asterisk
4309	"<computeroutput>*</computeroutput>" to explicitly specify that
4310	the command should be applied to all objects or metrics. Use
4311	<computeroutput>host</computeroutput> as the object name to limit
4312	the scope of the command to host-related metrics. To limit the
4313	scope to a subset of metrics, use a metric list with names
4314	separated by commas.
4315	</para>
4316
4317	<para>
4318	For example, to query metric data on the CPU time spent in user
4319	and kernel modes by the virtual machine named
4320	<computeroutput>test</computeroutput>, use the following command:
4321	</para>
4322
4323	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
4324
4325	<para>
4326	The following list summarizes the available subcommands:
4327	</para>
4328
4329	<variablelist>
4330
4331	<varlistentry>
4332	<term>
4333	<computeroutput>list</computeroutput>
4334	</term>
4335
4336	<listitem>
4337	<para>
4338	Shows the parameters of the currently existing metrics. Note
4339	that VM-specific metrics are only available when a
4340	particular VM is running.
4341	</para>
4342	</listitem>
4343	</varlistentry>
4344
4345	<varlistentry>
4346	<term>
4347	<computeroutput>setup</computeroutput>
4348	</term>
4349
4350	<listitem>
4351	<para>
4352	Sets the interval between taking two samples of metric data
4353	and the number of samples retained internally. The retained
4354	data is available for displaying with the
4355	<command>query</command> subcommand. The
4356	<computeroutput>--list</computeroutput> option shows which
4357	metrics have been modified as the result of the command
4358	execution.
4359	</para>
4360	</listitem>
4361	</varlistentry>
4362
4363	<varlistentry>
4364	<term>
4365	<computeroutput>enable</computeroutput>
4366	</term>
4367
4368	<listitem>
4369	<para>
4370	Resumes data collection after it has been stopped with the
4371	<command>disable</command> subcommand. Note that specifying
4372	submetrics as parameters will not enable underlying metrics.
4373	Use <computeroutput>--list</computeroutput> to find out if
4374	the command worked as expected.
4375	</para>
4376	</listitem>
4377	</varlistentry>
4378
4379	<varlistentry>
4380	<term>
4381	<computeroutput>disable</computeroutput>
4382	</term>
4383
4384	<listitem>
4385	<para>
4386	Suspends data collection without affecting collection
4387	parameters or collected data. Note that specifying
4388	submetrics as parameters will not disable underlying
4389	metrics. Use <computeroutput>--list</computeroutput> to find
4390	out if the command worked as expected.
4391	</para>
4392	</listitem>
4393	</varlistentry>
4394
4395	<varlistentry>
4396	<term>
4397	<computeroutput>query</computeroutput>
4398	</term>
4399
4400	<listitem>
4401	<para>
4402	Retrieves and displays the currently retained metric data.
4403	</para>
4404
4405	<note>
4406	<para>
4407	The <command>query</command> subcommand does not remove or
4408	flush retained data. If you query often enough you will
4409	see how old samples are gradually being phased out by new
4410	samples.
4411	</para>
4412	</note>
4413	</listitem>
4414	</varlistentry>
4415
4416	<varlistentry>
4417	<term>
4418	<computeroutput>collect</computeroutput>
4419	</term>
4420
4421	<listitem>
4422	<para>
4423	Sets the interval between taking two samples of metric data
4424	and the number of samples retained internally. The collected
4425	data is displayed periodically until Ctrl+C is pressed,
4426	unless the <computeroutput>--detach</computeroutput> option
4427	is specified. With the
4428	<computeroutput>--detach</computeroutput> option, this
4429	subcommand operates the same way as
4430	<computeroutput>setup</computeroutput> does. The
4431	<computeroutput>--list</computeroutput> option shows which
4432	metrics match the specified filter.
4433	</para>
4434	</listitem>
4435	</varlistentry>
4436
4437	</variablelist>
4438
4439	</sect1>
4440
4441	<sect1 id="vboxmanage-natnetwork">
4442
4443	<title>VBoxManage natnetwork</title>
4444
4445	<para>
4446	NAT networks use the Network Address Translation (NAT) service,
4447	which works in a similar way to a home router. It groups systems
4448	using it into a network and prevents outside systems from directly
4449	accessing those inside, while letting systems inside communicate
4450	with each other and outside systems using TCP and UDP over IPv4
4451	and IPv6.
4452	</para>
4453
4454	<para>
4455	A NAT service is attached to an internal network. Virtual machines
4456	to make use of one should be attached to it. The name of an
4457	internal network is chosen when the NAT service is created, and
4458	the internal network will be created if it does not already exist.
4459	The following is an example command to create a NAT network:
4460	</para>
4461
4462	<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
4463
4464	<para>
4465	Here, <computeroutput>natnet1</computeroutput> is the name of the
4466	internal network to be used and
4467	<computeroutput>192.168.15.0/24</computeroutput> is the network
4468	address and mask of the NAT service interface. By default, in this
4469	static configuration the gateway will be assigned the address
4470	192.168.15.1, the address after the interface address, though this
4471	is subject to change.
4472	</para>
4473
4474	<para>
4475	To add a DHCP server to the NAT network after creation, run the
4476	following command:
4477	</para>
4478
4479	<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
4480
4481	<para>
4482	The subcommands for <command>VBoxManage natnetwork</command> are
4483	as follows:
4484	</para>
4485
4486	<screen>VBoxManage natnetwork add --netname <name>
4487	[--network <network>]
4488	[--enable\|--disable]
4489	[--dhcp on\|off]
4490	[--port-forward-4 <rule>]
4491	[--loopback-4 <rule>]
4492	[--ipv6 on\|off]
4493	[--port-forward-6 <rule>]
4494	[--loopback-6 <rule>]
4495	</screen>
4496
4497	<para>
4498	<command>VBoxManage natnetwork add</command>: Creates a new
4499	internal network interface, and adds a NAT network service. This
4500	command is a prerequisite for enabling attachment of VMs to the
4501	NAT network. Parameters are as follows:
4502	</para>
4503
4504	<variablelist>
4505
4506	<varlistentry>
4507	<term>
4508	<computeroutput>--netname <name></computeroutput>
4509	</term>
4510
4511	<listitem>
4512	<para>
4513	Where <name> is the name of the new internal network
4514	interface on the host OS.
4515	</para>
4516	</listitem>
4517	</varlistentry>
4518
4519	<varlistentry>
4520	<term>
4521	<computeroutput>--network <network></computeroutput>
4522	</term>
4523
4524	<listitem>
4525	<para>
4526	Where <network> specifies the static or DHCP network
4527	address and mask of the NAT service interface. The default
4528	is a static network address.
4529	</para>
4530	</listitem>
4531	</varlistentry>
4532
4533	<varlistentry>
4534	<term>
4535	<computeroutput>--enable\|--disable</computeroutput>
4536	</term>
4537
4538	<listitem>
4539	<para>
4540	Enables and disables the NAT network service.
4541	</para>
4542	</listitem>
4543	</varlistentry>
4544
4545	<varlistentry>
4546	<term>
4547	<computeroutput>--dhcp on\|off</computeroutput>
4548	</term>
4549
4550	<listitem>
4551	<para>
4552	Enables and disables a DHCP server specified by
4553	<computeroutput>--netname</computeroutput>. Use of this
4554	option also indicates that it is a DHCP server.
4555	</para>
4556	</listitem>
4557	</varlistentry>
4558
4559	<varlistentry>
4560	<term>
4561	<computeroutput>--port-forward-4 <rule></computeroutput>
4562	</term>
4563
4564	<listitem>
4565	<para>
4566	Enables IPv4 port forwarding, with a rule specified by
4567	<rule>.
4568	</para>
4569	</listitem>
4570	</varlistentry>
4571
4572	<varlistentry>
4573	<term>
4574	<computeroutput>--loopback-4 <rule></computeroutput>
4575	</term>
4576
4577	<listitem>
4578	<para>
4579	Enables the IPv4 loopback interface, with a rule specified
4580	by <rule>.
4581	</para>
4582	</listitem>
4583	</varlistentry>
4584
4585	<varlistentry>
4586	<term>
4587	<computeroutput>--ipv6 on\|off</computeroutput>
4588	</term>
4589
4590	<listitem>
4591	<para>
4592	Enables and disables IPv6. The default setting is IPv4,
4593	disabling IPv6 enables IPv4.
4594	</para>
4595	</listitem>
4596	</varlistentry>
4597
4598	<varlistentry>
4599	<term>
4600	<computeroutput>--port-forward-6 <rule></computeroutput>
4601	</term>
4602
4603	<listitem>
4604	<para>
4605	Enables IPv6 port forwarding, with a rule specified by
4606	<rule>.
4607	</para>
4608	</listitem>
4609	</varlistentry>
4610
4611	<varlistentry>
4612	<term>
4613	<computeroutput>--loopback-6 <rule></computeroutput>
4614	</term>
4615
4616	<listitem>
4617	<para>
4618	Enables the IPv6 loopback interface, with a rule specified
4619	by <rule>.
4620	</para>
4621	</listitem>
4622	</varlistentry>
4623
4624	</variablelist>
4625
4626	<screen>VBoxManage natnetwork remove --netname <name> </screen>
4627
4628	<para>
4629	<command>VBoxManage natnetwork remove</command>: Removes a NAT
4630	network service. Parameters are as follows:
4631	</para>
4632
4633	<variablelist>
4634
4635	<varlistentry>
4636	<term>
4637	<computeroutput>--netname <name></computeroutput>
4638	</term>
4639
4640	<listitem>
4641	<para>
4642	Where <name> specifies an existing NAT network
4643	service. Does not remove any DHCP server enabled on the
4644	network.
4645	</para>
4646	</listitem>
4647	</varlistentry>
4648
4649	</variablelist>
4650
4651	<screen>VBoxManage natnetwork modify --netname <name>
4652	[--network <network>]
4653	[--enable\|--disable]
4654	[--dhcp on\|off]
4655	[--port-forward-4 <rule>]
4656	[--loopback-4 <rule>]
4657	[--ipv6 on\|off]
4658	[--port-forward-6 <rule>]
4659	[--loopback-6 <rule>]
4660	</screen>
4661
4662	<para>
4663	<command>VBoxManage natnetwork modify</command>: Modifies an
4664	existing NAT network service. Parameters are as follows:
4665	</para>
4666
4667	<variablelist>
4668
4669	<varlistentry>
4670	<term>
4671	<computeroutput>--netname <name></computeroutput>
4672	</term>
4673
4674	<listitem>
4675	<para>
4676	Where <name> specifies an existing NAT network
4677	service.
4678	</para>
4679	</listitem>
4680	</varlistentry>
4681
4682	<varlistentry>
4683	<term>
4684	<computeroutput>--network <network></computeroutput>
4685	</term>
4686
4687	<listitem>
4688	<para>
4689	Where <network> specifies the new static or DHCP
4690	network address and mask of the NAT service interface. The
4691	default is a static network address.
4692	</para>
4693	</listitem>
4694	</varlistentry>
4695
4696	<varlistentry>
4697	<term>
4698	<computeroutput>--enable\|--disable</computeroutput>
4699	</term>
4700
4701	<listitem>
4702	<para>
4703	Enables and disables the NAT network service.
4704	</para>
4705	</listitem>
4706	</varlistentry>
4707
4708	<varlistentry>
4709	<term>
4710	<computeroutput>--dhcp on\|off</computeroutput>
4711	</term>
4712
4713	<listitem>
4714	<para>
4715	Enables and disables a DHCP server. If a DHCP server is not
4716	present, using enable adds a new DHCP server.
4717	</para>
4718	</listitem>
4719	</varlistentry>
4720
4721	<varlistentry>
4722	<term>
4723	<computeroutput>--port-forward-4 <rule></computeroutput>
4724	</term>
4725
4726	<listitem>
4727	<para>
4728	Enables IPv4 port forwarding, with a rule specified by
4729	<rule>.
4730	</para>
4731	</listitem>
4732	</varlistentry>
4733
4734	<varlistentry>
4735	<term>
4736	<computeroutput>--loopback-4 <rule></computeroutput>
4737	</term>
4738
4739	<listitem>
4740	<para>
4741	Enables the IPv4 loopback interface, with a rule specified
4742	by <rule>.
4743	</para>
4744	</listitem>
4745	</varlistentry>
4746
4747	<varlistentry>
4748	<term>
4749	<computeroutput>--ipv6 on\|off</computeroutput>
4750	</term>
4751
4752	<listitem>
4753	<para>
4754	Enables and disables IPv6. The default setting is IPv4,
4755	disabling IPv6 enables IPv4.
4756	</para>
4757	</listitem>
4758	</varlistentry>
4759
4760	<varlistentry>
4761	<term>
4762	<computeroutput>--port-forward-6 <rule></computeroutput>
4763	</term>
4764
4765	<listitem>
4766	<para>
4767	Enables IPv6 port forwarding, with a rule specified by
4768	<rule>.
4769	</para>
4770	</listitem>
4771	</varlistentry>
4772
4773	<varlistentry>
4774	<term>
4775	<computeroutput>--loopback-6 <rule></computeroutput>
4776	</term>
4777
4778	<listitem>
4779	<para>
4780	Enables IPv6 loopback interface, with a rule specified by
4781	<rule>.
4782	</para>
4783	</listitem>
4784	</varlistentry>
4785
4786	</variablelist>
4787
4788	<screen>VBoxManage natnetwork start --netname <name>
4789	</screen>
4790
4791	<para>
4792	<command>VBoxManage natnetwork start</command>: Starts the
4793	specified NAT network service and any associated DHCP server.
4794	Parameters are as follows:
4795	</para>
4796
4797	<variablelist>
4798
4799	<varlistentry>
4800	<term>
4801	<computeroutput>--netname <name></computeroutput>
4802	</term>
4803
4804	<listitem>
4805	<para>
4806	Where <name> specifies an existing NAT network
4807	service.
4808	</para>
4809	</listitem>
4810	</varlistentry>
4811
4812	</variablelist>
4813
4814	<screen>VBoxManage natnetwork stop --netname <name>
4815	</screen>
4816
4817	<para>
4818	<command>VBoxManage natnetwork stop</command>: Stops the specified
4819	NAT network service and any DHCP server. Parameters are as
4820	follows:
4821	</para>
4822
4823	<variablelist>
4824
4825	<varlistentry>
4826	<term>
4827	<computeroutput>--netname <name></computeroutput>
4828	</term>
4829
4830	<listitem>
4831	<para>
4832	Where <name> specifies an existing NAT network
4833	service.
4834	</para>
4835	</listitem>
4836	</varlistentry>
4837
4838	</variablelist>
4839
4840	<screen>VBoxManage natnetwork list [<pattern>] </screen>
4841
4842	<para>
4843	<command>VBoxManage natnetwork list</command>: Lists all NAT
4844	network services, with optional filtering. Parameters are as
4845	follows:
4846	</para>
4847
4848	<variablelist>
4849
4850	<varlistentry>
4851	<term>
4852	<computeroutput>[<pattern>]</computeroutput>
4853	</term>
4854
4855	<listitem>
4856	<para>
4857	Where <pattern> is an optional filtering pattern.
4858	</para>
4859	</listitem>
4860	</varlistentry>
4861
4862	</variablelist>
4863
4864	</sect1>
4865
4866	<sect1 id="vboxmanage-hostonlyif">
4867
4868	<title>VBoxManage hostonlyif</title>
4869
4870	<para>
4871	The <command>hostonlyif</command> command enables you to change
4872	the IP configuration of a host-only network interface. For a
4873	description of host-only networking, see
4874	<xref linkend="network_hostonly" />. Each host-only interface is
4875	identified by a name and can either use the internal DHCP server
4876	or a manual IP configuration, both IP4 and IP6.
4877	</para>
4878
4879	<para>
4880	The following list summarizes the available subcommands:
4881	</para>
4882
4883	<variablelist>
4884
4885	<varlistentry>
4886	<term>
4887	<computeroutput>ipconfig "<name>"</computeroutput>
4888	</term>
4889
4890	<listitem>
4891	<para>
4892	Configures a host-only interface.
4893	</para>
4894	</listitem>
4895	</varlistentry>
4896
4897	<varlistentry>
4898	<term>
4899	<computeroutput>create</computeroutput>
4900	</term>
4901
4902	<listitem>
4903	<para>
4904	Creates a new vboxnet<N> interface on the host OS.
4905	This command is essential before you can attach VMs to a
4906	host-only network.
4907	</para>
4908	</listitem>
4909	</varlistentry>
4910
4911	<varlistentry>
4912	<term>
4913	<computeroutput>remove vboxnet<N></computeroutput>
4914	</term>
4915
4916	<listitem>
4917	<para>
4918	Removes a vboxnet<N> interface from the host OS.
4919	</para>
4920	</listitem>
4921	</varlistentry>
4922
4923	</variablelist>
4924
4925	</sect1>
4926
4927	<xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
4928
4929	<xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
4930
4931	<sect1 id="vboxmanage-usbdevsource">
4932
4933	<title>VBoxManage usbdevsource</title>
4934
4935	<para>
4936	The <command>usbdevsource</command> commands enable you to add and
4937	remove USB devices globally.
4938	</para>
4939
4940	<para>
4941	The following command adds a USB device.
4942	</para>
4943
4944	<screen>VBoxManage usbdevsource add <source name>
4945	--backend <backend>
4946	--address <address>
4947	</screen>
4948
4949	<para>
4950	Where the command line options are as follows:
4951	</para>
4952
4953	<itemizedlist>
4954
4955	<listitem>
4956	<para>
4957	<computeroutput><source name></computeroutput>:
4958	Specifies the ID of the source USB device to be added.
4959	Mandatory.
4960	</para>
4961	</listitem>
4962
4963	<listitem>
4964	<para>
4965	<computeroutput>--backend <backend></computeroutput>:
4966	Specifies the USB proxy service backend to use. Mandatory.
4967	</para>
4968	</listitem>
4969
4970	<listitem>
4971	<para>
4972	<computeroutput> --address <address></computeroutput>:
4973	Specifies the backend specific address. Mandatory.
4974	</para>
4975	</listitem>
4976
4977	</itemizedlist>
4978
4979	<para>
4980	The following command removes a USB device.
4981	</para>
4982
4983	<screen>VBoxManage usbdevsource remove <source name>
4984	</screen>
4985
4986	<para>
4987	Where the command line options are as follows:
4988	</para>
4989
4990	<itemizedlist>
4991
4992	<listitem>
4993	<para>
4994	<computeroutput><source name></computeroutput>:
4995	Specifies the ID of the source USB device to be removed.
4996	Mandatory.
4997	</para>
4998	</listitem>
4999
5000	</itemizedlist>
5001
5002	</sect1>
5003
5004	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
5005
5006	<xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
5007
5008	<xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
5009
5010	<!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
5011	sect1, so it's not possible to have them "in place" -->
5012
5013	<xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
5014
5015	</chapter>

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

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

Download in other formats: