man_VBoxManage-modifyvm.xml@ 96407

最後變更在這個檔案從96407是 96407,由 vboxsync 提交於 3 年前
scm copyright and license note update
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 127.2 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: