VirtualBox

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

Last change on this file since 94217 was 94217, checked in by vboxsync, 3 years ago

doc/manual,FE/VBoxManage: Convert storageattach command to refentry documentation, ​bugref:9186

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 22.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
133VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
134(C) 2005-2018 Oracle Corporation
135All rights reserved.
136
137Virtual machine 'SUSE 10.2' is created.
138UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
139Settings 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 <xi:include href="user_man_VBoxManage-storageattach.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
348
349 <xi:include href="user_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
350
351 <xi:include href="user_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
352
353 <xi:include href="user_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
354
355 <xi:include href="user_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
356
357 <sect1 id="vboxmanage-modifymedium">
358
359 <title>VBoxManage modifymedium</title>
360
361 <para>
362 With the <command>modifymedium</command> command, you can change
363 the characteristics of a disk image after it has been created.
364 </para>
365
366<screen>VBoxManage modifymedium [disk|dvd|floppy] &lt;uuid|filename&gt;
367 [--type normal|writethrough|immutable|shareable|
368 readonly|multiattach]
369 [--autoreset on|off]
370 [--property &lt;name=[value]&gt;]
371 [--compact]
372 [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]
373 [--move &lt;path&gt;]
374 [--setlocation &lt;path&gt;]</screen>
375
376 <note>
377 <para>
378 For compatibility with earlier versions of &product-name;, the
379 <command>modifyvdi</command> and <command>modifyhd</command>
380 commands are also supported and mapped internally to the
381 <command>modifymedium</command> command.
382 </para>
383 </note>
384
385 <para>
386 The disk image to modify must be specified either by its UUID, if
387 the medium is registered, or by its filename. Registered images
388 can be listed using <command>VBoxManage list hdds</command>, see
389 <xref linkend="vboxmanage-list" />. A filename must be specified
390 as a valid path, either as an absolute path or as a relative path
391 starting from the current directory.
392 </para>
393
394 <para>
395 The following options are available:
396 </para>
397
398 <itemizedlist>
399
400 <listitem>
401 <para>
402 With the <computeroutput>--type</computeroutput> argument, you
403 can change the type of an existing image between the normal,
404 immutable, write-through and other modes. See
405 <xref
406 linkend="hdimagewrites" />.
407 </para>
408 </listitem>
409
410 <listitem>
411 <para>
412 For immutable hard disks only, the <computeroutput>--autoreset
413 on|off</computeroutput> option determines whether the disk is
414 automatically reset on every VM startup. See
415 <xref linkend="hdimagewrites" />. By default, autoreset is on.
416 </para>
417 </listitem>
418
419 <listitem>
420 <para>
421 The <computeroutput>--compact</computeroutput> option can be
422 used to compact disk images. Compacting removes blocks that
423 only contains zeroes. Using this option will shrink a
424 dynamically allocated image. It will reduce the
425 <emphasis>physical</emphasis> size of the image without
426 affecting the logical size of the virtual disk. Compaction
427 works both for base images and for differencing images created
428 as part of a snapshot.
429 </para>
430
431 <para>
432 For this operation to be effective, it is required that free
433 space in the guest system first be zeroed out using a suitable
434 software tool. For Windows guests, you can use the
435 <command>sdelete</command> tool provided by Microsoft. Run
436 <command>sdelete -z</command> in the guest to zero the free
437 disk space, before compressing the virtual disk image. For
438 Linux, use the <command>zerofree</command> utility which
439 supports ext2/ext3 filesystems. For Mac OS X guests, use the
440 <computeroutput>diskutil secureErase freespace 0
441 /</computeroutput> command from an elevated Terminal.
442 </para>
443
444 <para>
445 Please note that compacting is currently only available for
446 VDI images. A similar effect can be achieved by zeroing out
447 free blocks and then cloning the disk to any other dynamically
448 allocated format. You can use this workaround until compacting
449 is also supported for disk formats other than VDI.
450 </para>
451 </listitem>
452
453 <listitem>
454 <para>
455 The <computeroutput>--resize x</computeroutput> option, where
456 x is the desired new total space in megabytes enables you to
457 change the capacity of an existing image. This adjusts the
458 <emphasis>logical</emphasis> size of a virtual disk without
459 affecting the physical size much.
460 </para>
461
462 <para>
463 This option currently works only for VDI and VHD formats, and
464 only for the dynamically allocated variants. It can only be
465 used to expand, but not shrink, the capacity. For example, if
466 you originally created a 10 GB disk which is now full, you can
467 use the <computeroutput>--resize 15360</computeroutput>
468 command to change the capacity to 15 GB (15,360 MB) without
469 having to create a new image and copy all data from within a
470 virtual machine. Note however that this only changes the drive
471 capacity. You will typically next need to use a partition
472 management tool inside the guest to adjust the main partition
473 to fill the drive.
474 </para>
475
476 <para>
477 The <computeroutput>--resizebyte x</computeroutput> option
478 does almost the same thing, except that x is expressed in
479 bytes instead of megabytes.
480 </para>
481 </listitem>
482
483 <listitem>
484 <para>
485 The <computeroutput>--move &lt;path&gt;</computeroutput>
486 option can be used to relocate a medium to a different
487 location &lt;path&gt; on the host file system. The path can be
488 either relative to the current directory or absolute.
489 </para>
490 </listitem>
491
492 <listitem>
493 <para>
494 The <computeroutput>--setlocation
495 &lt;path&gt;</computeroutput> option can be used to set the
496 new location &lt;path&gt; of the medium on the host file
497 system if the medium has been moved for any reasons. The path
498 can be either relative to the current directory or absolute.
499 </para>
500
501 <note>
502 <para>
503 The new location is used as is, without any sanity checks.
504 The user is responsible for setting the correct path.
505 </para>
506 </note>
507 </listitem>
508
509 </itemizedlist>
510
511 </sect1>
512
513 <xi:include href="user_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
514
515 <xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
516
517 <xi:include href="user_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
518
519 <xi:include href="user_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
520
521 <xi:include href="user_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
522
523 <xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
524
525 <xi:include href="user_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
526
527 <xi:include href="user_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
528
529 <xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
530
531 <xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
532
533 <xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
534
535 <xi:include href="user_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
536
537 <xi:include href="user_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
538
539 <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
540
541 <xi:include href="user_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
542
543 <xi:include href="user_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
544
545 <xi:include href="user_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
546
547 <xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
548
549 <xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
550
551 <xi:include href="user_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
552
553 <xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
554
555 <xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
556
557 <xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
558
559 <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
560 sect1, so it's not possible to have them "in place" -->
561
562 <xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
563
564</chapter>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette