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