diff --git a/website/docs/source/v2/boxes/format.html.md b/website/docs/source/v2/boxes/format.html.md index 411954c0a..0eb584026 100644 --- a/website/docs/source/v2/boxes/format.html.md +++ b/website/docs/source/v2/boxes/format.html.md @@ -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.