VirtualBox

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

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

doc/manual,FE/VBoxManage: Convert modifymedium command to refentry documentation, ​bugref:9186
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 16.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 <xi:include href="user_man_VBoxManage-modifymedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
358
359 <xi:include href="user_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
360
361 <xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
362
363 <xi:include href="user_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
364
365 <xi:include href="user_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
366
367 <xi:include href="user_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
368
369 <xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
370
371 <xi:include href="user_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
372
373 <xi:include href="user_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
374
375 <xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
376
377 <xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
378
379 <xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
380
381 <xi:include href="user_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
382
383 <xi:include href="user_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
384
385 <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
386
387 <xi:include href="user_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
388
389 <xi:include href="user_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
390
391 <xi:include href="user_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
392
393 <xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
394
395 <xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
396
397 <xi:include href="user_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
398
399 <xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
400
401 <xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
402
403 <xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
404
405 <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to
406 sect1, so it's not possible to have them "in place" -->
407
408 <xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
409
410</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