vagrant/docs/base_boxes.md

layout	title
documentation	Documentation - Base Boxes

Base Boxes

This topic is for advanced users

The following topic is for advanced users. The majority of Vagrant users will never have to do this. Therefore, only continue if you want to create a custom operating system. People wishing to distribute changes to an existing base box should see the packaging guide. If you continue with this guide, you will need a decent knowledge of the command line and the specific command lines tools available on the system you are installing.

There are a special category of boxes in Vagrant known as a "base boxes". These boxes are ones which contain the bare bones necessary for Vagrant to function. The basic requirements of a base box are as follows:

• VirtualBox Guest Additions for shared folders, port forwarding, etc.
• SSH with key-based auth support for the vagrant user
• Ruby & RubyGems to install Chef
• Chef for provisioning support

The above are absolutely required of a base box in order to work properly with Vagrant. The versions of those requirements however are up to you, as long as they are working properly.

What about password-based SSH? Why public/private keys?

While Vagrant was initially released with password-based SSH support, this proved to be difficult to support across multiple platforms. Instead, we switched to supporting only key-based authentication which has made cross platform support much easier.

Creating Base Boxes

Creating and Configuring the Virtual Machine

Base boxes must be created using the VirtualBox tool itself. This documentation will not cover the basics of setting up the virtual machine except for some specific guidelines to follow:

• Make sure you allocate enough disk space in a dynamically resizing drive. Typically, we use a 40 GB drive, which is big enough for almost everything.
• Make sure the default memory allocation is not too high. Most people don't want to download a box to find it using 1 GB of RAM. We typically set it at 360 MB to start, since that is the size of most small slices. The RAM is configurable by the user at run-time using their Vagrantfile.
• Disable audio, usb, etc. controllers unless they're needed. Most applications don't need to play music! So save resources by disabling these features.

Now this is really important: Make sure the network controller is set to NAT. For port forwarding to work properly, NAT must be used. Bridged connects are not supported since it requires the machine to specify which device it is bridged to, which is unknown.

Now go ahead and boot up the Virtual Machine, insert the DVD or attach the ISO file you're installing the operating system from, and follow the install procedure.

Size does matter!

Having an environment you can send and have others boot up is really neat, but not very portable if your file is a 5 GB download. Even 1 GB is pushing the limits. You should aim for a final Box size of no more than 500 MB. In order to achieve that size, there is a few things you can do.

• Install the operating system without a GUI. That is, when prompted, deselect the option to install a desktop environment. On a Debian Lenny install, the final size difference between an OS with and without a desktop environment was a whole 1 GB.
• Clear the system cache before you export at the end. You don't need tmp files, or cached system packages. In the case of Debian or Ubuntu based operating systems, you can clean the cache with `apt-get clean`.
• Where possible, avoid installing all the documentation. When installing RubyGems for example, append `--no-rdoc --no-ri` to the install commands.

Convention over Configuration

Choice is a good thing, so just about everything in Vagrant can be changed. However, it's easier for others to use Vagrant when you follow a set of conventions. Now, while these aren't enforced conventions, if you plan to distribute the box, it is recommended you follow the following where possible:

• Hostname: vagrant-[os-name], e.g. vagrant-debian-lenny
• Domain: vagrantup.com
• Root Password: vagrant
• Main account login: vagrant
• Main account password: vagrant

Setup Permissions

Once the Virtual Machine is created, boot it up if it isn't already. Then lets start by making sure the default account has proper permissions. Specifically, the main user should have password-less sudo privileges. We do this by running su and entering the root password you entered during the installation of the operating system. Once logged in, run visudo and set the admin group to use no password.

Note: Some bare bones systems will not include sudo by default. If visudo is not an available command, install the sudo package for your operating system.

The line you should add in the visudo configuration to do that looks like this:

{% highlight bash %} %admin ALL=NOPASSWD: ALL {% endhighlight %}

Once that is setup, you may need to make the 'admin' group, and you then need to assign the main user to that group (on Debian and Ubuntu systems, this is done with the groupadd and usermod utilities. Consult the documentation for the commands your operating system uses).

Then restart sudo using /etc/init.d/sudo restart (command may defer on operating systems). Finally, verify that sudo works without a password, but running exit out of the root account, then sudo which sudo. You should get output similar to /usr/bin/sudo.

Install VirtualBox Guest Additions

Now we have the permissions, lets gets shared folders and port forwarding working so we can harness the full power Vagrant has to offer. There are various guides across the internet explaining how to set up the Virtualbox Guest Additions, but for most unix-based systems, the following will work just fine.

First, build the necessary packages. You may have to look these up for your system, but they should be fairly similar. On Ubuntu and Debian based systems they are as follows:

