Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 282 insertions, 0 deletions

diff --git a/doc/manual/en_US/man_VBoxManage-common.xml b/doc/manual/en_US/man_VBoxManage-common.xml
new file mode 100644
index 00000000..b661c446
--- /dev/null
+++ b/doc/manual/en_US/man_VBoxManage-common.xml
@@ -0,0 +1,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>