---
modeline: |
  vim: set ft=pandoc:
description: |
  The VirtualBox Packer builder is able to create VirtualBox virtual machines
  and export them in the OVF format, starting from an ISO image.
layout: docs
page_title: VirtualBox ISO - Builders
sidebar_title: ISO
---

# VirtualBox Builder (from an ISO)

Type: `virtualbox-iso`

The VirtualBox Packer builder is able to create
[VirtualBox](https://www.virtualbox.org/) virtual machines and export them in
the OVF format, starting from an ISO image.

The builder builds a virtual machine by creating a new virtual machine from
scratch, booting it, installing an OS, provisioning software within the OS, then
shutting it down. The result of the VirtualBox builder is a directory containing
all the files necessary to run the virtual machine portably.

## Basic Example

Here is a basic example. This example is not functional. It will start the OS
installer but then fail because we don't provide the preseed file for Ubuntu to
self-install. Still, the example serves to show the basic configuration:

<Tabs>
<Tab heading="JSON">

```json
{
  "type": "virtualbox-iso",
  "guest_os_type": "Ubuntu_64",
  "iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.5-server-amd64.iso",
  "iso_checksum": "md5:769474248a3897f4865817446f9a4a53",
  "ssh_username": "packer",
  "ssh_password": "packer",
  "shutdown_command": "echo 'packer' | sudo -S shutdown -P now"
}
```

</Tab>
<Tab heading="HCL2">

```hcl
source "virtualbox-iso" "basic-example" {
  guest_os_type = "Ubuntu_64"
  iso_url = "http://releases.ubuntu.com/12.04/ubuntu-12.04.5-server-amd64.iso"
  iso_checksum = "md5:769474248a3897f4865817446f9a4a53"
  ssh_username = "packer"
  ssh_password = "packer"
  shutdown_command = "echo 'packer' | sudo -S shutdown -P now"
}

build {
  sources = ["sources.virtualbox-iso.basic-example"]
}
```

</Tab>
</Tabs>

It is important to add a `shutdown_command`. By default Packer halts the virtual
machine and the file system may not be sync'd. Thus, changes made in a
provisioner might not be saved.

## VirtualBox-ISO Builder Configuration Reference

There are many configuration options available for the builder. In addition to
the items listed here, you will want to look at the general configuration
references for [ISO](#iso-configuration),
[HTTP](#http-directory-configuration),
[Floppy](#floppy-configuration),
[Export](#export-configuration),
[Boot](#boot-configuration),
[Shutdown](#shutdown-configuration),
[Run](#run-configuration),
[Communicator](#communicator-configuration)
configuration references, which are
necessary for this build to succeed and can be found further down the page.

#### Optional:

@include 'builder/virtualbox/iso/Config-not-required.mdx'

@include 'builder/virtualbox/common/VBoxVersionConfig-not-required.mdx'

@include 'builder/virtualbox/common/VBoxBundleConfig-not-required.mdx'

@include 'builder/virtualbox/common/GuestAdditionsConfig-not-required.mdx'

### ISO Configuration

@include 'common/commonsteps/ISOConfig.mdx'

#### Required:

@include 'common/commonsteps/ISOConfig-required.mdx'

#### Optional:

@include 'common/commonsteps/ISOConfig-not-required.mdx'

### Http directory configuration

@include 'common/commonsteps/HTTPConfig.mdx'

#### Optional:

@include 'common/commonsteps/HTTPConfig-not-required.mdx'

### Floppy configuration

@include 'common/commonsteps/FloppyConfig.mdx'

#### Optional:

@include 'common/commonsteps/FloppyConfig-not-required.mdx'

### CD configuration

@include 'common/commonsteps/CDConfig.mdx'

#### Optional:

@include 'common/commonsteps/CDConfig-not-required.mdx'

### Export configuration

#### Optional:

@include 'builder/virtualbox/common/ExportConfig-not-required.mdx'

### Output configuration

#### Optional:

@include 'builder/virtualbox/common/OutputConfig-not-required.mdx'

### Run configuration

#### Optional:

@include 'builder/virtualbox/common/RunConfig-not-required.mdx'

### Shutdown configuration

#### Optional:

@include 'builder/virtualbox/common/ShutdownConfig-not-required.mdx'

### Hardware configuration

#### Optional:

@include 'builder/virtualbox/common/HWConfig-not-required.mdx'

### VBox Manage configuration

@include 'builder/virtualbox/common/VBoxManageConfig.mdx'

#### Optional:

@include 'builder/virtualbox/common/VBoxManageConfig-not-required.mdx'

### Communicator configuration

#### Optional common fields:

@include 'helper/communicator/Config-not-required.mdx'

@include 'builder/virtualbox/common/CommConfig-not-required.mdx'

#### Optional SSH fields:

@include 'helper/communicator/SSH-not-required.mdx'

@include 'helper/communicator/SSH-Private-Key-File-not-required.mdx'

@include 'helper/communicator/SSH-Agent-Auth-not-required.mdx'

#### Optional WinRM fields:

@include 'helper/communicator/WinRM-not-required.mdx'

### Boot Configuration

@include 'common/bootcommand/BootConfig.mdx'

Please note that for the Virtuabox builder, the IP address of the HTTP server
Packer launches for you to access files like the preseed file in the example
above (`{{ .HTTPIP }}`) is hardcoded to 10.0.2.2. If you change the network
of your VM you must guarantee that you can still access this HTTP server.

The boot command is sent to the VM through the `VBoxManage` utility in as few
invocations as possible. We send each character in groups of 25, with a default
delay of 100ms between groups. The delay alleviates issues with latency and CPU
contention. If you notice missing keys, you can tune this delay by specifying
"boot_keygroup_interval" in your Packer template, for example:


<Tabs>
<Tab heading="JSON">

```json
{
  "builders": [
    {
      "type": "virtualbox-iso",
      "boot_keygroup_interval": "500ms"
      ...
    }
  ]
}
```

</Tab>
<Tab heading="HCL2">

```hcl
source "virtualbox-iso" "basic-example" {
  boot_keygroup_interval = "500ms"
  # ...
}
```

</Tab>
</Tabs>

#### Optional:

@include 'common/bootcommand/BootConfig-not-required.mdx'

@include 'builders/virtualbox-ssh-key-pair.mdx'

## Guest Additions

Packer will automatically download the proper guest additions for the version of
VirtualBox that is running and upload those guest additions into the virtual
machine so that provisioners can easily install them.

Packer downloads the guest additions from the official VirtualBox website, and
verifies the file with the official checksums released by VirtualBox.

After the virtual machine is up and the operating system is installed, Packer
uploads the guest additions into the virtual machine. The path where they are
uploaded is controllable by `guest_additions_path`, and defaults to
"VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the home
directory of the SSH user.

## Creating an EFI enabled VM

If you want to create an EFI enabled VM, make sure you set the `iso_interface`
to "sata". Otherwise your attached drive will not be bootable. Example:

<Tabs>
<Tab heading="JSON">

```json
"iso_interface": "sata",
"vboxmanage": [
  [ "modifyvm", "{{.Name}}", "--firmware", "EFI" ]
]
```

</Tab>
<Tab heading="HCL2">

```hcl
iso_interface = "sata"
vboxmanage = [
  [ "modifyvm", "{{.Name}}", "--firmware", "EFI" ]
]
```

</Tab>
</Tabs>