summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/man_VBoxManage-createmedium.xml
blob: a73ad8f74b49c9cfec77bc96d998b24c71f37b1d (plain)
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
<?xml version="1.0" encoding="UTF-8"?>
<!--
    manpage, user manual, usage: VBoxManage createmedium
-->
<!--
    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-createmedium" lang="en">
  <refentryinfo>
    <pubdate>$Date: 2022-10-26 20:27:37 +0200 (Wed, 26 Oct 2022) $</pubdate>
    <title>VBoxManage createmedium</title>
  </refentryinfo>

  <refmeta>
    <refentrytitle>VBoxManage-createmedium</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>VBoxManage-createmedium</refname>
    <refpurpose>create a new medium</refpurpose>
    <refclass>&product-name;</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis id="synopsis-vboxmanage-createmedium">
<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
      <command>VBoxManage createmedium</command>
      <group>
        <arg choice="plain"><replaceable>disk</replaceable></arg>
        <arg choice="plain"><replaceable>dvd</replaceable></arg>
        <arg choice="plain"><replaceable>floppy</replaceable></arg>
      </group>
      <arg choice="req">--filename=<replaceable>filename</replaceable></arg>
      <group>
        <arg choice="plain">--size=<replaceable>megabytes</replaceable></arg>
        <arg choice="plain">--sizebyte=<replaceable>bytes</replaceable></arg>
      </group>
      <arg>--diffparent=<group choice="plain">
          <arg choice="plain"><replaceable>UUID</replaceable></arg>
          <arg choice="plain"><replaceable>filename</replaceable></arg>
        </group></arg>
      <arg>--format=<group choice="plain">
          <arg choice="plain"><replaceable>VDI</replaceable></arg>
          <arg choice="plain"><replaceable>VMDK</replaceable></arg>
          <arg choice="plain"><replaceable>VHD</replaceable></arg>
        </group></arg>
      <arg>--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</arg>
      <arg choice="plain" rep="repeat">--property
          <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
      <arg choice="plain" rep="repeat">--property-file
          <replaceable>name</replaceable>=<replaceable>/path/to/file/with/value</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      The <command>VBoxManage createmedium</command> command creates a
      new medium, such as a disk image file.
    </para>
    <note>
      <para>
        For compatibility with earlier versions of &product-name;, you
        can use the <command>createvdi</command> and
        <command>createhd</command> commands instead of the
        <command>createmedium</command> command.
      </para>
    </note>
    <variablelist>
      <varlistentry>
        <term>disk | dvd | floppy</term>
        <listitem><para>
            Specifies the media type. The default value is
            <literal>disk</literal>.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--filename=<replaceable>filename</replaceable></option></term>
        <listitem><para>
            Specifies the absolute path name to a file on the host file
            system.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--size=<replaceable>megabytes</replaceable></option></term>
        <listitem><para>
            Specifies the image capacity in one megabyte units.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--sizebyte=<replaceable>bytes</replaceable></option></term>
        <listitem><para>
            Specifies the image capacity in one byte units.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--diffparent=<replaceable>UUID</replaceable> | <replaceable>filename</replaceable></option></term>
        <listitem><para>
            Specifies the Universally Unique Identifier (UUID) or
            absolute path name of a differencing image parent file on
            the host file system.
          </para><para>
            Use this file to share a base box disk image among VMs.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--format=VDI | VMDK | VHD</option></term>
        <listitem><para>
            Specifies the file format of the output file. Valid formats
            are <literal>VDI</literal>, <literal>VMDK</literal>, and
            <literal>VHD</literal>. The default format is
            <literal>VDI</literal>.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</option></term>
        <listitem><para>
            Specifies the file format variant for the target medium,
            which is a comma-separated list of variants. Following are
            the valid values:
          </para><itemizedlist>
            <listitem><para>
                <literal>Standard</literal> is the default disk image
                type, which has a dynamically allocated file size.
              </para></listitem>
            <listitem><para>
                <literal>Fixed</literal> uses a disk image that has a
                fixed file size.
              </para></listitem>
            <listitem><para>
                <literal>Split2G</literal> indicates that the disk image
                is split into 2GB segments. This value is valid for VMDK
                disk images only.
              </para></listitem>
            <listitem><para>
                <literal>Stream</literal> optimizes the disk image for
                downloading. This value is valid for VMDK disk images
                only.
              </para></listitem>
            <listitem><para>
                <literal>ESX</literal> is used for some VMWare products.
                This value is valid for VMDK disk images only.
              </para></listitem>
            <listitem><para>
                <literal>Formatted</literal> formats the medium automatically.
                This value is valid for floppy images only.
              </para></listitem>
            <listitem><para>
                <literal>RawDisk</literal> is used for creating a VMDK
                image which provides direct access to the hard disk on
                the host using its raw interface. This value is valid for
                VMDK disk images only. For detailed information about raw
                disk access, see <xref linkend="adv-storage-config"/>.
              </para></listitem>
          </itemizedlist><para>
            Note that not all variant combinations are valid. Specifying
            incompatible variant values in the list will produce an
            error message.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--property <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
        <listitem><para>
            Specifies any required file format dependent parameters in
            <literal>key=value</literal> form. Optional.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--property-file <replaceable>name
          </replaceable>=<replaceable>/path/to/file/with/value</replaceable></option></term>
        <listitem><para>
            Specifies any required file format dependent parameters in
            <literal>key=file/with/value</literal> form. The value is
            taken from the file. Optional.
          </para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <remark role="help-scope" condition="GLOBAL" />
    <para>
      The following command creates a new disk image file named
      <filename>disk01.vdi</filename>. The file size is 1024 megabytes.
    </para>
<screen>$ VBoxManage createmedium --filename disk01.vdi --size 1024</screen>
    <para>
      The following command creates a new floppy disk image file named
      <filename>floppy01.vdi</filename>. The file size is 1 megabyte.
    </para>
<screen>$ VBoxManage createmedium floppy --filename floppy01.img --size 1</screen>
    <para>
        The following command creates a raw disk image of an entire physical disk
        on a Linux host.
    </para>
    <screen>$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/dev/sda</screen>
  </refsect1>
</refentry>