VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-createmedium.xml@ 103068

Last change on this file since 103068 was 99513, checked in by vboxsync, 20 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: 9.6 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage createmedium
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-createmedium" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 21:59:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage createmedium</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-createmedium</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-createmedium</refname>
44 <refpurpose>create a new medium</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-createmedium">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage createmedium</command>
52 <group>
53 <arg choice="plain"><replaceable>disk</replaceable></arg>
54 <arg choice="plain"><replaceable>dvd</replaceable></arg>
55 <arg choice="plain"><replaceable>floppy</replaceable></arg>
56 </group>
57 <arg choice="req">--filename=<replaceable>filename</replaceable></arg>
58 <group>
59 <arg choice="plain">--size=<replaceable>megabytes</replaceable></arg>
60 <arg choice="plain">--sizebyte=<replaceable>bytes</replaceable></arg>
61 </group>
62 <arg>--diffparent=<group choice="plain">
63 <arg choice="plain"><replaceable>UUID</replaceable></arg>
64 <arg choice="plain"><replaceable>filename</replaceable></arg>
65 </group></arg>
66 <arg>--format=<group choice="plain">
67 <arg choice="plain"><replaceable>VDI</replaceable></arg>
68 <arg choice="plain"><replaceable>VMDK</replaceable></arg>
69 <arg choice="plain"><replaceable>VHD</replaceable></arg>
70 </group></arg>
71 <arg rep="repeat" role="compact">--variant=<group choice="plain">
72 <arg choice="plain">Standard</arg>
73 <arg choice="plain">Fixed</arg>
74 <arg choice="plain">Split2G</arg>
75 <arg choice="plain">Stream</arg>
76 <arg choice="plain">ESX</arg>
77 <arg choice="plain">Formatted</arg>
78 <arg choice="plain">RawDisk</arg>
79 </group></arg> <!-- Value can be repated with comma separator. Difficult to express with docbook. -->
80 <arg rep="repeat">--property=<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
81 <arg rep="repeat">--property-file=<replaceable>name</replaceable>=<replaceable>/path/to/file/with/value</replaceable></arg>
82 </cmdsynopsis>
83 </refsynopsisdiv>
84
85 <refsect1 id="vboxmanage-createmedium-description">
86 <title>Description</title>
87 <para>
88 The <command>VBoxManage createmedium</command> command creates a
89 new medium, such as a disk image file.
90 </para>
91 <note>
92 <para>
93 For compatibility with earlier versions of &product-name;, you
94 can use the <command>createvdi</command> and
95 <command>createhd</command> commands instead of the
96 <command>createmedium</command> command.
97 </para>
98 </note>
99 <variablelist>
100 <varlistentry>
101 <term>disk | dvd | floppy</term>
102 <listitem><para>
103 Specifies the media type. The default value is
104 <literal>disk</literal>.
105 </para></listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><option>--filename=<replaceable>filename</replaceable></option></term>
109 <listitem><para>
110 Specifies the absolute path name to a file on the host file
111 system.
112 </para></listitem>
113 </varlistentry>
114 <varlistentry>
115 <term><option>--size=<replaceable>megabytes</replaceable></option></term>
116 <listitem><para>
117 Specifies the image capacity in one megabyte units.
118 </para></listitem>
119 </varlistentry>
120 <varlistentry>
121 <term><option>--sizebyte=<replaceable>bytes</replaceable></option></term>
122 <listitem><para>
123 Specifies the image capacity in one byte units.
124 </para></listitem>
125 </varlistentry>
126 <varlistentry>
127 <term><option>--diffparent=<replaceable>UUID</replaceable> | <replaceable>filename</replaceable></option></term>
128 <listitem><para>
129 Specifies the Universally Unique Identifier (UUID) or
130 absolute path name of a differencing image parent file on
131 the host file system.
132 </para><para>
133 Use this file to share a base box disk image among VMs.
134 </para></listitem>
135 </varlistentry>
136 <varlistentry>
137 <term><option>--format=VDI | VMDK | VHD</option></term>
138 <listitem><para>
139 Specifies the file format of the output file. Valid formats
140 are <literal>VDI</literal>, <literal>VMDK</literal>, and
141 <literal>VHD</literal>. The default format is
142 <literal>VDI</literal>.
143 </para></listitem>
144 </varlistentry>
145 <varlistentry>
146 <term><option>--variant=Standard | Fixed | Split2G | Stream | ESX | Formatted | RawDisk [,...]</option></term>
147 <listitem><para>
148 Specifies the file format variant for the target medium,
149 which is a comma-separated list of variants. Following are
150 the valid values:
151 </para><itemizedlist>
152 <listitem><para>
153 <literal>Standard</literal> is the default disk image
154 type, which has a dynamically allocated file size.
155 </para></listitem>
156 <listitem><para>
157 <literal>Fixed</literal> uses a disk image that has a
158 fixed file size.
159 </para></listitem>
160 <listitem><para>
161 <literal>Split2G</literal> indicates that the disk image
162 is split into 2GB segments. This value is valid for VMDK
163 disk images only.
164 </para></listitem>
165 <listitem><para>
166 <literal>Stream</literal> optimizes the disk image for
167 downloading. This value is valid for VMDK disk images
168 only.
169 </para></listitem>
170 <listitem><para>
171 <literal>ESX</literal> is used for some VMWare products.
172 This value is valid for VMDK disk images only.
173 </para></listitem>
174 <listitem><para>
175 <literal>Formatted</literal> formats the medium automatically.
176 This value is valid for floppy images only.
177 </para></listitem>
178 <listitem><para>
179 <literal>RawDisk</literal> is used for creating a VMDK
180 image which provides direct access to the hard disk on
181 the host using its raw interface. This value is valid for
182 VMDK disk images only. For detailed information about raw
183 disk access, see <xref linkend="adv-storage-config"/>.
184 </para></listitem>
185 </itemizedlist><para>
186 Note that not all variant combinations are valid. Specifying
187 incompatible variant values in the list will produce an
188 error message.
189 </para></listitem>
190 </varlistentry>
191 <varlistentry>
192 <term><option>--property=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
193 <listitem><para>
194 Specifies any required file format dependent parameters in
195 <literal>key=value</literal> form. Optional.
196 </para>
197 </listitem>
198 </varlistentry>
199 <varlistentry>
200 <term><option>--property-file=<replaceable>name</replaceable>=<replaceable>/path/to/file/with/value</replaceable></option></term>
201 <listitem><para>
202 Specifies any required file format dependent parameters in
203 <literal>key=file/with/value</literal> form. The value is
204 taken from the file. Optional.
205 </para></listitem>
206 </varlistentry>
207 </variablelist>
208 </refsect1>
209
210 <refsect1 id="vboxmanage-createmedium-examples">
211 <title>Examples</title>
212 <remark role="help-scope" condition="GLOBAL" />
213 <para>
214 The following command creates a new disk image file named
215 <filename>disk01.vdi</filename>. The file size is 1024 megabytes.
216 </para>
217<screen>$ VBoxManage createmedium --filename disk01.vdi --size 1024</screen>
218 <para>
219 The following command creates a new floppy disk image file named
220 <filename>floppy01.vdi</filename>. The file size is 1 megabyte.
221 </para>
222<screen>$ VBoxManage createmedium floppy --filename floppy01.img --size 1</screen>
223 <para>
224 The following command creates a raw disk image of an entire physical disk
225 on a Linux host.
226 </para>
227 <screen>$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/dev/sda</screen>
228 </refsect1>
229</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