summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/man_VBoxManage-controlvm.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual/en_US/man_VBoxManage-controlvm.xml')
-rw-r--r--doc/manual/en_US/man_VBoxManage-controlvm.xml2133
1 files changed, 2133 insertions, 0 deletions
diff --git a/doc/manual/en_US/man_VBoxManage-controlvm.xml b/doc/manual/en_US/man_VBoxManage-controlvm.xml
new file mode 100644
index 00000000..f022529c
--- /dev/null
+++ b/doc/manual/en_US/man_VBoxManage-controlvm.xml
@@ -0,0 +1,2133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ manpage, user manual, usage: VBoxManage controlvm
+-->
+<!--
+ Copyright (C) 2006-2022 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-controlvm" lang="en">
+ <refentryinfo>
+ <pubdate>$Date: 2022-08-22 19:43:14 +0200 (Mon, 22 Aug 2022) $</pubdate>
+ <title>VBoxManage controlvm</title>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>VBoxManage-controlvm</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>VBoxManage-controlvm</refname>
+ <refpurpose>change state and settings for a running virtual machine</refpurpose>
+ <refclass>&product-name;</refclass>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-pause">
+<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">pause</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-resume">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">resume</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-reset">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">reset</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-poweroff">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">poweroff</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-savestate">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">savestate</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpipowerbutton">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">acpipowerbutton</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpisleepbutton">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">acpisleepbutton</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-reboot">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">reboot</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-shutdown">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">shutdown</arg>
+ <arg choice="opt">--force</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputscancode">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">keyboardputscancode</arg>
+ <arg choice="req"><replaceable>hex</replaceable></arg>
+ <arg rep="repeat"><replaceable>hex</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputstring">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">keyboardputstring</arg>
+ <arg choice="req"><replaceable>string</replaceable></arg>
+ <arg rep="repeat"><replaceable>string</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputfile">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">keyboardputfile</arg>
+ <arg choice="req"><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-setlinkstate">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">setlinkstate<replaceable>N</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-nic">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">nic<replaceable>N</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">null</arg>
+ <arg choice="plain">nat</arg>
+ <arg choice="plain">bridged</arg>
+ <arg choice="plain">intnet</arg>
+ <arg choice="plain">hostonly</arg>
+ <arg choice="plain">generic</arg>
+ <arg choice="plain">natnetwork</arg>
+ </group>
+ <arg><replaceable>device-name</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictrace">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">nictrace<replaceable>N</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictracefile">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">nictracefile<replaceable>N</replaceable></arg>
+ <arg choice="req"><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicproperty">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">nicproperty<replaceable>N</replaceable></arg>
+ <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">deny</arg>
+ <arg choice="plain">allow-vms</arg>
+ <arg choice="plain">allow-all</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">natpf<replaceable>N</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">[<replaceable>rulename</replaceable>]<arg choice="plain">,tcp</arg></arg>
+ <arg choice="plain">udp,<arg><replaceable>host-IP</replaceable></arg>,<arg choice="plain"><replaceable>hostport</replaceable>,</arg><arg><replaceable>guest-IP</replaceable></arg>,<arg choice="plain"><replaceable>guestport</replaceable></arg></arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg>
+
+ <arg choice="req"><replaceable>rulename</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">guestmemoryballoon</arg>
+ <arg choice="req"><replaceable>balloon-size</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">usbattach</arg>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>address</replaceable></arg>
+ </group>
+ <arg>--capturefile=<replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">usbdetach</arg>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>address</replaceable></arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">audioin</arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">audioout</arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">clipboard mode</arg>
+ <group choice="req">
+ <arg choice="plain">disabled</arg>
+ <arg choice="plain">hosttoguest</arg>
+ <arg choice="plain">guesttohost</arg>
+ <arg choice="plain">bidirectional</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-filetransfers">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">clipboard filetransfers</arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">draganddrop</arg>
+ <group choice="req">
+ <arg choice="plain">disabled</arg>
+ <arg choice="plain">hosttoguest</arg>
+ <arg choice="plain">guesttohost</arg>
+ <arg choice="plain">bidirectional</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrde">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">vrde</arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeport">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">vrdeport</arg>
+ <arg choice="req"><replaceable>port</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeproperty">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">vrdeproperty</arg>
+ <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">vrdevideochannelquality</arg>
+ <arg choice="req"><replaceable>percentage</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">setvideomodehint</arg>
+ <arg choice="req"><replaceable>xres</replaceable></arg>
+ <arg choice="req"><replaceable>yres</replaceable></arg>
+ <arg choice="req"><replaceable>bpp</replaceable></arg>
+ <arg><arg><replaceable>display</replaceable></arg><group>
+ <arg choice="plain">enabled:yes | no</arg>
+ <arg><replaceable>x-origin</replaceable>&nbsp;<replaceable>y-origin</replaceable></arg>
+ </group></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">setscreenlayout</arg>
+ <arg choice="req"><replaceable>display</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">primary <replaceable>x-origin</replaceable>&nbsp;<replaceable>y-origin</replaceable>&nbsp;<replaceable>x-resolution</replaceable>&nbsp;<replaceable>y-resolution</replaceable>&nbsp;<replaceable>bpp</replaceable></arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">screenshotpng</arg>
+ <arg choice="req"><replaceable>filename</replaceable></arg>
+ <arg><replaceable>display</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording</arg>
+ <group choice="req">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording screens</arg>
+ <group choice="req">
+ <arg choice="plain">all</arg>
+ <arg choice="plain">none</arg>
+ <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording filename</arg>
+ <arg choice="req">filename</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording videores</arg>
+ <arg choice="req"><replaceable>width</replaceable>x<replaceable>height</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording videorate</arg>
+ <arg choice="req"><replaceable>rate</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording videofps</arg>
+ <arg choice="req"><replaceable>fps</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording maxtime</arg>
+ <arg choice="req"><replaceable>sec</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording maxfilesize</arg>
+ <arg choice="req"><replaceable>MB</replaceable></arg>
+ </cmdsynopsis>
+
+ <!--
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-opts">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">recording opts</arg>
+ <arg choice="req"><replaceable>key</replaceable>=<arg><replaceable>value</replaceable></arg></arg>
+ </cmdsynopsis>
+ -->
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">setcredentials</arg>
+ <arg choice="req"><replaceable>username</replaceable></arg>
+ <arg choice="plain">--passwordfile=<group choice="req">
+ <arg choice="plain"><replaceable>filename</replaceable></arg>
+ <arg choice="plain"><replaceable>password</replaceable></arg>
+ </group></arg>
+ <arg choice="req"><replaceable>domain-name</replaceable></arg>
+ <arg choice="plain">--allowlocallogon=<group choice="req">
+ <arg choice="plain">yes</arg>
+ <arg choice="plain">no</arg>
+ </group></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-teleport">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">teleport</arg>
+ <arg choice="req">--host=<replaceable>host-name</replaceable></arg>
+ <arg choice="req">--port=<replaceable>port-name</replaceable></arg>
+ <arg>--maxdowntime=<replaceable>msec</replaceable></arg>
+ <group>
+ <arg choice="plain">--passwordfile=<replaceable>filename</replaceable></arg>
+ <arg choice="plain">--password=<replaceable>password</replaceable></arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-plugcpu">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">plugcpu</arg>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-unplugcpu">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">unplugcpu</arg>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-cpuexecutioncap">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">cpuexecutioncap</arg>
+ <arg choice="req"><replaceable>num</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">vm-process-priority</arg>
+ <group choice="req">
+ <arg choice="plain">default</arg>
+ <arg choice="plain">flat</arg>
+ <arg choice="plain">low</arg>
+ <arg choice="plain">normal</arg>
+ <arg choice="plain">high</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">webcam attach</arg>
+ <arg><replaceable>pathname</replaceable><arg><replaceable>settings</replaceable></arg></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">webcam detach</arg>
+ <arg><replaceable>pathname</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">webcam list</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">addencpassword</arg>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain"><replaceable>password-file</replaceable></arg>
+ <arg choice="plain">-</arg>
+ </group>
+ <arg>--removeonsuspend=<group choice="plain">
+ <arg choice="plain">yes</arg>
+ <arg choice="plain">no</arg>
+ </group></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">removeencpassword</arg>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">removeallencpasswords</arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg>
+ <group choice="plain">
+ <arg choice="plain">disconnected</arg>
+ <arg choice="plain">server <replaceable>pipe-name</replaceable></arg>
+ <arg choice="plain">client <replaceable>pipe-name</replaceable></arg>
+ <arg choice="plain">tcpserver <replaceable>port</replaceable></arg>
+ <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg>
+ <arg choice="plain">file <replaceable>filename</replaceable></arg>
+ <arg choice="plain"><replaceable>device-name</replaceable></arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">autostart-enabled<replaceable>N</replaceable></arg>
+ <group choice="plain">
+ <arg choice="plain">on</arg>
+ <arg choice="plain">off</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay">
+ <command>VBoxManage controlvm</command>
+ <group choice="req">
+ <arg choice="plain"><replaceable>uuid</replaceable></arg>
+ <arg choice="plain"><replaceable>vmname</replaceable></arg>
+ </group>
+ <arg choice="plain">autostart-delay<replaceable>seconds</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ The <command>VBoxManage controlvm</command> command enables you to
+ change the state of a running virtual machine (VM). The following
+ sections describe the subcommands that you can use:
+ </para>
+ <refsect2 id="vboxmanage-controlvm-pause">
+ <title>Pause a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> pause</command> command
+ temporarily stops the execution of a VM. When paused, the VM's
+ state is not permanently changed.
+ </para>
+ <para>
+ The VM window appears as gray and the title bar of the window
+ indicates that the VM is currently Paused. This action is
+ equivalent to selecting <emphasis role="bold">Pause</emphasis>
+ from the <emphasis role="bold">Machine</emphasis> menu of the
+ GUI.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-resume">
+ <title>Resume a Paused Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> resume</command> command
+ restarts the execution of a paused VM. This action is equivalent
+ to selecting <emphasis role="bold">Resume</emphasis> from the
+ <emphasis role="bold">Machine</emphasis> menu of the GUI.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-reset">
+ <title>Reset a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> reset</command> command
+ performs a cold reset the VM. This command has the same effect
+ on a VM as pressing the Reset button on a physical computer.
+ </para>
+ <para>
+ The cold reboot immediately restarts and reboots the guest
+ operating system (OS). The state of the VM is not saved prior to
+ the reset, so data might be lost. This action is equivalent to
+ selecting <emphasis role="bold">Reset</emphasis> from the
+ <emphasis role="bold">Machine</emphasis> menu of the GUI.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-poweroff">
+ <title>Power Off a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> poweroff</command> command
+ powers off the VM. This command has the same effect on a VM as
+ pulling the power cable on a physical computer.
+ </para>
+ <para>
+ The state of the VM is not saved prior to poweroff, so data
+ might be lost. This action is equivalent to selecting
+ <emphasis role="bold">Close</emphasis> from the
+ <emphasis role="bold">Machine</emphasis> menu of the GUI or to
+ clicking the VM window's Close button, and then selecting
+ <emphasis role="bold">Power Off the Machine</emphasis>.
+ </para>
+ <para>
+ When in the powered off state, you can restart the VM. See
+ <xref linkend="vboxmanage-startvm" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-savestate">
+ <title>Save the State of a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> savestate</command> command
+ saves the current state of the VM to disk and then stops the VM.
+ </para>
+ <para>
+ This action is equivalent to selecting
+ <emphasis role="bold">Close</emphasis> from the
+ <emphasis role="bold">Machine</emphasis> menu of the GUI or to
+ clicking the VM window's Close button, and then selecting
+ <emphasis role="bold">Save the Machine State</emphasis>.
+ </para>
+ <para>
+ When in the saved state, you can restart the VM. It will continue
+ exactly in the state you saved.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-acpipowerbutton">
+ <title>Send an APCI Shutdown Signal to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> acpipowerbutton</command>
+ command sends an ACPI shutdown signal to the VM. This command
+ has the same effect on a VM as pressing the Power button on a
+ physical computer.
+ </para>
+ <para>
+ So long as the VM runs a guest OS that provides appropriately
+ configured ACPI support, this command triggers an operating
+ system shutdown from within the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-acpisleepbutton">
+ <title>Send an APCI Sleep Signal to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> acpisleepbutton</command>
+ command sends an ACPI sleep signal to the VM.
+ </para>
+ <para>
+ So long as the VM runs a guest OS that provides appropriately
+ configured ACPI support, this command triggers a sleep mechanism
+ from within the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-reboot">
+ <title>Reboot the guest OS</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> reboot</command>
+ command asks the guest OS to reboot itself.
+ </para>
+ <para>
+ This commands requires Guest Additions to be installed in the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-shutdown">
+ <title>Shut down the guest OS</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> shutdown</command>
+ command asks the guest OS to halt + shutdown, optionally forcing
+ the shutdown.
+ </para>
+ <para>
+ This commands requires Guest Additions to be installed in the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-keyboardputscancode">
+ <title>Send Keyboard Scancodes to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> keyboardputscancode</command>
+ command sends keyboard scancode commands to the VM.
+ </para>
+ <para>
+ For information about keyboard scancodes, see
+ <ulink url="http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-keyboardputstring">
+ <title>Send Keyboard Strings to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> keyboardputstring</command>
+ command sends keyboard strings to the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-keyboardputfile">
+ <title>Send a File to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> keyboardputfile</command>
+ command sends a file to the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-setlinkstate">
+ <title>Set the Link State for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ <command>VBoxManage controlvm <replaceable>vmname</replaceable>
+ setlinkstate<replaceable>N</replaceable></command> command
+ enables you to connect or disconnect the virtual network cable
+ from the network interface instance
+ (<replaceable>N</replaceable>). Valid values are
+ <literal>on</literal> and <literal>off</literal>. The default
+ value is <literal>on</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-nic">
+ <title>Set the Type of Networking to Use for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ nic<replaceable>N</replaceable></command> command specifies the
+ type of networking to use on the specified VM's virtual network
+ card. <replaceable>N</replaceable> numbering begins with
+ <literal>1</literal>.
+ </para>
+ <para>
+ The following valid network types are also described in
+ <xref linkend="networkingmodes" />:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <literal>null</literal> specifies that the VM is is not
+ connected to the host system.
+ </para></listitem>
+ <listitem><para>
+ <literal>nat</literal> specifies that the VM uses network
+ address translation (NAT).
+ </para></listitem>
+ <listitem><para>
+ <literal>bridged</literal> specifies that the VM uses
+ bridged networking.
+ </para></listitem>
+ <listitem><para>
+ <literal>intnet</literal> specifies that the VM communicates
+ with other VMs by using internal networking.
+ </para></listitem>
+ <listitem><para>
+ <literal>hostonly</literal> specifies that the VM uses
+ host-only networking.
+ </para></listitem>
+ <listitem><para>
+ <literal>natnetwork</literal> specifies that the VM uses NAT
+ networking.
+ </para></listitem>
+ <listitem><para>
+ <literal>generic</literal> specifies that the VM has access
+ to rarely used submodes
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-nictrace">
+ <title>Trace the Network Traffic of a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ nictrace<replaceable>N</replaceable></command> command enables
+ you to trace the network traffic on the specified virtual
+ network card (<replaceable>N</replaceable>).
+ <replaceable>N</replaceable> numbering begins with
+ <literal>1</literal>. Valid values are <literal>on</literal> and
+ <literal>off</literal>. The default value is
+ <literal>off</literal>.
+ </para>
+ <para>
+ If you did not configure a file name for the trace file then
+ a default one is used, placing it in the VM subdirectory.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-nictracefile">
+ <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ nictracefile<replaceable>N</replaceable></command> command
+ enables you to specify the name of the network traffic trace log
+ file for the specified virtual network card
+ (<replaceable>N</replaceable>). <replaceable>N</replaceable>
+ numbering begins with <literal>1</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-nicpromisc">
+ <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ nicpromisc<replaceable>N</replaceable></command> command enables
+ you to specify how to handle promiscuous mode for a bridged
+ network. The default value of <literal>deny</literal> hides any
+ traffic that is not intended for this VM. The
+ <literal>allow-vms</literal> value hides all host traffic from
+ this VM but enables the VM to see traffic to and from other VMs.
+ The <literal>allow-all</literal> value removes this restriction
+ completely.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-nicproperty">
+ <title>Specify the Network Backend Property Values for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ nicproperty<replaceable>N</replaceable>
+ <replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></command>
+ command, in combination with <literal>nicgenericdrv</literal>,
+ enables you to pass property values to rarely-used network
+ backends.
+ </para>
+ <para>
+ Those properties are backend engine-specific, and are different
+ between UDP Tunnel and the VDE backend drivers. See
+ <xref linkend="network_udp_tunnel" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-natpf">
+ <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ natpf<replaceable>N</replaceable></command> command specifies a
+ NAT port-forwarding rule. See <xref linkend="natforward"/>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-natpf-delete">
+ <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ natpf<replaceable>N</replaceable> delete</command> command deletes
+ the specified NAT port-forwarding rule. See
+ <xref linkend="natforward"/>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-guestmemoryballoon">
+ <title>Change Size of a Virtual Machine's Guest Memory Balloon</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> guestmemoryballoon</command>
+ command changes the size of the guest memory balloon. The guest
+ memory balloon is the memory allocated by the &product-name;
+ Guest Additions from the guest OS and returned to the hypervisor
+ for reuse by other VMs. The value you specify is in megabytes.
+ See <xref linkend="guestadd-balloon" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-usbattach">
+ <title>Make a Host System USB Device Visible to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> usbattach</command> command
+ dynamically attaches a host USB device to the VM, which makes it
+ visible. You do not need to create a filter.
+ </para>
+ <para>
+ Specify a USB device by its Universally Unique Identifier (UUID)
+ or by its address on the host system. Use the
+ <command>VBoxManage list usbhost</command> command to obtain
+ information about USB devices on the host system.
+ </para>
+ <para>
+ Use the <option>--capturefile</option> option to specify the
+ absolute path of a file in which to write logging data.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-usbdetach">
+ <title>Make a Host System USB Device Invisible to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> usbdetach</command> command
+ dynamically detaches a host USB device from the VM, which makes
+ it invisible. You do not need to create a filter.
+ </para>
+ <para>
+ Specify a USB device by its UUID or by its address on the host
+ system. Use the <command>VBoxManage list usbhost</command>
+ command to obtain information about USB devices on the host
+ system.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-audioin">
+ <title>Enable or Disable Audio Capture From the Host System</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> audioin</command> command
+ specifies whether to enable or disable audio capture from the
+ host system. Valid values are <literal>on</literal>, which
+ enables audio capture and <literal>off</literal>, which disables
+ audio capture. The default value is <literal>off</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-audioout">
+ <title>Enable or Disable Audio Playback From a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> audioout</command> command
+ specifies whether to enable or disable audio playback from the
+ guest VM. Valid values are <literal>on</literal>, which enables
+ audio playback and <literal>off</literal>, which disables audio
+ playback. The default value is <literal>off</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-clipboard-mode">
+ <title>Specify How to Share the Host OS or Guest OS Clipboard</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> clipboard mode</command> command
+ specifies how to share the guest or host OS's clipboard with the
+ host system or VM. Valid values are <literal>disabled</literal>,
+ <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
+ and <literal>bidirectional</literal>. The default value is
+ <literal>disabled</literal>. See
+ <xref linkend="generalsettings" />.
+ </para>
+ <para>
+ This feature requires that the &product-name; Guest Additions
+ are installed in the VM.
+ </para>
+ </refsect2>
+
+ <refsect2 id="vboxmanage-controlvm-clipboard-filetransfers">
+ <title>Specify If Files Can Be Transferred Through the Clipboard</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> clipboard filetransfers</command>
+ command specifies if it is possible to transfer files through the
+ clipboard between the host and VM, in the direction which is allowed.
+ Valid values are <literal>off</literal> and <literal>on</literal>.
+ The default value is <literal>off</literal>.
+ </para>
+ <para>
+ This feature requires that the &product-name; Guest Additions
+ are installed in the VM.
+ </para>
+ </refsect2>
+
+ <refsect2 id="vboxmanage-controlvm-draganddrop">
+ <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> draganddrop</command> command
+ specifies the current drag and drop mode to use between the host
+ system and the VM. Valid values are <literal>disabled</literal>,
+ <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
+ and <literal>bidirectional</literal>. The default value is
+ <literal>disabled</literal>. See
+ <xref linkend="guestadd-dnd" />.
+ </para>
+ <para>
+ This feature requires that the &product-name; Guest Additions
+ are installed in the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-vrde">
+ <title>Enable or Disable the VRDE Server</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> vrde</command> command enables
+ or disables the VirtualBox Remote Desktop Extension (VRDE)
+ server, if installed. Valid values are <literal>on</literal> and
+ <literal>off</literal>. The default value is
+ <literal>off</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-vrdeport">
+ <title>Specify VRDE Server Ports</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> vrdeport</command> command
+ specifies the port or range of ports to which the VRDE server
+ can bind. The default value is <literal>default</literal> or
+ <literal>0</literal>, which is the standard RDP port,
+ <literal>3389</literal>.
+ </para>
+ <para>
+ Also see the <option>--vrde-port</option> option description in
+ <xref linkend="vboxmanage-modifyvm-vrde" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-vrdeproperty">
+ <title>Specify VRDE Server Port Numbers and IP Addresses</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> vrdeproperty</command> command
+ specifies the port numbers and IP address on the VM to which the
+ VRDE server can bind.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <literal>TCP/Ports</literal> specifies a port or a range of
+ ports to which the VRDE server can bind. The default value
+ is <literal>default</literal> or <literal>0</literal>, which
+ is the standard RDP port, <literal>3389</literal>.
+ </para><para>
+ Also see the <option>--vrde-port</option> option description
+ in <xref linkend="vboxmanage-modifyvm-vrde" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>TCP/Address</literal> specifies the IP address of
+ the host network interface to which the VRDE server binds.
+ When specified, the server accepts to connect only on the
+ specified host network interface.
+ </para><para>
+ Also see the <option>--vrde-address</option> option
+ description in <xref linkend="vboxmanage-modifyvm-vrde" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>VideoChannel/Enabled</literal> specifies whether to
+ enable the VirtualBox Remote Desktop Protocol (VRDP) video
+ channel. Valid values are <literal>1</literal> to enable the
+ video channel and <literal>0</literal> to disable the video
+ channel. The default value is <literal>off</literal>. See
+ <xref linkend="vrde-videochannel" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>VideoChannel/Quality</literal> specifies the JPEG
+ compression level on the VRDE server video channel. Valid
+ values are between 10% and 100%, inclusive. Lower values
+ mean lower quality but higher compression. The default value
+ is <literal>100</literal>. See
+ <xref linkend="vrde-videochannel" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>VideoChannel/DownscaleProtection</literal>
+ specifies whether to enable the video channel downscale
+ protection feature. Specify <literal>1</literal> to enable
+ the feature. This feature is disabled by default.
+ </para><para>
+ When enabled, if the video's size equals the shadow buffer
+ size, the video is shown in full-screen mode. If the video's
+ size is between full-screen mode and the downscale
+ threshold, the video is not shown as it might be an
+ application window that is unreadable when downscaled. When
+ disabled, the downscale protection feature always attempts
+ to show videos.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableDisplay</literal> specifies whether
+ to disable the VRDE server display feature. Valid values are
+ <literal>1</literal> to disable the feature and an empty
+ string (<literal>""</literal>) to enable the feature.
+ The default value is an empty string. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableInput</literal> specifies whether to
+ disable the VRDE server input feature. Valid values are
+ <literal>1</literal> to disable the feature and an empty
+ string (<literal>""</literal>) to enable the feature.
+ The default value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableAudio</literal> specifies whether to
+ disable the VRDE server audio feature. Valid values are
+ <literal>1</literal> to disable the feature and an empty
+ string (<literal>""</literal>) to enable the feature.
+ The default value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableUSB</literal> specifies whether to
+ disable the VRDE server USB feature. Valid values are
+ <literal>1</literal> to disable the feature and an empty
+ string (<literal>""</literal>) to enable the feature.
+ The default value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableClipboard</literal> specifies whether
+ to disable the VRDE clipboard feature. Valid values are
+ <literal>1</literal> to disable the feature and an empty
+ string (<literal>""</literal>) to enable the feature.
+ To reenable the feature, use
+ <literal>Client/DisableClipboard=</literal>. The default
+ value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableUpstreamAudio</literal> specifies
+ whether to disable the VRDE upstream audio feature. Valid
+ values are <literal>1</literal> to disable the feature and
+ an empty string (<literal>""</literal>) to enable the
+ feature. To reenable the feature, use
+ <literal>Client/DisableUpstreamAudio=</literal>. The default
+ value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Client/DisableRDPDR</literal> specifies whether to
+ disable the RDP Device Redirection For Smart Cards feature
+ on the VRDE server. Valid values are <literal>1</literal> to
+ disable the feature and an empty string
+ (<literal>""</literal>) to enable the feature.
+ The default value is <literal>1</literal>. See
+ <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>H3DRedirect/Enabled</literal> specifies whether to
+ enable the VRDE server 3D redirection feature. Valid values
+ are <literal>1</literal> to enable the feature and an empty
+ string (<literal>""</literal>) to disable the feature.
+ See <xref linkend="vrde-customization"/>.
+ </para></listitem>
+ <listitem><para>
+ <literal>Security/Method</literal> specifies the security
+ method to use for a connection. See
+ <xref linkend="vrde-crypt" />.
+ </para><itemizedlist>
+ <listitem><para>
+ <literal>Negotiate</literal> accepts both enhanced (TLS)
+ and standard RDP security connections. The security
+ method is negotiated with the client. This is the
+ default value.
+ </para></listitem>
+ <listitem><para>
+ <literal>RDP</literal> accepts only standard RDP
+ security connections.
+ </para></listitem>
+ <listitem><para>
+ <literal>TLS</literal> accepts only enhanced RDP
+ security connections. The client must support TLS.
+ </para></listitem>
+ </itemizedlist></listitem>
+ <listitem><para>
+ <literal>Security/ServerCertificate</literal> specifies the
+ absolute path of the server certificate to use for a
+ connection. See <xref linkend="vrde-crypt" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>Security/ServerPrivateKey</literal> specifies the
+ absolute path of the server private key. See
+ <xref linkend="vrde-crypt" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>Security/CACertificate</literal> specifies the
+ absolute path of the CA self-signed certificate. See
+ <xref linkend="vrde-crypt" />.
+ </para></listitem>
+ <listitem><para>
+ <literal>Audio/RateCorrectionMode</literal> specifies the
+ rate correction mode to use.
+ </para><itemizedlist>
+ <listitem><para>
+ <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that
+ no mode is specified. Use this value to unset any audio
+ mode that is already set.
+ </para></listitem>
+ <listitem><para>
+ <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use
+ the rate correction mode.
+ </para></listitem>
+ <listitem><para>
+ <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use
+ the low pass filter mode.
+ </para></listitem>
+ <listitem><para>
+ <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use
+ the client sync mode to prevent underflow or overflow of
+ the client queue.
+ </para></listitem>
+ </itemizedlist></listitem>
+ <listitem><para>
+ <literal>Audio/LogPath</literal> specifies the absolute path
+ of the audio log file.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality">
+ <title>Specify the Image Quality for VRDP Video Redirection</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ vrdevideochannelquality</command> command sets the image
+ quality, as a JPEG compression level value, for video
+ redirection. Valid values are between 10% and 100%, inclusive.
+ Lower values mean lower quality but higher compression. See
+ <xref linkend="vrde-videochannel" />.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-setvideomodehint">
+ <title>Specify the Video Mode for the Guest VM</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> setvideomodehint</command>
+ command specifies the video mode for the guest VM to use. You
+ must have the &product-name; Guest Additions installed. Note
+ that this feature does not work for all guest systems.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-setscreenlayout">
+ <title>Specify the Screen Layout for a Display on the Guest VM</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> setscreenlayout</command>
+ command can be used to configure multiscreen displays. The
+ specified screen on the guest VM can be enabled or disabled, or
+ a custom screen layout can be configured.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-screenshotpng">
+ <title>Take a Screen Shot of the Virtual Machine Display</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> screenshotpng</command>
+ command takes a screenshot of the guest display and saves it as
+ PNG in the specified file.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <replaceable>filename</replaceable> specifies the name of
+ the PNG file to create.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>display</replaceable> specifies the display
+ number for the screen shot. For a single monitor guest
+ display, this is <literal>0</literal>.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording">
+ <title>Enable or Disable the Recording of a Virtual Machine Session</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording</command> command
+ enables or disables the recording of a VM session into a
+ WebM/VP8 file. Valid values are <literal>on</literal>, which
+ begins recording when the VM session starts and
+ <literal>off</literal>, which disables recording. The default
+ value is <literal>off</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-screens">
+ <title>Specify the Virtual Machine Screens to Record</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording screens</command>
+ command enables you to specify which VM screens to record. The
+ recording for each screen that you specify is saved to its own
+ file in the machine folder. You cannot modify this setting while
+ recording is enabled.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <literal>all</literal> specifies that you record all VM
+ screens.
+ </para></listitem>
+ <listitem><para>
+ <literal>none</literal> specifies that you do not record any
+ VM screens.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>screen-ID</replaceable> specifies one or more
+ VM screens to record.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-filename">
+ <title>Specify the File in Which to Save Virtual Machine Recording</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording filename</command>
+ command specifies the file in which to save the recording. You
+ cannot modify this setting while recording is enabled.
+ </para>
+ <para>
+ The default setting is to store a recording in the machine
+ folder, using the VM name as the file name, with a
+ <filename>webm</filename> file name extension.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-videores">
+ <title>Specify the Resolution of the Recorded Video</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ <command>VBoxManage controlvm <replaceable>vmname</replaceable>
+ recording videores</command> command specifies the resolution of
+ the recorded video in pixels. You cannot modify this setting
+ while recording is enabled.
+ </para>
+ <para>
+ Use the Settings tool to view the video recording settings,
+ which are based on the resolution (frame size). See the Frame
+ Size field on the Recording tab of the Display page to view the
+ default value.
+ </para>
+ <para>
+ Specify the resolution as
+ <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <replaceable>width</replaceable> specifies the width in
+ pixels.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>height</replaceable> specifies the height in
+ pixels.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-videorate">
+ <title>Specify the Bit Rate of the Video</title>
+ <remark role="help-copy-synopsis"/>
+<!-- @todo r=andy Clarify rate. -->
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording videorate</command>
+ command specifies the bit rate,
+ <replaceable>bit-rate</replaceable>, of the video in kilobits
+ per second. Increasing this value improves the appearance of the
+ video at the cost of an increased file size. You cannot modify
+ this setting while recording is enabled.
+ </para>
+ <para>
+ Use the Settings tool to view the video recording settings,
+ which are based on the frame size. See the Video Quality field
+ on the Recording tab of the Display page to view the default
+ value.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-videofps">
+ <title>Specify the Maximum Frequency of the Video</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording videofps</command>
+ command specifies the maximum frequency of the video to record.
+ Video frequency is measured in frames per second (FPS). The
+ recording skips any frames that have a frequency higher than the
+ specified maximum. Increasing the frequency reduces the number
+ of skipped frames and increases the file size. You cannot modify
+ this setting while recording is enabled.
+ </para>
+ <para>
+ Use the Settings tool to view the video recording settings,
+ which are based on the frame size. See the Frame Rate field on
+ the Recording tab of the Display page to view the default value.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-maxtime">
+ <title>Specify the Maximum Amount of Time to Record Video</title>
+ <remark role="help-copy-synopsis"/>
+<!-- @todo r=andy Clarify time format. -->
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording maxtime</command>
+ command specifies the maximum amount time to record in seconds.
+ The recording stops after the specified number of seconds
+ elapses. If this value is zero, the recording continues until
+ you stop the recording.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-recording-maxfilesize">
+ <title>Specify the Maximum Size of the Recorded Video</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording
+ maxfilesize</command> command specifies the maximum size of the
+ recorded video file in megabytes. The recording stops when the
+ file reaches the specified size. If this value is zero, the
+ recording continues until you stop the recording. You cannot
+ modify this setting while recording is enabled.
+ </para>
+ </refsect2>
+ <!--
+ <refsect2 id="vboxmanage-controlvm-recording-opts">
+ <title>Specify Custom Options for Recording Video and/or Audio</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> recording
+ opts</command> command specifies additional recording options
+ in a comma-separated keyword-value format. For example,
+ <computeroutput>foo=bar,a=b</computeroutput>. You cannot
+ modify this setting while recording is enabled.
+ </para>
+ <para>
+ Use this option if you are an advanced user only. For
+ information about keywords, see <emphasis>&product-name;
+ Programming Guide and Reference</emphasis>.
+ </para>
+ </refsect2>
+ -->
+ <refsect2 id="vboxmanage-controlvm-setcredentials">
+ <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>setcredentials</command> command enables you to
+ specify the credentials for remotely logging in to Windows VMs.
+ See <xref linkend="autologon" />.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <replaceable>username</replaceable> specifies the user name
+ with which to log in to the Windows VM.
+ </para></listitem>
+ <listitem><para>
+ <option>--passwordfile=<replaceable>filename</replaceable></option>
+ specifies the file from which to obtain the password for
+ <replaceable>username</replaceable>.
+ </para><para>
+ The <option>--passwordfile</option> is mutually exclusive
+ with the <option>--password</option> option.
+ </para></listitem>
+ <listitem><para>
+ <option>--password=<replaceable>password</replaceable></option>
+ specifies the password for
+ <replaceable>username</replaceable>.
+ </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><para>
+ The <option>--password</option> is mutually exclusive with
+ the <option>--passwordfile</option> option.
+ </para></listitem>
+ <listitem><para>
+ <option>--allowlocallogin</option> specifies whether to
+ enable or disable local logins. Valid values are
+ <literal>on</literal> to enable local logins and
+ <literal>off</literal> to disable local logins.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-teleport">
+ <title>Configure a Virtual Machine Target for Teleporting</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> teleport</command> command
+ initiates a teleporting operation between the specified VM and
+ the specified host system. See <xref linkend="teleporting" />.
+ </para>
+ <para>
+ If you specify a password, it must match the password you
+ specified when you issued the <command>VBoxManage
+ modifyvm</command> command for the target machine.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--host=<replaceable>hostname</replaceable></option></term>
+ <listitem><para>
+ Specifies the name of the VM.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--port=<replaceable>port</replaceable></option></term>
+ <listitem><para>
+ Specifies the port on the VM that should listen for a
+ teleporting request from other VMs. The port number can be
+ any free TCP/IP port number, such as
+ <literal>6000</literal>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--maxdowntime=<replaceable>msec</replaceable></option></term>
+ <listitem><para>
+ Specifies the maximum downtime, in milliseconds, for the
+ teleporting target VM.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--password=<replaceable>password</replaceable></option></term>
+ <listitem><para>
+ Specifies the password that the source machine uses for
+ the teleporting request. The request succeeds only if the
+ source machine specifies the same password.
+ </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><para>
+ The <option>--password</option> is mutually exclusive with
+ the <option>--passwordfile</option> option.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--passwordfile=<replaceable>filename</replaceable></option></term>
+ <listitem><para>
+ Specifies the file from which to obtain the password that
+ the source machine uses for the teleporting request. The
+ request succeeds only if the source machine specifies the
+ same password.
+ </para><para>
+ When you specify a file name of <literal>stdin</literal>,
+ you can read the password from standard input.
+ </para><para>
+ The <option>--passwordfile</option> is mutually exclusive
+ with the <option>--password</option> option.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-plugcpu">
+ <title>Add a Virtual CPU to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> plugcpu</command> command adds
+ a virtual CPU to the specified VM if CPU hot-plugging is
+ enabled. <replaceable>ID</replaceable> specifies the index of
+ the virtual CPU to be added and must be a number from 0 to the
+ maximum number of CPUs configured.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-unplugcpu">
+ <title>Remove a Virtual CPU From a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> unplugcpu</command> command
+ removes a virtual CPU from the specified VM if CPU hot-plugging
+ is enabled. <replaceable>ID</replaceable> specifies the index of
+ the virtual CPU to be removed and must be a number from 0 to the
+ maximum number of CPUs configured. You cannot remove CPU 0.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-cpuexecutioncap">
+ <title>Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> cpuexecutioncap</command>
+ command specifies how the maximum amount of physical CPU time
+ used by a virtual CPU. Valid values are a percentage between
+ <literal>1</literal> and <literal>100</literal>. A value of
+ <literal>50</literal> specifies that a single virtual CPU can
+ use up to 50% of a physical CPU. The default value is
+ <literal>100</literal>.
+ </para>
+ <para>
+ Use this feature with caution, it can have unexpected results
+ including timekeeping problems and lower performance than
+ specified. If you want to limit the resource usage of a VM
+ it is more reliable to pick an appropriate number of VCPUs.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-vm-process-priority">
+ <title>Change the Priority of a VM Process</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> vm-process-priority</command>
+ command specifies the priority scheme of the VM process to use
+ when starting the specified VM and while the VM runs.
+ </para>
+ <para>
+ Valid values are:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <literal>default</literal> &ndash; Default process
+ priority determined by the OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>flat</literal> &ndash; Assumes a scheduling
+ policy which puts the process at the default priority
+ and with all threads at the same priority.
+ </para></listitem>
+ <listitem><para>
+ <literal>low</literal> &ndash; Assumes a scheduling
+ policy which puts the process mostly below the default
+ priority of the host OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>normal</literal> &ndash; Assume a scheduling
+ policy which shares the CPU resources fairly with
+ other processes running with the default priority of
+ the host OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>high</literal> &ndash; Assumes a scheduling
+ policy which puts the task above the default priority of
+ the host OS. This policy might easily cause other tasks
+ in the system to starve.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-webcam-attach">
+ <title>Attach a Webcam to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> webcam attach</command>
+ command attaches a webcam to a running VM. Specify the webcam as
+ the absolute path of the webcam on the host OS or as an alias.
+ Use the <command>VBoxManage list webcams</command> command to
+ obtain the webcam alias.
+ </para>
+ <para>
+ Note that the <literal>.0</literal> alias is the default video
+ input device on the host OS. <literal>.1</literal> is the first
+ video input device, <literal>.2</literal> is the second video
+ input device, and so on. The order of the devices is specific to
+ the host system.
+ </para>
+ <para>
+ You can specify optional settings in the form of
+ semi-colon-separated (<literal>;</literal>) name-value pairs.
+ These properties enable you to configure the emulated webcam
+ device.
+ </para>
+ <para>
+ The following settings are supported:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>MaxFramerate</literal></term>
+ <listitem><para>
+ Specifies the highest rate at which to send video frames
+ to the VM. The rate is in frames per second. Higher frame
+ rates increase CPU load, so you can use this setting to
+ reduce CPU load. The default value is <literal>no maximum
+ limit</literal>. This value enables the VM to use any
+ frame rate supported by the webcam.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>MaxPayloadTransferSize</literal></term>
+ <listitem><para>
+ Specifies the maximum number of bytes that the VM receives
+ from the emulated webcam in one buffer. The default
+ setting is <literal>3060</literal> bytes, which is used by
+ some webcams. If the VM is able to use larger buffers,
+ higher values might reduce CPU load slightly. Note that
+ some guest OSes might not suppport higher
+ <literal>MaxPayloadTransferSize</literal> values.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-webcam-detach">
+ <title>Detach a Webcam From a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> webcam detach</command>
+ command detaches a webcam from a running VM. Specify the webcam
+ as the absolute path of the webcam on the host OS or as an
+ alias. Use the <command>VBoxManage list webcams</command> to
+ obtain the webcam alias.
+ </para>
+ <para>
+ When a webcam device is detached from the host, the host OS
+ determines how the emulated webcam behaves.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <emphasis role="bold">Windows hosts:</emphasis> The emulated
+ webcam device is detached from the VM automatically.
+ </para></listitem>
+ <listitem><para>
+ <emphasis role="bold">Mac OS X hosts that run at least OS X
+ 10.7:</emphasis> The emulated webcam device remains attached
+ to the VM and you must detach it manually by using the
+ <command>VBoxManage controlvm webcam detach</command>
+ command.
+ </para></listitem>
+ <listitem><para>
+ <emphasis role="bold">Linux hosts:</emphasis> The emulated
+ webcam device is detached from the VM automatically only if
+ the webcam is actively streaming video. If the emulated
+ webcam is inactive, manually detach it by using the
+ <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> webcam detach</command>
+ command.
+ </para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-webcam-list">
+ <title>List the Webcams Attached to a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> webcam list</command> command
+ lists webcams that are attached to the running VM. The output
+ shows a list of absolute paths or aliases that attached the
+ webcams to the VM by using the <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> webcam attach</command>
+ command.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-addencpassword">
+ <title>Set an Encryption Password for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> addencpassword</command>
+ command provides the <replaceable>vmname</replaceable> encrypted
+ VM with the encryption password to enable a headless start.
+ Specify the absolute path of a password file on the host system.
+ If <replaceable>filename</replaceable> is <literal>-</literal>,
+ <command>VBoxManage</command> prompts for the encryption
+ password.
+ </para>
+ <para>
+ Use the <option>--removeonsuspend</option> option to specify
+ whether to save the passsword or clear it from VM memory when
+ the VM is suspended.
+ </para>
+ <para>
+ If the VM is suspended and the password is cleared, use the
+ <command>VBoxManage controlvm <replaceable>vmname</replaceable>
+ addencpassword</command> to provide the password to resume
+ execution on the VM. Use this feature when you do not want to
+ store the password in VM memory while the VM is suspended by a
+ host suspend event.
+ </para>
+ <note>
+ <para>
+ You can encrypt data stored on hard disk images used by the
+ VM. &product-name; uses the AES algorithm in XTS mode and
+ supports 128-bit or 256-bit data encryption keys (DEK). The
+ encrypted DEK is stored in the medium properties and is
+ decrypted during VM startup when you provide the encryption
+ password.
+ </para>
+ </note>
+ <para>
+ Use the <command>VBoxManage encryptmedium</command> command to
+ create a DEK encrypted medium. See
+ <xref linkend="diskencryption-encryption" />.
+ </para>
+ <para>
+ The &product-name; GUI prompts you for the encryption password
+ when you start an encrypted VM.
+ </para>
+ <para>
+ Use the following command to perform a headless start of an
+ encrypted VM:
+ </para>
+<screen>
+ $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless
+ </screen>
+ <para>
+ Then, use the following command to provide the encryption
+ password:
+ </para>
+<screen>
+ $ VBoxManage <replaceable>vmname</replaceable> controlvm addencpassword <replaceable>vmname</replaceable> -
+ Password: <replaceable>encryption-password</replaceable>
+ </screen>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-removeencpassword">
+ <title>Disable an Encryption Password for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> removeencpassword</command>
+ command disables a specific encryption password for all
+ encrypted media attached to the VM.
+ </para>
+ <para>
+ <replaceable>ID</replaceable> is the password identifier for the
+ encryption password that you want to disable.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-removeallencpasswords">
+ <title>Disable All Encryption Passwords for a Virtual Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable>
+ removeallencpasswords</command> command disables all encryption
+ passwords for all encrypted media attached to the VM.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-changeuartmode">
+ <title>Change the Connection Mode for a Virtual Serial Port on a Virtual
+ Machine</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> changeuartmode</command>
+ command changes the connection mode for the specified virtual
+ serial port. Valid serial port values are integers that start
+ from <literal>1</literal>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>disconnected</term>
+ <listitem><para>
+ Disconnects the device.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>server <replaceable>pipe-name</replaceable></term>
+ <listitem><para>
+ Specifies the pipe name of the server.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>client <replaceable>pipe-name</replaceable></term>
+ <listitem><para>
+ Specifies the pipe name of the client.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>tcpserver <replaceable>port</replaceable></term>
+ <listitem><para>
+ Specifies the port number of the TCP server.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></term>
+ <listitem><para>
+ Specifies the host name and port number of the TCP client.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>file <replaceable>filename</replaceable></term>
+ <listitem><para>
+ Specifies the name of the file.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>device-name</replaceable></term>
+ <listitem><para>
+ Specifies the name of the device.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-autostart-enabled">
+ <title>Enabling autostart the VM during host system boot</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> autostart-enabled</command>
+ command specifies whether to enable or disable automatically
+ start the VM at host system boot-up. You must do some host
+ system configuration before you can use this feature.
+ See <xref linkend="autostart" />. Valid values are
+ <literal>on</literal>, which enables autostart feature for
+ the VM and <literal>off</literal>, which disables it. The
+ default value is <literal>off</literal>.
+ </para>
+ </refsect2>
+ <refsect2 id="vboxmanage-controlvm-autostart-delay">
+ <title>Setting the delay of starting the VM on host system boot</title>
+ <remark role="help-copy-synopsis"/>
+ <para>
+ The <command>VBoxManage controlvm
+ <replaceable>vmname</replaceable> autostart-delay</command>
+ command specifies the delay in seconds before the VM starts
+ on host system boot-up. See <xref linkend="autostart" />.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <remark role="help-scope" condition="GLOBAL" />
+ <para>
+ The following command temporarily stops the execution of the
+ <filename>ol7</filename> VM.
+ </para>
+<screen>$ VBoxManage controlvm ol7 pause</screen>
+ <para>
+ The following command configures shared clipboard operation for
+ the <filename>ol7</filename> VM. Copying of clipboard data is
+ allowed in both directions between the host and guest.
+ </para>
+<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <xref linkend="vboxmanage-list" />,
+ <xref linkend="vboxmanage-modifyvm" />,
+ <xref linkend="vboxmanage-startvm" />
+ </para>
+ </refsect1>
+</refentry>