5093f3120e
This is a big commit, and I apologize in advance for the future
git-blames all pointing to me. This commit does a few things:
1. Merges the website/docs and website/www repo into a single website repo
to be in line with other HashiCorp projects
2. Updates to use middleman-hashicorp
3. Converts less to scss to be in line with other projects
4. Updates page styles to be in line with other projects
5. Optimizes images
6. Prepare for S3 + Fastly deployment with scripts, etc.
7. Removes blog posts (they have been transferred to hashicorp.com with
redirects in place
8. Updated sitemap generation script for better SEO
9. Fixed many broken links
10. Add description to all fields
120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Box File Format"
|
|
sidebar_current: "boxes-format"
|
|
description: |-
|
|
The box file format for Vagrant has changed from only supporting VirtualBox to
|
|
supporting a number different providers and box formats.
|
|
---
|
|
|
|
# Box File Format
|
|
|
|
In the past, boxes were just [tar files](https://en.wikipedia.org/wiki/Tar_\(computing\))
|
|
of VirtualBox exports. With Vagrant supporting multiple
|
|
[providers](/docs/providers/) and [versioning](/docs/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 File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific
|
|
to a single provider and can contain anything. Vagrant core does not 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.
|
|
|
|
* Box Catalog Metadata - This is a JSON document (typically exchanged
|
|
during interactions with [HashiCorp's Atlas](https://atlas.hashicorp.com))
|
|
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 catalog
|
|
metadata does not exist, a box file can still be added directly, but
|
|
it will not support versioning and updating.
|
|
|
|
Each component is covered in more detail below.
|
|
|
|
## 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](/docs/providers/). 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 catalog metadata component; there is only one
|
|
`metadata.json` per box file (inside the box file), whereas one
|
|
catalog metadata JSON document can describe multiple versions of the
|
|
same box, potentially spanning multiple providers.
|
|
|
|
`metadata.json` 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 cannot 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.
|
|
|
|
## Box Metadata
|
|
|
|
The metadata is an optional component for a box (but highly recommended)
|
|
that enables [versioning](/docs/boxes/versioning.html), updating, multiple
|
|
providers from a single file, and more.
|
|
|
|
<div class="alert alert-block alert-info">
|
|
<strong>You do not need to manually make the metadata.</strong> If you
|
|
have an account with <a href="https://atlas.hashicorp.com">HashiCorp's Atlas</a>, you
|
|
can create boxes there, and HashiCorp's Atlas 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. In this case, the value for the
|
|
`url` key in the JSON can also be a file path. If multiple providers
|
|
are available, Vagrant will ask what provider you want to use.
|