vaguerent/website/source/docs/disks/configuration.html.md

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

Configuration

Warning! This feature is experimental and may break or change in between releases. Use at your own risk. It currently is not officially supported or functional.

This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:

VAGRANT_EXPERIMENTAL="disk_base_config"

Please note that VAGRANT_EXPERIMENTAL is an environment variable. For more information about this flag visit the Experimental docs page for more info. Without this flag enabled, any disks defined will not be configured.

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. 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.

• name (string) - Required option to give the disk a name. This name will be used as a 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.

• provider_config (hash) - Additional provider specific options for managing a given disk.

  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)

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

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.

Warning! This guide is still being written as we develop this new feature for Vagrant. Some points below are what we plan on covering once this feature is more fully developed in Vagrant.

TODO: Write a bit here about what the internal disk config object looks like, and how to use it. Add code links if possible to the virtualbox disk feature.

• provider_config and how to its structured and how to use/validate it

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.

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.