man_VBoxManage-modifyvm.xml@ 99095

Last change on this file since 99095 was 98103, checked in by vboxsync, 2 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 130.6 KB

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

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

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

Download in other formats: