1 | <?xml version="1.0" encoding="UTF-8"?>
|
---|
2 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
---|
3 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
---|
4 | <chapter id="vboxmanage">
|
---|
5 | <title>VBoxManage</title>
|
---|
6 |
|
---|
7 | <sect1>
|
---|
8 | <title>Introduction</title>
|
---|
9 |
|
---|
10 | <para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
|
---|
11 | the command-line interface to VirtualBox. With it, you can completely
|
---|
12 | control VirtualBox from the command line of your host operating system.
|
---|
13 | VBoxManage supports all the features that the graphical user interface
|
---|
14 | gives you access to, but it supports a lot more than that. It exposes
|
---|
15 | really all the features of the virtualization engine, even those that
|
---|
16 | cannot (yet) be accessed from the GUI.</para>
|
---|
17 |
|
---|
18 | <para>You will need to use the command line if you want to</para>
|
---|
19 |
|
---|
20 | <para><itemizedlist>
|
---|
21 | <listitem>
|
---|
22 | <para>use a different user interface than the main GUI (for example,
|
---|
23 | VBoxSDL or the VBoxHeadless server);</para>
|
---|
24 | </listitem>
|
---|
25 |
|
---|
26 | <listitem>
|
---|
27 | <para>control some of the more advanced and experimental
|
---|
28 | configuration settings for a VM.</para>
|
---|
29 | </listitem>
|
---|
30 | </itemizedlist></para>
|
---|
31 |
|
---|
32 | <para>There are two main things to keep in mind when using
|
---|
33 | <computeroutput>VBoxManage</computeroutput>: First,
|
---|
34 | <computeroutput>VBoxManage</computeroutput> must always be used with a
|
---|
35 | specific "subcommand", such as "list" or "createvm" or "startvm". All the
|
---|
36 | subcommands that <computeroutput>VBoxManage</computeroutput> supports are
|
---|
37 | described in detail in <xref linkend="vboxmanage" />.</para>
|
---|
38 |
|
---|
39 | <para>Second, most of these subcommands require that you specify a
|
---|
40 | particular virtual machine after the subcommand. There are two ways you
|
---|
41 | can do this:</para>
|
---|
42 |
|
---|
43 | <itemizedlist>
|
---|
44 | <listitem>
|
---|
45 | <para>You can specify the VM name, as it is shown in the VirtualBox
|
---|
46 | GUI. Note that if that name contains spaces, then you must enclose the
|
---|
47 | entire name in double quotes (as it is always required with command
|
---|
48 | line arguments that contain spaces).</para>
|
---|
49 |
|
---|
50 | <para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
|
---|
51 | </listitem>
|
---|
52 |
|
---|
53 | <listitem>
|
---|
54 | <para>You can specify the UUID, which is the internal unique
|
---|
55 | identifier that VirtualBox uses to refer to the virtual machine.
|
---|
56 | Assuming that the aforementioned VM called "Windows XP" has the UUID
|
---|
57 | shown below, the following command has the same effect as the
|
---|
58 | previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
|
---|
59 | </listitem>
|
---|
60 | </itemizedlist>
|
---|
61 |
|
---|
62 | <para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
|
---|
63 | have all currently registered VMs listed with all their settings,
|
---|
64 | including their respective names and UUIDs.</para>
|
---|
65 |
|
---|
66 | <para>Some typical examples of how to control VirtualBox from the command
|
---|
67 | line are listed below:</para>
|
---|
68 |
|
---|
69 | <itemizedlist>
|
---|
70 | <listitem>
|
---|
71 | <para>To create a new virtual machine from the command line and
|
---|
72 | immediately register it with VirtualBox, use
|
---|
73 | <computeroutput>VBoxManage createvm</computeroutput> with the
|
---|
74 | <computeroutput>--register</computeroutput> option,<footnote>
|
---|
75 | <para>For details, see <xref
|
---|
76 | linkend="vboxmanage-createvm" />.</para>
|
---|
77 | </footnote> like this:</para>
|
---|
78 |
|
---|
79 | <screen>$ VBoxManage createvm --name "SUSE 10.2" --register
|
---|
80 | VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
|
---|
81 | (C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
|
---|
82 | All rights reserved.
|
---|
83 |
|
---|
84 | Virtual machine 'SUSE 10.2' is created.
|
---|
85 | UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
|
---|
86 | Settings file: '/home/username/.VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'
|
---|
87 | </screen>
|
---|
88 |
|
---|
89 | <para>As can be seen from the above output, a new virtual machine has
|
---|
90 | been created with a new UUID and a new XML settings file.</para>
|
---|
91 | </listitem>
|
---|
92 |
|
---|
93 | <listitem>
|
---|
94 | <para>To show the configuration of a particular VM, use
|
---|
95 | <computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
|
---|
96 | linkend="vboxmanage-showvminfo" /> for details and an example.</para>
|
---|
97 | </listitem>
|
---|
98 |
|
---|
99 | <listitem>
|
---|
100 | <para>To change settings while a VM is powered off, use
|
---|
101 | <computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
|
---|
102 | follows:<screen>VBoxManage modifyvm "Windows XP" --memory "512MB"</screen></para>
|
---|
103 |
|
---|
104 | <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
|
---|
105 | </listitem>
|
---|
106 |
|
---|
107 | <listitem>
|
---|
108 | <para>To change the storage configuration (e.g. to add a storage
|
---|
109 | controller and then a virtual disk), use <computeroutput>VBoxManage
|
---|
110 | storagectl</computeroutput> and <computeroutput>VBoxManage
|
---|
111 | storageattach</computeroutput>; see <xref
|
---|
112 | linkend="vboxmanage-storagectl" /> and <xref
|
---|
113 | linkend="vboxmanage-storageattach" /> for details.</para>
|
---|
114 | </listitem>
|
---|
115 |
|
---|
116 | <listitem>
|
---|
117 | <para>To control VM operation, use one of the following:<itemizedlist>
|
---|
118 | <listitem>
|
---|
119 | <para>To start a VM that is currently powered off, use
|
---|
120 | <computeroutput>VBoxManage startvm</computeroutput>; see <xref
|
---|
121 | linkend="vboxmanage-startvm" /> for details.</para>
|
---|
122 | </listitem>
|
---|
123 |
|
---|
124 | <listitem>
|
---|
125 | <para>To pause or save a VM that is currently running or change
|
---|
126 | some of its settings, use <computeroutput>VBoxManage
|
---|
127 | controlvm</computeroutput>; see <xref
|
---|
128 | linkend="vboxmanage-controlvm" /> for details.</para>
|
---|
129 | </listitem>
|
---|
130 | </itemizedlist></para>
|
---|
131 | </listitem>
|
---|
132 | </itemizedlist>
|
---|
133 | </sect1>
|
---|
134 |
|
---|
135 | <sect1>
|
---|
136 | <title>Commands overview</title>
|
---|
137 |
|
---|
138 | <para>When running VBoxManage without parameters or when supplying an
|
---|
139 | invalid command line, the below syntax diagram will be shown. Note that
|
---|
140 | the output will be slightly different depending on the host platform; when
|
---|
141 | in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
|
---|
142 | for the commands available on your particular host.</para>
|
---|
143 |
|
---|
144 | <screen>$VBOX_MANAGE_OUTPUT</screen>
|
---|
145 |
|
---|
146 | <para>Each time VBoxManage is invoked, only one command can be executed.
|
---|
147 | However, a command might support several subcommands which then can be
|
---|
148 | invoked in one single call. The following sections provide detailed
|
---|
149 | reference information on the different commands.</para>
|
---|
150 | </sect1>
|
---|
151 |
|
---|
152 | <sect1 id="vboxmanage-general">
|
---|
153 | <title>General options</title>
|
---|
154 | <para>
|
---|
155 | <itemizedlist>
|
---|
156 | <listitem>
|
---|
157 | <para><computeroutput>--version</computeroutput>: show the version of
|
---|
158 | this tool and exit.</para>
|
---|
159 | </listitem>
|
---|
160 | <listitem>
|
---|
161 | <para><computeroutput>--nologo</computeroutput>: suppress the output
|
---|
162 | of the logo information (useful for scripts)</para>
|
---|
163 | </listitem>
|
---|
164 | <listitem>
|
---|
165 | <para><computeroutput>--settingspw</computeroutput>: specifiy a settings
|
---|
166 | password</para>
|
---|
167 | </listitem>
|
---|
168 | <listitem>
|
---|
169 | <para><computeroutput>--settingspwfile</computeroutput>: specify a file
|
---|
170 | containing the settings password.</para>
|
---|
171 | </listitem>
|
---|
172 | </itemizedlist>
|
---|
173 | The settings password is used for certain settings which need to be
|
---|
174 | stored encrypted for security reasons. At the moment, the only encrypted
|
---|
175 | setting is the iSCSI initiator secret (see
|
---|
176 | <xref linkend="vboxmanage-storageattach" /> for details). As long as no
|
---|
177 | settings password is specified, this information is stored in
|
---|
178 | <emphasis role="bold">plain text</emphasis>. After using the
|
---|
179 | <computeroutput>--settingspw|--settingspwfile</computeroutput> option
|
---|
180 | once, it must be always used, otherwise the encrypted setting cannot
|
---|
181 | be unencrypted.
|
---|
182 | </para>
|
---|
183 | </sect1>
|
---|
184 |
|
---|
185 | <sect1 id="vboxmanage-list">
|
---|
186 | <title>VBoxManage list</title>
|
---|
187 |
|
---|
188 | <para>The <computeroutput>list</computeroutput> command gives relevant
|
---|
189 | information about your system and information about VirtualBox's current
|
---|
190 | settings.</para>
|
---|
191 |
|
---|
192 | <para>The following subcommands are available with
|
---|
193 | <computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
|
---|
194 | <listitem>
|
---|
195 | <para><computeroutput>vms</computeroutput> lists all virtual
|
---|
196 | machines currently registered with VirtualBox. By default this
|
---|
197 | displays a compact list with each VM's name and UUID; if you also
|
---|
198 | specify <computeroutput>--long</computeroutput> or
|
---|
199 | <computeroutput>-l</computeroutput>, this will be a detailed list as
|
---|
200 | with the <computeroutput>showvminfo</computeroutput> command (see
|
---|
201 | below).</para>
|
---|
202 | </listitem>
|
---|
203 |
|
---|
204 | <listitem>
|
---|
205 | <para><computeroutput>runningvms</computeroutput> lists all
|
---|
206 | currently running virtual machines by their unique identifiers
|
---|
207 | (UUIDs) in the same format as with
|
---|
208 | <computeroutput>vms</computeroutput>.</para>
|
---|
209 | </listitem>
|
---|
210 |
|
---|
211 | <listitem>
|
---|
212 | <para><computeroutput>ostypes</computeroutput> lists all guest
|
---|
213 | operating systems presently known to VirtualBox, along with the
|
---|
214 | identifiers used to refer to them with the
|
---|
215 | <computeroutput>modifyvm</computeroutput> command.</para>
|
---|
216 | </listitem>
|
---|
217 |
|
---|
218 | <listitem>
|
---|
219 | <para><computeroutput>hostdvds</computeroutput>,
|
---|
220 | <computeroutput>hostfloppies</computeroutput>, respectively, list
|
---|
221 | DVD, floppy, bridged networking and host-only networking interfaces
|
---|
222 | on the host, along with the name used to access them from within
|
---|
223 | VirtualBox.</para>
|
---|
224 | </listitem>
|
---|
225 |
|
---|
226 | <listitem>
|
---|
227 | <para><computeroutput>bridgedifs</computeroutput>,
|
---|
228 | <computeroutput>hostonlyifs</computeroutput> and
|
---|
229 | <computeroutput>dhcpservers</computeroutput>, respectively, list
|
---|
230 | bridged network interfaces, host-only network interfaces and DHCP
|
---|
231 | servers currently available on the host. Please see <xref
|
---|
232 | linkend="networkingdetails" /> for details on these.</para>
|
---|
233 | </listitem>
|
---|
234 |
|
---|
235 | <listitem>
|
---|
236 | <para><computeroutput>hostinfo</computeroutput> displays information
|
---|
237 | about the host system, such as CPUs, memory size and operating
|
---|
238 | system version.</para>
|
---|
239 | </listitem>
|
---|
240 |
|
---|
241 | <listitem>
|
---|
242 | <para><computeroutput>hostcpuids</computeroutput> dumps the CPUID
|
---|
243 | parameters for the host CPUs. This can be used for a more fine
|
---|
244 | grained analyis of the host's virtualization capabilities.</para>
|
---|
245 | </listitem>
|
---|
246 |
|
---|
247 | <listitem>
|
---|
248 | <para><computeroutput>hddbackends</computeroutput> lists all known
|
---|
249 | virtual disk back-ends of VirtualBox. For each such format (such as
|
---|
250 | VDI, VMDK or RAW), this lists the back-end's capabilities and
|
---|
251 | configuration.</para>
|
---|
252 | </listitem>
|
---|
253 |
|
---|
254 | <listitem>
|
---|
255 | <para><computeroutput>hdds</computeroutput>,
|
---|
256 | <computeroutput>dvds</computeroutput> and
|
---|
257 | <computeroutput>floppies</computeroutput> all give you information
|
---|
258 | about virtual disk images currently in use by VirtualBox, including
|
---|
259 | all their settings, the unique identifiers (UUIDs) associated with
|
---|
260 | them by VirtualBox and all files associated with them. This is the
|
---|
261 | command-line equivalent of the Virtual Media Manager; see <xref
|
---|
262 | linkend="vdis" />.</para>
|
---|
263 | </listitem>
|
---|
264 |
|
---|
265 | <listitem>
|
---|
266 | <para><computeroutput>usbhost</computeroutput> supplies information
|
---|
267 | about USB devices attached to the host, notably information useful
|
---|
268 | for constructing USB filters and whether they are currently in use
|
---|
269 | by the host.</para>
|
---|
270 | </listitem>
|
---|
271 |
|
---|
272 | <listitem>
|
---|
273 | <para><computeroutput>usbfilters</computeroutput> lists all global
|
---|
274 | USB filters registered with VirtualBox -- that is, filters for
|
---|
275 | devices which are accessible to all virtual machines -- and displays
|
---|
276 | the filter parameters.</para>
|
---|
277 | </listitem>
|
---|
278 |
|
---|
279 | <listitem>
|
---|
280 | <para><computeroutput>systemproperties</computeroutput> displays
|
---|
281 | some global VirtualBox settings, such as minimum and maximum guest
|
---|
282 | RAM and virtual hard disk size, folder settings and the current
|
---|
283 | authentication library in use.</para>
|
---|
284 | </listitem>
|
---|
285 |
|
---|
286 | <listitem>
|
---|
287 | <para><computeroutput>extpacks</computeroutput> displays all
|
---|
288 | VirtualBox extension packs currently installed; see <xref
|
---|
289 | linkend="intro-installing" /> and <xref
|
---|
290 | linkend="vboxmanage-extpack" /> for more information.</para>
|
---|
291 | </listitem>
|
---|
292 | </itemizedlist></para>
|
---|
293 | </sect1>
|
---|
294 |
|
---|
295 | <sect1 id="vboxmanage-showvminfo">
|
---|
296 | <title>VBoxManage showvminfo</title>
|
---|
297 |
|
---|
298 | <para>The <computeroutput>showvminfo</computeroutput> command shows
|
---|
299 | information about a particular virtual machine. This is the same
|
---|
300 | information as <computeroutput>VBoxManage list vms --long</computeroutput>
|
---|
301 | would show for all virtual machines.</para>
|
---|
302 |
|
---|
303 | <para>You will get information similar to the following:</para>
|
---|
304 |
|
---|
305 | <para><screen>$ VBoxManage showvminfo "Windows XP"
|
---|
306 | VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
|
---|
307 | (C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
|
---|
308 | All rights reserved.
|
---|
309 |
|
---|
310 | Name: Windows XP
|
---|
311 | Guest OS: Other/Unknown
|
---|
312 | UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7
|
---|
313 | Config file: /home/username/.VirtualBox/Machines/Windows XP/Windows XP.xml
|
---|
314 | Memory size: 512MB
|
---|
315 | VRAM size: 12MB
|
---|
316 | Number of CPUs: 2
|
---|
317 | Synthetic Cpu: off
|
---|
318 | Boot menu mode: message and menu
|
---|
319 | Boot Device (1): DVD
|
---|
320 | Boot Device (2): HardDisk
|
---|
321 | Boot Device (3): Not Assigned
|
---|
322 | Boot Device (4): Not Assigned
|
---|
323 | ACPI: on
|
---|
324 | IOAPIC: on
|
---|
325 | PAE: on
|
---|
326 | Time offset: 0 ms
|
---|
327 | Hardw. virt.ext: on
|
---|
328 | Hardw. virt.ext exclusive: on
|
---|
329 | Nested Paging: on
|
---|
330 | VT-x VPID: off
|
---|
331 | State: powered off (since 2009-10-20T14:52:19.000000000)
|
---|
332 | Monitor count: 1
|
---|
333 | 3D Acceleration: off
|
---|
334 | 2D Video Acceleration: off
|
---|
335 | Teleporter Enabled: off
|
---|
336 | Teleporter Port: 0
|
---|
337 | Teleporter Address:
|
---|
338 | Teleporter Password:
|
---|
339 | Storage Controller (0): IDE Controller
|
---|
340 | Storage Controller Type (0): PIIX4
|
---|
341 | Storage Controller (1): Floppy Controller 1
|
---|
342 | Storage Controller Type (1): I82078
|
---|
343 | IDE Controller (0, 0): /home/user/windows.vdi (UUID: 46f6e53a-4557-460a-9b95-68b0f17d744b)
|
---|
344 | IDE Controller (0, 1): /home/user/openbsd-cd46.iso (UUID: 4335e162-59d3-4512-91d5-b63e94eebe0b)
|
---|
345 | Floppy Controller 1 (0, 0): /home/user/floppy.img (UUID: 62ac6ccb-df36-42f2-972e-22f836368137)
|
---|
346 | NIC 1: disabled
|
---|
347 | NIC 2: disabled
|
---|
348 | NIC 3: disabled
|
---|
349 | NIC 4: disabled
|
---|
350 | NIC 5: disabled
|
---|
351 | NIC 6: disabled
|
---|
352 | NIC 7: disabled
|
---|
353 | NIC 8: disabled
|
---|
354 | UART 1: disabled
|
---|
355 | UART 2: disabled
|
---|
356 | Audio: disabled (Driver: Unknown)
|
---|
357 | Clipboard Mode: Bidirectional
|
---|
358 | VRDE: disabled
|
---|
359 | USB: disabled
|
---|
360 |
|
---|
361 | USB Device Filters:
|
---|
362 | <none>
|
---|
363 |
|
---|
364 | Shared folders:
|
---|
365 | <none>
|
---|
366 |
|
---|
367 | Statistics update: disabled
|
---|
368 | </screen></para>
|
---|
369 | </sect1>
|
---|
370 |
|
---|
371 | <sect1 id="vboxmanage-registervm">
|
---|
372 | <title>VBoxManage registervm / unregistervm</title>
|
---|
373 |
|
---|
374 | <para>The <computeroutput>registervm</computeroutput> command allows you
|
---|
375 | to import a virtual machine definition in an XML file into VirtualBox. The
|
---|
376 | machine must not conflict with one already registered in VirtualBox and it
|
---|
377 | may not have any hard or removable disks attached. It is advisable to
|
---|
378 | place the definition file in the machines folder before registering
|
---|
379 | it.<note>
|
---|
380 | <para>When creating a new virtual machine with
|
---|
381 | <computeroutput>VBoxManage createvm</computeroutput> (see below), you
|
---|
382 | can directly specify the <computeroutput>--register</computeroutput>
|
---|
383 | option to avoid having to register it separately.</para>
|
---|
384 | </note></para>
|
---|
385 |
|
---|
386 | <para>The <computeroutput>unregistervm</computeroutput> command
|
---|
387 | unregisters a virtual machine. If
|
---|
388 | <computeroutput>--delete</computeroutput> is also specified, the following
|
---|
389 | files will automatically be deleted as well:<orderedlist>
|
---|
390 | <listitem>
|
---|
391 | <para>all hard disk image files, including differencing files, which
|
---|
392 | are used by the machine and not shared with other machines;</para>
|
---|
393 | </listitem>
|
---|
394 |
|
---|
395 | <listitem>
|
---|
396 | <para>saved state files that the machine created, if any (one if the
|
---|
397 | machine was in "saved" state and one for each online
|
---|
398 | snapshot);</para>
|
---|
399 | </listitem>
|
---|
400 |
|
---|
401 | <listitem>
|
---|
402 | <para>the machine XML file and its backups;</para>
|
---|
403 | </listitem>
|
---|
404 |
|
---|
405 | <listitem>
|
---|
406 | <para>the machine log files, if any;</para>
|
---|
407 | </listitem>
|
---|
408 |
|
---|
409 | <listitem>
|
---|
410 | <para>the machine directory, if it is empty after having deleted all
|
---|
411 | the above.</para>
|
---|
412 | </listitem>
|
---|
413 | </orderedlist></para>
|
---|
414 | </sect1>
|
---|
415 |
|
---|
416 | <sect1>
|
---|
417 | <title id="vboxmanage-createvm">VBoxManage createvm</title>
|
---|
418 |
|
---|
419 | <para>This command creates a new XML virtual machine definition
|
---|
420 | file.</para>
|
---|
421 |
|
---|
422 | <para>The <computeroutput>--name <name></computeroutput> parameter
|
---|
423 | is required and must specify the name of the machine. Since this name is
|
---|
424 | used by default as the file name of the settings file (with the extension
|
---|
425 | <computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
|
---|
426 | of the <computeroutput>.VirtualBox/Machines</computeroutput> folder), it
|
---|
427 | must conform to your host operating system's requirements for file name
|
---|
428 | specifications. If the VM is later renamed, the file and folder names will
|
---|
429 | change automatically.</para>
|
---|
430 |
|
---|
431 | <para>However, if the <computeroutput>--basefolder
|
---|
432 | <path></computeroutput> option is used, the machine folder will be
|
---|
433 | named <computeroutput><path></computeroutput>. In this case, the
|
---|
434 | names of the file and the folder will not change if the virtual machine is
|
---|
435 | renamed.</para>
|
---|
436 |
|
---|
437 | <para>By default, this command only creates the XML file without
|
---|
438 | automatically registering the VM with your VirtualBox installation. To
|
---|
439 | register the VM instantly, use the optional
|
---|
440 | <computeroutput>--register</computeroutput> option, or run
|
---|
441 | <computeroutput>VBoxManage registervm</computeroutput> separately
|
---|
442 | afterwards.</para>
|
---|
443 | </sect1>
|
---|
444 |
|
---|
445 | <sect1 id="vboxmanage-modifyvm">
|
---|
446 | <title>VBoxManage modifyvm</title>
|
---|
447 |
|
---|
448 | <para>This command changes the properties of a registered virtual machine
|
---|
449 | which is not running. Most of the properties that this command makes
|
---|
450 | available correspond to the VM settings that VirtualBox graphical user
|
---|
451 | interface displays in each VM's "Settings" dialog; these were described in
|
---|
452 | <xref linkend="BasicConcepts" />. Some of the more advanced settings,
|
---|
453 | however, are only available through the
|
---|
454 | <computeroutput>VBoxManage</computeroutput> interface.</para>
|
---|
455 |
|
---|
456 | <para>These commands require that the machine is powered off (neither
|
---|
457 | running nor in "saved" state). Some machine settings can also be changed
|
---|
458 | while a machine is running; those settings will then have a corresponding
|
---|
459 | subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
|
---|
460 | subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
|
---|
461 |
|
---|
462 | <sect2>
|
---|
463 | <title>General settings</title>
|
---|
464 |
|
---|
465 | <para>The following general settings are available through
|
---|
466 | <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
|
---|
467 | <listitem>
|
---|
468 | <para><computeroutput>--name <name></computeroutput>: This
|
---|
469 | changes the VM's name and possibly renames the internal virtual
|
---|
470 | machine files, as described with <computeroutput>VBoxManage
|
---|
471 | createvm</computeroutput> above.</para>
|
---|
472 | </listitem>
|
---|
473 |
|
---|
474 | <listitem>
|
---|
475 | <para><computeroutput>--ostype <ostype></computeroutput>:
|
---|
476 | This specifies what guest operating system is supposed to run in
|
---|
477 | the VM. To learn about the various identifiers that can be used
|
---|
478 | here, use <computeroutput>VBoxManage list
|
---|
479 | ostypes</computeroutput>.</para>
|
---|
480 | </listitem>
|
---|
481 |
|
---|
482 | <listitem>
|
---|
483 | <para><computeroutput>--memory
|
---|
484 | <memorysize></computeroutput>: This sets the amount of RAM,
|
---|
485 | in MB, that the virtual machine should allocate for itself from
|
---|
486 | the host. See the remarks in <xref linkend="gui-createvm" /> for
|
---|
487 | more information.</para>
|
---|
488 | </listitem>
|
---|
489 |
|
---|
490 | <listitem>
|
---|
491 | <para><computeroutput>--vram <vramsize></computeroutput>:
|
---|
492 | This sets the amount of RAM that the virtual graphics card should
|
---|
493 | have. See <xref linkend="settings-display" /> for details.</para>
|
---|
494 | </listitem>
|
---|
495 |
|
---|
496 | <listitem>
|
---|
497 | <para><computeroutput>--acpi on|off</computeroutput>;
|
---|
498 | <computeroutput>--ioapic on|off</computeroutput>: These two
|
---|
499 | determine whether the VM should have ACPI and I/O APIC support,
|
---|
500 | respectively; see <xref linkend="settings-motherboard" /> for
|
---|
501 | details.</para>
|
---|
502 | </listitem>
|
---|
503 |
|
---|
504 | <listitem>
|
---|
505 | <para><computeroutput>--hardwareuuid
|
---|
506 | <uuid></computeroutput>: The UUID presented to the guest via
|
---|
507 | memory tables (DMI/SMBIOS), hardware and guest properties. By
|
---|
508 | default this is the same as the VM uuid. Useful when cloning a VM.
|
---|
509 | Teleporting takes care of this automatically.</para>
|
---|
510 | </listitem>
|
---|
511 |
|
---|
512 | <listitem>
|
---|
513 | <para><computeroutput>--cpus <cpucount></computeroutput>:
|
---|
514 | This sets the number of virtual CPUs for the virtual machine (see
|
---|
515 | <xref linkend="settings-processor" />). If CPU hot-plugging is
|
---|
516 | enabled (see below), this then sets the
|
---|
517 | <emphasis>maximum</emphasis> number of virtual CPUs that can be
|
---|
518 | plugged into the virtual machines.</para>
|
---|
519 | </listitem>
|
---|
520 |
|
---|
521 | <listitem>
|
---|
522 | <para><computeroutput>--rtcuseutc on|off</computeroutput>: This
|
---|
523 | option lets the real-time clock (RTC) operate in UTC time (see
|
---|
524 | <xref linkend="settings-motherboard" />).</para>
|
---|
525 | </listitem>
|
---|
526 |
|
---|
527 | <listitem>
|
---|
528 | <para><computeroutput>--cpuhotplug on|off</computeroutput>: This
|
---|
529 | enables CPU hot-plugging. When enabled, virtual CPUs can be added
|
---|
530 | to and removed from a virtual machine while it is running. See
|
---|
531 | <xref linkend="cpuhotplug" /> for more information.</para>
|
---|
532 | </listitem>
|
---|
533 |
|
---|
534 | <listitem>
|
---|
535 | <para><computeroutput>--plugcpu|unplugcpu
|
---|
536 | <id></computeroutput>: If CPU hot-plugging is enabled (see
|
---|
537 | above), this adds a virtual CPU to the virtual machines (or
|
---|
538 | removes one). <computeroutput><id></computeroutput>
|
---|
539 | specifies the index of the virtual CPU to be added or removed and
|
---|
540 | must be a number from 0 to the maximum no. of CPUs configured with
|
---|
541 | the <computeroutput>--cpus</computeroutput> option. CPU 0 can
|
---|
542 | never be removed.</para>
|
---|
543 | </listitem>
|
---|
544 |
|
---|
545 | <listitem>
|
---|
546 | <para><computeroutput>--cpuexecutioncap
|
---|
547 | <1-100></computeroutput>: This setting controls how much cpu
|
---|
548 | time a virtual CPU can use. A value of 50 implies a single virtual
|
---|
549 | CPU can use up to 50% of a single host CPU.</para>
|
---|
550 | </listitem>
|
---|
551 |
|
---|
552 | <listitem>
|
---|
553 | <para><computeroutput>--synthcpu on|off</computeroutput>: This
|
---|
554 | setting determines whether VirtualBox will expose a synthetic CPU
|
---|
555 | to the guest to allow live migration between host systems that
|
---|
556 | differ significantly.</para>
|
---|
557 | </listitem>
|
---|
558 |
|
---|
559 | <listitem>
|
---|
560 | <para><computeroutput>--pae on|off</computeroutput>: This
|
---|
561 | enables/disables PAE (see <xref
|
---|
562 | linkend="settings-processor" />).</para>
|
---|
563 | </listitem>
|
---|
564 |
|
---|
565 | <listitem>
|
---|
566 | <para><computeroutput>--hpet on|off</computeroutput>: This
|
---|
567 | enables/disables a High Precision Event Timer (HPET) which can
|
---|
568 | replace the legacy system timers. This is turned off by default.
|
---|
569 | Note that Windows supports a HPET only from Vista onwards.</para>
|
---|
570 | </listitem>
|
---|
571 |
|
---|
572 | <listitem>
|
---|
573 | <para><computeroutput>--hwvirtex on|off</computeroutput>: This
|
---|
574 | enables or disables the use of hardware virtualization extensions
|
---|
575 | (Intel VT-x or AMD-V) in the processor of your host system; see
|
---|
576 | <xref linkend="hwvirt" />.</para>
|
---|
577 | </listitem>
|
---|
578 |
|
---|
579 | <listitem>
|
---|
580 | <para><computeroutput>--hwvirtexexcl on|off</computeroutput>: This
|
---|
581 | specifies whether VirtualBox will make exclusive use of the
|
---|
582 | hardware virtualization extensions (Intel VT-x or AMD-V) in the
|
---|
583 | processor of your host system; see <xref linkend="hwvirt" />. If
|
---|
584 | you wish to simultaneously share these extensions with other
|
---|
585 | hypervisors, then you must disable this setting. Doing so has
|
---|
586 | negative performance implications.</para>
|
---|
587 | </listitem>
|
---|
588 |
|
---|
589 | <listitem>
|
---|
590 | <para><computeroutput>--nestedpaging on|off</computeroutput>: If
|
---|
591 | hardware virtualization is enabled, this additional setting
|
---|
592 | enables or disables the use of the nested paging feature in the
|
---|
593 | processor of your host system; see <xref
|
---|
594 | linkend="hwvirt" />.</para>
|
---|
595 | </listitem>
|
---|
596 |
|
---|
597 | <listitem>
|
---|
598 | <para><computeroutput>--largepages on|off</computeroutput>: If
|
---|
599 | hardware virtualization <emphasis>and</emphasis> nested paging are
|
---|
600 | enabled, for Intel VT-x only, an additional performance
|
---|
601 | improvement of up to 5% can be obtained by enabling this setting.
|
---|
602 | This causes the hypervisor to use large pages to reduce TLB use
|
---|
603 | and overhead.</para>
|
---|
604 | </listitem>
|
---|
605 |
|
---|
606 | <listitem>
|
---|
607 | <para><computeroutput>--vtxvpid on|off</computeroutput>: If
|
---|
608 | hardware virtualization is enabled, for Intel VT-x only, this
|
---|
609 | additional setting enables or disables the use of the tagged TLB
|
---|
610 | (VPID) feature in the processor of your host system; see <xref
|
---|
611 | linkend="hwvirt" />.</para>
|
---|
612 | </listitem>
|
---|
613 |
|
---|
614 | <listitem>
|
---|
615 | <para><computeroutput>--accelerate3d on|off</computeroutput>: This
|
---|
616 | enables, if the Guest Additions are installed, whether hardware 3D
|
---|
617 | acceleration should be available; see <xref
|
---|
618 | linkend="guestadd-3d" />.</para>
|
---|
619 | </listitem>
|
---|
620 |
|
---|
621 | <listitem>
|
---|
622 | <para>You can influence the BIOS logo that is displayed when a
|
---|
623 | virtual machine starts up with a number of settings. Per default,
|
---|
624 | a VirtualBox logo is displayed.</para>
|
---|
625 |
|
---|
626 | <para>With <computeroutput>--bioslogofadein
|
---|
627 | on|off</computeroutput> and <computeroutput>--bioslogofadeout
|
---|
628 | on|off</computeroutput>, you can determine whether the logo should
|
---|
629 | fade in and out, respectively.</para>
|
---|
630 |
|
---|
631 | <para>With <computeroutput>--bioslogodisplaytime
|
---|
632 | <msec></computeroutput> you can set how long the logo should
|
---|
633 | be visible, in milliseconds.</para>
|
---|
634 |
|
---|
635 | <para>With <computeroutput>--bioslogoimagepath
|
---|
636 | <imagepath></computeroutput> you can, if you are so
|
---|
637 | inclined, replace the image that is shown, with your own logo. The
|
---|
638 | image must be an uncompressed 256 color BMP file.</para>
|
---|
639 | </listitem>
|
---|
640 |
|
---|
641 | <listitem>
|
---|
642 | <para><computeroutput>--biosbootmenu
|
---|
643 | disabled|menuonly|messageandmenu</computeroutput>: This specifies
|
---|
644 | whether the BIOS allows the user to select a temporary boot
|
---|
645 | device. <computeroutput>menuonly</computeroutput> suppresses the
|
---|
646 | message, but the user can still press F12 to select a temporary
|
---|
647 | boot device.</para>
|
---|
648 | </listitem>
|
---|
649 |
|
---|
650 | <listitem>
|
---|
651 | <para><computeroutput>--nicbootprio<1-N>
|
---|
652 | <priority></computeroutput>: This specifies the order in which
|
---|
653 | NICs are tried for booting over the network (using PXE). The
|
---|
654 | priority is an integer in the 0 to 4 range. Priority 1 is the
|
---|
655 | highest, priority 4 is low. Priority 0, which is the default unless
|
---|
656 | otherwise specified, is the lowest.
|
---|
657 | </para>
|
---|
658 | <para> Note that this option only has effect when the Intel PXE boot
|
---|
659 | ROM is used.
|
---|
660 | </para>
|
---|
661 | </listitem>
|
---|
662 |
|
---|
663 | <listitem>
|
---|
664 | <para><computeroutput>--boot<1-4>
|
---|
665 | none|floppy|dvd|disk|net</computeroutput>: This specifies the boot
|
---|
666 | order for the virtual machine. There are four "slots", which the
|
---|
667 | VM will try to access from 1 to 4, and for each of which you can
|
---|
668 | set a device that the VM should attempt to boot from.</para>
|
---|
669 | </listitem>
|
---|
670 |
|
---|
671 | <listitem>
|
---|
672 | <para><computeroutput>--snapshotfolder
|
---|
673 | default|<path></computeroutput>: This allows you to specify
|
---|
674 | the folder in which snapshots will be kept for a virtual
|
---|
675 | machine.</para>
|
---|
676 | </listitem>
|
---|
677 |
|
---|
678 | <listitem>
|
---|
679 | <para><computeroutput>--firmware efi|bios</computeroutput>:
|
---|
680 | Specifies which firmware is used to boot particular virtual
|
---|
681 | machine: EFI or BIOS. Use EFI only if your fully understand what
|
---|
682 | you're doing.</para>
|
---|
683 | </listitem>
|
---|
684 |
|
---|
685 | <listitem>
|
---|
686 | <para><computeroutput>--guestmemoryballoon
|
---|
687 | <size></computeroutput> sets the default size of the guest
|
---|
688 | memory balloon, that is, memory allocated by the VirtualBox Guest
|
---|
689 | Additions from the guest operating system and returned to the
|
---|
690 | hypervisor for re-use by other virtual machines. <size> must
|
---|
691 | be specified in megabytes. The default size is 0 megabytes. For
|
---|
692 | details, see <xref linkend="guestadd-balloon" />.</para>
|
---|
693 | </listitem>
|
---|
694 | </itemizedlist></para>
|
---|
695 | </sect2>
|
---|
696 |
|
---|
697 | <sect2>
|
---|
698 | <title>Networking settings</title>
|
---|
699 |
|
---|
700 | <para>The following networking settings are available through
|
---|
701 | <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
|
---|
702 | settings, the decimal number directly following the option name ("1-N"
|
---|
703 | in the list below) specifies the virtual network adapter whose settings
|
---|
704 | should be changed.<itemizedlist>
|
---|
705 | <listitem>
|
---|
706 | <para><computeroutput>--nic<1-N>
|
---|
707 | none|null|nat|bridged|intnet|hostonly|generic
|
---|
708 | </computeroutput>: With
|
---|
709 | this, you can set, for each of the VM's virtual network cards,
|
---|
710 | what type of networking should be available. They can be not
|
---|
711 | present (<computeroutput>none</computeroutput>), not connected to
|
---|
712 | the host (<computeroutput>null</computeroutput>), use network
|
---|
713 | address translation (<computeroutput>nat</computeroutput>),
|
---|
714 | bridged networking (<computeroutput>bridged</computeroutput>) or
|
---|
715 | communicate with other virtual machines using internal networking
|
---|
716 | (<computeroutput>intnet</computeroutput>), host-only networking
|
---|
717 | (<computeroutput>hostonly</computeroutput>), or access rarely used
|
---|
718 | sub-modes (<computeroutput>generic</computeroutput>).
|
---|
719 | These options correspond
|
---|
720 | to the modes which are described in detail in <xref
|
---|
721 | linkend="networkingmodes" />.</para>
|
---|
722 | </listitem>
|
---|
723 |
|
---|
724 | <listitem>
|
---|
725 | <para><computeroutput>--nictype<1-N>
|
---|
726 | Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
|
---|
727 | This allows you, for each of the VM's virtual network cards, to
|
---|
728 | specify which networking hardware VirtualBox presents to the
|
---|
729 | guest; see <xref linkend="nichardware" />.</para>
|
---|
730 | </listitem>
|
---|
731 |
|
---|
732 | <listitem>
|
---|
733 | <para><computeroutput>--cableconnected<1-N>
|
---|
734 | on|off</computeroutput>: This allows you to temporarily disconnect
|
---|
735 | a virtual network interface, as if a network cable had been pulled
|
---|
736 | from a real network card. This might be useful for resetting
|
---|
737 | certain software components in the VM.</para>
|
---|
738 | </listitem>
|
---|
739 |
|
---|
740 | <listitem>
|
---|
741 | <para>With the "nictrace" options, you can optionally trace
|
---|
742 | network traffic by dumping it to a file, for debugging
|
---|
743 | purposes.</para>
|
---|
744 |
|
---|
745 | <para>With <computeroutput>--nictrace<1-N>
|
---|
746 | on|off</computeroutput>, you can enable network tracing for a
|
---|
747 | particular virtual network card.</para>
|
---|
748 |
|
---|
749 | <para>If enabled, you must specify with
|
---|
750 | <computeroutput>--nictracefile<1-N>
|
---|
751 | <filename></computeroutput> what file the trace should be
|
---|
752 | logged to.</para>
|
---|
753 | </listitem>
|
---|
754 |
|
---|
755 | <listitem>
|
---|
756 | <para><computeroutput>--bridgeadapter<1-N>
|
---|
757 | none|<devicename></computeroutput>: If bridged networking
|
---|
758 | has been enabled for a virtual network card (see the
|
---|
759 | <computeroutput>--nic</computeroutput> option above; otherwise
|
---|
760 | this setting has no effect), use this option to specify which host
|
---|
761 | interface the given virtual network interface will use. For
|
---|
762 | details, please see <xref linkend="network_bridged" />.</para>
|
---|
763 | </listitem>
|
---|
764 |
|
---|
765 | <listitem>
|
---|
766 | <para><computeroutput>--hostonlyadapter<1-N>
|
---|
767 | none|<devicename></computeroutput>: If host-only networking
|
---|
768 | has been enabled for a virtual network card (see the --nic option
|
---|
769 | above; otherwise this setting has no effect), use this option to
|
---|
770 | specify which host-only networking interface the given virtual
|
---|
771 | network interface will use. For details, please see <xref
|
---|
772 | linkend="network_hostonly" />.</para>
|
---|
773 | </listitem>
|
---|
774 |
|
---|
775 | <listitem>
|
---|
776 | <para><computeroutput>--intnet<1-N>
|
---|
777 | network</computeroutput>: If internal networking has been enabled
|
---|
778 | for a virtual network card (see the
|
---|
779 | <computeroutput>--nic</computeroutput> option above; otherwise
|
---|
780 | this setting has no effect), use this option to specify the name
|
---|
781 | of the internal network (see <xref
|
---|
782 | linkend="network_internal" />).</para>
|
---|
783 | </listitem>
|
---|
784 |
|
---|
785 | <listitem>
|
---|
786 | <para><computeroutput>--macaddress<1-N>
|
---|
787 | auto|<mac></computeroutput>: With this option you can set
|
---|
788 | the MAC address of the virtual network card. Normally, each
|
---|
789 | virtual network card is assigned a random address by VirtualBox at
|
---|
790 | VM creation.</para>
|
---|
791 | </listitem>
|
---|
792 |
|
---|
793 | <listitem>
|
---|
794 | <para><computeroutput>--nicgenericdrv<1-N>
|
---|
795 | <backend driver></computeroutput>: If generic networking has been
|
---|
796 | enabled for a virtual network card (see the
|
---|
797 | <computeroutput>--nic</computeroutput> option above; otherwise
|
---|
798 | this setting has no effect), this mode allows you to access
|
---|
799 | rarely used networking sub-modes, such as VDE network or UDP Tunnel.
|
---|
800 | </para>
|
---|
801 | </listitem>
|
---|
802 |
|
---|
803 | <listitem>
|
---|
804 | <para><computeroutput>--nicproperty<1-N>
|
---|
805 | <paramname>="paramvalue"</computeroutput>:
|
---|
806 | This option, in combination with "nicgenericdrv" allows you to
|
---|
807 | pass parameters to rarely-used network backends.</para><para>
|
---|
808 | Those parameters are backend engine-specific, and are different
|
---|
809 | between UDP Tunnel and the VDE backend drivers. For example,
|
---|
810 | please see <xref linkend="network_udp_tunnel" />.
|
---|
811 | </para>
|
---|
812 | </listitem>
|
---|
813 | </itemizedlist></para>
|
---|
814 |
|
---|
815 | <sect3>
|
---|
816 | <title>NAT Networking settings.</title>
|
---|
817 |
|
---|
818 | <para>The following NAT networking settings are available through
|
---|
819 | <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
|
---|
820 | settings, the decimal number directly following the option name ("1-N"
|
---|
821 | in the list below) specifies the virtual network adapter whose
|
---|
822 | settings should be changed.<itemizedlist>
|
---|
823 | <listitem>
|
---|
824 | <para><computeroutput>--natpf<1-N>
|
---|
825 | [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>],
|
---|
826 | <guestport></computeroutput>: This option defines a NAT
|
---|
827 | port-forwarding rule (please see <xref linkend="natforward" />
|
---|
828 | for details).</para>
|
---|
829 | </listitem>
|
---|
830 |
|
---|
831 | <listitem>
|
---|
832 | <para><computeroutput>--natpf<1-N> delete
|
---|
833 | <name></computeroutput>: This option deletes a NAT
|
---|
834 | port-forwarding rule (please see <xref linkend="natforward" />
|
---|
835 | for details).</para>
|
---|
836 | </listitem>
|
---|
837 |
|
---|
838 | <listitem>
|
---|
839 | <para><computeroutput>--nattftpprefix<1-N>
|
---|
840 | <prefix></computeroutput>: This option defines a prefix
|
---|
841 | for the built-in TFTP server, i.e. where the boot file is
|
---|
842 | located (please see <xref linkend="nat-tftp" /> and <xref
|
---|
843 | linkend="nat-adv-tftp" /> for details).</para>
|
---|
844 | </listitem>
|
---|
845 |
|
---|
846 | <listitem>
|
---|
847 | <para><computeroutput>--nattftpfile<1-N>
|
---|
848 | <bootfile></computeroutput>: This option defines the TFT
|
---|
849 | boot file (please see <xref linkend="nat-adv-tftp" /> for
|
---|
850 | details).</para>
|
---|
851 | </listitem>
|
---|
852 |
|
---|
853 | <listitem>
|
---|
854 | <para><computeroutput>--nattftpserver<1-N>
|
---|
855 | <tftpserver></computeroutput>: This option defines the
|
---|
856 | TFTP server address to boot from (please see <xref
|
---|
857 | linkend="nat-adv-tftp" /> for details).</para>
|
---|
858 | </listitem>
|
---|
859 |
|
---|
860 | <listitem>
|
---|
861 | <para><computeroutput>--natdnspassdomain<1-N>
|
---|
862 | on|off</computeroutput>: This option specifies whether the
|
---|
863 | built-in DHCP server passes the domain name for network name
|
---|
864 | resolution.</para>
|
---|
865 | </listitem>
|
---|
866 |
|
---|
867 | <listitem>
|
---|
868 | <para><computeroutput>--natdnsproxy<1-N>
|
---|
869 | on|off</computeroutput>: This option makes the NAT engine proxy
|
---|
870 | all guest DNS requests to the host's DNS servers (please see
|
---|
871 | <xref linkend="nat-adv-dns" /> for details).</para>
|
---|
872 | </listitem>
|
---|
873 |
|
---|
874 | <listitem>
|
---|
875 | <para><computeroutput>--natdnshostresolver<1-N>
|
---|
876 | on|off</computeroutput>: This option makes the NAT engine use
|
---|
877 | the host's resolver mechanisms to handle DNS requests (please
|
---|
878 | see <xref linkend="nat-adv-dns" /> for details).</para>
|
---|
879 | </listitem>
|
---|
880 |
|
---|
881 | <listitem>
|
---|
882 | <para><computeroutput>--natnatsettings<1-N>
|
---|
883 | [<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>],
|
---|
884 | [<tcprcv>]</computeroutput>: This option controls several
|
---|
885 | NAT settings (please see <xref linkend="nat-adv-settings" /> for
|
---|
886 | details).</para>
|
---|
887 | </listitem>
|
---|
888 |
|
---|
889 | <listitem>
|
---|
890 | <para><computeroutput>--nataliasmode<1-N>
|
---|
891 | default|[log],[proxyonly],[sameports]</computeroutput>: This
|
---|
892 | option defines behaviour of NAT engine core: log - enables
|
---|
893 | logging, proxyonly - switches of aliasing mode makes NAT
|
---|
894 | transparent, sameports enforces NAT engine to send packets via
|
---|
895 | the same port as they originated on, default - disable all
|
---|
896 | mentioned modes above . (please see <xref
|
---|
897 | linkend="nat-adv-alias" /> for details).</para>
|
---|
898 | </listitem>
|
---|
899 | </itemizedlist></para>
|
---|
900 | </sect3>
|
---|
901 | </sect2>
|
---|
902 |
|
---|
903 | <sect2 id="vboxmanage-modifyvm-other">
|
---|
904 | <title>Serial port, audio, clipboard, remote desktop and USB
|
---|
905 | settings</title>
|
---|
906 |
|
---|
907 | <para>The following other hardware settings are available through
|
---|
908 | <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
|
---|
909 | <listitem>
|
---|
910 | <para><computeroutput>--uart<1-N> off|<I/O base>
|
---|
911 | <IRQ></computeroutput>: With this option you can configure
|
---|
912 | virtual serial ports for the VM; see <xref
|
---|
913 | linkend="serialports" /> for an introduction.</para>
|
---|
914 | </listitem>
|
---|
915 |
|
---|
916 | <listitem>
|
---|
917 | <para><computeroutput>--uartmode<1-N>
|
---|
918 | <arg></computeroutput>: This setting controls how VirtualBox
|
---|
919 | connects a given virtual serial port (previously configured with
|
---|
920 | the <computeroutput>--uartX</computeroutput> setting, see above)
|
---|
921 | to the host on which the virtual machine is running. As described
|
---|
922 | in detail in <xref linkend="serialports" />, for each such port,
|
---|
923 | you can specify <computeroutput><arg></computeroutput> as
|
---|
924 | one of the following options:<itemizedlist>
|
---|
925 | <listitem>
|
---|
926 | <para><computeroutput>disconnected</computeroutput>: Even
|
---|
927 | though the serial port is shown to the guest, it has no
|
---|
928 | "other end" -- like a real COM port without a cable.</para>
|
---|
929 | </listitem>
|
---|
930 |
|
---|
931 | <listitem>
|
---|
932 | <para><computeroutput>server
|
---|
933 | <pipename></computeroutput>: On a Windows host, this
|
---|
934 | tells VirtualBox to create a named pipe on the host named
|
---|
935 | <computeroutput><pipename></computeroutput> and
|
---|
936 | connect the virtual serial device to it. Note that Windows
|
---|
937 | requires that the name of a named pipe begin with
|
---|
938 | <computeroutput>\\.\pipe\</computeroutput>.</para>
|
---|
939 |
|
---|
940 | <para>On a Linux host, instead of a named pipe, a local
|
---|
941 | domain socket is used.</para>
|
---|
942 | </listitem>
|
---|
943 |
|
---|
944 | <listitem>
|
---|
945 | <para><computeroutput>client
|
---|
946 | <pipename></computeroutput>: This operates just like
|
---|
947 | <computeroutput>server ...</computeroutput>, except that the
|
---|
948 | pipe (or local domain socket) is not created by VirtualBox,
|
---|
949 | but assumed to exist already.</para>
|
---|
950 | </listitem>
|
---|
951 |
|
---|
952 | <listitem>
|
---|
953 | <para><computeroutput><devicename></computeroutput>:
|
---|
954 | If, instead of the above, the device name of a physical
|
---|
955 | hardware serial port of the host is specified, the virtual
|
---|
956 | serial port is connected to that hardware port. On a Windows
|
---|
957 | host, the device name will be a COM port such as
|
---|
958 | <computeroutput>COM1</computeroutput>; on a Linux host, the
|
---|
959 | device name will look like
|
---|
960 | <computeroutput>/dev/ttyS0</computeroutput>. This allows you
|
---|
961 | to "wire" a real serial port to a virtual machine.</para>
|
---|
962 | </listitem>
|
---|
963 | </itemizedlist></para>
|
---|
964 | </listitem>
|
---|
965 |
|
---|
966 | <listitem>
|
---|
967 | <para><computeroutput>--audio none|null|oss</computeroutput>: With
|
---|
968 | this option, you can set whether the VM should have audio
|
---|
969 | support.</para>
|
---|
970 | </listitem>
|
---|
971 |
|
---|
972 | <listitem>
|
---|
973 | <para><computeroutput>--clipboard
|
---|
974 | disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
|
---|
975 | With this setting, you can select whether the guest operating
|
---|
976 | system's clipboard should be shared with the host; see <xref
|
---|
977 | linkend="generalsettings" />. This requires that the Guest
|
---|
978 | Additions be installed in the virtual machine.</para>
|
---|
979 | </listitem>
|
---|
980 |
|
---|
981 | <listitem>
|
---|
982 | <para><computeroutput>--monitorcount
|
---|
983 | <count></computeroutput>: This enables multi-monitor
|
---|
984 | support; see <xref linkend="settings-display" />.</para>
|
---|
985 | </listitem>
|
---|
986 |
|
---|
987 | <listitem>
|
---|
988 | <para><computeroutput>--usb on|off</computeroutput>: This option
|
---|
989 | enables or disables the VM's virtual USB controller; see <xref
|
---|
990 | linkend="settings-usb" /> for details.</para>
|
---|
991 | </listitem>
|
---|
992 |
|
---|
993 | <listitem>
|
---|
994 | <para><computeroutput>--usbehci on|off</computeroutput>: This
|
---|
995 | option enables or disables the VM's virtual USB 2.0 controller;
|
---|
996 | see <xref linkend="settings-usb" /> for details.</para>
|
---|
997 | </listitem>
|
---|
998 | </itemizedlist></para>
|
---|
999 | </sect2>
|
---|
1000 |
|
---|
1001 | <sect2>
|
---|
1002 | <title>Remote machine settings</title>
|
---|
1003 |
|
---|
1004 | <para>The following settings that affect remote machine behavior are
|
---|
1005 | available through <computeroutput>VBoxManage
|
---|
1006 | modifyvm</computeroutput>:<itemizedlist>
|
---|
1007 | <listitem>
|
---|
1008 | <para><computeroutput>--vrde on|off</computeroutput>: With the
|
---|
1009 | VirtualBox graphical user interface, this enables or disables the
|
---|
1010 | VirtualBox remote desktop extension (VRDE) server. Note that if
|
---|
1011 | you are using <computeroutput>VBoxHeadless</computeroutput> (see
|
---|
1012 | <xref linkend="vboxheadless" />), VRDE is enabled by
|
---|
1013 | default.</para>
|
---|
1014 | </listitem>
|
---|
1015 |
|
---|
1016 | <listitem>
|
---|
1017 | <para><computeroutput>--vrdeport
|
---|
1018 | default|<ports></computeroutput>: A port or a range of ports
|
---|
1019 | the VRDE server can bind to; "default" or "0" means port 3389, the
|
---|
1020 | standard port for RDP. You can specify a comma-separated list of
|
---|
1021 | ports or ranges of ports. Use a dash between two port numbers to
|
---|
1022 | specify a range. The VRDE server will bind to <emphasis
|
---|
1023 | role="bold">one</emphasis> of available ports from the specified
|
---|
1024 | list. Only one machine can use a given port at a time. For
|
---|
1025 | example, the option <computeroutput> --vrdeport
|
---|
1026 | 5000,5010-5012</computeroutput> will tell the server to bind to
|
---|
1027 | one of following ports: 5000, 5010, 5011 or 5012.</para>
|
---|
1028 | </listitem>
|
---|
1029 |
|
---|
1030 | <listitem>
|
---|
1031 | <para><computeroutput>--vrdeaddress <IP
|
---|
1032 | address></computeroutput>: The IP address of the host network
|
---|
1033 | interface the VRDE server will bind to. If specified, the server
|
---|
1034 | will accept connections only on the specified host network
|
---|
1035 | interface.</para>
|
---|
1036 | </listitem>
|
---|
1037 |
|
---|
1038 | <listitem>
|
---|
1039 | <para><computeroutput>--vrdeauthtype
|
---|
1040 | null|external|guest</computeroutput>: This allows you to choose
|
---|
1041 | whether and how authorization will be performed; see <xref
|
---|
1042 | linkend="vbox-auth" /> for details.</para>
|
---|
1043 | </listitem>
|
---|
1044 |
|
---|
1045 | <listitem>
|
---|
1046 | <para><computeroutput>--vrdemulticon on|off</computeroutput>: This
|
---|
1047 | enables multiple connections to the same VRDE server, if the
|
---|
1048 | server supports this feature; see <xref lang=""
|
---|
1049 | linkend="vrde-multiconnection" />.</para>
|
---|
1050 | </listitem>
|
---|
1051 |
|
---|
1052 | <listitem>
|
---|
1053 | <para><computeroutput>--vrdereusecon on|off</computeroutput>: This
|
---|
1054 | specifies the VRDE server behavior when multiple connections are
|
---|
1055 | disabled. When this option is enabled, the server will allow a new
|
---|
1056 | client to connect and will drop the existing connection. When this
|
---|
1057 | option is disabled (this is the default setting), a new connection
|
---|
1058 | will not be accepted if there is already a client connected to the
|
---|
1059 | server.</para>
|
---|
1060 | </listitem>
|
---|
1061 |
|
---|
1062 | <listitem>
|
---|
1063 | <para><computeroutput>--vrdevideochannel on|off</computeroutput>:
|
---|
1064 | This enables video redirection, if it is supported by the VRDE
|
---|
1065 | server; see <xref lang="" linkend="vrde-videochannel" />.</para>
|
---|
1066 | </listitem>
|
---|
1067 |
|
---|
1068 | <listitem>
|
---|
1069 | <para><computeroutput>--vrdevideochannelquality
|
---|
1070 | <percent></computeroutput>: Sets the image quality for video
|
---|
1071 | redirection; see <xref lang=""
|
---|
1072 | linkend="vrde-videochannel" />.</para>
|
---|
1073 | </listitem>
|
---|
1074 | </itemizedlist></para>
|
---|
1075 | </sect2>
|
---|
1076 |
|
---|
1077 | <sect2 id="vboxmanage-modifyvm-teleport">
|
---|
1078 | <title>Teleporting settings</title>
|
---|
1079 |
|
---|
1080 | <para>With the following commands for <computeroutput>VBoxManage
|
---|
1081 | modifyvm</computeroutput> you can configure a machine to be a target for
|
---|
1082 | teleporting. See <xref linkend="teleporting" /> for an
|
---|
1083 | introduction.<itemizedlist>
|
---|
1084 | <listitem>
|
---|
1085 | <para><computeroutput>--teleporter on|off</computeroutput>: With
|
---|
1086 | this setting you turn on or off whether a machine waits for a
|
---|
1087 | teleporting request to come in on the network when it is started.
|
---|
1088 | If "on", when the machine is started, it does not boot the virtual
|
---|
1089 | machine as it would normally; instead, it then waits for a
|
---|
1090 | teleporting request to come in on the port and address listed with
|
---|
1091 | the next two parameters.</para>
|
---|
1092 | </listitem>
|
---|
1093 |
|
---|
1094 | <listitem>
|
---|
1095 | <para><computeroutput>--teleporterport
|
---|
1096 | <port></computeroutput>, <computeroutput>--teleporteraddress
|
---|
1097 | <address></computeroutput>: these must be used with
|
---|
1098 | --teleporter and tell the virtual machine on which port and
|
---|
1099 | address it should listen for a teleporting request from another
|
---|
1100 | virtual machine. <computeroutput><port></computeroutput> can
|
---|
1101 | be any free TCP/IP port number (e.g. 6000);
|
---|
1102 | <computeroutput><address></computeroutput> can be any IP
|
---|
1103 | address or hostname and specifies the TCP/IP socket to bind to.
|
---|
1104 | The default is "0.0.0.0", which means any address.</para>
|
---|
1105 | </listitem>
|
---|
1106 |
|
---|
1107 | <listitem>
|
---|
1108 | <para><computeroutput>--teleporterpassword
|
---|
1109 | <password></computeroutput>: if this optional argument is
|
---|
1110 | given, then the teleporting request will only succeed if the
|
---|
1111 | source machine specifies the same password as the one given with
|
---|
1112 | this command.</para>
|
---|
1113 | </listitem>
|
---|
1114 |
|
---|
1115 | <listitem>
|
---|
1116 | <para><computeroutput>--teleporterpasswordfile
|
---|
1117 | <password></computeroutput>: if this optional argument is
|
---|
1118 | given, then the teleporting request will only succeed if the
|
---|
1119 | source machine specifies the same password as the one specified
|
---|
1120 | in the file give with this command. Use <computeroutput>stdin</computeroutput>
|
---|
1121 | to read the password from stdin.</para>
|
---|
1122 | </listitem>
|
---|
1123 |
|
---|
1124 | <listitem>
|
---|
1125 | <para><computeroutput>--cpuid <leaf> <eax> <ebx>
|
---|
1126 | <ecx> <edx></computeroutput>: Advanced users can use
|
---|
1127 | this command before a teleporting operation to restrict the
|
---|
1128 | virtual CPU capabilities that VirtualBox presents to the guest
|
---|
1129 | operating system. This must be run on both the source and the
|
---|
1130 | target machines involved in the teleporting and will then modify
|
---|
1131 | what the guest sees when it executes the
|
---|
1132 | <computeroutput>CPUID</computeroutput> machine instruction. This
|
---|
1133 | might help with misbehaving applications that wrongly assume that
|
---|
1134 | certain CPU capabilities are present. The meaning of the
|
---|
1135 | parameters is hardware dependent; please refer to the AMD or Intel
|
---|
1136 | processor manuals.</para>
|
---|
1137 | </listitem>
|
---|
1138 | </itemizedlist></para>
|
---|
1139 | </sect2>
|
---|
1140 | </sect1>
|
---|
1141 |
|
---|
1142 | <sect1 id="vboxmanage-clonevm">
|
---|
1143 | <title>VBoxManage clonevm</title>
|
---|
1144 |
|
---|
1145 | <para>This command creates a full or linked copy of an existing virtual
|
---|
1146 | machine.</para>
|
---|
1147 |
|
---|
1148 | <para>The <computeroutput>clonevm</computeroutput> subcommand takes at
|
---|
1149 | least the name of the virtual machine which should be cloned. The following
|
---|
1150 | additional settings can be used to further configure the clone VM
|
---|
1151 | operation:</para>
|
---|
1152 |
|
---|
1153 | <itemizedlist>
|
---|
1154 | <listitem>
|
---|
1155 | <para><computeroutput>--snapshot <uuid>|<name></computeroutput>:
|
---|
1156 | Select a specific snapshot where the clone operation should refer
|
---|
1157 | to. Default is referring to the current state.</para>
|
---|
1158 | </listitem>
|
---|
1159 | <listitem>
|
---|
1160 | <para><computeroutput>--mode machine|machineandchildren|all</computeroutput>:
|
---|
1161 | Selects the cloning mode of the operation. If
|
---|
1162 | <computeroutput>machine</computeroutput> is selected (the default),
|
---|
1163 | the current state of the VM without any snapshots is cloned. In the
|
---|
1164 | <computeroutput>machineandchildren</computeroutput> mode the snapshot
|
---|
1165 | provided by <computeroutput>--snapshot</computeroutput> and all
|
---|
1166 | child snapshots are cloned. If <computeroutput>all</computeroutput>
|
---|
1167 | is the selected mode all snapshots and the current state are cloned.
|
---|
1168 | </para>
|
---|
1169 | </listitem>
|
---|
1170 | <listitem>
|
---|
1171 | <para><computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
|
---|
1172 | Allows additional fine tuning of the clone operation. The first
|
---|
1173 | option defines that a linked clone should be created, which is
|
---|
1174 | only possible for a machine clone from a snapshot. The next two
|
---|
1175 | options allow to define how the MAC addresses of every virtual
|
---|
1176 | network card should be handled. They can either be reinitialized
|
---|
1177 | (the default), left unchanged
|
---|
1178 | (<computeroutput>keepallmacs</computeroutput>) or left unchanged
|
---|
1179 | when the network type is NAT
|
---|
1180 | (<computeroutput>keepnatmacs</computeroutput>). If you add
|
---|
1181 | <computeroutput>keepdisknames</computeroutput> all new disk images
|
---|
1182 | are called like the original once, otherwise they are
|
---|
1183 | renamed.</para>
|
---|
1184 | </listitem>
|
---|
1185 | <listitem>
|
---|
1186 | <para><computeroutput>--name <name></computeroutput>: Select a
|
---|
1187 | new name for the new virtual machine. Default is "Original Name
|
---|
1188 | Clone".</para>
|
---|
1189 | </listitem>
|
---|
1190 | <listitem>
|
---|
1191 | <para><computeroutput>--basefolder <basefolder></computeroutput>:
|
---|
1192 | Select the folder where the new virtual machine configuration should
|
---|
1193 | be saved in.</para>
|
---|
1194 | </listitem>
|
---|
1195 | <listitem>
|
---|
1196 | <para><computeroutput>--uuid <uuid></computeroutput>:
|
---|
1197 | Select the UUID the new VM should have. This id has to be unique in
|
---|
1198 | the VirtualBox instance this clone should be registered. Default is
|
---|
1199 | creating a new UUID.</para>
|
---|
1200 | </listitem>
|
---|
1201 | <listitem>
|
---|
1202 | <para><computeroutput>--register</computeroutput>:
|
---|
1203 | Automatically register the new clone in this VirtualBox
|
---|
1204 | installation. If you manually want register the new VM later, see
|
---|
1205 | <xref linkend="vboxmanage-registervm" /> for instructions how to do
|
---|
1206 | so.</para>
|
---|
1207 | </listitem>
|
---|
1208 | </itemizedlist>
|
---|
1209 | </sect1>
|
---|
1210 |
|
---|
1211 | <sect1 id="vboxmanage-import">
|
---|
1212 | <title>VBoxManage import</title>
|
---|
1213 |
|
---|
1214 | <para>This command imports a virtual appliance in OVF format by copying
|
---|
1215 | the virtual disk images and creating virtual machines in VirtualBox. See
|
---|
1216 | <xref linkend="ovf" /> for an introduction to appliances.</para>
|
---|
1217 |
|
---|
1218 | <para>The <computeroutput>import</computeroutput> subcommand takes at
|
---|
1219 | least the path name of an OVF file as input and expects the disk images,
|
---|
1220 | if needed, in the same directory as the OVF file. A lot of additional
|
---|
1221 | command-line options are supported to control in detail what is being
|
---|
1222 | imported and modify the import parameters, but the details depend on the
|
---|
1223 | content of the OVF file.</para>
|
---|
1224 |
|
---|
1225 | <para>It is therefore recommended to first run the import subcommand with
|
---|
1226 | the <computeroutput>--dry-run</computeroutput> or
|
---|
1227 | <computeroutput>-n</computeroutput> option. This will then print a
|
---|
1228 | description of the appliance's contents to the screen how it would be
|
---|
1229 | imported into VirtualBox, together with the optional command-line options
|
---|
1230 | to influence the import behavior.</para>
|
---|
1231 |
|
---|
1232 | <para>As an example, here is the screen output with a sample appliance
|
---|
1233 | containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
|
---|
1234 | Interpreting WindowsXp.ovf...
|
---|
1235 | OK.
|
---|
1236 | Virtual system 0:
|
---|
1237 | 0: Suggested OS type: "WindowsXP"
|
---|
1238 | (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
|
---|
1239 | 1: Suggested VM name "Windows XP Professional_1"
|
---|
1240 | (change with "--vsys 0 --vmname <name>")
|
---|
1241 | 3: Number of CPUs: 1
|
---|
1242 | (change with "--vsys 0 --cpus <n>")
|
---|
1243 | 4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
|
---|
1244 | 5: Sound card (appliance expects "ensoniq1371", can change on import)
|
---|
1245 | (disable with "--vsys 0 --unit 5 --ignore")
|
---|
1246 | 6: USB controller
|
---|
1247 | (disable with "--vsys 0 --unit 6 --ignore")
|
---|
1248 | 7: Network adapter: orig bridged, config 2, extra type=bridged
|
---|
1249 | 8: Floppy
|
---|
1250 | (disable with "--vsys 0 --unit 8 --ignore")
|
---|
1251 | 9: SCSI controller, type BusLogic
|
---|
1252 | (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
|
---|
1253 | disable with "--vsys 0 --unit 9 --ignore")
|
---|
1254 | 10: IDE controller, type PIIX4
|
---|
1255 | (disable with "--vsys 0 --unit 10 --ignore")
|
---|
1256 | 11: Hard disk image: source image=WindowsXp.vmdk,
|
---|
1257 | target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
|
---|
1258 | (change controller with "--vsys 0 --unit 11 --controller <id>";
|
---|
1259 | disable with "--vsys 0 --unit 11 --ignore")</screen></para>
|
---|
1260 |
|
---|
1261 | <para>As you can see, the individual configuration items are numbered, and
|
---|
1262 | depending on their type support different command-line options. The import
|
---|
1263 | subcommand can be directed to ignore many such items with a
|
---|
1264 | <computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
|
---|
1265 | X is the number of the virtual system (zero unless there are several
|
---|
1266 | virtual system descriptions in the appliance) and Y the item number, as
|
---|
1267 | printed on the screen.</para>
|
---|
1268 |
|
---|
1269 | <para>In the above example, Item #1 specifies the name of the target
|
---|
1270 | machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
|
---|
1271 | respectively. Item #11 describes a hard disk image; in this case, the
|
---|
1272 | additional <computeroutput>--controller</computeroutput> option indicates
|
---|
1273 | which item the disk image should be connected to, with the default coming
|
---|
1274 | from the OVF file.</para>
|
---|
1275 |
|
---|
1276 | <para>You can combine several items for the same virtual system behind the
|
---|
1277 | same <computeroutput>--vsys</computeroutput> option. For example, to
|
---|
1278 | import a machine as described in the OVF, but without the sound card and
|
---|
1279 | without the USB controller, and with the disk image connected to the IDE
|
---|
1280 | controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
|
---|
1281 | --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
|
---|
1282 | </sect1>
|
---|
1283 |
|
---|
1284 | <sect1 id="vboxmanage-export">
|
---|
1285 | <title>VBoxManage export</title>
|
---|
1286 |
|
---|
1287 | <para>This command exports one or more virtual machines from VirtualBox
|
---|
1288 | into a virtual appliance in OVF format, including copying their virtual
|
---|
1289 | disk images to compressed VMDK. See <xref linkend="ovf" /> for an
|
---|
1290 | introduction to appliances.</para>
|
---|
1291 |
|
---|
1292 | <para>The <computeroutput>export</computeroutput> command is simple to
|
---|
1293 | use: list the machine (or the machines) that you would like to export to
|
---|
1294 | the same OVF file and specify the target OVF file after an additional
|
---|
1295 | <computeroutput>--output</computeroutput> or
|
---|
1296 | <computeroutput>-o</computeroutput> option. Note that the directory of the
|
---|
1297 | target OVF file will also receive the exported disk images in the
|
---|
1298 | compressed VMDK format (regardless of the original format) and should have
|
---|
1299 | enough disk space left for them.</para>
|
---|
1300 |
|
---|
1301 | <para>Beside a simple export of a given virtual machine, you can append
|
---|
1302 | several product information to the appliance file. Use
|
---|
1303 | <computeroutput>--product</computeroutput>,
|
---|
1304 | <computeroutput>--producturl</computeroutput>,
|
---|
1305 | <computeroutput>--vendor</computeroutput>,
|
---|
1306 | <computeroutput>--vendorurl</computeroutput> and
|
---|
1307 | <computeroutput>--version</computeroutput> to specify this additional
|
---|
1308 | information. For legal reasons you may add a license text or the content
|
---|
1309 | of a license file by using the <computeroutput>--eula</computeroutput> and
|
---|
1310 | <computeroutput>--eulafile</computeroutput> option respectively. As with
|
---|
1311 | OVF import, you must use the <computeroutput>--vsys X</computeroutput>
|
---|
1312 | option to direct the previously mentioned options to the correct virtual
|
---|
1313 | machine.</para>
|
---|
1314 |
|
---|
1315 | <para>For virtualization products which aren't fully compatible with the
|
---|
1316 | OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
|
---|
1317 | <computeroutput>--legacy09</computeroutput> option.</para>
|
---|
1318 | </sect1>
|
---|
1319 |
|
---|
1320 | <sect1 id="vboxmanage-startvm">
|
---|
1321 | <title>VBoxManage startvm</title>
|
---|
1322 |
|
---|
1323 | <para>This command starts a virtual machine that is currently in the
|
---|
1324 | "Powered off" or "Saved" states.</para>
|
---|
1325 |
|
---|
1326 | <note>
|
---|
1327 | <para>This is provided for backwards compatibility only. We recommend to
|
---|
1328 | start virtual machines directly by running the respective front-end, as
|
---|
1329 | you might otherwise miss important error and state information that
|
---|
1330 | VirtualBox may display on the console. This is especially important for
|
---|
1331 | front-ends other than <computeroutput>VirtualBox</computeroutput>, our
|
---|
1332 | graphical user interface, because those cannot display error messages in
|
---|
1333 | a popup window. See <xref linkend="vboxheadless" /> for more
|
---|
1334 | information.</para>
|
---|
1335 | </note>
|
---|
1336 |
|
---|
1337 | <para>The optional <computeroutput>--type</computeroutput> specifier
|
---|
1338 | determines whether the machine will be started in a window (GUI mode,
|
---|
1339 | which is the default) or whether the output should go through
|
---|
1340 | <computeroutput>VBoxHeadless</computeroutput>, with VRDE enabled or not;
|
---|
1341 | see <xref linkend="vboxheadless" /> for more information. The list of
|
---|
1342 | types is subject to change, and it's not guaranteed that all types are
|
---|
1343 | accepted by any product variant.</para>
|
---|
1344 |
|
---|
1345 | <para>The following values are allowed:</para>
|
---|
1346 |
|
---|
1347 | <glosslist>
|
---|
1348 | <glossentry>
|
---|
1349 | <glossterm>gui</glossterm>
|
---|
1350 |
|
---|
1351 | <glossdef>
|
---|
1352 | <para>Starts a VM showing a GUI window. This is the default.</para>
|
---|
1353 | </glossdef>
|
---|
1354 | </glossentry>
|
---|
1355 |
|
---|
1356 | <glossentry>
|
---|
1357 | <glossterm>headless</glossterm>
|
---|
1358 |
|
---|
1359 | <glossdef>
|
---|
1360 | <para>Starts a VM without a window for remote display only.</para>
|
---|
1361 | </glossdef>
|
---|
1362 | </glossentry>
|
---|
1363 | </glosslist>
|
---|
1364 | </sect1>
|
---|
1365 |
|
---|
1366 | <sect1 id="vboxmanage-controlvm">
|
---|
1367 | <title>VBoxManage controlvm</title>
|
---|
1368 |
|
---|
1369 | <para>The <computeroutput>controlvm</computeroutput> subcommand allows you
|
---|
1370 | to change the state of a virtual machine that is currently running. The
|
---|
1371 | following can be specified:</para>
|
---|
1372 |
|
---|
1373 | <para><itemizedlist>
|
---|
1374 | <listitem>
|
---|
1375 | <para><computeroutput>VBoxManage controlvm <vm>
|
---|
1376 | pause</computeroutput> temporarily puts a virtual machine on hold,
|
---|
1377 | without changing its state for good. The VM window will be painted
|
---|
1378 | in gray to indicate that the VM is currently paused. (This is
|
---|
1379 | equivalent to selecting the "Pause" item in the "Machine" menu of
|
---|
1380 | the GUI.)</para>
|
---|
1381 | </listitem>
|
---|
1382 |
|
---|
1383 | <listitem>
|
---|
1384 | <para>Use <computeroutput>VBoxManage controlvm <vm>
|
---|
1385 | resume</computeroutput> to undo a previous
|
---|
1386 | <computeroutput>pause</computeroutput> command. (This is equivalent
|
---|
1387 | to selecting the "Resume" item in the "Machine" menu of the
|
---|
1388 | GUI.)</para>
|
---|
1389 | </listitem>
|
---|
1390 |
|
---|
1391 | <listitem>
|
---|
1392 | <para><computeroutput>VBoxManage controlvm <vm>
|
---|
1393 | reset</computeroutput> has the same effect on a virtual machine as
|
---|
1394 | pressing the "Reset" button on a real computer: a cold reboot of the
|
---|
1395 | virtual machine, which will restart and boot the guest operating
|
---|
1396 | system again immediately. The state of the VM is not saved
|
---|
1397 | beforehand, and data may be lost. (This is equivalent to selecting
|
---|
1398 | the "Reset" item in the "Machine" menu of the GUI.)</para>
|
---|
1399 | </listitem>
|
---|
1400 |
|
---|
1401 | <listitem>
|
---|
1402 | <para><computeroutput>VBoxManage controlvm <vm>
|
---|
1403 | poweroff</computeroutput> has the same effect on a virtual machine
|
---|
1404 | as pulling the power cable on a real computer. Again, the state of
|
---|
1405 | the VM is not saved beforehand, and data may be lost. (This is
|
---|
1406 | equivalent to selecting the "Close" item in the "Machine" menu of
|
---|
1407 | the GUI or pressing the window's close button, and then selecting
|
---|
1408 | "Power off the machine" in the dialog.)</para>
|
---|
1409 |
|
---|
1410 | <para>After this, the VM's state will be "Powered off". From there,
|
---|
1411 | it can be started again; see <xref
|
---|
1412 | linkend="vboxmanage-startvm" />.</para>
|
---|
1413 | </listitem>
|
---|
1414 |
|
---|
1415 | <listitem>
|
---|
1416 | <para><computeroutput>VBoxManage controlvm <vm>
|
---|
1417 | savestate</computeroutput> will save the current state of the VM to
|
---|
1418 | disk and then stop the VM. (This is equivalent to selecting the
|
---|
1419 | "Close" item in the "Machine" menu of the GUI or pressing the
|
---|
1420 | window's close button, and then selecting "Save the machine state"
|
---|
1421 | in the dialog.)</para>
|
---|
1422 |
|
---|
1423 | <para>After this, the VM's state will be "Saved". From there, it can
|
---|
1424 | be started again; see <xref linkend="vboxmanage-startvm" />.</para>
|
---|
1425 | </listitem>
|
---|
1426 |
|
---|
1427 | <listitem>
|
---|
1428 | <para><computeroutput>VBoxManage controlvm <vm> teleport
|
---|
1429 | --hostname <name> --port <port> [--passwordfile
|
---|
1430 | <file> | --password <password>]</computeroutput> makes
|
---|
1431 | the machine the source of a teleporting operation and initiates a
|
---|
1432 | teleport to the given target. See <xref linkend="teleporting" /> for
|
---|
1433 | an introduction. If the optional password is specified, it must match
|
---|
1434 | the password that was given to the
|
---|
1435 | <computeroutput>modifyvm</computeroutput> command for the target
|
---|
1436 | machine; see <xref linkend="vboxmanage-modifyvm-teleport" /> for
|
---|
1437 | details.</para>
|
---|
1438 | </listitem>
|
---|
1439 | </itemizedlist></para>
|
---|
1440 |
|
---|
1441 | <para>A few extra options are available with
|
---|
1442 | <computeroutput>controlvm</computeroutput> that do not directly affect the
|
---|
1443 | VM's running state:</para>
|
---|
1444 |
|
---|
1445 | <itemizedlist>
|
---|
1446 | <listitem>
|
---|
1447 | <para>The <computeroutput>setlinkstate<1-N></computeroutput>
|
---|
1448 | operation connects or disconnects virtual network cables from their
|
---|
1449 | network interfaces.</para>
|
---|
1450 | </listitem>
|
---|
1451 |
|
---|
1452 | <listitem>
|
---|
1453 | <para><computeroutput>nic<1-N>
|
---|
1454 | null|nat|bridged|intnet|hostonly|generic</computeroutput>: With this, you can
|
---|
1455 | set, for each of the VM's virtual network cards, what type of
|
---|
1456 | networking should be available. They can be not connected to the host
|
---|
1457 | (<computeroutput>null</computeroutput>), use network address
|
---|
1458 | translation (<computeroutput>nat</computeroutput>), bridged networking
|
---|
1459 | (<computeroutput>bridged</computeroutput>) or communicate with other
|
---|
1460 | virtual machines using internal networking
|
---|
1461 | (<computeroutput>intnet</computeroutput>) or host-only networking
|
---|
1462 | (<computeroutput>hostonly</computeroutput>) or access to rarely used
|
---|
1463 | sub-modes
|
---|
1464 | (<computeroutput>generic</computeroutput>). These options correspond
|
---|
1465 | to the modes which are described in detail in <xref
|
---|
1466 | linkend="networkingmodes" />.</para>
|
---|
1467 | </listitem>
|
---|
1468 |
|
---|
1469 | <listitem>
|
---|
1470 | <para><computeroutput>usbattach</computeroutput> and
|
---|
1471 | <computeroutput>usbdettach</computeroutput> make host USB devices
|
---|
1472 | visible to the virtual machine on the fly, without the need for
|
---|
1473 | creating filters first. The USB devices can be specified by UUID
|
---|
1474 | (unique identifier) or by address on the host system.</para>
|
---|
1475 |
|
---|
1476 | <para>You can use <computeroutput>VBoxManage list
|
---|
1477 | usbhost</computeroutput> to locate this information.</para>
|
---|
1478 | </listitem>
|
---|
1479 |
|
---|
1480 | <listitem>
|
---|
1481 | <para><computeroutput>vrde on|off</computeroutput> lets you enable or
|
---|
1482 | disable the VRDE server, if it is installed.</para>
|
---|
1483 | </listitem>
|
---|
1484 |
|
---|
1485 | <listitem>
|
---|
1486 | <para><computeroutput>vrdeport default|<ports></computeroutput>
|
---|
1487 | changes the port or a range of ports that the VRDE server can bind to;
|
---|
1488 | "default" or "0" means port 3389, the standard port for RDP. For
|
---|
1489 | details, see the description for the
|
---|
1490 | <computeroutput>--vrdeport</computeroutput> option in <xref
|
---|
1491 | linkend="vboxmanage-modifyvm-other" />.</para>
|
---|
1492 | </listitem>
|
---|
1493 |
|
---|
1494 | <listitem>
|
---|
1495 | <para><computeroutput>setvideomodehint</computeroutput> requests that
|
---|
1496 | the guest system change to a particular video mode. This requires that
|
---|
1497 | the Guest Additions be installed, and will not work for all guest
|
---|
1498 | systems.</para>
|
---|
1499 | </listitem>
|
---|
1500 |
|
---|
1501 | <listitem>
|
---|
1502 | <para><computeroutput>screenshotpng</computeroutput> takes a screenshot
|
---|
1503 | of the guest display and saves it in PNG format.</para>
|
---|
1504 | </listitem>
|
---|
1505 |
|
---|
1506 | <listitem>
|
---|
1507 | <para>The <computeroutput>setcredentials</computeroutput> operation is
|
---|
1508 | used for remote logons in Windows guests. For details, please refer to
|
---|
1509 | <xref linkend="autologon" />.</para>
|
---|
1510 | </listitem>
|
---|
1511 |
|
---|
1512 | <listitem>
|
---|
1513 | <para>The <computeroutput>guestmemoryballoon</computeroutput>
|
---|
1514 | operation changes the size of the guest memory balloon, that is,
|
---|
1515 | memory allocated by the VirtualBox Guest Additions from the guest
|
---|
1516 | operating system and returned to the hypervisor for re-use by other
|
---|
1517 | virtual machines. This must be specified in megabytes. For details,
|
---|
1518 | see <xref linkend="guestadd-balloon" />.</para>
|
---|
1519 | </listitem>
|
---|
1520 |
|
---|
1521 | <listitem>
|
---|
1522 | <para>The <computeroutput>cpuexecutioncap
|
---|
1523 | <1-100></computeroutput>: This operation controls how much cpu
|
---|
1524 | time a virtual CPU can use. A value of 50 implies a single virtual CPU
|
---|
1525 | can use up to 50% of a single host CPU.</para>
|
---|
1526 | </listitem>
|
---|
1527 | </itemizedlist>
|
---|
1528 | </sect1>
|
---|
1529 |
|
---|
1530 | <sect1>
|
---|
1531 | <title>VBoxManage discardstate</title>
|
---|
1532 |
|
---|
1533 | <para>This command discards the saved state of a virtual machine which is
|
---|
1534 | not currently running, which will cause its operating system to restart
|
---|
1535 | next time you start it. This is the equivalent of pulling out the power
|
---|
1536 | cable on a physical machine, and should be avoided if possible.</para>
|
---|
1537 | </sect1>
|
---|
1538 |
|
---|
1539 | <sect1>
|
---|
1540 | <title>VBoxManage adoptstate</title>
|
---|
1541 |
|
---|
1542 | <para>If you have a saved state file (<computeroutput>.sav</computeroutput>)
|
---|
1543 | that is seperate from the VM configuration, you can use this command to
|
---|
1544 | "adopt" the file. This will change the VM to saved state and when you
|
---|
1545 | start it, VirtualBox will attempt to restore it from the saved state file
|
---|
1546 | you indicated. This command should only be used in special setups.</para>
|
---|
1547 | </sect1>
|
---|
1548 |
|
---|
1549 | <sect1>
|
---|
1550 | <title>VBoxManage snapshot</title>
|
---|
1551 |
|
---|
1552 | <para>This command is used to control snapshots from the command line. A
|
---|
1553 | snapshot consists of a complete copy of the virtual machine settings,
|
---|
1554 | copied at the time when the snapshot was taken, and optionally a virtual
|
---|
1555 | machine saved state file if the snapshot was taken while the machine was
|
---|
1556 | running. After a snapshot has been taken, VirtualBox creates differencing
|
---|
1557 | hard disk for each normal hard disk associated with the machine so that
|
---|
1558 | when a snapshot is restored, the contents of the virtual machine's virtual
|
---|
1559 | hard disks can be quickly reset by simply dropping the pre-existing
|
---|
1560 | differencing files.</para>
|
---|
1561 |
|
---|
1562 | <para>The <computeroutput>take</computeroutput> operation takes a snapshot
|
---|
1563 | of the current state of the virtual machine. You must supply a name for
|
---|
1564 | the snapshot and can optionally supply a description. The new snapshot is
|
---|
1565 | inserted into the snapshots tree as a child of the current snapshot and
|
---|
1566 | then becomes the new current snapshot.</para>
|
---|
1567 |
|
---|
1568 | <para>The <computeroutput>delete</computeroutput> operation deletes a
|
---|
1569 | snapshot (specified by name or by UUID). This can take a while to finish
|
---|
1570 | since the differencing images associated with the snapshot might need to
|
---|
1571 | be merged with their child differencing images.</para>
|
---|
1572 |
|
---|
1573 | <para>The <computeroutput>restore</computeroutput> operation will restore
|
---|
1574 | the given snapshot (specified by name or by UUID) by resetting the virtual
|
---|
1575 | machine's settings and current state to that of the snapshot. The previous
|
---|
1576 | current state of the machine will be lost. After this, the given snapshot
|
---|
1577 | becomes the new "current" snapshot so that subsequent snapshots are
|
---|
1578 | inserted under the snapshot from which was restored.</para>
|
---|
1579 |
|
---|
1580 | <para>The <computeroutput>restorecurrent</computeroutput> operation is a
|
---|
1581 | shortcut to restore the current snapshot (i.e. the snapshot from which the
|
---|
1582 | current state is derived). This subcommand is equivalent to using the
|
---|
1583 | "restore" subcommand with the name or UUID of the current snapshot, except
|
---|
1584 | that it avoids the extra step of determining that name or UUID.</para>
|
---|
1585 |
|
---|
1586 | <para>With the <computeroutput>edit</computeroutput> operation, you can
|
---|
1587 | change the name or description of an existing snapshot.</para>
|
---|
1588 |
|
---|
1589 | <para>With the <computeroutput>showvminfo</computeroutput> operation, you
|
---|
1590 | can view the virtual machine settings that were stored with an existing
|
---|
1591 | snapshot.</para>
|
---|
1592 | </sect1>
|
---|
1593 |
|
---|
1594 | <sect1 id="vboxmanage-closemedium">
|
---|
1595 | <title>VBoxManage closemedium</title>
|
---|
1596 |
|
---|
1597 | <para>This commands removes a hard disk, DVD or floppy image from a
|
---|
1598 | VirtualBox media registry.<footnote>
|
---|
1599 | <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
|
---|
1600 | openmedium before a medium could be attached to a virtual machine;
|
---|
1601 | that call "registered" the medium with the global VirtualBox media
|
---|
1602 | registry. With VirtualBox 4.0 this is no longer necessary; media are
|
---|
1603 | added to media registries automatically. The "closemedium" call has
|
---|
1604 | been retained, however, to allow for explicitly removing a medium from
|
---|
1605 | a registry.</para>
|
---|
1606 | </footnote></para>
|
---|
1607 |
|
---|
1608 | <para>Optionally, you can request that the image be deleted. You will get
|
---|
1609 | appropriate diagnostics that the deletion failed, however the image will
|
---|
1610 | become unregistered in any case.</para>
|
---|
1611 | </sect1>
|
---|
1612 |
|
---|
1613 | <sect1>
|
---|
1614 | <title id="vboxmanage-storageattach">VBoxManage storageattach</title>
|
---|
1615 |
|
---|
1616 | <para>This command attaches/modifies/removes a storage medium connected to
|
---|
1617 | a storage controller that was previously added with the
|
---|
1618 | <computeroutput>storagectl</computeroutput> command (see the previous
|
---|
1619 | section). The syntax is as follows:</para>
|
---|
1620 |
|
---|
1621 | <screen>VBoxManage storageattach <uuid|vmname>
|
---|
1622 | --storagectl <name>
|
---|
1623 | [--port <number>]
|
---|
1624 | [--device <number>]
|
---|
1625 | [--type dvddrive|hdd|fdd]
|
---|
1626 | [--medium none|emptydrive|
|
---|
1627 | <uuid>|<filename>|host:<drive>|iscsi]
|
---|
1628 | [--mtype normal|writethrough|immutable|shareable]
|
---|
1629 | [--comment <text>]
|
---|
1630 | [--setuuid <uuid>]
|
---|
1631 | [--setparentuuid <uuid>]
|
---|
1632 | [--passthrough on|off]
|
---|
1633 | [--tempeject on|off]
|
---|
1634 | [--bandwidthgroup name|none]
|
---|
1635 | [--forceunmount]
|
---|
1636 | [--server <name>|<ip>]
|
---|
1637 | [--target <target>]
|
---|
1638 | [--tport <port>]
|
---|
1639 | [--lun <lun>]
|
---|
1640 | [--encodedlun <lun>]
|
---|
1641 | [--username <username>]
|
---|
1642 | [--password <password>]
|
---|
1643 | [--intnet]
|
---|
1644 | </screen>
|
---|
1645 |
|
---|
1646 | <para>A number of parameters are commonly required; the ones at the end of
|
---|
1647 | the list are required only for iSCSI targets (see below).</para>
|
---|
1648 |
|
---|
1649 | <para>The common parameters are:<glosslist>
|
---|
1650 | <glossentry>
|
---|
1651 | <glossterm>uuid|vmname</glossterm>
|
---|
1652 |
|
---|
1653 | <glossdef>
|
---|
1654 | <para>The VM UUID or VM Name. Mandatory.</para>
|
---|
1655 | </glossdef>
|
---|
1656 | </glossentry>
|
---|
1657 |
|
---|
1658 | <glossentry>
|
---|
1659 | <glossterm>storagectl</glossterm>
|
---|
1660 |
|
---|
1661 | <glossdef>
|
---|
1662 | <para>Name of the storage controller. Mandatory. The list of the
|
---|
1663 | storage controllers currently attached to a VM can be obtained
|
---|
1664 | with <computeroutput>VBoxManage showvminfo</computeroutput>; see
|
---|
1665 | <xref linkend="vboxmanage-showvminfo" />.</para>
|
---|
1666 | </glossdef>
|
---|
1667 | </glossentry>
|
---|
1668 |
|
---|
1669 | <glossentry>
|
---|
1670 | <glossterm>port</glossterm>
|
---|
1671 |
|
---|
1672 | <glossdef>
|
---|
1673 | <para>The number of the storage controller's port which is to be
|
---|
1674 | modified. Mandatory, unless the storage controller has only a
|
---|
1675 | single port.</para>
|
---|
1676 | </glossdef>
|
---|
1677 | </glossentry>
|
---|
1678 |
|
---|
1679 | <glossentry>
|
---|
1680 | <glossterm>device</glossterm>
|
---|
1681 |
|
---|
1682 | <glossdef>
|
---|
1683 | <para>The number of the port's device which is to be modified.
|
---|
1684 | Mandatory, unless the storage controller has only a single device
|
---|
1685 | per port.</para>
|
---|
1686 | </glossdef>
|
---|
1687 | </glossentry>
|
---|
1688 |
|
---|
1689 | <glossentry>
|
---|
1690 | <glossterm>type</glossterm>
|
---|
1691 |
|
---|
1692 | <glossdef>
|
---|
1693 | <para>Define the type of the drive to which the medium is being
|
---|
1694 | attached/detached/modified. This argument can only be omitted if
|
---|
1695 | the type of medium can be determined from either the medium given
|
---|
1696 | with the <computeroutput>--medium</computeroutput> argument or
|
---|
1697 | from a previous medium attachment.</para>
|
---|
1698 | </glossdef>
|
---|
1699 | </glossentry>
|
---|
1700 |
|
---|
1701 | <glossentry>
|
---|
1702 | <glossterm>medium</glossterm>
|
---|
1703 |
|
---|
1704 | <glossdef>
|
---|
1705 | <para>Specifies what is to be attached. The following values are
|
---|
1706 | supported:<itemizedlist>
|
---|
1707 | <listitem>
|
---|
1708 | <para>"none": Any existing device should be removed from the
|
---|
1709 | given slot.</para>
|
---|
1710 | </listitem>
|
---|
1711 |
|
---|
1712 | <listitem>
|
---|
1713 | <para>"emptydrive": For a virtual DVD or floppy drive only,
|
---|
1714 | this makes the device slot behaves like a removeable drive
|
---|
1715 | into which no media has been inserted.</para>
|
---|
1716 | </listitem>
|
---|
1717 |
|
---|
1718 | <listitem>
|
---|
1719 | <para>If a UUID is specified, it must be the UUID of a
|
---|
1720 | storage medium that is already known to VirtualBox (e.g.
|
---|
1721 | because it has been attached to another virtual machine).
|
---|
1722 | See <xref linkend="vboxmanage-list" /> for how to list known
|
---|
1723 | media. This medium is then attached to the given device
|
---|
1724 | slot.</para>
|
---|
1725 | </listitem>
|
---|
1726 |
|
---|
1727 | <listitem>
|
---|
1728 | <para>If a filename is specified, it must be the full path
|
---|
1729 | of an existing disk image (ISO, RAW, VDI, VMDK or other),
|
---|
1730 | which is then attached to the given device slot.</para>
|
---|
1731 | </listitem>
|
---|
1732 |
|
---|
1733 | <listitem>
|
---|
1734 | <para>"host:<drive>": For a virtual DVD or floppy
|
---|
1735 | drive only, this connects the given device slot to the
|
---|
1736 | specified DVD or floppy drive on the host computer.</para>
|
---|
1737 | </listitem>
|
---|
1738 |
|
---|
1739 | <listitem>
|
---|
1740 | <para>"iscsi": For virtual hard disks only, this allows for
|
---|
1741 | specifying an iSCSI target. In this case, more parameters
|
---|
1742 | must be given; see below.</para>
|
---|
1743 | </listitem>
|
---|
1744 | </itemizedlist></para>
|
---|
1745 |
|
---|
1746 | <para>Some of the above changes, in particular for removeable
|
---|
1747 | media (floppies and CDs/DVDs), can be effected while a VM is
|
---|
1748 | running. Others (device changes or changes in hard disk device
|
---|
1749 | slots) require the VM to be powered off.</para>
|
---|
1750 | </glossdef>
|
---|
1751 | </glossentry>
|
---|
1752 |
|
---|
1753 | <glossentry>
|
---|
1754 | <glossterm>mtype</glossterm>
|
---|
1755 |
|
---|
1756 | <glossdef>
|
---|
1757 | <para>Defines how this medium behaves with respect to snapshots
|
---|
1758 | and write operations. See <xref linkend="hdimagewrites" /> for
|
---|
1759 | details.</para>
|
---|
1760 | </glossdef>
|
---|
1761 | </glossentry>
|
---|
1762 |
|
---|
1763 | <glossentry>
|
---|
1764 | <glossterm>comment</glossterm>
|
---|
1765 |
|
---|
1766 | <glossdef>
|
---|
1767 | <para>Any description that you want to have stored with this
|
---|
1768 | medium (optional; for example, for an iSCSI target, "Big storage
|
---|
1769 | server downstairs"). This is purely descriptive and not needed for
|
---|
1770 | the medium to function correctly.</para>
|
---|
1771 | </glossdef>
|
---|
1772 | </glossentry>
|
---|
1773 |
|
---|
1774 | <glossentry>
|
---|
1775 | <glossterm>setuuid, setparentuuid</glossterm>
|
---|
1776 |
|
---|
1777 | <glossdef>
|
---|
1778 | <para>Modifies the UUID or parent UUID of a medium before
|
---|
1779 | attaching it to a VM. This is an expert option. Inappropriate use
|
---|
1780 | can make the medium unusable or lead to broken VM configurations
|
---|
1781 | if any other VM is referring to the same media already. The most
|
---|
1782 | frequently used variant is <code>--setuuid ""</code>, which assigns
|
---|
1783 | a new (random) UUID to an image. This is useful to resolve the
|
---|
1784 | duplicate UUID errors if one duplicated an image using file copy
|
---|
1785 | utilities.</para>
|
---|
1786 | </glossdef>
|
---|
1787 | </glossentry>
|
---|
1788 |
|
---|
1789 | <glossentry>
|
---|
1790 | <glossterm>passthrough</glossterm>
|
---|
1791 |
|
---|
1792 | <glossdef>
|
---|
1793 | <para>For a virtual DVD drive only, you can enable DVD writing
|
---|
1794 | support (currently experimental; see <xref
|
---|
1795 | linkend="storage-cds" />).</para>
|
---|
1796 | </glossdef>
|
---|
1797 | </glossentry>
|
---|
1798 |
|
---|
1799 | <glossentry>
|
---|
1800 | <glossterm>tempeject</glossterm>
|
---|
1801 |
|
---|
1802 | <glossdef>
|
---|
1803 | <para>For a virtual DVD drive only, you can configure the behavior
|
---|
1804 | for guest-triggered medium eject. If this is set to "on", the eject
|
---|
1805 | has only temporary effects. If the VM is powered off and restarted
|
---|
1806 | the originally configured medium will be still in the drive.</para>
|
---|
1807 | </glossdef>
|
---|
1808 | </glossentry>
|
---|
1809 |
|
---|
1810 | <glossentry>
|
---|
1811 | <glossterm>bandwidthgroup</glossterm>
|
---|
1812 |
|
---|
1813 | <glossdef>
|
---|
1814 | <para>Sets the bandwidth group to use for the given device; see
|
---|
1815 | <xref linkend="storage-bandwidth-limit" />.</para>
|
---|
1816 | </glossdef>
|
---|
1817 | </glossentry>
|
---|
1818 |
|
---|
1819 | <glossentry>
|
---|
1820 | <glossterm>forceunmount</glossterm>
|
---|
1821 |
|
---|
1822 | <glossdef>
|
---|
1823 | <para>For a virtual DVD or floppy drive only, this forcibly
|
---|
1824 | unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if
|
---|
1825 | the previous one is locked down by the guest for reading. Again,
|
---|
1826 | see <xref linkend="storage-cds" /> for details.</para>
|
---|
1827 | </glossdef>
|
---|
1828 | </glossentry>
|
---|
1829 | </glosslist></para>
|
---|
1830 |
|
---|
1831 | <para>When "iscsi" is used with the
|
---|
1832 | <computeroutput>--medium</computeroutput> parameter for iSCSI support --
|
---|
1833 | see <xref linkend="storage-iscsi" /> --, additional parameters must or can
|
---|
1834 | be used:<glosslist>
|
---|
1835 | <glossentry>
|
---|
1836 | <glossterm>server</glossterm>
|
---|
1837 |
|
---|
1838 | <glossdef>
|
---|
1839 | <para>The host name or IP address of the iSCSI target;
|
---|
1840 | required.</para>
|
---|
1841 | </glossdef>
|
---|
1842 | </glossentry>
|
---|
1843 |
|
---|
1844 | <glossentry>
|
---|
1845 | <glossterm>target</glossterm>
|
---|
1846 |
|
---|
1847 | <glossdef>
|
---|
1848 | <para>Target name string. This is determined by the iSCSI target
|
---|
1849 | and used to identify the storage resource; required.</para>
|
---|
1850 | </glossdef>
|
---|
1851 | </glossentry>
|
---|
1852 |
|
---|
1853 | <glossentry>
|
---|
1854 | <glossterm>tport</glossterm>
|
---|
1855 |
|
---|
1856 | <glossdef>
|
---|
1857 | <para>TCP/IP port number of the iSCSI service on the target
|
---|
1858 | (optional).</para>
|
---|
1859 | </glossdef>
|
---|
1860 | </glossentry>
|
---|
1861 |
|
---|
1862 | <glossentry>
|
---|
1863 | <glossterm>lun</glossterm>
|
---|
1864 |
|
---|
1865 | <glossdef>
|
---|
1866 | <para>Logical Unit Number of the target resource (optional).
|
---|
1867 | Often, this value is zero.</para>
|
---|
1868 | </glossdef>
|
---|
1869 | </glossentry>
|
---|
1870 |
|
---|
1871 | <glossentry>
|
---|
1872 | <glossterm>username, password</glossterm>
|
---|
1873 |
|
---|
1874 | <glossdef>
|
---|
1875 | <para>Username and password (initiator secret) for target
|
---|
1876 | authentication, if required (optional).<note>
|
---|
1877 | <para>Username and password are stored without
|
---|
1878 | encryption (i.e. in clear text) in the XML machine
|
---|
1879 | configuration file if no settings password is provided.
|
---|
1880 | When a settings password was specified the first time,
|
---|
1881 | the password is stored encrypted.</para>
|
---|
1882 | </note></para>
|
---|
1883 | </glossdef>
|
---|
1884 | </glossentry>
|
---|
1885 |
|
---|
1886 | <glossentry>
|
---|
1887 | <glossterm>intnet</glossterm>
|
---|
1888 |
|
---|
1889 | <glossdef>
|
---|
1890 | <para>If specified, connect to the iSCSI target via Internal
|
---|
1891 | Networking. This needs further configuration which is described in
|
---|
1892 | <xref linkend="iscsi-intnet" />.</para>
|
---|
1893 | </glossdef>
|
---|
1894 | </glossentry>
|
---|
1895 | </glosslist></para>
|
---|
1896 | </sect1>
|
---|
1897 |
|
---|
1898 | <sect1 id="vboxmanage-storagectl">
|
---|
1899 | <title>VBoxManage storagectl</title>
|
---|
1900 |
|
---|
1901 | <para>This command attaches/modifies/removes a storage controller. After
|
---|
1902 | this, virtual media can be attached to the controller with the
|
---|
1903 | <computeroutput>storageattach</computeroutput> command (see the next
|
---|
1904 | section).</para>
|
---|
1905 |
|
---|
1906 | <para>The syntax is as follows:</para>
|
---|
1907 |
|
---|
1908 | <screen>VBoxManage storagectl <uuid|vmname>
|
---|
1909 | --name <name>
|
---|
1910 | [--add <ide/sata/scsi/floppy>]
|
---|
1911 | [--controller <LsiLogic|LSILogicSAS|BusLogic|
|
---|
1912 | IntelAhci|PIIX3|PIIX4|ICH6|I82078>]
|
---|
1913 | [--sataideemulation<1-4> <1-30>]
|
---|
1914 | [--sataportcount <1-30>]
|
---|
1915 | [--hostiocache on|off]
|
---|
1916 | [--bootable on|off]
|
---|
1917 | [--remove]</screen>
|
---|
1918 |
|
---|
1919 | <para>where the parameters mean: <glosslist>
|
---|
1920 | <glossentry>
|
---|
1921 | <glossterm>uuid|vmname</glossterm>
|
---|
1922 |
|
---|
1923 | <glossdef>
|
---|
1924 | <para>The VM UUID or VM Name. Mandatory.</para>
|
---|
1925 | </glossdef>
|
---|
1926 | </glossentry>
|
---|
1927 |
|
---|
1928 | <glossentry>
|
---|
1929 | <glossterm>name</glossterm>
|
---|
1930 |
|
---|
1931 | <glossdef>
|
---|
1932 | <para>Name of the storage controller. Mandatory.</para>
|
---|
1933 | </glossdef>
|
---|
1934 | </glossentry>
|
---|
1935 |
|
---|
1936 | <glossentry>
|
---|
1937 | <glossterm>add</glossterm>
|
---|
1938 |
|
---|
1939 | <glossdef>
|
---|
1940 | <para>Define the type of the system bus to which the storage
|
---|
1941 | controller must be connected.</para>
|
---|
1942 | </glossdef>
|
---|
1943 | </glossentry>
|
---|
1944 |
|
---|
1945 | <glossentry>
|
---|
1946 | <glossterm>controller</glossterm>
|
---|
1947 |
|
---|
1948 | <glossdef>
|
---|
1949 | <para>Allows to choose the type of chipset being emulated for the
|
---|
1950 | given storage controller.</para>
|
---|
1951 | </glossdef>
|
---|
1952 | </glossentry>
|
---|
1953 |
|
---|
1954 | <glossentry>
|
---|
1955 | <glossterm>sataideemulation</glossterm>
|
---|
1956 |
|
---|
1957 | <glossdef>
|
---|
1958 | <para>This specifies which SATA ports should operate in IDE
|
---|
1959 | emulation mode. As explained in <xref
|
---|
1960 | linkend="harddiskcontrollers" />, by default, this is the case for
|
---|
1961 | SATA ports 1-4; with this command, you can map four IDE channels
|
---|
1962 | to any of the 30 supported SATA ports.</para>
|
---|
1963 | </glossdef>
|
---|
1964 | </glossentry>
|
---|
1965 |
|
---|
1966 | <glossentry>
|
---|
1967 | <glossterm>sataportcount</glossterm>
|
---|
1968 |
|
---|
1969 | <glossdef>
|
---|
1970 | <para>This determines how many ports the SATA controller should
|
---|
1971 | support.</para>
|
---|
1972 | </glossdef>
|
---|
1973 | </glossentry>
|
---|
1974 |
|
---|
1975 | <glossentry>
|
---|
1976 | <glossterm>hostiocache</glossterm>
|
---|
1977 |
|
---|
1978 | <glossdef>
|
---|
1979 | <para>Configures the use of the host I/O cache for all disk images
|
---|
1980 | attached to this storage controller. For details, please see <xref
|
---|
1981 | linkend="iocaching" />.</para>
|
---|
1982 | </glossdef>
|
---|
1983 | </glossentry>
|
---|
1984 |
|
---|
1985 | <glossentry>
|
---|
1986 | <glossterm>bootable</glossterm>
|
---|
1987 |
|
---|
1988 | <glossdef>
|
---|
1989 | <para>Selects whether this controller is bootable.</para>
|
---|
1990 | </glossdef>
|
---|
1991 | </glossentry>
|
---|
1992 |
|
---|
1993 | <glossentry>
|
---|
1994 | <glossterm>remove</glossterm>
|
---|
1995 |
|
---|
1996 | <glossdef>
|
---|
1997 | <para>Removes the storage controller from the VM config.</para>
|
---|
1998 | </glossdef>
|
---|
1999 | </glossentry>
|
---|
2000 | </glosslist></para>
|
---|
2001 | </sect1>
|
---|
2002 |
|
---|
2003 | <sect1>
|
---|
2004 | <title>VBoxManage bandwidthctl</title>
|
---|
2005 |
|
---|
2006 | <para>This command creates/deletes/modifies/shows bandwidth groups of the given
|
---|
2007 | virtual machine:<screen>VBoxManage bandwidthctl <uuid|vmname>
|
---|
2008 | add <name> --type disk|network --limit <megabytes per second>[k|m|g|K|M|G] |
|
---|
2009 | set <name> --limit <megabytes per second>[k|m|g|K|M|G] |
|
---|
2010 | remove <name> |
|
---|
2011 | list [--machinereadable]</screen></para>
|
---|
2012 |
|
---|
2013 | <para>The following subcommands are available:<itemizedlist>
|
---|
2014 | <listitem>
|
---|
2015 | <para><computeroutput>add</computeroutput>, creates a new bandwidth
|
---|
2016 | group of given type.</para>
|
---|
2017 | </listitem>
|
---|
2018 | <listitem>
|
---|
2019 | <para><computeroutput>set</computeroutput>, modifies the limit for an
|
---|
2020 | existing bandwidth group.</para>
|
---|
2021 | </listitem>
|
---|
2022 | <listitem>
|
---|
2023 | <para><computeroutput>remove</computeroutput>, destroys a bandwidth
|
---|
2024 | group.</para>
|
---|
2025 | </listitem>
|
---|
2026 | <listitem>
|
---|
2027 | <para><computeroutput>list</computeroutput>, shows all bandwidth groups
|
---|
2028 | defined for the given VM.</para>
|
---|
2029 | </listitem>
|
---|
2030 | </itemizedlist>
|
---|
2031 | </para>
|
---|
2032 | <para>The parameters mean:<glosslist>
|
---|
2033 | <glossentry>
|
---|
2034 | <glossterm>uuid|vmname</glossterm>
|
---|
2035 |
|
---|
2036 | <glossdef>
|
---|
2037 | <para>The VM UUID or VM Name. Mandatory.</para>
|
---|
2038 | </glossdef>
|
---|
2039 | </glossentry>
|
---|
2040 |
|
---|
2041 | <glossentry>
|
---|
2042 | <glossterm>name</glossterm>
|
---|
2043 |
|
---|
2044 | <glossdef>
|
---|
2045 | <para>Name of the bandwidth group. Mandatory.</para>
|
---|
2046 | </glossdef>
|
---|
2047 | </glossentry>
|
---|
2048 |
|
---|
2049 | <glossentry>
|
---|
2050 | <glossterm>type</glossterm>
|
---|
2051 |
|
---|
2052 | <glossdef>
|
---|
2053 | <para>Type of the bandwidth group. Mandatory. Two types are
|
---|
2054 | supported: <computeroutput>disk</computeroutput> and
|
---|
2055 | <computeroutput>network</computeroutput>. See
|
---|
2056 | <xref linkend="storage-bandwidth-limit" /> or
|
---|
2057 | <xref linkend="network_bandwidth_limit" /> for a description of a
|
---|
2058 | particular type.</para>
|
---|
2059 | </glossdef>
|
---|
2060 | </glossentry>
|
---|
2061 |
|
---|
2062 | <glossentry>
|
---|
2063 | <glossterm>limit</glossterm>
|
---|
2064 |
|
---|
2065 | <glossdef>
|
---|
2066 | <para>Specifies the limit for the given group. Can be changed
|
---|
2067 | while the VM is running. The default unit is megabytes per
|
---|
2068 | second. The unit can be changed by specifying one of the
|
---|
2069 | following suffixes: <computeroutput>k</computeroutput> for kilobits/s, <computeroutput>m</computeroutput> for megabits/s, <computeroutput>g</computeroutput> for gigabits/s, <computeroutput>K</computeroutput> for kilobytes/s, <computeroutput>M</computeroutput> for megabytes/s, <computeroutput>G</computeroutput> for gigabytes/s.</para>
|
---|
2070 | </glossdef>
|
---|
2071 | </glossentry>
|
---|
2072 | </glosslist>
|
---|
2073 | <note>
|
---|
2074 | <para>The network bandwidth limits apply only to the traffic being sent by
|
---|
2075 | virtual machines. The traffic being received by VMs is unlimited.</para>
|
---|
2076 | </note>
|
---|
2077 | <note>
|
---|
2078 | <para>To remove a bandwidth group it must not be referenced by any disks
|
---|
2079 | or adapters in running VM.</para>
|
---|
2080 | </note>
|
---|
2081 | </para>
|
---|
2082 | </sect1>
|
---|
2083 |
|
---|
2084 | <sect1>
|
---|
2085 | <title>VBoxManage showhdinfo</title>
|
---|
2086 |
|
---|
2087 | <para>This command shows information about a virtual hard disk image,
|
---|
2088 | notably its size, its size on disk, its type and the virtual machines
|
---|
2089 | which use it.<note>
|
---|
2090 | <para>For compatibility with earlier versions of VirtualBox, the
|
---|
2091 | "showvdiinfo" command is also supported and mapped internally to the
|
---|
2092 | "showhdinfo" command.</para>
|
---|
2093 | </note></para>
|
---|
2094 | <para>The disk image must be specified either by its UUID (if the medium
|
---|
2095 | is registered) or by its filename. Registered images can be listed by
|
---|
2096 | <computeroutput>VBoxManage list hdds</computeroutput> (see <xref linkend="vboxmanage-list" />
|
---|
2097 | for more information). A filename must be specified as valid path, either
|
---|
2098 | as an absolute path or as a relative path starting from the current
|
---|
2099 | directory.</para>
|
---|
2100 | </sect1>
|
---|
2101 |
|
---|
2102 | <sect1 id="vboxmanage-createvdi">
|
---|
2103 | <title>VBoxManage createhd</title>
|
---|
2104 |
|
---|
2105 | <para>This command creates a new virtual hard disk image. The syntax is as
|
---|
2106 | follows:</para>
|
---|
2107 |
|
---|
2108 | <screen>VBoxManage createhd --filename <filename>
|
---|
2109 | --size <megabytes>
|
---|
2110 | [--format VDI|VMDK|VHD] (default: VDI)
|
---|
2111 | [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
|
---|
2112 |
|
---|
2113 | <para>where the parameters mean:<glosslist>
|
---|
2114 | <glossentry>
|
---|
2115 | <glossterm>filename</glossterm>
|
---|
2116 |
|
---|
2117 | <glossdef>
|
---|
2118 | <para>Allows to choose a file name. Mandatory.</para>
|
---|
2119 | </glossdef>
|
---|
2120 | </glossentry>
|
---|
2121 |
|
---|
2122 | <glossentry>
|
---|
2123 | <glossterm>size</glossterm>
|
---|
2124 |
|
---|
2125 | <glossdef>
|
---|
2126 | <para>Allows to define the image capacity, in 1 MiB units.
|
---|
2127 | Mandatory.</para>
|
---|
2128 | </glossdef>
|
---|
2129 | </glossentry>
|
---|
2130 |
|
---|
2131 | <glossentry>
|
---|
2132 | <glossterm>format</glossterm>
|
---|
2133 |
|
---|
2134 | <glossdef>
|
---|
2135 | <para>Allows to choose a file format for the output file different
|
---|
2136 | from the file format of the input file.</para>
|
---|
2137 | </glossdef>
|
---|
2138 | </glossentry>
|
---|
2139 |
|
---|
2140 | <glossentry>
|
---|
2141 | <glossterm>variant</glossterm>
|
---|
2142 |
|
---|
2143 | <glossdef>
|
---|
2144 | <para>Allows to choose a file format variant for the output file.
|
---|
2145 | It is a comma-separated list of variant flags. Not all
|
---|
2146 | combinations are supported, and specifying inconsistent flags will
|
---|
2147 | result in an error message.</para>
|
---|
2148 | </glossdef>
|
---|
2149 | </glossentry>
|
---|
2150 | </glosslist> <note>
|
---|
2151 | <para>For compatibility with earlier versions of VirtualBox, the
|
---|
2152 | "createvdi" command is also supported and mapped internally to the
|
---|
2153 | "createhd" command.</para>
|
---|
2154 | </note></para>
|
---|
2155 | </sect1>
|
---|
2156 |
|
---|
2157 | <sect1 id="vboxmanage-modifyvdi">
|
---|
2158 | <title>VBoxManage modifyhd</title>
|
---|
2159 |
|
---|
2160 | <para>With the <computeroutput>modifyhd</computeroutput> command, you can
|
---|
2161 | change the characteristics of a disk image after it has been
|
---|
2162 | created:<screen>VBoxManage modifyhd <uuid>|<filename>
|
---|
2163 | [--type normal|writethrough|immutable|shareable|
|
---|
2164 | readonly|multiattach]
|
---|
2165 | [--autoreset on|off]
|
---|
2166 | [--compact]
|
---|
2167 | [--resize <megabytes>|--resizebyte <bytes>]</screen><note>
|
---|
2168 | <para>Despite the "hd" in the subcommand name, the command works with
|
---|
2169 | all disk images, not only hard disks. For compatibility with earlier
|
---|
2170 | versions of VirtualBox, the "modifyvdi" command is also supported and
|
---|
2171 | mapped internally to the "modifyhd" command.</para>
|
---|
2172 | </note></para>
|
---|
2173 |
|
---|
2174 | <para>The disk image to modify must be specified either by its UUID
|
---|
2175 | (if the medium is registered) or by its filename. Registered images
|
---|
2176 | can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
|
---|
2177 | (see <xref linkend="vboxmanage-list" /> for more information).
|
---|
2178 | A filename must be specified as valid path, either as an absolute path
|
---|
2179 | or as a relative path starting from the current directory.</para>
|
---|
2180 | <para>The following options are available:<itemizedlist>
|
---|
2181 | <listitem>
|
---|
2182 | <para>With the <computeroutput>--type</computeroutput> argument, you
|
---|
2183 | can change the type of an existing image between the normal,
|
---|
2184 | immutable, write-through and other modes; see <xref
|
---|
2185 | linkend="hdimagewrites" /> for details.</para>
|
---|
2186 | </listitem>
|
---|
2187 |
|
---|
2188 | <listitem>
|
---|
2189 | <para>For immutable (differencing) hard disks only, the
|
---|
2190 | <computeroutput>--autoreset on|off</computeroutput> option
|
---|
2191 | determines whether the disk is automatically reset on every VM
|
---|
2192 | startup (again, see <xref linkend="hdimagewrites" />). The default
|
---|
2193 | is "on".</para>
|
---|
2194 | </listitem>
|
---|
2195 |
|
---|
2196 | <listitem>
|
---|
2197 | <para>With the <computeroutput>--compact</computeroutput> option,
|
---|
2198 | can be used to compact disk images, i.e. remove blocks that only
|
---|
2199 | contains zeroes. This will shrink a dynamically allocated image
|
---|
2200 | again; it will reduce the <emphasis>physical</emphasis> size of the
|
---|
2201 | image without affecting the logical size of the virtual disk.
|
---|
2202 | Compaction works both for base images and for diff images created as
|
---|
2203 | part of a snapshot.</para>
|
---|
2204 |
|
---|
2205 | <para>For this operation to be effective, it is required that free
|
---|
2206 | space in the guest system first be zeroed out using a suitable
|
---|
2207 | software tool. For Windows guests, you can use the
|
---|
2208 | <computeroutput>sdelete</computeroutput> tool provided by Microsoft.
|
---|
2209 | Execute <computeroutput>sdelete -z</computeroutput> in the guest to
|
---|
2210 | zero the free disk space before compressing the virtual disk
|
---|
2211 | image. For Linux, use the <code>zerofree</code> utility which
|
---|
2212 | supports ext2/ext3 filesystems.</para>
|
---|
2213 |
|
---|
2214 | <para>Please note that compacting is currently only available for
|
---|
2215 | VDI images. A similar effect can be achieved by zeroing out free
|
---|
2216 | blocks and then cloning the disk to any other dynamically allocated
|
---|
2217 | format. You can use this workaround until compacting is also
|
---|
2218 | supported for disk formats other than VDI.</para>
|
---|
2219 | </listitem>
|
---|
2220 |
|
---|
2221 | <listitem>
|
---|
2222 | <para>The <computeroutput>--resize x</computeroutput> option (where x
|
---|
2223 | is the desired new total space in <emphasis role="bold">megabytes</emphasis>)
|
---|
2224 | allows you to change the capacity of an existing image; this adjusts the
|
---|
2225 | <emphasis>logical</emphasis> size of a virtual disk without affecting
|
---|
2226 | the physical size much.<footnote>
|
---|
2227 | <para>Image resizing was added with VirtualBox 4.0.</para>
|
---|
2228 | </footnote> This currently works only for VDI and VHD formats, and only
|
---|
2229 | for the dynamically allocated variants, and can only be used to expand
|
---|
2230 | (not shrink) the capacity.
|
---|
2231 | For example, if you originally created a 10G disk which is now full,
|
---|
2232 | you can use the <computeroutput>--resize 15360</computeroutput>
|
---|
2233 | command to change the capacity to 15G (15,360MB) without having to create a new
|
---|
2234 | image and copy all data from within a virtual machine. Note however that
|
---|
2235 | this only changes the drive capacity; you will typically next need to use
|
---|
2236 | a partition management tool inside the guest to adjust the main partition
|
---|
2237 | to fill the drive.</para><para>The <computeroutput>--resizebyte x</computeroutput>
|
---|
2238 | option does almost the same thing, except that x is expressed in bytes
|
---|
2239 | instead of megabytes.</para>
|
---|
2240 | </listitem>
|
---|
2241 | </itemizedlist></para>
|
---|
2242 | </sect1>
|
---|
2243 |
|
---|
2244 | <sect1 id="vboxmanage-clonevdi">
|
---|
2245 | <title>VBoxManage clonehd</title>
|
---|
2246 |
|
---|
2247 | <para>This command duplicates a registered virtual hard disk image to a
|
---|
2248 | new image file with a new unique identifier (UUID). The new image can be
|
---|
2249 | transferred to another host system or imported into VirtualBox again using
|
---|
2250 | the Virtual Media Manager; see <xref linkend="vdis" /> and <xref
|
---|
2251 | linkend="cloningvdis" />. The syntax is as follows:</para>
|
---|
2252 |
|
---|
2253 | <screen>VBoxManage clonehd <uuid>|<filename> <outputfile>
|
---|
2254 | [--format VDI|VMDK|VHD|RAW|<other>]
|
---|
2255 | [--variant Standard,Fixed,Split2G,Stream,ESX]
|
---|
2256 | [--existing]</screen>
|
---|
2257 |
|
---|
2258 | <para>The disk image to clone as well as the target image must be described
|
---|
2259 | either by its UUIDs (if the mediums are registered) or by its filename.
|
---|
2260 | Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
|
---|
2261 | (see <xref linkend="vboxmanage-list" /> for more information).
|
---|
2262 | A filename must be specified as valid path, either as an absolute path or
|
---|
2263 | as a relative path starting from the current directory.</para>
|
---|
2264 | <para>The following options are available:<glosslist>
|
---|
2265 | <glossentry>
|
---|
2266 | <glossterm>format</glossterm>
|
---|
2267 |
|
---|
2268 | <glossdef>
|
---|
2269 | <para>Allow to choose a file format for the output file different
|
---|
2270 | from the file format of the input file.</para>
|
---|
2271 | </glossdef>
|
---|
2272 | </glossentry>
|
---|
2273 |
|
---|
2274 | <glossentry>
|
---|
2275 | <glossterm>variant</glossterm>
|
---|
2276 |
|
---|
2277 | <glossdef>
|
---|
2278 | <para>Allow to choose a file format variant for the output file.
|
---|
2279 | It is a comma-separated list of variant flags. Not all
|
---|
2280 | combinations are supported, and specifying inconsistent flags will
|
---|
2281 | result in an error message.</para>
|
---|
2282 | </glossdef>
|
---|
2283 | </glossentry>
|
---|
2284 |
|
---|
2285 | <glossentry>
|
---|
2286 | <glossterm>existing</glossterm>
|
---|
2287 |
|
---|
2288 | <glossdef>
|
---|
2289 | <para>Perform the clone operation to an already existing
|
---|
2290 | destination medium. Only the portion of the source medium which
|
---|
2291 | fits into the destination medium is copied. This means if the
|
---|
2292 | destination medium is smaller than the source only a part of it is
|
---|
2293 | copied, and if the destination medium is larger than the source
|
---|
2294 | the remaining part of the destination medium is unchanged.</para>
|
---|
2295 | </glossdef>
|
---|
2296 | </glossentry>
|
---|
2297 | </glosslist> <note>
|
---|
2298 | <para>For compatibility with earlier versions of VirtualBox, the
|
---|
2299 | "clonevdi" command is also supported and mapped internally to the
|
---|
2300 | "clonehd" command.</para>
|
---|
2301 | </note></para>
|
---|
2302 | </sect1>
|
---|
2303 |
|
---|
2304 | <sect1>
|
---|
2305 | <title>VBoxManage convertfromraw</title>
|
---|
2306 |
|
---|
2307 | <para>This command converts a raw disk image to a VirtualBox Disk Image
|
---|
2308 | (VDI) file. The syntax is as follows:</para>
|
---|
2309 |
|
---|
2310 | <screen>VBoxManage convertfromraw <filename> <outputfile>
|
---|
2311 | [--format VDI|VMDK|VHD]
|
---|
2312 | [--variant Standard,Fixed,Split2G,Stream,ESX]
|
---|
2313 | [--uuid <uuid>]
|
---|
2314 | VBoxManage convertfromraw stdin <outputfile> <bytes>
|
---|
2315 | [--format VDI|VMDK|VHD]
|
---|
2316 | [--variant Standard,Fixed,Split2G,Stream,ESX]
|
---|
2317 | [--uuid <uuid>]</screen>
|
---|
2318 |
|
---|
2319 | <para>where the parameters mean:<glosslist>
|
---|
2320 | <glossentry>
|
---|
2321 | <glossterm>bytes</glossterm>
|
---|
2322 |
|
---|
2323 | <glossdef>
|
---|
2324 | <para>The size of the image file, in bytes, provided through
|
---|
2325 | stdin.</para>
|
---|
2326 | </glossdef>
|
---|
2327 | </glossentry>
|
---|
2328 |
|
---|
2329 | <glossentry>
|
---|
2330 | <glossterm>format</glossterm>
|
---|
2331 |
|
---|
2332 | <glossdef>
|
---|
2333 | <para>Select the disk image format to create. Default is
|
---|
2334 | VDI.</para>
|
---|
2335 | </glossdef>
|
---|
2336 | </glossentry>
|
---|
2337 |
|
---|
2338 | <glossentry>
|
---|
2339 | <glossterm>variant</glossterm>
|
---|
2340 |
|
---|
2341 | <glossdef>
|
---|
2342 | <para>Allow to choose a file format variant for the output file.
|
---|
2343 | It is a comma-separated list of variant flags. Not all
|
---|
2344 | combinations are supported, and specifying inconsistent flags will
|
---|
2345 | result in an error message.</para>
|
---|
2346 | </glossdef>
|
---|
2347 | </glossentry>
|
---|
2348 |
|
---|
2349 | <glossentry>
|
---|
2350 | <glossterm>uuid</glossterm>
|
---|
2351 |
|
---|
2352 | <glossdef>
|
---|
2353 | <para>Allow to specifiy the UUID of the output file.</para>
|
---|
2354 | </glossdef>
|
---|
2355 | </glossentry>
|
---|
2356 | </glosslist> The second form forces VBoxManage to read the content for
|
---|
2357 | the disk image from standard input (useful for using that command in a
|
---|
2358 | pipe).</para>
|
---|
2359 |
|
---|
2360 | <para><note>
|
---|
2361 | <para>For compatibility with earlier versions of VirtualBox, the
|
---|
2362 | "convertdd" command is also supported and mapped internally to the
|
---|
2363 | "convertfromraw" command.</para>
|
---|
2364 | </note></para>
|
---|
2365 | </sect1>
|
---|
2366 |
|
---|
2367 | <sect1>
|
---|
2368 | <title>VBoxManage getextradata/setextradata</title>
|
---|
2369 |
|
---|
2370 | <para>These commands let you attach and retrieve string data to a virtual
|
---|
2371 | machine or to a VirtualBox configuration (by specifying
|
---|
2372 | <computeroutput>global</computeroutput> instead of a virtual machine
|
---|
2373 | name). You must specify a key (as a text string) to associate the data
|
---|
2374 | with, which you can later use to retrieve it. For example:</para>
|
---|
2375 |
|
---|
2376 | <screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
|
---|
2377 | VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
|
---|
2378 |
|
---|
2379 | <para>would associate the string "2006.01.01" with the key installdate for
|
---|
2380 | the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
|
---|
2381 | could retrieve the information as follows:</para>
|
---|
2382 |
|
---|
2383 | <screen>VBoxManage getextradata Fedora5 installdate</screen>
|
---|
2384 |
|
---|
2385 | <para>which would return</para>
|
---|
2386 |
|
---|
2387 | <screen>VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
|
---|
2388 | (C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
|
---|
2389 | All rights reserved.
|
---|
2390 |
|
---|
2391 | Value: 2006.01.01</screen>
|
---|
2392 | <para>To remove a key, the <computeroutput>setextradata</computeroutput>
|
---|
2393 | command must be run without specifying data (only the key), for example:
|
---|
2394 | </para>
|
---|
2395 |
|
---|
2396 | <screen>VBoxManage setextradata Fedora5 installdate</screen>
|
---|
2397 |
|
---|
2398 | </sect1>
|
---|
2399 |
|
---|
2400 | <sect1 id="vboxmanage-setproperty">
|
---|
2401 | <title>VBoxManage setproperty</title>
|
---|
2402 |
|
---|
2403 | <para>This command is used to change global settings which affect the
|
---|
2404 | entire VirtualBox installation. Some of these correspond to the settings
|
---|
2405 | in the "Global settings" dialog in the graphical user interface. The
|
---|
2406 | following properties are available:<glosslist>
|
---|
2407 | <glossentry>
|
---|
2408 | <glossterm>machinefolder</glossterm>
|
---|
2409 |
|
---|
2410 | <glossdef>
|
---|
2411 | <para>This specifies the default folder in which virtual machine
|
---|
2412 | definitions are kept; see <xref linkend="vboxconfigdata" /> for
|
---|
2413 | details.</para>
|
---|
2414 | </glossdef>
|
---|
2415 | </glossentry>
|
---|
2416 |
|
---|
2417 | <glossentry>
|
---|
2418 | <glossterm>vrdeauthlibrary</glossterm>
|
---|
2419 |
|
---|
2420 | <glossdef>
|
---|
2421 | <para>This specifies which library to use when "external"
|
---|
2422 | authentication has been selected for a particular virtual machine;
|
---|
2423 | see <xref linkend="vbox-auth" /> for details.</para>
|
---|
2424 | </glossdef>
|
---|
2425 | </glossentry>
|
---|
2426 |
|
---|
2427 | <glossentry>
|
---|
2428 | <glossterm>websrvauthlibrary</glossterm>
|
---|
2429 |
|
---|
2430 | <glossdef>
|
---|
2431 | <para>This specifies which library the web service uses to
|
---|
2432 | authenticate users. For details about the VirtualBox web service,
|
---|
2433 | please refer to the separate VirtualBox SDK reference (see <xref
|
---|
2434 | linkend="VirtualBoxAPI" />).</para>
|
---|
2435 | </glossdef>
|
---|
2436 | </glossentry>
|
---|
2437 |
|
---|
2438 | <glossentry>
|
---|
2439 | <glossterm>vrdelibrary</glossterm>
|
---|
2440 |
|
---|
2441 | <glossdef>
|
---|
2442 | <para>This specifies which library implements the VirtualBox
|
---|
2443 | Remote Desktop Extension.</para>
|
---|
2444 | </glossdef>
|
---|
2445 | </glossentry>
|
---|
2446 |
|
---|
2447 | <glossentry>
|
---|
2448 | <glossterm>hwvirtexenabled</glossterm>
|
---|
2449 |
|
---|
2450 | <glossdef>
|
---|
2451 | <para>This selects whether or not hardware virtualization support
|
---|
2452 | is enabled by default.</para>
|
---|
2453 | </glossdef>
|
---|
2454 | </glossentry>
|
---|
2455 | </glosslist></para>
|
---|
2456 | </sect1>
|
---|
2457 |
|
---|
2458 | <sect1>
|
---|
2459 | <title>VBoxManage usbfilter add/modify/remove</title>
|
---|
2460 |
|
---|
2461 | <para>The <computeroutput>usbfilter</computeroutput> commands are used for
|
---|
2462 | working with USB filters in virtual machines, or global filters which
|
---|
2463 | affect the whole VirtualBox setup. Global filters are applied before
|
---|
2464 | machine-specific filters, and may be used to prevent devices from being
|
---|
2465 | captured by any virtual machine. Global filters are always applied in a
|
---|
2466 | particular order, and only the first filter which fits a device is
|
---|
2467 | applied. So for example, if the first global filter says to hold (make
|
---|
2468 | available) a particular Kingston memory stick device and the second to
|
---|
2469 | ignore all Kingston devices, that memory stick will be available to any
|
---|
2470 | machine with an appropriate filter, but no other Kingston device
|
---|
2471 | will.</para>
|
---|
2472 |
|
---|
2473 | <para>When creating a USB filter using <computeroutput>usbfilter
|
---|
2474 | add</computeroutput>, you must supply three or four mandatory parameters.
|
---|
2475 | The index specifies the position in the list at which the filter should be
|
---|
2476 | placed. If there is already a filter at that position, then it and the
|
---|
2477 | following ones will be shifted back one place. Otherwise the new filter
|
---|
2478 | will be added onto the end of the list. The
|
---|
2479 | <computeroutput>target</computeroutput> parameter selects the virtual
|
---|
2480 | machine that the filter should be attached to or use "global" to apply it
|
---|
2481 | to all virtual machines. <computeroutput>name</computeroutput> is a name
|
---|
2482 | for the new filter and for global filters,
|
---|
2483 | <computeroutput>action</computeroutput> says whether to allow machines
|
---|
2484 | access to devices that fit the filter description ("hold") or not to give
|
---|
2485 | them access ("ignore"). In addition, you should specify parameters to
|
---|
2486 | filter by. You can find the parameters for devices attached to your system
|
---|
2487 | using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
|
---|
2488 | you can specify whether the filter should be active, and for local
|
---|
2489 | filters, whether they are for local devices, remote (over an RDP
|
---|
2490 | connection) or either.</para>
|
---|
2491 |
|
---|
2492 | <para>When you modify a USB filter using <computeroutput>usbfilter
|
---|
2493 | modify</computeroutput>, you must specify the filter by index (see the
|
---|
2494 | output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
|
---|
2495 | find global filter indexes and that of <computeroutput>VBoxManage
|
---|
2496 | showvminfo</computeroutput> to find indexes for individual machines) and
|
---|
2497 | by target, which is either a virtual machine or "global". The properties
|
---|
2498 | which can be changed are the same as for <computeroutput>usbfilter
|
---|
2499 | add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
|
---|
2500 | remove</computeroutput> and specify the index and the target.</para>
|
---|
2501 | </sect1>
|
---|
2502 |
|
---|
2503 | <sect1 id="vboxmanage-sharedfolder">
|
---|
2504 | <title>VBoxManage sharedfolder add/remove</title>
|
---|
2505 |
|
---|
2506 | <para>This command allows you to share folders on the host computer with
|
---|
2507 | guest operating systems. For this, the guest systems must have a version
|
---|
2508 | of the VirtualBox Guest Additions installed which supports this
|
---|
2509 | functionality.</para>
|
---|
2510 |
|
---|
2511 | <para>Shared folders are described in detail in <xref
|
---|
2512 | linkend="sharedfolders" />.</para>
|
---|
2513 | </sect1>
|
---|
2514 |
|
---|
2515 | <sect1 id="vboxmanage-guestproperty">
|
---|
2516 | <title>VBoxManage guestproperty</title>
|
---|
2517 |
|
---|
2518 | <para>The "guestproperty" commands allow you to get or set properties of a
|
---|
2519 | running virtual machine. Please see <xref linkend="guestadd-guestprops" />
|
---|
2520 | for an introduction. As explained there, guest properties are arbitrary
|
---|
2521 | key/value string pairs which can be written to and read from by either the
|
---|
2522 | guest or the host, so they can be used as a low-volume communication
|
---|
2523 | channel for strings, provided that a guest is running and has the Guest
|
---|
2524 | Additions installed. In addition, a number of values whose keys begin with
|
---|
2525 | "/VirtualBox/" are automatically set and maintained by the Guest
|
---|
2526 | Additions.</para>
|
---|
2527 |
|
---|
2528 | <para>The following subcommands are available (where
|
---|
2529 | <computeroutput><vm></computeroutput>, in each case, can either be a
|
---|
2530 | VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
|
---|
2531 | <listitem>
|
---|
2532 | <para><computeroutput>enumerate <vm> [--patterns
|
---|
2533 | <pattern>]</computeroutput>: This lists all the guest
|
---|
2534 | properties that are available for the given VM, including the value.
|
---|
2535 | This list will be very limited if the guest's service process cannot
|
---|
2536 | be contacted, e.g. because the VM is not running or the Guest
|
---|
2537 | Additions are not installed.</para>
|
---|
2538 |
|
---|
2539 | <para>If <computeroutput>--patterns <pattern></computeroutput>
|
---|
2540 | is specified, it acts as a filter to only list properties that match
|
---|
2541 | the given pattern. The pattern can contain the following wildcard
|
---|
2542 | characters:<itemizedlist>
|
---|
2543 | <listitem>
|
---|
2544 | <para><computeroutput>*</computeroutput> (asterisk):
|
---|
2545 | represents any number of characters; for example,
|
---|
2546 | "<computeroutput>/VirtualBox*</computeroutput>" would match
|
---|
2547 | all properties beginning with "/VirtualBox".</para>
|
---|
2548 | </listitem>
|
---|
2549 |
|
---|
2550 | <listitem>
|
---|
2551 | <para><computeroutput>?</computeroutput> (question mark):
|
---|
2552 | represents a single arbitrary character; for example,
|
---|
2553 | "<computeroutput>fo?</computeroutput>" would match both "foo"
|
---|
2554 | and "for".</para>
|
---|
2555 | </listitem>
|
---|
2556 |
|
---|
2557 | <listitem>
|
---|
2558 | <para><computeroutput>|</computeroutput> (pipe symbol): can be
|
---|
2559 | used to specify multiple alternative patterns; for example,
|
---|
2560 | "<computeroutput>s*|t*</computeroutput>" would match anything
|
---|
2561 | starting with either "s" or "t".</para>
|
---|
2562 | </listitem>
|
---|
2563 | </itemizedlist></para>
|
---|
2564 | </listitem>
|
---|
2565 |
|
---|
2566 | <listitem>
|
---|
2567 | <para><computeroutput>get <vm></computeroutput>: This
|
---|
2568 | retrieves the value of a single property only. If the property
|
---|
2569 | cannot be found (e.g. because the guest is not running), this will
|
---|
2570 | print <screen>No value set!</screen></para>
|
---|
2571 | </listitem>
|
---|
2572 |
|
---|
2573 | <listitem>
|
---|
2574 | <para><computeroutput>set <vm> <property> [<value>
|
---|
2575 | [--flags <flags>]]</computeroutput>: This allows you to set a
|
---|
2576 | guest property by specifying the key and value. If
|
---|
2577 | <computeroutput><value></computeroutput> is omitted, the
|
---|
2578 | property is deleted. With <computeroutput>--flags</computeroutput>
|
---|
2579 | you can optionally specify additional behavior (you can combine
|
---|
2580 | several by separating them with commas):<itemizedlist>
|
---|
2581 | <listitem>
|
---|
2582 | <para><computeroutput>TRANSIENT</computeroutput>: the value
|
---|
2583 | will not be stored with the VM data when the VM exits;</para>
|
---|
2584 | </listitem>
|
---|
2585 |
|
---|
2586 | <listitem>
|
---|
2587 | <para><computeroutput>TRANSRESET</computeroutput>: the value
|
---|
2588 | will be deleted as soon as the VM restarts and/or exits;</para>
|
---|
2589 | </listitem>
|
---|
2590 |
|
---|
2591 | <listitem>
|
---|
2592 | <para><computeroutput>RDONLYGUEST</computeroutput>: the value
|
---|
2593 | can only be changed by the host, but the guest can only read
|
---|
2594 | it;</para>
|
---|
2595 | </listitem>
|
---|
2596 |
|
---|
2597 | <listitem>
|
---|
2598 | <para><computeroutput>RDONLYHOST</computeroutput>: reversely,
|
---|
2599 | the value can only be changed by the guest, but the host can
|
---|
2600 | only read it;</para>
|
---|
2601 | </listitem>
|
---|
2602 |
|
---|
2603 | <listitem>
|
---|
2604 | <para><computeroutput>READONLY</computeroutput>: a combination
|
---|
2605 | of the two, the value cannot be changed at all.</para>
|
---|
2606 | </listitem>
|
---|
2607 | </itemizedlist></para>
|
---|
2608 | </listitem>
|
---|
2609 |
|
---|
2610 | <listitem>
|
---|
2611 | <para><computeroutput>wait <vm> <pattern> --timeout
|
---|
2612 | <timeout></computeroutput>: This waits for a particular value
|
---|
2613 | described by "pattern" to change or to be deleted or created. The
|
---|
2614 | pattern rules are the same as for the "enumerate" subcommand
|
---|
2615 | above.</para>
|
---|
2616 | </listitem>
|
---|
2617 | </itemizedlist></para>
|
---|
2618 | </sect1>
|
---|
2619 |
|
---|
2620 | <sect1 id="vboxmanage-guestcontrol">
|
---|
2621 | <title>VBoxManage guestcontrol</title>
|
---|
2622 |
|
---|
2623 | <para>The "guestcontrol" commands allow you to control certain things
|
---|
2624 | inside a guest from the host. Please see <xref
|
---|
2625 | linkend="guestadd-guestcontrol" /> for an introduction.</para>
|
---|
2626 |
|
---|
2627 | <para>Generally, the syntax is as follows:</para>
|
---|
2628 |
|
---|
2629 | <screen>VBoxManage guestcontrol <command></screen>
|
---|
2630 |
|
---|
2631 | <para>The following subcommands are available (where
|
---|
2632 | <computeroutput><vm></computeroutput>, in each case, can either be a
|
---|
2633 | VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
|
---|
2634 | <listitem>
|
---|
2635 | <para><computeroutput>execute</computeroutput>, which allows for
|
---|
2636 | executing a program/script (process) which already is installed and
|
---|
2637 | runnable on the guest. This command only works while a VM is up and
|
---|
2638 | running and has the following syntax:</para>
|
---|
2639 |
|
---|
2640 | <screen>VBoxManage guestcontrol <vmname>|<uuid> exec[ute]
|
---|
2641 | --image <path to program> --username <name>
|
---|
2642 | [--passwordfile <file> | --password <password>]
|
---|
2643 | [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"]
|
---|
2644 | [--verbose] [--timeout <msec>]
|
---|
2645 | [--wait-exit] [--wait-stdout] [--wait-stderr]
|
---|
2646 | [--dos2unix] [--unix2dos]
|
---|
2647 | -- [[<argument1>] ... [<argumentN>]]</screen>
|
---|
2648 |
|
---|
2649 | <para>where the parameters mean: <glosslist>
|
---|
2650 | <glossentry>
|
---|
2651 | <glossterm>uuid|vmname</glossterm>
|
---|
2652 |
|
---|
2653 | <glossdef>
|
---|
2654 | <para>The VM UUID or VM name. Mandatory.</para>
|
---|
2655 | </glossdef>
|
---|
2656 | </glossentry>
|
---|
2657 |
|
---|
2658 | <glossentry>
|
---|
2659 | <glossterm>--image "<path to program>"</glossterm>
|
---|
2660 |
|
---|
2661 | <glossdef>
|
---|
2662 | <para>Absolute path and process name of process to execute
|
---|
2663 | in the guest, e.g.
|
---|
2664 | <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
|
---|
2665 | </glossdef>
|
---|
2666 | </glossentry>
|
---|
2667 |
|
---|
2668 | <glossentry>
|
---|
2669 | <glossterm>--username <name></glossterm>
|
---|
2670 |
|
---|
2671 | <glossdef>
|
---|
2672 | <para>Name of the user the process should run under. This
|
---|
2673 | user must exist on the guest OS.</para>
|
---|
2674 | </glossdef>
|
---|
2675 | </glossentry>
|
---|
2676 |
|
---|
2677 | <glossentry>
|
---|
2678 | <glossterm>--passwordfile <file></glossterm>
|
---|
2679 |
|
---|
2680 | <glossdef>
|
---|
2681 | <para>Password of the user account specified to be read from
|
---|
2682 | the given file. If not given, an empty password is
|
---|
2683 | assumed.</para>
|
---|
2684 | </glossdef>
|
---|
2685 | </glossentry>
|
---|
2686 |
|
---|
2687 | <glossentry>
|
---|
2688 | <glossterm>--password <password></glossterm>
|
---|
2689 |
|
---|
2690 | <glossdef>
|
---|
2691 | <para>Password of the user account specified with
|
---|
2692 | <computeroutput>--username</computeroutput>. If not given,
|
---|
2693 | an empty password is assumed.</para>
|
---|
2694 | </glossdef>
|
---|
2695 | </glossentry>
|
---|
2696 |
|
---|
2697 | <glossentry>
|
---|
2698 | <glossterm>--dos2unix</glossterm>
|
---|
2699 |
|
---|
2700 | <glossdef>
|
---|
2701 | Converts output from DOS/Windows guests to UNIX-compatible
|
---|
2702 | line endings (CR + LF -> LF). Not implemented yet.
|
---|
2703 | </glossdef>
|
---|
2704 | </glossentry>
|
---|
2705 |
|
---|
2706 | <glossentry>
|
---|
2707 | <glossterm>--environment
|
---|
2708 | "<NAME>=<VALUE>"</glossterm>
|
---|
2709 |
|
---|
2710 | <glossdef>
|
---|
2711 | <para>One or more environment variables to be set or
|
---|
2712 | unset.</para>
|
---|
2713 |
|
---|
2714 | <para>By default, the new process in the guest will be
|
---|
2715 | created with the standard environment of the guest OS. This
|
---|
2716 | option allows for modifying that environment. To set/modify
|
---|
2717 | a variable, a pair of
|
---|
2718 | <computeroutput>NAME=VALUE</computeroutput> must be
|
---|
2719 | specified; to unset a certain variable, the name with no
|
---|
2720 | value must set, e.g.
|
---|
2721 | <computeroutput>NAME=</computeroutput>.</para>
|
---|
2722 |
|
---|
2723 | <para>Arguments containing spaces must be enclosed in
|
---|
2724 | quotation marks. More than one
|
---|
2725 | <computeroutput>--environment</computeroutput> at a time can
|
---|
2726 | be specified to keep the command line tidy.</para>
|
---|
2727 | </glossdef>
|
---|
2728 | </glossentry>
|
---|
2729 |
|
---|
2730 | <glossentry>
|
---|
2731 | <glossterm>--timeout <msec></glossterm>
|
---|
2732 |
|
---|
2733 | <glossdef>
|
---|
2734 | <para>Value (in milliseconds) that specifies the time how
|
---|
2735 | long the started process is allowed to run and how long
|
---|
2736 | VBoxManage waits for getting output from that process. If no
|
---|
2737 | timeout is specified, VBoxManage will wait forever until the
|
---|
2738 | started process ends or an error occured.</para>
|
---|
2739 | </glossdef>
|
---|
2740 | </glossentry>
|
---|
2741 |
|
---|
2742 | <glossentry>
|
---|
2743 | <glossterm>--unix2dos</glossterm>
|
---|
2744 |
|
---|
2745 | <glossdef>
|
---|
2746 | Converts output from a UNIX/Linux guests to DOS-/Windows-compatible
|
---|
2747 | line endings (LF -> CR + LF). Not implemented yet.
|
---|
2748 | </glossdef>
|
---|
2749 | </glossentry>
|
---|
2750 |
|
---|
2751 | <glossentry>
|
---|
2752 | <glossterm>--verbose</glossterm>
|
---|
2753 |
|
---|
2754 | <glossdef>
|
---|
2755 | <para>Tells VBoxManage to be more verbose.</para>
|
---|
2756 | </glossdef>
|
---|
2757 | </glossentry>
|
---|
2758 |
|
---|
2759 | <glossentry>
|
---|
2760 | <glossterm>--wait-exit</glossterm>
|
---|
2761 |
|
---|
2762 | <glossdef>
|
---|
2763 | <para>Waits until the process ends and outputs its
|
---|
2764 | exit code along with the exit reason/flags.</para>
|
---|
2765 | </glossdef>
|
---|
2766 | </glossentry>
|
---|
2767 |
|
---|
2768 | <glossentry>
|
---|
2769 | <glossterm>--wait-stdout</glossterm>
|
---|
2770 |
|
---|
2771 | <glossdef>
|
---|
2772 | <para>Waits until the process ends and outputs its
|
---|
2773 | exit code along with the exit reason/flags. While waiting
|
---|
2774 | VBoxManage retrieves the process output collected from stdout.</para>
|
---|
2775 | </glossdef>
|
---|
2776 | </glossentry>
|
---|
2777 |
|
---|
2778 | <glossentry>
|
---|
2779 | <glossterm>--wait-stderr</glossterm>
|
---|
2780 |
|
---|
2781 | <glossdef>
|
---|
2782 | <para>Waits until the process ends and outputs its
|
---|
2783 | exit code along with the exit reason/flags. While waiting
|
---|
2784 | VBoxManage retrieves the process output collected from stderr.</para>
|
---|
2785 | </glossdef>
|
---|
2786 | </glossentry>
|
---|
2787 |
|
---|
2788 | <glossentry>
|
---|
2789 | <glossterm>[-- [<argument1s>] ... [<argumentNs>]]</glossterm>
|
---|
2790 |
|
---|
2791 | <glossdef>
|
---|
2792 | <para>One or more arguments to pass to the process being
|
---|
2793 | executed.</para>
|
---|
2794 | <para>Arguments containing spaces must be enclosed in
|
---|
2795 | quotation marks.</para>
|
---|
2796 | </glossdef>
|
---|
2797 | </glossentry>
|
---|
2798 |
|
---|
2799 | </glosslist></para>
|
---|
2800 |
|
---|
2801 | <para><note>
|
---|
2802 | <para>On Windows there are certain limitations for graphical
|
---|
2803 | applications; please see <xref linkend="KnownIssues" /> for more
|
---|
2804 | information.</para>
|
---|
2805 | </note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls"
|
---|
2806 | --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "c:\\windows\\system32\\ipconfig.exe"
|
---|
2807 | --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
|
---|
2808 | the double backslashes in the second example are only required on
|
---|
2809 | Unix hosts.</para>
|
---|
2810 |
|
---|
2811 | <para><note>
|
---|
2812 | <para>For certain commands a user name of an existing user account on the guest
|
---|
2813 | must be specified; anonymous executions are not supported for security reasons. A
|
---|
2814 | user account password, however, is optional and depends on the guest's OS security
|
---|
2815 | policy or rules. If no password is specified for a given user name, an empty password
|
---|
2816 | will be used. On certain OSes like Windows the security policy may needs to be adjusted
|
---|
2817 | in order to allow user accounts with an empty password set. Also, global domain rules might
|
---|
2818 | apply and therefore cannot be changed.</para>
|
---|
2819 | </note></para>
|
---|
2820 |
|
---|
2821 | <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
|
---|
2822 | to serve up to 5 guest processes at a time. If a new guest process gets started
|
---|
2823 | which would exceed this limit, the oldest not running guest process will be discarded
|
---|
2824 | in order to be able to run that new process. Also, retrieving output from this
|
---|
2825 | old guest process will not be possible anymore then. If all 5 guest processes
|
---|
2826 | are still active and running, starting a new guest process will result in an
|
---|
2827 | appropriate error message.</para>
|
---|
2828 |
|
---|
2829 | <para>To raise or lower the guest process execution limit, either the guest
|
---|
2830 | property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
|
---|
2831 | or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
|
---|
2832 | needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
|
---|
2833 | guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
|
---|
2834 | </listitem>
|
---|
2835 |
|
---|
2836 | <listitem>
|
---|
2837 | <para><computeroutput>copyto</computeroutput>, which allows copying
|
---|
2838 | files from the host to the guest (only with installed Guest
|
---|
2839 | Additions 4.0 and later).</para>
|
---|
2840 |
|
---|
2841 | <screen>VBoxManage guestcontrol <vmname>|<uuid> copyto|cp
|
---|
2842 | <guest source> <host dest> --username <name>
|
---|
2843 | [--passwordfile <file> | --password <password>]
|
---|
2844 | [--dryrun] [--follow] [--recursive] [--verbose]</screen>
|
---|
2845 |
|
---|
2846 | <para>where the parameters mean: <glosslist>
|
---|
2847 | <glossentry>
|
---|
2848 | <glossterm>uuid|vmname</glossterm>
|
---|
2849 |
|
---|
2850 | <glossdef>
|
---|
2851 | <para>The VM UUID or VM name. Mandatory.</para>
|
---|
2852 | </glossdef>
|
---|
2853 | </glossentry>
|
---|
2854 |
|
---|
2855 | <glossentry>
|
---|
2856 | <glossterm>source on host</glossterm>
|
---|
2857 |
|
---|
2858 | <glossdef>
|
---|
2859 | <para>Absolute path of source file(s) on host to copy over
|
---|
2860 | to the guest, e.g.
|
---|
2861 | <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
|
---|
2862 | This also can be a wildcard expression, e.g.
|
---|
2863 | <computeroutput>C:\Windows\System32\*.dll</computeroutput></para>
|
---|
2864 | </glossdef>
|
---|
2865 | </glossentry>
|
---|
2866 |
|
---|
2867 | <glossentry>
|
---|
2868 | <glossterm>destination on guest</glossterm>
|
---|
2869 |
|
---|
2870 | <glossdef>
|
---|
2871 | <para>Absolute destination path on the guest, e.g.
|
---|
2872 | <computeroutput>C:\Temp</computeroutput></para>
|
---|
2873 | </glossdef>
|
---|
2874 | </glossentry>
|
---|
2875 |
|
---|
2876 | <glossentry>
|
---|
2877 | <glossterm>--username <name></glossterm>
|
---|
2878 |
|
---|
2879 | <glossdef>
|
---|
2880 | <para>Name of the user the copy process should run under.
|
---|
2881 | This user must exist on the guest OS.</para>
|
---|
2882 | </glossdef>
|
---|
2883 | </glossentry>
|
---|
2884 |
|
---|
2885 | <glossentry>
|
---|
2886 | <glossterm>--passwordfile <file></glossterm>
|
---|
2887 |
|
---|
2888 | <glossdef>
|
---|
2889 | <para>Password of the user account specified to be read from
|
---|
2890 | the given file. If not given, an empty password is
|
---|
2891 | assumed.</para>
|
---|
2892 | </glossdef>
|
---|
2893 | </glossentry>
|
---|
2894 |
|
---|
2895 | <glossentry>
|
---|
2896 | <glossterm>--password <password></glossterm>
|
---|
2897 |
|
---|
2898 | <glossdef>
|
---|
2899 | <para>Password of the user account specified with
|
---|
2900 | <computeroutput>--username</computeroutput>. If not given,
|
---|
2901 | an empty password is assumed.</para>
|
---|
2902 | </glossdef>
|
---|
2903 | </glossentry>
|
---|
2904 |
|
---|
2905 | <glossentry>
|
---|
2906 | <glossterm>--dryrun</glossterm>
|
---|
2907 |
|
---|
2908 | <glossdef>
|
---|
2909 | <para>Tells VBoxManage to only perform a dry run instead of
|
---|
2910 | really copying files to the guest.</para>
|
---|
2911 | </glossdef>
|
---|
2912 | </glossentry>
|
---|
2913 |
|
---|
2914 | <glossentry>
|
---|
2915 | <glossterm>--follow</glossterm>
|
---|
2916 |
|
---|
2917 | <glossdef>
|
---|
2918 | <para>Enables following symlinks on the host's
|
---|
2919 | source.</para>
|
---|
2920 | </glossdef>
|
---|
2921 | </glossentry>
|
---|
2922 |
|
---|
2923 | <glossentry>
|
---|
2924 | <glossterm>--recursive</glossterm>
|
---|
2925 |
|
---|
2926 | <glossdef>
|
---|
2927 | <para>Recursively copies files/directories of the specified
|
---|
2928 | source.</para>
|
---|
2929 | </glossdef>
|
---|
2930 | </glossentry>
|
---|
2931 |
|
---|
2932 | <glossentry>
|
---|
2933 | <glossterm>--verbose</glossterm>
|
---|
2934 |
|
---|
2935 | <glossdef>
|
---|
2936 | <para>Tells VBoxManage to be more verbose.</para>
|
---|
2937 | </glossdef>
|
---|
2938 | </glossentry>
|
---|
2939 |
|
---|
2940 | <glossentry>
|
---|
2941 | <glossterm>--flags <flags></glossterm>
|
---|
2942 |
|
---|
2943 | <glossdef>
|
---|
2944 | <para>Additional flags to set. This is not used at the
|
---|
2945 | moment.</para>
|
---|
2946 | </glossdef>
|
---|
2947 | </glossentry>
|
---|
2948 | </glosslist></para>
|
---|
2949 | </listitem>
|
---|
2950 |
|
---|
2951 | <listitem>
|
---|
2952 | <para><computeroutput>copyfrom</computeroutput>, which allows copying
|
---|
2953 | files from the guest to the host (only with installed Guest
|
---|
2954 | Additions 4.0 and later). It has the same parameters as
|
---|
2955 | <computeroutput>copyto</computeroutput> above.</para>
|
---|
2956 | </listitem>
|
---|
2957 |
|
---|
2958 | <listitem>
|
---|
2959 | <para><computeroutput>createdirectory</computeroutput>, which allows
|
---|
2960 | copying files from the host to the guest (only with installed Guest
|
---|
2961 | Additions 4.0 and later).</para>
|
---|
2962 |
|
---|
2963 | <screen>VBoxManage guestcontrol <vmname>|<uuid> createdir[ectory]|mkdir|md
|
---|
2964 | <guest directory>... --username <name>
|
---|
2965 | [--passwordfile <file> | --password <password>]
|
---|
2966 | [--parents] [--mode <mode>] [--verbose]</screen>
|
---|
2967 |
|
---|
2968 | <para>where the parameters mean: <glosslist>
|
---|
2969 | <glossentry>
|
---|
2970 | <glossterm>uuid|vmname</glossterm>
|
---|
2971 |
|
---|
2972 | <glossdef>
|
---|
2973 | <para>The VM UUID or VM name. Mandatory.</para>
|
---|
2974 | </glossdef>
|
---|
2975 | </glossentry>
|
---|
2976 |
|
---|
2977 | <glossentry>
|
---|
2978 | <glossterm>directory to create on guest</glossterm>
|
---|
2979 |
|
---|
2980 | <glossdef>
|
---|
2981 | <para>Absolute path of directory/directories to create on
|
---|
2982 | guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>.
|
---|
2983 | Parent directories need to exist (e.g. in this example
|
---|
2984 | <computeroutput>D:\Foo</computeroutput>) when switch
|
---|
2985 | <computeroutput>--parents</computeroutput> is omitted. The
|
---|
2986 | specified user must have appropriate rights to create the
|
---|
2987 | specified directory.</para>
|
---|
2988 | </glossdef>
|
---|
2989 | </glossentry>
|
---|
2990 |
|
---|
2991 | <glossentry>
|
---|
2992 | <glossterm>--username <name></glossterm>
|
---|
2993 |
|
---|
2994 | <glossdef>
|
---|
2995 | <para>Name of the user the copy process should run under.
|
---|
2996 | This user must exist on the guest OS.</para>
|
---|
2997 | </glossdef>
|
---|
2998 | </glossentry>
|
---|
2999 |
|
---|
3000 | <glossentry>
|
---|
3001 | <glossterm>--passwordfile <file></glossterm>
|
---|
3002 |
|
---|
3003 | <glossdef>
|
---|
3004 | <para>Password of the user account specified to be read from
|
---|
3005 | the given file. If not given, an empty password is
|
---|
3006 | assumed.</para>
|
---|
3007 | </glossdef>
|
---|
3008 | </glossentry>
|
---|
3009 |
|
---|
3010 | <glossentry>
|
---|
3011 | <glossterm>--password <password></glossterm>
|
---|
3012 |
|
---|
3013 | <glossdef>
|
---|
3014 | <para>Password of the user account specified with
|
---|
3015 | <computeroutput>--username</computeroutput>. If not given,
|
---|
3016 | an empty password is assumed.</para>
|
---|
3017 | </glossdef>
|
---|
3018 | </glossentry>
|
---|
3019 |
|
---|
3020 | <glossentry>
|
---|
3021 | <glossterm>--parents</glossterm>
|
---|
3022 |
|
---|
3023 | <glossdef>
|
---|
3024 | <para>Also creates not yet existing parent directories of
|
---|
3025 | the specified directory, e.g. if the directory
|
---|
3026 | <computeroutput>D:\Foo</computeroutput> of
|
---|
3027 | <computeroutput>D:\Foo\Bar</computeroutput> does not exist
|
---|
3028 | yet it will be created. Without specifying
|
---|
3029 | <computeroutput>--parent</computeroutput> the action would
|
---|
3030 | have failed.</para>
|
---|
3031 | </glossdef>
|
---|
3032 | </glossentry>
|
---|
3033 |
|
---|
3034 | <glossentry>
|
---|
3035 | <glossterm>--mode <mode></glossterm>
|
---|
3036 |
|
---|
3037 | <glossdef>
|
---|
3038 | <para>Sets the permission mode of the specified directory.
|
---|
3039 | Only octal modes (e.g.
|
---|
3040 | <computeroutput>0755</computeroutput>) are supported right
|
---|
3041 | now.</para>
|
---|
3042 | </glossdef>
|
---|
3043 | </glossentry>
|
---|
3044 |
|
---|
3045 | <glossentry>
|
---|
3046 | <glossterm>--verbose</glossterm>
|
---|
3047 |
|
---|
3048 | <glossdef>
|
---|
3049 | <para>Tells VBoxManage to be more verbose.</para>
|
---|
3050 | </glossdef>
|
---|
3051 | </glossentry>
|
---|
3052 | </glosslist></para>
|
---|
3053 | </listitem>
|
---|
3054 |
|
---|
3055 | <listitem>
|
---|
3056 | <para><computeroutput>stat</computeroutput>, which displays file
|
---|
3057 | or file system status on the guest.</para>
|
---|
3058 |
|
---|
3059 | <screen>VBoxManage guestcontrol <vmname>|<uuid> stat
|
---|
3060 | <file>... --username <name>
|
---|
3061 | [--passwordfile <file> | --password <password>]
|
---|
3062 | [--verbose]</screen>
|
---|
3063 |
|
---|
3064 | <para>where the parameters mean: <glosslist>
|
---|
3065 | <glossentry>
|
---|
3066 | <glossterm>uuid|vmname</glossterm>
|
---|
3067 |
|
---|
3068 | <glossdef>
|
---|
3069 | <para>The VM UUID or VM name. Mandatory.</para>
|
---|
3070 | </glossdef>
|
---|
3071 | </glossentry>
|
---|
3072 |
|
---|
3073 | <glossentry>
|
---|
3074 | <glossterm>file element(s) to check on guest</glossterm>
|
---|
3075 |
|
---|
3076 | <glossdef>
|
---|
3077 | <para>Absolute path of directory/directories to check on
|
---|
3078 | guest, e.g. <computeroutput>/home/foo/a.out</computeroutput>.
|
---|
3079 | The specified user must have appropriate rights to access
|
---|
3080 | the given file element(s).</para>
|
---|
3081 | </glossdef>
|
---|
3082 | </glossentry>
|
---|
3083 |
|
---|
3084 | <glossentry>
|
---|
3085 | <glossterm>--username <name></glossterm>
|
---|
3086 |
|
---|
3087 | <glossdef>
|
---|
3088 | <para>Name of the user the copy process should run under.
|
---|
3089 | This user must exist on the guest OS.</para>
|
---|
3090 | </glossdef>
|
---|
3091 | </glossentry>
|
---|
3092 |
|
---|
3093 | <glossentry>
|
---|
3094 | <glossterm>--passwordfile <file></glossterm>
|
---|
3095 |
|
---|
3096 | <glossdef>
|
---|
3097 | <para>Password of the user account specified to be read from
|
---|
3098 | the given file. If not given, an empty password is
|
---|
3099 | assumed.</para>
|
---|
3100 | </glossdef>
|
---|
3101 | </glossentry>
|
---|
3102 |
|
---|
3103 | <glossentry>
|
---|
3104 | <glossterm>--password <password></glossterm>
|
---|
3105 |
|
---|
3106 | <glossdef>
|
---|
3107 | <para>Password of the user account specified with
|
---|
3108 | <computeroutput>--username</computeroutput>. If not given,
|
---|
3109 | an empty password is assumed.</para>
|
---|
3110 | </glossdef>
|
---|
3111 | </glossentry>
|
---|
3112 |
|
---|
3113 | <glossentry>
|
---|
3114 | <glossterm>--verbose</glossterm>
|
---|
3115 |
|
---|
3116 | <glossdef>
|
---|
3117 | <para>Tells VBoxManage to be more verbose.</para>
|
---|
3118 | </glossdef>
|
---|
3119 | </glossentry>
|
---|
3120 | </glosslist></para>
|
---|
3121 | </listitem>
|
---|
3122 |
|
---|
3123 | <listitem>
|
---|
3124 | <para><computeroutput>updateadditions</computeroutput>, which allows
|
---|
3125 | for updating an already installed Guest Additions version on the
|
---|
3126 | guest (only already installed Guest Additions 4.0 and later).</para>
|
---|
3127 |
|
---|
3128 | <screen>VBoxManage guestcontrol <vmname>|<uuid> updateadditions
|
---|
3129 | [--source "<guest additions .ISO file to use>"] [--verbose]
|
---|
3130 | [--wait-start]</screen>
|
---|
3131 |
|
---|
3132 | <para>where the parameters mean: <glosslist>
|
---|
3133 | <glossentry>
|
---|
3134 | <glossterm>uuid|vmname</glossterm>
|
---|
3135 |
|
---|
3136 | <glossdef>
|
---|
3137 | <para>The VM UUID or VM name. Mandatory.</para>
|
---|
3138 | </glossdef>
|
---|
3139 | </glossentry>
|
---|
3140 |
|
---|
3141 | <glossentry>
|
---|
3142 | <glossterm>--source "<guest additions .ISO file to
|
---|
3143 | use>"</glossterm>
|
---|
3144 |
|
---|
3145 | <glossdef>
|
---|
3146 | <para>Full path to an alternative VirtualBox Guest Additions
|
---|
3147 | .ISO file to use for the Guest Additions update.</para>
|
---|
3148 | </glossdef>
|
---|
3149 | </glossentry>
|
---|
3150 |
|
---|
3151 | <glossentry>
|
---|
3152 | <glossterm>--verbose</glossterm>
|
---|
3153 |
|
---|
3154 | <glossdef>
|
---|
3155 | <para>Tells VBoxManage to be more verbose.</para>
|
---|
3156 | </glossdef>
|
---|
3157 | </glossentry>
|
---|
3158 |
|
---|
3159 | <glossentry>
|
---|
3160 | <glossterm>--wait-start</glossterm>
|
---|
3161 | <glossdef>
|
---|
3162 | <para>Starts the regular updating process and waits until the
|
---|
3163 | actual Guest Additions update inside the guest was started.
|
---|
3164 | This can be necessary due to needed interaction with the
|
---|
3165 | guest OS during the installation phase.</para>
|
---|
3166 | <para>When omitting this flag VBoxManage will wait for the
|
---|
3167 | whole Guest Additions update to complete.</para>
|
---|
3168 | </glossdef>
|
---|
3169 | </glossentry>
|
---|
3170 | </glosslist></para>
|
---|
3171 | </listitem>
|
---|
3172 | </itemizedlist></para>
|
---|
3173 | </sect1>
|
---|
3174 |
|
---|
3175 | <sect1 id="vboxmanage-debugvm">
|
---|
3176 | <title>VBoxManage debugvm</title>
|
---|
3177 |
|
---|
3178 | <para>The "debugvm" commands are for experts who want to tinker with the
|
---|
3179 | exact details of virtual machine execution. Like the VM debugger described
|
---|
3180 | in <xref linkend="ts_debugger" />, these commands are only useful if you are
|
---|
3181 | very familiar with the details of the PC architecture and how to debug
|
---|
3182 | software.</para>
|
---|
3183 |
|
---|
3184 | <para>The subcommands of "debugvm" all operate on a running virtual
|
---|
3185 | machine. The following are available:<itemizedlist>
|
---|
3186 | <listitem>
|
---|
3187 | <para>With <computeroutput>dumpguestcore --filename
|
---|
3188 | <name></computeroutput>, you can create a system dump of the
|
---|
3189 | running VM, which will be written into the given file. This file
|
---|
3190 | will have the standard ELF core format (with custom sections); see
|
---|
3191 | <xref linkend="ts_guest-core-format" />.</para>
|
---|
3192 |
|
---|
3193 | <para>This corresponds to the
|
---|
3194 | <computeroutput>writecore</computeroutput> command in the debugger.
|
---|
3195 | </para>
|
---|
3196 | </listitem>
|
---|
3197 |
|
---|
3198 | <listitem>
|
---|
3199 | <para>The <computeroutput>info</computeroutput> command is used to
|
---|
3200 | display info items relating to the VMM, device emulations and
|
---|
3201 | associated drivers. This command takes one or two arguments: the
|
---|
3202 | name of the info item, optionally followed by a string containing
|
---|
3203 | arguments specific to the info item.
|
---|
3204 | The <computeroutput>help</computeroutput> info item provides a
|
---|
3205 | listning of the available items and hints about any optional
|
---|
3206 | arguments.</para>
|
---|
3207 |
|
---|
3208 | <para>This corresponds to the <computeroutput>info</computeroutput>
|
---|
3209 | command in the debugger.</para>
|
---|
3210 | </listitem>
|
---|
3211 |
|
---|
3212 | <listitem>
|
---|
3213 | <para>The <computeroutput>injectnmi</computeroutput> command causes
|
---|
3214 | a non-maskable interrupt (NMI) in the guest, which might be useful
|
---|
3215 | for certain debugging scenarios. What happens exactly is dependent
|
---|
3216 | on the guest operating system, but an NMI can crash the whole guest
|
---|
3217 | operating system. Do not use unless you know what you're
|
---|
3218 | doing.</para>
|
---|
3219 | </listitem>
|
---|
3220 |
|
---|
3221 | <listitem>
|
---|
3222 | <para>The <computeroutput>osdetect</computeroutput> command makes the
|
---|
3223 | VMM's debugger facility (re-)detection the guest operation
|
---|
3224 | system.</para>
|
---|
3225 |
|
---|
3226 | <para>This corresponds to the <computeroutput>detect</computeroutput>
|
---|
3227 | command in the debugger.</para>
|
---|
3228 | </listitem>
|
---|
3229 |
|
---|
3230 | <listitem>
|
---|
3231 | <para>The <computeroutput>osinfo</computeroutput> command is used to
|
---|
3232 | display info about the operating system (OS) detected by the VMM's
|
---|
3233 | debugger facility.</para>
|
---|
3234 | </listitem>
|
---|
3235 |
|
---|
3236 | <listitem>
|
---|
3237 | <para>The <computeroutput>getregisters</computeroutput> command is
|
---|
3238 | used to display CPU and device registers. The command takes a list
|
---|
3239 | of registers, each having one of the following forms:
|
---|
3240 | <itemizedlist>
|
---|
3241 | <listitem><computeroutput>register-set.register-name.sub-field</computeroutput></listitem>
|
---|
3242 | <listitem><computeroutput>register-set.register-name</computeroutput></listitem>
|
---|
3243 | <listitem><computeroutput>cpu-register-name.sub-field</computeroutput></listitem>
|
---|
3244 | <listitem><computeroutput>cpu-register-name</computeroutput></listitem>
|
---|
3245 | <listitem><computeroutput>all</computeroutput></listitem>
|
---|
3246 | </itemizedlist>
|
---|
3247 | The <computeroutput>all</computeroutput> form will cause all
|
---|
3248 | registers to be shown (no sub-fields). The registers names are
|
---|
3249 | case-insensitive. When requesting a CPU register the register set
|
---|
3250 | can be omitted, it will be selected using the value of the
|
---|
3251 | <computeroutput>--cpu</computeroutput> option (defaulting to 0).
|
---|
3252 | </para>
|
---|
3253 | </listitem>
|
---|
3254 |
|
---|
3255 | <listitem>
|
---|
3256 | <para>The <computeroutput>setregisters</computeroutput> command is
|
---|
3257 | used to change CPU and device registers. The command takes a list
|
---|
3258 | of register assignments, each having one of the following forms:
|
---|
3259 | <itemizedlist>
|
---|
3260 | <listitem><computeroutput>register-set.register-name.sub-field=value</computeroutput></listitem>
|
---|
3261 | <listitem><computeroutput>register-set.register-name=value</computeroutput></listitem>
|
---|
3262 | <listitem><computeroutput>cpu-register-name.sub-field=value</computeroutput></listitem>
|
---|
3263 | <listitem><computeroutput>cpu-register-name=value</computeroutput></listitem>
|
---|
3264 | </itemizedlist>
|
---|
3265 | The value format should be in the same style as what
|
---|
3266 | <computeroutput>getregisters</computeroutput> displays, with the
|
---|
3267 | exception that both octal and decimal can be used instead of
|
---|
3268 | hexadecimal. The register naming and the default CPU register set
|
---|
3269 | are handled the same way as with the
|
---|
3270 | <computeroutput>getregisters</computeroutput> command.</para>
|
---|
3271 | </listitem>
|
---|
3272 |
|
---|
3273 | <listitem>
|
---|
3274 | <para>The <computeroutput>statistics</computeroutput> command can be
|
---|
3275 | used to display VMM statistics on the command line. The
|
---|
3276 | <computeroutput>--reset</computeroutput> option will reset
|
---|
3277 | statistics. The affected statistics can be filtered with the
|
---|
3278 | <computeroutput>--pattern</computeroutput> option, which accepts
|
---|
3279 | DOS/NT-style wildcards (<computeroutput>?</computeroutput> and
|
---|
3280 | <computeroutput>*</computeroutput>).</para>
|
---|
3281 | </listitem>
|
---|
3282 | </itemizedlist></para>
|
---|
3283 | </sect1>
|
---|
3284 |
|
---|
3285 | <sect1>
|
---|
3286 | <title id="metrics">VBoxManage metrics</title>
|
---|
3287 |
|
---|
3288 | <para>This command supports monitoring the usage of system resources.
|
---|
3289 | Resources are represented by various metrics associated with the host
|
---|
3290 | system or a particular VM. For example, the host system has a
|
---|
3291 | <computeroutput>CPU/Load/User</computeroutput> metric that shows the
|
---|
3292 | percentage of time CPUs spend executing in user mode over a specific
|
---|
3293 | sampling period.</para>
|
---|
3294 |
|
---|
3295 | <para>Metric data is collected and retained internally; it may be
|
---|
3296 | retrieved at any time with the <computeroutput>VBoxManage metrics
|
---|
3297 | query</computeroutput> subcommand. The data is available as long as the
|
---|
3298 | background <computeroutput>VBoxSVC</computeroutput> process is alive. That
|
---|
3299 | process terminates shortly after all VMs and frontends have been
|
---|
3300 | closed.</para>
|
---|
3301 |
|
---|
3302 | <para>By default no metrics are collected at all. Metrics collection does
|
---|
3303 | not start until <computeroutput>VBoxManage metrics setup</computeroutput>
|
---|
3304 | is invoked with a proper sampling interval and the number of metrics to be
|
---|
3305 | retained. The interval is measured in seconds. For example, to enable
|
---|
3306 | collecting the host processor and memory usage metrics every second and
|
---|
3307 | keeping the 5 most current samples, the following command can be
|
---|
3308 | used:</para>
|
---|
3309 |
|
---|
3310 | <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
|
---|
3311 |
|
---|
3312 | <para>Metric collection can only be enabled for started VMs. Collected
|
---|
3313 | data and collection settings for a particular VM will disappear as soon as
|
---|
3314 | it shuts down. Use <computeroutput>VBoxManage metrics list
|
---|
3315 | </computeroutput> subcommand to see which metrics are currently available.
|
---|
3316 | You can also use <computeroutput>--list</computeroutput> option with any
|
---|
3317 | subcommand that modifies metric settings to find out which metrics were
|
---|
3318 | affected.</para>
|
---|
3319 |
|
---|
3320 | <para>Note that the <computeroutput>VBoxManage metrics
|
---|
3321 | setup</computeroutput> subcommand discards all samples that may have been
|
---|
3322 | previously collected for the specified set of objects and metrics.</para>
|
---|
3323 |
|
---|
3324 | <para>To enable or disable metrics collection without discarding the data
|
---|
3325 | <computeroutput>VBoxManage metrics enable</computeroutput> and
|
---|
3326 | <computeroutput>VBoxManage metrics disable</computeroutput> subcommands
|
---|
3327 | can be used. Note that these subcommands expect metrics, not submetrics,
|
---|
3328 | like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
|
---|
3329 | other words enabling <code>CPU/Load/User</code> while disabling
|
---|
3330 | <code>CPU/Load/Kernel</code> is not supported.</para>
|
---|
3331 |
|
---|
3332 | <para>The host and VMs have different sets of associated metrics.
|
---|
3333 | Available metrics can be listed with <computeroutput>VBoxManage metrics
|
---|
3334 | list</computeroutput> subcommand.</para>
|
---|
3335 |
|
---|
3336 | <para>A complete metric name may include an aggregate function. The name
|
---|
3337 | has the following form:
|
---|
3338 | <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
|
---|
3339 | For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
|
---|
3340 | for the minimum amount of available memory over all retained data if
|
---|
3341 | applied to the host object.</para>
|
---|
3342 |
|
---|
3343 | <para>Subcommands may apply to all objects and metrics or can be limited
|
---|
3344 | to one object or/and a list of metrics. If no objects or metrics are given
|
---|
3345 | in the parameters, the subcommands will apply to all available metrics of
|
---|
3346 | all objects. You may use an asterisk
|
---|
3347 | ("<computeroutput>*</computeroutput>") to explicitly specify that the
|
---|
3348 | command should be applied to all objects or metrics. Use "host" as the
|
---|
3349 | object name to limit the scope of the command to host-related metrics. To
|
---|
3350 | limit the scope to a subset of metrics, use a metric list with names
|
---|
3351 | separated by commas.</para>
|
---|
3352 |
|
---|
3353 | <para>For example, to query metric data on the CPU time spent in user and
|
---|
3354 | kernel modes by the virtual machine named "test", you can use the
|
---|
3355 | following command:</para>
|
---|
3356 |
|
---|
3357 | <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
|
---|
3358 |
|
---|
3359 | <para>The following list summarizes the available subcommands:</para>
|
---|
3360 |
|
---|
3361 | <glosslist>
|
---|
3362 | <glossentry>
|
---|
3363 | <glossterm>list</glossterm>
|
---|
3364 |
|
---|
3365 | <glossdef>
|
---|
3366 | <para>This subcommand shows the parameters of the currently existing
|
---|
3367 | metrics. Note that VM-specific metrics are only available when a
|
---|
3368 | particular VM is running.</para>
|
---|
3369 | </glossdef>
|
---|
3370 | </glossentry>
|
---|
3371 |
|
---|
3372 | <glossentry>
|
---|
3373 | <glossterm>setup</glossterm>
|
---|
3374 |
|
---|
3375 | <glossdef>
|
---|
3376 | <para>This subcommand sets the interval between taking two samples
|
---|
3377 | of metric data and the number of samples retained internally. The
|
---|
3378 | retained data is available for displaying with the
|
---|
3379 | <code>query</code> subcommand. The <computeroutput>--list
|
---|
3380 | </computeroutput> option shows which metrics have been modified as
|
---|
3381 | the result of the command execution.</para>
|
---|
3382 | </glossdef>
|
---|
3383 | </glossentry>
|
---|
3384 |
|
---|
3385 | <glossentry>
|
---|
3386 | <glossterm>enable</glossterm>
|
---|
3387 |
|
---|
3388 | <glossdef>
|
---|
3389 | <para>This subcommand "resumes" data collection after it has been
|
---|
3390 | stopped with <code>disable</code> subcommand. Note that specifying
|
---|
3391 | submetrics as parameters will not enable underlying metrics. Use
|
---|
3392 | <computeroutput>--list</computeroutput> to find out if the command
|
---|
3393 | did what was expected.</para>
|
---|
3394 | </glossdef>
|
---|
3395 | </glossentry>
|
---|
3396 |
|
---|
3397 | <glossentry>
|
---|
3398 | <glossterm>disable</glossterm>
|
---|
3399 |
|
---|
3400 | <glossdef>
|
---|
3401 | <para>This subcommand "suspends" data collection without affecting
|
---|
3402 | collection parameters or collected data. Note that specifying
|
---|
3403 | submetrics as parameters will not disable underlying metrics. Use
|
---|
3404 | <computeroutput>--list</computeroutput> to find out if the command
|
---|
3405 | did what was expected.</para>
|
---|
3406 | </glossdef>
|
---|
3407 | </glossentry>
|
---|
3408 |
|
---|
3409 | <glossentry>
|
---|
3410 | <glossterm>query</glossterm>
|
---|
3411 |
|
---|
3412 | <glossdef>
|
---|
3413 | <para>This subcommand retrieves and displays the currently retained
|
---|
3414 | metric data.<note>
|
---|
3415 | <para>The <code>query</code> subcommand does not remove or
|
---|
3416 | "flush" retained data. If you query often enough you will see
|
---|
3417 | how old samples are gradually being "phased out" by new
|
---|
3418 | samples.</para>
|
---|
3419 | </note></para>
|
---|
3420 | </glossdef>
|
---|
3421 | </glossentry>
|
---|
3422 |
|
---|
3423 | <glossentry>
|
---|
3424 | <glossterm>collect</glossterm>
|
---|
3425 |
|
---|
3426 | <glossdef>
|
---|
3427 | <para>This subcommand sets the interval between taking two samples
|
---|
3428 | of metric data and the number of samples retained internally. The
|
---|
3429 | collected data is displayed periodically until Ctrl-C is pressed
|
---|
3430 | unless the <computeroutput>--detach</computeroutput> option is
|
---|
3431 | specified. With the <computeroutput>--detach</computeroutput>
|
---|
3432 | option, this subcommand operates the same way as <code>setup</code>
|
---|
3433 | does. The <computeroutput>--list</computeroutput> option shows which
|
---|
3434 | metrics match the specified filter.</para>
|
---|
3435 | </glossdef>
|
---|
3436 | </glossentry>
|
---|
3437 | </glosslist>
|
---|
3438 | </sect1>
|
---|
3439 |
|
---|
3440 | <sect1>
|
---|
3441 | <title>VBoxManage hostonlyif</title>
|
---|
3442 |
|
---|
3443 | <para>With "hostonlyif" you can change the IP configuration of a host-only
|
---|
3444 | network interface. For a description of host-only networking, please
|
---|
3445 | refer to <xref linkend="network_hostonly" />. Each host-only interface is
|
---|
3446 | identified by a name and can either use the internal DHCP server or a
|
---|
3447 | manual IP configuration (both IP4 and IP6).</para>
|
---|
3448 | </sect1>
|
---|
3449 |
|
---|
3450 | <sect1 id="vboxmanage-dhcpserver">
|
---|
3451 | <title>VBoxManage dhcpserver</title>
|
---|
3452 |
|
---|
3453 | <para>The "dhcpserver" commands allow you to control the DHCP server that
|
---|
3454 | is built into VirtualBox. You may find this useful when using internal or
|
---|
3455 | host-only networking. (Theoretically, you can enable it for a bridged
|
---|
3456 | network as well, but that will likely cause conflicts with other DHCP
|
---|
3457 | servers in your physical network.)</para>
|
---|
3458 |
|
---|
3459 | <para>Use the following command line options:<itemizedlist>
|
---|
3460 | <listitem>
|
---|
3461 | <para>If you use internal networking for a virtual network adapter
|
---|
3462 | of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
|
---|
3463 | --netname <network_name></computeroutput>, where
|
---|
3464 | <computeroutput><network_name></computeroutput> is the same
|
---|
3465 | network name you used with <computeroutput>VBoxManage modifyvm
|
---|
3466 | <vmname> --intnet<X>
|
---|
3467 | <network_name></computeroutput>.</para>
|
---|
3468 | </listitem>
|
---|
3469 |
|
---|
3470 | <listitem>
|
---|
3471 | <para>If you use host-only networking for a virtual network adapter
|
---|
3472 | of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
|
---|
3473 | --ifname <hostonly_if_name></computeroutput> instead, where
|
---|
3474 | <computeroutput><hostonly_if_name></computeroutput> is the
|
---|
3475 | same host-only interface name you used with
|
---|
3476 | <computeroutput>VBoxManage modifyvm <vmname>
|
---|
3477 | --hostonlyadapter<X>
|
---|
3478 | <hostonly_if_name></computeroutput>.</para>
|
---|
3479 |
|
---|
3480 | <para>Alternatively, you can also use the --netname option as with
|
---|
3481 | internal networks if you know the host-only network's name; you can
|
---|
3482 | see the names with <computeroutput>VBoxManage list
|
---|
3483 | hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
|
---|
3484 | above).</para>
|
---|
3485 | </listitem>
|
---|
3486 | </itemizedlist></para>
|
---|
3487 |
|
---|
3488 | <para>The following additional parameters are required when first adding a
|
---|
3489 | DHCP server:<itemizedlist>
|
---|
3490 | <listitem>
|
---|
3491 | <para>With <computeroutput>--ip</computeroutput>, specify the IP
|
---|
3492 | address of the DHCP server itself.</para>
|
---|
3493 | </listitem>
|
---|
3494 |
|
---|
3495 | <listitem>
|
---|
3496 | <para>With <computeroutput>--netmask</computeroutput>, specify the
|
---|
3497 | netmask of the network.</para>
|
---|
3498 | </listitem>
|
---|
3499 |
|
---|
3500 | <listitem>
|
---|
3501 | <para>With <computeroutput>--lowerip</computeroutput> and
|
---|
3502 | <computeroutput>--upperip</computeroutput>, you can specify the
|
---|
3503 | lowest and highest IP address, respectively, that the DHCP server
|
---|
3504 | will hand out to clients.</para>
|
---|
3505 | </listitem>
|
---|
3506 | </itemizedlist></para>
|
---|
3507 |
|
---|
3508 | <para>Finally, you must specify <computeroutput>--enable</computeroutput>
|
---|
3509 | or the DHCP server will be created in the disabled state, doing
|
---|
3510 | nothing.</para>
|
---|
3511 |
|
---|
3512 | <para>After this, VirtualBox will automatically start the DHCP server for
|
---|
3513 | given internal or host-only network as soon as the first virtual machine
|
---|
3514 | which uses that network is started.</para>
|
---|
3515 |
|
---|
3516 | <para>Reversely, use <computeroutput>VBoxManage dhcpserver
|
---|
3517 | remove</computeroutput> with the given <computeroutput>--netname
|
---|
3518 | <network_name></computeroutput> or <computeroutput>--ifname
|
---|
3519 | <hostonly_if_name></computeroutput> to remove the DHCP server again
|
---|
3520 | for the given internal or host-only network.</para>
|
---|
3521 |
|
---|
3522 | <para>To modify the settings of a DHCP server created earlier with
|
---|
3523 | <computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
|
---|
3524 | <computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
|
---|
3525 | network or host-only interface name.</para>
|
---|
3526 | </sect1>
|
---|
3527 |
|
---|
3528 | <sect1 id="vboxmanage-extpack">
|
---|
3529 | <title>VBoxManage extpack</title>
|
---|
3530 |
|
---|
3531 | <para>The "extpack" command allows you to add or remove VirtualBox
|
---|
3532 | extension packs, as described in <xref
|
---|
3533 | linkend="intro-installing" />.<itemizedlist>
|
---|
3534 | <listitem>
|
---|
3535 | <para>To add a new extension pack, use <computeroutput>VBoxManage
|
---|
3536 | extpack install <tarball></computeroutput>. This command
|
---|
3537 | will fail if an older version of the same extension pack is already
|
---|
3538 | installed. The optional <computeroutput>--replace</computeroutput>
|
---|
3539 | parameter can be used to uninstall the old package before the new
|
---|
3540 | package is installed.</para>
|
---|
3541 | </listitem>
|
---|
3542 |
|
---|
3543 | <listitem>
|
---|
3544 | <para>To remove a previously installed extension pack, use
|
---|
3545 | <computeroutput>VBoxManage extpack uninstall
|
---|
3546 | <name></computeroutput>. You can use
|
---|
3547 | <computeroutput>VBoxManage list extpacks</computeroutput> to show
|
---|
3548 | the names of the extension packs which are currently installed;
|
---|
3549 | please see <xref linkend="vboxmanage-list" /> also. The optional
|
---|
3550 | <computeroutput>--force</computeroutput> parameter can be used to
|
---|
3551 | override the refusal of an extension pack to be uninstalled.</para>
|
---|
3552 | </listitem>
|
---|
3553 |
|
---|
3554 | <listitem>
|
---|
3555 | <para>The <computeroutput>VBoxManage extpack
|
---|
3556 | cleanup</computeroutput> command can be used to remove temporary
|
---|
3557 | files and directories that may have been left behind if a previous
|
---|
3558 | install or uninstall command failed.</para>
|
---|
3559 | </listitem>
|
---|
3560 | </itemizedlist></para>
|
---|
3561 | <para>The following commands show examples how to list extension packs and
|
---|
3562 | remove one:<screen>
|
---|
3563 | $ VBoxManage list extpacks
|
---|
3564 | Extension Packs: 1
|
---|
3565 | Pack no. 0: Oracle VM VirtualBox Extension Pack
|
---|
3566 | Version: 4.1.12
|
---|
3567 | Revision: 77218
|
---|
3568 | Edition:
|
---|
3569 | Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support.
|
---|
3570 | VRDE Module: VBoxVRDP
|
---|
3571 | Usable: true
|
---|
3572 | Why unusable:
|
---|
3573 | $ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack"
|
---|
3574 | 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
|
---|
3575 | Successfully uninstalled "Oracle VM VirtualBox Extension Pack".</screen></para>
|
---|
3576 | </sect1>
|
---|
3577 | </chapter>
|
---|