1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
manpage, user manual, usage: VBoxManage modifymedium
-->
<!--
Copyright (C) 2006-2022 Oracle and/or its affiliates.
This file is part of VirtualBox base platform packages, as
available from https://www.virtualbox.org.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, in version 3 of the
License.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see <https://www.gnu.org/licenses>.
SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<refentry id="vboxmanage-modifymedium" lang="en">
<refentryinfo>
<pubdate>$Date: 2022-08-22 19:43:14 +0200 (Mon, 22 Aug 2022) $</pubdate>
<title>VBoxManage modifymedium</title>
</refentryinfo>
<refmeta>
<refentrytitle>VBoxManage-modifymedium</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>VBoxManage-modifymedium</refname>
<refpurpose>change the characteristics of an existing disk image</refpurpose>
<refclass>&product-name;</refclass>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis id="synopsis-vboxmanage-modifymedium">
<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
<command>VBoxManage modifymedium</command>
<group>
<arg choice="plain">disk</arg>
<arg choice="plain">dvd</arg>
<arg choice="plain">floppy</arg>
</group>
<group choice="req">
<arg choice="plain"><replaceable>uuid</replaceable></arg>
<arg choice="plain"><replaceable>filename</replaceable></arg>
</group>
<arg>--autoreset=on | off</arg>
<arg>--compact</arg>
<arg>--description=<replaceable>description</replaceable></arg>
<arg>--move=<replaceable>pathname</replaceable></arg>
<arg>--property=<replaceable>name</replaceable>=[<replaceable>value</replaceable>]</arg>
<arg>--resize=<replaceable>megabytes</replaceable> | --resizebyte=<replaceable>bytes</replaceable></arg>
<arg>--setlocation=<replaceable>pathname</replaceable></arg>
<arg>--type=normal | writethrough | immutable | shareable | readonly | multiattach</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>VBoxManage modifymedium</command> command enables you
to change the characteristics of an existing disk image.
</para>
<note>
<para>
For compatibility with earlier versions of &product-name;, you
can use the <command>modifyvdi</command> and
<command>modifyhd</command> commands.
</para>
</note>
<variablelist>
<varlistentry>
<term>disk | dvd | floppy</term>
<listitem><para>
Specifies the media type of the image.
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>filename</replaceable></term>
<listitem><para>
Specifies the Universally Unique Identifier (UUID) or path
name of the disk image on the host file system. You can
specify the UUID only if the medium is registered. Use the
<command>VBoxManage list hdds</command> command to list the
registered images. You can specfy an absolute or relative
path to the medium.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--autoreset=on | off</option></term>
<listitem><para>
Specifies whether to automatically reset an immutable hard
disk on every virtual machine (VM) startup. This option is
only for immutable hard disks and the default value is
<literal>on</literal>. See <xref linkend="hdimagewrites" />.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--compact</option></term>
<listitem><para>
Compresses disk images by removing blocks that contain only
zeroes. This option shrinks a dynamically allocated image
and reduces the <emphasis>physical</emphasis> size of the
image without affecting the logical size of the virtual
disk.
</para><para>
You can use this option for base images and for differencing
images that are created as part of a snapshot.
</para><note>
<para>
Before you compress the image, you must use a suitable
software tool to zero out free space in the guest system.
For example:
</para>
<itemizedlist>
<listitem><para>
<emphasis role="bold">Windows guests.</emphasis> Run
the <command>sdelete -z</command> command.
</para></listitem>
<listitem><para>
<emphasis role="bold">Linux guests.</emphasis> Use the
<command>zerofree</command> utility, which supports
<literal>ext2</literal> and <literal>ext3</literal>
file systems.
</para></listitem>
<listitem><para>
<emphasis role="bold">Mac OS X guests.</emphasis> Use
the <command>diskutil secureErase freespace 0
/</command> command.
</para></listitem>
</itemizedlist>
</note><para>
Note that you can only use this option to compress VDI
images. To compress non-VID images, you can zero out free
blocks and then clone the disk to any other dynamically
allocated format.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--description=<replaceable>description</replaceable></option></term>
<listitem><para>
Specifies a text description of the medium.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--move=<replaceable>pathname</replaceable></option></term>
<listitem><para>
Specifies a relative or absolute path to a medium on the
host system. Use this option to relocate a medium to a
different location on the host system.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--property=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem><para>
Specifies a property name and value for the medium.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--resize=<replaceable>size</replaceable></option></term>
<listitem><para>
Specifes the new capacity of an existing image in MB. You
can use this option only to expand the capacity of an image.
You can cannot shrink the capacity of an image.
</para><para>
Note that you can resize only dynamically allocated disk
images that use the VDI and VHD formats. This option adjusts
the <emphasis>logical</emphasis> size of a virtual disk and
has only a minor affect on the physical size.
</para><para>
For example, if your dynamically allocated 10 GB disk is
full, you can use the <option>--resize 15360</option> option
to increase the capacity of the existing disk to 15 GB
(15,360 MB). This operation enables you to avoid having to
create a new image and copy all data from within a VM.
</para><para>
Note that using this option only changes the capacity of the
drive. So, you might need to subsequently use a partition
management tool in the guest to adjust the main partition to
fill the drive.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--resizebyte=<replaceable>size</replaceable></option></term>
<listitem><para>
Specifes the new capacity of an existing image in bytes.
This option is similar to the <option>--resize</option>
option, but you specify the size in bytes instead of
megabytes.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--setlocation=<replaceable>pathname</replaceable></option></term>
<listitem><para>
Specifies the new location of the medium on the host system
after the medium has been moved. The path name can be
relative to the current directory or be absolute to the
root.
</para><para>
Note that the <command>VBoxManage modifymedium</command>
command does not perform any sanity checks on the path name
you specify. Ensure that the path name is valid.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--type</option></term>
<listitem><para>
Specifies the new mode type of an existing image. Valid
values are <literal>normal</literal>,
<literal>immutable</literal>,
<literal>writethrough</literal>,
<literal>multi-attach</literal>,
<literal>shareable</literal>, and
<literal>readonly</literal>. For descriptions of these mode
types, see <xref linkend="hdimagewrites" />.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<remark role="help-scope" condition="GLOBAL" />
<para>
The following command modifies the description for the disk image
file called <filename>disk01.vdi</filename>.
</para>
<screen>$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"</screen>
<para>
The following command modifies the write mode for the disk image
file called <filename>disk01.vdi</filename>.
</para>
<screen>$ VBoxManage modifymedium disk disk01.vdi --type writethrough</screen>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="vboxmanage-list" />
</para>
</refsect1>
</refentry>
|
