man_VBoxManage-modifyvm.xml@ 95368

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

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

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

Download in other formats: