<?xml version="1.0" encoding="UTF-8"?>
<!--
    manpage, user manual, usage: VBoxManage controlvm
-->
<!--
    Copyright (C) 2006-2024 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: 2024-09-16 16:03:52 +0200 (Mon, 16 Sep 2024) $</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>

      <arg choice="req" role="compact"><arg><replaceable>rulename</replaceable></arg>,<group choice="req"><arg choice="plain">tcp</arg><arg choice="plain">udp</arg></group>,<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>
    </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>
        <replaceable>display</replaceable>
        <arg>
          <group choice="req">
            <arg choice="plain">yes</arg>
            <arg choice="plain">no</arg>
          </group>
          <arg>
            <arg choice="plain"><replaceable>x-origin</replaceable></arg>
            <arg choice="plain"><replaceable>y-origin</replaceable></arg>
          </arg>
        </arg>
      </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
          <arg choice="req"><replaceable>x-origin</replaceable></arg>
          <arg choice="req"><replaceable>y-origin</replaceable></arg>
          <arg choice="req"><replaceable>x-resolution</replaceable></arg>
          <arg choice="req"><replaceable>y-resolution</replaceable></arg>
          <arg choice="req"><replaceable>bpp</replaceable></arg>
        </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>

      <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 start</arg>
      <arg>--wait</arg>

      <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 stop</arg>

      <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 attach</arg>

      <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><arg rep="repeat">,<replaceable>screen-ID</replaceable></arg></arg>
      </group>

      <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>

      <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"><arg choice="req"><replaceable>width</replaceable></arg>x<arg choice="req"><replaceable>height</replaceable></arg></arg>

      <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>

      <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>

      <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>

      <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>

      <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"><arg choice="plain">server</arg> <arg choice="req"><replaceable>pipe-name</replaceable></arg></arg>
        <arg choice="plain"><arg choice="plain">client</arg> <arg choice="req"><replaceable>pipe-name</replaceable></arg></arg>
        <arg choice="plain"><arg choice="plain">tcpserver</arg> <arg choice="req"><replaceable>port</replaceable></arg></arg>
        <arg choice="plain"><arg choice="plain">tcpclient</arg> <arg choice="req"><replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg></arg>
        <arg choice="plain"><arg choice="plain">file</arg> <arg choice="req"><replaceable>filename</replaceable></arg></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</arg>
      <arg choice="req"><replaceable>seconds</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="vboxmanage-controlvm-description">
    <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>
        A 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>
        The <command>poweroff</command> subcommand places a VM into
        the Powered Off state from which you can restart the VM using
        <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>
        The <command>savestate</command> subcommand places a VM into
        the Saved state from which you can restart the VM using
        <xref linkend="vboxmanage-startvm" />.  The VM will resume
        from the exact point at which it was 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 command requires the &product-name; 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 command requires the &product-name; 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 do 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 Virtual Distributed Ethernet (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 the &product-name; Guest Additions
        to be 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(s) configured for
        the <command>clipboard mode</command>.  Valid values are
        <literal>off</literal> and <literal>on</literal>.  The default value
        is <literal>off</literal>.
      </para>
      <para>
        This feature requires the &product-name; Guest Additions
        to be 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 the &product-name; Guest Additions
        to be 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 uses the standard RDP port,
        <literal>3389</literal>.
      </para>
      <para>
        See also 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>
            See also 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 connections only on the
            specified host network interface.
          </para><para>
            See also 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>0</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 re-enable 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 re-enable 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>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>

      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording start</command> command
        starts the recording of a VM session into a
        WebM/VP8 file.
      </para>

      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording stop</command> command
        stops the recording of a VM session.
      </para>

      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording attach</command> command
        attaches to a running recording of a VM session.
      </para>

      <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
        a screen recording is in progress.
      </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>

      <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 a screen recording is in progress.
      </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>

      <para>
        The <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 a screen recording is in progress.
      </para>
      <para>
        The <emphasis role="bold">Recording</emphasis> settings in the GUI
        which are located in the <emphasis role="bold">Display</emphasis>
        page show the current video recording settings which are based on
        the resolution (frame size). The <emphasis role="bold">Frame Size</emphasis>
        field shows the default value for the recording video resolution.
      </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>

      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording videorate</command>
        command specifies the
        <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 a VM is running with recording enabled.
      </para>
      <para>
        The <emphasis role="bold">Recording</emphasis> settings in the GUI
        which are located in the <emphasis role="bold">Display</emphasis>
        page show the current video recording settings which are based on
        the resolution (frame size). The <emphasis role="bold">Video Quality</emphasis>
        field shows the default value for the recording video quality.
      </para>

      <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 a VM is running with recording enabled.
      </para>
      <para>
        The <emphasis role="bold">Recording</emphasis> settings in the GUI
        which are located in the <emphasis role="bold">Display</emphasis>
        page show the current video recording settings which are based on
        the resolution (frame size). The <emphasis role="bold">Frame Rate</emphasis>
        field shows the default value for the recording frame rate.
      </para>

      <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 VM or stop the recording.
      </para>

      <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 VM or stop the recording.
        You cannot modify this setting while a screen recording is in
        progress.
      </para>

      <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 a screen recording is in progress.
      </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> 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> option is mutually exclusive with
            the <option>--passwordfile</option> option.
          </para></listitem>
        <listitem><para>
            <option>--allowlocallogon</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> 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> 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 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; Uses 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; Uses a scheduling
            policy which puts the process mostly below the default
            priority of the host OS.
          </para></listitem>
        <listitem><para>
            <literal>normal</literal> &ndash; Uses 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; Uses 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
        semicolon-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 support 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> 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 of the webcams which
        were attached to the VM using the <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> webcam attach</command>
        command.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-addencpassword">
      <title>Starting a Virtual Machine with Encrypted Images</title>
      <remark role="help-copy-synopsis"/>
      <para>
        You can encrypt the data stored in the 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>
      <para>
        Use the <command>VBoxManage encryptmedium</command> command to
        create a DEK encrypted medium. See
        <xref linkend="diskencryption-encryption" />.
      </para>
      <para>
        When a VM which contains one or more encrypted disk images is
        started using the &product-name; GUI a dialog will open to prompt
        the user for the password of each encrypted disk attached to the
        VM.  If the <command>VBoxHeadless</command> frontend is used, the
        VM will be paused as soon as the guest tries to access an encrypted
        disk. The user needs to provide the passwords by using
        <command>addencpassword</command> subcommand.
      </para>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> addencpassword</command>
        command provides the encryption password to the VM named
        <replaceable>vmname</replaceable> which contains encrypted disks
        that has been started using the <command>VBoxHeadless</command>
        frontend.  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 when the VM is suspended by a
        host suspend event.
      </para>
      <para>
        The following is one way to perform a headless start of VM which
        contains encrypted disk images:
      </para>
<screen>
          $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless
        </screen>
      <para>
        The following command provides the encryption password to the VM
        so that it can resume starting up:
      </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
        starting of 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 the 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 id="vboxmanage-controlvm-examples">
    <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 id="vboxmanage-controlvm-see-also">
    <title>See Also</title>
    <para>
      <xref linkend="vboxmanage-list" />,
      <xref linkend="vboxmanage-modifyvm" />,
      <xref linkend="vboxmanage-startvm" />
    </para>
  </refsect1>
</refentry>