man_VBoxManage-modifyvm.xml@ 99216

Last change on this file since 99216 was 99192, checked in by vboxsync, 23 months ago
manual: Corrections. bugref:10302
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 130.6 KB

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

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

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

Download in other formats: