» Creating a Base Box

There are a special category of boxes known as "base boxes." These boxescontain the bare minimum required for Vagrant to function, are generallynot made by repackaging an existing Vagrant environment (hence the "base"in the "base box").

For example, the Ubuntu boxes provided by the Vagrant project (such as"precise64") are base boxes. They were created from a minimal Ubuntu installfrom an ISO, rather than repackaging an existing environment.

Base boxes are extremely useful for having a clean slate starting point fromwhich to build future development environments. The Vagrant project hopesin the future to be able to provide base boxes for many more operating systems.Until then, this page documents how you can create your own base box.

Advanced topic! Creating a base box can be a time consumingand tedious process, and is not recommended for new Vagrant users. If you arejust getting started with Vagrant, we recommend trying to find existingbase boxes to use first.

» What's in a Base Box?

A base box typically consists of only a bare minimum set of softwarefor Vagrant to function. As an example, a Linux box may contain only thefollowing:

  • Package manager
  • SSH
  • SSH user so Vagrant can connect
  • Perhaps Chef, Puppet, etc. but not strictly required.In addition to this, each provider may requireadditional software. For example, if you are making a base box for VirtualBox,you will want to include the VirtualBox guest additions so that shared folderswork properly. But if you are making an AWS base box, this is not required.

» Creating a Base Box

Creating a base box is actually provider-specific. This means that dependingon if you are using VirtualBox, VMware, AWS, etc. the process for creatinga base box is different. Because of this, this one document cannot be afull guide to creating a base box.

This page will document some general guidelines for creating base boxes,however, and will link to provider-specific guides for creating baseboxes.

Provider-specific guides for creating base boxes are linked below:

» Packer and Vagrant Cloud

We strongly recommend using Packer to create reproduciblebuilds for your base boxes, as well as automating the builds. Read more aboutautomating Vagrant box creation with Packerin the Packer documentation.

» Disk Space

When creating a base box, make sure the user will have enough disk spaceto do interesting things, without being annoying. For example, in VirtualBox,you should create a dynamically resizing drive with a large maximum size.This causes the actual footprint of the drive to be small initially, butto dynamically grow towards the max size as disk space is needed, providingthe most flexibility for the end user.

If you are creating an AWS base box, do not force the AMI to allocateterabytes of EBS storage, for example, since the user can do that on theirown. But you should default to mounting ephemeral drives, because they'refree and provide a lot of disk space.

» Memory

Like disk space, finding the right balance of the default amount of memoryis important. For most providers, the user can modify the memory withthe Vagrantfile, so do not use too much by default. It would be a pooruser experience (and mildly shocking) if a vagrant up from a base boxinstantly required many gigabytes of RAM. Instead, choose a value suchas 512MB, which is usually enough to play around and do interesting thingswith a Vagrant machine, but can easily be increased when needed.

» Peripherals (Audio, USB, etc.)

Disable any non-necessary hardware in a base box such as audio and USBcontrollers. These are generally unnecessary for Vagrant usage and, again,can be easily added via the Vagrantfile in most cases.

» Default User Settings

Just about every aspect of Vagrant can be modified. However, Vagrant doesexpect some defaults which will cause your base box to "just work" outof the box. You should create these as defaults if you intend to publiclydistribute your box.

If you are creating a base box for private use, you should try not tofollow these, as they open up your base box to security risks (knownusers, passwords, private keys, etc.).

» "vagrant" User

By default, Vagrant expects a "vagrant" user to SSH into the machine as.This user should be setup with theinsecure keypairthat Vagrant uses as a default to attempt to SSH. Also, even thoughVagrant uses key-based authentication by default, it is a general conventionto set the password for the "vagrant" user to "vagrant". This lets peoplelogin as that user manually if they need to.

To configure SSH access with the insecure keypair, place the publickey into the ~/.ssh/authorized_keys file for the "vagrant" user. Notethat OpenSSH is very picky about file permissions. Therefore, make surethat ~/.ssh has 0700 permissions and the authorized keys file has0600 permissions.

When Vagrant boots a box and detects the insecure keypair, it willautomatically replace it with a randomly generated keypair for additionalsecurity while the box is running.

» Root Password: "vagrant"

Vagrant does not actually use or expect any root password. However, havinga generally well known root password makes it easier for the general publicto modify the machine if needed.

