7.11. VBoxManage import

This command imports a virtual appliance in OVF format by copying the virtual disk images and creating virtual machines in Oracle VM VirtualBox. See Section 1.15, “Importing and Exporting Virtual Machines” for an introduction to appliances.

The import subcommand takes at least the path name of an OVF file as input and expects the disk images, if needed, in the same directory as the OVF file. A lot of additional command-line options are supported to control in detail what is being imported and modify the import parameters, but the details depend 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 clone operation. The first two options enable specification of 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 #9 and #10 specify hard disk controllers, respectively. Item #11 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 behind the same --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 5 --ignore --unit 6 --ignore --unit 11 --controller 10