» Box File Format

In the past, boxes were just tar files)of VirtualBox exports. With Vagrant supporting multipleproviders and versioningnow, box files are slightly more complicated.

Box files made for Vagrant 1.0.x (the VirtualBox export tar files) continueto work with Vagrant today. When Vagrant encounters one of these old boxes,it automatically updates it internally to the new format.

Today, there are three different components:

  • Box File - This is a compressed (tar, tar.gz, zip) file that is specificto a single provider and can contain anything. Vagrant core does not everuse the contents of this file. Instead, they are passed to the provider.Therefore, a VirtualBox box file has different contents from a VMwarebox file and so on.

  • Box Catalog Metadata - This is a JSON document (typically exchangedduring interactions with HashiCorp's Vagrant Cloud)that specifies the name of the box, a description, availableversions, available providers, and URLs to the actual box files(next component) for each provider and version. If this catalogmetadata does not exist, a box file can still be added directly, butit will not support versioning and updating.

  • Box Information - This is a JSON document that can provide additionalinformation about the box that displays when a user runsvagrant box list -i. More information is provided here.

The first two components are covered in more detail below.

» Box File

The actual box file is the required portion for Vagrant. It is recommendedyou always use a metadata file alongside a box file, but direct box filesare supported for legacy reasons in Vagrant.

Box files are compressed using tar, tar.gz, or zip. The contents of thearchive can be anything, and is specific to eachprovider. Vagrant core itself only unpacksthe boxes for use later.

Within the archive, Vagrant does expect a single file:metadata.json. This is a JSON file that is completely unrelated tothe above box catalog metadata component; there is only onemetadata.json per box file (inside the box file), whereas onecatalog metadata JSON document can describe multiple versions of thesame box, potentially spanning multiple providers.

metadata.json must contain at least the "provider" key with theprovider the box is for. Vagrant uses this to verify the provider ofthe box. For example, if your box was for VirtualBox, themetadata.json would look like this:

  1. {
  2.   "provider": "virtualbox"
  3. }

If there is no metadata.json file or the file does not contain valid JSONwith at least a "provider" key, then Vagrant will error when adding the box,because it cannot verify the provider.

Other keys/values may be added to the metadata without issue. The valueof the metadata file is passed opaquely into Vagrant and plugins can makeuse of it. At this point, Vagrant core does not use any other keys in thisfile.

» Box Metadata

The metadata is an optional component for a box (but highly recommended)that enables versioning, updating, multipleproviders from a single file, and more.

You do not need to manually make the metadata. If youhave an account with HashiCorp's Vagrant Cloud, youcan create boxes there, and HashiCorp's Vagrant Cloud automatically createsthe metadata for you. The format is still documented here.

It is a JSON document, structured in the following way:

  1. {
  2.   "name": "hashicorp/precise64",
  3.   "description": "This box contains Ubuntu 12.04 LTS 64-bit.",
  4.   "versions": [
  5.     {
  6.       "version": "0.1.0",
  7.       "providers": [
  8.         {
  9.           "name": "virtualbox",
  10.           "url": "http://somewhere.com/precise64_010_virtualbox.box",
  11.           "checksum_type": "sha1",
  12.           "checksum": "foo"
  13.         }
  14.       ]
  15.     }
  16.   ]
  17. }

As you can see, the JSON document can describe multiple versions of a box,multiple providers, and can add/remove providers in different versions.

This JSON file can be passed directly to vagrant box add from thelocal filesystem using a file path or via a URL, and Vagrant willinstall the proper version of the box. In this case, the value for theurl key in the JSON can also be a file path. If multiple providersare available, Vagrant will ask what provider you want to use.