source: vbox/trunk/doc/manual/en_US/man_VBoxManage-controlvm.xml@ 85670

<?xml version="1.0" encoding="UTF-8"?>
<!--
         manpage, user manual, usage: VBoxManage controlvm

    Copyright (C) 2006-2020 Oracle Corporation

    This file is part of VirtualBox Open Source Edition (OSE), as
    available from http://www.virtualbox.org. This file is free software;
    you can redistribute it and/or modify it under the terms of the GNU
    General Public License (GPL) as published by the Free Software
    Foundation, in version 2 as it comes in the "COPYING" file of the
    VirtualBox OSE distribution. VirtualBox OSE is distributed in the
    hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 -->
<!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>September 2019</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>Oracle VM VirtualBox</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>
    </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>=<arg><replaceable>prop-value</replaceable></arg></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg>
      <group choice="req">
        <arg choice="plain">deny</arg>
        <arg choice="plain">allow-vms</arg>
        <arg choice="plain">allow-all</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">natpf<replaceable>N</replaceable></arg>
      <group choice="req">
        <arg choice="plain">[<replaceable>rulename</replaceable>]<arg choice="plain">,tcp</arg></arg>
        <arg choice="plain">udp,<arg><replaceable>host-IP</replaceable></arg>,<arg choice="plain"><replaceable>hostport</replaceable>,</arg><arg><replaceable>guest-IP</replaceable></arg>,<arg choice="plain"><replaceable>guestport</replaceable></arg></arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg>

      <arg choice="req"><replaceable>rulename</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">guestmemoryballoon</arg>
      <arg choice="req"><replaceable>balloon-size</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">usbattach</arg>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>address</replaceable></arg>
      </group>
      <arg>--capturefile=<replaceable>filename</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">usbdetach</arg>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>address</replaceable></arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">audioin</arg>
      <group choice="req">
        <arg choice="plain">on</arg>
        <arg choice="plain">off</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">audioout</arg>
      <group choice="req">
        <arg choice="plain">on</arg>
        <arg choice="plain">off</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard">
      <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</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-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>=<arg><replaceable>prop-value</replaceable></arg></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">vrdevideochannelquality</arg>
      <arg choice="req"><replaceable>percentage</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">setvideomodehint</arg>
      <arg choice="req"><replaceable>xres</replaceable></arg>
      <arg choice="req"><replaceable>yres</replaceable></arg>
      <arg choice="req"><replaceable>bpp</replaceable></arg>
      <arg><arg><replaceable>display</replaceable></arg><group>
          <arg choice="plain">enabled:yes | no</arg>
          <arg><replaceable>x-origin</replaceable>&nbsp;<replaceable>y-origin</replaceable></arg>
        </group></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">setscreenlayout</arg>
      <arg choice="req"><replaceable>display</replaceable></arg>
      <group choice="req">
        <arg choice="plain">on</arg>
        <arg choice="plain">primary <replaceable>x-origin</replaceable>&nbsp;<replaceable>y-origin</replaceable>&nbsp;<replaceable>x-resolution</replaceable>&nbsp;<replaceable>y-resolution</replaceable>&nbsp;<replaceable>bpp</replaceable></arg>
        <arg choice="plain">off</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">screenshotpng</arg>
      <arg choice="req"><replaceable>filename</replaceable></arg>
      <arg><replaceable>display</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording</arg>
      <group choice="req">
        <arg choice="plain">on</arg>
        <arg choice="plain">off</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingscreens">
      <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</replaceable>,[<replaceable>screen</replaceable>...]</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingfilename">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording filename</arg>
      <arg choice="req">filename</arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideores">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording videores</arg>
      <arg choice="req"><replaceable>width</replaceable>x<replaceable>height</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideorate">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording videorate</arg>
      <arg choice="req"><replaceable>rate</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingvideofps">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording videofps</arg>
      <arg choice="req"><replaceable>fps</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxtime">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording maxtime</arg>
      <arg choice="req"><replaceable>sec</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-recordingmaxfilesize">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">recording maxfilesize</arg>
      <arg choice="req"><replaceable>MB</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-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-vmprocesspriority">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">vm-process-priority</arg>
      <group choice="req">
        <arg choice="plain">default</arg>
        <arg choice="plain">flat</arg>
        <arg choice="plain">low</arg>
        <arg choice="plain">normal</arg>
        <arg choice="plain">high</arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">webcam attach</arg>
      <arg><replaceable>pathname</replaceable><arg><replaceable>settings</replaceable></arg></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">webcam detach</arg>
      <arg><replaceable>pathname</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">webcam list</arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">addencpassword</arg>
      <arg choice="req"><replaceable>ID</replaceable></arg>
      <group choice="req">
        <arg choice="plain"><replaceable>password-file</replaceable></arg>
        <arg choice="plain">-</arg>
      </group>
      <arg>--removeonsuspend=<group choice="plain">
          <arg choice="plain">yes</arg>
          <arg choice="plain">no</arg>
        </group></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">removeencpassword</arg>
      <arg choice="req"><replaceable>ID</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">removeallencpasswords</arg>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode">
      <command>VBoxManage controlvm</command>
      <group choice="req">
        <arg choice="plain"><replaceable>uuid</replaceable></arg>
        <arg choice="plain"><replaceable>vmname</replaceable></arg>
      </group>
      <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg>
      <group choice="plain">
        <arg choice="plain">disconnected</arg>
        <arg choice="plain">server <replaceable>pipe-name</replaceable></arg>
        <arg choice="plain">client <replaceable>pipe-name</replaceable></arg>
        <arg choice="plain">tcpserver <replaceable>port</replaceable></arg>
        <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg>
        <arg choice="plain">file <replaceable>filename</replaceable></arg>
        <arg choice="plain"><replaceable>device-name</replaceable></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      The <command>VBoxManage controlvm</command> command enables you to
      change the state of a running virtual machine (VM). The following
      sections describe the subcommands that you can use:
    </para>
    <refsect2 id="vboxmanage-controlvm-pause">
      <title>Pause a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> pause</command> command
        temporarily stops the execution of a VM. When paused, the VM's
        state is not permanently changed.
      </para>
      <para>
        The VM window appears as gray and the title bar of the window
        indicates that the VM is currently Paused. This action is
        equivalent to selecting <emphasis role="bold">Pause</emphasis>
        from the <emphasis role="bold">Machine</emphasis> menu of the
        GUI.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-resume">
      <title>Resume a Paused Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> resume</command> command
        restarts the execution of a paused VM. This action is equivalent
        to selecting <emphasis role="bold">Resume</emphasis> from the
        <emphasis role="bold">Machine</emphasis> menu of the GUI.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-reset">
      <title>Reset a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> reset</command> command
        performs a cold reset the VM. This command has the same effect
        on a VM as pressing the Reset button on a physical computer.
      </para>
      <para>
        The cold reboot immediately restarts and reboots the guest
        operating system (OS). The state of the VM is not saved prior to
        the reset, so data might be lost. This action is equivalent to
        selecting <emphasis role="bold">Reset</emphasis> from the
        <emphasis role="bold">Machine</emphasis> menu of the GUI.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-poweroff">
      <title>Power Off a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> poweroff</command> command
        powers off the VM. This command has the same effect on a VM as
        pulling the power cable on a physical computer.
      </para>
      <para>
        The state of the VM is not saved prior to poweroff, so data
        might be lost. This action is equivalent to selecting
        <emphasis role="bold">Close</emphasis> from the
        <emphasis role="bold">Machine</emphasis> menu of the GUI or to
        clicking the VM window's Close button, and then selecting
        <emphasis role="bold">Power Off the Machine</emphasis>.
      </para>
      <para>
        When in the powered off state, you can restart the VM. See
        <xref linkend="vboxmanage-startvm" />.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-savestate">
      <title>Save the State of a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> savestate</command> command
        saves the current state of the VM to disk and then stops the VM.
      </para>
      <para>
        This action is equivalent to selecting
        <emphasis role="bold">Close</emphasis> from the
        <emphasis role="bold">Machine</emphasis> menu of the GUI or to
        clicking the VM window's Close button, and then selecting
        <emphasis role="bold">Save the Machine State</emphasis>.
      </para>
      <para>
        When in the powered off state, you can restart the VM.
      </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 ACPI support,
        this command triggers a proper shutdown mechanism 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 ACPI support,
        this command triggers a proper sleep mechanism from within the
        VM.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-reboot">
      <title>Reboot the guest OS</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> reboot</command>
        command asks the guest OS to reboot itself.
      </para>
      <para>
        This commands new recent Guest Additions installed.
      </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.
      </para>
      <para>
        This commands new recent Guest Additions installed.
      </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-teleport">
      <title>Configure a Virtual Machine Target for Teleporting</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> teleport</command> command
        initiates a teleporting operation between the specified VM and
        the specified host system. See <xref linkend="teleporting" />.
      </para>
      <para>
        If you specify a password, it must match the password you
        specified when you issued the <command>VBoxManage
        modifyvm</command> command for the target machine.
      </para>
      <variablelist>
        <varlistentry>
          <term><option>--host=<replaceable>hostname</replaceable></option></term>
          <listitem><para>
              Specifies the name of the VM.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--port=<replaceable>port</replaceable></option></term>
          <listitem><para>
              Specifies the port on the VM that should listen for a
              teleporting request from other VMs. The port number can be
              any free TCP/IP port number, such as
              <literal>6000</literal>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--maxdowntime=<replaceable>msec</replaceable></option></term>
          <listitem><para>
              Specifies the maximum downtime, in milliseconds, for the
              teleporting target VM.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--password=<replaceable>password</replaceable></option></term>
          <listitem><para>
              Specifies the password that the source machine uses for
              the teleporting request. The request succeeds only if the
              source machine specifies the same password.
            </para><remark>
              This design does not conform to Oracle's security
              guidelines. You should not be able to specify a password
              on the command line because the password can be seen in a
              process listing.
            </remark><para>
              The <option>--password</option> is mutually exclusive with
              the <option>--passwordfile</option> option.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--passwordfile=<replaceable>filename</replaceable></option></term>
          <listitem><para>
              Specifies the file from which to obtain the password that
              the source machine uses for the teleporting request. The
              request succeeds only if the source machine specifies the
              same password.
            </para><para>
              When you specify a file name of <literal>stdin</literal>,
              you can read the password from standard input.
            </para><para>
              The <option>--passwordfile</option> is mutually exclusive
              with the <option>--password</option> option.
            </para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-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>
      <para>
        Before connecting the virtual network cable, use the
        <command>VBoxManage controlvm
        nictracefile<replaceable>N</replaceable></command> command at
        runtime to specify the name of the file in which to log the
        trace. Otherwise, use the <command>VBoxManage modifyvm
        --nictracefile<replaceable>N</replaceable>=<replaceable>filename</replaceable></command>
        command to specify the name of the file.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </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>
        When set to <literal>on</literal>, use the same value of
        <replaceable>N</replaceable> for the <command>VBoxManage
        controlvm <replaceable>vmname</replaceable>
        nictracefile<replaceable>N</replaceable></command> command that
        you use to specify the path name to the log file in which to
        write trace output.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>. Ensure that you use
        the same value of <replaceable>N</replaceable> as you used for
        the <command>VBoxManage controlvm
        <replaceable>vmname</replaceable>
        nic<replaceable>N</replaceable></command> and
        <command>VBoxManage controlvm <replaceable>vmname</replaceable>
        nictrace<replaceable>N</replaceable></command> commands.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-nicproperty">
      <title>Specify the Network Backend Property Values for a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable>
        nicproperty<replaceable>N</replaceable>
        <replaceable>prop-name</replaceable>="<replaceable>prop-value</replaceable>"</command>
        command, in combination with <literal>nicgenericdrv</literal>,
        enables you to pass property values to rarely-used network
        backends.
      </para>
      <para>
        Those properties are backend engine-specific, and are different
        between UDP Tunnel and the VDE backend drivers. See
        <xref linkend="network_udp_tunnel" />.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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> deletes the
        specified NAT port-forwarding rule. See
        <xref linkend="natforward"/>.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-clipboard">
      <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</command> command
        specifies how to share the guest or host OS's clipboard with the
        host system or VM. Valid values are <literal>disabled</literal>,
        <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
        and <literal>bidirectional</literal>. The default value is
        <literal>disabled</literal>. See
        <xref linkend="generalsettings" />.
      </para>
      <para>
        This feature requires that the &product-name; Guest Additions
        are installed in the VM.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-draganddrop">
      <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> draganddrop</command> command
        specifies the current drag and drop mode to use between the host
        system and the VM. Valid values are <literal>disabled</literal>,
        <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
        and <literal>bidirectional</literal>. The default value is
        <literal>disabled</literal>. See
        <xref linkend="guestadd-dnd" />.
      </para>
      <para>
        This feature requires that the &product-name; Guest Additions
        are installed in the VM.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-vrdeport">
      <title>Specify VRDE Server Ports</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> vrdeport</command> command
        specifies the port or range of ports to which the VRDE server
        can bind. The default value is <literal>default</literal> or
        <literal>0</literal>, which is the standard RDP port,
        <literal>3389</literal>.
      </para>
      <para>
        Also see the <option>--vrdeport</option> option description in
        <xref linkend="vboxmanage-modifyvm" />.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
      <itemizedlist>
        <listitem><para>
            <literal>TCP/Ports</literal> specifies a port or a range of
            ports to which the VRDE server can bind. The default value
            is <literal>default</literal> or <literal>0</literal>, which
            is the standard RDP port, <literal>3389</literal>.
          </para><para>
            Also see the <option>--vrdeport</option> option description
            in <xref linkend="vboxmanage-modifyvm" />.
          </para></listitem>
        <listitem><para>
            <literal>TCP/Address</literal> specifies the IP address of
            the host network interface to which the VRDE server binds.
            When specified, the server accepts to connect only on the
            specified host network interface.
          </para><para>
            Also see the <option>--vrdeaddress</option> option
            description in <xref linkend="vboxmanage-modifyvm" />.
          </para></listitem>
        <listitem><para>
            <literal>VideoChannel/Enabled</literal> specifies whether to
            enable the VirtualBox Remote Desktop Protocol (VRDP) video
            channel. Valid values are <literal>1</literal> to enable the
            video channel and <literal>0</literal> to disable the video
            channel. The default value is <literal>off</literal>. See
            <xref linkend="vrde-videochannel" />.
          </para></listitem>
        <listitem><para>
            <literal>VideoChannel/Quality</literal> specifies the JPEG
            compression level on the VRDE server video channel. Valid
            values are between 10% and 100%, inclusive. Lower values
            mean lower quality but higher compression. The default value
            is <literal>100</literal>. See
            <xref linkend="vrde-videochannel" />.
          </para></listitem>
        <listitem><para>
            <literal>VideoChannel/DownscaleProtection</literal>
            specifies whether to enable the video channel downscale
            protection feature. Specify <literal>1</literal> to enable
            the feature. This feature is disabled by default.
          </para><para>
            When enabled, if the video's size equals the shadow buffer
            size, the video is shown in full-screen mode. If the video's
            size is between full-screen mode and the downscale
            threshold, the video is not shown as it might be an
            application window that is unreadable when downscaled. When
            disabled, the downscale protection feature always attempts
            to show videos.
          </para></listitem>
        <listitem><para>
            <literal>Client/DisableDisplay</literal> specifies whether
            to disable the VRDE server display feature. Valid values are
            <literal>1</literal> to disable the feature and null
            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
            The default value is null. 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 null
            (<literal>&ldquo;&rdquo;</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 null
            (<literal>&ldquo;&rdquo;</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 null
            (<literal>&ldquo;&rdquo;</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 null
            (<literal>&ldquo;&rdquo;</literal>) to enable the feature.
            To reenable the feature, use
            <literal>Client/DisableClipboard=</literal>. The default
            value is <literal>1</literal>. See
            <xref linkend="vrde-customization"/>.
          </para></listitem>
        <listitem><para>
            <literal>Client/DisableUpstreamAudio</literal> specifies
            whether to disable the VRDE upstream audio feature. Valid
            values are <literal>1</literal> to disable the feature and
            null (<literal>&ldquo;&rdquo;</literal>) to enable the
            feature. To reenable the feature, use
            <literal>Client/DisableUpstreamAudio=</literal>. The default
            value is <literal>1</literal>. See
            <xref linkend="vrde-customization"/>.
          </para></listitem>
        <listitem><para>
            <literal>Client/DisableRDPDR</literal> specifies whether to
            disable the RDP Device Redirection For Smart Cards feature
            on the VRDE server. Valid values are <literal>1</literal> to
            disable the feature and null
            (<literal>&ldquo;&rdquo;</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 null
            (<literal>&ldquo;&rdquo;</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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
      <itemizedlist>
        <listitem><para>
            <replaceable>filename</replaceable> specifies the name of
            the PNG file to create.
          </para></listitem>
        <listitem><para>
            <replaceable>display</replaceable> specifies the display
            number for the screen shot. For a single monitor guest
            display, this is <literal>0</literal>.
          </para></listitem>
      </itemizedlist>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recording">
      <title>Enable or Disable the Recording of a Virtual Machine Session</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording</command> command
        enables or disables the recording of a VM session into a
        WebM/VP8 file. Valid values are <literal>on</literal>, which
        begins recording when the VM session starts and
        <literal>off</literal>, which disables recording. The default
        value is <literal>off</literal>.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingscreens">
      <title>Specify the Virtual Machine Screens to Record</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording screens</command>
        command enables you to specify which VM screens to record. The
        recording for each screen that you specify is saved to its own
        file in the machine folder. You cannot modify this setting while
        recording is enabled.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
      <itemizedlist>
        <listitem><para>
            <literal>all</literal> specifies that you record all VM
            screens.
          </para></listitem>
        <listitem><para>
            <literal>none</literal> specifies that you do not record any
            VM screens.
          </para></listitem>
        <listitem><para>
            <replaceable>screen-ID</replaceable> specifies one or more
            VM screens to record.
          </para></listitem>
      </itemizedlist>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingfilename">
      <title>Specify the File in Which to Save Virtual Machine Recording</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording filename</command>
        command specifies the file in which to save the recording. You
        cannot modify this setting while recording is enabled.
      </para>
      <para>
        The default setting is to store a recording in the machine
        folder, using the VM name as the file name, with a
        <filename>webm</filename> file name extension.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingvideores">
      <title>Specify the Resolution of the Recorded Video</title>
      <remark role="help-copy-synopsis"/>
      <para>
        <command>VBoxManage controlvm <replaceable>vmname</replaceable>
        recording videores</command> command specifies the resolution of
        the recorded video in pixels. You cannot modify this setting
        while recording is enabled.
      </para>
      <para>
        Use the Settings tool to view the video recording settings,
        which are based on the resolution (frame size). See the Frame
        Size field on the Recording tab of the Display page to view the
        default value.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
      <para>
        Specify the resolution as
        <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>:
      </para>
      <itemizedlist>
        <listitem><para>
            <replaceable>width</replaceable> specifies the width in
            pixels.
          </para></listitem>
        <listitem><para>
            <replaceable>height</replaceable> specifies the height in
            pixels.
          </para></listitem>
      </itemizedlist>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingvideorate">
      <title>Specify the Bit Rate of the Video</title>
      <remark role="help-copy-synopsis"/>
<!-- @todo r=andy Clarify rate. -->
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording videorate</command>
        command specifies the bit rate,
        <replaceable>bit-rate</replaceable>, of the video in kilobits
        per second. Increasing this value improves the appearance of the
        video at the cost of an increased file size. You cannot modify
        this setting while recording is enabled.
      </para>
      <para>
        Use the Settings tool to view the video recording settings,
        which are based on the frame size. See the Video Quality field
        on the Recording tab of the Display page to view the default
        value.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingvideofps">
      <title>Specify the Maximum Frequency of the Video</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording videofps</command>
        command specifies the maximum frequency of the video to record.
        Video frequency is measured in frames per second (FPS). The
        recording skips any frames that have a frequency higher than the
        specified maximum. Increasing the frequency reduces the number
        of skipped frames and increases the file size. You cannot modify
        this setting while recording is enabled.
      </para>
      <para>
        Use the Settings tool to view the video recording settings,
        which are based on the frame size. See the Frame Rate field on
        the Recording tab of the Display page to view the default value.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingmaxtime">
      <title>Specify the Maximum Amount of Time to Record Video</title>
      <remark role="help-copy-synopsis"/>
<!-- @todo r=andy Clarify time format. -->
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording maxtime</command>
        command specifies the maximum amount time to record in seconds.
        The recording stops after the specified number of seconds
        elapses. If this value is zero, the recording continues until
        you stop the recording.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-recordingmaxfilesize">
      <title>Specify the Maximum Size of the Recorded Video</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> recording
        maxfilesize</command> command specifies the maximum size of the
        recorded video file in megabytes. The recording stops when the
        file reaches the specified size. If this value is zero, the
        recording continues until you stop the recording. You cannot
        modify this setting while recording is enabled.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
      <itemizedlist>
        <listitem><para>
            <replaceable>username</replaceable> specifies the user name
            with which to log in to the Windows VM.
          </para></listitem>
        <listitem><para>
            <option>--passwordfile=<replaceable>filename</replaceable></option>
            specifies the file from which to obtain the password for
            <replaceable>username</replaceable>.
          </para><para>
            The <option>--passwordfile</option> is mutually exclusive
            with the <option>--password</option> option.
          </para></listitem>
        <listitem><para>
            <option>--password=<replaceable>password</replaceable></option>
            specifies the password for
            <replaceable>username</replaceable>.
          </para><remark>
            This design does not conform to Oracle's security
            guidelines. You should not be able to specify a password on
            the command line because the password can be seen in a
            process listing.
          </remark><para>
            The <option>--password</option> is mutually exclusive with
            the <option>--passwordfile</option> option.
          </para></listitem>
        <listitem><para>
            <option>--allowlocallogin</option> specifies whether to
            enable or disable local logins. Valid values are
            <literal>on</literal> to enable local logins and
            <literal>off</literal> to disable local logins.
          </para></listitem>
      </itemizedlist>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-cpuexecutioncap">
      <title>Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> cpuexecutioncap</command>
        command specifies how the maximum amount of physical CPU time
        used by a virtual CPU. Valid values are a percentage between
        <literal>1</literal> and <literal>100</literal>. A value of
        <literal>50</literal> specifies that a single virtual CPU can
        use up to 50% of a physical CPU. The default value is
        <literal>100</literal>.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-vmprocesspriority">
      <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 <literal>default</literal>,
        <literal>flat</literal>, <literal>low</literal>,
        <literal>normal</literal>, and <literal>high</literal>.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-webcam-attach">
      <title>Attach a Webcam to a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> webcam attach</command>
        command attaches a webcam to a running VM. Specify the webcam as
        the absolute path of the webcam on the host OS or as an alias.
        Use the <command>VBoxManage list webcams</command> command to
        obtain the webcam alias.
      </para>
      <para>
        Note that the <literal>.0</literal> alias is the default video
        input device on the host OS. <literal>.1</literal> is the first
        video input device, <literal>.2</literal> is the second video
        input device, and so on. The order of the devices is specific to
        the host system.
      </para>
      <para>
        You can specify optional settings in the form of
        semi-colon-separated (<literal>;</literal>) name-value pairs.
        These properties enable you to configure the emulated webcam
        device.
      </para>
      <para>
        The following settings are supported:
      </para>
      <variablelist>
        <varlistentry>
          <term><literal>MaxFramerate</literal></term>
          <listitem><para>
              Specifies the highest rate at which to send video frames
              to the VM. The rate is in frames per second. Higher frame
              rates increase CPU load, so you can use this setting to
              reduce CPU load. The default value is <literal>no maximum
              limit</literal>. This value enables the VM to use any
              frame rate supported by the webcam.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>MaxPayloadTransferSize</literal></term>
          <listitem><para>
              Specifies the maximum number of bytes that the VM receives
              from the emulated webcam in one buffer. The default
              setting is <literal>3060</literal> bytes, which is used by
              some webcams. If the VM is able to use larger buffers,
              higher values might reduce CPU load slightly. Note that
              some guest OSes might not suppport higher
              <literal>MaxPayloadTransferSize</literal> values.
            </para></listitem>
        </varlistentry>
      </variablelist>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-webcam-detach">
      <title>Detach a Webcam From a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> webcam detach</command>
        command detaches a webcam from a running VM. Specify the webcam
        as the absolute path of the webcam on the host OS or as an
        alias. Use the <command>VBoxManage list webcams</command> to
        obtain the webcam alias.
      </para>
      <para>
        When a webcam device is detached from the host, the host OS
        determines how the emulated webcam behaves.
      </para>
      <itemizedlist>
        <listitem><para>
            <emphasis role="bold">Windows hosts:</emphasis> The emulated
            webcam device is detached from the VM automatically.
          </para></listitem>
        <listitem><para>
            <emphasis role="bold">Mac OS X hosts that run at least OS X
            10.7:</emphasis> The emulated webcam device remains attached
            to the VM and you must detach it manually by using the
            <command>VBoxManage controlvm webcam detach</command>
            command.
          </para></listitem>
        <listitem><para>
            <emphasis role="bold">Linux hosts:</emphasis> The emulated
            webcam device is detached from the VM automatically only if
            the webcam is actively streaming video. If the emulated
            webcam is inactive, manually detach it by using the
            <command>VBoxManage controlvm
            <replaceable>vmname</replaceable> webcam detach</command>
            command.
          </para></listitem>
      </itemizedlist>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-webcam-list">
      <title>List the Webcams Attached to a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> webcam list</command> command
        lists webcams that are attached to the running VM. The output
        shows a list of absolute paths or aliases that attached the
        webcams to the VM by using the <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> webcam attach</command>
        command.
      </para>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-controlvm-addencpassword">
      <title>Set an Encryption Password for a Virtual Machine</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage controlvm
        <replaceable>vmname</replaceable> addencpassword</command>
        command provides the <replaceable>vmname</replaceable> encrypted
        VM with the encryption password to enable a headless start.
        Specify the absolute path of a password file on the host system.
        If <replaceable>filename</replaceable> is <literal>-</literal>,
        <command>VBoxManage</command> prompts for the encryption
        password.
      </para>
      <para>
        Use the <option>--removeonsuspend</option> option to specify
        whether to save the passsword or clear it from VM memory when
        the VM is suspended.
      </para>
      <para>
        If the VM is suspended and the password is cleared, use the
        <command>VBoxManage controlvm <replaceable>vmname</replaceable>
        addencpassword</command> to provide the password to resume
        execution on the VM. Use this feature when you do not want to
        store the password in VM memory while the VM is suspended by a
        host suspend event.
      </para>
      <note>
        <para>
          You can encrypt data stored on hard disk images used by the
          VM. &product-name; uses the AES algorithm in XTS mode and
          supports 128-bit or 256-bit data encryption keys (DEK). The
          encrypted DEK is stored in the medium properties and is
          decrypted during VM startup when you provide the encryption
          password.
        </para>
      </note>
      <para>
        Use the <command>VBoxManage encryptmedium</command> command to
        create a DEK encrypted medium. See
        <xref linkend="diskencryption-encryption" />.
      </para>
      <para>
        The &product-name; GUI prompts you for the encryption password
        when you start an encrypted VM.
      </para>
      <para>
        Use the following command to perform a headless start of an
        encrypted VM:
      </para>
<screen>
          $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless
        </screen>
      <para>
        Then, use the following command to provide the encryption
        password:
      </para>
<screen>
          $ VBoxManage <replaceable>vmname</replaceable> controlvm addencpassword <replaceable>vmname</replaceable> -
          Password: <replaceable>encryption-password</replaceable>
        </screen>
      <para>
        This subcommand does not affect the VM's running state directly.
      </para>
    </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
      <para>
        This subcommand does not affect the VM's running state directly.
      </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>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <remark role="help-scope" condition="GLOBAL" />
    <para>
      The following command temporarily stops the execution of the
      <filename>ol7</filename> VM.
    </para>
<screen>$ VBoxManage controlvm ol7 pause</screen>
    <para>
      The following command configures shared clipboard operation for
      the <filename>ol7</filename> VM. Copying of clipboard data is
      allowed in both directions between the host and guest.
    </para>
<screen>$ VBoxManage controlvm ol7 clipboard bidirectional</screen>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <xref linkend="vboxmanage-list" />,
      <xref linkend="vboxmanage-modifyvm" />,
      <xref linkend="vboxmanage-startvm" />
    </para>
  </refsect1>
</refentry>