diff --git a/website/content/docs/boxes/base.mdx b/website/content/docs/boxes/base.mdx deleted file mode 100644 index 95757d81583..00000000000 --- a/website/content/docs/boxes/base.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -layout: docs -page_title: Creating a Base Box -description: |- - There are a special category of boxes known as "base boxes." These boxes - contain the bare minimum required for Vagrant to function, are generally - not made by repackaging an existing Vagrant environment (hence the "base" - in the "base box"). ---- - -# Creating a Base Box - -There are a special category of boxes known as "base boxes." These boxes -contain the bare minimum required for Vagrant to function, are generally -not made by repackaging an existing Vagrant environment (hence the "base" -in the "base box"). - -For example, the Ubuntu boxes provided by the Vagrant project (such as -"bionic64") are base boxes. They were created from a minimal Ubuntu install -from an ISO, rather than repackaging an existing environment. - -Base boxes are extremely useful for having a clean slate starting point from -which to build future development environments. The Vagrant project hopes -in the future to be able to provide base boxes for many more operating systems. -Until then, this page documents how you can create your own base box. - -~> **Advanced topic!** Creating a base box can be a time consuming -and tedious process, and is not recommended for new Vagrant users. If you are -just getting started with Vagrant, we recommend trying to find existing -base boxes to use first. - -## What's in a Base Box? - -A base box typically consists of only a bare minimum set of software -for Vagrant to function. As an example, a Linux box may contain only the -following: - -- Package manager -- SSH -- SSH user so Vagrant can connect -- Perhaps Chef, Puppet, etc. but not strictly required. - -In addition to this, each [provider](/vagrant/docs/providers/) may require -additional software. For example, if you are making a base box for VirtualBox, -you will want to include the VirtualBox guest additions so that shared folders -work properly. But if you are making an AWS base box, this is not required. - -## Creating a Base Box - -Creating a base box is actually provider-specific. This means that depending -on if you are using VirtualBox, VMware, AWS, etc. the process for creating -a base box is different. Because of this, this one document cannot be a -full guide to creating a base box. - -This page will document some general guidelines for creating base boxes, -however, and will link to provider-specific guides for creating base -boxes. - -Provider-specific guides for creating base boxes are linked below: - -- [Docker Base Boxes](/vagrant/docs/providers/docker/boxes) -- [Hyper-V Base Boxes](/vagrant/docs/providers/hyperv/boxes) -- [VMware Base Boxes](/vagrant/docs/providers/vmware/boxes) -- [VirtualBox Base Boxes](/vagrant/docs/providers/virtualbox/boxes) - -### Packer and Vagrant Cloud - -We strongly recommend using [Packer](https://www.packer.io/) to create reproducible -builds for your base boxes, as well as automating the builds. Read more about -[automating Vagrant box creation with Packer](/packer/guides/packer-on-cicd/build-image-in-cicd) -in the Packer documentation. - -### Disk Space - -When creating a base box, make sure the user will have enough disk space -to do interesting things, without being annoying. For example, in VirtualBox, -you should create a dynamically resizing drive with a large maximum size. -This causes the actual footprint of the drive to be small initially, but -to dynamically grow towards the max size as disk space is needed, providing -the most flexibility for the end user. - -If you are creating an AWS base box, do not force the AMI to allocate -terabytes of EBS storage, for example, since the user can do that on their -own. But you should default to mounting ephemeral drives, because they're -free and provide a lot of disk space. - -### Memory - -Like disk space, finding the right balance of the default amount of memory -is important. For most providers, the user can modify the memory with -the Vagrantfile, so do not use too much by default. It would be a poor -user experience (and mildly shocking) if a `vagrant up` from a base box -instantly required many gigabytes of RAM. Instead, choose a value such -as 512MB, which is usually enough to play around and do interesting things -with a Vagrant machine, but can easily be increased when needed. - -### Peripherals (Audio, USB, etc.) - -Disable any non-necessary hardware in a base box such as audio and USB -controllers. These are generally unnecessary for Vagrant usage and, again, -can be easily added via the Vagrantfile in most cases. - -## Default User Settings - -Just about every aspect of Vagrant can be modified. However, Vagrant does -expect some defaults which will cause your base box to "just work" out -of the box. You should create these as defaults if you intend to publicly -distribute your box. - -If you are creating a base box for private use, you should try _not_ to -follow these, as they open up your base box to security risks (known -users, passwords, private keys, etc.). - -### "vagrant" User - -By default, Vagrant expects a "vagrant" user to SSH into the machine as. -This user should be setup with the -[insecure keypairs](https://github.com/hashicorp/vagrant/tree/main/keys) -that Vagrant uses as a default to attempt to SSH. It should belong to a -group named "vagrant". Also, even though Vagrant uses key-based -authentication by default, it is a general convention to set the -password for the "vagrant" user to "vagrant". This lets people login as -that user manually if they need to. - -To configure SSH access with the insecure keypair, place the [public -keys](https://github.com/hashicorp/vagrant/tree/main/keys/vagrant.pub) -into the `~/.ssh/authorized_keys` file for the "vagrant" user. Note -that OpenSSH is very picky about file permissions. Therefore, make sure -that `~/.ssh` has `0700` permissions and the authorized keys file has -`0600` permissions. - -When Vagrant boots a box and detects the insecure keypair, it will -automatically replace it with a randomly generated keypair for additional -security while the box is running. - -### Root Password: "vagrant" - -Vagrant does not actually use or expect any root password. However, having -a generally well known root password makes it easier for the general public -to modify the machine if needed. - -Publicly available base boxes usually use a root password of "vagrant" to -keep things easy. - -### Password-less Sudo - -This is **important!**. Many aspects of Vagrant expect the default SSH user -to have passwordless sudo configured. This lets Vagrant configure networks, -mount synced folders, install software, and more. - -To begin, some minimal installations of operating systems do not even include -`sudo` by default. Verify that you install `sudo` in some way. - -After installing sudo, configure it (usually using `visudo`) to allow -passwordless sudo for the "vagrant" user. This can be done with the -following line at the end of the configuration file: - -``` -vagrant ALL=(ALL) NOPASSWD: ALL -``` - -Additionally, Vagrant does not use a pty or tty by default when connected -via SSH. You will need to make sure there is no line that has `requiretty` in -it. Remove that if it exists. This allows sudo to work properly without a -tty. Note that you _can_ configure Vagrant to request a pty, which lets -you keep this configuration. But Vagrant by default does not do this. - -### SSH Tweaks - -In order to keep SSH speedy even when your machine or the Vagrant machine -is not connected to the internet, set the `UseDNS` configuration to `no` -in the SSH server configuration. - -This avoids a reverse DNS lookup on the connecting SSH client which -can take many seconds. - -## Windows Boxes - -Supported Windows guest operating systems: - -- Windows 7 -- Windows 8 -- Windows Server 2008 -- Windows Server 2008 R2 -- Windows Server 2012 -- Windows Server 2012 R2 - -Windows Server 2003 and Windows XP are _not_ supported, but if you are a die -hard XP fan [this](https://stackoverflow.com/a/18593425/18475) may help you. - -### Base Windows Configuration - -- Turn off UAC -- Disable complex passwords -- Disable "Shutdown Tracker" -- Disable "Server Manager" starting at login (for non-Core) - -In addition to disabling UAC in the control panel, you also must disable -UAC in the registry. This may vary from Windows version to Windows version, -but Windows 8/8.1 use the command below. This will allow some things like -automated Puppet installs to work within Vagrant Windows base boxes. - -``` -reg add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /d 0 /t REG_DWORD /f /reg:64 -``` - -### Base WinRM Configuration - -To enable and configure WinRM you will need to set the WinRM service to -auto-start and allow unencrypted basic auth (obviously this is not secure). -Run the following commands from a regular Windows command prompt: - -``` -winrm quickconfig -q -winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"} -winrm set winrm/config @{MaxTimeoutms="1800000"} -winrm set winrm/config/service @{AllowUnencrypted="true"} -winrm set winrm/config/service/auth @{Basic="true"} -sc config WinRM start= auto -``` - -### Additional WinRM 1.1 Configuration - -These additional configuration steps are specific to Windows Server 2008 -(WinRM 1.1). For Windows Server 2008 R2, Windows 7 and later versions of -Windows you can ignore this section. - -1. Ensure the Windows PowerShell feature is installed -2. Change the WinRM port to 5985 or upgrade to WinRM 2.0 - -The following commands will change the WinRM 1.1 port to what's expected by -Vagrant: - -``` -netsh firewall add portopening TCP 5985 "Port 5985" -winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"} -``` - -### Optional WinSSH Configuration - -When using the WinSSH communicator, you may run into an issue where a PowerShell -command can't display a progress bar. A typical error message might look like: - -``` -Win32 internal error "Access is denied" 0x5 occurred while reading the console output buffer. -``` - -In order to prevent this, we recommend setting `$ProgressPreference = "SilentlyContinue"` -in your box's PowerShell profile: - -``` -if (!(Test-Path -Path $PROFILE)) { - New-Item -ItemType File -Path $PROFILE -Force -} - -Add-Content $PROFILE '$ProgressPreference = "SilentlyContinue"' -``` - -## Other Software - -At this point, you have all the common software you absolutely _need_ for -your base box to work with Vagrant. However, there is some additional software -you can install if you wish. - -While we plan on it in the future, Vagrant still does not install Chef -or Puppet automatically when using those provisioners. Users can use a shell -provisioner to do this, but if you want Chef/Puppet to just work out of the -box, you will have to install them in the base box. - -Installing this is outside the scope of this page, but should be fairly -straightforward. - -In addition to this, feel free to install and configure any other software -you want available by default for this base box. - -## Packaging the Box - -Packaging the box into a `box` file is provider-specific. Please refer to -the provider-specific documentation for creating a base box. Some -provider-specific guides are linked to towards the top of this page. - -## Distributing the Box - -You can distribute the box file however you would like. However, if you want -to support versioning, putting multiple providers at a single URL, pushing -updates, analytics, and more, we recommend you add the box to -[HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud). - -You can upload both public and private boxes to this service. - -## Testing the Box - -To test the box, pretend you are a new user of Vagrant and give it a shot: - -```shell-session -$ vagrant box add --name my-box /path/to/the/new.box -... -$ vagrant init my-box -... -$ vagrant up -... -``` - -If you made a box for some other provider, be sure to specify the -`--provider` option to `vagrant up`. If the up succeeded, then your -box worked! diff --git a/website/content/docs/boxes/box_repository.mdx b/website/content/docs/boxes/box_repository.mdx deleted file mode 100644 index 3c3c2668216..00000000000 --- a/website/content/docs/boxes/box_repository.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -layout: docs -page_title: Box Repository -description: |- - Vagrant can download boxes from a Box Repository. [Vagrantcloud](https://vagrantcloud.com/) - is the HashiCorp maintained Box Repository. ---- - -# Box Repository - -A Vagrant Box Repository provides Vagrant with some boxes and information -on how to get the boxes. This can exist on a local filesystem or a service -like Vagrantcloud. - -There are two components that make up a Box Repository: - -- Vagrant Boxes - These are Vagrant `.box` files. See the - [box documentation](/vagrant/docs/boxes) for more information on Vagrant boxes. - -- Box Catalog Metadata - This is a JSON document (typically exchanged - during interactions with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud)) - that specifies the name of the box, a description, available - versions, available providers, and URLs to the actual box files - (next component) for each provider and version. If this catalog - metadata does not exist, a box file can still be added directly, but - it will not support versioning and updating. - -## Box Catalog Metadata - -The metadata is an optional component for a box (but highly recommended) -that enables [versioning](/vagrant//docs/boxes/versioning), updating, multiple -providers from a single file, and more. - --> **You do not need to manually make the metadata.** If you -have an account with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud), you -can create boxes there, and HashiCorp's Vagrant Cloud automatically creates -the metadata for you. The format is still documented here. - -It is a JSON document, structured in the following way: - -```json -{ - "name": "hashicorp/bionic64", - "description": "This box contains Ubuntu 18.04 LTS 64-bit.", - "versions": [ - { - "version": "0.1.0", - "providers": [ - { - "name": "virtualbox", - "url": "http://example.com/bionic64_010_virtualbox.box", - "checksum_type": "sha1", - "checksum": "foo", - "architecture": "amd64", - "default_architecture": true - } - ] - } - ] -} -``` - -As you can see, the JSON document can describe multiple versions of a box, -multiple providers, and can add/remove providers/architectures in different -versions. - -This JSON file can be passed directly to `vagrant box add` from the -local filesystem using a file path or via a URL, and Vagrant will -install the proper version of the box. In this case, the value for the -`url` key in the JSON can also be a file path. If multiple providers -are available, Vagrant will ask what provider you want to use. diff --git a/website/content/docs/boxes/format.mdx b/website/content/docs/boxes/format.mdx deleted file mode 100644 index bd8d4e32989..00000000000 --- a/website/content/docs/boxes/format.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -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]() -(`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. Values currently used by Vagrant core: - -* `provider` - (string) Provider for the box -* `architecture` - (string) Architecture of the box diff --git a/website/content/docs/boxes/info.mdx b/website/content/docs/boxes/info.mdx deleted file mode 100644 index 3a5a5b62944..00000000000 --- a/website/content/docs/boxes/info.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: docs -page_title: Box Info Format -description: |- - A box can provide additional information to the user by supplying an info.json - file within the box. ---- - -# Additional Box Information - -When creating a Vagrant box, you can supply additional information that might be -relevant to the user when running `vagrant box list -i`. For example, you could -package your box to include information about the author of the box and a -website for users to learn more: - -``` -brian@localghost % vagrant box list -i -hashicorp/bionic64 (virtualbox, 1.0.0) - - author: brian - - homepage: https://www.vagrantup.com -``` - -## Box Info - -To accomplish this, you simply need to include a file named `info.json` when -creating a [base box](/vagrant/docs/boxes/base) which is a JSON document containing -any and all relevant information that will be displayed to the user when the -`-i` option is used with `vagrant box list`. - -```json -{ - "author": "brian", - "homepage": "https://example.com" -} -``` - -There are no special keys or values in `info.json`, and Vagrant will print each -key and value on its own line. - -The [Box File Format](/vagrant/docs/boxes/format) provides more information about what -else goes into a Vagrant box. diff --git a/website/content/docs/boxes/versioning.mdx b/website/content/docs/boxes/versioning.mdx deleted file mode 100644 index 7b99b2a05b8..00000000000 --- a/website/content/docs/boxes/versioning.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -layout: docs -page_title: Box Versioning -description: |- - Since Vagrant 1.5, boxes support versioning. This allows the people who - make boxes to push updates to the box, and the people who use the box - have a simple workflow for checking for updates, updating their boxes, - and seeing what has changed. ---- - -# Box Versioning - -Since Vagrant 1.5, boxes support versioning. This allows the people who -make boxes to push updates to the box, and the people who use the box -have a simple workflow for checking for updates, updating their boxes, -and seeing what has changed. - -If you are just getting started with Vagrant, box versioning is not too -important, and we recommend learning about some other topics first. But -if you are using Vagrant on a team or plan on creating your own boxes, -versioning is very important. Luckily, having versioning built right in -to Vagrant makes it easy to use and fit nicely into the Vagrant workflow. - -This page will cover how to use versioned boxes. It does _not_ cover how -to update your own custom boxes with versions. That is covered in -[creating a base box](/vagrant/docs/boxes/base). - -## Viewing Versions and Updating - -`vagrant box list` only shows _installed_ versions of boxes. If you want -to see all available versions of a box, you will have to find the box -on [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud). An easy way to find a box -is to use the url `https://vagrantcloud.com/$USER/$BOX`. For example, for -the `hashicorp/bionic64` box, you can find information about it at -`https://vagrantcloud.com/hashicorp/bionic64`. - -You can check if the box you are using is outdated with `vagrant box outdated`. -This can check if the box in your current Vagrant environment is outdated -as well as any other box installed on the system. - -Finally, you can update boxes with `vagrant box update`. This will download -and install the new box. This _will not_ magically update running Vagrant -environments. If a Vagrant environment is already running, you will have to -destroy and recreate it to acquire the new updates in the box. The update -command just downloads these updates locally. - -## Version Constraints - -You can constrain a Vagrant environment to a specific version or versions -of a box using the [Vagrantfile](/vagrant/docs/vagrantfile/) by specifying -the `config.vm.box_version` option. - -If this option is not specified, the latest version is always used. This is -equivalent to specifying a constraint of ">= 0". - -The box version configuration can be a specific version or a constraint of -versions. Constraints can be any combination of the following: -`= X`, `> X`, `< X`, `>= X`, `<= X`, `~> X`. You can combine multiple -constraints by separating them with commas. All the constraints should be -self explanatory except perhaps for `~>`, known as the "pessimistic constraint". -Examples explain it best: `~> 1.0` is equivalent to `>= 1.0, < 2.0`. And -`~> 1.1.5` is equivalent to `>= 1.1.5, < 1.2.0`. - -You can choose to handle versions however you see fit. However, many boxes -in the public catalog follow [semantic versioning](http://semver.org/). -Basically, only the first number (the "major version") breaks backwards -compatibility. In terms of Vagrant boxes, this means that any software that -runs in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on, -but "2.0" might introduce big changes that break your software. By following -this convention, the best constraint is `~> 1.0` because you know it is safe -no matter what version is in that range. - -Please note that, while the semantic versioning specification allows for -more than three points and pre-release or beta versions, Vagrant boxes must be -of the format `X.Y.Z` where `X`, `Y`, and `Z` are all positive integers. - -## Automatic Update Checking - -Using the [Vagrantfile](/vagrant/docs/vagrantfile/), you can also configure -Vagrant to automatically check for updates during any `vagrant up`. This is -enabled by default, but can easily be disabled with -`config.vm.box_check_update = false` in your Vagrantfile. - -When this is enabled, Vagrant will check for updates on every `vagrant up`, -not just when the machine is being created from scratch, but also when it -is resuming, starting after being halted, etc. - -If an update is found, Vagrant will output a warning to the user letting -them know an update is available. That user can choose to ignore the warning -for now, or can update the box by running `vagrant box update`. - -Vagrant can not and does not automatically download the updated box and -update the machine because boxes can be relatively large and updating the -machine requires destroying it and recreating it, which can cause important -data to be lost. Therefore, this process is manual to the extent that the -user has to manually enter a command to do it. - -## Pruning Old Versions - -Vagrant does not automatically prune old versions because it does not know -if they might be in use by other Vagrant environments. Because boxes can -be large, you may want to actively prune them once in a while using -`vagrant box remove`. You can see all the boxes that are installed -using `vagrant box list`. - -Another option is to use `vagrant box prune` command to remove all installed boxes that are outdated and not currently in use. diff --git a/website/content/docs/providers/docker/commands.mdx b/website/content/docs/cli/docker-exec.mdx similarity index 99% rename from website/content/docs/providers/docker/commands.mdx rename to website/content/docs/cli/docker-exec.mdx index 1c4812d73e6..7e785165c4a 100644 --- a/website/content/docs/providers/docker/commands.mdx +++ b/website/content/docs/cli/docker-exec.mdx @@ -8,7 +8,7 @@ description: |- underneath. --- -# Docker Commands +# Docker commands The Docker provider exposes some additional Vagrant commands that are useful for interacting with Docker containers. This helps with your diff --git a/website/content/docs/cli/docker-logs.mdx b/website/content/docs/cli/docker-logs.mdx new file mode 100644 index 00000000000..7e785165c4a --- /dev/null +++ b/website/content/docs/cli/docker-logs.mdx @@ -0,0 +1,112 @@ +--- +layout: docs +page_title: Commands - Docker Provider +description: |- + The Docker provider exposes some additional Vagrant commands that are + useful for interacting with Docker containers. This helps with your + workflow on top of Vagrant so that you have full access to Docker + underneath. +--- + +# Docker commands + +The Docker provider exposes some additional Vagrant commands that are +useful for interacting with Docker containers. This helps with your +workflow on top of Vagrant so that you have full access to Docker +underneath. + +### docker-exec + +`vagrant docker-exec` can be used to run one-off commands against +a Docker container that is currently running. If the container is not running, +an error will be returned. + +```shell-session +$ vagrant docker-exec app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. + +Note that the "name" corresponds to the name of the VM, **not** the name of the +Docker container. Consider the following Vagrantfile: + +```ruby +Vagrant.configure(2) do |config| + config.vm.provider "docker" do |d| + d.image = "consul" + end +end +``` + +This Vagrantfile will start the official Docker Consul image. However, the +associated Vagrant command to `docker-exec` into this instance is: + +```shell-session +$ vagrant docker-exec -it -- /bin/sh +``` + +In particular, the command is actually: + +```shell-session +$ vagrant docker-exec default -it -- /bin/sh +``` + +Because "default" is the default name of the first defined VM. In a +multi-machine Vagrant setup as shown below, the "name" attribute corresponds +to the name of the VM, **not** the name of the container: + +```ruby +Vagrant.configure do |config| + config.vm.define "web" do + config.vm.provider "docker" do |d| + d.image = "nginx" + end + end + + config.vm.define "consul" do + config.vm.provider "docker" do |d| + d.image = "consul" + end + end +end +``` + +The following command is invalid: + +```shell-session +# Not valid +$ vagrant docker-exec -it nginx -- /bin/sh +``` + +This is because the "name" of the VM is "web", so the command is actually: + +```shell-session +$ vagrant docker-exec -it web -- /bin/sh +``` + +For this reason, it is recommended that you name the VM the same as the +container. In the above example, it is unambiguous that the command to enter +the Consul container is: + +```shell-session +$ vagrant docker-exec -it consul -- /bin/sh +``` + +### docker-logs + +`vagrant docker-logs` can be used to see the logs of a running container. +Because most Docker containers are single-process, this is used to see +the logs of that one process. Additionally, the logs can be tailed. + +### docker-run + +`vagrant docker-run` can be used to run one-off commands against +a Docker container. The one-off Docker container that is started shares +all the volumes, links, etc. of the original Docker container. An +example is shown below: + +```shell-session +$ vagrant docker-run app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. diff --git a/website/content/docs/cli/docker-run.mdx b/website/content/docs/cli/docker-run.mdx new file mode 100644 index 00000000000..7e785165c4a --- /dev/null +++ b/website/content/docs/cli/docker-run.mdx @@ -0,0 +1,112 @@ +--- +layout: docs +page_title: Commands - Docker Provider +description: |- + The Docker provider exposes some additional Vagrant commands that are + useful for interacting with Docker containers. This helps with your + workflow on top of Vagrant so that you have full access to Docker + underneath. +--- + +# Docker commands + +The Docker provider exposes some additional Vagrant commands that are +useful for interacting with Docker containers. This helps with your +workflow on top of Vagrant so that you have full access to Docker +underneath. + +### docker-exec + +`vagrant docker-exec` can be used to run one-off commands against +a Docker container that is currently running. If the container is not running, +an error will be returned. + +```shell-session +$ vagrant docker-exec app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. + +Note that the "name" corresponds to the name of the VM, **not** the name of the +Docker container. Consider the following Vagrantfile: + +```ruby +Vagrant.configure(2) do |config| + config.vm.provider "docker" do |d| + d.image = "consul" + end +end +``` + +This Vagrantfile will start the official Docker Consul image. However, the +associated Vagrant command to `docker-exec` into this instance is: + +```shell-session +$ vagrant docker-exec -it -- /bin/sh +``` + +In particular, the command is actually: + +```shell-session +$ vagrant docker-exec default -it -- /bin/sh +``` + +Because "default" is the default name of the first defined VM. In a +multi-machine Vagrant setup as shown below, the "name" attribute corresponds +to the name of the VM, **not** the name of the container: + +```ruby +Vagrant.configure do |config| + config.vm.define "web" do + config.vm.provider "docker" do |d| + d.image = "nginx" + end + end + + config.vm.define "consul" do + config.vm.provider "docker" do |d| + d.image = "consul" + end + end +end +``` + +The following command is invalid: + +```shell-session +# Not valid +$ vagrant docker-exec -it nginx -- /bin/sh +``` + +This is because the "name" of the VM is "web", so the command is actually: + +```shell-session +$ vagrant docker-exec -it web -- /bin/sh +``` + +For this reason, it is recommended that you name the VM the same as the +container. In the above example, it is unambiguous that the command to enter +the Consul container is: + +```shell-session +$ vagrant docker-exec -it consul -- /bin/sh +``` + +### docker-logs + +`vagrant docker-logs` can be used to see the logs of a running container. +Because most Docker containers are single-process, this is used to see +the logs of that one process. Additionally, the logs can be tailed. + +### docker-run + +`vagrant docker-run` can be used to run one-off commands against +a Docker container. The one-off Docker container that is started shares +all the volumes, links, etc. of the original Docker container. An +example is shown below: + +```shell-session +$ vagrant docker-run app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. diff --git a/website/content/docs/cloud-init/index.mdx b/website/content/docs/cloud-init/index.mdx deleted file mode 100644 index 9bc1f8cc01e..00000000000 --- a/website/content/docs/cloud-init/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: docs -page_title: Cloud-Init -description: Introduction to using cloud-init with Vagrant ---- - -# Vagrant cloud-init - -For examples on how to achieve this, among other use cases, please refer to the [usage](/vagrant/docs/cloud-init/usage) -guide for more information! - -For more information about what options are available for configuring cloud-init, see the -[configuration section](/vagrant/docs/cloud-init/configuration). diff --git a/website/content/docs/concept/box-architecture.mdx b/website/content/docs/concept/box-architecture.mdx new file mode 100644 index 00000000000..ea6b8c3091a --- /dev/null +++ b/website/content/docs/concept/box-architecture.mdx @@ -0,0 +1,117 @@ +--- +layout: vagrant-cloud +page_title: Vagrant Box Architecture +description: "Vagrant box architecture and default architecture." +--- + +# Architecture for Vagrant boxes + +Providers for Vagrant boxes, in Vagrant version 2.4.0 and newer, can include +multiple architecture options. This allows you to have multiple instances +of one specific provider. The specific provider shares a common name for +artifacts of different architectures. + +For example, the `hashicorp/precise32` and `hashicorp/precise64` boxes each +include a provider for `virtualbox`. + +``` +hashicorp/precise32 + v1.0.0 + provider: virtualbox + +hashicorp/precise64 + v1.0.0 + provider: virtualbox +``` + +The addition of architecture now allows these to be combined into a single +box. Instead of having a `hashicorp/precise32` box for a 32-bit guest, and +a `hashicorp/precise64` box for a 64-bit guest, a single `hashicorp/precise` +box can provide both. + +``` +hashicorp/precise + v1.0.0 + provider: virtualbox, architecture: amd64 + provider: virtualbox, architecture: i386 +``` + +The Vagrant CLI will automatically match the provider architecture using the +detected local host architecture. If the Vagrant CLI cannot find a matching +architecture, it will attempt a +[special case match](/vagrant/vagrant-cloud/boxes/architecture#unknown-architecture). + +## Default architecture + +Vagrant Cloud allows you to optionally specify one architecture as the +"default architecture" for a provider. This enables the box owner to +control which architecture for the provider the Vagrant CLI uses +when architecture filtering is not available. By default, the first +provider in the configuration for a box version is the default architecture. + +Note, this functionality enables backwards compatiblity +with previous versions of the Vagrant CLI that do not support architecture +filtering when matching an appropriate provider. + +For example, the `2.0.0` version of the `hashicorp/precise` box is created and +a new `virtualbox` provider is created with `amd64` architecture. + +``` +hashicorp/precise + v2.0.0 + provider: virtualbox, architecture: amd64, default_architecture: true +``` + +Adding another `virtualbox` provider with `i386` architecture. + +``` +hashicorp/precise + v2.0.0 + provider: virtualbox, architecture: amd64, default_architecture: true + provider: virtualbox, architecture: i386, default_architecture: false +``` + +When the Vagrant CLI, prior to version 2.4.0, requests the `hashicorp/precise` +box with the `virtualbox` provider, it will receive the information from +the `virtualbox` provider with the `amd64` architecture because it is flagged +as being the default architecture. If, instead, the provider with `i386` +architecture should be returned, the `virtualbox` provider for the `i386` +architecture can be updated to be the default architecture. + +``` +hashicorp/precise + v2.0.0 + provider: virtualbox, architecture: amd64, default_architecture: false + provider: virtualbox, architecture: i386, default_architecture: true +``` + +Now the provider with the `i386` architecture will be returned. + +## Special cases + +There are two cases where Vagrant CLI versions with architecture support +will use the default architecture flag. + +### User requested + +If the user sets the [config.vm.box_architecture](/vagrant/docs/vagrantfile/machine_settings#config-vm-box_architecture) +option in their Vagrantfile to `nil`, the Vagrant CLI will use the +provider which has been flagged as the default architecture. + +### Unknown architecture + +The architecture value `unknown` combined with the default architecture +flag provides a special matching case for the Vagrant CLI. If the +[config.vm.box_architecture](/vagrant/docs/vagrantfile/machine_settings#config-vm-box_architecture) +option in the local Vagrantfile is configured with the default `:auto` +value, and no architecture matching the host platform can be found +for the desired provider, the Vagrant CLI will check for a matching +provider that is flagged as the default architecture and has an +architecture value of `unknown`. If that match is found, the Vagrant +CLI will use that provider. + +This special case matching was included so the Vagrant CLI would be +able to use boxes published to Vagrant Cloud prior to the introduction +of architecture metadata. All previously existing providers have a +default architecture value of `unknown` and are flagged as the default +architecture since they are the only provider to exist for a given name. diff --git a/website/content/docs/boxes/index.mdx b/website/content/docs/concept/box.mdx similarity index 69% rename from website/content/docs/boxes/index.mdx rename to website/content/docs/concept/box.mdx index 2da3f1f82a2..cdc133f50c9 100644 --- a/website/content/docs/boxes/index.mdx +++ b/website/content/docs/concept/box.mdx @@ -11,8 +11,11 @@ description: |- Boxes are the package format for Vagrant environments. You specify a box environment and operating configurations in your [Vagrantfile](/vagrant/docs/vagrantfile). You can use a box on any [supported platform](/vagrant/downloads) to bring up identical working environments. To enable teams to use and manage the same boxes, [versions are supported](/vagrant/docs/boxes/versioning). -~> **Note**: Boxes require a provider, a virtualization product, to operate. Before you can use a box, -ensure that you have properly installed a supported [provider](/vagrant/docs/providers). + + +Boxes require a provider, a virtualization product, to operate. Before you can use a box, ensure that you have properly installed a supported [provider](/vagrant/docs/providers). + + The quickest way to get started is to select a pre-defined box environment from the [publicly available catalog on Vagrant Cloud](https://vagrantcloud.com/boxes/search). @@ -23,26 +26,15 @@ command for more information. ## Discover boxes -To find boxes, explore the -[public Vagrant box catalog](https://vagrantcloud.com/boxes/search) -for a box that matches your use case. The catalog contains most major operating -systems as bases, as well as specialized boxes to get you started with common -configurations such as LAMP stacks, Ruby, and Python. +To find boxes, explore the [public Vagrant box catalog](https://vagrantcloud.com/boxes/search) for a box that matches your use case. The catalog contains most major operating systems as bases, as well as specialized boxes to get you started with common configurations such as LAMP stacks, Ruby, and Python. -The boxes on the public catalog work with many different -[providers](/vagrant/docs/providers/). The list of supported providers is located in the box descriptions. +The boxes on the public catalog work with many different [providers](/vagrant/docs/providers/). The list of supported providers is located in the box descriptions. ### Add a box -You can add a box from the public catalog at any time. The box's description includes instructions -on how to add it to an existing Vagrantfile or initiate it as a new environment on the command-line. +You can add a box from the public catalog at any time. The box's description includes instructions on how to add it to an existing Vagrantfile or initiate it as a new environment on the command-line. -A common misconception is -that a namespace like "ubuntu" represents the official space for Ubuntu boxes. -This is untrue. Namespaces on Vagrant Cloud behave very similarly to namespaces on -GitHub. Just as GitHub's support team is unable to assist with -issues in someone's repository, HashiCorp's support team is unable to assist -with third-party published boxes. +A common misconception is that a namespace like "ubuntu" represents the official space for Ubuntu boxes. This is untrue. Namespaces on Vagrant Cloud behave very similarly to namespaces on GitHub. Just as GitHub's support team is unable to assist with issues in someone's repository, HashiCorp's support team is unable to assist with third-party published boxes. ## Official boxes diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/concept/plugin.mdx similarity index 51% rename from website/content/docs/plugins/index.mdx rename to website/content/docs/concept/plugin.mdx index 072b18640a7..ed17d6e519b 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/concept/plugin.mdx @@ -10,17 +10,10 @@ description: |- # Plugins -Vagrant comes with many great features out of the box to get your environments up -and running. Sometimes, however, you want to change the way Vagrant does something -or add additional functionality to Vagrant. This can be done via Vagrant -_plugins_. +Vagrant comes with many great features out of the box to get your environments up and running. Sometimes, however, you want to change the way Vagrant does something or add additional functionality to Vagrant. This can be done via Vagrant _plugins_. -Plugins are powerful, first-class citizens that extend Vagrant using a -well-documented, stable API that can withstand major version upgrades. +Plugins are powerful, first-class citizens that extend Vagrant using a well-documented, stable API that can withstand major version upgrades. -In fact, most of the core of Vagrant is [implemented using plugins](https://github.com/hashicorp/vagrant/tree/main/plugins). -Since Vagrant [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) its own -plugin API, you can be confident that the interface is stable and well supported. +In fact, most of the core of Vagrant is [implemented using plugins](https://github.com/hashicorp/vagrant/tree/main/plugins). Since Vagrant [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) its own plugin API, you can be confident that the interface is stable and well supported. -Use the navigation on the left below the "Plugins" section to learn more -about how to use and build your own plugins. +Use the navigation on the left below the "Plugins" section to learn more about how to use and build your own plugins. diff --git a/website/content/docs/concept/provider.mdx b/website/content/docs/concept/provider.mdx new file mode 100644 index 00000000000..5eedca687b9 --- /dev/null +++ b/website/content/docs/concept/provider.mdx @@ -0,0 +1,30 @@ +--- +layout: docs +page_title: Providers +description: |- + While Vagrant ships out of the box with support for VirtualBox, Hyper-V, and + Docker. Vagrant has the ability to manage other types of machines as well. + This is done by using other providers with Vagrant. +--- + +# Providers + +While Vagrant ships out of the box with support for [VirtualBox](https://www.virtualbox.org), [Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/), and [Docker](https://www.docker.io), Vagrant has the ability to manage other types of machines as well. This is done by using other _providers_ with Vagrant. + +Alternate providers can offer different features that make more sense in your use case. For example, if you are using Vagrant for any real work, [VMware](https://www.vmware.com) providers are recommended since they're well supported and generally more stable and performant than VirtualBox. + +Before you can use another provider, you must install it. Installation of other providers is done via the Vagrant plugin system. + +Once the provider is installed, usage is straightforward and simple, as you would expect with Vagrant. Read into the relevant subsections found in the navigation to the left for more information. + +## Install a provider + +Providers are distributed as Vagrant plugins, and are therefore installed using [standard plugin installation steps](/vagrant/docs/plugins/usage). After installing a plugin which contains a provider, the provider should immediately be available. + +## Default Provider + +By default, VirtualBox is the default provider for Vagrant. VirtualBox is still the most accessible platform to use Vagrant: it is free, cross-platform, and has been supported by Vagrant for years. With VirtualBox as the default provider, it provides the lowest friction for new users to get started with Vagrant. + +However, you may find after using Vagrant for some time that you prefer to use another provider as your default. In fact, this is quite common. To make this experience better, Vagrant allows specifying the default provider to use by setting the `VAGRANT_DEFAULT_PROVIDER` environmental variable. + +Just set `VAGRANT_DEFAULT_PROVIDER` to the provider you wish to be the default. For example, if you use Vagrant with VMware Fusion, you can set the environmental variable to `vmware_desktop` and it will be your default. \ No newline at end of file diff --git a/website/content/docs/configure-vagrant/environment-variables.mdx b/website/content/docs/configure-vagrant/environment-variables.mdx new file mode 100644 index 00000000000..0df0014ef33 --- /dev/null +++ b/website/content/docs/configure-vagrant/environment-variables.mdx @@ -0,0 +1,141 @@ +--- +layout: docs +page_title: Environment variables +description: |- + Vagrant has a set of environment variables that can be used to + configure and control it in a global way. This page lists those environmental + variables. +--- + +# Environment variables + +Vagrant has a set of environment variables that can be used to configure and control it in a global way. This page lists those environment variables. + +- `CFLAGS` - If set, the contents of this environment variable will be appended to the value generated by the Vagrant launcher. + +- `CPPFLAGS` - If set, the contents of this environment variable will be appended to the value generated by the Vagrant launcher. + +- `CURL_CA_BUNDLE` - If set, this environment variable will be passed through to the Vagrant process. By default Vagrant will use the CA certificate included with the Vagrant installation. + +- `LDFLAGS` - If set, the contents of this environment variable will be appended to the value generated by the Vagrant launcher. + +- `SSL_CERT_FILE` - If set, this environment variable will be passed through to the Vagrant process. By default, Vagrant will use the CA certificate included with the Vagrant installation. + +- `VAGRANT_ALIAS_FILE` - Changes the file where Vagrant aliases are defined. By default, this is set to `~/.vagrant.d/aliases`. + +- `VAGRANT_ALLOW_PLUGIN_SOURCE_ERRORS` - If set, Vagrant will not error when a configured plugin source is unavailable. When installing a Vagrant plugin Vagrant will error and halt if a plugin source is inaccessible. In some cases it may be desirable to ignore inaccessible sources and continue with the plugin installation. Enabling this value will cause Vagrant to simply log the plugin source error and continue. + +- `VAGRANT_BOX_UPDATE_CHECK_DISABLE` - By default, Vagrant will query the metadata API server to see if a newer box version is available for download. This optional can be disabled on a per-Vagrantfile basis with `config.vm.box_check_update`, but it can also be disabled globally setting `VAGRANT_BOX_UPDATE_CHECK_DISABLE` to any non-empty value. This option will not affect global box functions like `vagrant box update`. + +- `VAGRANT_CHECKPOINT_DISABLE` - Vagrant does occasional network calls to check whether the version of Vagrant that is running locally is up to date. We understand that software making remote calls over the internet for any reason can be undesirable. To suppress these calls, set the environment variable `VAGRANT_CHECKPOINT_DISABLE` to any non-empty value. + + If you use other HashiCorp tools like Packer and would prefer to configure this setting only once, you can set `CHECKPOINT_DISABLE` instead. + +- `VAGRANT_CWD` - Changes the working directory of Vagrant. By default, Vagrant uses the current directory you are in. The working directory +is important because it is where Vagrant looks for the Vagrantfile. It also defines how relative paths in the Vagrantfile are expanded, since they're expanded relative to where the Vagrantfile is found. + + This environment variable is most commonly set when running Vagrant from a scripting environment in order to set the directory that Vagrant sees. + +- `VAGRANT_DEBUG_LAUNCHER` - For performance reasons, especially for Windows users, Vagrant uses a static binary to launch the actual Vagrant process. If you have _very_ early issues when launching Vagrant from the official installer, you can specify the `VAGRANT_DEBUG_LAUNCHER` environment variable to output debugging information about the launch process. + +- `VAGRANT_DEFAULT_PROVIDER` - Configures the default provider Vagrant will use. + + You normally do not need to set this since Vagrant should automatically detect the default provider. By setting this, you will force Vagrant to use this provider for any _new_ Vagrant environments. Existing Vagrant environments will continue to use the provider they came `up` with. Once you `vagrant destroy` existing environments, this will take effect. + +- `VAGRANT_DEFAULT_TEMPLATE` - Configures the template used by `vagrant init` when the `--template` option is not provided. + +- `VAGRANT_DETECTED_ARCH` - This environment variable may be set by the Vagrant launcher to help determine the current runtime architecture in use. In general, Vagrant will set this value when running on a Windows host using a cygwin or msys based shell. The value the Vagrant launcher may set in this environment variable will not always match the actual architecture of the platform itself. Instead, it signifies the detected architecture of the environment it is running within. If this value is set, the Vagrant launcher will not modify it. + +- `VAGRANT_DETECTED_OS` - This environment variable may be set by the Vagrant launcher to help determine the current runtime platform. In general Vagrant will set this value when running on a Windows host using a cygwin or msys based shell. If this value is set, the Vagrant launcher will not modify it. + +- `VAGRANT_DISABLE_RESOLV_REPLACE` - Vagrant can optionally use the Ruby Resolv library in place of the libc resolver. +This can be disabled setting this environment variable. + +- `VAGRANT_DISABLE_VBOXSYMLINKCREATE` - If set, this will completely disable the ability to create symlinks with all VirtualBox shared folders. If this environment variable is not set, the VirtualBox synced folders option `SharedFoldersEnableSymlinksCreate` will be enabled by default. This option can be overridden on a per-folder basis within your Vagrantfile config by setting the `SharedFoldersEnableSymlinksCreate` option to true if you do not wish to completely disable this feature for all VirtualBox guests. + + Refer to the [VirtualBox synced folders docs page](/vagrant/docs/synced-folders/virtualbox#sharedfoldersenablesymlinkscreate) for more information. + +- `VAGRANT_DISABLE_SMBMFSYMLINKS` - If set, this will disable the `mfsymlinks` option for mounting SMB filesystems. If not set, then the `mfsymlinks` option will be enabled by default. This option can be overriden on a pre-folder basis with your Vagrantfile by setting `mount_options: ['mfsymlinks']`. + +- `VAGRANT_DOTFILE_PATH` - Change the directory where Vagrant stores VM-specific state, such as the VirtualBox VM UUID. By default, this is set to `.vagrant`. For example, if you keep your Vagrantfile in a Dropbox folder in order to share the folder between your desktop and laptop, Vagrant will overwrite the files in this directory with the details of the VM on the most recently-used host. To avoid this, you could set `VAGRANT_DOTFILE_PATH` to `.vagrant-laptop` and `.vagrant-desktop` on the respective machines. (Remember to update your `.gitignore`!) + +- `VAGRANT_ENABLE_RESOLV_REPLACE` - Use the Ruby Resolv library in place of the libc resolver. + +- `VAGRANT_FORCE_COLOR` - If set, Vagrant will force colored output, even if it detected that there is no TTY or the current environment does not +support it. + + You can achieve the same behavior by using the `--color` flag. This environment variable is useful for setting this flag globally. + +- `VAGRANT_HOME` - Changes the directory where Vagrant stores global state. By default, this is set to `~/.vagrant.d`. The Vagrant home directory is where things such as boxes are stored, so it can actually become quite large on disk. + +- `VAGRANT_IGNORE_WINRM_PLUGIN` - Vagrant will not display warning when `vagrant-winrm` plugin is installed. + +- `VAGRANT_INSTALL_LOCAL_PLUGINS` - If set, Vagrant will not prompt for confirmation prior to installing local plugins which have been defined within the local Vagrantfile. + +- `VAGRANT_IS_HYPERV_ADMIN` - Disable Vagrant's check for Hyper-V admin privileges and allow Vagrant to assume the current user has full access to Hyper-V. This is useful if the internal privilege check incorrectly determines the current user does not have access to Hyper-V. + +- `VAGRANT_LOCAL_PLUGINS_LOAD` - If set, Vagrant will not stub the Vagrantfile when running `vagrant plugin` commands. When this environment variable is set the `--local` flag will not be required by `vagrant plugin` commands to enable local project plugins. + +- `VAGRANT_LOG` - Specifies the verbosity of log messages from Vagrant. By default, Vagrant does not actively show any log messages. Log messages are very useful when troubleshooting issues, reporting bugs, or getting support. At the most verbose level, Vagrant outputs basically everything it is doing. + + Available log levels are `debug`, `info`, `warn`, and `error`. + + - The `warn` and `error` levels are practically useless since there are very few cases of these, and Vagrant generally reports them within the normal output. + + - The `info` level is a good level to start with if you are having problems, because while it is much louder than normal output, it is still very human-readable and can help identify certain issues. + + - The `debug` level is _extremely_ verbose and can be difficult to read without some knowledge of Vagrant internals. However, it is the best output to attach to a support request or bug report. + +- `VAGRANT_MAX_REBOOT_RETRY_DURATION` - By default, Vagrant will wait up to 120 seconds for a machine to reboot. However, if you find your OS is taking longer than 120 seconds to reboot successfully, you can configure this environment variable and Vagrant will wait for the configured number of seconds. + +- `VAGRANT_NO_COLOR` - If set, Vagrant will not use any colorized output. This is useful if you are logging the output to a file or on a system that does not support colors. + + The equivalent behavior can be achieved by using the `--no-color` flag on a command-by-command basis. This environment variable is useful for setting this flag globally. + +- `VAGRANT_NO_PARALLEL` - If set, Vagrant will not perform any parallel operations (such as parallel box provisioning). All operations will be performed in serial. + +- `VAGRANT_NO_PLUGINS` - If set, Vagrant will not load any 3rd party plugins. This is useful if you install a plugin and it is introducing instability to Vagrant, or if you want a specific Vagrant environment to not load plugins. + + Note that any `vagrant plugin` commands automatically do not load any plugins, so if you do install any unstable plugins, you can always use the `vagrant plugin` commands without having to worry. + +- `VAGRANT_POWERSHELL_VERSION_DETECTION_TIMEOUT` - Vagrant uses a default timeout when checking for the installed version of PowerShell. Occasionally the default can be too low and Vagrant will report being unable to detect the installed version of PowerShell. You can use this environment variable to extend the timeout used during PowerShell version detection. + +- `VAGRANT_PREFERRED_POWERSHELL` - Configures the preferred PowerShell executable. By default, when executing PowerShell commands, Vagrant prefers to use `pwsh.exe` over `powershell.exe`. You can modify this preference to make Vagrant prefer `powershell.exe`. The current supported values are `powershell` and `pwsh`. + +- `VAGRANT_PREFERRED_PROVIDERS` - Configures providers that Vagrant should prefer. + + Much like the `VAGRANT_DEFAULT_PROVIDER`, this environment variable normally does not need to be set. By setting this you will instruct Vagrant to _prefer_ providers defined in this environment variable for any _new_ Vagrant environments. Existing Vagrant environments will continue to use the provider they came `up` with. Once you `vagrant destroy` existing environments, this will take effect. A single provider can be defined within this environment variable or a comma delimited list of providers. + +- `VAGRANT_PREFER_SYSTEM_BIN` - If set, Vagrant will prefer using utility executables (like `ssh` and `rsync`) from the local system instead of those vendored within the Vagrant installation. + + Vagrant will default to using a system provided `ssh` on Windows. This environment variable can also be used to disable that behavior to force Vagrant to use the embedded `ssh` executable by setting it to `0`. + +- `VAGRANT_SUPPRESS_GO_EXPERIMENTAL_WARNING` - If set, `vagrant-go` will not output a warning message about compatibility with `vagrant-ruby`. This does not effect the stable Ruby release of Vagrant. + +- `VAGRANT_DISABLE_WINCURL` - If set, Vagrant will use the mingw build of curl which uses the installer provided ca-certificates bundle instead of the native Windows curl executable. + +- `VAGRANT_SERVER_URL` - Configures the remote server which Vagrant will connect to for fetching Vagrant boxes. By default, this is configured for Vagrant Cloud (https://vagrantcloud.com) + +- `VAGRANT_SERVER_ACCESS_TOKEN_BY_URL` If set, Vagrant will change the way it authenticates with the configured Vagrant server. When set, the authentication behavior will be reverted to the deprecated authentication behavior of: + + 1. not adding an authentication header to the request + 2. setting the configured access token as a query parameter on URLs + + This behavior can be useful for third party servers which do not accept the authentication header currently used with Vagrant Cloud. + +- `VAGRANT_SKIP_SUBPROCESS_JAILBREAK` - As of Vagrant 1.7.3, Vagrant tries to intelligently detect if it is running in the installer or running via Bundler. Although not officially supported, Vagrant tries its best to work when executed via Bundler. When Vagrant detects that you have spawned a subprocess that lives outside of Vagrant's installer, Vagrant will do its best to reset the preserved environment during the subprocess execution. + + If Vagrant detects it is running outside of the officially installer, the original environment will always be restored. You can disable this automatic jailbreak by setting `VAGRANT_SKIP_SUBPROCESS_JAILBREAK`. + +- `VAGRANT_USER_AGENT_PROVISIONAL_STRING` - Vagrant will append the contents of this variable to the default user agent header. + +- `VAGRANT_USE_VAGRANT_TRIGGERS` - Vagrant will not display the warning about disabling the core trigger feature if +the community plugin is installed. + +- `VAGRANT_VAGRANTFILE` - Specifies the filename of the Vagrantfile that Vagrant searches for. By default, this is "Vagrantfile". Note that this is _not_ a file path, but just a filename. + + This environment variable is commonly used in scripting environments + where a single folder may contain multiple Vagrantfiles representing + different configurations. + +- `VAGRANT_WINPTY_DISABLE` - If set, Vagrant will _not_ wrap interactive processes with winpty where required. diff --git a/website/content/docs/experimental/index.mdx b/website/content/docs/configure-vagrant/experimental-features.mdx similarity index 100% rename from website/content/docs/experimental/index.mdx rename to website/content/docs/configure-vagrant/experimental-features.mdx diff --git a/website/content/docs/configure-vagrant/feature-flag.mdx b/website/content/docs/configure-vagrant/feature-flag.mdx new file mode 100644 index 00000000000..4dc9be917e4 --- /dev/null +++ b/website/content/docs/configure-vagrant/feature-flag.mdx @@ -0,0 +1,42 @@ +--- +layout: docs +page_title: Vagrant Experimental Feature Flag +description: Introduction to Vagrants Experimental Feature Flag +--- + +# Experimental Feature Flag + +Some features that aren't ready for release can be enabled through this feature +flag. There are a couple of different ways of going about enabling these features. +It is also worth noting that Vagrant will not validate the existence of a feature +flag. + +For example if you are on Linux or Mac, and you wish to enable every single experimental feature, you can set the flag +to "on" by setting it to `1`: + +```shell +export VAGRANT_EXPERIMENTAL="1" +``` + +You can also enable some or many features if there are specific ones you would like, +but don't want every single feature enabled: + +```shell +# Only enables feature_one +export VAGRANT_EXPERIMENTAL="feature_one" +``` + +```shell +# Enables both feature_one and feature_two +export VAGRANT_EXPERIMENTAL="feature_one,feature_two" +``` + +## Valid experimental features + +~> **Advanced topic!** This is an advanced topic for use only if +you want to use new Vagrant features. If you are just getting +started with Vagrant, you may safely skip this section. + +This is a list of all the valid experimental features that Vagrant recognizes: + +* `none_communicator` - Allows Vagrant to manage remote machines without the ability to connect to them for configuration/provisioning. diff --git a/website/content/docs/configure-vagrant/index.mdx b/website/content/docs/configure-vagrant/index.mdx new file mode 100644 index 00000000000..00df731594d --- /dev/null +++ b/website/content/docs/configure-vagrant/index.mdx @@ -0,0 +1,9 @@ +--- +layout: docs +page_title: Configure Vagrant +description: Placeholder +--- + +# Configure Vagrant + +PLACEHOLDER \ No newline at end of file diff --git a/website/content/docs/create-box/format.mdx b/website/content/docs/create-box/format.mdx new file mode 100644 index 00000000000..e17a21b8deb --- /dev/null +++ b/website/content/docs/create-box/format.mdx @@ -0,0 +1,47 @@ +--- +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]() (`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: + +1. 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. + +1. metadata.json (required) - Contains a map with information about the box. Most importantly the target provider. + +1. 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). + +1. 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, refer to 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. Values currently used by Vagrant core: + +- `provider` - (string) Provider for the box +- `architecture` - (string) Architecture of the box diff --git a/website/content/docs/create-box/index.mdx b/website/content/docs/create-box/index.mdx new file mode 100644 index 00000000000..92297a8b5d2 --- /dev/null +++ b/website/content/docs/create-box/index.mdx @@ -0,0 +1,212 @@ +--- +layout: docs +page_title: Create a Base Box +description: |- + There are a special category of boxes known as "base boxes." These boxes + contain the bare minimum required for Vagrant to function, are generally + not made by repackaging an existing Vagrant environment (hence the "base" + in the "base box"). +--- + +# Create a base box + +There are a special category of boxes known as "base boxes." These boxes contain the bare minimum required for Vagrant to function, are generally not made by repackaging an existing Vagrant environment (hence the "base" in the "base box"). + +For example, the Ubuntu boxes provided by the Vagrant project (such as "bionic64") are base boxes. They were created from a minimal Ubuntu install from an ISO, rather than repackaging an existing environment. + +Base boxes are extremely useful for having a clean slate starting point from which to build future development environments. The Vagrant project hopes in the future to be able to provide base boxes for many more operating systems. Until then, this page documents how you can create your own base box. + + + +Creating a base box can be a time consuming and tedious process, and is not recommended for new Vagrant users. If you are just getting started with Vagrant, we recommend trying to find existing base boxes to use first. + + + +## What's in a base box? + +A base box typically consists of only a bare minimum set of software for Vagrant to function. As an example, a Linux box may contain only the following: + +- Package manager +- SSH +- SSH user so Vagrant can connect +- Perhaps Chef, Puppet, etc. but not strictly required. + +In addition to this, each [provider](/vagrant/docs/providers/) may require additional software. For example, if you are making a base box for VirtualBox, you will want to include the VirtualBox guest additions so that shared folders work properly. But if you are making an AWS base box, this is not required. + +## Creating a base box + +Creating a base box is actually provider-specific. This means that depending on if you are using VirtualBox, VMware, AWS, etc. the process for creating a base box is different. Because of this, this one document cannot be a full guide to creating a base box. + +This page will document some general guidelines for creating base boxes, however, and will link to provider-specific guides for creating base boxes. + +Provider-specific guides for creating base boxes are linked below: + +- [Docker Base Boxes](/vagrant/docs/providers/docker/boxes) +- [Hyper-V Base Boxes](/vagrant/docs/providers/hyperv/boxes) +- [VMware Base Boxes](/vagrant/docs/providers/vmware/boxes) +- [VirtualBox Base Boxes](/vagrant/docs/providers/virtualbox/boxes) + +### Packer and HCP Vagrant + +We strongly recommend using [Packer](https://www.packer.io/) to create reproducible builds for your base boxes, as well as automating the builds. Read more about [automating Vagrant box creation with Packer](/packer/guides/packer-on-cicd/build-image-in-cicd) in the Packer documentation. + +### Disk space + +When creating a base box, make sure the user will have enough disk space to do interesting things, without being annoying. For example, in VirtualBox, you should create a dynamically resizing drive with a large maximum size. This causes the actual footprint of the drive to be small initially, but to dynamically grow towards the max size as disk space is needed, providing the most flexibility for the end user. + +If you are creating an AWS base box, do not force the AMI to allocate terabytes of EBS storage, for example, since the user can do that on their own. But you should default to mounting ephemeral drives, because they're free and provide a lot of disk space. + +### Memory + +Like disk space, finding the right balance of the default amount of memory is important. For most providers, the user can modify the memory with the Vagrantfile, so do not use too much by default. It would be a poor user experience (and mildly shocking) if a `vagrant up` from a base box instantly required many gigabytes of RAM. Instead, choose a value such as 512MB, which is usually enough to play around and do interesting things with a Vagrant machine, but can easily be increased when needed. + +### Peripherals (Audio, USB, etc.) + +Disable any non-necessary hardware in a base box such as audio and USB controllers. These are generally unnecessary for Vagrant usage and, again, can be easily added via the Vagrantfile in most cases. + +## Default user settings + +Just about every aspect of Vagrant can be modified. However, Vagrant does expect some defaults which will cause your base box to "just work" out of the box. You should create these as defaults if you intend to publicly distribute your box. + +If you are creating a base box for private use, you should try _not_ to follow these, as they open up your base box to security risks (known users, passwords, private keys, etc.). + +### "vagrant" user + +By default, Vagrant expects a "vagrant" user to SSH into the machine as. This user should be setup with the [insecure keypairs](https://github.com/hashicorp/vagrant/tree/main/keys) that Vagrant uses as a default to attempt to SSH. It should belong to a group named "vagrant". Also, even though Vagrant uses key-based authentication by default, it is a general convention to set the password for the "vagrant" user to "vagrant". This lets people login as that user manually if they need to. + +To configure SSH access with the insecure keypair, place the [public keys](https://github.com/hashicorp/vagrant/tree/main/keys/vagrant.pub) into the `~/.ssh/authorized_keys` file for the "vagrant" user. Note that OpenSSH is very picky about file permissions. Therefore, make sure that `~/.ssh` has `0700` permissions and the authorized keys file has `0600` permissions. + +When Vagrant boots a box and detects the insecure keypair, it will automatically replace it with a randomly generated keypair for additional security while the box is running. + +### Root Password: "vagrant" + +Vagrant does not actually use or expect any root password. However, having a generally well known root password makes it easier for the general public to modify the machine if needed. + +Publicly available base boxes usually use a root password of "vagrant" to keep things easy. + +### Password-less sudo + +This is **important!**. Many aspects of Vagrant expect the default SSH user to have passwordless sudo configured. This lets Vagrant configure networks, mount synced folders, install software, and more. + +To begin, some minimal installations of operating systems do not even include `sudo` by default. Verify that you install `sudo` in some way. + +After installing sudo, configure it (usually using `visudo`) to allow passwordless sudo for the "vagrant" user. This can be done with the following line at the end of the configuration file: + +``` +vagrant ALL=(ALL) NOPASSWD: ALL +``` + +Additionally, Vagrant does not use a pty or tty by default when connected via SSH. You will need to make sure there is no line that has `requiretty` in it. Remove that if it exists. This allows sudo to work properly without a tty. Note that you _can_ configure Vagrant to request a pty, which lets you keep this configuration. But Vagrant by default does not do this. + +### SSH tweaks + +In order to keep SSH speedy even when your machine or the Vagrant machine is not connected to the internet, set the `UseDNS` configuration to `no` in the SSH server configuration. + +This avoids a reverse DNS lookup on the connecting SSH client which can take many seconds. + +## Windows boxes + +Supported Windows guest operating systems: + +- Windows 7 +- Windows 8 +- Windows Server 2008 +- Windows Server 2008 R2 +- Windows Server 2012 +- Windows Server 2012 R2 + +Windows Server 2003 and Windows XP are _not_ supported, but if you are a die hard XP fan [this](https://stackoverflow.com/a/18593425/18475) may help you. + +### Base Windows configuration + +- Turn off UAC +- Disable complex passwords +- Disable "Shutdown Tracker" +- Disable "Server Manager" starting at login (for non-Core) + +In addition to disabling UAC in the control panel, you also must disable UAC in the registry. This may vary from Windows version to Windows version, but Windows 8/8.1 use the command below. This will allow some things like automated Puppet installs to work within Vagrant Windows base boxes. + +``` +reg add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /d 0 /t REG_DWORD /f /reg:64 +``` + +### Base WinRM configuration + +To enable and configure WinRM you will need to set the WinRM service to auto-start and allow unencrypted basic auth (obviously this is not secure). Run the following commands from a regular Windows command prompt: + +``` +winrm quickconfig -q +winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"} +winrm set winrm/config @{MaxTimeoutms="1800000"} +winrm set winrm/config/service @{AllowUnencrypted="true"} +winrm set winrm/config/service/auth @{Basic="true"} +sc config WinRM start= auto +``` + +### Additional WinRM 1.1 configuration + +These additional configuration steps are specific to Windows Server 2008 (WinRM 1.1). For Windows Server 2008 R2, Windows 7 and later versions of Windows you can ignore this section. + +1. Ensure the Windows PowerShell feature is installed +2. Change the WinRM port to 5985 or upgrade to WinRM 2.0 + +The following commands will change the WinRM 1.1 port to what's expected by Vagrant: + +``` +netsh firewall add portopening TCP 5985 "Port 5985" +winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"} +``` + +### Optional WinSSH configuration + +When using the WinSSH communicator, you may run into an issue where a PowerShell command can't display a progress bar. A typical error message might look like: + +``` +Win32 internal error "Access is denied" 0x5 occurred while reading the console output buffer. +``` + +In order to prevent this, we recommend setting `$ProgressPreference = "SilentlyContinue"` in your box's PowerShell profile: + +``` +if (!(Test-Path -Path $PROFILE)) { + New-Item -ItemType File -Path $PROFILE -Force +} + +Add-Content $PROFILE '$ProgressPreference = "SilentlyContinue"' +``` + +## Other software + +At this point, you have all the common software you absolutely _need_ for your base box to work with Vagrant. However, there is some additional software you can install if you wish. + +While we plan on it in the future, Vagrant still does not install Chef or Puppet automatically when using those provisioners. Users can use a shell provisioner to do this, but if you want Chef/Puppet to just work out of the box, you will have to install them in the base box. + +Installing this is outside the scope of this page, but should be fairly straightforward. + +In addition to this, feel free to install and configure any other software you want available by default for this base box. + +## Package the box + +Packaging the box into a `box` file is provider-specific. Please refer to the provider-specific documentation for creating a base box. Some +provider-specific guides are linked to towards the top of this page. + +## Distribute the box + +You can distribute the box file however you would like. However, if you want to support versioning, putting multiple providers at a single URL, pushing updates, analytics, and more, we recommend you add the box to [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud). + +You can upload both public and private boxes to this service. + +## Test the box + +To test the box, pretend you are a new user of Vagrant and give it a shot: + +```shell-session +$ vagrant box add --name my-box /path/to/the/new.box +... +$ vagrant init my-box +... +$ vagrant up +... +``` + +If you made a box for some other provider, be sure to specify the `--provider` option to `vagrant up`. If the up succeeded, then your box worked! \ No newline at end of file diff --git a/website/content/docs/create-box/info.mdx b/website/content/docs/create-box/info.mdx new file mode 100644 index 00000000000..a1849cf4ab0 --- /dev/null +++ b/website/content/docs/create-box/info.mdx @@ -0,0 +1,33 @@ +--- +layout: docs +page_title: Box Info Format +description: |- + A box can provide additional information to the user by supplying an info.json + file within the box. +--- + +# Additional box information + +When creating a Vagrant box, you can supply additional information that might be relevant to the user when running `vagrant box list -i`. For example, you could package your box to include information about the author of the box and a website for users to learn more: + +```shell-session +$ vagrant box list -i +hashicorp/bionic64 (virtualbox, 1.0.0) + - author: brian + - homepage: https://www.vagrantup.com +``` + +## Box info + +To accomplish this, you need to include a file named `info.json` when creating a [base box](/vagrant/docs/boxes/base) which is a JSON document containing any and all relevant information that will be displayed to the user when the `-i` option is used with `vagrant box list`. + +```json +{ + "author": "brian", + "homepage": "https://example.com" +} +``` + +There are no special keys or values in `info.json`, and Vagrant will print each key and value on its own line. + +The [Box File Format](/vagrant/docs/boxes/format) provides more information about what else goes into a Vagrant box. diff --git a/website/content/docs/providers/docker/boxes.mdx b/website/content/docs/create-box/provider/docker.mdx similarity index 100% rename from website/content/docs/providers/docker/boxes.mdx rename to website/content/docs/create-box/provider/docker.mdx diff --git a/website/content/docs/providers/hyperv/boxes.mdx b/website/content/docs/create-box/provider/hyperv.mdx similarity index 99% rename from website/content/docs/providers/hyperv/boxes.mdx rename to website/content/docs/create-box/provider/hyperv.mdx index e0093aaa439..dae528ab9b8 100644 --- a/website/content/docs/providers/hyperv/boxes.mdx +++ b/website/content/docs/create-box/provider/hyperv.mdx @@ -6,7 +6,7 @@ description: |- format that affects how base boxes are made. --- -# Creating a Base Box +# Create a base box As with [every Vagrant provider](/vagrant/docs/providers/basic_usage), the Vagrant Hyper-V provider has a custom box format that affects how base boxes are made. diff --git a/website/content/docs/providers/virtualbox/boxes.mdx b/website/content/docs/create-box/provider/virtualbox.mdx similarity index 99% rename from website/content/docs/providers/virtualbox/boxes.mdx rename to website/content/docs/create-box/provider/virtualbox.mdx index aebf56a3ebe..5bb70dbbc1b 100644 --- a/website/content/docs/providers/virtualbox/boxes.mdx +++ b/website/content/docs/create-box/provider/virtualbox.mdx @@ -6,7 +6,7 @@ description: |- box format that affects how base boxes are made. --- -# Creating a Base Box +# Create a base box As with [every Vagrant provider](/vagrant/docs/providers/basic_usage), the Vagrant VirtualBox provider has a custom box format that affects how base diff --git a/website/content/docs/providers/vmware/boxes.mdx b/website/content/docs/create-box/provider/vmware.mdx similarity index 100% rename from website/content/docs/providers/vmware/boxes.mdx rename to website/content/docs/create-box/provider/vmware.mdx diff --git a/website/content/docs/create-box/repository.mdx b/website/content/docs/create-box/repository.mdx new file mode 100644 index 00000000000..dfe59b1b66c --- /dev/null +++ b/website/content/docs/create-box/repository.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: Box Repository +description: |- + Vagrant can download boxes from a Box Repository. [Vagrantcloud](https://vagrantcloud.com/) + is the HashiCorp maintained Box Repository. +--- + +# Box Repository + +A Vagrant Box Repository provides Vagrant with some boxes and information +on how to get the boxes. This can exist on a local filesystem or a service +like Vagrantcloud. + +There are two components that make up a Box Repository: + +1. Vagrant Boxes - These are Vagrant `.box` files. Refer to the [box documentation](/vagrant/docs/boxes) for more information on Vagrant boxes. + +1. Box Catalog Metadata - This is a JSON document (typically exchanged during interactions with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud)) that specifies the name of the box, a description, available versions, available providers, and URLs to the actual box files (next component) for each provider and version. If this catalog metadata does not exist, a box file can still be added directly, but it will not support versioning and updating. + +## Box catalog metadata + +The metadata is an optional component for a box (but highly recommended) that enables [versioning](/vagrant//docs/boxes/versioning), updating, multiple providers from a single file, and more. + + + +If you have an account with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud), you can create boxes there, and HashiCorp's Vagrant Cloud automatically creates the metadata for you. The format is still documented here. + + + +It is a JSON document, structured in the following way: + +```json +{ + "name": "hashicorp/bionic64", + "description": "This box contains Ubuntu 18.04 LTS 64-bit.", + "versions": [ + { + "version": "0.1.0", + "providers": [ + { + "name": "virtualbox", + "url": "http://example.com/bionic64_010_virtualbox.box", + "checksum_type": "sha1", + "checksum": "foo", + "architecture": "amd64", + "default_architecture": true + } + ] + } + ] +} +``` + +As you can see, the JSON document can describe multiple versions of a box, multiple providers, and can add/remove providers/architectures in different versions. + +This JSON file can be passed directly to `vagrant box add` from the local filesystem using a file path or via a URL, and Vagrant will install the proper version of the box. In this case, the value for the `url` key in the JSON can also be a file path. If multiple providers are available, Vagrant will ask what provider you want to use. diff --git a/website/content/docs/create-box/versioning.mdx b/website/content/docs/create-box/versioning.mdx new file mode 100644 index 00000000000..00785ee66bd --- /dev/null +++ b/website/content/docs/create-box/versioning.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: Box Versioning +description: |- + Since Vagrant 1.5, boxes support versioning. This allows the people who + make boxes to push updates to the box, and the people who use the box + have a simple workflow for checking for updates, updating their boxes, + and seeing what has changed. +--- + +# Box versioning + +Since Vagrant 1.5, boxes support versioning. This allows the people who make boxes to push updates to the box, and the people who use the box have a simple workflow for checking for updates, updating their boxes, and seeing what has changed. + +If you are just getting started with Vagrant, box versioning is not too important, and we recommend learning about some other topics first. But if you are using Vagrant on a team or plan on creating your own boxes, versioning is very important. Luckily, having versioning built right in to Vagrant makes it easy to use and fit nicely into the Vagrant workflow. + +This page will cover how to use versioned boxes. It does _not_ cover how to update your own custom boxes with versions. That is covered in [creating a base box](/vagrant/docs/boxes/base). + +## View and update versions + +`vagrant box list` only shows _installed_ versions of boxes. If you want to see all available versions of a box, you will have to find the box on [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud). An easy way to find a box is to use the url `https://vagrantcloud.com/$USER/$BOX`. For example, for the `hashicorp/bionic64` box, you can find information about it at `https://vagrantcloud.com/hashicorp/bionic64`. + +You can check if the box you are using is outdated with `vagrant box outdated`. This can check if the box in your current Vagrant environment is outdated as well as any other box installed on the system. + +Finally, you can update boxes with `vagrant box update`. This will download and install the new box. This _will not_ magically update running Vagrant environments. If a Vagrant environment is already running, you will have to destroy and recreate it to acquire the new updates in the box. The update command just downloads these updates locally. + +## Version constraints + +You can constrain a Vagrant environment to a specific version or versions of a box using the [Vagrantfile](/vagrant/docs/vagrantfile/) by specifying the `config.vm.box_version` option. + +If this option is not specified, the latest version is always used. This is equivalent to specifying a constraint of ">= 0". + +The box version configuration can be a specific version or a constraint of versions. Constraints can be any combination of the following: `= X`, `> X`, `< X`, `>= X`, `<= X`, `~> X`. You can combine multiple constraints by separating them with commas. All the constraints should be self explanatory except perhaps for `~>`, known as the "pessimistic constraint". Examples explain it best: `~> 1.0` is equivalent to `>= 1.0, < 2.0`. And `~> 1.1.5` is equivalent to `>= 1.1.5, < 1.2.0`. + +You can choose to handle versions however you see fit. However, many boxes in the public catalog follow [semantic versioning](http://semver.org/). Basically, only the first number (the "major version") breaks backwards compatibility. In terms of Vagrant boxes, this means that any software that runs in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on, but "2.0" might introduce big changes that break your software. By following this convention, the best constraint is `~> 1.0` because you know it is safe no matter what version is in that range. + +Please note that, while the semantic versioning specification allows for more than three points and pre-release or beta versions, Vagrant boxes must be of the format `X.Y.Z` where `X`, `Y`, and `Z` are all positive integers. + +## Automatically check for updates + +Using the [Vagrantfile](/vagrant/docs/vagrantfile/), you can also configure Vagrant to automatically check for updates during any `vagrant up`. This is enabled by default, but can easily be disabled with `config.vm.box_check_update = false` in your Vagrantfile. + +When this is enabled, Vagrant will check for updates on every `vagrant up`, not just when the machine is being created from scratch, but also when it is resuming, starting after being halted, etc. + +If an update is found, Vagrant will output a warning to the user letting them know an update is available. That user can choose to ignore the warning for now, or can update the box by running `vagrant box update`. + +Vagrant can not and does not automatically download the updated box and update the machine because boxes can be relatively large and updating the machine requires destroying it and recreating it, which can cause important data to be lost. Therefore, this process is manual to the extent that the user has to manually enter a command to do it. + +## Prune old versions + +Vagrant does not automatically prune old versions because it does not know if they might be in use by other Vagrant environments. Because boxes can be large, you may want to actively prune them once in a while using `vagrant box remove`. You can see all the boxes that are installed using `vagrant box list`. + +Another option is to use `vagrant box prune` command to remove all installed boxes that are outdated and not currently in use. diff --git a/website/content/docs/cloud-init/usage.mdx b/website/content/docs/define/cloud-init.mdx similarity index 55% rename from website/content/docs/cloud-init/usage.mdx rename to website/content/docs/define/cloud-init.mdx index e120febf1dc..cca69ba605e 100644 --- a/website/content/docs/cloud-init/usage.mdx +++ b/website/content/docs/define/cloud-init.mdx @@ -1,20 +1,24 @@ --- layout: docs -page_title: Vagrant Cloud-Init Usage -description: Various Vagrant Cloud-Init examples +page_title: Cloud-Init +description: Introduction to using cloud-init with Vagrant --- +# Cloud-Init + +Cloud-Init is a tool for managing the configuration of virtual machines. You can use `cloud-init` to configure the virtual machines during the boot process. + +For more information about what options are available for configuring cloud-init, see the [configuration section](/vagrant/docs/cloud-init/configuration). + # Basic Usage Below are some very simple examples of how to use Vagrant Cloud-Init with the VirtualBox provider. -For more detailed information about these config values and how to use cloud-init, -please read the [official documentation for cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html). +For more detailed information about these config values and how to use cloud-init, please read the [official documentation for cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html). ## Basic Examples -A cloud_init config can be defined as a "hash" of key values, or as a block. Below -are two examples of this for defining a cloud_init config: +You can define the `cloud_init` config as a "hash" of key values or as a block. Below are two examples of this for defining a cloud_init config: ```ruby # Simplified form @@ -31,9 +35,7 @@ config.vm.cloud_init do |cloud_init| end ``` -The first part will be read from a local file `./foo/bar`, and the second part -will be attached using the inline content. Both "block" and "hash" forms are supported, -and should work interchangeably. +The first part will be read from a local file `./foo/bar`, and the second part will be attached using the inline content. Both "block" and "hash" forms are supported, and should work interchangeably. Individual machines may have their own cloud-init data: diff --git a/website/content/docs/define/disks/hyperv.mdx b/website/content/docs/define/disks/hyperv.mdx new file mode 100644 index 00000000000..c823d7da012 --- /dev/null +++ b/website/content/docs/define/disks/hyperv.mdx @@ -0,0 +1,65 @@ +--- +layout: docs +page_title: Disks for Hyper-V Provider +description: |- + Vagrant comes with support out of the box for Hyper-V, a free, + cross-platform consumer virtualization product. +--- + +# Hyper-V + +Because of how Hyper-V handles disk management, a Vagrant guest _must_ be powered 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. + +# Usage + +For more information on how to use Hyper-V to configure disks for a guest, refer to the [Disks examples](/vagrant/docs/define/disks#examples) and [configuration](/vagrant/docs/vagrantfile/vm/disk) guide for more information. + +## `provider_config` options + +Most options are used for either creating or attaching a hard disk to your guest. Vagrant supports most options for these operations. You should be able to define the PowerShell specific argument to a given Hyper-V command in the `provider_config` hash, and Vagrant should properly pass it along to the command. + +### New-VHD supported options + +For more information about each option, visit the [New-VHD Hyper-V documentation](https://docs.microsoft.com/en-us/powershell/module/hyper-v/new-vhd?view=win10-ps). + + + +By default, all Hyper-V disks are defined as a dynamic virtual hard disk. If you wish to make the disk a fixed size, set the `Fixed` option when creating a new disk. + + + +- `BlockSizeBytes` (string) - Optional argument, i.e. `"128MB"` +- `Differencing` (bool) - If set, the disk will be used to store differencing changes from parent disk (must set `ParentPath`) +- `Fixed` (bool) - If set, the disk will be a fixed size, not dynamically allocated. +- `LogicalSectorSizeBytes` (int) - Optional argument, must be either `512` or `4096` +- `ParentPath` (string) - The parent disk path used if a `Differencing` disk is defined +- `PhysicalSectorSizeBytes` (string) - Optional argument, must be either `512` or `4096` +- `SourceDisk` (int) - Existing disk to use as a source for the new disk + +### Add-VMHardDiskDrive supported options + +For more information about each option, visit the [Add-VMHardDiskDrive Hyper-V documentation](https://docs.microsoft.com/en-us/powershell/module/hyper-v/add-vmharddiskdrive?view=win10-ps). + +Most users do not need to set these options. Vagrant can attach disks for you without these options. + +Only use these options if you are sure you know what you are doing and you need to specify a specific location for a disk. + +- `ControllerLocation` (int) - The location that the disk should be attached to on the controller +- `ControllerNumber` (int) - The controller to use for attaching the disk +- `ControllerType` (string) - The kind of controller to use when attaching the a disk. Only `"IDE"` and `"SCSI"` are valid. + +## Common issues and troubleshooting + +This section lists some common issues people run into with Vagrant and Hyper-V as well as solutions for those issues. + +### Are my disks attached? + +A handy way to figure out what disks are attached (or not attached) to your guest is to open up the Hyper-V GUI and select the guest. When selecting a guest on the GUI, it should open more information about the guest, including storage information. Here you should see a list of disks attached to your guest. + +### Apply Vagrant disk configuration changes to guests + +Due to how Hyper-V works, you must reload your guest for any disk config changes to be applied. If you update your Vagrantfile to update or remove disks, reload your guest for these changes to be applied. + +```shell-session +$ vagrant reload +``` \ No newline at end of file diff --git a/website/content/docs/define/disks/index.mdx b/website/content/docs/define/disks/index.mdx new file mode 100644 index 00000000000..e1174c05825 --- /dev/null +++ b/website/content/docs/define/disks/index.mdx @@ -0,0 +1,110 @@ +--- +layout: docs +page_title: Vagrant Disks +description: Introduction to Vagrant Disks +--- + +# Vagrant Disks + +Vagrant Disks is a feature that allows users to define what mediums should be attached +to their guests, as well as allowing users to resize their primary disk. + +For examples on how to achieve this, among other use cases, please refer to the [usage](/vagrant/docs/disks/usage) +guide for more information! + +For more information about what options are available for configuring disks, see the +[configuration section](/vagrant/docs/disks/configuration). + +## Supported providers + +Currently, only VirtualBox is supported. Please refer to the [VirtualBox documentation](/vagrant/docs/disks/virtualbox) for more information on using disks with the VirtualBox provider! + +## Examples + +The following examples show how to use Vagrant Disks with the VirtualBox provider. + +### Resize your primary disk + +Sometimes, the primary disk for a guest is not large enough and you will need to add more space. To resize a disk, you can simply add a config like this below to expand the size of your guests drive. + +```ruby +config.vm.disk :disk, size: "100GB", primary: true +``` + +The `primary: true` is what tells Vagrant to expand the guests main drive. Without this option, Vagrant will instead attach a _new_ disk to the guest. + +The following example shows how to resize the primary disk for an Ubuntu guest. This guest will now come with 100GB of space, rather than the default. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "100GB", primary: true + end +end +``` + +Due to how VirtualBox functions, it is not possible to shrink the size of a disk. + +### Attaching new hard disks + +Vagrant can attach multiple disks to a guest using the VirtualBox provider. The following example shows how to attach a single disk to a guest with 10 GB of storage. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "10GB", name: "extra_storage" + end +end +``` + +Optionally, if you need to attach many disks, you can use Ruby to generate multiple disks for Vagrant to create and attach to your guest. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + (0..3).each do |i| + h.vm.disk :disk, size: "5GB", name: "disk-#{i}" + end + end +end +``` + +VirtualBox has a hard limit on the number of disks that can be attached to a given storage controller, which is defined by the controller type. Attempting to configure more disks than are supported by the primary controller will result in a Vagrant error. + +### Attach optical drives + +Vagrant can attach `.iso` files as optical drives using the VirtualBox provider. The following example shows how to attach an optical drive to a guest. + +```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 +``` + +As with hard disks, configuring more disks than are supported by your VM's +storage controller arrangement will result in a Vagrant error. + +### Remove 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. + + + +Removing virtual hard disks created by Vagrant will also delete the medium from your hard drive. + + + diff --git a/website/content/docs/define/disks/virtualbox.mdx b/website/content/docs/define/disks/virtualbox.mdx new file mode 100644 index 00000000000..1efa1c47054 --- /dev/null +++ b/website/content/docs/define/disks/virtualbox.mdx @@ -0,0 +1,59 @@ +--- +layout: docs +page_title: Disks for VirtualBox Provider +description: |- + Vagrant comes with support out of the box for VirtualBox, a free, + cross-platform consumer virtualization product. +--- + +# VirtualBox + +Vagrant currently only supports VirtualBox version 5.x and newer for configuring and attaching disks. + +Because of how VirtualBox handles disk management, a Vagrant guest _must_ be powered 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 attach disks to a particular storage controller based on the type of disk configured: + +- For the `:disk` type, Vagrant will use the storage controller containing the boot disk. It will also create the disk if necessary. + +- For the `:dvd` type, Vagrant will attach the disk to the storage controller that comes earliest in the machine's boot order. For example, if a VM has a SATA controller and an IDE controller, the disk will be attached to the 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](/vagrant/docs/providers/virtualbox/configuration#vboxmanage-customizations) to add a required storage controller. + +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. + +## Usage + +For more information on how to use VirtualBox to configure disks for a guest, refer to the [Disks examples](/vagrant/docs/define/disks#examples) and [configuration](/vagrant/docs/vagrantfile/vm/disk) guide. + +## `provider_config` options + +Currently, there are no additional options supported for the `provider_config` option. + +## Common issues and troubleshooting + +This section lists some common issues people run into with Vagrant and VirtualBox as well as solutions for those issues. + +### Are my disks attached? + +A handy way to figure out what disks are attached (or not attached) to your guest is to open up the VirtualBox GUI and select the guest. When selecting a guest on the GUI, it should open more information about the guest, including storage information. Here you should see a list of disks attached to your guest. + +### How many disks can I attach? + +Vagrant attaches all new disks defined to guest's primary controller. As of VirtualBox 6.1.x, storage controllers have the following limits to the number of disks that are supported per guest: + +- IDE Controllers: 4 +- SATA Controllers: 30 +- SCSI Controllers: 16 + +Therefore if your primary disk is attached to a SATA Controller and you try to define and attach more than 30, it will result in an error. This number includes the primary disk for the guest. + +DVD attachments are subject to the same limits. Optical disk attachments will be attached to the storage controller with the highest boot priority (usually the IDE controller). + +### Resize VMDK format disks + +VMDK disks cannot be resized in their current state, so Vagrant will automatically convert these disks to VDI, resize the disk, and convert it back to its original format. Many Vagrant boxes default to using the VMDK disk format, so resizing disks for many users will require Vagrant to convert these disks. Generally, this will be transparent to the user. However if Vagrant crashes or if a user interrupts Vagrant during the cloning process, there is a chance that you might lose your data. + +### Apply Vagrant disk configuration changes to guests + +Due to how VirtualBox works, you must reload your guest for any disk config changes to be applied. So if you update your Vagrantfile to update or even remove disks, make sure to `vagrant reload` your guests for these changes to be applied. diff --git a/website/content/docs/define/disks/vmware.mdx b/website/content/docs/define/disks/vmware.mdx new file mode 100644 index 00000000000..5a9e9c65ff1 --- /dev/null +++ b/website/content/docs/define/disks/vmware.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: Disks for VMware Provider +description: |- + HashiCorp develops an official VMware Fusion and VMware Workstation provider + for Vagrant. This provider allows Vagrant to power VMware based machines and + take advantage of the improved stability and performance that VMware software + offers. +--- + +# VMware + +Because of how VMware handles disk management, a Vagrant guest _must_ be powered 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. + +## Usage + +For more information on how to use VMware to configure disks for a guest, refer to the [Disks examples](/vagrant/docs/define/disks#examples) and [configuration](/vagrant/docs/vagrantfile/vm/disk) guide for more information. + +## `provider_config` options + +Vagrant supports some additional VMWware specific options for specifying disk. + +- `bus_type` (string) - Sets the bus type when attaching the disk. Possible options are `sata`, `ide`, and `scsi`. Defaults to `scsi` +- `adapter_type` (string) - Sets the adapter type when creating the disk. Possible options are `ide`, `buslogic` and `lsilogic`. Defaults to `lsilogic` + +## Common issues and troubleshooting + +This section lists some common issues people run into with Vagrant and VMware as well as solutions for those issues. + +### Are my disks attached? + +A handy way to figure out what disks are attached (or not attached) to your guest is to open up the VMware GUI and open up the guest settings and selecting the disks options. + +### How many disks can I attach? + +Vagrant will attempt to attach all disks specified in the Vagrantfile. If more than four `ide` type disks are specified, only the first four will be attached. + +### Apply Vagrant disk configuration changes to guests + +Due to how VMware works, you must reload your guest for any disk config changes to be applied. So if you update your Vagrantfile to update or even remove disks, make sure to `vagrant reload` your guests for these changes to be applied. Vagrant will not decrease the size of a disk. + +### Disk functionality with snapshots + +If snapshots exist for a VM, disk functionality will be limited. Vagrant will return an error for any actions that are limited due to the existence of snapshots. + +In order to restore functionality you must [remove the snapshots](/vagrant/docs/cli/snapshot). + +```shell-session +$ vagrant snapshot delete +``` + +Use the following command to delete all snapshots for a VMware backed VM. Once a snapshot is deleted, it can not be restored. + +```shell-session +$ vagrant cap provider delete_all_snapshots --target +``` diff --git a/website/content/docs/define/index.mdx b/website/content/docs/define/index.mdx new file mode 100644 index 00000000000..ab685c84392 --- /dev/null +++ b/website/content/docs/define/index.mdx @@ -0,0 +1,84 @@ +--- +layout: docs +page_title: Vagrantfile +description: |- + The primary function of the Vagrantfile is to describe the type + of machine required for a project, and how to configure and + provision these machines. Vagrantfiles are called Vagrantfiles because + the actual literal filename for the file is "Vagrantfile". +--- + +# Vagrantfile + +The primary function of the Vagrantfile is to describe the type +of machine required for a project, and how to configure and +provision these machines. Vagrantfiles are called Vagrantfiles because +the actual literal filename for the file is `Vagrantfile` (casing does not +matter unless your file system is running in a strict case sensitive mode). + +Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile +is supposed to be committed to version control. This allows other developers +involved in the project to check out the code, run `vagrant up`, and be on +their way. Vagrantfiles are portable across every platform Vagrant supports. + +The syntax of Vagrantfiles is [Ruby](http://www.ruby-lang.org), but knowledge +of the Ruby programming language is not necessary to make modifications to the +Vagrantfile, since it is mostly simple variable assignment. In fact, Ruby is not +even the most popular community Vagrant is used within, which should help show +you that despite not having Ruby knowledge, people are very successful with +Vagrant. + +## Lookup Path + +When you run any `vagrant` command, Vagrant climbs up the directory tree +looking for the first Vagrantfile it can find, starting first in the +current directory. So if you run `vagrant` in `/home/mitchellh/projects/foo`, +it will search the following paths in order for a Vagrantfile, until it +finds one: + +``` +/home/mitchellh/projects/foo/Vagrantfile +/home/mitchellh/projects/Vagrantfile +/home/mitchellh/Vagrantfile +/home/Vagrantfile +/Vagrantfile +``` + +This feature lets you run `vagrant` from any directory in your project. + +You can change the starting directory where Vagrant looks for a Vagrantfile +by setting the `VAGRANT_CWD` environmental variable to some other path. + +## Load Order and Merging ((#load-order)) + +An important concept to understand is how Vagrant loads Vagrantfiles. Vagrant +actually loads a series of Vagrantfiles, merging the settings as it goes. This +allows Vagrantfiles of varying level of specificity to override prior settings. +Vagrantfiles are loaded in the order shown below. Note that if a Vagrantfile +is not found at any step, Vagrant continues with the next step. + +1. Vagrantfile packaged with the [box](/vagrant/docs/boxes) that is to be used + for a given machine. +2. Vagrantfile in your Vagrant home directory (defaults to `~/.vagrant.d`). + This lets you specify some defaults for your system user. +3. Vagrantfile from the project directory. This is the Vagrantfile that you will + be modifying most of the time. +4. [Multi-machine overrides](/vagrant/docs/multi-machine/) if any. +5. [Provider-specific overrides](/vagrant/docs/providers/configuration), + if any. + +At each level, settings set will be merged with previous values. What this +exactly means depends on the setting. For most settings, this means that +the newer setting overrides the older one. However, for things such as defining +networks, the networks are actually appended to each other. By default, you +should assume that settings will override each other. If the behavior is +different, it will be noted in the relevant documentation section. + +Within each Vagrantfile, you may specify multiple `Vagrant.configure` blocks. +All configurations will be merged within a single Vagrantfile in the order +they're defined. + +## Available Configuration Options + +You can learn more about the available configuration options by clicking +the relevant section in the left navigational area. diff --git a/website/content/docs/define/multi-machine.mdx b/website/content/docs/define/multi-machine.mdx new file mode 100644 index 00000000000..27458cadf1d --- /dev/null +++ b/website/content/docs/define/multi-machine.mdx @@ -0,0 +1,102 @@ +--- +layout: docs +page_title: Multi-Machine +description: |- + Vagrant is able to define and control multiple guest machines per + Vagrantfile. This is known as a "multi-machine" environment. +--- + +# Multi-Machine + +Vagrant is able to define and control multiple guest machines per Vagrantfile. This is known as a "multi-machine" environment. + +These machines are generally able to work together or are somehow associated with each other. Here are some use-cases people are using multi-machine environments for today: + +- Accurately modeling a multi-server production topology, such as separating a web and database server. +- Modeling a distributed system and how they interact with each other. +- Testing an interface, such as an API to a service component. +- Disaster-case testing: machines dying, network partitions, slow networks, inconsistent world views, etc. + +Historically, running complex environments such as these was done by flattening them onto a single machine. The problem with that is that it is an inaccurate model of the production setup, which can behave far differently. + +Using the multi-machine feature of Vagrant, these environments can be modeled in the context of a single Vagrant environment without losing any of the benefits of Vagrant. + +## Define multiple machines + +Multiple machines are defined within the same project [Vagrantfile](/vagrant/docs/vagrantfile/) using the `config.vm.define` method call. The following example shows a multi-machine configuration. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo Hello" + + config.vm.define "web" do |web| + web.vm.box = "apache" + end + + config.vm.define "db" do |db| + db.vm.box = "mysql" + end +end +``` + +As you can see, `config.vm.define` takes a block with another variable. This variable, such as `web` above, is the _exact_ same as the `config` variable, except any configuration of the inner variable applies only to the machine being defined. Therefore, any configuration on `web` will only affect the `web` machine. + +Importantly, you can continue to use the `config` object as well. The configuration object is loaded and merged before the machine-specific configuration, just like other Vagrantfiles within the [Vagrantfile load order](/vagrant/docs/vagrantfile/#load-order). + +If you are familiar with programming, this is similar to how languages have different variable scopes. + +When using these scopes, order of execution for things such as provisioners becomes important. Vagrant enforces ordering outside-in, in the order listed in the Vagrantfile. The following example shows a Vagrantfile with multi-machine configuration highlighting the order of execution. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision :shell, inline: "echo A" + + config.vm.define :testing do |test| + test.vm.provision :shell, inline: "echo B" + end + + config.vm.provision :shell, inline: "echo C" +end +``` + +In this case, the provisioners will output "A", then "C", then "B". Notice that "B" is last. That is because the ordering is outside-in, in the order of the file. + +If you want to apply a slightly different configuration to multiple machines, refer to [this tip](/vagrant/docs/vagrantfile/tips#loop-over-vm-definitions). + +## Control multiple machines + +The moment more than one machine is defined within a Vagrantfile, the usage of the various `vagrant` commands changes slightly. The change should be mostly intuitive. + +Commands that only make sense to target a single machine, such as `vagrant ssh`, now _require_ the name of the machine to control. Using the example above, you would say `vagrant ssh web` or `vagrant ssh db`. + +Other commands, such as `vagrant up`, operate on _every_ machine by default. So if you ran `vagrant up`, Vagrant would bring up both the web and DB machine. You could also optionally be specific and say `vagrant up web` or `vagrant up db`. + +Additionally, you can specify a regular expression for matching only certain machines. This is useful in some cases where you specify many similar machines, for example if you are testing a distributed service you may have a `leader` machine as well as a `follower0`, `follower1`, `follower2`, etc. If you want to bring up all the followers but not the leader, you can just do `vagrant up /follower[0-9]/`. If Vagrant sees a machine name within forward slashes, it assumes you are using a regular expression. + +## Communication between machines + +In order to facilitate communication within machines in a multi-machine setup, you need to use various [networking](/vagrant/docs/networking/) options. In particular, you can use the [private network](/vagrant/docs/networking/private_network) option to make a private network between multiple machines and the host. + +## Specify a primary machine + +You can also specify a _primary machine_. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified. + +To specify a default machine, mark it primary when defining it. You can only specify one primary machine. + +```ruby +config.vm.define "web", primary: true do |web| + # ... +end +``` + +## Autostart machines + +By default in a multi-machine environment, `vagrant up` will start all of the defined machines. The `autostart` setting lets you tell Vagrant to not start specific machines. The following example shows a Vagrantfile with a multi-machine configuration and the `autostart` setting. + +```ruby +config.vm.define "web" +config.vm.define "db" +config.vm.define "db_follower", autostart: false +``` + +When you run `vagrant up` with these settings, Vagrant will automatically start the `web` and `db` machines, but will not start the `db_follower` machine. You can manually force the `db_follower` machine to start by running `vagrant up db_follower`. diff --git a/website/content/docs/networking/forwarded_ports.mdx b/website/content/docs/define/networking/forwarded_ports.mdx similarity index 100% rename from website/content/docs/networking/forwarded_ports.mdx rename to website/content/docs/define/networking/forwarded_ports.mdx diff --git a/website/content/docs/define/networking/index.mdx b/website/content/docs/define/networking/index.mdx new file mode 100644 index 00000000000..9d2f3b7622b --- /dev/null +++ b/website/content/docs/define/networking/index.mdx @@ -0,0 +1,71 @@ +--- +layout: docs +page_title: Networking +description: |- + In order to access the Vagrant environment created, Vagrant exposes + some high-level networking options for things such as forwarded ports, + connecting to a public network, or creating a private network. +--- + +# Networking + +In order to access the Vagrant environment created, Vagrant exposes some high-level networking options for things such as forwarded ports, connecting to a public network, or creating a private network. + +The high-level networking options are meant to define an abstraction that works across multiple [providers](/vagrant/docs/providers/). This means that you can take your Vagrantfile you used to spin up a VirtualBox machine and you can reasonably expect that Vagrantfile to behave the same with something like VMware. + +Vagrant assumes there is an available NAT device on `eth0`. This ensures that Vagrant always has a way of communicating with the guest machine. It is possible to change this manually (outside of Vagrant), however, this may lead to inconsistent behavior. Providers might have additional assumptions. For example, in VirtualBox, this assumption means that network adapter 1 is a NAT device. + +Vagrant offers multiple options for how you are able to connect your guest machines to the network, but there is a standard usage pattern as well as some points common to all network configurations that are important to know. + +## Configure your network + +All networks are configured within your [Vagrantfile](/vagrant/docs/vagrantfile/) using the `config.vm.network` method call. For example, the Vagrantfile below defines some port forwarding: + +```ruby +Vagrant.configure("2") do |config| + # ... + config.vm.network "forwarded_port", guest: 80, host: 8080 +end +``` + +Every network type has an identifier such as `"forwarded_port"` in the above example. Following this is a set of configuration arguments that can differ for each network type. In the case of forwarded ports, two numeric arguments are expected: the port on the guest followed by the port on the host that the guest port can be accessed by. + +## Define multiple networks + +Multiple networks can be defined by having multiple `config.vm.network` calls within the Vagrantfile. The exact meaning of this can differ for each [provider](/vagrant/docs/providers/), but in general the order specifies the order in which the networks are enabled. + +## Enable networks + +Networks are automatically configured and enabled after they've been defined in the Vagrantfile as part of the `vagrant up` or `vagrant reload` process. + +## Set hostname + +A hostname may be defined for a Vagrant VM using the `config.vm.hostname` setting. By default, this will modify `/etc/hosts`, adding the hostname on a loopback interface that is not in use. The following example will add the entry `127.0.X.1 myhost myhost.local` to `/etc/hosts`. + +```ruby +Vagrant.configure("2") do |config| + # ... + config.vm.hostname = "myhost.local" +end +``` + +A public or private network with an assigned IP may be flagged for hostname. In this case, the hostname will be added to the flagged network. Note, that if there are multiple networks only one may be flagged for hostname. The following example will add the entry `192.168.0.1 myhost myhost.local` to `/etc/hosts`. + +```ruby +Vagrant.configure("2") do |config| + # ... + config.vm.hostname = "myhost.local" + config.vm.network "public_network", ip: "192.168.0.1", hostname: true + config.vm.network "public_network", ip: "192.168.0.2" +end +``` + +## Advanced configuration + +In some cases, these options are _too_ high-level, and you may want to more finely tune and configure the network interfaces of the underlying machine. Most providers expose [provider-specific configuration](/vagrant/docs/providers/configuration) to do this, so please read the documentation for your specific provider to see what options are available. + + + +We strongly recommend you use only the high-level networking options until you are comfortable with the Vagrant workflow and have things working at a basic level. Provider-specific network configuration can very quickly lock you out of your guest machine if improperly done. + + diff --git a/website/content/docs/networking/private_network.mdx b/website/content/docs/define/networking/private_network.mdx similarity index 100% rename from website/content/docs/networking/private_network.mdx rename to website/content/docs/define/networking/private_network.mdx diff --git a/website/content/docs/providers/docker/networking.mdx b/website/content/docs/define/networking/provider/docker.mdx similarity index 100% rename from website/content/docs/providers/docker/networking.mdx rename to website/content/docs/define/networking/provider/docker.mdx diff --git a/website/content/docs/providers/virtualbox/networking.mdx b/website/content/docs/define/networking/provider/virtualbox.mdx similarity index 100% rename from website/content/docs/providers/virtualbox/networking.mdx rename to website/content/docs/define/networking/provider/virtualbox.mdx diff --git a/website/content/docs/networking/public_network.mdx b/website/content/docs/define/networking/public_network.mdx similarity index 100% rename from website/content/docs/networking/public_network.mdx rename to website/content/docs/define/networking/public_network.mdx diff --git a/website/content/docs/providers/custom.mdx b/website/content/docs/define/providers/custom.mdx similarity index 53% rename from website/content/docs/providers/custom.mdx rename to website/content/docs/define/providers/custom.mdx index ebb6512a176..261c8a8d9fc 100644 --- a/website/content/docs/providers/custom.mdx +++ b/website/content/docs/define/providers/custom.mdx @@ -6,7 +6,6 @@ description: |- plugin development guide on creating custom providers. --- -# Custom Provider +# Custom provider -To learn how to make your own custom Vagrant providers, read the Vagrant plugin -development guide on [creating custom providers](/vagrant/docs/plugins/providers). +To learn how to make your own custom Vagrant providers, refer to the Vagrant plugin development guide on [creating custom providers](/vagrant/docs/plugins/providers). diff --git a/website/content/docs/define/providers/docker.mdx b/website/content/docs/define/providers/docker.mdx new file mode 100644 index 00000000000..d724b92a872 --- /dev/null +++ b/website/content/docs/define/providers/docker.mdx @@ -0,0 +1,95 @@ +--- +layout: docs +page_title: Docker Provider +description: |- + Vagrant comes with support out of the box for + using Docker as a provider. This allows for your development environments + to be backed by Docker containers rather than virtual machines. Additionally, + it provides for a good workflow for developing Dockerfiles. +--- + +# Docker + +Vagrant comes with support out of the box for using Docker as a provider. This allows for your development environments to be backed by Docker containers rather than virtual machines. Additionally, it provides for a good workflow for developing Dockerfiles. + + + +We assume that you know what Docker is and that you are comfortable with the basics of Docker. If not, we recommend starting with another provider such as [VirtualBox](/vagrant/docs/providers/virtualbox). + + + +## Usage + +The Docker provider in Vagrant behaves just like any other provider. If you are familiar with Vagrant already, then using the Docker provider should be intuitive and simple. + +The Docker provider _does not_ require a `config.vm.box` setting. Since the "base image" for a Docker container is pulled from the Docker Index or built from a Dockerfile, the box does not add much value, and is optional for this provider. + +### Docker images + +The first method that Vagrant can use to source a Docker container is via an image. This image can be from any Docker registry. An example is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.image = "foo/bar" + end +end +``` + +When `vagrant up --provider=docker` is run, this will bring up the image `foo/bar`. + +This is useful for extra components of your application that it might depend on: databases, queues, etc. Typically, the primary application you are working on is built with a Dockerfile, or via a container with SSH. + +### Dockerfiles + +Vagrant can also automatically build and run images based on a local Dockerfile. This is useful for iterating on an application locally that is built into an image later. An example is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.build_dir = "." + end +end +``` + +The above configuration will look for a `Dockerfile` in the same directory as the Vagrantfile. When `vagrant up --provider=docker` is run, Vagrant automatically builds that Dockerfile and starts a container based on that Dockerfile. + +The Dockerfile is rebuilt when `vagrant reload` is called. + +### Synced folders and networking + +When using Docker, Vagrant automatically converts synced folders and networking options into Docker volumes and forwarded ports. You do not have to use the Docker-specific configurations to do this. This helps keep your Vagrantfile similar to how it has always looked. + +The Docker provider does not support specifying options for `owner` or `group` +on folders synced with a docker container. + +#### Volume consistency + +Docker's [volume consistency](https://docs.docker.com/v17.09/engine/admin/volumes/bind-mounts/) setting can be specified using the `docker_consistency` option when defining a synced folder. This can [greatly improve performance on macOS](https://docs.docker.com/docker-for-mac/osxfs-caching). An example is shown using the `cached` and `delegated` settings: + +```ruby +config.vm.synced_folder "/host/dir1", "/guest/dir1", docker_consistency: "cached" +config.vm.synced_folder "/host/dir2", "/guest/dir2", docker_consistency: "delegated" +``` + +### Host VM + +If the system cannot run Linux containers natively, Vagrant automatically spins up a "host VM" to run Docker. This allows your Docker-based Vagrant environments to remain portable, without inconsistencies depending on the platform they are running on. + +Vagrant will spin up a single instance of a host VM and run multiple containers on this one VM. This means that with the Docker provider, you only have the overhead of one virtual machine, and only if it is absolutely necessary. + +By default, the host VM Vagrant spins up is [backed by boot2docker](https://github.com/hashicorp/vagrant/blob/main/plugins/providers/docker/hostmachine/Vagrantfile), because it launches quickly and uses little resources. But the host VM can be customized to point to _any_ Vagrantfile. This allows the host VM to more closely match production by running a VM running Ubuntu, RHEL, etc. It can run any operating system supported by Vagrant. + +-> **Synced folder note:** Vagrant will attempt to use the "best" synced folder implementation it can. For boot2docker, this is often rsync. In this case, make sure you have rsync installed on your host machine. Vagrant will give you a human-friendly error message if it is not. + +An example of changing the host VM is shown below. Remember that this is optional, and Vagrant will spin up a default host VM if it is not specified: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.vagrant_vagrantfile = "../path/to/Vagrantfile" + end +end +``` + +The host VM will be spun up at the first `vagrant up` where the provider is Docker. To control this host VM, use the [global-status command](/vagrant/docs/cli/global-status) along with global control. diff --git a/website/content/docs/define/providers/hyperv.mdx b/website/content/docs/define/providers/hyperv.mdx new file mode 100644 index 00000000000..b319cba3f12 --- /dev/null +++ b/website/content/docs/define/providers/hyperv.mdx @@ -0,0 +1,48 @@ +--- +layout: docs +page_title: Hyper-V Provider +description: |- + Vagrant comes with support out of the box for Hyper-V, a native hypervisor + written by Microsoft. Hyper-V is available by default for almost all + Windows 8.1 and later installs. +--- + +# Hyper-V + +Vagrant comes with support out of the box for [Hyper-V](https://en.wikipedia.org/wiki/Hyper-V), a native hypervisor written by Microsoft. Hyper-V is available by default for almost all Windows 8.1 and later installs. + +The Hyper-V provider is compatible with Windows 8.1 and later only. Prior versions of Hyper-V do not include the necessary APIs for Vagrant to work. + +Hyper-V must be enabled prior to using the provider. Most Windows installations will not have Hyper-V enabled by default. Hyper-V is available by default for almost all Windows Enterprise, Professional, or Education 8.1 and later installs. To enable Hyper-V, go to "Programs and Features", click on "Turn Windows features on or off" and check the box next to "Hyper-V". Or install via PowerShell with: + +```powershell +Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All +``` + +Refer to official documentation [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). + +## Usage + +The Vagrant Hyper-V provider is used just like any other provider. Refer to the general [basic usage](/vagrant/docs/providers/basic_usage) page for providers. + +The value to use for the `--provider` flag is `hyperv`. + +Hyper-V also requires that you execute Vagrant with administrative privileges. Creating and managing virtual machines with Hyper-V requires admin rights. Vagrant will show you an error if it does not have the proper permissions. + +You can find boxes for Hyper-V on [HashiCorp's Vagrant Cloud](https://vagrantcloud.com/boxes/search). To get started, you might want to try the `hashicorp/bionic64` box. + +## Limitations + +The Vagrant Hyper-V provider works in almost every way like the VirtualBox or VMware provider would, but has some limitations that are inherent to Hyper-V itself. + +### Limited networking + +Vagrant does not yet know how to create and configure new networks for Hyper-V. When launching a machine with Hyper-V, Vagrant will prompt you asking what virtual switch you want to connect the virtual machine to. + +A result of this is that networking configurations in the Vagrantfile are completely ignored with Hyper-V. Vagrant cannot enforce a static IP or automatically configure a NAT. + +However, the IP address of the machine will be reported as part of the `vagrant up`, and you can use that IP address as if it were a host only network. + +### Snapshots + +Restoring snapshot VMs using `vagrant snapshot pop` or `vagrant snapshot restore` will sometimes raise errors when mounting SMB shared folders, however these mounts will still work inside the guest. diff --git a/website/content/docs/define/providers/index.mdx b/website/content/docs/define/providers/index.mdx new file mode 100644 index 00000000000..aa661c02204 --- /dev/null +++ b/website/content/docs/define/providers/index.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: Providers +description: |- + While Vagrant ships out of the box with support for VirtualBox, Hyper-V, and + Docker. Vagrant has the ability to manage other types of machines as well. + This is done by using other providers with Vagrant. +--- + +# Providers + +While Vagrant ships out of the box with support for [VirtualBox](https://www.virtualbox.org), [Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/), and [Docker](https://www.docker.io), Vagrant has the ability to manage other types of machines as well. This is done by using other _providers_ with Vagrant. + +Alternate providers can offer different features that make more sense in your use case. For example, if you are using Vagrant for any real work, [VMware](https://www.vmware.com) providers are recommended since they're well supported and generally more stable and performant than VirtualBox. + +Before you can use another provider, you must install it. Installation of other providers is done via the Vagrant plugin system. + +Once the provider is installed, usage is straightforward and simple, as you would expect with Vagrant. Read into the relevant subsections found in the navigation to the left for more information. + +## Install a provider + +Providers are distributed as Vagrant plugins. After installing a plugin which contains a provider, the provider should immediately be available. + + + +3rd party plugins can introduce instabilities into Vagrant due to the nature of them being written by non-core users. + + + +You can install plugins using `vagrant plugin install`. + +Use the following command to install a plugin from a known gem source. + +```shell-session +$ vagrant plugin install my-plugin +``` + +If you want to install a plugin from a local file source, use the following command. + +```shell-session +$ vagrant plugin install /path/to/my-plugin.gem +``` + +Once you install a plugin, Vagrant will automatically load it. If Vagrant cannot load a plugin, Vagrant will show an error message instead of crashing Vagrant. + +## Usage + +Once a plugin is installed, you should refer to the plugin's documentation to see exactly how to use it. Plugins which add commands should be instantly available via `vagrant`, provisioners should be available via `config.vm.provision`, etc. + + + +In the future, the `vagrant plugin` command will include a subcommand that will document the components that each plugin installs. + + + +## Update plugin + +Plugins can be updated by running `vagrant plugin update`. This will update every installed plugin to the latest version. You can update a specific plugin by calling `vagrant plugin update NAME`. Vagrant will output what plugins were updated and to what version. + +To determine the changes in a specific version of a plugin, refer to the plugin's homepage (usually a GitHub page or similar). It is the plugin author's responsibility to provide a change log if he or she chooses to. + +## Uninstall plugin + +Uninstalling a plugin is as easy as installing it. Just use the `vagrant plugin uninstall` command and the plugin will be removed. Example: + +```shell-session +$ vagrant plugin uninstall my-plugin +``` + +## List plugins + +To view what plugins are installed into your Vagrant environment at any time, use the `vagrant plugin list` command. This will list the plugins +that are installed along with their version. + + +## Default Provider + +By default, VirtualBox is the default provider for Vagrant. VirtualBox is still the most accessible platform to use Vagrant: it is free, cross-platform, and has been supported by Vagrant for years. With VirtualBox as the default provider, it provides the lowest friction for new users to get started with Vagrant. + +However, you may find after using Vagrant for some time that you prefer to use another provider as your default. In fact, this is quite common. To make this experience better, Vagrant allows specifying the default provider to use by setting the `VAGRANT_DEFAULT_PROVIDER` environmental variable. + +Just set `VAGRANT_DEFAULT_PROVIDER` to the provider you wish to be the default. For example, if you use Vagrant with VMware Fusion, you can set the environmental variable to `vmware_desktop` and it will be your default. \ No newline at end of file diff --git a/website/content/docs/define/providers/virtualbox.mdx b/website/content/docs/define/providers/virtualbox.mdx new file mode 100644 index 00000000000..80a6b39572a --- /dev/null +++ b/website/content/docs/define/providers/virtualbox.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: VirtualBox Provider +description: |- + Vagrant comes with support out of the box for VirtualBox, a free, + cross-platform consumer virtualization product. +--- + +# VirtualBox + +Vagrant comes with support out of the box for [VirtualBox](https://www.virtualbox.org), a free, cross-platform consumer virtualization product. + +The VirtualBox provider is compatible with VirtualBox versions 4.0.x, 4.1.x, 4.2.x, 4.3.x, 5.0.x, 5.1.x, 5.2.x, 6.0.x, 6.1.x, 7.0.x, and 7.1.x. Other versions are unsupported and the provider will display an error message. Please note that beta and pre-release versions VirtualBox are not supported and may not be well-behaved. + +VirtualBox must be installed on its own prior to using the provider, or the provider will display an error message asking you to install it. VirtualBox can be installed by [downloading](https://www.virtualbox.org/wiki/Downloads) a package or installer for your operating system and using standard procedures to install that package. + +## Usage + +The Vagrant VirtualBox provider is used just like any other provider. Please read the general [basic usage](/vagrant/docs/providers/basic_usage) page for providers. + +The value to use for the `--provider` flag is `virtualbox`. + +The Vagrant VirtualBox provider does not support parallel execution at this time. Specifying the `--parallel` option will have no effect. + +## Networking + +Refer to the [networking](/vagrant/docs/define/networking/virtualbox) page for more information. + +## Common Issues + +This section lists some common issues people run into with Vagrant and VirtualBox as well as solutions for those issues. + +### Hanging on Windows + +If Vagrant commands are hanging on Windows because they're communicating to VirtualBox, this may be caused by a permissions issue with VirtualBox. This is easy to fix. Starting VirtualBox as a normal user or as an administrator will prevent you from using it in the opposite way. Please keep in mind that when Vagrant interacts with VirtualBox, it will interact with it with the same access level as the console running Vagrant. + +To fix this issue, completely shut down all VirtualBox machines and GUIs. Wait a few seconds. Then, launch VirtualBox only with the access level you wish to use. + +### DNS not working + +If DNS is not working within your VM, then you may need to enable a DNS proxy (built-in to VirtualBox). Please refer to the [StackOverflow answers here](https://serverfault.com/questions/453185/vagrant-virtualbox-dns-10-0-2-3-not-working) for a guide on how to do that. diff --git a/website/content/docs/define/providers/vmware.mdx b/website/content/docs/define/providers/vmware.mdx new file mode 100644 index 00000000000..cbfcc13aa0d --- /dev/null +++ b/website/content/docs/define/providers/vmware.mdx @@ -0,0 +1,148 @@ +--- +layout: docs +page_title: VMware Provider +description: |- + HashiCorp develops an official VMware Fusion and VMware Workstation provider + for Vagrant. This provider allows Vagrant to power VMware based machines and + take advantage of the improved stability and performance that VMware software + offers. +--- + +# VMware + +HashiCorp develops an official [VMware Fusion](https://www.vmware.com/products/fusion/overview.html) and [VMware Workstation](https://www.vmware.com/products/workstation/) [provider](/vagrant/docs/providers/) for Vagrant. This provider allows Vagrant to power VMware based machines and take advantage of the improved stability and performance that VMware software offers. + +The Vagrant VMware plugin is now open sourced under the MPL. The code repository for the Vagrant VMware plugin is available on [GitHub](https://github.com/hashicorp/vagrant-vmware-desktop). + +This provider is a drop-in replacement for VirtualBox. However, there are some VMware-specific things such as box formats, configurations, etc. that are documented here. + +Please note that VMware Fusion and VMware Workstation are third-party products that must be purchased and installed separately prior to using the provider. + +## Install the provider + +If you are upgrading from the Vagrant VMware Workstation or Vagrant VMware Fusion plugins, please halt or destroy all VMware VMs currently being managed by Vagrant. Then continue with the instructions below. + +Installation of the Vagrant VMware provider requires two steps. First the Vagrant VMware Utility must be installed. This can be done by downloading and installing the correct system package from the [Vagrant VMware Utility downloads page](/vagrant/downloads/vmware). + +Next, install the Vagrant VMware provider plugin using the standard plugin installation procedure: + +```shell-session +$ vagrant plugin install vagrant-vmware-desktop +``` + +For more information on plugin installation, refer to the [Vagrant plugin usage documentation](/vagrant/docs/plugins/usage). + +## Upgrade to v1.x + +It is **extremely important** that the VMware plugin is upgraded to 1.0.0 or above. This release resolved critical security vulnerabilities. To learn more, please [read our release announcement](https://www.hashicorp.com/blog/introducing-the-vagrant-vmware-desktop-plugin). + +After upgrading, please verify that the following paths are empty. The upgrade process should remove these for you, but for security reasons it is important to double check. If you're a new user or installing the VMware provider on a new machine, you may skip this step. If you're a Windows user, you may skip this step as well. + +The path `~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}` should no longer exist. The gem `vagrant-vmware-desktop` may exist since this is the name of the new plugin. If the old directories exist, remove them. An example for a Unix-like shell is shown below: + +```shell-session +# Check if they exist and verify that they're the correct paths as shown below. +$ ls ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} +... + +# Remove them +$ rm -rf ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} +``` + +## Update the Vagrant VMware Desktop plugin + +The Vagrant VMware Desktop plugin can be updated directly from Vagrant. Run the following command to update Vagrant to the latest version of the Vagrant VMware Desktop plugin: + +```shell-session +$ vagrant plugin update vagrant-vmware-desktop +``` + +## Usage + +The Vagrant VMware provider is used just like any other provider. Please read the general [basic usage](/vagrant/docs/providers/basic_usage) page for providers. + +The value to use for the `--provider` flag is `vmware_desktop`. For compatibility with older versions of the plugin, `vmware_fusion` can be used for VMware Fusion, and `vmware_workstation` for VMware Workstation. + +The Vagrant VMware provider does not support parallel execution at this time. Specifying the `--parallel` option will have no effect. + +To get started, create a new `Vagrantfile` that points to a VMware box: + +```ruby +# vagrant init hashicorp/bionic64 +Vagrant.configure("2") do |config| + config.vm.box = "hashicorp/bionic64" +end +``` + +Then run: + +```shell-session +$ vagrant up --provider vmware_desktop +``` + +This will download and bring up a new VMware Fusion/Workstation virtual machine in Vagrant. + +## Known issues + +This section tracks some known issues or limitations of the VMware provider. Note that none of these are generally blockers to using the provider, but are good to know. + +### Network disconnect + +When Vagrant applies port forwarding rules while bring up a guest instance, other running VMware VMs may experience a loss of network connectivity. The cause of this connectivity issue is the restarting of the VMware NAT service to apply new port forwarding rules. Since new rules cannot be applied to the NAT service while it is running, it is required to restart the service, which results in the loss of connectivity. + +### Forwarded ports fail in Workstation on Windows + +VMware Workstation has a bug on Windows where forwarded ports do not work properly. Vagrant actually works around this bug and makes them work. However, if you run the virtual network editor on Windows, the forwarded ports will suddenly stop working. + +In this case, run `vagrant reload` and things will begin working again. + +This issue has been reported to VMware, but a fix has not been released yet. + +### Create network devices (Big Sur) + +Starting with the Big Sur release VMware Fusion is no longer able to create network devices with custom subnet and mask settings to attach to guests. This means custom IP addresses are not valid when creating a private network. When creating a private network device to attach to a guest, simply define it with no options: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = "hashicorp/bionic64" + config.vm.network :private_network +end +``` + +### Port forwarding (Big Sur) + +VMware Fusion currently does not support port forwarding to the localhost. To work around this issue, the vagrant-vmware-utility provides functionality to simulate port forwarding behavior available within VMware Fusion prior to Big Sur. The port forward management is contained to the vagrant-vmware-utility and is not accessible via the VMware Fusion networking UI. + +### DHCP reservations (Big Sur) + +Due VMware Fusion no longer utilizing its own service for DHCP, defining DHCP reservations is currently not working with VMware Fusion on Big Sur. + +## Frequently asked questions (FAQs) + +This section tracks some frequently asked questions about the VMware provider. + +### How do I use the VMware Fusion Tech Preview? + +The Vagrant VMware utility expects VMware Fusion to be installed in a specific path on macOS. Since the VMware Fusion Tech Preview installs into a different path, the Vagrant VMware utility will fail to detect the installation and will not start. To resolve this you can create a symlink from the VMware Fusion Tech Preview installation path to the normal VMware Fusion installation path: + +```shell-session +sudo ln -s /Applications/VMware\ Fusion\ Tech\ Preview.app /Applications/VMware\ Fusion.app +``` + +## Q: How do I upgrade my currently installed Vagrant VMware plugin? + +You can update the Vagrant VMware plugin to the latest version by re-running the install command: + +```shell-session +$ vagrant plugin install vagrant-vmware-desktop +``` + +To upgrade the Vagrant VMware utility, download the latest version from the [Vagrant VMware utility downloads page](/vagrant/downloads/vmware) and install the system package to your local system. + +## Q: Do I need a license for the Vagrant VMware plugin? + +No, the Vagrant VMware plugin has been open sourced under the MPL. A license is no longer required for using the Vagrant VMware plugin. If the plugin you are using still requires a license, simply upgrade your plugin: + +```shell-session +$ vagrant plugin update vagrant-vmware-desktop +``` diff --git a/website/content/docs/provisioning/ansible.mdx b/website/content/docs/define/provision/ansible/ansible.mdx similarity index 100% rename from website/content/docs/provisioning/ansible.mdx rename to website/content/docs/define/provision/ansible/ansible.mdx diff --git a/website/content/docs/provisioning/ansible_common.mdx b/website/content/docs/define/provision/ansible/common.mdx similarity index 100% rename from website/content/docs/provisioning/ansible_common.mdx rename to website/content/docs/define/provision/ansible/common.mdx diff --git a/website/content/docs/provisioning/ansible_intro.mdx b/website/content/docs/define/provision/ansible/index.mdx similarity index 100% rename from website/content/docs/provisioning/ansible_intro.mdx rename to website/content/docs/define/provision/ansible/index.mdx diff --git a/website/content/docs/provisioning/ansible_local.mdx b/website/content/docs/define/provision/ansible/local.mdx similarity index 100% rename from website/content/docs/provisioning/ansible_local.mdx rename to website/content/docs/define/provision/ansible/local.mdx diff --git a/website/content/docs/provisioning/cfengine.mdx b/website/content/docs/define/provision/cfengine.mdx similarity index 100% rename from website/content/docs/provisioning/cfengine.mdx rename to website/content/docs/define/provision/cfengine.mdx diff --git a/website/content/docs/provisioning/chef_apply.mdx b/website/content/docs/define/provision/chef/apply.mdx similarity index 100% rename from website/content/docs/provisioning/chef_apply.mdx rename to website/content/docs/define/provision/chef/apply.mdx diff --git a/website/content/docs/provisioning/chef_client.mdx b/website/content/docs/define/provision/chef/client.mdx similarity index 100% rename from website/content/docs/provisioning/chef_client.mdx rename to website/content/docs/define/provision/chef/client.mdx diff --git a/website/content/docs/provisioning/chef_common.mdx b/website/content/docs/define/provision/chef/common.mdx similarity index 100% rename from website/content/docs/provisioning/chef_common.mdx rename to website/content/docs/define/provision/chef/common.mdx diff --git a/website/content/docs/define/provision/chef/index.mdx b/website/content/docs/define/provision/chef/index.mdx new file mode 100644 index 00000000000..f23fd128299 --- /dev/null +++ b/website/content/docs/define/provision/chef/index.mdx @@ -0,0 +1,10 @@ +--- +layout: docs +page_title: Chef - Short Introduction +description: |- + Placeholder +--- + +# Chef and Vagrant + +Placeholder \ No newline at end of file diff --git a/website/content/docs/provisioning/chef_solo.mdx b/website/content/docs/define/provision/chef/solo.mdx similarity index 100% rename from website/content/docs/provisioning/chef_solo.mdx rename to website/content/docs/define/provision/chef/solo.mdx diff --git a/website/content/docs/provisioning/chef_zero.mdx b/website/content/docs/define/provision/chef/zero.mdx similarity index 100% rename from website/content/docs/provisioning/chef_zero.mdx rename to website/content/docs/define/provision/chef/zero.mdx diff --git a/website/content/docs/provisioning/docker.mdx b/website/content/docs/define/provision/docker.mdx similarity index 100% rename from website/content/docs/provisioning/docker.mdx rename to website/content/docs/define/provision/docker.mdx diff --git a/website/content/docs/provisioning/file.mdx b/website/content/docs/define/provision/file.mdx similarity index 100% rename from website/content/docs/provisioning/file.mdx rename to website/content/docs/define/provision/file.mdx diff --git a/website/content/docs/define/provision/index.mdx b/website/content/docs/define/provision/index.mdx new file mode 100644 index 00000000000..66e9e1f232d --- /dev/null +++ b/website/content/docs/define/provision/index.mdx @@ -0,0 +1,281 @@ +--- +layout: docs +page_title: Provisioning +description: >- + Provisioners in Vagrant allow you to automatically install software, alter + configurations, and more on the machine as part of the `vagrant up` process. +--- + +# Provisioning + +Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the `vagrant up` process. + +This is useful since [boxes](/vagrant/docs/boxes) typically are not built _perfectly_ for your use case. Of course, if you want to just use `vagrant ssh` and install the software by hand, that works. But by using the provisioning systems built-in to Vagrant, it automates the process so that it is repeatable. Most importantly, it requires no human interaction, so you can `vagrant destroy` and `vagrant up` and have a fully ready-to-go work environment with a single command. Powerful. + +Vagrant gives you multiple options for provisioning the machine, from simple shell scripts to more complex, industry-standard configuration management systems. + +If you've never used a configuration management system before, it is recommended you start with basic [shell scripts](/vagrant/docs/provisioning/shell) for provisioning. + +You can find the full list of built-in provisioners and usage of these provisioners in the navigational area to the left. + +## When provisioning happens + +Provisioning happens at certain points during the lifetime of your Vagrant environment: + +- On the first `vagrant up` that creates the environment, provisioning is run. If the environment was already created and the up is just resuming a machine or booting it up, they will not run unless the `--provision` flag is explicitly provided. + +- When `vagrant provision` is used on a running environment. + +- When `vagrant reload --provision` is called. The `--provision` flag must be present to force provisioning. + +You can also bring up your environment and explicitly _not_ run provisioners by specifying `--no-provision`. + +## Configure provisioners + +First, every provisioner is configured within your [Vagrantfile](/vagrant/docs/vagrantfile/) using the `config.vm.provision` method call. For example, the Vagrantfile below enables shell provisioning: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell", inline: "echo hello" +end +``` + +Every provisioner has a type, such as `"shell"`, used as the first parameter to the provisioning configuration. Following that is basic key/value for configuring that specific provisioner. Instead of basic key/value, you can also use a Ruby block for a syntax that is more like variable assignment. The following is effectively the same as the prior example: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell" do |s| + s.inline = "echo hello" + end +end +``` + +The benefit of the block-based syntax is that with more than a couple options it can greatly improve readability. Additionally, some provisioners, like the Chef provisioner, have special methods that can be called within that block to ease configuration that cannot be done with the key/value approach, or you can use this syntax to pass arguments to a shell script. + +The attributes that can be set in a single-line are the attributes that are set with the `=` style, such as `inline = "echo hello"` above. If the style is instead more of a function call, such as `add_recipe "foo"`, then this cannot be specified in a single line. + +Provisioners can also be named (since 1.7.0). These names are used cosmetically for output as well as overriding provisioner settings (covered further below). An example of naming provisioners is shown below: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "bootstrap", type: "shell" do |s| + s.inline = "echo hello" + end +end +``` + +Naming provisioners is simple. The first argument to `config.vm.provision` becomes the name, and then a `type` option is used to specify the provisioner type, such as `type: "shell"` above. + +## Run provisioners + +Provisioners are run in three cases: the initial `vagrant up`, `vagrant provision`, and `vagrant reload --provision`. + +A `--no-provision` flag can be passed to `up` and `reload` if you do not want to run provisioners. Likewise, you can pass `--provision` to force provisioning. + +The `--provision-with` flag can be used if you only want to run a specific provisioner if you have multiple provisioners specified. For example, if you have a shell and Puppet provisioner and only want to run the shell one, you can do `vagrant provision --provision-with shell`. The arguments to `--provision-with` can be the provisioner type (such as "shell") or the provisioner name (such as "bootstrap" from above). + +## Run once, always or never + +By default, provisioners are only run once, during the first `vagrant up` since the last `vagrant destroy`, unless the `--provision` flag is set, as noted above. + +Optionally, you can configure provisioners to run on every `up` or `reload`. They will only be not run if the `--no-provision` flag is explicitly specified. To do this set the `run` option to "always", as shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo hello", + run: "always" +end +``` + +You can also set `run:` to `"never"` if you have an optional provisioner that you want to mention to the user in a "post up message" or that requires some other configuration before it is possible, then call this with `vagrant provision --provision-with bootstrap`. + +If you are using the block format, you must specify it outside of the block, as shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "bootstrap", type: "shell", run: "never" do |s| + s.inline = "echo hello" + end +end +``` + +## Multiple provisioners + +Multiple `config.vm.provision` methods can be used to define multiple provisioners. These provisioners will be run in the order they're defined. This is useful for a variety of reasons, but most commonly it is used so that a shell script can bootstrap some of the system so that another provisioner can take over later. + +If you define provisioners at multiple "scope" levels (such as globally in the configuration block, then in a [multi-machine](/vagrant/docs/multi-machine/) definition, then maybe in a [provider-specific override](/vagrant/docs/providers/configuration)), then the outer scopes will always run _before_ any inner scopes. For example, in the Vagrantfile below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo foo" + + config.vm.define "web" do |web| + web.vm.provision "shell", inline: "echo bar" + end + + config.vm.provision "shell", inline: "echo baz" +end +``` + +The ordering of the provisioners will be to echo "foo", "baz", then "bar" (note the second one might not be what you expect!). Remember: ordering is _outside in_. + +With multiple provisioners, use the `--provision-with` setting along with names to get more fine grained control over what is run and when. + +## Override provisioner settings + + + +Provisioner overriding is an advanced topic that really only becomes useful if you are already using multi-machine and/or provider overrides. If you are just getting started with Vagrant, you can safely skip this. + + + +When using features such as [multi-machine](/vagrant/docs/multi-machine/) or [provider-specific overrides](/vagrant/docs/providers/configuration), you may want to define common provisioners in the global configuration scope of a Vagrantfile, but override certain aspects of them internally. Vagrant allows you to do this, but has some details to consider. + +To override settings, you must assign a name to your provisioner. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "foo", type: "shell", + inline: "echo foo" + + config.vm.define "web" do |web| + web.vm.provision "foo", type: "shell", + inline: "echo bar" + end +end +``` + +In the above, only "bar" will be echoed, because the inline setting overloaded the outer provisioner. This overload is only effective within that scope: the "web" VM. If there were another VM defined, it would still echo "foo" unless it itself also overloaded the provisioner. + +**Be careful with ordering.** When overriding a provisioner in a sub-scope, the provisioner will run at _that point_. In the example below, the output would be "foo" then "bar": + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "foo", type: "shell", + inline: "echo ORIGINAL!" + + config.vm.define "web" do |web| + web.vm.provision "shell", + inline: "echo foo" + web.vm.provision "foo", type: "shell", + inline: "echo bar" + end +end +``` + +If you want to preserve the original ordering, you can specify the `preserve_order: true` flag. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "do-this", + type: "shell", + preserve_order: true, + inline: "echo FIRST!" + config.vm.provision "then-this", + type: "shell", + preserve_order: true, + inline: "echo SECOND!" +end +``` + +## Dependency provisioners + + + +Dependency provisioners are an advanced topic. If you are just getting started with Vagrant, you can safely skip this. + + + +If a provisioner has been configured using the `before` or `after` options, it is considered a _Dependency Provisioner_. This means it has been configured to run before or after a _Root Provisioner_, which does not have the `before` or `after` options configured. + +Dependency provisioners also have two valid shortcuts: `:each` and `:all`. + + + +As of 2.2.6, dependency provisioners cannot rely on other dependency provisioners and is considered a configuration state error in Vagrant. If you must order dependency provisioners, you can still order them by the order they are defined inside your Vagrantfile. + + + +The following example shows how to use dependency provisioners. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "C", after: "B", type: "shell", inline:<<-SHELL + echo 'C' + SHELL + config.vm.provision "B", type: "shell", inline:<<-SHELL + echo 'B' + SHELL + config.vm.provision "D", type: "shell", inline:<<-SHELL + echo 'D' + SHELL + config.vm.provision "A", before: "B", type: "shell", inline:<<-SHELL + echo 'A' + SHELL + config.vm.provision "Separate After", after: :each, type: "shell", inline:<<-SHELL + echo '==============================' + SHELL + config.vm.provision "Separate Before", before: :each, type: "shell", inline:<<-SHELL + echo '++++++++++++++++++++++++++++++' + SHELL + config.vm.provision "Hello", before: :all, type: "shell", inline:<<-SHELL + echo 'HERE WE GO!!' + SHELL + config.vm.provision "Goodbye", after: :all, type: "shell", inline:<<-SHELL + echo 'The end' + SHELL +end +``` + +The result of running `vagrant provision` with a guest configured above is: + +``` +==> default: Running provisioner: Hello (shell)... + default: Running: inline script + default: HERE WE GO!! +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: A (shell)... + default: Running: inline script + default: A +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: B (shell)... + default: Running: inline script + default: B +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: C (shell)... + default: Running: inline script + default: C +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: D (shell)... + default: Running: inline script + default: D +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Goodbye (shell)... + default: Running: inline script + default: The end +``` diff --git a/website/content/docs/provisioning/podman.mdx b/website/content/docs/define/provision/podman.mdx similarity index 100% rename from website/content/docs/provisioning/podman.mdx rename to website/content/docs/define/provision/podman.mdx diff --git a/website/content/docs/provisioning/puppet_agent.mdx b/website/content/docs/define/provision/puppet/agent.mdx similarity index 100% rename from website/content/docs/provisioning/puppet_agent.mdx rename to website/content/docs/define/provision/puppet/agent.mdx diff --git a/website/content/docs/provisioning/puppet_apply.mdx b/website/content/docs/define/provision/puppet/apply.mdx similarity index 100% rename from website/content/docs/provisioning/puppet_apply.mdx rename to website/content/docs/define/provision/puppet/apply.mdx diff --git a/website/content/docs/define/provision/puppet/index.mdx b/website/content/docs/define/provision/puppet/index.mdx new file mode 100644 index 00000000000..c064afd389f --- /dev/null +++ b/website/content/docs/define/provision/puppet/index.mdx @@ -0,0 +1,10 @@ +--- +layout: docs +page_title: Puppet - Short Introduction +description: |- + Placeholder +--- + +# Puppet and Vagrant + +Placeholder \ No newline at end of file diff --git a/website/content/docs/provisioning/salt.mdx b/website/content/docs/define/provision/salt.mdx similarity index 100% rename from website/content/docs/provisioning/salt.mdx rename to website/content/docs/define/provision/salt.mdx diff --git a/website/content/docs/provisioning/shell.mdx b/website/content/docs/define/provision/shell.mdx similarity index 100% rename from website/content/docs/provisioning/shell.mdx rename to website/content/docs/define/provision/shell.mdx diff --git a/website/content/docs/define/synced-folders/index.mdx b/website/content/docs/define/synced-folders/index.mdx new file mode 100644 index 00000000000..b7ee66a2f68 --- /dev/null +++ b/website/content/docs/define/synced-folders/index.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: Synced Folders +description: |- + Synced folders enable Vagrant to sync a folder on the host machine to the + guest machine, allowing you to continue working on your project's files + on your host machine, but use the resources in the guest machine to + compile or run your project. +--- + +# Synced folders + +Synced folders enable Vagrant to sync a folder on the host machine to the guest machine, letting you continue working on your project's files on your host machine, but use the resources in the guest machine to compile or run your project. + +By default, Vagrant shares your project directory (the directory with the [Vagrantfile](/vagrant/docs/vagrantfile/)) to `/vagrant`. + +### Symbolic links + +Support for symbolic links across synced folder implementations and host/guest combinations is inconsistent. Vagrant does its best to make sure symbolic links work by configuring various hypervisors (such as VirtualBox), but some host/guest combinations still do not work properly. This can affect some development environments that rely on symbolic links. + +We recommend you test symbolic links on all the host/guest combinations you sync folders on. + +## Enable synced folders + +Synced folders are automatically setup during `vagrant up` and `vagrant reload`. + +## Disable synced folders + +You can disable synced folders by adding the `disabled` option to any definition. + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder "src/", "/srv/website", disabled: true +end +``` + +You can disable the default `/vagrant` share by adding the `disabled` option to the definition. + +```ruby +config.vm.synced_folder ".", "/vagrant", disabled: true +``` + +## Modify the owner/group + +If you need to mount folders with a different owner/group than the default SSH user, use the `owner` and `group` options. Keep in mind that these options will only affect the synced folder itself. + +```ruby +config.vm.synced_folder "src/", "/srv/website", + owner: "root", group: "root" +``` + +Owner and group IDs defined within `mount_options` will have precedence over the `owner` and `group` options. For example, given the following configuration, the user with ID `1234` and the group with ID `1234` will own the synced folder. Vagrant ignores the `owner` and `group` options. + +```ruby +config.vm.synced_folder ".", "/vagrant", owner: "vagrant", + group: "vagrant", mount_options: ["uid=1234", "gid=1234"] +``` \ No newline at end of file diff --git a/website/content/docs/synced-folders/nfs.mdx b/website/content/docs/define/synced-folders/nfs.mdx similarity index 60% rename from website/content/docs/synced-folders/nfs.mdx rename to website/content/docs/define/synced-folders/nfs.mdx index 1cc14193e9c..eabcd2d0603 100644 --- a/website/content/docs/synced-folders/nfs.mdx +++ b/website/content/docs/define/synced-folders/nfs.mdx @@ -2,46 +2,34 @@ layout: docs page_title: NFS - Synced Folders description: >- - In some cases the default shared folder implementations such as VirtualBox - - shared folders have high performance penalties. If you are seeing less than - + In some cases the default shared folder implementations such as VirtualBox + shared folders have high performance penalties. If you are seeing less than ideal performance with synced folders, NFS can offer a solution. Vagrant has - built-in support to orchestrate the configuration of the NFS server on the - host - - and guest for you. + host and guest for you. --- # NFS -In some cases the default shared folder implementations (such as VirtualBox -shared folders) have high performance penalties. If you are seeing less -than ideal performance with synced folders, [NFS](https://en.wikipedia.org/wiki/Network_File_System_%28protocol%29) -can offer a solution. Vagrant has built-in support to orchestrate the -configuration of the NFS server on the host and guest for you. +In some cases the default shared folder implementations (such as VirtualBox shared folders) have high performance penalties. If you are seeing less than ideal performance with synced folders, [NFS](https://en.wikipedia.org/wiki/Network_File_System_%28protocol%29) can offer a solution. Vagrant has built-in support to orchestrate the configuration of the NFS server on the host and guest for you. + + + +NFS folders do not work on Windows hosts. Vagrant will ignore your request for NFS synced folders on Windows. -~> **Windows users:** NFS folders do not work on Windows hosts. Vagrant will -ignore your request for NFS synced folders on Windows. + ## Prerequisites -Before using synced folders backed by NFS, the host machine must have -`nfsd` installed, the NFS server daemon. This comes pre-installed on Mac -OS X, and is typically a simple package install on Linux. +Before using synced folders backed by NFS, the host machine must have `nfsd` installed, the NFS server daemon. This comes pre-installed on macOS, and is typically a simple package install on Linux. -Additionally, the guest machine must have NFS support installed. This is -also usually a simple package installation away. +Additionally, the guest machine must have NFS support installed. This is also usually a simple package installation away. -If you are using the VirtualBox provider, you will also need to make sure you -have a -[private network set up](/vagrant/docs/networking/private_network). This is due to a limitation of VirtualBox's built-in networking. With -VMware, you do not need this. +If you are using the VirtualBox provider, you will also need to make sure you have a [private network set up](/vagrant/docs/networking/private_network). This is due to a limitation of VirtualBox's built-in networking. With VMware, you do not need this. -## Enabling NFS Synced Folders +## Enable NFS synced folders -To enable NFS, just add the `type: "nfs"` flag onto your synced folder: +To enable NFS, add the `type: "nfs"` flag onto your synced folder. ```ruby Vagrant.configure("2") do |config| @@ -49,49 +37,31 @@ Vagrant.configure("2") do |config| end ``` -If you add this to an existing Vagrantfile that has a running guest machine, -be sure to `vagrant reload` to see your changes. +If you add this to an existing Vagrantfile that has a running guest machine, be sure to `vagrant reload` to see your changes. -## NFS Synced Folder Options +## NFS synced folder options -NFS synced folders have a set of options that can be specified that are -unique to NFS. These are listed below. These options can be specified in -the final part of the `config.vm.synced_folder` definition, along with the -`type` option. +NFS synced folders have a set of options that you can specify that are unique to NFS. You can specify these options in the final part of the `config.vm.synced_folder` definition, along with the `type` option. -- `nfs_export` (boolean) - If this is false, then Vagrant will not modify - your `/etc/exports` automatically and assumes you've done so already. +- `nfs_export` (boolean) - If this is false, Vagrant will not modify your `/etc/exports` automatically and assumes you've done so already. -- `nfs_udp` (boolean) - Whether or not to use UDP as the transport. UDP - is faster but has some limitations (see the NFS documentation for more - details). This defaults to true. +- `nfs_udp` (boolean) - Whether or not to use UDP as the transport. UDP is faster but has some limitations (see the NFS documentation for more details). This defaults to true. -- `nfs_version` (string | integer) - The NFS protocol version to use when - mounting the folder on the guest. This defaults to 3. +- `nfs_version` (string | integer) - The NFS protocol version to use when mounting the folder on the guest. This defaults to 3. -## NFS Global Options +## NFS global options -There are also more global NFS options you can set with `config.nfs` in -the Vagrantfile. These are documented below: +You can specify global NFS options with `config.nfs` in the Vagrantfile. -- `functional` (bool) - Defaults to true. If false, then NFS will not be used - as a synced folder type. If a synced folder specifically requests NFS, - it will error. +- `functional` (bool) - Defaults to true. If false, NFS will not be used as a synced folder type. If a synced folder specifically requests NFS, it will error. -- `map_uid` and `map_gid` (int) - The UID/GID, respectively, to map all - read/write requests too. This will not affect the owner/group within the - guest machine itself, but any writes will behave as if they were written - as this UID/GID on the host. This defaults to the current user running - Vagrant. +- `map_uid` and `map_gid` (int) - The UID/GID, respectively, to map all read/write requests too. This will not affect the owner/group within the guest machine itself, but any writes will behave as if they were written as this UID/GID on the host. This defaults to the current user running Vagrant. -- `verify_installed` (bool) - Defaults to true. If this is false, then - Vagrant will skip checking if NFS is installed. +- `verify_installed` (bool) - Defaults to true. If this is false, Vagrant will skip checking if NFS is installed. -## Specifying NFS Arguments +## Specify NFS arguments -In addition to the options specified above, it is possible for Vagrant to -specify alternate NFS arguments when mounting the NFS share by using the -`mount_options` key. For example, to use the `actimeo=2` client mount option: +In addition to the options specified above, you can specify alternate NFS arguments when mounting the NFS share by using the `mount_options` key.For example, to use the `actimeo=2` client mount option: ```ruby config.vm.synced_folder ".", "/vagrant", @@ -101,15 +71,15 @@ config.vm.synced_folder ".", "/vagrant", This would result in the following `mount` command being executed on the guest: -``` + + +```shell-session mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant ``` -You can also tweak the arguments specified in the `/etc/exports` template -when the mount is added, by using the OS-specific `linux__nfs_options` or -`bsd__nfs_options` keys. Note that these options completely override the default -arguments that are added by Vagrant automatically. For example, to make the -NFS share asynchronous: + + +You can also tweak the arguments specified in the `/etc/exports` template when the mount is added, by using the OS-specific `linux__nfs_options` or `bsd__nfs_options` keys. Note that these options completely override the default arguments that are added by Vagrant automatically. For example, to make the NFS share asynchronous: ```ruby config.vm.synced_folder ".", "/vagrant", @@ -117,8 +87,9 @@ config.vm.synced_folder ".", "/vagrant", linux__nfs_options: ['rw','no_subtree_check','all_squash','async'] ``` -This would result in the following content in `/etc/exports` on the host (note -the added `async` flag): +This would result in the following content in `/etc/exports` on the host (note the added `async` flag): + + ``` # VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261 @@ -126,33 +97,33 @@ the added `async` flag): # VAGRANT-END: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261 ``` -## Root Privilege Requirement + + +## Root privilege requirement -To configure NFS, Vagrant must modify system files on the host. Therefore, -at some point during the `vagrant up` sequence, you may be prompted for -administrative privileges (via the typical `sudo` program). These -privileges are used to modify `/etc/exports` as well as to start and -stop the NFS server daemon. +To configure NFS, Vagrant must modify system files on the host. Therefore, at some point during the `vagrant up` sequence, you may be prompted for administrative privileges (via the typical `sudo` program). Vagrant uses these privileges to modify `/etc/exports` as well as to start and stop the NFS server daemon. -If you do not want to type your password on every `vagrant up`, Vagrant -uses thoughtfully crafted commands to make fine-grained sudoers modifications -possible to avoid entering your password. +If you do not want to type your password on every `vagrant up`, Vagrant uses thoughtfully crafted commands to make fine-grained sudoers modifications possible to avoid entering your password. -Below, we have a couple example sudoers entries. Note that you may -have to modify them _slightly_ on certain hosts because the way Vagrant -modifies `/etc/exports` changes a bit from OS to OS. If the commands below -are located in non-standard paths, modify them as appropriate. +Below, we have a couple example sudoers entries. Note that you may have to modify them _slightly_ on certain hosts because the way Vagrant modifies `/etc/exports` changes a bit from OS to OS. If the commands below are located in non-standard paths, modify them as appropriate. Also note that in the sudoer file format, entries are applied in order. If you've added the appropriate entries but still have to type in your password, make sure the entries aren't inserted too early. From the sudoers man page: "When multiple entries match for a user, they are applied in order. Where there are multiple matches, the last match is used (which is not necessarily the most specific match)." -For \*nix users, make sure to edit your `/etc/sudoers` file with `visudo`. It protects you against syntax errors which could leave you without the ability to gain elevated privileges. +For Nix users, make sure to edit your `/etc/sudoers` file with `visudo`. It protects you against syntax errors which could leave you without the ability to gain elevated privileges. -All of the snippets below require Vagrant version 1.7.3 or higher. +All of the snippets below require Vagrant version 1.7.3 or higher. If you don't want to edit `/etc/sudoers` directly, you can create `/etc/sudoers.d/vagrant-syncedfolders` with the appropriate entries, assuming `/etc/sudoers.d` has been enabled. -~> **Use the appropriate group for your user** Depending on how your machine is -configured, you might need to use a different group than the ones listed in the examples below. + -For macOS, sudoers should have this entry: +Depending on how your machine is configured, you might need to use a different group than the ones listed in the examples below. + + + + + + + +For macOS, sudoers should have this entry. ``` Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports @@ -161,7 +132,10 @@ Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports %admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE ``` -For Linux , sudoers should look like this: + + + +For Linux, sudoers should have this entry. ``` Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/vagrant-exports @@ -172,8 +146,10 @@ Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar %sudo ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY ``` -For Fedora Linux, sudoers might look like this (given your user -belongs to the vagrant group): + + + +For Fedora Linux, sudoers should have this entry (given your user belongs to the vagrant group). ``` Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/vagrant-exports @@ -184,8 +160,10 @@ Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar %vagrant ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY ``` -For SUSE Linux, sudoers might look like this (given your user -belongs to the vagrant group): + + + +For SUSE Linux, sudoers should have this entry (given your user belongs to the vagrant group). ``` Cmnd_Alias VAGRANT_CHOWN = /usr/bin/chown 0\:0 /tmp/vagrant-exports @@ -196,11 +174,10 @@ Cmnd_Alias VAGRANT_APPLY = /usr/sbin/exportfs -ar %vagrant ALL=(root) NOPASSWD: VAGRANT_CHOWN, VAGRANT_MV, VAGRANT_START, VAGRANT_STATUS, VAGRANT_APPLY ``` -If you don't want to edit `/etc/sudoers` directly, you can create -`/etc/sudoers.d/vagrant-syncedfolders` with the appropriate entries, -assuming `/etc/sudoers.d` has been enabled. + + -## Other Notes +## Other notes **Encrypted folders:** If you have an encrypted disk, then NFS very often will refuse to export the filesystem. The error message given by NFS is @@ -234,10 +211,9 @@ For more information about transport protocols and NFS version 4 see: - NFSv4.0 - [RFC7530](https://tools.ietf.org/html/rfc7530#section-3.1) - NFSv4.1 - [RFC5661](https://tools.ietf.org/html/rfc5661#section-2.9.1) -## Troubleshooting NFS Issues +## Troubleshoot NFS issues -NFS issues may arise for a variety of reasons. The following list -describes how to possibly identify the root of the issue. +NFS issues may arise for a variety of reasons. The following list describes how to possibly identify the root of the issue. - Ensure nfs server is running on the host. Check if it is running using the command `ps aux | grep nfsd`. If the nfs service is not running, @@ -268,10 +244,17 @@ describes how to possibly identify the root of the issue. - Ensure a firewall is not blocking NFS. -- Try manually mounting the folder, enabling verbose output: +- Try manually mounting the folder, enabling verbose output. + + First, connect to the guest machine. - ``` + ```shell-session $ vagrant ssh + ``` + + Then, mount the folder. + + ```shell-session $ mount -v -t nfs -o : ``` diff --git a/website/content/docs/synced-folders/rsync.mdx b/website/content/docs/define/synced-folders/rsync.mdx similarity index 100% rename from website/content/docs/synced-folders/rsync.mdx rename to website/content/docs/define/synced-folders/rsync.mdx diff --git a/website/content/docs/synced-folders/smb.mdx b/website/content/docs/define/synced-folders/smb.mdx similarity index 100% rename from website/content/docs/synced-folders/smb.mdx rename to website/content/docs/define/synced-folders/smb.mdx diff --git a/website/content/docs/synced-folders/virtualbox.mdx b/website/content/docs/define/synced-folders/virtualbox.mdx similarity index 100% rename from website/content/docs/synced-folders/virtualbox.mdx rename to website/content/docs/define/synced-folders/virtualbox.mdx diff --git a/website/content/docs/vagrantfile/tips.mdx b/website/content/docs/define/tips.mdx similarity index 100% rename from website/content/docs/vagrantfile/tips.mdx rename to website/content/docs/define/tips.mdx diff --git a/website/content/docs/define/triggers.mdx b/website/content/docs/define/triggers.mdx new file mode 100644 index 00000000000..7eb2a80f80a --- /dev/null +++ b/website/content/docs/define/triggers.mdx @@ -0,0 +1,265 @@ +--- +layout: docs +page_title: Vagrant Triggers +description: Introduction to Vagrant Triggers +--- + +# Vagrant Triggers + +As of version 2.1.0, Vagrant is capable of executing machine triggers _before_ or _after_ Vagrant commands. + +Each trigger is expected to be given a command key for when it should be fired during the Vagrant command lifecycle. These could be defined as a single key or an array which acts like a _whitelist_ for the defined trigger. + +```ruby +# single command trigger +config.trigger.after :up do |trigger| +... +end + +# multiple commands for this trigger +config.trigger.before [:up, :destroy, :halt, :package] do |trigger| +... +end + +# or defined as a splat list +config.trigger.before :up, :destroy, :halt, :package do |trigger| +... +end +``` + +Alternatively, the key `:all` could be given which would run the trigger before or after every Vagrant command. If there is a command you don't want the trigger to run on, you can ignore that command with the `ignore` option. + +```ruby +# single command trigger +config.trigger.before :all do |trigger| + trigger.info = "Running a before trigger!" + trigger.ignore = [:destroy, :halt] +end +``` + +If you define a trigger on a command that does not exist, Vagrant will display a warning. + +You can define triggers as a block or hash in a Vagrantfile. The following example defines the same trigger. + +```ruby +config.trigger.after :up do |trigger| + trigger.name = "Finished Message" + trigger.info = "Machine is up!" +end + +config.trigger.after :up, + name: "Finished Message", + info: "Machine is up!" +``` + +You can also define triggers within the scope of guests in a Vagrantfile. These triggers will only run on the configured guest. The following example defines a guest-only trigger. + +```ruby +config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + ubuntu.trigger.before :destroy do |trigger| + trigger.warn = "Dumping database to /vagrant/outfile" + trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} + end +end +``` + +Vagrant will trigger global and machine-scoped triggers in the order that they are defined within a Vagrantfile. The following example shows an abstracted Vagrantfile. In this example, Vagrant will trigger the triggers in the following order: `1` -> `2` -> `3` -> `4`. + +```ruby +Vagrantfile + global trigger 1 + global trigger 2 + machine defined + machine trigger 3 + global trigger 4 +end +``` + +For more information about what options are available for triggers, refer to the [`config.trigger` configuration](/vagrant/docs/triggers/configuration) documentation. + +## Examples + +The following examples show how to use triggers. + +### Global triggers before and after vagrant up + +The following example shows two global triggers: one that runs before the `:up` command and one that runs after the `:up` command. These will run before and after each defined guest in the Vagrantfile. + +```ruby +Vagrant.configure("2") do |config| + config.trigger.before :up do |trigger| + trigger.name = "Hello world" + trigger.info = "I am running before vagrant up!!" + end + + config.trigger.after :up do |trigger| + trigger.name = "Hello world" + trigger.info = "I am running after vagrant up!!" + end + + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + end +end +``` + +### Save a database on your host before destroying a guest + +The following example shows a global trigger that runs before the `destroy` command. This trigger will run a remote script to save a database on your host before destroying a guest. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.before :destroy do |trigger| + trigger.warn = "Dumping database to /vagrant/outfile" + trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} + end + end +end +``` + +Now that the trigger is defined, Vagrant will run the trigger before destroying the machine. + +```shell-session +$ vagrant destroy ubuntu +``` + +### Start and stop tinyproxy on your host machine using homebrew + +The following example shows how to define three triggers that start and stop tinyproxy on your host machine. + + + + + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.before :up do |trigger| + trigger.info = "Starting tinyproxy..." + trigger.run = {path: "start-tinyproxy.sh"} + end + + ubuntu.trigger.after :destroy, :halt do |trigger| + trigger.info = "Stopping tinyproxy..." + trigger.run = {path: "stop-tinyproxy.sh"} + end + end +end +``` + + + + + +```shell +#/bin/bash +brew services start tinyproxy +``` + + + + + +```shell +#/bin/bash +# stop-tinyproxy.sh +brew services stop tinyproxy +``` + + + + + + +### Define triggers with Ruby + +You can also define triggers to run Ruby, rather than bash or PowerShell. The following example shows how to use a Ruby option to get more information from the `VBoxManage` tool. In this example, the trigger prints the `ostype` defined for the guest after Vagrant starts it. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.after :up do |trigger| + trigger.info = "More information with ruby magic" + trigger.ruby do |env,machine| + puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype` + end + end + end +end +``` + +If you want to define your triggers using the hash syntax, you must use the `Proc` type for defining a Ruby trigger. + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.after :up, + info: "More information with ruby magic", + ruby: proc{|env,machine| puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype`} + end +end +``` + +### Use typed triggers + +The following examples show how to use `:type` triggers. These examples cover commands, hooks, and actions. Command triggers are the most commonly used type, while action and hook triggers are more advanced and complex use cases. + +The most common use case for typed triggers are with `command`. These kinds of triggers let you run something before or after a subcommand in Vagrant. Because they are specifically for subcommands, they do not work with any guest operations like `run_remote` or if you define the trigger as a guest trigger. + +```ruby +config.trigger.after :status, type: :command do |t| + t.info = "Showing status of all VMs!" +end +``` + +The following example shows a Vagrant trigger that runs before and after each defined provisioner. + +```ruby +config.trigger.before :provisioner_run, type: :hook do |t| + t.info = "Before the provision!" +end + +config.vm.provision "file", source: "scripts/script.sh", destination: "/test/script.sh" + +config.vm.provision "shell", inline: <<-SHELL +echo "Provision the guest!" +SHELL +``` + +This trigger runs before _each_ provisioner defined for the guest. + + + +```shell +==> guest: Running provisioner: Sandbox (file)... +==> vagrant: Running hook triggers before provisioner_run ... +==> vagrant: Running trigger... +==> vagrant: Before the provision! + guest: /home/hashicorp/vagrant-sandbox/scripts/script.sh => /home/vagrant/test/script.sh +==> guest: Running provisioner: shell... +==> vagrant: Running hook triggers before provisioner_run ... +==> vagrant: Running trigger... +==> vagrant: Before the provision! + guest: Running: inline script + guest: Provision the guest! +``` + + + +With action typed triggers, you can fire off triggers before or after certain Action classes. The following example shows a trigger that warns the user when Vagrant invokes the `GracefulHalt` action. + +```ruby +config.trigger.before :"Vagrant::Action::Builtin::GracefulHalt", type: :action do |t| + t.warn = "Vagrant is halting your guest..." +end +``` diff --git a/website/content/docs/plugins/action-hooks.mdx b/website/content/docs/develop-plugin/action-hooks.mdx similarity index 89% rename from website/content/docs/plugins/action-hooks.mdx rename to website/content/docs/develop-plugin/action-hooks.mdx index ceb5328e8fb..4ffa053c0de 100644 --- a/website/content/docs/plugins/action-hooks.mdx +++ b/website/content/docs/develop-plugin/action-hooks.mdx @@ -9,13 +9,13 @@ description: |- # Action Hooks -Action hooks provide ways to interact with Vagrant at a very low level by -injecting middleware in various phases of Vagrant's lifecycle. This is an -advanced option, even for plugin development. +Action hooks provide ways to interact with Vagrant at a very low level by injecting middleware in various phases of Vagrant's lifecycle. This is an advanced option, even for plugin development. -~> **Warning: Advanced Topic!** Developing plugins is an -advanced topic that only experienced Vagrant users who are reasonably -comfortable with Ruby should approach. + + +Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach. + + ## Public Action Hooks diff --git a/website/content/docs/develop-plugin/commands.mdx b/website/content/docs/develop-plugin/commands.mdx new file mode 100644 index 00000000000..8e8dea23997 --- /dev/null +++ b/website/content/docs/develop-plugin/commands.mdx @@ -0,0 +1,101 @@ +--- +layout: docs +page_title: Command Plugins - Plugin Development +description: |- + This page documents how to add new commands to Vagrant, invocable + via "vagrant YOUR-COMMAND". Prior to reading this, you should be familiar + with the plugin development basics. +--- + +# Plugin Development: Commands + +This page documents how to add new commands to Vagrant, invocable via `vagrant YOUR-COMMAND`. Prior to reading this, you should be familiar with the [plugin development basics](/vagrant/docs/plugins/development-basics). + + + +Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach. + + + +## Definition Component + +Within the context of a plugin definition, new commands can be defined like so: + +```ruby +command "foo" do + require_relative "command" + Command +end +``` + +Commands are defined with the `command` method, which takes as an argument the name of the command, in this case "foo." This means the command will be invocable via `vagrant foo`. Then the block argument returns a class that implements the `Vagrant.plugin(2, "command")` interface. + +You can also define _non-primary commands_. These commands do not show up in the `vagrant -h` output. They only show up if the user explicitly does a `vagrant list-commands` which shows the full listing of available commands. This is useful for highly specific commands or plugins that a beginner to Vagrant would not be using anyways. Vagrant itself uses non-primary commands to expose some internal functions, as well. + +To define a non-primary command: + +```ruby +command("foo", primary: false) do + require_relative "command" + Command +end +``` + +## Implementation + +Implementations of commands should subclass `Vagrant.plugin(2, :command)`, which is a Vagrant method that will return the proper superclass for a version 2 command. The implementation itself is quite simple, since the class needs to only implement a single method: `execute`. Example: + +```ruby +class Command < Vagrant.plugin(2, :command) + def execute + puts "Hello!" + 0 + end +end +``` + +The `execute` method is called when the command is invoked, and it should return the exit status (0 for success, anything else for error). + +This is a command at its simplest form. Of course, the command superclass gives you access to the Vagrant environment and provides some helpers to do common tasks such as command line parsing. + +## Parsing Command-Line Options + +The `parse_options` method is available which will parse the command line for you. It takes an [OptionParser](http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html) as an argument, and adds some common elements to it such as the `--help` flag, automatically showing help if requested. View the API docs directly for more information. + +This is recommended over raw parsing/manipulation of command line flags. The following is an example of parsing command line flags pulled directly from the built-in Vagrant `destroy` command: + +```ruby +options = {} +options[:force] = false + +opts = OptionParser.new do |o| + o.banner = "Usage: vagrant destroy [vm-name]" + o.separator "" + + o.on("-f", "--force", "Destroy without confirmation.") do |f| + options[:force] = f + end +end + +# Parse the options +argv = parse_options(opts) +``` + +## Using Vagrant Machines + +The `with_target_vms` method is a helper that helps you interact with the machines that Vagrant manages in a standard Vagrant way. This method automatically does the right thing in the case of multi-machine environments, handling target machines on the command line (`vagrant foo my-vm`), etc. If you need to do any manipulation of a Vagrant machine, including SSH access, this helper should be used. + +An example of using the helper, again pulled directly from the built-in `destroy` command: + +```ruby +with_target_vms(argv, reverse: true) do |machine| + machine.action(:destroy) +end +``` + +In this case, it asks for the machines in reverse order and calls the destroy action on each of them. If a user says `vagrant destroy foo`, then the helper automatically only yields the `foo` machine. If no parameter is given and it is a multi-machine environment, every machine in the environment is yielded, and so on. It just does the right thing. + +## Using the Raw Vagrant Environment + +The raw loaded `Vagrant::Environment` object is available with the +'@env' instance variable. diff --git a/website/content/docs/plugins/configuration.mdx b/website/content/docs/develop-plugin/configuration.mdx similarity index 100% rename from website/content/docs/plugins/configuration.mdx rename to website/content/docs/develop-plugin/configuration.mdx diff --git a/website/content/docs/plugins/go-plugins/guests.mdx b/website/content/docs/develop-plugin/go-plugins/guests.mdx similarity index 73% rename from website/content/docs/plugins/go-plugins/guests.mdx rename to website/content/docs/develop-plugin/go-plugins/guests.mdx index f594f1f42c0..400f410e11d 100644 --- a/website/content/docs/plugins/go-plugins/guests.mdx +++ b/website/content/docs/develop-plugin/go-plugins/guests.mdx @@ -23,7 +23,9 @@ template and follow the Readme. The file structure of a guest plugin looks like: -``` + + +```text - myplugin |- main.go \- guest @@ -32,39 +34,41 @@ The file structure of a guest plugin looks like: |- mycapability.go ``` + + Where `main.go` defines the plugin options. `guest/myguest.go` defines the core plugin functionality including the detection of the guest. `cap/*` has the definitions of all the guest plugin capabilities. These capabilities are the same as those for [Ruby plugins](/vagrant/docs/plugins/guest-capabilities). -## Writing a guest plugin +## Write a guest plugin -A guest must satisfy the interface defined for a guest component +A guest must satisfy the interface defined for a guest component. Refer to the [component.go](https://github.com/hashicorp/vagrant-plugin-sdk/blob/main/component/component.go) file for the source code. -``` + + +```go GuestDetectFunc() interface{} ParentFunc() interface{} HasCapabilityFunc() interface{} CapabilityFunc(capName string) interface{} ``` -Src: https://github.com/hashicorp/vagrant-plugin-sdk/blob/main/component/component.go -`GuestDetectFunc`: returns a function that defines the code that determines if the guest is - detected. The returned function must return a `bool`. + -`ParentFunc`: returns a function that defines the code that determines the most immediate parent - plugin. A child plugin will inherit all the capabilities defined in the parent. The - returned function must return a `string`. +- `GuestDetectFunc` returns a function that defines the code that determines if the guest is detected. The returned function must return a `bool`. -`HasCapabilityFunc`: returns a function that defines a lookup for a capability. The returned - function must return an `bool`. +- `ParentFunc` returns a function that defines the code that determines the most immediate parent plugin. A child plugin will inherit all the capabilities defined in the parent. The returned function must return a `string`. -`CapabilityFunc`: returns a capability function that is defined by the plugin registered by a given name. +- `HasCapabilityFunc` returns a function that defines a lookup for a capability. The returned function must return an `bool`. -An example guest plugin +- `CapabilityFunc` returns a capability function that is defined by the plugin registered by a given name. -``` -// file: myplugin/guest/myguest.go +An example guest plugin. + + + +```go package guest import ( @@ -115,8 +119,13 @@ var ( ) ``` -``` -// file: myplugin/main.go + + +In this example, the guest plugin will always be detected. It does not define any capabilities or have any parent plugins. + + + +```go package myplugin import ( @@ -138,19 +147,20 @@ func main() { } ``` -In this example, the guest plugin will always be detected. It does not define any -capabilities, or have any parent plugins. + -### Defining and registering guest capabilities +### Define and register guest capabilities A guest plugin may have capabilities two ways: + 1. By defining and implementing the capability in the plugin -2. By inheriting the capability from a parent guest plugin +1. By inheriting the capability from a parent guest plugin -Define a capability by writing out a function that returns the desired capability +Define a capability by writing out a function that returns the desired capability. -``` -// file: myplugin/guest/cap/mycapability.go + + +```go package cap import ( @@ -169,10 +179,13 @@ func WriteHello(trm terminal.UI) error { } ``` -Make the capability available to the plugin by filling in the capability functions + -``` -myplugin/guest/myguest.go +Make the capability available to the plugin by filling in the capability functions. + + + +```go // HasCapabilityFunc implements component.Guest func (h *AlwaysTrueGuest) HasCapabilityFunc() interface{} { return h.CheckCapability @@ -198,16 +211,13 @@ func (h *AlwaysTrueGuest) WriteHelloCap(ui terminal.UI) error { } ``` -A guest plugin may inherit the capabilities of a parent function by defining -a parent in the plugin implementation. This is done by setting the return -value of the `Parent` function to the name of the desired parent plugin. Go -based guest plugins may use Ruby based plugins as their parent. + -``` -// file: myplugin/guest/myguest.go +A guest plugin may inherit the capabilities of a parent function by defining a parent in the plugin implementation. This is done by setting the return value of the `Parent` function to the name of the desired parent plugin. Go based guest plugins may use Ruby based plugins as their parent. -... - + + +```go // ParentsFunc implements component.Guest func (h *AlwaysTrueGuest) ParentFunc() interface{} { return h.Parent @@ -220,3 +230,5 @@ func (h *AlwaysTrueGuest) Parent() string { return "debian" } ``` + + diff --git a/website/content/docs/plugins/go-plugins/index.mdx b/website/content/docs/develop-plugin/go-plugins/index.mdx similarity index 100% rename from website/content/docs/plugins/go-plugins/index.mdx rename to website/content/docs/develop-plugin/go-plugins/index.mdx diff --git a/website/content/docs/plugins/guest-capabilities.mdx b/website/content/docs/develop-plugin/guest-capabilities.mdx similarity index 100% rename from website/content/docs/plugins/guest-capabilities.mdx rename to website/content/docs/develop-plugin/guest-capabilities.mdx diff --git a/website/content/docs/plugins/guests.mdx b/website/content/docs/develop-plugin/guests.mdx similarity index 100% rename from website/content/docs/plugins/guests.mdx rename to website/content/docs/develop-plugin/guests.mdx diff --git a/website/content/docs/plugins/host-capabilities.mdx b/website/content/docs/develop-plugin/host-capabilities.mdx similarity index 100% rename from website/content/docs/plugins/host-capabilities.mdx rename to website/content/docs/develop-plugin/host-capabilities.mdx diff --git a/website/content/docs/plugins/hosts.mdx b/website/content/docs/develop-plugin/hosts.mdx similarity index 100% rename from website/content/docs/plugins/hosts.mdx rename to website/content/docs/develop-plugin/hosts.mdx diff --git a/website/content/docs/plugins/development-basics.mdx b/website/content/docs/develop-plugin/index.mdx similarity index 100% rename from website/content/docs/plugins/development-basics.mdx rename to website/content/docs/develop-plugin/index.mdx diff --git a/website/content/docs/plugins/packaging.mdx b/website/content/docs/develop-plugin/packaging.mdx similarity index 100% rename from website/content/docs/plugins/packaging.mdx rename to website/content/docs/develop-plugin/packaging.mdx diff --git a/website/content/docs/plugins/providers.mdx b/website/content/docs/develop-plugin/providers.mdx similarity index 100% rename from website/content/docs/plugins/providers.mdx rename to website/content/docs/develop-plugin/providers.mdx diff --git a/website/content/docs/plugins/provisioners.mdx b/website/content/docs/develop-plugin/provisioners.mdx similarity index 100% rename from website/content/docs/plugins/provisioners.mdx rename to website/content/docs/develop-plugin/provisioners.mdx diff --git a/website/content/docs/disks/hyperv/common-issues.mdx b/website/content/docs/disks/hyperv/common-issues.mdx deleted file mode 100644 index 6c16a22b12a..00000000000 --- a/website/content/docs/disks/hyperv/common-issues.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: docs -page_title: Common Issues - Disks Hyper-V Provider -description: |- - This page lists some common issues people run into with Vagrant and Hyper-V - as well as solutions for those issues. ---- - -# Common Issues and Troubleshooting - -This page lists some common issues people run into with Vagrant and Hyper-V -as well as solutions for those issues. - -## Are my disks attached? - -A handy way to figure out what disks are attached (or not attached) to your guest -is to open up the Hyper-V GUI and select the guest. When selecting a guest on the GUI, -it should open more information about the guest, including storage information. Here -you should see a list of disks attached to your guest. - -## Applying Vagrant disk configuration changes to guests - -Due to how Hyper-V works, you must reload your guest for any disk config changes -to be applied. So if you update your Vagrantfile to update or even remove disks, make -sure to `vagrant reload` your guests for these changes to be applied. diff --git a/website/content/docs/disks/hyperv/index.mdx b/website/content/docs/disks/hyperv/index.mdx deleted file mode 100644 index d206d8cc01b..00000000000 --- a/website/content/docs/disks/hyperv/index.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: docs -page_title: Disks for Hyper-V Provider -description: |- - Vagrant comes with support out of the box for Hyper-V, a free, - cross-platform consumer virtualization product. ---- - -# Hyper-V - -Because of how Hyper-V handles disk management, a Vagrant guest _must_ be powered -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. - -For more information on how to use Hyper-V to configure disks for a guest, refer -to the [general usage](/vagrant/docs/disks/usage) and [configuration](/vagrant/docs/disks/configuration) -guide for more information. diff --git a/website/content/docs/disks/hyperv/usage.mdx b/website/content/docs/disks/hyperv/usage.mdx deleted file mode 100644 index 9378ccf0dca..00000000000 --- a/website/content/docs/disks/hyperv/usage.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: docs -page_title: Usage - Disks Hyper-V Provider -description: |- - The Vagrant Hyper-V provider is used just like any other provider. Please - read the general basic usage page for providers. ---- - -# Usage - -For examples of how to use the disk feature with Hyper-V, please refer to the -[general disk usage guide](/vagrant/docs/disks/usage) for more examples. - -## provider_config options - -Most options are used for either creating or attaching a hard disk to your guest. -Vagrant supports most options for these operations. You should be able to define -the PowerShell specific argument to a given Hyper-V command in the provider_config -hash, and Vagrant should properly pass it along to the command. - -To define a provider specific option, please refer to the [Disk Options documentation page](/vagrant/docs/disks/configuration) for more info. - -### Note about options defined below - -It is possible these options could be out of date or stale. If you happen to see -an option that has changed or is missing from this page, please open an issue -or pull request on Vagrants GitHub page to correct this. - -### New-VHD Supported Options - -For more information about each option, please visit the [New-VHD Hyper-V documentation](https://docs.microsoft.com/en-us/powershell/module/hyper-v/new-vhd?view=win10-ps). - -**Note:** By default, all Hyper-V disks are defined as a Dynamic virtual hard disk. If you -wish to make the disk a fixed size, you can set the `Fixed` option below when creating -a new disk. - -- `BlockSizeBytes` (string) - Optional argument, i.e. `"128MB"` -- `Differencing` (bool) - If set, the disk will be used to store differencing changes from parent disk (must set `ParentPath`) -- `Fixed` (bool) - If set, the disk will be a fixed size, not dynamically allocated. -- `LogicalSectorSizeBytes` (int) - Optional argument, must be either `512` or `4096` -- `ParentPath` (string) - The parent disk path used if a `Differencing` disk is defined -- `PhysicalSectorSizeBytes` (string) - Optional argument, must be either `512` or `4096` -- `SourceDisk` (int) - Existing disk to use as a source for the new disk - -### Add-VMHardDiskDrive Supported Options - -For more information about each option, please visit the [Add-VMHardDiskDrive Hyper-V documentation](https://docs.microsoft.com/en-us/powershell/module/hyper-v/add-vmharddiskdrive?view=win10-ps) - -Generally, these options do not need to be set or handled by most users. Only -use these options if you are sure you know what you are doing. Vagrant will -be able to attach disks for you without these options, but they are available -if it is required that you specify a specific location for a disk. - -- `ControllerLocation` (int) - The location that the disk should be attached to on the controller -- `ControllerNumber` (int) - The controller to use for attaching the disk -- `ControllerType` (string) - The kind of controller to use when attaching the a disk. Only `"IDE"` and `"SCSI"` are valid. diff --git a/website/content/docs/disks/index.mdx b/website/content/docs/disks/index.mdx deleted file mode 100644 index ceac80ce24d..00000000000 --- a/website/content/docs/disks/index.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: docs -page_title: Vagrant Disks -description: Introduction to Vagrant Disks ---- - -# Vagrant Disks - -Vagrant Disks is a feature that allows users to define what mediums should be attached -to their guests, as well as allowing users to resize their primary disk. - -For examples on how to achieve this, among other use cases, please refer to the [usage](/vagrant/docs/disks/usage) -guide for more information! - -For more information about what options are available for configuring disks, see the -[configuration section](/vagrant/docs/disks/configuration). - -## Supported Providers - -Currently, only VirtualBox is supported. Please refer to the [VirtualBox documentation](/vagrant/docs/disks/virtualbox) for more information on using disks with the VirtualBox provider! diff --git a/website/content/docs/disks/usage.mdx b/website/content/docs/disks/usage.mdx deleted file mode 100644 index f5c66b390e3..00000000000 --- a/website/content/docs/disks/usage.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -layout: docs -page_title: Vagrant Disk Usage -description: Various Vagrant Disk examples ---- - -# Basic Usage - -Below are some very simple examples of how to use Vagrant Disks with the VirtualBox provider. - -## Basic Examples - -### Resizing your primary disk - -Sometimes, the primary disk for a guest is not large enough and you will need to -add more space. To resize a disk, you can simply add a config like this below -to expand the size of your guests drive: - -```ruby -config.vm.disk :disk, size: "100GB", primary: true -``` - -Note: the `primary: true` is what tells Vagrant to expand the guests main drive. -Without this option, Vagrant will instead attach a _new_ disk to the guest. - -For example, this Ubuntu guest will now come with 100GB of space, rather than the default: - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "hashicorp" do |h| - h.vm.box = "hashicorp/bionic64" - h.vm.provider :virtualbox - - h.vm.disk :disk, size: "100GB", primary: true - end -end -``` - -It should be noted that due to how VirtualBox functions, it is not possible to shrink -the size of a disk. - -### 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: - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "hashicorp" do |h| - h.vm.box = "hashicorp/bionic64" - h.vm.provider :virtualbox - - h.vm.disk :disk, size: "10GB", name: "extra_storage" - end -end -``` - -Optionally, if you need to attach many disks, you can use Ruby to generate multiple -disks for Vagrant to create and attach to your guest: - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "hashicorp" do |h| - h.vm.box = "hashicorp/bionic64" - h.vm.provider :virtualbox - - (0..3).each do |i| - h.vm.disk :disk, size: "5GB", name: "disk-#{i}" - end - end -end -``` - -Note: VirtualBox has a hard limit on the number of disks that can be attached -to a given storage controller, which is defined by the controller type. -Attempting to configure more disks than are supported by the primary -controller 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 -``` - -As with hard disks, configuring more disks than are supported by your VM's -storage controller arrangement will result in a Vagrant error. - -### 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:** Removing virtual hard disks created by Vagrant will -also delete the medium from your hard drive. diff --git a/website/content/docs/disks/virtualbox/common-issues.mdx b/website/content/docs/disks/virtualbox/common-issues.mdx deleted file mode 100644 index 83bd6560e80..00000000000 --- a/website/content/docs/disks/virtualbox/common-issues.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: docs -page_title: Common Issues - Disks VirtualBox Provider -description: |- - This page lists some common issues people run into with Vagrant and VirtualBox - as well as solutions for those issues. ---- - -# Common Issues and Troubleshooting - -This page lists some common issues people run into with Vagrant and VirtualBox -as well as solutions for those issues. - -## Are my disks attached? - -A handy way to figure out what disks are attached (or not attached) to your guest -is to open up the VirtualBox GUI and select the guest. When selecting a guest on the GUI, -it should open more information about the guest, including storage information. Here -you should see a list of disks attached to your guest. - -## How many disks can I attach? - -Vagrant attaches all new disks defined to guest's primary controller. As of -VirtualBox 6.1.x, storage controllers have the following limits to the number -of disks that are supported per guest: - -- IDE Controllers: 4 -- SATA Controllers: 30 -- SCSI Controllers: 16 - -Therefore if your primary disk is attached to a SATA Controller and you try to -define and attach more than 30, it will result in an error. This number -_includes_ the primary disk for the guest. - -DVD attachments are subject to the same limits. Optical disk attachments will -be attached to the storage controller with the highest boot priority (usually -the IDE controller). - -## Resizing VMDK format disks - -VMDK disks cannot be resized in their current state, so Vagrant will automatically -convert these disks to VDI, resize the disk, and convert it back to its original format. -Many Vagrant boxes default to using the VMDK disk format, so resizing disks for -many users will require Vagrant to convert these disks. Generally, this will be transparent -to the user. However if Vagrant crashes or if a user interrupts Vagrant during the -cloning process, there is a chance that you might lose your data. - -## Applying Vagrant disk configuration changes to guests - -Due to how VirtualBox works, you must reload your guest for any disk config changes -to be applied. So if you update your Vagrantfile to update or even remove disks, make -sure to `vagrant reload` your guests for these changes to be applied. diff --git a/website/content/docs/disks/virtualbox/index.mdx b/website/content/docs/disks/virtualbox/index.mdx deleted file mode 100644 index c1f1e3d0111..00000000000 --- a/website/content/docs/disks/virtualbox/index.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: docs -page_title: Disks for VirtualBox Provider -description: |- - Vagrant comes with support out of the box for VirtualBox, a free, - cross-platform consumer virtualization product. ---- - -# VirtualBox - -**Vagrant currently only supports VirtualBox version 5.x and newer for configuring and -attaching disks.** - -Because of how VirtualBox handles disk management, a Vagrant guest _must_ be powered -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 attach -disks to a particular storage controller based on the type of disk configured: - -- For the `:disk` type, Vagrant will use the storage controller containing the - boot disk. It will also create the disk if necessary. -- For the `:dvd` type, Vagrant will attach the disk to the storage controller - that comes earliest in the machine's boot order. For example, if a VM has a - SATA controller and an IDE controller, the disk will be attached to the 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](/vagrant/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](/vagrant/docs/disks/usage) and [configuration](/vagrant/docs/disks/configuration) -guide for more information. diff --git a/website/content/docs/disks/virtualbox/usage.mdx b/website/content/docs/disks/virtualbox/usage.mdx deleted file mode 100644 index a8b70bc57aa..00000000000 --- a/website/content/docs/disks/virtualbox/usage.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: docs -page_title: Usage - Disks VirtualBox Provider -description: |- - The Vagrant VirtualBox provider is used just like any other provider. Please - read the general basic usage page for providers. ---- - -# Usage - -For examples of how to use the disk feature with VirtualBox, please refer to the -[general disk usage guide](/vagrant/docs/disks/usage) for more examples. - -## provider_config options - -Currently, there are no additional options supported for the `provider_config` option. -This page will be updated with any valid options as they become supported. diff --git a/website/content/docs/disks/vmware/common-issues.mdx b/website/content/docs/disks/vmware/common-issues.mdx deleted file mode 100644 index 6681571e228..00000000000 --- a/website/content/docs/disks/vmware/common-issues.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: docs -page_title: Common Issues - Disks VMware Provider -description: |- - HashiCorp develops an official VMware Fusion and VMware Workstation provider - for Vagrant. This provider allows Vagrant to power VMware based machines and - take advantage of the improved stability and performance that VMware software - offers. ---- - -# Common Issues and Troubleshooting - -This page lists some common issues people run into with Vagrant and VMware -as well as solutions for those issues. - -## Are my disks attached? - -A handy way to figure out what disks are attached (or not attached) to your guest -is to open up the VMware GUI and open up the guest settings and selecting the -disks options. - -## How many disks can I attach? - -Vagrant will attempt to attach all disks specified in the Vagrantfile. If more than -four `ide` type disks are specified, only the first four will be attached. - -## Applying Vagrant disk configuration changes to guests - -Due to how VMware works, you must reload your guest for any disk config changes -to be applied. So if you update your Vagrantfile to update or even remove disks, make -sure to `vagrant reload` your guests for these changes to be applied. Also note, that -Vagrant will not decrease the size of a disk. - -## Disk functionality with snapshots - -If snapshots exist for a VM, disk functionality will be limited. Vagrant will return -an error for any actions that are limited due to the existence of snapshots. In order -to restore functionality the snapshots must be removed. This can be done using the -[`vagrant snapshot delete`](/vagrant/docs/cli/snapshot) command. To delete all snapshots -for a VMware backed VM try `vagrant cap provider delete_all_snapshots --target `. -Note once a snapshot is deleted, it can not be restored. diff --git a/website/content/docs/disks/vmware/index.mdx b/website/content/docs/disks/vmware/index.mdx deleted file mode 100644 index 7bdb3ed8cb4..00000000000 --- a/website/content/docs/disks/vmware/index.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: docs -page_title: Disks for VMware Provider -description: |- - HashiCorp develops an official VMware Fusion and VMware Workstation provider - for Vagrant. This provider allows Vagrant to power VMware based machines and - take advantage of the improved stability and performance that VMware software - offers. ---- - -# VMware - -Because of how VMware handles disk management, a Vagrant guest _must_ be powered -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. - -For more information on how to use VMware to configure disks for a guest, refer -to the [general usage](/vagrant/docs/disks/usage) and [configuration](/vagrant/docs/disks/configuration) -guide for more information. diff --git a/website/content/docs/disks/vmware/usage.mdx b/website/content/docs/disks/vmware/usage.mdx deleted file mode 100644 index 45311febbc9..00000000000 --- a/website/content/docs/disks/vmware/usage.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: docs -page_title: Usage - Disks VMware Provider -description: |- - HashiCorp develops an official VMware Fusion and VMware Workstation provider - for Vagrant. This provider allows Vagrant to power VMware based machines and - take advantage of the improved stability and performance that VMware software - offers. ---- - -# Usage - -For examples of how to use the disk feature with VMWware, please refer to the -[general disk usage guide](/vagrant/docs/disks/usage) for more examples. - -## provider_config options - -Vagrant supports some additional VMWware specific options for specifying disk. - -To define a provider specific option, please refer to the [Disk Options documentation page](/vagrant/docs/disks/configuration) for more info. - -### Note about options defined below - -It is possible these options could be out of date or stale. If you happen to see -an option that has changed or is missing from this page, please open an issue -or pull request on Vagrants GitHub page to correct this. - -- `bus_type` (string) - Sets the bus type when attaching the disk. Possible options are `sata`, `ide`, and `scsi`. Defaults to `scsi` -- `adapter_type` (string) - Sets the adapter type when creating the disk. Possible options are `ide`, `buslogic` and `lsilogic`. Defaults to `lsilogic` diff --git a/website/content/docs/hcp/api/v1.mdx b/website/content/docs/hcp/api/v1.mdx new file mode 100644 index 00000000000..a8b632e8e71 --- /dev/null +++ b/website/content/docs/hcp/api/v1.mdx @@ -0,0 +1,1613 @@ +--- +layout: vagrant-cloud +page_title: Vagrant Cloud API (Version 1) +description: "Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application." +--- + +# Vagrant Cloud API (Version 1) + +## Using the API + +Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application. + +### Authentication + +Some API endpoints require authentication to create new resources, update or delete existing resources, or to read a private resource. + +Clients can authenticate using an authentication token. +The token can be passed to Vagrant Cloud one of two ways: + +1. (Preferred) Set the `Authorization` header to `"Bearer "` and the value of the authentication token. +2. Pass the authentication token as an `access_token` URL parameter (_NOTE_: deprecated). + +Examples below will set the header, but feel free to use whichever method is easier for your implementation. + +-> The `X-Atlas-Token` header is also supported for backwards-compatibility. + +### Request and Response Format + +Requests to Vagrant Cloud which include data attributes (`POST` or `PUT`/`PATCH`) should set the `Content-Type` header to `"application/json"`, and include a valid JSON body with the request. + +JSON responses may include an `errors` key, which will contain an array of error strings, as well as a `success` key. +For example: + +```json +{ + "errors": ["Resource not found!"], + "success": false +} +``` + +### Response Codes + +Vagrant Cloud may respond with the following response codes, depending on the status of the request and context: + +#### Success + +##### **200** OK + +##### **201** Created + +##### **204** No Content + +#### Client Errors + +##### **401** Unauthorized + +You do not have authorization to access the requested resource. + +##### **402** Payment Required + +You are trying to access a resource which is delinquent on billing. +Please contact the owner of the resource so that they can update their billing information. + +##### **403** Forbidden + +You are attempting to use the system in a way which is not allowed. +There could be required request parameters that are missing, or one of the parameters is invalid. +Please check the response `errors` key, and double-check the examples below for any discrepancies. + +##### **404** Not Found + +The resource you are trying to access does not exist. This may also be returned if you attempt to access a private resource that you don't have authorization to view. + +##### **422** Unprocessable Entity + +##### **429** Too Many Requests + +You are currently being rate-limited. Please decrease your frequency of usage or [contact support](/vagrant/intro/support) with a description of your use case so that we can consider creating an exception. + +#### Server Errors + +##### **500** Internal Server Error + +The server failed to respond to the request for an unknown reason. +Please [contact support](/vagrant/intro/support) with a description of the problem so that we can investigate. + +##### **503** Service Unavailable + +Vagrant Cloud is temporarily in maintenance mode. +Please check the [HashiCorp Status Site](http://status.hashicorp.com) for more information. + +## Creating a usable box from scratch + +-> This assumes that you have a valid Vagrant Cloud authentication token. You can [create one via the API](#create-a-token), or [create one on the Vagrant Cloud website](https://app.vagrantup.com/settings/security). + +In order to create a usable box on Vagrant Cloud, perform the following steps: + +1. [Create a new box](#create-a-box) +1. [Create a new version](#create-a-version) +1. [Create a new provider](#create-a-provider) +1. [Upload a box image for that provider](#upload-a-provider) +1. [Release the version](#release-a-version) + +#### Example Requests + + + + +```shell +# Create a new box +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data '{ "box": { "username": "myuser", "name": "test" } }' + +# Create a new version + +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data '{ "version": { "version": "1.2.3" } }' + +# Create a new provider + +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data '{ "provider": { "name": "virtualbox" } }' + +# Prepare the provider for upload/get an upload URL + +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + +# Extract the upload URL from the response (requires the jq command) + +upload_path=$(echo "$response" | jq .upload_path) + +# Perform the upload + +curl --request PUT "${upload_path}" --upload-file virtualbox-1.2.3.box + +# Release the version + +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release + +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +# Create a new box + +api.post "/api/v1/boxes", +json: { box: { username: "myuser", name: "test" } } + +# Create a new version + +api.post "/api/v1/box/myuser/test/versions", +json: { version: { version: "1.2.3" } } + +# Create a new provider + +api.post "/api/v1/box/myuser/test/version/1.2.3/providers", +json: { provider: { name: "virtualbox" } } + +# Prepare the provider for upload + +response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + +# Extract the upload URL + +upload_path = response.parse['upload_path'] + +# Upload the box image + +HTTP.put upload_path, body: File.open("virtualbox-1.2.3.box") + +# Release the version + +api.put("/api/v1/box/myuser/test/version/1.2.3/release") +``` + + + + +## Authentication + +### Create a token + +`POST /api/v1/authenticate` + +Creates a new token for the given user. + +#### Arguments + +- `token` +- `description` (Optional) - A description of the token. +- `two_factor` +- `code` - A two-factor authentication code. Required to use this API method if 2FA is enabled. See [Request a 2FA code](#request-a-2fa-code) if not using a TOTP application. +- `user` +- `login` - Username or email address of the user authenticating. +- `password` - The user's password. + +#### Example Request + + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + https://app.vagrantup.com/api/v1/authenticate \ + --data ' + { + "token": { + "description": "Login from cURL" + }, + "user": { + "login": "myuser", + "password": "secretpassword" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( +"Content-Type" => "application/json" +) + +response = api.post("/api/v1/authenticate", json: { + token: { description: "Login from Ruby" }, + user: { login: "myuser", password: "secretpassword" } +}) + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "description": "Login from cURL", + "token": "qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs", + "token_hash": "7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c", + "created_at": "2017-10-18T19:16:24.956Z" +} +``` + +### Validate a token + +`GET /api/v1/authenticate` + +Responds [`200 OK`](#200-ok) if the authentication request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/authenticate +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/authenticate") + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +### Delete a token + +`DELETE /api/v1/authenticate` + +Responds [`204 OK`](#204-no-content) if the deletion request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/authenticate +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v1/authenticate") + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +### Request a 2FA code + +`POST /api/v1/two-factor/request-code` + +Sends a 2FA code to the requested delivery method. + +#### Arguments + +- `two_factor` +- `delivery_method` - A valid 2FA delivery method. Currently only `sms` is supported. +- `user` +- `login` - Username or email address of the user authenticating. +- `password` - The user's password. + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + https://app.vagrantup.com/api/v1/two-factor/request-code \ + --data ' + { + "two_factor": { + "delivery_method": "sms" + }, + "user": { + "login": "myuser", + "password": "secretpassword" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json" +) + +response = api.post("/api/v1/two-factor/request-code", json: { + two_factor: { delivery_method: "sms" }, + user: { login: "myuser", password: "secretpassword" } +}) + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "two_factor": { + "obfuscated_destination": "SMS number ending in 7890" + } +} +``` + +## Organizations + +### Read an organization + +`GET /api/v1/user/:username` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/user/myuser +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/user/myuser") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "username": "myuser", + "avatar_url": "https://www.gravatar.com/avatar/130a640278870c3dada38b3d912ee022?s=460&d=mm", + "profile_html": "

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

\n", + "profile_markdown": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + "boxes": [] +} +``` + +## Search + +### Search for boxes + +`GET /api/v1/search` + +#### Arguments + +- `q` - (Optional) The search query. Results will match the `username`, `name`, or `short_description` fields for a box. If omitted, the top boxes based on `sort` and `order` will be returned (defaults to "downloads desc"). +- `provider` - (Optional) Filter results to boxes supporting for a specific provider. +- `sort` - (Optional, default: `"downloads"`) The field to sort results on. Can be one of `"downloads"`, `"created"`, or `"updated"`. +- `order` - (Optional, default: `"desc"`) The order to return the sorted field in. Can be `"desc"` os `"asc"`. +- `limit` - (Optional, default: `10`) The number of results to return (max of 100). +- `page` - (Optional, default: `1`) + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + "https://app.vagrantup.com/api/v1/search?q=test&provider=virtualbox" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/search", params: { + q: "test", + provider: "virtualbox" +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "boxes": [ + { + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + } + ] +} +``` + +## Boxes + +### Read a box + +`GET /api/v1/box/:username/:name` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/box/myuser/test") + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + }, + "versions": [ + { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + ] +} +``` + +### Create a box + +`POST /api/v1/boxes` + +#### Arguments + +- `box` + - `username` - The username of the organization that will own this box. + - `name` - The name of the box. + - `short_description` - A short summary of the box. + - `description` - A longer description of the box. Can be formatted with [Markdown][markdown]. + - `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data ' + { + "box": { + "username": "myuser", + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v1/boxes", json: { + box: { + username: "myuser", + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +### Update a box + +`PUT /api/v1/box/:username/:name` + +#### Arguments + +- `box` + - `name` - The name of the box. + - `short_description` - A short summary of the box. + - `description` - A longer description of the box. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + - `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test \ + --data ' + { + "box": { + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v1/box/myuser/test", json: { + box: { + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +### Delete a box + +`DELETE /api/v1/box/:username/:name` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v1/box/myuser/test") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +## Versions + +### Read a version + +`GET /api/v1/box/:username/:name/version/:version` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/box/myuser/test/version/1.2.3") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] +} +``` + +### Create a version + +`POST /api/v1/box/:username/:name/versions` + +-> New versions start as `unreleased`. You must create a valid provider before releasing a new version. + +#### Arguments + +- `version` + - `version` - The version number of this version. + - `description` - A description for this version. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v1/box/myuser/test/versions", json: { + version: { + version: "1.2.3", + description: "A new version" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Update a version + +`PUT /api/v1/box/:username/:name/version/1.2.3` + +#### Arguments + +- `version` + - `version` - The version number of this version. + - `description` - A description for this version. Can be formatted with [Markdown][markdown]. + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v1/box/myuser/test/version/1.2.3", json: { + version: { + name: "1.2.3", + description: "A new version" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Delete a version + +`DELETE /api/v1/box/:username/:name/version/:version` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v1/box/myuser/test/version/1.2.3") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Release a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/release` + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v1/box/myuser/test/version/1.2.3/release") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Revoke a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/revoke` + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v1/box/myuser/test/version/1.2.3/revoke") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +## Providers + +### Read a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box", + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5" +} +``` + +### Create a provider + +`POST /api/v1/box/:username/:name/version/:version/providers` + +#### Arguments + +- `provider` + - `name` - The name of the provider. + - `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + - `checksum` - Computed checksum of the box assets. When set, Vagrant will compute the checksum of the downloaded box asset and validate it matches this value. + - `checksum_type` - Type of checksum used. Currently supported values: md5, sha1, sha256, sha384, and sha512 + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data ' + { + "provider": { + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5", + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v1/box/myuser/test/version/1.2.3/providers", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Update a provider + +`PUT /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Arguments + +- `provider` + - `name` - The name of the provider. + - `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox \ + --data ' + { + "provider": { + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5", + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Delete a provider + +`DELETE /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Upload a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload` + +Prepares the provider for upload, and returns a JSON blob containing an `upload_path`. + +~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL. + +#### Example Request + + + + +```shell +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + +# Requires the jq command +upload_path=$(echo "$response" | jq .upload_path) + +curl \ + --request PUT \ + --upload-file virtualbox-1.2.3.box \ + "${upload_path}" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + +if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" +} +``` + +### Upload a provider directly to backend storage + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload/direct` + +Prepares the provider for upload. This version of the upload API allows uploading the box asset directly to the backend storage. It requires +a two step process for uploading the box assets. First uploading the asset to storage and then finalizing the upload within Vagrant Cloud +via a provided callback. + +The request returns a JSON blob containing two fields: + +- `upload_path` - URL to `PUT` the box asset +- `callback` - Vagrant Cloud callback URL to finalize upload + +The box asset is uploaded directly to the URL provided by the `upload_path` via a `PUT` request. Once complete, a `PUT` request to the URL +provided in the `callback` field (complete with authentication header) finalizes the upload. + +~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL. + +#### Example Request + + + + +```shell +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload/direct) + +# Requires the jq command +upload_path=$(echo "$response" | jq .upload_path) +callback=$(echo "$response" | jq .callback) + +curl \ + --request PUT \ + --upload-file virtualbox-1.2.3.box \ + "${upload_path}" + +curl + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + "${callback}" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" +require "uri" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + +if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + callback = response.parse['callback'] + # Upload the box asset + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") + # Finalize the upload + api.put(URI.parse(callback).path) +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "upload_path": "https://remote-storage.example.com/bucket/630e42d9-2364-2412-4121-18266770468e?auth=9023wqfda", + "callback": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload/direct/630e42d9-2364-2412-4121-18266770468e" +} +``` + +[markdown]: https://daringfireball.net/projects/markdown/syntax diff --git a/website/content/docs/hcp/api/v2.mdx b/website/content/docs/hcp/api/v2.mdx new file mode 100644 index 00000000000..b5ca5aca124 --- /dev/null +++ b/website/content/docs/hcp/api/v2.mdx @@ -0,0 +1,1437 @@ +--- +layout: vagrant-cloud +page_title: Vagrant Cloud API (Version 2) +description: "Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application." +--- + +# Vagrant Cloud API (Version 2) + +## Using the API + +Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application. + +### Authentication + +Some API endpoints require authentication to create new resources, update or delete existing resources, or to read a private resource. + +Clients can authenticate using an authentication token. +The token can be passed to Vagrant Cloud one of two ways: + +1. (Preferred) Set the `Authorization` header to `"Bearer "` and the value of the authentication token. +2. Pass the authentication token as an `access_token` URL parameter (_NOTE_: deprecated). + +Examples below will set the header, but feel free to use whichever method is easier for your implementation. + +-> The `X-Atlas-Token` header is also supported for backwards-compatibility. + +### Request and Response Format + +Requests to Vagrant Cloud which include data attributes (`POST` or `PUT`/`PATCH`) should set the `Content-Type` header to `"application/json"`, and include a valid JSON body with the request. + +JSON responses may include an `errors` key, which will contain an array of error strings, as well as a `success` key. +For example: + +```json +{ + "errors": ["Resource not found!"], + "success": false +} +``` + +### Response Codes + +Vagrant Cloud may respond with the following response codes, depending on the status of the request and context: + +#### Success + +##### **200** OK + +##### **201** Created + +##### **204** No Content + +#### Client Errors + +##### **401** Unauthorized + +You do not have authorization to access the requested resource. + +##### **402** Payment Required + +You are trying to access a resource which is delinquent on billing. +Please contact the owner of the resource so that they can update their billing information. + +##### **403** Forbidden + +You are attempting to use the system in a way which is not allowed. +There could be required request parameters that are missing, or one of the parameters is invalid. +Please check the response `errors` key, and double-check the examples below for any discrepancies. + +##### **404** Not Found + +The resource you are trying to access does not exist. This may also be returned if you attempt to access a private resource that you don't have authorization to view. + +##### **422** Unprocessable Entity + +##### **429** Too Many Requests + +You are currently being rate-limited. Please decrease your frequency of usage or [contact support](/vagrant/intro/support) with a description of your use case so that we can consider creating an exception. + +#### Server Errors + +##### **500** Internal Server Error + +The server failed to respond to the request for an unknown reason. +Please [contact support](/vagrant/intro/support) with a description of the problem so that we can investigate. + +##### **503** Service Unavailable + +Vagrant Cloud is temporarily in maintenance mode. +Please check the [HashiCorp Status Site](http://status.hashicorp.com) for more information. + +## Creating a usable box from scratch + +-> This assumes that you have a valid Vagrant Cloud authentication token. You can [create one via the API](#create-a-token), or [create one on the Vagrant Cloud website](https://app.vagrantup.com/settings/security). + +In order to create a usable box on Vagrant Cloud, perform the following steps: + +1. [Create a new box](#create-a-box) +1. [Create a new version](#create-a-version) +1. [Create a new provider](#create-a-provider) +1. [Upload a box image for that provider](#upload-a-provider) +1. [Release the version](#release-a-version) + +#### Example Requests + + + + +```shell +# Create a new box +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/boxes \ + --data '{ "box": { "username": "myuser", "name": "test" } }' + +# Create a new version + +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/versions \ + --data '{ "version": { "version": "1.2.3" } }' + +# Create a new provider + +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/providers \ + --data '{ "provider": { "name": "virtualbox" } }' + +# Prepare the provider for upload/get an upload URL + +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + +# Extract the upload URL from the response (requires the jq command) + +upload_path=$(echo "$response" | jq .upload_path) + +# Perform the upload + +curl --request PUT "${upload_path}" --upload-file virtualbox-1.2.3.box + +# Release the version + +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release + +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +# Create a new box + +api.post "/api/v2/boxes", +json: { box: { username: "myuser", name: "test" } } + +# Create a new version + +api.post "/api/v2/box/myuser/test/versions", +json: { version: { version: "1.2.3" } } + +# Create a new provider + +api.post "/api/v2/box/myuser/test/version/1.2.3/providers", +json: { provider: { name: "virtualbox" } } + +# Prepare the provider for upload + +response = api.get("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + +# Extract the upload URL + +upload_path = response.parse['upload_path'] + +# Upload the box image + +HTTP.put upload_path, body: File.open("virtualbox-1.2.3.box") + +# Release the version + +api.put("/api/v2/box/myuser/test/version/1.2.3/release") +``` + + + + +## Authentication + +### Validate a token + +`GET /api/v2/authenticate` + +Responds [`200 OK`](#200-ok) if the authentication request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/authenticate +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/authenticate") + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +## Organizations + +### Read an organization + +`GET /api/v2/user/:username` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/user/myuser +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/user/myuser") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "username": "myuser", + "avatar_url": "https://www.gravatar.com/avatar/130a640278870c3dada38b3d912ee022?s=460&d=mm", + "profile_html": "

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

\n", + "profile_markdown": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + "boxes": [] +} +``` + +## Search + +### Search for boxes + +`GET /api/v2/search` + +#### Arguments + +- `q` - (Optional) The search query. Results will match the `username`, `name`, or `short_description` fields for a box. If omitted, the top boxes based on `sort` and `order` will be returned (defaults to "downloads desc"). +- `architcture` (Optional) Filter results to boxes supporting a specific architecture. +- `provider` - (Optional) Filter results to boxes supporting for a specific provider. +- `sort` - (Optional, default: `"downloads"`) The field to sort results on. Can be one of `"downloads"`, `"created"`, or `"updated"`. +- `order` - (Optional, default: `"desc"`) The order to return the sorted field in. Can be `"desc"` os `"asc"`. +- `limit` - (Optional, default: `10`) The number of results to return (max of 100). +- `page` - (Optional, default: `1`) + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + "https://app.vagrantup.com/api/v2/search?q=test&provider=virtualbox" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/search", params: { + q: "test", + provider: "virtualbox" +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "boxes": [ + { + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + } + ] +} +``` + +## Boxes + +### Read a box + +`GET /api/v2/box/:username/:name` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/box/myuser/test") + +if response.status.success? # Success, the response attributes are available here. + p response.parse +else # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + }, + "versions": [ + { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + ] +} +``` + +### Create a box + +`POST /api/v2/boxes` + +#### Arguments + +- `box` + - `username` - The username of the organization that will own this box. + - `name` - The name of the box. + - `short_description` - A short summary of the box. + - `description` - A longer description of the box. Can be formatted with [Markdown][markdown]. + - `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/boxes \ + --data ' + { + "box": { + "username": "myuser", + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v2/boxes", json: { + box: { + username: "myuser", + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +### Update a box + +`PUT /api/v2/box/:username/:name` + +#### Arguments + +- `box` + - `name` - The name of the box. + - `short_description` - A short summary of the box. + - `description` - A longer description of the box. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + - `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test \ + --data ' + { + "box": { + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v2/box/myuser/test", json: { + box: { + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +### Delete a box + +`DELETE /api/v2/box/:username/:name` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v2/box/myuser/test") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +## Versions + +### Read a version + +`GET /api/v2/box/:username/:name/version/:version` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/box/myuser/test/version/1.2.3") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box", + "architecture": "amd64", + "default_architecture": true + } + ] +} +``` + +### Create a version + +`POST /api/v2/box/:username/:name/versions` + +-> New versions start as `unreleased`. You must create a valid provider before releasing a new version. + +#### Arguments + +- `version` + - `version` - The version number of this version. + - `description` - A description for this version. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/versions \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v2/box/myuser/test/versions", json: { + version: { + version: "1.2.3", + description: "A new version" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Update a version + +`PUT /api/v2/box/:username/:name/version/1.2.3` + +#### Arguments + +- `version` + - `version` - The version number of this version. + - `description` - A description for this version. Can be formatted with [Markdown][markdown]. + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3 \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v2/box/myuser/test/version/1.2.3", json: { + version: { + name: "1.2.3", + description: "A new version" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Delete a version + +`DELETE /api/v2/box/:username/:name/version/:version` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v2/box/myuser/test/version/1.2.3") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Release a version + +`PUT /api/v2/box/:username/:name/version/1.2.3/release` + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/release +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v2/box/myuser/test/version/1.2.3/release") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Revoke a version + +`PUT /api/v2/box/:username/:name/version/1.2.3/revoke` + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/revoke +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v2/box/myuser/test/version/1.2.3/revoke") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +## Providers + +### Read a provider + +`GET /api/v2/box/:username/:name/version/:version/provider/:provider/:architecture` + +#### Example Request + + + + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box", + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5", + "architecture": "amd64", + "default_architecture": true +} +``` + +### Create a provider + +`POST /api/v2/box/:username/:name/version/:version/providers` + +#### Arguments + +- `provider` + - `name` - The name of the provider. + - `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + - `checksum` - Computed checksum of the box assets. When set, Vagrant will compute the checksum of the downloaded box asset and validate it matches this value. + - `checksum_type` - Type of checksum used. Currently supported values: md5, sha1, sha256, sha384, and sha512 + - `architecture` - Architecture of the Vagrant box image. Currently supported values: amd64, i386, arm, arm64, ppc64le, ppc64, mips64le, mips64, mipsle, mips, and s390x + - `default_architecture` - Set as the default architecture to be used when no architecture information is provided + +#### Example Request + + + + +```shell +curl \ + --request POST \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/providers \ + --data ' + { + "provider": { + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5", + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box", + "architecture": "amd64", + "default_architecture": true + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.post("/api/v2/box/myuser/test/version/1.2.3/providers", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box", + architecture: "amd64", + default_architecture: true + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Update a provider + +`PUT /api/v2/box/:username/:name/version/:version/provider/:provider/:architecture` + +#### Arguments + +- `provider` + - `name` - The name of the provider. + - `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + - `checksum` - Computed checksum of the box assets. When set, Vagrant will compute the checksum of the downloaded box asset and validate it matches this value. + - `checksum_type` - Type of checksum used. Currently supported values: md5, sha1, sha256, sha384, and sha512 + - `architecture` - Architecture of the Vagrant box image. Currently supported values: amd64, i386, arm, arm64, ppc64le, ppc64, mips64le, mips64, mipsle, mips, and s390x + - `default_architecture` - Set as the default architecture to be used when no architecture information is provided + +#### Example Request + + + + +```shell +curl \ + --request PUT \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64 \ + --data ' + { + "provider": { + "checksum": "a59e7332e8bbe896f11f478fc61fa8a6", + "checksum_type": "md5", + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.put("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } +}) + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Delete a provider + +`DELETE /api/v2/box/:username/:name/version/:version/provider/:provider/:architecture` + +#### Example Request + + + + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64 +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.delete("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64") + +if response.status.success? + # Success, the response attributes are available here. + p response.parse +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Upload a provider + +`GET /api/v2/box/:username/:name/version/:version/provider/:provider/:architecture/upload` + +Prepares the provider for upload, and returns a JSON blob containing an `upload_path`. + +~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL. + +#### Example Request + + + + +```shell +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64/upload) + +# Requires the jq command +upload_path=$(echo "$response" | jq .upload_path) + +curl \ + --request PUT \ + --upload-file virtualbox-1.2.3.box \ + "${upload_path}" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64/upload") + +if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "upload_path": "https://archivist.hashicorp.com/v2/object/630e42d9-2364-2412-4121-18266770468e" +} +``` + +### Upload a provider directly to backend storage + +`GET /api/v2/box/:username/:name/version/:version/provider/:provider/:architecture/upload/direct` + +Prepares the provider for upload. This version of the upload API allows uploading the box asset directly to the backend storage. It requires +a two step process for uploading the box assets. First uploading the asset to storage and then finalizing the upload within Vagrant Cloud +via a provided callback. + +The request returns a JSON blob containing two fields: + +- `upload_path` - URL to `PUT` the box asset +- `callback` - Vagrant Cloud callback URL to finalize upload + +The box asset is uploaded directly to the URL provided by the `upload_path` via a `PUT` request. Once complete, a `PUT` request to the URL +provided in the `callback` field (complete with authentication header) finalizes the upload. + +~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL. + +#### Example Request + + + + +```shell +response=$(curl \ + --request GET \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64/upload/direct) + +# Requires the jq command +upload_path=$(echo "$response" | jq .upload_path) +callback=$(echo "$response" | jq .callback) + +curl \ + --request PUT \ + --upload-file virtualbox-1.2.3.box \ + "${upload_path}" + +curl + --request PUT \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + "${callback}" +``` + + + + +```ruby +# gem install http, or add `gem "http"` to your Gemfile +require "http" +require "uri" + +api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" +) + +response = api.get("/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64/upload") + +if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + callback = response.parse['callback'] + # Upload the box asset + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") + # Finalize the upload + api.put(URI.parse(callback).path) +else + # Error, inspect the `errors` key for more information. + p response.code, response.body +end +``` + + + + +#### Example Response + +```json +{ + "upload_path": "https://remote-storage.example.com/bucket/630e42d9-2364-2412-4121-18266770468e?auth=9023wqfda", + "callback": "https://app.vagrantup.com/api/v2/box/myuser/test/version/1.2.3/provider/virtualbox/amd64/upload/direct/630e42d9-2364-2412-4121-18266770468e" +} +``` + +[markdown]: https://daringfireball.net/projects/markdown/syntax diff --git a/website/content/docs/hcp/box/api-release-workflow.mdx b/website/content/docs/hcp/box/api-release-workflow.mdx new file mode 100644 index 00000000000..b9b24424065 --- /dev/null +++ b/website/content/docs/hcp/box/api-release-workflow.mdx @@ -0,0 +1,24 @@ +--- +layout: vagrant-cloud +page_title: API Release Workflow +description: "Automate box creation with the Vagrant Cloud API." +--- + +# API Release Workflow + +Creating new boxes through their [release lifecycle](/vagrant/vagrant-cloud/boxes/lifecycle) +is possible through the Vagrant Cloud website, but you can also automate +the task via the Vagrant Cloud API. + +1. Create box, or locate a boxes `tag`, like `hashicorp/bionic64` +2. After some event, like the end of a CI build, you may want to + release a new version of the box. To do this, first use the API to + create a new version with a version number and a short description + of the changes +3. Then, create any providers associated with the version, like + `virtualbox` +4. Once your system has made the necessary requests to the API and the + version is ready, make a request to the `release` endpoint on the version +5. The version should now be available to users of the box via + the command `vagrant box outdated` or via the automated checks on + `vagrant up` diff --git a/website/content/docs/hcp/box/create-version.mdx b/website/content/docs/hcp/box/create-version.mdx new file mode 100644 index 00000000000..a599d29df10 --- /dev/null +++ b/website/content/docs/hcp/box/create-version.mdx @@ -0,0 +1,37 @@ +--- +layout: vagrant-cloud +page_title: Create a New Box Version +description: "Create a new box version in the Vagrant Cloud UI." +--- + +# Create a new box version + +To release a new version of a box to the public or to your team: + +1. Click on the name of the box you want to release a new version for. + +2. To the right of the box name, there is a dropdown of all the available + versions. Click this, and click "Create a New Version" + +3. Enter details for your new version and click "Create Version." Note that + after clicking create version, the version is not yet _released_. + +4. Click "Create new provider" on this next page to add at least one + provider to the version. Specify the name of the provider (this is the + same value you specify to `--provider` when using Vagrant). Then + enter the URL to a self-hosted box file or upload a box to us. + +5. Once the provider is created, you now have the option to release the + version by clicking "Release now," or you can add more providers. + +Once you click "Release now," that version will be available for installation +with Vagrant. Before clicking this, Vagrant does not know the version even +exists. + +## Note about public boxes + +Be aware, when you create and upload a new version artifact on a public box in +Vagrant Cloud, even if that specific version has not been marked for "release", +it can be accessible if a user knows the box URL with the new version. Releasing +a box simply makes it publicly accessible through search, or through reference +using the `organization/box-name` syntax. diff --git a/website/content/docs/hcp/box/create.mdx b/website/content/docs/hcp/box/create.mdx new file mode 100644 index 00000000000..15e430a0415 --- /dev/null +++ b/website/content/docs/hcp/box/create.mdx @@ -0,0 +1,88 @@ +--- +layout: vagrant-cloud +page_title: Creating a New Vagrant Box +description: "Create and distribute new boxes to users." +--- + +# Creating a New Vagrant Box + +This page will cover creating a new box in Vagrant Cloud and how to distribute +it to users. Boxes can be distributed without Vagrant Cloud, but +miss out on several [important features](/vagrant/vagrant-cloud/boxes). + +There are **three ways to create and upload Vagrant Boxes to Vagrant Cloud**. All +three options are outlined below. + +We recommend using Packer, as it is fully repeatable and keeps a strong +history of changes within Vagrant Cloud. However, for some situations, including +legacy workflows, the Web UI or API will work well. + +All three options require you [sign up for Vagrant Cloud](https://vagrantcloud.com/account/new). + +## Create boxes with Packer + +Using Packer requires more up front effort, but the repeatable and +automated builds will end any manual management of boxes. Additionally, +all boxes will be stored and served from Vagrant Cloud, keeping a history along +the way. + +## Create boxes via the Vagrant Cloud Web Interface + +You'll first need to create a box file. This can be done via +the [vagrant `package` command](http://docs.vagrantup.com/v2/boxes/base) +or with Packer locally. + +After you've created the `.box` file, this guide can be followed. + +1. Go to the [Create Box](https://vagrantcloud.com/boxes/new) page. + +1. Name the box and give it a simple description + +1. Create your first version for the box. This version + must match the format `[0-9].[0-9].[0-9]` + +1. Create a provider for the box, matching the provider you need + locally in Vagrant. `virtualbox` is the most common provider. + +1. Upload the `.box` file for each provider, or use a url to the `.box` + file that is publicly accessible + +You can find all of your boxes in the [Vagrant section](https://vagrantcloud.com/vagrant) of Vagrant Cloud. + +Once you've created and released a box, you can release new versions of +the box by clicking "Create New Version" under the versions sidebar on +a box page. For more information on the release lifecycle of boxes, see +the [help page dedicated to box lifecycle](/vagrant/vagrant-cloud/boxes/lifecycle). + +## Create boxes with the API + +This example uses the API to upload boxes with `curl`. To get started, you'll +need to get an [access token](https://vagrantcloud.com/settings/security). + +Then, prepare the upload: + +```shell-session +$ curl 'https://vagrantcloud.com/api/v2/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_NAME/ARCHITECTURE_NAME/upload?access_token=ACCESS_TOKEN' +``` + +This should return something like this: + +```json +{ + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" +} +``` + +Then, upload your box with the following command, with the filename in this case being `foo.box`: + +```shell-session +$ curl -X PUT --upload-file foo.box https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e +``` + +When the upload finishes, you can verify it worked by making this request and matching the `hosted_token` it returns to the previously retrieved upload token. + +```shell-session +$ curl 'https://vagrantcloud.com/api/v2/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME/ARCHITECTURE_NAME?access_token=ACCESS_TOKEN' +``` + +Your box should then be available for download. diff --git a/website/content/docs/hcp/box/index.mdx b/website/content/docs/hcp/box/index.mdx new file mode 100644 index 00000000000..17d1b1f5750 --- /dev/null +++ b/website/content/docs/hcp/box/index.mdx @@ -0,0 +1,22 @@ +--- +layout: vagrant-cloud +page_title: About Vagrant Boxes +description: "Boxes are the package format for environments." +--- + +# Vagrant Boxes + +Boxes are the package format for [Vagrant](https://vagrantup.com/) environments. +A box can be used on any Vagrant-supported platform to bring up an identical +working environment across a development team. + +## Create and version Vagrant boxes + +Boxes support versioning so that members of your team using Vagrant can update +the underlying box easily, and the people who create boxes can push fixes and +communicate these fixes efficiently. + +Vagrant Cloud makes it easy to manage the versioning of boxes. Versioning boxes in +Vagrant Cloud allows for easy updates, transparent fixes, and clear communication in +changes made. Learn more about the [box release lifecycle +here](/vagrant/vagrant-cloud/boxes/lifecycle). \ No newline at end of file diff --git a/website/content/docs/hcp/box/lifecycle.mdx b/website/content/docs/hcp/box/lifecycle.mdx new file mode 100644 index 00000000000..a2509c47d0a --- /dev/null +++ b/website/content/docs/hcp/box/lifecycle.mdx @@ -0,0 +1,49 @@ +--- +layout: vagrant-cloud +page_title: Box Versioning and Lifecycle +description: "Boxes support versioning so that members of your team can update the underlying box efficiently." +--- + +# Box versioning and lifecycle + +Boxes support versioning so that members of your team using Vagrant can +update the underlying box easily, and the people who create boxes can +push fixes and communicate these fixes efficiently. + +There are multiple components of a box: + +- The box itself, comprised of the box name and description. +- One or more box versions. +- One or more providers for each box version. + +## Vagrant messaging + +Upon `vagrant up` or `vagrant box outdated`, an out-of-date box +user will see the following message in Vagrant: + +```log +Bringing machine 'default' up with 'virtualbox' provider... +==> default: Checking if box 'hashicorp/example' is up to date... +==> default: A newer version of the box 'hashicorp/example' is available! You currently +==> default: have version '0.0.5'. The latest is version '0.0.6'. Run +==> default: `vagrant box update` to update. +... +``` + +## Box version release states + +Vagrant Cloud lets you create new versions of boxes without +releasing them or without Vagrant seeing the update. This lets you prepare +a box for release slowly. Box versions have three states: + +- `unreleased`: Vagrant cannot see this version yet, so it needs + to be released. Versions can be released by editing them and clicking + the release button at the top of the page +- `active`: Vagrant is able to add and use this box version +- `revoked`: Vagrant cannot see this version, and it cannot be re-released. + You must create the version again + +### Release requirements + +A box can only be released if it has at least one of each component: a +box, a version, and a provider. diff --git a/website/content/docs/hcp/box/private.mdx b/website/content/docs/hcp/box/private.mdx new file mode 100644 index 00000000000..19400ee64eb --- /dev/null +++ b/website/content/docs/hcp/box/private.mdx @@ -0,0 +1,44 @@ +--- +layout: vagrant-cloud +page_title: Private Boxes +description: "Private boxes are only accessible by you and any collaborators you add." +--- + +# Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. + +## Collaborators + +To add a collaborator: + +1. Click the gear setting beside the boxes name in order to edit it. +2. Under the "Add Collaborator" section, enter their username and + submit the form. +3. You'll now see a list of collaborators, and if necessary a collaborator + can be removed. + +Collaborators can edit the box, versions and providers. The only +things they cannot do are: + +- Add another collaborator +- Delete the box + +## Vagrant Login + +In order to access these boxes from Vagrant, you'll need to first +authenticate with your Vagrant Cloud account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +## 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/content/docs/hcp/discover/index.mdx b/website/content/docs/hcp/discover/index.mdx new file mode 100644 index 00000000000..6b0549dd0d1 --- /dev/null +++ b/website/content/docs/hcp/discover/index.mdx @@ -0,0 +1,59 @@ +--- +layout: vagrant-cloud +page_title: Discover Vagrant boxes +description: "Vagrant Cloud serves a public, searchable index of Vagrant boxes." +--- + +## Discover and use Vagrant boxes + +Vagrant Cloud hosts a catalog of publicly available Vagrant Boxes. These are boxes +created by both HashiCorp and community contributions. You can find an owner of +a box by selecting their username in the URL or on the box page. + +Public Vagrant boxes let you get up-and-running quickly in unfamiliar +environments. This is a popular way to set a base development environment +launchable in a single command within an organization or community. + +### Discover Vagrant boxes + +Vagrant Cloud serves a public, searchable index of Vagrant boxes. It's easy to find +boxes you can use with Vagrant that contain the technologies you need +for a Vagrant environment. + +You don't need a Vagrant Cloud account to use public boxes. + +1. Go to the [Box search page](https://vagrantcloud.com/boxes/search). + +1. Once you find a box, click its name to learn more about it. + +1. When you're ready to use it, copy the name, such as "hashicorp/bionic64" + and initialize your Vagrant project with `vagrant init hashicorp/bionic64`. + Or, if you already have a Vagrant project created, modify the Vagrantfile + to use the box: `config.vm.box = "hashicorp/bionic64"`. + +## Provider support + +Not all boxes are available for all providers. You may need to sort by a provider that you have on your local system to narrow down your search. + +## Choose the right box + +As with all software and configuration used from a public source, +it's important to keep in mind whose box you're using. Here +are some things to note when you're choosing a box: + +- **The username of the user**. If it's `bento` or `ubuntu`, you can likely + trust the box more than an anonymous user. +- **The number of downloads of the box**. Heavily downloaded boxes + are likely vetted more often by other members of the community. HashiCorp + responds to reports of malicious software distributed via Vagrant Cloud + by disabling and/or removing boxes. If you find a box which includes + malicious software, please [contact support](/vagrant/intro/support) to make a report. +- **The latest release date**. Boxes which are updated periodically or which + have recent release dates will generally contain more up-to-date software. +- **Availability of the box download**. Vagrant Cloud periodically checks if a box + which is externally hosted (hosted by the box author, not Vagrant Cloud) is publicly + accessible. You can see this information on the box page next to the provider. + +# Use box + +When you are ready to use it, copy the name, such as "hashicorp/bionic64" and initialize your Vagrant project with `vagrant init hashicorp/bionic64`. Or, if you already have a Vagrant project created, modify the Vagrantfile to use the box: `config.vm.box = "hashicorp/bionic64"` diff --git a/website/content/docs/hcp/discover/private.mdx b/website/content/docs/hcp/discover/private.mdx new file mode 100644 index 00000000000..19400ee64eb --- /dev/null +++ b/website/content/docs/hcp/discover/private.mdx @@ -0,0 +1,44 @@ +--- +layout: vagrant-cloud +page_title: Private Boxes +description: "Private boxes are only accessible by you and any collaborators you add." +--- + +# Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. + +## Collaborators + +To add a collaborator: + +1. Click the gear setting beside the boxes name in order to edit it. +2. Under the "Add Collaborator" section, enter their username and + submit the form. +3. You'll now see a list of collaborators, and if necessary a collaborator + can be removed. + +Collaborators can edit the box, versions and providers. The only +things they cannot do are: + +- Add another collaborator +- Delete the box + +## Vagrant Login + +In order to access these boxes from Vagrant, you'll need to first +authenticate with your Vagrant Cloud account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +## 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/content/docs/hcp/discover/use.mdx b/website/content/docs/hcp/discover/use.mdx new file mode 100644 index 00000000000..e4f084a181b --- /dev/null +++ b/website/content/docs/hcp/discover/use.mdx @@ -0,0 +1,60 @@ +--- +layout: vagrant-cloud +page_title: Use HCP Vagrant boxes +description: "Configure both public and private boxes for distribution or to add collaborators." +--- + +## Use HCP Vagrant boxes + +To distribute the box to your team, update your Vagrantfile to reference the +box on Vagrant Cloud. + +```ruby +Vagrant.configure(2) do |config| + config.vm.box = "username/example-box" +end +``` + +Now when a team member runs `vagrant up`, the box will be downloaded from Vagrant Cloud. +If the box is private, the team member will be prompted to authorize access. Users +are granted access to private resources by logging in with a Vagrant Cloud username and +password or by using a shared Vagrant Cloud token. +[Learn more about authorization options here](/vagrant/vagrant-cloud/users/authentication). + +## Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. This is valuable if you +have information, data or provisioning in your box +that cannot be public. + +Private boxes will be excluded from the box catalog. + +### Collaborators + +Collaborators can be both teams in organizations or individual users. + +To add a collaborator: + +1. Go to the "Access" page of a box via the sidebar +2. Enter the username or team name and submit the form +3. You'll now see the user or team in the list of collaborators, + and if necessary a collaborator can be removed + +### Vagrant Login + +In order to access these private boxes from Vagrant, you'll need to first +authenticate with your Vagrant Cloud account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +### 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/content/docs/hcp/index.mdx b/website/content/docs/hcp/index.mdx new file mode 100644 index 00000000000..1f61ed62a9b --- /dev/null +++ b/website/content/docs/hcp/index.mdx @@ -0,0 +1,22 @@ +--- +layout: vagrant-cloud +page_title: Vagrant Cloud +description: "Vagrant Cloud serves a public, searchable index of Vagrant boxes" +--- + +# Vagrant Cloud + +## Support + +For Vagrant Cloud questions, feedback, or feature requests, please submit a ticket to +HashiCorp Support. + +[Click here](/vagrant/vagrant-cloud/support) for instructions on submitting a support ticket. + +## Features + +Vagrant Cloud provides the following features for Vagrant: + +- [Vagrant Box Catalog](/vagrant/vagrant-cloud/boxes/catalog) +- [Vagrant Box Creation](/vagrant/vagrant-cloud/boxes/create) +- [Vagrant Box Versioning](/vagrant/vagrant-cloud/boxes/lifecycle) diff --git a/website/content/docs/hcp/migrate/guide.mdx b/website/content/docs/hcp/migrate/guide.mdx new file mode 100644 index 00000000000..b704274a185 --- /dev/null +++ b/website/content/docs/hcp/migrate/guide.mdx @@ -0,0 +1,86 @@ +--- +layout: vagrant-cloud +page_title: Migrate to HCP Vagrant Registry +description: "Use Vagrant Cloud's migration tools to move all your artifacts to HashiCorp Cloud Platform (HCP)." +--- + +# Migrate to HCP Vagrant Registry + +Your Vagrant Cloud Organization will be put into a read-only state and marked `Migrating` until the migration is complete. During this time boxes will be available in searches and to download, but write functionality like uploading new boxes, releasing versions, and managing settings for your Vagrant Cloud Organization will be unavailable. Your new HCP Registry will not be available until the migration is complete. + +When you migrate your default organization your Profile Settings (user name, gravatar url, etc) will no longer be available to manage in Vagrant Cloud and should be managed from your [HCP Settings](https://portal.cloud.hashicorp.com/account-settings). + +## Overview + +HCP [Vagrant Registry](https://portal.cloud.hashicorp.com/vagrant/discover), like Vagrant Cloud, is a public, searchable index of Vagrant boxes that allows box owners to host and share artifacts. + +To take advantage of shared infrastructure and platform investments available on the Hashicorp Cloud Platform (HCP), Hashicorp is migrating all existing boxes to HCP Vagrant Registry and retiring the current Vagrant Cloud application at the end of July 2024. + +Migrated organizations will be permanently accessible at their original Vagrant Cloud URLs and won’t require changes to user workflows. Migrated registries will have access to the modern HCP Vagrant Registry UI, an improved search experience, and free private boxes. + +Those who take no action will have their boxes migrated as part of the site wide migration. The Vagrant team will maintain redirects to ensure users can expect all existing URLs and workflows to operate as usual after migration regardless of how boxes are migrated. + +## Prerequisites + +Before you continue with this guide, you should familiarize yourself with a few new resource management concepts in HCP and HCP Vagrant Registry. + +###### Registries + +The collection that holds a user’s boxes, the registry name is incorporated into the first half of resource names. For example, `hashicorp/atlas`. + +~> Note: An HCP registry is analogous to an Organization in Vagrant Cloud. A given HCP project may have an unlimited number of registries. + +##### HCP Organizations + +[HCP organizations](/hcp/docs/hcp/admin/orgs) are parent-level entities that can have up to ten projects. A single HCP account can be a member of multiple organizations, as an invited user, but can only create and own a single organization. + +##### HCP Projects + +[HCP projects](/hcp/docs/hcp/admin/orgs) allow organization owners to segment resources by team, environment, etc. Resources such as HCP Vagrant Registries, Hashicorp Virtual Private Networks (HPN). Each organization is assigned a `default-project` at creation and may have up to 10 projects. + +#### Create an HCP Vagrant Registry account + +To use the Vagrant Cloud migration tool, you must define an organization and project within an HCP account and be signed into an active session on that account. + +Your HCP account must use the email address associated with your Vagrant Cloud account. Check under `Settings → Profile` if you are unsure what email address you use for Vagrant Cloud. + +1. Sign up for a (free) [HCP account](https://portal.cloud.hashicorp.com/orgs/create), with your primary Vagrant Cloud organization email address. You must verify your account and sign into HCP. +2. At first log-in, use the wizard to create an HCP organization. +3. On creation of your organization, you will be directed to the dashboard for your `default-project`. You can create an additional project from the Projects page. +4. Now that you have a project in an HCP Account that uses the same email address as your Vagrant Cloud account, you can begin the migration process. + +## Migrate to HCP Vagrant Registry + +#### 1. Sign in to both accounts and open the migration tool + +Once you have signed into both your HCP and Vagrant Cloud accounts, you can access the [migration tool](https://app.vagrantup.com/migration). + +#### 2. Select a Vagrant Cloud organization to migrate + +Select a single organization from the dropdown to migrate or select the checkbox `Migrate all organizations` to migrate them all at once to a single HCP Project. + +##### 3. Select a destination project in HCP + +If you have multiple projects in HCP, select the project you want from the HCP Project dropdown. If you have not created a second project the `default-project` will be auto-selected. + +When preparing for migration it is worth noting the following: + +- Your Vagrant Cloud Organization will be put into a read-only state and marked `Migrating` until the migration is complete. During this time boxes will be available in searches and to download, but write functionality like uploading new boxes, releasing versions, and managing settings for your Vagrant Cloud Organization will be unavailable. +- Your new HCP Registry will not be available until the migration is complete. +- When you migrate your default organization your Profile Settings (user name, gravatar url, etc) will no longer be available to manage in Vagrant Cloud and should be managed from your [HCP Settings](https://portal.cloud.hashicorp.com/account-settings). + +#### 4. Start the migration + +After you press the `Migrate` button you will be redirected to a status page that will keep you updated on the progress of your migration. + +#### 5. Visit your Registry in HCP + +Once your migration is complete you can view your new Registry in HCP. + +To view your registries , click on [Vagrant Registry](https://portal.cloud.hashicorp.com/services/vagrant/registries) in the side panel or by visiting [https://portal.cloud.hashicorp.com/services/vagrant/registries](https://portal.cloud.hashicorp.com/services/vagrant/registries). + +It is important to note that while a migrated organization will no longer be available in Vagrant Cloud the status of the migration will be visible from the `Status` tab on the [Migration](https://app.vagrantup.com/migration) page. + +## Conclusion + +If for some reason you are unable to access your new HCP Registry or your migration does not complete successfully, review the [Migration Troubleshooting](/vagrant/vagrant-cloud/hcp-vagrant/troubleshooting) guide or [contact support](/vagrant/intro/support) . Our team will be happy to help you complete your migration or reset your organization state. diff --git a/website/content/docs/hcp/migrate/post-migration-guide.mdx b/website/content/docs/hcp/migrate/post-migration-guide.mdx new file mode 100644 index 00000000000..a9424c22396 --- /dev/null +++ b/website/content/docs/hcp/migrate/post-migration-guide.mdx @@ -0,0 +1,87 @@ +--- +layout: vagrant-cloud +page_title: Usage and Behavior Post Migration to HCP +description: "Learn about how Vagrant and Vagrant Cloud will behave after migrating to HashiCorp Cloud Platform (HCP)." +--- + +# Migrating to HCP Vagrant Registry + +This document describes the behavior of Vagrant Cloud after an organization is migrated to HCP Vagrant Registry. For information on migrating to HCP Vagrant Registry please see the [migration guide](/vagrant/vagrant-cloud/hcp-vagrant/migration-guide). + +# Vagrant Cloud Redirects + +After an organization has been migrated to HCP Vagrant Registry any requests Vagrant Cloud receives for that organization, or any boxes within that organization, will be automatically redirected to the proper location on HCP Vagrant Registry. + +# API + +API requests to Vagrant Cloud for organizations that have been migrated to HCP Vagrant Registry will be automatically proxied to HCP. + +## Authenticated Requests + +Authenticated API requests for migrated organizations will be proxied to HCP Vagrant Registry. This will require an HCP access token to be available to Vagrant Cloud to complete the request. Vagrant Cloud supports a composite access token comprised of the Vagrant Cloud access token and the HCP access token allowing seamless interactions with organizations that still remain on Vagrant Cloud as well as organizations that have been migrated to HCP Vagrant Registry. + +The format of the composite access token is: + +``` +; +``` + +If all organizations have been migrated to HCP Vagrant Registry the Vagrant Cloud access token will not be needed. The format of the access token is simply the access token: + +``` + +``` + +### HCP Access Token + +The following prerequisites are required for generating an HCP access token: + +* [HCP Service Principal](/hcp/docs/hcp/admin/iam/service-principals) +* [HCP CLI](/hcp/docs/cli) + +Using the `CLIENT_ID` and `CLIENT_SECRET` from the HCP service principal login to HCP using the `hcp` command: + +``` +hcp auth login --client-id=CLIENT_ID --client-secret=CLIENT_SECRET +``` + +Once authenticated the access token can be printed using the following command: + +``` +hcp auth print-access-token +``` + +### Vagrant Cloud Composite Token + +The Vagrant CLI supports using the `VAGRANT_CLOUD_TOKEN` environment variable to hold the access token used for authentication. This environment variable can be set with both access tokens to allow request for migrated organization and unmigrated organizations to both work as expected. As noted above, the format of the composite token will consist of: the Vagrant Cloud access token, a semi-colon, and the HCP access token. An example of setting the environment variable would be: + +``` +export VAGRANT_CLOUD_TOKEN=";" +``` + +The `hcp` command can also be used to provide the HCP access token to reduce the need for copying and pasting the access token: + +``` +export VAGRANT_CLOUD_TOKEN=";$(hcp auth print-access-token)" +``` + +If all organizations have been migrated to HCP Vagrant Registry, only authentication with HCP will be required. This can be done by providing the HCP access token in the `VAGRANT_CLOUD_TOKEN` environment variable: + +``` +export VAGRANT_CLOUD_TOKEN="$(hcp auth print-access-token)" +``` + +Or, if using Vagrant v2.4.3 or later, by setting the `HCP_CLIENT_ID` and `HCP_CLIENT_SECRET` environment variables: + +``` +export HCP_CLIENT_ID=""` +export HCP_CLIENT_SECRET=""` +``` + +If these variables are set, and the `VAGRANT_CLOUD_TOKEN` environment variable is unset, access tokens will be generated as needed when performing requests. + +# Packer + +After migrating to HCP, box uploads may fail when using the [vagrant-cloud](/packer/integrations/hashicorp/vagrant/latest/components/post-processor/vagrant-cloud) post-processor. This is due to the HCP access token used in the composite token expiring prior to the post-processor being executed. + +To resolve this issue, a new Packer post-processor has been introduced: [vagrant-registry](/packer/integrations/hashicorp/vagrant/latest/components/post-processor/vagrant-registry). This post-processor iteracts directly with the HCP Vagrant Box Registry and removes the requirement of a composite access token. The configuration of the `vagrant-registry` post-processor matches the configuration of the `vagrant-cloud` post-processor with the exception of the [authentication settings](/packer/integrations/hashicorp/vagrant/latest/components/post-processor/vagrant-registry#required) which requires a `client_id` and `client_secret` value instead of the `access_token` used by the `vagrant-cloud` post-processor. diff --git a/website/content/docs/hcp/migrate/troubleshoot.mdx b/website/content/docs/hcp/migrate/troubleshoot.mdx new file mode 100644 index 00000000000..170e2d2cb6c --- /dev/null +++ b/website/content/docs/hcp/migrate/troubleshoot.mdx @@ -0,0 +1,20 @@ +--- +layout: vagrant-cloud +page_title: Migration Troubleshooting +description: 'HCP Migration troubleshooting guide' +--- + +# Troubleshooting + +### Inactive HCP Session + +You may see a warning in the Migration Wizard if your HCP Session is inactive. The wizard will attempt to reload your page automatically within 5 seconds or you may attempt to refresh your session by reloading manually. The error will persist if you are not logged into HCP, log in from another window and refresh. + +### Missing Boxes or Registries + +In the rare case that an inoperable box was successfully uploaded (e.g legacy box improperly ported from Atlas) that box will not be migrated to HCP Vagrant. Any failed boxes will be listed in the Migration Status page. + +### Retrying Migrations + +If a migration fails, a `retry` icon will appear beside the name of that organization on the [migration status](https://app.vagrantup.com/migration/status) page. Failed migrations can be retried once. +In the event of a second failure, please [contact support](/vagrant/intro/support) with a description of your issue. Our team will be happy to help you complete your migration or reset your organization state. diff --git a/website/content/docs/hcp/organizations/authentication-policy.mdx b/website/content/docs/hcp/organizations/authentication-policy.mdx new file mode 100755 index 00000000000..0fe716a8bd6 --- /dev/null +++ b/website/content/docs/hcp/organizations/authentication-policy.mdx @@ -0,0 +1,29 @@ +--- +layout: vagrant-cloud +page_title: Organization Authentication Policy +description: "Secure sensitive resources with organization-wide authentication policy in Vagrant Enterprise." +--- + +# Set an Organization Authentication Policy + +Because organization membership affords members access to potentially sensitive +resources, owners can set organization-wide authentication policy in Vagrant +Enterprise. + +## Requiring Two-Factor Authentication + +Organization owners can require that all organization team members use +[two-factor authentication](/vagrant/vagrant-cloud/users/authentication). +Those that lack two-factor authentication will be locked out of the web +interface until they enable it or leave the organization. + +Visit your organization's configuration page to enable this feature. All +organization owners must have two-factor authentication enabled to require the +practice organization-wide. Note: locked-out users are still be able to interact +with Vagrant Cloud using their `ATLAS_TOKEN`. + +## Disabling Two-Factor Authentication Requirement + +Organization owners can disable the two-factor authentication requirement from +their organization's configuration page. Locked-out team members (those who have +not enabled two-factor authentication) will have their memberships reinstated. diff --git a/website/content/docs/hcp/organizations/create.mdx b/website/content/docs/hcp/organizations/create.mdx new file mode 100755 index 00000000000..9e581e7be16 --- /dev/null +++ b/website/content/docs/hcp/organizations/create.mdx @@ -0,0 +1,15 @@ +--- +layout: vagrant-cloud +page_title: Create an Organization +description: "Organizations enable you to share ownership of Vagrant resources." +--- + +# Create an Organization + +To create an organization: + +1. Create a personal account. You'll use this to create and administrate the + organization. You'll be able to add other users as owners of the organization, + so it won't be tied solely to your account. + +1. Visit your new organization page to create the organization. diff --git a/website/content/docs/hcp/organizations/index.mdx b/website/content/docs/hcp/organizations/index.mdx new file mode 100755 index 00000000000..c26bcb9a256 --- /dev/null +++ b/website/content/docs/hcp/organizations/index.mdx @@ -0,0 +1,14 @@ +--- +layout: vagrant-cloud +page_title: Organizations in Vagrant Cloud +description: "Organizations are a group of users in Vagrant Cloud that have access and ownership over shared resources." +--- + +## Organizations in Vagrant Cloud + +Organizations are a group of users in Vagrant Cloud that have access and +ownership over shared resources. When operating within a team, we recommend +creating an organization to manage access control, auditing, billing and +authorization. + +Each individual member of your organization should have their own account. diff --git a/website/content/docs/hcp/organizations/users/authentication.mdx b/website/content/docs/hcp/organizations/users/authentication.mdx new file mode 100755 index 00000000000..546f7ee1949 --- /dev/null +++ b/website/content/docs/hcp/organizations/users/authentication.mdx @@ -0,0 +1,56 @@ +--- +layout: vagrant-cloud +page_title: Authentication +description: "Authenticate your account with a username and password, tokens, or two-factor auth." +--- + +# Authentication + +Vagrant Cloud requires a username and password to sign up and login. +However, there are several ways to authenticate with your account. + +### Authentication Tokens + +Authentication tokens are keys used to access your account via tools or over the +various APIs used in Vagrant Cloud. + +You can create new tokens in the token section of your account settings. It's +important to keep tokens secure, as they are essentially a password and can be +used to access your account or resources. Additionally, token authentication +bypasses two factor authentication. + +### Authenticating Tools + +All HashiCorp tools look for the `ATLAS_TOKEN` environment variable: + +```shell-session +$ export ATLAS_TOKEN=TOKEN +``` + +This will automatically authenticate all requests against this token. This is +the recommended way to authenticate with our various tools. Care should be given +to how this token is stored, as it is as good as a password. + +### Two Factor Authentication + +You can optionally enable Two Factor authentication, requiring an SMS or TOTP +one-time code every time you log in, after entering your username and password. + +You can enable Two Factor authentication in the security section of your account +settings. + +Be sure to save the generated recovery codes. Each backup code can be used once +to sign in if you do not have access to your two-factor authentication device. + +### Sudo Mode + +When accessing certain admin-level pages (adjusting your user profile, for +example), you may notice that you're prompted for your password, even though +you're already logged in. This is by design, and aims to help guard protect you +if your screen is unlocked and unattended. + +### Session Management + +You can see a list of your active sessions on your security settings page. From +here, you can revoke sessions, in case you have lost access to a machine from +which you were accessing. diff --git a/website/content/docs/hcp/organizations/users/index.mdx b/website/content/docs/hcp/organizations/users/index.mdx new file mode 100755 index 00000000000..92a0636835b --- /dev/null +++ b/website/content/docs/hcp/organizations/users/index.mdx @@ -0,0 +1,11 @@ +--- +layout: vagrant-cloud +page_title: User Accounts +description: "Users are the main identity system in Vagrant Cloud." +--- + +# User Accounts + +Users are the main identity system in Vagrant Cloud. A user can be a +member of multiple [organizations](/vagrant/vagrant-cloud/organizations), +as well as individually collaborate on various resources. diff --git a/website/content/docs/hcp/organizations/users/migrate.mdx b/website/content/docs/hcp/organizations/users/migrate.mdx new file mode 100755 index 00000000000..78512770a1f --- /dev/null +++ b/website/content/docs/hcp/organizations/users/migrate.mdx @@ -0,0 +1,26 @@ +--- +layout: vagrant-cloud +page_title: Migrate User to Organization +description: "Step-by-step instructions to migrate existing users to an organization." +--- + +# Migrate User to Organization + +To migrate an existing user account to an organization: + +1. Create or retrieve the username of a new personal account. You'll add this + account as an "owner" for the new organization during the migration process. If + you already have another account, write down your username. + +2. Sign in as the account you wish to migrate. + +3. Go to [the account migration page](https://app.vagrantup.com/account/migrate). + +4. Put the username of the personal account you wish to make an owner of the + organization into the username text field and press "Migrate". + +5. You should now be logged out and receive a confirmation email with the + personal account you migrated to. + +6. Now, sign in with your personal account. If you visit you settings page, you + should see your migrated organization available to administrate. diff --git a/website/content/docs/hcp/organizations/users/recovery.mdx b/website/content/docs/hcp/organizations/users/recovery.mdx new file mode 100755 index 00000000000..fab2bafba63 --- /dev/null +++ b/website/content/docs/hcp/organizations/users/recovery.mdx @@ -0,0 +1,13 @@ +--- +layout: vagrant-cloud +page_title: Account Recovery +description: "Reset your Vagrant Cloud password with the reset link in the UI." +--- + +# Account Recovery + +If you have lost access to your Vagrant Cloud account, use the reset +password form on the login page to send yourself a link to reset your password. + +If an email is unknown, [contact support](/vagrant/intro/support) +for further help. diff --git a/website/content/docs/hcp/request-limits.mdx b/website/content/docs/hcp/request-limits.mdx new file mode 100644 index 00000000000..7ed5fbebaa5 --- /dev/null +++ b/website/content/docs/hcp/request-limits.mdx @@ -0,0 +1,30 @@ +--- +layout: vagrant-cloud +page_title: Request Limits +description: "Rate limits restrict the number of requests a client may send to services over a set time interval" +--- + +# Request Limits + +## What is Rate Limiting? + +Rate limiting is a process to protect our quality of service we provide to you. Rate limiting will limit the number of requests a client may send to services over a set time interval. We track requests by IP address origin of the request. + +## How many requests can I make? + +You can make a set amount of requests per minute from a single IP address. This rate can vary per resource but the current value is returned in the HTTP headers of your request. For the most up to date rate limiting for your requests please view the information in the headers of your response. + +## Why are you rate limiting my requests? + +We have detected a request rate in excess of our current threshold. To provide a high quality of services to all users, your request may have been rate limited. + +## How do I know if I have been rate limited? + +If you have received a 429 HTTP status code in the response to your request, your request has likely been rate limited. There is some additional information in the headers that will help you determine if this is the case. Each request response will include the headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. + +- **X-RateLimit-Limit**: The current maximum number of requests allowed from your client. +- **X-RateLimit-Remaining**: How many requests you have remaining in the time window. +- **X-RateLimit-Reset**: The Unix timestamp for when the window resets. + +## My use case requires more requests. What do I do? +Please [contact support](/vagrant/intro/support) with a description of your use case so that we can consider creating an exception.. diff --git a/website/content/docs/hcp/support.mdx b/website/content/docs/hcp/support.mdx new file mode 100755 index 00000000000..db0d1b29581 --- /dev/null +++ b/website/content/docs/hcp/support.mdx @@ -0,0 +1,40 @@ +--- +layout: vagrant-cloud +page_title: Vagrant Cloud Support +description: "Find support for Vagrant Cloud" +--- + +# Contact support + +For Vagrant Cloud questions, feedback, or feature requests, please submit a ticket to +[HashiCorp Support](/vagrant/intro/support). + +### Free Support + +We do not currently publish support SLAs for free accounts, but endeavor to +respond as quickly as possible. We respond to most requests within less than 24 +hours. + +## HashiCorp Tools Support + +It's often the case that Vagrant Cloud questions or feedback relates to +the HashiCorp tooling. We encourage all Vagrant Cloud users to search for +related issues and problems in the open source repositories and mailing lists +prior to contacting us to help make our support more efficient and to help +resolve problems faster. + +Visit the updating tools section for a list of our tools and their project +websites. + +## Documentation Feedback + +Due to the dynamic nature of Vagrant Cloud and the broad set of features +it provides, there may be information lacking in the documentation. + +Vagrant Cloud documentation is open source. +If you'd like to improve or correct the documentation, +please submit a pull-request to the +[Vagrant project on GitHub](https://github.com/hashicorp/vagrant/tree/main/website/content/vagrant-cloud/). +The Vagrant Cloud documentation can be found in the `/website/pages/vagrant-cloud/` directory. + +Otherwise, to make a suggestion or report an error in documentation, please [contact support](/vagrant/intro/support). diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx index 37995148a8b..bd066f0aa32 100644 --- a/website/content/docs/index.mdx +++ b/website/content/docs/index.mdx @@ -20,4 +20,4 @@ HashiCorp's Learn platform first, and then returning to this page. The navigation will take you through each component of Vagrant. Click on a navigation item to get started, or read more about [why developers, designers, and operators choose Vagrant](/vagrant/intro) -for their needs. +for their needs. \ No newline at end of file diff --git a/website/content/docs/install/advanced.mdx b/website/content/docs/install/advanced.mdx new file mode 100644 index 00000000000..dbf05151a4c --- /dev/null +++ b/website/content/docs/install/advanced.mdx @@ -0,0 +1,90 @@ +--- +layout: docs +page_title: Install Vagrant +description: |- + Vagrant is available for most platforms. Install the Vagrant + package using standard procedures for your operating system. +--- + +# Install Vagrant + +To get started with Vagrant, download the appropriate installer or package for your platform from our [Vagrant downloads page](/vagrant/downloads). Install the package with the standard procedures for your operating system. + +The installer automatically adds `vagrant` to your system path so that it is available in terminals. If it is not found, log out and back into your system; this is a common issue for Windows. + + + +Vagrant 1.0.x has the option to be installed as a [RubyGem](https://en.wikipedia.org/wiki/RubyGems). However, this installation method is no longer supported. If you have an old version of Vagrant installed via Rubygems, remove it prior to installing newer versions of Vagrant. + + + +## First development environment + +If you are new to Vagrant, the next step to set up a development environment is to install a [box](/vagrant/tutorials/getting-started/getting-started-boxes). + +## How to use multiple hypervisors + +Hypervisors often do not allow you to bring up virtual machines if you have more than one hypervisor in use. + +Below are a couple of examples to allow you to use Vagrant and VirtualBox if another hypervisor is present. + +### Linux, VirtualBox, and KVM + +If you encounter the following error message, it is because another hypervisor, like KVM, is in use. + +```shell-session +There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below. + +Command: ["startvm", , "--type", "headless"] + +Stderr: VBoxManage: error: VT-x is being used by another hypervisor (VERR_VMX_IN_VMX_ROOT_MODE). +VBoxManage: error: VirtualBox can't operate in VMX root mode. Please disable the KVM kernel extension, recompile your kernel and reboot +(VERR_VMX_IN_VMX_ROOT_MODE) +VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component ConsoleWrap, interface IConsole +``` + +You must add the additional hypervisors to the deny list in order for VirtualBox to run correctly. + +First, find out the name of the hypervisor. + +```shell-session +$ lsmod | grep kvm +kvm_intel 204800 6 +kvm 593920 1 kvm_intel +irqbypass 16384 1 kvm +``` + +Use the `blacklist` command to add the hypervisor to your denylist. + +```shell-session +$ echo 'blacklist kvm-intel' >> /etc/modprobe.d/blacklist.conf +``` + +Restart your machine and try the `vagrant` command again. + +### Windows, VirtualBox, and Hyper-V + +If you encounter an issue with Windows, you will get a blue screen if you attempt to bring up a VirtualBox VM with Hyper-V enabled. + +If you wish to use VirtualBox on Windows, you must ensure that Hyper-V is not enabled on Windows. You can turn off the feature with the following Powershell command for Windows 10. + +```powershell +Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All +``` + +For Windows 11, you can use an elevated Powershell. + +```powershell +bcdedit /set hypervisorlaunchtype off +``` + +You can also disable Hyper-V in the Windows system settings. + +- Right click on the Windows button and select 'Apps and Features'. +- Select Turn Windows Features on or off. +- Unselect Hyper-V and click OK. + +You might have to reboot your machine for the changes to take effect. More information +about Hyper-V can be read [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). + + diff --git a/website/content/docs/install/macos-catalina.mdx b/website/content/docs/install/macos-catalina.mdx new file mode 100644 index 00000000000..8bbd43089ef --- /dev/null +++ b/website/content/docs/install/macos-catalina.mdx @@ -0,0 +1,25 @@ +--- +layout: docs +page_title: Vagrant and macOS Catalina +description: An overview of using Vagrant on macOS Catalina. +--- + +# Vagrant and macOS Catalina + +The latest version of macOS (Catalina) includes security changes that prevent applications from accessing data in your Documents, Desktop, and Downloads folders without explicit permission. If you keep any virtual machine files in these folders, you will need to allow access to these folders for your terminal emulator. + +Initially when you try to access one of these folders from the command line, you should see a popup that says something like: + + + +```text +"Terminal" would like to access files in your Documents folder. +``` + + + +Click "OK" to grant those permissions. + +If you click "Don't Allow" and find that you need to grant access later on, you can go to **System Preferences** -> **Security & Privacy** -> **Files and Folders** and you should see your terminal emulator there. Click on the lock, and then click on the checkbox next to the folder that contains the files that Vagrant needs to access. + +Note that granting the `vagrant` binary "Full Disk Access" is not sufficient or necessary. If Terminal (or iTerm2/Hyper/etc.) is granted access to a particular folder, then Vagrant will also be able to access that folder. \ No newline at end of file diff --git a/website/content/docs/installation/uninstallation.mdx b/website/content/docs/install/uninstall.mdx similarity index 57% rename from website/content/docs/installation/uninstallation.mdx rename to website/content/docs/install/uninstall.mdx index 1c75bb8c3d9..dceed559da0 100644 --- a/website/content/docs/installation/uninstallation.mdx +++ b/website/content/docs/install/uninstall.mdx @@ -9,14 +9,11 @@ description: |- # Uninstall Vagrant -To uninstall Vagrant, you can either uninstall -the Vagrant binary, the user data, or both. The two sections below detail how to -uninstall Vagrant on any platform. +To uninstall Vagrant, you can either uninstall the Vagrant binary, the user data, or both. The two sections below detail how to uninstall Vagrant on any platform. ## Remove the Vagrant program -When you remove the Vagrant program, it will remove the `vagrant` binary and all -dependencies from your machine. It will _not_ remove user data. The next section provides more details on how to remove that directory from your system. +When you remove the Vagrant program, it will remove the `vagrant` binary and all dependencies from your machine. It will _not_ remove user data. The next section provides more details on how to remove that directory from your system. ### Windows machines @@ -42,22 +39,14 @@ rm -f /usr/bin/vagrant ## Remove user data -The removal of user data will remove all [boxes](/vagrant/docs/boxes), -[plugins](/vagrant/docs/plugins), license files, and any stored state that may be used -by Vagrant. Removing the user data effectively makes Vagrant think it -is a fresh install. +The removal of user data will remove all [boxes](/vagrant/docs/boxes), [plugins](/vagrant/docs/plugins), license files, and any stored state that may be used by Vagrant. Removing the user data effectively makes Vagrant think it is a fresh install. -On Linux and Mac OS platforms, the user data directory location is in the root of your home directory under `vagrant.d`. Remove the `~/.vagrant.d` directory to delete all the user data. On -Windows, this directory is, `C:\Users\YourUsername\.vagrant.d`, where -`YourUsername` is the username of your local user. +On Linux and Mac OS platforms, the user data directory location is in the root of your home directory under `vagrant.d`. Remove the `~/.vagrant.d` directory to delete all the user data. On Windows, this directory is, `C:\Users\YourUsername\.vagrant.d`, where `YourUsername` is the username of your local user. -If the Vagrant support team asks you to remove this -directory to debug, you should make a backup. +If the Vagrant support team asks you to remove this directory to debug, you should make a backup. When you use Vagrant again, Vagrant will automatically regenerate any data necessary to operate. ## Reinstall Vagrant -If you decide to reinstall Vagrant, you can -follow the [installation docs](/vagrant/docs/installation) again for any standard -method. +If you decide to reinstall Vagrant, you can follow the [installation docs](/vagrant/docs/installation) again for any standard method. \ No newline at end of file diff --git a/website/content/docs/install/wsl.mdx b/website/content/docs/install/wsl.mdx new file mode 100644 index 00000000000..5b7fff5333c --- /dev/null +++ b/website/content/docs/install/wsl.mdx @@ -0,0 +1,84 @@ +--- +layout: docs +page_title: Vagrant and Windows Subsystem for Linux +description: |- + An overview of using Vagrant on Windows within the Windows Subsystem + for Linux. +--- + +# Vagrant and Windows Subsystem for Linux + +Recent versions of Windows 10 now include Windows Subsystem for Linux (WSL) as an optional Windows feature. The WSL supports running a Linux environment within Windows. Vagrant support for WSL is still in development and should be considered _beta_. + + + +Using Vagrant within the Windows Subsystem for Linux is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Windows, WSL, and Linux should approach. + + + +## Install Vagrant + +Vagrant _must_ be installed within the Linux distribution used with WSL. While the `vagrant.exe` executable provided by the Vagrant Windows installation is accessible from within the WSL, it will not function as expected. + +Download the installer package for the Linux distribution from the releases page and install Vagrant. + +When Vagrant is installed on the Windows system the version installed within the Linux distribution _must_ match. + +## Enable Windows access + +By default, Vagrant will not access features available on the Windows system from within the WSL. This means the VirtualBox and Hyper-V providers will not be available. To enable Windows access, which will also enable the VirtualBox and Hyper-V providers, set the `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS` environment variable: + +```shell-session +$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +``` + +When Windows access is enabled, Vagrant will automatically adjust `VAGRANT_HOME` to be located on the Windows host. This is required to ensure `VAGRANT_HOME` is located on a DrvFs file system. + +## Update PATH + +Vagrant will detect when it is being run within the WSL and adjust how it locates and executes third party executables. For example, when using the VirtualBox provider Vagrant will interact with VirtualBox installed on the Windows system, not within the WSL. It is important to ensure that any required Windows executable is available within your `PATH` to allow Vagrant to access them. + +For example, when using the VirtualBox provider: + +```shell-session +$ export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox" +``` + +## Synced folders + +Support for synced folders within the WSL is implementation dependent. In most cases synced, folders will not be supported when running Vagrant within WSL on a VolFs file system. Synced folder implementations must "opt-in" to supporting usage from VolFs file systems. To use synced folders from within the WSL that do not support VolFs file systems, move the Vagrant project directory to a DrvFs file system location (/mnt/c/ prefixed path for example). + +## Windows access + +Working within the WSL provides a layer of isolation from the actual Windows system. In most cases Vagrant will need access to the actual Windows system to function correctly. As most Vagrant providers will need to be installed on Windows directly (not within the WSL) Vagrant will require Windows access. Access to the Windows system is controlled via an environment variable: `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS`. If this environment variable is set, Vagrant will access the Windows system to run executables and enable things like synced folders. When running in a bash shell within WSL, the environment variable can be setup like so: + +```shell-session +$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +``` + +This will enable Vagrant to access the Windows system outside of the WSL and properly interact with Windows executables. This will automatically modify the `VAGRANT_HOME` environment variable if it is not already defined, setting it to be within the user's home directory on Windows. + +It is important to note that paths shared with the Windows system will not have Linux permissions enforced. For example, when a directory within the WSL is synced to a guest using the VirtualBox provider, any local permissions defined on that directory (or its contents) will not be visible from the guest. Likewise, any files created from the guest within the synced folder will be world readable/writeable in WSL. + +Other useful WSL related environment variables: + +- `VAGRANT_WSL_WINDOWS_ACCESS_USER` - Override current Windows username +- `VAGRANT_WSL_DISABLE_VAGRANT_HOME` - Do not modify the `VAGRANT_HOME` variable +- `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` - Custom Windows system home path + +If a Vagrant project directory is not within the user's home directory on the Windows system, certain actions that include permission checks may fail (like `vagrant ssh`). When accessing Vagrant projects outside the WSL Vagrant will skip these permission checks when the project path is within the path defined in the `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` environment variable. For example, if a user wants to run a Vagrant project from the WSL that is located at `C:\TestDir\vagrant-project`: + +```shell-session +C:\Users\vagrant> cd C:\TestDir\vagrant-project +C:\TestDir\vagrant-project> bash +vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ export VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH="/mnt/c/TestDir" +vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ vagrant ssh +``` + +## Use Docker + +The docker daemon cannot be run inside the Windows Subsystem for Linux. However, the daemon can be run on Windows and accessed by Vagrant while running in the WSL. Once docker is installed and running on Windows, export the following environment variable to give Vagrant access: + +```shell-session +$ vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375 +``` diff --git a/website/content/docs/installation/backwards-compatibility.mdx b/website/content/docs/installation/backwards-compatibility.mdx deleted file mode 100644 index faf60272c0a..00000000000 --- a/website/content/docs/installation/backwards-compatibility.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: docs -page_title: Backwards Compatibility -description: Vagrant makes a very strict backwards-compatibility promise. ---- - -# Backwards Compatibility - -## For 1.0.x - -Vagrant 1.1+ provides full backwards compatibility for valid Vagrant 1.0.x -Vagrantfiles which do not use plugins. After installing Vagrant 1.1, your 1.0.x -environments should continue working without modifications, and existing running -machines will continue to be managed properly. - -This compatibility layer will remain in Vagrant up to and including Vagrant 2.0. -It may still exist after that, but Vagrant's compatibility promise is only for -two versions. Seeing that major Vagrant releases take years to develop and -release, it is safe to stick with your version 1.0.x Vagrantfile for the -time being. - -If you use any Vagrant 1.0.x plugins, you must remove references to these from -your Vagrantfile prior to upgrading. Vagrant 1.1+ introduces a new plugin -format that will protect against this sort of incompatibility from ever -happening again. - -## For 1.x - -Backwards compatibility between 1.x is not promised, and Vagrantfile -syntax stability is not promised until 2.0 final. Any backwards -incompatibilities within 1.x will be clearly documented. - -This is similar to how Vagrant 0.x was handled. In practice, Vagrant 0.x -only introduced a handful of backwards incompatibilities during the entire -development cycle, but the possibility of backwards incompatibilities -is made clear so people are not surprised. - -Vagrant 2.0 final will have a stable Vagrantfile format that will -remain backwards compatible, just as 1.0 is considered stable. diff --git a/website/content/docs/installation/source.mdx b/website/content/docs/installation/source.mdx deleted file mode 100644 index 1bbee138ee1..00000000000 --- a/website/content/docs/installation/source.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -layout: docs -page_title: Installing Vagrant from Source -description: |- - Vagrant installations from source is an advanced operation. It is only recommended - if you cannot use the official installer. ---- - -# Install Vagrant from source - -Vagrant installations from source is an advanced operation. We only recommended -if you cannot use the official installer. This page details the prerequisites and three -steps to install Vagrant from source. - -1. Install Ruby -1. Clone Vagrant -1. Configure locally - -## Install Ruby - -To develop and build Vagrant, you must install a specific version of Ruby. The -specific Ruby version that you will need is documented -in `vagrant.gemspec`, located in the repository on GitHub. -It contains the most up-to-date requirements. - - -You will also need to be aware of plugin compatibility between Vagrant source installations and package based installations. Since Vagrant plugins are configured based on the current environment, plugins installed with Vagrant from source will not work with the package based Vagrant installation. - -## Clone Vagrant - -Clone Vagrant's repository from GitHub into the directory where you keep code on your machine. - -```shell-session -$ git clone https://github.com/hashicorp/vagrant.git -``` - -Next, `cd` into that path. You must initiate all commands from this directory. - -```shell-session -$ cd /path/to/your/vagrant/clone -``` - -Use the `bundle` command with a required version\* to install the requirements. - -```shell-session -$ bundle install -``` - -You can now start Vagrant with the `bundle` command. - -```shell-session -$ bundle exec vagrant -``` - -## Configure locally - -In order to use your locally-installed version of Vagrant in other projects, you will need to create a binstub and add it to your path. - -First, use the `bundle` command from your Vagrant directory. - -```shell-session -$ bundle --binstubs exec -``` - -This will generate files in `exec/`, including `vagrant`. You can now specify -the full path to the `exec/vagrant` anywhere on your operating system. - -```shell-session -$ /path/to/vagrant/exec/vagrant init -m hashicorp/bionic64 -``` - --> **Tip:** Warning messages are expected when you use a local Vagrant from source installation, since it is not supported or recommended. - -If you do not want to specify the full path to Vagrant (i.e. you just want to -run `vagrant`), you can create a symbolic link to your exec. - -```shell-session -$ ln -sf /path/to/vagrant/exec/vagrant /usr/local/bin/vagrant -``` - -When you want to switch back to the official Vagrant version, -remove the symlink. diff --git a/website/content/docs/installation/upgrading-from-1-0.mdx b/website/content/docs/installation/upgrading-from-1-0.mdx deleted file mode 100644 index f11112c9f7f..00000000000 --- a/website/content/docs/installation/upgrading-from-1-0.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: docs -page_title: Upgrade from Vagrant 1.0 -description: |- - The upgrade process from 1.0.x to 1.x is straightforward, Vagrant is - backwards compatible with Vagrant 1.0.x. To reinstall Vagrant - over your previous installation, download the latest package and - install it with standard procedures for your operating system. ---- - -# Upgrade from Vagrant 1.0.x - -The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is quite -[backwards compatible](/vagrant/docs/installation/backwards-compatibility) -with Vagrant 1.0.x, so you can simply reinstall Vagrant -over your previous installation by downloading the latest package and -installing it using standard procedures for your operating system. - -As the [backwards compatibility](/vagrant/docs/installation/backwards-compatibility) -page says, **Vagrant 1.0.x plugins will not work with Vagrant 1.1+**. Many -of these plugins have been updated to work with newer versions of Vagrant, -so you will need to verify if they've been updated. If not however, you will have -to remove them before the upgrade. - -We recommend that you remove _all_ plugins before the upgrade and then slowly -add them back. This usually makes for a smoother upgrade process. - -~> **If your version of Vagrant was installed via Rubygems**, you -must uninstall the old version prior to installing the package for the -new version of Vagrant. The Rubygems installation is no longer supported. diff --git a/website/content/docs/installation/upgrading.mdx b/website/content/docs/installation/upgrading.mdx deleted file mode 100644 index 550d28eeb8f..00000000000 --- a/website/content/docs/installation/upgrading.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: docs -page_title: Upgrade Vagrant -description: |- - This page details the general process to upgrade Vagrant for the - 1.x.x series. If you need to upgrade from Vagrant 1.0.x, read the specific page - dedicated to that. ---- - -# Upgrade Vagrant - -This page details how to upgrade Vagrant in the 1.x.x series. - -~> If you need to upgrade from Vagrant 1.0.x, read the -[specific page dedicated to that](/vagrant/docs/installation/upgrading-from-1-0). - -Vagrant upgrades during the 1.x.x release series are straightforward: - -1. [Download](/vagrant/downloads) the new package -2. Install it over the existing package - -The installers will properly overwrite and remove old files. It is recommended -that no other Vagrant processes are running during the upgrade process. - -## Vagrantfile compatibility with 3.0 - -Note that Vagrantfile stability for the new Vagrantfile syntax is not -guaranteed until Vagrant 3.0. While Vagrantfiles made for 1.0.x will -[continue to work](/vagrant/docs/installation/backwards-compatibility), -newer Vagrantfiles may have backwards incompatible changes until 3.0. - -## Issue reports - -If you encounter any problems at upgrade time, [report them as an issue in Github](https://github.com/hashicorp/vagrant/issues). Upgrades are meant to be a smooth process and we consider it a bug if it was not. diff --git a/website/content/docs/multi-machine.mdx b/website/content/docs/multi-machine.mdx deleted file mode 100644 index e9f59be8ef1..00000000000 --- a/website/content/docs/multi-machine.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -layout: docs -page_title: Multi-Machine -description: |- - Vagrant is able to define and control multiple guest machines per - Vagrantfile. This is known as a "multi-machine" environment. ---- - -# Multi-Machine - -Vagrant is able to define and control multiple guest machines per -Vagrantfile. This is known as a "multi-machine" environment. - -These machines are generally able to work together or are somehow associated -with each other. Here are some use-cases people are using multi-machine -environments for today: - -- Accurately modeling a multi-server production topology, such as separating - a web and database server. -- Modeling a distributed system and how they interact with each other. -- Testing an interface, such as an API to a service component. -- Disaster-case testing: machines dying, network partitions, slow networks, - inconsistent world views, etc. - -Historically, running complex environments such as these was done by -flattening them onto a single machine. The problem with that is that it is -an inaccurate model of the production setup, which can behave far differently. - -Using the multi-machine feature of Vagrant, these environments can be modeled -in the context of a single Vagrant environment without losing any of the -benefits of Vagrant. - -## Defining Multiple Machines - -Multiple machines are defined within the same project [Vagrantfile](/vagrant/docs/vagrantfile/) -using the `config.vm.define` method call. This configuration directive -is a little funny, because it creates a Vagrant configuration within a -configuration. An example shows this best: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "shell", inline: "echo Hello" - - config.vm.define "web" do |web| - web.vm.box = "apache" - end - - config.vm.define "db" do |db| - db.vm.box = "mysql" - end -end -``` - -As you can see, `config.vm.define` takes a block with another variable. This -variable, such as `web` above, is the _exact_ same as the `config` variable, -except any configuration of the inner variable applies only to the machine -being defined. Therefore, any configuration on `web` will only affect the -`web` machine. - -And importantly, you can continue to use the `config` object as well. The -configuration object is loaded and merged before the machine-specific configuration, -just like other Vagrantfiles within the -[Vagrantfile load order](/vagrant/docs/vagrantfile/#load-order). - -If you are familiar with programming, this is similar to how languages have -different variable scopes. - -When using these scopes, order of execution for things such as -provisioners becomes important. Vagrant enforces ordering outside-in, in -the order listed in the Vagrantfile. For example, with the Vagrantfile -below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision :shell, inline: "echo A" - - config.vm.define :testing do |test| - test.vm.provision :shell, inline: "echo B" - end - - config.vm.provision :shell, inline: "echo C" -end -``` - -The provisioners in this case will output "A", then "C", then "B". Notice -that "B" is last. That is because the ordering is outside-in, in -the order of the file. - -If you want to apply a slightly different configuration to multiple machines, -see [this tip](/vagrant/docs/vagrantfile/tips#loop-over-vm-definitions). - -## Controlling Multiple Machines - -The moment more than one machine is defined within a Vagrantfile, the -usage of the various `vagrant` commands changes slightly. The change should -be mostly intuitive. - -Commands that only make sense to target a single machine, such as -`vagrant ssh`, now _require_ the name of the machine to control. Using -the example above, you would say `vagrant ssh web` or `vagrant ssh db`. - -Other commands, such as `vagrant up`, operate on _every_ machine by -default. So if you ran `vagrant up`, Vagrant would bring up both the -web and DB machine. You could also optionally be specific and say -`vagrant up web` or `vagrant up db`. - -Additionally, you can specify a regular expression for matching only -certain machines. This is useful in some cases where you specify many similar -machines, for example if you are testing a distributed service you may have -a `leader` machine as well as a `follower0`, `follower1`, `follower2`, etc. If you -want to bring up all the followers but not the leader, you can just do -`vagrant up /follower[0-9]/`. If Vagrant sees a machine name within forward -slashes, it assumes you are using a regular expression. - -## Communication Between Machines - -In order to facilitate communication within machines in a multi-machine setup, -the various [networking](/vagrant/docs/networking/) options should be used. -In particular, the [private network](/vagrant/docs/networking/private_network) can -be used to make a private network between multiple machines and the host. - -## Specifying a Primary Machine - -You can also specify a _primary machine_. The primary machine will be the -default machine used when a specific machine in a multi-machine environment -is not specified. - -To specify a default machine, just mark it primary when defining it. Only -one primary machine may be specified. - -```ruby -config.vm.define "web", primary: true do |web| - # ... -end -``` - -## Autostart Machines - -By default in a multi-machine environment, `vagrant up` will start -all of the defined machines. The `autostart` setting allows you to tell -Vagrant to _not_ start specific machines. Example: - -```ruby -config.vm.define "web" -config.vm.define "db" -config.vm.define "db_follower", autostart: false -``` - -When running `vagrant up` with the settings above, Vagrant will automatically -start the "web" and "db" machines, but will not start the "db_follower" machine. -You can manually force the "db_follower" machine to start by running -`vagrant up db_follower`. diff --git a/website/content/docs/networking/basic_usage.mdx b/website/content/docs/networking/basic_usage.mdx deleted file mode 100644 index d15c622f61a..00000000000 --- a/website/content/docs/networking/basic_usage.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -layout: docs -page_title: Basic Usage - Networking -description: |- - Vagrant offers multiple options for how you are able to connect your - guest machines to the network, but there is a standard usage pattern as - well as some points common to all network configurations that - are important to know. ---- - -# Basic Usage of Networking - -Vagrant offers multiple options for how you are able to connect your -guest machines to the network, but there is a standard usage pattern as -well as some points common to all network configurations that -are important to know. - -## Configuration - -All networks are configured within your [Vagrantfile](/vagrant/docs/vagrantfile/) -using the `config.vm.network` method call. For example, the Vagrantfile -below defines some port forwarding: - -```ruby -Vagrant.configure("2") do |config| - # ... - config.vm.network "forwarded_port", guest: 80, host: 8080 -end -``` - -Every network type has an identifier such as `"forwarded_port"` in the above -example. Following this is a set of configuration arguments that can differ -for each network type. In the case of forwarded ports, two numeric arguments -are expected: the port on the guest followed by the port on the host that -the guest port can be accessed by. - -## Multiple Networks - -Multiple networks can be defined by having multiple `config.vm.network` -calls within the Vagrantfile. The exact meaning of this can differ for -each [provider](/vagrant/docs/providers/), but in general the order specifies -the order in which the networks are enabled. - -## Enabling Networks - -Networks are automatically configured and enabled after they've been defined -in the Vagrantfile as part of the `vagrant up` or `vagrant reload` process. - -## Setting Hostname - -A hostname may be defined for a Vagrant VM using the `config.vm.hostname` -setting. By default, this will modify `/etc/hosts`, adding the hostname -on a loopback interface that is not in use. For example: - -```ruby -Vagrant.configure("2") do |config| - # ... - config.vm.hostname = "myhost.local" -end -``` - -will add the entry `127.0.X.1 myhost myhost.local` to `/etc/hosts`. - -A public or private network with an assigned IP may be flagged for hostname. -In this case, the hostname will be added to the flagged network. Note, that -if there are multiple networks only one may be flagged for hostname. For -example: - -```ruby -Vagrant.configure("2") do |config| - # ... - config.vm.hostname = "myhost.local" - config.vm.network "public_network", ip: "192.168.0.1", hostname: true - config.vm.network "public_network", ip: "192.168.0.2" -end -``` - -will add the entry `192.168.0.1 myhost myhost.local` to `/etc/hosts`. diff --git a/website/content/docs/networking/index.mdx b/website/content/docs/networking/index.mdx deleted file mode 100644 index d387372b6cb..00000000000 --- a/website/content/docs/networking/index.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: docs -page_title: Networking -description: |- - In order to access the Vagrant environment created, Vagrant exposes - some high-level networking options for things such as forwarded ports, - connecting to a public network, or creating a private network. ---- - -# Networking - -In order to access the Vagrant environment created, Vagrant exposes -some high-level networking options for things such as forwarded ports, -connecting to a public network, or creating a private network. - -The high-level networking options are meant to define an abstraction that -works across multiple [providers](/vagrant/docs/providers/). This means that -you can take your Vagrantfile you used to spin up a VirtualBox machine and -you can reasonably expect that Vagrantfile to behave the same with something -like VMware. - -You should first read the [basic usage](/vagrant/docs/networking/basic_usage) page -and then continue by reading the documentation for a specific networking -primitive by following the navigation to the left. - -## Advanced Configuration - -In some cases, -these options are _too_ high-level, and you may want to more finely tune -and configure the network interfaces of the underlying machine. Most -providers expose [provider-specific configuration](/vagrant/docs/providers/configuration) -to do this, so please read the documentation for your specific provider -to see what options are available. - --> **For beginners:** It is strongly recommended you use -only the high-level networking options until you are comfortable -with the Vagrant workflow and have things working at a basic level. -Provider-specific network configuration can very quickly lock you out -of your guest machine if improperly done. - -## Networking Assumptions - -### There is a NAT available - -Vagrant assumes there is an available NAT device on eth0. This ensures -that Vagrant always has a way of communicating with the guest machine. -It is possible to change this manually (outside of Vagrant), however, -this may lead to inconsistent behavior. -Providers might have additional assumptions. For example, in VirtualBox, -this assumption means that network adapter 1 is a NAT device. diff --git a/website/content/docs/other/debugging.mdx b/website/content/docs/other/debugging.mdx deleted file mode 100644 index 782b23e498a..00000000000 --- a/website/content/docs/other/debugging.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -layout: docs -page_title: Debugging and Troubleshooting -description: |- - As much as we try to keep Vagrant stable and bug free, it is inevitable - that issues will arise and Vagrant will behave in unexpected ways. In - these cases, Vagrant has amazing support channels available to assist you. ---- - -# Debugging - -As much as we try to keep Vagrant stable and bug free, it is inevitable -that issues will arise and Vagrant will behave in unexpected ways. - -When using these support channels, it is generally helpful to include -debugging logs along with any error reports. These logs can often help you -troubleshoot any problems you may be having. - -!> **Scan for sensitive information!** Vagrant debug logs include information -about your system including environment variables and user information. If you -store sensitive information in the environment or in your user account, please -scan or scrub the debug log of this information before uploading the contents to -the public Internet. - -~> **Submit debug logs using GitHub Gist.** If you plan on submitting a bug -report or issue that includes debug-level logs, please use a service like -[Gist](https://gist.github.com). **Do not** paste the raw debug logs into an -issue as it makes it very difficult to scroll and parse the information. - -To enable detailed logging, set the `VAGRANT_LOG` environmental variable -to the desired log level name, which is one of `debug` (loud), `info` (normal), -`warn` (quiet), and `error` (very quiet). When asking for support, please -set this to `debug`. When troubleshooting your own issues, you should start -with `info`, which is much quieter, but contains important information -about the behavior of Vagrant. - -On Linux and Mac systems, this can be done by prepending the `vagrant` -command with an environmental variable declaration: - -```shell-session -$ VAGRANT_LOG=info vagrant up -``` - -On Windows, multiple steps are required: - -```shell-session -$ set VAGRANT_LOG=info -$ vagrant up -``` - -You can also get the debug level output using the `--debug` command line -option. For example: - -```shell-session -$ vagrant up --debug -``` - -On Linux and Mac, if you are saving the output to a file, you may need to redirect stderr and -stdout using `&>`: - -```shell-session -$ vagrant up --debug &> vagrant.log -``` - -On Windows in PowerShell (outputs to log and screen): - -```shell-session -$ vagrant up --debug 2>&1 | Tee-Object -FilePath ".\vagrant.log" -``` diff --git a/website/content/docs/other/environmental-variables.mdx b/website/content/docs/other/environmental-variables.mdx deleted file mode 100644 index 4b9c86e37e9..00000000000 --- a/website/content/docs/other/environmental-variables.mdx +++ /dev/null @@ -1,362 +0,0 @@ ---- -layout: docs -page_title: Environmental Variables -description: |- - Vagrant has a set of environmental variables that can be used to - configure and control it in a global way. This page lists those environmental - variables. ---- - -# Environmental Variables - -Vagrant has a set of environmental variables that can be used to -configure and control it in a global way. This page lists those environmental -variables. - -## `CFLAGS` - -If set the contents of this environment variable will be appended to the -value generated by the Vagrant launcher. - -## `CPPFLAGS` - -If set the contents of this environment variable will be appended to the -value generated by the Vagrant launcher. - -## `CURL_CA_BUNDLE` - -If set this environment variable will be passed through to the Vagrant -process. By default Vagrant will use the CA certificate included with -the Vagrant installation. - -## `LDFLAGS` - -If set the contents of this environment variable will be appended to the -value generated by the Vagrant launcher. - -## `SSL_CERT_FILE` - -If set this environment variable will be passed through to the Vagrant -process. By default Vagrant will use the CA certificate included with -the Vagrant installation. - -## `VAGRANT_ALIAS_FILE` - -`VAGRANT_ALIAS_FILE` can be set to change the file where Vagrant aliases are -defined. By default, this is set to `~/.vagrant.d/aliases`. - -## `VAGRANT_ALLOW_PLUGIN_SOURCE_ERRORS` - -If this is set to any value, then Vagrant will not error when a configured -plugin source is unavailable. When installing a Vagrant plugin Vagrant -will error and halt if a plugin source is inaccessible. In some cases it -may be desirable to ignore inaccessible sources and continue with the -plugin installation. Enabling this value will cause Vagrant to simply log -the plugin source error and continue. - -## `VAGRANT_BOX_UPDATE_CHECK_DISABLE` - -By default, Vagrant will query the metadata API server to see if a newer -box version is available for download. This optional can be disabled on a -per-Vagrantfile basis with `config.vm.box_check_update`, but it can also be -disabled globally setting `VAGRANT_BOX_UPDATE_CHECK_DISABLE` to any non-empty -value. - -This option will not affect global box functions like `vagrant box update`. - -## `VAGRANT_CHECKPOINT_DISABLE` - -Vagrant does occasional network calls to check whether the version of Vagrant -that is running locally is up to date. We understand that software making remote -calls over the internet for any reason can be undesirable. To suppress these -calls, set the environment variable `VAGRANT_CHECKPOINT_DISABLE` to any -non-empty value. - -If you use other HashiCorp tools like Packer and would prefer to configure this -setting only once, you can set `CHECKPOINT_DISABLE` instead. - -## `VAGRANT_CWD` - -`VAGRANT_CWD` can be set to change the working directory of Vagrant. By -default, Vagrant uses the current directory you are in. The working directory -is important because it is where Vagrant looks for the Vagrantfile. It -also defines how relative paths in the Vagrantfile are expanded, since they're -expanded relative to where the Vagrantfile is found. - -This environmental variable is most commonly set when running Vagrant from -a scripting environment in order to set the directory that Vagrant sees. - -## `VAGRANT_DEBUG_LAUNCHER` - -For performance reasons, especially for Windows users, Vagrant uses a static -binary to launch the actual Vagrant process. If you have _very_ early issues -when launching Vagrant from the official installer, you can specify the -`VAGRANT_DEBUG_LAUNCHER` environment variable to output debugging information -about the launch process. - -## `VAGRANT_DEFAULT_PROVIDER` - -This configures the default provider Vagrant will use. - -This normally does not need to be set since Vagrant is fairly intelligent -about how to detect the default provider. By setting this, you will force -Vagrant to use this provider for any _new_ Vagrant environments. Existing -Vagrant environments will continue to use the provider they came `up` with. -Once you `vagrant destroy` existing environments, this will take effect. - -## `VAGRANT_DEFAULT_TEMPLATE` - -This configures the template used by `vagrant init` when the `--template` option -is not provided. - -## `VAGRANT_DETECTED_ARCH` - -This environment variable may be set by the Vagrant launcher to help determine -the current runtime architecture in use. In general Vagrant will set this value -when running on a Windows host using a cygwin or msys based shell. The value -the Vagrant launcher may set in this environment variable will not always match -the actual architecture of the platform itself. Instead it signifies the detected -architecture of the environment it is running within. If this value is set, the -Vagrant launcher will not modify it. - -## `VAGRANT_DETECTED_OS` - -This environment variable may be set by the Vagrant launcher to help determine -the current runtime platform. In general Vagrant will set this value when running -on a Windows host using a cygwin or msys based shell. If this value is set, the -Vagrant launcher will not modify it. - -## `VAGRANT_DISABLE_RESOLV_REPLACE` - -Vagrant can optionally use the Ruby Resolv library in place of the libc resolver. -This can be disabled setting this environment variable. - -## `VAGRANT_DISABLE_VBOXSYMLINKCREATE` - -If set, this will completely disable the ability to create symlinks with all VirtualBox -shared folders. If this environment variable is not set, the VirtualBox synced -folders option `SharedFoldersEnableSymlinksCreate` will be enabled by default. -This option can be overridden on a per-folder basis within your Vagrantfile -config by setting the `SharedFoldersEnableSymlinksCreate` option to true if you -do not wish to completely disable this feature for all VirtualBox guests. - -More information on the option can be read in the [VirtualBox synced folders docs page.](/vagrant/docs/synced-folders/virtualbox#sharedfoldersenablesymlinkscreate) - -## `VAGRANT_DISABLE_SMBMFSYMLINKS` - -If set, this will disable the `mfsymlinks` option for mounting SMB filesystems. If not set, then the `mfsymlinks` option will be enabled by default. This option can be overriden on a pre-folder basis with your Vagrantfile by setting `mount_options: ['mfsymlinks']`. - -## `VAGRANT_DOTFILE_PATH` - -`VAGRANT_DOTFILE_PATH` can be set to change the directory where Vagrant stores -VM-specific state, such as the VirtualBox VM UUID. By default, this is set to -`.vagrant`. If you keep your Vagrantfile in a Dropbox folder in order to share -the folder between your desktop and laptop (for example), Vagrant will overwrite -the files in this directory with the details of the VM on the most recently-used -host. To avoid this, you could set `VAGRANT_DOTFILE_PATH` to `.vagrant-laptop` -and `.vagrant-desktop` on the respective machines. (Remember to update your -`.gitignore`!) - -## `VAGRANT_ENABLE_RESOLV_REPLACE` - -Use the Ruby Resolv library in place of the libc resolver. - -## `VAGRANT_FORCE_COLOR` - -If this is set to any value, then Vagrant will force colored output, even -if it detected that there is no TTY or the current environment does not -support it. - -The equivalent behavior can be achieved by using the `--color` flag on a -command-by-command basis. This environmental variable is useful for setting -this flag globally. - -## `VAGRANT_HOME` - -`VAGRANT_HOME` can be set to change the directory where Vagrant stores -global state. By default, this is set to `~/.vagrant.d`. The Vagrant home -directory is where things such as boxes are stored, so it can actually become -quite large on disk. - -## `VAGRANT_IGNORE_WINRM_PLUGIN` - -Vagrant will not display warning when `vagrant-winrm` plugin is installed. - -## `VAGRANT_INSTALL_LOCAL_PLUGINS` - -If this is set to any value, Vagrant will not prompt for confirmation -prior to installing local plugins which have been defined within the -local Vagrantfile. - -## `VAGRANT_IS_HYPERV_ADMIN` - -Disable Vagrant's check for Hyper-V admin privileges and allow Vagrant to assume -the current user has full access to Hyper-V. This is useful if the internal -privilege check incorrectly determines the current user does not have access -to Hyper-V. - -## `VAGRANT_LOCAL_PLUGINS_LOAD` - -If this is set Vagrant will not stub the Vagrantfile when running -`vagrant plugin` commands. When this environment variable is set the -`--local` flag will not be required by `vagrant plugin` commands to -enable local project plugins. - -## `VAGRANT_LOG` - -`VAGRANT_LOG` specifies the verbosity of log messages from Vagrant. -By default, Vagrant does not actively show any log messages. - -Log messages are very useful when troubleshooting issues, reporting -bugs, or getting support. At the most verbose level, Vagrant outputs -basically everything it is doing. - -Available log levels are "debug," "info," "warn," and "error." Both -"warn" and "error" are practically useless since there are very few -cases of these, and Vagrant generally reports them within the normal -output. - -"info" is a good level to start with if you are having problems, because -while it is much louder than normal output, it is still very human-readable -and can help identify certain issues. - -"debug" output is _extremely_ verbose and can be difficult to read without -some knowledge of Vagrant internals. It is the best output to attach to -a support request or bug report, however. - -## `VAGRANT_MAX_REBOOT_RETRY_DURATION` - -By default, Vagrant will wait up to 120 seconds for a machine to reboot. -However, if you're finding your OS is taking longer than 120 seconds to -reboot successfully, you can configure this environment variable and Vagrant -will wait for the configured number of seconds. - -## `VAGRANT_NO_COLOR` - -If this is set to any value, then Vagrant will not use any colorized -output. This is useful if you are logging the output to a file or -on a system that does not support colors. - -The equivalent behavior can be achieved by using the `--no-color` flag -on a command-by-command basis. This environmental variable is useful -for setting this flag globally. - -## `VAGRANT_NO_PARALLEL` - -If this is set, Vagrant will not perform any parallel operations (such as -parallel box provisioning). All operations will be performed in serial. - -## `VAGRANT_NO_PLUGINS` - -If this is set to any value, then Vagrant will not load any 3rd party -plugins. This is useful if you install a plugin and it is introducing -instability to Vagrant, or if you want a specific Vagrant environment to -not load plugins. - -Note that any `vagrant plugin` commands automatically do not load any -plugins, so if you do install any unstable plugins, you can always use -the `vagrant plugin` commands without having to worry. - -## `VAGRANT_POWERSHELL_VERSION_DETECTION_TIMEOUT` - -Vagrant will use a default timeout when checking for the installed version -of PowerShell. Occasionally the default can be too low and Vagrant will report -being unable to detect the installed version of PowerShell. This environment -variable can be used to extend the timeout used during PowerShell version -detection. - -When setting this environment variable, its value will be in seconds. By default, -it will use 30 seconds as a timeout. - -## `VAGRANT_PREFERRED_POWERSHELL` - -When executing PowerShell commands, Vagrant will prefer to use `pwsh.exe` -over `powershell.exe` by default. This environment variable can be used to -modify this preference and make Vagrant prefer `powershell.exe`. The value -set in this environment variable are any supported PowerShell executables -which currently are: `powershell` and `pwsh`. - -## `VAGRANT_PREFERRED_PROVIDERS` - -This configures providers that Vagrant should prefer. - -Much like the `VAGRANT_DEFAULT_PROVIDER` this environment variable normally -does not need to be set. By setting this you will instruct Vagrant to -_prefer_ providers defined in this environment variable for any _new_ -Vagrant environments. Existing Vagrant environments will continue to use -the provider they came `up` with. Once you `vagrant destroy` existing environments, -this will take effect. A single provider can be defined within this environment -variable or a comma delimited list of providers. - -## `VAGRANT_PREFER_SYSTEM_BIN` - -If this is set, Vagrant will prefer using utility executables (like `ssh` and `rsync`) -from the local system instead of those vendored within the Vagrant installation. - -Vagrant will default to using a system provided `ssh` on Windows. This -environment variable can also be used to disable that behavior to force Vagrant to -use the embedded `ssh` executable by setting it to `0`. - -## `VAGRANT_SUPPRESS_GO_EXPERIMENTAL_WARNING` - -If this is set, Vagrant-go will not output a warning message about compatibility -with Vagrant-ruby. This does not effect the stable Ruby release of Vagrant. - -## `VAGRANT_DISABLE_WINCURL` - -If set Vagrant will use the mingw build of curl which uses the installer provided -ca-certificates bundle instead of the native Windows curl executable. - -## `VAGRANT_SERVER_URL` - -This configures the remote server which Vagrant will connect to for fetching -Vagrant boxes. By default this is configured for Vagrant Cloud (https://vagrantcloud.com) - -## `VAGRANT_SERVER_ACCESS_TOKEN_BY_URL` - -If this is set Vagrant will change the way it authenticates with the configured -Vagrant server. When set, the authentication behavior will be reverted to the -deprecated authentication behavior of: - -1. not adding an authentication header to the request -2. setting the configured access token as a query parameter on URLs - -This behavior can be useful for third party servers which do not accept the -authentication header currently used with Vagrant Cloud. - -## `VAGRANT_SKIP_SUBPROCESS_JAILBREAK` - -As of Vagrant 1.7.3, Vagrant tries to intelligently detect if it is running in -the installer or running via Bundler. Although not officially supported, Vagrant -tries its best to work when executed via Bundler. When Vagrant detects that you -have spawned a subprocess that lives outside of Vagrant's installer, Vagrant -will do its best to reset the preserved environment during the subprocess -execution. - -If Vagrant detects it is running outside of the officially installer, the -original environment will always be restored. You can disable this automatic -jailbreak by setting `VAGRANT_SKIP_SUBPROCESS_JAILBREAK`. - -## `VAGRANT_USER_AGENT_PROVISIONAL_STRING` - -Vagrant will append the contents of this variable to the default user agent header. - -## `VAGRANT_USE_VAGRANT_TRIGGERS` - -Vagrant will not display the warning about disabling the core trigger feature if -the community plugin is installed. - -## `VAGRANT_VAGRANTFILE` - -This specifies the filename of the Vagrantfile that Vagrant searches for. -By default, this is "Vagrantfile". Note that this is _not_ a file path, -but just a filename. - -This environmental variable is commonly used in scripting environments -where a single folder may contain multiple Vagrantfiles representing -different configurations. - -## `VAGRANT_WINPTY_DISABLE` - -If this is set, Vagrant will _not_ wrap interactive processes with winpty where -required. diff --git a/website/content/docs/other/index.mdx b/website/content/docs/other/index.mdx deleted file mode 100644 index 29541ebfba9..00000000000 --- a/website/content/docs/other/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: docs -page_title: Other -description: |- - This page covers Vagrant information that does not quite fit under the other - categories. ---- - -# Other - -This section covers other information that does not quite fit under the -other categories. - -- [Debugging](/vagrant/docs/other/debugging) -- [Environment Variables](/vagrant/docs/other/environmental-variables) diff --git a/website/content/docs/other/macos-catalina.mdx b/website/content/docs/other/macos-catalina.mdx deleted file mode 100644 index 92fa5e5ca4e..00000000000 --- a/website/content/docs/other/macos-catalina.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: docs -page_title: Vagrant and macOS Catalina -description: An overview of using Vagrant on macOS Catalina. ---- - -# Vagrant and macOS Catalina - -The latest version of macOS (Catalina) includes security changes that prevent -applications from accessing data in your Documents, Desktop, and Downloads -folders without explicit permission. If you keep any virtual machine files in -these folders, you will need to allow access to these folders for your terminal -emulator. - -Initially when you try to access one of these folders from the command line, you -should see a popup that says something like: - -> “Terminal” would like to access files in your Documents folder. - -Click "OK" to grant those permissions. - -If you click "Don't Allow" and find that you need to grant access later on, you -can go to "System Preferences" -> "Security & Privacy" -> "Files and Folders" -and you should see your terminal emulator there. Click on the lock, and then -click on the checkbox next to the folder that contains the files that Vagrant -needs to access. - -Note that granting the `vagrant` binary "Full Disk Access" is not sufficient or -necessary. If Terminal (or iTerm2/Hyper/etc.) is granted access to a particular -folder, then Vagrant will also be able to access that folder. diff --git a/website/content/docs/other/wsl.mdx b/website/content/docs/other/wsl.mdx deleted file mode 100644 index dbbff3d3c24..00000000000 --- a/website/content/docs/other/wsl.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -layout: docs -page_title: Vagrant and Windows Subsystem for Linux -description: |- - An overview of using Vagrant on Windows within the Windows Subsystem - for Linux. ---- - -# Vagrant and Windows Subsystem for Linux - -Recent versions of Windows 10 now include Windows Subsystem for Linux (WSL) as -an optional Windows feature. The WSL supports running a Linux environment -within Windows. Vagrant support for WSL is still in development and should -be considered _beta_. - -~> **Warning: Advanced Topic!** Using Vagrant within the Windows -Subsystem for Linux is an advanced topic that only experienced Vagrant users -who are reasonably comfortable with Windows, WSL, and Linux should approach. - -## Vagrant Installation - -Vagrant _must_ be installed within the Linux distribution used with WSL. While -the `vagrant.exe` executable provided by the Vagrant Windows installation is -accessible from within the WSL, it will not function as expected. - -Download the installer package for the Linux distribution from the releases -page and install Vagrant. - -**NOTE: When Vagrant is installed on the Windows system the version installed -within the Linux distribution _must_ match.** - -# Vagrant Usage - -## Windows Access - -By default Vagrant will not access features available on the Windows system -from within the WSL. This means the VirtualBox and Hyper-V providers will -not be available. To enable Windows access, which will also enable the -VirtualBox and Hyper-V providers, set the `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS` -environment variable: - -```shell-session -$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" -``` - -When Windows access is enabled Vagrant will automatically adjust `VAGRANT_HOME` -to be located on the Windows host. This is required to ensure `VAGRANT_HOME` -is located on a DrvFs file system. - -## PATH modifications - -Vagrant will detect when it is being run within the WSL and adjust how it -locates and executes third party executables. For example, when using the -VirtualBox provider Vagrant will interact with VirtualBox installed on -the Windows system, not within the WSL. It is important to ensure that -any required Windows executable is available within your `PATH` to allow -Vagrant to access them. - -For example, when using the VirtualBox provider: - -```shell -export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox" -``` - -## Synced Folders - -Support for synced folders within the WSL is implementation dependent. In -most cases synced folders will not be supported when running Vagrant within -WSL on a VolFs file system. Synced folder implementations must "opt-in" to -supporting usage from VolFs file systems. To use synced folders from within -the WSL that do not support VolFs file systems, move the Vagrant project -directory to a DrvFs file system location (/mnt/c/ prefixed path for example). - -## Windows Access - -Working within the WSL provides a layer of isolation from the actual -Windows system. In most cases Vagrant will need access to the actual -Windows system to function correctly. As most Vagrant providers will -need to be installed on Windows directly (not within the WSL) Vagrant -will require Windows access. Access to the Windows system is controlled -via an environment variable: `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS`. If -this environment variable is set, Vagrant will access the Windows system -to run executables and enable things like synced folders. When running -in a bash shell within WSL, the environment variable can be setup like so: - -```shell-session -$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" -``` - -This will enable Vagrant to access the Windows system outside of the -WSL and properly interact with Windows executables. This will automatically -modify the `VAGRANT_HOME` environment variable if it is not already defined, -setting it to be within the user's home directory on Windows. - -It is important to note that paths shared with the Windows system will -not have Linux permissions enforced. For example, when a directory within -the WSL is synced to a guest using the VirtualBox provider, any local -permissions defined on that directory (or its contents) will not be -visible from the guest. Likewise, any files created from the guest within -the synced folder will be world readable/writeable in WSL. - -Other useful WSL related environment variables: - -- `VAGRANT_WSL_WINDOWS_ACCESS_USER` - Override current Windows username -- `VAGRANT_WSL_DISABLE_VAGRANT_HOME` - Do not modify the `VAGRANT_HOME` variable -- `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` - Custom Windows system home path - -If a Vagrant project directory is not within the user's home directory on the -Windows system, certain actions that include permission checks may fail (like -`vagrant ssh`). When accessing Vagrant projects outside the WSL Vagrant will -skip these permission checks when the project path is within the path defined -in the `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` environment variable. For -example, if a user wants to run a Vagrant project from the WSL that is located -at `C:\TestDir\vagrant-project`: - -```shell-session -C:\Users\vagrant> cd C:\TestDir\vagrant-project -C:\TestDir\vagrant-project> bash -vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ export VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH="/mnt/c/TestDir" -vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ vagrant ssh -``` - -## Using Docker - -The docker daemon cannot be run inside the Windows Subsystem for Linux. However, -the daemon _can_ be run on Windows and accessed by Vagrant while running in the -WSL. Once docker is installed and running on Windows, export the following -environment variable to give Vagrant access: - -```shell-session -vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375 -``` diff --git a/website/content/docs/plugins/commands.mdx b/website/content/docs/plugins/commands.mdx deleted file mode 100644 index 9a3da151d5a..00000000000 --- a/website/content/docs/plugins/commands.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -layout: docs -page_title: Command Plugins - Plugin Development -description: |- - This page documents how to add new commands to Vagrant, invocable - via "vagrant YOUR-COMMAND". Prior to reading this, you should be familiar - with the plugin development basics. ---- - -# Plugin Development: Commands - -This page documents how to add new commands to Vagrant, invocable -via `vagrant YOUR-COMMAND`. Prior to reading this, you should be familiar -with the [plugin development basics](/vagrant/docs/plugins/development-basics). - -~> **Warning: Advanced Topic!** Developing plugins is an -advanced topic that only experienced Vagrant users who are reasonably -comfortable with Ruby should approach. - -## Definition Component - -Within the context of a plugin definition, new commands can be defined -like so: - -```ruby -command "foo" do - require_relative "command" - Command -end -``` - -Commands are defined with the `command` method, which takes as an argument -the name of the command, in this case "foo." This means the command will be -invocable via `vagrant foo`. Then the block argument returns a class that -implements the `Vagrant.plugin(2, "command")` interface. - -You can also define _non-primary commands_. These commands do not show -up in the `vagrant -h` output. They only show up if the user explicitly -does a `vagrant list-commands` which shows the full listing of available -commands. This is useful for highly specific commands or plugins that a -beginner to Vagrant would not be using anyways. Vagrant itself uses non-primary -commands to expose some internal functions, as well. - -To define a non-primary command: - -```ruby -command("foo", primary: false) do - require_relative "command" - Command -end -``` - -## Implementation - -Implementations of commands should subclass `Vagrant.plugin(2, :command)`, -which is a Vagrant method that will return the proper superclass for -a version 2 command. The implementation itself is quite simple, since the -class needs to only implement a single method: `execute`. Example: - -```ruby -class Command < Vagrant.plugin(2, :command) - def execute - puts "Hello!" - 0 - end -end -``` - -The `execute` method is called when the command is invoked, and it should -return the exit status (0 for success, anything else for error). - -This is a command at its simplest form. Of course, the command superclass -gives you access to the Vagrant environment and provides some helpers to -do common tasks such as command line parsing. - -## Parsing Command-Line Options - -The `parse_options` method is available which will parse the command line -for you. It takes an [OptionParser](http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html) -as an argument, and adds some common elements to it such as the `--help` flag, -automatically showing help if requested. View the API docs directly for more -information. - -This is recommended over raw parsing/manipulation of command line flags. -The following is an example of parsing command line flags pulled directly -from the built-in Vagrant `destroy` command: - -```ruby -options = {} -options[:force] = false - -opts = OptionParser.new do |o| - o.banner = "Usage: vagrant destroy [vm-name]" - o.separator "" - - o.on("-f", "--force", "Destroy without confirmation.") do |f| - options[:force] = f - end -end - -# Parse the options -argv = parse_options(opts) -``` - -## Using Vagrant Machines - -The `with_target_vms` method is a helper that helps you interact with -the machines that Vagrant manages in a standard Vagrant way. This method -automatically does the right thing in the case of multi-machine environments, -handling target machines on the command line (`vagrant foo my-vm`), etc. -If you need to do any manipulation of a Vagrant machine, including SSH -access, this helper should be used. - -An example of using the helper, again pulled directly from the built-in -`destroy` command: - -```ruby -with_target_vms(argv, reverse: true) do |machine| - machine.action(:destroy) -end -``` - -In this case, it asks for the machines in reverse order and calls the -destroy action on each of them. If a user says `vagrant destroy foo`, then -the helper automatically only yields the `foo` machine. If no parameter -is given and it is a multi-machine environment, every machine in the environment -is yielded, and so on. It just does the right thing. - -## Using the Raw Vagrant Environment - -The raw loaded `Vagrant::Environment` object is available with the -'@env' instance variable. diff --git a/website/content/docs/plugins/usage.mdx b/website/content/docs/plugins/usage.mdx deleted file mode 100644 index 463f301f130..00000000000 --- a/website/content/docs/plugins/usage.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -layout: docs -page_title: Plugin Usage - Plugins -description: |- - Installing a Vagrant plugin is easy, and should not take more than a few - seconds. ---- - -# Plugin Usage - -Installing a Vagrant plugin is easy, and should not take more than a few seconds. - -Please refer to the documentation of any plugin you plan on using for -more information on how to use it, but there is one common method for -installation and plugin activation. - -~> **Warning!** 3rd party plugins can introduce instabilities -into Vagrant due to the nature of them being written by non-core users. - -## Installation - -Plugins are installed using `vagrant plugin install`: - -```shell -# Installing a plugin from a known gem source -$ vagrant plugin install my-plugin - -# Installing a plugin from a local file source -$ vagrant plugin install /path/to/my-plugin.gem -``` - -Once a plugin is installed, it will automatically be loaded by Vagrant. -Plugins which cannot be loaded should not crash Vagrant. Instead, -Vagrant will show an error message that a plugin failed to load. - -## Usage - -Once a plugin is installed, you should refer to the plugin's documentation -to see exactly how to use it. Plugins which add commands should be instantly -available via `vagrant`, provisioners should be available via -`config.vm.provision`, etc. - -**Note:** In the future, the `vagrant plugin` command will include a -subcommand that will document the components that each plugin installs. - -## Updating - -Plugins can be updated by running `vagrant plugin update`. This will -update every installed plugin to the latest version. You can update a -specific plugin by calling `vagrant plugin update NAME`. Vagrant will -output what plugins were updated and to what version. - -To determine the changes in a specific version of a plugin, refer to -the plugin's homepage (usually a GitHub page or similar). It is the -plugin author's responsibility to provide a change log if he or she -chooses to. - -## Uninstallation - -Uninstalling a plugin is as easy as installing it. Just use the -`vagrant plugin uninstall` command and the plugin will be removed. Example: - -```shell-session -$ vagrant plugin uninstall my-plugin -``` - -## Listing Plugins - -To view what plugins are installed into your Vagrant environment at -any time, use the `vagrant plugin list` command. This will list the plugins -that are installed along with their version. diff --git a/website/content/docs/providers/default.mdx b/website/content/docs/providers/default.mdx deleted file mode 100644 index 76b54648346..00000000000 --- a/website/content/docs/providers/default.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: docs -page_title: Default Provider - Providers -description: |- - By default, VirtualBox is the default provider for Vagrant. VirtualBox is - still the most accessible platform to use Vagrant: it is free, cross-platform, - and has been supported by Vagrant for years. With VirtualBox as the default - provider, it provides the lowest friction for new users to get started with - Vagrant. ---- - -# Default Provider - -By default, VirtualBox is the default provider for Vagrant. VirtualBox is -still the most accessible platform to use Vagrant: it is free, cross-platform, -and has been supported by Vagrant for years. With VirtualBox as the default -provider, it provides the lowest friction for new users to get started with -Vagrant. - -However, you may find after using Vagrant for some time that you prefer -to use another provider as your default. In fact, this is quite common. -To make this experience better, Vagrant allows specifying the default -provider to use by setting the `VAGRANT_DEFAULT_PROVIDER` environmental -variable. - -Just set `VAGRANT_DEFAULT_PROVIDER` to the provider you wish to be the -default. For example, if you use Vagrant with VMware Fusion, you can set -the environmental variable to `vmware_desktop` and it will be your default. diff --git a/website/content/docs/providers/docker/basics.mdx b/website/content/docs/providers/docker/basics.mdx deleted file mode 100644 index ffc9635fe5a..00000000000 --- a/website/content/docs/providers/docker/basics.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -layout: docs -page_title: Basic Usage - Docker Provider -description: |- - The Docker provider in Vagrant behaves just like any other provider. - If you are familiar with Vagrant already, then using the Docker provider - should be intuitive and simple. ---- - -# Docker Basic Usage - -The Docker provider in Vagrant behaves just like any other provider. -If you are familiar with Vagrant already, then using the Docker provider -should be intuitive and simple. - -The Docker provider _does not_ require a `config.vm.box` setting. Since -the "base image" for a Docker container is pulled from the -Docker Index or -built from a Dockerfile, the box does not -add much value, and is optional for this provider. - -## Docker Images - -The first method that Vagrant can use to source a Docker container -is via an image. This image can be from any Docker registry. An -example is shown below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provider "docker" do |d| - d.image = "foo/bar" - end -end -``` - -When `vagrant up --provider=docker` is run, this will bring up the -image `foo/bar`. - -This is useful for extra components of your application that it might -depend on: databases, queues, etc. Typically, the primary application -you are working on is built with a Dockerfile, or via a container with -SSH. - -## Dockerfiles - -Vagrant can also automatically build and run images based on a local -Dockerfile. This is useful for iterating on an application locally -that is built into an image later. An example is shown below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provider "docker" do |d| - d.build_dir = "." - end -end -``` - -The above configuration will look for a `Dockerfile` in the same -directory as the Vagrantfile. When `vagrant up --provider=docker` is run, Vagrant -automatically builds that Dockerfile and starts a container -based on that Dockerfile. - -The Dockerfile is rebuilt when `vagrant reload` is called. - -## Synced Folders and Networking - -When using Docker, Vagrant automatically converts synced folders -and networking options into Docker volumes and forwarded ports. -You do not have to use the Docker-specific configurations to do this. -This helps keep your Vagrantfile similar to how it has always looked. - -The Docker provider does not support specifying options for `owner` or `group` -on folders synced with a docker container. - -### Volume Consistency - -Docker's [volume consistency](https://docs.docker.com/v17.09/engine/admin/volumes/bind-mounts/) setting can be specified using the `docker_consistency` option when defining a synced folder. This can -[greatly improve performance on macOS](https://docs.docker.com/docker-for-mac/osxfs-caching). An example is shown using the `cached` and `delegated` settings: - -```ruby -config.vm.synced_folder "/host/dir1", "/guest/dir1", docker_consistency: "cached" -config.vm.synced_folder "/host/dir2", "/guest/dir2", docker_consistency: "delegated" -``` - -## Host VM - -If the system cannot run Linux containers natively, Vagrant automatically spins -up a "host VM" to run Docker. This allows your Docker-based Vagrant environments -to remain portable, without inconsistencies depending on the platform they are -running on. - -Vagrant will spin up a single instance of a host VM and run multiple -containers on this one VM. This means that with the Docker provider, -you only have the overhead of one virtual machine, and only if it is -absolutely necessary. - -By default, the host VM Vagrant spins up is -[backed by boot2docker](https://github.com/hashicorp/vagrant/blob/main/plugins/providers/docker/hostmachine/Vagrantfile), -because it launches quickly and uses little resources. But the host VM -can be customized to point to _any_ Vagrantfile. This allows the host VM -to more closely match production by running a VM running Ubuntu, RHEL, -etc. It can run any operating system supported by Vagrant. - --> **Synced folder note:** Vagrant will attempt to use the -"best" synced folder implementation it can. For boot2docker, this is -often rsync. In this case, make sure you have rsync installed on your -host machine. Vagrant will give you a human-friendly error message if -it is not. - -An example of changing the host VM is shown below. Remember that this -is optional, and Vagrant will spin up a default host VM if it is not -specified: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provider "docker" do |d| - d.vagrant_vagrantfile = "../path/to/Vagrantfile" - end -end -``` - -The host VM will be spun up at the first `vagrant up` where the provider -is Docker. To control this host VM, use the -[global-status command](/vagrant/docs/cli/global-status) -along with global control. diff --git a/website/content/docs/providers/docker/index.mdx b/website/content/docs/providers/docker/index.mdx deleted file mode 100644 index 19fab6ffbda..00000000000 --- a/website/content/docs/providers/docker/index.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: docs -page_title: Docker Provider -description: |- - Vagrant comes with support out of the box for - using Docker as a provider. This allows for your development environments - to be backed by Docker containers rather than virtual machines. Additionally, - it provides for a good workflow for developing Dockerfiles. ---- - -# Docker - -Vagrant comes with support out of the box for -using Docker as a provider. This allows for your development environments -to be backed by Docker containers rather than virtual machines. Additionally, -it provides for a good workflow for developing Dockerfiles. - -~> **Warning: Docker knowledge assumed.** We assume that -you know what Docker is and that you are comfortable with the basics -of Docker. If not, we recommend starting with another provider such -as [VirtualBox](/vagrant/docs/providers/virtualbox). - -Use the navigation to the left to find a specific Docker topic -to read more about. diff --git a/website/content/docs/providers/hyperv/index.mdx b/website/content/docs/providers/hyperv/index.mdx deleted file mode 100644 index 272bf41acbb..00000000000 --- a/website/content/docs/providers/hyperv/index.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: docs -page_title: Hyper-V Provider -description: |- - Vagrant comes with support out of the box for Hyper-V, a native hypervisor - written by Microsoft. Hyper-V is available by default for almost all - Windows 8.1 and later installs. ---- - -# Hyper-V - -Vagrant comes with support out of the box for [Hyper-V](https://en.wikipedia.org/wiki/Hyper-V), -a native hypervisor written by Microsoft. Hyper-V is available by default for -almost all Windows 8.1 and later installs. - -The Hyper-V provider is compatible with Windows 8.1 and later only. Prior versions -of Hyper-V do not include the necessary APIs for Vagrant to work. - -Hyper-V must be enabled prior to using the provider. Most Windows installations -will not have Hyper-V enabled by default. Hyper-V is available by default for -almost all Windows Enterprise, Professional, or Education 8.1 and later installs. -To enable Hyper-V, go to "Programs and Features", click on "Turn Windows -features on or off" and check the box next to "Hyper-V". Or install via -PowerShell with: - -```powershell -Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All -``` - -See official documentation [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). diff --git a/website/content/docs/providers/hyperv/limitations.mdx b/website/content/docs/providers/hyperv/limitations.mdx deleted file mode 100644 index 9458f926f63..00000000000 --- a/website/content/docs/providers/hyperv/limitations.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: docs -page_title: Limitations - Hyper-V Provider -description: |- - The Hyper-V provider works in almost every way like the VirtualBox - or VMware provider would, but has some limitations that are inherent to - Hyper-V itself. ---- - -# Limitations - -The Vagrant Hyper-V provider works in almost every way like the VirtualBox -or VMware provider would, but has some limitations that are inherent to -Hyper-V itself. - -## Limited Networking - -Vagrant does not yet know how to create and configure new networks for -Hyper-V. When launching a machine with Hyper-V, Vagrant will prompt you -asking what virtual switch you want to connect the virtual machine to. - -A result of this is that networking configurations in the Vagrantfile -are completely ignored with Hyper-V. Vagrant cannot enforce a static IP -or automatically configure a NAT. - -However, the IP address of the machine will be reported as part of -the `vagrant up`, and you can use that IP address as if it were -a host only network. - -## Snapshots - -Restoring snapshot VMs using `vagrant snapshot pop` or -`vagrant snapshot restore` will sometimes raise errors when mounting -SMB shared folders, however these mounts will still work inside the guest. diff --git a/website/content/docs/providers/hyperv/usage.mdx b/website/content/docs/providers/hyperv/usage.mdx deleted file mode 100644 index 6c6f0f015b2..00000000000 --- a/website/content/docs/providers/hyperv/usage.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: docs -page_title: Usage - Hyper-V Provider -description: |- - The Hyper-V provider is used just like any other provider. Please read the - general basic usage page for providers. ---- - -# Usage - -The Vagrant Hyper-V provider is used just like any other provider. Please -read the general [basic usage](/vagrant/docs/providers/basic_usage) page for -providers. - -The value to use for the `--provider` flag is `hyperv`. - -Hyper-V also requires that you execute Vagrant with administrative -privileges. Creating and managing virtual machines with Hyper-V requires -admin rights. Vagrant will show you an error if it does not have the proper -permissions. - -Boxes for Hyper-V can be easily found on -[HashiCorp's Vagrant Cloud](https://vagrantcloud.com/boxes/search). To get started, you might -want to try the `hashicorp/bionic64` box. diff --git a/website/content/docs/providers/index.mdx b/website/content/docs/providers/index.mdx deleted file mode 100644 index 2444f54f2dd..00000000000 --- a/website/content/docs/providers/index.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: docs -page_title: Providers -description: |- - While Vagrant ships out of the box with support for VirtualBox, Hyper-V, and - Docker. Vagrant has the ability to manage other types of machines as well. - This is done by using other providers with Vagrant. ---- - -# Providers - -While Vagrant ships out of the box with support for [VirtualBox](https://www.virtualbox.org), -[Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/), and [Docker](https://www.docker.io), -Vagrant has the ability to manage other types of machines as well. This is done -by using other _providers_ with Vagrant. - -Alternate providers can offer different features that make more sense in your use case. -For example, if you are using Vagrant for any real work, [VMware](https://www.vmware.com) -providers are recommended since they're well supported and generally more -stable and performant than VirtualBox. - -Before you can use another provider, you must install it. Installation of other providers -is done via the Vagrant plugin system. - -Once the provider is installed, usage is straightforward and simple, as -you would expect with Vagrant. Read into the relevant subsections found in -the navigation to the left for more information. diff --git a/website/content/docs/providers/installation.mdx b/website/content/docs/providers/installation.mdx deleted file mode 100644 index cb412f5375a..00000000000 --- a/website/content/docs/providers/installation.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: docs -page_title: Installation - Providers -description: |- - Providers are distributed as Vagrant plugins, and are therefore installed - using standard plugin installation steps. After installing a plugin which - contains a provider, the provider should immediately be available. ---- - -# Provider Installation - -Providers are distributed as Vagrant plugins, and are therefore installed -using [standard plugin installation steps](/vagrant/docs/plugins/usage). After -installing a plugin which contains a provider, the provider should -immediately be available. diff --git a/website/content/docs/providers/virtualbox/common-issues.mdx b/website/content/docs/providers/virtualbox/common-issues.mdx deleted file mode 100644 index 4da808cf8b1..00000000000 --- a/website/content/docs/providers/virtualbox/common-issues.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: docs -page_title: Common Issues - VirtualBox Provider -description: |- - This page lists some common issues people run into with Vagrant and VirtualBox - as well as solutions for those issues. ---- - -# Common Issues - -This page lists some common issues people run into with Vagrant and VirtualBox -as well as solutions for those issues. - -## Hanging on Windows - -If Vagrant commands are hanging on Windows because they're communicating -to VirtualBox, this may be caused by a permissions issue with VirtualBox. -This is easy to fix. Starting VirtualBox as a normal user or as an -administrator will prevent you from using it in the opposite way. Please keep -in mind that when Vagrant interacts with VirtualBox, it will interact with -it with the same access level as the console running Vagrant. - -To fix this issue, completely shut down all VirtualBox machines and GUIs. -Wait a few seconds. Then, launch VirtualBox only with the access level you -wish to use. - -## DNS Not Working - -If DNS is not working within your VM, then you may need to enable -a DNS proxy (built-in to VirtualBox). Please [see the StackOverflow answers -here](https://serverfault.com/questions/453185/vagrant-virtualbox-dns-10-0-2-3-not-working) -for a guide on how to do that. diff --git a/website/content/docs/providers/virtualbox/index.mdx b/website/content/docs/providers/virtualbox/index.mdx deleted file mode 100644 index 236127455e1..00000000000 --- a/website/content/docs/providers/virtualbox/index.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: docs -page_title: VirtualBox Provider -description: |- - Vagrant comes with support out of the box for VirtualBox, a free, - cross-platform consumer virtualization product. ---- - -# VirtualBox - -Vagrant comes with support out of the box for [VirtualBox](https://www.virtualbox.org), -a free, cross-platform consumer virtualization product. - -The VirtualBox provider is compatible with VirtualBox versions 4.0.x, 4.1.x, -4.2.x, 4.3.x, 5.0.x, 5.1.x, 5.2.x, 6.0.x, 6.1.x, 7.0.x, and 7.1.x. Other versions -are unsupported and the provider will display an error message. Please note that -beta and pre-release versions VirtualBox are not supported and may not be well-behaved. - -VirtualBox must be installed on its own prior to using the provider, or -the provider will display an error message asking you to install it. -VirtualBox can be installed by [downloading](https://www.virtualbox.org/wiki/Downloads) -a package or installer for your operating system and using standard procedures -to install that package. - -Use the navigation to the left to find a specific VirtualBox topic to read more about. diff --git a/website/content/docs/providers/virtualbox/usage.mdx b/website/content/docs/providers/virtualbox/usage.mdx deleted file mode 100644 index 29661f53520..00000000000 --- a/website/content/docs/providers/virtualbox/usage.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: docs -page_title: Usage - VirtualBox Provider -description: |- - The Vagrant VirtualBox provider is used just like any other provider. Please - read the general basic usage page for providers. ---- - -# Usage - -The Vagrant VirtualBox provider is used just like any other provider. Please -read the general [basic usage](/vagrant/docs/providers/basic_usage) page for -providers. - -The value to use for the `--provider` flag is `virtualbox`. - -The Vagrant VirtualBox provider does not support parallel execution at this -time. Specifying the `--parallel` option will have no effect. diff --git a/website/content/docs/providers/vmware/faq.mdx b/website/content/docs/providers/vmware/faq.mdx deleted file mode 100644 index fcef7c646a8..00000000000 --- a/website/content/docs/providers/vmware/faq.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -layout: docs -page_title: Frequently Asked Questions - VMware Provider -description: |- - Frequently asked questions related to using Vagrant with VMware - Workstation and VMware Fusion ---- - -# Frequently Asked Questions - -## Q: How do I use the VMware Fusion Tech Preview? - -The Vagrant VMware utility expects VMware Fusion to be installed in a specific -path on macOS. Since the VMware Fusion Tech Preview installs into a different -path, the Vagrant VMware utility will fail to detect the installation and will -not start. To resolve this you can create a symlink from the VMware Fusion -Tech Preview installation path to the normal VMware Fusion installation path: - -```shell-session -sudo ln -s /Applications/VMware\ Fusion\ Tech\ Preview.app /Applications/VMware\ Fusion.app -``` - - -## Q: How do I upgrade my currently installed Vagrant VMware plugin? - -You can update the Vagrant VMware plugin to the latest version by re-running the -install command: - -```shell-session -$ vagrant plugin install vagrant-vmware-desktop -``` - -To upgrade the Vagrant VMware utility, download the latest version from the -[Vagrant VMware utility downloads page](/vagrant/downloads/vmware) and install the -system package to your local system. - -## Q: Do I need a license for the Vagrant VMware plugin? - -No, the Vagrant VMware plugin has been open sourced under the MPL. A license -is no longer required for using the Vagrant VMware plugin. If the plugin you -are using still requires a license, simply upgrade your plugin: - -``` -$ vagrant plugin update vagrant-vmware-desktop -``` diff --git a/website/content/docs/providers/vmware/index.mdx b/website/content/docs/providers/vmware/index.mdx deleted file mode 100644 index 92ada344960..00000000000 --- a/website/content/docs/providers/vmware/index.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: docs -page_title: VMware Provider -description: |- - HashiCorp develops an official VMware Fusion and VMware Workstation provider - for Vagrant. This provider allows Vagrant to power VMware based machines and - take advantage of the improved stability and performance that VMware software - offers. ---- - -# VMware - -[HashiCorp](https://www.hashicorp.com) develops an official -[VMware Fusion](https://www.vmware.com/products/fusion/overview.html) -and [VMware Workstation](https://www.vmware.com/products/workstation/)  -[provider](/vagrant/docs/providers/) for Vagrant. This provider allows -Vagrant to power VMware based machines and take advantage of the -improved stability and performance that VMware software offers. - -The Vagrant VMware plugin is now open sourced under the MPL. The code -repository for the Vagrant VMware plugin is available on [GitHub](https://github.com/hashicorp/vagrant-vmware-desktop). - -This provider is a drop-in replacement for VirtualBox. However, there are some -VMware-specific things such as box formats, configurations, etc. that are -documented here. - -Please note that VMware Fusion and VMware Workstation are third-party products -that must be purchased and installed separately prior to using the provider. - -Use the navigation to the left to find a specific VMware topic to read -more about. diff --git a/website/content/docs/providers/vmware/installation.mdx b/website/content/docs/providers/vmware/installation.mdx deleted file mode 100644 index 729e38e3890..00000000000 --- a/website/content/docs/providers/vmware/installation.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: docs -page_title: Installation - VMware Provider -description: |- - The Vagrant VMware provider requires a two step installation - process which includes a system package and a Vagrant plugin. ---- - -# Installation - -If you are upgrading from the Vagrant VMware Workstation or Vagrant -VMware Fusion plugins, please halt or destroy all VMware VMs currently -being managed by Vagrant. Then continue with the instructions below. - -Installation of the Vagrant VMware provider requires two steps. First the -Vagrant VMware Utility must be installed. This can be done by downloading -and installing the correct system package from the [Vagrant VMware Utility -downloads page](/vagrant/downloads/vmware). - -Next, install the Vagrant VMware provider plugin using the standard plugin -installation procedure: - -```shell-session -$ vagrant plugin install vagrant-vmware-desktop -``` - -For more information on plugin installation, please see the -[Vagrant plugin usage documentation](/vagrant/docs/plugins/usage). - -## Upgrading to v1.x - -It is **extremely important** that the VMware plugin is upgraded to 1.0.0 or -above. This release resolved critical security vulnerabilities. To learn more, -please [read our release announcement](https://www.hashicorp.com/blog/introducing-the-vagrant-vmware-desktop-plugin). - -After upgrading, please verify that the following paths are empty. The upgrade -process should remove these for you, but for security reasons it is important -to double check. If you're a new user or installing the VMware provider on a -new machine, you may skip this step. If you're a Windows user, you may skip this -step as well. - -The path `~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}` -should no longer exist. The gem `vagrant-vmware-desktop` may exist since this -is the name of the new plugin. If the old directories exist, remove them. An -example for a Unix-like shell is shown below: - -```shell-session -# Check if they exist and verify that they're the correct paths as shown below. -$ ls ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} -... - -# Remove them -$ rm -rf ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} -``` - -## Updating the Vagrant VMware Desktop plugin - -The Vagrant VMware Desktop plugin can be updated directly from Vagrant. Run the -following command to update Vagrant to the latest version of the Vagrant VMware -Desktop plugin: - -```shell-session -$ vagrant plugin update vagrant-vmware-desktop -``` diff --git a/website/content/docs/providers/vmware/known-issues.mdx b/website/content/docs/providers/vmware/known-issues.mdx deleted file mode 100644 index 444fcddb9e5..00000000000 --- a/website/content/docs/providers/vmware/known-issues.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: docs -page_title: Known Issues - VMware Provider -description: |- - This page tracks some known issues or limitations of the VMware provider. - Note that none of these are generally blockers to using the provider, but - are good to know. ---- - -# Known Issues - -This page tracks some known issues or limitations of the VMware provider. -Note that none of these are generally blockers to using the provider, but -are good to know. - -## Network disconnect - -When Vagrant applies port forwarding rules while bring up a guest instance, -other running VMware VMs may experience a loss of network connectivity. The -cause of this connectivity issue is the restarting of the VMware NAT service -to apply new port forwarding rules. Since new rules cannot be applied to the -NAT service while it is running, it is required to restart the service, which -results in the loss of connectivity. - -## Forwarded Ports Failing in Workstation on Windows - -VMware Workstation has a bug on Windows where forwarded ports do not work -properly. Vagrant actually works around this bug and makes them work. However, -if you run the virtual network editor on Windows, the forwarded ports will -suddenly stop working. - -In this case, run `vagrant reload` and things will begin working again. - -This issue has been reported to VMware, but a fix has not been released yet. - -## Big Sur Related Issues - -### Creating Network Devices - -Starting with the Big Sur release VMware Fusion is no longer able to create -network devices with custom subnet and mask settings to attach to guests. This -means custom IP addresses are not valid when creating a private network. When -creating a private network device to attach to a guest, simply define it with -no options: - -```ruby -Vagrant.configure("2") do |config| - config.vm.box = "hashicorp/bionic64" - config.vm.network :private_network -end -``` - -### Port Forwarding - -VMware Fusion currently does not support port forwarding to the localhost. To -work around this issue, the vagrant-vmware-utility provides functionality to -simulate port forwarding behavior available within VMware Fusion prior to -Big Sur. The port forward management is contained to the vagrant-vmware-utility -and is not accessible via the VMware Fusion networking UI. - -### DHCP Reservations - -Due VMware Fusion no longer utilizing its own service for DHCP, defining DHCP -reservations is currently not working with VMware Fusion on Big Sur. diff --git a/website/content/docs/providers/vmware/usage.mdx b/website/content/docs/providers/vmware/usage.mdx deleted file mode 100644 index 23675b63437..00000000000 --- a/website/content/docs/providers/vmware/usage.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: docs -page_title: Usage - VMware Provider -description: |- - The Vagrant VMware providers are used just like any other provider. Please - read the general basic usage page for providers. ---- - -# Usage - -The Vagrant VMware provider is used just like any other provider. Please -read the general [basic usage](/vagrant/docs/providers/basic_usage) page for -providers. - -The value to use for the `--provider` flag is `vmware_desktop`. For compatibility -with older versions of the plugin, `vmware_fusion` can be used for VMware -Fusion, and `vmware_workstation` for VMware Workstation. - -The Vagrant VMware provider does not support parallel execution at this time. -Specifying the `--parallel` option will have no effect. - -To get started, create a new `Vagrantfile` that points to a VMware box: - -```ruby -# vagrant init hashicorp/bionic64 -Vagrant.configure("2") do |config| - config.vm.box = "hashicorp/bionic64" -end -``` - -Then run: - -```shell-session -$ vagrant up --provider vmware_desktop -``` - -This will download and bring up a new VMware Fusion/Workstation virtual machine -in Vagrant. diff --git a/website/content/docs/provisioning/basic_usage.mdx b/website/content/docs/provisioning/basic_usage.mdx deleted file mode 100644 index 7a75fef2fa9..00000000000 --- a/website/content/docs/provisioning/basic_usage.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -layout: docs -page_title: Basic Usage - Provisioning -description: |- - While Vagrant offers multiple options for how you are able to provision - your machine, there is a standard usage pattern as well as some important - points common to all provisioners that are important to know. ---- - -# Basic Usage of Provisioners - -While Vagrant offers multiple options for how you are able to provision -your machine, there is a standard usage pattern as well as some important -points common to all provisioners that are important to know. - -## Options - -Every Vagrant provisioner accepts a few base options. The only required -option is what type a provisioner is: - -- `name` (string) - The name of the provisioner. Note: if no `type` option is given, - this option _must_ be the type of provisioner it is. If you wish to give it a - different name you must also set the `type` option to define the kind of provisioner. -- `type` (string) - The class of provisioner to configure. (i.e. `"shell"` or `"file"`) -- `before` (string or symbol) - The exact name of an already defined provisioner - that _this_ provisioner should run before. If defined as a symbol, its only valid - values are `:each` or `:all`, which makes the provisioner run before each and - every root provisioner, or before all provisioners respectively. -- `after` (string or symbol) - The exact name of an already defined provisioner - that _this_ provisioner should run after. If defined as a symbol, its only valid - values are `:each` or `:all`, which makes the provisioner run after each and - every root provisioner, or before all provisioners respectively. -- `communicator_required` (boolean) - Specifies the machine must be accessible by - Vagrant in order to run the provisioner. If set to true, the provisioner will - only run if Vagrant can establish communication with the guest. If set to false - the provisioner will run regardless of Vagrant's ability to communicate with the - guest. Defaults to true. - -More information about how to use `before` and `after` options can be read [below](#dependency-provisioners). - -## Configuration - -First, every provisioner is configured within your -[Vagrantfile](/vagrant/docs/vagrantfile/) -using the `config.vm.provision` method call. For example, the Vagrantfile -below enables shell provisioning: - -```ruby -Vagrant.configure("2") do |config| - # ... other configuration - - config.vm.provision "shell", inline: "echo hello" -end -``` - -Every provisioner has a type, such as `"shell"`, used as the first -parameter to the provisioning configuration. Following that is basic key/value -for configuring that specific provisioner. Instead of basic key/value, you -can also use a Ruby block for a syntax that is more like variable assignment. -The following is effectively the same as the prior example: - -```ruby -Vagrant.configure("2") do |config| - # ... other configuration - - config.vm.provision "shell" do |s| - s.inline = "echo hello" - end -end -``` - -The benefit of the block-based syntax is that with more than a couple options -it can greatly improve readability. Additionally, some provisioners, like -the Chef provisioner, have special methods that can be called within that -block to ease configuration that cannot be done with the key/value approach, -or you can use this syntax to pass arguments to a shell script. - -The attributes that can be set in a single-line are the attributes that -are set with the `=` style, such as `inline = "echo hello"` above. If the -style is instead more of a function call, such as `add_recipe "foo"`, then -this cannot be specified in a single line. - -Provisioners can also be named (since 1.7.0). These names are used cosmetically for output -as well as overriding provisioner settings (covered further below). An example -of naming provisioners is shown below: - -```ruby -Vagrant.configure("2") do |config| - # ... other configuration - - config.vm.provision "bootstrap", type: "shell" do |s| - s.inline = "echo hello" - end -end -``` - -Naming provisioners is simple. The first argument to `config.vm.provision` -becomes the name, and then a `type` option is used to specify the provisioner -type, such as `type: "shell"` above. - -## Running Provisioners - -Provisioners are run in three cases: the initial `vagrant up`, `vagrant provision`, and `vagrant reload --provision`. - -A `--no-provision` flag can be passed to `up` and `reload` if you do not -want to run provisioners. Likewise, you can pass `--provision` to force -provisioning. - -The `--provision-with` flag can be used if you only want to run a -specific provisioner if you have multiple provisioners specified. For -example, if you have a shell and Puppet provisioner and only want to -run the shell one, you can do `vagrant provision --provision-with shell`. -The arguments to `--provision-with` can be the provisioner type (such as -"shell") or the provisioner name (such as "bootstrap" from above). - -## Run Once, Always or Never - -By default, provisioners are only run once, during the first `vagrant up` -since the last `vagrant destroy`, unless the `--provision` flag is set, -as noted above. - -Optionally, you can configure provisioners to run on every `up` or -`reload`. They will only be not run if the `--no-provision` flag is -explicitly specified. To do this set the `run` option to "always", -as shown below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "shell", inline: "echo hello", - run: "always" -end -``` - -You can also set `run:` to `"never"` if you have an optional provisioner -that you want to mention to the user in a "post up message" or that -requires some other configuration before it is possible, then call this -with `vagrant provision --provision-with bootstrap`. - -If you are using the block format, you must specify it outside -of the block, as shown below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "bootstrap", type: "shell", run: "never" do |s| - s.inline = "echo hello" - end -end -``` - -## Multiple Provisioners - -Multiple `config.vm.provision` methods can be used to define multiple -provisioners. These provisioners will be run in the order they're defined. -This is useful for a variety of reasons, but most commonly it is used so -that a shell script can bootstrap some of the system so that another provisioner -can take over later. - -If you define provisioners at multiple "scope" levels (such as globally -in the configuration block, then in a -[multi-machine](/vagrant/docs/multi-machine/) definition, then maybe -in a [provider-specific override](/vagrant/docs/providers/configuration)), -then the outer scopes will always run _before_ any inner scopes. For -example, in the Vagrantfile below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "shell", inline: "echo foo" - - config.vm.define "web" do |web| - web.vm.provision "shell", inline: "echo bar" - end - - config.vm.provision "shell", inline: "echo baz" -end -``` - -The ordering of the provisioners will be to echo "foo", "baz", then -"bar" (note the second one might not be what you expect!). Remember: -ordering is _outside in_. - -With multiple provisioners, use the `--provision-with` setting along -with names to get more fine grained control over what is run and when. - -## Overriding Provisioner Settings - -~> **Warning: Advanced Topic!** Provisioner overriding is -an advanced topic that really only becomes useful if you are already -using multi-machine and/or provider overrides. If you are just getting -started with Vagrant, you can safely skip this. - -When using features such as [multi-machine](/vagrant/docs/multi-machine/) -or [provider-specific overrides](/vagrant/docs/providers/configuration), -you may want to define common provisioners in the global configuration -scope of a Vagrantfile, but override certain aspects of them internally. -Vagrant allows you to do this, but has some details to consider. - -To override settings, you must assign a name to your provisioner. - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "foo", type: "shell", - inline: "echo foo" - - config.vm.define "web" do |web| - web.vm.provision "foo", type: "shell", - inline: "echo bar" - end -end -``` - -In the above, only "bar" will be echoed, because the inline setting -overloaded the outer provisioner. This overload is only effective -within that scope: the "web" VM. If there were another VM defined, -it would still echo "foo" unless it itself also overloaded the -provisioner. - -**Be careful with ordering.** When overriding a provisioner in -a sub-scope, the provisioner will run at _that point_. In the example -below, the output would be "foo" then "bar": - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "foo", type: "shell", - inline: "echo ORIGINAL!" - - config.vm.define "web" do |web| - web.vm.provision "shell", - inline: "echo foo" - web.vm.provision "foo", type: "shell", - inline: "echo bar" - end -end -``` - -If you want to preserve the original ordering, you can specify -the `preserve_order: true` flag: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "do-this", - type: "shell", - preserve_order: true, - inline: "echo FIRST!" - config.vm.provision "then-this", - type: "shell", - preserve_order: true, - inline: "echo SECOND!" -end -``` - -## Dependency Provisioners - -~> **Warning: Advanced Topic!** Dependency provisioners are -an advanced topic. If you are just getting started with Vagrant, you can -safely skip this. - -If a provisioner has been configured using the `before` or `after` options, it -is considered a _Dependency Provisioner_. This means it has been configured to -run before or after a _Root Provisioner_, which does not have the `before` or -`after` options configured. - -Dependency provisioners also have two valid shortcuts: -`:each` and `:all`. - -**Note**: As of 2.2.6, dependency provisioners cannot rely on other dependency -provisioners and is considered a configuration state error in Vagrant. If you must -order dependency provisioners, you can still order them by the order they are defined -inside your Vagrantfile. - -An example of these dependency provisioners can be seen below: - -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "C", after: "B", type: "shell", inline:<<-SHELL - echo 'C' - SHELL - config.vm.provision "B", type: "shell", inline:<<-SHELL - echo 'B' - SHELL - config.vm.provision "D", type: "shell", inline:<<-SHELL - echo 'D' - SHELL - config.vm.provision "A", before: "B", type: "shell", inline:<<-SHELL - echo 'A' - SHELL - config.vm.provision "Separate After", after: :each, type: "shell", inline:<<-SHELL - echo '==============================' - SHELL - config.vm.provision "Separate Before", before: :each, type: "shell", inline:<<-SHELL - echo '++++++++++++++++++++++++++++++' - SHELL - config.vm.provision "Hello", before: :all, type: "shell", inline:<<-SHELL - echo 'HERE WE GO!!' - SHELL - config.vm.provision "Goodbye", after: :all, type: "shell", inline:<<-SHELL - echo 'The end' - SHELL -end -``` - -The result of running `vagrant provision` with a guest configured above: - -``` -==> default: Running provisioner: Hello (shell)... - default: Running: inline script - default: HERE WE GO!! -==> default: Running provisioner: Separate Before (shell)... - default: Running: inline script - default: ++++++++++++++++++++++++++++++ -==> default: Running provisioner: A (shell)... - default: Running: inline script - default: A -==> default: Running provisioner: Separate After (shell)... - default: Running: inline script - default: ============================== -==> default: Running provisioner: Separate Before (shell)... - default: Running: inline script - default: ++++++++++++++++++++++++++++++ -==> default: Running provisioner: B (shell)... - default: Running: inline script - default: B -==> default: Running provisioner: Separate After (shell)... - default: Running: inline script - default: ============================== -==> default: Running provisioner: Separate Before (shell)... - default: Running: inline script - default: ++++++++++++++++++++++++++++++ -==> default: Running provisioner: C (shell)... - default: Running: inline script - default: C -==> default: Running provisioner: Separate After (shell)... - default: Running: inline script - default: ============================== -==> default: Running provisioner: Separate Before (shell)... - default: Running: inline script - default: ++++++++++++++++++++++++++++++ -==> default: Running provisioner: D (shell)... - default: Running: inline script - default: D -==> default: Running provisioner: Separate After (shell)... - default: Running: inline script - default: ============================== -==> default: Running provisioner: Goodbye (shell)... - default: Running: inline script - default: The end -``` diff --git a/website/content/docs/provisioning/index.mdx b/website/content/docs/provisioning/index.mdx deleted file mode 100644 index abe89201fd0..00000000000 --- a/website/content/docs/provisioning/index.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: docs -page_title: Provisioning -description: >- - Provisioners in Vagrant allow you to automatically install software, alter - configurations, and more on the machine as part of the `vagrant up` process. ---- - -# Provisioning - -Provisioners in Vagrant allow you to automatically install software, alter configurations, -and more on the machine as part of the `vagrant up` process. - -This is useful since [boxes](/vagrant/docs/boxes) typically are not -built _perfectly_ for your use case. Of course, if you want to just use -`vagrant ssh` and install the software by hand, that works. But by using -the provisioning systems built-in to Vagrant, it automates the process so -that it is repeatable. Most importantly, it requires no human interaction, -so you can `vagrant destroy` and `vagrant up` and have a fully ready-to-go -work environment with a single command. Powerful. - -Vagrant gives you multiple options for provisioning the machine, from -simple shell scripts to more complex, industry-standard configuration -management systems. - -If you've never used a configuration management system before, it is -recommended you start with basic [shell scripts](/vagrant/docs/provisioning/shell) -for provisioning. - -You can find the full list of built-in provisioners and usage of these -provisioners in the navigational area to the left. - -## When Provisioning Happens - -Provisioning happens at certain points during the lifetime of your -Vagrant environment: - -- On the first `vagrant up` that creates the environment, provisioning is run. - If the environment was already created and the up is just resuming a machine - or booting it up, they will not run unless the `--provision` flag is explicitly - provided. - -- When `vagrant provision` is used on a running environment. - -- When `vagrant reload --provision` is called. The `--provision` flag must - be present to force provisioning. - -You can also bring up your environment and explicitly _not_ run provisioners -by specifying `--no-provision`. diff --git a/website/content/docs/start/debug.mdx b/website/content/docs/start/debug.mdx new file mode 100644 index 00000000000..49f7cd02020 --- /dev/null +++ b/website/content/docs/start/debug.mdx @@ -0,0 +1,60 @@ +--- +layout: docs +page_title: Debug and troubleshoot +description: |- + As much as we try to keep Vagrant stable and bug free, it is inevitable + that issues will arise and Vagrant will behave in unexpected ways. In + these cases, Vagrant has amazing support channels available to assist you. +--- + +# Debug and troubleshoot + +As much as we try to keep Vagrant stable and bug free, it is inevitable that issues will arise and Vagrant will behave in unexpected ways. + +When using these support channels, it is generally helpful to include debugging logs along with any error reports. These logs can often help you troubleshoot any problems you may be having. + +!> **Scan for sensitive information!** Vagrant debug logs include information about your system including environment variables and user information. If you store sensitive information in the environment or in your user account, please scan or scrub the debug log of this information before uploading the contents to the public Internet. + +~> **Submit debug logs using GitHub Gist.** If you plan on submitting a bug report or issue that includes debug-level logs, please use a service like [Gist](https://gist.github.com). **Do not** paste the raw debug logs into an issue as it makes it very difficult to scroll and parse the information. + +## Enable debug logging + +To enable detailed logging, set the `VAGRANT_LOG` environmental variable to the desired log level name, which is one of `debug` (loud), `info` (normal), `warn` (quiet), and `error` (very quiet). When asking for support, please set this to `debug`. When troubleshooting your own issues, you should start with `info`, which is much quieter, but contains important information about the behavior of Vagrant. + +On Linux and Mac systems, you can prepend the `vagrant` command with an environmental variable declaration. + +```shell-session +$ VAGRANT_LOG=info vagrant up +``` + +On Windows, you need to set the `VAGRANT_LOG` environmental variable. + +```shell-session +$ set VAGRANT_LOG=info +``` + +Then, start your environment. + +```shell-session +$ vagrant up +``` + +You can also get the debug level output using the `--debug` command line option. + +```shell-session +$ vagrant up --debug +``` + +## Save debug logs + +On Linux and Mac, use `&>` to redirect stderr and stdout to a file. + +```shell-session +$ vagrant up --debug &> vagrant.log +``` + +On Windows in PowerShell, use `2>&1 | Tee-Object -FilePath ".\vagrant.log"` to print the log and redirect stderr and stdout to the log file. + +```shell-session +$ vagrant up --debug 2>&1 | Tee-Object -FilePath ".\vagrant.log" +``` diff --git a/website/content/docs/providers/basic_usage.mdx b/website/content/docs/start/index.mdx similarity index 90% rename from website/content/docs/providers/basic_usage.mdx rename to website/content/docs/start/index.mdx index 7d659c89256..d54a1e9f44a 100644 --- a/website/content/docs/providers/basic_usage.mdx +++ b/website/content/docs/start/index.mdx @@ -1,17 +1,13 @@ --- layout: docs -page_title: Basic Usage - Providers +page_title: Start environment description: |- - Vagrant boxes are all provider-specific. A box for VirtualBox is incompatible - with the VMware Fusion provider, or any other provider. A box must be - installed for each provider, and can share the same name as other boxes as - long as the providers differ. So you can have both a VirtualBox and VMware - Fusion "bionic64" box. + Placeholder for start environment. --- -# Basic Provider Usage +# Start environment -## Boxes +TODO: Add introduction Vagrant boxes are all provider-specific. A box for VirtualBox is incompatible with the VMware Fusion provider, or any other provider. A box must be installed diff --git a/website/content/docs/synced-folders/basic_usage.mdx b/website/content/docs/synced-folders/basic_usage.mdx deleted file mode 100644 index 27e555cb7b9..00000000000 --- a/website/content/docs/synced-folders/basic_usage.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -layout: docs -page_title: Basic Usage - Synced Folders -description: |- - Synced folders are configured within your Vagrantfile using the - "config.vm.synced_folder" method. ---- - -# Basic Usage - -## Configuration - -Synced folders are configured within your Vagrantfile using the -`config.vm.synced_folder` method. Usage of the configuration directive -is very simple: - -```ruby -Vagrant.configure("2") do |config| - # other config here - - config.vm.synced_folder "src/", "/srv/website" -end -``` - -The first parameter is a path to a directory on the host machine. If -the path is relative, it is relative to the project root. The second -parameter must be an absolute path of where to share the folder within -the guest machine. This folder will be created (recursively, if it must) -if it does not exist. By default, Vagrant mounts the synced folders with -the owner/group set to the SSH user and any parent folders set to root. - -## Options - -You may also specify additional optional parameters when configuring -synced folders. These options are listed below. More detailed examples of using -some of these options are shown below this section, note the owner/group example -supplies two additional options separated by commas. - -In addition to these options, the specific synced folder type might -allow more options. See the documentation for your specific synced folder -type for more details. The built-in synced folder types are documented -in other pages available in the navigation for these docs. - -- `create` (boolean) - If true, the host path will be created if it - does not exist. Defaults to false. - -- `disabled` (boolean) - If true, this synced folder will be disabled and - will not be setup. This can be used to disable a previously defined synced - folder or to conditionally disable a definition based on some external - factor. - -- `group` (string) - The group that will own the synced folder. By default - this will be the SSH user. Some synced folder types do not support - modifying the group. - -- `mount_options` (array) - A list of additional mount options to pass - to the `mount` command. - -- `owner` (string) - The user who should be the owner of this synced folder. - By default this will be the SSH user. Some synced folder types do not - support modifying the owner. - -- `type` (string) - The type of synced folder. If this is not specified, - Vagrant will automatically choose the best synced folder option for your - environment. Otherwise, you can specify a specific type such as "nfs". - -- `id` (string) - The name for the mount point of this synced folder in the - guest machine. This shows up when you run `mount` in the guest machine. - -## Enabling - -Synced folders are automatically setup during `vagrant up` and -`vagrant reload`. - -## Disabling - -Synced folders can be disabled by adding the `disabled` option to -any definition: - -```ruby -Vagrant.configure("2") do |config| - config.vm.synced_folder "src/", "/srv/website", disabled: true -end -``` - -Disabling the default `/vagrant` share can be done as follows: - -```ruby -config.vm.synced_folder ".", "/vagrant", disabled: true -``` - -## Modifying the Owner/Group - -Sometimes it is preferable to mount folders with a different owner/group than -the default SSH user. Keep in mind that these options will only affect the -synced folder itself. If you want to modify the owner/group of the synced -folder's parent folders use a script. It is possible to set these options: - -```ruby -config.vm.synced_folder "src/", "/srv/website", - owner: "root", group: "root" -``` - -_NOTE: Owner and group IDs defined within `mount_options` will have precedence -over the `owner` and `group` options._ - -For example, given the following configuration: - -```ruby -config.vm.synced_folder ".", "/vagrant", owner: "vagrant", - group: "vagrant", mount_options: ["uid=1234", "gid=1234"] -``` - -the mounted synced folder will be owned by the user with ID `1234` and the -group with ID `1234`. The `owner` and `group` options will be ignored. - -## Symbolic Links - -Support for symbolic links across synced folder implementations and -host/guest combinations is not consistent. Vagrant does its best to -make sure symbolic links work by configuring various hypervisors (such -as VirtualBox), but some host/guest combinations still do not work -properly. This can affect some development environments that rely on -symbolic links. - -The recommendation is to make sure to test symbolic links on all the -host/guest combinations you sync folders on if this is important to you. diff --git a/website/content/docs/synced-folders/index.mdx b/website/content/docs/synced-folders/index.mdx deleted file mode 100644 index 6546ef08430..00000000000 --- a/website/content/docs/synced-folders/index.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: docs -page_title: Synced Folders -description: |- - Synced folders enable Vagrant to sync a folder on the host machine to the - guest machine, allowing you to continue working on your project's files - on your host machine, but use the resources in the guest machine to - compile or run your project. ---- - -# Synced Folders - -Synced folders enable Vagrant to sync a folder on the host machine to the -guest machine, allowing you to continue working on your project's files -on your host machine, but use the resources in the guest machine to -compile or run your project. - -By default, Vagrant will share your project directory (the directory -with the [Vagrantfile](/vagrant/docs/vagrantfile/)) to `/vagrant`. - -Read the [basic usage](/vagrant/docs/synced-folders/basic_usage) page to get started -with synced folders. diff --git a/website/content/docs/triggers/index.mdx b/website/content/docs/triggers/index.mdx deleted file mode 100644 index b7764a0d744..00000000000 --- a/website/content/docs/triggers/index.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: docs -page_title: Vagrant Triggers -description: Introduction to Vagrant Triggers ---- - -# Vagrant Triggers - -As of version 2.1.0, Vagrant is capable of executing machine triggers _before_ or -_after_ Vagrant commands. - -Each trigger is expected to be given a command key for when it should be fired -during the Vagrant command lifecycle. These could be defined as a single key or -an array which acts like a _whitelist_ for the defined trigger. - -```ruby -# single command trigger -config.trigger.after :up do |trigger| -... -end - -# multiple commands for this trigger -config.trigger.before [:up, :destroy, :halt, :package] do |trigger| -... -end - -# or defined as a splat list -config.trigger.before :up, :destroy, :halt, :package do |trigger| -... -end -``` - -Alternatively, the key `:all` could be given which would run the trigger before -or after every Vagrant command. If there is a command you don't want the trigger -to run on, you can ignore that command with the `ignore` option. - -```ruby -# single command trigger -config.trigger.before :all do |trigger| - trigger.info = "Running a before trigger!" - trigger.ignore = [:destroy, :halt] -end -``` - -**Note:** _If a trigger is defined on a command that does not exist, a warning -will be displayed._ - -Triggers can be defined as a block or hash in a Vagrantfile. The example below -will result in the same trigger: - -```ruby -config.trigger.after :up do |trigger| - trigger.name = "Finished Message" - trigger.info = "Machine is up!" -end - -config.trigger.after :up, - name: "Finished Message", - info: "Machine is up!" -``` - -Triggers can also be defined within the scope of guests in a Vagrantfile. These -triggers will only run on the configured guest. An example of a guest only trigger: - -```ruby -config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - ubuntu.trigger.before :destroy do |trigger| - trigger.warn = "Dumping database to /vagrant/outfile" - trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} - end -end -``` - -Global and machine-scoped triggers will execute in the order that they are -defined within a Vagrantfile. Take for example an abstracted Vagrantfile: - -``` -Vagrantfile - global trigger 1 - global trigger 2 - machine defined - machine trigger 3 - global trigger 4 -end -``` - -In this generic case, the triggers would fire in the order: 1 -> 2 -> 3 -> 4 - -For more information about what options are available for triggers, see the -[configuration section](/vagrant/docs/triggers/configuration). diff --git a/website/content/docs/triggers/usage.mdx b/website/content/docs/triggers/usage.mdx deleted file mode 100644 index 03b1d6220b3..00000000000 --- a/website/content/docs/triggers/usage.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -layout: docs -page_title: Vagrant Triggers Usage -description: Various Vagrant Triggers examples ---- - -# Basic Usage - -Below are some very simple examples of how to use Vagrant Triggers. - -## Examples - -The following is a basic example of two global triggers. One that runs _before_ -the `:up` command and one that runs _after_ the `:up` command: - -```ruby -Vagrant.configure("2") do |config| - config.trigger.before :up do |trigger| - trigger.name = "Hello world" - trigger.info = "I am running before vagrant up!!" - end - - config.trigger.after :up do |trigger| - trigger.name = "Hello world" - trigger.info = "I am running after vagrant up!!" - end - - config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - end -end -``` - -These will run before and after each defined guest in the Vagrantfile. - -Running a remote script to save a database on your host before **destroy**ing a -guest: - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - - ubuntu.trigger.before :destroy do |trigger| - trigger.warn = "Dumping database to /vagrant/outfile" - trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} - end - end -end -``` - -Now that the trigger is defined, running the **destroy** command will fire off -the defined trigger before Vagrant destroys the machine. - -```shell-session -$ vagrant destroy ubuntu -``` - -An example of defining three triggers that start and stop tinyproxy on your host -machine using homebrew: - -```shell -#/bin/bash -# start-tinyproxy.sh -brew services start tinyproxy -``` - -```shell -#/bin/bash -# stop-tinyproxy.sh -brew services stop tinyproxy -``` - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - - ubuntu.trigger.before :up do |trigger| - trigger.info = "Starting tinyproxy..." - trigger.run = {path: "start-tinyproxy.sh"} - end - - ubuntu.trigger.after :destroy, :halt do |trigger| - trigger.info = "Stopping tinyproxy..." - trigger.run = {path: "stop-tinyproxy.sh"} - end - end -end -``` - -Running `vagrant up` would fire the before trigger to start tinyproxy, where as -running either `vagrant destroy` or `vagrant halt` would stop tinyproxy. - -### Ruby Option - -Triggers can also be defined to run Ruby, rather than bash or PowerShell. An -example of this might be using a Ruby option to get more information from the `VBoxManage` -tool. In this case, we are printing the `ostype` defined for thte guest after -it has been brought up. - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - - ubuntu.trigger.after :up do |trigger| - trigger.info = "More information with ruby magic" - trigger.ruby do |env,machine| - puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype` - end - end - end -end -``` - -If you are defining your triggers using the hash syntax, you must use the `Proc` -type for defining a ruby trigger. - -```ruby -Vagrant.configure("2") do |config| - config.vm.define "ubuntu" do |ubuntu| - ubuntu.vm.box = "ubuntu" - - ubuntu.trigger.after :up, - info: "More information with ruby magic", - ruby: proc{|env,machine| puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype`} - end -end -``` - -### Typed Triggers - -Below are some basic examples of using `:type` triggers. They cover commands, hooks, -and actions. - -It is important to note that while `command` triggers will be a fairly common use case, -both `action` and `hook` triggers are more complicated and are a more advanced use case. - -#### Commands - -The most common use case for typed triggers are with `command`. These kinds of -triggers allow you to run something before or after a subcommand in Vagrant. - -```ruby -config.trigger.after :status, type: :command do |t| - t.info = "Showing status of all VMs!" -end -``` - -Because they are specifically for subcommands, they do not work with any guest -operations like `run_remote` or if you define the trigger as a guest trigger. - -#### Hooks - -Below is an example of a Vagrant trigger that runs before and after each defined -provisioner: - -```ruby -config.trigger.before :provisioner_run, type: :hook do |t| - t.info = "Before the provision!" -end - -config.vm.provision "file", source: "scripts/script.sh", destination: "/test/script.sh" - -config.vm.provision "shell", inline: <<-SHELL -echo "Provision the guest!" -SHELL - -``` - -Notice how this trigger runs before _each_ provisioner defined for the guest: - -```shell -==> guest: Running provisioner: Sandbox (file)... -==> vagrant: Running hook triggers before provisioner_run ... -==> vagrant: Running trigger... -==> vagrant: Before the provision! - guest: /home/hashicorp/vagrant-sandbox/scripts/script.sh => /home/vagrant/test/script.sh -==> guest: Running provisioner: shell... -==> vagrant: Running hook triggers before provisioner_run ... -==> vagrant: Running trigger... -==> vagrant: Before the provision! - guest: Running: inline script - guest: Provision the guest! -``` - -#### Actions - -With action typed triggers, you can fire off triggers before or after certain -Action classes. A simple example of this might be warning the user when Vagrant -invokes the `GracefulHalt` action. - -```ruby -config.trigger.before :"Vagrant::Action::Builtin::GracefulHalt", type: :action do |t| - t.warn = "Vagrant is halting your guest..." -end -``` diff --git a/website/content/docs/upgrade/backwards-compatibility.mdx b/website/content/docs/upgrade/backwards-compatibility.mdx new file mode 100644 index 00000000000..4e4f71119e4 --- /dev/null +++ b/website/content/docs/upgrade/backwards-compatibility.mdx @@ -0,0 +1,23 @@ +--- +layout: docs +page_title: Backwards Compatibility +description: Vagrant makes a very strict backwards-compatibility promise. +--- + +# Backwards Compatibility + +## For 1.0.x + +Vagrant 1.1+ provides full backwards compatibility for valid Vagrant 1.0.x Vagrantfiles which do not use plugins. After installing Vagrant 1.1, your 1.0.x environments should continue working without modifications, and existing running machines will continue to be managed properly. + +This compatibility layer will remain in Vagrant up to and including Vagrant 2.0. It may still exist after that, but Vagrant's compatibility promise is only for two versions. Seeing that major Vagrant releases take years to develop and release, it is safe to stick with your version 1.0.x Vagrantfile for the time being. + +If you use any Vagrant 1.0.x plugins, you must remove references to these from your Vagrantfile prior to upgrading. Vagrant 1.1+ introduces a new plugin format that will protect against this sort of incompatibility from ever happening again. + +## For 1.x + +Backwards compatibility between 1.x is not promised, and Vagrantfile syntax stability is not promised until 2.0 final. Any backwards incompatibilities within 1.x will be clearly documented. + +This is similar to how Vagrant 0.x was handled. In practice, Vagrant 0.x only introduced a handful of backwards incompatibilities during the entire development cycle, but the possibility of backwards incompatibilities is made clear so people are not surprised. + +Vagrant 2.0 final will have a stable Vagrantfile format that will remain backwards compatible, just as 1.0 is considered stable. diff --git a/website/content/docs/installation/index.mdx b/website/content/docs/upgrade/index.mdx similarity index 68% rename from website/content/docs/installation/index.mdx rename to website/content/docs/upgrade/index.mdx index 31d6f196a33..dbf05151a4c 100644 --- a/website/content/docs/installation/index.mdx +++ b/website/content/docs/upgrade/index.mdx @@ -8,32 +8,25 @@ description: |- # Install Vagrant -To get started with Vagrant, download the appropriate installer or -package for your platform from our -[Vagrant downloads page](/vagrant/downloads). Install the package with the standard procedures for -your operating system. +To get started with Vagrant, download the appropriate installer or package for your platform from our [Vagrant downloads page](/vagrant/downloads). Install the package with the standard procedures for your operating system. -The installer automatically adds `vagrant` to your system path -so that it is available in terminals. If it is not found, -log out and back into your system; this is a common issue for Windows. +The installer automatically adds `vagrant` to your system path so that it is available in terminals. If it is not found, log out and back into your system; this is a common issue for Windows. -~> **Rubygem installation is unsupported** Vagrant 1.0.x has the option to -be installed as a [RubyGem](https://en.wikipedia.org/wiki/RubyGems). -However, this installation method is no longer supported. If you have an old version -of Vagrant installed via Rubygems, remove it prior to installing newer -versions of Vagrant. + + +Vagrant 1.0.x has the option to be installed as a [RubyGem](https://en.wikipedia.org/wiki/RubyGems). However, this installation method is no longer supported. If you have an old version of Vagrant installed via Rubygems, remove it prior to installing newer versions of Vagrant. + + ## First development environment -If you are new to Vagrant, the next step to set up a development environment is to install -a [box](/vagrant/tutorials/getting-started/getting-started-boxes). +If you are new to Vagrant, the next step to set up a development environment is to install a [box](/vagrant/tutorials/getting-started/getting-started-boxes). ## How to use multiple hypervisors Hypervisors often do not allow you to bring up virtual machines if you have more than one hypervisor in use. -Below are a couple of examples to allow you -to use Vagrant and VirtualBox if another hypervisor is present. +Below are a couple of examples to allow you to use Vagrant and VirtualBox if another hypervisor is present. ### Linux, VirtualBox, and KVM @@ -71,11 +64,9 @@ Restart your machine and try the `vagrant` command again. ### Windows, VirtualBox, and Hyper-V -If you encounter an issue with Windows, you will get a blue screen if you attempt to bring up -a VirtualBox VM with Hyper-V enabled. +If you encounter an issue with Windows, you will get a blue screen if you attempt to bring up a VirtualBox VM with Hyper-V enabled. -If you wish to use VirtualBox on Windows, you must ensure that Hyper-V is not enabled -on Windows. You can turn off the feature with the following Powershell command for Windows 10. +If you wish to use VirtualBox on Windows, you must ensure that Hyper-V is not enabled on Windows. You can turn off the feature with the following Powershell command for Windows 10. ```powershell Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All @@ -89,7 +80,7 @@ bcdedit /set hypervisorlaunchtype off You can also disable Hyper-V in the Windows system settings. -- Right click on the Windows button and select ‘Apps and Features’. +- Right click on the Windows button and select 'Apps and Features'. - Select Turn Windows Features on or off. - Unselect Hyper-V and click OK. diff --git a/website/content/docs/providers/vmware/vagrant-vmware-utility.mdx b/website/content/docs/vagrant-vmware-utility.mdx similarity index 100% rename from website/content/docs/providers/vmware/vagrant-vmware-utility.mdx rename to website/content/docs/vagrant-vmware-utility.mdx diff --git a/website/content/docs/vagrantfile/ssh_settings.mdx b/website/content/docs/vagrantfile/ssh.mdx similarity index 100% rename from website/content/docs/vagrantfile/ssh_settings.mdx rename to website/content/docs/vagrantfile/ssh.mdx diff --git a/website/content/docs/triggers/configuration.mdx b/website/content/docs/vagrantfile/trigger.mdx similarity index 100% rename from website/content/docs/triggers/configuration.mdx rename to website/content/docs/vagrantfile/trigger.mdx diff --git a/website/content/docs/vagrantfile/vagrant_version.mdx b/website/content/docs/vagrantfile/vagrant-version.mdx similarity index 100% rename from website/content/docs/vagrantfile/vagrant_version.mdx rename to website/content/docs/vagrantfile/vagrant-version.mdx diff --git a/website/content/docs/vagrantfile/vagrant_settings.mdx b/website/content/docs/vagrantfile/vagrant.mdx similarity index 100% rename from website/content/docs/vagrantfile/vagrant_settings.mdx rename to website/content/docs/vagrantfile/vagrant.mdx diff --git a/website/content/docs/cloud-init/configuration.mdx b/website/content/docs/vagrantfile/vm/cloud-init.mdx similarity index 98% rename from website/content/docs/cloud-init/configuration.mdx rename to website/content/docs/vagrantfile/vm/cloud-init.mdx index b223180e8ba..c7d05c35ad4 100644 --- a/website/content/docs/cloud-init/configuration.mdx +++ b/website/content/docs/vagrantfile/vm/cloud-init.mdx @@ -4,7 +4,7 @@ page_title: Vagrant Cloud-Init Configuration description: Documentation of various configuration options for Vagrant cloud-init --- -# Configuration +# Vagrant cloud-init configuration Vagrant cloud-init has several options that allow users to define a config to be used with cloud-init. diff --git a/website/content/docs/disks/configuration.mdx b/website/content/docs/vagrantfile/vm/disk.mdx similarity index 87% rename from website/content/docs/disks/configuration.mdx rename to website/content/docs/vagrantfile/vm/disk.mdx index c15adaf99a8..ff6473100ba 100644 --- a/website/content/docs/disks/configuration.mdx +++ b/website/content/docs/vagrantfile/vm/disk.mdx @@ -4,7 +4,7 @@ page_title: Vagrant Disks Configuration description: Documentation of various configuration options for Vagrant Disks --- -# Configuration +# Vagrant disk configuration Vagrant Disks has several options that allow users to define and attach disks to guests. @@ -41,21 +41,28 @@ Vagrant Disks has several options that allow users to define and attach disks to - `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 + + + 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 + + +## Disk types The disk config currently accepts three kinds of disk types: -- `disk` (symbol) -- `dvd` (symbol) -- `floppy` (symbol) +1. `disk` (symbol) +2. `dvd` (symbol) +3. `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. +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: @@ -65,13 +72,15 @@ config.vm.disk :dvd, name: "installer", file: "./installer.iso" config.vm.disk :floppy, name: "cool_files" ``` -## Provider Author Guide +## 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. + + -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. +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. -~> **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: diff --git a/website/content/docs/vagrantfile/machine_settings.mdx b/website/content/docs/vagrantfile/vm/index.mdx similarity index 98% rename from website/content/docs/vagrantfile/machine_settings.mdx rename to website/content/docs/vagrantfile/vm/index.mdx index 3931d082603..c3fd998a3c1 100644 --- a/website/content/docs/vagrantfile/machine_settings.mdx +++ b/website/content/docs/vagrantfile/vm/index.mdx @@ -6,12 +6,11 @@ description: |- machine that Vagrant manages. --- -# Machine Settings +# Virtual machine configuration **Config namespace: `config.vm`** -The settings within `config.vm` modify the configuration of the -machine that Vagrant manages. +The settings within `config.vm` modify the configuration of the machine that Vagrant manages. ## Available Settings diff --git a/website/content/docs/providers/docker/configuration.mdx b/website/content/docs/vagrantfile/vm/provider/docker.mdx similarity index 100% rename from website/content/docs/providers/docker/configuration.mdx rename to website/content/docs/vagrantfile/vm/provider/docker.mdx diff --git a/website/content/docs/providers/hyperv/configuration.mdx b/website/content/docs/vagrantfile/vm/provider/hyperv.mdx similarity index 100% rename from website/content/docs/providers/hyperv/configuration.mdx rename to website/content/docs/vagrantfile/vm/provider/hyperv.mdx diff --git a/website/content/docs/providers/configuration.mdx b/website/content/docs/vagrantfile/vm/provider/index.mdx similarity index 100% rename from website/content/docs/providers/configuration.mdx rename to website/content/docs/vagrantfile/vm/provider/index.mdx diff --git a/website/content/docs/providers/virtualbox/configuration.mdx b/website/content/docs/vagrantfile/vm/provider/virtualbox.mdx similarity index 100% rename from website/content/docs/providers/virtualbox/configuration.mdx rename to website/content/docs/vagrantfile/vm/provider/virtualbox.mdx diff --git a/website/content/docs/providers/vmware/configuration.mdx b/website/content/docs/vagrantfile/vm/provider/vmware.mdx similarity index 99% rename from website/content/docs/providers/vmware/configuration.mdx rename to website/content/docs/vagrantfile/vm/provider/vmware.mdx index a97d67a3c7e..f93e7f34114 100644 --- a/website/content/docs/providers/vmware/configuration.mdx +++ b/website/content/docs/vagrantfile/vm/provider/vmware.mdx @@ -7,7 +7,7 @@ description: |- configure VMware-specific aspects of your machines. --- -# Configuration +# config.vm.provider.vmware_desktop While Vagrant VMware Desktop provider is a drop-in replacement for VirtualBox, there are some additional features that are exposed that allow you to more finely diff --git a/website/content/docs/vagrantfile/vm/provision.mdx b/website/content/docs/vagrantfile/vm/provision.mdx new file mode 100644 index 00000000000..a026856eaba --- /dev/null +++ b/website/content/docs/vagrantfile/vm/provision.mdx @@ -0,0 +1,100 @@ +--- +layout: docs +page_title: Basic Usage - Provisioning +description: |- + While Vagrant offers multiple options for how you are able to provision + your machine, there is a standard usage pattern as well as some important + points common to all provisioners that are important to know. +--- + +# Configure provisioners + +While Vagrant offers multiple options for how you are able to provision +your machine, there is a standard usage pattern as well as some important +points common to all provisioners that are important to know. + + +## Configuration + +First, every provisioner is configured within your +[Vagrantfile](/vagrant/docs/vagrantfile/) +using the `config.vm.provision` method call. For example, the Vagrantfile +below enables shell provisioning: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell", inline: "echo hello" +end +``` + +Every provisioner has a type, such as `"shell"`, used as the first +parameter to the provisioning configuration. Following that is basic key/value +for configuring that specific provisioner. Instead of basic key/value, you +can also use a Ruby block for a syntax that is more like variable assignment. +The following is effectively the same as the prior example: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell" do |s| + s.inline = "echo hello" + end +end +``` + +The benefit of the block-based syntax is that with more than a couple options +it can greatly improve readability. Additionally, some provisioners, like +the Chef provisioner, have special methods that can be called within that +block to ease configuration that cannot be done with the key/value approach, +or you can use this syntax to pass arguments to a shell script. + +The attributes that can be set in a single-line are the attributes that +are set with the `=` style, such as `inline = "echo hello"` above. If the +style is instead more of a function call, such as `add_recipe "foo"`, then +this cannot be specified in a single line. + +Provisioners can also be named (since 1.7.0). These names are used cosmetically for output +as well as overriding provisioner settings (covered further below). An example +of naming provisioners is shown below: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "bootstrap", type: "shell" do |s| + s.inline = "echo hello" + end +end +``` + +Naming provisioners is simple. The first argument to `config.vm.provision` +becomes the name, and then a `type` option is used to specify the provisioner +type, such as `type: "shell"` above. + +## Options + +Every Vagrant provisioner accepts a few base options. The only required +option is what type a provisioner is: + +- `name` (string) - The name of the provisioner. Note: if no `type` option is given, + this option _must_ be the type of provisioner it is. If you wish to give it a + different name you must also set the `type` option to define the kind of provisioner. +- `type` (string) - The class of provisioner to configure. (i.e. `"shell"` or `"file"`) +- `before` (string or symbol) - The exact name of an already defined provisioner + that _this_ provisioner should run before. If defined as a symbol, its only valid + values are `:each` or `:all`, which makes the provisioner run before each and + every root provisioner, or before all provisioners respectively. +- `after` (string or symbol) - The exact name of an already defined provisioner + that _this_ provisioner should run after. If defined as a symbol, its only valid + values are `:each` or `:all`, which makes the provisioner run after each and + every root provisioner, or before all provisioners respectively. +- `communicator_required` (boolean) - Specifies the machine must be accessible by + Vagrant in order to run the provisioner. If set to true, the provisioner will + only run if Vagrant can establish communication with the guest. If set to false + the provisioner will run regardless of Vagrant's ability to communicate with the + guest. Defaults to true. + +More information about how to use `before` and `after` options can be read [below](#dependency-provisioners). \ No newline at end of file diff --git a/website/content/docs/vagrantfile/vm/synced-folder.mdx b/website/content/docs/vagrantfile/vm/synced-folder.mdx new file mode 100644 index 00000000000..270a1a048cd --- /dev/null +++ b/website/content/docs/vagrantfile/vm/synced-folder.mdx @@ -0,0 +1,42 @@ +--- +layout: docs +page_title: Synced folder configuration +description: |- + Synced folders are configured within your Vagrantfile using the + "config.vm.synced_folder" method. +--- + +# Synced folder configuration + +Synced folders are configured within your Vagrantfile using the `config.vm.synced_folder` method. The following example shows a simple synced folder configuration. + +```ruby +Vagrant.configure("2") do |config| + # other config here + + config.vm.synced_folder "src/", "/srv/website" +end +``` + +The first parameter is a path to a directory on the host machine. If the path is relative, it is relative to the project root. The second parameter must be an absolute path of where to share the folder within the guest machine. This folder will be created (recursively, if it must) if it does not exist. By default, Vagrant mounts the synced folders with the owner/group set to the SSH user and any parent folders set to root. + +## Options + +You may also specify additional optional parameters when configuring synced folders. These options are listed below. More detailed examples of using some of these options are shown below this section, note the owner/group example supplies two additional options separated by commas. + +In addition to these options, the specific synced folder type might allow more options. Refer to the documentation for your specific synced folder +type for more details. The built-in synced folder types are documented in other pages available in the navigation for these docs. + +- `create` (boolean) - If true, the host path will be created if it does not exist. Defaults to false. + +- `disabled` (boolean) - If true, this synced folder will be disabled and will not be setup. This can be used to disable a previously defined synced folder or to conditionally disable a definition based on some external factor. + +- `group` (string) - The group that will own the synced folder. By default this will be the SSH user. Some synced folder types do not support modifying the group. + +- `mount_options` (array) - A list of additional mount options to pass to the `mount` command. + +- `owner` (string) - The user who should be the owner of this synced folder. By default, this will be the SSH user. Some synced folder types do not support modifying the owner. + +- `type` (string) - The type of synced folder. If this is not specified, Vagrant will automatically choose the best synced folder option for your environment. Otherwise, you can specify a specific type such as `nfs`. + +- `id` (string) - The name for the mount point of this synced folder in the guest machine. This shows up when you run `mount` in the guest machine. \ No newline at end of file diff --git a/website/content/docs/vagrantfile/winrm_settings.mdx b/website/content/docs/vagrantfile/winrm.mdx similarity index 100% rename from website/content/docs/vagrantfile/winrm_settings.mdx rename to website/content/docs/vagrantfile/winrm.mdx diff --git a/website/content/docs/vagrantfile/winssh_settings.mdx b/website/content/docs/vagrantfile/winssh.mdx similarity index 100% rename from website/content/docs/vagrantfile/winssh_settings.mdx rename to website/content/docs/vagrantfile/winssh.mdx diff --git a/website/content/docs/what-is.mdx b/website/content/docs/what-is.mdx new file mode 100644 index 00000000000..cf6e1dd41ef --- /dev/null +++ b/website/content/docs/what-is.mdx @@ -0,0 +1,72 @@ +--- +layout: intro +page_title: Introduction +description: |- + Vagrant is a tool for building complete development environments. With an + easy-to-use workflow and focus on automation, Vagrant lowers development + environment setup time, increases development/production parity, and makes + the "it works on my machine" excuse a relic of the past. +--- + +# Introduction to Vagrant + +Vagrant is a tool for building and managing virtual machine environments in a +single workflow. With an easy-to-use workflow and focus on automation, Vagrant +lowers development environment setup time, increases production parity, and +makes the "works on my machine" excuse a relic of the past. + +If you are already familiar with the basics of Vagrant, the +[documentation](/vagrant/docs) provides a better reference build for all +available features and internals. + +## Why Vagrant? + +Vagrant provides easy to configure, reproducible, and portable work environments +built on top of industry-standard technology and controlled by a single +consistent workflow to help maximize the productivity and flexibility of you and +your team. + +To achieve its magic, Vagrant stands on the shoulders of giants. Machines +are provisioned on top of VirtualBox, VMware, AWS, or +[any other provider](/vagrant/docs/providers/). Then, industry-standard +[provisioning tools](/vagrant/docs/provisioning/) +such as shell scripts, Chef, or Puppet can automatically install +and configure software on the virtual machine. + +### For Developers + +If you are a **developer**, Vagrant will isolate dependencies and their +configuration within a single disposable, consistent environment, without +sacrificing any of the tools you are used to working with (editors, browsers, +debuggers, etc.). Once you or someone else creates a single +[Vagrantfile](/vagrant/docs/vagrantfile/), you just need to `vagrant up` and everything +is installed and configured for you to work. Other members of your team create +their development environments from the same configuration, so whether you are +working on Linux, Mac OS X, or Windows, all your team members are running code +in the same environment, against the same dependencies, all configured the same +way. Say goodbye to "works on my machine" bugs. + +### For Operators + +If you are an **operations engineer** or **DevOps engineer**, Vagrant gives you a disposable +environment and consistent workflow for developing and testing infrastructure +management scripts. You can quickly test things like shell scripts, Chef +cookbooks, Puppet modules, and more using local virtualization such as +VirtualBox or VMware. Then, with the _same configuration_, you can test these +scripts on remote clouds such as AWS or RackSpace with the _same workflow_. +Ditch your custom scripts to recycle EC2 instances, stop juggling SSH prompts to +various machines, and start using Vagrant to bring sanity to your life. + +### For Designers + +If you are a **designer**, Vagrant will automatically set everything up that is +required for that web app in order for you to focus on doing what you do best: +design. Once a developer configures Vagrant, you do not need to worry about how +to get that app running ever again. No more bothering other developers to help +you fix your environment so you can test designs. Just check out the code, +`vagrant up`, and start designing. + +### For Everyone + +Vagrant is designed for everyone as the easiest and fastest way to create a +virtualized environment! diff --git a/website/content/docs/why/cli-tools.mdx b/website/content/docs/why/cli-tools.mdx new file mode 100644 index 00000000000..f38b0b3fb41 --- /dev/null +++ b/website/content/docs/why/cli-tools.mdx @@ -0,0 +1,37 @@ +--- +layout: intro +page_title: Vagrant vs. CLI Tools +description: |- + Virtualization software like VirtualBox and VMware comes with command line + utilities for managing the lifecycle of machines on their platform. Vagrant + actually uses many of these utilities internally. The difference between these + CLI tools and Vagrant is that Vagrant provides a declarative, reproducible, + idempotent workflow. +--- + +# Vagrant vs. CLI Tools + +Virtualization software like VirtualBox and VMware come with command line +utilities for managing the lifecycle of machines on their platform. Many +people make use of these utilities to write their own automation. Vagrant +actually uses many of these utilities internally. + +The difference between these CLI tools and Vagrant is that Vagrant builds +on top of these utilities in a number of ways while still providing a +consistent workflow. Vagrant supports multiple synced folder types, multiple +provisioners to set up the machine, automatic SSH setup, creating HTTP tunnels +into your development environment and more. All of these can be configured +using a single simple configuration file. + +Vagrant still has a number of improvements over manual scripting even if you +ignore all the higher-level features Vagrant provides. The command line +utilities provided by virtualization software often change each version +or have subtle bugs with workarounds. Vagrant automatically detects the +version, uses the correct flags, and can work around known issues. So if +you're using one version of VirtualBox and a co-worker is using a different +version, Vagrant will still work consistently. + +For highly specific workflows that don't change often, it can still be +beneficial to maintain custom scripts. Vagrant is targeted at building +development environments but some advanced users still use the CLI tools +underneath to do other manual things. diff --git a/website/content/docs/why/docker.mdx b/website/content/docs/why/docker.mdx new file mode 100644 index 00000000000..05f1ab2711a --- /dev/null +++ b/website/content/docs/why/docker.mdx @@ -0,0 +1,32 @@ +--- +layout: intro +page_title: Vagrant vs. Docker +description: |- + Vagrant and Docker both provide isolation primitives. This page details the + differences between them. +--- + +# Vagrant vs. Docker + +Vagrant is a tool focused on providing a consistent development environment +workflow across multiple operating systems. Docker is a container management +that can consistently run software as long as a containerization system exists. + +Containers are generally more lightweight than virtual machines, so starting +and stopping containers is extremely fast. Docker uses the native +containerization functionality on macOS, Linux, and Windows. + +Currently, Docker lacks support for certain operating systems (such as +BSD). If your target deployment is one of these operating systems, +Docker will not provide the same production parity as a tool like Vagrant. +Vagrant will allow you to run a Windows development environment on Mac or Linux, +as well. + +For microservice heavy environments, Docker can be attractive because you +can easily start a single Docker VM and start many containers above that +very quickly. This is a good use case for Docker. Vagrant can do this as well +with the Docker provider. A primary benefit for Vagrant is a consistent workflow +but there are many cases where a pure-Docker workflow does make sense. + +Both Vagrant and Docker have a vast library of community-contributed "images" +or "boxes" to choose from. diff --git a/website/content/docs/why/index.mdx b/website/content/docs/why/index.mdx new file mode 100644 index 00000000000..0e77b0e137f --- /dev/null +++ b/website/content/docs/why/index.mdx @@ -0,0 +1,20 @@ +--- +layout: intro +page_title: Vagrant vs. Other Software +description: |- + Vagrant is not the only tool to manage virtual machines and development + environments. These pages detail similar tools to Vagrant. +--- + +# Vagrant vs. Other Software + +Vagrant is not the only tool to manage virtual machines and development +environments. This section compares Vagrant to these other software choices. + +Due to the bias of the comparisons, we attempt to only use facts. If you find +something that is invalid or out of date in the comparisons, please [open an +issue](https://github.com/hashicorp/vagrant/issues) and we'll address it as soon +as possible. + +Use the navigation on the left to read comparisons of Vagrant versus similar +software. diff --git a/website/content/docs/why/terraform.mdx b/website/content/docs/why/terraform.mdx new file mode 100644 index 00000000000..9fad56e5318 --- /dev/null +++ b/website/content/docs/why/terraform.mdx @@ -0,0 +1,36 @@ +--- +layout: intro +page_title: Vagrant vs. Terraform +description: |- + Vagrant is a tool for managing virtual machines. Terraform is another open + source tool from HashiCorp which enables infrastructure as code. +--- + +# Vagrant vs. Terraform + +Vagrant and [Terraform][terraform] are both projects from [HashiCorp][hashicorp]. +Vagrant is a tool focused for managing development environments and +Terraform is a tool for building infrastructure. + +Terraform can describe complex sets of infrastructure that exist +locally or remotely. It is focused on building and changing that infrastructure +over time. The minimal aspects of virtual machine lifecycle can be reproduced +in Terraform, sometimes leading to confusion with Vagrant. + +Vagrant provides a number of higher level features that Terraform doesn't. +Synced folders, automatic networking, HTTP tunneling, and more are features +provided by Vagrant to ease development environment usage. Because Terraform +is focused on infrastructure management and not development environments, +these features are out of scope for that project. + +The primary usage of Terraform is for managing remote resources in cloud +providers such as AWS. Terraform is designed to be able to manage extremely +large infrastructures that span multiple cloud providers. Vagrant is designed +primarily for local development environments that use only a handful of +virtual machines at most. + +Vagrant is for development environments. Terraform is for more general +infrastructure management. + +[hashicorp]: https://www.hashicorp.com +[terraform]: https://www.terraform.io/ diff --git a/website/content/vmware/index.mdx b/website/content/vmware/index.mdx deleted file mode 100644 index 95221c0e67b..00000000000 --- a/website/content/vmware/index.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: vmware -page_title: VMware -description: This is a placeholder page. ---- - -See [/docs/providers/vmware](/vagrant/docs/providers/vmware) diff --git a/website/data/alert-banner.js b/website/data/alert-banner.js deleted file mode 100644 index 5e1a167631a..00000000000 --- a/website/data/alert-banner.js +++ /dev/null @@ -1,17 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: BUSL-1.1 - */ - -export const ALERT_BANNER_ACTIVE = false - -// https://github.com/hashicorp/web-components/tree/master/packages/alert-banner -export default { - tag: 'Blog post', - url: 'https://www.hashicorp.com/blog/a-new-chapter-for-hashicorp', - text: 'HashiCorp shares have begun trading on the Nasdaq. Read the blog from our founders, Mitchell Hashimoto and Armon Dadgar.', - linkText: 'Read the post', - // Set the expirationDate prop with a datetime string (e.g. '2020-01-31T12:00:00-07:00') - // if you'd like the component to stop showing at or after a certain date - expirationDate: '2021-12-17T23:00:00-07:00', -} diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index fb3c0282308..0a1a5725b0a 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -4,192 +4,402 @@ "path": "" }, { - "title": "Installation", + "title": "What is Vagrant?", + "path": "what-is" + }, + { + "title": "Why use Vagrant?", "routes": [ { "title": "Overview", - "path": "installation" - }, - { - "title": "Backwards Compatibility", - "path": "installation/backwards-compatibility" - }, - { - "title": "Upgrading", - "path": "installation/upgrading" + "path": "why" }, { - "title": "Upgrading from 1.0.x", - "path": "installation/upgrading-from-1-0" + "title": "CLI tools", + "path": "why/cli-tools" }, { - "title": "From Source", - "path": "installation/source" + "title": "Docker", + "path": "why/docker" }, { - "title": "Uninstallation", - "path": "installation/uninstallation" + "title": "Terraform", + "path": "why/terraform" } ] }, { - "title": "Commands (CLI)", + "title": "How does Vagrant work?", "routes": [ { "title": "Overview", - "path": "cli" + "href": "#" }, { - "title": "box", - "path": "cli/box" - }, - { - "title": "cloud", - "path": "cli/cloud" - }, - { - "title": "connect", - "path": "cli/connect" + "title": "Plugins", + "path": "concept/plugin" }, { - "title": "destroy", - "path": "cli/destroy" - }, - { - "title": "global-status", - "path": "cli/global-status" - }, - { - "title": "halt", - "path": "cli/halt" - }, - { - "title": "init", - "path": "cli/init" + "title": "Providers", + "path": "concept/provider" }, { - "title": "login", - "path": "cli/login" + "title": "Boxes", + "path": "concept/box" }, + { - "title": "package", - "path": "cli/package" + "title": "Box provider architecture", + "path": "concept/box-architecture" }, { - "title": "plugin", - "path": "cli/plugin" - }, + "title": "Vagrantfile", + "href": "#TODO" + } + ] + }, + { + "divider": true + }, + { + "heading": "Vagrant operations" + }, + { + "title": "Install Vagrant", + "routes": [ { - "title": "port", - "path": "cli/port" + "title": "Overview", + "href": "/vagrant/install" }, { - "title": "powershell", - "path": "cli/powershell" + "title": "Windows Subsystem for Linux (WSL)", + "path": "install/wsl" }, { - "title": "provision", - "path": "cli/provision" + "title": "macOS Catalina", + "path": "install/macos-catalina", + "hidden": true }, { - "title": "rdp", - "path": "cli/rdp" + "title": "Advanced", + "path": "install/advanced" }, { - "title": "reload", - "path": "cli/reload" - }, + "title": "Uninstall Vagrant", + "path": "install/uninstall" + } + ] + }, + { + "title": "Quickstart", + "href": "/vagrant/tutorials/get-started" + }, + { + "title": "Upgrade Vagrant", + "routes": [ { - "title": "resume", - "path": "cli/resume" + "title": "Overview", + "path": "upgrade" }, { - "title": "share", - "path": "cli/share" - }, + "title": "Backwards compatibility", + "path": "upgrade/backwards-compatibility" + } + ] + }, + { + "title": "Configure Vagrant", + "routes": [ { - "title": "snapshot", - "path": "cli/snapshot" + "title": "Overview", + "path": "configure-vagrant" }, { - "title": "ssh", - "path": "cli/ssh" + "title": "Environment variables", + "path": "configure-vagrant/environment-variables" }, { - "title": "ssh-config", - "path": "cli/ssh_config" + "title": "Enable experimental features", + "path": "configure-vagrant/experimental-features" }, { - "title": "status", - "path": "cli/status" - }, + "title": "Feature flag", + "badge": { + "text": "EXPERIMENTAL", + "type": "outlined", + "color": "neutral" + }, + "path": "configure-vagrant/feature-flag" + } + ] + }, + { + "divider": true + }, + { + "heading": "Manage and use environments" + }, + { + "title": "Define environment", + "routes": [ { - "title": "suspend", - "path": "cli/suspend" + "title": "Overview", + "path": "define" }, { - "title": "up", - "path": "cli/up" + "title": "Providers", + "routes": [ + { + "title": "Overview", + "path": "define/providers" + }, + { + "title": "VirtualBox", + "path": "define/providers/virtualbox" + }, + { + "title": "VMware", + "path": "define/providers/vmware" + }, + { + "title": "Docker", + "path": "define/providers/docker" + }, + { + "title": "Hyper-V", + "path": "define/providers/hyperv" + }, + { + "title": "Custom provider", + "path": "define/providers/custom" + } + ] }, { - "title": "upload", - "path": "cli/upload" + "title": "Cloud-Init", + "path": "define/cloud-init" }, { - "title": "validate", - "path": "cli/validate" + "title": "Provisioners", + "routes": [ + { + "title": "Overview", + "path": "define/provision" + }, + { + "title": "File", + "path": "define/provision/file" + }, + { + "title": "Shell", + "path": "define/provision/shell" + }, + { + "title": "Ansible", + "routes": [ + { + "title": "Overview", + "path": "define/provision/ansible" + }, + { + "title": "Common Ansible options", + "path": "define/provision/ansible/common" + }, + { + "title": "Ansible", + "path": "define/provision/ansible/ansible" + }, + { + "title": "Ansible Local", + "path": "define/provision/ansible/local" + } + ] + }, + { + "title": "CFEngine", + "path": "define/provision/cfengine" + }, + { + "title": "Chef", + "routes": [ + { + "title": "Overview", + "path": "define/provision/chef" + }, + { + "title": "Chef Common configuration", + "path": "define/provision/chef/common" + }, + { + "title": "Chef Solo", + "path": "define/provision/chef/solo" + }, + { + "title": "Chef Zero", + "path": "define/provision/chef/zero" + }, + { + "title": "Chef Client", + "path": "define/provision/chef/client" + }, + { + "title": "Chef Apply", + "path": "define/provision/chef/apply" + } + ] + }, + { + "title": "Docker", + "path": "define/provision/docker" + }, + { + "title": "Podman", + "path": "define/provision/podman" + }, + { + "title": "Puppet", + "routes": [ + { + "title": "Overview", + "path": "define/provision/puppet" + }, + { + "title": "Puppet Apply", + "path": "define/provision/puppet/apply" + }, + { + "title": "Puppet Agent", + "path": "define/provision/puppet/agent" + } + ] + }, + { + "title": "Salt", + "path": "define/provision/salt" + } + ] }, { - "title": "version", - "path": "cli/version" + "title": "Disks", + "routes": [ + { + "title": "Overview", + "path": "define/disks" + }, + { + "title": "VirtualBox", + "path": "define/disks/virtualbox" + }, + { + "title": "Hyper-V", + "path": "define/disks/hyperv" + }, + { + "title": "VMware", + "path": "define/disks/vmware" + } + ] }, { - "title": "More Commands", - "path": "cli/non-primary" + "title": "Synced folders", + "routes": [ + { + "title": "Overview", + "path": "define/synced-folders" + }, + { + "title": "NFS", + "path": "define/synced-folders/nfs" + }, + { + "title": "RSync", + "path": "define/synced-folders/rsync" + }, + { + "title": "SMB", + "path": "define/synced-folders/smb" + }, + { + "title": "VirtualBox", + "path": "define/synced-folders/virtualbox" + } + ] }, { - "title": "Aliases", - "path": "cli/aliases" + "title": "Networking", + "routes": [ + { + "title": "Overview", + "path": "define/networking" + }, + { + "title": "Provider-specific", + "routes": [ + { + "title": "VirtualBox", + "path": "define/networking/provider/virtualbox" + }, + { + "title": "Docker", + "path": "define/networking/provider/docker" + } + ] + }, + { + "title": "Forwarded ports", + "path": "define/networking/forwarded_ports" + }, + { + "title": "Private network", + "path": "define/networking/private_network" + }, + { + "title": "Public network", + "path": "define/networking/public_network" + } + ] }, { - "title": "Machine Readable Output", - "path": "cli/machine-readable" + "title": "Vagrant lifecycle triggers", + "path": "define/triggers" }, { - "title": "rsync", - "path": "cli/rsync", - "hidden": true + "title": "Multi-machine", + "path": "define/multi-machine" }, + { - "title": "rsync-auto", - "path": "cli/rsync-auto", - "hidden": true - }, + "title": "Tips and tricks", + "path": "define/tips" + } + ] + }, + { + "title": "Start environment", + "routes": [ { - "title": "winrm", - "path": "cli/winrm", - "hidden": true + "title": "Overview", + "path": "start" }, { - "title": "winrm_config", - "path": "cli/winrm_config", - "hidden": true + "title": "Debug", + "path": "start/debug" } ] }, { - "title": "Vagrant Share", + "title": "Share environment", "routes": [ { "title": "Overview", "path": "share" }, { - "title": "HTTP Sharing", + "title": "HTTP sharing", "path": "share/http" }, { - "title": "SSH Sharing", + "title": "SSH sharing", "path": "share/ssh" }, { @@ -201,602 +411,680 @@ "path": "share/security" }, { - "title": "Custom Provider", + "title": "Custom provider", "path": "share/provider" } ] }, { - "title": "Vagrantfile", + "title": "Deploy environment", "routes": [ { "title": "Overview", - "path": "vagrantfile" - }, - { - "title": "Configuration Version", - "path": "vagrantfile/version" - }, - { - "title": "Minimum Vagrant Version", - "path": "vagrantfile/vagrant_version" - }, - { - "title": "Tips & Tricks", - "path": "vagrantfile/tips" - }, - { - "title": "config.vm", - "path": "vagrantfile/machine_settings" - }, - { - "title": "config.ssh", - "path": "vagrantfile/ssh_settings" + "path": "push" }, { - "title": "config.winrm", - "path": "vagrantfile/winrm_settings" + "title": "FTP / SFTP", + "path": "push/ftp" }, { - "title": "config.winssh", - "path": "vagrantfile/winssh_settings" + "title": "Heroku", + "path": "push/heroku" }, { - "title": "config.vagrant", - "path": "vagrantfile/vagrant_settings" + "title": "Local Exec", + "path": "push/local-exec" } ] }, { - "title": "Boxes", + "divider": true + }, + { + "heading": "Extend Vagrant" + }, + { + "title": "Create a base box", "routes": [ { "title": "Overview", - "path": "boxes" + "path": "create-box" }, { - "title": "Box Versioning", - "path": "boxes/versioning" + "title": "Provider-specific", + "routes": [ + { + "title": "VirtualBox", + "path": "create-box/provider/virtualbox" + }, + { + "title": "VMware", + "path": "create-box/provider/vmware" + }, + { + "title": "Hyper-V", + "path": "create-box/provider/hyperv" + }, + { + "title": "Docker", + "path": "create-box/provider/docker" + } + ] }, { - "title": "Creating a Base Box", - "path": "boxes/base" + "title": "Box info format", + "path": "create-box/info" }, { - "title": "Box File Format", - "path": "boxes/format" + "title": "Box file format", + "path": "create-box/format" }, { - "title": "Box Repository", - "path": "boxes/box_repository" + "title": "Box repository", + "path": "create-box/repository" }, { - "title": "Box Info Format", - "path": "boxes/info" + "title": "Box versioning", + "path": "create-box/versioning" } ] }, { - "title": "Provisioning", + "title": "Develop Vagrant plugins", "routes": [ { "title": "Overview", - "path": "provisioning" - }, - { - "title": "Basic Usage", - "path": "provisioning/basic_usage" - }, - { - "title": "File", - "path": "provisioning/file" - }, - { - "title": "Shell", - "path": "provisioning/shell" + "path": "develop-plugin" }, { - "title": "Ansible Intro", - "path": "provisioning/ansible_intro" - }, - { - "title": "Ansible", - "path": "provisioning/ansible" - }, - { - "title": "Ansible Local", - "path": "provisioning/ansible_local" - }, - { - "title": "Common Ansible Options", - "path": "provisioning/ansible_common" - }, - { - "title": "CFEngine", - "path": "provisioning/cfengine" - }, - { - "title": "Chef Common Configuration", - "path": "provisioning/chef_common" - }, - { - "title": "Chef Solo", - "path": "provisioning/chef_solo" - }, - { - "title": "Chef Zero", - "path": "provisioning/chef_zero" - }, - { - "title": "Chef Client", - "path": "provisioning/chef_client" + "title": "Action Hooks", + "path": "develop-plugin/action-hooks" }, { - "title": "Chef Apply", - "path": "provisioning/chef_apply" + "title": "Commands", + "path": "develop-plugin/commands" }, { - "title": "Docker", - "path": "provisioning/docker" + "title": "Configuration", + "path": "develop-plugin/configuration" }, { - "title": "Podman", - "path": "provisioning/podman" + "title": "Guests", + "path": "develop-plugin/guests" }, { - "title": "Puppet Apply", - "path": "provisioning/puppet_apply" + "title": "Guest Capabilities", + "path": "develop-plugin/guest-capabilities" }, { - "title": "Puppet Agent", - "path": "provisioning/puppet_agent" + "title": "Hosts", + "path": "develop-plugin/hosts" }, { - "title": "Salt", - "path": "provisioning/salt" - } - ] - }, - { - "title": "Networking", - "routes": [ - { - "title": "Overview", - "path": "networking" + "title": "Host Capabilities", + "path": "develop-plugin/host-capabilities" }, { - "title": "Basic Usage", - "path": "networking/basic_usage" + "title": "Providers", + "path": "develop-plugin/providers" }, { - "title": "Forwarded Ports", - "path": "networking/forwarded_ports" + "title": "Provisioners", + "path": "develop-plugin/provisioners" }, { - "title": "Private Network", - "path": "networking/private_network" + "title": "Packaging & Distribution", + "path": "develop-plugin/packaging" }, { - "title": "Public Network", - "path": "networking/public_network" + "title": "Go Plugins", + "routes": [ + { + "title": "Overview", + "path": "develop-plugin/go-plugins" + }, + { + "title": "Guests", + "path": "develop-plugin/go-plugins/guests" + } + ] } ] }, { - "title": "Synced Folders", + "divider": true + }, + { + "heading": "HCP Vagrant" + }, + { + "title": "Overview", + "href": "hcp" + }, + { + "title": "Create and share boxes", "routes": [ { "title": "Overview", - "path": "synced-folders" + "href": "hcp/box" }, { - "title": "Basic Usage", - "path": "synced-folders/basic_usage" + "title": "Create a new box", + "href": "hcp/box/create" }, { - "title": "NFS", - "path": "synced-folders/nfs" + "title": "Lifecycle", + "href": "hcp/box/lifecycle" }, { - "title": "RSync", - "path": "synced-folders/rsync" + "title": "Create a new version", + "href": "hcp/box/create-version" }, { - "title": "SMB", - "path": "synced-folders/smb" + "title": "Private boxes", + "href": "hcp/box/private" }, { - "title": "VirtualBox", - "path": "synced-folders/virtualbox" + "title": "API release workflow", + "href": "hcp/box/api-release-workflow" } ] }, { - "title": "Cloud-Init", + "title": "Discover and use boxes", "routes": [ { "title": "Overview", - "path": "cloud-init" + "href": "hcp/discover" }, { - "title": "Configuration", - "path": "cloud-init/configuration" + "title": "Use HCP Vagrant boxes", + "href": "hcp/discover/use" }, { - "title": "Usage", - "path": "cloud-init/usage" + "title": "Private boxes", + "href": "hcp/discover/private" } ] }, { - "title": "Disks", + "title": "Manage organizations and users", "routes": [ { "title": "Overview", - "path": "disks" + "href": "hcp/organizations" }, { - "title": "Configuration", - "path": "disks/configuration" - }, - { - "title": "Usage", - "path": "disks/usage" + "title": "Create an organization", + "href": "hcp/organizations/create" }, { - "title": "VirtualBox", - "routes": [ - { - "title": "Overview", - "path": "disks/virtualbox" - }, - { - "title": "Usage", - "path": "disks/virtualbox/usage" - }, - { - "title": "Common Issues", - "path": "disks/virtualbox/common-issues" - } - ] + "title": "Authentication policy", + "href": "hcp/organizations/authentication-policy" }, { - "title": "Hyper-V", + "title": "Manage users", "routes": [ { "title": "Overview", - "path": "disks/hyperv" + "href": "hcp/organizations/users" }, { - "title": "Usage", - "path": "disks/hyperv/usage" - }, - { - "title": "Common Issues", - "path": "disks/hyperv/common-issues" - } - ] - }, - { - "title": "VMware", - "routes": [ - { - "title": "Overview", - "path": "disks/vmware" + "title": "Authentication", + "href": "hcp/organizations/users/authentication" }, { - "title": "Usage", - "path": "disks/vmware/usage" + "title": "Account recovery", + "href": "hcp/organizations/users/recovery" }, { - "title": "Common Issues", - "path": "disks/vmware/common-issues" + "title": "Migrate user to organization", + "href": "hcp/organizations/users/migrate" } ] } ] }, + { - "title": "Multi-Machine", - "path": "multi-machine" - }, - { - "title": "Providers", + "title": "Migrate from Vagrant Cloud", "routes": [ { - "title": "Overview", - "path": "providers" - }, - { - "title": "Installation", - "path": "providers/installation" + "title": "Migration guide", + "href": "hcp/migrate/guide" }, { - "title": "Basic Usage", - "path": "providers/basic_usage" + "title": "Troubleshoot migration", + "href": "hcp/migrate/troubleshoot" }, { - "title": "Configuration", - "path": "providers/configuration" - }, + "title": "Post-migration guide", + "href": "hcp/migrate/post-migration-guide" + } + ] + }, + { + "title": "Request limits", + "href": "hcp/request-limits" + }, + { + "title": "Support", + "href": "hcp/support" + }, + { + "title": "HCP Vagrant", + "hidden": true, + "routes": [ { - "title": "Default Provider", - "path": "providers/default" + "title": "Overview", + "path": "hcp" }, { - "title": "VirtualBox", + "title": "Create and share boxes", "routes": [ { "title": "Overview", - "path": "providers/virtualbox" + "path": "hcp/box" }, { - "title": "Usage", - "path": "providers/virtualbox/usage" + "title": "Create a new box", + "path": "hcp/box/create" }, { - "title": "Creating a Base Box", - "path": "providers/virtualbox/boxes" + "title": "Lifecycle", + "path": "hcp/box/lifecycle" }, { - "title": "Configuration", - "path": "providers/virtualbox/configuration" + "title": "Create a new version", + "path": "hcp/box/create-version" }, { - "title": "Networking", - "path": "providers/virtualbox/networking" + "title": "Private Boxes", + "path": "hcp/box/private" }, { - "title": "Common Issues", - "path": "providers/virtualbox/common-issues" + "title": "API release workflow", + "path": "hcp/box/api-release-workflow" } ] }, { - "title": "VMware", + "title": "Discover and use boxes", "routes": [ { "title": "Overview", - "path": "providers/vmware" + "path": "hcp/discover" }, { - "title": "Installation", - "path": "providers/vmware/installation" + "title": "Use HCP Vagrant boxes", + "path": "hcp/discover/use" }, { - "title": "VMware Utility", - "path": "providers/vmware/vagrant-vmware-utility" - }, - { - "title": "Usage", - "path": "providers/vmware/usage" - }, + "title": "Private boxes", + "path": "hcp/discover/private" + } + ] + }, + { + "title": "Manage users and organizations", + "routes": [ { - "title": "Boxes", - "path": "providers/vmware/boxes" + "title": "Overview", + "path": "hcp/organizations" }, { - "title": "Configuration", - "path": "providers/vmware/configuration" + "title": "Create an organization", + "path": "hcp/organizations/create" }, { - "title": "Known Issues", - "path": "providers/vmware/known-issues" + "title": "Authentication policy", + "path": "hcp/organizations/authentication-policy" }, { - "title": "FAQ", - "path": "providers/vmware/faq" + "title": "Manage users", + "routes": [ + { + "title": "Overview", + "path": "hcp/organizations/users" + }, + { + "title": "Authentication", + "path": "hcp/organizations/users/authentication" + }, + { + "title": "Account recovery", + "path": "hcp/organizations/users/recovery" + }, + { + "title": "Migrate user to organization", + "path": "hcp/organizations/users/migrate" + } + ] } ] }, + { - "title": "Docker", + "title": "Migrate from Vagrant Cloud", "routes": [ { - "title": "Overview", - "path": "providers/docker" - }, - { - "title": "Basic Usage", - "path": "providers/docker/basics" + "title": "HCP Vagrant Registry Migration Guide", + "path": "hcp/migrate/guide" }, { - "title": "Commands", - "path": "providers/docker/commands" + "title": "Migration Troubleshooting", + "path": "hcp/migrate/troubleshoot" }, { - "title": "Boxes", - "path": "providers/docker/boxes" - }, + "title": "Post Migration", + "path": "hcp/migrate/post-migration-guide" + } + ] + }, + { + "title": "Request limits", + "path": "hcp/request-limits" + }, + { + "title": "Support", + "path": "hcp/support" + }, + { + "title": "HCP Vagrant API", + "hidden": true, + "routes": [ { - "title": "Configuration", - "path": "providers/docker/configuration" + "title": "v2", + "path": "hcp/api/v2" }, { - "title": "Networking", - "path": "providers/docker/networking" + "title": "v1", + "path": "hcp/api/v1" } ] + } + ] + }, + { + "divider": true + }, + { + "heading": "Reference" + }, + { + "title": "Vagrantfile", + "routes": [ + { + "title": "Overview", + "path": "vagrantfile" }, { - "title": "Hyper-V", + "title": "Minimum Vagrant version", + "path": "vagrantfile/vagrant-version" + }, + { + "title": "Configuration version", + "path": "vagrantfile/version" + }, + { + "title": "config.vm", "routes": [ { "title": "Overview", - "path": "providers/hyperv" + "path": "vagrantfile/vm" + }, + { + "title": "config.vm.provider", + "routes": [ + { + "title": "Overview", + "path": "vagrantfile/vm/provider" + }, + { + "title": "VirtualBox", + "path": "vagrantfile/vm/provider/virtualbox" + }, + { + "title": "VMware", + "path": "vagrantfile/vm/provider/vmware" + }, + { + "title": "Docker", + "path": "vagrantfile/vm/provider/docker" + }, + { + "title": "Hyper-V", + "path": "vagrantfile/vm/provider/hyperv" + } + ] }, { - "title": "Usage", - "path": "providers/hyperv/usage" + "title": "config.vm.cloud_init", + "path": "vagrantfile/vm/cloud-init" }, { - "title": "Creating a Base Box", - "path": "providers/hyperv/boxes" + "title": "config.vm.provision", + "path": "vagrantfile/vm/provision" }, { - "title": "Configuration", - "path": "providers/hyperv/configuration" + "title": "config.vm.disk", + "path": "vagrantfile/vm/disk" }, { - "title": "Limitations", - "path": "providers/hyperv/limitations" + "title": "config.vm.synced_folder", + "path": "vagrantfile/vm/synced-folder" } ] }, { - "title": "Custom Provider", - "path": "providers/custom" + "title": "config.trigger", + "path": "vagrantfile/trigger" + }, + { + "title": "config.ssh", + "path": "vagrantfile/ssh" + }, + { + "title": "config.winrm", + "path": "vagrantfile/winrm" + }, + { + "title": "config.winssh", + "path": "vagrantfile/winssh" + }, + { + "title": "config.vagrant", + "path": "vagrantfile/vagrant" } ] }, { - "title": "Plugins", + "title": "Commands (CLI)", "routes": [ { "title": "Overview", - "path": "plugins" + "path": "cli" }, { - "title": "Usage", - "path": "plugins/usage" + "title": "box", + "path": "cli/box" }, { - "title": "Plugin Development Basics", - "path": "plugins/development-basics" + "title": "cloud", + "path": "cli/cloud" }, { - "title": "Action Hooks", - "path": "plugins/action-hooks" + "title": "connect", + "path": "cli/connect" }, { - "title": "Commands", - "path": "plugins/commands" + "title": "destroy", + "path": "cli/destroy" }, { - "title": "Configuration", - "path": "plugins/configuration" + "title": "docker-exec", + "badge": { + "text": "DOCKER", + "type": "outlined", + "color": "neutral" + }, + "path": "cli/docker-exec" }, { - "title": "Guests", - "path": "plugins/guests" + "title": "docker-logs", + "badge": { + "text": "DOCKER", + "type": "outlined", + "color": "neutral" + }, + "path": "cli/docker-logs" }, { - "title": "Guest Capabilities", - "path": "plugins/guest-capabilities" + "title": "docker-run", + "badge": { + "text": "DOCKER", + "type": "outlined", + "color": "neutral" + }, + "path": "cli/docker-run" }, { - "title": "Hosts", - "path": "plugins/hosts" + "title": "global-status", + "path": "cli/global-status" }, { - "title": "Host Capabilities", - "path": "plugins/host-capabilities" + "title": "halt", + "path": "cli/halt" }, { - "title": "Providers", - "path": "plugins/providers" + "title": "init", + "path": "cli/init" }, { - "title": "Provisioners", - "path": "plugins/provisioners" + "title": "login", + "path": "cli/login" }, { - "title": "Packaging & Distribution", - "path": "plugins/packaging" + "title": "package", + "path": "cli/package" }, { - "title": "Go Plugins", - "routes": [ - { - "title": "Overview", - "path": "plugins/go-plugins" - }, - { - "title": "Guests", - "path": "plugins/go-plugins/guests" - } - ] - } - ] - }, - { - "title": "Push", - "routes": [ + "title": "plugin", + "path": "cli/plugin" + }, { - "title": "Overview", - "path": "push" + "title": "port", + "path": "cli/port" }, { - "title": "FTP / SFTP", - "path": "push/ftp" + "title": "powershell", + "path": "cli/powershell" }, { - "title": "Heroku", - "path": "push/heroku" + "title": "provision", + "path": "cli/provision" }, { - "title": "Local Exec", - "path": "push/local-exec" - } - ] - }, - { - "title": "Triggers", - "routes": [ + "title": "rdp", + "path": "cli/rdp" + }, { - "title": "Overview", - "path": "triggers" + "title": "reload", + "path": "cli/reload" }, { - "title": "Configuration", - "path": "triggers/configuration" + "title": "resume", + "path": "cli/resume" }, { - "title": "Usage", - "path": "triggers/usage" - } - ] - }, - { - "title": "Experimental", - "routes": [ + "title": "share", + "path": "cli/share" + }, { - "title": "Feature Flags", - "path": "experimental" - } - ] - }, - { - "title": "Other", - "routes": [ + "title": "snapshot", + "path": "cli/snapshot" + }, { - "title": "Overview", - "path": "other" + "title": "ssh", + "path": "cli/ssh" + }, + { + "title": "ssh-config", + "path": "cli/ssh_config" }, { - "title": "Debugging", - "path": "other/debugging" + "title": "status", + "path": "cli/status" }, { - "title": "Environmental Variables", - "path": "other/environmental-variables" + "title": "suspend", + "path": "cli/suspend" }, { - "title": "WSL", - "path": "other/wsl" + "title": "up", + "path": "cli/up" }, { - "title": "macOS Catalina", - "path": "other/macos-catalina", + "title": "upload", + "path": "cli/upload" + }, + { + "title": "validate", + "path": "cli/validate" + }, + { + "title": "version", + "path": "cli/version" + }, + { + "title": "More Commands", + "path": "cli/non-primary" + }, + { + "title": "Aliases", + "path": "cli/aliases" + }, + { + "title": "Machine Readable Output", + "path": "cli/machine-readable" + }, + { + "title": "rsync", + "path": "cli/rsync", + "hidden": true + }, + { + "title": "rsync-auto", + "path": "cli/rsync-auto", + "hidden": true + }, + { + "title": "winrm", + "path": "cli/winrm", + "hidden": true + }, + { + "title": "winrm_config", + "path": "cli/winrm_config", "hidden": true } ] }, { - "divider": true + "title": "VMware Utility", + "path": "vagrant-vmware-utility" }, { - "title": "Vagrant Cloud", - "href": "/vagrant-cloud" + "title": "HCP Vagrant API", + "routes": [ + { + "title": "v2", + "href": "hcp/api/v2" + }, + { + "title": "v1", + "href": "hcp/api/v1" + } + ] } -] +] \ No newline at end of file diff --git a/website/data/metadata.js b/website/data/metadata.js deleted file mode 100644 index a80d65111ed..00000000000 --- a/website/data/metadata.js +++ /dev/null @@ -1,7 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: BUSL-1.1 - */ - -export const productName = 'Vagrant' -export const productSlug = 'vagrant' diff --git a/website/data/subnav.js b/website/data/subnav.js deleted file mode 100644 index 362b173707b..00000000000 --- a/website/data/subnav.js +++ /dev/null @@ -1,22 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: BUSL-1.1 - */ - -export default [ - { - text: 'Intro', - url: '/intro', - type: 'inbound', - }, - { - text: 'Docs', - url: '/docs', - type: 'inbound', - }, - { - text: 'Community', - url: '/community', - type: 'inbound', - }, -] diff --git a/website/data/vmware-nav-data.json b/website/data/vmware-nav-data.json deleted file mode 100644 index 9e33b555085..00000000000 --- a/website/data/vmware-nav-data.json +++ /dev/null @@ -1,6 +0,0 @@ -[ - { - "title": "Privacy Policy", - "href": "https://www.hashicorp.com/privacy" - } -] diff --git a/website/redirects.js b/website/redirects.js index 78d94cbb53a..e40138e3816 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -32,4 +32,9 @@ permanent: true, }, */ + { + source: '/vagrant/vmware', + destination: '/vagrant/docs/providers/vmware', + permanent: true + } ]