man_VBoxManage-modifyvm.xml@ 97706

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

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

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

Download in other formats: