282 lines
11 KiB
XML
282 lines
11 KiB
XML
<?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>
|