man_VBoxManage-modifyvm.xml@ 96836

Last change on this file since 96836 was 96604, checked in by vboxsync, 2 years ago
doc/manual/man_VBoxManage-modifyvm.xml: Bring audio driver config in sync with reality (new values "default" and "was").
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 127.3 KB

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

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

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

Download in other formats: