beckermj/vaguerent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

port in raw content

Browse Source
This commit is contained in:
Jeff Escalante 2020-05-05 18:11:12 -04:00
parent 28a5c07c89
commit 3daf2b8db9
No known key found for this signature in database
GPG Key ID: 32D23C61AB5450DB
218 changed files with 18691 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
website/next.config.js
View File

@ -8,7 +8,7 @@ module.exports = withHashicorp({
env: {
HASHI_ENV: process.env.HASHI_ENV || 'development',
SEGMENT_WRITE_KEY: 'wFMyBE4PJCZttWfu0pNhYdWr7ygW0io4',
BUGSNAG_CLIENT_KEY: 'c1d6da7a26dc367253f39fae8d83fdac',
BUGSNAG_SERVER_KEY: 'c1d6da7a26dc367253f39fae8d83fdac',
BUGSNAG_CLIENT_KEY: '87a42e709789c35676b06b0d29a9075d',
BUGSNAG_SERVER_KEY: '4acc6140aaebfab35f535a3666674a07',
},
})

83
website/pages/docs/boxes.html.md Normal file
View File

@ -0,0 +1,83 @@
---
layout: 'docs'
page_title: 'Boxes'
sidebar_current: 'boxes'
description: |-
Boxes are the package format for Vagrant environments. A box can be used by
anyone on any platform that Vagrant supports to bring up an identical
working environment.
---
# Boxes
Boxes are the package format for Vagrant environments. A box can be used by
anyone on any platform that Vagrant supports to bring up an identical
working environment.
The `vagrant box` utility provides all the functionality for managing
boxes. You can read the documentation on the [vagrant box](/docs/cli/box.html)
command for more information.
The easiest way to use a box is to add a box from the
[publicly available catalog of Vagrant boxes](https://vagrantcloud.com/boxes/search).
You can also add and share your own customized boxes on this website.
Boxes also 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.
You can learn all about boxes by reading this page as well as the
sub-pages in the navigation to the left.
## Discovering Boxes
The easiest way to find boxes is to look on the
[public Vagrant box catalog](https://vagrantcloud.com/boxes/search)
for a box matching your use case. The catalog contains most major operating
systems as bases, as well as specialized boxes to get you up and running
quickly with LAMP stacks, Ruby, Python, etc.
The boxes on the public catalog work with many different
[providers](/docs/providers/). Whether you are using Vagrant with
VirtualBox, VMware, AWS, etc. you should be able to find a box you need.
Adding a box from the catalog is very easy. Each box shows you instructions
with how to add it, but they all follow the same format:
```
$ vagrant box add USER/BOX
```
For example: `vagrant box add hashicorp/bionic64`. You can also quickly
initialize a Vagrant environment with `vagrant init hashicorp/bionic64`.
~> **Namespaces do not guarantee canonical boxes!** A common misconception is
that a namespace like "ubuntu" represents the canonical space for Ubuntu boxes.
This is untrue. Namespaces on Vagrant Cloud behave very similarly to namespaces on
GitHub, for example. 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
HashiCorp (the makers of Vagrant) publish a basic Ubuntu 18.04 64-bit box that is available for minimal use cases. It is highly optimized, small in size, and includes support for Virtualbox, Hyper-V, and VMware. You can use it like this:
```shell
$ vagrant init hashicorp/bionic64
```
or you can update your `Vagrantfile` as follows:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = "hashicorp/bionic64"
end
```
For other users, we recommend the [Bento boxes](https://vagrantcloud.com/bento). The Bento boxes are [open source](https://github.com/chef/bento) and built for a number of providers including VMware, Virtualbox, and Parallels. There are a variety of operating systems and versions available.
These are the only two officially-recommended box sets.
Special thanks to the Bento project for providing a solid base template for the `hashicorp/bionic64` box.
~> **It is often a point of confusion**, but Canonical (the company that makes the Ubuntu operating system) publishes boxes under the "ubuntu" namespace on Vagrant Cloud. These boxes only support Virtualbox and do not provide an ideal experience for most users. If you encounter issues with these boxes, please try the Bento boxes instead.

307
website/pages/docs/boxes/base.html.md Normal file
View File

@ -0,0 +1,307 @@
---
layout: 'docs'
page_title: 'Creating a Base Box'
sidebar_current: 'boxes-base'
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.
<div class="alert alert-warning">
<strong>Advanced topic!</strong> 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.
</div>
## 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](/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](/docs/docker/boxes.html)
- [Hyper-V Base Boxes](/docs/hyperv/boxes.html)
- [VMware Base Boxes](/docs/vmware/boxes.html)
- [VirtualBox Base Boxes](/docs/virtualbox/boxes.html)
### 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](https://www.packer.io/guides/packer-on-cicd/build-image-in-cicd.html)
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 keypair](https://github.com/hashicorp/vagrant/tree/master/keys)
that Vagrant uses as a default to attempt to SSH. 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
key 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](/docs/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:
```
$ 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!

123
website/pages/docs/boxes/format.html.md Normal file
View File

@ -0,0 +1,123 @@
---
layout: 'docs'
page_title: 'Box File Format'
sidebar_current: 'boxes-format'
description: |-
The box file format for Vagrant has changed from only supporting VirtualBox to
supporting a number different providers and box formats.
---
# Box File Format
In the past, boxes were just [tar files](<https://en.wikipedia.org/wiki/Tar_(computing)>)
of VirtualBox exports. With Vagrant supporting multiple
[providers](/docs/providers/) and [versioning](/docs/boxes/versioning.html)
now, box files are slightly more complicated.
Box files made for Vagrant 1.0.x (the VirtualBox export `tar` files) continue
to work with Vagrant today. When Vagrant encounters one of these old boxes,
it automatically updates it internally to the new format.
Today, there are three different components:
- Box File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific
to a single provider and can contain anything. Vagrant core does not ever
use the contents of this file. Instead, they are passed to the provider.
Therefore, a VirtualBox box file has different contents from a VMware
box file and so on.
- Box Catalog Metadata - This is a JSON document (typically exchanged
during interactions with [HashiCorp's Vagrant Cloud](/docs/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 Information - 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](/docs/boxes/info.html).
The first two components are covered in more detail below.
## Box File
The actual box file is the required portion for Vagrant. It is recommended
you always use a metadata file alongside a box file, but direct box files
are supported for legacy reasons in Vagrant.
Box files are compressed using `tar`, `tar.gz`, or `zip`. The contents of the
archive can be anything, and is specific to each
[provider](/docs/providers/). Vagrant core itself only unpacks
the boxes for use later.
Within the archive, Vagrant does expect a single file:
`metadata.json`. This is a JSON file that is completely unrelated to
the above box catalog metadata component; there is only one
`metadata.json` per box file (inside the box file), whereas one
catalog metadata JSON document can describe multiple versions of the
same box, potentially spanning multiple providers.
`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. At this point, Vagrant core does not use any other keys in this
file.
## Box Metadata
The metadata is an optional component for a box (but highly recommended)
that enables [versioning](/docs/boxes/versioning.html), updating, multiple
providers from a single file, and more.
<div class="alert alert-block alert-info">
<strong>You do not need to manually make the metadata.</strong> If you
have an account with <a href="/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>, you
can create boxes there, and HashiCorp's Vagrant Cloud automatically creates
the metadata for you. The format is still documented here.
</div>
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://somewhere.com/bionic64_010_virtualbox.box",
"checksum_type": "sha1",
"checksum": "foo"
}
]
}
]
}
```
As you can see, the JSON document can describe multiple versions of a box,
multiple providers, and can add/remove providers 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.

42
website/pages/docs/boxes/info.html.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: 'docs'
page_title: 'Box Info Format'
sidebar_current: 'boxes-info'
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](/docs/boxes/base.html) 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](/docs/boxes/format.html) provides more information about what
else goes into a Vagrant box.

107
website/pages/docs/boxes/versioning.html.md Normal file
View File

@ -0,0 +1,107 @@
---
layout: 'docs'
page_title: 'Box Versioning'
sidebar_current: 'boxes-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](/docs/boxes/base.html).
## 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](/docs/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](/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](/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.

74
website/pages/docs/cli/aliases.html.md Normal file
View File

@ -0,0 +1,74 @@
---
layout: 'docs'
page_title: 'Aliases - Command-Line Interface'
sidebar_current: 'cli-aliases'
description: |-
Custom Vagrant commands can be defined using aliases, allowing for a simpler,
easier, and more familiar command line interface.
---
# Aliases
Inspired in part by Git's own
[alias functionality](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases),
aliases make your Vagrant experience simpler, easier, and more familiar by
allowing you to create your own custom Vagrant commands.
Aliases can be defined within `VAGRANT_HOME/aliases` file, or in a custom file
defined using the `VAGRANT_ALIAS_FILE` environment variable, in the following
format:
```
# basic command-level aliases
start = up
stop = halt
# advanced command-line aliases
eradicate = !vagrant destroy && rm -rf .vagrant
```
In a nutshell, aliases are defined using a standard `key = value` format, where
the `key` is the new Vagrant command, and the `value` is the aliased command.
Using this format, there are two types of aliases that can be defined: internal
and external aliases.
## Internal Aliases
Internal command aliases call the CLI class directly, allowing you to alias
one Vagrant command to another Vagrant command. This technique can be very
useful for creating commands that you think _should_ exist. For example,
if `vagrant stop` feels more intuitive than `vagrant halt`, the following alias
definitions would make that change possible:
```
stop = halt
```
This makes the following commands equivalent:
```
vagrant stop
vagrant halt
```
## External Aliases
While internal aliases can be used to define more intuitive Vagrant commands,
external command aliases are used to define Vagrant commands with brand new
functionality. These aliases are prefixed with the `!` character, which
indicates to the interpreter that the alias should be executed as a shell
command. For example, let's say that you want to be able to view the processor
and memory utilization of the active project's virtual machine. To do this, you
could define a `vagrant metrics` command that returns the required information
in an easy-to-read format, like so:
```
metrics = !ps aux | grep "[V]BoxHeadless" | grep $(cat .vagrant/machines/default/virtualbox/id) | awk '{ printf("CPU: %.02f%%, Memory: %.02f%%", $3, $4) }'
```
The above alias, from within the context of an active Vagrant project, would
print the CPU and memory utilization directly to the console:
```
CPU: 4.20%, Memory: 11.00%
```

216
website/pages/docs/cli/box.html.md Normal file
View File

@ -0,0 +1,216 @@
---
layout: 'docs'
page_title: 'vagrant box - Command-Line Interface'
sidebar_current: 'cli-box'
description: |-
The "vagrant box" command is used to manage "vagrant box add", "vagrant box
remove", and other box-related commands such as "outdated", "list", and
"update".
---
# Box
**Command: `vagrant box`**
This is the command used to manage (add, remove, etc.) [boxes](/docs/boxes.html).
The main functionality of this command is exposed via even more subcommands:
- [`add`](#box-add)
- [`list`](#box-list)
- [`outdated`](#box-outdated)
- [`prune`](#box-prune)
- [`remove`](#box-remove)
- [`repackage`](#box-repackage)
- [`update`](#box-update)
# Box Add
**Command: `vagrant box add ADDRESS`**
This adds a box with the given address to Vagrant. The address can be
one of three things:
- A shorthand name from the
[public catalog of available Vagrant images](https://vagrantcloud.com/boxes/search),
such as "hashicorp/bionic64".
- File path or HTTP URL to a box in a [catalog](https://vagrantcloud.com/boxes/search).
For HTTP, basic authentication is supported and `http_proxy` environmental
variables are respected. HTTPS is also supported.
- URL directly a box file. In this case, you must specify a `--name` flag
(see below) and versioning/updates will not work.
If an error occurs during the download or the download is interrupted with
a Ctrl-C, then Vagrant will attempt to resume the download the next time it
is requested. Vagrant will only attempt to resume a download for 24 hours
after the initial download.
## Options
- `--box-version VALUE` - The version of the box you want to add. By default,
the latest version will be added. The value of this can be an exact version
number such as "1.2.3" or it can be a set of version constraints. A version
constraint looks like ">= 1.0, < 2.0".
- `--cacert CERTFILE` - The certificate for the CA used to verify the peer.
This should be used if the remote end does not use a standard root CA.
- `--capath CERTDIR` - The certificate directory for the CA used to verify the peer.
This should be used if the remote end does not use a standard root CA.
- `--cert CERTFILE` - A client certificate to use when downloading the box, if
necessary.
- `--clean` - If given, Vagrant will remove any old temporary files from
prior downloads of the same URL. This is useful if you do not want Vagrant
to resume a download from a previous point, perhaps because the contents
changed.
- `--force` - When present, the box will be downloaded and overwrite any
existing box with this name.
- `--insecure` - When present, SSL certificates will not be verified if the
URL is an HTTPS URL.
- `--provider PROVIDER` - If given, Vagrant will verify the box you are
adding is for the given provider. By default, Vagrant automatically
detects the proper provider to use.
## Options for direct box files
The options below only apply if you are adding a box file directly (when
you are not using a catalog).
- `--checksum VALUE` - A checksum for the box that is downloaded. If specified,
Vagrant will compare this checksum to what is actually downloaded and will
error if the checksums do not match. This is highly recommended since
box files are so large. If this is specified, `--checksum-type` must
also be specified. If you are downloading from a catalog, the checksum is
included within the catalog entry.
- `--checksum-type TYPE` - The type of checksum that `--checksum` is if it
is specified. Supported values are currently "md5", "sha1", "sha256",
"sha384", and "sha512".
- `--name VALUE` - Logical name for the box. This is the value that you
would put into `config.vm.box` in your Vagrantfile. When adding a box from
a catalog, the name is included in the catalog entry and does not have
to be specified.
<div class="alert alert-warning">
<strong>Checksums for versioned boxes or boxes from HashiCorp's Vagrant Cloud:</strong>
For boxes from HashiCorp's Vagrant Cloud, the checksums are embedded in the metadata
of the box. The metadata itself is served over TLS and its format is validated.
</div>
# Box List
**Command: `vagrant box list`**
This command lists all the boxes that are installed into Vagrant.
# Box Outdated
**Command: `vagrant box outdated`**
This command tells you whether or not the box you are using in
your current Vagrant environment is outdated. If the `--global` flag
is present, every installed box will be checked for updates.
This will show the latest version available for the specific provider type,
which may be different than the absolute latest version available.
Checking for updates involves refreshing the metadata associated with
a box. This generally requires an internet connection.
By default, if Vagrant has recently checked for a box that's out of date, it will
cache that answer and not look up another update for one hour. This cached value
can be ignored if the `--force` flag is used.
## Options
- `--force` - Check for updates for all installed boxes and ignore cache interval.
- `--global` - Check for updates for all installed boxes, not just the
boxes for the current Vagrant environment.
# Box Prune
**Command: `vagrant box prune`**
This command removes old versions of installed boxes. If the box is currently in use vagrant will ask for confirmation.
## Options
- `--provider PROVIDER` - The specific provider type for the boxes to destroy.
- `--dry-run` - Only print the boxes that would be removed.
- `--name NAME` - The specific box name to check for outdated versions.
- `--force` - Destroy without confirmation even when box is in use.
- `--keep-active-boxes` - When combined with `--force`, will keep boxes still actively in use.
# Box Remove
**Command: `vagrant box remove NAME`**
This command removes a box from Vagrant that matches the given name.
If a box has multiple providers, the exact provider must be specified
with the `--provider` flag. If a box has multiple versions, you can select
what versions to delete with the `--box-version` flag or remove all versions
with the `--all` flag.
## Options
- `--box-version VALUE` - Version of version constraints of the boxes to
remove. See documentation on this flag for `box add` for more details.
- `--all` - Remove all available versions of a box.
- `--force` - Forces removing the box even if an active Vagrant
environment is using it.
- `--provider VALUE` - The provider-specific box to remove with the given
name. This is only required if a box is backed by multiple providers.
If there is only a single provider, Vagrant will default to removing it.
# Box Repackage
**Command: `vagrant box repackage NAME PROVIDER VERSION`**
This command repackages the given box and puts it in the current
directory so you can redistribute it. The name, provider, and version
of the box can be retrieved using `vagrant box list`.
When you add a box, Vagrant unpacks it and stores it internally. The
original `*.box` file is not preserved. This command is useful for
reclaiming a `*.box` file from an installed Vagrant box.
# Box Update
**Command: `vagrant box update`**
This command updates the box for the current Vagrant environment if there
are updates available. The command can also update a specific box (outside
of an active Vagrant environment), by specifying the `--box` flag.
<small><i>Note that updating the box will not update an already-running Vagrant
machine. To reflect the changes in the box, you will have to destroy and
bring back up the Vagrant machine.</i></small>
If you just want to check if there are updates available, use the
`vagrant box outdated` command.
## Options
- `--box VALUE` - Name of a specific box to update. If this flag is not
specified, Vagrant will update the boxes for the active Vagrant
environment.
- `--provider VALUE` - When `--box` is present, this controls what
provider-specific box to update. This is not required unless the box has
multiple providers. Without the `--box` flag, this has no effect.

338
website/pages/docs/cli/cloud.html.md Normal file
View File

@ -0,0 +1,338 @@
---
layout: 'docs'
page_title: 'vagrant cloud - Command-Line Interface'
sidebar_current: 'cli-cloud'
description: |-
The "vagrant cloud" command can be used for taking actions against
Vagrant Cloud like searching or uploading a Vagrant Box
---
# Cloud
**Command: `vagrant cloud`**
This is the command used to manage anything related to [Vagrant Cloud](https://vagrantcloud.com).
The main functionality of this command is exposed via subcommands:
- [`auth`](#cloud-auth)
- [`box`](#cloud-box)
- [`provider`](#cloud-provider)
- [`publish`](#cloud-publish)
- [`search`](#cloud-search)
- [`version`](#cloud-version)
# Cloud Auth
**Command: `vagrant cloud auth`**
The `cloud auth` command is for handling all things related to authorization with
Vagrant Cloud.
- [`login`](#cloud-auth-login)
- [`logout`](#cloud-auth-logout)
- [`whoami`](#cloud-auth-whoami)
## Cloud Auth Login
**Command: `vagrant cloud auth login`**
The login command is used to authenticate with [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud)
server. Logging in is only necessary if you are accessing protected boxes.
**Logging in is not a requirement to use Vagrant.** The vast majority
of Vagrant does _not_ require a login. Only certain features such as protected
boxes.
The reference of available command-line flags to this command
is available below.
### Options
- `--check` - This will check if you are logged in. In addition to outputting
whether you are logged in or not, the command exit status will be 0 if you are
logged in, or 1 if you are not.
- `--logout` - This will log you out if you are logged in. If you are already
logged out, this command will do nothing. It is not an error to call this
command if you are already logged out.
- `--token` - This will set the Vagrant Cloud login token manually to the provided
string. It is assumed this token is a valid Vagrant Cloud access token.
### Examples
Securely authenticate to Vagrant Cloud using a username and password:
```text
$ vagrant cloud auth login
# ...
Vagrant Cloud username:
Vagrant Cloud password:
```
Check if the current user is authenticated:
```text
$ vagrant cloud auth login --check
You are already logged in.
```
Securely authenticate with Vagrant Cloud using a token:
```text
$ vagrant cloud auth login --token ABCD1234
The token was successfully saved.
```
## Cloud Auth Logout
**Command: `vagrant cloud auth logout`**
This will log you out if you are logged in. If you are already
logged out, this command will do nothing. It is not an error to call this
command if you are already logged out.
## Cloud Auth Whomi
**Command: `vagrant cloud auth whoami [TOKEN]`**
This command will validate your Vagrant Cloud token and will print the user who
it belongs to. If a token is passed in, it will attempt to validate it instead
of the token stored stored on disk.
# Cloud Box
**Command: `vagrant cloud box`**
The `cloud box` command is used to manage life cycle operations for all `box`
entities on Vagrant Cloud.
- [`create`](#cloud-box-create)
- [`delete`](#cloud-box-delete)
- [`show`](#cloud-box-show)
- [`update`](#cloud-box-update)
## Cloud Box Create
**Command: `vagrant cloud box create ORGANIZATION/BOX-NAME`**
The box create command is used to create a new box entry on Vagrant Cloud.
### Options
- `--description DESCRIPTION` - A full description of the box. Can be
formatted with Markdown.
- `--short-description DESCRIPTION` - A short summary of the box.
- `--private` - Will make the new box private (Public by default)
## Cloud Box Delete
**Command: `vagrant cloud box delete ORGANIZATION/BOX-NAME`**
The box delete command will _permanently_ delete the given box entry on Vagrant Cloud. Before
making the request, it will ask if you are sure you want to delete the box.
## Cloud Box Show
**Command: `vagrant cloud box show ORGANIZATION/BOX-NAME`**
The box show command will display information about the latest version for the given Vagrant box.
## Cloud Box Update
**Command: `vagrant cloud box update ORGANIZATION/BOX-NAME`**
The box update command will update an already created box on Vagrant Cloud with the given options.
### Options
- `--description DESCRIPTION` - A full description of the box. Can be
formatted with Markdown.
- `--short-description DESCRIPTION` - A short summary of the box.
- `--private` - Will make the new box private (Public by default)
# Cloud Provider
**Command: `vagrant cloud provider`**
The `cloud provider` command is used to manage the life cycle operations for all
`provider` entities on Vagrant Cloud.
- [`create`](#cloud-provider-create)
- [`delete`](#cloud-provider-delete)
- [`update`](#cloud-provider-update)
- [`upload`](#cloud-provider-upload)
## Cloud Provider Create
**Command: `vagrant cloud provider create ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]`**
The provider create command is used to create a new provider entry on Vagrant Cloud.
The `url` argument is expected to be a remote URL that Vagrant Cloud can use
to download the provider. If no `url` is specified, the provider entry can be updated
later with a url or the [upload](#cloud-provider-upload) command can be used to
upload a Vagrant [box file](/docs/boxes.html).
## Cloud Provider Delete
**Command: `vagrant cloud provider delete ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION`**
The provider delete command is used to delete a provider entry on Vagrant Cloud.
Before making the request, it will ask if you are sure you want to delete the provider.
## Cloud Provider Update
**Command: `vagrant cloud provider update ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]`**
The provider update command will update an already created provider for a box on
Vagrant Cloud with the given options.
## Cloud Provider Upload
**Command: `vagrant cloud provider upload ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION BOX-FILE`**
The provider upload command will upload a Vagrant [box file](/docs/boxes.html) to Vagrant Cloud for
the specified version and provider.
# Cloud Publish
**Command: `vagrant cloud publish ORGANIZATION/BOX-NAME VERSION PROVIDER-NAME [PROVIDER-FILE]`**
The publish command is a complete solution for creating and updating a
Vagrant box on Vagrant Cloud. Instead of having to create each attribute of a Vagrant
box with separate commands, the publish command instead asks you to provide all
the information required before creating or updating a new box.
## Options
- `--box-version VERSION` - Version to create for the box
- `--description DESCRIPTION` - A full description of the box. Can be
formatted with Markdown.
- `--force` - Disables confirmation when creating or updating a box.
- `--short-description DESCRIPTION` - A short summary of the box.
- `--private` - Will make the new box private (Public by default)
- `--release` - Automatically releases the box after creation (Unreleased by default)
- `--url` - Valid remote URL to download the box file
- `--version-description DESCRIPTION` - Description of the version that will be created.
## Examples
Creating a new box on Vagrant Cloud:
```text
$ vagrant cloud publish briancain/supertest 1.0.0 virtualbox boxes/my/virtualbox.box -d "A really cool box to download and use" --version-description "A cool version" --release --short-description "Download me!"
You are about to create a box on Vagrant Cloud with the following options:
briancain/supertest (1.0.0) for virtualbox
Automatic Release: true
Box Description: A really cool box to download and use
Box Short Description: Download me!
Version Description: A cool version
Do you wish to continue? [y/N] y
Creating a box entry...
Creating a version entry...
Creating a provider entry...
Uploading provider with file /Users/vagrant/boxes/my/virtualbox.box
Releasing box...
Complete! Published briancain/supertest
tag: briancain/supertest
username: briancain
name: supertest
private: false
downloads: 0
created_at: 2018-07-25T17:53:04.340Z
updated_at: 2018-07-25T18:01:10.665Z
short_description: Download me!
description_markdown: A really cool box to download and use
current_version: 1.0.0
providers: virtualbox
```
# Cloud Search
**Command: `vagrant cloud search QUERY`**
The cloud search command will take a query and search Vagrant Cloud for any matching
Vagrant boxes. Various filters can be applied to the results.
## Options
- `--json` - Format search results in JSON.
- `--page PAGE` - The page to display. Defaults to the first page of results.
- `--short` - Shows a simple list of box names for the results.
- `--order ORDER` - Order to display results. Can either be `desc` or `asc`.
Defaults to `desc`.
- `--limit LIMIT` - Max number of search results to display. Defaults to 25.
- `--provider PROVIDER` - Filter search results to a single provider.
- `--sort-by SORT` - The field to sort results on. Can be `created`, `downloads`
, or `updated`. Defaults to `downloads`.
## Examples
If you are looking for a HashiCorp box:
```text
vagrant cloud search hashicorp --limit 5
| NAME | VERSION | DOWNLOADS | PROVIDERS |
+-------------------------+---------+-----------+---------------------------------+
| hashicorp/precise64 | 1.1.0 | 6,675,725 | virtualbox,vmware_fusion,hyperv |
| hashicorp/precise32 | 1.0.0 | 2,261,377 | virtualbox |
| hashicorp/boot2docker | 1.7.8 | 59,284 | vmware_desktop,virtualbox |
| hashicorp/connect-vm | 0.1.0 | 6,912 | vmware_desktop,virtualbox |
| hashicorp/vagrant-share | 0.1.0 | 3,488 | vmware_desktop,virtualbox |
+-------------------------+---------+-----------+---------------------------------+
```
# Cloud Version
**Command: `vagrant cloud version`**
The `cloud version` command is used to manage life cycle operations for all `version`
entities for a box on Vagrant Cloud.
- [`create`](#cloud-version-create)
- [`delete`](#cloud-version-delete)
- [`release`](#cloud-version-release)
- [`revoke`](#cloud-version-revoke)
- [`update`](#cloud-version-update)
## Cloud Version Create
**Command: `vagrant cloud version create ORGANIZATION/BOX-NAME VERSION`**
The cloud create command creates a version entry for a box on Vagrant Cloud.
### Options
- `--description DESCRIPTION` - Description of the version that will be created.
## Cloud Version Delete
**Command: `vagrant cloud version delete ORGANIZATION/BOX-NAME VERSION`**
The cloud delete command deletes a version entry for a box on Vagrant Cloud.
Before making the request, it will ask if you are sure you want to delete the version.
## Cloud Version Release
**Command: `vagrant cloud version release ORGANIZATION/BOX-NAME VERSION`**
The cloud release command releases a version entry for a box on Vagrant Cloud
if it already exists. Before making the request, it will ask if you are sure you
want to release the version.
## Cloud Version Revoke
**Command: `vagrant cloud version revoke ORGANIZATION/BOX-NAME VERSION`**
The cloud revoke command revokes a version entry for a box on Vagrant Cloud
if it already exists. Before making the request, it will ask if you are sure you
want to revoke the version.
## Cloud Version Update
**Command: `vagrant cloud version update ORGANIZATION/BOX-NAME VERSION`**
### Options
- `--description DESCRIPTION` - Description of the version that will be created.

34
website/pages/docs/cli/connect.html.md Normal file
View File

@ -0,0 +1,34 @@
---
layout: 'docs'
page_title: 'vagrant connect - Command-Line Interface'
sidebar_current: 'cli-connect'
description: |-
The "vagrant connect" command compliments the "vagrant share" command to allow
a user to remotely connect to your Vagrant environment.
---
# Connect
**Command: `vagrant connect NAME`**
The connect command complements the
[share command](/docs/cli/share.html) by enabling access to shared
environments. You can learn about all the details of Vagrant Share in the
[Vagrant Share section](/docs/share/).
The reference of available command-line flags to this command
is available below.
## Options
- `--disable-static-ip` - The connect command will not spin up a small
virtual machine to create a static IP you can access. When this flag is
set, the only way to access the connection is to use the SOCKS proxy
address outputted.
- `--static-ip IP` - Tells connect what static IP address to use for the virtual
machine. By default, Vagrant connect will use an IP address that looks
available in the 172.16.0.0/16 space.
- `--ssh` - Connects via SSH to an environment shared with
`vagrant share --ssh`.

42
website/pages/docs/cli/destroy.html.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: 'docs'
page_title: 'vagrant destroy - Command-Line Interface'
sidebar_current: 'cli-destroy'
description: |-
The "vagrant destroy" command is used to stop the running virtual machine and
terminate use of all resources that were in use by that machine.
---
# Destroy
**Command: `vagrant destroy [name|id]`**
This command stops the running machine Vagrant is managing and
destroys all resources that were created during the machine creation process.
After running this command, your computer should be left at a clean state,
as if you never created the guest machine in the first place.
For linux-based guests, Vagrant uses the `shutdown` command to gracefully
terminate the machine. Due to the varying nature of operating systems, the
`shutdown` command may exist at many different locations in the guest's `$PATH`.
It is the guest machine's responsibility to properly populate the `$PATH` with
directory containing the `shutdown` command.
## Options
- `-f` or `--force` - Do not ask for confirmation before destroying.
- `--[no-]parallel` - Destroys multiple machines in parallel if the provider
supports it. Please consult the provider documentation to see if this feature
is supported.
<div class="alert alert-info">
The `destroy` command does not remove a box that may have been installed on
your computer during `vagrant up`. Thus, even if you run `vagrant destroy`,
the box installed in the system will still be present on the hard drive. To
return your computer to the state as it was before `vagrant up` command, you
need to use `vagrant box remove`.
For more information, read about the
<a href="/docs/cli/box.html">`vagrant box remove`</a> command.
</div>

39
website/pages/docs/cli/global-status.html.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: 'docs'
page_title: 'vagrant global-status - Command-Line Interface'
sidebar_current: 'cli-globalstatus'
description: |-
The "vagrant global-status" command is used to determine the state of all
active Vagrant environments on the system for the currently logged in user.
---
# Global Status
**Command: `vagrant global-status`**
This command will tell you the state of all active Vagrant environments
on the system for the currently logged in user.
~> **This command does not actively verify the state of machines**,
and is instead based on a cache. Because of this, it is possible to see
stale results (machines say they're running but they're not). For example,
if you restart your computer, Vagrant would not know. To prune the invalid
entries, run global status with the `--prune` flag.
The IDs in the output that look like `a1b2c3` can be used to control
the Vagrant machine from anywhere on the system. Any Vagrant command
that takes a target machine (such as `up`, `halt`, `destroy`) can be
used with this ID to control it. For example: `vagrant destroy a1b2c3`.
## Options
- `--prune` - Prunes invalid entries from the list. This is much more time
consuming than simply listing the entries.
## Environment Not Showing Up
If your environment is not showing up, you may have to do a `vagrant destroy`
followed by a `vagrant up`.
If you just upgraded from a previous version of Vagrant, existing environments
will not show up in global-status until they are destroyed and recreated.

29
website/pages/docs/cli/halt.html.md Normal file
View File

@ -0,0 +1,29 @@
---
layout: 'docs'
page_title: 'vagrant halt - Command-Line Interface'
sidebar_current: 'cli-halt'
description: |-
The "vagrant halt" command is used to shut down the virtual machine that
Vagrant is currently managing.
---
# Halt
**Command: `vagrant halt [name|id]`**
This command shuts down the running machine Vagrant is managing.
Vagrant will first attempt to gracefully shut down the machine by running
the guest OS shutdown mechanism. If this fails, or if the `--force` flag is
specified, Vagrant will effectively just shut off power to the machine.
For linux-based guests, Vagrant uses the `shutdown` command to gracefully
terminate the machine. Due to the varying nature of operating systems, the
`shutdown` command may exist at many different locations in the guest's `$PATH`.
It is the guest machine's responsibility to properly populate the `$PATH` with
directory containing the `shutdown` command.
## Options
- `-f` or `--force` - Do not attempt to gracefully shut down the machine.
This effectively pulls the power on the guest machine.

32
website/pages/docs/cli/index.html.md Normal file
View File

@ -0,0 +1,32 @@
---
layout: 'docs'
page_title: 'Command-Line Interface'
sidebar_current: 'cli'
description: |-
Almost all interaction with Vagrant is done via the command-line interface.
---
# Command-Line Interface
Almost all interaction with Vagrant is done through the command-line
interface.
The interface is available using the `vagrant` command, and comes installed
with Vagrant automatically. The `vagrant` command in turn has many subcommands,
such as `vagrant up`, `vagrant destroy`, etc.
If you run `vagrant` by itself, help will be displayed showing all available
subcommands. In addition to this, you can run any Vagrant command with the
`-h` flag to output help about that specific command. For example, try
running `vagrant init -h`. The help will output a one sentence synopsis of
what the command does as well as a list of all the flags the command
accepts.
In depth documentation and use cases of various Vagrant commands is
available by reading the appropriate sub-section available in the left
navigational area of this site.
You may also wish to consult the
[documentation](/docs/other/environmental-variables.html) regarding the
environmental variables that can be used to configure and control
Vagrant in a global way.

71
website/pages/docs/cli/init.html.md Normal file
View File

@ -0,0 +1,71 @@
---
layout: 'docs'
page_title: 'vagrant init - Command-Line Interface'
sidebar_current: 'cli-init'
description: |-
The "vagrant init" command is used to initialize the current directory to be
a Vagrant environment by creating an initial Vagrantfile.
---
# Init
**Command: `vagrant init [name [url]]`**
This initializes the current directory to be a Vagrant environment
by creating an initial [Vagrantfile](/docs/vagrantfile/) if
one does not already exist.
If a first argument is given, it will prepopulate the `config.vm.box`
setting in the created Vagrantfile.
If a second argument is given, it will prepopulate the `config.vm.box_url`
setting in the created Vagrantfile.
## Options
- `--box-version` - (Optional) The box version or box version constraint to add
to the `Vagrantfile`.
- `--force` - If specified, this command will overwrite any existing
`Vagrantfile`.
- `--minimal` - If specified, a minimal Vagrantfile will be created. This
Vagrantfile does not contain the instructional comments that the normal
Vagrantfile contains.
- `--output FILE` - This will output the Vagrantfile to the given file.
If this is "-", the Vagrantfile will be sent to stdout.
- `--template FILE` - Provide a custom ERB template for generating the Vagrantfile.
## Examples
Create a base Vagrantfile:
```sh
$ vagrant init hashicorp/bionic64
```
Create a minimal Vagrantfile (no comments or helpers):
```sh
$ vagrant init -m hashicorp/bionic64
```
Create a new Vagrantfile, overwriting the one at the current path:
```sh
$ vagrant init -f hashicorp/bionic64
```
Create a Vagrantfile with the specific box, from the specific box URL:
```sh
$ vagrant init my-company-box https://boxes.company.com/my-company.box
```
Create a Vagrantfile, locking the box to a version constraint:
```sh
$ vagrant init --box-version '> 0.1.5' hashicorp/bionic64
```

62
website/pages/docs/cli/login.html.md Normal file
View File

@ -0,0 +1,62 @@
---
layout: 'docs'
page_title: 'vagrant login - Command-Line Interface'
sidebar_current: 'cli-login'
description: |-
The "vagrant login" command is used to authenticate Vagrant with HashiCorp's
Vagrant Cloud service to use features like private boxes and "vagrant push".
---
# Login
**Command: `vagrant login`**
The login command is used to authenticate with the
[HashiCorp's Vagrant Cloud](/docs/vagrant-cloud) server. Logging in is only
necessary if you are accessing protected boxes or using
[Vagrant Share](/docs/share/).
**Logging in is not a requirement to use Vagrant.** The vast majority
of Vagrant does _not_ require a login. Only certain features such as protected
boxes or [Vagrant Share](/docs/share/) require a login.
The reference of available command-line flags to this command
is available below.
## Options
- `--check` - This will check if you are logged in. In addition to outputting
whether you are logged in or not, the command will have exit status 0 if you are
logged in, and exit status 1 if you are not.
- `--logout` - This will log you out if you are logged in. If you are already
logged out, this command will do nothing. It is not an error to call this
command if you are already logged out.
- `--token` - This will set the Vagrant Cloud login token manually to the provided
string. It is assumed this token is a valid Vagrant Cloud access token.
## Examples
Securely authenticate to Vagrant Cloud using a username and password:
```text
$ vagrant login
# ...
Vagrant Cloud username:
Vagrant Cloud password:
```
Check if the current user is authenticated:
```text
$ vagrant login --check
You are already logged in.
```
Securely authenticate with Vagrant Cloud using a token:
```text
$ vagrant login --token ABCD1234
The token was successfully saved.
```

162
website/pages/docs/cli/machine-readable.html.md Normal file
View File

@ -0,0 +1,162 @@
---
layout: 'docs'
page_title: 'Machine Readable Output - Command-Line Interface'
sidebar_current: 'cli-machinereadable'
description: |-
Almost all commands in Vagrant accept a --machine-readable flag to enable
machine-readable output mode.
---
# Machine Readable Output
Every Vagrant command accepts a `--machine-readable` flag which enables
machine readable output mode. In this mode, the output to the terminal
is replaced with machine-friendly output.
This mode makes it easy to programmatically execute Vagrant and read data
out of it. This output format is protected by our
[backwards compatibility](/docs/installation/backwards-compatibility.html)
policy. Until Vagrant 2.0 is released, however, the machine readable output
may change as we determine more use cases for it. But the backwards
compatibility promise should make it safe to write client libraries to
parse the output format.
<div class="alert alert-warning">
<strong>Advanced topic!</strong> This is an advanced topic for use only if
you want to programmatically execute Vagrant. If you are just getting started
with Vagrant, you may safely skip this section.
</div>
## Work-In-Progress
The machine-readable output is very new (released as part of Vagrant 1.4).
We're still gathering use cases for it and building up the output for each
of the commands. It is likely that what you may want to achieve with
the machine-readable output is not possible due to missing information.
In this case, we ask that you please
[open an issue](https://github.com/hashicorp/vagrant/issues)
requesting that certain information become available. We will most likely add
it!
## Format
The machine readable format is a line-oriented, comma-delimited text format.
This makes it extremely easy to parse using standard Unix tools such as awk or
grep in addition to full programming languages like Ruby or Python.
The format is:
```
timestamp,target,type,data...
```
Each component is explained below:
- **timestamp** is a Unix timestamp in UTC of when the message was printed.
- **target** is the target of the following output. This is empty if the
message is related to Vagrant globally. Otherwise, this is generally a machine
name so you can relate output to a specific machine when multi-VM is in use.
- **type** is the type of machine-readable message being outputted. There are
a set of standard types which are covered later.
- **data** is zero or more comma-separated values associated with the prior
type. The exact amount and meaning of this data is type-dependent, so you
must read the documentation associated with the type to understand fully.
Within the format, if data contains a comma, it is replaced with
`%!(VAGRANT_COMMA)`. This was preferred over an escape character such as \'
because it is more friendly to tools like awk.
Newlines within the format are replaced with their respective standard escape
sequence. Newlines become a literal `\n` within the output. Carriage returns
become a literal `\r`.
## Types
This section documents all the available types that may be outputted
with the machine-readable output.
<table class="table table-hover table-bordered mr-types">
<thead>
<tr>
<th class="mr-type">Type</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td>box-name</td>
<td>
Name of a box installed into Vagrant.
</td>
</tr>
<tr>
<td>box-provider</td>
<td>
Provider for an installed box.
</td>
</tr>
<tr>
<td>cli-command</td>
<td>
A subcommand of <code>vagrant</code> that is available.
</td>
</tr>
<tr>
<td>error-exit</td>
<td>
An error occurred that caused Vagrant to exit. This contains that
error. Contains two data elements: type of error, error message.
</td>
</tr>
<tr>
<td>provider-name</td>
<td>
The provider name of the target machine.
<span class="label">targeted</span>
</td>
</tr>
<tr>
<td>ssh-config</td>
<td>
The OpenSSH compatible SSH config for a machine. This is usually
the result of the "ssh-config" command.
<span class="label">targeted</span>
</td>
</tr>
<tr>
<td>state</td>
<td>
The state ID of the target machine.
<span class="label">targeted</span>
</td>
</tr>
<tr>
<td>state-human-long</td>
<td>
Human-readable description of the state of the machine. This is the
long version, and may be a paragraph or longer.
<span class="label">targeted</span>
</td>
</tr>
<tr>
<td>state-human-short</td>
<td>
Human-readable description of the state of the machine. This is the
short version, limited to at most a sentence.
<span class="label">targeted</span>
</td>
</tr>
</table>

34
website/pages/docs/cli/non-primary.html.md Normal file
View File

@ -0,0 +1,34 @@
---
layout: 'docs'
page_title: 'More Vagrant Commands - Command-Line Interface'
sidebar_current: 'cli-nonprimary'
description: |-
In addition to the commands listed in the sidebar and shown in "vagrant -h",
Vagrant comes with some more commands that are hidden from basic help output.
These commands are hidden because they're not useful to beginners or they're
not commonly used. We call these commands "non-primary subcommands".
---
# More Commands
In addition to the commands listed in the sidebar and shown in `vagrant -h`,
Vagrant comes with some more commands that are hidden from basic help output.
These commands are hidden because they're not useful to beginners or they're
not commonly used. We call these commands "non-primary subcommands".
You can view all subcommands, including the non-primary subcommands,
by running `vagrant list-commands`, which itself is a non-primary subcommand!
Note that while you have to run a special command to list the non-primary
subcommands, you do not have to do anything special to actually _run_ the
non-primary subcommands. They're executed just like any other subcommand:
`vagrant COMMAND`.
The list of non-primary commands is below. Click on any command to learn
more about it.
- [docker-exec](/docs/docker/commands.html)
- [docker-logs](/docs/docker/commands.html)
- [docker-run](/docs/docker/commands.html)
- [rsync](/docs/cli/rsync.html)
- [rsync-auto](/docs/cli/rsync-auto.html)

44
website/pages/docs/cli/package.html.md Normal file
View File

@ -0,0 +1,44 @@
---
layout: 'docs'
page_title: 'vagrant package - Command-Line Interface'
sidebar_current: 'cli-package'
description: |-
The "vagrant package" command is used to package a currently-running
VirtualBox or Hyper-V vagrant environment into a reusable Vagrant box.
---
# Package
**Command: `vagrant package [name|id]`**
This packages a currently running _VirtualBox_ or _Hyper-V_ environment into a
re-usable [box](/docs/boxes.html). This command can only be used with
other [providers](/docs/providers/) based on the provider implementation
and if the provider supports it.
## Options
- `--base NAME` - Instead of packaging a VirtualBox machine that Vagrant
manages, this will package a VirtualBox machine that VirtualBox manages.
`NAME` should be the name or UUID of the machine from the VirtualBox GUI.
Currently this option is only available for VirtualBox.
- `--output NAME` - The resulting package will be saved as `NAME`. By default,
it will be saved as `package.box`.
- `--include x,y,z` - Additional files will be packaged with the box. These
can be used by a packaged Vagrantfile (documented below) to perform additional
tasks.
- `--vagrantfile FILE` - Packages a Vagrantfile with the box, that is loaded
as part of the [Vagrantfile load order](/docs/vagrantfile/#load-order)
when the resulting box is used.
<div class="alert alert-info">
<strong>A common misconception</strong> is that the <code>--vagrantfile</code>
option will package a Vagrantfile that is used when <code>vagrant init</code>
is used with this box. This is not the case. Instead, a Vagrantfile
is loaded and read as part of the Vagrant load process when the box is
used. For more information, read about the
<a href="/docs/vagrantfile/#load-order">Vagrantfile load order</a>.
</div>

165
website/pages/docs/cli/plugin.html.md Normal file
View File

@ -0,0 +1,165 @@
---
layout: 'docs'
page_title: 'vagrant plugin - Command-Line Interface'
sidebar_current: 'cli-plugin'
description: |-
The "vagrant plugin" command is used to manage Vagrant plugins including
installing, uninstalling, and license management.
---
# Plugin
**Command: `vagrant plugin`**
This is the command used to manage [plugins](/docs/plugins/).
The main functionality of this command is exposed via another level
of subcommands:
- [`expunge`](#plugin-expunge)
- [`install`](#plugin-install)
- [`license`](#plugin-license)
- [`list`](#plugin-list)
- [`repair`](#plugin-repair)
- [`uninstall`](#plugin-uninstall)
- [`update`](#plugin-update)
# Plugin Expunge
**Command: `vagrant plugin expunge`**
This removes all user installed plugin information. All plugin gems, their
dependencies, and the `plugins.json` file are removed. This command
provides a simple mechanism to fully remove all user installed custom plugins.
When upgrading Vagrant it may be required to reinstall plugins due to
an internal incompatibility. The expunge command can help make that process
easier by attempting to automatically reinstall currently configured
plugins:
```shell
# Delete all plugins and reinstall
$ vagrant plugin expunge --reinstall
```
This command accepts optional command-line flags:
- `--force` - Do not prompt for confirmation prior to removal
- `--global-only` - Only expunge global plugins
- `--local` - Include plugins in local project
- `--local-only` - Only expunge local project plugins
- `--reinstall` - Attempt to reinstall plugins after removal
# Plugin Install
**Command: `vagrant plugin install <name>...`**
This installs a plugin with the given name or file path. If the name
is not a path to a file, then the plugin is installed from remote
repositories, usually [RubyGems](https://rubygems.org). This command will
also update a plugin if it is already installed, but you can also use
`vagrant plugin update` for that.
```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
```
If multiple names are specified, multiple plugins will be installed. If
flags are given below, the flags will apply to _all_ plugins being installed
by the current command invocation.
If the plugin is already installed, this command will reinstall it with
the latest version available.
This command accepts optional command-line flags:
- `--entry-point ENTRYPOINT` - By default, installed plugins are loaded
internally by loading an initialization file of the same name as the plugin.
Most of the time, this is correct. If the plugin you are installing has
another entrypoint, this flag can be used to specify it.
- `--local` - Install plugin to the local Vagrant project only.
- `--plugin-clean-sources` - Clears all sources that have been defined so
far. This is an advanced feature. The use case is primarily for corporate
firewalls that prevent access to RubyGems.org.
- `--plugin-source SOURCE` - Adds a source from which to fetch a plugin. Note
that this does not only affect the single plugin being installed, by all future
plugin as well. This is a limitation of the underlying plugin installer
Vagrant uses.
- `--plugin-version VERSION` - The version of the plugin to install. By default,
this command will install the latest version. You can constrain the version
using this flag. You can set it to a specific version, such as "1.2.3" or
you can set it to a version constraint, such as "> 1.0.2". You can set it
to a more complex constraint by comma-separating multiple constraints:
"> 1.0.2, < 1.1.0" (do not forget to quote these on the command-line).
# Plugin License
**Command: `vagrant plugin license <name> <license-file>`**
This command installs a license for a proprietary Vagrant plugin,
such as the [VMware Fusion provider](/docs/vmware).
# Plugin List
**Command: `vagrant plugin list`**
This lists all installed plugins and their respective installed versions.
If a version constraint was specified for a plugin when installing it, the
constraint will be listed as well. Other plugin-specific information may
be shown, too.
This command accepts optional command-line flags:
- `--local` - Include local project plugins.
# Plugin Repair
Vagrant may fail to properly initialize user installed custom plugins. This can
be caused my improper plugin installation/removal, or by manual manipulation of
plugin related files like the `plugins.json` data file. Vagrant can attempt
to automatically repair the problem.
If automatic repair is not successful, refer to the [expunge](#plugin-expunge)
command
This command accepts optional command-line flags:
- `--local` - Repair local project plugins.
# Plugin Uninstall
**Command: `vagrant plugin uninstall <name> [<name2> <name3> ...]`**
This uninstalls the plugin with the given name. Any dependencies of the
plugin will also be uninstalled assuming no other plugin needs them.
If multiple plugins are given, multiple plugins will be uninstalled.
This command accepts optional command-line flags:
- `--local` - Uninstall plugin from local project.
# Plugin Update
**Command: `vagrant plugin update [<name>]`**
This updates the plugins that are installed within Vagrant. If you specified
version constraints when installing the plugin, this command will respect
those constraints. If you want to change a version constraint, re-install
the plugin using `vagrant plugin install`.
If a name is specified, only that single plugin will be updated. If a
name is specified of a plugin that is not installed, this command will not
install it.
This command accepts optional command-line flags:
- `--local` - Update plugin from local project.

39
website/pages/docs/cli/port.html.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: 'docs'
page_title: 'vagrant port - Command-Line Interface'
sidebar_current: 'cli-port'
description: |-
The "vagrant port" command is used to display the full list of guest ports
mapped to the host machine ports.
---
# Port
**Command: `vagrant port [name|id]`**
The port command displays the full list of guest ports mapped to the host
machine ports:
```
$ vagrant port
22 (guest) => 2222 (host)
80 (guest) => 8080 (host)
```
In a multi-machine Vagrantfile, the name of the machine must be specified:
```
$ vagrant port my-machine
```
## Options
- `--guest PORT` - This displays just the host port that corresponds to the
given guest port. If the guest is not forwarding that port, an error is
returned. This is useful for quick scripting, for example:
$ ssh -p $(vagrant port --guest 22)
- `--machine-readable` - This tells Vagrant to display machine-readable output
instead of the human-friendly output. More information is available in the
[machine-readable output](/docs/cli/machine-readable.html) documentation.

23
website/pages/docs/cli/powershell.html.md Normal file
View File

@ -0,0 +1,23 @@
---
layout: 'docs'
page_title: 'vagrant powershell - Command-Line Interface'
sidebar_current: 'cli-powershell'
description: |-
The "vagrant powershell" command is used to open a powershell prompt running
inside the guest machine.
---
# PowerShell
**Command: `vagrant powershell`**
This will open a PowerShell prompt on the host into a running Vagrant guest machine.
This command will only work if the machines supports PowerShell. Not every
environment will support PowerShell. At the moment, only Windows is supported
with this command.
## Options
- `-c COMMAND` or `--command COMMAND` - This executes a single PowerShell command,
prints out the stdout and stderr, and exits.

28
website/pages/docs/cli/provision.html.md Normal file
View File

@ -0,0 +1,28 @@
---
layout: 'docs'
page_title: 'vagrant provision - Command-Line Interface'
sidebar_current: 'cli-provision'
description: |-
The "vagrant provision" command is used to run any provisioners configured
for the guest machine, such as Puppet, Chef, Ansible, Salt, or Shell.
---
# Provision
**Command: `vagrant provision [vm-name]`**
Runs any configured [provisioners](/docs/provisioning/)
against the running Vagrant managed machine.
This command is a great way to quickly test any provisioners, and is especially
useful for incremental development of shell scripts, Chef cookbooks, or Puppet
modules. You can just make simple modifications to the provisioning scripts
on your machine, run a `vagrant provision`, and check for the desired results.
Rinse and repeat.
# Options
- `--provision-with x,y,z` - This will only run the given provisioners. For
example, if you have a `:shell` and `:chef_solo` provisioner and run
`vagrant provision --provision-with shell`, only the shell provisioner will
be run.

42
website/pages/docs/cli/rdp.html.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: 'docs'
page_title: 'vagrant rdp - Command-Line Interface'
sidebar_current: 'cli-rdp'
description: |-
The "vagrant rdp" command is used to start an RDP client for a remote desktop
session with the guest machine.
---
# RDP
**Command: `vagrant rdp`**
This will start an RDP client for a remote desktop session with the
guest. This only works for Vagrant environments that support remote
desktop, which is typically only Windows.
## Raw Arguments
You can pass raw arguments through to your RDP client on the
command-line by appending it after a `--`. Vagrant just passes
these through. For example:
```
$ vagrant rdp -- /span
```
The above command on Windows will execute `mstsc.exe /span config.rdp`,
allowing your RDP to span multiple desktops.
On Darwin hosts, such as Mac OS X, the additional arguments are added to the
generated RDP configuration file. Since these files can contain multiple options
with different spacing, you _must_ quote multiple arguments. For example:
```
$ vagrant rdp -- "screen mode id:i:0" "other config:s:value"
```
Note that as of the publishing of this guide, the Microsoft RDP Client for Mac
does _not_ perform validation on the configuration file. This means if you
specify an invalid configuration option or make a typographical error, the
client will silently ignore the error and continue!

31
website/pages/docs/cli/reload.html.md Normal file
View File

@ -0,0 +1,31 @@
---
layout: 'docs'
page_title: 'vagrant reload - Command-Line Interface'
sidebar_current: 'cli-reload'
description: |-
The "vagrant reload" command is the equivalent of running "vagrant halt"
followed by "vagrant up".
---
# Reload
**Command: `vagrant reload [name|id]`**
The equivalent of running a [halt](/docs/cli/halt.html) followed by an
[up](/docs/cli/up.html).
This command is usually required for changes made in the Vagrantfile to
take effect. After making any modifications to the Vagrantfile, a `reload`
should be called.
The configured provisioners will not run again, by default. You can force
the provisioners to re-run by specifying the `--provision` flag.
# Options
- `--provision` - Force the provisioners to run.
- `--provision-with x,y,z` - This will only run the given provisioners. For
example, if you have a `:shell` and `:chef_solo` provisioner and run
`vagrant reload --provision-with shell`, only the shell provisioner will
be run.

28
website/pages/docs/cli/resume.html.md Normal file
View File

@ -0,0 +1,28 @@
---
layout: 'docs'
page_title: 'vagrant resume - Command-Line Interface'
sidebar_current: 'cli-resume'
description: |-
The "vagrant resume" command is used to bring a machine back into the "up"
state, perhaps if it was previously suspended via "vagrant halt" or "vagrant
suspend".
---
# Resume
**Command: `vagrant resume [name|id]`**
This resumes a Vagrant managed machine that was previously suspended,
perhaps with the [suspend command](/docs/cli/suspend.html).
The configured provisioners will not run again, by default. You can force
the provisioners to re-run by specifying the `--provision` flag.
# Options
- `--provision` - Force the provisioners to run.
- `--provision-with x,y,z` - This will only run the given provisioners. For
example, if you have a `:shell` and `:chef_solo` provisioner and run
`vagrant provision --provision-with shell`, only the shell provisioner will
be run.

56
website/pages/docs/cli/rsync-auto.html.md Normal file
View File

@ -0,0 +1,56 @@
---
layout: 'docs'
page_title: 'vagrant rsync-auto - Command-Line Interface'
sidebar_current: 'cli-rsyncauto'
description: |-
The "vagrant rsync-auto" command watches all local directories of any rsync
configured synced folders and automatically initiates an rsync transfer when
changes are detected.
---
# rsync-auto
**Command: `vagrant rsync-auto`**
This command watches all local directories of any
[rsync synced folders](/docs/synced-folders/rsync.html) and automatically
initiates an rsync transfer when changes are detected. This command does
not exit until an interrupt is received.
The change detection is optimized to use platform-specific APIs to listen
for filesystem changes, and does not simply poll the directory.
## Options
- `--[no-]rsync-chown` - Use rsync to modify ownership of transferred files. Enabling
this option can result in faster completion due to a secondary process not being
required to update ownership. By default this is disabled.
- `--[no-]poll` - Force Vagrant to watch for changes using filesystem
polling instead of filesystem events. This is required for some filesystems
that do not support events. Warning: enabling this will make `rsync-auto`
_much_ slower. By default, polling is disabled.
## Machine State Changes
The `rsync-auto` command does not currently handle machine state changes
gracefully. For example, if you start the `rsync-auto` command, then
halt the guest machine, then make changes to some files, then boot it
back up, `rsync-auto` will not attempt to resync.
To ensure that the command works properly, you should start `rsync-auto`
only when the machine is running, and shut it down before any machine
state changes.
You can always force a resync with the [rsync](/docs/cli/rsync.html) command.
## Vagrantfile Changes
If you change or move your Vagrantfile, the `rsync-auto` command will have
to be restarted. For example, if you add synced folders to the Vagrantfile,
or move the directory that contains the Vagrantfile, the `rsync-auto`
command will either not pick up the changes or may begin experiencing
strange behavior.
Before making any such changes, it is recommended that you turn off
`rsync-auto`, then restart it afterwards.

24
website/pages/docs/cli/rsync.html.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: 'docs'
page_title: 'vagrant rsync - Command-Line Interface'
sidebar_current: 'cli-rsync'
description: |-
The "vagrant rsync" command forces a re-sync of any rsync synced folders.
---
# Rsync
**Command: `vagrant rsync`**
This command forces a re-sync of any
[rsync synced folders](/docs/synced-folders/rsync.html).
Note that if you change any settings within the rsync synced folders such
as exclude paths, you will need to `vagrant reload` before this command will
pick up those changes.
## Options
- `--[no-]rsync-chown` - Use rsync to modify ownership of transferred files. Enabling
this option can result in faster completion due to a secondary process not being
required to update ownership. By default this is disabled.

49
website/pages/docs/cli/share.html.md Normal file
View File

@ -0,0 +1,49 @@
---
layout: 'docs'
page_title: 'vagrant share - Command-Line Interface'
sidebar_current: 'cli-share'
description: |-
The "vagrant share" command initializes a new Vagrant share session, which
allows you to share your virtual machine with the public Internet.
---
# Share
**Command: `vagrant share`**
The share command initializes a Vagrant Share session, allowing you to
share your Vagrant environment with anyone in the world, enabling collaboration
directly in your Vagrant environment in almost any network environment.
You can learn about all the details of Vagrant Share in the
[Vagrant Share section](/docs/share/).
The reference of available command-line flags to this command
is available below.
## Options
- `--disable-http` - Disables the creation of a publicly accessible
HTTP endpoint to your Vagrant environment. With this set, the only way
to access your share is with `vagrant connect`.
- `--http PORT` - The port of the HTTP server running in the Vagrant
environment. By default, Vagrant will attempt to find this for you.
This has no effect if `--disable-http` is set.
- `--https PORT` - The port of an HTTPS server running in the Vagrant
environment. By default, Vagrant will attempt to find this for you.
This has no effect if `--disable-http` is set.
- `--ssh` - Enables SSH sharing (more information below). By default, this
is not enabled.
- `--ssh-no-password` - Disables the encryption of the SSH keypair created
when SSH sharing is enabled.
- `--ssh-port PORT` - The port of the SSH server running in the Vagrant
environment. By default, Vagrant will attempt to find this for you.
- `--ssh-once` - Allows SSH access only once. After the first attempt to
connect via SSH to the Vagrant environment, the generated keypair is
destroyed.

98
website/pages/docs/cli/snapshot.html.md Normal file
View File

@ -0,0 +1,98 @@
---
layout: 'docs'
page_title: 'vagrant snapshot - Command-Line Interface'
sidebar_current: 'cli-snapshot'
description: |-
The "vagrant snapshot" command is used to manage snapshots of the guest
machine.
---
# Snapshot
**Command: `vagrant snapshot`**
This is the command used to manage snapshots with the guest machine.
Snapshots record a point-in-time state of a guest machine. You can then
quickly restore to this environment. This lets you experiment and try things
and quickly restore back to a previous state.
Snapshotting is not supported by every provider. If it is not supported,
Vagrant will give you an error message.
The main functionality of this command is exposed via even more subcommands:
- [`push`](#snapshot-push)
- [`pop`](#snapshot-pop)
- [`save`](#snapshot-save)
- [`restore`](#snapshot-restore)
- [`list`](#snapshot-list)
- [`delete`](#snapshot-delete)
# Snapshot Push
**Command: `vagrant snapshot push`**
This takes a snapshot and pushes it onto the snapshot stack.
This is a shorthand for `vagrant snapshot save` where you do not need
to specify a name. When you call the inverse `vagrant snapshot pop`, it will
restore the pushed state.
~> **Warning:** If you are using `push` and `pop`, avoid using `save`
and `restore` which are unsafe to mix.
# Snapshot Pop
**Command: `vagrant snapshot pop`**
This command is the inverse of `vagrant snapshot push`: it will restore
the pushed state.
## Options
- `--[no-]provision` - Force the provisioners to run (or prevent them
from doing so).
- `--no-delete` - Prevents deletion of the snapshot after restoring
(so that you can restore to the same point again later).
- `--no-start` - Prevents the guest from being started after restore
# Snapshot Save
**Command: `vagrant snapshot save [vm-name] NAME`**
This command saves a new named snapshot. If this command is used, the
`push` and `pop` subcommands cannot be safely used.
# Snapshot Restore
**Command: `vagrant snapshot restore [vm-name] NAME`**
This command restores the named snapshot.
- `--[no-]provision` - Force the provisioners to run (or prevent them
from doing so).
- `--no-start` - Prevents the guest from being started after restore
# Snapshot List
**Command: `vagrant snapshot list`**
This command will list all the snapshots taken.
# Snapshot Delete
**Command: `vagrant snapshot delete [vm-name] NAME`**
This command will delete the named snapshot.
Some providers require all "child" snapshots to be deleted first. Vagrant
itself does not track what these children are. If this is the case (such
as with VirtualBox), then you must be sure to delete the snapshots in the
reverse order they were taken.
This command is typically _much faster_ if the machine is halted prior to
snapshotting. If this is not an option, or is not ideal, then the deletion
can also be done online with most providers.

140
website/pages/docs/cli/ssh.html.md Normal file
View File

@ -0,0 +1,140 @@
---
layout: 'docs'
page_title: 'vagrant ssh - Command-Line Interface'
sidebar_current: 'cli-ssh'
description: |-
The "vagrant ssh" command is used to establish an SSH session into a running
virtual machine to give you shell access.
---
# SSH
**Command: `vagrant ssh [name|id] [-- extra_ssh_args]`**
This will SSH into a running Vagrant machine and give you access to a shell.
On a simple vagrant project, the instance created will be named default.
Vagrant will ssh into this instance without the instance name:
```bash
$ vagrant ssh
Welcome to your Vagrant-built virtual machine.
Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2
$ logout
Connection to 127.0.0.1 closed.
```
Or you could use the name:
```bash
$ vagrant ssh default
Welcome to your Vagrant-built virtual machine.
Last login: Fri Jul 20 15:09:52 2018 from 10.0.2.2
$ logout
Connection to 127.0.0.1 closed.
$
```
On multi-machine setups, you can login to each vm using the name as displayed
on `vagrant status`
```bash
$ vagrant status
Current machine states:
node1 running (virtualbox)
node2 running (virtualbox)
This environment represents multiple VMs. The VMs are all listed
above with their current state.
$ vagrant ssh node1
Welcome to your Vagrant-built virtual machine.
Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2
vagrant@bionic64:~$ logout
Connection to 127.0.0.1 closed.
$ vagrant ssh node2
Welcome to your Vagrant-built virtual machine.
Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2
vagrant@bionic64:~$ logout
Connection to 127.0.0.1 closed.
$
```
On a system with machines running from different projects, you could use the id
as listed in `vagrant global-status`
```bash
$ vagrant global-status
id name provider state directory
-----------------------------------------------------------------------
13759ff node1 virtualbox running /Users/user/vagrant/folder
The above shows information about all known Vagrant environments
on this machine. This data is cached and may not be completely
up-to-date (use "vagrant global-status --prune" to prune invalid
entries). To interact with any of the machines, you can go to that
directory and run Vagrant, or you can use the ID directly with
Vagrant commands from any directory.
$ vagrant ssh 13759ff
Welcome to your Vagrant-built virtual machine.
Last login: Fri Jul 20 15:19:36 2018 from 10.0.2.2
vagrant@bionic64:~$ logout
Connection to 127.0.0.1 closed.
$
```
If a `--` (two hyphens) are found on the command line, any arguments after
this are passed directly into the `ssh` executable. This allows you to pass
any arbitrary commands to do things such as reverse tunneling down into the
`ssh` program.
## Options
- `-c COMMAND` or `--command COMMAND` - This executes a single SSH command, prints
out the stdout and stderr, and exits.
- `-p` or `--plain` - This does an SSH without authentication, leaving
authentication up to the user.
## SSH client usage
Vagrant will attempt to use the local SSH client installed on the host machine. On
POSIX machines, an SSH client must be installed and available on the PATH.
For Windows installations, an SSH client is provided within the installer
image. If no SSH client is found on the current PATH, Vagrant will use the
SSH client it provided. Depending on the local environment used for running
Vagrant, the installer provided SSH client may not work correctly. For example,
when using a cygwin or msys2 shell the SSH client will fail to work as expected
when run interactively. Installing the SSH package built for the current working
environment will resolve this issue.
## Background Execution
If the command you specify runs in the background (such as appending a `&` to
a shell command), it will be terminated almost immediately. This is because
when Vagrant executes the command, it executes it within the context of a
shell, and when the shell exits, all of the child processes also exit.
To avoid this, you will need to detach the process from the shell. Please
Google to learn how to do this for your shell. One method of doing this is
the `nohup` command.
## Pageant on Windows
The SSH executable will not be able to access Pageant on Windows. While
Vagrant is capable of accessing Pageant via internal libraries, the
SSH executable does not have support for Pageant. This means keys
from Pageant will not be available for forwarding when using the
`vagrant ssh` command.
Third party programs exist to allow the SSH executable to access Pageant
by creating a unix socket for the SSH executable to read. For more information
please see [ssh-pageant](https://github.com/cuviper/ssh-pageant).

20
website/pages/docs/cli/ssh_config.html.md Normal file
View File

@ -0,0 +1,20 @@
---
layout: 'docs'
page_title: 'vagrant ssh-config - Command-Line Interface'
sidebar_current: 'cli-ssh_config'
description: |-
The "vagrant ssh-config" command is used to output a valid SSH configuration
file capable of SSHing into the guest machine directly.
---
# SSH Config
**Command: `vagrant ssh-config [name|id]`**
This will output valid configuration for an SSH config file to SSH
into the running Vagrant machine from `ssh` directly (instead of
using `vagrant ssh`).
## Options
- `--host NAME` - Name of the host for the outputted configuration.

18
website/pages/docs/cli/status.html.md Normal file
View File

@ -0,0 +1,18 @@
---
layout: 'docs'
page_title: 'vagrant status - Command-Line Interface'
sidebar_current: 'cli-status'
description: |-
The "vagrant status" command is used to tell you the status of the virtual
machines in the current Vagrant environment.
---
# Status
**Command: `vagrant status [name|id]`**
This will tell you the state of the machines Vagrant is managing.
It is quite easy, especially once you get comfortable with Vagrant, to
forget whether your Vagrant machine is running, suspended, not created, etc.
This command tells you the state of the underlying guest machine.

23
website/pages/docs/cli/suspend.html.md Normal file
View File

@ -0,0 +1,23 @@
---
layout: 'docs'
page_title: 'vagrant suspend - Command-Line Interface'
sidebar_current: 'cli-suspend'
description: |-
The "vagrant suspend" command is used to suspend the guest machine Vagrant is
currently managing.
---
# Suspend
**Command: `vagrant suspend [name|id]`**
This suspends the guest machine Vagrant is managing, rather than fully
[shutting it down](/docs/cli/halt.html) or [destroying it](/docs/cli/destroy.html).
A suspend effectively saves the _exact point-in-time state_ of the machine,
so that when you [resume](/docs/cli/resume.html) it later, it begins running
immediately from that point, rather than doing a full boot.
This generally requires extra disk space to store all the contents of the
RAM within your guest machine, but the machine no longer consumes the
RAM of your host machine or CPU cycles while it is suspended.

48
website/pages/docs/cli/up.html.md Normal file
View File

@ -0,0 +1,48 @@
---
layout: 'docs'
page_title: 'vagrant up - Command-Line Interface'
sidebar_current: 'cli-up'
description: |-
The "vagrant up" command is used to create, configuration, and provision a
guest machine according to your Vagrantfile.
---
# Up
**Command: `vagrant up [name|id]`**
This command creates and configures guest machines according to your
[Vagrantfile](/docs/vagrantfile/).
This is the single most important command in Vagrant, since it is how
any Vagrant machine is created. Anyone using Vagrant must use this command
on a day-to-day basis.
## Options
- `name` - Name of machine defined in [Vagrantfile](/docs/vagrantfile/)
- `id` - Machine id found with `vagrant global-status`. Using `id` allows
you to call `vagrant up id` from any directory.
- `--[no-]destroy-on-error` - Destroy the newly created machine if a fatal,
unexpected error occurs. This will only happen on the first `vagrant up`.
By default this is set.
- `--[no-]install-provider` - If the requested provider is not installed,
Vagrant will attempt to automatically install it if it can. By default this
is enabled.
- `--[no-]parallel` - Bring multiple machines up in parallel if the provider
supports it. Please consult the provider documentation to see if this feature
is supported.
- `--provider x` - Bring the machine up with the given
[provider](/docs/providers/). By default this is "virtualbox".
- `--[no-]provision` - Force, or prevent, the provisioners to run.
- `--provision-with x,y,z` - This will only run the given provisioners. For
example, if you have a `:shell` and `:chef_solo` provisioner and run
`vagrant provision --provision-with shell`, only the shell provisioner will
be run.

30
website/pages/docs/cli/upload.html.md Normal file
View File

@ -0,0 +1,30 @@
---
layout: 'docs'
page_title: 'vagrant upload - Command-Line Interface'
sidebar_current: 'cli-upload'
description: |-
The "vagrant upload" command is used to upload files from the host
to a guest machine.
---
# Upload
**Command: `vagrant upload source [destination] [name|id]`**
This command uploads files and directories from the host to the guest
machine.
## Options
- `destination` - Path on the guest machine to upload file or directory.
- `source` - Path to file or directory on host to upload to guest machine.
- `--compress` - Compress the file or directory before uploading to guest machine.
- `--compression-type type` - Type of compression to use when compressing
file or directory for upload. Defaults to `zip` for Windows guests and
`tgz` for non-Windows guests. Valid values: `tgz`, `zip`.
- `--temporary` - Create a temporary location on the guest machine and upload
files to that location.

24
website/pages/docs/cli/validate.html.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: 'docs'
page_title: 'vagrant validate - Command-Line Interface'
sidebar_current: 'cli-validate'
description: |-
The "vagrant validate" command is used to validate your Vagrantfile.
---
# Validate
**Command: `vagrant validate`**
This command validates your [Vagrantfile](/docs/vagrantfile/).
## Options
- `--ignore-provider` - Ignores provider config options.
## Examples
```sh
$ vagrant validate
Vagrantfile validated successfully.
```

19
website/pages/docs/cli/version.html.md Normal file
View File

@ -0,0 +1,19 @@
---
layout: 'docs'
page_title: 'vagrant version - Command-Line Interface'
sidebar_current: 'cli-version'
description: |-
The "vagrant version" command is used to output the version of Vagrant
currently installed on the system.
---
# Version
**Command: `vagrant version`**
This command tells you the version of Vagrant you have installed
as well as the latest version of Vagrant that is currently available.
In order to determine the latest available Vagrant version, this
command must make a network call. If you only want to see the currently
installed version, use `vagrant --version`.

26
website/pages/docs/cli/winrm.html.md Normal file
View File

@ -0,0 +1,26 @@
---
layout: 'docs'
page_title: 'vagrant winrm - Command-Line Interface'
sidebar_current: 'cli-winrm'
description: |-
The "vagrant winrm" command is used execute commands on the remote
machine via WinRM
---
# WinRM
**Command: `vagrant winrm [name|id]`**
Executes the provided command(s) on the guest machine using the
WinRM communicator. Commands are provided with the `--command`
option and multiple `--command` flags may be provided for
executing multiple commands. This command requires the guest
machine to be configured with the WinRM communicator.
## Options
- `--command COMMAND` - Command to execute.
- `--elevated` - Run command(s) with elevated credentials.
- `--shell (cmd|powershell)` - Shell to execute commands. Defaults to `powershell`.

20
website/pages/docs/cli/winrm_config.html.md Normal file
View File

@ -0,0 +1,20 @@
---
layout: 'docs'
page_title: 'vagrant winrm-config - Command-Line Interface'
sidebar_current: 'cli-winrm_config'
description: |-
The "vagrant winrm-config" command is used to output the WinRM configuration
used to connect to the guest machine.
---
# WinRM Config
**Command: `vagrant winrm-config [name|id]`**
This will output the WinRM configuration used for connecting to
the guest machine. It requires that the WinRM communicator is in
use for the guest machine.
## Options
- `--host NAME` - Name of the host for the outputted configuration.

112
website/pages/docs/disks/configuration.html.md Normal file
View File

@ -0,0 +1,112 @@
---
layout: 'docs'
page_title: 'Vagrant Disks Configuration'
sidebar_current: 'disks-configuration'
description: |-
Documentation of various configuration options for Vagrant Disks
---
# Configuration
Vagrant Disks has several options that allow users to define and attach disks to guests.
## Disk Options
- `disk_ext` (string) - Optional argument that defines what kind of file
extension a disk should have. Defaults to `"vdi"` if unspecified. For a list of
supported disk extensions, please check the specific provider being used.
- `file` (string) - Optional argument that defines a path on disk pointing to
the location of a disk file that already exists.
- `name` (string) - Required option to give the disk a name. This name will be
used as the filename when creating the disk.
- `primary` (boolean) - Optional argument that configures a given disk to be the
"primary" disk to manage on the guest. There can only be one `primary` disk per guest.
Defaults to `false` if not specified.
- `provider_config` (hash) - Additional provider specific options for managing a given disk. Please refer to
the provider specific documentation to see any available provider_config options.
Generally, the disk option accepts two kinds of ways to define a provider config:
+ `providername__diskoption: value`
- The provider name followed by a double underscore, and then the provider specific option for that disk
+ `{providername: {diskoption: value}, otherprovidername: {diskoption: value}`
- A hash where the top level key(s) are one or more providers, and each provider keys values are a hash of options and their values.
- `size` (String) - The size of the disk to create. For example, `"10GB"`.
**Note:** More specific examples of these can be found under the provider
specific disk page. The `provider_config` option will depend on the provider
you are using. Please read the provider specific documentation for disk
management to learn about what options are available to use.
## Disk Types
The disk config currently accepts three kinds of disk types:
- `disk` (symbol)
- `dvd` (symbol)
- `floppy` (symbol)
**NOTE:** These types depend on the provider used, and may not yet be functional. Please
refer to the provider specific implementation for more details for what is supported.
You can set a disk type with the first argument of a disk config in your Vagrantfile:
```ruby
config.vm.disk :disk, name: "backup", size: "10GB"
config.vm.disk :floppy, name: "cool_files"
```
## Provider Author Guide
If you are a vagrant plugin author who maintains a provider for Vagrant, this short guide will hopefully give some information on how to use the internal disk config object.
<div class="alert alert-warning">
<strong>Warning!</strong> This guide is still being written as we develop this
new feature for Vagrant. Is something missing, or could this be improved? Please
let us know on GitHub by opening an issue or open a pull request directly.
</div>
All providers must implement the capability `configure_disks`, and `cleanup_disks`.
These methods are responsible for the following:
- `configure_disks` - Reads in a Vagrant config for defined disks from a Vagrantfile,
and creates and attaches the disks based on the given config
- `cleanup_disks` - Compares the current Vagrant config for defined disks and detaches
any disks that are no longer valid for a guest.
These methods are called in the builtin Vagrant actions _Disk_ and _CleanupDisks_.
If the provider does not support these capabilities, they will be skipped over and no
disks will be configured. It is the providers job to implement these provider capabilities
and handle the methods required to support disk creation and deletion. Vagrant will
handle parsing and supplying the config object based on what has been defined inside
a users Vagrantfile.
For a more detailed example of how to use this disk configuration with Vagrant, please
check out how it was implemented using the VirtualBox provider.
### The disk_meta file
Both builtin disk actions `configure_disks` and `cleanup_disks` expect to read and
write down a `disk_meta` file inside a machines data dir. This file is specifically
for keeping track of the _last configured state_ for disks in a given provider.
Generally, this file is used as a way for Vagrant to keep track of what disks
are being managed by Vagrant with the provider uses, so that it does not accidentally
delete or manage disks that were configured outside of Vagrants configuration.
For the VirtualBox provider, Vagrant uses this file to see what disks were configured
on the _last run_ of Vagrant, and compares that to the current configured state for
the Vagrantfile on the _current run_ of Vagrant. It specifically stores each disks
UUID and disk name for use. If it notices a disk that is no longer in the
Vagrantfile, it can be assumed that the disk is no longer valid for that guest,
and cleans up the disk.
This may not be required for your provider, however with the VirtualBox provider, Vagrant
needs a way to keep track of the defined disks managed by Vagrant and their disk UUIDs
that VirtualBox uses to keep track of these disks.
### The provider_config hash
The disk config class supports an optional hash of options called `provider_config`.
This allows the user to define some additional options for a provider to use that
may be non-standard across different providers.

29
website/pages/docs/disks/index.html.md Normal file
View File

@ -0,0 +1,29 @@
---
layout: 'docs'
page_title: 'Vagrant Disks'
sidebar_current: 'disks'
description: |-
Introduction to Vagrant Disks
---
# Vagrant Disks
<div class="alert alert-warning">
<strong>Warning!</strong> This feature is experimental and may break or
change in between releases. Use at your own risk. It currently is not officially
supported or functional. Please refer to the providier specific disk documentation
for more information on how to use and enable this feature.
</div>
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](/docs/disks/usage.html)
guide for more information!
For more information about what options are available for configuring disks, see the
[configuration section](/docs/disks/configuration.html).
## Supported Providers
Currently, only VirtualBox is supported. Please refer to the [VirtualBox documentation](/docs/disks/virtualbox/index.html) for more information on using disks with the VirtualBox provider!

104
website/pages/docs/disks/usage.html.md Normal file
View File

@ -0,0 +1,104 @@
---
layout: 'docs'
page_title: 'Vagrant Disk Usage'
sidebar_current: 'disks-usage'
description: |-
Various Vagrant Disk examples
---
# Basic Usage
<div class="alert alert-warning">
<strong>Warning!</strong> This feature is experimental and may break or
change in between releases. Use at your own risk. It currently is not officially
supported or functional.
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
```
VAGRANT_EXPERIMENTAL="disks"
```
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
information about this flag visit the [Experimental docs page](/docs/experimental/)
for more info. Without this flag enabled, any disks defined will not be configured.
Also note that the examples below use the VirtualBox provider, which is the current
supported providier for this feature.
</div>
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 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 only allows for up to 30 disks to be attached to a given SATA Controller,
and this number includes the primary disk! Attempting to configure more than 30 will
result in a Vagrant error.
### Removing Disks
If you have removed a disk from your Vagrant config and wish for it to be detached from the guest,
you will need to `vagrant reload` your guest to apply these changes. **NOTE:** Doing so
will also delete the medium from your hard drive.

42
website/pages/docs/disks/virtualbox/common-issues.html.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: 'docs'
page_title: 'Common Issues - Disks VirtualBox Provider'
sidebar_current: 'disks-providers-virtualbox-issues'
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 a guests SATA Controller. As of VirtualBox 6.1.x,
SATA Controllers can only support up to **30 disks** per guest. Therefore if you try
to define and attach more than 30, it will result in an error. This number _includes_
the primary disk for the guest.
## 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.

43
website/pages/docs/disks/virtualbox/index.html.md Normal file
View File

@ -0,0 +1,43 @@
---
layout: 'docs'
page_title: 'Disks for VirtualBox Provider'
sidebar_current: 'disks-providers-virtualbox'
description: |-
Vagrant comes with support out of the box for VirtualBox, a free,
cross-platform consumer virtualization product.
---
# VirtualBox
<div class="alert alert-warning">
<strong>Warning!</strong> This feature is experimental and may break or
change in between releases. Use at your own risk. It currently is not officially
supported or functional.
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
```
VAGRANT_EXPERIMENTAL="disks"
```
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
information about this flag visit the [Experimental docs page](/docs/experimental/)
for more info. Without this flag enabled, any disks defined will not be configured.
</div>
**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 create and attach
these disks to a guests SATA Controller. It should be noted that up to 30 disks
can be attached to the SATA Controller.
For more information on how to use VirtualBox to configure disks for a guest, refer
to the [general usage](/docs/disks/usage.html) and [configuration](/docs/disks/configuration.html)
guide for more information.

35
website/pages/docs/disks/virtualbox/usage.html.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: 'docs'
page_title: 'Usage - Disks VirtualBox Provider'
sidebar_current: 'disks-providers-virtualbox-usage'
description: |-
The Vagrant VirtualBox provider is used just like any other provider. Please
read the general basic usage page for providers.
---
# Usage
<div class="alert alert-warning">
<strong>Warning!</strong> This feature is experimental and may break or
change in between releases. Use at your own risk. It currently is not officially
supported or functional.
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
```
VAGRANT_EXPERIMENTAL="disks"
```
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
information about this flag visit the [Experimental docs page](/docs/experimental/)
for more info. Without this flag enabled, any disks defined will not be configured.
</div>
For examples of how to use the disk feature with VirtualBox, please refer to the
[general disk usage guide](/docs/disks/usage.html) 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.

128
website/pages/docs/docker/basics.html.md Normal file
View File

@ -0,0 +1,128 @@
---
layout: 'docs'
page_title: 'Basic Usage - Docker Provider'
sidebar_current: 'providers-docker-basics'
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/master/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.
<div class="alert alert-info">
<strong>Synced folder note:</strong> 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.
</div>
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](/docs/cli/global-status.html)
along with global control.

20
website/pages/docs/docker/boxes.html.md Normal file
View File

@ -0,0 +1,20 @@
---
layout: 'docs'
page_title: 'Boxes - Docker Provider'
sidebar_current: 'providers-docker-boxes'
description: |-
The Docker provider does not require a Vagrant box. The "config.vm.box"
setting is completely optional.
---
# Docker Boxes
The Docker provider does not require a Vagrant box. The `config.vm.box`
setting is completely optional.
A box can still be used and specified, however, to provide defaults.
Because the `Vagrantfile` within a box is loaded as part of the
configuration loading sequence, it can be used to configure the
foundation of a development environment.
In general, however, you will not need a box with the Docker provider.

113
website/pages/docs/docker/commands.html.md Normal file
View File

@ -0,0 +1,113 @@
---
layout: 'docs'
page_title: 'Commands - Docker Provider'
sidebar_current: 'providers-docker-commands'
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.
```sh
$ 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:
```sh
$ vagrant docker-exec -it -- /bin/sh
```
In particular, the command is actually:
```sh
$ 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:
```sh
# Not valid
$ vagrant docker-exec -it nginx -- /bin/sh
```
This is because the "name" of the VM is "web", so the command is actually:
```sh
$ 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:
```sh
$ 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:
```sh
$ vagrant docker-run app -- rake db:migrate
```
The above would run `rake db:migrate` in the context of an `app` container.

123
website/pages/docs/docker/configuration.html.md Normal file
View File

@ -0,0 +1,123 @@
---
layout: 'docs'
page_title: 'Configuration- Docker Provider'
sidebar_current: 'providers-docker-configuration'
description: |-
The Docker provider has some provider-specific configuration options
you may set. A complete reference is shown on this page.
---
# Docker Configuration
The Docker provider has some provider-specific configuration options
you may set. A complete reference is shown below.
### Required
One of the following settings is required when using the Docker provider:
- `build_dir` (string) - The path to a directory containing a Dockerfile.
- `image` (string) - The image to launch, specified by the image ID or a name
such as `ubuntu:12.04`.
- `git_repo` (string) - The URL of a git repository to build the image from.
Supports pulling specific tags, branches and revision, consult the
[docker documentation](https://docs.docker.com/engine/reference/commandline/build/#/git-repositories)
for more information.
### Optional
General settings:
- `build_args` (array of strings) - Extra arguments to pass to
`docker build` when `build_dir` is in use.
- `cmd` (array of strings) - Custom command to run on the container.
Example: `["ls", "/app"]`.
- `compose` (boolean) - If true, Vagrant will use `docker-compose` to
manage the lifecycle and configuration of containers. This defaults
to false.
- `compose_configuration` (Hash) - Configuration values used for populating
the `docker-compose.yml` file. The value of this Hash is directly merged
and written to the `docker-compose.yml` file allowing customization of
non-services items like networks and volumes.
- `create_args` (array of strings) - Additional arguments to pass to
`docker run` when the container is started. This can be used to set
parameters that are not exposed via the Vagrantfile.
- `dockerfile` (string) - Name of the Dockerfile in the build directory.
This defaults to "Dockerfile"
- `env` (hash) - Environmental variables to expose into the container.
- `expose` (array of integers) - Ports to expose from the container
but not to the host machine. Useful for links.
- `link` (method, string argument) - Link this container to another
by name. The argument should be in the format of `(name:alias)`.
Example: `docker.link("db:db")`. Note, if you are linking to
another container in the same Vagrantfile, make sure you call
`vagrant up` with the `--no-parallel` flag.
- `force_host_vm` (boolean) - If true, then a host VM will be spun up
even if the computer running Vagrant supports Linux containers. This
is useful to enforce a consistent environment to run Docker. This value
defaults to "false" on Linux, Mac, and Windows hosts and defaults to "true"
on other hosts. Users on other hosts who choose to use a different Docker
provider or opt-in to the native Docker builds can explicitly set this
value to false to disable the behavior.
- `has_ssh` (boolean) - If true, then Vagrant will support SSH with
the container. This allows `vagrant ssh` to work, provisioners, etc.
This defaults to false.
- `host_vm_build_dir_options` (hash) - Synced folder options for the
`build_dir`, since the build directory is synced using a synced folder
if a host VM is in use.
- `name` (string) - Name of the container. Note that this has to be unique
across all containers on the host VM. By default Vagrant will generate
some random name.
- `pull` (bool) - If true, the image will be pulled on every `up` and
`reload`. Defaults to false.
- `ports` (array of strings) - Ports to expose from the container to the
host. These should be in the format of `host:container`.
- `remains_running` (boolean) - If true, Vagrant expects this container
to remain running and will make sure that it does for a certain amount
of time. If false, then Vagrant expects that this container will
automatically stop at some point, and will not error if it sees it do that.
- `stop_timeout` (integer) - The amount of time to wait when stopping
a container before sending a SIGTERM to the process.
- `vagrant_machine` (string) - The name of the Vagrant machine in the
`vagrant_vagrantfile` to use as the host machine. This defaults to
"default".
- `vagrant_vagrantfile` (string) - Path to a Vagrantfile that contains
the `vagrant_machine` to use as the host VM if needed.
- `volumes` (array of strings) - List of directories to mount as
volumes into the container. These directories must exist in the
host where Docker is running. If you want to sync folders from the
host Vagrant is running, just use synced folders.
Below, we have settings related to auth. If these are set, then Vagrant
will `docker login` prior to starting containers, allowing you to pull
images from private repositories.
- `email` (string) - Email address for logging in.
- `username` (string) - Username for logging in.
- `password` (string) - Password for logging in.
- `auth_server` (string) - The server to use for authentication. If not
set, the Docker Hub will be used.

27
website/pages/docs/docker/index.html.md Normal file
View File

@ -0,0 +1,27 @@
---
layout: 'docs'
page_title: 'Docker Provider'
sidebar_current: 'providers-docker'
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.
<div class="alert alert-warning">
<strong>Warning: Docker knowledge assumed.</strong> 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 <a href="/docs/virtualbox/">VirtualBox</a>.
</div>
Use the navigation to the left to find a specific Docker topic
to read more about.

290
website/pages/docs/docker/networking.html.md Normal file
View File

@ -0,0 +1,290 @@
---
layout: 'docs'
page_title: 'Networking - Docker Provider'
sidebar_current: 'providers-docker-networking'
description: |-
The Vagrant Docker provider supports using the private network using the
`docker network` commands.
---
# Networking
Vagrant uses the `docker network` command under the hood to create and manage
networks for containers. Vagrant will do its best to create and manage networks
for any containers configured inside the Vagrantfile. Each docker network is grouped
by the subnet used for a requested ip address.
For each newly unique network, Vagrant will run the `docker network create` subcommand
with the provided options from the network config inside your Vagrantfile. If multiple
networks share the same subnet, Vagrant will reuse that existing network for multiple
containers. Once these networks have been created, Vagrant will attach these
networks to the requested containers using the `docker network connect` for each
network.
Vagrant names the networks inside docker as `vagrant_network` or `vagrant_network_<subnet here>`
where `<subnet_here>` is the subnet for the network if defined by the user. An
example of these networks is shown later in this page. If no subnet is requested
for the network, Vagrant will connect the `vagrant_network` to the container.
When destroying containers through Vagrant, Vagrant will clean up the network if
there are no more containers using the network.
## Docker Network Options
Most of the options work similar to other Vagrant providers. Defining either an
ip or using `type: 'dhcp'` will give you a network on your container.
```ruby
docker.vm.network :private_network, type: "dhcp"
docker.vm.network :private_network, ip: "172.20.128.2"
```
If you want to set something specific with a new network you can use scoped options
which align with the command line flags for the [docker network create](https://docs.docker.com/engine/reference/commandline/network_create/)
command. If there are any specific options you want to enable from the `docker network create`
command, you can specify them like this:
```ruby
docker.vm.network :private_network, type: "dhcp", docker_network__internal: true
```
This will enable the `internal` option for the network when created with `docker network create`.
Where `option` corresponds to the given flag that will be provided to the `docker network create`
command. Similarly, if there is a value you wish to enable when connecting a container
to a given network, you can use the following value in your network config:
```ruby
docker_connect__option: "value"
```
When the docker provider creates a new network a netmask is required. If the netmask
is not provided, Vagrant will default to a `/24` for IPv4 and `/64` for IPv6. To provide
a different mask, set it using the `netmask` option:
```ruby
docker.vm.network :private_network, ip: "172.20.128.2", netmask: 16
```
For networks which set the type to "dhcp", it is also possible to specify a specific
subnet for the network connection. This allows containers to connect to networks other
than the default `vagrant_network` network. The docker provider supports specifying
the desired subnet in two ways. The first is by using the `ip` and `netmask` options:
```ruby
docker.vm.network :private_network, type: "dhcp", ip: "172.20.128.0", netmask: 24
```
The second is by using the `subnet` option:
```ruby
docker.vm.network :private_network, type: "dhcp", subnet: "172.20.128.0/24"
```
### Public Networks
The Vagrant docker provider also supports defining public networks. The easiest way
to define a public network is by setting the `type` option to "dhcp":
```ruby
docker.vm.network :public_network, type: "dhcp"
```
A bridge interface is required when setting up a public network. When no bridge
device name is provided, Vagrant will prompt for the appropriate device to use. This
can also be set using the `bridge` option:
```ruby
docker.vm.network :public_network, type: "dhcp", bridge: "eth0"
```
The `bridge` option also supports a list of interfaces which can be used for
setting up the network. Vagrant will inspect the defined interfaces and use
the first active interface when setting up the network:
```ruby
docker.vm.network :public_network, type: "dhcp", bridge: ["eth0", "wlan0"]
```
The available IP range for the bridge interface must be known when setting up
the docker network. Even though a DHCP service may be available on the public
network, docker will manage IP addresses provided to containers. This means
that the subnet provided when defining the available IP range for the network
should not be included within the subnet managed by the DHCP service. Vagrant
will prompt for the available IP range information, however, it can also be
provided in the Vagrantfile using the `docker_network__ip_range` option:
```ruby
docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__ip_range: "192.168.1.252/30"
```
Finally, the gateway for the interface is required during setup. The docker
provider will default the gateway address to the first address available for
the subnet of the bridge device. Vagrant will prompt for confirmation to use
the default address. The address can also be manually set in the Vagrantfile
using the `docker_network__gateway` option:
```ruby
docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__gateway: "192.168.1.2"
```
More examples are shared below which demonstrate creating a few common network
interfaces.
## Docker Network Example
The following Vagrantfile will generate these networks for a container:
1. A IPv4 IP address assigned by DHCP
2. A IPv4 IP address 172.20.128.2 on a network with subnet 172.20.0.0/16
3. A IPv6 IP address assigned by DHCP on subnet 2a02:6b8:b010:9020:1::/80
```ruby
Vagrant.configure("2") do |config|
config.vm.define "docker" do |docker|
docker.vm.network :private_network, type: "dhcp", docker_network__internal: true
docker.vm.network :private_network,
ip: "172.20.128.2", netmask: "16"
docker.vm.network :private_network, type: "dhcp", subnet: "2a02:6b8:b010:9020:1::/80"
docker.vm.provider "docker" do |d|
d.build_dir = "docker_build_dir"
end
end
end
```
You can test that your container has the proper configured networks by looking
at the result of running `ip addr`, for example:
```
brian@localghost:vagrant-sandbox % docker ps ±[●][master]
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
370f4e5d2217 196a06ef12f5 "tail -f /dev/null" 5 seconds ago Up 3 seconds 80/tcp, 443/tcp vagrant-sandbox_docker-1_1551810440
brian@localghost:vagrant-sandbox % docker exec 370f4e5d2217 ip addr ±[●][master]
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
24: eth0@if25: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:11:00:03 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.17.0.3/16 brd 172.17.255.255 scope global eth0
valid_lft forever preferred_lft forever
27: eth1@if28: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:13:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.19.0.2/16 brd 172.19.255.255 scope global eth1
valid_lft forever preferred_lft forever
30: eth2@if31: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:14:80:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.20.128.2/16 brd 172.20.255.255 scope global eth2
valid_lft forever preferred_lft forever
33: eth3@if34: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:ac:15:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 172.21.0.2/16 brd 172.21.255.255 scope global eth3
valid_lft forever preferred_lft forever
inet6 2a02:6b8:b010:9020:1::2/80 scope global nodad
valid_lft forever preferred_lft forever
inet6 fe80::42:acff:fe15:2/64 scope link
valid_lft forever preferred_lft forever
```
You can also connect your containers to a docker network that was created outside
of Vagrant:
```
$ docker network create my-custom-network --subnet=172.20.0.0/16
```
```ruby
Vagrant.configure("2") do |config|
config.vm.define "docker" do |docker|
docker.vm.network :private_network, type: "dhcp", name: "my-custom-network"
docker.vm.provider "docker" do |d|
d.build_dir = "docker_build_dir"
end
end
end
```
Vagrant will not delete or modify these outside networks when deleting the container, however.
## Useful Debugging Tips
The `docker network` command provides some helpful insights to what might be going
on with the networks Vagrant creates. For example, if you want to know what networks
you currently have running on your machine, you can run the `docker network ls` command:
```
brian@localghost:vagrant-sandbox % docker network ls ±[●][master]
NETWORK ID NAME DRIVER SCOPE
a2bfc26bd876 bridge bridge local
2a2845e77550 host host local
f36682aeba68 none null local
00d4986c7dc2 vagrant_network bridge local
d02420ff4c39 vagrant_network_2a02:6b8:b010:9020:1::/80 bridge local
799ae9dbaf98 vagrant_network_172.20.0.0/16 bridge local
```
You can also inspect any network for more information:
```
brian@localghost:vagrant-sandbox % docker network inspect vagrant_network ±[●][master]
[
{
"Name": "vagrant_network",
"Id": "00d4986c7dc2ed7bf1961989ae1cfe98504c711f9de2f547e5dfffe2bb819fc2",
"Created": "2019-03-05T10:27:21.558824922-08:00",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Options": {},
"Config": [
{
"Subnet": "172.19.0.0/16",
"Gateway": "172.19.0.1"
}
]
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": ""
},
"ConfigOnly": false,
"Containers": {
"370f4e5d2217e698b16376583fbf051dd34018e5fd18958b604017def92fea63": {
"Name": "vagrant-sandbox_docker-1_1551810440",
"EndpointID": "166b7ca8960a9f20a150bb75a68d07e27e674781ed9f916e9aa58c8bc2539a61",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {},
"Labels": {}
}
]
```
## Caveats
For now, Vagrant only looks at the subnet when figuring out if it should create
a new network for a guest container. If you bring up a container with a network,
and then change or add some new options (but leave the subnet the same), it will
not apply those changes or create a new network.
Because the `--link` flag for the `docker network connect` command is considered
legacy, Vagrant does not support that option when creating containers and connecting
networks.
## More Information
For more information on how docker manages its networks, please refer to their
documentation:
- https://docs.docker.com/network/
- https://docs.docker.com/engine/reference/commandline/network/

56
website/pages/docs/experimental/index.html.md Normal file
View File

@ -0,0 +1,56 @@
---
layout: 'docs'
page_title: 'Vagrant Experimental Feature Flag'
sidebar_current: 'experimental'
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
<div class="alert alert-warning">
<strong>Advanced topic!</strong> 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.
</div>
This is a list of all the valid experimental features that Vagrant recognizes:
### `typed_triggers`
Enabling this feature allows triggers to recognize and execute `:type` triggers.
More information about how these should be used can be found on the [trigger documentation page](/docs/triggers/configuration.html#trigger-types)
### `dependency_provisioners`
Enabling this feature allows all provisioners to specify `before` and `after`
options. These options allow provisioners to be configured to run before or after
any given "root" provisioner. more information about these options can be found
on the [base provisioner documentation page](/docs/provisioning/basic_usage.html)

103
website/pages/docs/hyperv/boxes.html.md Normal file
View File

@ -0,0 +1,103 @@
---
layout: 'docs'
page_title: 'Creating a Base Box - Hyper-V Provider'
sidebar_current: 'providers-hyperv-boxes'
description: |-
As with every Vagrant provider, the Vagrant Hyper-V provider has a custom box
format that affects how base boxes are made.
---
# Creating a Base Box
As with [every Vagrant provider](/docs/providers/basic_usage.html), the
Vagrant Hyper-V provider has a custom box format that affects how base boxes are made.
Prior to reading this, you should read the
[general guide to creating base boxes](/docs/boxes/base.html). Actually,
it would probably be most useful to keep this open in a separate tab
as you may be referencing it frequently while creating a base box. That
page contains important information about common software to install
on the box.
Additionally, it is helpful to understand the
[basics of the box file format](/docs/boxes/format.html).
<div class="alert alert-warning">
<strong>Advanced topic!</strong> This is a reasonably advanced topic that
a beginning user of Vagrant does not need to understand. If you are
just getting started with Vagrant, skip this and use an available
box. If you are an experienced user of Vagrant and want to create
your own custom boxes, this is for you.
</div>
## Additional Software
In addition to the software that should be installed based on the
[general guide to creating base boxes](/docs/boxes/base.html),
Hyper-V base boxes require some additional software.
### Hyper-V Kernel Modules
You will need to install Hyper-V kernel modules. While this improves performance,
it also enables necessary features such as reporting its IP address so that
Vagrant can access it.
You can verify Hyper-V kernel modules are properly installed by
running `lsmod` on Linux machines and looking for modules prefixed with
`hv_`. Additionally, you will need to verify that the "Network" tab for your
virtual machine in the Hyper-V manager is reporting an IP address. If it
is not reporting an IP address, Vagrant will not be able to access it.
For most newer Linux distributions, the Hyper-V modules will be available
out of the box.
Ubuntu 12.04 requires some special steps to make networking work. These
are reproduced here in case similar steps are needed with other distributions.
Without these commands, Ubuntu 12.04 will not report an IP address to
Hyper-V:
```
$ sudo apt-get install linux-tools-3.11.0-15-generic
$ sudo apt-get install hv-kvp-daemon-init
$ sudo cp /usr/lib/linux-tools/3.11.0-15/hv_* /usr/sbin/
```
## Packaging the Box
To package a Hyper-V box, export the virtual machine from the
Hyper-V Manager using the "Export" feature. This will create a directory
with a structure similar to the following:
```
.
|-- Snapshots
|-- Virtual Hard drives
|-- Virtual Machines
```
Delete the "Snapshots" folder. It is of no use to the Vagrant Hyper-V
provider and can only add to the size of the box if there are snapshots
in that folder.
Then, create the "metadata.json" file necessary for the box, as documented
in [basics of the box file format](/docs/boxes/format.html). The proper
provider value to use for the metadata is "hyperv".
Finally, create an archive of those contents (but _not_ the parent folder)
using a tool such as `tar`:
```
$ tar cvzf ~/custom.box ./*
```
A common mistake is to also package the parent folder by accident. Vagrant
will not work in this case. To verify you've packaged it properly, add the
box to Vagrant and try to bring up the machine.
## Additional Help
There is also some less structured help available from the experience of
other users. These are not official documentation but if you are running
into trouble they may help you:
- [Ubuntu 14.04.2 without secure boot](https://github.com/hashicorp/vagrant/issues/5419#issuecomment-86235427)

57
website/pages/docs/hyperv/configuration.html.md Normal file
View File

@ -0,0 +1,57 @@
---
layout: 'docs'
page_title: 'Configuration- Hyper-V Provider'
sidebar_current: 'providers-hyperv-configuration'
description: |-
The Vagrant Hyper-V provider has some provider-specific configuration options
you may set.
---
# Configuration
The Vagrant Hyper-V provider has some provider-specific configuration options
you may set. A complete reference is shown below:
- `auto_start_action` (Nothing, StartIfRunning, Start) - Automatic start action for VM on host startup. Default: Nothing.
- `auto_stop_action` (ShutDown, TurnOff, Save) - Automatic stop action for VM on host shutdown. Default: ShutDown.
- `cpus` (integer) - Number of virtual CPUs allocated to VM at startup.
- `differencing_disk` (boolean) - **Deprecated** Use differencing disk instead of cloning entire VHD (use `linked_clone` instead) Default: false.
- `enable_virtualization_extensions` (boolean) - Enable virtualization extensions for the virtual CPUs. Default: false
- `enable_checkpoints` (boolean) Enable checkpoints of the VM. Default: true
- `enable_automatic_checkpoints` (boolean) Enable automatic checkpoints of the VM. Default: false
- `ip_address_timeout` (integer) - Number of seconds to wait for the VM to report an IP address. Default: 120.
- `linked_clone` (boolean) - Use differencing disk instead of cloning entire VHD. Default: false
- `mac` (string) - MAC address for the guest network interface
- `maxmemory` (integer) - Maximum number of megabytes allowed to be allocated for the VM. When set Dynamic Memory Allocation will be enabled.
- `memory` (integer) - Number of megabytes allocated to VM at startup. If `maxmemory` is set, this will be amount of memory allocated at startup.
- `vlan_id` (integer) - VLAN ID for the guest network interface.
- `vmname` (string) - Name of virtual machine as shown in Hyper-V manager. Default: Generated name.
- `vm_integration_services` (Hash) - Hash to set the state of integration services. (Note: Unknown key values will be passed directly.)
- `guest_service_interface` (boolean)
- `heartbeat` (boolean)
- `key_value_pair_exchange` (boolean)
- `shutdown` (boolean)
- `time_synchronization` (boolean)
- `vss` (boolean)
## VM Integration Services
The `vm_integration_services` configuration option consists of a simple Hash. The key values are the
names of VM integration services to enable or disable for the VM. Vagrant includes an internal
mapping of known services which allows them to be provided in a "snake case" format. When a provided
key is unknown, the key value is used "as-is" without any modifications.
For example, if a new `CustomVMSRV` VM integration service was added and Vagrant is not aware of this
new service name, it can be provided as the key value explicitly:
```ruby
config.vm.provider "hyperv" do |h|
h.vm_integration_services = {
guest_service_interface: true,
CustomVMSRV: true
}
end
```
This example would enable the `GuestServiceInterface` (which Vagrant is aware) and `CustomVMSRV` (which
Vagrant is _not_ aware) VM integration services.

37
website/pages/docs/hyperv/index.html.md Normal file
View File

@ -0,0 +1,37 @@
---
layout: 'docs'
page_title: 'Hyper-V Provider'
sidebar_current: 'providers-hyperv'
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:
<code>Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All</code>
See official documentation [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v).
<div class="alert alert-warning">
<strong>Warning:</strong> Enabling Hyper-V will cause VirtualBox, VMware,
and any other virtualization technology to no longer work. See
<a href="http://www.hanselman.com/blog/SwitchEasilyBetweenVirtualBoxAndHyperVWithABCDEditBootEntryInWindows81.aspx">this blog post</a>
for an easy way to create a boot entry to boot Windows without Hyper-V
enabled, if there will be times you will need other hypervisors.
</div>

35
website/pages/docs/hyperv/limitations.html.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: 'docs'
page_title: 'Limitations - Hyper-V Provider'
sidebar_current: 'providers-hyperv-limitations'
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.

25
website/pages/docs/hyperv/usage.html.md Normal file
View File

@ -0,0 +1,25 @@
---
layout: 'docs'
page_title: 'Usage - Hyper-V Provider'
sidebar_current: 'providers-hyperv-usage'
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](/docs/providers/basic_usage.html) 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.

24
website/pages/docs/index.html.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: 'docs'
sidebar_current: 'overview'
page_title: 'Documentation'
description: |-
Welcome to the documentation for Vagrant - the command line utility for
managing the lifecycle of virtual machines. This website aims to document
every feature of Vagrant from top-to-bottom, covering as much detail as
possible.
---
# Vagrant Documentation
Welcome to the documentation for Vagrant - the command line utility for managing
the lifecycle of virtual machines. This website aims to document every feature
of Vagrant from top-to-bottom, covering as much detail as possible. If you are
just getting started with Vagrant, it is highly recommended that you start with
the [getting started guide](/intro/getting-started/index.html) first, and then
return 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](/intro/index.html)
for their needs.

41
website/pages/docs/installation/backwards-compatibility.html.md Normal file
View File

@ -0,0 +1,41 @@
---
layout: 'docs'
page_title: 'Backwards Compatibility'
sidebar_current: 'installation-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.

96
website/pages/docs/installation/index.html.md Normal file
View File

@ -0,0 +1,96 @@
---
layout: 'docs'
page_title: 'Installing Vagrant'
sidebar_current: 'installation'
description: |-
Installing Vagrant is extremely easy. Head over to the Vagrant downloads page
and get the appropriate installer or package for your platform. Install the
package using standard procedures for your operating system.
---
# Installing Vagrant
Installing Vagrant is extremely easy. Head over to the
[Vagrant downloads page](/downloads.html) and get the appropriate installer or
package for your platform. Install the package using standard procedures for
your operating system.
The installer will automatically add `vagrant` to your system path
so that it is available in terminals. If it is not found, please try
logging out and logging back in to your system (this is particularly
necessary sometimes for Windows).
<div class="alert alert-warning" role="alert">
<strong>Looking for the gem install?</strong> Vagrant 1.0.x had the option to
be installed as a <a href="https://en.wikipedia.org/wiki/RubyGems">RubyGem</a>.
This installation method is no longer supported. If you have an old version
of Vagrant installed via Rubygems, please remove it prior to installing newer
versions of Vagrant.
</div>
<div class="alert alert-warning" role="alert">
<strong>Beware of system package managers!</strong> Some operating system
distributions include a vagrant package in their upstream package repos.
Please do not install Vagrant in this manner. Typically these packages are
missing dependencies or include very outdated versions of Vagrant. If you
install via your system's package manager, it is very likely that you will
experience issues. Please use the official installers on the downloads page.
</div>
## Running Multiple Hypervisors
Sometimes, certain hypervisors do not allow you to bring up virtual machines
if more than one hypervisor is in use. If you are lucky, you might see the following
error message come up when trying to bring up a virtual machine with Vagrant and
VirtualBox:
There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below.
Command: ["startvm", <ID of the VM>, "--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
Other operating systems like Windows will blue screen if you attempt to bring up
a VirtualBox VM with Hyper-V enabled. Below are a couple of ways to ensure you
can use Vagrant and VirtualBox if another hypervisor is present.
### Linux, VirtualBox, and KVM
The above error message is because another hypervisor (like KVM) is in use.
We must blacklist these in order for VirtualBox to run correctly.
First find out the name of the hypervisor:
$ lsmod | grep kvm
kvm_intel 204800 6
kvm 593920 1 kvm_intel
irqbypass 16384 1 kvm
The one we're interested in is `kvm_intel`. You might have another.
Blacklist the hypervisor (run the following as root):
# echo 'blacklist kvm-intel' >> /etc/modprobe.d/blacklist.conf
Restart your machine and try running vagrant again.
### Windows, VirtualBox, and Hyper-V
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 by running this Powershell command:
```powershell
Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All
```
You can also disable it by going through 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).

80
website/pages/docs/installation/source.html.md Normal file
View File

@ -0,0 +1,80 @@
---
layout: 'docs'
page_title: 'Installing Vagrant from Source'
sidebar_current: 'installation-source'
description: |-
Installing Vagrant from source is an advanced topic and is only recommended
when using the official installer is not an option. This page details the
steps and prerequisites for installing Vagrant from source.
---
# Installing Vagrant from Source
Installing Vagrant from source is an advanced topic and is only recommended
when using the official installer is not an option. This page details the
steps and prerequisites for installing Vagrant from source.
## Install Ruby
You must have a modern Ruby (>= 2.2) in order to develop and build Vagrant. The
specific Ruby version is documented in the Vagrant's `gemspec`. Please refer to
the `vagrant.gemspec` in the repository on GitHub, as it will contain the most
up-to-date requirement. This guide will not discuss how to install and manage Ruby.
However, beware of the following pitfalls:
- Do **NOT** use the system Ruby - use a Ruby version manager like rvm or chruby
- Vagrant plugins are configured based on current environment. If plugins are installed
using Vagrant from source, they will not work from the package based Vagrant installation.
## Clone Vagrant
Clone Vagrant's repository from GitHub into the directory where you keep code on your machine:
```shell
$ git clone https://github.com/hashicorp/vagrant.git
```
Next, `cd` into that path. All commands will be run from this path:
```shell
$ cd /path/to/your/vagrant/clone
```
Run the `bundle` command with a required version\* to install the requirements:
```shell
$ bundle install
```
You can now run Vagrant by running `bundle exec vagrant` from inside that
directory.
## Use 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, run the following command from the Vagrant repo:
```shell
$ 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
$ /path/to/vagrant/exec/vagrant init -m hashicorp/bionic64
```
Note that you _will_ receive warnings that running Vagrant like this is not
supported. It's true. It's not. You should listen to those warnings.
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
$ ln -sf /path/to/vagrant/exec/vagrant /usr/local/bin/vagrant
```
When you want to switch back to the official Vagrant version, simply
remove the symlink.

61
website/pages/docs/installation/uninstallation.html.md Normal file
View File

@ -0,0 +1,61 @@
---
layout: 'docs'
page_title: 'Uninstalling Vagrant'
sidebar_current: 'installation-uninstallation'
description: |-
Uninstalling Vagrant is easy and straightforward. You can either uninstall
the Vagrant binary, the user data, or both. The sections below cover how to
do this on every platform.
---
# Uninstalling Vagrant
Uninstalling Vagrant is easy and straightforward. You can either uninstall
the Vagrant binary, the user data, or both. The sections below cover how to
do this on every platform.
## Removing the Vagrant Program
Removing the Vagrant program will remove the `vagrant` binary and all
dependencies from your machine. After uninstalling the program, you can
always [reinstall](/docs/installation/) again using standard
methods. Uninstalling Vagrant will _not_ remove user data. The section below this
one gives more detailed instructions on how to remove that directory from your
system.
On **Windows**
> Uninstall using the add/remove programs section of the control panel
On **Mac OS X**:
```sh
rm -rf /opt/vagrant
rm -f /usr/local/bin/vagrant
sudo pkgutil --forget com.vagrant.vagrant
```
On **Linux**:
```sh
rm -rf /opt/vagrant
rm -f /usr/bin/vagrant
```
## Removing User Data
Removing the user data will remove all [boxes](/docs/boxes.html),
[plugins](/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 all platforms, this directory is located in the root of your home directory,
and is named `vagrant.d`. Simply remove the `~/.vagrant.d` directory to delete the user data. If on
Windows, this directory is located at `C:\Users\YourUsername\.vagrant.d`, where
`YourUsername` is the username of your local user.
When debugging, the Vagrant support team may ask you to remove this
directory. Before removing this directory, please make a backup.
Running Vagrant will automatically regenerate any data necessary to run,
so it is safe to remove the user data at any time.

33
website/pages/docs/installation/upgrading-from-1-0.html.md Normal file
View File

@ -0,0 +1,33 @@
---
layout: 'docs'
page_title: 'Upgrading from Vagrant 1.0'
sidebar_current: 'installation-1-0-upgrading'
description: |-
The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is
backwards compatible 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.
---
# Upgrading From Vagrant 1.0.x
The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is quite
[backwards compatible](/docs/installation/backwards-compatibility.html)
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](/docs/installation/backwards-compatibility.html)
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 can look to see if they've been updated. If not however, you will have
to remove them before upgrading.
It is recommended you remove _all_ plugins before upgrading, and then slowly
add back the plugins. This usually makes for a smoother upgrade process.
<div class="alert alert-warning" role="alert">
<strong>If your version of Vagrant was installed via Rubygems</strong>, you
must uninstall the old version prior to installing the package for the
new version of Vagrant. The Rubygems installation is no longer supported.
</div>

35
website/pages/docs/installation/upgrading.html.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: 'docs'
page_title: 'Upgrading Vagrant'
sidebar_current: 'installation-upgrading'
description: |-
If you are upgrading from Vagrant 1.0.x, please read the specific page
dedicated to that. This page covers upgrading Vagrant in general during the
1.x series.
---
# Upgrading Vagrant
If you are upgrading from Vagrant 1.0.x, please read the
[specific page dedicated to that](/docs/installation/upgrading-from-1-0.html).
This page covers upgrading Vagrant in general during the 1.x series.
Vagrant upgrades during the 1.x release series are straightforward:
1. [Download](/downloads.html) 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.
Note that Vagrantfile stability for the new Vagrantfile syntax is not
promised until 2.0 final. So while Vagrantfiles made for 1.0.x will
[continue to work](/docs/installation/backwards-compatibility.html),
newer Vagrantfiles may have backwards incompatible changes until 2.0 final.
<div class="alert alert-info alert-block">
<strong>Run into troubles upgrading?</strong> Please
<a href="https://github.com/hashicorp/vagrant/issues" class="alert-link">report an issue</a>
if you run into problems upgrading. Upgrades are meant to be a smooth
process and we consider it a bug if it was not.
</div>

153
website/pages/docs/multi-machine/index.html.md Normal file
View File

@ -0,0 +1,153 @@
---
layout: 'docs'
page_title: 'Multi-Machine'
sidebar_current: 'multimachine'
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](/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](/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](/docs/vagrantfile/tips.html#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](/docs/networking/) options should be used.
In particular, the [private network](/docs/networking/private_network.html) 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`.

48
website/pages/docs/networking/basic_usage.html.md Normal file
View File

@ -0,0 +1,48 @@
---
layout: 'docs'
page_title: 'Basic Usage - Networking'
sidebar_current: 'networking-basic'
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](/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](/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.

122
website/pages/docs/networking/forwarded_ports.html.md Normal file
View File

@ -0,0 +1,122 @@
---
layout: 'docs'
page_title: 'Forwarded Ports - Networking'
sidebar_current: 'networking-fp'
description: |-
Vagrant forwarded ports allow you to access a port on your host machine and
have all data forwarded to a port on the guest machine, over either TCP or
UDP.
---
# Forwarded Ports
**Network identifier: `forwarded_port`**
Vagrant forwarded ports allow you to access a port on your host machine and have
all data forwarded to a port on the guest machine, over either TCP or UDP.
For example: If the guest machine is running a web server listening on port 80,
you can make a forwarded port mapping to port 8080 (or anything) on your host
machine. You can then open your browser to `localhost:8080` and browse the
website, while all actual network data is being sent to the guest.
## Defining a Forwarded Port
The forwarded port configuration expects two parameters, the port on the
guest and the port on the host. Example:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "forwarded_port", guest: 80, host: 8080
end
```
This will allow accessing port 80 on the guest via port 8080 on the host.
For most providers, forwarded ports by default bind to all interfaces. This
means that other devices on your network can access the forwarded ports.
If you want to restrict access, see the `guest_ip` and `host_ip` settings
below.
## Options Reference
This is a complete list of the options that are available for forwarded
ports. Only the `guest` and `host` options are required. Below this section,
there are more detailed examples of using these options.
- `auto_correct` (boolean) - If true, the host port will be changed
automatically in case it collides with a port already in use. By
default, this is false.
- `guest` (int) - The port on the guest that you want to be exposed on
the host. This can be any port.
- `guest_ip` (string) - The guest IP to bind the forwarded port to. If
this is not set, the port will go to every IP interface. By default,
this is empty.
- `host` (int) - The port on the host that you want to use to access the
port on the guest. This must be greater than port 1024 unless Vagrant
is running as root (which is not recommended).
- `host_ip` (string) - The IP on the host you want to bind the forwarded
port to. If not specified, it will be bound to every IP. By default,
this is empty.
- `protocol` (string) - Either "udp" or "tcp". This specifies the protocol
that will be allowed through the forwarded port. By default this is "tcp".
- `id` (string) - Name of the rule (can be visible in VirtualBox). By
default this is "protocol""guest" (example : "tcp123").
## Forwarded Port Protocols
By default, any defined port will only forward the TCP protocol. As an optional
third parameter, you may specify `protocol: 'udp'` in order to pass UDP
traffic. If a given port needs to be able to listen to the same port on both
protocols, you must define the port twice with each protocol specified, like
so:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: "tcp"
config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: "udp"
end
```
## Port Collisions and Correction
It is common when running multiple Vagrant machines to unknowingly create
forwarded port definitions that collide with each other (two separate
Vagrant projects forwarded to port 8080, for example). Vagrant includes
built-in mechanism to detect this and correct it, automatically.
Port collision detection is always done. Vagrant will not allow you to
define a forwarded port where the port on the host appears to be accepting
traffic or connections.
Port collision auto-correction must be manually enabled for each forwarded
port, since it is often surprising when it occurs and can lead the Vagrant
user to think that the port was not properly forwarded. Enabling auto correct
is easy:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "forwarded_port", guest: 80, host: 8080,
auto_correct: true
end
```
The final `:auto_correct` parameter set to true tells Vagrant to auto
correct any collisions. During a `vagrant up` or `vagrant reload`, Vagrant
will output information about any collisions detections and auto corrections
made, so you can take notice and act accordingly.
You can define allowed port range assignable by Vagrant when port collision is
detected via [config.vm.usable_port_range](/docs/vagrantfile/machine_settings.html) property.
```ruby
Vagrant.configure("2") do |config|
config.vm.usable_port_range = 8000..8999
end
```

42
website/pages/docs/networking/index.html.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: 'docs'
page_title: 'Networking'
sidebar_current: '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](/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](/docs/networking/basic_usage.html) 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](/docs/providers/configuration.html)
to do this, so please read the documentation for your specific provider
to see what options are available.
<div class="alert alert-info">
<strong>For beginners:</strong> 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.
</div>

126
website/pages/docs/networking/private_network.html.md Normal file
View File

@ -0,0 +1,126 @@
---
layout: 'docs'
page_title: 'Private Networks - Networking'
sidebar_current: 'networking-private'
description: |-
Vagrant private networks allow you to access your guest machine by some
address that is not publicly accessible from the global internet. In general,
this means your machine gets an address in the private address space.
---
# Private Networks
**Network identifier: `private_network`**
Vagrant private networks allow you to access your guest machine by some address
that is not publicly accessible from the global internet. In general, this
means your machine gets an address in the [private address space](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces).
Multiple machines within the same private network (also usually with the
restriction that they're backed by the same [provider](/docs/providers/))
can communicate with each other on private networks.
<div class="alert alert-info">
<strong>Guest operating system support.</strong> Private networks
generally require configuring the network adapters on the guest
machine. This process varies from OS to OS. Vagrant ships with
knowledge of how to configure networks on a variety of guest
operating systems, but it is possible if you are using a particularly
old or new operating system that private networks will not properly
configure.
</div>
## DHCP
The easiest way to use a private network is to allow the IP to be assigned
via DHCP.
```ruby
Vagrant.configure("2") do |config|
config.vm.network "private_network", type: "dhcp"
end
```
This will automatically assign an IP address from the reserved address space.
The IP address can be determined by using `vagrant ssh` to SSH into the
machine and using the appropriate command line tool to find the IP,
such as `ifconfig`.
## Static IP
You can also specify a static IP address for the machine. This lets you
access the Vagrant managed machine using a static, known IP. The
Vagrantfile for a static IP looks like this:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "private_network", ip: "192.168.50.4"
end
```
It is up to the users to make sure that the static IP does not collide
with any other machines on the same network.
While you can choose any IP you would like, you _should_ use an IP from
the [reserved private address space](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces). These IPs are guaranteed to never be publicly routable,
and most routers actually block traffic from going to them from the
outside world.
For some operating systems, additional configuration options for the static
IP address are available such as setting the default gateway or MTU.
<div class="alert alert-warning">
<strong>Warning!</strong> Do not choose an IP that overlaps with any
other IP space on your system. This can cause the network to not be
reachable.
</div>
## IPv6
You can specify a static IP via IPv6. DHCP for IPv6 is not supported.
To use IPv6, just specify an IPv6 address as the IP:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "private_network", ip: "fde4:8dba:82e1::c4"
end
```
This will assign that IP to the machine. The entire `/64` subnet will
be reserved. Please make sure to use the reserved local addresses approved
for IPv6.
You can also modify the prefix length by changing the `netmask` option
(defaults to 64):
```ruby
Vagrant.configure("2") do |config|
config.vm.network "private_network",
ip: "fde4:8dba:82e1::c4",
netmask: "96"
end
```
IPv6 supports for private networks was added in Vagrant 1.7.5 and may
not work with every provider.
## Disable Auto-Configuration
If you want to manually configure the network interface yourself, you
can disable Vagrant's auto-configure feature by specifying `auto_config`:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "private_network", ip: "192.168.50.4",
auto_config: false
end
```
If you already started the Vagrant environment before setting `auto_config`,
the files it initially placed there will stay there. You will have to remove
those files manually or destroy and recreate the machine.
The files created by Vagrant depend on the OS. For example, for many
Linux distros, this is `/etc/network/interfaces`. In general you should
look in the normal location that network interfaces are configured for your
distro.

162
website/pages/docs/networking/public_network.html.md Normal file
View File

@ -0,0 +1,162 @@
---
layout: 'docs'
page_title: 'Public Networks - Networking'
sidebar_current: 'networking-public'
description: |-
Vagrant public networks are less private than private networks, and the exact
meaning actually varies from provider to provider, hence the ambiguous
definition. The idea is that while private networks should never allow the
general public access to your machine, public networks can.
---
# Public Networks
**Network identifier: `public_network`**
Vagrant public networks are less private than private networks, and the exact
meaning actually varies from [provider to provider](/docs/providers/),
hence the ambiguous definition. The idea is that while
[private networks](/docs/networking/private_network.html) should never allow the
general public access to your machine, public networks can.
<div class="alert alert-info">
<strong>Confused?</strong> We kind of are, too. It is likely that
public networks will be replaced by <code>:bridged</code> in a
future release, since that is in general what should be done with
public networks, and providers that do not support bridging generally
do not have any other features that map to public networks either.
</div>
<div class="alert alert-warning">
<strong>Warning!</strong> Vagrant boxes are insecure by default
and by design, featuring public passwords, insecure keypairs
for SSH access, and potentially allow root access over SSH. With
these known credentials, your box is easily accessible by anyone on
your network. Before configuring Vagrant to use a public network,
consider <em>all</em> potential security implications
and review the <a href="/docs/boxes/base.html">default box
configuration</a> to identify potential security risks.
</div>
## DHCP
The easiest way to use a public network is to allow the IP to be assigned
via DHCP. In this case, defining a public network is trivially easy:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "public_network"
end
```
When DHCP is used, the IP can be determined by using `vagrant ssh` to
SSH into the machine and using the appropriate command line tool to find
the IP, such as `ifconfig`.
### Using the DHCP Assigned Default Route
Some cases require the DHCP assigned default route to be untouched. In these cases one
may specify the `use_dhcp_assigned_default_route` option. As an example:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "public_network",
use_dhcp_assigned_default_route: true
end
```
## Static IP
Depending on your setup, you may wish to manually set the IP of your
bridged interface. To do so, add a `:ip` clause to the network definition.
```ruby
config.vm.network "public_network", ip: "192.168.0.17"
```
## Default Network Interface
If more than one network interface is available on the host machine, Vagrant will
ask you to choose which interface the virtual machine should bridge to. A default
interface can be specified by adding a `:bridge` clause to the network definition.
```ruby
config.vm.network "public_network", bridge: "en1: Wi-Fi (AirPort)"
```
The string identifying the desired interface must exactly match the name of an
available interface. If it cannot be found, Vagrant will ask you to pick
from a list of available network interfaces.
With some providers, it is possible to specify a list of adapters to bridge
against:
```ruby
config.vm.network "public_network", bridge: [
"en1: Wi-Fi (AirPort)",
"en6: Broadcom NetXtreme Gigabit Ethernet Controller",
]
```
In this example, the first network adapter that exists and can successfully be
bridge will be used.
## Disable Auto-Configuration
If you want to manually configure the network interface yourself, you
can disable auto-configuration by specifying `auto_config`:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "public_network", auto_config: false
end
```
Then the shell provisioner can be used to configure the ip of the interface:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "public_network", auto_config: false
# manual ip
config.vm.provision "shell",
run: "always",
inline: "ifconfig eth1 192.168.0.17 netmask 255.255.255.0 up"
# manual ipv6
config.vm.provision "shell",
run: "always",
inline: "ifconfig eth1 inet6 add fc00::17/7"
end
```
## Default Router
Depending on your setup, you may wish to manually override the default
router configuration. This is required if you need to access the Vagrant box from
other networks over the public network. To do so, you can use a shell
provisioner script:
```ruby
Vagrant.configure("2") do |config|
config.vm.network "public_network", ip: "192.168.0.17"
# default router
config.vm.provision "shell",
run: "always",
inline: "route add default gw 192.168.0.1"
# default router ipv6
config.vm.provision "shell",
run: "always",
inline: "route -A inet6 add default gw fc00::1 eth1"
# delete default gw on eth0
config.vm.provision "shell",
run: "always",
inline: "eval `route -n | awk '{ if ($8 ==\"eth0\" && $2 != \"0.0.0.0\") print \"route del default gw \" $2; }'`"
end
```
Note the above is fairly complex and may be guest OS specific, but we
document the rough idea of how to do it because it is a common question.

70
website/pages/docs/other/debugging.html.md Normal file
View File

@ -0,0 +1,70 @@
---
layout: 'docs'
page_title: 'Debugging and Troubleshooting'
sidebar_current: 'other-debugging'
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:
```
$ VAGRANT_LOG=info vagrant up
```
On Windows, multiple steps are required:
```
$ set VAGRANT_LOG=info
$ vagrant up
```
You can also get the debug level output using the `--debug` command line
option. For example:
```
$ 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 `&>`:
```
$ vagrant up --debug &> vagrant.log
```
On Windows in PowerShell (outputs to log and screen):
```
$ vagrant up --debug 2>&1 | Tee-Object -FilePath ".\vagrant.log"
```

321
website/pages/docs/other/environmental-variables.html.md Normal file
View File

@ -0,0 +1,321 @@
---
layout: 'docs'
page_title: 'Environmental Variables'
sidebar_current: 'other-envvars'
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.](/docs/synced-folders/virtualbox.html#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_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_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_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.

16
website/pages/docs/other/index.html.md Normal file
View File

@ -0,0 +1,16 @@
---
layout: 'docs'
page_title: 'Other'
sidebar_current: '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](/docs/other/debugging.html)
- [Environment Variables](/docs/other/environmental-variables.html)

32
website/pages/docs/other/macos-catalina.html.md Normal file
View File

@ -0,0 +1,32 @@
---
layout: 'docs'
page_title: 'Vagrant and macOS Catalina'
sidebar_current: 'other-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.

135
website/pages/docs/other/wsl.html.md Normal file
View File

@ -0,0 +1,135 @@
---
layout: 'docs'
page_title: 'Vagrant and Windows Subsystem for Linux'
sidebar_current: 'other-wsl'
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_.
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> 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.
</div>
## 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:
```
$ 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:
```
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:
```
$ 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`:
```
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:
```
vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375
```

83
website/pages/docs/plugins/action-hooks.html.md Normal file
View File

@ -0,0 +1,83 @@
---
layout: 'docs'
page_title: 'Plugin Development Basics - Action Hooks'
sidebar_current: 'plugins-action-hooks'
description: |-
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
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.
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## Public Action Hooks
The following action hooks are available in the core of Vagrant. Please note
that this list is not exhaustive and additional hooks can be added via plugins.
- `environment_plugins_loaded` - called after the plugins have been loaded,
but before the configurations, provisioners, providers, etc. are loaded.
* `environment_load` - called after the environment and all configurations are
fully loaded.
- `environment_unload` - called after the environment is done being used. The
environment should not be used in this hook.
* `machine_action_boot` - called after the hypervisor has reported the machine
was booted.
- `machine_action_config_validate` - called after all `Vagrantfile`s have been
loaded, merged, and validated.
* `machine_action_destroy` - called after the hypervisor has reported the
virtual machine is down.
- `machine_action_halt` - called after the hypervisor has moved the machine
into a halted state (usually "stopped" but not "terminated").
* `machine_action_package` - called after Vagrant has successfully packaged a
new box.
- `machine_action_provision` - called after all provisioners have executed.
* `machine_action_read_state` - called after Vagrant has loaded state from
disk and the hypervisor.
- `machine_action_reload` - called after a virtual machine is reloaded (varies
by hypervisor).
* `machine_action_resume` - called after a virtual machine is moved from the
halted to up state.
- `machine_action_run_command` - called after a command is executed on the
machine.
* `machine_action_ssh` - called after an SSH connection has been established.
- `machine_action_ssh_run` - called after an SSH command is executed.
* `machine_action_start` - called after the machine has been started.
- `machine_action_suspend` - called after the machine has been suspended.
* `machine_action_sync_folders` - called after synced folders have been set up.
- `machine_action_up` - called after the machine has entered the up state.
## Private API
You may find additional action hooks if you browse the Vagrant source code, but
only the list of action hooks here are guaranteed to persist between Vagrant
releases. Please do not rely on the internal API as it is subject to change
without notice.

135
website/pages/docs/plugins/commands.html.md Normal file
View File

@ -0,0 +1,135 @@
---
layout: 'docs'
page_title: 'Command Plugins - Plugin Development'
sidebar_current: 'plugins-commands'
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](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## 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.

208
website/pages/docs/plugins/configuration.html.md Normal file
View File

@ -0,0 +1,208 @@
---
layout: 'docs'
page_title: 'Custom Configuration - Plugin Development'
sidebar_current: 'plugins-configuration'
description: |-
This page documents how to add new configuration options to Vagrant,
settable with "config.YOURKEY" in Vagrantfiles. Prior to reading this,
you should be familiar with the plugin development basics.
---
# Plugin Development: Configuration
This page documents how to add new configuration options to Vagrant,
settable with `config.YOURKEY` in Vagrantfiles. Prior to reading this,
you should be familiar with the
[plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## Definition Component
Within the context of a plugin definition, new configuration keys can be defined
like so:
```ruby
config "foo" do
require_relative "config"
Config
end
```
Configuration keys are defined with the `config` method, which takes as an
argument the name of the configuration variable as the argument. This
means that the configuration object will be accessible via `config.foo`
in Vagrantfiles. Then, the block argument returns a class that implements
the `Vagrant.plugin(2, :config)` interface.
## Implementation
Implementations of configuration keys should subclass `Vagrant.plugin(2, :config)`,
which is a Vagrant method that will return the proper subclass for a version
2 configuration section. The implementation is very simple, and acts mostly
as a plain Ruby object. Here is an example:
```ruby
class Config < Vagrant.plugin(2, :config)
attr_accessor :widgets
def initialize
@widgets = UNSET_VALUE
end
def finalize!
@widgets = 0 if @widgets == UNSET_VALUE
end
end
```
When using this configuration class, it looks like the following:
```ruby
Vagrant.configure("2") do |config|
# ...
config.foo.widgets = 12
end
```
Easy. The only odd thing is the `UNSET_VALUE` bits above. This is actually
so that Vagrant can properly automatically merge multiple configurations.
Merging is covered in the next section, and `UNSET_VALUE` will be explained
there.
## Merging
Vagrant works by loading [multiple Vagrantfiles and merging them](/docs/vagrantfile/#load-order).
This merge logic is built-in to configuration classes. When merging two
configuration objects, we will call them "old" and "new", it'll by default
take all the instance variables defined on "new" that are not `UNSET_VALUE`
and set them onto the merged result.
The reason `UNSET_VALUE` is used instead of Ruby's `nil` is because
it is possible that you want the default to be some value, and the user
actually wants to set the value to `nil`, and it is impossible for Vagrant
to automatically determine whether the user set the instance variable, or
if it was defaulted as nil.
This merge logic is what you want almost every time. Hence, in the example
above, `@widgets` is set to `UNSET_VALUE`. If we had two Vagrant configuration
objects in the same file, then Vagrant would properly merge the follows.
The example below shows this:
```ruby
Vagrant.configure("2") do |config|
config.widgets = 1
end
Vagrant.configure("2") do |config|
# ... other stuff
end
Vagrant.configure("2") do |config|
config.widgets = 2
end
```
If this were placed in a Vagrantfile, after merging, the value of widgets
would be "2".
The `finalize!` method is called only once ever on the final configuration
object in order to set defaults. If `finalize!` is called, that configuration
will never be merged again, it is final. This lets you detect any `UNSET_VALUE`
and set the proper default, as we do in the above example.
Of course, sometimes you want custom merge logic. Let us say we
wanted our widgets to be additive. We can override the `merge` method to
do this:
```ruby
class Config < Vagrant.config("2", :config)
attr_accessor :widgets
def initialize
@widgets = 0
end
def merge(other)
super.tap do |result|
result.widgets = @widgets + other.widgets
end
end
end
```
In this case, we did not use `UNSET_VALUE` for widgets because we did not
need that behavior. We default to 0 and always merge by summing the
two widgets. Now, if we ran the example above that had the 3 configuration
blocks, the final value of widgets would be "3".
## Validation
Configuration classes are also responsible for validating their own
values. Vagrant will call the `validate` method to do this. An example
validation method is shown below:
```ruby
class Config < Vagrant.plugin("2", :config)
# ...
def validate(machine)
errors = _detected_errors
if @widgets <= 5
errors << "widgets must be greater than 5"
end
{ "foo" => errors }
end
end
```
The validation method is given a `machine` object, since validation is
done for each machine that Vagrant is managing. This allows you to
conditionally validate some keys based on the state of the machine and so on.
The `_detected_errors` method returns any errors already detected by Vagrant,
such as unknown configuration keys. This returns an array of error messages,
so be sure to turn it into the proper Hash object to return later.
The return value is a Ruby Hash object, where the key is a section name,
and the value is a list of error messages. These will be displayed by
Vagrant. The hash must not contain any values if there are no errors.
## Accessing
After all the configuration options are merged and finalized, you will likely
want to access the finalized value in your plugin. The initializer function
varies with each type of plugin, but _most_ plugins expose an initializer like
this:
```ruby
def initialize(machine, config)
@machine = machine
@config = config
end
```
When authoring a plugin, simply call `super` in your initialize function to
setup these instance variables:
```ruby
def initialize(*)
super
@config.is_now_available
# ...existing code
end
def my_helper
@config.is_here_too
end
```
For examples, take a look at Vagrant's own internal plugins in the `plugins`
folder in Vagrant's source on GitHub.

181
website/pages/docs/plugins/development-basics.html.md Normal file
View File

@ -0,0 +1,181 @@
---
layout: 'docs'
page_title: 'Plugin Development Basics - Plugins'
sidebar_current: 'plugins-development-basics'
description: |-
Plugins are a great way to augment or change the behavior and functionality
of Vagrant. Since plugins introduce additional external dependencies for
users, they should be used as a last resort when attempting to
do something with Vagrant.
---
# Plugin Development Basics
Plugins are a great way to augment or change the behavior and functionality
of Vagrant. Since plugins introduce additional external dependencies for
users, they should be used as a last resort when attempting to
do something with Vagrant.
But if you need to introduce custom behaviors
into Vagrant, plugins are the best way, since they are safe against future
upgrades and use a stable API.
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
Plugins are written using [Ruby](https://www.ruby-lang.org/en/) and are packaged
using [RubyGems](https://rubygems.org/). Familiarity with Ruby is required,
but the [packaging and distribution](/docs/plugins/packaging.html) section should help
guide you to packaging your plugin into a RubyGem.
## Setup and Workflow
Because plugins are packaged as RubyGems, Vagrant plugins should be
developed as if you were developing a regular RubyGem. The easiest
way to do this is to use the `bundle gem` command.
Once the directory structure for a RubyGem is setup, you will want
to modify your Gemfile. Here is the basic structure of a Gemfile for
Vagrant plugin development:
```ruby
source "https://rubygems.org"
group :development do
gem "vagrant", git: "https://github.com/hashicorp/vagrant.git"
end
group :plugins do
gem "my-vagrant-plugin", path: "."
end
```
This Gemfile gets "vagrant" for development. This allows you to
`bundle exec vagrant` to run Vagrant with your plugin already loaded,
so that you can test it manually that way.
The only thing about this Gemfile that may stand out as odd is the
"plugins" group and putting your plugin in that group. Because
`vagrant plugin` commands do not work in development, this is how
you "install" your plugin into Vagrant. Vagrant will automatically
load any gems listed in the "plugins" group. Note that this also
allows you to add multiple plugins to Vagrant for development, if
your plugin works with another plugin.
When you want to manually test your plugin, use
`bundle exec vagrant` in order to run Vagrant with your plugin
loaded (as we specified in the Gemfile).
## Plugin Definition
All plugins are required to have a definition. A definition contains details
about the plugin such as the name of it and what components it contains.
A definition at the bare minimum looks like the following:
```ruby
class MyPlugin < Vagrant.plugin("2")
name "My Plugin"
end
```
A definition is a class that inherits from `Vagrant.plugin("2")`. The "2"
there is the version that the plugin is valid for. API stability is only
promised for each major version of Vagrant, so this is important. (The
1.x series is working towards 2.0, so the API version is "2")
**The most critical feature of a plugin definition** is that it must _always_
load, no matter what version of Vagrant is running. Theoretically, Vagrant
version 87 (does not actually exist) would be able to load a version 2 plugin
definition. This is achieved through clever lazy loading of individual components
of the plugin, and is covered shortly.
## Plugin Components
Within the definition, a plugin advertises what components it adds to
Vagrant. An example is shown below where a command and provisioner are
added:
```ruby
class MyPlugin < Vagrant.plugin("2")
name "My Plugin"
command "run-my-plugin" do
require_relative "command"
Command
end
provisioner "my-provisioner" do
require_relative "provisioner"
Provisioner
end
end
```
Let us go over the major pieces of what is going on here. Note from a general
Ruby language perspective the above _should_ be familiar. The syntax should
not scare you. If it does, then please familiarize with Ruby further before
attempting to write a plugin.
The first thing to note is that individual components are defined by
making a method call with the component name, such as `command` or
`provisioner`. These in turn take some parameters. In the case of our
example it is just the name of the command and the name of the provisioner.
All component definitions then take a block argument (a callback) that
must return the actual component implementation class.
The block argument is where the "clever lazy loading" (mentioned above)
comes into play. The component blocks should lazy load the actual file that
contains the implementation of the component, and then return that component.
This is done because the actual dependencies and APIs used when defining
components are not stable across major Vagrant versions. A command implementation
written for Vagrant 2.0 will not be compatible with Vagrant 3.0 and so on. But
the _definition_ is just plain Ruby that must always be forward compatible
to future Vagrant versions.
To repeat, **the lazy loading aspect of plugin components is critical**
to the way Vagrant plugins work. All components must be lazily loaded
and returned within their definition blocks.
Now, each component has a different API. Please visit the relevant section
using the navigation to the left under "Plugins" to learn more about developing
each type of component.
## Error Handling
One of Vagrant's biggest strength is gracefully handling errors and reporting
them in human-readable ways. Vagrant has always strongly believed that if
a user sees a stack trace, it is a bug. It is expected that plugins will behave
the same way, and Vagrant provides strong error handling mechanisms to
assist with this.
Error handling in Vagrant is done entirely by raising Ruby exceptions.
But Vagrant treats certain errors differently than others. If an error
is raised that inherits from `Vagrant::Errors::VagrantError`, then the
`vagrant` command will output the message of the error in nice red text
to the console and exit with an exit status of 1.
Otherwise, Vagrant reports an "unexpected error" that should be reported
as a bug, and shows a full stack trace and other ugliness. Any stack traces
should be considered bugs.
Therefore, to fit into Vagrant's error handling mechanisms, subclass
`VagrantError` and set a proper message on your exception. To see
examples of this, look at Vagrant's [built-in errors](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/errors.rb).
## Console Input and Output
Most plugins are likely going to want to do some sort of input/output.
Plugins should _never_ use Ruby's built-in `puts` or `gets` style methods.
Instead, all input/output should go through some sort of Vagrant UI object.
The Vagrant UI object properly handles cases where there is no TTY, output
pipes are closed, there is no input pipe, etc.
A UI object is available on every `Vagrant::Environment` via the `ui` property
and is exposed within every middleware environment via the `:ui` key. UI
objects have [decent documentation](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/ui.rb)
within the comments of their source.

104
website/pages/docs/plugins/guest-capabilities.html.md Normal file
View File

@ -0,0 +1,104 @@
---
layout: 'docs'
page_title: 'Guest Capabilities - Plugin Development'
sidebar_current: 'plugins-guestcapabilities'
description: |-
This page documents how to add new capabilities for guests to Vagrant,
allowing Vagrant to perform new actions on specific guest operating systems.
Prior to reading this, you should be familiar with the plugin development
basics.
---
# Plugin Development: Guest Capabilities
This page documents how to add new capabilities for [guests](/docs/plugins/guests.html)
to Vagrant, allowing Vagrant to perform new actions on specific guest
operating systems.
Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
Guest capabilities augment [guests](/docs/plugins/guests.html) by attaching
specific "capabilities" to the guest, which are actions that can be performed
in the context of that guest operating system.
The power of capabilities is that plugins can add new capabilities to
existing guest operating systems without modifying the core of Vagrant.
In earlier versions of Vagrant, all the guest logic was contained in the
core of Vagrant and was not easily augmented.
## Definition Component
Within the context of a plugin definition, guest capabilities can be
defined like so:
```ruby
guest_capability "ubuntu", "my_custom_capability" do
require_relative "cap/my_custom_capability"
Cap::MyCustomCapability
end
```
Guest capabilities are defined by calling the `guest_capability` method,
which takes two parameters: the guest to add the capability to, and the
name of the capability itself. Then, the block argument returns a class
that implements a method named the same as the capability. This is
covered in more detail in the next section.
## Implementation
Implementations should be classes or modules that have a method with
the same name as the capability. The method must be immediately accessible
on the class returned from the `guest_capability` component, meaning that
if it is an instance method, an instance should be returned.
In general, class methods are used for capabilities. For example, here
is the implementation for the capability above:
```ruby
module Cap
class MyCustomCapability
def self.my_custom_capability(machine)
# implementation
end
end
end
```
All capabilities get the Vagrant machine object as the first argument.
Additional arguments are determined by the specific capability, so view the
documentation or usage of the capability you are trying to implement for more
information.
Some capabilities must also return values back to the caller, so be aware
of that when implementing a capability.
Capabilities always have access to communication channels such as SSH
on the machine, and the machine can generally be assumed to be booted.
## Calling Capabilities
Since you have access to the machine in every capability, capabilities can
also call _other_ capabilities. This is useful for using the inheritance
mechanism of capabilities to potentially ask helpers for more information.
For example, the "redhat" guest has a "network_scripts_dir" capability that
simply returns the directory where networking scripts go.
Capabilities on child guests of RedHat such as CentOS or Fedora use this
capability to determine where networking scripts go, while sometimes overriding
it themselves.
Capabilities can be called like so:
```ruby
machine.guest.capability(:capability_name)
```
Any additional arguments given to the method will be passed on to the
capability, and the capability will return the value that the actual
capability returned.

102
website/pages/docs/plugins/guests.html.md Normal file
View File

@ -0,0 +1,102 @@
---
layout: 'docs'
page_title: 'Custom Guests - Plugin Development'
sidebar_current: 'plugins-guests'
description: |-
This page documents how to add new guest OS detection to Vagrant, allowing
Vagrant to properly configure new operating systems. Prior to reading this,
you should be familiar with the plugin development basics.
---
# Plugin Development: Guests
This page documents how to add new guest OS detection to Vagrant, allowing
Vagrant to properly configure new operating systems.
Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
Vagrant has many features that requires doing guest OS-specific
actions, such as mounting folders, configuring networks, etc. These
tasks vary from operating system to operating system. If you find that
one of these does not work for your operating system, then maybe the
guest implementation is incomplete or incorrect.
## Definition Component
Within the context of a plugin definition, new guests can be defined
like so:
```ruby
guest "ubuntu" do
require_relative "guest"
Guest
end
```
Guests are defined with the `guest` method. The first argument is the
name of the guest. This name is not actually used anywhere, but may in the
future, so choose something helpful. Then, the block argument returns a
class that implements the `Vagrant.plugin(2, :guest)` interface.
## Implementation
Implementations of guests subclass `Vagrant.plugin("2", "guest")`. Within
this implementation, only the `detect?` method needs to be implemented.
The `detect?` method is called by Vagrant at some point after the machine
is booted in order to determine what operating system the guest is running.
If you detect that it is your operating system, return `true` from `detect?`.
Otherwise, return `false`.
Communication channels to the machine are guaranteed to be running at this
point, so the most common way to detect the operating system is to do
some basic testing:
```ruby
class MyGuest < Vagrant.plugin("2", "guest")
def detect?(machine)
machine.communicate.test("cat /etc/myos-release")
end
end
```
After detecting an OS, that OS is used for various
[guest capabilities](/docs/plugins/guest-capabilities.html) that may be
required.
## Guest Inheritance
Vagrant also supports a form of inheritance for guests, since sometimes
operating systems stem from a common root. A good example of this is Linux
is the root of Debian, which further is the root of Ubuntu in many cases.
Inheritance allows guests to share a lot of common behavior while allowing
distro-specific overrides.
Inheritance is not done via standard Ruby class inheritance because Vagrant
uses a custom [capability-based](/docs/plugins/guest-capabilities.html) system.
Vagrant handles inheritance dispatch for you.
To subclass another guest, specify that guest's name as a second parameter
in the guest definition:
```ruby
guest "ubuntu", "debian" do
require_relative "guest"
Guest
end
```
With the above component, the "ubuntu" guest inherits from "debian." When
a capability is looked up for "ubuntu", all capabilities from "debian" are
also available, and any capabilities in "ubuntu" override parent capabilities.
When detecting operating systems with `detect?`, Vagrant always does a
depth-first search by searching the children operating systems before
checking their parents. Therefore, it is guaranteed in the above example
that the `detect?` method on "ubuntu" will be called before "debian."

64
website/pages/docs/plugins/host-capabilities.html.md Normal file
View File

@ -0,0 +1,64 @@
---
layout: 'docs'
page_title: 'Host Capabilities - Plugin Development'
sidebar_current: 'plugins-hostcapabilities'
description: |-
This page documents how to add new capabilities for hosts to Vagrant, allowing Vagrant to perform new actions on specific host operating systems. Prior to reading this, you should be familiar with the plugin development basics.
---
# Plugin Development: Host Capabilities
This page documents how to add new capabilities for [hosts](/docs/plugins/hosts.html)
to Vagrant, allowing Vagrant to perform new actions on specific host
operating systems.
Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
Host capabilities augment [hosts](/docs/plugins/hosts.html) by attaching
specific "capabilities" to the host, which are actions that can be performed
in the context of that host operating system.
The power of capabilities is that plugins can add new capabilities to
existing host operating systems without modifying the core of Vagrant.
In earlier versions of Vagrant, all the host logic was contained in the
core of Vagrant and was not easily augmented.
## Definition and Implementation
The definition and implementation of host capabilities is identical
to [guest capabilities](/docs/plugins/guest-capabilities.html).
The main difference from guest capabilities, however, is that instead of
taking a machine as the first argument, all host capabilities take an
instance of `Vagrant::Environment` as their first argument.
Access to the environment allows host capabilities to access global state,
specific machines, and also allows them to call other host capabilities.
## Calling Capabilities
Since you have access to the environment in every capability, capabilities can
also call _other_ host capabilities. This is useful for using the inheritance
mechanism of capabilities to potentially ask helpers for more information.
For example, the "linux" guest has a "nfs_check_command" capability that
returns the command to use to check if NFS is running.
Capabilities on child guests of Linux such as RedHat or Arch use this
capability to mostly inherit the Linux behavior, except for this minor
detail.
Capabilities can be called like so:
```ruby
environment.host.capability(:capability_name)
```
Any additional arguments given to the method will be passed on to the
capability, and the capability will return the value that the actual
capability returned.

99
website/pages/docs/plugins/hosts.html.md Normal file
View File

@ -0,0 +1,99 @@
---
layout: 'docs'
page_title: 'Custom Hosts - Plugin Development'
sidebar_current: 'plugins-hosts'
description: |-
This page documents how to add new host OS detection to Vagrant, allowing
Vagrant to properly execute host-specific operations on new operating systems.
Prior to reading this, you should be familiar with the plugin development
basics.
---
# Plugin Development: Hosts
This page documents how to add new host OS detection to Vagrant, allowing
Vagrant to properly execute host-specific operations on new operating systems.
Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
Vagrant has some features that require host OS-specific actions, such as
exporting NFS folders. These tasks vary from operating system to operating
system. Vagrant uses host detection as well as
[host capabilities](/docs/plugins/host-capabilities.html) to perform these
host OS-specific operations.
## Definition Component
Within the context of a plugin definition, new hosts can be defined
like so:
```ruby
host "ubuntu" do
require_relative "host"
Host
end
```
Hosts are defined with the `host` method. The first argument is the
name of the host. This name is not actually used anywhere, but may in the
future, so choose something helpful. Then, the block argument returns a
class that implements the `Vagrant.plugin(2, :host)` interface.
## Implementation
Implementations of hosts subclass `Vagrant.plugin("2", "host")`. Within
this implementation, only the `detect?` method needs to be implemented.
The `detect?` method is called by Vagrant very early on in its initialization
process to determine if the OS that Vagrant is running on is this host.
If you detect that it is your operating system, return `true` from `detect?`.
Otherwise, return `false`.
```ruby
class MyHost < Vagrant.plugin("2", "host")
def detect?(environment)
File.file?("/etc/arch-release")
end
end
```
After detecting an OS, that OS is used for various
[host capabilities](/docs/plugins/host-capabilities.html) that may be
required.
## Host Inheritance
Vagrant also supports a form of inheritance for hosts, since sometimes
operating systems stem from a common root. A good example of this is Linux
is the root of Debian, which further is the root of Ubuntu in many cases.
Inheritance allows hosts to share a lot of common behavior while allowing
distro-specific overrides.
Inheritance is not done via standard Ruby class inheritance because Vagrant
uses a custom [capability-based](/docs/plugins/host-capabilities.html) system.
Vagrant handles inheritance dispatch for you.
To subclass another host, specify that host's name as a second parameter
in the host definition:
```ruby
host "ubuntu", "debian" do
require_relative "host"
Host
end
```
With the above component, the "ubuntu" host inherits from "debian." When
a capability is looked up for "ubuntu", all capabilities from "debian" are
also available, and any capabilities in "ubuntu" override parent capabilities.
When detecting operating systems with `detect?`, Vagrant always does a
depth-first search by searching the children operating systems before
checking their parents. Therefore, it is guaranteed in the above example
that the `detect?` method on "ubuntu" will be called before "debian."

27
website/pages/docs/plugins/index.html.md Normal file
View File

@ -0,0 +1,27 @@
---
layout: 'docs'
page_title: 'Plugins'
sidebar_current: 'plugins'
description: |-
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
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.
In fact, most of the core of Vagrant is [implemented using plugins](https://github.com/hashicorp/vagrant/tree/master/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.

114
website/pages/docs/plugins/packaging.html.md Normal file
View File

@ -0,0 +1,114 @@
---
layout: 'docs'
page_title: 'Packaging and Distribution - Plugin Development'
sidebar_current: 'plugins-packaging'
description: |-
This page documents how to organize the file structure of your plugin
and distribute it so that it is installable using standard installation
methods. Prior to reading this, you should be familiar with the plugin
development basics.
---
# Plugin Development: Packaging & Distribution
This page documents how to organize the file structure of your plugin
and distribute it so that it is installable using
[standard installation methods](/docs/plugins/usage.html).
Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## Example Plugin
The best way to describe packaging and distribution is to look at
how another plugin does it. The best example plugin available for this
is [vagrant-aws](https://github.com/mitchellh/vagrant-aws).
By using [Bundler](http://bundler.io) and Rake, building a new
vagrant-aws package is easy. By simply calling `rake package`, a
`gem` file is dropped into the directory. By calling `rake release`,
the gem is built and it is uploaded to the central [RubyGems](https://rubygems.org)
repository so that it can be installed using `vagrant plugin install`.
Your plugin can and should be this easy, too, since you basically
get this for free by using Bundler.
## Setting Up Your Project
To setup your project, run `bundle gem vagrant-my-plugin`. This will create a
`vagrant-my-plugin` directory that has the initial layout to be a RubyGem.
You should modify the `vagrant-my-plugin.gemspec` file to add any
dependencies and change any metadata. View the [vagrant-aws.gemspec](https://github.com/mitchellh/vagrant-aws/blob/master/vagrant-aws.gemspec)
for a good example.
<div class="alert alert-warning">
<p>
<strong>Do not depend on Vagrant</strong> for your gem. Vagrant
is no longer distributed as a gem, and you can assume that it will
always be available when your plugin is installed.
</p>
</div>
Once the directory structure for a RubyGem is setup, you will want
to modify your Gemfile. Here is the basic structure of a Gemfile for
Vagrant plugin development:
```ruby
source "https://rubygems.org"
group :development do
gem "vagrant", git: "https://github.com/hashicorp/vagrant.git"
end
group :plugins do
gem "my-vagrant-plugin", path: "."
end
```
This Gemfile gets "vagrant" for development. This allows you to
`bundle exec vagrant` to run Vagrant with your plugin already loaded,
so that you can test it manually that way.
The only thing about this Gemfile that may stand out as odd is the
"plugins" group and putting your plugin in that group. Because
`vagrant plugin` commands do not work in development, this is how
you "install" your plugin into Vagrant. Vagrant will automatically
load any gems listed in the "plugins" group. Note that this also
allows you to add multiple plugins to Vagrant for development, if
your plugin works with another plugin.
Next, create a `Rakefile` that has at the very least, the following
contents:
```ruby
require "rubygems"
require "bundler/setup"
Bundler::GemHelper.install_tasks
```
If you run `rake -T` now, which lists all the available rake tasks,
you should see that you have the `package` and `release` tasks. You
can now develop your plugin and build it!
You can view the [vagrant-aws Rakefile](https://github.com/mitchellh/vagrant-aws/blob/master/Rakefile)
for a more comprehensive example that includes testing.
## Testing Your Plugin
To manually test your plugin during development, use
`bundle exec vagrant` to execute Vagrant with your plugin loaded
(thanks to the Gemfile setup we did earlier).
For automated testing, the
[vagrant-spec](https://github.com/hashicorp/vagrant-spec)
project provides helpers for both unit and acceptance testing
plugins. See the giant README for that project for a detailed
description of how to integrate vagrant-spec into your project.
Vagrant itself (and all of its core plugins) use vagrant-spec
for automated testing.

237
website/pages/docs/plugins/providers.html.md Normal file
View File

@ -0,0 +1,237 @@
---
layout: 'docs'
page_title: 'Custom Providers - Plugin Development'
sidebar_current: 'plugins-providers'
description: |-
This page documents how to add support for new providers to Vagrant, allowing
Vagrant to run and manage machines powered by a system other than VirtualBox.
Prior to reading this, you should be familiar with the plugin development
basics.
---
# Plugin Development: Providers
This page documents how to add support for new [providers](/docs/providers/)
to Vagrant, allowing Vagrant to run and manage machines powered by a
system other than VirtualBox. Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
Prior to developing a provider you should also be familiar with how
[providers work](/docs/providers/) from
a user standpoint.
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## Example Provider: AWS
The best way to learn how to write a provider is to see how one is
written in practice. To augment this documentation, please heavily
study the [vagrant-aws](https://github.com/mitchellh/vagrant-aws) plugin,
which implements an AWS provider. The plugin is a good example of how to
structure, test, and implement your plugin.
## Definition Component
Within the context of a plugin definition, new providers are defined
like so:
```ruby
provider "my_cloud" do
require_relative "provider"
Provider
end
```
Providers are defined with the `provider` method, which takes a single
argument specifying the name of the provider. This is the name that is
used with `vagrant up` to specify the provider. So in the case above,
our provider would be used by calling `vagrant up --provider=my_cloud`.
The block argument then lazily loads and returns a class that
implements the `Vagrant.plugin(2, :provider)` interface, which is covered
next.
## Provider Class
The provider class should subclass and implement
`Vagrant.plugin(2, :provider)` which is an upgrade-safe way to let Vagrant
return the proper parent class.
This class and the methods that need to be implemented are
[very well documented](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provider.rb). The documentation done on the class in the comments should be
enough to understand what needs to be done.
Viewing the [AWS provider class](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/provider.rb) as well as the
[overall structure of the plugin](https://github.com/mitchellh/vagrant-aws) is recommended as a strong getting started point.
Instead of going in depth over each method that needs to be implemented,
the documentation will cover high-level but important points to help you
create your provider.
## Box Format
Each provider is responsible for having its own box format. This is
actually an extremely simple step due to how generic boxes are. Before
explaining you should get familiar with the general
[box file format](/docs/boxes/format.html).
The only requirement for your box format is that the `metadata.json`
file have a `provider` key which matches the name of your provider you
chose above.
In addition to this, you may put any data in the metadata as well
as any files in the archive. Since Vagrant core itself does not care,
it is up to your provider to handle the data of the box. Vagrant core
just handles unpacking and verifying the box is for the proper
provider.
As an example of a couple box formats that are actually in use:
- The `virtualbox` box format is just a flat directory of the contents
of a `VBoxManage export` command.
- The `vmware_fusion` box format is just a flat directory of the
contents of a `vmwarevm` folder, but only including the bare essential
files for VMware to function.
- The `aws` box format is just a Vagrantfile defaulting some configuration.
You can see an [example aws box unpacked here](https://github.com/mitchellh/vagrant-aws/tree/master/example_box).
Before anything with your provider is even written, you can verify
your box format works by doing `vagrant box add` with it. When you do
a `vagrant box list` you can see what boxes for what providers are installed.
You do _not need_ the provider plugin installed to add a box for that
provider.
<a name="actions"></a>
## Actions
Probably the most important concept to understand when building a
provider is the provider "action" interface. It is the secret sauce that
makes providers do the magic they do.
Actions are built on top of the concept of
[middleware](https://github.com/mitchellh/middleware), which
allow providers to execute multiple distinct steps, have error recovery
mechanics, as well as before/after behaviors, and much more.
Vagrant core requests specific actions from your provider through the
`action` method on your provider class. The full list of actions requested
is listed in the comments of that method on the superclass. If your
provider does not implement a certain action, then Vagrant core will show
a friendly error, so do not worry if you miss any, things will not explode
or crash spectacularly.
Take a look at how the VirtualBox provider
[uses actions to build up complicated multi-step processes](https://github.com/hashicorp/vagrant/blob/master/plugins/providers/virtualbox/action.rb#L287). The AWS provider [uses a similar process](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/action.rb).
## Built-in Middleware
To assist with common tasks, Vagrant ships with a set of
[built-in middleware](https://github.com/hashicorp/vagrant/tree/master/lib/vagrant/action/builtin). Each of the middleware is well commented on the behavior and options
for each, and using these built-in middleware is critical to building
a well-behaved provider.
These built-in middleware can be thought of as a standard library for
your actions on your provider. The core VirtualBox provider uses these
built-in middleware heavily.
## Persisting State
In the process of creating and managing a machine, providers generally need
to store some sort of state somewhere. Vagrant provides each machine with
a directory to store this state.
As a use-case example for this, the VirtualBox provider stores the UUID
of the VirtualBox virtual machine created. This allows the provider to track
whether the machine is created, running, suspended, etc.
The VMware provider actually copies the entire virtual machine into this
state directory, complete with virtual disk drives and everything.
The directory is available from the `data_dir` attribute of the `Machine`
instance given to initialize your provider. Within middleware actions, the
machine is always available via the `:machine` key on the environment. The
`data_dir` attribute is a Ruby [Pathname](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/pathname/rdoc/Pathname.html) object.
It is important for providers to carefully manage all the contents of
this directory. Vagrant core itself does little to clean up this directory.
Therefore, when a machine is destroyed, be sure to clean up all the state
from this directory.
## Configuration
Vagrant supports [provider-specific configuration](/docs/providers/configuration.html),
allowing for users to finely tune and control specific providers from
Vagrantfiles. It is easy for your custom provider to expose custom configuration
as well.
Provider-specific configuration is a special case of a normal
[configuration plugin](/docs/plugins/configuration.html). When defining the
configuration component, name the configuration the same as the provider,
and as a second parameter, specify `:provider`, like so:
```ruby
config("my_cloud", :provider) do
require_relative "config"
Config
end
```
As long as the name matches your provider, and the second `:provider`
parameter is given, Vagrant will automatically expose this as provider-specific
configuration for your provider. Users can now do the following in their
Vagrantfiles:
```ruby
config.vm.provider :my_cloud do |config|
# Your specific configuration!
end
```
The configuration class returned from the `config` component in the plugin
is the same as any other [configuration plugin](/docs/plugins/configuration.html),
so read that page for more information. Vagrant automatically handles
configuration validation and such just like any other configuration piece.
The provider-specific configuration is available on the machine object
via the `provider_config` attribute. So within actions or your provider class,
you can access the config via `machine.provider_config`.
<div class="alert alert-info">
<strong>Best practice:</strong> Your provider should <em>not require</em>
provider-specific configuration to function, if possible. Vagrant
practices a strong <a href="https://en.wikipedia.org/wiki/Convention_over_configuration">convention over configuration</a>
philosophy. When a user installs your provider, they should ideally
be able to <code>vagrant up --provider=your_provider</code> and
have it just work.
</div>
## Parallelization
Vagrant supports parallelizing some actions, such as `vagrant up`, if the
provider explicitly supports it. By default, Vagrant will not parallelize a
provider.
When parallelization is enabled, multiple [actions](#actions) may be run
in parallel. Therefore, providers must be certain that their action stacks
are thread-safe. The core of Vagrant itself (such as box collections, SSH,
etc.) is thread-safe.
Providers can explicitly enable parallelization by setting the `parallel`
option on the provider component:
```ruby
provider("my_cloud", parallel: true) do
require_relative "provider"
Provider
end
```
That is the only change that is needed to enable parallelization.

68
website/pages/docs/plugins/provisioners.html.md Normal file
View File

@ -0,0 +1,68 @@
---
layout: 'docs'
page_title: 'Custom Provisioners - Plugin Development'
sidebar_current: 'plugins-provisioners'
script: |-
This page documents how to add new provisioners to Vagrant, allowing Vagrant
to automatically install software and configure software using a custom
provisioner. Prior to reading this, you should be familiar with the plugin
development basics.
---
# Plugin Development: Provisioners
This page documents how to add new [provisioners](/docs/provisioning/) to Vagrant,
allowing Vagrant to automatically install software and configure software
using a custom provisioner. Prior to reading this, you should be familiar
with the [plugin development basics](/docs/plugins/development-basics.html).
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
advanced topic that only experienced Vagrant users who are reasonably
comfortable with Ruby should approach.
</div>
## Definition Component
Within the context of a plugin definition, new provisioners can be defined
like so:
```ruby
provisioner "custom" do
require_relative "provisioner"
Provisioner
end
```
Provisioners are defined with the `provisioner` method, which takes a
single argument specifying the name of the provisioner. This is the
name that used with `config.vm.provision` when configuring and enabling
the provisioner. So in the case above, the provisioner would be enabled
using `config.vm.provision :custom`.
The block argument then lazily loads and returns a class that implements
the `Vagrant.plugin(2, :provisioner)` interface, which is covered next.
## Provisioner Class
The provisioner class should subclass and implement
`Vagrant.plugin(2, :provisioner)` which is an upgrade-safe way to let
Vagrant return the proper parent class for provisioners.
This class and the methods that need to be implemented are
[very well documented](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provisioner.rb).
The documentation on the class in the comments should be enough
to understand what needs to be done.
There are two main methods that need to be implemented: the
`configure` method and the `provision` method.
The `configure` method is called early in the machine booting process
to allow the provisioner to define new configuration on the machine, such
as sharing folders, defining networks, etc. As an example, the
[Chef solo provisioner](https://github.com/hashicorp/vagrant/blob/master/plugins/provisioners/chef/provisioner/chef_solo.rb#L24)
uses this to define shared folders.
The `provision` method is called when the machine is booted and ready
for SSH connections. In this method, the provisioner should execute
any commands that need to be executed.

74
website/pages/docs/plugins/usage.html.md Normal file
View File

@ -0,0 +1,74 @@
---
layout: 'docs'
page_title: 'Plugin Usage - Plugins'
sidebar_current: 'plugins-usage'
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.
<div class="alert alert-warning">
<strong>Warning!</strong> 3rd party plugins can introduce instabilities
into Vagrant due to the nature of them being written by non-core users.
</div>
## 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
$ 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.

111
website/pages/docs/providers/basic_usage.html.md Normal file
View File

@ -0,0 +1,111 @@
---
layout: 'docs'
page_title: 'Basic Usage - Providers'
sidebar_current: 'providers-basic-usage'
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.
---
# Basic Provider Usage
## Boxes
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.
Installing boxes has not changed at all:
```
$ vagrant box add hashicorp/bionic64
```
Vagrant now automatically detects what provider a box is for. This is
visible when listing boxes. Vagrant puts the provider in parentheses next
to the name, as can be seen below.
```
$ vagrant box list
bionic64 (virtualbox)
bionic64 (vmware_fusion)
```
## Vagrant Up
Once a provider is installed, you can use it by calling `vagrant up`
with the `--provider` flag. This will force Vagrant to use that specific
provider. No other configuration is necessary!
In normal day-to-day usage, the `--provider` flag is not necessary
since Vagrant can usually pick the right provider for you. More details
on how it does this is below.
```
$ vagrant up --provider=vmware_fusion
```
If you specified a `--provider` flag, you only need to do this for the
`up` command. Once a machine is up and running, Vagrant is able to
see what provider is backing a running machine, so commands such as
`destroy`, `suspend`, etc. do not need to be told what provider to use.
<div class="alert alert-info">
Vagrant currently restricts you to bringing up one provider per machine.
If you have a multi-machine environment, you can bring up one machine
backed by VirtualBox and another backed by VMware Fusion, for example, but you
cannot back the <em>same machine</em> with both VirtualBox and
VMware Fusion. This is a limitation that will be removed in a future
version of Vagrant.
</div>
## Default Provider
As mentioned earlier, you typically do not need to specify `--provider`
_ever_. Vagrant is smart enough about being able to detect the provider
you want for a given environment.
Vagrant attempts to find the default provider in the following order:
1. The `--provider` flag on a `vagrant up` is chosen above all else, if
it is present.
2. If the `VAGRANT_DEFAULT_PROVIDER` environmental variable is set,
it takes next priority and will be the provider chosen.
3. Vagrant will go through all of the `config.vm.provider` calls in the
Vagrantfile and try each in order. It will choose the first provider
that is usable. For example, if you configure Hyper-V, it will never
be chosen on Mac this way. It must be both configured and usable.
4. Vagrant will go through all installed provider plugins (including the
ones that come with Vagrant), and find the first plugin that reports
it is usable. There is a priority system here: systems that are known
better have a higher priority than systems that are worse. For example,
if you have the VMware provider installed, it will always take priority
over VirtualBox.
5. If Vagrant still has not found any usable providers, it will error.
Using this method, there are very few cases that Vagrant does not find the
correct provider for you. This also allows each
[Vagrantfile](/docs/vagrantfile/) to define what providers
the development environment is made for by ordering provider configurations.
A trick is to use `config.vm.provider` with no configuration at the top of
your Vagrantfile to define the order of providers you prefer to support:
```ruby
Vagrant.configure("2") do |config|
# ... other config up here
# Prefer VMware Fusion before VirtualBox
config.vm.provider "vmware_fusion"
config.vm.provider "virtualbox"
end
```

91
website/pages/docs/providers/configuration.html.md Normal file
View File

@ -0,0 +1,91 @@
---
layout: 'docs'
page_title: 'Configuration - Providers'
sidebar_current: 'providers-configuration'
description: |-
While well-behaved Vagrant providers should work with any Vagrantfile with
sane defaults, providers generally expose unique configuration options so that
you can get the most out of each provider
---
# Configuration
While well-behaved Vagrant providers should work with any Vagrantfile with sane
defaults, providers generally expose unique configuration
options so that you can get the most out of each provider.
This provider-specific configuration is done within the Vagrantfile
in a way that is portable, easy to use, and easy to understand.
## Portability
An important fact is that even if you configure other providers within
a Vagrantfile, the Vagrantfile remains portable even to individuals who
do not necessarily have that provider installed.
For example, if you configure VMware Fusion and send it to an individual
who does not have the VMware Fusion provider, Vagrant will silently ignore
that part of the configuration.
## Provider Configuration
Configuring a specific provider looks like this:
```ruby
Vagrant.configure("2") do |config|
# ...
config.vm.provider "virtualbox" do |vb|
vb.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
end
end
```
Multiple `config.vm.provider` blocks can exist to configure multiple
providers.
The configuration format should look very similar to how provisioners
are configured. The `config.vm.provider` takes a single parameter: the
name of the provider being configured. Then, an inner block with custom
configuration options is exposed that can be used to configure that
provider.
This inner configuration differs among providers, so please read the
documentation for your provider of choice to see available configuration
options.
Remember, some providers do not require any provider-specific configuration
and work directly out of the box. Provider-specific configuration is meant
as a way to expose more options to get the most of the provider of your
choice. It is not meant as a roadblock to running against a specific provider.
## Overriding Configuration
Providers can also override non-provider specific configuration, such
as `config.vm.box` and any other Vagrant configuration. This is done by
specifying a second argument to `config.vm.provider`. This argument is
just like the normal `config`, so set any settings you want, and they will
be overridden only for that provider.
Example:
```ruby
Vagrant.configure("2") do |config|
config.vm.box = "bionic64"
config.vm.provider "vmware_fusion" do |v, override|
override.vm.box = "bionic64_fusion"
end
end
```
In the above case, Vagrant will use the "bionic64" box by default, but
will use "bionic64_fusion" if the VMware Fusion provider is used.
<div class="alert alert-info">
<strong>The Vagrant Way:</strong> The proper "Vagrant way" is to
avoid any provider-specific overrides if possible by making boxes
for multiple providers that are as identical as possible, since box
names can map to multiple providers. However, this is not always possible,
and in those cases, overrides are available.
</div>

13
website/pages/docs/providers/custom.html.md Normal file
View File

@ -0,0 +1,13 @@
---
layout: 'docs'
page_title: 'Custom Provider - Providers'
sidebar_current: 'providers-custom'
description: |-
To learn how to make your own custom Vagrant providers, read the Vagrant
plugin development guide on creating custom providers.
---
# Custom Provider
To learn how to make your own custom Vagrant providers, read the Vagrant plugin
development guide on [creating custom providers](/docs/plugins/providers.html).

29
website/pages/docs/providers/default.html.md Normal file
View File

@ -0,0 +1,29 @@
---
layout: 'docs'
page_title: 'Default Provider - Providers'
sidebar_current: 'providers-default'
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.

28
website/pages/docs/providers/index.html.md Normal file
View File

@ -0,0 +1,28 @@
---
layout: 'docs'
page_title: 'Providers'
sidebar_current: '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://www.microsoft.com/hyper-v), 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.

16
website/pages/docs/providers/installation.html.md Normal file
View File

@ -0,0 +1,16 @@
---
layout: 'docs'
page_title: 'Installation - Providers'
sidebar_current: 'providers-installation'
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](/docs/plugins/usage.html). After
installing a plugin which contains a provider, the provider should
immediately be available.

151
website/pages/docs/provisioning/ansible.html.md Normal file
View File

@ -0,0 +1,151 @@
---
layout: 'docs'
page_title: 'Ansible - Provisioning'
sidebar_current: 'provisioning-ansible-provisioner'
description: |-
The Vagrant Ansible provisioner allows you to provision the guest using
Ansible playbooks by executing "ansible-playbook" from the Vagrant host.
---
# Ansible Provisioner
**Provisioner name: `ansible`**
The Vagrant Ansible provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` from the Vagrant host**.
<div class="alert alert-warning">
<strong>Warning:</strong>
If you are not familiar with Ansible and Vagrant already, we recommend starting with the <a href="/docs/provisioning/shell.html">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.
</div>
## Setup Requirements
- **[Install Ansible](https://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your Vagrant host**.
- Your Vagrant host should ideally provide a recent version of OpenSSH that [supports ControlPersist](https://docs.ansible.com/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file).
If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the <a href="/docs/provisioning/ansible_local.html">Ansible Local provisioner</a> alternative.
## Usage
This page only documents the specific parts of the `ansible` (remote) provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/docs/provisioning/ansible_intro.html).
### Simplest Configuration
To run Ansible against your Vagrant guest, the basic `Vagrantfile` configuration looks like:
```ruby
Vagrant.configure("2") do |config|
#
# Run Ansible from the Vagrant Host
#
config.vm.provision "ansible" do |ansible|
ansible.playbook = "playbook.yml"
end
end
```
## Options
This section lists the _specific_ options for the Ansible (remote) provisioner. In addition to the options listed below, this provisioner supports the [**common options** for both Ansible provisioners](/docs/provisioning/ansible_common.html).
- `ask_become_pass` (boolean) - require Ansible to [prompt for a password](https://docs.ansible.com/intro_getting_started.html#remote-connection-information) when switching to another user with the [become/sudo mechanism](http://docs.ansible.com/ansible/become.html).
The default value is `false`.
- `ask_sudo_pass` (boolean) - Backwards compatible alias for the [ask_become_pass](#ask_become_pass) option.
<div class="alert alert-warning">
<strong>Deprecation:</strong>
The `ask_sudo_pass` option is deprecated and will be removed in a future release. Please use the [**`ask_become_pass`**](#ask_become_pass) option instead.
</div>
- `ask_vault_pass` (boolean) - require Ansible to [prompt for a vault password](https://docs.ansible.com/playbooks_vault.html#vault).
The default value is `false`.
- `force_remote_user` (boolean) - require Vagrant to set the `ansible_ssh_user` setting in the generated inventory, or as an extra variable when a static inventory is used. All the Ansible `remote_user` parameters will then be overridden by the value of `config.ssh.username` of the [Vagrant SSH Settings](/docs/vagrantfile/ssh_settings.html).
If this option is set to `false` Vagrant will set the Vagrant SSH username as a default Ansible remote user, but `remote_user` parameters of your Ansible plays or tasks will still be taken into account and thus override the Vagrant configuration.
The default value is `true`.
<div class="alert alert-info">
<strong>Compatibility Note:</strong>
This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to `false`.
</div>
- `host_key_checking` (boolean) - require Ansible to [enable SSH host key checking](https://docs.ansible.com/intro_getting_started.html#host-key-checking).
The default value is `false`.
- `raw_ssh_args` (array of strings) - require Ansible to apply a list of OpenSSH client options.
Example: `['-o ControlMaster=no']`.
It is an _unsafe wildcard_ that can be used to pass additional SSH settings to Ansible via `ANSIBLE_SSH_ARGS` environment variable, overriding any other SSH arguments (e.g. defined in an [`ansible.cfg` configuration file](https://docs.ansible.com/intro_configuration.html#ssh-args)).
## Tips and Tricks
### Ansible Parallel Execution
Vagrant is designed to provision [multi-machine environments](/docs/multi-machine) in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:
```ruby
# Vagrant 1.7+ automatically inserts a different
# insecure keypair for each new VM created. The easiest way
# to use the same keypair for all the machines is to disable
# this feature and rely on the legacy insecure key.
# config.ssh.insert_key = false
#
# Note:
# As of Vagrant 1.7.3, it is no longer necessary to disable
# the keypair creation when using the auto-generated inventory.
N = 3
(1..N).each do |machine_id|
config.vm.define "machine#{machine_id}" do |machine|
machine.vm.hostname = "machine#{machine_id}"
machine.vm.network "private_network", ip: "192.168.77.#{20+machine_id}"
# Only execute once the Ansible provisioner,
# when all the machines are up and ready.
if machine_id == N
machine.vm.provision :ansible do |ansible|
# Disable default limit to connect to all the machines
ansible.limit = "all"
ansible.playbook = "playbook.yml"
end
end
end
end
```
<div class="alert alert-info">
<strong>Tip:</strong>
If you apply this parallel provisioning pattern with a static Ansible inventory, you will have to organize the things so that [all the relevant private keys are provided to the `ansible-playbook` command](https://github.com/hashicorp/vagrant/pull/5765#issuecomment-120247738). The same kind of considerations applies if you are using multiple private keys for a same machine (see [`config.ssh.private_key_path` SSH setting](/docs/vagrantfile/ssh_settings.html)).
</div>
### Force Paramiko Connection Mode
The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for [paramiko](https://github.com/paramiko/paramiko/) (A native Python SSHv2 protocol library).
If you really need to use this connection mode though, it is possible to enable paramiko as illustrated in the following configuration examples:
With auto-generated inventory:
```ruby
ansible.raw_arguments = ["--connection=paramiko"]
```
With a custom inventory, the private key must be specified (e.g. via an `ansible.cfg` configuration file, `--private-key` argument, or as part of your inventory file):
```ruby
ansible.inventory_path = "./my-inventory"
ansible.raw_arguments = [
"--connection=paramiko",
"--private-key=/home/.../.vagrant/machines/.../private_key"
]
```

210
website/pages/docs/provisioning/ansible_common.html.md Normal file
View File

@ -0,0 +1,210 @@
---
layout: 'docs'
page_title: 'Common Ansible Options - Provisioning'
sidebar_current: 'provisioning-ansible-common'
description: |-
This page details the common options to the Vagrant Ansible provisioners.
---
# Shared Ansible Options
The following options are available to both Vagrant Ansible provisioners:
- [`ansible`](/docs/provisioning/ansible.html)
- [`ansible_local`](/docs/provisioning/ansible_local.html)
These options get passed to the `ansible-playbook` command that ships with Ansible, either via command line arguments or environment variables, depending on Ansible own capabilities.
Some of these options are for advanced usage only and should not be used unless you understand their purpose.
- `become` (boolean) - Perform all the Ansible playbook tasks [as another user](http://docs.ansible.com/ansible/become.html), different from the user used to log into the guest system.
The default value is `false`.
- `become_user` (string) - Set the default username to be used by the Ansible `become` [privilege escalation](http://docs.ansible.com/ansible/become.html) mechanism.
By default this option is not set, and the Ansible default value (`root`) will be used.
- `compatibility_mode` (string) - Set the **minimal** version of Ansible to be supported. Vagrant will only use parameters that are compatible with the given version.
Possible values:
- `"auto"` _(Vagrant will automatically select the optimal compatibility mode by checking the Ansible version currently available)_
- `"1.8"` _(Ansible versions prior to 1.8 should mostly work well, but some options might not be supported)_
- `"2.0"` _(The generated Ansible inventory will be incompatible with Ansible 1.x)_
By default this option is set to `"auto"`. If Vagrant is not able to detect any supported Ansible version, it will fall back on the compatibility mode `"1.8"` with a warning.
Vagrant will error if the specified compatibility mode is incompatible with the current Ansible version.
<div class="alert alert-warning">
<strong>Attention:</strong>
Vagrant doesn't perform any validation between the `compatibility_mode` value and the value of the [`version`](#version) option.
</div>
<div class="alert alert-info">
<strong>Compatibility Note:</strong>
This option was introduced in Vagrant 2.0. The behavior of previous Vagrant versions can be simulated by setting the `compatibility_mode` to `"1.8"`.
</div>
- `config_file` (string) - The path to an [Ansible Configuration file](https://docs.ansible.com/intro_configuration.html).
By default, this option is not set, and Ansible will [search for a possible configuration file in some default locations](/docs/provisioning/ansible_intro.html#ANSIBLE_CONFIG).
- `extra_vars` (string or hash) - Pass additional variables (with highest priority) to the playbook.
This parameter can be a path to a JSON or YAML file, or a hash.
Example:
```ruby
ansible.extra_vars = {
ntp_server: "pool.ntp.org",
nginx: {
port: 8008,
workers: 4
}
}
```
These variables take the highest precedence over any other variables.
- `galaxy_command` (template string) - The command pattern used to install Galaxy roles when `galaxy_role_file` is set.
The following (optional) placeholders can be used in this command pattern:
- `%{role_file}` is replaced by the absolute path to the `galaxy_role_file` option
- `%{roles_path}` is
- replaced by the absolute path to the `galaxy_roles_path` option when such option is defined, or
- replaced by the absolute path to a `roles` subdirectory sitting in the `playbook` parent directory.
By default, this option is set to
`ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force`
- `galaxy_role_file` (string) - The path to the Ansible Galaxy role file.
By default, this option is set to `nil` and Galaxy support is then disabled.
Note: if an absolute path is given, the `ansible_local` provisioner will assume that it corresponds to the exact location on the guest system.
```ruby
ansible.galaxy_role_file = "requirements.yml"
```
- `galaxy_roles_path` (string) - The path to the directory where Ansible Galaxy roles must be installed
By default, this option is set to `nil`, which means that the Galaxy roles will be installed in a `roles` subdirectory located in the parent directory of the `playbook` file.
- `groups` (hash) - Set of inventory groups to be included in the [auto-generated inventory file](/docs/provisioning/ansible_intro.html).
Example:
```ruby
ansible.groups = {
"web" => ["vm1", "vm2"],
"db" => ["vm3"]
}
```
Example with [group variables](https://docs.ansible.com/ansible/intro_inventory.html#group-variables):
```ruby
ansible.groups = {
"atlanta" => ["host1", "host2"],
"atlanta:vars" => {"ntp_server" => "ntp.atlanta.example.com",
"proxy" => "proxy.atlanta.example.com"}
}
```
Notes:
- Alphanumeric patterns are not supported (e.g. `db-[a:f]`, `vm[01:10]`).
- This option has no effect when the `inventory_path` option is defined.
- `host_vars` (hash) - Set of inventory host variables to be included in the [auto-generated inventory file](https://docs.ansible.com/ansible/intro_inventory.html#host-variables).
Example:
```ruby
ansible.host_vars = {
"host1" => {"http_port" => 80,
"maxRequestsPerChild" => 808,
"comments" => "text with spaces"},
"host2" => {"http_port" => 303,
"maxRequestsPerChild" => 909}
}
```
Note: This option has no effect when the `inventory_path` option is defined.
- `inventory_path` (string) - The path to an Ansible inventory resource (e.g. a [static inventory file](https://docs.ansible.com/intro_inventory.html), a [dynamic inventory script](https://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)).
By default, this option is disabled and Vagrant generates an inventory based on the `Vagrantfile` information.
- `limit` (string or array of strings) - Set of machines or groups from the inventory file to further control which hosts [are affected](https://docs.ansible.com/glossary.html#limit-groups).
The default value is set to the machine name (taken from `Vagrantfile`) to ensure that `vagrant provision` command only affect the expected machine.
Setting `limit = "all"` can be used to make Ansible connect to all machines from the inventory file.
- `playbook_command` (string) - The command used to run playbooks.
The default value is `ansible-playbook`
- `raw_arguments` (array of strings) - a list of additional `ansible-playbook` arguments.
It is an _unsafe wildcard_ that can be used to apply Ansible options that are not (yet) supported by this Vagrant provisioner. As of Vagrant 1.7, `raw_arguments` has the highest priority and its values can potentially override or break other Vagrant settings.
Examples:
- `['--check', '-M', '/my/modules']`
- `["--connection=paramiko", "--forks=10"]`
<div class="alert alert-warn">
<strong>Attention:</strong>
The `ansible` provisioner does not support whitespace characters in `raw_arguments` elements. Therefore **don't write** something like `["-c paramiko"]`, which will result with an invalid `" paramiko"` parameter value.
</div>
- `skip_tags` (string or array of strings) - Only plays, roles and tasks that [_do not match_ these values will be executed](https://docs.ansible.com/playbooks_tags.html).
- `start_at_task` (string) - The task name where the [playbook execution will start](https://docs.ansible.com/playbooks_startnstep.html#start-at-task).
- `sudo` (boolean) - Backwards compatible alias for the [`become`](#become) option.
<div class="alert alert-warning">
<strong>Deprecation:</strong>
The `sudo` option is deprecated and will be removed in a future release. Please use the [**`become`**](#become) option instead.
</div>
- `sudo_user` (string) - Backwards compatible alias for the [`become_user`](#become_user) option.
<div class="alert alert-warning">
<strong>Deprecation:</strong>
The `sudo_user` option is deprecated and will be removed in a future release. Please use the [**`become_user`**](#become_user) option instead.
</div>
- `tags` (string or array of strings) - Only plays, roles and tasks [tagged with these values will be executed](https://docs.ansible.com/playbooks_tags.html) .
- `vault_password_file` (string) - The path of a file containing the password used by [Ansible Vault](https://docs.ansible.com/playbooks_vault.html#vault).
- `verbose` (boolean or string) - Set Ansible's verbosity to obtain detailed logging
Default value is `false` (minimal verbosity).
Examples: `true` (equivalent to `v`), `-vvv` (equivalent to `vvv`), `vvvv`.
Note that when the `verbose` option is enabled, the `ansible-playbook` command used by Vagrant will be displayed.
- `version` (string) - The expected Ansible version.
This option is disabled by default.
When an Ansible version is defined (e.g. `"2.1.6.0"`), the Ansible provisioner will be executed only if Ansible is installed at the requested version.
When this option is set to `"latest"`, no version check is applied.
<div class="alert alert-info">
<strong>Tip:</strong>
With the `ansible_local` provisioner, it is currently possible to use this option to specify which version of Ansible must be automatically installed, but <strong>only</strong> in combination with the [**`install_mode`**](/docs/provisioning/ansible_local.html#install_mode) set to <strong>`:pip`</strong>.
</div>

260
website/pages/docs/provisioning/ansible_intro.html.md Normal file
View File

@ -0,0 +1,260 @@
---
layout: 'docs'
page_title: 'Ansible - Short Introduction'
sidebar_current: 'provisioning-ansible'
description: |-
This page includes options and information that is applicable to both Vagrant
Ansible provisioners.
---
# Ansible and Vagrant
The information below is applicable to both Vagrant Ansible provisioners:
- [`ansible`](/docs/provisioning/ansible.html), where Ansible is executed on the **Vagrant host**
- [`ansible_local`](/docs/provisioning/ansible_local.html), where Ansible is executed on the **Vagrant guest**
The list of common options for these two provisioners is documented in a [separate documentation page](/docs/provisioning/ansible_common.html).
This documentation page will not go into how to use Ansible or how to write Ansible playbooks, since Ansible is a complete deployment and configuration management system that is beyond the scope of Vagrant documentation.
To learn more about Ansible, please consult the [Ansible Documentation Site](https://docs.ansible.com/).
## The Playbook File
The first component of a successful Ansible provisioner setup is the Ansible playbook which contains the steps that should be run on the guest. Ansible's
[playbook documentation](https://docs.ansible.com/playbooks.html) goes into great detail on how to author playbooks, and there are a number of [best practices](https://docs.ansible.com/playbooks_best_practices.html) that can be applied to use Ansible's powerful features effectively.
A playbook that installs and starts (or restarts) the NTP daemon via YUM looks like:
```
---
- hosts: all
tasks:
- name: ensure ntpd is at the latest version
yum: pkg=ntp state=latest
notify:
- restart ntpd
handlers:
- name: restart ntpd
service: name=ntpd state=restarted
```
You can of course target other operating systems that do not have YUM by changing the playbook tasks. Ansible ships with a number of [modules](https://docs.ansible.com/modules.html) that make running otherwise tedious tasks dead simple.
### Running Ansible
The `playbook` option is strictly required by both Ansible provisioners ([`ansible`](/docs/provisioning/ansible.html) and [`ansible_local`](/docs/provisioning/ansible_local.html)), as illustrated in this basic `Vagrantfile` configuration:
```ruby
Vagrant.configure("2") do |config|
# Use :ansible or :ansible_local to
# select the provisioner of your choice
config.vm.provision :ansible do |ansible|
ansible.playbook = "playbook.yml"
end
end
```
Since an Ansible playbook can include many files, you may also collect the related files in a [directory structure](https://docs.ansible.com/playbooks_best_practices.html#directory-layout) like this:
```
.
|-- Vagrantfile
|-- provisioning
| |-- group_vars
| |-- all
| |-- roles
| |-- bar
| |-- foo
| |-- playbook.yml
```
In such an arrangement, the `ansible.playbook` path should be adjusted accordingly:
```ruby
Vagrant.configure("2") do |config|
config.vm.provision "ansible" do |ansible|
ansible.playbook = "provisioning/playbook.yml"
end
end
```
## The Inventory File
When using Ansible, it needs to know on which machines a given playbook should run. It does this by way of an [inventory](https://docs.ansible.com/intro_inventory.html) file which lists those machines. In the context of Vagrant, there are two ways to approach working with inventory files.
### Auto-Generated Inventory
The first and simplest option is to not provide one to Vagrant at all. Vagrant will generate an inventory file encompassing all of the virtual machines it manages, and use it for provisioning machines.
#### Example with the [`ansible`](/docs/provisioning/ansible.html) provisioner
```
# Generated by Vagrant
default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/default/virtualbox/private_key'
```
Note that the generated inventory file is stored as part of your local Vagrant environment in
`.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`.
#### Example with the [`ansible_local`](/docs/provisioning/ansible_local.html) provisioner
```
# Generated by Vagrant
default ansible_connection=local
```
Note that the generated inventory file is uploaded to the guest VM in a subdirectory of [`tmp_path`](/docs/provisioning/ansible_local.html), e.g. `/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory`.
#### Host Variables
As of Vagrant 1.8.0, the [`host_vars`](/docs/provisioning/ansible_common.html#host_vars) option can be used to set [variables for individual hosts](https://docs.ansible.com/ansible/intro_inventory.html#host-variables) in the generated inventory file (see also the notes on group variables below).
With this configuration example:
```
Vagrant.configure("2") do |config|
config.vm.define "host1"
config.vm.define "host2"
config.vm.provision "ansible" do |ansible|
ansible.playbook = "playbook.yml"
ansible.host_vars = {
"host1" => {"http_port" => 80,
"maxRequestsPerChild" => 808},
"host2" => {"http_port" => 303,
"maxRequestsPerChild" => 909}
}
end
end
```
Vagrant would generate the following inventory file:
```
# Generated by Vagrant
host1 ansible_ssh_host=... http_port=80 maxRequestsPerChild=808
host2 ansible_ssh_host=... http_port=303 maxRequestsPerChild=909
```
#### Groups and Group Variables
The [`groups`](/docs/provisioning/ansible_common.html#groups) option can be used to pass a hash of group names and group members to be included in the generated inventory file.
As of Vagrant 1.8.0, it is also possible to specify [group variables](https://docs.ansible.com/ansible/intro_inventory.html#group-variables), and group members as [host ranges (with numeric or alphabetic patterns)](https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups).
With this configuration example:
```
Vagrant.configure("2") do |config|
config.vm.box = "ubuntu/trusty64"
config.vm.define "machine1"
config.vm.define "machine2"
config.vm.provision "ansible" do |ansible|
ansible.playbook = "playbook.yml"
ansible.groups = {
"group1" => ["machine1"],
"group2" => ["machine2"],
"group3" => ["machine[1:2]"],
"group4" => ["other_node-[a:d]"], # silly group definition
"all_groups:children" => ["group1", "group2"],
"group1:vars" => {"variable1" => 9,
"variable2" => "example"}
}
end
end
```
Vagrant would generate the following inventory file:
```
# Generated by Vagrant
machine1 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine1/virtualbox/private_key'
machine2 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine2/virtualbox/private_key'
[group1]
machine1
[group2]
machine2
[group3]
machine[1:2]
[group4]
other_node-[a:d]
[all_groups:children]
group1
group2
[group1:vars]
variable1=9
variable2=example
```
**Notes:**
- Prior to Vagrant 1.7.3, the `ansible_ssh_private_key_file` variable was not set in generated inventory, but passed as command line argument to `ansible-playbook` command.
- The generation of group variables blocks (e.g. `[group1:vars]`) is only possible since Vagrant 1.8.0. Note however that setting variables directly in the inventory is not the [preferred practice in Ansible](https://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data). If possible, group (or host) variables should be set in `YAML` files stored in the `group_vars/` or `host_vars/` directories in the playbook (or inventory) directory instead.
- Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. _unreachable host_ or _undefined child group_)
For example, `machine3` and `group3` in the example below would not be added to the generated inventory file:
```ruby
ansible.groups = {
"group1" => ["machine1"],
"group2" => ["machine2", "machine3"],
"all_groups:children" => ["group1", "group2", "group3"]
}
```
- [Host range patterns (numeric and alphabetic ranges)](https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups) will not be validated by Vagrant. As of Vagrant 1.8.0, host range patterns will be added as group members to the inventory anyway, this might lead to errors in Ansible (e.g _unreachable host_).
### Static Inventory
The second option is for situations where you would like to have more control over the inventory management.
With the [`inventory_path`](/docs/provisioning/ansible_common.html#inventory_path) option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](https://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). Vagrant will then use this inventory information instead of generating it.
A very simple inventory file for use with Vagrant might look like:
```
default ansible_ssh_host=192.168.111.222
```
Where the above IP address is one set in your Vagrantfile:
```
config.vm.network :private_network, ip: "192.168.111.222"
```
**Notes:**
- The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines.
- The `ansible.inventory_path` option by default is only scoped to apply to a single guest in the inventory file, and does not apply to all defined guests. To allow access to all available machines in the inventory, it is necessary to set `ansible.limit = "all"`.
- The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files.
- Sharing hostnames across Vagrant host and guests might be a good idea (e.g. with some Ansible configuration task, or with a plugin like [`vagrant-hostmanager`](https://github.com/smdahlen/vagrant-hostmanager)).
### The Ansible Configuration File
Certain settings in Ansible are (only) adjustable via a [configuration file](https://docs.ansible.com/intro_configuration.html), and you might want to ship such a file in your Vagrant project.
When shipping an Ansible configuration file it is good to know that:
- as of Ansible 1.5, the lookup order is the following:
- any path set as `ANSIBLE_CONFIG` environment variable
- `ansible.cfg` in the runtime working directory
- `.ansible.cfg` in the user home directory
- `/etc/ansible/ansible.cfg`
- Ansible commands don't look for a configuration file relative to the playbook file location (e.g. in the same directory)
- an `ansible.cfg` file located in the same directory as your `Vagrantfile` will be used by default.
- it is also possible to reference any other location with the [config_file](/docs/provisioning/ansible_common.html#config_file) provisioner option. In this case, Vagrant will set the `ANSIBLE_CONFIG` environment variable accordingly.

247
website/pages/docs/provisioning/ansible_local.html.md Normal file
View File

@ -0,0 +1,247 @@
---
layout: 'docs'
page_title: 'Ansible Local - Provisioning'
sidebar_current: 'provisioning-ansible-local'
description: |-
The Vagrant Ansible Local provisioner allows you to provision the guest using Ansible playbooks by executing "ansible-playbook" directly on the guest
machine.
---
# Ansible Local Provisioner
**Provisioner name: `ansible_local`**
The Vagrant Ansible Local provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` directly on the guest machine**.
<div class="alert alert-warning">
<strong>Warning:</strong>
If you are not familiar with Ansible and Vagrant already, we recommend starting with the <a href="/docs/provisioning/shell.html">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.
</div>
## Setup Requirements
The main advantage of the Ansible Local provisioner in comparison to the [Ansible (remote) provisioner](/docs/provisioning/ansible.html) is that it does not require any additional software on your Vagrant host.
On the other hand, [Ansible must obviously be installed](https://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your guest machine(s).
**Note:** By default, Vagrant will _try_ to automatically install Ansible if it is not yet present on the guest machine (see the `install` option below for more details).
## Usage
This page only documents the specific parts of the `ansible_local` provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/docs/provisioning/ansible_intro.html).
The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine, at the location referred by the `provisioning_path` option. Usually these files are initially present on the host machine (as part of your Vagrant project), and it is quite easy to share them with a Vagrant [Synced Folder](/docs/synced-folders/).
### Simplest Configuration
To run Ansible from your Vagrant guest, the basic `Vagrantfile` configuration looks like:
```ruby
Vagrant.configure("2") do |config|
# Run Ansible from the Vagrant VM
config.vm.provision "ansible_local" do |ansible|
ansible.playbook = "playbook.yml"
end
end
```
**Requirements:**
- The `playbook.yml` file is stored in your Vagrant's project home directory.
- The [default shared directory](/docs/synced-folders/basic_usage.html) is enabled (`.` &rarr; `/vagrant`).
## Options
This section lists the _specific_ options for the Ansible Local provisioner. In addition to the options listed below, this provisioner supports the [**common options** for both Ansible provisioners](/docs/provisioning/ansible_common.html).
- `install` (boolean) - Try to automatically install Ansible on the guest system.
This option is enabled by default.
Vagrant will try to install (or upgrade) Ansible when one of these conditions are met:
- Ansible is not installed (or cannot be found).
- The [`version`](/docs/provisioning/ansible_common.html#version) option is set to `"latest"`.
- The current Ansible version does not correspond to the [`version`](/docs/provisioning/ansible_common.html#version) option.
<div class="alert alert-warning">
<strong>Attention:</strong>
There is no guarantee that this automated installation will replace a custom Ansible setup, that might be already present on the Vagrant box.
</div>
- `install_mode` (`:default`, `:pip`, or `:pip_args_only`) - Select the way to automatically install Ansible on the guest system.
- `:default`: Ansible is installed from the operating system package manager. This mode doesn't support `version` selection. For many platforms (e.g Debian, FreeBSD, OpenSUSE) the official package repository is used, except for the following Linux distributions:
- On Ubuntu-like systems, the latest Ansible release is installed from the `ppa:ansible/ansible` repository. The compatibility is maintained only for active long-term support (LTS) versions.
- On RedHat-like systems, the latest Ansible release is installed from the [EPEL](http://fedoraproject.org/wiki/EPEL) repository.
- `:pip`: Ansible is installed from [PyPI](https://pypi.python.org/pypi) with [pip](https://pip.pypa.io) package installer. With this mode, Vagrant will systematically try to [install the latest pip version](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py). With the `:pip` mode you can optionally install a specific Ansible release by setting the [`version`](/docs/provisioning/ansible_common.html#version) option.
Example:
```ruby
config.vm.provision "ansible_local" do |ansible|
ansible.playbook = "playbook.yml"
ansible.install_mode = "pip"
ansible.version = "2.2.1.0"
end
```
With this configuration, Vagrant will install `pip` and then execute the command
```shell
sudo pip install --upgrade ansible==2.2.1.0
```
As-is `pip` is installed if needed via a default command which looks like
```shell
curl https://bootstrap.pypa.io/get-pip.py | sudo python
```
This can be problematic in certain scenarios, for example, when behind a proxy. It is possible to override this default command by providing an explicit command to run as part of the config using `pip_install_cmd`. For example:
```ruby
config.vm.provision "ansible_local" do |ansible|
ansible.playbook = "playbook.yml"
ansible.install_mode = "pip"
ansible.pip_install_cmd = "https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http/your.proxy.server:port python"
ansible.version = "2.2.1.0"
end
```
In this case case `pip` will be installed via the command:
```shell
https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http://your.proxy.server:porpython
```
If `pip_install_cmd` is not provided in the config, then `pip` is installed via the default command.
- `:pip_args_only`: This mode is very similar to the `:pip` mode, with the difference that in this case no pip arguments will be automatically set by Vagrant.
Example:
```ruby
config.vm.provision "ansible_local" do |ansible|
ansible.playbook = "playbook.yml"
ansible.install_mode = "pip_args_only"
ansible.pip_args = "-r /vagrant/requirements.txt"
end
```
With this configuration, Vagrant will install `pip` and then execute the command
```shell
sudo pip install -r /vagrant/requirements.txt
```
The default value of `install_mode` is `:default`, and any invalid value for this option will silently fall back to the default value.
- `pip_args` (string) - When Ansible is installed via pip, this option allows the definition of additional pip arguments to be passed along on the command line (for example, [`--index-url`](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-i)).
By default, this option is not set.
Example:
```ruby
config.vm.provision "ansible_local" do |ansible|
ansible.playbook = "playbook.yml"
ansible.install_mode = :pip
ansible.pip_args = "--index-url https://pypi.internal"
end
```
With this configuration, Vagrant will install `pip` and then execute the command
```shell
sudo pip install --index-url https://pypi.internal --upgrade ansible
```
- `provisioning_path` (string) - An absolute path on the guest machine where the Ansible files are stored. The `ansible-galaxy` and `ansible-playbook` commands are executed from this directory. This is the location to place an [ansible.cfg](http://docs.ansible.com/ansible/intro_configuration.html) file, in case you need it.
The default value is `/vagrant`.
- `tmp_path` (string) - An absolute path on the guest machine where temporary files are stored by the Ansible Local provisioner.
The default value is `/tmp/vagrant-ansible`
## Tips and Tricks
### Install Galaxy Roles in a path owned by root
<div class="alert alert-warning">
<strong>Disclaimer:</strong> This tip is not a recommendation to install galaxy roles out of the vagrant user space, especially if you rely on ssh agent forwarding to fetch the roles.
</div>
Be careful that `ansible-galaxy` command is executed by default as vagrant user. Setting `galaxy_roles_path` to a folder like `/etc/ansible/roles` will fail, and `ansible-galaxy` will extract the role a second time in `/home/vagrant/.ansible/roles/`. Then if your playbook uses `become` to run as `root`, it will fail with a _"role was not found"_ error.
To work around that, you can use `ansible.galaxy_command` to prepend the command with `sudo`, as illustrated in the example below:
```ruby
Vagrant.configure(2) do |config|
config.vm.box = "centos/7"
config.vm.provision "ansible_local" do |ansible|
ansible.become = true
ansible.playbook = "playbook.yml"
ansible.galaxy_role_file = "requirements.yml"
ansible.galaxy_roles_path = "/etc/ansible/roles"
ansible.galaxy_command = "sudo ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force"
end
end
```
### Ansible Parallel Execution from a Guest
With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the `"controller"`) to provision all your machines.
```ruby
Vagrant.configure("2") do |config|
config.vm.box = "ubuntu/trusty64"
config.vm.define "node1" do |machine|
machine.vm.network "private_network", ip: "172.17.177.21"
end
config.vm.define "node2" do |machine|
machine.vm.network "private_network", ip: "172.17.177.22"
end
config.vm.define 'controller' do |machine|
machine.vm.network "private_network", ip: "172.17.177.11"
machine.vm.provision :ansible_local do |ansible|
ansible.playbook = "example.yml"
ansible.verbose = true
ansible.install = true
ansible.limit = "all" # or only "nodes" group, etc.
ansible.inventory_path = "inventory"
end
end
end
```
You need to create a static `inventory` file that corresponds to your `Vagrantfile` machine definitions:
```
controller ansible_connection=local
node1 ansible_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key
node2 ansible_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key
[nodes]
node[1:2]
```
And finally, you also have to create an [`ansible.cfg` file](https://docs.ansible.com/intro_configuration.html#openssh-specific-settings) to fully disable SSH host key checking. More SSH configurations can be added to the `ssh_args` parameter (e.g. agent forwarding, etc.)
```
[defaults]
host_key_checking = no
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes
```

367
website/pages/docs/provisioning/basic_usage.html.md Normal file
View File

@ -0,0 +1,367 @@
---
layout: 'docs'
page_title: 'Basic Usage - Provisioning'
sidebar_current: 'provisioning-basic'
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.
**Note**: This option is currently experimental, so it needs to be explicitly
enabled to work. More info can be found [here](/docs/experimental/index.html).
- `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.
**Note**: This option is currently experimental, so it needs to be explicitly
enabled to work. More info can be found [here](/docs/experimental/index.html).
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](/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](/docs/multi-machine/) definition, then maybe
in a [provider-specific override](/docs/providers/configuration.html)),
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
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> 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.
</div>
When using features such as [multi-machine](/docs/multi-machine/)
or [provider-specific overrides](/docs/providers/configuration.html),
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
<div class="alert alert-warning">
<strong>Warning: Advanced Topic!</strong> Dependency provisioners are
an advanced topic. If you are just getting started with Vagrant, you can
safely skip this.
</div>
<div class="alert alert-warning">
<strong>Warning!</strong> This feature is still experimental and may break or
change in between releases. Use at your own risk.
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
```
VAGRANT_EXPERIMENTAL="dependency_provisioners"
```
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
information about this flag visit the [Experimental docs page](/docs/experimental/)
for more info. Without this flag enabled, provisioners with the `before` and
`after` option will be ignored.
</div>
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
```

Some files were not shown because too many files have changed in this diff Show More