Publicly available base boxes usually use a root password of "vagrant" tokeep things easy.

» Password-less Sudo

This is important!. Many aspects of Vagrant expect the default SSH userto have passwordless sudo configured. This lets Vagrant configure networks,mount synced folders, install software, and more.

To begin, some minimal installations of operating systems do not even includesudo by default. Verify that you install sudo in some way.

After installing sudo, configure it (usually using visudo) to allowpasswordless sudo for the "vagrant" user. This can be done with thefollowing line at the end of the configuration file:

  1. vagrant ALL=(ALL) NOPASSWD: ALL

Additionally, Vagrant does not use a pty or tty by default when connectedvia SSH. You will need to make sure there is no line that has requiretty init. Remove that if it exists. This allows sudo to work properly without atty. Note that you can configure Vagrant to request a pty, which letsyou keep this configuration. But Vagrant by default does not do this.

» SSH Tweaks

In order to keep SSH speedy even when your machine or the Vagrant machineis not connected to the internet, set the UseDNS configuration to noin the SSH server configuration.

This avoids a reverse DNS lookup on the connecting SSH client whichcan take many seconds.

» Windows Boxes

Supported Windows guest operating systems:- Windows 7- Windows 8- Windows Server 2008- Windows Server 2008 R2- Windows Server 2012- Windows Server 2012 R2

Windows Server 2003 and Windows XP are not supported, but if you are a diehard XP fan this may help you.

» Base Windows Configuration

  • Turn off UAC
  • Disable complex passwords
  • Disable "Shutdown Tracker"
  • Disable "Server Manager" starting at login (for non-Core)In addition to disabling UAC in the control panel, you also must disableUAC in the registry. This may vary from Windows version to Windows version,but Windows 8/8.1 use the command below. This will allow some things likeautomated Puppet installs to work within Vagrant Windows base boxes.
  1. reg add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /d 0 /t REG_DWORD /f /reg:64

» Base WinRM Configuration

To enable and configure WinRM you will need to set the WinRM service toauto-start and allow unencrypted basic auth (obviously this is not secure).Run the following commands from a regular Windows command prompt:

  1. winrm quickconfig -q
  2. winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"}
  3. winrm set winrm/config @{MaxTimeoutms="1800000"}
  4. winrm set winrm/config/service @{AllowUnencrypted="true"}
  5. winrm set winrm/config/service/auth @{Basic="true"}
  6. sc config WinRM start= auto

» Additional WinRM 1.1 Configuration

These additional configuration steps are specific to Windows Server 2008(WinRM 1.1). For Windows Server 2008 R2, Windows 7 and later versions ofWindows you can ignore this section.

  • Ensure the Windows PowerShell feature is installed
  • Change the WinRM port to 5985 or upgrade to WinRM 2.0The following commands will change the WinRM 1.1 port to what's expected byVagrant:
  1. netsh firewall add portopening TCP 5985 "Port 5985"
  2. winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"}

» Other Software

At this point, you have all the common software you absolutely need foryour base box to work with Vagrant. However, there is some additional softwareyou can install if you wish.

While we plan on it in the future, Vagrant still does not install Chefor Puppet automatically when using those provisioners. Users can use a shellprovisioner to do this, but if you want Chef/Puppet to just work out of thebox, you will have to install them in the base box.

Installing this is outside the scope of this page, but should be fairlystraightforward.

In addition to this, feel free to install and configure any other softwareyou want available by default for this base box.

» Packaging the Box

Packaging the box into a box file is provider-specific. Please refer tothe provider-specific documentation for creating a base box. Someprovider-specific guides are linked to towards the top of this page.

» Distributing the Box

You can distribute the box file however you would like. However, if you wantto support versioning, putting multiple providers at a single URL, pushingupdates, analytics, and more, we recommend you add the box toHashiCorp's Vagrant Cloud.

You can upload both public and private boxes to this service.

» Testing the Box

To test the box, pretend you are a new user of Vagrant and give it a shot:

  1. $ vagrant box add --name my-box /path/to/the/new.box
  2. ...
  3. $ vagrant init my-box
  4. ...
  5. $ vagrant up
  6. ...

If you made a box for some other provider, be sure to specify the—provider option to vagrant up. If the up succeeded, then yourbox worked!