VirtualBox

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

Last change on this file since 85918 was 84575, checked in by vboxsync, 5 years ago

Guest Control/VBoxManage: Added "controlvm [...] reboot|shutdown" commands to reboot or shut down the guest OS. bugref:9320

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