{% highlight bash %} $ sudo apt-get install linux-headers-$(uname -r) build-essential {% endhighlight %}

Next, make sure to insert the guest additions image by using the GUI and clicking on "Devices" followed by "Install Guest Additions.". Then run the following to mount the CD Rom:

{% highlight bash %} $ sudo mount /media/cdrom {% endhighlight %}

And finally, run the shell script which matches your system. For linux on x86, it is the following:

{% highlight bash %} sudo sh /cdrom/VBoxLinuxAdditions-x86.run {% endhighlight %}

If you didn't install a Desktop environment when you installed the operating system, as recommended to reduce size, the install of the VirtualBox additions should warn you about the lack of OpenGL or Window System Drivers, but you can safely ignore this.

Boot and Setup Basic Software

We need to setup the software Vagrant relies on. The required software is listed below:

• Ruby - Use the dev package so mkmf is present for Chef to compile
• RubyGems - To install the Chef gem
• Chef gem - For provisioning support (gem install chef)
• SSH

These are typically straightforward to install using the operating systems default package management tools, so the details won't be gone into here. If promoted, make sure that the SSH package is set to use basic username/password authentication and write down the username/password for later.

Configure SSH Authentication with a Public Key

Since Vagrant only supports key-based authentication for SSH, you must setup the SSH user to use key-based authentication. This simply requires copying a public key into ~/.ssh/authorized_keys.

If you plan on distributing this base box as a public box, Vagrant provides an "insecure" pair of public and private keys which are available here. By using the public key in that box, any Vagrant installation will automatically be able to connect to your box since Vagrant defaults to using that insecure private key.

If this box is meant to be private, we recommend you create your own custom pair of keys and set that up. Users of your box can then specify the private key you created by setting config.ssh.private_key_path.

Copy the MAC Address

When the operating system was installed, it typically sets up the basic network devices (eth0 and so on) automatically. This includes setting the MAC address of these devices. Since configuring these network devices is often very OS-specific, instead of Vagrant dynamically setting this at runtime, it forces VirtualBox to use a specific MAC address.

This requires little work on your end, but only needs to be done once per base box. Simply run sudo ifconfig or the equivalent and copy the MAC address down somewhere on your host machine. A screenshot of this is shown below:

This MAC Address will be used soon. Go ahead and shutdown the virtual machine before continuing.

Export the Virtual Machine

Next, export the virtual machine with "File" then "Export Appliance." Export it to any folder, but make sure the filename is set to box.ovf, which is the Vagrant default. You may actually name this ovf file anything you wish, but naming it the default has no consequence and will make your life easier.

The export process can take several minutes. While that is running, you can progress onto the next step.

Setup the Vagrantfile

Create a Vagrantfile within the directory which contains the exported virtual machine files (i.e. the directory with box.ovf). Then setup the contents of the Vagrantfile. The following is what the contents of the Vagrantfile should look like, well commented to explain each option:

{% highlight ruby %} Vagrant::Config.run do |config|

Forward the SSH port. The 'forward_port_key' should match the

name of the forwarded port.

config.ssh.forwarded_port_key = "ssh" config.vm.forward_port("ssh", 22, 2222)

The name of your OVF file. This probably won't need to be changed

if you exported as box.ovf

config.vm.box_ovf = "box.ovf"

The MAC address which was copied earlier, without the colons ":"

config.vm.base_mac = "0800279C2E42" end {% endhighlight %}

Package and Distribute

Now that you have the exported virtual machine and the necessary Vagrantfile, the final step is to package the contents into a "box" file and distribute it. The format of "box" files is nothing special: they're simply tar files. The biggest thing is to make sure that all the files in the archive are top-level, meaning that the files aren't in a subdirectory.

Hold on, why not .gz, .bz2, or .7z ?!

Simple. When you export the virtual machine from VirtualBox, it is already compressed. Adding additional compression is slower and yields no smaller box size than just using tar.

The following shows how to build the tar archive properly:

{% highlight bash %} $ cd export_directory $ ls box.mf box.ovf drive.vmdk Vagrantfile $ tar -cvf package.box ./* {% endhighlight %}

As with the export, this can take several minutes. The result is a file called package.box which can be distributed and installed by Vagrant users.

It would be a good idea to try and add this box to your own Vagrant installation, setup a test environment, and try ssh in.

{% highlight bash %} $ cd export_directory $ vagrant box add my_box package.box $ mkdir test_environment $ cd test_environment $ vagrant init

open up Vagrantfile and set config.vm.box to 'my_box'

$ vagrant up $ vagrant ssh {% endhighlight %}