VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-common.xml@ 103068

Last change on this file since 103068 was 99513, checked in by vboxsync, 20 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

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

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