VirtualBox

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

Last change on this file since 103131 was 99513, checked in by vboxsync, 19 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 91.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage controlvm
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="vboxmanage-controlvm" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 21:59:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage controlvm</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-controlvm</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-controlvm</refname>
44 <refpurpose>change state and settings for a running virtual machine</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-controlvm-pause">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage controlvm</command>
52 <group choice="req">
53 <arg choice="plain"><replaceable>uuid</replaceable></arg>
54 <arg choice="plain"><replaceable>vmname</replaceable></arg>
55 </group>
56 <arg choice="plain">pause</arg>
57 </cmdsynopsis>
58
59 <cmdsynopsis id="synopsis-vboxmanage-controlvm-resume">
60 <command>VBoxManage controlvm</command>
61 <group choice="req">
62 <arg choice="plain"><replaceable>uuid</replaceable></arg>
63 <arg choice="plain"><replaceable>vmname</replaceable></arg>
64 </group>
65 <arg choice="plain">resume</arg>
66 </cmdsynopsis>
67
68 <cmdsynopsis id="synopsis-vboxmanage-controlvm-reset">
69 <command>VBoxManage controlvm</command>
70 <group choice="req">
71 <arg choice="plain"><replaceable>uuid</replaceable></arg>
72 <arg choice="plain"><replaceable>vmname</replaceable></arg>
73 </group>
74 <arg choice="plain">reset</arg>
75 </cmdsynopsis>
76
77 <cmdsynopsis id="synopsis-vboxmanage-controlvm-poweroff">
78 <command>VBoxManage controlvm</command>
79 <group choice="req">
80 <arg choice="plain"><replaceable>uuid</replaceable></arg>
81 <arg choice="plain"><replaceable>vmname</replaceable></arg>
82 </group>
83 <arg choice="plain">poweroff</arg>
84 </cmdsynopsis>
85
86 <cmdsynopsis id="synopsis-vboxmanage-controlvm-savestate">
87 <command>VBoxManage controlvm</command>
88 <group choice="req">
89 <arg choice="plain"><replaceable>uuid</replaceable></arg>
90 <arg choice="plain"><replaceable>vmname</replaceable></arg>
91 </group>
92 <arg choice="plain">savestate</arg>
93 </cmdsynopsis>
94
95 <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpipowerbutton">
96 <command>VBoxManage controlvm</command>
97 <group choice="req">
98 <arg choice="plain"><replaceable>uuid</replaceable></arg>
99 <arg choice="plain"><replaceable>vmname</replaceable></arg>
100 </group>
101 <arg choice="plain">acpipowerbutton</arg>
102 </cmdsynopsis>
103
104 <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpisleepbutton">
105 <command>VBoxManage controlvm</command>
106 <group choice="req">
107 <arg choice="plain"><replaceable>uuid</replaceable></arg>
108 <arg choice="plain"><replaceable>vmname</replaceable></arg>
109 </group>
110 <arg choice="plain">acpisleepbutton</arg>
111 </cmdsynopsis>
112
113 <cmdsynopsis id="synopsis-vboxmanage-controlvm-reboot">
114 <command>VBoxManage controlvm</command>
115 <group choice="req">
116 <arg choice="plain"><replaceable>uuid</replaceable></arg>
117 <arg choice="plain"><replaceable>vmname</replaceable></arg>
118 </group>
119 <arg choice="plain">reboot</arg>
120 </cmdsynopsis>
121
122 <cmdsynopsis id="synopsis-vboxmanage-controlvm-shutdown">
123 <command>VBoxManage controlvm</command>
124 <group choice="req">
125 <arg choice="plain"><replaceable>uuid</replaceable></arg>
126 <arg choice="plain"><replaceable>vmname</replaceable></arg>
127 </group>
128 <arg choice="plain">shutdown</arg>
129 <arg choice="opt">--force</arg>
130 </cmdsynopsis>
131
132 <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputscancode">
133 <command>VBoxManage controlvm</command>
134 <group choice="req">
135 <arg choice="plain"><replaceable>uuid</replaceable></arg>
136 <arg choice="plain"><replaceable>vmname</replaceable></arg>
137 </group>
138 <arg choice="plain">keyboardputscancode</arg>
139 <arg choice="req"><replaceable>hex</replaceable></arg>
140 <arg rep="repeat"><replaceable>hex</replaceable></arg>
141 </cmdsynopsis>
142
143 <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputstring">
144 <command>VBoxManage controlvm</command>
145 <group choice="req">
146 <arg choice="plain"><replaceable>uuid</replaceable></arg>
147 <arg choice="plain"><replaceable>vmname</replaceable></arg>
148 </group>
149 <arg choice="plain">keyboardputstring</arg>
150 <arg choice="req"><replaceable>string</replaceable></arg>
151 <arg rep="repeat"><replaceable>string</replaceable></arg>
152 </cmdsynopsis>
153
154 <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputfile">
155 <command>VBoxManage controlvm</command>
156 <group choice="req">
157 <arg choice="plain"><replaceable>uuid</replaceable></arg>
158 <arg choice="plain"><replaceable>vmname</replaceable></arg>
159 </group>
160 <arg choice="plain">keyboardputfile</arg>
161 <arg choice="req"><replaceable>filename</replaceable></arg>
162 </cmdsynopsis>
163
164 <cmdsynopsis id="synopsis-vboxmanage-controlvm-setlinkstate">
165 <command>VBoxManage controlvm</command>
166 <group choice="req">
167 <arg choice="plain"><replaceable>uuid</replaceable></arg>
168 <arg choice="plain"><replaceable>vmname</replaceable></arg>
169 </group>
170 <arg choice="plain">setlinkstate<replaceable>N</replaceable></arg>
171 <group choice="req">
172 <arg choice="plain">on</arg>
173 <arg choice="plain">off</arg>
174 </group>
175 </cmdsynopsis>
176
177 <cmdsynopsis id="synopsis-vboxmanage-controlvm-nic">
178 <command>VBoxManage controlvm</command>
179 <group choice="req">
180 <arg choice="plain"><replaceable>uuid</replaceable></arg>
181 <arg choice="plain"><replaceable>vmname</replaceable></arg>
182 </group>
183 <arg choice="plain">nic<replaceable>N</replaceable></arg>
184 <group choice="req">
185 <arg choice="plain">null</arg>
186 <arg choice="plain">nat</arg>
187 <arg choice="plain">bridged</arg>
188 <arg choice="plain">intnet</arg>
189 <arg choice="plain">hostonly</arg>
190 <arg choice="plain">generic</arg>
191 <arg choice="plain">natnetwork</arg>
192 </group>
193 <arg><replaceable>device-name</replaceable></arg>
194 </cmdsynopsis>
195
196 <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictrace">
197 <command>VBoxManage controlvm</command>
198 <group choice="req">
199 <arg choice="plain"><replaceable>uuid</replaceable></arg>
200 <arg choice="plain"><replaceable>vmname</replaceable></arg>
201 </group>
202 <arg choice="plain">nictrace<replaceable>N</replaceable></arg>
203 <group choice="req">
204 <arg choice="plain">on</arg>
205 <arg choice="plain">off</arg>
206 </group>
207 </cmdsynopsis>
208
209 <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictracefile">
210 <command>VBoxManage controlvm</command>
211 <group choice="req">
212 <arg choice="plain"><replaceable>uuid</replaceable></arg>
213 <arg choice="plain"><replaceable>vmname</replaceable></arg>
214 </group>
215 <arg choice="plain">nictracefile<replaceable>N</replaceable></arg>
216 <arg choice="req"><replaceable>filename</replaceable></arg>
217 </cmdsynopsis>
218
219 <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicproperty">
220 <command>VBoxManage controlvm</command>
221 <group choice="req">
222 <arg choice="plain"><replaceable>uuid</replaceable></arg>
223 <arg choice="plain"><replaceable>vmname</replaceable></arg>
224 </group>
225 <arg choice="plain">nicproperty<replaceable>N</replaceable></arg>
226 <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg>
227 </cmdsynopsis>
228
229 <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc">
230 <command>VBoxManage controlvm</command>
231 <group choice="req">
232 <arg choice="plain"><replaceable>uuid</replaceable></arg>
233 <arg choice="plain"><replaceable>vmname</replaceable></arg>
234 </group>
235 <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg>
236 <group choice="req">
237 <arg choice="plain">deny</arg>
238 <arg choice="plain">allow-vms</arg>
239 <arg choice="plain">allow-all</arg>
240 </group>
241 </cmdsynopsis>
242
243 <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf">
244 <command>VBoxManage controlvm</command>
245 <group choice="req">
246 <arg choice="plain"><replaceable>uuid</replaceable></arg>
247 <arg choice="plain"><replaceable>vmname</replaceable></arg>
248 </group>
249 <arg choice="plain">natpf<replaceable>N</replaceable></arg>
250
251 <arg choice="req" role="compact"><arg><replaceable>rulename</replaceable></arg>,<group choice="req"><arg choice="plain">tcp</arg><arg choice="plain">udp</arg></group>,<arg><replaceable>host-IP</replaceable></arg>,<arg choice="plain"><replaceable>hostport</replaceable></arg>,<arg><replaceable>guest-IP</replaceable></arg>,<arg choice="plain"><replaceable>guestport</replaceable></arg></arg>
252 </cmdsynopsis>
253
254 <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete">
255 <command>VBoxManage controlvm</command>
256 <group choice="req">
257 <arg choice="plain"><replaceable>uuid</replaceable></arg>
258 <arg choice="plain"><replaceable>vmname</replaceable></arg>
259 </group>
260 <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg>
261
262 <arg choice="req"><replaceable>rulename</replaceable></arg>
263 </cmdsynopsis>
264
265 <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon">
266 <command>VBoxManage controlvm</command>
267 <group choice="req">
268 <arg choice="plain"><replaceable>uuid</replaceable></arg>
269 <arg choice="plain"><replaceable>vmname</replaceable></arg>
270 </group>
271 <arg choice="plain">guestmemoryballoon</arg>
272 <arg choice="req"><replaceable>balloon-size</replaceable></arg>
273 </cmdsynopsis>
274
275 <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach">
276 <command>VBoxManage controlvm</command>
277 <group choice="req">
278 <arg choice="plain"><replaceable>uuid</replaceable></arg>
279 <arg choice="plain"><replaceable>vmname</replaceable></arg>
280 </group>
281 <arg choice="plain">usbattach</arg>
282 <group choice="req">
283 <arg choice="plain"><replaceable>uuid</replaceable></arg>
284 <arg choice="plain"><replaceable>address</replaceable></arg>
285 </group>
286 <arg>--capturefile=<replaceable>filename</replaceable></arg>
287 </cmdsynopsis>
288
289 <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach">
290 <command>VBoxManage controlvm</command>
291 <group choice="req">
292 <arg choice="plain"><replaceable>uuid</replaceable></arg>
293 <arg choice="plain"><replaceable>vmname</replaceable></arg>
294 </group>
295 <arg choice="plain">usbdetach</arg>
296 <group choice="req">
297 <arg choice="plain"><replaceable>uuid</replaceable></arg>
298 <arg choice="plain"><replaceable>address</replaceable></arg>
299 </group>
300 </cmdsynopsis>
301
302 <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin">
303 <command>VBoxManage controlvm</command>
304 <group choice="req">
305 <arg choice="plain"><replaceable>uuid</replaceable></arg>
306 <arg choice="plain"><replaceable>vmname</replaceable></arg>
307 </group>
308 <arg choice="plain">audioin</arg>
309 <group choice="req">
310 <arg choice="plain">on</arg>
311 <arg choice="plain">off</arg>
312 </group>
313 </cmdsynopsis>
314
315 <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout">
316 <command>VBoxManage controlvm</command>
317 <group choice="req">
318 <arg choice="plain"><replaceable>uuid</replaceable></arg>
319 <arg choice="plain"><replaceable>vmname</replaceable></arg>
320 </group>
321 <arg choice="plain">audioout</arg>
322 <group choice="req">
323 <arg choice="plain">on</arg>
324 <arg choice="plain">off</arg>
325 </group>
326 </cmdsynopsis>
327
328 <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode">
329 <command>VBoxManage controlvm</command>
330 <group choice="req">
331 <arg choice="plain"><replaceable>uuid</replaceable></arg>
332 <arg choice="plain"><replaceable>vmname</replaceable></arg>
333 </group>
334 <arg choice="plain">clipboard mode</arg>
335 <group choice="req">
336 <arg choice="plain">disabled</arg>
337 <arg choice="plain">hosttoguest</arg>
338 <arg choice="plain">guesttohost</arg>
339 <arg choice="plain">bidirectional</arg>
340 </group>
341 </cmdsynopsis>
342
343 <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-filetransfers">
344 <command>VBoxManage controlvm</command>
345 <group choice="req">
346 <arg choice="plain"><replaceable>uuid</replaceable></arg>
347 <arg choice="plain"><replaceable>vmname</replaceable></arg>
348 </group>
349 <arg choice="plain">clipboard filetransfers</arg>
350 <group choice="req">
351 <arg choice="plain">on</arg>
352 <arg choice="plain">off</arg>
353 </group>
354 </cmdsynopsis>
355
356 <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop">
357 <command>VBoxManage controlvm</command>
358 <group choice="req">
359 <arg choice="plain"><replaceable>uuid</replaceable></arg>
360 <arg choice="plain"><replaceable>vmname</replaceable></arg>
361 </group>
362 <arg choice="plain">draganddrop</arg>
363 <group choice="req">
364 <arg choice="plain">disabled</arg>
365 <arg choice="plain">hosttoguest</arg>
366 <arg choice="plain">guesttohost</arg>
367 <arg choice="plain">bidirectional</arg>
368 </group>
369 </cmdsynopsis>
370
371 <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrde">
372 <command>VBoxManage controlvm</command>
373 <group choice="req">
374 <arg choice="plain"><replaceable>uuid</replaceable></arg>
375 <arg choice="plain"><replaceable>vmname</replaceable></arg>
376 </group>
377 <arg choice="plain">vrde</arg>
378 <group choice="req">
379 <arg choice="plain">on</arg>
380 <arg choice="plain">off</arg>
381 </group>
382 </cmdsynopsis>
383
384 <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeport">
385 <command>VBoxManage controlvm</command>
386 <group choice="req">
387 <arg choice="plain"><replaceable>uuid</replaceable></arg>
388 <arg choice="plain"><replaceable>vmname</replaceable></arg>
389 </group>
390 <arg choice="plain">vrdeport</arg>
391 <arg choice="req"><replaceable>port</replaceable></arg>
392 </cmdsynopsis>
393
394 <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeproperty">
395 <command>VBoxManage controlvm</command>
396 <group choice="req">
397 <arg choice="plain"><replaceable>uuid</replaceable></arg>
398 <arg choice="plain"><replaceable>vmname</replaceable></arg>
399 </group>
400 <arg choice="plain">vrdeproperty</arg>
401 <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg>
402 </cmdsynopsis>
403
404 <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality">
405 <command>VBoxManage controlvm</command>
406 <group choice="req">
407 <arg choice="plain"><replaceable>uuid</replaceable></arg>
408 <arg choice="plain"><replaceable>vmname</replaceable></arg>
409 </group>
410 <arg choice="plain">vrdevideochannelquality</arg>
411 <arg choice="req"><replaceable>percentage</replaceable></arg>
412 </cmdsynopsis>
413
414 <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint">
415 <command>VBoxManage controlvm</command>
416 <group choice="req">
417 <arg choice="plain"><replaceable>uuid</replaceable></arg>
418 <arg choice="plain"><replaceable>vmname</replaceable></arg>
419 </group>
420 <arg choice="plain">setvideomodehint</arg>
421 <arg choice="req"><replaceable>xres</replaceable></arg>
422 <arg choice="req"><replaceable>yres</replaceable></arg>
423 <arg choice="req"><replaceable>bpp</replaceable></arg>
424 <arg>
425 <replaceable>display</replaceable>
426 <arg>
427 <group choice="req">
428 <arg choice="plain">yes</arg>
429 <arg choice="plain">no</arg>
430 </group>
431 <arg>
432 <arg choice="plain"><replaceable>x-origin</replaceable></arg>
433 <arg choice="plain"><replaceable>y-origin</replaceable></arg>
434 </arg>
435 </arg>
436 </arg>
437 </cmdsynopsis>
438
439 <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout">
440 <command>VBoxManage controlvm</command>
441 <group choice="req">
442 <arg choice="plain"><replaceable>uuid</replaceable></arg>
443 <arg choice="plain"><replaceable>vmname</replaceable></arg>
444 </group>
445 <arg choice="plain">setscreenlayout</arg>
446 <arg choice="req"><replaceable>display</replaceable></arg>
447 <group choice="req">
448 <arg choice="plain">on</arg>
449 <arg choice="plain">primary
450 <arg choice="req"><replaceable>x-origin</replaceable></arg>
451 <arg choice="req"><replaceable>y-origin</replaceable></arg>
452 <arg choice="req"><replaceable>x-resolution</replaceable></arg>
453 <arg choice="req"><replaceable>y-resolution</replaceable></arg>
454 <arg choice="req"><replaceable>bpp</replaceable></arg>
455 </arg>
456 <arg choice="plain">off</arg>
457 </group>
458 </cmdsynopsis>
459
460 <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng">
461 <command>VBoxManage controlvm</command>
462 <group choice="req">
463 <arg choice="plain"><replaceable>uuid</replaceable></arg>
464 <arg choice="plain"><replaceable>vmname</replaceable></arg>
465 </group>
466 <arg choice="plain">screenshotpng</arg>
467 <arg choice="req"><replaceable>filename</replaceable></arg>
468 <arg><replaceable>display</replaceable></arg>
469 </cmdsynopsis>
470
471 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording">
472 <command>VBoxManage controlvm</command>
473 <group choice="req">
474 <arg choice="plain"><replaceable>uuid</replaceable></arg>
475 <arg choice="plain"><replaceable>vmname</replaceable></arg>
476 </group>
477 <arg choice="plain">recording</arg>
478 <group choice="req">
479 <arg choice="plain">on</arg>
480 <arg choice="plain">off</arg>
481 </group>
482 </cmdsynopsis>
483
484 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens">
485 <command>VBoxManage controlvm</command>
486 <group choice="req">
487 <arg choice="plain"><replaceable>uuid</replaceable></arg>
488 <arg choice="plain"><replaceable>vmname</replaceable></arg>
489 </group>
490 <arg choice="plain">recording screens</arg>
491 <group choice="req">
492 <arg choice="plain">all</arg>
493 <arg choice="plain">none</arg>
494 <arg choice="plain"><replaceable>screen-ID</replaceable><arg rep="repeat">,<replaceable>screen-ID</replaceable></arg></arg>
495 </group>
496 </cmdsynopsis>
497
498 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename">
499 <command>VBoxManage controlvm</command>
500 <group choice="req">
501 <arg choice="plain"><replaceable>uuid</replaceable></arg>
502 <arg choice="plain"><replaceable>vmname</replaceable></arg>
503 </group>
504 <arg choice="plain">recording filename</arg>
505 <arg choice="req">filename</arg>
506 </cmdsynopsis>
507
508 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores">
509 <command>VBoxManage controlvm</command>
510 <group choice="req">
511 <arg choice="plain"><replaceable>uuid</replaceable></arg>
512 <arg choice="plain"><replaceable>vmname</replaceable></arg>
513 </group>
514 <arg choice="plain">recording videores</arg>
515 <arg choice="req"><arg choice="req"><replaceable>width</replaceable></arg>x<arg choice="req"><replaceable>height</replaceable></arg></arg>
516 </cmdsynopsis>
517
518 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate">
519 <command>VBoxManage controlvm</command>
520 <group choice="req">
521 <arg choice="plain"><replaceable>uuid</replaceable></arg>
522 <arg choice="plain"><replaceable>vmname</replaceable></arg>
523 </group>
524 <arg choice="plain">recording videorate</arg>
525 <arg choice="req"><replaceable>rate</replaceable></arg>
526 </cmdsynopsis>
527
528 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps">
529 <command>VBoxManage controlvm</command>
530 <group choice="req">
531 <arg choice="plain"><replaceable>uuid</replaceable></arg>
532 <arg choice="plain"><replaceable>vmname</replaceable></arg>
533 </group>
534 <arg choice="plain">recording videofps</arg>
535 <arg choice="req"><replaceable>fps</replaceable></arg>
536 </cmdsynopsis>
537
538 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime">
539 <command>VBoxManage controlvm</command>
540 <group choice="req">
541 <arg choice="plain"><replaceable>uuid</replaceable></arg>
542 <arg choice="plain"><replaceable>vmname</replaceable></arg>
543 </group>
544 <arg choice="plain">recording maxtime</arg>
545 <arg choice="req"><replaceable>sec</replaceable></arg>
546 </cmdsynopsis>
547
548 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize">
549 <command>VBoxManage controlvm</command>
550 <group choice="req">
551 <arg choice="plain"><replaceable>uuid</replaceable></arg>
552 <arg choice="plain"><replaceable>vmname</replaceable></arg>
553 </group>
554 <arg choice="plain">recording maxfilesize</arg>
555 <arg choice="req"><replaceable>MB</replaceable></arg>
556 </cmdsynopsis>
557
558 <!--
559 <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-opts">
560 <command>VBoxManage controlvm</command>
561 <group choice="req">
562 <arg choice="plain"><replaceable>uuid</replaceable></arg>
563 <arg choice="plain"><replaceable>vmname</replaceable></arg>
564 </group>
565 <arg choice="plain">recording opts</arg>
566 <arg choice="req"><replaceable>key</replaceable>=<arg><replaceable>value</replaceable></arg></arg>
567 </cmdsynopsis>
568 -->
569
570 <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials">
571 <command>VBoxManage controlvm</command>
572 <group choice="req">
573 <arg choice="plain"><replaceable>uuid</replaceable></arg>
574 <arg choice="plain"><replaceable>vmname</replaceable></arg>
575 </group>
576 <arg choice="plain">setcredentials</arg>
577 <arg choice="req"><replaceable>username</replaceable></arg>
578 <arg choice="plain">--passwordfile=<group choice="req">
579 <arg choice="plain"><replaceable>filename</replaceable></arg>
580 <arg choice="plain"><replaceable>password</replaceable></arg>
581 </group></arg>
582 <arg choice="req"><replaceable>domain-name</replaceable></arg>
583 <arg choice="plain">--allowlocallogon=<group choice="req">
584 <arg choice="plain">yes</arg>
585 <arg choice="plain">no</arg>
586 </group></arg>
587 </cmdsynopsis>
588
589 <cmdsynopsis id="synopsis-vboxmanage-controlvm-teleport">
590 <command>VBoxManage controlvm</command>
591 <group choice="req">
592 <arg choice="plain"><replaceable>uuid</replaceable></arg>
593 <arg choice="plain"><replaceable>vmname</replaceable></arg>
594 </group>
595 <arg choice="plain">teleport</arg>
596 <arg choice="req">--host=<replaceable>host-name</replaceable></arg>
597 <arg choice="req">--port=<replaceable>port-name</replaceable></arg>
598 <arg>--maxdowntime=<replaceable>msec</replaceable></arg>
599 <group>
600 <arg choice="plain">--passwordfile=<replaceable>filename</replaceable></arg>
601 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
602 </group>
603 </cmdsynopsis>
604
605 <cmdsynopsis id="synopsis-vboxmanage-controlvm-plugcpu">
606 <command>VBoxManage controlvm</command>
607 <group choice="req">
608 <arg choice="plain"><replaceable>uuid</replaceable></arg>
609 <arg choice="plain"><replaceable>vmname</replaceable></arg>
610 </group>
611 <arg choice="plain">plugcpu</arg>
612 <arg choice="req"><replaceable>ID</replaceable></arg>
613 </cmdsynopsis>
614
615 <cmdsynopsis id="synopsis-vboxmanage-controlvm-unplugcpu">
616 <command>VBoxManage controlvm</command>
617 <group choice="req">
618 <arg choice="plain"><replaceable>uuid</replaceable></arg>
619 <arg choice="plain"><replaceable>vmname</replaceable></arg>
620 </group>
621 <arg choice="plain">unplugcpu</arg>
622 <arg choice="req"><replaceable>ID</replaceable></arg>
623 </cmdsynopsis>
624
625 <cmdsynopsis id="synopsis-vboxmanage-controlvm-cpuexecutioncap">
626 <command>VBoxManage controlvm</command>
627 <group choice="req">
628 <arg choice="plain"><replaceable>uuid</replaceable></arg>
629 <arg choice="plain"><replaceable>vmname</replaceable></arg>
630 </group>
631 <arg choice="plain">cpuexecutioncap</arg>
632 <arg choice="req"><replaceable>num</replaceable></arg>
633 </cmdsynopsis>
634
635 <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority">
636 <command>VBoxManage controlvm</command>
637 <group choice="req">
638 <arg choice="plain"><replaceable>uuid</replaceable></arg>
639 <arg choice="plain"><replaceable>vmname</replaceable></arg>
640 </group>
641 <arg choice="plain">vm-process-priority</arg>
642 <group choice="req">
643 <arg choice="plain">default</arg>
644 <arg choice="plain">flat</arg>
645 <arg choice="plain">low</arg>
646 <arg choice="plain">normal</arg>
647 <arg choice="plain">high</arg>
648 </group>
649 </cmdsynopsis>
650
651 <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach">
652 <command>VBoxManage controlvm</command>
653 <group choice="req">
654 <arg choice="plain"><replaceable>uuid</replaceable></arg>
655 <arg choice="plain"><replaceable>vmname</replaceable></arg>
656 </group>
657 <arg choice="plain">webcam attach</arg>
658 <arg><replaceable>pathname</replaceable> <arg><replaceable>settings</replaceable></arg></arg>
659 </cmdsynopsis>
660
661 <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach">
662 <command>VBoxManage controlvm</command>
663 <group choice="req">
664 <arg choice="plain"><replaceable>uuid</replaceable></arg>
665 <arg choice="plain"><replaceable>vmname</replaceable></arg>
666 </group>
667 <arg choice="plain">webcam detach</arg>
668 <arg><replaceable>pathname</replaceable></arg>
669 </cmdsynopsis>
670
671 <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list">
672 <command>VBoxManage controlvm</command>
673 <group choice="req">
674 <arg choice="plain"><replaceable>uuid</replaceable></arg>
675 <arg choice="plain"><replaceable>vmname</replaceable></arg>
676 </group>
677 <arg choice="plain">webcam list</arg>
678 </cmdsynopsis>
679
680 <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword">
681 <command>VBoxManage controlvm</command>
682 <group choice="req">
683 <arg choice="plain"><replaceable>uuid</replaceable></arg>
684 <arg choice="plain"><replaceable>vmname</replaceable></arg>
685 </group>
686 <arg choice="plain">addencpassword</arg>
687 <arg choice="req"><replaceable>ID</replaceable></arg>
688 <group choice="req">
689 <arg choice="plain"><replaceable>password-file</replaceable></arg>
690 <arg choice="plain">-</arg>
691 </group>
692 <arg>--removeonsuspend=<group choice="plain">
693 <arg choice="plain">yes</arg>
694 <arg choice="plain">no</arg>
695 </group></arg>
696 </cmdsynopsis>
697
698 <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword">
699 <command>VBoxManage controlvm</command>
700 <group choice="req">
701 <arg choice="plain"><replaceable>uuid</replaceable></arg>
702 <arg choice="plain"><replaceable>vmname</replaceable></arg>
703 </group>
704 <arg choice="plain">removeencpassword</arg>
705 <arg choice="req"><replaceable>ID</replaceable></arg>
706 </cmdsynopsis>
707
708 <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords">
709 <command>VBoxManage controlvm</command>
710 <group choice="req">
711 <arg choice="plain"><replaceable>uuid</replaceable></arg>
712 <arg choice="plain"><replaceable>vmname</replaceable></arg>
713 </group>
714 <arg choice="plain">removeallencpasswords</arg>
715 </cmdsynopsis>
716
717 <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode">
718 <command>VBoxManage controlvm</command>
719 <group choice="req">
720 <arg choice="plain"><replaceable>uuid</replaceable></arg>
721 <arg choice="plain"><replaceable>vmname</replaceable></arg>
722 </group>
723 <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg>
724 <group choice="plain">
725 <arg choice="plain">disconnected</arg>
726 <arg choice="plain"><arg choice="plain">server</arg> <arg choice="req"><replaceable>pipe-name</replaceable></arg></arg>
727 <arg choice="plain"><arg choice="plain">client</arg> <arg choice="req"><replaceable>pipe-name</replaceable></arg></arg>
728 <arg choice="plain"><arg choice="plain">tcpserver</arg> <arg choice="req"><replaceable>port</replaceable></arg></arg>
729 <arg choice="plain"><arg choice="plain">tcpclient</arg> <arg choice="req"><replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg></arg>
730 <arg choice="plain"><arg choice="plain">file</arg> <arg choice="req"><replaceable>filename</replaceable></arg></arg>
731 <arg choice="plain"><replaceable>device-name</replaceable></arg>
732 </group>
733 </cmdsynopsis>
734
735 <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled">
736 <command>VBoxManage controlvm</command>
737 <group choice="req">
738 <arg choice="plain"><replaceable>uuid</replaceable></arg>
739 <arg choice="plain"><replaceable>vmname</replaceable></arg>
740 </group>
741 <arg choice="plain">autostart-enabled<replaceable>N</replaceable></arg>
742 <group choice="plain">
743 <arg choice="plain">on</arg>
744 <arg choice="plain">off</arg>
745 </group>
746 </cmdsynopsis>
747
748 <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay">
749 <command>VBoxManage controlvm</command>
750 <group choice="req">
751 <arg choice="plain"><replaceable>uuid</replaceable></arg>
752 <arg choice="plain"><replaceable>vmname</replaceable></arg>
753 </group>
754 <arg choice="plain">autostart-delay</arg>
755 <arg choice="req"><replaceable>seconds</replaceable></arg>
756 </cmdsynopsis>
757 </refsynopsisdiv>
758
759 <refsect1 id="vboxmanage-controlvm-description">
760 <title>Description</title>
761 <para>
762 The <command>VBoxManage controlvm</command> command enables you to
763 change the state of a running virtual machine (VM). The following
764 sections describe the subcommands that you can use:
765 </para>
766 <refsect2 id="vboxmanage-controlvm-pause">
767 <title>Pause a Virtual Machine</title>
768 <remark role="help-copy-synopsis"/>
769 <para>
770 The <command>VBoxManage controlvm
771 <replaceable>vmname</replaceable> pause</command> command
772 temporarily stops the execution of a VM. When paused, the VM's
773 state is not permanently changed.
774 </para>
775 <para>
776 The VM window appears as gray and the title bar of the window
777 indicates that the VM is currently Paused. This action is
778 equivalent to selecting <emphasis role="bold">Pause</emphasis>
779 from the <emphasis role="bold">Machine</emphasis> menu of the
780 GUI.
781 </para>
782 </refsect2>
783 <refsect2 id="vboxmanage-controlvm-resume">
784 <title>Resume a Paused Virtual Machine</title>
785 <remark role="help-copy-synopsis"/>
786 <para>
787 The <command>VBoxManage controlvm
788 <replaceable>vmname</replaceable> resume</command> command
789 restarts the execution of a paused VM. This action is equivalent
790 to selecting <emphasis role="bold">Resume</emphasis> from the
791 <emphasis role="bold">Machine</emphasis> menu of the GUI.
792 </para>
793 </refsect2>
794 <refsect2 id="vboxmanage-controlvm-reset">
795 <title>Reset a Virtual Machine</title>
796 <remark role="help-copy-synopsis"/>
797 <para>
798 The <command>VBoxManage controlvm
799 <replaceable>vmname</replaceable> reset</command> command
800 performs a cold reset the VM. This command has the same effect
801 on a VM as pressing the Reset button on a physical computer.
802 </para>
803 <para>
804 The cold reboot immediately restarts and reboots the guest
805 operating system (OS). The state of the VM is not saved prior to
806 the reset, so data might be lost. This action is equivalent to
807 selecting <emphasis role="bold">Reset</emphasis> from the
808 <emphasis role="bold">Machine</emphasis> menu of the GUI.
809 </para>
810 </refsect2>
811 <refsect2 id="vboxmanage-controlvm-poweroff">
812 <title>Power Off a Virtual Machine</title>
813 <remark role="help-copy-synopsis"/>
814 <para>
815 The <command>VBoxManage controlvm
816 <replaceable>vmname</replaceable> poweroff</command> command
817 powers off the VM. This command has the same effect on a VM as
818 pulling the power cable on a physical computer.
819 </para>
820 <para>
821 The state of the VM is not saved prior to poweroff, so data
822 might be lost. This action is equivalent to selecting
823 <emphasis role="bold">Close</emphasis> from the
824 <emphasis role="bold">Machine</emphasis> menu of the GUI or to
825 clicking the VM window's Close button, and then selecting
826 <emphasis role="bold">Power Off the Machine</emphasis>.
827 </para>
828 <para>
829 When in the powered off state, you can restart the VM. See
830 <xref linkend="vboxmanage-startvm" />.
831 </para>
832 </refsect2>
833 <refsect2 id="vboxmanage-controlvm-savestate">
834 <title>Save the State of a Virtual Machine</title>
835 <remark role="help-copy-synopsis"/>
836 <para>
837 The <command>VBoxManage controlvm
838 <replaceable>vmname</replaceable> savestate</command> command
839 saves the current state of the VM to disk and then stops the VM.
840 </para>
841 <para>
842 This action is equivalent to selecting
843 <emphasis role="bold">Close</emphasis> from the
844 <emphasis role="bold">Machine</emphasis> menu of the GUI or to
845 clicking the VM window's Close button, and then selecting
846 <emphasis role="bold">Save the Machine State</emphasis>.
847 </para>
848 <para>
849 When in the saved state, you can restart the VM. It will continue
850 exactly in the state you saved.
851 </para>
852 </refsect2>
853 <refsect2 id="vboxmanage-controlvm-acpipowerbutton">
854 <title>Send an APCI Shutdown Signal to a Virtual Machine</title>
855 <remark role="help-copy-synopsis"/>
856 <para>
857 The <command>VBoxManage controlvm
858 <replaceable>vmname</replaceable> acpipowerbutton</command>
859 command sends an ACPI shutdown signal to the VM. This command
860 has the same effect on a VM as pressing the Power button on a
861 physical computer.
862 </para>
863 <para>
864 So long as the VM runs a guest OS that provides appropriately
865 configured ACPI support, this command triggers an operating
866 system shutdown from within the VM.
867 </para>
868 </refsect2>
869 <refsect2 id="vboxmanage-controlvm-acpisleepbutton">
870 <title>Send an APCI Sleep Signal to a Virtual Machine</title>
871 <remark role="help-copy-synopsis"/>
872 <para>
873 The <command>VBoxManage controlvm
874 <replaceable>vmname</replaceable> acpisleepbutton</command>
875 command sends an ACPI sleep signal to the VM.
876 </para>
877 <para>
878 So long as the VM runs a guest OS that provides appropriately
879 configured ACPI support, this command triggers a sleep mechanism
880 from within the VM.
881 </para>
882 </refsect2>
883 <refsect2 id="vboxmanage-controlvm-reboot">
884 <title>Reboot the guest OS</title>
885 <remark role="help-copy-synopsis"/>
886 <para>
887 The <command>VBoxManage controlvm
888 <replaceable>vmname</replaceable> reboot</command>
889 command asks the guest OS to reboot itself.
890 </para>
891 <para>
892 This commands requires Guest Additions to be installed in the VM.
893 </para>
894 </refsect2>
895 <refsect2 id="vboxmanage-controlvm-shutdown">
896 <title>Shut down the guest OS</title>
897 <remark role="help-copy-synopsis"/>
898 <para>
899 The <command>VBoxManage controlvm
900 <replaceable>vmname</replaceable> shutdown</command>
901 command asks the guest OS to halt + shutdown, optionally forcing
902 the shutdown.
903 </para>
904 <para>
905 This commands requires Guest Additions to be installed in the VM.
906 </para>
907 </refsect2>
908 <refsect2 id="vboxmanage-controlvm-keyboardputscancode">
909 <title>Send Keyboard Scancodes to a Virtual Machine</title>
910 <remark role="help-copy-synopsis"/>
911 <para>
912 The <command>VBoxManage controlvm
913 <replaceable>vmname</replaceable> keyboardputscancode</command>
914 command sends keyboard scancode commands to the VM.
915 </para>
916 <para>
917 For information about keyboard scancodes, see
918 <ulink url="http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html" />.
919 </para>
920 </refsect2>
921 <refsect2 id="vboxmanage-controlvm-keyboardputstring">
922 <title>Send Keyboard Strings to a Virtual Machine</title>
923 <remark role="help-copy-synopsis"/>
924 <para>
925 The <command>VBoxManage controlvm
926 <replaceable>vmname</replaceable> keyboardputstring</command>
927 command sends keyboard strings to the VM.
928 </para>
929 </refsect2>
930 <refsect2 id="vboxmanage-controlvm-keyboardputfile">
931 <title>Send a File to a Virtual Machine</title>
932 <remark role="help-copy-synopsis"/>
933 <para>
934 The <command>VBoxManage controlvm
935 <replaceable>vmname</replaceable> keyboardputfile</command>
936 command sends a file to the VM.
937 </para>
938 </refsect2>
939 <refsect2 id="vboxmanage-controlvm-setlinkstate">
940 <title>Set the Link State for a Virtual Machine</title>
941 <remark role="help-copy-synopsis"/>
942 <para>
943 <command>VBoxManage controlvm <replaceable>vmname</replaceable>
944 setlinkstate<replaceable>N</replaceable></command> command
945 enables you to connect or disconnect the virtual network cable
946 from the network interface instance
947 (<replaceable>N</replaceable>). Valid values are
948 <literal>on</literal> and <literal>off</literal>. The default
949 value is <literal>on</literal>.
950 </para>
951 </refsect2>
952 <refsect2 id="vboxmanage-controlvm-nic">
953 <title>Set the Type of Networking to Use for a Virtual Machine</title>
954 <remark role="help-copy-synopsis"/>
955 <para>
956 The <command>VBoxManage controlvm
957 <replaceable>vmname</replaceable>
958 nic<replaceable>N</replaceable></command> command specifies the
959 type of networking to use on the specified VM's virtual network
960 card. <replaceable>N</replaceable> numbering begins with
961 <literal>1</literal>.
962 </para>
963 <para>
964 The following valid network types are also described in
965 <xref linkend="networkingmodes" />:
966 </para>
967 <itemizedlist>
968 <listitem><para>
969 <literal>null</literal> specifies that the VM is is not
970 connected to the host system.
971 </para></listitem>
972 <listitem><para>
973 <literal>nat</literal> specifies that the VM uses network
974 address translation (NAT).
975 </para></listitem>
976 <listitem><para>
977 <literal>bridged</literal> specifies that the VM uses
978 bridged networking.
979 </para></listitem>
980 <listitem><para>
981 <literal>intnet</literal> specifies that the VM communicates
982 with other VMs by using internal networking.
983 </para></listitem>
984 <listitem><para>
985 <literal>hostonly</literal> specifies that the VM uses
986 host-only networking.
987 </para></listitem>
988 <listitem><para>
989 <literal>natnetwork</literal> specifies that the VM uses NAT
990 networking.
991 </para></listitem>
992 <listitem><para>
993 <literal>generic</literal> specifies that the VM has access
994 to rarely used submodes
995 </para></listitem>
996 </itemizedlist>
997 </refsect2>
998 <refsect2 id="vboxmanage-controlvm-nictrace">
999 <title>Trace the Network Traffic of a Virtual Machine</title>
1000 <remark role="help-copy-synopsis"/>
1001 <para>
1002 The <command>VBoxManage controlvm
1003 <replaceable>vmname</replaceable>
1004 nictrace<replaceable>N</replaceable></command> command enables
1005 you to trace the network traffic on the specified virtual
1006 network card (<replaceable>N</replaceable>).
1007 <replaceable>N</replaceable> numbering begins with
1008 <literal>1</literal>. Valid values are <literal>on</literal> and
1009 <literal>off</literal>. The default value is
1010 <literal>off</literal>.
1011 </para>
1012 <para>
1013 If you did not configure a file name for the trace file then
1014 a default one is used, placing it in the VM subdirectory.
1015 </para>
1016 </refsect2>
1017 <refsect2 id="vboxmanage-controlvm-nictracefile">
1018 <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title>
1019 <remark role="help-copy-synopsis"/>
1020 <para>
1021 The <command>VBoxManage controlvm
1022 <replaceable>vmname</replaceable>
1023 nictracefile<replaceable>N</replaceable></command> command
1024 enables you to specify the name of the network traffic trace log
1025 file for the specified virtual network card
1026 (<replaceable>N</replaceable>). <replaceable>N</replaceable>
1027 numbering begins with <literal>1</literal>.
1028 </para>
1029 </refsect2>
1030 <refsect2 id="vboxmanage-controlvm-nicpromisc">
1031 <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title>
1032 <remark role="help-copy-synopsis"/>
1033 <para>
1034 The <command>VBoxManage controlvm
1035 <replaceable>vmname</replaceable>
1036 nicpromisc<replaceable>N</replaceable></command> command enables
1037 you to specify how to handle promiscuous mode for a bridged
1038 network. The default value of <literal>deny</literal> hides any
1039 traffic that is not intended for this VM. The
1040 <literal>allow-vms</literal> value hides all host traffic from
1041 this VM but enables the VM to see traffic to and from other VMs.
1042 The <literal>allow-all</literal> value removes this restriction
1043 completely.
1044 </para>
1045 </refsect2>
1046 <refsect2 id="vboxmanage-controlvm-nicproperty">
1047 <title>Specify the Network Backend Property Values for a Virtual Machine</title>
1048 <remark role="help-copy-synopsis"/>
1049 <para>
1050 The <command>VBoxManage controlvm
1051 <replaceable>vmname</replaceable>
1052 nicproperty<replaceable>N</replaceable>
1053 <replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></command>
1054 command, in combination with <literal>nicgenericdrv</literal>,
1055 enables you to pass property values to rarely-used network
1056 backends.
1057 </para>
1058 <para>
1059 Those properties are backend engine-specific, and are different
1060 between UDP Tunnel and the VDE backend drivers. See
1061 <xref linkend="network_udp_tunnel" />.
1062 </para>
1063 </refsect2>
1064 <refsect2 id="vboxmanage-controlvm-natpf">
1065 <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title>
1066 <remark role="help-copy-synopsis"/>
1067 <para>
1068 The <command>VBoxManage controlvm
1069 <replaceable>vmname</replaceable>
1070 natpf<replaceable>N</replaceable></command> command specifies a
1071 NAT port-forwarding rule. See <xref linkend="natforward"/>.
1072 </para>
1073 </refsect2>
1074 <refsect2 id="vboxmanage-controlvm-natpf-delete">
1075 <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title>
1076 <remark role="help-copy-synopsis"/>
1077 <para>
1078 The <command>VBoxManage controlvm
1079 <replaceable>vmname</replaceable>
1080 natpf<replaceable>N</replaceable> delete</command> command deletes
1081 the specified NAT port-forwarding rule. See
1082 <xref linkend="natforward"/>.
1083 </para>
1084 </refsect2>
1085 <refsect2 id="vboxmanage-controlvm-guestmemoryballoon">
1086 <title>Change Size of a Virtual Machine's Guest Memory Balloon</title>
1087 <remark role="help-copy-synopsis"/>
1088 <para>
1089 The <command>VBoxManage controlvm
1090 <replaceable>vmname</replaceable> guestmemoryballoon</command>
1091 command changes the size of the guest memory balloon. The guest
1092 memory balloon is the memory allocated by the &product-name;
1093 Guest Additions from the guest OS and returned to the hypervisor
1094 for reuse by other VMs. The value you specify is in megabytes.
1095 See <xref linkend="guestadd-balloon" />.
1096 </para>
1097 </refsect2>
1098 <refsect2 id="vboxmanage-controlvm-usbattach">
1099 <title>Make a Host System USB Device Visible to a Virtual Machine</title>
1100 <remark role="help-copy-synopsis"/>
1101 <para>
1102 The <command>VBoxManage controlvm
1103 <replaceable>vmname</replaceable> usbattach</command> command
1104 dynamically attaches a host USB device to the VM, which makes it
1105 visible. You do not need to create a filter.
1106 </para>
1107 <para>
1108 Specify a USB device by its Universally Unique Identifier (UUID)
1109 or by its address on the host system. Use the
1110 <command>VBoxManage list usbhost</command> command to obtain
1111 information about USB devices on the host system.
1112 </para>
1113 <para>
1114 Use the <option>--capturefile</option> option to specify the
1115 absolute path of a file in which to write logging data.
1116 </para>
1117 </refsect2>
1118 <refsect2 id="vboxmanage-controlvm-usbdetach">
1119 <title>Make a Host System USB Device Invisible to a Virtual Machine</title>
1120 <remark role="help-copy-synopsis"/>
1121 <para>
1122 The <command>VBoxManage controlvm
1123 <replaceable>vmname</replaceable> usbdetach</command> command
1124 dynamically detaches a host USB device from the VM, which makes
1125 it invisible. You do not need to create a filter.
1126 </para>
1127 <para>
1128 Specify a USB device by its UUID or by its address on the host
1129 system. Use the <command>VBoxManage list usbhost</command>
1130 command to obtain information about USB devices on the host
1131 system.
1132 </para>
1133 </refsect2>
1134 <refsect2 id="vboxmanage-controlvm-audioin">
1135 <title>Enable or Disable Audio Capture From the Host System</title>
1136 <remark role="help-copy-synopsis"/>
1137 <para>
1138 The <command>VBoxManage controlvm
1139 <replaceable>vmname</replaceable> audioin</command> command
1140 specifies whether to enable or disable audio capture from the
1141 host system. Valid values are <literal>on</literal>, which
1142 enables audio capture and <literal>off</literal>, which disables
1143 audio capture. The default value is <literal>off</literal>.
1144 </para>
1145 </refsect2>
1146 <refsect2 id="vboxmanage-controlvm-audioout">
1147 <title>Enable or Disable Audio Playback From a Virtual Machine</title>
1148 <remark role="help-copy-synopsis"/>
1149 <para>
1150 The <command>VBoxManage controlvm
1151 <replaceable>vmname</replaceable> audioout</command> command
1152 specifies whether to enable or disable audio playback from the
1153 guest VM. Valid values are <literal>on</literal>, which enables
1154 audio playback and <literal>off</literal>, which disables audio
1155 playback. The default value is <literal>off</literal>.
1156 </para>
1157 </refsect2>
1158 <refsect2 id="vboxmanage-controlvm-clipboard-mode">
1159 <title>Specify How to Share the Host OS or Guest OS Clipboard</title>
1160 <remark role="help-copy-synopsis"/>
1161 <para>
1162 The <command>VBoxManage controlvm
1163 <replaceable>vmname</replaceable> clipboard mode</command> command
1164 specifies how to share the guest or host OS's clipboard with the
1165 host system or VM. Valid values are <literal>disabled</literal>,
1166 <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
1167 and <literal>bidirectional</literal>. The default value is
1168 <literal>disabled</literal>. See
1169 <xref linkend="generalsettings" />.
1170 </para>
1171 <para>
1172 This feature requires that the &product-name; Guest Additions
1173 are installed in the VM.
1174 </para>
1175 </refsect2>
1176
1177 <refsect2 id="vboxmanage-controlvm-clipboard-filetransfers">
1178 <title>Specify If Files Can Be Transferred Through the Clipboard</title>
1179 <remark role="help-copy-synopsis"/>
1180 <para>
1181 The <command>VBoxManage controlvm
1182 <replaceable>vmname</replaceable> clipboard filetransfers</command>
1183 command specifies if it is possible to transfer files through the
1184 clipboard between the host and VM, in the direction which is allowed.
1185 Valid values are <literal>off</literal> and <literal>on</literal>.
1186 The default value is <literal>off</literal>.
1187 </para>
1188 <para>
1189 This feature requires that the &product-name; Guest Additions
1190 are installed in the VM.
1191 </para>
1192 </refsect2>
1193
1194 <refsect2 id="vboxmanage-controlvm-draganddrop">
1195 <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title>
1196 <remark role="help-copy-synopsis"/>
1197 <para>
1198 The <command>VBoxManage controlvm
1199 <replaceable>vmname</replaceable> draganddrop</command> command
1200 specifies the current drag and drop mode to use between the host
1201 system and the VM. Valid values are <literal>disabled</literal>,
1202 <literal>hosttoguest</literal>, <literal>guesttohost</literal>,
1203 and <literal>bidirectional</literal>. The default value is
1204 <literal>disabled</literal>. See
1205 <xref linkend="guestadd-dnd" />.
1206 </para>
1207 <para>
1208 This feature requires that the &product-name; Guest Additions
1209 are installed in the VM.
1210 </para>
1211 </refsect2>
1212 <refsect2 id="vboxmanage-controlvm-vrde">
1213 <title>Enable or Disable the VRDE Server</title>
1214 <remark role="help-copy-synopsis"/>
1215 <para>
1216 The <command>VBoxManage controlvm
1217 <replaceable>vmname</replaceable> vrde</command> command enables
1218 or disables the VirtualBox Remote Desktop Extension (VRDE)
1219 server, if installed. Valid values are <literal>on</literal> and
1220 <literal>off</literal>. The default value is
1221 <literal>off</literal>.
1222 </para>
1223 </refsect2>
1224 <refsect2 id="vboxmanage-controlvm-vrdeport">
1225 <title>Specify VRDE Server Ports</title>
1226 <remark role="help-copy-synopsis"/>
1227 <para>
1228 The <command>VBoxManage controlvm
1229 <replaceable>vmname</replaceable> vrdeport</command> command
1230 specifies the port or range of ports to which the VRDE server
1231 can bind. The default value is <literal>default</literal> or
1232 <literal>0</literal>, which is the standard RDP port,
1233 <literal>3389</literal>.
1234 </para>
1235 <para>
1236 Also see the <option>--vrde-port</option> option description in
1237 <xref linkend="vboxmanage-modifyvm-vrde" />.
1238 </para>
1239 </refsect2>
1240 <refsect2 id="vboxmanage-controlvm-vrdeproperty">
1241 <title>Specify VRDE Server Port Numbers and IP Addresses</title>
1242 <remark role="help-copy-synopsis"/>
1243 <para>
1244 The <command>VBoxManage controlvm
1245 <replaceable>vmname</replaceable> vrdeproperty</command> command
1246 specifies the port numbers and IP address on the VM to which the
1247 VRDE server can bind.
1248 </para>
1249 <itemizedlist>
1250 <listitem><para>
1251 <literal>TCP/Ports</literal> specifies a port or a range of
1252 ports to which the VRDE server can bind. The default value
1253 is <literal>default</literal> or <literal>0</literal>, which
1254 is the standard RDP port, <literal>3389</literal>.
1255 </para><para>
1256 Also see the <option>--vrde-port</option> option description
1257 in <xref linkend="vboxmanage-modifyvm-vrde" />.
1258 </para></listitem>
1259 <listitem><para>
1260 <literal>TCP/Address</literal> specifies the IP address of
1261 the host network interface to which the VRDE server binds.
1262 When specified, the server accepts to connect only on the
1263 specified host network interface.
1264 </para><para>
1265 Also see the <option>--vrde-address</option> option
1266 description in <xref linkend="vboxmanage-modifyvm-vrde" />.
1267 </para></listitem>
1268 <listitem><para>
1269 <literal>VideoChannel/Enabled</literal> specifies whether to
1270 enable the VirtualBox Remote Desktop Protocol (VRDP) video
1271 channel. Valid values are <literal>1</literal> to enable the
1272 video channel and <literal>0</literal> to disable the video
1273 channel. The default value is <literal>off</literal>. See
1274 <xref linkend="vrde-videochannel" />.
1275 </para></listitem>
1276 <listitem><para>
1277 <literal>VideoChannel/Quality</literal> specifies the JPEG
1278 compression level on the VRDE server video channel. Valid
1279 values are between 10% and 100%, inclusive. Lower values
1280 mean lower quality but higher compression. The default value
1281 is <literal>100</literal>. See
1282 <xref linkend="vrde-videochannel" />.
1283 </para></listitem>
1284 <listitem><para>
1285 <literal>VideoChannel/DownscaleProtection</literal>
1286 specifies whether to enable the video channel downscale
1287 protection feature. Specify <literal>1</literal> to enable
1288 the feature. This feature is disabled by default.
1289 </para><para>
1290 When enabled, if the video's size equals the shadow buffer
1291 size, the video is shown in full-screen mode. If the video's
1292 size is between full-screen mode and the downscale
1293 threshold, the video is not shown as it might be an
1294 application window that is unreadable when downscaled. When
1295 disabled, the downscale protection feature always attempts
1296 to show videos.
1297 </para></listitem>
1298 <listitem><para>
1299 <literal>Client/DisableDisplay</literal> specifies whether
1300 to disable the VRDE server display feature. Valid values are
1301 <literal>1</literal> to disable the feature and an empty
1302 string (<literal>""</literal>) to enable the feature.
1303 The default value is an empty string. See
1304 <xref linkend="vrde-customization"/>.
1305 </para></listitem>
1306 <listitem><para>
1307 <literal>Client/DisableInput</literal> specifies whether to
1308 disable the VRDE server input feature. Valid values are
1309 <literal>1</literal> to disable the feature and an empty
1310 string (<literal>""</literal>) to enable the feature.
1311 The default value is <literal>1</literal>. See
1312 <xref linkend="vrde-customization"/>.
1313 </para></listitem>
1314 <listitem><para>
1315 <literal>Client/DisableAudio</literal> specifies whether to
1316 disable the VRDE server audio feature. Valid values are
1317 <literal>1</literal> to disable the feature and an empty
1318 string (<literal>""</literal>) to enable the feature.
1319 The default value is <literal>1</literal>. See
1320 <xref linkend="vrde-customization"/>.
1321 </para></listitem>
1322 <listitem><para>
1323 <literal>Client/DisableUSB</literal> specifies whether to
1324 disable the VRDE server USB feature. Valid values are
1325 <literal>1</literal> to disable the feature and an empty
1326 string (<literal>""</literal>) to enable the feature.
1327 The default value is <literal>1</literal>. See
1328 <xref linkend="vrde-customization"/>.
1329 </para></listitem>
1330 <listitem><para>
1331 <literal>Client/DisableClipboard</literal> specifies whether
1332 to disable the VRDE clipboard feature. Valid values are
1333 <literal>1</literal> to disable the feature and an empty
1334 string (<literal>""</literal>) to enable the feature.
1335 To reenable the feature, use
1336 <literal>Client/DisableClipboard=</literal>. The default
1337 value is <literal>1</literal>. See
1338 <xref linkend="vrde-customization"/>.
1339 </para></listitem>
1340 <listitem><para>
1341 <literal>Client/DisableUpstreamAudio</literal> specifies
1342 whether to disable the VRDE upstream audio feature. Valid
1343 values are <literal>1</literal> to disable the feature and
1344 an empty string (<literal>""</literal>) to enable the
1345 feature. To reenable the feature, use
1346 <literal>Client/DisableUpstreamAudio=</literal>. The default
1347 value is <literal>1</literal>. See
1348 <xref linkend="vrde-customization"/>.
1349 </para></listitem>
1350 <listitem><para>
1351 <literal>Client/DisableRDPDR</literal> specifies whether to
1352 disable the RDP Device Redirection For Smart Cards feature
1353 on the VRDE server. Valid values are <literal>1</literal> to
1354 disable the feature and an empty string
1355 (<literal>""</literal>) to enable the feature.
1356 The default value is <literal>1</literal>. See
1357 <xref linkend="vrde-customization"/>.
1358 </para></listitem>
1359 <listitem><para>
1360 <literal>H3DRedirect/Enabled</literal> specifies whether to
1361 enable the VRDE server 3D redirection feature. Valid values
1362 are <literal>1</literal> to enable the feature and an empty
1363 string (<literal>""</literal>) to disable the feature.
1364 See <xref linkend="vrde-customization"/>.
1365 </para></listitem>
1366 <listitem><para>
1367 <literal>Security/Method</literal> specifies the security
1368 method to use for a connection. See
1369 <xref linkend="vrde-crypt" />.
1370 </para><itemizedlist>
1371 <listitem><para>
1372 <literal>Negotiate</literal> accepts both enhanced (TLS)
1373 and standard RDP security connections. The security
1374 method is negotiated with the client. This is the
1375 default value.
1376 </para></listitem>
1377 <listitem><para>
1378 <literal>RDP</literal> accepts only standard RDP
1379 security connections.
1380 </para></listitem>
1381 <listitem><para>
1382 <literal>TLS</literal> accepts only enhanced RDP
1383 security connections. The client must support TLS.
1384 </para></listitem>
1385 </itemizedlist></listitem>
1386 <listitem><para>
1387 <literal>Security/ServerCertificate</literal> specifies the
1388 absolute path of the server certificate to use for a
1389 connection. See <xref linkend="vrde-crypt" />.
1390 </para></listitem>
1391 <listitem><para>
1392 <literal>Security/ServerPrivateKey</literal> specifies the
1393 absolute path of the server private key. See
1394 <xref linkend="vrde-crypt" />.
1395 </para></listitem>
1396 <listitem><para>
1397 <literal>Security/CACertificate</literal> specifies the
1398 absolute path of the CA self-signed certificate. See
1399 <xref linkend="vrde-crypt" />.
1400 </para></listitem>
1401 <listitem><para>
1402 <literal>Audio/RateCorrectionMode</literal> specifies the
1403 rate correction mode to use.
1404 </para><itemizedlist>
1405 <listitem><para>
1406 <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that
1407 no mode is specified. Use this value to unset any audio
1408 mode that is already set.
1409 </para></listitem>
1410 <listitem><para>
1411 <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use
1412 the rate correction mode.
1413 </para></listitem>
1414 <listitem><para>
1415 <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use
1416 the low pass filter mode.
1417 </para></listitem>
1418 <listitem><para>
1419 <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use
1420 the client sync mode to prevent underflow or overflow of
1421 the client queue.
1422 </para></listitem>
1423 </itemizedlist></listitem>
1424 <listitem><para>
1425 <literal>Audio/LogPath</literal> specifies the absolute path
1426 of the audio log file.
1427 </para></listitem>
1428 </itemizedlist>
1429 </refsect2>
1430 <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality">
1431 <title>Specify the Image Quality for VRDP Video Redirection</title>
1432 <remark role="help-copy-synopsis"/>
1433 <para>
1434 The <command>VBoxManage controlvm
1435 <replaceable>vmname</replaceable>
1436 vrdevideochannelquality</command> command sets the image
1437 quality, as a JPEG compression level value, for video
1438 redirection. Valid values are between 10% and 100%, inclusive.
1439 Lower values mean lower quality but higher compression. See
1440 <xref linkend="vrde-videochannel" />.
1441 </para>
1442 </refsect2>
1443 <refsect2 id="vboxmanage-controlvm-setvideomodehint">
1444 <title>Specify the Video Mode for the Guest VM</title>
1445 <remark role="help-copy-synopsis"/>
1446 <para>
1447 The <command>VBoxManage controlvm
1448 <replaceable>vmname</replaceable> setvideomodehint</command>
1449 command specifies the video mode for the guest VM to use. You
1450 must have the &product-name; Guest Additions installed. Note
1451 that this feature does not work for all guest systems.
1452 </para>
1453 </refsect2>
1454 <refsect2 id="vboxmanage-controlvm-setscreenlayout">
1455 <title>Specify the Screen Layout for a Display on the Guest VM</title>
1456 <remark role="help-copy-synopsis"/>
1457 <para>
1458 The <command>VBoxManage controlvm
1459 <replaceable>vmname</replaceable> setscreenlayout</command>
1460 command can be used to configure multiscreen displays. The
1461 specified screen on the guest VM can be enabled or disabled, or
1462 a custom screen layout can be configured.
1463 </para>
1464 </refsect2>
1465 <refsect2 id="vboxmanage-controlvm-screenshotpng">
1466 <title>Take a Screen Shot of the Virtual Machine Display</title>
1467 <remark role="help-copy-synopsis"/>
1468 <para>
1469 The <command>VBoxManage controlvm
1470 <replaceable>vmname</replaceable> screenshotpng</command>
1471 command takes a screenshot of the guest display and saves it as
1472 PNG in the specified file.
1473 </para>
1474 <itemizedlist>
1475 <listitem><para>
1476 <replaceable>filename</replaceable> specifies the name of
1477 the PNG file to create.
1478 </para></listitem>
1479 <listitem><para>
1480 <replaceable>display</replaceable> specifies the display
1481 number for the screen shot. For a single monitor guest
1482 display, this is <literal>0</literal>.
1483 </para></listitem>
1484 </itemizedlist>
1485 </refsect2>
1486 <refsect2 id="vboxmanage-controlvm-recording">
1487 <title>Enable or Disable the Recording of a Virtual Machine Session</title>
1488 <remark role="help-copy-synopsis"/>
1489 <para>
1490 The <command>VBoxManage controlvm
1491 <replaceable>vmname</replaceable> recording</command> command
1492 enables or disables the recording of a VM session into a
1493 WebM/VP8 file. Valid values are <literal>on</literal>, which
1494 begins recording when the VM session starts and
1495 <literal>off</literal>, which disables recording. The default
1496 value is <literal>off</literal>.
1497 </para>
1498 </refsect2>
1499 <refsect2 id="vboxmanage-controlvm-recording-screens">
1500 <title>Specify the Virtual Machine Screens to Record</title>
1501 <remark role="help-copy-synopsis"/>
1502 <para>
1503 The <command>VBoxManage controlvm
1504 <replaceable>vmname</replaceable> recording screens</command>
1505 command enables you to specify which VM screens to record. The
1506 recording for each screen that you specify is saved to its own
1507 file in the machine folder. You cannot modify this setting while
1508 recording is enabled.
1509 </para>
1510 <itemizedlist>
1511 <listitem><para>
1512 <literal>all</literal> specifies that you record all VM
1513 screens.
1514 </para></listitem>
1515 <listitem><para>
1516 <literal>none</literal> specifies that you do not record any
1517 VM screens.
1518 </para></listitem>
1519 <listitem><para>
1520 <replaceable>screen-ID</replaceable> specifies one or more
1521 VM screens to record.
1522 </para></listitem>
1523 </itemizedlist>
1524 </refsect2>
1525 <refsect2 id="vboxmanage-controlvm-recording-filename">
1526 <title>Specify the File in Which to Save Virtual Machine Recording</title>
1527 <remark role="help-copy-synopsis"/>
1528 <para>
1529 The <command>VBoxManage controlvm
1530 <replaceable>vmname</replaceable> recording filename</command>
1531 command specifies the file in which to save the recording. You
1532 cannot modify this setting while recording is enabled.
1533 </para>
1534 <para>
1535 The default setting is to store a recording in the machine
1536 folder, using the VM name as the file name, with a
1537 <filename>webm</filename> file name extension.
1538 </para>
1539 </refsect2>
1540 <refsect2 id="vboxmanage-controlvm-recording-videores">
1541 <title>Specify the Resolution of the Recorded Video</title>
1542 <remark role="help-copy-synopsis"/>
1543 <para>
1544 <command>VBoxManage controlvm <replaceable>vmname</replaceable>
1545 recording videores</command> command specifies the resolution of
1546 the recorded video in pixels. You cannot modify this setting
1547 while recording is enabled.
1548 </para>
1549 <para>
1550 Use the Settings tool to view the video recording settings,
1551 which are based on the resolution (frame size). See the Frame
1552 Size field on the Recording tab of the Display page to view the
1553 default value.
1554 </para>
1555 <para>
1556 Specify the resolution as
1557 <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>:
1558 </para>
1559 <itemizedlist>
1560 <listitem><para>
1561 <replaceable>width</replaceable> specifies the width in
1562 pixels.
1563 </para></listitem>
1564 <listitem><para>
1565 <replaceable>height</replaceable> specifies the height in
1566 pixels.
1567 </para></listitem>
1568 </itemizedlist>
1569 </refsect2>
1570 <refsect2 id="vboxmanage-controlvm-recording-videorate">
1571 <title>Specify the Bit Rate of the Video</title>
1572 <remark role="help-copy-synopsis"/>
1573<!-- @todo r=andy Clarify rate. -->
1574 <para>
1575 The <command>VBoxManage controlvm
1576 <replaceable>vmname</replaceable> recording videorate</command>
1577 command specifies the bit rate,
1578 <replaceable>bit-rate</replaceable>, of the video in kilobits
1579 per second. Increasing this value improves the appearance of the
1580 video at the cost of an increased file size. You cannot modify
1581 this setting while recording is enabled.
1582 </para>
1583 <para>
1584 Use the Settings tool to view the video recording settings,
1585 which are based on the frame size. See the Video Quality field
1586 on the Recording tab of the Display page to view the default
1587 value.
1588 </para>
1589 </refsect2>
1590 <refsect2 id="vboxmanage-controlvm-recording-videofps">
1591 <title>Specify the Maximum Frequency of the Video</title>
1592 <remark role="help-copy-synopsis"/>
1593 <para>
1594 The <command>VBoxManage controlvm
1595 <replaceable>vmname</replaceable> recording videofps</command>
1596 command specifies the maximum frequency of the video to record.
1597 Video frequency is measured in frames per second (FPS). The
1598 recording skips any frames that have a frequency higher than the
1599 specified maximum. Increasing the frequency reduces the number
1600 of skipped frames and increases the file size. You cannot modify
1601 this setting while recording is enabled.
1602 </para>
1603 <para>
1604 Use the Settings tool to view the video recording settings,
1605 which are based on the frame size. See the Frame Rate field on
1606 the Recording tab of the Display page to view the default value.
1607 </para>
1608 </refsect2>
1609 <refsect2 id="vboxmanage-controlvm-recording-maxtime">
1610 <title>Specify the Maximum Amount of Time to Record Video</title>
1611 <remark role="help-copy-synopsis"/>
1612<!-- @todo r=andy Clarify time format. -->
1613 <para>
1614 The <command>VBoxManage controlvm
1615 <replaceable>vmname</replaceable> recording maxtime</command>
1616 command specifies the maximum amount time to record in seconds.
1617 The recording stops after the specified number of seconds
1618 elapses. If this value is zero, the recording continues until
1619 you stop the recording.
1620 </para>
1621 </refsect2>
1622 <refsect2 id="vboxmanage-controlvm-recording-maxfilesize">
1623 <title>Specify the Maximum Size of the Recorded Video</title>
1624 <remark role="help-copy-synopsis"/>
1625 <para>
1626 The <command>VBoxManage controlvm
1627 <replaceable>vmname</replaceable> recording
1628 maxfilesize</command> command specifies the maximum size of the
1629 recorded video file in megabytes. The recording stops when the
1630 file reaches the specified size. If this value is zero, the
1631 recording continues until you stop the recording. You cannot
1632 modify this setting while recording is enabled.
1633 </para>
1634 </refsect2>
1635 <!--
1636 <refsect2 id="vboxmanage-controlvm-recording-opts">
1637 <title>Specify Custom Options for Recording Video and/or Audio</title>
1638 <remark role="help-copy-synopsis"/>
1639 <para>
1640 The <command>VBoxManage controlvm
1641 <replaceable>vmname</replaceable> recording
1642 opts</command> command specifies additional recording options
1643 in a comma-separated keyword-value format. For example,
1644 <computeroutput>foo=bar,a=b</computeroutput>. You cannot
1645 modify this setting while recording is enabled.
1646 </para>
1647 <para>
1648 Use this option if you are an advanced user only. For
1649 information about keywords, see <emphasis>&product-name;
1650 Programming Guide and Reference</emphasis>.
1651 </para>
1652 </refsect2>
1653 -->
1654 <refsect2 id="vboxmanage-controlvm-setcredentials">
1655 <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title>
1656 <remark role="help-copy-synopsis"/>
1657 <para>
1658 The <command>setcredentials</command> command enables you to
1659 specify the credentials for remotely logging in to Windows VMs.
1660 See <xref linkend="autologon" />.
1661 </para>
1662 <itemizedlist>
1663 <listitem><para>
1664 <replaceable>username</replaceable> specifies the user name
1665 with which to log in to the Windows VM.
1666 </para></listitem>
1667 <listitem><para>
1668 <option>--passwordfile=<replaceable>filename</replaceable></option>
1669 specifies the file from which to obtain the password for
1670 <replaceable>username</replaceable>.
1671 </para><para>
1672 The <option>--passwordfile</option> is mutually exclusive
1673 with the <option>--password</option> option.
1674 </para></listitem>
1675 <listitem><para>
1676 <option>--password=<replaceable>password</replaceable></option>
1677 specifies the password for
1678 <replaceable>username</replaceable>.
1679 </para><remark>
1680 This design does not conform to Oracle's security
1681 guidelines. You should not be able to specify a password on
1682 the command line because the password can be seen in a
1683 process listing.
1684 </remark><para>
1685 The <option>--password</option> is mutually exclusive with
1686 the <option>--passwordfile</option> option.
1687 </para></listitem>
1688 <listitem><para>
1689 <option>--allowlocallogin</option> specifies whether to
1690 enable or disable local logins. Valid values are
1691 <literal>on</literal> to enable local logins and
1692 <literal>off</literal> to disable local logins.
1693 </para></listitem>
1694 </itemizedlist>
1695 </refsect2>
1696 <refsect2 id="vboxmanage-controlvm-teleport">
1697 <title>Configure a Virtual Machine Target for Teleporting</title>
1698 <remark role="help-copy-synopsis"/>
1699 <para>
1700 The <command>VBoxManage controlvm
1701 <replaceable>vmname</replaceable> teleport</command> command
1702 initiates a teleporting operation between the specified VM and
1703 the specified host system. See <xref linkend="teleporting" />.
1704 </para>
1705 <para>
1706 If you specify a password, it must match the password you
1707 specified when you issued the <command>VBoxManage
1708 modifyvm</command> command for the target machine.
1709 </para>
1710 <variablelist>
1711 <varlistentry>
1712 <term><option>--host=<replaceable>hostname</replaceable></option></term>
1713 <listitem><para>
1714 Specifies the name of the VM.
1715 </para></listitem>
1716 </varlistentry>
1717 <varlistentry>
1718 <term><option>--port=<replaceable>port</replaceable></option></term>
1719 <listitem><para>
1720 Specifies the port on the VM that should listen for a
1721 teleporting request from other VMs. The port number can be
1722 any free TCP/IP port number, such as
1723 <literal>6000</literal>.
1724 </para></listitem>
1725 </varlistentry>
1726 <varlistentry>
1727 <term><option>--maxdowntime=<replaceable>msec</replaceable></option></term>
1728 <listitem><para>
1729 Specifies the maximum downtime, in milliseconds, for the
1730 teleporting target VM.
1731 </para></listitem>
1732 </varlistentry>
1733 <varlistentry>
1734 <term><option>--password=<replaceable>password</replaceable></option></term>
1735 <listitem><para>
1736 Specifies the password that the source machine uses for
1737 the teleporting request. The request succeeds only if the
1738 source machine specifies the same password.
1739 </para><remark>
1740 This design does not conform to Oracle's security
1741 guidelines. You should not be able to specify a password
1742 on the command line because the password can be seen in a
1743 process listing.
1744 </remark><para>
1745 The <option>--password</option> is mutually exclusive with
1746 the <option>--passwordfile</option> option.
1747 </para></listitem>
1748 </varlistentry>
1749 <varlistentry>
1750 <term><option>--passwordfile=<replaceable>filename</replaceable></option></term>
1751 <listitem><para>
1752 Specifies the file from which to obtain the password that
1753 the source machine uses for the teleporting request. The
1754 request succeeds only if the source machine specifies the
1755 same password.
1756 </para><para>
1757 When you specify a file name of <literal>stdin</literal>,
1758 you can read the password from standard input.
1759 </para><para>
1760 The <option>--passwordfile</option> is mutually exclusive
1761 with the <option>--password</option> option.
1762 </para></listitem>
1763 </varlistentry>
1764 </variablelist>
1765 </refsect2>
1766 <refsect2 id="vboxmanage-controlvm-plugcpu">
1767 <title>Add a Virtual CPU to a Virtual Machine</title>
1768 <remark role="help-copy-synopsis"/>
1769 <para>
1770 The <command>VBoxManage controlvm
1771 <replaceable>vmname</replaceable> plugcpu</command> command adds
1772 a virtual CPU to the specified VM if CPU hot-plugging is
1773 enabled. <replaceable>ID</replaceable> specifies the index of
1774 the virtual CPU to be added and must be a number from 0 to the
1775 maximum number of CPUs configured.
1776 </para>
1777 </refsect2>
1778 <refsect2 id="vboxmanage-controlvm-unplugcpu">
1779 <title>Remove a Virtual CPU From a Virtual Machine</title>
1780 <remark role="help-copy-synopsis"/>
1781 <para>
1782 The <command>VBoxManage controlvm
1783 <replaceable>vmname</replaceable> unplugcpu</command> command
1784 removes a virtual CPU from the specified VM if CPU hot-plugging
1785 is enabled. <replaceable>ID</replaceable> specifies the index of
1786 the virtual CPU to be removed and must be a number from 0 to the
1787 maximum number of CPUs configured. You cannot remove CPU 0.
1788 </para>
1789 </refsect2>
1790 <refsect2 id="vboxmanage-controlvm-cpuexecutioncap">
1791 <title>Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU</title>
1792 <remark role="help-copy-synopsis"/>
1793 <para>
1794 The <command>VBoxManage controlvm
1795 <replaceable>vmname</replaceable> cpuexecutioncap</command>
1796 command specifies how the maximum amount of physical CPU time
1797 used by a virtual CPU. Valid values are a percentage between
1798 <literal>1</literal> and <literal>100</literal>. A value of
1799 <literal>50</literal> specifies that a single virtual CPU can
1800 use up to 50% of a physical CPU. The default value is
1801 <literal>100</literal>.
1802 </para>
1803 <para>
1804 Use this feature with caution, it can have unexpected results
1805 including timekeeping problems and lower performance than
1806 specified. If you want to limit the resource usage of a VM
1807 it is more reliable to pick an appropriate number of VCPUs.
1808 </para>
1809 </refsect2>
1810 <refsect2 id="vboxmanage-controlvm-vm-process-priority">
1811 <title>Change the Priority of a VM Process</title>
1812 <remark role="help-copy-synopsis"/>
1813 <para>
1814 The <command>VBoxManage controlvm
1815 <replaceable>vmname</replaceable> vm-process-priority</command>
1816 command specifies the priority scheme of the VM process to use
1817 when starting the specified VM and while the VM runs.
1818 </para>
1819 <para>
1820 Valid values are:
1821 </para>
1822 <itemizedlist>
1823 <listitem><para>
1824 <literal>default</literal> &ndash; Default process
1825 priority determined by the OS.
1826 </para></listitem>
1827 <listitem><para>
1828 <literal>flat</literal> &ndash; Assumes a scheduling
1829 policy which puts the process at the default priority
1830 and with all threads at the same priority.
1831 </para></listitem>
1832 <listitem><para>
1833 <literal>low</literal> &ndash; Assumes a scheduling
1834 policy which puts the process mostly below the default
1835 priority of the host OS.
1836 </para></listitem>
1837 <listitem><para>
1838 <literal>normal</literal> &ndash; Assume a scheduling
1839 policy which shares the CPU resources fairly with
1840 other processes running with the default priority of
1841 the host OS.
1842 </para></listitem>
1843 <listitem><para>
1844 <literal>high</literal> &ndash; Assumes a scheduling
1845 policy which puts the task above the default priority of
1846 the host OS. This policy might easily cause other tasks
1847 in the system to starve.
1848 </para></listitem>
1849 </itemizedlist>
1850 </refsect2>
1851 <refsect2 id="vboxmanage-controlvm-webcam-attach">
1852 <title>Attach a Webcam to a Virtual Machine</title>
1853 <remark role="help-copy-synopsis"/>
1854 <para>
1855 The <command>VBoxManage controlvm
1856 <replaceable>vmname</replaceable> webcam attach</command>
1857 command attaches a webcam to a running VM. Specify the webcam as
1858 the absolute path of the webcam on the host OS or as an alias.
1859 Use the <command>VBoxManage list webcams</command> command to
1860 obtain the webcam alias.
1861 </para>
1862 <para>
1863 Note that the <literal>.0</literal> alias is the default video
1864 input device on the host OS. <literal>.1</literal> is the first
1865 video input device, <literal>.2</literal> is the second video
1866 input device, and so on. The order of the devices is specific to
1867 the host system.
1868 </para>
1869 <para>
1870 You can specify optional settings in the form of
1871 semi-colon-separated (<literal>;</literal>) name-value pairs.
1872 These properties enable you to configure the emulated webcam
1873 device.
1874 </para>
1875 <para>
1876 The following settings are supported:
1877 </para>
1878 <variablelist>
1879 <varlistentry>
1880 <term><literal>MaxFramerate</literal></term>
1881 <listitem><para>
1882 Specifies the highest rate at which to send video frames
1883 to the VM. The rate is in frames per second. Higher frame
1884 rates increase CPU load, so you can use this setting to
1885 reduce CPU load. The default value is <literal>no maximum
1886 limit</literal>. This value enables the VM to use any
1887 frame rate supported by the webcam.
1888 </para></listitem>
1889 </varlistentry>
1890 <varlistentry>
1891 <term><literal>MaxPayloadTransferSize</literal></term>
1892 <listitem><para>
1893 Specifies the maximum number of bytes that the VM receives
1894 from the emulated webcam in one buffer. The default
1895 setting is <literal>3060</literal> bytes, which is used by
1896 some webcams. If the VM is able to use larger buffers,
1897 higher values might reduce CPU load slightly. Note that
1898 some guest OSes might not suppport higher
1899 <literal>MaxPayloadTransferSize</literal> values.
1900 </para></listitem>
1901 </varlistentry>
1902 </variablelist>
1903 </refsect2>
1904 <refsect2 id="vboxmanage-controlvm-webcam-detach">
1905 <title>Detach a Webcam From a Virtual Machine</title>
1906 <remark role="help-copy-synopsis"/>
1907 <para>
1908 The <command>VBoxManage controlvm
1909 <replaceable>vmname</replaceable> webcam detach</command>
1910 command detaches a webcam from a running VM. Specify the webcam
1911 as the absolute path of the webcam on the host OS or as an
1912 alias. Use the <command>VBoxManage list webcams</command> to
1913 obtain the webcam alias.
1914 </para>
1915 <para>
1916 When a webcam device is detached from the host, the host OS
1917 determines how the emulated webcam behaves.
1918 </para>
1919 <itemizedlist>
1920 <listitem><para>
1921 <emphasis role="bold">Windows hosts:</emphasis> The emulated
1922 webcam device is detached from the VM automatically.
1923 </para></listitem>
1924 <listitem><para>
1925 <emphasis role="bold">Mac OS X hosts that run at least OS X
1926 10.7:</emphasis> The emulated webcam device remains attached
1927 to the VM and you must detach it manually by using the
1928 <command>VBoxManage controlvm webcam detach</command>
1929 command.
1930 </para></listitem>
1931 <listitem><para>
1932 <emphasis role="bold">Linux hosts:</emphasis> The emulated
1933 webcam device is detached from the VM automatically only if
1934 the webcam is actively streaming video. If the emulated
1935 webcam is inactive, manually detach it by using the
1936 <command>VBoxManage controlvm
1937 <replaceable>vmname</replaceable> webcam detach</command>
1938 command.
1939 </para></listitem>
1940 </itemizedlist>
1941 </refsect2>
1942 <refsect2 id="vboxmanage-controlvm-webcam-list">
1943 <title>List the Webcams Attached to a Virtual Machine</title>
1944 <remark role="help-copy-synopsis"/>
1945 <para>
1946 The <command>VBoxManage controlvm
1947 <replaceable>vmname</replaceable> webcam list</command> command
1948 lists webcams that are attached to the running VM. The output
1949 shows a list of absolute paths or aliases that attached the
1950 webcams to the VM by using the <command>VBoxManage controlvm
1951 <replaceable>vmname</replaceable> webcam attach</command>
1952 command.
1953 </para>
1954 </refsect2>
1955 <refsect2 id="vboxmanage-controlvm-addencpassword">
1956 <title>Set an Encryption Password for a Virtual Machine</title>
1957 <remark role="help-copy-synopsis"/>
1958 <para>
1959 The <command>VBoxManage controlvm
1960 <replaceable>vmname</replaceable> addencpassword</command>
1961 command provides the <replaceable>vmname</replaceable> encrypted
1962 VM with the encryption password to enable a headless start.
1963 Specify the absolute path of a password file on the host system.
1964 If <replaceable>filename</replaceable> is <literal>-</literal>,
1965 <command>VBoxManage</command> prompts for the encryption
1966 password.
1967 </para>
1968 <para>
1969 Use the <option>--removeonsuspend</option> option to specify
1970 whether to save the passsword or clear it from VM memory when
1971 the VM is suspended.
1972 </para>
1973 <para>
1974 If the VM is suspended and the password is cleared, use the
1975 <command>VBoxManage controlvm <replaceable>vmname</replaceable>
1976 addencpassword</command> to provide the password to resume
1977 execution on the VM. Use this feature when you do not want to
1978 store the password in VM memory while the VM is suspended by a
1979 host suspend event.
1980 </para>
1981 <note>
1982 <para>
1983 You can encrypt data stored on hard disk images used by the
1984 VM. &product-name; uses the AES algorithm in XTS mode and
1985 supports 128-bit or 256-bit data encryption keys (DEK). The
1986 encrypted DEK is stored in the medium properties and is
1987 decrypted during VM startup when you provide the encryption
1988 password.
1989 </para>
1990 </note>
1991 <para>
1992 Use the <command>VBoxManage encryptmedium</command> command to
1993 create a DEK encrypted medium. See
1994 <xref linkend="diskencryption-encryption" />.
1995 </para>
1996 <para>
1997 The &product-name; GUI prompts you for the encryption password
1998 when you start an encrypted VM.
1999 </para>
2000 <para>
2001 Use the following command to perform a headless start of an
2002 encrypted VM:
2003 </para>
2004<screen>
2005 $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless
2006 </screen>
2007 <para>
2008 Then, use the following command to provide the encryption
2009 password:
2010 </para>
2011<screen>
2012 $ VBoxManage <replaceable>vmname</replaceable> controlvm addencpassword <replaceable>vmname</replaceable> -
2013 Password: <replaceable>encryption-password</replaceable>
2014 </screen>
2015 </refsect2>
2016 <refsect2 id="vboxmanage-controlvm-removeencpassword">
2017 <title>Disable an Encryption Password for a Virtual Machine</title>
2018 <remark role="help-copy-synopsis"/>
2019 <para>
2020 The <command>VBoxManage controlvm
2021 <replaceable>vmname</replaceable> removeencpassword</command>
2022 command disables a specific encryption password for all
2023 encrypted media attached to the VM.
2024 </para>
2025 <para>
2026 <replaceable>ID</replaceable> is the password identifier for the
2027 encryption password that you want to disable.
2028 </para>
2029 </refsect2>
2030 <refsect2 id="vboxmanage-controlvm-removeallencpasswords">
2031 <title>Disable All Encryption Passwords for a Virtual Machine</title>
2032 <remark role="help-copy-synopsis"/>
2033 <para>
2034 The <command>VBoxManage controlvm
2035 <replaceable>vmname</replaceable>
2036 removeallencpasswords</command> command disables all encryption
2037 passwords for all encrypted media attached to the VM.
2038 </para>
2039 </refsect2>
2040 <refsect2 id="vboxmanage-controlvm-changeuartmode">
2041 <title>Change the Connection Mode for a Virtual Serial Port on a Virtual
2042 Machine</title>
2043 <remark role="help-copy-synopsis"/>
2044 <para>
2045 The <command>VBoxManage controlvm
2046 <replaceable>vmname</replaceable> changeuartmode</command>
2047 command changes the connection mode for the specified virtual
2048 serial port. Valid serial port values are integers that start
2049 from <literal>1</literal>.
2050 </para>
2051 <variablelist>
2052 <varlistentry>
2053 <term>disconnected</term>
2054 <listitem><para>
2055 Disconnects the device.
2056 </para></listitem>
2057 </varlistentry>
2058 <varlistentry>
2059 <term>server <replaceable>pipe-name</replaceable></term>
2060 <listitem><para>
2061 Specifies the pipe name of the server.
2062 </para></listitem>
2063 </varlistentry>
2064 <varlistentry>
2065 <term>client <replaceable>pipe-name</replaceable></term>
2066 <listitem><para>
2067 Specifies the pipe name of the client.
2068 </para></listitem>
2069 </varlistentry>
2070 <varlistentry>
2071 <term>tcpserver <replaceable>port</replaceable></term>
2072 <listitem><para>
2073 Specifies the port number of the TCP server.
2074 </para></listitem>
2075 </varlistentry>
2076 <varlistentry>
2077 <term>tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></term>
2078 <listitem><para>
2079 Specifies the host name and port number of the TCP client.
2080 </para></listitem>
2081 </varlistentry>
2082 <varlistentry>
2083 <term>file <replaceable>filename</replaceable></term>
2084 <listitem><para>
2085 Specifies the name of the file.
2086 </para></listitem>
2087 </varlistentry>
2088 <varlistentry>
2089 <term><replaceable>device-name</replaceable></term>
2090 <listitem><para>
2091 Specifies the name of the device.
2092 </para></listitem>
2093 </varlistentry>
2094 </variablelist>
2095 </refsect2>
2096 <refsect2 id="vboxmanage-controlvm-autostart-enabled">
2097 <title>Enabling autostart the VM during host system boot</title>
2098 <remark role="help-copy-synopsis"/>
2099 <para>
2100 The <command>VBoxManage controlvm
2101 <replaceable>vmname</replaceable> autostart-enabled</command>
2102 command specifies whether to enable or disable automatically
2103 start the VM at host system boot-up. You must do some host
2104 system configuration before you can use this feature.
2105 See <xref linkend="autostart" />. Valid values are
2106 <literal>on</literal>, which enables autostart feature for
2107 the VM and <literal>off</literal>, which disables it. The
2108 default value is <literal>off</literal>.
2109 </para>
2110 </refsect2>
2111 <refsect2 id="vboxmanage-controlvm-autostart-delay">
2112 <title>Setting the delay of starting the VM on host system boot</title>
2113 <remark role="help-copy-synopsis"/>
2114 <para>
2115 The <command>VBoxManage controlvm
2116 <replaceable>vmname</replaceable> autostart-delay</command>
2117 command specifies the delay in seconds before the VM starts
2118 on host system boot-up. See <xref linkend="autostart" />.
2119 </para>
2120 </refsect2>
2121 </refsect1>
2122
2123 <refsect1 id="vboxmanage-controlvm-examples">
2124 <title>Examples</title>
2125 <remark role="help-scope" condition="GLOBAL" />
2126 <para>
2127 The following command temporarily stops the execution of the
2128 <filename>ol7</filename> VM.
2129 </para>
2130<screen>$ VBoxManage controlvm ol7 pause</screen>
2131 <para>
2132 The following command configures shared clipboard operation for
2133 the <filename>ol7</filename> VM. Copying of clipboard data is
2134 allowed in both directions between the host and guest.
2135 </para>
2136<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen>
2137 </refsect1>
2138
2139 <refsect1 id="vboxmanage-controlvm-see-also">
2140 <title>See Also</title>
2141 <para>
2142 <xref linkend="vboxmanage-list" />,
2143 <xref linkend="vboxmanage-modifyvm" />,
2144 <xref linkend="vboxmanage-startvm" />
2145 </para>
2146 </refsect1>
2147</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette