user_VBoxManage.xml@ 94207

Last change on this file since 94207 was 94207, checked in by vboxsync, 3 years ago
doc/manual,FE/VBoxManage: Convert usbfilter command to refentry documentation, bugref:9186
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 116.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	<xi:include href="user_man_VBoxManage-adoptstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
342
343	<xi:include href="user_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
344
345	<xi:include href="user_man_VBoxManage-closemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
346
347	<sect1 id="vboxmanage-storageattach">
348
349	<title>VBoxManage storageattach</title>
350
351	<para>
352	This command attaches, modifies, and removes a storage medium
353	connected to a storage controller that was previously added with
354	the <command>storagectl</command> command. The syntax is as
355	follows:
356	</para>
357
358	<screen>VBoxManage storageattach <uuid\|vmname>
359	--storagectl <name>
360	[--port <number>]
361	[--device <number>]
362	[--type dvddrive\|hdd\|fdd]
363	[--medium none\|emptydrive\|additions\|
364	<uuid>\|<filename>\|host:<drive>\|iscsi]
365	[--mtype normal\|writethrough\|immutable\|shareable
366	readonly\|multiattach]
367	[--comment <text>]
368	[--setuuid <uuid>]
369	[--setparentuuid <uuid>]
370	[--passthrough on\|off]
371	[--tempeject on\|off]
372	[--nonrotational on\|off]
373	[--discard on\|off]
374	[--hotpluggable on\|off]
375	[--bandwidthgroup name\|none]
376	[--forceunmount]
377	[--server <name>\|<ip>]
378	[--target <target>]
379	[--tport <port>]
380	[--lun <lun>]
381	[--encodedlun <lun>]
382	[--username <username>]
383	[--password <password>]
384	[--passwordfile <file>]
385	[--initiator <initiator>]
386	[--intnet]</screen>
387
388	<para>
389	A number of parameters are commonly required. Some parameters are
390	required only for iSCSI targets.
391	</para>
392
393	<para>
394	The common parameters are as follows:
395	</para>
396
397	<variablelist>
398
399	<varlistentry>
400	<term>
401	<computeroutput>uuid\|vmname</computeroutput>
402	</term>
403
404	<listitem>
405	<para>
406	The VM UUID or VM Name. Mandatory.
407	</para>
408	</listitem>
409	</varlistentry>
410
411	<varlistentry>
412	<term>
413	<computeroutput>--storagectl</computeroutput>
414	</term>
415
416	<listitem>
417	<para>
418	Name of the storage controller. Mandatory. The list of the
419	storage controllers currently attached to a VM can be
420	obtained with <command>VBoxManage showvminfo</command>. See
421	<xref linkend="vboxmanage-showvminfo" />.
422	</para>
423	</listitem>
424	</varlistentry>
425
426	<varlistentry>
427	<term>
428	<computeroutput>--port</computeroutput>
429	</term>
430
431	<listitem>
432	<para>
433	The number of the storage controller's port which is to be
434	modified. Mandatory, unless the storage controller has only
435	a single port.
436	</para>
437	</listitem>
438	</varlistentry>
439
440	<varlistentry>
441	<term>
442	<computeroutput>--device</computeroutput>
443	</term>
444
445	<listitem>
446	<para>
447	The number of the port's device which is to be modified.
448	Mandatory, unless the storage controller has only a single
449	device per port.
450	</para>
451	</listitem>
452	</varlistentry>
453
454	<varlistentry>
455	<term>
456	<computeroutput>--type</computeroutput>
457	</term>
458
459	<listitem>
460	<para>
461	Define the type of the drive to which the medium is being
462	attached, detached, or modified. This argument can only be
463	omitted if the type of medium can be determined from either
464	the medium given with the
465	<computeroutput>--medium</computeroutput> argument or from a
466	previous medium attachment.
467	</para>
468	</listitem>
469	</varlistentry>
470
471	<varlistentry>
472	<term>
473	<computeroutput>--medium</computeroutput>
474	</term>
475
476	<listitem>
477	<para>
478	Specifies what is to be attached. The following values are
479	supported:
480	</para>
481
482	<itemizedlist>
483
484	<listitem>
485	<para>
486	<computeroutput>none</computeroutput>: Any existing
487	device should be removed from the given slot.
488	</para>
489	</listitem>
490
491	<listitem>
492	<para>
493	<computeroutput>emptydrive</computeroutput>: For a
494	virtual DVD or floppy drive only, this makes the device
495	slot behave like a removeable drive into which no media
496	has been inserted.
497	</para>
498	</listitem>
499
500	<listitem>
501	<para>
502	<computeroutput>additions</computeroutput>: For a
503	virtual DVD drive only, this attaches the
504	<emphasis>VirtualBox Guest Additions</emphasis> image to
505	the given device slot.
506	</para>
507	</listitem>
508
509	<listitem>
510	<para>
511	If a UUID is specified, it must be the UUID of a storage
512	medium that is already known to &product-name;. For
513	example, because it has been attached to another virtual
514	machine. See <xref linkend="vboxmanage-list" /> for
515	details of how to list known media. This medium is then
516	attached to the given device slot.
517	</para>
518	</listitem>
519
520	<listitem>
521	<para>
522	If a filename is specified, it must be the full path of
523	an existing disk image in ISO, RAW, VDI, VMDK, or other
524	format. The disk image is then attached to the given
525	device slot.
526	</para>
527	</listitem>
528
529	<listitem>
530	<para>
531	<computeroutput>host:<drive></computeroutput>: For
532	a virtual DVD or floppy drive only, this connects the
533	given device slot to the specified DVD or floppy drive
534	on the host computer.
535	</para>
536	</listitem>
537
538	<listitem>
539	<para>
540	<computeroutput>iscsi</computeroutput>: For virtual hard
541	disks only, this is used for specifying an iSCSI target.
542	In this case, additional parameters must be given. These
543	are described below.
544	</para>
545	</listitem>
546
547	</itemizedlist>
548
549	<para>
550	Some of the above changes, in particular for removeable
551	media such as floppies and CDs/DVDs, can be effected while a
552	VM is running. Others, such as device changes or changes in
553	hard disk device slots, require the VM to be powered off.
554	</para>
555	</listitem>
556	</varlistentry>
557
558	<varlistentry>
559	<term>
560	<computeroutput>--mtype</computeroutput>
561	</term>
562
563	<listitem>
564	<para>
565	Defines how this medium behaves with respect to snapshots
566	and write operations. See <xref linkend="hdimagewrites" />.
567	</para>
568	</listitem>
569	</varlistentry>
570
571	<varlistentry>
572	<term>
573	<computeroutput>--comment</computeroutput>
574	</term>
575
576	<listitem>
577	<para>
578	An optional description that you want to have stored with
579	this medium. For example, for an iSCSI target, "Big storage
580	server downstairs". This is purely descriptive and not
581	needed for the medium to function correctly.
582	</para>
583	</listitem>
584	</varlistentry>
585
586	<varlistentry>
587	<term>
588	<computeroutput>--setuuid, --setparentuuid</computeroutput>
589	</term>
590
591	<listitem>
592	<para>
593	Modifies the UUID or parent UUID of a medium before
594	attaching it to a VM. This is an expert option.
595	Inappropriate use can make the medium unusable or lead to
596	broken VM configurations if any other VM is referring to the
597	same media already. The most frequently used variant is
598	<computeroutput>--setuuid ""</computeroutput>, which assigns
599	a new random UUID to an image. This option is useful for
600	resolving duplicate UUID errors if you duplicated an image
601	using a file copy utility.
602	</para>
603	</listitem>
604	</varlistentry>
605
606	<varlistentry>
607	<term>
608	<computeroutput>--passthrough</computeroutput>
609	</term>
610
611	<listitem>
612	<para>
613	For a virtual DVD drive only, you can enable DVD writing
614	support. This feature is currently experimental, see
615	<xref
616	linkend="storage-cds" />.
617	</para>
618	</listitem>
619	</varlistentry>
620
621	<varlistentry>
622	<term>
623	<computeroutput>--tempeject</computeroutput>
624	</term>
625
626	<listitem>
627	<para>
628	For a virtual DVD drive only, you can configure the behavior
629	for guest-triggered medium eject. If this is set to on, the
630	eject has only a temporary effect. If the VM is powered off
631	and restarted the originally configured medium will be still
632	in the drive.
633	</para>
634	</listitem>
635	</varlistentry>
636
637	<varlistentry>
638	<term>
639	<computeroutput>--nonrotational</computeroutput>
640	</term>
641
642	<listitem>
643	<para>
644	Enables you to enable the non-rotational flag for virtual
645	hard disks. Some guests, such as Windows 7 or later, treat
646	such disks like SSDs and do not perform disk fragmentation
647	on such media.
648	</para>
649	</listitem>
650	</varlistentry>
651
652	<varlistentry>
653	<term>
654	<computeroutput>--discard</computeroutput>
655	</term>
656
657	<listitem>
658	<para>
659	Enables the auto-discard feature for a virtual hard disks.
660	This specifies that a VDI image will be shrunk in response
661	to the trim command from the guest OS. The following
662	requirements must be met:
663	</para>
664
665	<itemizedlist>
666
667	<listitem>
668	<para>
669	The disk format must be VDI.
670	</para>
671	</listitem>
672
673	<listitem>
674	<para>
675	The size of the cleared area must be at least 1 MB.
676	</para>
677	</listitem>
678
679	<listitem>
680	<para>
681	&product-name; will only trim whole 1 MB blocks. The
682	VDIs themselves are organized into 1 MB blocks, so this
683	will only work if the space being trimmed is at least a
684	1 MB contiguous block at a 1 MB boundary. On Windows,
685	occasional defragmentation with <command>defrag.exe
686	/D</command>, or on Linux running <command>btrfs
687	filesystem defrag</command> as a background cron job may
688	be beneficial.
689	</para>
690	</listitem>
691
692	</itemizedlist>
693
694	<note>
695	<para>
696	The Guest OS must be configured to issue the
697	<command>trim</command> command, and typically this means
698	that the guest OS is made to see the disk as an SSD. Ext4
699	supports the -o discard mount flag. Mac OS X probably
700	requires additional settings. Windows should automatically
701	detect and support SSDs, at least in versions 7, 8, and
702	10. The Linux exFAT driver from Samsung supports the
703	<command>trim</command> command.
704	</para>
705	</note>
706
707	<para>
708	It is unclear whether Microsoft's implementation of exFAT
709	supports this feature, even though that file system was
710	originally designed for flash.
711	</para>
712
713	<para>
714	Alternatively, there are other methods to issue trim. For
715	example, the Linux <command>fstrim</command> command, part
716	of the util-linux package. Earlier solutions required a user
717	to zero out unused areas, using zerofree or similar, and to
718	compact the disk. This is only possible when the VM is
719	offline.
720	</para>
721	</listitem>
722	</varlistentry>
723
724	<varlistentry>
725	<term>
726	<computeroutput>--bandwidthgroup</computeroutput>
727	</term>
728
729	<listitem>
730	<para>
731	Sets the bandwidth group to use for the given device. See
732	<xref linkend="storage-bandwidth-limit" />.
733	</para>
734	</listitem>
735	</varlistentry>
736
737	<varlistentry>
738	<term>
739	<computeroutput>--forceunmount</computeroutput>
740	</term>
741
742	<listitem>
743	<para>
744	For a virtual DVD or floppy drive only, this forcibly
745	unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy
746	even if the previous one is locked down by the guest for
747	reading. See <xref linkend="storage-cds" />.
748	</para>
749	</listitem>
750	</varlistentry>
751
752	</variablelist>
753
754	<para>
755	When <computeroutput>iscsi</computeroutput> is used with the
756	<computeroutput>--medium</computeroutput> parameter for iSCSI
757	support, additional parameters must or can be used. See also
758	<xref linkend="storage-iscsi" />.
759	</para>
760
761	<variablelist>
762
763	<varlistentry>
764	<term>
765	<computeroutput>--server</computeroutput>
766	</term>
767
768	<listitem>
769	<para>
770	The host name or IP address of the iSCSI target. Required.
771	</para>
772	</listitem>
773	</varlistentry>
774
775	<varlistentry>
776	<term>
777	<computeroutput>--target</computeroutput>
778	</term>
779
780	<listitem>
781	<para>
782	Target name string. This is determined by the iSCSI target
783	and used to identify the storage resource. Required.
784	</para>
785	</listitem>
786	</varlistentry>
787
788	<varlistentry>
789	<term>
790	<computeroutput>--tport</computeroutput>
791	</term>
792
793	<listitem>
794	<para>
795	TCP/IP port number of the iSCSI service on the target.
796	Optional.
797	</para>
798	</listitem>
799	</varlistentry>
800
801	<varlistentry>
802	<term>
803	<computeroutput>--lun</computeroutput>
804	</term>
805
806	<listitem>
807	<para>
808	Logical Unit Number of the target resource. Optional. Often,
809	this value is zero.
810	</para>
811	</listitem>
812	</varlistentry>
813
814	<varlistentry>
815	<term>
816	<computeroutput>--encodedlun</computeroutput>
817	</term>
818
819	<listitem>
820	<para>
821	Hex-encoded Logical Unit Number of the target resource.
822	Optional. Often, this value is zero.
823	</para>
824	</listitem>
825	</varlistentry>
826
827	<varlistentry>
828	<term>
829	<computeroutput>--username, --password,
830	--passwordfile</computeroutput>
831	</term>
832
833	<listitem>
834	<para>
835	Username and password, called the initiator secret, for
836	target authentication, if required. Optional.
837	</para>
838
839	<note>
840	<para>
841	Username and password are stored without encryption, in
842	clear text, in the XML machine configuration file if no
843	settings password is provided. When a settings password is
844	specified for the first time, the password is stored in
845	encrypted form. As an alternative to providing the
846	password on the command line, a reference to a file
847	containing the text can be provided using the
848	<computeroutput>passwordfile</computeroutput> option.
849	</para>
850	</note>
851	</listitem>
852	</varlistentry>
853
854	<varlistentry>
855	<term>
856	<computeroutput>--initiator</computeroutput>
857	</term>
858
859	<listitem>
860	<para>
861	iSCSI Initiator. Optional.
862	</para>
863
864	<para>
865	Microsoft iSCSI Initiator is a system, such as a server that
866	attaches to an IP network and initiates requests and
867	receives responses from an iSCSI target. The SAN components
868	in Microsoft iSCSI Initiator are largely analogous to Fibre
869	Channel SAN components, and they include the following:
870	</para>
871
872	<itemizedlist>
873
874	<listitem>
875	<para>
876	To transport blocks of iSCSI commands over the IP
877	network, an iSCSI driver must be installed on the iSCSI
878	host. An iSCSI driver is included with Microsoft iSCSI
879	Initiator.
880	</para>
881	</listitem>
882
883	<listitem>
884	<para>
885	A gigabit Ethernet adapter that transmits 1000 megabits
886	per second (Mbps) is recommended for the connection to
887	an iSCSI target. Like standard 10/100 adapters, most
888	gigabit adapters use a preexisting Category 5 or
889	Category 6E cable. Each port on the adapter is
890	identified by a unique IP address.
891	</para>
892	</listitem>
893
894	<listitem>
895	<para>
896	An iSCSI target is any device that receives iSCSI
897	commands. The device can be an end node, such as a
898	storage device, or it can be an intermediate device,
899	such as a network bridge between IP and Fibre Channel
900	devices. Each port on the storage array controller or
901	network bridge is identified by one or more IP addresses
902	</para>
903	</listitem>
904
905	</itemizedlist>
906	</listitem>
907	</varlistentry>
908
909	<varlistentry>
910	<term>
911	<computeroutput>--intnet</computeroutput>
912	</term>
913
914	<listitem>
915	<para>
916	If specified, connect to the iSCSI target using Internal
917	Networking. This needs further configuration, see
918	<xref linkend="iscsi-intnet" />.
919	</para>
920	</listitem>
921	</varlistentry>
922
923	</variablelist>
924
925	</sect1>
926
927	<xi:include href="user_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
928
929	<xi:include href="user_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
930
931	<xi:include href="user_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
932
933	<xi:include href="user_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
934
935	<sect1 id="vboxmanage-modifymedium">
936
937	<title>VBoxManage modifymedium</title>
938
939	<para>
940	With the <command>modifymedium</command> command, you can change
941	the characteristics of a disk image after it has been created.
942	</para>
943
944	<screen>VBoxManage modifymedium [disk\|dvd\|floppy] <uuid\|filename>
945	[--type normal\|writethrough\|immutable\|shareable\|
946	readonly\|multiattach]
947	[--autoreset on\|off]
948	[--property <name=[value]>]
949	[--compact]
950	[--resize <megabytes>\|--resizebyte <bytes>]
951	[--move <path>]
952	[--setlocation <path>]</screen>
953
954	<note>
955	<para>
956	For compatibility with earlier versions of &product-name;, the
957	<command>modifyvdi</command> and <command>modifyhd</command>
958	commands are also supported and mapped internally to the
959	<command>modifymedium</command> command.
960	</para>
961	</note>
962
963	<para>
964	The disk image to modify must be specified either by its UUID, if
965	the medium is registered, or by its filename. Registered images
966	can be listed using <command>VBoxManage list hdds</command>, see
967	<xref linkend="vboxmanage-list" />. A filename must be specified
968	as a valid path, either as an absolute path or as a relative path
969	starting from the current directory.
970	</para>
971
972	<para>
973	The following options are available:
974	</para>
975
976	<itemizedlist>
977
978	<listitem>
979	<para>
980	With the <computeroutput>--type</computeroutput> argument, you
981	can change the type of an existing image between the normal,
982	immutable, write-through and other modes. See
983	<xref
984	linkend="hdimagewrites" />.
985	</para>
986	</listitem>
987
988	<listitem>
989	<para>
990	For immutable hard disks only, the <computeroutput>--autoreset
991	on\|off</computeroutput> option determines whether the disk is
992	automatically reset on every VM startup. See
993	<xref linkend="hdimagewrites" />. By default, autoreset is on.
994	</para>
995	</listitem>
996
997	<listitem>
998	<para>
999	The <computeroutput>--compact</computeroutput> option can be
1000	used to compact disk images. Compacting removes blocks that
1001	only contains zeroes. Using this option will shrink a
1002	dynamically allocated image. It will reduce the
1003	<emphasis>physical</emphasis> size of the image without
1004	affecting the logical size of the virtual disk. Compaction
1005	works both for base images and for differencing images created
1006	as part of a snapshot.
1007	</para>
1008
1009	<para>
1010	For this operation to be effective, it is required that free
1011	space in the guest system first be zeroed out using a suitable
1012	software tool. For Windows guests, you can use the
1013	<command>sdelete</command> tool provided by Microsoft. Run
1014	<command>sdelete -z</command> in the guest to zero the free
1015	disk space, before compressing the virtual disk image. For
1016	Linux, use the <command>zerofree</command> utility which
1017	supports ext2/ext3 filesystems. For Mac OS X guests, use the
1018	<computeroutput>diskutil secureErase freespace 0
1019	/</computeroutput> command from an elevated Terminal.
1020	</para>
1021
1022	<para>
1023	Please note that compacting is currently only available for
1024	VDI images. A similar effect can be achieved by zeroing out
1025	free blocks and then cloning the disk to any other dynamically
1026	allocated format. You can use this workaround until compacting
1027	is also supported for disk formats other than VDI.
1028	</para>
1029	</listitem>
1030
1031	<listitem>
1032	<para>
1033	The <computeroutput>--resize x</computeroutput> option, where
1034	x is the desired new total space in megabytes enables you to
1035	change the capacity of an existing image. This adjusts the
1036	<emphasis>logical</emphasis> size of a virtual disk without
1037	affecting the physical size much.
1038	</para>
1039
1040	<para>
1041	This option currently works only for VDI and VHD formats, and
1042	only for the dynamically allocated variants. It can only be
1043	used to expand, but not shrink, the capacity. For example, if
1044	you originally created a 10 GB disk which is now full, you can
1045	use the <computeroutput>--resize 15360</computeroutput>
1046	command to change the capacity to 15 GB (15,360 MB) without
1047	having to create a new image and copy all data from within a
1048	virtual machine. Note however that this only changes the drive
1049	capacity. You will typically next need to use a partition
1050	management tool inside the guest to adjust the main partition
1051	to fill the drive.
1052	</para>
1053
1054	<para>
1055	The <computeroutput>--resizebyte x</computeroutput> option
1056	does almost the same thing, except that x is expressed in
1057	bytes instead of megabytes.
1058	</para>
1059	</listitem>
1060
1061	<listitem>
1062	<para>
1063	The <computeroutput>--move <path></computeroutput>
1064	option can be used to relocate a medium to a different
1065	location <path> on the host file system. The path can be
1066	either relative to the current directory or absolute.
1067	</para>
1068	</listitem>
1069
1070	<listitem>
1071	<para>
1072	The <computeroutput>--setlocation
1073	<path></computeroutput> option can be used to set the
1074	new location <path> of the medium on the host file
1075	system if the medium has been moved for any reasons. The path
1076	can be either relative to the current directory or absolute.
1077	</para>
1078
1079	<note>
1080	<para>
1081	The new location is used as is, without any sanity checks.
1082	The user is responsible for setting the correct path.
1083	</para>
1084	</note>
1085	</listitem>
1086
1087	</itemizedlist>
1088
1089	</sect1>
1090
1091	<xi:include href="user_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1092
1093	<xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1094
1095	<xi:include href="user_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1096
1097	<xi:include href="user_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1098
1099	<xi:include href="user_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1100
1101	<xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1102
1103	<xi:include href="user_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1104
1105	<xi:include href="user_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1106
1107	<xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1108
1109	<xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1110
1111	<xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1112
1113	<sect1 id="vboxmanage-guestproperty">
1114
1115	<title>VBoxManage guestproperty</title>
1116
1117	<para>
1118	The <command>guestproperty</command> commands enable you to get or
1119	set properties of a running virtual machine. See
1120	<xref linkend="guestadd-guestprops" />. Guest properties are
1121	arbitrary keyword-value string pairs which can be written to and
1122	read from by either the guest or the host, so they can be used as
1123	a low-volume communication channel for strings, provided that a
1124	guest is running and has the Guest Additions installed. In
1125	addition, a number of values whose keywords begin with
1126	<computeroutput>/VirtualBox/</computeroutput>are automatically set
1127	and maintained by the Guest Additions.
1128	</para>
1129
1130	<para>
1131	The following subcommands are available, where
1132	<computeroutput><vm></computeroutput> can either be a VM
1133	name or a VM UUID, as with the other <command>VBoxManage</command>
1134	commands:
1135	</para>
1136
1137	<itemizedlist>
1138
1139	<listitem>
1140	<para>
1141	<computeroutput>enumerate <vm> [--patterns
1142	<pattern>]</computeroutput>: Lists all the guest
1143	properties that are available for the given VM, including the
1144	value. This list will be very limited if the guest's service
1145	process cannot be contacted, for example because the VM is not
1146	running or the Guest Additions are not installed.
1147	</para>
1148
1149	<para>
1150	If <computeroutput>--patterns <pattern></computeroutput>
1151	is specified, it acts as a filter to only list properties that
1152	match the given pattern. The pattern can contain the following
1153	wildcard characters:
1154	</para>
1155
1156	<itemizedlist>
1157
1158	<listitem>
1159	<para>
1160	<computeroutput>*</computeroutput> (asterisk): Represents
1161	any number of characters. For example,
1162	"<computeroutput>/VirtualBox*</computeroutput>" would
1163	match all properties beginning with "/VirtualBox".
1164	</para>
1165	</listitem>
1166
1167	<listitem>
1168	<para>
1169	<computeroutput>?</computeroutput> (question mark):
1170	Represents a single arbitrary character. For example,
1171	"<computeroutput>fo?</computeroutput>" would match both
1172	"foo" and "for".
1173	</para>
1174	</listitem>
1175
1176	<listitem>
1177	<para>
1178	<computeroutput>\|</computeroutput> (pipe symbol): Can be
1179	used to specify multiple alternative patterns. For
1180	example, "<computeroutput>s\|t</computeroutput>" would
1181	match anything starting with either "s" or "t".
1182	</para>
1183	</listitem>
1184
1185	</itemizedlist>
1186	</listitem>
1187
1188	<listitem>
1189	<para>
1190	<computeroutput>get <vm>
1191	<property></computeroutput>: Retrieves the value of a
1192	single property only. If the property cannot be found, for
1193	example because the guest is not running, the following
1194	message is shown:
1195	</para>
1196
1197	<screen>No value set!</screen>
1198	</listitem>
1199
1200	<listitem>
1201	<para>
1202	<computeroutput>set <vm> <property> [<value>
1203	[--flags <flags>]]</computeroutput>: Enables you to set
1204	a guest property by specifying the keyword and value. If
1205	<computeroutput><value></computeroutput> is omitted, the
1206	property is deleted. With
1207	<computeroutput>--flags</computeroutput>, you can specify
1208	additional behavior. You can combine several flags by
1209	separating them with commas.
1210	</para>
1211
1212	<itemizedlist>
1213
1214	<listitem>
1215	<para>
1216	<computeroutput>TRANSIENT</computeroutput>: The value will
1217	not be stored with the VM data when the VM exits.
1218	</para>
1219	</listitem>
1220
1221	<listitem>
1222	<para>
1223	<computeroutput>TRANSRESET</computeroutput>: The value
1224	will be deleted as soon as the VM restarts or exits.
1225	</para>
1226	</listitem>
1227
1228	<listitem>
1229	<para>
1230	<computeroutput>RDONLYGUEST</computeroutput>: The value
1231	can only be changed by the host, but the guest can only
1232	read it.
1233	</para>
1234	</listitem>
1235
1236	<listitem>
1237	<para>
1238	<computeroutput>RDONLYHOST</computeroutput>: The value can
1239	only be changed by the guest, but the host can only read
1240	it.
1241	</para>
1242	</listitem>
1243
1244	<listitem>
1245	<para>
1246	<computeroutput>READONLY</computeroutput>: The value
1247	cannot be changed at all.
1248	</para>
1249	</listitem>
1250
1251	</itemizedlist>
1252	</listitem>
1253
1254	<listitem>
1255	<para>
1256	<computeroutput>wait <vm> <pattern> --timeout
1257	<timeout></computeroutput>: Waits for a particular value
1258	described by the pattern string to change or to be deleted or
1259	created. The pattern rules are the same as for the
1260	<command>enumerate</command> subcommand.
1261	</para>
1262	</listitem>
1263
1264	<listitem>
1265	<para>
1266	<computeroutput>delete <vm>
1267	<property></computeroutput>: Deletes a guest property
1268	which has been set previously.
1269	</para>
1270	</listitem>
1271
1272	</itemizedlist>
1273
1274	</sect1>
1275
1276	<sect1 id="vboxmanage-guestcontrol">
1277
1278	<title>VBoxManage guestcontrol</title>
1279
1280	<para>
1281	The <command>guestcontrol</command> commands enable control of the
1282	guest from the host. See
1283	<xref
1284	linkend="guestadd-guestcontrol" /> for an introduction.
1285	</para>
1286
1287	<para>
1288	The <command>guestcontrol</command> command has two sets of
1289	subcommands. The first set requires guest credentials to be
1290	specified, the second does not.
1291	</para>
1292
1293	<para>
1294	The first set of subcommands is of the following form:
1295	</para>
1296
1297	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
1298	[--username <name> ]
1299	[--passwordfile <file> \| --password <password>]
1300	[--domain <domain> ]
1301	[-v\|--verbose] [-q\|quiet] ...
1302	</screen>
1303
1304	<para>
1305	The common options are as follows:
1306	</para>
1307
1308	<screen>
1309	[--username <name> ]
1310	[--passwordfile <file> \| --password <password>]
1311	[--domain <domain> ]
1312	[-v\|--verbose] [-q\|quiet]
1313	</screen>
1314
1315	<para>
1316	The common options for the first set of subcommands are explained
1317	in the following list.
1318	</para>
1319
1320	<variablelist>
1321
1322	<varlistentry>
1323	<term>
1324	<computeroutput><uuid\|vmname></computeroutput>
1325	</term>
1326
1327	<listitem>
1328	<para>
1329	Specifies the VM UUID or VM name. Mandatory.
1330	</para>
1331	</listitem>
1332	</varlistentry>
1333
1334	<varlistentry>
1335	<term>
1336	<computeroutput>--username <name></computeroutput>
1337	</term>
1338
1339	<listitem>
1340	<para>
1341	Specifies the user name on guest OS under which the process
1342	should run. This user name must already exist on the guest
1343	OS. If unspecified, the host user name is used. Optional
1344	</para>
1345	</listitem>
1346	</varlistentry>
1347
1348	<varlistentry>
1349	<term>
1350	<computeroutput>--passwordfile
1351	<file>\|--password</computeroutput>
1352	</term>
1353
1354	<listitem>
1355	<para>
1356	Specifies the absolute path on guest file system of password
1357	file containing the password for the specified user account
1358	or password for the specified user account. Optional. If
1359	both are omitted, empty password is assumed.
1360	</para>
1361	</listitem>
1362	</varlistentry>
1363
1364	<varlistentry>
1365	<term>
1366	<computeroutput>--domain <domain></computeroutput>
1367	</term>
1368
1369	<listitem>
1370	<para>
1371	User domain for Windows guests. Optional.
1372	</para>
1373	</listitem>
1374	</varlistentry>
1375
1376	<varlistentry>
1377	<term>
1378	<computeroutput>-v\|--verbose</computeroutput>
1379	</term>
1380
1381	<listitem>
1382	<para>
1383	Makes the subcommand execution more verbose. Optional
1384	</para>
1385	</listitem>
1386	</varlistentry>
1387
1388	<varlistentry>
1389	<term>
1390	<computeroutput>-q\|--quiet</computeroutput>
1391	</term>
1392
1393	<listitem>
1394	<para>
1395	Makes the subcommand execution quieter. Optional.
1396	</para>
1397	</listitem>
1398	</varlistentry>
1399
1400	</variablelist>
1401
1402	<para>
1403	The first set of subcommands are as follows:
1404	</para>
1405
1406	<itemizedlist>
1407
1408	<listitem>
1409	<para>
1410	<computeroutput>run</computeroutput>: Executes a guest
1411	program, forwarding stdout, stderr, and stdin to and from the
1412	host until it completes.
1413	</para>
1414
1415	<screen>VBoxManage guestcontrol <uuid\|vmname> run [common-options]
1416	--exe <path to executable> [--timeout <msec>]
1417	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
1418	[--ignore-operhaned-processes] [--profile]
1419	[--no-wait-stdout\|--wait-stdout]
1420	[--no-wait-stderr\|--wait-stderr]
1421	[--dos2unix] [--unix2dos]
1422	-- <program/arg0> [argument1] ... [argumentN]]
1423	</screen>
1424
1425	<variablelist>
1426
1427	<varlistentry>
1428	<term>
1429	<computeroutput><uuid\|vmname></computeroutput>
1430	</term>
1431
1432	<listitem>
1433	<para>
1434	Specifies the VM UUID or VM name. Mandatory.
1435	</para>
1436	</listitem>
1437	</varlistentry>
1438
1439	<varlistentry>
1440	<term>
1441	<computeroutput>--exe <path to
1442	executable></computeroutput>
1443	</term>
1444
1445	<listitem>
1446	<para>
1447	Specifies the absolute path of the executable on the
1448	guest OS file system. Mandatory. For example:
1449	<filename>C:\Windows\System32\calc.exe</filename>.
1450	</para>
1451	</listitem>
1452	</varlistentry>
1453
1454	<varlistentry>
1455	<term>
1456	<computeroutput>--timeout <msec></computeroutput>
1457	</term>
1458
1459	<listitem>
1460	<para>
1461	Specifies the maximum time, in microseconds, that the
1462	executable can run, during which
1463	<command>VBoxManage</command> receives its output.
1464	Optional. If unspecified, <command>VBoxManage</command>
1465	waits indefinitely for the process to end, or an error
1466	occurs.
1467	</para>
1468	</listitem>
1469	</varlistentry>
1470
1471	<varlistentry>
1472	<term>
1473	<computeroutput>-E\|--putenv
1474	<NAME>=<VALUE></computeroutput>
1475	</term>
1476
1477	<listitem>
1478	<para>
1479	Sets, modifies, and unsets environment variables in the
1480	environment in which the program will run. Optional.
1481	</para>
1482
1483	<para>
1484	The guest process is created with the standard default
1485	guest OS environment. Use this option to modify that
1486	default environment. To set or modify a variable use:
1487	<computeroutput><NAME>=<VALUE></computeroutput>.
1488	To unset a variable use:
1489	<computeroutput><NAME>=</computeroutput>
1490	</para>
1491
1492	<para>
1493	Any spaces in names and values should be enclosed by
1494	quotes.
1495	</para>
1496
1497	<para>
1498	To set, modify, and unset multiple variables, use
1499	multiple instances of the
1500	<computeroutput>--E\|--putenv</computeroutput> option.
1501	</para>
1502	</listitem>
1503	</varlistentry>
1504
1505	<varlistentry>
1506	<term>
1507	<computeroutput>--unquoted-args</computeroutput>
1508	</term>
1509
1510	<listitem>
1511	<para>
1512	Disables escaped double quoting, such as \"fred\", on
1513	arguments passed to the executed program. Optional.
1514	</para>
1515	</listitem>
1516	</varlistentry>
1517
1518	<varlistentry>
1519	<term>
1520	<computeroutput>--ignore-operhaned-processes</computeroutput>
1521	</term>
1522
1523	<listitem>
1524	<para>
1525	Ignore orphaned processes. Not yet implemented.
1526	Optional.
1527	</para>
1528	</listitem>
1529	</varlistentry>
1530
1531	<varlistentry>
1532	<term>
1533	<computeroutput>--profile</computeroutput>
1534	</term>
1535
1536	<listitem>
1537	<para>
1538	Use Profile. Not yet implemented. Optional.
1539	</para>
1540	</listitem>
1541	</varlistentry>
1542
1543	<varlistentry>
1544	<term>
1545	<computeroutput>--no-wait-stdout\|--wait-stdout</computeroutput>
1546	</term>
1547
1548	<listitem>
1549	<para>
1550	Does not wait or waits until the guest process ends and
1551	receives its exit code and reason/flags. In the case of
1552	<computeroutput>--wait-stdout</computeroutput>,
1553	<command>VBoxManage</command> receives its stdout while
1554	the process runs. Optional.
1555	</para>
1556	</listitem>
1557	</varlistentry>
1558
1559	<varlistentry>
1560	<term>
1561	<computeroutput>--no-wait-stderr\|--wait-stderr</computeroutput>
1562	</term>
1563
1564	<listitem>
1565	<para>
1566	Does not wait or waits until the guest process ends and
1567	receives its exit code, error messages, and flags. In
1568	the case of
1569	<computeroutput>--wait-stderr</computeroutput>,
1570	<command>VBoxManage</command> receives its stderr while
1571	the process runs. Optional.
1572	</para>
1573	</listitem>
1574	</varlistentry>
1575
1576	<varlistentry>
1577	<term>
1578	<computeroutput>--dos2unix</computeroutput>
1579	</term>
1580
1581	<listitem>
1582	<para>
1583	Converts output from DOS/Windows guests to
1584	UNIX/Linux-compatible line endings, CR + LF to LF. Not
1585	yet implemented. Optional.
1586	</para>
1587	</listitem>
1588	</varlistentry>
1589
1590	<varlistentry>
1591	<term>
1592	<computeroutput>--unix2dos</computeroutput>
1593	</term>
1594
1595	<listitem>
1596	<para>
1597	Converts output from a UNIX/Linux guests to
1598	DOS/Windows-compatible line endings, LF to CR + LF. Not
1599	yet implemented. Optional.
1600	</para>
1601	</listitem>
1602	</varlistentry>
1603
1604	<varlistentry>
1605	<term>
1606	<computeroutput>[-- <program/arg0>
1607	[<argument1>] ...
1608	[<argumentN>]]</computeroutput>
1609	</term>
1610
1611	<listitem>
1612	<para>
1613	Specifies the program name, followed by one or more
1614	arguments to pass to the program. Optional.
1615	</para>
1616
1617	<para>
1618	Any spaces in arguments should be enclosed by quotes.
1619	</para>
1620	</listitem>
1621	</varlistentry>
1622
1623	</variablelist>
1624
1625	<note>
1626	<para>
1627	On Windows there are certain limitations for graphical
1628	applications. See <xref linkend="KnownIssues" />.
1629	</para>
1630	</note>
1631
1632	<para>
1633	Examples of using the <command>guestcontrol run</command>
1634	command are as follows:
1635	</para>
1636
1637	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
1638	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
1639
1640	<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
1641	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
1642
1643	<para>
1644	Note that the double backslashes in the second example are
1645	only required on UNIX hosts.
1646	</para>
1647
1648	<note>
1649	<para>
1650	For certain commands a user name of an existing user account
1651	on the guest must be specified. Anonymous executions are not
1652	supported for security reasons. A user account password,
1653	however, is optional and depends on the guest's OS security
1654	policy or rules. If no password is specified for a given
1655	user name, an empty password will be used. On certain OSes
1656	like Windows the security policy may needs to be adjusted in
1657	order to allow user accounts with an empty password set.
1658	Also, global domain rules might apply and therefore cannot
1659	be changed.
1660	</para>
1661	</note>
1662
1663	<para>
1664	Starting at &product-name; 4.1.2 guest process execution by
1665	default is limited to serve up to five guest processes at a
1666	time. If a new guest process gets started which would exceed
1667	this limit, the oldest not running guest process will be
1668	discarded in order to be able to run that new process. Also,
1669	retrieving output from this old guest process will not be
1670	possible anymore then. If all five guest processes are still
1671	active and running, starting a new guest process will result
1672	in an appropriate error message.
1673	</para>
1674
1675	<para>
1676	To raise or lower the guest process execution limit, either
1677	use the guest property
1678	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
1679	or <command>VBoxService</command> command line by specifying
1680	<computeroutput>--control-procs-max-kept</computeroutput>
1681	needs to be modified. A restart of the guest OS is required
1682	afterwards. To serve unlimited guest processes, a value of
1683	<computeroutput>0</computeroutput> needs to be set, but this
1684	is not recommended.
1685	</para>
1686	</listitem>
1687
1688	<listitem>
1689	<para>
1690	<computeroutput>start</computeroutput>: Executes a guest
1691	program until it completes.
1692	</para>
1693
1694	<screen>VBoxManage guestcontrol <uuid\|vmname> start [common-options]
1695	[--exe <path to executable>] [--timeout <msec>]
1696	[-E\|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
1697	[--ignore-operhaned-processes] [--profile]
1698	-- <program/arg0> [argument1] ... [argumentN]]
1699	</screen>
1700
1701	<para>
1702	Where the options are as follows:
1703	</para>
1704
1705	<variablelist>
1706
1707	<varlistentry>
1708	<term>
1709	<computeroutput><uuid\|vmname></computeroutput>
1710	</term>
1711
1712	<listitem>
1713	<para>
1714	Specifies the VM UUID or VM name. Mandatory.
1715	</para>
1716	</listitem>
1717	</varlistentry>
1718
1719	<varlistentry>
1720	<term>
1721	<computeroutput>--exe <path to
1722	executable></computeroutput>
1723	</term>
1724
1725	<listitem>
1726	<para>
1727	Specifies the absolute path of the executable on the
1728	guest OS file system. Mandatory. For example:
1729	<filename>C:\Windows\System32\calc.exe</filename>
1730	</para>
1731	</listitem>
1732	</varlistentry>
1733
1734	<varlistentry>
1735	<term>
1736	<computeroutput>--timeout <msec></computeroutput>
1737	</term>
1738
1739	<listitem>
1740	<para>
1741	Specifies the maximum time, in microseconds, that the
1742	executable can run. Optional. If unspecified,
1743	<command>VBoxManage</command> waits indefinitely for the
1744	process to end, or an error occurs.
1745	</para>
1746	</listitem>
1747	</varlistentry>
1748
1749	<varlistentry>
1750	<term>
1751	<computeroutput>-E\|--putenv
1752	<NAME>=<VALUE></computeroutput>
1753	</term>
1754
1755	<listitem>
1756	<para>
1757	Sets, modifies, and unsets environment variables in the
1758	environment in which the program will run. Optional.
1759	</para>
1760
1761	<para>
1762	The guest process is created with the standard default
1763	guest OS environment. Use this option to modify that
1764	default environment. To set or modify a variable use:
1765	<computeroutput><NAME>=<VALUE></computeroutput>.
1766	To unset a variable use:
1767	<computeroutput><NAME>=</computeroutput>
1768	</para>
1769
1770	<para>
1771	Any spaces in names and values should be enclosed by
1772	quotes.
1773	</para>
1774
1775	<para>
1776	To set, modify, or unset multiple variables, use
1777	multiple instances of the
1778	<computeroutput>--E\|--putenv</computeroutput> option.
1779	</para>
1780	</listitem>
1781	</varlistentry>
1782
1783	<varlistentry>
1784	<term>
1785	<computeroutput>--unquoted-args</computeroutput>
1786	</term>
1787
1788	<listitem>
1789	<para>
1790	Disables escaped double quoting, such as \"fred\", on
1791	arguments passed to the executed program. Optional.
1792	</para>
1793	</listitem>
1794	</varlistentry>
1795
1796	<varlistentry>
1797	<term>
1798	<computeroutput>--ignore-operhaned-processes</computeroutput>
1799	</term>
1800
1801	<listitem>
1802	<para>
1803	Ignores orphaned processes. Not yet implemented.
1804	Optional.
1805	</para>
1806	</listitem>
1807	</varlistentry>
1808
1809	<varlistentry>
1810	<term>
1811	<computeroutput>--profile</computeroutput>
1812	</term>
1813
1814	<listitem>
1815	<para>
1816	Use a profile. Not yet implemented. Optional.
1817	</para>
1818	</listitem>
1819	</varlistentry>
1820
1821	<varlistentry>
1822	<term>
1823	<computeroutput>[-- <program/arg0>
1824	[<argument1>] ...
1825	[<argumentN>]]</computeroutput>
1826	</term>
1827
1828	<listitem>
1829	<para>
1830	Specifies the program name, followed by one or more
1831	arguments to pass to the program. Optional.
1832	</para>
1833
1834	<para>
1835	Any spaces in arguments should be enclosed by quotes.
1836	</para>
1837	</listitem>
1838	</varlistentry>
1839
1840	</variablelist>
1841
1842	<note>
1843	<para>
1844	On Windows there are certain limitations for graphical
1845	applications. See <xref linkend="KnownIssues" />.
1846	</para>
1847	</note>
1848
1849	<para>
1850	Examples of using the <command>guestcontrol start</command>
1851	command are as follows:
1852	</para>
1853
1854	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
1855	--username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
1856
1857	<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
1858	--username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
1859
1860	<para>
1861	Note that the double backslashes in the second example are
1862	only required on UNIX hosts.
1863	</para>
1864
1865	<note>
1866	<para>
1867	For certain commands a user name of an existing user account
1868	on the guest must be specified. Anonymous executions are not
1869	supported for security reasons. A user account password,
1870	however, is optional and depends on the guest's OS security
1871	policy or rules. If no password is specified for a given
1872	user name, an empty password will be used. On certain OSes
1873	like Windows the security policy may needs to be adjusted in
1874	order to allow user accounts with an empty password set.
1875	Also, global domain rules might apply and therefore cannot
1876	be changed.
1877	</para>
1878	</note>
1879
1880	<para>
1881	Starting at &product-name; 4.1.2 guest process execution by
1882	default is limited to serve up to five guest processes at a
1883	time. If a new guest process gets started which would exceed
1884	this limit, the oldest not running guest process will be
1885	discarded in order to be able to run that new process. Also,
1886	retrieving output from this old guest process will not be
1887	possible anymore then. If all five guest processes are still
1888	active and running, starting a new guest process will result
1889	in an appropriate error message.
1890	</para>
1891
1892	<para>
1893	To raise or lower the guest process execution limit, either
1894	use the guest property
1895	<computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
1896	or <command>VBoxService</command> command line by specifying
1897	<computeroutput>--control-procs-max-kept</computeroutput>
1898	needs to be modified. A restart of the guest OS is required
1899	afterwards. To serve unlimited guest processes, a value of
1900	<computeroutput>0</computeroutput> needs to be set, but this
1901	is not recommended.
1902	</para>
1903	</listitem>
1904
1905	<listitem>
1906	<para>
1907	<computeroutput>copyfrom</computeroutput>: Copies files from
1908	the guest to the host file system. Only available with Guest
1909	Additions 4.0 or later installed.
1910	</para>
1911
1912	<screen>VBoxManage guestcontrol <uuid\|vmname> copyfrom [common-options]
1913	[--follow] [--R\|recursive]
1914	--target-directory <host-dst-dir>
1915	<guest-src0> [<guest-src1> [...]] </screen>
1916
1917	<para>
1918	Where the parameters are as follows:
1919	</para>
1920
1921	<variablelist>
1922
1923	<varlistentry>
1924	<term>
1925	<computeroutput><uid\|vmname></computeroutput>
1926	</term>
1927
1928	<listitem>
1929	<para>
1930	Specifies the VM UUID or VM name. Mandatory.
1931	</para>
1932	</listitem>
1933	</varlistentry>
1934
1935	<varlistentry>
1936	<term>
1937	<computeroutput>--follow</computeroutput>
1938	</term>
1939
1940	<listitem>
1941	<para>
1942	Enables symlink following on the guest file system.
1943	Optional.
1944	</para>
1945	</listitem>
1946	</varlistentry>
1947
1948	<varlistentry>
1949	<term>
1950	<computeroutput>-R\|--recursive</computeroutput>
1951	</term>
1952
1953	<listitem>
1954	<para>
1955	Enables recursive copying of files and directories from
1956	the specified guest file system directory. Optional.
1957	</para>
1958	</listitem>
1959	</varlistentry>
1960
1961	<varlistentry>
1962	<term>
1963	<computeroutput>--target-directory
1964	<host-dst-dir></computeroutput>
1965	</term>
1966
1967	<listitem>
1968	<para>
1969	Specifies the absolute path of the host file system
1970	destination directory. Mandatory. For example:
1971	<filename>C:\Temp</filename>.
1972	</para>
1973	</listitem>
1974	</varlistentry>
1975
1976	<varlistentry>
1977	<term>
1978	<computeroutput><guest-src0> [<guest-src1>
1979	[...]]</computeroutput>
1980	</term>
1981
1982	<listitem>
1983	<para>
1984	Specifies the absolute paths of guest file system files
1985	to be copied. Mandatory. For example:
1986	<filename>C:\Windows\System32\calc.exe</filename>.
1987	Wildcards can be used in the expressions. For example:
1988	<filename>C:\Windows\System\.dll</filename>.
1989	</para>
1990	</listitem>
1991	</varlistentry>
1992
1993	</variablelist>
1994	</listitem>
1995
1996	<listitem>
1997	<para>
1998	<computeroutput>copyto</computeroutput>: Copies files from the
1999	host to the guest file system. Only available with Guest
2000	Additions 4.0 or later installed.
2001	</para>
2002
2003	<screen>VBoxManage guestcontrol <uuid\|vmname> copyto [common-options]
2004	[--follow] [--R\|recursive]
2005	--target-directory <guest-dst>
2006	<host-src0> [<host-src1> [...]] </screen>
2007
2008	<para>
2009	Where the parameters are as follows:
2010	</para>
2011
2012	<variablelist>
2013
2014	<varlistentry>
2015	<term>
2016	<computeroutput><uuid\|vmname></computeroutput>
2017	</term>
2018
2019	<listitem>
2020	<para>
2021	Specifies the VM UUID or VM name. Mandatory.
2022	</para>
2023	</listitem>
2024	</varlistentry>
2025
2026	<varlistentry>
2027	<term>
2028	<computeroutput>--follow</computeroutput>
2029	</term>
2030
2031	<listitem>
2032	<para>
2033	Enables symlink following on the host file system.
2034	Optional.
2035	</para>
2036	</listitem>
2037	</varlistentry>
2038
2039	<varlistentry>
2040	<term>
2041	<computeroutput>-R\|--recursive</computeroutput>
2042	</term>
2043
2044	<listitem>
2045	<para>
2046	Enables recursive copying of files and directories from
2047	the specified host file system directory. Optional.
2048	</para>
2049	</listitem>
2050	</varlistentry>
2051
2052	<varlistentry>
2053	<term>
2054	<computeroutput>--target-directory
2055	<guest-dst></computeroutput>
2056	</term>
2057
2058	<listitem>
2059	<para>
2060	Specifies the absolute path of the guest file system
2061	destination directory. Mandatory. For example:
2062	<filename>C:\Temp</filename>.
2063	</para>
2064	</listitem>
2065	</varlistentry>
2066
2067	<varlistentry>
2068	<term>
2069	<computeroutput><host-src0> [<host-src1>
2070	[...]]</computeroutput>
2071	</term>
2072
2073	<listitem>
2074	<para>
2075	Specifies the absolute paths of host file system files
2076	to be copied. Mandatory. For example:
2077	<filename>C:\Windows\System32\calc.exe</filename>.
2078	Wildcards can be used in the expressions. For example:
2079	<filename>C:\Windows\System\.dll</filename>.
2080	</para>
2081	</listitem>
2082	</varlistentry>
2083
2084	</variablelist>
2085	</listitem>
2086
2087	<listitem>
2088	<para>
2089	<computeroutput>md\|mkdir\|createdir\|createdirectory</computeroutput>:
2090	Creates one or more directories on the guest file system. Only
2091	available with Guest Additions 4.0 or later installed.
2092	</para>
2093
2094	<screen>VBoxManage guestcontrol <uuid\|vmname> md\|mkdir\|createdir\|createdirectory [common-options]
2095	[--parents] [--mode <mode>]
2096	<guest-dir0> [<guest-dir1> [...]] </screen>
2097
2098	<para>
2099	Where the parameters are as follows:
2100	</para>
2101
2102	<variablelist>
2103
2104	<varlistentry>
2105	<term>
2106	<computeroutput><uuid\|vmname></computeroutput>
2107	</term>
2108
2109	<listitem>
2110	<para>
2111	Specifies the VM UUID or VM name. Mandatory.
2112	</para>
2113	</listitem>
2114	</varlistentry>
2115
2116	<varlistentry>
2117	<term>
2118	<computeroutput>--parents</computeroutput>
2119	</term>
2120
2121	<listitem>
2122	<para>
2123	Creates any absent parent directories of the specified
2124	directory. Optional.
2125	</para>
2126
2127	<para>
2128	For example: If specified directory is
2129	<filename>D:\Foo\Bar</filename> and
2130	<filename>D:\Foo</filename> is absent, it will be
2131	created. In such a case, had the
2132	<computeroutput>--parents</computeroutput> option not
2133	been used, this command would have failed.
2134	</para>
2135	</listitem>
2136	</varlistentry>
2137
2138	<varlistentry>
2139	<term>
2140	<computeroutput>--mode <mode></computeroutput>
2141	</term>
2142
2143	<listitem>
2144	<para>
2145	Specifies the permission mode on the specified
2146	directories, and any parents, if the
2147	<computeroutput>--parents</computeroutput> option is
2148	used. Currently octal modes only, such as.
2149	<computeroutput>0755</computeroutput>, are supported.
2150	</para>
2151	</listitem>
2152	</varlistentry>
2153
2154	<varlistentry>
2155	<term>
2156	<computeroutput><guest-dir0> [<guest-dir1>
2157	[...]]</computeroutput>
2158	</term>
2159
2160	<listitem>
2161	<para>
2162	Specifies a list of absolute paths of directories to be
2163	created on guest file system. Mandatory. For example:
2164	<filename>D:\Foo\Bar</filename>.
2165	</para>
2166
2167	<para>
2168	All parent directories must already exist unless the
2169	switch <computeroutput>--parents</computeroutput> is
2170	used. For example, in the above example
2171	<filename>D:\Foo</filename>. The specified user must
2172	have sufficient rights to create the specified
2173	directories, and any parents that need to be created.
2174	</para>
2175	</listitem>
2176	</varlistentry>
2177
2178	</variablelist>
2179	</listitem>
2180
2181	<listitem>
2182	<para>
2183	<computeroutput>rmdir\|removedir\|removedirectory</computeroutput>:
2184	Deletes specified guest file system directories. Only
2185	available with installed Guest Additions 4.3.2 and later.
2186	</para>
2187
2188	<screen>VBoxManage guestcontrol <uuid\|vmname> rmdir\|removedir\|removedirectory [common-options]
2189	[--recursive\|-R]
2190	<guest-dir0> [<guest-dir1> [...]]
2191	</screen>
2192
2193	<para>
2194	Where the parameters are as follows:
2195	</para>
2196
2197	<variablelist>
2198
2199	<varlistentry>
2200	<term>
2201	<computeroutput><uuid\|vmname></computeroutput>
2202	</term>
2203
2204	<listitem>
2205	<para>
2206	Specifies the VM UUID or VM name. Mandatory.
2207	</para>
2208	</listitem>
2209	</varlistentry>
2210
2211	<varlistentry>
2212	<term>
2213	<computeroutput>--recursive</computeroutput>
2214	</term>
2215
2216	<listitem>
2217	<para>
2218	Recursively removes directories and contents. Optional.
2219	</para>
2220	</listitem>
2221	</varlistentry>
2222
2223	<varlistentry>
2224	<term>
2225	<computeroutput><guest-dir0> [<guest-dir1>
2226	[...]]</computeroutput>
2227	</term>
2228
2229	<listitem>
2230	<para>
2231	Specifies a list of the absolute paths of directories to
2232	be deleted on guest file system. Mandatory. Wildcards
2233	are allowed. For example:
2234	<filename>D:\Foo\*Bar</filename>. The specified user
2235	must have sufficient rights to delete the specified
2236	directories.
2237	</para>
2238	</listitem>
2239	</varlistentry>
2240
2241	</variablelist>
2242	</listitem>
2243
2244	<listitem>
2245	<para>
2246	<computeroutput>rm\|removefile</computeroutput>: Deletes
2247	specified files on the guest file system. Only available with
2248	installed Guest Additions 4.3.2 and later.
2249	</para>
2250
2251	<screen>VBoxManage guestcontrol <uuid\|vmname> rm\|removefile [common-options]
2252	[-f\|--force]
2253	<guest-file0> [<guest-file1> [...]] </screen>
2254
2255	<para>
2256	Where the parameters are as follows:
2257	</para>
2258
2259	<variablelist>
2260
2261	<varlistentry>
2262	<term>
2263	<computeroutput><uuid\|vmname></computeroutput>
2264	</term>
2265
2266	<listitem>
2267	<para>
2268	Specifies the VM UUID or VM name. Mandatory.
2269	</para>
2270	</listitem>
2271	</varlistentry>
2272
2273	<varlistentry>
2274	<term>
2275	<computeroutput>-f\|--force</computeroutput>
2276	</term>
2277
2278	<listitem>
2279	<para>
2280	Enforce operation and override any requests for
2281	confirmations. Optional.
2282	</para>
2283	</listitem>
2284	</varlistentry>
2285
2286	<varlistentry>
2287	<term>
2288	<computeroutput><guest-file0> [<guest-file1>
2289	[...]]</computeroutput>
2290	</term>
2291
2292	<listitem>
2293	<para>
2294	Specifies a list of absolute paths of files to be
2295	deleted on guest file system. Mandatory. Wildcards are
2296	allowed. For example:
2297	<filename>D:\Foo\Bar\text*.txt</filename>. The specified
2298	user should have sufficient rights to delete the
2299	specified files.
2300	</para>
2301	</listitem>
2302	</varlistentry>
2303
2304	</variablelist>
2305	</listitem>
2306
2307	<listitem>
2308	<para>
2309	<computeroutput>mv\|move\|ren\|rename</computeroutput>: Renames
2310	files and/or directories on the guest file system. Only
2311	available with installed Guest Additions 4.3.2 and later.
2312	</para>
2313
2314	<screen>VBoxManage guestcontrol <uuid\|vmname> mv\|move\|ren\|rename [common-options]
2315	<guest-source0> [<guest-source1> [...]] <guest-dest></screen>
2316
2317	<para>
2318	Where the parameters are as follows:
2319	</para>
2320
2321	<variablelist>
2322
2323	<varlistentry>
2324	<term>
2325	<computeroutput><uuid\|vmname></computeroutput>
2326	</term>
2327
2328	<listitem>
2329	<para>
2330	Specifies the VM UUID or VM name. Mandatory.
2331	</para>
2332	</listitem>
2333	</varlistentry>
2334
2335	<varlistentry>
2336	<term>
2337	<computeroutput><guest-source0>
2338	[<guest-source1> [...]]</computeroutput>
2339	</term>
2340
2341	<listitem>
2342	<para>
2343	Specifies absolute paths of files or a single directory
2344	to be moved and renamed on guest file system. Mandatory.
2345	Wildcards are allowed in file names. The specified user
2346	should have sufficient rights to access the specified
2347	files.
2348	</para>
2349	</listitem>
2350	</varlistentry>
2351
2352	<varlistentry>
2353	<term>
2354	<computeroutput><dest></computeroutput>
2355	</term>
2356
2357	<listitem>
2358	<para>
2359	Specifies the absolute path of the destination file or
2360	directory to which the files are to be moved. Mandatory.
2361	If only one file to be moved, <dest> can be file
2362	or directory, else it must be a directory. The specified
2363	user must have sufficient rights to access the
2364	destination file or directory.
2365	</para>
2366	</listitem>
2367	</varlistentry>
2368
2369	</variablelist>
2370	</listitem>
2371
2372	<listitem>
2373	<para>
2374	<computeroutput>mktemp\|createtemp\|createtemporary</computeroutput>:
2375	Creates a temporary file or directory on the guest file
2376	system, to assist subsequent copying of files from the host to
2377	the guest file systems. By default, the file or directory is
2378	created in the guest's platform specific temp directory. Not
2379	currently supported. Only available with installed Guest
2380	Additions 4.2 and later.
2381	</para>
2382
2383	<screen>VBoxManage guestcontrol <uuid\|vmname> mktemp\|createtemp\|createtemporary [common-options]
2384	[--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
2385	<template>
2386	</screen>
2387
2388	<para>
2389	The parameters are as follows:
2390	</para>
2391
2392	<variablelist>
2393
2394	<varlistentry>
2395	<term>
2396	<computeroutput><uuid\|vmname></computeroutput>
2397	</term>
2398
2399	<listitem>
2400	<para>
2401	Specifies the VM UUID or VM name. Mandatory.
2402	</para>
2403	</listitem>
2404	</varlistentry>
2405
2406	<varlistentry>
2407	<term>
2408	<computeroutput>--directory</computeroutput>
2409	</term>
2410
2411	<listitem>
2412	<para>
2413	Creates a temporary directory instead of a file,
2414	specified by the <template> parameter. Optional.
2415	</para>
2416	</listitem>
2417	</varlistentry>
2418
2419	<varlistentry>
2420	<term>
2421	<computeroutput>--secure</computeroutput>
2422	</term>
2423
2424	<listitem>
2425	<para>
2426	Enforces secure file and directory creation. Optional.
2427	The permission mode is set to
2428	<computeroutput>0755</computeroutput>. Operation fails
2429	if it cannot be performed securely.
2430	</para>
2431	</listitem>
2432	</varlistentry>
2433
2434	<varlistentry>
2435	<term>
2436	<computeroutput>--mode <mode></computeroutput>
2437	</term>
2438
2439	<listitem>
2440	<para>
2441	Specifies the permission mode of the specified
2442	directory. Optional. Currently only octal modes, such as
2443	<computeroutput>0755</computeroutput>, are supported.
2444	</para>
2445	</listitem>
2446	</varlistentry>
2447
2448	<varlistentry>
2449	<term>
2450	<computeroutput>--tmpdir
2451	<directory></computeroutput>
2452	</term>
2453
2454	<listitem>
2455	<para>
2456	Specifies the absolute path of the directory on the
2457	guest file system where the file or directory specified
2458	will be created. Optional. If unspecified, the
2459	platform-specific temp directory is used.
2460	</para>
2461	</listitem>
2462	</varlistentry>
2463
2464	<varlistentry>
2465	<term>
2466	<computeroutput><template></computeroutput>
2467	</term>
2468
2469	<listitem>
2470	<para>
2471	Specifies a file name without a directory path,
2472	containing at least one sequence of three consecutive X
2473	characters, or ending in X. Mandatory.
2474	</para>
2475	</listitem>
2476	</varlistentry>
2477
2478	</variablelist>
2479	</listitem>
2480
2481	<listitem>
2482	<para>
2483	<computeroutput>stat</computeroutput>: Displays file or file
2484	system statuses on the guest.
2485	</para>
2486
2487	<screen>VBoxManage guestcontrol <uuid\|vmname> stat [common-options]
2488	<file0> [<file1> [...]]</screen>
2489
2490	<para>
2491	Where the parameters are as follows:
2492	</para>
2493
2494	<variablelist>
2495
2496	<varlistentry>
2497	<term>
2498	<computeroutput><uuid\|vmname></computeroutput>
2499	</term>
2500
2501	<listitem>
2502	<para>
2503	Specifies the VM UUID or VM name. Mandatory.
2504	</para>
2505	</listitem>
2506	</varlistentry>
2507
2508	<varlistentry>
2509	<term>
2510	<computeroutput><file0> [<file1>
2511	[...]]</computeroutput>
2512	</term>
2513
2514	<listitem>
2515	<para>
2516	Specifies absolute paths of files or file systems on the
2517	guest file system. Mandatory. For example:
2518	<filename>/home/foo/a.out</filename>. The specified user
2519	should have sufficient rights to access the specified
2520	files or file systems.
2521	</para>
2522	</listitem>
2523	</varlistentry>
2524
2525	</variablelist>
2526	</listitem>
2527
2528	</itemizedlist>
2529
2530	<para>
2531	The second set of subcommands is of the form:
2532	</para>
2533
2534	<screen>VBoxManage guestcontrol <uuid\|vmname> <sub-command>
2535	[-v\|--verbose] [-q\|quiet] ...
2536	</screen>
2537
2538	<para>
2539	The common options are as follows:
2540	</para>
2541
2542	<screen>
2543	[-v\|--verbose] [-q\|--quiet]
2544	</screen>
2545
2546	<para>
2547	Details of the common options for the second set of subcommands
2548	are as follows:
2549	</para>
2550
2551	<variablelist>
2552
2553	<varlistentry>
2554	<term>
2555	<computeroutput>-v\|--verbose</computeroutput>
2556	</term>
2557
2558	<listitem>
2559	<para>
2560	Makes the subcommand execution more verbose. Optional.
2561	</para>
2562	</listitem>
2563	</varlistentry>
2564
2565	<varlistentry>
2566	<term>
2567	<computeroutput>-q\|--quiet</computeroutput>
2568	</term>
2569
2570	<listitem>
2571	<para>
2572	Makes the subcommand execution quieter. Optional.
2573	</para>
2574	</listitem>
2575	</varlistentry>
2576
2577	</variablelist>
2578
2579	<para>
2580	The second set of subcommands are as follows:
2581	</para>
2582
2583	<itemizedlist>
2584
2585	<listitem>
2586	<para>
2587	<computeroutput>list</computeroutput>: Lists guest control
2588	configuration and status data. For example: open guest
2589	sessions, guest processes, and files.
2590	</para>
2591
2592	<screen>VBoxManage guestcontrol <uuid\|vmname> list [common-opts]
2593	<all\|sessions\|processes\|files> </screen>
2594
2595	<para>
2596	Where the parameters are as follows:
2597	</para>
2598
2599	<variablelist>
2600
2601	<varlistentry>
2602	<term>
2603	<computeroutput><uuid\|vmname></computeroutput>
2604	</term>
2605
2606	<listitem>
2607	<para>
2608	Specifies the VM UUID or VM name. Mandatory.
2609	</para>
2610	</listitem>
2611	</varlistentry>
2612
2613	<varlistentry>
2614	<term>
2615	<computeroutput>all\|sessions\|processes\|files</computeroutput>
2616	</term>
2617
2618	<listitem>
2619	<para>
2620	Indicates whether to list all available data or guest
2621	sessions, processes or files. Mandatory.
2622	</para>
2623	</listitem>
2624	</varlistentry>
2625
2626	</variablelist>
2627	</listitem>
2628
2629	<listitem>
2630	<para>
2631	<computeroutput>closeprocess</computeroutput>: Terminates
2632	guest processes specified by PIDs running in a guest session,
2633	specified by the session ID or name.
2634	</para>
2635
2636	<screen>VBoxManage guestcontrol <uuid\|vmname> closeprocess [common-options]
2637	--session-id <ID> \| --session-name <name or pattern>
2638	<PID0> [<PID1> [...]] </screen>
2639
2640	<para>
2641	Where the parameters are as follows:
2642	</para>
2643
2644	<variablelist>
2645
2646	<varlistentry>
2647	<term>
2648	<computeroutput><uuid\|vmname></computeroutput>
2649	</term>
2650
2651	<listitem>
2652	<para>
2653	Specifies the VM UUID or VM name. Mandatory.
2654	</para>
2655	</listitem>
2656	</varlistentry>
2657
2658	<varlistentry>
2659	<term>
2660	<computeroutput>--session-id <ID></computeroutput>
2661	</term>
2662
2663	<listitem>
2664	<para>
2665	Specifies the guest session by its ID. Optional.
2666	</para>
2667	</listitem>
2668	</varlistentry>
2669
2670	<varlistentry>
2671	<term>
2672	<computeroutput>--session-name <name or
2673	pattern></computeroutput>
2674	</term>
2675
2676	<listitem>
2677	<para>
2678	Specifies the guest session by its name, or multiple
2679	sessions using a pattern containing wildcards. Optional.
2680	</para>
2681	</listitem>
2682	</varlistentry>
2683
2684	<varlistentry>
2685	<term>
2686	<computeroutput><PID0> [<PID1>
2687	[...]]</computeroutput>
2688	</term>
2689
2690	<listitem>
2691	<para>
2692	Specifies a list of process identifiers (PIDs) of guest
2693	processes to be terminated. Mandatory.
2694	</para>
2695	</listitem>
2696	</varlistentry>
2697
2698	</variablelist>
2699	</listitem>
2700
2701	<listitem>
2702	<para>
2703	<computeroutput>closesession</computeroutput>: Closes
2704	specified guest sessions, specified either by session ID or
2705	name.
2706	</para>
2707
2708	<screen>VBoxManage guestcontrol <uuid\|vmname> closesession [common-options]
2709	--session-id <ID> \| --session-name <name or pattern> \| --all </screen>
2710
2711	<para>
2712	Where the parameters are as follows:
2713	</para>
2714
2715	<variablelist>
2716
2717	<varlistentry>
2718	<term>
2719	<computeroutput><uuid\|vmname></computeroutput>
2720	</term>
2721
2722	<listitem>
2723	<para>
2724	Specifies the VM UUID or VM name. Mandatory.
2725	</para>
2726	</listitem>
2727	</varlistentry>
2728
2729	<varlistentry>
2730	<term>
2731	<computeroutput>--session-id <ID></computeroutput>
2732	</term>
2733
2734	<listitem>
2735	<para>
2736	Specifies the guest session to be closed by ID.
2737	Optional.
2738	</para>
2739	</listitem>
2740	</varlistentry>
2741
2742	<varlistentry>
2743	<term>
2744	<computeroutput>--session-name <name or
2745	pattern></computeroutput>
2746	</term>
2747
2748	<listitem>
2749	<para>
2750	Specifies the guest session to be closed by name.
2751	Optional. Multiple sessions can be specified by using a
2752	pattern containing wildcards.
2753	</para>
2754	</listitem>
2755	</varlistentry>
2756
2757	<varlistentry>
2758	<term>
2759	<computeroutput>--all</computeroutput>
2760	</term>
2761
2762	<listitem>
2763	<para>
2764	Close all guest sessions. Optional.
2765	</para>
2766	</listitem>
2767	</varlistentry>
2768
2769	</variablelist>
2770	</listitem>
2771
2772	<listitem>
2773	<para>
2774	<computeroutput>updatega\|updateadditions\|updateguestadditions</computeroutput>:
2775	Ugrades Guest Additions already installed on the guest. Only
2776	available for already installed Guest Additions 4.0 and later.
2777	</para>
2778
2779	<screen>VBoxManage guestcontrol <uuid\|vmname> updatega\|updateadditions\|updateguestadditions
2780	[common-options]
2781	[--source <New .ISO path>]
2782	[--wait-start]
2783	[-- <argument0> [<argument1> [...]]]</screen>
2784
2785	<para>
2786	Where the parameters are as follows:
2787	</para>
2788
2789	<variablelist>
2790
2791	<varlistentry>
2792	<term>
2793	<computeroutput><uuid\|vmname></computeroutput>
2794	</term>
2795
2796	<listitem>
2797	<para>
2798	Specifies the VM UUID or VM name. Mandatory.
2799	</para>
2800	</listitem>
2801	</varlistentry>
2802
2803	<varlistentry>
2804	<term>
2805	<computeroutput>--source</computeroutput> <New .ISO
2806	path>
2807	</term>
2808
2809	<listitem>
2810	<para>
2811	Specifies the absolute path on the guest file system of
2812	the .ISO file for the Guest Additions update. Mandatory.
2813	</para>
2814	</listitem>
2815	</varlistentry>
2816
2817	<varlistentry>
2818	<term>
2819	<computeroutput>--wait-start</computeroutput>
2820	</term>
2821
2822	<listitem>
2823	<para>
2824	Indicates that <command>VBoxManage</command> starts the
2825	usual updating process on the guest and then waits until
2826	the actual Guest Additions updating begins, at which
2827	point <command>VBoxManage</command> self-terminates.
2828	Optional.
2829	</para>
2830
2831	<para>
2832	Default behavior is that <command>VBoxManage</command>
2833	waits for completion of the Guest Additions update
2834	before terminating. Use of this option is sometimes
2835	necessary, as a running <command>VBoxManage</command>
2836	can affect the interaction between the installer and the
2837	guest OS.
2838	</para>
2839	</listitem>
2840	</varlistentry>
2841
2842	<varlistentry>
2843	<term>
2844	<computeroutput>[-- <argument0> [<argument1>
2845	[...]]]</computeroutput>
2846	</term>
2847
2848	<listitem>
2849	<para>
2850	Specifies optional command line arguments to be supplied
2851	to the Guest Additions updater. Useful for retrofitting
2852	features which are not currently installed.
2853	</para>
2854
2855	<para>
2856	Arguments containing spaces should be enclosed by
2857	quotes.
2858	</para>
2859	</listitem>
2860	</varlistentry>
2861
2862	</variablelist>
2863	</listitem>
2864
2865	<listitem>
2866	<para>
2867	<computeroutput>watch</computeroutput>: Prints current guest
2868	control activity.
2869	</para>
2870
2871	<screen>VBoxManage guestcontrol <uuid\|vmname> watch [common-options]
2872	</screen>
2873
2874	<para>
2875	Where the parameters are as follows:
2876	</para>
2877
2878	<variablelist>
2879
2880	<varlistentry>
2881	<term>
2882	<computeroutput><uuid\|vmname></computeroutput>
2883	</term>
2884
2885	<listitem>
2886	<para>
2887	Specifies the VM UUID or VM name. Mandatory.
2888	</para>
2889	</listitem>
2890	</varlistentry>
2891
2892	</variablelist>
2893	</listitem>
2894
2895	</itemizedlist>
2896
2897	</sect1>
2898
2899	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
2900
2901	<sect1 id="vboxmanage-metrics">
2902
2903	<title>VBoxManage metrics</title>
2904
2905	<para>
2906	This command supports monitoring the usage of system resources.
2907	Resources are represented by various metrics associated with the
2908	host system or a particular VM. For example, the host system has a
2909	<computeroutput>CPU/Load/User</computeroutput> metric that shows
2910	the percentage of time CPUs spend executing in user mode over a
2911	specific sampling period.
2912	</para>
2913
2914	<para>
2915	Metric data is collected and retained internally. It may be
2916	retrieved at any time with the <command>VBoxManage metrics
2917	query</command> subcommand. The data is available as long as the
2918	background <computeroutput>VBoxSVC</computeroutput> process is
2919	alive. That process terminates shortly after all VMs and frontends
2920	have been closed.
2921	</para>
2922
2923	<para>
2924	By default no metrics are collected at all. Metrics collection
2925	does not start until <command>VBoxManage metrics setup</command>
2926	is invoked with a proper sampling interval and the number of
2927	metrics to be retained. The interval is measured in seconds. For
2928	example, to enable collecting the host processor and memory usage
2929	metrics every second and keeping the five most current samples,
2930	the following command can be used:
2931	</para>
2932
2933	<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
2934
2935	<para>
2936	Metric collection can only be enabled for started VMs. Collected
2937	data and collection settings for a particular VM will disappear as
2938	soon as it shuts down. Use the <command>VBoxManage metrics
2939	list</command> subcommand to see which metrics are currently
2940	available. You can also use the <option>--list</option> option
2941	with any subcommand that modifies metric settings to find out
2942	which metrics were affected.
2943	</para>
2944
2945	<para>
2946	Note that the <command>VBoxManage metrics setup</command>
2947	subcommand discards all samples that may have been previously
2948	collected for the specified set of objects and metrics.
2949	</para>
2950
2951	<para>
2952	To enable or disable metrics collection without discarding the
2953	data, <command>VBoxManage metrics enable</command> and
2954	<command>VBoxManage metrics disable</command> subcommands can be
2955	used. Note that these subcommands expect metrics as parameters,
2956	not submetrics such as <computeroutput>CPU/Load</computeroutput>
2957	or <computeroutput>RAM/Usage</computeroutput>. In other words
2958	enabling <computeroutput>CPU/Load/User</computeroutput> while
2959	disabling <computeroutput>CPU/Load/Kernel</computeroutput> is not
2960	supported.
2961	</para>
2962
2963	<para>
2964	The host and VMs have different sets of associated metrics.
2965	Available metrics can be listed with <command>VBoxManage metrics
2966	list</command> subcommand.
2967	</para>
2968
2969	<para>
2970	A complete metric name may include an aggregate function. The name
2971	has the following form:
2972	<computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
2973	For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
2974	stands for the minimum amount of available memory over all
2975	retained data if applied to the host object.
2976	</para>
2977
2978	<para>
2979	Subcommands may apply to all objects and metrics or can be limited
2980	to one object and a list of metrics. If no objects or metrics are
2981	given in the parameters, the subcommands will apply to all
2982	available metrics of all objects. You may use an asterisk
2983	"<computeroutput>*</computeroutput>" to explicitly specify that
2984	the command should be applied to all objects or metrics. Use
2985	<computeroutput>host</computeroutput> as the object name to limit
2986	the scope of the command to host-related metrics. To limit the
2987	scope to a subset of metrics, use a metric list with names
2988	separated by commas.
2989	</para>
2990
2991	<para>
2992	For example, to query metric data on the CPU time spent in user
2993	and kernel modes by the virtual machine named
2994	<computeroutput>test</computeroutput>, use the following command:
2995	</para>
2996
2997	<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
2998
2999	<para>
3000	The following list summarizes the available subcommands:
3001	</para>
3002
3003	<variablelist>
3004
3005	<varlistentry>
3006	<term>
3007	<computeroutput>list</computeroutput>
3008	</term>
3009
3010	<listitem>
3011	<para>
3012	Shows the parameters of the currently existing metrics. Note
3013	that VM-specific metrics are only available when a
3014	particular VM is running.
3015	</para>
3016	</listitem>
3017	</varlistentry>
3018
3019	<varlistentry>
3020	<term>
3021	<computeroutput>setup</computeroutput>
3022	</term>
3023
3024	<listitem>
3025	<para>
3026	Sets the interval between taking two samples of metric data
3027	and the number of samples retained internally. The retained
3028	data is available for displaying with the
3029	<command>query</command> subcommand. The
3030	<computeroutput>--list</computeroutput> option shows which
3031	metrics have been modified as the result of the command
3032	execution.
3033	</para>
3034	</listitem>
3035	</varlistentry>
3036
3037	<varlistentry>
3038	<term>
3039	<computeroutput>enable</computeroutput>
3040	</term>
3041
3042	<listitem>
3043	<para>
3044	Resumes data collection after it has been stopped with the
3045	<command>disable</command> subcommand. Note that specifying
3046	submetrics as parameters will not enable underlying metrics.
3047	Use <computeroutput>--list</computeroutput> to find out if
3048	the command worked as expected.
3049	</para>
3050	</listitem>
3051	</varlistentry>
3052
3053	<varlistentry>
3054	<term>
3055	<computeroutput>disable</computeroutput>
3056	</term>
3057
3058	<listitem>
3059	<para>
3060	Suspends data collection without affecting collection
3061	parameters or collected data. Note that specifying
3062	submetrics as parameters will not disable underlying
3063	metrics. Use <computeroutput>--list</computeroutput> to find
3064	out if the command worked as expected.
3065	</para>
3066	</listitem>
3067	</varlistentry>
3068
3069	<varlistentry>
3070	<term>
3071	<computeroutput>query</computeroutput>
3072	</term>
3073
3074	<listitem>
3075	<para>
3076	Retrieves and displays the currently retained metric data.
3077	</para>
3078
3079	<note>
3080	<para>
3081	The <command>query</command> subcommand does not remove or
3082	flush retained data. If you query often enough you will
3083	see how old samples are gradually being phased out by new
3084	samples.
3085	</para>
3086	</note>
3087	</listitem>
3088	</varlistentry>
3089
3090	<varlistentry>
3091	<term>
3092	<computeroutput>collect</computeroutput>
3093	</term>
3094
3095	<listitem>
3096	<para>
3097	Sets the interval between taking two samples of metric data
3098	and the number of samples retained internally. The collected
3099	data is displayed periodically until Ctrl+C is pressed,
3100	unless the <computeroutput>--detach</computeroutput> option
3101	is specified. With the
3102	<computeroutput>--detach</computeroutput> option, this
3103	subcommand operates the same way as
3104	<computeroutput>setup</computeroutput> does. The
3105	<computeroutput>--list</computeroutput> option shows which
3106	metrics match the specified filter.
3107	</para>
3108	</listitem>
3109	</varlistentry>
3110
3111	</variablelist>
3112
3113	</sect1>
3114
3115	<sect1 id="vboxmanage-natnetwork">
3116
3117	<title>VBoxManage natnetwork</title>
3118
3119	<para>
3120	NAT networks use the Network Address Translation (NAT) service,
3121	which works in a similar way to a home router. It groups systems
3122	using it into a network and prevents outside systems from directly
3123	accessing those inside, while letting systems inside communicate
3124	with each other and outside systems using TCP and UDP over IPv4
3125	and IPv6.
3126	</para>
3127
3128	<para>
3129	A NAT service is attached to an internal network. Virtual machines
3130	to make use of one should be attached to it. The name of an
3131	internal network is chosen when the NAT service is created, and
3132	the internal network will be created if it does not already exist.
3133	The following is an example command to create a NAT network:
3134	</para>
3135
3136	<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
3137
3138	<para>
3139	Here, <computeroutput>natnet1</computeroutput> is the name of the
3140	internal network to be used and
3141	<computeroutput>192.168.15.0/24</computeroutput> is the network
3142	address and mask of the NAT service interface. By default, in this
3143	static configuration the gateway will be assigned the address
3144	192.168.15.1, the address after the interface address, though this
3145	is subject to change.
3146	</para>
3147
3148	<para>
3149	To add a DHCP server to the NAT network after creation, run the
3150	following command:
3151	</para>
3152
3153	<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
3154
3155	<para>
3156	The subcommands for <command>VBoxManage natnetwork</command> are
3157	as follows:
3158	</para>
3159
3160	<screen>VBoxManage natnetwork add --netname <name>
3161	[--network <network>]
3162	[--enable\|--disable]
3163	[--dhcp on\|off]
3164	[--port-forward-4 <rule>]
3165	[--loopback-4 <rule>]
3166	[--ipv6 on\|off]
3167	[--port-forward-6 <rule>]
3168	[--loopback-6 <rule>]
3169	</screen>
3170
3171	<para>
3172	<command>VBoxManage natnetwork add</command>: Creates a new
3173	internal network interface, and adds a NAT network service. This
3174	command is a prerequisite for enabling attachment of VMs to the
3175	NAT network. Parameters are as follows:
3176	</para>
3177
3178	<variablelist>
3179
3180	<varlistentry>
3181	<term>
3182	<computeroutput>--netname <name></computeroutput>
3183	</term>
3184
3185	<listitem>
3186	<para>
3187	Where <name> is the name of the new internal network
3188	interface on the host OS.
3189	</para>
3190	</listitem>
3191	</varlistentry>
3192
3193	<varlistentry>
3194	<term>
3195	<computeroutput>--network <network></computeroutput>
3196	</term>
3197
3198	<listitem>
3199	<para>
3200	Where <network> specifies the static or DHCP network
3201	address and mask of the NAT service interface. The default
3202	is a static network address.
3203	</para>
3204	</listitem>
3205	</varlistentry>
3206
3207	<varlistentry>
3208	<term>
3209	<computeroutput>--enable\|--disable</computeroutput>
3210	</term>
3211
3212	<listitem>
3213	<para>
3214	Enables and disables the NAT network service.
3215	</para>
3216	</listitem>
3217	</varlistentry>
3218
3219	<varlistentry>
3220	<term>
3221	<computeroutput>--dhcp on\|off</computeroutput>
3222	</term>
3223
3224	<listitem>
3225	<para>
3226	Enables and disables a DHCP server specified by
3227	<computeroutput>--netname</computeroutput>. Use of this
3228	option also indicates that it is a DHCP server.
3229	</para>
3230	</listitem>
3231	</varlistentry>
3232
3233	<varlistentry>
3234	<term>
3235	<computeroutput>--port-forward-4 <rule></computeroutput>
3236	</term>
3237
3238	<listitem>
3239	<para>
3240	Enables IPv4 port forwarding, with a rule specified by
3241	<rule>.
3242	</para>
3243	</listitem>
3244	</varlistentry>
3245
3246	<varlistentry>
3247	<term>
3248	<computeroutput>--loopback-4 <rule></computeroutput>
3249	</term>
3250
3251	<listitem>
3252	<para>
3253	Enables the IPv4 loopback interface, with a rule specified
3254	by <rule>.
3255	</para>
3256	</listitem>
3257	</varlistentry>
3258
3259	<varlistentry>
3260	<term>
3261	<computeroutput>--ipv6 on\|off</computeroutput>
3262	</term>
3263
3264	<listitem>
3265	<para>
3266	Enables and disables IPv6. The default setting is IPv4,
3267	disabling IPv6 enables IPv4.
3268	</para>
3269	</listitem>
3270	</varlistentry>
3271
3272	<varlistentry>
3273	<term>
3274	<computeroutput>--port-forward-6 <rule></computeroutput>
3275	</term>
3276
3277	<listitem>
3278	<para>
3279	Enables IPv6 port forwarding, with a rule specified by
3280	<rule>.
3281	</para>
3282	</listitem>
3283	</varlistentry>
3284
3285	<varlistentry>
3286	<term>
3287	<computeroutput>--loopback-6 <rule></computeroutput>
3288	</term>
3289
3290	<listitem>
3291	<para>
3292	Enables the IPv6 loopback interface, with a rule specified
3293	by <rule>.
3294	</para>
3295	</listitem>
3296	</varlistentry>
3297
3298	</variablelist>
3299
3300	<screen>VBoxManage natnetwork remove --netname <name> </screen>
3301
3302	<para>
3303	<command>VBoxManage natnetwork remove</command>: Removes a NAT
3304	network service. Parameters are as follows:
3305	</para>
3306
3307	<variablelist>
3308
3309	<varlistentry>
3310	<term>
3311	<computeroutput>--netname <name></computeroutput>
3312	</term>
3313
3314	<listitem>
3315	<para>
3316	Where <name> specifies an existing NAT network
3317	service. Does not remove any DHCP server enabled on the
3318	network.
3319	</para>
3320	</listitem>
3321	</varlistentry>
3322
3323	</variablelist>
3324
3325	<screen>VBoxManage natnetwork modify --netname <name>
3326	[--network <network>]
3327	[--enable\|--disable]
3328	[--dhcp on\|off]
3329	[--port-forward-4 <rule>]
3330	[--loopback-4 <rule>]
3331	[--ipv6 on\|off]
3332	[--port-forward-6 <rule>]
3333	[--loopback-6 <rule>]
3334	</screen>
3335
3336	<para>
3337	<command>VBoxManage natnetwork modify</command>: Modifies an
3338	existing NAT network service. Parameters are as follows:
3339	</para>
3340
3341	<variablelist>
3342
3343	<varlistentry>
3344	<term>
3345	<computeroutput>--netname <name></computeroutput>
3346	</term>
3347
3348	<listitem>
3349	<para>
3350	Where <name> specifies an existing NAT network
3351	service.
3352	</para>
3353	</listitem>
3354	</varlistentry>
3355
3356	<varlistentry>
3357	<term>
3358	<computeroutput>--network <network></computeroutput>
3359	</term>
3360
3361	<listitem>
3362	<para>
3363	Where <network> specifies the new static or DHCP
3364	network address and mask of the NAT service interface. The
3365	default is a static network address.
3366	</para>
3367	</listitem>
3368	</varlistentry>
3369
3370	<varlistentry>
3371	<term>
3372	<computeroutput>--enable\|--disable</computeroutput>
3373	</term>
3374
3375	<listitem>
3376	<para>
3377	Enables and disables the NAT network service.
3378	</para>
3379	</listitem>
3380	</varlistentry>
3381
3382	<varlistentry>
3383	<term>
3384	<computeroutput>--dhcp on\|off</computeroutput>
3385	</term>
3386
3387	<listitem>
3388	<para>
3389	Enables and disables a DHCP server. If a DHCP server is not
3390	present, using enable adds a new DHCP server.
3391	</para>
3392	</listitem>
3393	</varlistentry>
3394
3395	<varlistentry>
3396	<term>
3397	<computeroutput>--port-forward-4 <rule></computeroutput>
3398	</term>
3399
3400	<listitem>
3401	<para>
3402	Enables IPv4 port forwarding, with a rule specified by
3403	<rule>.
3404	</para>
3405	</listitem>
3406	</varlistentry>
3407
3408	<varlistentry>
3409	<term>
3410	<computeroutput>--loopback-4 <rule></computeroutput>
3411	</term>
3412
3413	<listitem>
3414	<para>
3415	Enables the IPv4 loopback interface, with a rule specified
3416	by <rule>.
3417	</para>
3418	</listitem>
3419	</varlistentry>
3420
3421	<varlistentry>
3422	<term>
3423	<computeroutput>--ipv6 on\|off</computeroutput>
3424	</term>
3425
3426	<listitem>
3427	<para>
3428	Enables and disables IPv6. The default setting is IPv4,
3429	disabling IPv6 enables IPv4.
3430	</para>
3431	</listitem>
3432	</varlistentry>
3433
3434	<varlistentry>
3435	<term>
3436	<computeroutput>--port-forward-6 <rule></computeroutput>
3437	</term>
3438
3439	<listitem>
3440	<para>
3441	Enables IPv6 port forwarding, with a rule specified by
3442	<rule>.
3443	</para>
3444	</listitem>
3445	</varlistentry>
3446
3447	<varlistentry>
3448	<term>
3449	<computeroutput>--loopback-6 <rule></computeroutput>
3450	</term>
3451
3452	<listitem>
3453	<para>
3454	Enables IPv6 loopback interface, with a rule specified by
3455	<rule>.
3456	</para>
3457	</listitem>
3458	</varlistentry>
3459
3460	</variablelist>
3461
3462	<screen>VBoxManage natnetwork start --netname <name>
3463	</screen>
3464
3465	<para>
3466	<command>VBoxManage natnetwork start</command>: Starts the
3467	specified NAT network service and any associated DHCP server.
3468	Parameters are as follows:
3469	</para>
3470
3471	<variablelist>
3472
3473	<varlistentry>
3474	<term>
3475	<computeroutput>--netname <name></computeroutput>
3476	</term>
3477
3478	<listitem>
3479	<para>
3480	Where <name> specifies an existing NAT network
3481	service.
3482	</para>
3483	</listitem>
3484	</varlistentry>
3485
3486	</variablelist>
3487
3488	<screen>VBoxManage natnetwork stop --netname <name>
3489	</screen>
3490
3491	<para>
3492	<command>VBoxManage natnetwork stop</command>: Stops the specified
3493	NAT network service and any DHCP server. Parameters are as
3494	follows:
3495	</para>
3496
3497	<variablelist>
3498
3499	<varlistentry>
3500	<term>
3501	<computeroutput>--netname <name></computeroutput>
3502	</term>
3503
3504	<listitem>
3505	<para>
3506	Where <name> specifies an existing NAT network
3507	service.
3508	</para>
3509	</listitem>
3510	</varlistentry>
3511
3512	</variablelist>
3513
3514	<screen>VBoxManage natnetwork list [<pattern>] </screen>
3515
3516	<para>
3517	<command>VBoxManage natnetwork list</command>: Lists all NAT
3518	network services, with optional filtering. Parameters are as
3519	follows:
3520	</para>
3521
3522	<variablelist>
3523
3524	<varlistentry>
3525	<term>
3526	<computeroutput>[<pattern>]</computeroutput>
3527	</term>
3528
3529	<listitem>
3530	<para>
3531	Where <pattern> is an optional filtering pattern.
3532	</para>
3533	</listitem>
3534	</varlistentry>
3535
3536	</variablelist>
3537
3538	</sect1>
3539
3540	<sect1 id="vboxmanage-hostonlyif">
3541
3542	<title>VBoxManage hostonlyif</title>
3543
3544	<para>
3545	The <command>hostonlyif</command> command enables you to change
3546	the IP configuration of a host-only network interface. For a
3547	description of host-only networking, see
3548	<xref linkend="network_hostonly" />. Each host-only interface is
3549	identified by a name and can either use the internal DHCP server
3550	or a manual IP configuration, both IP4 and IP6.
3551	</para>
3552
3553	<para>
3554	The following list summarizes the available subcommands:
3555	</para>
3556
3557	<variablelist>
3558
3559	<varlistentry>
3560	<term>
3561	<computeroutput>ipconfig "<name>"</computeroutput>
3562	</term>
3563
3564	<listitem>
3565	<para>
3566	Configures a host-only interface.
3567	</para>
3568	</listitem>
3569	</varlistentry>
3570
3571	<varlistentry>
3572	<term>
3573	<computeroutput>create</computeroutput>
3574	</term>
3575
3576	<listitem>
3577	<para>
3578	Creates a new vboxnet<N> interface on the host OS.
3579	This command is essential before you can attach VMs to a
3580	host-only network.
3581	</para>
3582	</listitem>
3583	</varlistentry>
3584
3585	<varlistentry>
3586	<term>
3587	<computeroutput>remove vboxnet<N></computeroutput>
3588	</term>
3589
3590	<listitem>
3591	<para>
3592	Removes a vboxnet<N> interface from the host OS.
3593	</para>
3594	</listitem>
3595	</varlistentry>
3596
3597	</variablelist>
3598
3599	</sect1>
3600
3601	<xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3602
3603	<xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3604
3605	<sect1 id="vboxmanage-usbdevsource">
3606
3607	<title>VBoxManage usbdevsource</title>
3608
3609	<para>
3610	The <command>usbdevsource</command> commands enable you to add and
3611	remove USB devices globally.
3612	</para>
3613
3614	<para>
3615	The following command adds a USB device.
3616	</para>
3617
3618	<screen>VBoxManage usbdevsource add <source name>
3619	--backend <backend>
3620	--address <address>
3621	</screen>
3622
3623	<para>
3624	Where the command line options are as follows:
3625	</para>
3626
3627	<itemizedlist>
3628
3629	<listitem>
3630	<para>
3631	<computeroutput><source name></computeroutput>:
3632	Specifies the ID of the source USB device to be added.
3633	Mandatory.
3634	</para>
3635	</listitem>
3636
3637	<listitem>
3638	<para>
3639	<computeroutput>--backend <backend></computeroutput>:
3640	Specifies the USB proxy service backend to use. Mandatory.
3641	</para>
3642	</listitem>
3643
3644	<listitem>
3645	<para>
3646	<computeroutput> --address <address></computeroutput>:
3647	Specifies the backend specific address. Mandatory.
3648	</para>
3649	</listitem>
3650
3651	</itemizedlist>
3652
3653	<para>
3654	The following command removes a USB device.
3655	</para>
3656
3657	<screen>VBoxManage usbdevsource remove <source name>
3658	</screen>
3659
3660	<para>
3661	Where the command line options are as follows:
3662	</para>
3663
3664	<itemizedlist>
3665
3666	<listitem>
3667	<para>
3668	<computeroutput><source name></computeroutput>:
3669	Specifies the ID of the source USB device to be removed.
3670	Mandatory.
3671	</para>
3672	</listitem>
3673
3674	</itemizedlist>
3675
3676	</sect1>
3677
3678	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3679
3680	<xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3681
3682	<xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3683
3684	<!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
3685	sect1, so it's not possible to have them "in place" -->
3686
3687	<xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
3688
3689	</chapter>

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

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

Download in other formats: