user_VBoxManage.xml@ 94212

Last change on this file since 94212 was 94212, checked in by vboxsync, 3 years ago
doc/manual,FE/VBoxManage: Convert hostonlyif command to refentry documentation, bugref:9186
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 41.9 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	<xi:include href="user_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1114
1115	<xi:include href="user_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1116
1117	<xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1118
1119	<xi:include href="user_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1120
1121	<xi:include href="user_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1122
1123	<xi:include href="user_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1124
1125	<xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1126
1127	<xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1128
1129	<sect1 id="vboxmanage-usbdevsource">
1130
1131	<title>VBoxManage usbdevsource</title>
1132
1133	<para>
1134	The <command>usbdevsource</command> commands enable you to add and
1135	remove USB devices globally.
1136	</para>
1137
1138	<para>
1139	The following command adds a USB device.
1140	</para>
1141
1142	<screen>VBoxManage usbdevsource add <source name>
1143	--backend <backend>
1144	--address <address>
1145	</screen>
1146
1147	<para>
1148	Where the command line options are as follows:
1149	</para>
1150
1151	<itemizedlist>
1152
1153	<listitem>
1154	<para>
1155	<computeroutput><source name></computeroutput>:
1156	Specifies the ID of the source USB device to be added.
1157	Mandatory.
1158	</para>
1159	</listitem>
1160
1161	<listitem>
1162	<para>
1163	<computeroutput>--backend <backend></computeroutput>:
1164	Specifies the USB proxy service backend to use. Mandatory.
1165	</para>
1166	</listitem>
1167
1168	<listitem>
1169	<para>
1170	<computeroutput> --address <address></computeroutput>:
1171	Specifies the backend specific address. Mandatory.
1172	</para>
1173	</listitem>
1174
1175	</itemizedlist>
1176
1177	<para>
1178	The following command removes a USB device.
1179	</para>
1180
1181	<screen>VBoxManage usbdevsource remove <source name>
1182	</screen>
1183
1184	<para>
1185	Where the command line options are as follows:
1186	</para>
1187
1188	<itemizedlist>
1189
1190	<listitem>
1191	<para>
1192	<computeroutput><source name></computeroutput>:
1193	Specifies the ID of the source USB device to be removed.
1194	Mandatory.
1195	</para>
1196	</listitem>
1197
1198	</itemizedlist>
1199
1200	</sect1>
1201
1202	<xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1203
1204	<xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1205
1206	<xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1207
1208	<!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
1209	sect1, so it's not possible to have them "in place" -->
1210
1211	<xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
1212
1213	</chapter>

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

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

Download in other formats: