---
layout: docs
page_title: Vagrant 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.
  Not used for type `:dvd.`

- `file` (string) - For type `:dvd`, this is a required argument that should
  point to an `.iso` file on the host machine. For type `:disk`, this is an
  optional argument that can point to the location of a disk file that already
  exists.

- `name` (string) - Required option to give the disk a name. This name will
  also be used as the filename when creating a virtual hard 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, and it must be of type `:disk`. 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"`. Not
  used for type `:dvd.`

  **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 :dvd, name: "installer", file: "./installer.iso"
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.

~> **Warning!** 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.

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.
