From c9be89718daeb367879f26b948be7aa5fada7111 Mon Sep 17 00:00:00 2001 From: Jeff Bonhag Date: Fri, 5 Jun 2020 13:59:15 -0400 Subject: [PATCH] Write documentation for :dvd disk type --- website/pages/docs/boxes/index.mdx | 6 ++-- website/pages/docs/disks/configuration.mdx | 24 ++++++++++----- website/pages/docs/disks/usage.mdx | 30 +++++++++++++++---- website/pages/docs/disks/virtualbox/index.mdx | 20 +++++++++++-- 4 files changed, 62 insertions(+), 18 deletions(-) diff --git a/website/pages/docs/boxes/index.mdx b/website/pages/docs/boxes/index.mdx index eb9157985..f2da40784 100644 --- a/website/pages/docs/boxes/index.mdx +++ b/website/pages/docs/boxes/index.mdx @@ -60,7 +60,7 @@ with third-party published boxes. ## Official Boxes -HashiCorp (the makers of Vagrant) publish a basic Ubuntu 18.04 64-bit box that is available for minimal use cases. It is highly optimized, small in size, and includes support for Virtualbox, Hyper-V, and VMware. You can use it like this: +HashiCorp (the makers of Vagrant) publish a basic Ubuntu 18.04 64-bit box that is available for minimal use cases. It is highly optimized, small in size, and includes support for VirtualBox, Hyper-V, and VMware. You can use it like this: ```shell-session $ vagrant init hashicorp/bionic64 @@ -74,10 +74,10 @@ Vagrant.configure("2") do |config| end ``` -For other users, we recommend the [Bento boxes](https://vagrantcloud.com/bento). The Bento boxes are [open source](https://github.com/chef/bento) and built for a number of providers including VMware, Virtualbox, and Parallels. There are a variety of operating systems and versions available. +For other users, we recommend the [Bento boxes](https://vagrantcloud.com/bento). The Bento boxes are [open source](https://github.com/chef/bento) and built for a number of providers including VMware, VirtualBox, and Parallels. There are a variety of operating systems and versions available. These are the only two officially-recommended box sets. Special thanks to the Bento project for providing a solid base template for the `hashicorp/bionic64` box. -~> **It is often a point of confusion**, but Canonical (the company that makes the Ubuntu operating system) publishes boxes under the "ubuntu" namespace on Vagrant Cloud. These boxes only support Virtualbox and do not provide an ideal experience for most users. If you encounter issues with these boxes, please try the Bento boxes instead. +~> **It is often a point of confusion**, but Canonical (the company that makes the Ubuntu operating system) publishes boxes under the "ubuntu" namespace on Vagrant Cloud. These boxes only support VirtualBox and do not provide an ideal experience for most users. If you encounter issues with these boxes, please try the Bento boxes instead. diff --git a/website/pages/docs/disks/configuration.mdx b/website/pages/docs/disks/configuration.mdx index 59650e651..ec6cb9a01 100644 --- a/website/pages/docs/disks/configuration.mdx +++ b/website/pages/docs/disks/configuration.mdx @@ -14,13 +14,21 @@ Vagrant Disks has several options that allow users to define and attach disks to - `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. + Not used for type `:dvd.` + +- `file` (string) - Ffor 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 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. + 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. @@ -31,7 +39,8 @@ Vagrant Disks has several options that allow users to define and attach disks to - `{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"`. +- `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 @@ -53,6 +62,7 @@ You can set a disk type with the first argument of a disk config in your Vagrant ```ruby config.vm.disk :disk, name: "backup", size: "10GB" +config.vm.disk :dvd, name: "installer", path: "./installer.iso" config.vm.disk :floppy, name: "cool_files" ``` diff --git a/website/pages/docs/disks/usage.mdx b/website/pages/docs/disks/usage.mdx index 1bedbf6e9..4a3fdd49a 100644 --- a/website/pages/docs/disks/usage.mdx +++ b/website/pages/docs/disks/usage.mdx @@ -54,7 +54,7 @@ end It should be noted that due to how VirtualBox functions, it is not possible to shrink the size of a disk. -### Attaching new disks +### Attaching new hard disks Vagrant can attach multiple disks to a guest using the VirtualBox provider. An example of attaching a single disk to a guest with 10 GB of storage can be found below: @@ -86,12 +86,32 @@ Vagrant.configure("2") do |config| end ``` -Note: Virtualbox only allows for up to 30 disks to be attached to a given SATA Controller, +Note: VirtualBox only allows for up to 30 disks to be attached to a given SATA Controller, and this number includes the primary disk! Attempting to configure more than 30 will result in a Vagrant error. +### Attaching optical drives + +Vagrant can attach .iso files as optical drives using the VirtualBox provider. +An example of attaching an optical drive to a guest can be found below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :dvd, name: "installer", file: "./installer.iso" + end +end +``` + +Note: VirtualBox only allows for up to 4 optical drives to be attached to a +given IDE controller. + ### Removing Disks -If you have removed a disk from your Vagrant config and wish for it to be detached from the guest, -you will need to `vagrant reload` your guest to apply these changes. **NOTE:** Doing so -will also delete the medium from your hard drive. +If you have removed a disk from your Vagrant config and wish for it to be +detached from the guest, you will need to `vagrant reload` your guest to apply +these changes. **NOTE:** Removing virtual hard disks created by Vagrant will +also delete the medium from your hard drive. diff --git a/website/pages/docs/disks/virtualbox/index.mdx b/website/pages/docs/disks/virtualbox/index.mdx index 8f0241767..974efe76f 100644 --- a/website/pages/docs/disks/virtualbox/index.mdx +++ b/website/pages/docs/disks/virtualbox/index.mdx @@ -31,9 +31,23 @@ off for any changes to be applied to a guest. If you make a configuration change with a guests disk, you will need to `vagrant reload` the guest for any changes to be applied. -When new disks are defined to be attached to a guest, Vagrant will create and attach -these disks to a guests SATA Controller. It should be noted that up to 30 disks -can be attached to the SATA Controller. +When new disks are defined to be attached to a guest, Vagrant will attach +disks to a particular storage controller based on the type of disk configured: + +- For the `:disk` type, Vagrant will attach the disk to a guest's SATA + controller. It will also create the disk if necessary. +- For the `:dvd` type, Vagrant will attach the disk to a guest's IDE + controller. + +Vagrant will not be able to configure disks of a given type if the associated +storage controller does not exist. In this case, you may use +[provider-specific customizations](/docs/providers/virtualbox/configuration#vboxmanage-customizations) +to add a required storage controller. + +It should also be noted that storage controllers have different limits for the +number of disks that can be attached. Attempting to configure more than the +maximum number of disks for a storage controller type will result in a Vagrant +error. For more information on how to use VirtualBox to configure disks for a guest, refer to the [general usage](/docs/disks/usage) and [configuration](/docs/disks/configuration)