man_VBoxManage-modifyvm.xml@ 94660

Last change on this file since 94660 was 94070, checked in by vboxsync, 3 years ago
CloudNet: bugref:9469 Dropped local gateway parameters in VBoxManage cloud network setup, added support for cloud network attachment in VBoxManage modifyvm, updated help for both, bug fixes and minor improvements in error reporting.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 126.8 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!--
3	manpage, user manual, usage: VBoxManage modifyvm
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-modifyvm" lang="en">
21	<refentryinfo>
22	<pubdate>$Date: 2022-03-03 11:54:06 +0000 (Thu, 03 Mar 2022) $</pubdate>
23	<title>VBoxManage modifyvm</title>
24	</refentryinfo>
25
26	<refmeta>
27	<refentrytitle>VBoxManage-modifyvm</refentrytitle>
28	<manvolnum>1</manvolnum>
29	</refmeta>
30
31	<refnamediv>
32	<refname>VBoxManage-modifyvm</refname>
33	<refpurpose>Change settings for a virtual machine that is stopped</refpurpose>
34	<refclass>&product-name;</refclass>
35	</refnamediv>
36
37	<refsynopsisdiv>
38	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-general">
39	<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
40	<command>VBoxManage modifyvm</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>--name=<replaceable>name</replaceable></arg>
46	<arg>--groups= <arg choice="plain"><replaceable>group</replaceable> [,<replaceable>group</replaceable>...]</arg></arg>
47	<arg>--description=<replaceable>description</replaceable></arg>
48	<arg>--os-type=<replaceable>OS-type</replaceable></arg>
49	<arg>--icon-file=<replaceable>filename</replaceable></arg>
50	<arg>--memory=<replaceable>size-in-MB</replaceable></arg>
51	<arg>--page-fusion=<group choice="plain">
52	<arg choice="plain">on</arg>
53	<arg choice="plain">off</arg>
54	</group></arg>
55	<arg>--vram=<replaceable>size-in-MB</replaceable></arg>
56	<arg>--acpi=<group choice="plain">
57	<arg choice="plain">on</arg>
58	<arg choice="plain">off</arg>
59	</group></arg>
60	<arg>--ioapic=<group choice="plain">
61	<arg choice="plain">on</arg>
62	<arg choice="plain">off</arg>
63	</group></arg>
64	<arg>--hardware-uuid=<replaceable>UUID</replaceable></arg>
65	<arg>--cpus=<replaceable>CPU-count</replaceable></arg>
66	<arg>--cpu-hotplug=<group choice="plain">
67	<arg choice="plain">on</arg>
68	<arg choice="plain">off</arg>
69	</group></arg>
70	<arg>--plug-cpu=<replaceable>CPU-ID</replaceable></arg>
71	<arg>--unplug-cpu=<replaceable>CPU-ID</replaceable></arg>
72	<arg>--cpu-execution-cap=<replaceable>number</replaceable></arg>
73	<arg>--pae=<group choice="plain">
74	<arg choice="plain">on</arg>
75	<arg choice="plain">off</arg>
76	</group></arg>
77	<arg>--long-mode=<group choice="plain">
78	<arg choice="plain">on</arg>
79	<arg choice="plain">off</arg>
80	</group></arg>
81	<arg>--ibpb-on-vm-exit=<group choice="plain">
82	<arg choice="plain">on</arg>
83	<arg choice="plain">off</arg>
84	</group></arg>
85	<arg>--ibpb-on-vm-entry=<group choice="plain">
86	<arg choice="plain">on</arg>
87	<arg choice="plain">off</arg>
88	</group></arg>
89	<arg>--spec-ctrl=<group choice="plain">
90	<arg choice="plain">on</arg>
91	<arg choice="plain">off</arg>
92	</group></arg>
93	<arg>--l1d-flush-on-sched=<group choice="plain">
94	<arg choice="plain">on</arg>
95	<arg choice="plain">off</arg>
96	</group></arg>
97	<arg>--l1d-flush-on-vm-entry=<group choice="plain">
98	<arg choice="plain">on</arg>
99	<arg choice="plain">off</arg>
100	</group></arg>
101	<arg>--mds-clear-on-sched=<group choice="plain">
102	<arg choice="plain">on</arg>
103	<arg choice="plain">off</arg>
104	</group></arg>
105	<arg>--mds-clear-on-vm-entry=<group choice="plain">
106	<arg choice="plain">on</arg>
107	<arg choice="plain">off</arg>
108	</group></arg>
109	<arg>--cpu-profile=<group choice="plain">
110	<arg choice="plain">host</arg>
111	<arg choice="plain">Intel 8086</arg>
112	<arg choice="plain">Intel 80286</arg>
113	<arg choice="plain">Intel 80386</arg>
114	</group></arg>
115	<arg>--hpet=<group choice="plain">
116	<arg choice="plain">on</arg>
117	<arg choice="plain">off</arg>
118	</group></arg>
119	<arg>--hwvirtex=<group choice="plain">
120	<arg choice="plain">on</arg>
121	<arg choice="plain">off</arg>
122	</group></arg>
123	<arg>--triple-fault-reset=<group choice="plain">
124	<arg choice="plain">on</arg>
125	<arg choice="plain">off</arg>
126	</group></arg>
127	<arg>--apic=<group choice="plain">
128	<arg choice="plain">on</arg>
129	<arg choice="plain">off</arg>
130	</group></arg>
131	<arg>--x2apic=<group choice="plain">
132	<arg choice="plain">on</arg>
133	<arg choice="plain">off</arg>
134	</group></arg>
135	<arg>--paravirt-provider=<group choice="plain">
136	<arg choice="plain">none</arg>
137	<arg choice="plain">default</arg>
138	<arg choice="plain">legacy</arg>
139	<arg choice="plain">minimal</arg>
140	<arg choice="plain">hyperv</arg>
141	<arg choice="plain">kvm</arg>
142	</group></arg>
143	<arg>--paravirt-debug= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable> [,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg>
144	<arg>--nested-paging=<group choice="plain">
145	<arg choice="plain">on</arg>
146	<arg choice="plain">off</arg>
147	</group></arg>
148	<arg>--large-pages=<group choice="plain">
149	<arg choice="plain">on</arg>
150	<arg choice="plain">off</arg>
151	</group></arg>
152	<arg>--vtx-vpid=<group choice="plain">
153	<arg choice="plain">on</arg>
154	<arg choice="plain">off</arg>
155	</group></arg>
156	<arg>--vtx-ux=<group choice="plain">
157	<arg choice="plain">on</arg>
158	<arg choice="plain">off</arg>
159	</group></arg>
160	<arg>--nested-hw-virt=<group choice="plain">
161	<arg choice="plain">on</arg>
162	<arg choice="plain">off</arg>
163	</group></arg>
164	<arg>--virt-vmsave-vmload=<group choice="plain">
165	<arg choice="plain">on</arg>
166	<arg choice="plain">off</arg>
167	</group></arg>
168	<arg>--accelerate-3d=<group choice="plain">
169	<arg choice="plain">on</arg>
170	<arg choice="plain">off</arg>
171	</group></arg>
172	<arg>--accelerate-2d-video=<group choice="plain">
173	<arg choice="plain">on</arg>
174	<arg choice="plain">off</arg>
175	</group></arg>
176	<arg>--chipset=<group choice="plain">
177	<arg choice="plain">ich9</arg>
178	<arg choice="plain">piix3</arg>
179	</group></arg>
180	<arg>--iommu=<group choice="plain">
181	<arg choice="plain">none</arg>
182	<arg choice="plain">automatic</arg>
183	<arg choice="plain">amd</arg>
184	<arg choice="plain">intel</arg>
185	</group></arg>
186	<arg>--tpm-type=<group choice="plain">
187	<arg choice="plain">none</arg>
188	<arg choice="plain">1.2</arg>
189	<arg choice="plain">2.0</arg>
190	<arg choice="plain">host</arg>
191	<arg choice="plain">swtpm</arg>
192	</group></arg>
193	<arg>--tpm-location=<group choice="plain">
194	<arg choice="plain"><replaceable>location</replaceable></arg>
195	</group></arg>
196	<arg>--bios-logo-fade-in=<group choice="plain">
197	<arg choice="plain">on</arg>
198	<arg choice="plain">off</arg>
199	</group></arg>
200	<arg>--bios-logo-fade-out=<group choice="plain">
201	<arg choice="plain">on</arg>
202	<arg choice="plain">off</arg>
203	</group></arg>
204	<arg>--bios-logo-display-time=<replaceable>msec</replaceable></arg>
205	<arg>--bios-logo-image-path=<replaceable>pathname</replaceable></arg>
206	<arg>--bios-boot-menu=<group choice="plain">
207	<arg choice="plain">disabled</arg>
208	<arg choice="plain">menuonly</arg>
209	<arg choice="plain">messageandmenu</arg>
210	</group></arg>
211	<arg>--bios-apic=<group choice="plain">
212	<arg choice="plain">disabled</arg>
213	<arg choice="plain">apic</arg>
214	<arg choice="plain">x2apic</arg>
215	</group></arg>
216	<arg>--bios-system-time-offset=<replaceable>msec</replaceable></arg>
217	<arg>--bios-pxe-debug=<group choice="plain">
218	<arg choice="plain">on</arg>
219	<arg choice="plain">off</arg>
220	</group></arg>
221	<arg>--system-uuid-le=<group choice="plain">
222	<arg choice="plain">on</arg>
223	<arg choice="plain">off</arg>
224	</group></arg>
225	<arg>--boot<replaceable>X</replaceable>=<group choice="plain">
226	<arg choice="plain">none</arg>
227	<arg choice="plain">floppy</arg>
228	<arg choice="plain">dvd</arg>
229	<arg choice="plain">disk</arg>
230	<arg choice="plain">net</arg>
231	</group></arg>
232	<arg>--rtc-use-utc=<group choice="plain">
233	<arg choice="plain">on</arg>
234	<arg choice="plain">off</arg>
235	</group></arg>
236	<arg>--graphicscontroller=<group choice="plain">
237	<arg choice="plain">none</arg>
238	<arg choice="plain">vboxvga</arg>
239	<arg choice="plain">vmsvga</arg>
240	<arg choice="plain">vboxsvga</arg>
241	</group></arg>
242	<arg>--snapshot-folder=<group choice="plain">
243	<arg choice="plain">default</arg>
244	<arg choice="plain"><replaceable>pathname</replaceable></arg>
245	</group></arg>
246	<arg>--firmware=<group choice="plain">
247	<arg choice="plain">bios</arg>
248	<arg choice="plain">efi</arg>
249	<arg choice="plain">efi32</arg>
250	<arg choice="plain">efi64</arg>
251	</group></arg>
252	<arg>--guest-memory-balloon=<replaceable>size-in-MB</replaceable></arg>
253	<arg>--default-frontend=<group choice="plain">
254	<arg choice="plain">default</arg>
255	<arg choice="plain"><replaceable>name</replaceable></arg>
256	</group></arg>
257	<!-- There are currently undocumented options --iocache and
258	--iocachesize which are scheduled for removal. Not worth spending
259	time on documenting it. -->
260	<arg>--vm-process-priority=<group choice="plain">
261	<arg choice="plain">default</arg>
262	<arg choice="plain">flat</arg>
263	<arg choice="plain">low</arg>
264	<arg choice="plain">normal</arg>
265	<arg choice="plain">high</arg>
266	</group></arg>
267	</cmdsynopsis>
268
269	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking">
270	<command>VBoxManage modifyvm</command>
271	<group choice="req">
272	<arg choice="plain"><replaceable>uuid</replaceable></arg>
273	<arg choice="plain"><replaceable>vmname</replaceable></arg>
274	</group>
275	<arg>--nic<replaceable>N</replaceable>=<group choice="plain">
276	<arg choice="plain">none</arg>
277	<arg choice="plain">null</arg>
278	<arg choice="plain">nat</arg>
279	<arg choice="plain">bridged</arg>
280	<arg choice="plain">intnet</arg>
281	<arg choice="plain">hostonly</arg>
282	<arg choice="plain">hostonlynet</arg>
283	<arg choice="plain">generic</arg>
284	<arg choice="plain">natnetwork</arg>
285	<arg choice="plain">cloud</arg>
286	</group></arg>
287	<arg>--nic-type<replaceable>N</replaceable>=<group choice="plain">
288	<arg choice="plain">Am79C970A</arg>
289	<arg choice="plain">Am79C973</arg>
290	<arg choice="plain">82540EM</arg>
291	<arg choice="plain">82543GC</arg>
292	<arg choice="plain">82545EM</arg>
293	<arg choice="plain">virtio</arg>
294	</group></arg>
295	<arg>--cable-connected<replaceable>N</replaceable>=<group choice="plain">
296	<arg choice="plain">on</arg>
297	<arg choice="plain">off</arg>
298	</group></arg>
299	<arg>--nic-trace<replaceable>N</replaceable>=<group choice="plain">
300	<arg choice="plain">on</arg>
301	<arg choice="plain">off</arg>
302	</group></arg>
303	<arg>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg>
304	<arg>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>= <arg><replaceable>value</replaceable></arg></arg>
305	<arg>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></arg>
306	<arg>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></arg>
307	<arg>--nic-promisc<replaceable>N</replaceable>=<group choice="plain">
308	<arg choice="plain">deny</arg>
309	<arg choice="plain">allow-vms</arg>
310	<arg choice="plain">allow-all</arg>
311	</group></arg>
312	<arg>--nic-bandwidth-group<replaceable>N</replaceable>=<group choice="plain">
313	<arg choice="plain">none</arg>
314	<arg choice="plain"><replaceable>name</replaceable></arg>
315	</group></arg>
316	<arg>--bridge-adapter<replaceable>N</replaceable>=<group choice="plain">
317	<arg choice="plain">none</arg>
318	<arg choice="plain"><replaceable>device-name</replaceable></arg>
319	</group></arg>
320	<arg>--cloud-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg>
321	<arg>--host-only-adapter<replaceable>N</replaceable>=<group choice="plain">
322	<arg choice="plain">none</arg>
323	<arg choice="plain"><replaceable>device-name</replaceable></arg>
324	</group></arg>
325	<arg>--host-only-net<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg>
326	<arg>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg>
327	<arg>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg>
328	<arg>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>driver-name</replaceable></arg>
329	<arg>--mac-address<replaceable>N</replaceable>=<group choice="plain">
330	<arg choice="plain">auto</arg>
331	<arg choice="plain"><replaceable>MAC-address</replaceable></arg>
332	</group></arg>
333	</cmdsynopsis>
334
335	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking-nat">
336	<command>VBoxManage modifyvm</command>
337	<group choice="req">
338	<arg choice="plain"><replaceable>uuid</replaceable></arg>
339	<arg choice="plain"><replaceable>vmname</replaceable></arg>
340	</group>
341	<arg>--nat-net<replaceable>N</replaceable>=<group choice="plain">
342	<arg choice="plain"><replaceable>network</replaceable></arg>
343	<arg choice="plain">default</arg>
344	</group></arg>
345	<arg>--nat-pf<replaceable>N</replaceable>=<group choice="plain">
346	<arg choice="plain">[<replaceable>rule-name</replaceable>],tcp</arg>
347	<arg choice="plain">udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></arg>
348	</group></arg>
349	<arg>--nat-pf<replaceable>N</replaceable>=delete=<replaceable>rule-name</replaceable></arg>
350	<arg>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></arg>
351	<arg>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg>
352	<arg>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg>
353	<arg>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg>
354	<arg>--nat-dns-pass-domain<replaceable>N</replaceable>=<group choice="plain">
355	<arg choice="plain">on</arg>
356	<arg choice="plain">off</arg>
357	</group></arg>
358	<arg>--nat-dns-proxy<replaceable>N</replaceable>=<group choice="plain">
359	<arg choice="plain">on</arg>
360	<arg choice="plain">off</arg>
361	</group></arg>
362	<arg>--nat-dns-host-resolver<replaceable>N</replaceable>=<group choice="plain">
363	<arg choice="plain">on</arg>
364	<arg choice="plain">off</arg>
365	</group></arg>
366	<arg>--nat-localhostreachable<replaceable>N</replaceable>=<group choice="plain">
367	<arg choice="plain">on</arg>
368	<arg choice="plain">off</arg>
369	</group></arg>
370	<arg>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</arg>
371	<arg>--nat-alias-mode<replaceable>N</replaceable>=<group choice="plain">
372	<arg choice="plain">default</arg>
373	<arg choice="plain">[log],[proxyonly],[sameports]</arg>
374	</group></arg>
375	</cmdsynopsis>
376
377	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-other-hardware">
378	<command>VBoxManage modifyvm</command>
379	<group choice="req">
380	<arg choice="plain"><replaceable>uuid</replaceable></arg>
381	<arg choice="plain"><replaceable>vmname</replaceable></arg>
382	</group>
383	<arg>--mouse=<group choice="plain">
384	<arg choice="plain">ps2</arg>
385	<arg choice="plain">usb</arg>
386	<arg choice="plain">usbtablet</arg>
387	<arg choice="plain">usbmultitouch</arg>
388	</group></arg>
389	<arg>--keyboard=<group choice="plain">
390	<arg choice="plain">ps2</arg>
391	<arg choice="plain">usb</arg>
392	</group></arg>
393	<arg>--uart<replaceable>N</replaceable>=<group choice="plain">
394	<arg choice="plain">off</arg>
395	<arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg>
396	</group></arg>
397	<arg>--uart-mode<replaceable>N</replaceable>=<group choice="plain">
398	<arg choice="plain">disconnected</arg>
399	<arg choice="plain">server <replaceable>pipe</replaceable></arg>
400	<arg choice="plain">client <replaceable>pipe</replaceable></arg>
401	<arg choice="plain">tcpserver <replaceable>port</replaceable></arg>
402	<arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg>
403	<arg choice="plain">file <replaceable>filename</replaceable></arg>
404	<arg choice="plain"><replaceable>device-name</replaceable></arg>
405	</group></arg>
406	<arg>--uart-type<replaceable>N</replaceable>=<group choice="plain">
407	<arg choice="plain">16450</arg>
408	<arg choice="plain">16550A</arg>
409	<arg choice="plain">16750</arg>
410	</group></arg>
411	<arg>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></arg>
412	<arg>--lpt<replaceable>N</replaceable>=<group choice="plain">
413	<arg choice="plain">off</arg>
414	<arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg>
415	</group></arg>
416	<arg>--audio=<group choice="plain">
417	<arg choice="plain">none</arg>
418	<arg choice="plain">null</arg>
419	<arg choice="plain">dsound</arg>
420	<arg choice="plain">oss</arg>
421	<arg choice="plain">alsa</arg>
422	<arg choice="plain">pulse</arg>
423	<arg choice="plain">coreaudio</arg>
424	</group></arg>
425	<arg>--audio-controller=<group choice="plain">
426	<arg choice="plain">ac97</arg>
427	<arg choice="plain">hda</arg>
428	<arg choice="plain">sb16</arg>
429	</group></arg>
430	<arg>--audio-codec=<group choice="plain">
431	<arg choice="plain">stac9700</arg>
432	<arg choice="plain">ad1980</arg>
433	<arg choice="plain">stac9221</arg>
434	<arg choice="plain">sb16</arg>
435	</group></arg>
436	<arg>--audio-in=<group choice="plain">
437	<arg choice="plain">on</arg>
438	<arg choice="plain">off</arg>
439	</group></arg>
440	<arg>--audio-out=<group choice="plain">
441	<arg choice="plain">on</arg>
442	<arg choice="plain">off</arg>
443	</group></arg>
444	<arg>--clipboard-mode=<group choice="plain">
445	<arg choice="plain">disabled</arg>
446	<arg choice="plain">hosttoguest</arg>
447	<arg choice="plain">guesttohost</arg>
448	<arg choice="plain">bidirectional</arg>
449	</group></arg>
450	<!-- There is a currently undocumented option --clipboard-file-transfers.
451	The implementation is not finished, so postpone documenting until it
452	actually is ready for users. -->
453	<arg>--drag-and-drop=<group choice="plain">
454	<arg choice="plain">disabled</arg>
455	<arg choice="plain">hosttoguest</arg>
456	<arg choice="plain">guesttohost</arg>
457	<arg choice="plain">bidirectional</arg>
458	</group></arg>
459	<arg>--monitor-count=<replaceable>number</replaceable></arg>
460	<arg>--usb-ehci=<group choice="plain">
461	<arg choice="plain">on</arg>
462	<arg choice="plain">off</arg>
463	</group></arg>
464	<arg>--usb-ohci=<group choice="plain">
465	<arg choice="plain">on</arg>
466	<arg choice="plain">off</arg>
467	</group></arg>
468	<arg>--usb-xhci=<group choice="plain">
469	<arg choice="plain">on</arg>
470	<arg choice="plain">off</arg>
471	</group></arg>
472	<arg>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></arg>
473	</cmdsynopsis>
474
475	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-recording">
476	<command>VBoxManage modifyvm</command>
477	<group choice="req">
478	<arg choice="plain"><replaceable>uuid</replaceable></arg>
479	<arg choice="plain"><replaceable>vmname</replaceable></arg>
480	</group>
481	<arg>--recording=<group choice="plain">
482	<arg choice="plain">on</arg>
483	<arg choice="plain">off</arg>
484	</group></arg>
485	<arg>--recording-screens=<group choice="plain">
486	<arg choice="plain">all</arg>
487	<arg choice="plain">none</arg>
488	<arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg>
489	</group></arg>
490	<arg>--recording-file=<replaceable>filename</replaceable></arg>
491	<arg>--recording-max-size=<replaceable>MB</replaceable></arg>
492	<arg>--recording-max-time=<replaceable>msec</replaceable></arg>
493	<arg>--recording-opts= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable>[,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg>
494	<arg>--recording-video-fps=<replaceable>fps</replaceable></arg>
495	<arg>--recording-video-rate=<replaceable>rate</replaceable></arg>
496	<arg>--recording-video-res=<replaceable>width</replaceable> <replaceable>height</replaceable></arg>
497	</cmdsynopsis>
498
499	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-vrde">
500	<command>VBoxManage modifyvm</command>
501	<group choice="req">
502	<arg choice="plain"><replaceable>uuid</replaceable></arg>
503	<arg choice="plain"><replaceable>vmname</replaceable></arg>
504	</group>
505	<arg>--vrde=<group choice="plain">
506	<arg choice="plain">on</arg>
507	<arg choice="plain">off</arg>
508	</group></arg>
509	<arg>--vrde-property=<replaceable>property-name</replaceable>= <arg><replaceable>property-value</replaceable></arg></arg>
510	<arg>--vrde-extpack=<group choice="plain">
511	<arg choice="plain">default</arg>
512	<arg choice="plain"><replaceable>name</replaceable></arg>
513	</group></arg>
514	<arg>--vrde-port=<replaceable>port</replaceable></arg>
515	<arg>--vrde-address=<replaceable>hostip</replaceable></arg>
516	<arg>--vrde-auth-type=<group choice="plain">
517	<arg choice="plain">null</arg>
518	<arg choice="plain">external</arg>
519	<arg choice="plain">guest</arg>
520	</group></arg>
521	<arg>--vrde-auth-library=<group choice="plain">
522	<arg choice="plain">default</arg>
523	<arg choice="plain"><replaceable>name</replaceable></arg>
524	</group></arg>
525	<arg>--vrde-multi-con=<group choice="plain">
526	<arg choice="plain">on</arg>
527	<arg choice="plain">off</arg>
528	</group></arg>
529	<arg>--vrde-reuse-con=<group choice="plain">
530	<arg choice="plain">on</arg>
531	<arg choice="plain">off</arg>
532	</group></arg>
533	<arg>--vrde-video-channel=<group choice="plain">
534	<arg choice="plain">on</arg>
535	<arg choice="plain">off</arg>
536	</group></arg>
537	<arg>--vrde-video-channel-quality=<replaceable>percent</replaceable></arg>
538	</cmdsynopsis>
539
540	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-teleport">
541	<command>VBoxManage modifyvm</command>
542	<group choice="req">
543	<arg choice="plain"><replaceable>uuid</replaceable></arg>
544	<arg choice="plain"><replaceable>vmname</replaceable></arg>
545	</group>
546	<arg>--teleporter=<group choice="plain">
547	<arg choice="plain">on</arg>
548	<arg choice="plain">off</arg>
549	</group></arg>
550	<arg>--teleporter-port=<replaceable>port</replaceable></arg>
551	<arg>--teleporter-address=<group choice="plain">
552	<arg choice="plain"><replaceable>address</replaceable></arg>
553	<arg choice="plain">empty</arg>
554	</group></arg>
555	<arg>--teleporter-password=<replaceable>password</replaceable></arg>
556	<arg>--teleporter-password-file=<group choice="plain">
557	<arg choice="plain"><replaceable>filename</replaceable></arg>
558	<arg choice="plain">stdin</arg>
559	</group></arg>
560	<arg>--cpuid-portability-level=<replaceable>level</replaceable></arg>
561	<arg>--cpuid-set=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg>
562	<arg>--cpuid-remove=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg></arg>
563	<arg>--cpuid-remove-all</arg>
564	</cmdsynopsis>
565
566	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-debugging">
567	<command>VBoxManage modifyvm</command>
568	<group choice="req">
569	<arg choice="plain"><replaceable>uuid</replaceable></arg>
570	<arg choice="plain"><replaceable>vmname</replaceable></arg>
571	</group>
572	<arg>--tracing-enabled=<group choice="plain">
573	<arg choice="plain">on</arg>
574	<arg choice="plain">off</arg>
575	</group></arg>
576	<arg>--tracing-config=<replaceable>string</replaceable></arg>
577	<arg>--tracing-allow-vm-access=<group choice="plain">
578	<arg choice="plain">on</arg>
579	<arg choice="plain">off</arg>
580	</group></arg>
581	</cmdsynopsis>
582
583	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-usbcardreader">
584	<command>VBoxManage modifyvm</command>
585	<group choice="req">
586	<arg choice="plain"><replaceable>uuid</replaceable></arg>
587	<arg choice="plain"><replaceable>vmname</replaceable></arg>
588	</group>
589	<arg>--usb-card-reader=<group choice="plain">
590	<arg choice="plain">on</arg>
591	<arg choice="plain">off</arg>
592	</group></arg>
593	</cmdsynopsis>
594
595	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-autostart">
596	<command>VBoxManage modifyvm</command>
597	<group choice="req">
598	<arg choice="plain"><replaceable>uuid</replaceable></arg>
599	<arg choice="plain"><replaceable>vmname</replaceable></arg>
600	</group>
601	<arg>--autostart-enabled=<group choice="plain">
602	<arg choice="plain">on</arg>
603	<arg choice="plain">off</arg>
604	</group></arg>
605	<arg>--autostart-delay=<replaceable>seconds</replaceable></arg>
606	<!-- There is a currently undocumented option --autostop-type.
607	Most autostart service implementations either ignore it or rely it is
608	left unchanged due to otherwise running into timeouts established by the
609	host OS, defeating the purpose. Not worth spending time on documenting
610	it unless this changes. -->
611	</cmdsynopsis>
612
613	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough">
614	<command>VBoxManage modifyvm</command>
615	<group choice="req">
616	<arg choice="plain"><replaceable>uuid</replaceable></arg>
617	<arg choice="plain"><replaceable>vmname</replaceable></arg>
618	</group>
619	<arg>--pci-attach=<replaceable>host-PCI-address</replaceable><arg>@<replaceable>guest-PCI-bus-address</replaceable></arg></arg>
620	<arg>--pci-detach=<replaceable>host-PCI-address</replaceable></arg>
621	</cmdsynopsis>
622
623	<cmdsynopsis id="synopsis-vboxmanage-modifyvm-testing">
624	<command>VBoxManage modifyvm</command>
625	<group choice="req">
626	<arg choice="plain"><replaceable>uuid</replaceable></arg>
627	<arg choice="plain"><replaceable>vmname</replaceable></arg>
628	</group>
629	<arg>--testing-enabled=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg>
630	<arg>--testing-mmio=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg>
631	<arg>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></arg>
632	</cmdsynopsis>
633	</refsynopsisdiv>
634
635	<refsect1>
636	<title>Description</title>
637	<para>
638	The <command>VBoxManage modifyvm</command> command enables you to
639	change the properties of a registered virtual machine (VM) that is
640	not running.
641	</para>
642	<para>
643	Most of these properties correspond to the VM settings that are
644	shown in each VM's <emphasis role="bold">Settings</emphasis>
645	dialog in the VirtualBox Manager. See
646	<xref linkend="BasicConcepts" />. However, some settings can only
647	be viewed and managed with the <command>VBoxManage</command>
648	command.
649	</para>
650	<para>
651	You can use the <command>VBoxManage modifyvm</command> command to
652	change VM settings only when the VM is powered off. The VM cannot
653	be running or in saved state when you use this command.
654	</para>
655	<para>
656	You can use the <command>VBoxManage controlvm</command> command to
657	dynamically change some VM machine settings while the VM is
658	running. See <xref linkend="vboxmanage-controlvm" />.
659	</para>
660	<refsect2 id="vboxmanage-modifyvm-general">
661	<title>General Settings</title>
662	<remark role="help-copy-synopsis"/>
663	<para>
664	The following options enable you to modify general information
665	about your VM.
666	</para>
667	<para>
668	The <command>VBoxManage modifyvm</command> command supports the
669	following options:
670	</para>
671	<variablelist>
672	<varlistentry>
673	<term><option>--name=<replaceable>vmname</replaceable></option></term>
674	<listitem><para>
675	Changes the name of the VM and its related internal VM
676	files. See <xref linkend="vboxmanage-createvm"/>.
677	</para></listitem>
678	</varlistentry>
679	<varlistentry>
680	<term><option>--groups=<replaceable>group</replaceable></option></term>
681	<listitem><para>
682	Changes the group membership of a VM. Group names always
683	begin with a slash character (<literal>/</literal>) and
684	can be nested. By default, VMs are members of the
685	<literal>/</literal> group. A VM can be member of multiple
686	groups, but its primary group determines the directory
687	structure where the internal VM files are placed by default.
688	</para></listitem>
689	</varlistentry>
690	<varlistentry>
691	<term><option>--description=<replaceable>desc</replaceable></option></term>
692	<listitem><para>
693	Changes the optional VM description. Use a description to
694	record details about the VM in a meaningful way. The GUI
695	interprets HTML markup while the <command>VBoxManage
696	modifyvm</command> command enables you include arbitrary
697	strings that can contain multiple lines.
698	</para></listitem>
699	</varlistentry>
700	<varlistentry>
701	<term><option>--os-type=<replaceable>OS-type</replaceable></option></term>
702	<listitem><para>
703	Specifies the guest operating system (OS) information for
704	the VM. Use the <command>VBoxManage list ostypes</command>
705	command to view the OS type identifiers.
706	</para></listitem>
707	</varlistentry>
708	<varlistentry>
709	<term><option>--icon-file=<replaceable>filename</replaceable></option></term>
710	<listitem><para>
711	Specifies the path to the VM icon file in PNG format
712	on the host system. The icon is shown in the VM manager
713	UI and when running the VM with UI.
714	</para></listitem>
715	</varlistentry>
716	<varlistentry>
717	<term><option>--memory=<replaceable>size</replaceable></option></term>
718	<listitem><para>
719	Specifies the amount of host system RAM to allocate to the
720	VM. The size is in MB. See
721	<xref linkend="gui-createvm" />.
722	</para></listitem>
723	</varlistentry>
724	<varlistentry>
725	<term><option>--page-fusion=on \| off</option></term>
726	<listitem><para>
727	Enables or disables the Page Fusion feature, which is
728	disabled by default. Use the Page Fusion feature to
729	minimize the memory duplication between VMs that have
730	similar configurations and that run on the same host
731	system. See <xref linkend="guestadd-pagefusion" />.
732	</para></listitem>
733	</varlistentry>
734	<varlistentry>
735	<term><option>--vram=<replaceable>size</replaceable></option></term>
736	<listitem><para>
737	Specifies the amount of RAM to allocate to the virtual
738	graphics card. See <xref linkend="settings-display" />.
739	</para></listitem>
740	</varlistentry>
741	<varlistentry>
742	<term><option>--acpi=on \| off</option></term>
743	<listitem><para>
744	Determines whether the VM has ACPI support. See
745	<xref linkend="settings-motherboard" />.
746	</para></listitem>
747	</varlistentry>
748	<varlistentry>
749	<term><option>--ioapic=on \| off</option></term>
750	<listitem><para>
751	Determines whether the VM has I/O APIC support. See
752	<xref linkend="settings-motherboard" />.
753	</para></listitem>
754	</varlistentry>
755	<varlistentry>
756	<term><option>--hardware-uuid=<replaceable>uuid</replaceable></option></term>
757	<listitem><para>
758	Specifies the Universally Unique Identifier (UUID) to
759	present to the guest VM in memory tables (DMI/SMBIOS),
760	hardware, and VM properties. By default this hardware UUID
761	is the same as the VM UUID. Cloning a VM and the teleporting
762	feature automatically preserve the hardware UUID value.
763	Likewise for Virtual Appliance export and import, but only
764	if both operations are done by &product-name;.
765	</para></listitem>
766	</varlistentry>
767	<varlistentry>
768	<term><option>--cpus=<replaceable>CPU-count</replaceable></option></term>
769	<listitem><para>
770	Specifies the number of virtual CPUs to assign to the VM.
771	See <xref linkend="settings-processor" />.
772	</para><para>
773	If CPU hot-plugging is enabled, this option specifies the
774	maximum number of virtual CPUs that can be plugged into
775	the VMs.
776	</para></listitem>
777	</varlistentry>
778	<varlistentry>
779	<term><option>--cpu-hotplug=on \| off</option></term>
780	<listitem><para>
781	Enables or disables CPU hot-plugging. When enabled, you
782	can dynamically add virtual CPUs to a VM or remove virtual
783	CPUs from a VM. See <xref linkend="cpuhotplug" />.
784	</para></listitem>
785	</varlistentry>
786	<varlistentry>
787	<term><option>--plug-cpu=<replaceable>CPU-ID</replaceable></option></term>
788	<listitem><para>
789	Adds a virtual CPU to the VM.
790	<replaceable>CPU-ID</replaceable> is the index of the
791	virtual CPU to add. A valid index value is a number from
792	<literal>0</literal> to the maximum number of CPUs that
793	you configured by using the <option>--cpus</option>
794	option.
795	</para><para>
796	Only use this option if CPU hot-plugging is enabled.
797	</para></listitem>
798	</varlistentry>
799	<varlistentry>
800	<term><option>--unplug-cpu=<replaceable>CPU-ID</replaceable></option></term>
801	<listitem><para>
802	Removes a virtual CPU from the VM.
803	<replaceable>CPU-ID</replaceable> is the index of the
804	virtual CPU to remove. A valid index value is a number
805	from <literal>1</literal> to the maximum number of CPUs
806	that you configured by using the <option>--cpus</option>
807	option.
808	</para><para>
809	Only use this option if CPU hot-plugging is enabled.
810	</para><para>
811	Note that you cannot remove CPU 0.
812	</para></listitem>
813	</varlistentry>
814	<varlistentry>
815	<term><option>--cpuexectioncap=<replaceable>percentage</replaceable></option></term>
816	<listitem>
817	<para>
818	Specifies how much CPU time a virtual CPU can use. A valid
819	value is from <literal>1</literal> to
820	<literal>100</literal>. A value of 50 indicates that a
821	single virtual CPU can use up to 50% of a single host CPU.
822	</para>
823	<para>
824	Use this feature with caution, it can have unexpected results
825	including timekeeping problems and lower performance than
826	specified. If you want to limit the resource usage of a VM
827	it is more reliable to pick an appropriate number of VCPUs.
828	</para>
829	</listitem>
830	</varlistentry>
831	<varlistentry>
832	<term><option>--pae=on \| off</option></term>
833	<listitem><para>
834	Enables or disables physical address extension (PAE). See
835	<xref linkend="settings-processor" />.
836	</para></listitem>
837	</varlistentry>
838	<varlistentry>
839	<term><option>--long-mode=on \| off</option></term>
840	<listitem><para>
841	Enables or disables long mode. See
842	<xref linkend="settings-processor" />.
843	</para></listitem>
844	</varlistentry>
845	<varlistentry>
846	<term><option>--ibpb-on-vm-exit=on \| off</option></term>
847	<listitem><para>
848	Enables use of Indirect Branch Prediction Barrier (IBPB)
849	on every VM exit.
850	</para></listitem>
851	</varlistentry>
852	<varlistentry>
853	<term><option>--ibpb-on-vm-entry=on \| off</option></term>
854	<listitem><para>
855	Enables use of Indirect Branch Prediction Barrier (IBPB)
856	on every VM entry.
857	</para></listitem>
858	</varlistentry>
859	<varlistentry>
860	<term><option>--spec-ctrl=on \| off</option></term>
861	<listitem><para>
862	Enables or disables the exposure of speculation control
863	interfaces to the guest VM. These interfaces must be
864	available on the host system.
865	</para><para>
866	Depending on the host CPU and the workload, enabling
867	speculation control might significantly reduce
868	performance.
869	</para></listitem>
870	</varlistentry>
871	<varlistentry>
872	<term><option>--l1d-flush-on-sched=on \| off</option></term>
873	<listitem><para>
874	Enables or disables level 1 data cache flushing when a
875	thread is scheduled to execute guest code. See
876	<xref linkend="sec-rec-cve-2018-3646" />.
877	</para></listitem>
878	</varlistentry>
879	<varlistentry>
880	<term><option>--l1d-flush-on-vm-entry=on \| off</option></term>
881	<listitem><para>
882	Enables or disables level 1 data cache flushing on every
883	VM entry. See <xref linkend="sec-rec-cve-2018-3646" />.
884	</para></listitem>
885	</varlistentry>
886	<varlistentry>
887	<term><option>--mds-clear-on-sched=on \| off</option></term>
888	<listitem><para>
889	Enables CPU buffer clearing when a thread is scheduled to
890	execute guest code. See
891	<xref linkend="sec-rec-cve-2018-12126-et-al" />.
892	</para></listitem>
893	</varlistentry>
894	<varlistentry>
895	<term><option>--mds-clear-on-vm-entry=on \| off</option></term>
896	<listitem><para>
897	Enables CPU buffer clearing on every VM entry. See
898	<xref linkend="sec-rec-cve-2018-12126-et-al" />.
899	</para></listitem>
900	</varlistentry>
901	<varlistentry>
902	<term><option>--cpu-profile=host \| Intel 8086 \| Intel 80286 \| Intel 80386</option></term>
903	<listitem><para>
904	Specifies the profile to use for guest CPU emulation.
905	Specify a value that is based on the host system CPU
906	(<literal>host</literal>) or one of the following older
907	Intel micro-architectures: <literal>8086</literal>,
908	<literal>80286</literal>, or <literal>80386</literal>.
909	</para></listitem>
910	</varlistentry>
911	<varlistentry>
912	<term><option>--hpet=on \| off</option></term>
913	<listitem><para>
914	Enables or disables a High Precision Event Timer (HPET)
915	that can replace a legacy system timer. This feature is
916	disabled by default. Note HPET is supported on Windows
917	versions starting with Vista.
918	</para></listitem>
919	</varlistentry>
920	<varlistentry>
921	<term><option>--hwvirtex=on \| off</option></term>
922	<listitem><para>
923	Enables or disables the use of hardware virtualization
924	extensions in the processor of the host system. Such
925	extensions are Intel VT-x or AMD-V. See
926	<xref linkend="hwvirt" />.
927	</para></listitem>
928	</varlistentry>
929	<varlistentry>
930	<term><option>--triple-fault-reset=on \| off</option></term>
931	<listitem><para>
932	Enables or disables the resetting of the guest VM instead
933	of triggering a Guru Meditation. Some guest VMs raise a
934	triple fault to reset the CPU, so sometimes resetting the
935	guest VM is the best outcome. This option only applies to
936	guests that do not use symmetric multiprocessing (SMP).
937	</para></listitem>
938	</varlistentry>
939	<varlistentry>
940	<term><option>--apic=on \| off</option></term>
941	<listitem><para>
942	Enables or disables APIC. With APIC, OSes can use
943	more than 16 interrupt requests (IRQs) to avoid IRQ
944	sharing and to improve reliability. APIC is enabled by
945	default. See <xref linkend="settings-motherboard" />.
946	</para></listitem>
947	</varlistentry>
948	<varlistentry>
949	<term><option>--x2apic=on \| off</option></term>
950	<listitem><para>
951	Enables or disables the CPU x2APIC feature. CPU x2APIC
952	enables an OS to run more efficiently on high core count
953	configurations and to optimize interrupt distribution in
954	virtualized environments. This feature is enabled by
955	default.
956	</para><para>
957	Disable this feature when the OS that runs on a host
958	system or a guest VM is incompatible with CPU x2APIC.
959	</para></listitem>
960	</varlistentry>
961	<varlistentry>
962	<term><option>--paravirt-provider=none \| default \| legacy \| minimal \| hyperv \| kvm</option></term>
963	<listitem><para>
964	Specifies one of the following paravirtualization
965	interfaces to provide to the guest OS:
966	</para><itemizedlist>
967	<listitem><para>
968	<literal>none</literal> does not expose any
969	paravirtualization interface.
970	</para></listitem>
971	<listitem><para>
972	<literal>default</literal> selects the appropriate
973	interface based on the guest OS type when starting the
974	VM. This is the default value used when creating new
975	VMs.
976	</para></listitem>
977	<listitem><para>
978	<literal>legacy</literal> selects a paravirtual
979	interface for VMs that were created by older
980	&product-name; versions.
981	</para></listitem>
982	<listitem><para>
983	<literal>minimal</literal> is required for Mac OS X
984	guest VMs.
985	</para></listitem>
986	<listitem><para>
987	<literal>kvm</literal> is recommended for Linux guest
988	VMs. See <xref linkend="gimproviders" />.
989	</para></listitem>
990	<listitem><para>
991	<literal>hyperv</literal> is recommended for Windows
992	guest VMs. See <xref linkend="gimproviders" />.
993	</para></listitem>
994	</itemizedlist></listitem>
995	</varlistentry>
996	<varlistentry>
997	<term><option>--paravirt-debug=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term>
998	<listitem><para>
999	Specifies debugging properties that are specific to the
1000	paravirtualization provider configured for the specified
1001	VM. See <xref linkend="gimdebug" />.
1002	</para></listitem>
1003	</varlistentry>
1004	<varlistentry>
1005	<term><option>--nested-paging=on \| off</option></term>
1006	<listitem><para>
1007	Enables or disables the nested paging feature in the
1008	processor of the host system. This option is available
1009	only when hardware virtualization is enabled. See
1010	<xref linkend="hwvirt" /> and
1011	<xref linkend="sec-rec-cve-2018-3646" />.
1012	</para></listitem>
1013	</varlistentry>
1014	<varlistentry>
1015	<term><option>--large-pages=on \| off</option></term>
1016	<listitem><para>
1017	Enables or disables the hypervisor's use of large pages,
1018	which can improve performance by up to 5%. The use of
1019	large pages reduces TLB use and overhead. This option is
1020	available only when both hardware virtualization and
1021	nested paging are enabled.
1022	</para></listitem>
1023	</varlistentry>
1024	<varlistentry>
1025	<term><option>--vtx-vpid=on \| off</option></term>
1026	<listitem><para>
1027	Enables or disables the use of the tagged TLB (VPID)
1028	feature in the processor of your host system. See
1029	<xref linkend="hwvirt" />. This option is available only
1030	when hardware virtualization is enabled on Intel VT-x.
1031	</para></listitem>
1032	</varlistentry>
1033	<varlistentry>
1034	<term><option>--vtx-ux=on \| off</option></term>
1035	<listitem><para>
1036	Enables or disables the use of unrestricted guest mode for
1037	executing the guest VM. This option is available only when
1038	hardware virtualization is enabled on Intel VT-x.
1039	</para></listitem>
1040	</varlistentry>
1041	<varlistentry>
1042	<term><option>--nested-hw-virt=on \| off</option></term>
1043	<listitem><para>
1044	Enables or disables nested virtualization. Enabling makes
1045	hardware virtualization features available to the VM. See
1046	<xref linkend="nested-virt" />.
1047	</para></listitem>
1048	</varlistentry>
1049	<varlistentry>
1050	<term><option>--virt-vmsave-vmload=on \| off</option></term>
1051	<listitem><para>
1052	If hardware virtualization is enabled and the host has an
1053	AMD CPU, this setting enables or disables the use of the
1054	virtualized vmsave/vmload host feature while executing the
1055	VM. It is enabled by default. It is recommended to leave it
1056	enabled as it has a drastic impact on performance while
1057	executing nested VMs when using the nested hardware
1058	virtualization feature.
1059	<xref linkend="nested-virt" />.
1060	</para></listitem>
1061	</varlistentry>
1062	<varlistentry>
1063	<term><option>--accelerated3d=on \| off</option></term>
1064	<listitem><para>
1065	Enables or disables hardware 3D acceleration for the
1066	graphics adapter variants which support it. This option
1067	has an effect only when the Guest Additions are installed.
1068	See <xref linkend="guestadd-3d" />.
1069	</para></listitem>
1070	</varlistentry>
1071	<varlistentry>
1072	<term><option>--accelerated2dvideo=on \| off</option></term>
1073	<listitem><para>
1074	Enables or disables 2D video acceleration for the graphics
1075	adapter variants which support it. This option has an effect
1076	only when the Guest Additions are installed. See
1077	<xref linkend="guestadd-2d" />.
1078	</para></listitem>
1079	</varlistentry>
1080	<varlistentry>
1081	<term><option>--chipset=piix3 \| ich9</option></term>
1082	<listitem><para>
1083	Specify the Intel chipset for &product-name; to emulate.
1084	The default value is the Intel PIIX3 chipset
1085	(<literal>piix3</literal>).
1086	</para><para>
1087	Change this value only if you need to relax some of the
1088	chipset constraints. See
1089	<xref linkend="settings-motherboard" />.
1090	</para></listitem>
1091	</varlistentry>
1092	<varlistentry>
1093	<term><option>--iommu=none \| automatic \| amd \| intel</option></term>
1094	<listitem><para>
1095	Specifies the IOMMU type for &product-name; to emulate.
1096	Both Intel and AMD IOMMU emulation currently require the
1097	use of the Intel ICH9 chipset (see
1098	<option>--chipset</option> option).
1099	</para><para>
1100	Valid values are as follows:
1101	</para><itemizedlist>
1102	<listitem><para>
1103	<literal>none</literal> – No IOMMU is present
1104	and is the default value.
1105	</para></listitem>
1106	<listitem><para>
1107	<literal>automatic</literal> – An IOMMU is
1108	present but its type is automatically chosen to match
1109	the host CPU vendor when the VM is powered on.
1110	</para></listitem>
1111	<listitem><para>
1112	<literal>amd</literal> – An AMD IOMMU is
1113	present.
1114	</para></listitem>
1115	<listitem><para>
1116	<literal>intel</literal> – An Intel IOMMU is
1117	present.
1118	</para></listitem>
1119	</itemizedlist></listitem>
1120	</varlistentry>
1121	<varlistentry>
1122	<term><option>--tpm-type=none \| 1.2 \| 2.0 \| host \| swtpm</option></term>
1123	<listitem><para>
1124	Specifies the TPM type for &product-name; to emulate.
1125	</para><para>
1126	Valid values are as follows:
1127	</para><itemizedlist>
1128	<listitem><para>
1129	<literal>none</literal> – No TPM is present
1130	and is the default value.
1131	</para></listitem>
1132	<listitem><para>
1133	<literal>1.2</literal> – A TPM conforming to the TCG specification
1134	version 1.2 is present.
1135	</para></listitem>
1136	<listitem><para>
1137	<literal>2.0</literal> – A TPM conforming to the TCG specification
1138	version 2.0 is present.
1139	</para></listitem>
1140	<listitem><para>
1141	<literal>host</literal> – The host TPM is passed through to the guest.
1142	May not be available on all supported host platforms.
1143	</para></listitem>
1144	<listitem><para>
1145	<literal>swtpm</literal> – The VM connects to an external TPM emulation
1146	compliant to swtpm. Requires to set the TPM location to connect to (see
1147	<option>--tpm-location</option> option).
1148	</para></listitem>
1149	</itemizedlist></listitem>
1150	</varlistentry>
1151	<varlistentry>
1152	<term><option>--bios-logo-fade-in=on \| off</option></term>
1153	<listitem><para>
1154	Specifies whether the BIOS logo fades in on VM startup. By
1155	default, an &product-name; logo is shown.
1156	</para></listitem>
1157	</varlistentry>
1158	<varlistentry>
1159	<term><option>--bios-logo-fade-out=on \| off</option></term>
1160	<listitem><para>
1161	Specifies whether the BIOS logo fades out on VM startup.
1162	</para></listitem>
1163	</varlistentry>
1164	<varlistentry>
1165	<term><option>--bios-logo-display-time=<replaceable>msec</replaceable></option></term>
1166	<listitem><para>
1167	Specifies the amount of time in milliseconds that the BIOS
1168	logo is visible.
1169	</para></listitem>
1170	</varlistentry>
1171	<varlistentry>
1172	<term><option>--bios-logo-image-path=<replaceable>pathname</replaceable></option></term>
1173	<listitem><para>
1174	Replaces the existing BIOS logo with a different image.
1175	The replacement image must be an uncompressed 16, 256 or 16M
1176	color bitmap file (BMP) that does not contain color space
1177	information (Windows 3.0 format). Also ensure that the
1178	image is no larger than 640 X 480 pixels.
1179	</para></listitem>
1180	</varlistentry>
1181	<varlistentry>
1182	<term><option>--bios-boot-menu=disabled \| menuonly \| messageandmenu</option></term>
1183	<listitem><para>
1184	Specifies whether the BIOS permits you to select a
1185	temporary boot device. Valid values are:
1186	</para><itemizedlist>
1187	<listitem><para>
1188	<literal>disabled</literal> outputs the alternate boot
1189	device message and permits you to select a temporary
1190	boot device by pressing F12.
1191	</para></listitem>
1192	<listitem><para>
1193	<literal>menuonly</literal> suppresses the alternate
1194	boot device message, but permits you to select a
1195	temporary boot device by pressing F12.
1196	</para></listitem>
1197	<listitem><para>
1198	<literal>messageandmenu</literal> suppresses the
1199	alternate boot device message and prevents you from
1200	selecting a temporary boot device by pressing F12.
1201	</para></listitem>
1202	</itemizedlist></listitem>
1203	</varlistentry>
1204	<varlistentry>
1205	<term><option>--bios-apic=x2apic \| apic \| disabled</option></term>
1206	<listitem><para>
1207	Specifies the APIC level of the firmware. Valid values
1208	are: <literal>x2apic</literal>, <literal>apic</literal>,
1209	and <literal>disabled</literal>. When the value is
1210	<literal>disabled</literal>, neither the
1211	<literal>apic</literal> nor the <literal>x2apic</literal>
1212	version of the firmware is used.
1213	</para><para>
1214	Note that if you specify the <literal>x2apic</literal>
1215	value and x2APIC is unsupported by the virtual CPU, the
1216	APIC level downgrades to <literal>apic</literal>, if
1217	supported. Otherwise, the APIC level downgrades to
1218	<literal>disabled</literal>. Similarly, if you specify the
1219	<literal>apic</literal> value and APIC is unsupported by
1220	the virtual CPU, the APIC level downgrades to
1221	<literal>disabled</literal>.
1222	</para></listitem>
1223	</varlistentry>
1224	<varlistentry>
1225	<term><option>--bios-system-time-offset=<replaceable>msec</replaceable></option></term>
1226	<listitem><para>
1227	Specifies the time offset in milliseconds of the guest VM
1228	relative to the time on the host system. If the offset
1229	value is positive, the guest VM time runs ahead of the
1230	time on the host system.
1231	</para></listitem>
1232	</varlistentry>
1233	<varlistentry>
1234	<term><option>--bios-pxe-debug=on \| off</option></term>
1235	<listitem><para>
1236	Enables or disables additional debugging output when using
1237	the Intel PXE boot ROM. The debug output is written to the
1238	release log file. See
1239	<xref linkend="collect-debug-info" />.
1240	</para></listitem>
1241	</varlistentry>
1242	<varlistentry>
1243	<term><option>--system-uuid-le=on \| off</option></term>
1244	<listitem><para>
1245	Enables or disables representing the system UUID in little
1246	endian form. The default value is <literal>on</literal> for
1247	new VMs. For old VMs the setting is <literal>off</literal> to
1248	keep the content of the DMI/SMBIOS table unchanged, which can
1249	be important for Windows license activation.
1250	</para></listitem>
1251	</varlistentry>
1252	<varlistentry>
1253	<term><option>--boot<replaceable>N</replaceable>=none \| floppy \| dvd \| disk \| net</option></term>
1254	<listitem><para>
1255	Enables you to specify the boot device order for the VM by
1256	assigning one of the device types to each of the four boot
1257	device slots that are represented by
1258	<replaceable>N</replaceable> in the option name.
1259	</para><para>
1260	A value of 1 for <replaceable>N</replaceable> represents
1261	the first boot device slot, and so on.
1262	</para><para>
1263	The device types are <literal>floppy</literal> for floppy
1264	disks, <literal>dvd</literal> for DVDs or CDs,
1265	<literal>disk</literal> for hard disks, and
1266	<literal>net</literal> for a network device. A value of
1267	<literal>none</literal> indicates that no boot device is
1268	associated with the specified slot.
1269	</para></listitem>
1270	</varlistentry>
1271	<varlistentry>
1272	<term><option>--rtc-use-utc=on \| off</option></term>
1273	<listitem><para>
1274	Specifies whether the real-time clock (RTC) uses
1275	coordinated universal time (UTC). See
1276	<xref linkend="settings-motherboard" />.
1277	</para></listitem>
1278	</varlistentry>
1279	<varlistentry>
1280	<term><option>--graphicscontroller=none \| vboxvga \| vmsvga \| vboxsvga</option></term>
1281	<listitem><para>
1282	Specifies the graphics controller type to use. See
1283	<xref linkend="settings-screen" />.
1284	</para></listitem>
1285	</varlistentry>
1286	<varlistentry>
1287	<term><option>--snapshot-folder=default \| <replaceable>pathname</replaceable></option></term>
1288	<listitem><para>
1289	Specifies the name of the VM's snapshot storage folder. If
1290	you specify <literal>default</literal>, the folder name is
1291	<filename>Snapshots/</filename> in the machine folder.
1292	</para></listitem>
1293	</varlistentry>
1294	<varlistentry>
1295	<term><option>--firmware=bios \| efi \| efi32 \| efi64</option></term>
1296	<listitem><para>
1297	Specifies the firmware used to boot the VM. Valid values
1298	are: <literal>bios</literal>, <literal>efi</literal>,
1299	<literal>efi32</literal>, or <literal>efi64</literal>. Use
1300	EFI values with care.
1301	</para><para>
1302	By default, BIOS firmware is used.
1303	</para></listitem>
1304	</varlistentry>
1305	<varlistentry>
1306	<term><option>--guest-memory-balloon=<replaceable>size</replaceable></option></term>
1307	<listitem><para>
1308	Specifies the size of the guest memory balloon. The guest
1309	memory balloon is the memory allocated by the Guest
1310	Additions from the guest OS and returned to the hypervisor
1311	for use by other VMs. Specify
1312	<replaceable>size</replaceable> in megabytes. The default
1313	value is <literal>0</literal> megabytes. See
1314	<xref linkend="guestadd-balloon" />.
1315	</para></listitem>
1316	</varlistentry>
1317	<varlistentry>
1318	<term><option>--default-frontend=default \| <replaceable>name</replaceable></option></term>
1319	<listitem><para>
1320	Specifies the default frontend to use when starting the
1321	specified VM. If you specify <literal>default</literal>,
1322	the VM is shown in a window on the user's desktop. See
1323	<xref linkend="vboxmanage-startvm" />.
1324	</para></listitem>
1325	</varlistentry>
1326	<varlistentry>
1327	<term><option>--vm-process-priority=default \| flat \| low \| normal \| high</option></term>
1328	<listitem><para>
1329	Specifies the priority scheme of the VM process to use
1330	when starting the specified VM and while the VM runs.
1331	</para><para>
1332	The following valid values are:
1333	</para><itemizedlist>
1334	<listitem><para>
1335	<literal>default</literal> – Default process
1336	priority determined by the OS.
1337	</para></listitem>
1338	<listitem><para>
1339	<literal>flat</literal> – Assumes a scheduling
1340	policy which puts the process at the default priority
1341	and with all threads at the same priority.
1342	</para></listitem>
1343	<listitem><para>
1344	<literal>low</literal> – Assumes a scheduling
1345	policy which puts the process mostly below the default
1346	priority of the host OS.
1347	</para></listitem>
1348	<listitem><para>
1349	<literal>normal</literal> – Assume a scheduling
1350	policy which shares the CPU resources fairly with
1351	other processes running with the default priority of
1352	the host OS.
1353	</para></listitem>
1354	<listitem><para>
1355	<literal>high</literal> – Assumes a scheduling
1356	policy which puts the task above the default priority of
1357	the host OS. This policy might easily cause other tasks
1358	in the system to starve.
1359	</para></listitem>
1360	</itemizedlist></listitem>
1361	</varlistentry>
1362	</variablelist>
1363	</refsect2>
1364	<refsect2 id="vboxmanage-modifyvm-networking">
1365	<title>Networking Settings</title>
1366	<remark role="help-copy-synopsis"/>
1367	<para>
1368	The following options enable you to modify networking on your
1369	VM. With all these options, <replaceable>N</replaceable> is an
1370	integer greater than zero that represents the particular virtual
1371	network adapter to configure.
1372	</para>
1373	<variablelist>
1374	<varlistentry>
1375	<term><option>--nic<replaceable>N</replaceable>=none \| null \| nat \| natnetwork \| bridged \| intnet \| hostonly \| generic</option></term>
1376	<listitem><para>
1377	Configures the network type used by each virtual network
1378	card in the VM.
1379	</para><para>
1380	The following valid values correspond to the modes
1381	described in <xref linkend="networkingmodes" />:
1382	</para><itemizedlist>
1383	<listitem><para>
1384	<literal>none</literal> – No networking present
1385	</para></listitem>
1386	<listitem><para>
1387	<literal>null</literal> – Not connected to the
1388	host system
1389	</para></listitem>
1390	<listitem><para>
1391	<literal>nat</literal> – Use network address
1392	translation (NAT)
1393	</para></listitem>
1394	<listitem><para>
1395	<literal>natnetwork</literal> – Use a NAT
1396	network
1397	</para></listitem>
1398	<listitem><para>
1399	<literal>bridged</literal> – Use bridged
1400	networking
1401	</para></listitem>
1402	<listitem><para>
1403	<literal>intnet</literal> – Use internal
1404	networking
1405	</para></listitem>
1406	<listitem><para>
1407	<literal>hostonly</literal> – Use host-only
1408	networking
1409	</para></listitem>
1410	<listitem><para>
1411	<literal>generic</literal> – Access rarely used
1412	sub-modes
1413	</para></listitem>
1414	</itemizedlist></listitem>
1415	</varlistentry>
1416	<varlistentry>
1417	<term><option>--nic-type<replaceable>N</replaceable>=Am79C970A \| Am79C973 \| 82540EM \| 82543GC \| 82545EM \| virtio</option></term>
1418	<listitem><para>
1419	Identifies the type of networking hardware that
1420	&product-name; presents to the guest VM for the specified
1421	virtual network card. See <xref linkend="nichardware" />.
1422	</para><para>
1423	Valid values are as follows:
1424	</para><itemizedlist>
1425	<listitem><para>
1426	<literal>Am79C970A</literal> represents the AMD PCNet
1427	PCI II.
1428	</para></listitem>
1429	<listitem><para>
1430	<literal>Am79C973</literal> represents the AMD PCNet
1431	FAST III, which is the default value.
1432	</para></listitem>
1433	<listitem><para>
1434	<literal>82540EM</literal> represents the Intel
1435	PRO/1000 MT Desktop.
1436	</para></listitem>
1437	<listitem><para>
1438	<literal>82543GC</literal> represents the Intel
1439	PRO/1000 T Server.
1440	</para></listitem>
1441	<listitem><para>
1442	<literal>82545EM</literal> represents the Intel
1443	PRO/1000 MT Server.
1444	</para></listitem>
1445	<listitem><para>
1446	<literal>virtio</literal> represents a paravirtualized
1447	network adapter.
1448	</para></listitem>
1449	</itemizedlist></listitem>
1450	</varlistentry>
1451	<varlistentry>
1452	<term><option>--cable-connected<replaceable>N</replaceable>=on \| off</option></term>
1453	<listitem><para>
1454	Temporarily disconnects a virtual network interface, as if
1455	you pull a network cable from a physical network card. You
1456	might use this option to reset certain software components
1457	in the VM.
1458	</para></listitem>
1459	</varlistentry>
1460	<varlistentry>
1461	<term><option>--nic-trace<replaceable>N</replaceable>=on \| off</option></term>
1462	<listitem><para>
1463	Enables or disables network tracing for the specified
1464	virtual network card.
1465	</para></listitem>
1466	</varlistentry>
1467	<varlistentry>
1468	<term><option>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></option></term>
1469	<listitem><para>
1470	Specifies the absolute path of the file in which to write
1471	trace log information. Use this option if network tracing
1472	is enabled.
1473	</para></listitem>
1474	</varlistentry>
1475	<varlistentry>
1476	<term><option>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
1477	<listitem><para>
1478	Enables you to set property values and pass them to rarely
1479	used network backends. To use this option, you must also
1480	use the <option>--nic-generic-drv</option> option.
1481	</para><para>
1482	These properties are specific to the backend engine and
1483	differ between the UDP Tunnel and the VDE backend drivers.
1484	For property examples, see
1485	<xref linkend="network_udp_tunnel" />.
1486	</para></listitem>
1487	</varlistentry>
1488	<varlistentry>
1489	<term><option>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></option></term>
1490	<listitem><para>
1491	Specifies the throughput rate in kilobits per second for
1492	rarely used networking sub-modes such as VDE network and
1493	UDP Tunnel. Use this option only if you used the
1494	<option>--nic</option> option to enable generic networking
1495	for the specified virtual network card.
1496	</para></listitem>
1497	</varlistentry>
1498	<varlistentry>
1499	<term><option>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></option></term>
1500	<listitem><para>
1501	Assigns a priority to each NIC that determines the order
1502	in which that NIC is used to perform a PXE network boot.
1503	The priority value is an integer in the range from
1504	<literal>0</literal> to <literal>4</literal>. Priority
1505	<literal>0</literal>, which is the default value, is the
1506	lowest priority. Priority <literal>1</literal> is the
1507	highest priority, and priorities <literal>3</literal> and
1508	<literal>4</literal> are lower.
1509	</para><para>
1510	This option has an effect only when using the Intel PXE
1511	boot ROM.
1512	</para></listitem>
1513	</varlistentry>
1514	<varlistentry>
1515	<term><option>--nic-promisc<replaceable>N</replaceable>=deny \| allow-vms \| allow-all</option></term>
1516	<listitem><para>
1517	Enables you to specify whether to deny or allow
1518	promiscuous mode for the specified VM virtual network
1519	card. This option is relevant only for bridged networking.
1520	Valid values are as follows:
1521	</para><itemizedlist>
1522	<listitem><para>
1523	<literal>deny</literal> hides any traffic that is not
1524	intended for the VM. This is the default value.
1525	</para></listitem>
1526	<listitem><para>
1527	<literal>allow-vms</literal> hides all host traffic
1528	from the VM, but allows the VM to see traffic to and
1529	from other VMs.
1530	</para></listitem>
1531	<listitem><para>
1532	<literal>allow-all</literal> allows the VM to see all
1533	traffic.
1534	</para></listitem>
1535	</itemizedlist></listitem>
1536	</varlistentry>
1537	<varlistentry>
1538	<term><option>--nic-bandwidth-group<replaceable>N</replaceable>=none \| <replaceable>name</replaceable></option></term>
1539	<listitem><para>
1540	Adds or removes a bandwidth group assignment to the
1541	specified virtual network interface. Valid values are as
1542	follows:
1543	</para><itemizedlist>
1544	<listitem><para>
1545	<literal>none</literal> removes any current bandwidth
1546	group assignment from the specified virtual network
1547	interface.
1548	</para></listitem>
1549	<listitem><para>
1550	<replaceable>name</replaceable> adds a bandwidth group
1551	assignment to the specified virtual network interface.
1552	</para></listitem>
1553	</itemizedlist><para>
1554	See <xref linkend="network_bandwidth_limit" />.
1555	</para></listitem>
1556	</varlistentry>
1557	<varlistentry>
1558	<term><option>--bridge-adapter<replaceable>N</replaceable>=none \| <replaceable>device-name</replaceable></option></term>
1559	<listitem><para>
1560	Specifies the host interface to use for the specified
1561	virtual network interface. See
1562	<xref linkend="network_bridged" />. Use this option only
1563	if you used the <option>--nic</option> option to enable
1564	bridged networking for the specified virtual network card.
1565	</para></listitem>
1566	</varlistentry>
1567	<varlistentry>
1568	<term><option>--host-only-adapter<replaceable>N</replaceable>=none \| <replaceable>device-name</replaceable></option></term>
1569	<listitem><para>
1570	Specifies which host-only networking interface to use for
1571	the specified virtual network interface. See
1572	<xref linkend="network_hostonly" />. Use this option only
1573	if you used the <option>--nic</option> option to enable
1574	host-only networking for the specified virtual network
1575	card.
1576	</para></listitem>
1577	</varlistentry>
1578	<varlistentry>
1579	<term><option>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term>
1580	<listitem><para>
1581	Specifies the name of the internal network. See
1582	<xref linkend="network_internal" />. Use this option only
1583	if you used the <option>--nic</option> option to enable
1584	internal networking for the specified virtual network
1585	card.
1586	</para></listitem>
1587	</varlistentry>
1588	<varlistentry>
1589	<term><option>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term>
1590	<listitem><para>
1591	Specifies the name of the NAT network to which this
1592	adapter is connected. Use this option only if the
1593	networking type is <literal>natnetwork</literal>, not
1594	<literal>nat</literal>.
1595	</para></listitem>
1596	</varlistentry>
1597	<varlistentry>
1598	<term><option>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>backend-driver</replaceable></option></term>
1599	<listitem><para>
1600	Enables you to access rarely used networking sub-modes,
1601	such as VDE networks and UDP Tunnel. Use this option only
1602	if you used the <option>--nic</option> option to enable
1603	generic networking for a virtual network card.
1604	</para></listitem>
1605	</varlistentry>
1606	<varlistentry>
1607	<term><option>--mac-address<replaceable>N</replaceable>=auto \| <replaceable>MAC-address</replaceable></option></term>
1608	<listitem><para>
1609	Specifies the MAC address of the specified network adapter
1610	on the VM. By default, &product-name; assigns a random MAC
1611	address to each network adapter at VM creation.
1612	</para></listitem>
1613	</varlistentry>
1614	</variablelist>
1615	</refsect2>
1616	<refsect2 id="vboxmanage-modifyvm-networking-nat">
1617	<title>NAT Networking Settings</title>
1618	<remark role="help-copy-synopsis"/>
1619	<para>
1620	The following options use <replaceable>N</replaceable> to
1621	specify the particular virtual network adapter to modify.
1622	</para>
1623	<variablelist>
1624	<varlistentry>
1625	<term><option>--nat-net<replaceable>N</replaceable>=default \| <replaceable>network</replaceable></option></term>
1626	<listitem><para>
1627	Specifies the IP address range to use for this network.
1628	See <xref linkend="changenat" />. Use this option only if
1629	the networking type is <literal>nat</literal>, not
1630	<literal>natnetwork</literal>.
1631	</para></listitem>
1632	</varlistentry>
1633	<varlistentry>
1634	<term><option>--nat-pf<replaceable>N</replaceable>=[<replaceable>name</replaceable>],tcp \| udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></option></term>
1635	<listitem><para>
1636	Specifies the NAT port-forwarding rule to use. See
1637	<xref linkend="natforward" />.
1638	</para></listitem>
1639	</varlistentry>
1640	<varlistentry>
1641	<term><option>--nat-pf<replaceable>N</replaceable>=delete <replaceable>name</replaceable></option></term>
1642	<listitem><para>
1643	Specifies the NAT port-forwarding rule to delete. See
1644	<xref linkend="natforward" />.
1645	</para></listitem>
1646	</varlistentry>
1647	<varlistentry>
1648	<term><option>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></option></term>
1649	<listitem><para>
1650	Specifies a prefix to use for the built-in TFTP server.
1651	For example, you might use a prefix to indicate where the
1652	boot file is located. See <xref linkend="nat-tftp" /> and
1653	<xref linkend="nat-adv-tftp" />.
1654	</para></listitem>
1655	</varlistentry>
1656	<varlistentry>
1657	<term><option>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>boot-file</replaceable></option></term>
1658	<listitem><para>
1659	Specifies the name of the TFT boot file. See
1660	<xref linkend="nat-adv-tftp" />.
1661	</para></listitem>
1662	</varlistentry>
1663	<varlistentry>
1664	<term><option>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>tftp-server</replaceable></option></term>
1665	<listitem><para>
1666	Specifies the address of the TFTP server from which to
1667	boot. See <xref linkend="nat-adv-tftp" />.
1668	</para></listitem>
1669	</varlistentry>
1670	<varlistentry>
1671	<term><option>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></option></term>
1672	<listitem><para>
1673	Specifies an alternate IP address to which the NAT engine
1674	binds. See <xref linkend="nat-adv-settings" />. By
1675	default, &product-name;'s NAT engine routes TCP/IP packets
1676	through the default interface assigned by the host's
1677	TCP/IP stack.
1678	</para></listitem>
1679	</varlistentry>
1680	<varlistentry>
1681	<term><option>--nat-dns-pass-domain<replaceable>N</replaceable>=on \| off</option></term>
1682	<listitem><para>
1683	Specifies whether the built-in DHCP server passes the
1684	domain name for network name resolution.
1685	</para></listitem>
1686	</varlistentry>
1687	<varlistentry>
1688	<term><option>--nat-dns-proxy<replaceable>N</replaceable>=on \| off</option></term>
1689	<listitem><para>
1690	Specifies whether the NAT engine is the proxy for all
1691	guest DNS requests to the host system's DNS servers. See
1692	<xref linkend="nat-adv-dns" />.
1693	</para></listitem>
1694	</varlistentry>
1695	<varlistentry>
1696	<term><option>--nat-dns-host-resolver<replaceable>N</replaceable>=on \| off</option></term>
1697	<listitem><para>
1698	Specifies whether the NAT engine uses the host system's
1699	resolver mechanisms to handle DNS requests. See
1700	<xref linkend="nat-adv-dns" />.
1701	</para></listitem>
1702	</varlistentry>
1703	<varlistentry>
1704	<term><option>--nat-localhostreachable<replaceable>N</replaceable>=on \| off</option></term>
1705	<listitem><para>
1706	Specifies whether the NAT engine allows traffic from the guest directed to
1707	10.0.2.2 to pass to the host's loopback interface, i.e. localhost or 127.0.0.1.
1708	</para></listitem>
1709	</varlistentry>
1710	<varlistentry>
1711	<term><option>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</option></term>
1712	<listitem><para>
1713	Specifies values for tuning NAT performance. See
1714	<xref linkend="nat-adv-settings" />.
1715	</para></listitem>
1716	</varlistentry>
1717	<varlistentry>
1718	<term><option>--nat-alias-mode<replaceable>N</replaceable>=default \| [log],[proxyonly],[sameports]</option></term>
1719	<listitem><para>
1720	Specifies the behavior of the NAT engine core as follows:
1721	</para><itemizedlist>
1722	<listitem><para>
1723	<literal>log</literal> enables logging
1724	</para></listitem>
1725	<listitem><para>
1726	<literal>proxyonly</literal> switches off aliasing
1727	mode and makes NAT transparent
1728	</para></listitem>
1729	<listitem><para>
1730	<literal>sameports</literal> enforces that the NAT
1731	engine sends packets through the same port on which
1732	they originated
1733	</para></listitem>
1734	<listitem><para>
1735	<literal>default</literal> disables all aliasing modes
1736	</para></listitem>
1737	</itemizedlist><para>
1738	For more information, see
1739	<xref linkend="nat-adv-alias" />.
1740	</para></listitem>
1741	</varlistentry>
1742	</variablelist>
1743	</refsect2>
1744	<refsect2 id="vboxmanage-modifyvm-other-hardware">
1745	<title>Other Hardware Settings</title>
1746	<remark role="help-copy-synopsis"/>
1747	<para>
1748	The following options enable you to configure other hardware,
1749	such as the serial port, monitor, audio device, USB ports, and
1750	the clipboard, and drag-and-drop features.
1751	</para>
1752	<variablelist>
1753	<varlistentry>
1754	<term><option>--mouse=ps2 \| usb \| usbtablet \| usbmultitouch</option></term>
1755	<listitem><para>
1756	Specifies the mode of the mouse to use in the VM. Valid
1757	values are: <literal>ps2</literal>,
1758	<literal>usb</literal>, <literal>usbtablet</literal>, and
1759	<literal>usbmultitouch</literal>.
1760	</para></listitem>
1761	</varlistentry>
1762	<varlistentry>
1763	<term><option>--keyboard=ps2 \| usb</option></term>
1764	<listitem><para>
1765	Specifies the mode of the keyboard to use in the VM. Valid
1766	values are: <literal>ps2</literal> and
1767	<literal>usb</literal>.
1768	</para></listitem>
1769	</varlistentry>
1770	<varlistentry>
1771	<term><option>--uart<replaceable>N</replaceable>=off \| <replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term>
1772	<listitem><para>
1773	Configures virtual serial ports for the VM.
1774	<replaceable>N</replaceable> represents the serial port to
1775	modify. Valid values are <literal>off</literal> to disable
1776	the port or an I/O base address and IRQ. For information
1777	about the traditional COM port I/O base address and IRQ
1778	values, see <xref linkend="serialports" />.
1779	</para></listitem>
1780	</varlistentry>
1781	<varlistentry>
1782	<term><option>--uart-mode<replaceable>N</replaceable>=<replaceable>mode</replaceable></option></term>
1783	<listitem><para>
1784	Specifies how &product-name; connects the specified
1785	virtual serial port to the host system that runs the VM.
1786	See <xref linkend="serialports" />.
1787	</para><para>
1788	Ensure that you first configure the virtual serial port by
1789	using the
1790	<option>--uart<replaceable>N</replaceable></option>
1791	option.
1792	</para><para>
1793	Specify one of the following connection modes for each
1794	port:
1795	</para><itemizedlist>
1796	<listitem><para>
1797	<literal>disconnected</literal> indicates that even
1798	though the serial port is shown to the guest VM, it is
1799	not connected. This state is like a physical COM port
1800	without a cable attached.
1801	</para></listitem>
1802	<listitem><para>
1803	<literal>server</literal>
1804	<replaceable>pipe-name</replaceable> creates the
1805	specified named pipe or local domain socket on the
1806	host system and connects the virtual serial device to
1807	it.
1808	</para><para>
1809	On a Windows host system,
1810	<replaceable>pipe-name</replaceable> is a named pipe
1811	that has a name that uses the following form:
1812	<literal>\\.\pipe\<replaceable>pipe-name</replaceable></literal>.
1813	</para><para>
1814	On a Linux host system,
1815	<replaceable>pipe-name</replaceable> is a local domain
1816	socket.
1817	</para></listitem>
1818	<listitem><para>
1819	<literal>client</literal>
1820	<replaceable>pipe-name</replaceable> connects the
1821	virtual serial device to the specified named pipe or
1822	local domain socket.
1823	</para><para>
1824	Note that the named pipe or local domain socket must
1825	already exist.
1826	</para></listitem>
1827	<listitem><para>
1828	<literal>tcpserver</literal>
1829	<replaceable>port</replaceable> creates a TCP socket
1830	with the specified TCP port on the host system and
1831	connects the virtual serial device to it.
1832	</para><para>
1833	For UNIX-like systems, use ports over 1024 for
1834	non-root users.
1835	</para></listitem>
1836	<listitem><para>
1837	<literal>tcpclient</literal>
1838	<replaceable>hostname</replaceable>:<replaceable>port</replaceable>
1839	connects the virtual serial device to the TCP socket.
1840	</para><para>
1841	Note that the TCP socket must already exist.
1842	</para></listitem>
1843	<listitem><para>
1844	<literal>file</literal>
1845	<replaceable>filename</replaceable> redirects the
1846	serial port output to the specified raw file. Ensure
1847	that <replaceable>filename</replaceable> is the
1848	absolute path of the file on the host system.
1849	</para></listitem>
1850	<listitem><para>
1851	<replaceable>device-name</replaceable>: specifies the
1852	device name of a physical hardware serial port on the
1853	specified host system to which the virtual serial port
1854	connects.
1855	</para><para>
1856	Use this mode to connect a physical serial port to a
1857	VM.
1858	</para><para>
1859	On a Windows host system, the device name is a COM
1860	port such as <literal>COM1</literal>. On a Linux host
1861	system, the device name is similar to
1862	<filename>/dev/ttyS0</filename>.
1863	</para></listitem>
1864	</itemizedlist></listitem>
1865	</varlistentry>
1866	<varlistentry>
1867	<term><option>--uart-type<replaceable>N</replaceable>=<replaceable>UART-type</replaceable></option></term>
1868	<listitem><para>
1869	Configures the UART type for the specified virtual serial
1870	port (<replaceable>N</replaceable>). Valid values are
1871	<literal>16450</literal>, <literal>16550A</literal>, and
1872	<literal>16750</literal>. The default value is
1873	<literal>16550A</literal>.
1874	</para></listitem>
1875	</varlistentry>
1876	<varlistentry>
1877	<term><option>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></option></term>
1878	<listitem><para>
1879	Specifies the device name of the parallel port to use.
1880	</para><para>
1881	For a Windows host system, use a device name such as
1882	<command>lpt1</command>. For a Linux host system, use a
1883	device name such as <filename>/dev/lp0</filename>.
1884	</para></listitem>
1885	</varlistentry>
1886	<varlistentry>
1887	<term><option>--lpt<replaceable>N</replaceable>=<replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term>
1888	<listitem><para>
1889	Specifies the I/O base address and IRQ of the parallel
1890	port.
1891	</para><para>
1892	You can view the I/O base address and IRQ that the VM uses
1893	for the parallel port in the Device Manager.
1894	</para></listitem>
1895	</varlistentry>
1896	<varlistentry>
1897	<term><option>--audio=<replaceable>type</replaceable></option></term>
1898	<listitem><para>
1899	Specifies whether the VM has audio support, and if so,
1900	which type. Valid audio type values are:
1901	<literal>none</literal>, <literal>null</literal>,
1902	<literal>dsound</literal>, <literal>oss</literal>,
1903	<literal>alsa</literal>, <literal>pulse</literal>, and
1904	<literal>coreaudio</literal>.
1905	</para><para>
1906	Note that the audio types are dependent on the host
1907	operating system. Use the <command>VBoxManage
1908	modifyvm</command> command usage output to determine the
1909	supported audio types for your host system.
1910	</para></listitem>
1911	</varlistentry>
1912	<varlistentry>
1913	<term><option>--audio-controller=<replaceable>controller-type</replaceable></option></term>
1914	<listitem><para>
1915	Specifies the audio controller to be used with the VM.
1916	Valid audio controller type values are:
1917	<literal>ac97</literal>, <literal>hda</literal>, and
1918	<literal>sb16</literal>.
1919	</para></listitem>
1920	</varlistentry>
1921	<varlistentry>
1922	<term><option>--audio-codec=<replaceable>codec-type</replaceable></option></term>
1923	<listitem><para>
1924	Specifies the audio codec to be used with the VM. Valid
1925	audio codec type values are: <literal>stac9700</literal>,
1926	<literal>ad1980</literal>, <literal>stac9221</literal>,
1927	and <literal>sb16</literal>.
1928	</para></listitem>
1929	</varlistentry>
1930	<varlistentry>
1931	<term><option>--audio-in=on\|off</option></term>
1932	<listitem><para>
1933	Specifies whether to enable or disable audio capture from
1934	the host system.
1935	</para></listitem>
1936	</varlistentry>
1937	<varlistentry>
1938	<term><option>--audio-out=on\|off</option></term>
1939	<listitem><para>
1940	Specifies whether to enable or disable audio playback from
1941	the guest VM.
1942	</para></listitem>
1943	</varlistentry>
1944	<varlistentry>
1945	<term><option>--clipboard-mode=<replaceable>value</replaceable></option></term>
1946	<listitem><para>
1947	Specifies how to share the guest VM or host system OS's
1948	clipboard with the host system or guest VM, respectively.
1949	Valid values are: <literal>disabled</literal>,
1950	<literal>hosttoguest</literal>,
1951	<literal>guesttohost</literal>, and
1952	<literal>bidirectional</literal>. See
1953	<xref linkend="generalsettings" />.
1954	</para><para>
1955	The clipboard feature is available only if you have the
1956	Guest Additions be installed in the VM.
1957	</para></listitem>
1958	</varlistentry>
1959	<varlistentry>
1960	<term><option>--drag-and-drop=<replaceable>value</replaceable></option></term>
1961	<listitem><para>
1962	Specifies how to use the drag and drop feature between the
1963	host system and the VM. Valid values are:
1964	<literal>disabled</literal>,
1965	<literal>hosttoguest</literal>,
1966	<literal>guesttohost</literal>, and
1967	<literal>bidirectional</literal>. See
1968	<xref linkend="guestadd-dnd" />.
1969	</para><para>
1970	The drag and drop feature is available only if you have
1971	the Guest Additions be installed in the VM.
1972	</para></listitem>
1973	</varlistentry>
1974	<varlistentry>
1975	<term><option>--monitor-count=<replaceable>count</replaceable></option></term>
1976	<listitem><para>
1977	Enables you to configure multiple monitors. See
1978	<xref linkend="settings-display" />.
1979	</para></listitem>
1980	</varlistentry>
1981	<varlistentry>
1982	<term><option>--usb-ohci=on \| off</option></term>
1983	<listitem><para>
1984	Enables or disables the VM's virtual USB 1.1 controller.
1985	See <xref linkend="settings-usb" />.
1986	</para></listitem>
1987	</varlistentry>
1988	<varlistentry>
1989	<term><option>--usb-ehci=on \| off</option></term>
1990	<listitem><para>
1991	Enables or disables the VM's virtual USB 2.0 controller.
1992	See <xref linkend="settings-usb" />.
1993	</para></listitem>
1994	</varlistentry>
1995	<varlistentry>
1996	<term><option>--usb-xhci=on \| off</option></term>
1997	<listitem><para>
1998	Enables or disables the VM's virtual USB 3.0 controller.
1999	This is the most efficient option if the VM supports it.
2000	See <xref linkend="settings-usb" />.
2001	</para></listitem>
2002	</varlistentry>
2003	<varlistentry>
2004	<term><option>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></option></term>
2005	<listitem><para>
2006	Rename's the VM's virtual USB controller from
2007	<replaceable>old-name</replaceable> to
2008	<replaceable>new-name</replaceable>.
2009	</para></listitem>
2010	</varlistentry>
2011	</variablelist>
2012	</refsect2>
2013	<refsect2 id="vboxmanage-modifyvm-recording">
2014	<title>Recording Settings</title>
2015	<remark role="help-copy-synopsis"/>
2016	<para>
2017	The following options enable you to modify settings for video
2018	recording, audio recording, or both.
2019	</para>
2020	<variablelist>
2021	<varlistentry>
2022	<term><option>--recording=on \| off</option></term>
2023	<listitem><para>
2024	Enables or disables the recording of a VM session into a
2025	WebM or VP8 file. When set to <literal>on</literal>,
2026	recording begins when the VM session starts.
2027	</para></listitem>
2028	</varlistentry>
2029	<varlistentry>
2030	<term><option>--recording-screens=all \| none \| <replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...</option></term>
2031	<listitem><para>
2032	Enables you to specify the VM screens to record. The
2033	recording for each screen is output to its own file. Valid
2034	values are: <literal>all</literal>, which records all
2035	screens, <literal>none</literal>, which records no
2036	screens, or one or more specified screens.
2037	</para></listitem>
2038	</varlistentry>
2039	<varlistentry>
2040	<term><option>--recording-file=<replaceable>filename</replaceable></option></term>
2041	<listitem><para>
2042	Specifies the name of the file in which to save the
2043	recording.
2044	</para></listitem>
2045	</varlistentry>
2046	<varlistentry>
2047	<term><option>--recording-max-size=<replaceable>MB</replaceable></option></term>
2048	<listitem><para>
2049	Specifies the maximum size of the recorded video file in
2050	megabytes. When the file reaches the specified size,
2051	recording stops. If the value is <literal>0</literal>,
2052	recording continues until you manually stop recording.
2053	</para></listitem>
2054	</varlistentry>
2055	<varlistentry>
2056	<term><option>--recording-max-time=<replaceable>seconds</replaceable></option></term>
2057	<listitem><para>
2058	Specifies the maximum amount of time to record in seconds.
2059	When the specified time elapses, recording stops. If the
2060	value is <literal>0</literal>, recording continues until
2061	you manually stop recording.
2062	</para></listitem>
2063	</varlistentry>
2064	<varlistentry>
2065	<term><option>--recording-opts=<replaceable>keyword</replaceable>=<replaceable>value</replaceable></option></term>
2066	<listitem><para>
2067	Specifies additional video-recording properties as a
2068	comma-separated property keyword-value list. For example,
2069	<literal>foo=bar,a=b</literal>.
2070	</para><para>
2071	Only use this option if you are an advanced user. For
2072	information about keywords, see the <citetitle>Oracle VM
2073	VirtualBox Programming Guide and Reference</citetitle>.
2074	</para></listitem>
2075	</varlistentry>
2076	<varlistentry>
2077	<term><option>--recording-video-fps=<replaceable>fps</replaceable></option></term>
2078	<listitem><para>
2079	Specifies the maximum number of video frames per second
2080	(FPS) to record. The recording ignores any frames that
2081	have a higher frequency. When you increase the FPS, fewer
2082	frames are ignored but the recording and the size of the
2083	recording file increases.
2084	</para></listitem>
2085	</varlistentry>
2086	<varlistentry>
2087	<term><option>--recording-video-rate=<replaceable>bit-rate</replaceable></option></term>
2088	<listitem><para>
2089	Specifies the bit rate of the video in kilobits per
2090	second. When you increase the bit rate, the recording
2091	appearance improves and the size of the recording file
2092	increases.
2093	</para></listitem>
2094	</varlistentry>
2095	<varlistentry>
2096	<term><option>--recording-video-res=<replaceable>width</replaceable>x<replaceable>height</replaceable></option></term>
2097	<listitem><para>
2098	Specifies the video resolution (width and height) of the
2099	recorded video in pixels.
2100	</para></listitem>
2101	</varlistentry>
2102	</variablelist>
2103	</refsect2>
2104	<refsect2 id="vboxmanage-modifyvm-vrde">
2105	<title>Remote Machine Settings</title>
2106	<remark role="help-copy-synopsis"/>
2107	<para>
2108	The following options enable you to modify the VirtualBox Remote
2109	Desktop Extension (VRDE) behavior.
2110	</para>
2111	<variablelist>
2112	<varlistentry>
2113	<term><option>--vrde=on \| off</option></term>
2114	<listitem><para>
2115	Enables or disables the VRDE server.
2116	</para></listitem>
2117	</varlistentry>
2118	<varlistentry>
2119	<term><option>--vrde-property=TCP/Ports=<replaceable>port</replaceable></option></term>
2120	<listitem><para>
2121	<replaceable>port</replaceable> is the port or port range
2122	to which the VRDE server binds. The
2123	<literal>default</literal> or <literal>0</literal> value
2124	uses port <literal>3389</literal>, which is the standard
2125	RDP port.
2126	</para><para>
2127	Also see the <option>--vrde-port</option> option
2128	description.
2129	</para></listitem>
2130	</varlistentry>
2131	<varlistentry>
2132	<term><option>--vrde-property=TCP/Address=<replaceable>IP-address</replaceable></option></term>
2133	<listitem><para>
2134	<replaceable>IP-address</replaceable> is the IP address of
2135	the host network interface to which the VRDE server binds.
2136	When specified, the server accepts connections only on the
2137	host network interface at that IP address.
2138	</para><para>
2139	Also see the <option>--vrde-address</option> option
2140	description.
2141	</para></listitem>
2142	</varlistentry>
2143	<varlistentry>
2144	<term><option>--vrde-property=VideoChannel/Enabled=<replaceable>value</replaceable></option></term>
2145	<listitem><para>
2146	Specifies whether the VRDP video channel is on or off.
2147	<literal>1</literal> means <literal>on</literal> and
2148	<literal>0</literal> means <literal>off</literal>. See
2149	<xref linkend="vrde-videochannel" />.
2150	</para></listitem>
2151	</varlistentry>
2152	<varlistentry>
2153	<term><option>--vrde-property=Quality=<replaceable>value</replaceable></option></term>
2154	<listitem><para>
2155	Specifies a value between 10% and 100%, inclusive, that
2156	represents the JPEG compression level on the VRDE server
2157	video channel. A lower value produces lower JPEG quality
2158	but higher compression. See
2159	<xref linkend="vrde-videochannel" />.
2160	</para></listitem>
2161	</varlistentry>
2162	<varlistentry>
2163	<term><option>--vrde-property=DownscaleProtection=<replaceable>value</replaceable></option></term>
2164	<listitem><para>
2165	Enables or disables the video downscale protection
2166	feature. Valid values are <literal>1</literal> to enable
2167	the feature and <literal>0</literal> to disable the
2168	feature.
2169	</para><para>
2170	When this feature is enabled, &product-name; determines
2171	whether to display the video:
2172	</para><itemizedlist>
2173	<listitem><para>
2174	When the video size equals the size of the shadow
2175	buffer, the video is considered to be full screen and
2176	is displayed.
2177	</para></listitem>
2178	<listitem><para>
2179	When the video size is between full screen and the
2180	downscale threshold, the video is not displayed. Such
2181	a video might be an application window, which is
2182	unreadable when downscaled.
2183	</para></listitem>
2184	</itemizedlist><para>
2185	When this feature is disabled, an attempt is always made
2186	to display a video.
2187	</para></listitem>
2188	</varlistentry>
2189	<varlistentry>
2190	<term><option>--vrde-property=Client/DisableDisplay=1</option></term>
2191	<listitem><para>
2192	Disables the display VRDE server feature.
2193	</para><para>
2194	To reenable a feature, assign an empty value. For example,
2195	to reenable the display feature, specify the
2196	<command>VBoxManage modifyvm
2197	--vrde-property=Client/DisableDisplay=</command> command.
2198	See <xref linkend="vrde-customization" />.
2199	</para></listitem>
2200	</varlistentry>
2201	<varlistentry>
2202	<term><option>--vrde-property=DisableInput=1</option></term>
2203	<listitem><para>
2204	Disables the input VRDE server feature.
2205	</para></listitem>
2206	</varlistentry>
2207	<varlistentry>
2208	<term><option>--vrde-property=DisableAudio=1</option></term>
2209	<listitem><para>
2210	Disables the audio VRDE server feature.
2211	</para></listitem>
2212	</varlistentry>
2213	<varlistentry>
2214	<term><option>--vrde-property=DisableUSB=1</option></term>
2215	<listitem><para>
2216	Disables the USB VRDE server feature.
2217	</para></listitem>
2218	</varlistentry>
2219	<varlistentry>
2220	<term><option>--vrde-property=Client/DisableClipboard=1</option></term>
2221	<listitem><para>
2222	Disables the clipboard VRDE server feature. To reenable
2223	the feature, assign an empty value. See
2224	<xref linkend="vrde-customization" />.
2225	</para></listitem>
2226	</varlistentry>
2227	<varlistentry>
2228	<term><option>--vrde-property=DisableUpstreamAudio=1</option></term>
2229	<listitem><para>
2230	Disables the upstream audio VRDE server feature. To
2231	reenable the feature, assign an empty value. See
2232	<xref linkend="vrde-customization" />.
2233	</para></listitem>
2234	</varlistentry>
2235	<varlistentry>
2236	<term><option>--vrde-property=Client/DisableRDPDR=1</option></term>
2237	<listitem><para>
2238	Disables the RDP device redirection for smart cards VRDE
2239	server feature. To reenable this feature, assign an empty
2240	value.
2241	</para></listitem>
2242	</varlistentry>
2243	<varlistentry>
2244	<term><option>--vrde-property=H3DRedirect/Enabled=1</option></term>
2245	<listitem><para>
2246	Enables the 3D redirection VRDE server feature. To disable
2247	this feature, assign an empty value.
2248	</para></listitem>
2249	</varlistentry>
2250	<varlistentry>
2251	<term><option>--vrde-property=Security/Method=<replaceable>value</replaceable></option></term>
2252	<listitem><para>
2253	Specifies the following information that is required for a
2254	connection:
2255	</para><itemizedlist>
2256	<listitem><para>
2257	<literal>Negotiate</literal> indicates that both
2258	Enhanced (TLS) and Standard RDP Security connections
2259	are permitted. The security method is negotiated with
2260	the client. This is the default value.
2261	</para></listitem>
2262	<listitem><para>
2263	<literal>RDP</literal> indicates that only Standard
2264	RDP Security is accepted.
2265	</para></listitem>
2266	<listitem><para>
2267	<literal>TLS</literal> indicates that only Enhanced
2268	RDP Security is accepted. The client must support TLS.
2269	</para></listitem>
2270	</itemizedlist><para>
2271	See <xref linkend="vrde-crypt" />.
2272	</para></listitem>
2273	</varlistentry>
2274	<varlistentry>
2275	<term><option>--vrde-property=ServerCertificate=<replaceable>value</replaceable></option></term>
2276	<listitem><para>
2277	Specifies the absolute path to the server certificate. See
2278	<xref linkend="vrde-crypt" />.
2279	</para></listitem>
2280	</varlistentry>
2281	<varlistentry>
2282	<term><option>--vrde-property=ServerPrivateKey=<replaceable>value</replaceable></option></term>
2283	<listitem><para>
2284	Specifies the absolute path to the server private key. See
2285	<xref linkend="vrde-crypt" />.
2286	</para></listitem>
2287	</varlistentry>
2288	<varlistentry>
2289	<term><option>--vrde-property=CACertificate=<replaceable>value</replaceable></option></term>
2290	<listitem><para>
2291	Specifies the absolute path to the CA self-signed
2292	certificate. See <xref linkend="vrde-crypt" />.
2293	</para></listitem>
2294	</varlistentry>
2295	<varlistentry>
2296	<term><option>--vrde-property Audio/RateCorrectionMode=<replaceable>value</replaceable></option></term>
2297	<listitem><para>
2298	Specifies the audio connection mode or the path to the
2299	audio log file. Valid values are as follows:
2300	</para><itemizedlist>
2301	<listitem><para>
2302	<literal>VRDP_AUDIO_MODE_VOID</literal> is no mode.
2303	Use this value to unset any set audio mode.
2304	</para></listitem>
2305	<listitem><para>
2306	<literal>VRDP_AUDIO_MODE_RC</literal> is the rate
2307	correction mode.
2308	</para></listitem>
2309	<listitem><para>
2310	<literal>VRDP_AUDIO_MODE_LPF</literal> is the low pass
2311	filter mode.
2312	</para></listitem>
2313	<listitem><para>
2314	<literal>VRDP_AUDIO_MODE_CS</literal> is the client
2315	sync sync mode to prevent an underflow or overflow of
2316	the client queue.
2317	</para></listitem>
2318	</itemizedlist></listitem>
2319	</varlistentry>
2320	<varlistentry>
2321	<term><option>--vrde-property=LogPath=<replaceable>value</replaceable></option></term>
2322	<listitem><para>
2323	Specifies the absolute path to the audio log file.
2324	</para></listitem>
2325	</varlistentry>
2326	<varlistentry>
2327	<term><option>--vrde-extpack=default \| <replaceable>name</replaceable></option></term>
2328	<listitem><para>
2329	Specifies the library to use to access the VM remotely.
2330	The <literal>default</literal> value uses the RDP code
2331	that is part of the &product-name; Extension Pack.
2332	</para><para>
2333	To use the VRDE module in VNC, specify
2334	<literal>VNC</literal>. See
2335	<xref linkend="otherextpacks"/>.
2336	</para></listitem>
2337	</varlistentry>
2338	<varlistentry>
2339	<term><option>--vrde-port=default \| <replaceable>port</replaceable></option></term>
2340	<listitem><para>
2341	<replaceable>port</replaceable> is the port or port range
2342	to which the VRDE server binds. The
2343	<literal>default</literal> or <literal>0</literal> value
2344	uses port <literal>3389</literal>, which is the standard
2345	RDP port.
2346	</para><para>
2347	You can specify a comma-separated list of ports or port
2348	ranges of ports. Use a dash between two port numbers to
2349	specify a port range. The VRDE server binds to only one of
2350	the available ports from the list. Only one machine can
2351	use a given port at a time. For example, the
2352	<option>--vrde-port=5000,5010-5012</option> option
2353	specifies that server can bind to one of following ports:
2354	<literal>5000</literal>, <literal>5010</literal>,
2355	<literal>5011</literal>, or <literal>5012</literal>.
2356	</para></listitem>
2357	</varlistentry>
2358	<varlistentry>
2359	<term><option>--vrde-address=<replaceable>IP-address</replaceable></option></term>
2360	<listitem><para>
2361	Specifies the IP address of the host network interface to
2362	which the VRDE server binds. If you specify an IP address,
2363	the server accepts connections only on the specified host
2364	network interface.
2365	</para><para>
2366	Use this option to specify whether the VRDP server should
2367	accept IPv4, IPv6, or both type of connections:
2368	</para><itemizedlist>
2369	<listitem><para>
2370	<emphasis role="bold">Only IPv4:</emphasis> Use the
2371	<option>--vrde-address="0.0.0.0"</option> option.
2372	</para></listitem>
2373	<listitem><para>
2374	<emphasis role="bold">Only IPv6:</emphasis> Use the
2375	<option>--vrde-address="::"</option> option.
2376	</para></listitem>
2377	<listitem><para>
2378	<emphasis role="bold">Both IPv6 and IPv4:</emphasis>
2379	Use the <option>--vrde-address=""</option>
2380	option. This is the default value.
2381	</para></listitem>
2382	</itemizedlist></listitem>
2383	</varlistentry>
2384	<varlistentry>
2385	<term><option>--vrde-auth-type=null \| external \| guest</option></term>
2386	<listitem><para>
2387	Specify whether to use authorization and how to perform
2388	authorization. See <xref linkend="vbox-auth" />. Valid
2389	values are as follows:
2390	</para><itemizedlist>
2391	<listitem><para>
2392	<literal>null</literal> provides no authentication.
2393	</para></listitem>
2394	<listitem><para>
2395	<literal>external</literal> provides external
2396	authentication through an authentication library.
2397	</para></listitem>
2398	<listitem><para>
2399	<literal>guest</literal> performs authentication by
2400	using guest user accounts. This unsupported method
2401	requires that you install the Guest Additions on the
2402	VM.
2403	</para></listitem>
2404	</itemizedlist></listitem>
2405	</varlistentry>
2406	<varlistentry>
2407	<term><option>--vrde-auth-library=default \| <replaceable>name</replaceable></option></term>
2408	<listitem><para>
2409	Specifies the library to use for RDP authentication. The
2410	default library for external authentication is
2411	<filename>VBoxAuth</filename>. See
2412	<xref linkend="vbox-auth" />.
2413	</para></listitem>
2414	</varlistentry>
2415	<varlistentry>
2416	<term><option>--vrde-multi-con=on \| off</option></term>
2417	<listitem><para>
2418	Enables or disables the multiple connections VRDE server
2419	feature, if supported. See
2420	<xref linkend="vrde-multiconnection" />.
2421	</para></listitem>
2422	</varlistentry>
2423	<varlistentry>
2424	<term><option>--vrde-reuse-con=on \| off</option></term>
2425	<listitem><para>
2426	Specifies how the VRDE server behaves when multiple
2427	connections are disabled. When the value is
2428	<literal>on</literal>, the server permits a new client to
2429	connect and drops the existing connection. When the value
2430	is <literal>off</literal>, a new connection is not
2431	accepted if a client is already connected to the server.
2432	This is the default value.
2433	</para></listitem>
2434	</varlistentry>
2435	<varlistentry>
2436	<term><option>--vrde-video-channel=on \| off</option></term>
2437	<listitem><para>
2438	Enables video redirection if supported by the VRDE server.
2439	See <xref linkend="vrde-videochannel" />.
2440	</para></listitem>
2441	</varlistentry>
2442	<varlistentry>
2443	<term><option>--vrde-video-channel-quality=<replaceable>percent</replaceable></option></term>
2444	<listitem><para>
2445	Specifies the image quality for video redirection as a
2446	value from 10 to 100 percent. The percentage represents
2447	the JPEG compression level where a lower number diminishes
2448	quality and provides higher compression. See
2449	<xref linkend="vrde-videochannel" />.
2450	</para></listitem>
2451	</varlistentry>
2452	</variablelist>
2453	</refsect2>
2454	<refsect2 id="vboxmanage-modifyvm-teleport">
2455	<title>Teleporting Settings</title>
2456	<remark role="help-copy-synopsis"/>
2457	<para>
2458	The following options enable you to configure a machine as a
2459	teleporting target. See <xref linkend="teleporting" />.
2460	</para>
2461	<variablelist>
2462	<varlistentry>
2463	<term><option>--teleporter=on \| off</option></term>
2464	<listitem><para>
2465	Enables or disables the teleporter. When enabled, a
2466	machine starts up and waits to receive a teleporting
2467	request from the network instead of booting normally.
2468	</para><para>
2469	Teleporting requests are received on the port and address
2470	specified using the following parameters.
2471	</para></listitem>
2472	</varlistentry>
2473	<varlistentry>
2474	<term><option>--teleporter-port=<replaceable>port</replaceable></option></term>
2475	<listitem><para>
2476	Specifies the port on which the VM listens to receive a
2477	teleporting request from another VM.
2478	<replaceable>port</replaceable> is any free TCP/IP port
2479	number, such as <literal>6000</literal>. You must also
2480	specify the <option>--teleporter</option> option.
2481	</para></listitem>
2482	</varlistentry>
2483	<varlistentry>
2484	<term><option>--teleporter-address=<replaceable>IP-address</replaceable></option></term>
2485	<listitem><para>
2486	Specifies the IP address on which the VM listens to
2487	receive a teleporting request from another VM.
2488	<replaceable>IP-address</replaceable> is any IP address or
2489	host name and specifies the TCP/IP socket on which to
2490	bind. The default IP address is
2491	<literal>0.0.0.0</literal>, which represents any IP
2492	address. You must also specify the
2493	<option>--teleporter</option> option.
2494	</para></listitem>
2495	</varlistentry>
2496	<varlistentry>
2497	<term><option>--teleporter-password=<replaceable>password</replaceable></option></term>
2498	<listitem><para>
2499	Specifies the password to use for authentication. When
2500	specified, the teleporting request only succeeds if the
2501	password on the source machine is the same password as the
2502	one you specify.
2503	</para></listitem>
2504	</varlistentry>
2505	<varlistentry>
2506	<term><option>--teleporter-password-file=<replaceable>filename</replaceable></option></term>
2507	<listitem><para>
2508	Specifies a file that contains the password to use for
2509	authentication. When specified, the teleporting request
2510	only succeeds if the password on the source machine is the
2511	same password as the one you specify in the password file.
2512	A value of <literal>stdin</literal> reads the password
2513	from standard input.
2514	</para></listitem>
2515	</varlistentry>
2516	<varlistentry>
2517	<term><option>--cpuid-portability-level=<replaceable>level</replaceable></option></term>
2518	<listitem>
2519	<para>
2520	Restricts the virtual CPU capabilities that &product-name;
2521	presents to the guest OS by using portability rules. Higher
2522	integer values designate more restrictive behavior. The
2523	default level of <literal>0</literal> indicates that all
2524	virtualized features supported by the host are made available
2525	to the guest. The value <literal>3</literal> supresses most
2526	features. Values of <literal>1</literal> and <literal>2</literal>
2527	represent restrictions in between. The behavior may change
2528	depending on the product version.
2529	</para></listitem>
2530	</varlistentry>
2531	<varlistentry>
2532	<term><option>--cpuid-set=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]
2533	<replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term>
2534	<listitem>
2535	<para>
2536	Advanced users can use this setting before a teleporting
2537	operation (in fact before starting the VM) to restrict the
2538	virtual CPU capabilities that &product-name; presents to
2539	the guest operating system. This must be run on both the
2540	source and the target machines involved in teleporting and
2541	will then modify what the guest sees when it executes the
2542	CPUID machine instruction. This might help with misbehaving
2543	applications that wrongly assume that certain CPU
2544	capabilities are present. The meaning of the parameters
2545	is hardware dependent. Refer to the AMD or Intel processor
2546	documentation.
2547	</para><para>
2548	The values of <replaceable>leaf</replaceable>,
2549	<replaceable>subleaf</replaceable> (optional),
2550	<replaceable>eax</replaceable>, <replaceable>ebx</replaceable>,
2551	<replaceable>ecx</replaceable> and <replaceable>edx</replaceable>
2552	are integers given in hexadecimal format, i.e. using a radix
2553	(base) of 16 without requiring any prefix.
2554	</para></listitem>
2555	</varlistentry>
2556	<varlistentry>
2557	<term><option>--cpuid-remove=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]</option></term>
2558	<listitem>
2559	<para>
2560	Removes an adjustment established with <option>--cpuid-set</option>.
2561	</para></listitem>
2562	</varlistentry>
2563	<varlistentry>
2564	<term><option>--cpuid-remove-all</option></term>
2565	<listitem>
2566	<para>
2567	Removes all adjustments established with <option>--cpuid-set</option>.
2568	</para></listitem>
2569	</varlistentry>
2570	</variablelist>
2571	</refsect2>
2572	<refsect2 id="vboxmanage-modifyvm-debugging">
2573	<title>Debugging Settings</title>
2574	<remark role="help-copy-synopsis"/>
2575	<para>
2576	Only use the following options to perform low-level VM
2577	debugging. These options are for advanced users only.
2578	</para>
2579	<variablelist>
2580	<varlistentry>
2581	<term><option>--tracing-enabled=on \| off</option></term>
2582	<listitem><para>
2583	Enables or disables the trace buffer. Note that when
2584	specified, the trace buffer consumes some memory and adds
2585	overhead.
2586	</para></listitem>
2587	</varlistentry>
2588	<varlistentry>
2589	<term><option>--tracing-config=<replaceable>config-string</replaceable></option></term>
2590	<listitem><para>
2591	Enables a tracing configuration that defines which group
2592	of trace points are enabled.
2593	</para></listitem>
2594	</varlistentry>
2595	<varlistentry>
2596	<term><option>--tracing-allow-vm-access=on \| off</option></term>
2597	<listitem><para>
2598	Enables or disables VM access to the trace buffer. The
2599	default value is <literal>off</literal>, which disables
2600	access.
2601	</para></listitem>
2602	</varlistentry>
2603	</variablelist>
2604	</refsect2>
2605	<refsect2 id="vboxmanage-modifyvm-usbcardreader">
2606	<title>USB Card Reader Settings</title>
2607	<remark role="help-copy-synopsis"/>
2608	<para>
2609	The following options specify the access to a USB Card Reader by
2610	the guest environment. A USB card reader can access data on
2611	memory cards, such as CompactFlash (CF), Secure Digital (SD),
2612	and MultiMediaCard (MMC).
2613	</para>
2614	<variablelist>
2615	<varlistentry>
2616	<term><option>--usb-card-reader=on \| off</option></term>
2617	<listitem><para>
2618	Enables or disables the USB card reader interface.
2619	</para></listitem>
2620	</varlistentry>
2621	</variablelist>
2622	</refsect2>
2623	<refsect2 id="vboxmanage-modifyvm-autostart">
2624	<title>Autostarting VMs During Host System Boot</title>
2625	<para>
2626	The following options enable you to configure the VM autostart
2627	feature, which automatically starts the VM at host system
2628	boot-up. You must do some host system configuration before you
2629	can use this feature. See <xref linkend="autostart" />.
2630	</para>
2631	<remark role="help-copy-synopsis"/>
2632	<variablelist>
2633	<varlistentry>
2634	<term><option>--autostart-enabled=on \| off</option></term>
2635	<listitem><para>
2636	Enables or disables VM autostart at host system boot-up
2637	for the specified users.
2638	</para></listitem>
2639	</varlistentry>
2640	<varlistentry>
2641	<term><option>--autostart-delay=<replaceable>seconds</replaceable></option></term>
2642	<listitem><para>
2643	Specifies the number of seconds after host system boot-up
2644	to autostart the VM.
2645	</para></listitem>
2646	</varlistentry>
2647	</variablelist>
2648	</refsect2>
2649	<refsect2 id="vboxmanage-modifyvm-pcipassthrough">
2650	<title>PCI Passthrough Settings</title>
2651	<para>
2652	The following options enable you to configure the PCI passthrough
2653	feature, which currently is not available in &product-name;. It is
2654	planned to bring this functionality back in the future.
2655	</para>
2656	<remark role="help-copy-synopsis"/>
2657	<variablelist>
2658	<varlistentry>
2659	<term><option>--pci-attach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-bus-address</replaceable>]</option></term>
2660	<listitem><para>
2661	Attaches the specified PCI network controller on the host
2662	to the guest VM. You can optionally specify the PCI bus on
2663	the guest VM on which to attach the controller.
2664	<!-- See <xref linkend="pcipassthrough" />. -->
2665	</para></listitem>
2666	</varlistentry>
2667	<varlistentry>
2668	<term><option>--pci-detach=<replaceable>host-PCI-address</replaceable></option></term>
2669	<listitem><para>
2670	Detaches the specified PCI network controller from the
2671	attached PCI bus on the guest VM.
2672	<!-- See <xref linkend="pcipassthrough" />. -->
2673	</para></listitem>
2674	</varlistentry>
2675	</variablelist>
2676	</refsect2>
2677	<refsect2 id="vboxmanage-modifyvm-testing">
2678	<title>Testing (ValidationKit / Bootsector)</title>
2679	<para>
2680	These options are for configuring the testing functionality of the VMM
2681	device and almost exclusively used by the bootsector testcases in the
2682	ValidationKit.
2683	</para>
2684	<remark role="help-copy-synopsis"/>
2685	<variablelist>
2686	<varlistentry>
2687	<term><option>--testing-enabled=on \| off</option></term>
2688	<listitem><para>Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details. </para></listitem>
2689	</varlistentry>
2690	<varlistentry>
2691	<term><option>--testing-mmio=on \| off</option></term>
2692	<listitem><para>Enabled the MMIO region of the VMMDev testing feature.</para></listitem>
2693	</varlistentry>
2694	<varlistentry>
2695	<term><option>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></option></term>
2696	<listitem><para>
2697	This sets one of the 10 dword configuration values. The
2698	<replaceable>idx</replaceable> must be in the range 0 thru 9.
2699	The <replaceable>value</replaceable> is limited to 32 bits (dword).
2700	</para></listitem>
2701	</varlistentry>
2702	</variablelist>
2703	</refsect2>
2704
2705	</refsect1>
2706
2707	<refsect1>
2708	<title>Examples</title>
2709	<remark role="help-scope" condition="GLOBAL" />
2710	<para>
2711	The following command changes the description for the
2712	<filename>ol7</filename> VM.
2713	</para>
2714	<screen>$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"</screen>
2715	<para>
2716	The following command enables VirtualBox Remote Display Protocol
2717	(VRDP) support for the <filename>ol7</filename> VM.
2718	</para>
2719	<screen>$ VBoxManage modifyvm ol7 --vrde on</screen>
2720	</refsect1>
2721
2722	<refsect1>
2723	<title>See Also</title>
2724	<para>
2725	<xref linkend="vboxmanage-showvminfo" />,
2726	<xref linkend="vboxmanage-controlvm" />,
2727	<xref linkend="vboxmanage-createvm" />,
2728	<xref linkend="vboxmanage-startvm" />
2729	<xref linkend="vboxmanage-list" />
2730	</para>
2731	</refsect1>
2732	</refentry>

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-modifyvm.xml@ 94660

Download in other formats: