7.10. VBoxManage import

This command imports one or more virtual machines into Oracle VM VirtualBox. You can import from either of the following:

  • A virtual appliance in OVF format.

  • A cloud service, such as Oracle Cloud Infrastructure. Only a single cloud instance can be imported.

See Section 1.14, “Importing and Exporting Virtual Machines” for more details on importing VMs into Oracle VM VirtualBox.

7.10.1. Import from OVF

The import subcommand takes at least the path name of an OVF file as input and expects the disk images, if needed, to be in the same directory as the OVF file. Many additional command-line options are supported. These enable you to control in detail what is being imported and to modify the import parameters, depending on the content of the OVF file.

It is therefore recommended to first run the import subcommand with the --dry-run or -n option. This will then print a description of the appliance's contents to the screen how it would be imported into Oracle VM VirtualBox, together with the optional command-line options to influence the import behavior.

Use of the --options keepallmacs|keepnatmacs|keepdisknames option enables additional fine tuning of the import operation. The first two options enable you to specify how the MAC addresses of every virtual network card should be handled. They can either be reinitialized, which is the default setting, left unchanged (keepallmacs) or left unchanged when the network type is NAT (keepnatmacs). If you add keepdisknames all new disk images are assigned the same names as the originals, otherwise they are renamed.

As an example, the following is a screen output for a sample appliance containing a Windows XP guest:

VBoxManage import WindowsXp.ovf --dry-run
      Interpreting WindowsXp.ovf...
      Virtual system 0:
       0: Suggested OS type: "WindowsXP"
          (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all)
       1: Suggested VM name "Windows XP Professional_1"
          (change with "--vsys 0 --vmname <name>")
       2: Suggested VM group "/"
          (change with "--vsys 0 --group <group>")
       3: Suggested VM settings file name "/home/klaus/VirtualBox VMs/dummy2 2/dummy2 2.vbox"
          (change with "--vsys 0 --settingsfile <filename>")
       4: Suggested VM base folder "/home/klaus/VirtualBox VMs"
          (change with "--vsys 0 --basefolder <path>")
       5: End-user license agreement
          (display with "--vsys 0 --eula show";
          accept with "--vsys 0 --eula accept")
       6: Number of CPUs: 1
          (change with "--vsys 0 --cpus <n>")
       7: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>")
       8: Sound card (appliance expects "ensoniq1371", can change on import)
          (disable with "--vsys 0 --unit 5 --ignore")
       9: USB controller
          (disable with "--vsys 0 --unit 6 --ignore")
      10: Network adapter: orig bridged, config 2, extra type=bridged
      11: Floppy
          (disable with "--vsys 0 --unit 8 --ignore")
      12: SCSI controller, type BusLogic
          (change with "--vsys 0 --unit 9 --scsitype {BusLogic|LsiLogic}";
          disable with "--vsys 0 --unit 9 --ignore")
      13: IDE controller, type PIIX4
          (disable with "--vsys 0 --unit 10 --ignore")
      14: Hard disk image: source image=WindowsXp.vmdk,
            target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
          (change controller with "--vsys 0 --unit 11 --controller <id>";
          disable with "--vsys 0 --unit 11 --ignore")

The individual configuration items are numbered, and depending on their type support different command-line options. The import subcommand can be directed to ignore many such items with a --vsys X --unit Y --ignore option, where X is the number of the virtual system and Y the item number, as printed on the screen. X is zero, unless there are several virtual system descriptions in the appliance.

In the above example, Item #1 specifies the name of the target machine in Oracle VM VirtualBox. Items #12 and #13 specify hard disk controllers, respectively. Item #14 describes a hard disk image. In this case, the additional --controller option indicates which item the disk image should be connected to, with the default coming from the OVF file.

You can combine several items for the same virtual system using the --vsys option. For example, to import a machine as described in the OVF, but without the sound card and without the USB controller, and with the disk image connected to the IDE controller instead of the SCSI controller, use the following command:

VBoxManage import WindowsXp.ovf
  --vsys 0 --unit 8 --ignore --unit 9 --ignore --unit 14 --controller 13

7.10.2. Import from Oracle Cloud Infrastructure

As the result of this operation, a file with the suffix .oci is downloaded to the local host. This file is a TAR archive which contains a bootable instance image in QCOW2 format and a JSON file with some metadata related to the imported instance.

The downloaded file is deleted after a successful import. If import fails, the downloaded file may not be deleted and the VBoxSVC log file may indicate the location where the file was stored.

During import the bootable image is extracted from the archive and converted into VMDK format. The JSON file is also extracted and stored in the VM machine folder.

The command syntax for importing an Oracle Cloud Infrastructure instance begins with VBoxManage import OCI:// --cloud.

You can list the available Oracle Cloud Infrastructure VM instances and their IDs by using the following command:

VBoxManage cloud --provider=OCI --profile=cloud-profile-name list instances

To import a VM from a cloud service such as Oracle Cloud Infrastructure, use the --cloud option to specify the import from the Cloud. Some of the following options are settings for the VM, for others you must enter an Oracle Cloud Identifier (OCID) for a resource. Use the Oracle Cloud Infrastructure Console to view OCIDs.

The following parameters can be specified:

  • --vmname: Specifies a new name for the imported VM. This name is used as the VM name by Oracle VM VirtualBox.

  • --cloudinstanceid: The ID of an existing instance in the Cloud.

  • --cloudprofile: Specifies the cloud profile that is used to connect to the cloud service provider. The cloud profile contains your Oracle Cloud Infrastructure account details, such as your user OCID and the fingerprint for your public key. To use a cloud profile, you must have the required permissions on Oracle Cloud Infrastructure.

  • --cloudbucket: Specifies the bucket name in which to store the object created from an instance bootable volume. In Oracle Cloud Infrastructure, a bucket is a logical container for storing objects.

The following import options have the same meaning as for OVF import:

  • --ostype: An OS type supported by Oracle VM VirtualBox. Use the VBoxManage list ostypes command to see the whole list of supported OSes. If the type was not set, the Unknown type is used.

  • --basefolder: The folder where the new VM is stored.

  • --description: A string describing the VM.

  • --memory: The amount of RAM memory assigned for the VM, in MB. If this option is not set either the default memory size for the OS type is used, or the value is taken from the Oracle Cloud Infrastructure instance.

  • --cpus: the number of virtual CPUs assigned for the VM. If this option is not set, either the default virtual CPUs setting for the OS type is used, or the value is taken from the Oracle Cloud Infrastructure instance.

The import options --disk, --controller, --scsitype, --unit, --settingsfile are not valid for cloud import.

The following example shows a typical command line for importing an instance from Oracle Cloud Infrastructure:

# VBoxManage import OCI:// --cloud --vmname import_from_oci --memory 4000
  --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" 
  --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket