» Creating a Base Box

As with every Vagrant provider, theVagrant VirtualBox provider has a custom box format that affects how baseboxes are made.

Prior to reading this, you should read thegeneral guide to creating base boxes. Actually,it would probably be most useful to keep this open in a separate tabas you may be referencing it frequently while creating a base box. Thatpage contains important information about common software to installon the box.

Additionally, it is helpful to understand thebasics of the box file format.

Advanced topic! This is a reasonably advanced topic thata beginning user of Vagrant does not need to understand. If you arejust getting started with Vagrant, skip this and use an availablebox. If you are an experienced user of Vagrant and want to createyour own custom boxes, this is for you.

» Virtual Machine

The virtual machine created in VirtualBox can use any configuration you wouldlike, but Vagrant has some hard requirements:

  • The first network interface (adapter 1) must be a NAT adapter.Vagrant uses this to connect the first time.

  • The MAC address of the first network interface (the NAT adapter)should be noted, since you will need to put it in a Vagrantfilelater as the value for config.vm.base_mac. To get this value, usethe VirtualBox GUI.

Other than the above, you are free to customize the base virtual machineas you see fit.

» Additional Software

In addition to the software that should be installed based on thegeneral guide to creating base boxes,VirtualBox base boxes require some additional software.

» VirtualBox Guest Additions

VirtualBox Guest Additionsmust be installed so that things such as shared folders can function.Installing guest additions also usually improves performance since the guestOS can make some optimizations by knowing it is running within VirtualBox.

Before installing the guest additions, you will need the linux kernel headersand the basic developer tools. On Ubuntu, you can easily install these likeso:

  1. $ sudo apt-get install linux-headers-$(uname -r) build-essential dkms

» To install via the GUI:

Next, make sure that the guest additions image is available by using theGUI and clicking on "Devices" followed by "Install Guest Additions".Then mount the CD-ROM to some location. On Ubuntu, this usually looks likethis:

  1. $ sudo mount /dev/cdrom /media/cdrom

Finally, run the shell script that matches your system to install theguest additions. For example, for Linux on x86, it is the following:

  1. $ sudo sh /media/cdrom/VBoxLinuxAdditions.run

If the command succeeds, then the guest additions are now installed!

» To install via the command line:

You can find the appropriate guest additions version to match your VirtualBoxversion by selecting the appropriate versionhere. The examples below use4.3.8, which was the latest VirtualBox version at the time of writing.

  1. wget http://download.virtualbox.org/virtualbox/4.3.8/VBoxGuestAdditions_4.3.8.iso
  2. sudo mkdir /media/VBoxGuestAdditions
  3. sudo mount -o loop,ro VBoxGuestAdditions_4.3.8.iso /media/VBoxGuestAdditions
  4. sudo sh /media/VBoxGuestAdditions/VBoxLinuxAdditions.run
  5. rm VBoxGuestAdditions_4.3.8.iso
  6. sudo umount /media/VBoxGuestAdditions
  7. sudo rmdir /media/VBoxGuestAdditions

If you did not install a Desktop environment when you installed the operatingsystem, as recommended to reduce size, the install of the VirtualBox additionsshould warn you about the lack of OpenGL or Window System Drivers, but you cansafely ignore this.

If the commands succeed, then the guest additions are now installed!

» Packaging the Box

Vagrant includes a simple way to package VirtualBox base boxes. Once you'veinstalled all the software you want to install, you can run this command:

  1. $ vagrant package --base my-virtual-machine

Where "my-virtual-machine" is replaced by the name of the virtual machinein VirtualBox to package as a base box.

It will take a few minutes, but after it is complete, a file "package.box"should be in your working directory which is the new base box. At thispoint, you've successfully created a base box!

» Raw Contents

This section documents the actual raw contents of the box file. This is notas useful when creating a base box but can be useful in debugging issuesif necessary.

A VirtualBox base box is an archive of the resulting files ofexportinga VirtualBox virtual machine. Here is an example of what is containedin such a box:

  1. $ tree
  2. .
  3. |-- Vagrantfile
  4. |-- box-disk1.vmdk
  5. |-- box.ovf
  6. |-- metadata.json
  8. 0 directories, 4 files

In addition to the files from exporting a VirtualBox VM, there isthe "metadata.json" file used by Vagrant itself.

Also, there is a "Vagrantfile." This contains some configuration toproperly set the MAC address of the NAT network device, since VirtualBoxrequires this to be correct in order to function properly. If you arenot using vagrant package —base above, you will have to set theconfig.vm.base_mac setting in this Vagrantfile to the MAC addressof the NAT device without colons.

When bringing up a VirtualBox backed machine, Vagrantimportsthe "box.ovf" file found in the box contents.