man_VBoxManage-modifyvm.xml@ 91099

Last change on this file since 91099 was 90279, checked in by vboxsync, 3 years ago
doc/manual: Added documentation for the iommu option under the VBoxManage man page.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 117.1 KB

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

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

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

Download in other formats: