VirtualBox

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

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

manual: Split out the topics of converted manpages into separate files and generate ditamap files for each manpage to avoid needing to hardcode anything in UserManual.xml. This means that the topics inside a manpage can be supressed from the toc, but otoh, they get numbered (with 4.x). The per-topic files are named by refentry/refsect1/refsect2 @id and are currently not cleaned up by 'kmk clean'. bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage import
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-import" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 01:55:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage import</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-import</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-import</refname>
44 <refpurpose>import a virtual appliance in OVF format or from a cloud service and create virtual machines</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-import-ovf">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage import</command>
52 <group choice="req">
53 <arg choice="plain"><replaceable>ovfname</replaceable></arg>
54 <arg choice="plain"><replaceable>ovaname</replaceable></arg>
55 </group>
56 <arg>--dry-run</arg>
57 <arg>--options=<group choice="plain">
58 <arg choice="plain">keepallmacs</arg>
59 <arg choice="plain">keepnatmacs</arg>
60 <arg choice="plain">importtovdi</arg>
61 </group></arg>
62 <arg>--vsys=<replaceable>n</replaceable></arg>
63 <arg>--ostype=<replaceable>ostype</replaceable></arg>
64 <arg>--vmname=<replaceable>name</replaceable></arg>
65 <arg>--settingsfile=<replaceable>file</replaceable></arg>
66 <arg>--basefolder=<replaceable>folder</replaceable></arg>
67 <arg>--group=<replaceable>group</replaceable></arg>
68 <arg>--memory=<replaceable>MB</replaceable></arg>
69 <arg>--cpus=<replaceable>n</replaceable></arg>
70 <arg>--description=<replaceable>text</replaceable></arg>
71 <arg>--eula=<group choice="plain">
72 <arg choice="plain">show</arg>
73 <arg choice="plain">accept</arg>
74 </group></arg>
75 <arg>--unit=<replaceable>n</replaceable></arg>
76 <arg>--ignore</arg>
77 <arg>--scsitype=<group choice="plain">
78 <arg choice="plain">BusLogic</arg>
79 <arg choice="plain">LsiLogic</arg>
80 </group></arg>
81 <!-- <arg>&#45;&#45;controller=<replaceable>n</replaceable></arg> -->
82 <arg>--disk=<replaceable>path</replaceable></arg>
83 <arg>--controller=<replaceable>index</replaceable></arg>
84 <arg>--port=<replaceable>n</replaceable></arg>
85 </cmdsynopsis>
86
87 <cmdsynopsis id="synopsis-vboxmanage-import-cloud">
88<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
89 <command>VBoxManage import</command>
90 <arg choice="plain">OCI://</arg>
91 <arg choice="plain">--cloud</arg>
92 <arg>--ostype=<replaceable>ostype</replaceable></arg>
93 <arg>--vmname=<replaceable>name</replaceable></arg>
94 <arg>--basefolder=<replaceable>folder</replaceable></arg>
95 <arg>--memory=<replaceable>MB</replaceable></arg>
96 <arg>--cpus=<replaceable>n</replaceable></arg>
97 <arg>--description=<replaceable>text</replaceable></arg>
98 <arg choice="req">--cloudprofile=<replaceable>profile</replaceable></arg>
99 <arg choice="req">--cloudinstanceid=<replaceable>id</replaceable></arg>
100 <arg>--cloudbucket=<replaceable>bucket</replaceable></arg>
101 </cmdsynopsis>
102 </refsynopsisdiv>
103
104 <refsect1 id="vboxmanage-import-description">
105 <title>Description</title>
106 <para>
107 The <command>VBoxManage import</command> command imports a virtual
108 appliance either in OVF format or from a cloud service such as &oci;.
109 The import is performed by copying virtual disk images (by default using
110 the VMDK image format) and by creating virtual machines (VMs) in
111 &product-name;. See <xref linkend="ovf" />.
112 </para>
113 <para>
114 You must specify the path name of an OVF file or OVA archive to
115 use as input, or a placeholder for the cloud case. For OVF appliances
116 ensure that any disk images are in the same directory as the OVF file.
117 </para>
118 <para>
119 Note that any options you specify to control the imported virtual
120 appliance or to modify the import parameters rely on the contents
121 of the OVF file or the information from the cloud service.
122 </para>
123 <para>
124 Before you use the import operation to create the VM, perform a
125 dry run to verify the correctness of your configuration. This is more
126 useful with an OVF or OVA appliance, because with a cloud service even
127 a dry run needs to perform most of the time consuming steps.
128 </para>
129 <para>
130 The import from a cloud service downloads a temporary file containing
131 both the boot image and some metadata describing the details of the
132 VM instance. The temporary file is deleted after successful import.
133 </para>
134 <refsect2 id="vboxmanage-import-common-options">
135 <title>Common Options</title>
136 <variablelist>
137 <varlistentry>
138 <term><replaceable>ovfname</replaceable> | <replaceable>ovaname</replaceable></term>
139 <listitem><para>
140 Specifies the name of the OVF file or OVA archive that
141 describes the appliance. In the cloud case this is usually
142 a fixed string such as <literal>OCI://</literal>.
143 </para></listitem>
144 </varlistentry>
145 <varlistentry>
146 <term><option>--dry-run</option></term>
147 <!-- Does this option really work for cloud import? -->
148 <listitem><para>
149 Performs a dry run of the <command>VBoxManage
150 import</command> command before you perform the actual
151 import operation. A dry run operation does the following:
152 </para><itemizedlist>
153 <listitem><para>
154 Outputs a description of the appliance's contents
155 based on the specified OVF or OVA file.
156 </para></listitem>
157 <listitem><para>
158 Shows how the appliance would be imported into
159 &product-name;. In addition, the output shows any
160 options that you can use to change the import
161 behavior.
162 </para></listitem>
163 </itemizedlist><para>
164 The shortened form of this option is <option>-n</option>.
165 </para></listitem>
166 </varlistentry>
167 <varlistentry>
168 <term><option>--options=keepallmacs | keepnatmacs | importtovdi</option></term>
169 <!-- Does this option really work for cloud import? -->
170 <listitem><para>
171 Enables you to fine tune the import operation.
172 </para><para>
173 Valid arguments are as follows:
174 </para><itemizedlist>
175 <listitem><para>
176 <literal>keepallmacs</literal>: Specifies that the MAC
177 addresses of every virtual network card are left
178 unchanged.
179 </para></listitem>
180 <listitem><para>
181 <literal>keepnatmacs</literal>: Specifies that the MAC
182 addresses of every virtual network card are left
183 unchanged if the network type is NAT.
184 </para></listitem>
185 <listitem><para>
186 <literal>importtovdi</literal>: Specifies that all new
187 disk images are in VDI file format.
188 </para></listitem>
189 </itemizedlist></listitem>
190 </varlistentry>
191 <varlistentry>
192 <term><option>--ostype=<replaceable>ostype</replaceable></option></term>
193 <listitem><para>
194 Specifies the guest operating system (OS) information for
195 the VM. Use the <command>VBoxManage list ostypes</command>
196 command to view the OS type identifiers.
197 </para></listitem>
198 </varlistentry>
199 <varlistentry>
200 <term><option>--vmname=<replaceable>name</replaceable></option></term>
201 <listitem><para>
202 Specifies the name of the VM to be used by &product-name;.
203 </para></listitem>
204 </varlistentry>
205 <varlistentry>
206 <term><option>--basefolder=<replaceable>folder</replaceable></option></term>
207 <!-- Does this option really work for cloud import? -->
208 <listitem><para>
209 Specifies the folder where the files of the imported VM
210 are stored.
211 </para></listitem>
212 </varlistentry>
213 <varlistentry>
214 <term><option>--memory=<replaceable>MB</replaceable></option></term>
215 <listitem><para>
216 Specifies the memory size in Megabytes for the imported VM.
217 </para></listitem>
218 </varlistentry>
219 <varlistentry>
220 <term><option>--cpus=<replaceable>n</replaceable></option></term>
221 <listitem><para>
222 Specifies the number of CPUs for the imported VM.
223 </para></listitem>
224 </varlistentry>
225 <varlistentry>
226 <term><option>--description=<replaceable>text</replaceable></option></term>
227 <listitem><para>
228 Specifies the description text visible in the GUI and
229 CLI when checking the VM details.
230 </para></listitem>
231 </varlistentry>
232 </variablelist>
233 </refsect2>
234
235 <refsect2 id="vboxmanage-import-ovf">
236 <title>OVF / OVA Import Options</title>
237 <para>
238 The following options are specific for importing a virtual appliance
239 in OVF or OVA format. Such an appliance can contain one or more VMs,
240 which requires specifying which VM configuration should be adjusted
241 in case you want to change it. See <xref linkend="ovf-import-appliance" />.
242 </para>
243 <remark role="help-copy-synopsis"/>
244 <variablelist>
245 <varlistentry>
246 <term><option>--vsys=<replaceable>n</replaceable></option></term>
247 <listitem><para>
248 Specifies the index selecting a specific VM within the
249 appliance. Affects the following options.
250 </para></listitem>
251 </varlistentry>
252 <varlistentry>
253 <term><option>--unit=<replaceable>n</replaceable></option></term>
254 <listitem><para>
255 Specifies the index selecting a specific unit of a VM
256 within the appliance. Affects the following options.
257 </para></listitem>
258 </varlistentry>
259 <varlistentry>
260 <term><option>--settingsfile=<replaceable>file</replaceable></option></term>
261 <listitem><para>
262 Specifies the name (with or without path) of the VM config
263 file which will be created as part of the import. Usually
264 the preferred way is overriding the VM name with
265 <option>--vmname</option> and if necessary specify the
266 folder in which to create the VM with
267 <option>--basefolder</option>.
268 </para></listitem>
269 </varlistentry>
270 <varlistentry>
271 <term><option>--group=<replaceable>group</replaceable></option></term>
272 <listitem><para>
273 Specifies the primary group of the imported VM.
274 </para></listitem>
275 </varlistentry>
276 <varlistentry>
277 <term><option>--eula=show | accept</option></term>
278 <listitem><para>
279 Enables you to show or accept the license conditions of a
280 VM within the appliance,
281 </para><para>
282 Valid arguments are as follows:
283 </para><itemizedlist>
284 <listitem><para>
285 <literal>show</literal>: Shows the EULA of a VM.
286 </para></listitem>
287 <listitem><para>
288 <literal>accepts</literal>: Accepts the EULA of a VM.
289 Any VMs in an appliance which have an EULA require
290 accepting it, otherwise the import will fail.
291 </para></listitem>
292 </itemizedlist></listitem>
293 </varlistentry>
294 <varlistentry>
295 <term><option>--ignore</option></term>
296 <listitem><para>
297 Ignores the current unit of an imported VM, effectively
298 removing the associated hardware.
299 </para></listitem>
300 </varlistentry>
301 <varlistentry>
302 <term><option>--scsitype=BusLogic | LsiLogic</option></term>
303 <listitem><para>
304 Enables you to select the type of the SCSI controller for
305 the current unit of an imported VM.
306 </para><para>
307 Valid arguments are as follows:
308 </para><itemizedlist>
309 <listitem><para>
310 <literal>BusLogic</literal>: Uses the (very old) BusLogic
311 SCSI controller type.
312 </para></listitem>
313 <listitem><para>
314 <literal>LsiLogic</literal>: Uses the (more modern)
315 LsiLogic SCSI controller type.
316 </para></listitem>
317 </itemizedlist></listitem>
318 </varlistentry>
319 </variablelist>
320 </refsect2>
321
322 <refsect2 id="vboxmanage-import-cloud">
323 <title>Cloud Import Options</title>
324 <para>
325 The following options are specific for importing a VM instance
326 from a cloud service provider. It always deals with a single VM.
327 See <xref linkend="cloud-import-oci" />.
328 </para>
329 <remark role="help-copy-synopsis"/>
330 <variablelist>
331 <varlistentry>
332 <term><option>--cloud</option></term>
333 <listitem><para>
334 Specifies that the import should be from the cloud.
335 </para></listitem>
336 </varlistentry>
337 <varlistentry>
338 <term><option>--cloudprofile=<replaceable>profile</replaceable></option></term>
339 <listitem><para>
340 Specifies the cloud profile which is used to connect to the
341 cloud service provider. The cloud profile contains your &oci;
342 account details, such as your user OCID and the fingerprint
343 for your public key. To use a cloud profile, you must have
344 the required permissions on &oci;.
345 </para></listitem>
346 </varlistentry>
347 <varlistentry>
348 <term><option>--cloudinstanceid=<replaceable>id</replaceable></option></term>
349 <listitem><para>
350 Specifies the ID of an existing instance in the cloud.
351 </para></listitem>
352 </varlistentry>
353 <varlistentry>
354 <term><option>--cloudbucket=<replaceable>bucket</replaceable></option></term>
355 <listitem><para>
356 Specifies the bucket name in which to store the object created
357 from the instance. In &oci;, a bucket is a logical container
358 for storing objects. By default the first bucket available with
359 the cloud profile is used.
360 </para></listitem>
361 </varlistentry>
362 </variablelist>
363 </refsect2>
364 </refsect1>
365
366 <refsect1 id="vboxmanage-import-examples">
367 <title>Examples</title>
368 <remark role="help-scope" condition="GLOBAL"/>
369 <para>
370 The following example performs the dry run of an OVF import operation
371 for a sample appliance that contains a Windows 10 guest:
372 </para>
373<screen>$ VBoxManage import Windows10.ovf --dry-run
374Interpreting Windows10.ovf...
375OK.
376Virtual system 0:
377 0: Suggested OS type: "Windows10_64"
378 (change with "--vsys 0 --ostype &lt;type&gt;"; use "list ostypes" to list all)
379 1: Suggested VM name "win10-appliance"
380 (change with "--vsys 0 --vmname &lt;name&gt;")
381 2: Suggested VM group "/"
382 (change with "--vsys 0 --group &lt;group&gt;")
383 3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox"
384 (change with "--vsys 0 --settingsfile &lt;filename&gt;")
385 4: Suggested VM base folder "/home/user1/VirtualBox VMs"
386 (change with "--vsys 0 --basefolder &lt;path&gt;")
387 5: End-user license agreement
388 (display with "--vsys 0 --eula show";
389 accept with "--vsys 0 --eula accept")
390 6: Number of CPUs: 1
391 (change with "--vsys 0 --cpus &lt;n&gt;")
392 7: Guest memory: 2048 MB (change with "--vsys 0 --memory &lt;MB&gt;")
393 8: Sound card (appliance expects "ensoniq1371", can change on import)
394 (disable with "--vsys 0 --unit 8 --ignore")
395 9: USB controller
396 (disable with "--vsys 0 --unit 9 --ignore")
39710: Network adapter: orig bridged, config 2, extra type=bridged
39811: Floppy
399 (disable with "--vsys 0 --unit 11 --ignore")
40012: SCSI controller, type BusLogic
401 (change with "--vsys 0 --unit 12 --scsitype {BusLogic|LsiLogic}";
402 disable with "--vsys 0 --unit 12 --ignore")
40313: IDE controller, type PIIX4
404 (disable with "--vsys 0 --unit 13 --ignore")
40514: Hard disk image: source image=Windows10.vmdk,
406 target path=/home/user1/disks/Windows10.vmdk, controller=12;channel=0
407 (change target path with "--vsys 0 --unit 14 --disk &lt;path&gt;";
408 change controller with "--vsys 0 --unit 14 --controller &lt;index&gt;";
409 change controller port with "--vsys 0 --unit 14 --port &lt;n&gt;";
410 disable with "--vsys 0 --unit 14 --ignore")</screen>
411 <para>
412 The dry run output lists and numbers the individual configuration
413 items that are described in the <filename>Windows10.ovf</filename>
414 file. Some of the items include information about how to disable
415 or change the configuration of the item.
416 </para>
417 <para>
418 You can disable many of the items by using the <option>--vsys
419 <replaceable>X</replaceable> --unit <replaceable>Y</replaceable>
420 --ignore</option> options. <replaceable>X</replaceable> is the
421 number of the virtual system. The value is <literal>0</literal>
422 unless the appliance includes several virtual system descriptions.
423 <replaceable>Y</replaceable> is the configuration item number.
424 </para>
425 <para>
426 Item 1 in the example command output specifies the name of the
427 target machine. Items 12 and 13 specify the IDE and SCSI hard disk
428 controllers, respectively.
429 </para>
430 <para>
431 Item 14 indicates the hard disk image and the
432 <option>--disk</option> option specifies the target path where the
433 image will be stored, the <option>--controller</option> option specifies
434 which controller the disk will be attached to, and the
435 <option>--port</option> option specifies which port on the controller the
436 disk will be attached to. The default values are specified in the OVF file.
437 </para>
438 <para>
439 You can combine several items for the same virtual system by
440 specifying the same value for the <option>--vsys</option> option.
441 For example use the following command to import a machine as
442 described in the OVF, exclude the sound card and USB controller
443 and specify that the disk image is stored with a different name.
444 </para>
445<screen>$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \
446 --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk</screen>
447 <para>
448 The following example illustrates how to import a VM from &oci;. To find
449 the &oci; VM instances and its ID you can list all available instances
450 with:
451 </para>
452<screen>$ VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen>
453 <para>
454 Once you know the ID the following command imports the instance from
455 &oci;:
456 </para>
457<screen>$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \
458 --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \
459 --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen>
460 </refsect1>
461</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