1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
manpage, user manual, usage: VBoxManage
-->
<!--
Copyright (C) 2006-2023 Oracle and/or its affiliates.
This file is part of VirtualBox base platform packages, as
available from https://www.virtualbox.org.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, in version 3 of the
License.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see <https://www.gnu.org/licenses>.
SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<refentry id="vboxmanage-common" lang="en">
<refentryinfo>
<pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate>
<title>VBoxManage</title>
</refentryinfo>
<refmeta>
<refentrytitle>VBoxManage</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>VBoxManage</refname>
<refpurpose>&product-name; command-line interface</refpurpose>
<refclass>&product-name;</refclass>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis id="synopsis-vboxmanage-common">
<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
<command>VBoxManage</command>
<group>
<arg choice="plain">-V</arg>
<arg choice="plain">--version</arg>
</group>
<arg>--dump-build-type</arg>
<group>
<arg choice="plain">-q</arg>
<arg choice="plain">--nologo</arg>
</group>
<arg>--settingspw=<replaceable>password</replaceable></arg>
<arg>--settingspwfile=<replaceable>pw-file</replaceable></arg>
<arg>@<replaceable>response-file</replaceable></arg>
<arg><arg>help</arg> <replaceable>subcommand</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>VBoxManage</command> command is the command-line
interface (CLI) for the &product-name; software. The CLI supports
all the features that are available with the &product-name;
graphical user interface (GUI). In addition, you can use the
<command>VBoxManage</command> command to manage the features of
the virtualization engine that cannot be managed by the GUI.
</para>
<para>
Each time you invoke the <command>VBoxManage</command> command,
only one command is executed. Note that some
<command>VBoxManage</command> subcommands invoke several
subcommands.
</para>
<para>
Run the <command>VBoxManage</command> command from the command
line of the host operating system (OS) to control &product-name;
software.
</para>
<para>
The <command>VBoxManage</command> command is stored in the
following locations on the host system:
</para>
<itemizedlist>
<listitem><para>
<emphasis role="bold">Linux:</emphasis>
<filename>/usr/bin/VBoxManage</filename>
</para></listitem>
<listitem><para>
<emphasis role="bold">Mac OS X:</emphasis>
<filename>/Applications/VirtualBox.app/Contents/MacOS/VBoxManage</filename>
</para></listitem>
<listitem><para>
<emphasis role="bold">Oracle Solaris:</emphasis>
<filename>/opt/VirtualBox/bin/VBoxManage</filename>
</para></listitem>
<listitem><para>
<emphasis role="bold">Windows:</emphasis>
<filename>C:\Program
Files\Oracle\VirtualBox\VBoxManage.exe</filename>
</para></listitem>
</itemizedlist>
<para>
In addition to managing virtual machines (VMs) with this CLI or
the GUI, you can use the <command>VBoxHeadless</command> CLI to
manage VMs remotely.
</para>
<para>
The <command>VBoxManage</command> command performs particular
tasks by using subcommands, such as <command>list</command>,
<command>createvm</command>, and <command>startvm</command>. See
the associated information for each <command>VBoxManage</command>
subcommand.
</para>
<para>
If required, specify the VM by its name or by its Universally
Unique Identifier (UUID).
</para>
<para>
Use the <command>VBoxManage list vms</command> command to obtain
information about all currently registered VMs, including the VM
names and associated UUIDs.
</para>
<para>
Note that you must enclose the entire VM name in double quotes if
it contains spaces.
</para>
<refsect2 id="vboxmanage-common-options">
<title>General Options</title>
<variablelist>
<varlistentry>
<term><option>--nologo</option></term>
<listitem><para>
Suppresses the output of the logo information, which is
useful for scripts.
</para><para>
The short version of this option is <option>-q</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--settingspw=[<replaceable>password</replaceable>]</option></term>
<listitem><para>
Specifies the settings password. You can optionally
specify the password as an argument to this option. If you
do not specify the password in this way, the
<command>VBoxManage</command> command prompts you for the
password.
</para><para>
The settings password is a security feature that encrypts
stored settings, which are stored as plain text by
default.
</para><para>
You cannot unencrypt encrypted settings. So, if the
settings are encrypted, you must continue to specify the
<option>--settingspw</option> or
<option>--settingspwfile</option> option.
</para><para>
Only the iSCSI secret is encrypted at this time.
</para><remark>
This design does not conform to Oracle's security
guidelines. You should not be able to specify a password
on the command line because the password can be seen in a
process listing.
</remark></listitem>
</varlistentry>
<varlistentry>
<term><option>--settingspwfile=<replaceable>pw-filename</replaceable></option></term>
<listitem><para>
Specifies the file that contains the settings password.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Shows version information about the
<command>VBoxManage</command> command.
</para><para>
The short version of this option is <option>-V</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>@<replaceable>response-file</replaceable></term>
<listitem><para>
Loads arguments from the specified Bourne shell response
file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>subcommand</replaceable></term>
<listitem><para>
Specifies one of the <command>VBoxManage</command>
subcommands, such as <command>controlvm</command>,
<command>createvm</command>, <command>list</command>,
<command>modifyvm</command>,
<command>showvminfo</command>, <command>startvm</command>,
<command>storageattach</command>, and
<command>storagectl</command>.
</para><para>
Each subcommand is described in its own command topic,
some of which are shown in See Also sections.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<remark role="help-scope" condition="GLOBAL"/>
<para>
The following command creates a virtual machine called
<literal>Win8</literal> and registers it with &product-name; by
using the <option>--register</option> option.
</para>
<screen>$ VBoxManage createvm --name "Win8" --register
Virtual machine 'Win8' is created.
UUID: <replaceable>UUID-string</replaceable>
Settings file: '/home/<replaceable>username</replaceable>/VirtualBox VMs/Win8/Win8.vbox'</screen>
<para>
The command output shows that the <literal>Win8</literal> VM is
assigned a UUID and an XML machine settings file.
</para>
<para>
You can use the <command>VBoxManage showvminfo</command> command
to view the configuration information of a VM.
</para>
<para>
The following example uses the <command>VBoxManage
modifyvm</command> command to change the amount of memory for the
<literal>Windows XP</literal> VM to be 1024 megabytes:
</para>
<screen>$ VBoxManage modifyvm "Windows XP" --memory 1024</screen>
<para>
Note that you can use the <command>VBoxManage modifyvm</command>
command even when the VM is powered off.
</para>
<para>
You can use the <command>VBoxManage storagectl</command> command
or the <command>VBoxManage storageattach</command> command to
modify the storage configuration for a VM. For example, to create
a SATA storage controller called <literal>sata01</literal> and add
it to the <literal>ol7</literal> VM:
</para>
<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata</screen>
<para>
Use the <command>VBoxManage startvm</command> command to start a
VM that is currently powered off. For example, to start the
<literal>win7</literal> VM:
</para>
<screen>$ VBoxManage startvm win7</screen>
<para>
Use the <command>VBoxManage controlvm</command> command to pause
or save a VM that is currently running. You can also use this
command to modify settings for the VM. For example, to enable
audio input for the <literal>ol6u9</literal> VM.
</para>
<screen>$ VBoxManage controlvm ol6u9 audioin on</screen>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="vboxmanage-controlvm" />,
<xref linkend="vboxmanage-createvm" />,
<xref linkend="vboxmanage-list" />,
<xref linkend="vboxmanage-modifyvm" />,
<xref linkend="vboxmanage-showvminfo" />,
<xref linkend="vboxmanage-startvm" />,
<xref linkend="vboxmanage-storageattach" />,
<xref linkend="vboxmanage-storagectl" />
</para>
</refsect1>
</refentry>
|
