606fc7a9e4
It doesn't make sense to use the present tense when saying box files are split into two components, when one of those components is the box file and one is something else. One better way of phrasing it would be to use the past tense: "Box files were split into two separate components" but even that's not completely correct, because the old format did not include the metadata JSON document which is one of the new components. So it's safer to just say that today there are two different components.
104 lines
3.9 KiB
Markdown
104 lines
3.9 KiB
Markdown
---
|
|
page_title: "Box File Format"
|
|
sidebar_current: "boxes-format"
|
|
---
|
|
|
|
# Box File Format
|
|
|
|
In the past, boxes were just [tar files](http://en.wikipedia.org/wiki/Tar_\(computing\))
|
|
of VirtualBox exports. With Vagrant supporting multiple
|
|
[providers](/v2/providers/index.html) and [versioning](/v2/boxes/versioning.html)
|
|
now, box files are slightly more complicated.
|
|
|
|
Box files made for Vagrant 1.0.x (the VirtualBox export `tar` files) continue
|
|
to work with Vagrant today. When Vagrant encounters one of these old boxes,
|
|
it automatically updates it internally to the new format.
|
|
|
|
Today, there are two different components:
|
|
|
|
* Box Metadata - This is a JSON document that specifies the name of the box,
|
|
a description, available versions, available providers, and URLs to the
|
|
actual box files (next component) for each provider and version. If this
|
|
metadata doesn't exist, a box file can still be added directly, but it
|
|
will not support versioning and updating.
|
|
|
|
* Box File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific
|
|
to a single provider and can contain anything. Vagrant core doesn't ever
|
|
use the contents of this file. Instead, they are passed to the provider.
|
|
Therefore, a VirtualBox box file has different contents from a VMware
|
|
box file and so on.
|
|
|
|
Each component is covered in more detail below.
|
|
|
|
## Box Metadata
|
|
|
|
The metadata is an optional component for a box (but highly recommended)
|
|
that enables [versioning](/v2/boxes/versioning.html), updating, multiple
|
|
providers from a single file, and more.
|
|
|
|
<div class="alert alert-block alert-info">
|
|
<strong>You don't need to manually make the metadata.</strong> If you
|
|
have an account with <a href="https://vagrantcloud.com">Vagrant Cloud</a>, you
|
|
can create boxes there, and Vagrant Cloud automatically creates
|
|
the metadata for you. The format is still documented here.
|
|
</div>
|
|
|
|
It is a JSON document, structured in the following way:
|
|
|
|
```json
|
|
{
|
|
"name": "hashicorp/precise64",
|
|
"description": "This box contains Ubuntu 12.04 LTS 64-bit.",
|
|
"versions": [{
|
|
"version": "0.1.0",
|
|
"providers": [{
|
|
"name": "virtualbox",
|
|
"url": "http://somewhere.com/precise64_010_virtualbox.box",
|
|
"checksum_type": "sha1",
|
|
"checksum": "foo"
|
|
}]
|
|
}]
|
|
}
|
|
```
|
|
|
|
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 the local
|
|
filesystem using a file path or via a URL, and Vagrant
|
|
will install the proper version of the box. If multiple providers are
|
|
available, Vagrant will ask what provider you want to use.
|
|
|
|
## Box File
|
|
|
|
The actual box file is the required portion for Vagrant. It is recommended
|
|
you always use a metadata file alongside a box file, but direct box files
|
|
are supported for legacy reasons in Vagrant.
|
|
|
|
Box files are compressed using `tar`, `tar.gz`, or `zip`. The contents of the
|
|
archive can be anything, and is specific to each
|
|
[provider](/v2/providers/index.html). Vagrant core itself only unpacks
|
|
the boxes for use later.
|
|
|
|
Within the archive, Vagrant does expect a single file: `metadata.json`.
|
|
This is a JSON file that is completely unrelated to the above "box metadata"
|
|
component. This file must contain at least the "provider" key with the
|
|
provider the box is for. Vagrant uses this to verify the provider of the
|
|
box. For example, if your box was for VirtualBox,
|
|
the `metadata.json` would look like this:
|
|
|
|
```json
|
|
{
|
|
"provider": "virtualbox"
|
|
}
|
|
```
|
|
|
|
If there is no `metadata.json` file or the file does not contain valid JSON
|
|
with at least a "provider" key, then Vagrant will error when adding the box,
|
|
because it can't verify the provider.
|
|
|
|
Other keys/values may be added to the metadata without issue. The value
|
|
of the metadata file is passed opaquely into Vagrant and plugins can make
|
|
use of it. At this point, Vagrant core does not use any other keys in this
|
|
file.
|