VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-modifymedium.xml@ 103131

Last change on this file since 103131 was 99513, checked in by vboxsync, 19 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette