---
layout: "docs"
page_title: "Vagrant Disks Configuration"
sidebar_current: "disks-configuration"
description: |-
  Documentation of various configuration options for Vagrant Disks
---

# Configuration

Vagrant Disks has several options that allow users to define and attach disks to guests.

## Disk Options

* `disk_ext` (string) - Optional argument that defines what kind of file
extension a disk should have. Defaults to `"vdi"` if unspecified. For a list of
supported disk extensions, please check the specific provider being used.
* `file` (string) - Optional argument that defines a path on disk pointing to
the location of a disk file that already exists.
* `name` (string) - Required option to give the disk a name. This name will be
used as the filename when creating the disk.
* `primary` (boolean) - Optional argument that configures a given disk to be the
"primary" disk to manage on the guest. There can only be one `primary` disk per guest.
Defaults to `false` if not specified.
* `provider_config` (hash) - Additional provider specific options for managing a given disk. Please refer to
the provider specific documentation to see any available provider_config options.

    Generally, the disk option accepts two kinds of ways to define a provider config:

    + `providername__diskoption: value`
      - The provider name followed by a double underscore, and then the provider specific option for that disk
    + `{providername: {diskoption: value}, otherprovidername: {diskoption: value}`
      - A hash where the top level key(s) are one or more providers, and each provider keys values are a hash of options and their values.
* `size` (String) - The size of the disk to create. For example, `"10GB"`.

    **Note:** More specific examples of these can be found under the provider
    specific disk page. The `provider_config` option will depend on the provider
    you are using. Please read the provider specific documentation for disk
    management to learn about what options are available to use.

## Disk Types

The disk config currently accepts three kinds of disk types:

* `disk` (symbol)
* `dvd` (symbol)
* `floppy` (symbol)

**NOTE:** These types depend on the provider used, and may not yet be functional. Please
refer to the provider specific implementation for more details for what is supported.

You can set a disk type with the first argument of a disk config in your Vagrantfile:

```ruby
config.vm.disk :disk, name: "backup", size: "10GB"
config.vm.disk :floppy, name: "cool_files"
```

## Provider Author Guide

If you are a vagrant plugin author who maintains a provider for Vagrant, this short guide will hopefully give some information on how to use the internal disk config object.

<div class="alert alert-warning">
  <strong>Warning!</strong> This guide is still being written as we develop this
  new feature for Vagrant. Is something missing, or could this be improved? Please
  let us know on GitHub by opening an issue or open a pull request directly.
</div>

All providers must implement the capability `configure_disks`, and `cleanup_disks`.
These methods are responsible for the following:

- `configure_disks` - Reads in a Vagrant config for defined disks from a Vagrantfile,
and creates and attaches the disks based on the given config
- `cleanup_disks` - Compares the current Vagrant config for defined disks and detaches
any disks that are no longer valid for a guest.

These methods are called in the builtin Vagrant actions _Disk_ and _CleanupDisks_.
If the provider does not support these capabilities, they will be skipped over and no
disks will be configured. It is the providers job to implement these provider capabilities
and handle the methods required to support disk creation and deletion. Vagrant will
handle parsing and supplying the config object based on what has been defined inside
a users Vagrantfile.

For a more detailed example of how to use this disk configuration with Vagrant, please
check out how it was implemented using the VirtualBox provider.

### The disk_meta file

Both builtin disk actions `configure_disks` and `cleanup_disks` expect to read and
write down a `disk_meta` file inside a machines data dir. This file is specifically
for keeping track of the _last configured state_ for disks in a given provider.
Generally, this file is used as a way for Vagrant to keep track of what disks
are being managed by Vagrant with the provider uses, so that it does not accidentally
delete or manage disks that were configured outside of Vagrants configuration.

For the VirtualBox provider, Vagrant uses this file to see what disks were configured
on the _last run_ of Vagrant, and compares that to the current configured state for
the Vagrantfile on the _current run_ of Vagrant. It specifically stores each disks
UUID and disk name for use. If it notices a disk that is no longer in the
Vagrantfile, it can be assumed that the disk is no longer valid for that guest,
and cleans up the disk.

This may not be required for your provider, however with the VirtualBox provider, Vagrant
needs a way to keep track of the defined disks managed by Vagrant and their disk UUIDs
that VirtualBox uses to keep track of these disks.

### The provider_config hash

The disk config class supports an optional hash of options called `provider_config`.
This allows the user to define some additional options for a provider to use that
may be non-standard across different providers.