65 lines
2.3 KiB
Plaintext
65 lines
2.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Box File Format
|
|
description: |-
|
|
The box file format for Vagrant supports a number different providers.
|
|
---
|
|
|
|
# Box File Format
|
|
|
|
A Vagrant `.box` file is a [tarball](<https://en.wikipedia.org/wiki/Tar_(computing)>)
|
|
(`tar`, `tar.gz`, `zip`) that contains all the information for a provider
|
|
to launch a Vagrant machine.
|
|
|
|
There are four different components that make up a box:
|
|
|
|
- VM artifacts (required) - This is the VM image and other artifacts
|
|
in the format accepted by the provider the box is intended for.
|
|
For example, a box targeting the VirtualBox provider might have a `.ofv`
|
|
file and some `.vmdk` files.
|
|
|
|
- metadata.json (required) - Contains a map with information about the box.
|
|
Most importantly the target provider.
|
|
|
|
- info.json - This is a JSON document that can provide additional
|
|
information about the box that displays when a user runs
|
|
`vagrant box list -i`. More information is provided [here](/vagrant/docs/boxes/info).
|
|
|
|
- Vagrantfile - The Vagrantfile embedded in the Vagrant box will provide
|
|
some defaults for users of the box. For more information on how
|
|
Vagrant merges Vagrantfiles including ones sourced within the
|
|
box file see the [Vagrantfile docs](/vagrant/vagrant-cloud)
|
|
|
|
So, if you extract a box and look at it's contents it will look like:
|
|
```
|
|
# contents of the hashicorp/bionic64 box
|
|
# ref: https://app.vagrantup.com/hashicorp/boxes/bionic64
|
|
$ ls hashicorp_bionic_box
|
|
Vagrantfile metadata.json
|
|
box.ovf ubuntu-18.04-amd64-disk001.vmdk
|
|
```
|
|
|
|
## Box metadata.json
|
|
|
|
Within the archive, Vagrant does expect a single file:
|
|
`metadata.json`. There is only one `metadata.json` per box file.
|
|
`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.
|