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

<?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 14:15:46 +0000 (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>