Vagrant Base Boxes

Vagrant Base Boxes

What are Vagrant Base Boxes?

There is 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.

This topic is for advanced users

Icon

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 line tools available on the system you are installing.

Technically a box is an OVA (Open Virtualization Format Archive) file.

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 and Puppet
Chef and Puppet 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?

Icon

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

In this case, we create an Oracle64.box based on Oracle Linux 6.

Creating and Configuring the Virtual Machine

Create the base box using VirtualBox, in this case, it's Oracle Linux 6.3 x86_64 (Oracle64.box).

Guidelines:

Allocate enough disk space in a dynamically resizing drive. Typically, 20-40 GB drive
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.

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.

Create Port Forwarding rule for NAT using VBoxManage command

VBoxManage modifyvm oracle64 --natpf1 "guestssh, tcp,,2222,,22"

Install Linux from DVD ISO.

Keep the base box minimal

Size does matter! Keep the base box under 1 GB, ideally 500 MB.

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
Cleaning up tmp files, or cached system packages.
Debian or Ubuntu => apt-get clean.
RHEL / Oracle / CentOS => yum clean all
Either keep RubyGems from installing documentation, using --no-rdoc --no-ri or consider removing all documentation afterwards using rm -r "$(gem env gemdir)"/doc/*

Conventions over Configuration

Recommended configuration:

Hostname: vagrant-[os-name], e.g. vagrant-debian-lenny
RHEL / Oracle => /etc/sysconfig/network, set HOSTNAME => HOSTNAME=oracle.vagrantup.com
Debian / Ubuntu => /etc/hostname
Domain: vagrantup.com
root Password: vagrant
Main account login: vagrant
Main account password: vagrant

Keep in mind that, in order to simplify configurations, Vagrant make assumptions about the main account login/password. It will assume the text 'vagrant' for both values. If any of these are changed, you will need to remember to specify them in the Vagrantfile using the appropriate configuration methods before packaging the box.

Setup Permissions

Password-less sudo

For user terry

Create /etc/sudoers.d/terry (mode bits => 0440)

terry ALL=(ALL) NOPASSWD:ALL

For user vagrant

Create admin group

groupadd admin

Add vagrant to admin group

usermod -G admin vagrant

In /etc/sudoers file, add the following

%admin ALL=NOPASSWD:ALL

Additionally, set the env_keep variable to "SSH_AUTH_SOCK" so the connection to the forward agent is kept when sudo is run. That way provisioners may run commands as other users and authenticate against the forward agent.

Defaults    env_keep += "SSH_AUTH_SOCK"

Disable requiretty

Some distros automatically enable requiretty within the sudo configuration. If so, there will be a line that looks like Defaults requiretty. Make sure this line is commented, otherwise Vagrant will fail.

Make sure you comment out the following

#Defaults    requiretty

Install VirtualBox Guest Additions

For Debian / Ubuntu, install kernel headers

# Install kernel headers and build-essential
sudo apt-get install linux-headers-$(uname -r) build-essential
# Mount the guest additions image CDROM
sudo mount /dev/cdrom /media/cdrom
# Install VirtualBox Guest Additions
sudo sh /media/cdrom/VBoxLinuxAdditions.run

For RHEL / Oracle

Make sure the kernel devel and headers packages for the running kernel are installed.

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

Install the software Vagrant relies on. The required software is listed below:

Ruby - Use the dev package so mkmf is present for Chef to compile
Recommended to use rbenv, RVM does the same job.
RubyGems - To install the Chef gem
Puppet - To install Puppet (also ensure that a ‘puppet’ group is present!)
Chef gem - For provisioning support (gem install chef)
SSH

Configure SSH Authentication with a Public Key

Refer to SSH Public Key Authentication

Since Vagrant only supports key-based authentication for SSH, SSH must be configured 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, DO 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.

OpenSSH Server side config

Make sure you have the following in /etc/ssh/sshd_config

RSAAuthentication yes
PubkeyAuthentication yes

Make sure the file / folder permissions are properly set, otherwise public key authentication may fail.

File / Folder	Permission
~/.ssh	0700
~/.ssh/authorized_keys	0600

Restart sshd if necessary

Download the insecure vagrant public key and add it to ~vagrant/.ssh/authorized_keys

curl -k https://raw.github.com/mitchellh/vagrant/master/keys/vagrant.pub >> ~vagrant/.ssh/authorized_keys

Troubleshooting

Run sshd in foreground to troubleshoot issue

sudo /usr/sbin/sshd -Dd

SSH Tweaks

In order to keep SSH access speedy even when your host computer can't access the internet, be sure to set UseDNS to no in /etc/ssh/sshd_config. This will disable DNS lookup of clients connecting to the server, which speeds up SSH connection.

UseDNS no

Setup the Vagrantfile

By default, Vagrant only forwards SSH (from port 22 to 2222 with automatic port collision fixing enabled). If you want to modify any defaults or add any other ports to forward, you will have to package a Vagrantfile with your box. You can create a Vagrantfile in any directory.

In the next section when the base box is packaged, it’ll explain how to include your custom Vagrantfile.

Package and Distribute

Now that you have a completed virtual machine and possibly its accompanying Vagrantfile, the final step is to package the contents into a “box” file and distribute it. Packaging is done from Vagrant itself. Open a terminal and go to the directory where your base box’s Vagrantfile is, if you made one. If you didn’t make one, you can be in any directory.

Next, run vagrant package, specifying the name of the virtual machine in VirtualBox that you want to package. If you created a custom Vagrantfile, don’t forget to add --vagrantfile Vagrantfile at the end of the following command as well to include that in the package.

$ vagrant package --base oracle64 --output /path/to/oracle64.box

This will take a few minutes, but the export will show you a progress bar. The result is a file named package.box within the same directory which can be distributed and installed by Vagrant users.

Make sure to test it locally before distributing, setup a test environment, and try ssh in.

$ vagrant box add oracle64 oracle64.box
$ mkdir test_environment
$ cd test_environment
$ vagrant init oracle64
$ vagrant up
$ vagrant ssh

The Oracle Linux vagrant base box is available at vagrantbox.es build notes is available at GitHub.