haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #3618 from aspiers/box-format-doc-improvements 

website/docs: box format doc improvements
This commit is contained in:
Mitchell Hashimoto 2014-05-02 15:30:22 -07:00
parent 89dfac86c6 3a386f8bde
commit 2f125ef8c8
1 changed files with 54 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
website/docs/source/v2/boxes/format.html.md
View File

@ -10,26 +10,66 @@ 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
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, box files are split into two different components:
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
* 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.
* Box Catalog Metadata - This is a JSON document (typically exchanged
during interactions with [Vagrant Cloud](https://vagrantcloud.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 doesn't 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](/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 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 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.
## Box Metadata
The metadata is an optional component for a box (but highly recommended)
@ -64,40 +104,8 @@ It is a JSON document, structured in the following way:
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.
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.