From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/vagrant/boxes%2Fbase.html | 32 +++++ devdocs/vagrant/boxes%2Fformat.html | 32 +++++ devdocs/vagrant/boxes%2Finfo.html | 16 +++ devdocs/vagrant/boxes%2Fversioning.html | 6 + devdocs/vagrant/boxes.html | 14 +++ devdocs/vagrant/cli%2Faliases.html | 21 ++++ devdocs/vagrant/cli%2Fbox.html | 39 ++++++ devdocs/vagrant/cli%2Fcloud.html | 101 ++++++++++++++++ devdocs/vagrant/cli%2Fconnect.html | 9 ++ devdocs/vagrant/cli%2Fdestroy.html | 8 ++ devdocs/vagrant/cli%2Fglobal-status.html | 7 ++ devdocs/vagrant/cli%2Fhalt.html | 7 ++ devdocs/vagrant/cli%2Findex.html | 6 + devdocs/vagrant/cli%2Finit.html | 20 ++++ devdocs/vagrant/cli%2Flogin.html | 19 +++ devdocs/vagrant/cli%2Fmachine-readable.html | 22 ++++ devdocs/vagrant/cli%2Fnon-primary.html | 11 ++ devdocs/vagrant/cli%2Fpackage.html | 10 ++ devdocs/vagrant/cli%2Fplugin.html | 36 ++++++ devdocs/vagrant/cli%2Fport.html | 16 +++ devdocs/vagrant/cli%2Fpowershell.html | 7 ++ devdocs/vagrant/cli%2Fprovision.html | 7 ++ devdocs/vagrant/cli%2Frdp.html | 10 ++ devdocs/vagrant/cli%2Freload.html | 8 ++ devdocs/vagrant/cli%2Fresume.html | 8 ++ devdocs/vagrant/cli%2Frsync-auto.html | 7 ++ devdocs/vagrant/cli%2Frsync.html | 6 + devdocs/vagrant/cli%2Fshare.html | 13 ++ devdocs/vagrant/cli%2Fsnapshot.html | 15 +++ devdocs/vagrant/cli%2Fssh.html | 65 ++++++++++ devdocs/vagrant/cli%2Fssh_config.html | 7 ++ devdocs/vagrant/cli%2Fstatus.html | 6 + devdocs/vagrant/cli%2Fsuspend.html | 6 + devdocs/vagrant/cli%2Fup.html | 14 +++ devdocs/vagrant/cli%2Fvalidate.html | 8 ++ devdocs/vagrant/cli%2Fversion.html | 6 + devdocs/vagrant/docker%2Fbasics.html | 28 +++++ devdocs/vagrant/docker%2Fboxes.html | 6 + devdocs/vagrant/docker%2Fcommands.html | 41 +++++++ devdocs/vagrant/docker%2Fconfiguration.html | 33 ++++++ devdocs/vagrant/docker%2Findex.html | 7 ++ devdocs/vagrant/hyperv%2Fboxes.html | 19 +++ devdocs/vagrant/hyperv%2Fconfiguration.html | 34 ++++++ devdocs/vagrant/hyperv%2Findex.html | 6 + devdocs/vagrant/hyperv%2Flimitations.html | 6 + devdocs/vagrant/hyperv%2Fusage.html | 6 + devdocs/vagrant/index | 1 + devdocs/vagrant/index.html | 6 + .../installation%2Fbackwards-compatibility.html | 6 + devdocs/vagrant/installation%2Findex.html | 26 ++++ devdocs/vagrant/installation%2Fsource.html | 18 +++ devdocs/vagrant/installation%2Funinstallation.html | 13 ++ .../vagrant/installation%2Fupgrading-from-1-0.html | 6 + devdocs/vagrant/installation%2Fupgrading.html | 7 ++ devdocs/vagrant/metadata | 2 + devdocs/vagrant/multi-machine%2Findex.html | 36 ++++++ devdocs/vagrant/multi-machine.html | 36 ++++++ devdocs/vagrant/networking%2Fbasic_usage.html | 11 ++ devdocs/vagrant/networking%2Fforwarded_ports.html | 30 +++++ devdocs/vagrant/networking%2Findex.html | 6 + devdocs/vagrant/networking%2Fprivate_network.html | 31 +++++ devdocs/vagrant/networking%2Fpublic_network.html | 63 ++++++++++ devdocs/vagrant/other%2Fdebugging.html | 16 +++ .../vagrant/other%2Fenvironmental-variables.html | 6 + devdocs/vagrant/other%2Findex.html | 8 ++ devdocs/vagrant/other%2Fwsl.html | 22 ++++ devdocs/vagrant/plugins%2Faction-hooks.html | 26 ++++ devdocs/vagrant/plugins%2Fcommands.html | 43 +++++++ devdocs/vagrant/plugins%2Fconfiguration.html | 85 +++++++++++++ devdocs/vagrant/plugins%2Fdevelopment-basics.html | 35 ++++++ devdocs/vagrant/plugins%2Fguest-capabilities.html | 22 ++++ devdocs/vagrant/plugins%2Fguests.html | 23 ++++ devdocs/vagrant/plugins%2Fhost-capabilities.html | 9 ++ devdocs/vagrant/plugins%2Fhosts.html | 23 ++++ devdocs/vagrant/plugins%2Findex.html | 6 + devdocs/vagrant/plugins%2Fpackaging.html | 23 ++++ devdocs/vagrant/plugins%2Fproviders.html | 30 +++++ devdocs/vagrant/plugins%2Fprovisioners.html | 12 ++ devdocs/vagrant/plugins%2Fusage.html | 15 +++ devdocs/vagrant/providers%2Fbasic_usage.html | 27 +++++ devdocs/vagrant/providers%2Fconfiguration.html | 22 ++++ devdocs/vagrant/providers%2Fcustom.html | 6 + devdocs/vagrant/providers%2Fdefault.html | 6 + devdocs/vagrant/providers%2Findex.html | 6 + devdocs/vagrant/providers%2Finstallation.html | 6 + devdocs/vagrant/provisioning%2Fansible.html | 64 ++++++++++ devdocs/vagrant/provisioning%2Fansible_common.html | 72 +++++++++++ devdocs/vagrant/provisioning%2Fansible_intro.html | 132 +++++++++++++++++++++ devdocs/vagrant/provisioning%2Fansible_local.html | 99 ++++++++++++++++ devdocs/vagrant/provisioning%2Fbasic_usage.html | 83 +++++++++++++ devdocs/vagrant/provisioning%2Fcfengine.html | 43 +++++++ devdocs/vagrant/provisioning%2Fchef_apply.html | 34 ++++++ devdocs/vagrant/provisioning%2Fchef_client.html | 42 +++++++ devdocs/vagrant/provisioning%2Fchef_common.html | 33 ++++++ devdocs/vagrant/provisioning%2Fchef_solo.html | 71 +++++++++++ devdocs/vagrant/provisioning%2Fchef_zero.html | 29 +++++ devdocs/vagrant/provisioning%2Fdocker.html | 66 +++++++++++ devdocs/vagrant/provisioning%2Ffile.html | 53 +++++++++ devdocs/vagrant/provisioning%2Findex.html | 9 ++ devdocs/vagrant/provisioning%2Fpuppet_agent.html | 31 +++++ devdocs/vagrant/provisioning%2Fpuppet_apply.html | 78 ++++++++++++ devdocs/vagrant/provisioning%2Fsalt.html | 75 ++++++++++++ devdocs/vagrant/provisioning%2Fshell.html | 60 ++++++++++ devdocs/vagrant/provisioning.html | 9 ++ devdocs/vagrant/push%2Fftp.html | 22 ++++ devdocs/vagrant/push%2Fheroku.html | 15 +++ devdocs/vagrant/push%2Findex.html | 24 ++++ devdocs/vagrant/push%2Flocal-exec.html | 28 +++++ devdocs/vagrant/share%2Fconnect.html | 6 + devdocs/vagrant/share%2Fhttp.html | 15 +++ devdocs/vagrant/share%2Findex.html | 11 ++ devdocs/vagrant/share%2Fprovider.html | 8 ++ devdocs/vagrant/share%2Fsecurity.html | 10 ++ devdocs/vagrant/share%2Fssh.html | 62 ++++++++++ devdocs/vagrant/synced-folders%2Fbasic_usage.html | 31 +++++ devdocs/vagrant/synced-folders%2Findex.html | 6 + devdocs/vagrant/synced-folders%2Fnfs.html | 57 +++++++++ devdocs/vagrant/synced-folders%2Frsync.html | 22 ++++ devdocs/vagrant/synced-folders%2Fsmb.html | 26 ++++ devdocs/vagrant/synced-folders%2Fvirtualbox.html | 10 ++ devdocs/vagrant/triggers%2Fconfiguration.html | 36 ++++++ devdocs/vagrant/triggers%2Findex.html | 52 ++++++++ devdocs/vagrant/triggers%2Fusage.html | 81 +++++++++++++ devdocs/vagrant/vagrantfile%2Findex.html | 14 +++ .../vagrant/vagrantfile%2Fmachine_settings.html | 31 +++++ devdocs/vagrant/vagrantfile%2Fssh_settings.html | 32 +++++ devdocs/vagrant/vagrantfile%2Ftips.html | 27 +++++ .../vagrant/vagrantfile%2Fvagrant_settings.html | 20 ++++ devdocs/vagrant/vagrantfile%2Fvagrant_version.html | 9 ++ devdocs/vagrant/vagrantfile%2Fversion.html | 18 +++ devdocs/vagrant/vagrantfile%2Fwinrm_settings.html | 18 +++ devdocs/vagrant/vagrantfile%2Fwinssh_settings.html | 20 ++++ devdocs/vagrant/virtualbox%2Fboxes.html | 34 ++++++ devdocs/vagrant/virtualbox%2Fcommon-issues.html | 6 + devdocs/vagrant/virtualbox%2Fconfiguration.html | 33 ++++++ devdocs/vagrant/virtualbox%2Findex.html | 6 + devdocs/vagrant/virtualbox%2Fnetworking.html | 20 ++++ devdocs/vagrant/virtualbox%2Fusage.html | 6 + devdocs/vagrant/vmware%2Fboxes.html | 40 +++++++ devdocs/vagrant/vmware%2Fconfiguration.html | 39 ++++++ devdocs/vagrant/vmware%2Findex.html | 6 + devdocs/vagrant/vmware%2Finstallation.html | 24 ++++ devdocs/vagrant/vmware%2Fkernel-upgrade.html | 21 ++++ devdocs/vagrant/vmware%2Fknown-issues.html | 6 + devdocs/vagrant/vmware%2Fusage.html | 13 ++ .../vagrant/vmware%2Fvagrant-vmware-utility.html | 23 ++++ devdocs/vagrant/vmware.html | 6 + 147 files changed, 3663 insertions(+) create mode 100644 devdocs/vagrant/boxes%2Fbase.html create mode 100644 devdocs/vagrant/boxes%2Fformat.html create mode 100644 devdocs/vagrant/boxes%2Finfo.html create mode 100644 devdocs/vagrant/boxes%2Fversioning.html create mode 100644 devdocs/vagrant/boxes.html create mode 100644 devdocs/vagrant/cli%2Faliases.html create mode 100644 devdocs/vagrant/cli%2Fbox.html create mode 100644 devdocs/vagrant/cli%2Fcloud.html create mode 100644 devdocs/vagrant/cli%2Fconnect.html create mode 100644 devdocs/vagrant/cli%2Fdestroy.html create mode 100644 devdocs/vagrant/cli%2Fglobal-status.html create mode 100644 devdocs/vagrant/cli%2Fhalt.html create mode 100644 devdocs/vagrant/cli%2Findex.html create mode 100644 devdocs/vagrant/cli%2Finit.html create mode 100644 devdocs/vagrant/cli%2Flogin.html create mode 100644 devdocs/vagrant/cli%2Fmachine-readable.html create mode 100644 devdocs/vagrant/cli%2Fnon-primary.html create mode 100644 devdocs/vagrant/cli%2Fpackage.html create mode 100644 devdocs/vagrant/cli%2Fplugin.html create mode 100644 devdocs/vagrant/cli%2Fport.html create mode 100644 devdocs/vagrant/cli%2Fpowershell.html create mode 100644 devdocs/vagrant/cli%2Fprovision.html create mode 100644 devdocs/vagrant/cli%2Frdp.html create mode 100644 devdocs/vagrant/cli%2Freload.html create mode 100644 devdocs/vagrant/cli%2Fresume.html create mode 100644 devdocs/vagrant/cli%2Frsync-auto.html create mode 100644 devdocs/vagrant/cli%2Frsync.html create mode 100644 devdocs/vagrant/cli%2Fshare.html create mode 100644 devdocs/vagrant/cli%2Fsnapshot.html create mode 100644 devdocs/vagrant/cli%2Fssh.html create mode 100644 devdocs/vagrant/cli%2Fssh_config.html create mode 100644 devdocs/vagrant/cli%2Fstatus.html create mode 100644 devdocs/vagrant/cli%2Fsuspend.html create mode 100644 devdocs/vagrant/cli%2Fup.html create mode 100644 devdocs/vagrant/cli%2Fvalidate.html create mode 100644 devdocs/vagrant/cli%2Fversion.html create mode 100644 devdocs/vagrant/docker%2Fbasics.html create mode 100644 devdocs/vagrant/docker%2Fboxes.html create mode 100644 devdocs/vagrant/docker%2Fcommands.html create mode 100644 devdocs/vagrant/docker%2Fconfiguration.html create mode 100644 devdocs/vagrant/docker%2Findex.html create mode 100644 devdocs/vagrant/hyperv%2Fboxes.html create mode 100644 devdocs/vagrant/hyperv%2Fconfiguration.html create mode 100644 devdocs/vagrant/hyperv%2Findex.html create mode 100644 devdocs/vagrant/hyperv%2Flimitations.html create mode 100644 devdocs/vagrant/hyperv%2Fusage.html create mode 100644 devdocs/vagrant/index create mode 100644 devdocs/vagrant/index.html create mode 100644 devdocs/vagrant/installation%2Fbackwards-compatibility.html create mode 100644 devdocs/vagrant/installation%2Findex.html create mode 100644 devdocs/vagrant/installation%2Fsource.html create mode 100644 devdocs/vagrant/installation%2Funinstallation.html create mode 100644 devdocs/vagrant/installation%2Fupgrading-from-1-0.html create mode 100644 devdocs/vagrant/installation%2Fupgrading.html create mode 100644 devdocs/vagrant/metadata create mode 100644 devdocs/vagrant/multi-machine%2Findex.html create mode 100644 devdocs/vagrant/multi-machine.html create mode 100644 devdocs/vagrant/networking%2Fbasic_usage.html create mode 100644 devdocs/vagrant/networking%2Fforwarded_ports.html create mode 100644 devdocs/vagrant/networking%2Findex.html create mode 100644 devdocs/vagrant/networking%2Fprivate_network.html create mode 100644 devdocs/vagrant/networking%2Fpublic_network.html create mode 100644 devdocs/vagrant/other%2Fdebugging.html create mode 100644 devdocs/vagrant/other%2Fenvironmental-variables.html create mode 100644 devdocs/vagrant/other%2Findex.html create mode 100644 devdocs/vagrant/other%2Fwsl.html create mode 100644 devdocs/vagrant/plugins%2Faction-hooks.html create mode 100644 devdocs/vagrant/plugins%2Fcommands.html create mode 100644 devdocs/vagrant/plugins%2Fconfiguration.html create mode 100644 devdocs/vagrant/plugins%2Fdevelopment-basics.html create mode 100644 devdocs/vagrant/plugins%2Fguest-capabilities.html create mode 100644 devdocs/vagrant/plugins%2Fguests.html create mode 100644 devdocs/vagrant/plugins%2Fhost-capabilities.html create mode 100644 devdocs/vagrant/plugins%2Fhosts.html create mode 100644 devdocs/vagrant/plugins%2Findex.html create mode 100644 devdocs/vagrant/plugins%2Fpackaging.html create mode 100644 devdocs/vagrant/plugins%2Fproviders.html create mode 100644 devdocs/vagrant/plugins%2Fprovisioners.html create mode 100644 devdocs/vagrant/plugins%2Fusage.html create mode 100644 devdocs/vagrant/providers%2Fbasic_usage.html create mode 100644 devdocs/vagrant/providers%2Fconfiguration.html create mode 100644 devdocs/vagrant/providers%2Fcustom.html create mode 100644 devdocs/vagrant/providers%2Fdefault.html create mode 100644 devdocs/vagrant/providers%2Findex.html create mode 100644 devdocs/vagrant/providers%2Finstallation.html create mode 100644 devdocs/vagrant/provisioning%2Fansible.html create mode 100644 devdocs/vagrant/provisioning%2Fansible_common.html create mode 100644 devdocs/vagrant/provisioning%2Fansible_intro.html create mode 100644 devdocs/vagrant/provisioning%2Fansible_local.html create mode 100644 devdocs/vagrant/provisioning%2Fbasic_usage.html create mode 100644 devdocs/vagrant/provisioning%2Fcfengine.html create mode 100644 devdocs/vagrant/provisioning%2Fchef_apply.html create mode 100644 devdocs/vagrant/provisioning%2Fchef_client.html create mode 100644 devdocs/vagrant/provisioning%2Fchef_common.html create mode 100644 devdocs/vagrant/provisioning%2Fchef_solo.html create mode 100644 devdocs/vagrant/provisioning%2Fchef_zero.html create mode 100644 devdocs/vagrant/provisioning%2Fdocker.html create mode 100644 devdocs/vagrant/provisioning%2Ffile.html create mode 100644 devdocs/vagrant/provisioning%2Findex.html create mode 100644 devdocs/vagrant/provisioning%2Fpuppet_agent.html create mode 100644 devdocs/vagrant/provisioning%2Fpuppet_apply.html create mode 100644 devdocs/vagrant/provisioning%2Fsalt.html create mode 100644 devdocs/vagrant/provisioning%2Fshell.html create mode 100644 devdocs/vagrant/provisioning.html create mode 100644 devdocs/vagrant/push%2Fftp.html create mode 100644 devdocs/vagrant/push%2Fheroku.html create mode 100644 devdocs/vagrant/push%2Findex.html create mode 100644 devdocs/vagrant/push%2Flocal-exec.html create mode 100644 devdocs/vagrant/share%2Fconnect.html create mode 100644 devdocs/vagrant/share%2Fhttp.html create mode 100644 devdocs/vagrant/share%2Findex.html create mode 100644 devdocs/vagrant/share%2Fprovider.html create mode 100644 devdocs/vagrant/share%2Fsecurity.html create mode 100644 devdocs/vagrant/share%2Fssh.html create mode 100644 devdocs/vagrant/synced-folders%2Fbasic_usage.html create mode 100644 devdocs/vagrant/synced-folders%2Findex.html create mode 100644 devdocs/vagrant/synced-folders%2Fnfs.html create mode 100644 devdocs/vagrant/synced-folders%2Frsync.html create mode 100644 devdocs/vagrant/synced-folders%2Fsmb.html create mode 100644 devdocs/vagrant/synced-folders%2Fvirtualbox.html create mode 100644 devdocs/vagrant/triggers%2Fconfiguration.html create mode 100644 devdocs/vagrant/triggers%2Findex.html create mode 100644 devdocs/vagrant/triggers%2Fusage.html create mode 100644 devdocs/vagrant/vagrantfile%2Findex.html create mode 100644 devdocs/vagrant/vagrantfile%2Fmachine_settings.html create mode 100644 devdocs/vagrant/vagrantfile%2Fssh_settings.html create mode 100644 devdocs/vagrant/vagrantfile%2Ftips.html create mode 100644 devdocs/vagrant/vagrantfile%2Fvagrant_settings.html create mode 100644 devdocs/vagrant/vagrantfile%2Fvagrant_version.html create mode 100644 devdocs/vagrant/vagrantfile%2Fversion.html create mode 100644 devdocs/vagrant/vagrantfile%2Fwinrm_settings.html create mode 100644 devdocs/vagrant/vagrantfile%2Fwinssh_settings.html create mode 100644 devdocs/vagrant/virtualbox%2Fboxes.html create mode 100644 devdocs/vagrant/virtualbox%2Fcommon-issues.html create mode 100644 devdocs/vagrant/virtualbox%2Fconfiguration.html create mode 100644 devdocs/vagrant/virtualbox%2Findex.html create mode 100644 devdocs/vagrant/virtualbox%2Fnetworking.html create mode 100644 devdocs/vagrant/virtualbox%2Fusage.html create mode 100644 devdocs/vagrant/vmware%2Fboxes.html create mode 100644 devdocs/vagrant/vmware%2Fconfiguration.html create mode 100644 devdocs/vagrant/vmware%2Findex.html create mode 100644 devdocs/vagrant/vmware%2Finstallation.html create mode 100644 devdocs/vagrant/vmware%2Fkernel-upgrade.html create mode 100644 devdocs/vagrant/vmware%2Fknown-issues.html create mode 100644 devdocs/vagrant/vmware%2Fusage.html create mode 100644 devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html create mode 100644 devdocs/vagrant/vmware.html (limited to 'devdocs/vagrant') diff --git a/devdocs/vagrant/boxes%2Fbase.html b/devdocs/vagrant/boxes%2Fbase.html new file mode 100644 index 00000000..1f3b2e14 --- /dev/null +++ b/devdocs/vagrant/boxes%2Fbase.html @@ -0,0 +1,32 @@ +

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 "precise64") are base boxes. They were created from a minimal Ubuntu install from an ISO, rather than repackaging an existing environment.

Base boxes are extremely useful for having a clean slate starting point from which to build future development environments. The Vagrant project hopes in the future to be able to provide base boxes for many more operating systems. Until then, this page documents how you can create your own base box.

Advanced topic! Creating a base box can be a time consuming and tedious process, and is not recommended for new Vagrant users. If you are just getting started with Vagrant, we recommend trying to find existing base boxes to use first.

+

What's in a Base Box?

A base box typically consists of only a bare minimum set of software for Vagrant to function. As an example, a Linux box may contain only the following:

In addition to this, each provider 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:

Packer and Vagrant Cloud

We strongly recommend using Packer to create reproducible builds for your base boxes, as well as automating the builds. Read more about automating Vagrant box creation with Packer 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 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 may help you.

Base Windows Configuration

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"}
+
+

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.

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!

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/boxes/base.html +

+
diff --git a/devdocs/vagrant/boxes%2Fformat.html b/devdocs/vagrant/boxes%2Fformat.html new file mode 100644 index 00000000..86e9aadd --- /dev/null +++ b/devdocs/vagrant/boxes%2Fformat.html @@ -0,0 +1,32 @@ +

Box File Format

In the past, boxes were just tar files of VirtualBox exports. With Vagrant supporting multiple providers and versioning 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:

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

{
+  "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, updating, multiple providers from a single file, and more.

You do not need to manually make the metadata. If you have an account with HashiCorp's Vagrant Cloud, you can create boxes there, and HashiCorp's Vagrant Cloud automatically creates the metadata for you. The format is still documented here.

+

It is a JSON document, structured in the following way:

{
+  "name": "hashicorp/precise64",
+  "description": "This box contains Ubuntu 12.04 LTS 64-bit.",
+  "versions": [
+    {
+      "version": "0.1.0",
+      "providers": [
+        {
+          "name": "virtualbox",
+          "url": "http://somewhere.com/precise64_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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/boxes/format.html +

+
diff --git a/devdocs/vagrant/boxes%2Finfo.html b/devdocs/vagrant/boxes%2Finfo.html new file mode 100644 index 00000000..2b41e052 --- /dev/null +++ b/devdocs/vagrant/boxes%2Finfo.html @@ -0,0 +1,16 @@ +

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/precise64     (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 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.

{
+ "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 provides more information about what else goes into a Vagrant box.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/boxes/info.html +

+
diff --git a/devdocs/vagrant/boxes%2Fversioning.html b/devdocs/vagrant/boxes%2Fversioning.html new file mode 100644 index 00000000..0309e9c0 --- /dev/null +++ b/devdocs/vagrant/boxes%2Fversioning.html @@ -0,0 +1,6 @@ +

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.

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. An easy way to find a box is to use the url https://vagrantcloud.com/$USER/$BOX. For example, for the hashicorp/precise64 box, you can find information about it at https://vagrantcloud.com/hashicorp/precise64.

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/boxes/versioning.html +

+
diff --git a/devdocs/vagrant/boxes.html b/devdocs/vagrant/boxes.html new file mode 100644 index 00000000..b53366a2 --- /dev/null +++ b/devdocs/vagrant/boxes.html @@ -0,0 +1,14 @@ +

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 command for more information.

The easiest way to use a box is to add a box from the publicly available catalog of Vagrant boxes. 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 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. 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/precise64. You can also quickly initialize a Vagrant environment with vagrant init hashicorp/precise64.

Official Boxes

HashiCorp (the makers of Vagrant) publish a basic Ubuntu 12.04 (32 and 64-bit) box that is available for minimal use cases. It is highly optimized, small in size, and includes support for Virtualbox and VMware. You can use it like this:

$ vagrant init hashicorp/precise64
+
+

or you can update your Vagrantfile as follows:

Vagrant.configure("2") do |config|
+  config.vm.box = "hashicorp/precise64"
+end
+
+

For other users, we recommend the Bento boxes. The Bento boxes are open source 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/boxes.html +

+
diff --git a/devdocs/vagrant/cli%2Faliases.html b/devdocs/vagrant/cli%2Faliases.html new file mode 100644 index 00000000..ce38a939 --- /dev/null +++ b/devdocs/vagrant/cli%2Faliases.html @@ -0,0 +1,21 @@ +

Aliases

Inspired in part by Git's own alias functionality, 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%
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/aliases.html +

+
diff --git a/devdocs/vagrant/cli%2Fbox.html b/devdocs/vagrant/cli%2Fbox.html new file mode 100644 index 00000000..c271661d --- /dev/null +++ b/devdocs/vagrant/cli%2Fbox.html @@ -0,0 +1,39 @@ +

Box

Command: vagrant box

This is the command used to manage (add, remove, etc.) boxes.

The main functionality of this command is exposed via even more subcommands:

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:

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

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

Checksums for versioned boxes or boxes from HashiCorp's Vagrant Cloud: 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.

+

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.

Checking for updates involves refreshing the metadata associated with a box. This generally requires an internet connection.

Options

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

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

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.

If you just want to check if there are updates available, use the vagrant box outdated command.

Options

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/box.html +

+
diff --git a/devdocs/vagrant/cli%2Fcloud.html b/devdocs/vagrant/cli%2Fcloud.html new file mode 100644 index 00000000..12fa44e3 --- /dev/null +++ b/devdocs/vagrant/cli%2Fcloud.html @@ -0,0 +1,101 @@ +

Cloud

Command: vagrant cloud

This is the command used to manage anything related to Vagrant Cloud.

The main functionality of this command is exposed via subcommands:

Cloud Auth

Command: vagrant cloud auth

The cloud auth command is for handling all things related to authorization with Vagrant Cloud.

Cloud Auth Login

Command: vagrant cloud auth login

The login command is used to authenticate with HashiCorp's 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

Examples

Securely authenticate to Vagrant Cloud using a username and password:

$ vagrant cloud auth login
+# ...
+Vagrant Cloud username:
+Vagrant Cloud password:
+
+

Check if the current user is authenticated:

$ vagrant cloud auth login --check
+You are already logged in.
+
+

Securely authenticate with Vagrant Cloud using a token:

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

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

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

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.

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 command can be used to upload a Vagrant box file.

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

Examples

Creating a new box on Vagrant Cloud:

$ 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 "Donwload 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 reall 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

Examples

If you are looking for a HashiCorp box:

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.

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

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/cloud.html +

+
diff --git a/devdocs/vagrant/cli%2Fconnect.html b/devdocs/vagrant/cli%2Fconnect.html new file mode 100644 index 00000000..20965f7f --- /dev/null +++ b/devdocs/vagrant/cli%2Fconnect.html @@ -0,0 +1,9 @@ +

Connect

Command: vagrant connect NAME

The connect command complements the share command by enabling access to shared environments. You can learn about all the details of Vagrant Share in the Vagrant Share section.

The reference of available command-line flags to this command is available below.

Options

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/connect.html +

+
diff --git a/devdocs/vagrant/cli%2Fdestroy.html b/devdocs/vagrant/cli%2Fdestroy.html new file mode 100644 index 00000000..29573042 --- /dev/null +++ b/devdocs/vagrant/cli%2Fdestroy.html @@ -0,0 +1,8 @@ +

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

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 vagrant box remove command.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/destroy.html +

+
diff --git a/devdocs/vagrant/cli%2Fglobal-status.html b/devdocs/vagrant/cli%2Fglobal-status.html new file mode 100644 index 00000000..61ceeaf9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fglobal-status.html @@ -0,0 +1,7 @@ +

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.

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

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/global-status.html +

+
diff --git a/devdocs/vagrant/cli%2Fhalt.html b/devdocs/vagrant/cli%2Fhalt.html new file mode 100644 index 00000000..44eda701 --- /dev/null +++ b/devdocs/vagrant/cli%2Fhalt.html @@ -0,0 +1,7 @@ +

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/halt.html +

+
diff --git a/devdocs/vagrant/cli%2Findex.html b/devdocs/vagrant/cli%2Findex.html new file mode 100644 index 00000000..3d96c3b7 --- /dev/null +++ b/devdocs/vagrant/cli%2Findex.html @@ -0,0 +1,6 @@ +

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 regarding the environmental variables that can be used to configure and control Vagrant in a global way.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/ +

+
diff --git a/devdocs/vagrant/cli%2Finit.html b/devdocs/vagrant/cli%2Finit.html new file mode 100644 index 00000000..0b074a05 --- /dev/null +++ b/devdocs/vagrant/cli%2Finit.html @@ -0,0 +1,20 @@ +

Init

Command: vagrant init [name [url]]

This initializes the current directory to be a Vagrant environment by creating an initial 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

Examples

Create a base Vagrantfile:

$ vagrant init hashicorp/precise64
+
+

Create a minimal Vagrantfile (no comments or helpers):

$ vagrant init -m hashicorp/precise64
+
+

Create a new Vagrantfile, overwriting the one at the current path:

$ vagrant init -f hashicorp/precise64
+
+

Create a Vagrantfile with the specific box, from the specific box URL:

$ vagrant init my-company-box https://boxes.company.com/my-company.box
+
+

Create a Vagrantfile, locking the box to a version constraint:

$ vagrant init --box-version '> 0.1.5' hashicorp/precise64
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/init.html +

+
diff --git a/devdocs/vagrant/cli%2Flogin.html b/devdocs/vagrant/cli%2Flogin.html new file mode 100644 index 00000000..ad5485fb --- /dev/null +++ b/devdocs/vagrant/cli%2Flogin.html @@ -0,0 +1,19 @@ +

Login

Command: vagrant login

The login command is used to authenticate with the HashiCorp's Vagrant Cloud server. Logging in is only necessary if you are accessing protected boxes or using Vagrant 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 require a login.

The reference of available command-line flags to this command is available below.

Options

Examples

Securely authenticate to Vagrant Cloud using a username and password:

$ vagrant login
+# ...
+Vagrant Cloud username:
+Vagrant Cloud password:
+
+

Check if the current user is authenticated:

$ vagrant login --check
+You are already logged in.
+
+

Securely authenticate with Vagrant Cloud using a token:

$ vagrant login --token ABCD1234
+The token was successfully saved.
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/login.html +

+
diff --git a/devdocs/vagrant/cli%2Fmachine-readable.html b/devdocs/vagrant/cli%2Fmachine-readable.html new file mode 100644 index 00000000..1af06e73 --- /dev/null +++ b/devdocs/vagrant/cli%2Fmachine-readable.html @@ -0,0 +1,22 @@ +

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

Advanced topic! 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.

+

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

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.

+ + + + + + + + +
Type Description
box-name Name of a box installed into Vagrant.
box-provider Provider for an installed box.
cli-command A subcommand of vagrant that is available.
error-exit An error occurred that caused Vagrant to exit. This contains that error. Contains two data elements: type of error, error message.
provider-name The provider name of the target machine. targeted
ssh-config The OpenSSH compatible SSH config for a machine. This is usually the result of the "ssh-config" command. targeted
state The state ID of the target machine. targeted
state-human-long Human-readable description of the state of the machine. This is the long version, and may be a paragraph or longer. targeted
state-human-short Human-readable description of the state of the machine. This is the short version, limited to at most a sentence. targeted
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/machine-readable.html +

+
diff --git a/devdocs/vagrant/cli%2Fnon-primary.html b/devdocs/vagrant/cli%2Fnon-primary.html new file mode 100644 index 00000000..39c9ccea --- /dev/null +++ b/devdocs/vagrant/cli%2Fnon-primary.html @@ -0,0 +1,11 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/non-primary.html +

+
diff --git a/devdocs/vagrant/cli%2Fpackage.html b/devdocs/vagrant/cli%2Fpackage.html new file mode 100644 index 00000000..c64962d6 --- /dev/null +++ b/devdocs/vagrant/cli%2Fpackage.html @@ -0,0 +1,10 @@ +

Package

Command: vagrant package [name|id]

This packages a currently running VirtualBox or Hyper-V environment into a re-usable box. This command can only be used with other providers based on the provider implementation and if the provider supports it.

Options

A common misconception is that the --vagrantfile option will package a Vagrantfile that is used when vagrant init 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 Vagrantfile load order.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/package.html +

+
diff --git a/devdocs/vagrant/cli%2Fplugin.html b/devdocs/vagrant/cli%2Fplugin.html new file mode 100644 index 00000000..3156c071 --- /dev/null +++ b/devdocs/vagrant/cli%2Fplugin.html @@ -0,0 +1,36 @@ +

Plugin

Command: vagrant plugin

This is the command used to manage plugins.

The main functionality of this command is exposed via another level of subcommands:

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:

# Delete all plugins and reinstall
+$ vagrant plugin expunge --reinstall
+
+

This command accepts optional command-line flags:

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. This command will also update a plugin if it is already installed, but you can also use vagrant plugin update for that.

# 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:

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.

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:

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 command

This command accepts optional command-line flags:

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:

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:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/plugin.html +

+
diff --git a/devdocs/vagrant/cli%2Fport.html b/devdocs/vagrant/cli%2Fport.html new file mode 100644 index 00000000..86afbecc --- /dev/null +++ b/devdocs/vagrant/cli%2Fport.html @@ -0,0 +1,16 @@ +

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/port.html +

+
diff --git a/devdocs/vagrant/cli%2Fpowershell.html b/devdocs/vagrant/cli%2Fpowershell.html new file mode 100644 index 00000000..88bfedfb --- /dev/null +++ b/devdocs/vagrant/cli%2Fpowershell.html @@ -0,0 +1,7 @@ +

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/powershell.html +

+
diff --git a/devdocs/vagrant/cli%2Fprovision.html b/devdocs/vagrant/cli%2Fprovision.html new file mode 100644 index 00000000..30089253 --- /dev/null +++ b/devdocs/vagrant/cli%2Fprovision.html @@ -0,0 +1,7 @@ +

Provision

Command: vagrant provision [vm-name]

Runs any configured provisioners 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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/provision.html +

+
diff --git a/devdocs/vagrant/cli%2Frdp.html b/devdocs/vagrant/cli%2Frdp.html new file mode 100644 index 00000000..9fef1627 --- /dev/null +++ b/devdocs/vagrant/cli%2Frdp.html @@ -0,0 +1,10 @@ +

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!

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/rdp.html +

+
diff --git a/devdocs/vagrant/cli%2Freload.html b/devdocs/vagrant/cli%2Freload.html new file mode 100644 index 00000000..4966cd62 --- /dev/null +++ b/devdocs/vagrant/cli%2Freload.html @@ -0,0 +1,8 @@ +

Reload

Command: vagrant reload [name|id]

The equivalent of running a halt followed by an up.

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/reload.html +

+
diff --git a/devdocs/vagrant/cli%2Fresume.html b/devdocs/vagrant/cli%2Fresume.html new file mode 100644 index 00000000..6e7e85d9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fresume.html @@ -0,0 +1,8 @@ +

Resume

Command: vagrant resume [name|id]

This resumes a Vagrant managed machine that was previously suspended, perhaps with the suspend command.

The configured provisioners will not run again, by default. You can force the provisioners to re-run by specifying the --provision flag.

Options

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/resume.html +

+
diff --git a/devdocs/vagrant/cli%2Frsync-auto.html b/devdocs/vagrant/cli%2Frsync-auto.html new file mode 100644 index 00000000..e47773d2 --- /dev/null +++ b/devdocs/vagrant/cli%2Frsync-auto.html @@ -0,0 +1,7 @@ +

rsync-auto

Command: vagrant rsync-auto

This command watches all local directories of any rsync synced folders 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

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/rsync-auto.html +

+
diff --git a/devdocs/vagrant/cli%2Frsync.html b/devdocs/vagrant/cli%2Frsync.html new file mode 100644 index 00000000..9228d232 --- /dev/null +++ b/devdocs/vagrant/cli%2Frsync.html @@ -0,0 +1,6 @@ +

Rsync

Command: vagrant rsync

This command forces a re-sync of any rsync synced folders.

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/rsync.html +

+
diff --git a/devdocs/vagrant/cli%2Fshare.html b/devdocs/vagrant/cli%2Fshare.html new file mode 100644 index 00000000..7055ffa9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fshare.html @@ -0,0 +1,13 @@ +

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.

The reference of available command-line flags to this command is available below.

Options

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/share.html +

+
diff --git a/devdocs/vagrant/cli%2Fsnapshot.html b/devdocs/vagrant/cli%2Fsnapshot.html new file mode 100644 index 00000000..97182227 --- /dev/null +++ b/devdocs/vagrant/cli%2Fsnapshot.html @@ -0,0 +1,15 @@ +

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:

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.

Snapshot Pop

Command: vagrant snapshot pop

This command is the inverse of vagrant snapshot push: it will restore the pushed state.

Options

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.

Snapshot List

Command: vagrant snapshot list

This command will list all the snapshots taken.

Snapshot Delete

Command: vagrant snapshot delete 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/snapshot.html +

+
diff --git a/devdocs/vagrant/cli%2Fssh.html b/devdocs/vagrant/cli%2Fssh.html new file mode 100644 index 00000000..30b8bbea --- /dev/null +++ b/devdocs/vagrant/cli%2Fssh.html @@ -0,0 +1,65 @@ +

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:

$ 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:

$ 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

 $ 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@precise64:~$ 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@precise64:~$ 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

$ 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@precise64:~$ 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

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/ssh.html +

+
diff --git a/devdocs/vagrant/cli%2Fssh_config.html b/devdocs/vagrant/cli%2Fssh_config.html new file mode 100644 index 00000000..356a73ec --- /dev/null +++ b/devdocs/vagrant/cli%2Fssh_config.html @@ -0,0 +1,7 @@ +

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/ssh_config.html +

+
diff --git a/devdocs/vagrant/cli%2Fstatus.html b/devdocs/vagrant/cli%2Fstatus.html new file mode 100644 index 00000000..5a7effd4 --- /dev/null +++ b/devdocs/vagrant/cli%2Fstatus.html @@ -0,0 +1,6 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/status.html +

+
diff --git a/devdocs/vagrant/cli%2Fsuspend.html b/devdocs/vagrant/cli%2Fsuspend.html new file mode 100644 index 00000000..2bbb0642 --- /dev/null +++ b/devdocs/vagrant/cli%2Fsuspend.html @@ -0,0 +1,6 @@ +

Suspend

Command: vagrant suspend [name|id]

This suspends the guest machine Vagrant is managing, rather than fully shutting it down or destroying it.

A suspend effectively saves the exact point-in-time state of the machine, so that when you resume 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/suspend.html +

+
diff --git a/devdocs/vagrant/cli%2Fup.html b/devdocs/vagrant/cli%2Fup.html new file mode 100644 index 00000000..f85bcc49 --- /dev/null +++ b/devdocs/vagrant/cli%2Fup.html @@ -0,0 +1,14 @@ +

Up

Command: vagrant up [name|id]

This command creates and configures guest machines according to your 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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/up.html +

+
diff --git a/devdocs/vagrant/cli%2Fvalidate.html b/devdocs/vagrant/cli%2Fvalidate.html new file mode 100644 index 00000000..0218ec84 --- /dev/null +++ b/devdocs/vagrant/cli%2Fvalidate.html @@ -0,0 +1,8 @@ +

Validate

Command: vagrant validate

This command validates your Vagrantfile.

Examples 

$ vagrant validate
+Vagrantfile validated successfully.
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/validate.html +

+
diff --git a/devdocs/vagrant/cli%2Fversion.html b/devdocs/vagrant/cli%2Fversion.html new file mode 100644 index 00000000..fc8335b8 --- /dev/null +++ b/devdocs/vagrant/cli%2Fversion.html @@ -0,0 +1,6 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/cli/version.html +

+
diff --git a/devdocs/vagrant/docker%2Fbasics.html b/devdocs/vagrant/docker%2Fbasics.html new file mode 100644 index 00000000..595c111b --- /dev/null +++ b/devdocs/vagrant/docker%2Fbasics.html @@ -0,0 +1,28 @@ +

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:

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:

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.

Private and public networks are not currently supported.

Volume Consistency

Docker's volume consistency setting can be specified using the docker_consistency option when defining a synced folder. This can greatly improve performance on macOS. An example is shown using the cached and delegated settings:

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, because it launches quickly and uses little resources. But the host VM can be customized to point to any Vagrantfile. This allows the host VM to more closely match production by running a VM running Ubuntu, RHEL, etc. It can run any operating system supported by Vagrant.

Synced folder note: Vagrant will attempt to use the "best" synced folder implementation it can. For boot2docker, this is often rsync. In this case, make sure you have rsync installed on your host machine. Vagrant will give you a human-friendly error message if it is not.

+

An example of changing the host VM is shown below. Remember that this is optional, and Vagrant will spin up a default host VM if it is not specified:

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 along with global control.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/docker/basics.html +

+
diff --git a/devdocs/vagrant/docker%2Fboxes.html b/devdocs/vagrant/docker%2Fboxes.html new file mode 100644 index 00000000..c8a89ea1 --- /dev/null +++ b/devdocs/vagrant/docker%2Fboxes.html @@ -0,0 +1,6 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/docker/boxes.html +

+
diff --git a/devdocs/vagrant/docker%2Fcommands.html b/devdocs/vagrant/docker%2Fcommands.html new file mode 100644 index 00000000..08a5f415 --- /dev/null +++ b/devdocs/vagrant/docker%2Fcommands.html @@ -0,0 +1,41 @@ +

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.

$ 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:

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:

$ vagrant docker-exec -it -- /bin/sh
+
+

In particular, the command is actually:

$ 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:

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:

# Not valid
+$ vagrant docker-exec -it nginx -- /bin/sh
+
+

This is because the "name" of the VM is "web", so the command is actually:

$ 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:

$ 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:

$ vagrant docker-run app -- rake db:migrate
+
+

The above would run rake db:migrate in the context of an app container.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/docker/commands.html +

+
diff --git a/devdocs/vagrant/docker%2Fconfiguration.html b/devdocs/vagrant/docker%2Fconfiguration.html new file mode 100644 index 00000000..87e132f9 --- /dev/null +++ b/devdocs/vagrant/docker%2Fconfiguration.html @@ -0,0 +1,33 @@ +

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:

Optional

General settings:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/docker/configuration.html +

+
diff --git a/devdocs/vagrant/docker%2Findex.html b/devdocs/vagrant/docker%2Findex.html new file mode 100644 index 00000000..0744af89 --- /dev/null +++ b/devdocs/vagrant/docker%2Findex.html @@ -0,0 +1,7 @@ +

Docker

Vagrant comes with support out of the box for using Docker as a provider. This allows for your development environments to be backed by Docker containers rather than virtual machines. Additionally, it provides for a good workflow for developing Dockerfiles.

Warning: Docker knowledge assumed. We assume that you know what Docker is and that you are comfortable with the basics of Docker. If not, we recommend starting with another provider such as VirtualBox.

+

Use the navigation to the left to find a specific Docker topic to read more about.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/docker/ +

+
diff --git a/devdocs/vagrant/hyperv%2Fboxes.html b/devdocs/vagrant/hyperv%2Fboxes.html new file mode 100644 index 00000000..ade9dc48 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fboxes.html @@ -0,0 +1,19 @@ +

Creating a Base Box

As with every Vagrant provider, 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. 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.

Advanced topic! 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.

+

Additional Software

In addition to the software that should be installed based on the general guide to creating base boxes, 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. 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:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/hyperv/boxes.html +

+
diff --git a/devdocs/vagrant/hyperv%2Fconfiguration.html b/devdocs/vagrant/hyperv%2Fconfiguration.html new file mode 100644 index 00000000..af18e540 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fconfiguration.html @@ -0,0 +1,34 @@ +

Configuration

The Vagrant Hyper-V provider has some provider-specific configuration options you may set. A complete reference is shown below:

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/hyperv/configuration.html +

+
diff --git a/devdocs/vagrant/hyperv%2Findex.html b/devdocs/vagrant/hyperv%2Findex.html new file mode 100644 index 00000000..803b685f --- /dev/null +++ b/devdocs/vagrant/hyperv%2Findex.html @@ -0,0 +1,6 @@ +

Hyper-V

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.

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:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

See official documentation here.

Warning: Enabling Hyper-V will cause VirtualBox, VMware, and any other virtualization technology to no longer work. See this blog post 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/hyperv/ +

+
diff --git a/devdocs/vagrant/hyperv%2Flimitations.html b/devdocs/vagrant/hyperv%2Flimitations.html new file mode 100644 index 00000000..c001f596 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Flimitations.html @@ -0,0 +1,6 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/hyperv/limitations.html +

+
diff --git a/devdocs/vagrant/hyperv%2Fusage.html b/devdocs/vagrant/hyperv%2Fusage.html new file mode 100644 index 00000000..aaea813f --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fusage.html @@ -0,0 +1,6 @@ +

Usage

The Vagrant Hyper-V provider is used just like any other provider. Please read the general basic usage page for providers.

The value to use for the --provider flag is hyperv.

Hyper-V also requires that you execute Vagrant with administrative privileges. Creating and managing virtual machines with Hyper-V requires admin rights. Vagrant will show you an error if it does not have the proper permissions.

Boxes for Hyper-V can be easily found on HashiCorp's Vagrant Cloud. To get started, you might want to try the hashicorp/precise64 box.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/hyperv/usage.html +

+
diff --git a/devdocs/vagrant/index b/devdocs/vagrant/index new file mode 100644 index 00000000..529a25c3 --- /dev/null +++ b/devdocs/vagrant/index @@ -0,0 +1 @@ +((pages . ["index" "installation/index" "cli/box" "cli/plugin" "cli/powershell" "installation/upgrading-from-1-0" "installation/uninstallation" "cli/index" "cli/cloud" "cli/connect" "cli/destroy" "cli/global-status" "cli/halt" "cli/init" "cli/package" "cli/port" "cli/provision" "installation/source" "installation/backwards-compatibility" "installation/upgrading" "cli/login" "cli/rdp" "cli/reload" "cli/resume" "cli/share" "cli/ssh_config" "cli/status" "cli/suspend" "cli/validate" "cli/version" "cli/up" "cli/non-primary" "cli/aliases" "share/index" "cli/ssh" "cli/machine-readable" "cli/snapshot" "share/http" "share/connect" "share/security" "share/provider" "vagrantfile/machine_settings" "vagrantfile/ssh_settings" "share/ssh" "vagrantfile/version" "vagrantfile/vagrant_version" "boxes/versioning" "vagrantfile/index" "vagrantfile/tips" "vagrantfile/winrm_settings" "vagrantfile/winssh_settings" "boxes/base" "vagrantfile/vagrant_settings" "boxes" "boxes/format" "boxes/info" "provisioning/file" "provisioning/shell" "provisioning/ansible" "provisioning/cfengine" "provisioning/index" "provisioning/basic_usage" "provisioning/ansible_local" "provisioning/chef_solo" "provisioning/chef_client" "provisioning/puppet_agent" "provisioning/salt" "provisioning/chef_zero" "provisioning/chef_apply" "provisioning/docker" "provisioning/puppet_apply" "networking/index" "networking/forwarded_ports" "networking/basic_usage" "networking/private_network" "networking/public_network" "synced-folders/index" "synced-folders/basic_usage" "synced-folders/nfs" "synced-folders/rsync" "synced-folders/smb" "multi-machine/index" "providers/installation" "synced-folders/virtualbox" "providers/index" "providers/basic_usage" "providers/configuration" "virtualbox/usage" "virtualbox/boxes" "virtualbox/configuration" "providers/default" "virtualbox/index" "virtualbox/networking" "virtualbox/common-issues" "vmware/index" "vmware/installation" "vmware/boxes" "vmware/configuration" "vmware/usage" "vmware/vagrant-vmware-utility" "vmware/known-issues" "vmware/kernel-upgrade" "docker/index" "docker/basics" "docker/commands" "docker/boxes" "docker/configuration" "hyperv/usage" "hyperv/boxes" "hyperv/index" "hyperv/limitations" "hyperv/configuration" "providers/custom" "plugins/index" "plugins/development-basics" "plugins/commands" "plugins/usage" "plugins/configuration" "plugins/action-hooks" "plugins/host-capabilities" "plugins/providers" "plugins/guests" "plugins/guest-capabilities" "plugins/hosts" "plugins/provisioners" "push/index" "push/ftp" "plugins/packaging" "push/heroku" "push/local-exec" "triggers/index" "triggers/configuration" "triggers/usage" "other/index" "other/debugging" "other/environmental-variables" "other/wsl" "cli/rsync" "vmware" "cli/rsync-auto" "provisioning/ansible_intro" "provisioning/chef_common" "provisioning/ansible_common" "multi-machine" "provisioning"]) (entries . [((name . "Action Hooks") (path . "plugins/action-hooks") (type . "Plugins")) ((name . "Additional Box Information") (path . "boxes/info") (type . "Boxes")) ((name . "Aliases") (path . "cli/aliases") (type . "Commands (CLI)")) ((name . "Ansible and Vagrant") (path . "provisioning/ansible_intro") (type . "Provisioning")) ((name . "Ansible Local Provisioner") (path . "provisioning/ansible_local") (type . "Provisioning")) ((name . "Ansible Provisioner") (path . "provisioning/ansible") (type . "Provisioning")) ((name . "Backwards Compatibility") (path . "installation/backwards-compatibility") (type . "Installation")) ((name . "Basic Provider Usage") (path . "providers/basic_usage") (type . "Providers")) ((name . "Basic Usage") (path . "synced-folders/basic_usage") (type . "Synced Folders")) ((name . "Basic Usage") (path . "triggers/usage") (type . "Triggers")) ((name . "Basic Usage of Networking") (path . "networking/basic_usage") (type . "Networking")) ((name . "Basic Usage of Provisioners") (path . "provisioning/basic_usage") (type . "Provisioning")) ((name . "Box File Format") (path . "boxes/format") (type . "Boxes")) ((name . "Box Versioning") (path . "boxes/versioning") (type . "Boxes")) ((name . "Boxes") (path . "boxes") (type . "Boxes")) ((name . "Boxes") (path . "vmware/boxes") (type . "Providers: VMware")) ((name . "CFEngine Provisioner") (path . "provisioning/cfengine") (type . "Provisioning")) ((name . "Chef Apply Provisioner") (path . "provisioning/chef_apply") (type . "Provisioning")) ((name . "Chef Client Provisioner") (path . "provisioning/chef_client") (type . "Provisioning")) ((name . "Chef Solo Provisioner") (path . "provisioning/chef_solo") (type . "Provisioning")) ((name . "Chef Zero Provisioner") (path . "provisioning/chef_zero") (type . "Provisioning")) ((name . "Command-Line Interface") (path . "cli/index") (type . "Commands (CLI)")) ((name . "Common Issues") (path . "virtualbox/common-issues") (type . "Providers: VirtualBox")) ((name . "config.ssh.username") (path . "vagrantfile/ssh_settings#config-ssh-username") (type . "Config")) ((name . "config.vagrant.host") (path . "vagrantfile/vagrant_settings#config-vagrant-host") (type . "Config")) ((name . "config.vm.base_mac") (path . "vagrantfile/machine_settings#config-vm-base_mac") (type . "Config")) ((name . "config.winrm.username") (path . "vagrantfile/winrm_settings#config-winrm-username") (type . "Config")) ((name . "Configuration") (path . "vmware/configuration") (type . "Providers: VMware")) ((name . "Configuration") (path . "virtualbox/configuration") (type . "Providers: VirtualBox")) ((name . "Configuration") (path . "providers/configuration") (type . "Providers")) ((name . "Configuration") (path . "hyperv/configuration") (type . "Providers: Hyper-V")) ((name . "Configuration") (path . "triggers/configuration") (type . "Triggers")) ((name . "Configuration Version") (path . "vagrantfile/version") (type . "Vagrantfile")) ((name . "Creating a Base Box") (path . "boxes/base") (type . "Boxes")) ((name . "Creating a Base Box") (path . "hyperv/boxes") (type . "Providers: Hyper-V")) ((name . "Creating a Base Box") (path . "virtualbox/boxes") (type . "Providers: VirtualBox")) ((name . "Custom Provider") (path . "share/provider") (type . "Vagrant Share")) ((name . "Custom Provider") (path . "providers/custom") (type . "Providers")) ((name . "Debugging") (path . "other/debugging") (type . "Other")) ((name . "Default Provider") (path . "providers/default") (type . "Providers")) ((name . "Docker") (path . "docker/index") (type . "Providers: Docker")) ((name . "Docker Basic Usage") (path . "docker/basics") (type . "Providers: Docker")) ((name . "Docker Boxes") (path . "docker/boxes") (type . "Providers: Docker")) ((name . "Docker Commands") (path . "docker/commands") (type . "Providers: Docker")) ((name . "Docker Configuration") (path . "docker/configuration") (type . "Providers: Docker")) ((name . "Docker Provisioner") (path . "provisioning/docker") (type . "Provisioning")) ((name . "Environmental Variables") (path . "other/environmental-variables") (type . "Other")) ((name . "File Provisioner") (path . "provisioning/file") (type . "Provisioning")) ((name . "Forwarded Ports") (path . "networking/forwarded_ports") (type . "Networking")) ((name . "FTP & SFTP Strategy") (path . "push/ftp") (type . "Push")) ((name . "Heroku Strategy") (path . "push/heroku") (type . "Push")) ((name . "HTTP Sharing") (path . "share/http") (type . "Vagrant Share")) ((name . "Hyper-V") (path . "hyperv/index") (type . "Providers: Hyper-V")) ((name . "Installation") (path . "vmware/installation") (type . "Providers: VMware")) ((name . "Installing Vagrant") (path . "installation/index") (type . "Installation")) ((name . "Installing Vagrant from Source") (path . "installation/source") (type . "Installation")) ((name . "Kernel Upgrade") (path . "vmware/kernel-upgrade") (type . "Providers: VMware")) ((name . "Known Issues") (path . "vmware/known-issues") (type . "Providers: VMware")) ((name . "Limitations") (path . "hyperv/limitations") (type . "Providers: Hyper-V")) ((name . "Local Exec Strategy") (path . "push/local-exec") (type . "Push")) ((name . "Machine Readable Output") (path . "cli/machine-readable") (type . "Commands (CLI)")) ((name . "Machine Settings") (path . "vagrantfile/machine_settings") (type . "Vagrantfile")) ((name . "Minimum Vagrant Version") (path . "vagrantfile/vagrant_version") (type . "Vagrantfile")) ((name . "More Commands") (path . "cli/non-primary") (type . "Commands (CLI)")) ((name . "Multi-Machine") (path . "multi-machine") (type . "Multi-Machine")) ((name . "Multi-Machine") (path . "multi-machine/index") (type . "Multi-Machine")) ((name . "Networking") (path . "virtualbox/networking") (type . "Providers: VirtualBox")) ((name . "Networking") (path . "networking/index") (type . "Networking")) ((name . "NFS") (path . "synced-folders/nfs") (type . "Synced Folders")) ((name . "Other") (path . "other/index") (type . "Other")) ((name . "Plugin Development Basics") (path . "plugins/development-basics") (type . "Plugins")) ((name . "Plugin Development: Commands") (path . "plugins/commands") (type . "Plugins")) ((name . "Plugin Development: Configuration") (path . "plugins/configuration") (type . "Plugins")) ((name . "Plugin Development: Guest Capabilities") (path . "plugins/guest-capabilities") (type . "Plugins")) ((name . "Plugin Development: Guests") (path . "plugins/guests") (type . "Plugins")) ((name . "Plugin Development: Host Capabilities") (path . "plugins/host-capabilities") (type . "Plugins")) ((name . "Plugin Development: Hosts") (path . "plugins/hosts") (type . "Plugins")) ((name . "Plugin Development: Packaging & Distribution") (path . "plugins/packaging") (type . "Plugins")) ((name . "Plugin Development: Providers") (path . "plugins/providers") (type . "Plugins")) ((name . "Plugin Development: Provisioners") (path . "plugins/provisioners") (type . "Plugins")) ((name . "Plugin Usage") (path . "plugins/usage") (type . "Plugins")) ((name . "Plugins") (path . "plugins/index") (type . "Plugins")) ((name . "Private Networks") (path . "networking/private_network") (type . "Networking")) ((name . "Provider Installation") (path . "providers/installation") (type . "Providers")) ((name . "Providers") (path . "providers/index") (type . "Providers")) ((name . "Provisioning") (path . "provisioning") (type . "Provisioning")) ((name . "Provisioning") (path . "provisioning/index") (type . "Provisioning")) ((name . "Public Networks") (path . "networking/public_network") (type . "Networking")) ((name . "Puppet Agent Provisioner") (path . "provisioning/puppet_agent") (type . "Provisioning")) ((name . "Puppet Apply Provisioner") (path . "provisioning/puppet_apply") (type . "Provisioning")) ((name . "RSync") (path . "synced-folders/rsync") (type . "Synced Folders")) ((name . "Salt Provisioner") (path . "provisioning/salt") (type . "Provisioning")) ((name . "Security") (path . "share/security") (type . "Vagrant Share")) ((name . "Shared Ansible Options") (path . "provisioning/ansible_common") (type . "Provisioning")) ((name . "Shared Chef Options") (path . "provisioning/chef_common") (type . "Provisioning")) ((name . "Shell Provisioner") (path . "provisioning/shell") (type . "Provisioning")) ((name . "SMB") (path . "synced-folders/smb") (type . "Synced Folders")) ((name . "SSH Settings") (path . "vagrantfile/ssh_settings") (type . "Vagrantfile")) ((name . "SSH Sharing") (path . "share/ssh") (type . "Vagrant Share")) ((name . "Synced Folders") (path . "synced-folders/index") (type . "Synced Folders")) ((name . "Tips & Tricks") (path . "vagrantfile/tips") (type . "Vagrantfile")) ((name . "Uninstalling Vagrant") (path . "installation/uninstallation") (type . "Installation")) ((name . "Upgrading From Vagrant 1.0.x") (path . "installation/upgrading-from-1-0") (type . "Installation")) ((name . "Upgrading Vagrant") (path . "installation/upgrading") (type . "Installation")) ((name . "Usage") (path . "virtualbox/usage") (type . "Providers: VirtualBox")) ((name . "Usage") (path . "vmware/usage") (type . "Providers: VMware")) ((name . "Usage") (path . "hyperv/usage") (type . "Providers: Hyper-V")) ((name . "Vagrant and Windows Subsystem for Linux") (path . "other/wsl") (type . "Other")) ((name . "vagrant box") (path . "cli/box") (type . "Commands (CLI)")) ((name . "vagrant cloud") (path . "cli/cloud") (type . "Commands (CLI)")) ((name . "vagrant connect") (path . "cli/connect") (type . "Commands (CLI)")) ((name . "Vagrant Connect") (path . "share/connect") (type . "Vagrant Share")) ((name . "vagrant destroy") (path . "cli/destroy") (type . "Commands (CLI)")) ((name . "vagrant global-status") (path . "cli/global-status") (type . "Commands (CLI)")) ((name . "vagrant halt") (path . "cli/halt") (type . "Commands (CLI)")) ((name . "vagrant init") (path . "cli/init") (type . "Commands (CLI)")) ((name . "vagrant login") (path . "cli/login") (type . "Commands (CLI)")) ((name . "vagrant package") (path . "cli/package") (type . "Commands (CLI)")) ((name . "vagrant plugin") (path . "cli/plugin") (type . "Commands (CLI)")) ((name . "vagrant port") (path . "cli/port") (type . "Commands (CLI)")) ((name . "vagrant powershell") (path . "cli/powershell") (type . "Commands (CLI)")) ((name . "vagrant provision") (path . "cli/provision") (type . "Commands (CLI)")) ((name . "Vagrant Push") (path . "push/index") (type . "Push")) ((name . "vagrant rdp") (path . "cli/rdp") (type . "Commands (CLI)")) ((name . "vagrant reload") (path . "cli/reload") (type . "Commands (CLI)")) ((name . "vagrant resume") (path . "cli/resume") (type . "Commands (CLI)")) ((name . "vagrant rsync") (path . "cli/rsync") (type . "Commands (CLI)")) ((name . "vagrant rsync-auto") (path . "cli/rsync-auto") (type . "Commands (CLI)")) ((name . "Vagrant Settings") (path . "vagrantfile/vagrant_settings") (type . "Vagrantfile")) ((name . "Vagrant Share") (path . "share/index") (type . "Vagrant Share")) ((name . "vagrant share") (path . "cli/share") (type . "Commands (CLI)")) ((name . "vagrant snapshot") (path . "cli/snapshot") (type . "Commands (CLI)")) ((name . "vagrant ssh") (path . "cli/ssh") (type . "Commands (CLI)")) ((name . "vagrant ssh-config") (path . "cli/ssh_config") (type . "Commands (CLI)")) ((name . "vagrant status") (path . "cli/status") (type . "Commands (CLI)")) ((name . "vagrant suspend") (path . "cli/suspend") (type . "Commands (CLI)")) ((name . "Vagrant Triggers") (path . "triggers/index") (type . "Triggers")) ((name . "vagrant up") (path . "cli/up") (type . "Commands (CLI)")) ((name . "vagrant validate") (path . "cli/validate") (type . "Commands (CLI)")) ((name . "vagrant version") (path . "cli/version") (type . "Commands (CLI)")) ((name . "Vagrant VMware Utility Installation") (path . "vmware/vagrant-vmware-utility") (type . "Providers: VMware")) ((name . "Vagrantfile") (path . "vagrantfile/index") (type . "Vagrantfile")) ((name . "VirtualBox") (path . "virtualbox/index") (type . "Providers: VirtualBox")) ((name . "VirtualBox") (path . "synced-folders/virtualbox") (type . "Synced Folders")) ((name . "VMware") (path . "vmware/index") (type . "Providers: VMware")) ((name . "VMware") (path . "vmware") (type . "Providers: VMware")) ((name . "WinRM Settings") (path . "vagrantfile/winrm_settings") (type . "Vagrantfile")) ((name . "WinSSH") (path . "vagrantfile/winssh_settings") (type . "Vagrantfile"))]) (types . [((name . "Boxes") (count . 5) (slug . "boxes")) ((name . "Commands (CLI)") (count . 31) (slug . "commands-cli")) ((name . "Config") (count . 4) (slug . "config")) ((name . "Installation") (count . 6) (slug . "installation")) ((name . "Multi-Machine") (count . 2) (slug . "multi-machine")) ((name . "Networking") (count . 5) (slug . "networking")) ((name . "Other") (count . 4) (slug . "other")) ((name . "Plugins") (count . 13) (slug . "plugins")) ((name . "Providers") (count . 6) (slug . "providers")) ((name . "Providers: Docker") (count . 5) (slug . "providers-docker")) ((name . "Providers: Hyper-V") (count . 5) (slug . "providers-hyper-v")) ((name . "Providers: VirtualBox") (count . 6) (slug . "providers-virtualbox")) ((name . "Providers: VMware") (count . 9) (slug . "providers-vmware")) ((name . "Provisioning") (count . 19) (slug . "provisioning")) ((name . "Push") (count . 4) (slug . "push")) ((name . "Synced Folders") (count . 6) (slug . "synced-folders")) ((name . "Triggers") (count . 3) (slug . "triggers")) ((name . "Vagrant Share") (count . 6) (slug . "vagrant-share")) ((name . "Vagrantfile") (count . 9) (slug . "vagrantfile"))])) \ No newline at end of file diff --git a/devdocs/vagrant/index.html b/devdocs/vagrant/index.html new file mode 100644 index 00000000..c2b9b742 --- /dev/null +++ b/devdocs/vagrant/index.html @@ -0,0 +1,6 @@ +

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 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 for their needs.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/index.html +

+
diff --git a/devdocs/vagrant/installation%2Fbackwards-compatibility.html b/devdocs/vagrant/installation%2Fbackwards-compatibility.html new file mode 100644 index 00000000..a96f5a84 --- /dev/null +++ b/devdocs/vagrant/installation%2Fbackwards-compatibility.html @@ -0,0 +1,6 @@ +

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/backwards-compatibility.html +

+
diff --git a/devdocs/vagrant/installation%2Findex.html b/devdocs/vagrant/installation%2Findex.html new file mode 100644 index 00000000..ee69a0d3 --- /dev/null +++ b/devdocs/vagrant/installation%2Findex.html @@ -0,0 +1,26 @@ +

Installing Vagrant

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.

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

+ +

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:

Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All
+
+

You can also disable it by going through the Windows system settings:

You might have to reboot your machine for the changes to take effect. More information about Hyper-V can be read here.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/ +

+
diff --git a/devdocs/vagrant/installation%2Fsource.html b/devdocs/vagrant/installation%2Fsource.html new file mode 100644 index 00000000..3d95033a --- /dev/null +++ b/devdocs/vagrant/installation%2Fsource.html @@ -0,0 +1,18 @@ +

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:

Clone Vagrant

Clone Vagrant's repository from GitHub into the directory where you keep code on your machine:

$ git clone https://github.com/hashicorp/vagrant.git
+
+

Next, cd into that path. All commands will be run from this path:

$ cd /path/to/your/vagrant/clone
+
+

Run the bundle command with a required version* to install the requirements:

$ 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:

$ 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:

$ /path/to/vagrant/exec/vagrant init -m hashicorp/precise64
+
+

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:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/source.html +

+
diff --git a/devdocs/vagrant/installation%2Funinstallation.html b/devdocs/vagrant/installation%2Funinstallation.html new file mode 100644 index 00000000..f727b004 --- /dev/null +++ b/devdocs/vagrant/installation%2Funinstallation.html @@ -0,0 +1,13 @@ +

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 again using standard methods.

On Windows

Uninstall using the add/remove programs section of the control panel

On Mac OS X:

rm -rf /opt/vagrant
+rm -f /usr/local/bin/vagrant
+sudo pkgutil --forget com.vagrant.vagrant
+
+

On Linux:

rm -rf /opt/vagrant
+rm -f /usr/bin/vagrant
+
+

Removing User Data

Removing the user data will remove all boxes, 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, remove the ~/.vagrant.d directory to delete the user data. 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/uninstallation.html +

+
diff --git a/devdocs/vagrant/installation%2Fupgrading-from-1-0.html b/devdocs/vagrant/installation%2Fupgrading-from-1-0.html new file mode 100644 index 00000000..27ded35d --- /dev/null +++ b/devdocs/vagrant/installation%2Fupgrading-from-1-0.html @@ -0,0 +1,6 @@ +

Upgrading From Vagrant 1.0.x

The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is quite 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.

As the backwards compatibility page says, Vagrant 1.0.x plugins will not work with Vagrant 1.1+. Many of these plugins have been updated to work with newer versions of Vagrant, so you 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/upgrading-from-1-0.html +

+
diff --git a/devdocs/vagrant/installation%2Fupgrading.html b/devdocs/vagrant/installation%2Fupgrading.html new file mode 100644 index 00000000..92753ee5 --- /dev/null +++ b/devdocs/vagrant/installation%2Fupgrading.html @@ -0,0 +1,7 @@ +

Upgrading Vagrant

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.

Vagrant upgrades during the 1.x release series are straightforward:

  1. +Download 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, newer Vagrantfiles may have backwards incompatible changes until 2.0 final.

Run into troubles upgrading? Please report an issue if you run into problems upgrading. Upgrades are meant to be a smooth process and we consider it a bug if it was not.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/installation/upgrading.html +

+
diff --git a/devdocs/vagrant/metadata b/devdocs/vagrant/metadata new file mode 100644 index 00000000..b8dab5f1 --- /dev/null +++ b/devdocs/vagrant/metadata @@ -0,0 +1,2 @@ +(1 (name . "Vagrant") (slug . "vagrant") (type . "simple") (links (home . "https://www.vagrantup.com/") (code . "https://github.com/mitchellh/vagrant")) (release . "2.2.0") (mtime . 1541375199) (db_size . 620133) (attribution . "© 2010–2018 Mitchell Hashimoto
+ Licensed under the MPL 2.0 License.")) \ No newline at end of file diff --git a/devdocs/vagrant/multi-machine%2Findex.html b/devdocs/vagrant/multi-machine%2Findex.html new file mode 100644 index 00000000..f9da77ef --- /dev/null +++ b/devdocs/vagrant/multi-machine%2Findex.html @@ -0,0 +1,36 @@ +

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:

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

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.

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:

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.

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 options should be used. In particular, the private network can be used to make a private network between multiple machines and the host.

Specifying a Primary Machine

You can also specify a primary machine. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified.

To specify a default machine, just mark it primary when defining it. Only one primary machine may be specified.

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/multi-machine/ +

+
diff --git a/devdocs/vagrant/multi-machine.html b/devdocs/vagrant/multi-machine.html new file mode 100644 index 00000000..d8ecf760 --- /dev/null +++ b/devdocs/vagrant/multi-machine.html @@ -0,0 +1,36 @@ +

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:

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

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.

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:

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.

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 options should be used. In particular, the private network can be used to make a private network between multiple machines and the host.

Specifying a Primary Machine

You can also specify a primary machine. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified.

To specify a default machine, just mark it primary when defining it. Only one primary machine may be specified.

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/multi-machine +

+
diff --git a/devdocs/vagrant/networking%2Fbasic_usage.html b/devdocs/vagrant/networking%2Fbasic_usage.html new file mode 100644 index 00000000..1b24e0f6 --- /dev/null +++ b/devdocs/vagrant/networking%2Fbasic_usage.html @@ -0,0 +1,11 @@ +

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 using the config.vm.network method call. For example, the Vagrantfile below defines some port forwarding:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/networking/basic_usage.html +

+
diff --git a/devdocs/vagrant/networking%2Fforwarded_ports.html b/devdocs/vagrant/networking%2Fforwarded_ports.html new file mode 100644 index 00000000..1cef787c --- /dev/null +++ b/devdocs/vagrant/networking%2Fforwarded_ports.html @@ -0,0 +1,30 @@ +

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:

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.

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:

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:

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

Vagrant.configure("2") do |config|
+  config.vm.usable_port_range = 8000..8999
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/networking/forwarded_ports.html +

+
diff --git a/devdocs/vagrant/networking%2Findex.html b/devdocs/vagrant/networking%2Findex.html new file mode 100644 index 00000000..1eb374ad --- /dev/null +++ b/devdocs/vagrant/networking%2Findex.html @@ -0,0 +1,6 @@ +

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. 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 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 to do this, so please read the documentation for your specific provider to see what options are available.

For beginners: It is strongly recommended you use only the high-level networking options until you are comfortable with the Vagrant workflow and have things working at a basic level. Provider-specific network configuration can very quickly lock you out of your guest machine if improperly done.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/networking/ +

+
diff --git a/devdocs/vagrant/networking%2Fprivate_network.html b/devdocs/vagrant/networking%2Fprivate_network.html new file mode 100644 index 00000000..e88ce9e1 --- /dev/null +++ b/devdocs/vagrant/networking%2Fprivate_network.html @@ -0,0 +1,31 @@ +

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.

Multiple machines within the same private network (also usually with the restriction that they're backed by the same provider) can communicate with each other on private networks.

Guest operating system support. 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.

+

DHCP

The easiest way to use a private network is to allow the IP to be assigned via DHCP.

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:

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

Warning! Do not choose an IP that overlaps with any other IP space on your system. This can cause the network to not be reachable.

+

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:

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):

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/networking/private_network.html +

+
diff --git a/devdocs/vagrant/networking%2Fpublic_network.html b/devdocs/vagrant/networking%2Fpublic_network.html new file mode 100644 index 00000000..54329bd4 --- /dev/null +++ b/devdocs/vagrant/networking%2Fpublic_network.html @@ -0,0 +1,63 @@ +

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, hence the ambiguous definition. The idea is that while private networks should never allow the general public access to your machine, public networks can.

Confused? We kind of are, too. It is likely that public networks will be replaced by :bridged 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.

+

Warning! 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 all potential security implications and review the default box configuration to identify potential security risks.

+

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:

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:

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.

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.

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:

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:

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:

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 access the Vagrant box from other networks over the public network. To do so, you can use a shell provisioner script:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/networking/public_network.html +

+
diff --git a/devdocs/vagrant/other%2Fdebugging.html b/devdocs/vagrant/other%2Fdebugging.html new file mode 100644 index 00000000..a8e6eb8a --- /dev/null +++ b/devdocs/vagrant/other%2Fdebugging.html @@ -0,0 +1,16 @@ +

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.

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"
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/other/debugging.html +

+
diff --git a/devdocs/vagrant/other%2Fenvironmental-variables.html b/devdocs/vagrant/other%2Fenvironmental-variables.html new file mode 100644 index 00000000..b3b2f155 --- /dev/null +++ b/devdocs/vagrant/other%2Fenvironmental-variables.html @@ -0,0 +1,6 @@ +

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.

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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_WINPTY_DISABLE

If this is set, Vagrant will not wrap interactive processes with winpty where required.

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_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_DISABLE_VBOXSYMLINKCREATE

If set, this will disable the ability to create symlinks with all virtualbox shared folders. Defaults to true if the option is not set. This can be overridden on a per-folder basis within your Vagrantfile config by settings the SharedFoldersEnableSymlinksCreate option to true.

VAGRANT_ENABLE_RESOLV_REPLACE

Use the Ruby Resolv library in place of the libc resolver.

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_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_USE_VAGRANT_TRIGGERS

Vagrant will not display the warning about disabling the core trigger feature if the community plugin is installed.

VAGRANT_IGNORE_WINRM_PLUGIN

Vagrant will not display warning when vagrant-winrm plugin is installed.

VAGRANT_USER_AGENT_PROVISIONAL_STRING

Vagrant will append the contents of this variable to the default user agent header.

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/other/environmental-variables.html +

+
diff --git a/devdocs/vagrant/other%2Findex.html b/devdocs/vagrant/other%2Findex.html new file mode 100644 index 00000000..050f6271 --- /dev/null +++ b/devdocs/vagrant/other%2Findex.html @@ -0,0 +1,8 @@ +

Other

This section covers other information that does not quite fit under the other categories.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/other/ +

+
diff --git a/devdocs/vagrant/other%2Fwsl.html b/devdocs/vagrant/other%2Fwsl.html new file mode 100644 index 00000000..d5d3302f --- /dev/null +++ b/devdocs/vagrant/other%2Fwsl.html @@ -0,0 +1,22 @@ +

Vagrant and Windows Subsystem for Linux

Recent versions of Windows 10 now include Windows Subsystem for Linux (WSL) as an optional Windows feature. The WSL supports running a Linux environment within Windows. Vagrant support for WSL is still in development and should be considered beta.

Warning: Advanced Topic! Using Vagrant within the Windows Subsystem for Linux is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Windows, WSL, and Linux should approach.

+

Vagrant Installation

Vagrant must be installed within the Linux distribution used with WSL. While the vagrant.exe executable provided by the Vagrant Windows installation is accessible from within the WSL, it will not function as expected.

Download the installer package for the Linux distribution from the releases page and install Vagrant.

_NOTE: When Vagrant is installed on the Windows system the version installed within the Linux distribution must match.

Vagrant Usage

Windows Access

By default Vagrant will not access features available on the Windows system from within the WSL. This means the VirtualBox and Hyper-V providers will not be available. To enable Windows access, which will also enable the VirtualBox and Hyper-V providers, set the VAGRANT_WSL_ENABLE_WINDOWS_ACCESS environment variable:

$ 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:

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

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/other/wsl.html +

+
diff --git a/devdocs/vagrant/plugins%2Faction-hooks.html b/devdocs/vagrant/plugins%2Faction-hooks.html new file mode 100644 index 00000000..69f78e05 --- /dev/null +++ b/devdocs/vagrant/plugins%2Faction-hooks.html @@ -0,0 +1,26 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

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.

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/action-hooks.html +

+
diff --git a/devdocs/vagrant/plugins%2Fcommands.html b/devdocs/vagrant/plugins%2Fcommands.html new file mode 100644 index 00000000..cb46319a --- /dev/null +++ b/devdocs/vagrant/plugins%2Fcommands.html @@ -0,0 +1,43 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Definition Component

Within the context of a plugin definition, new commands can be defined like so:

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:

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:

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

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/commands.html +

+
diff --git a/devdocs/vagrant/plugins%2Fconfiguration.html b/devdocs/vagrant/plugins%2Fconfiguration.html new file mode 100644 index 00000000..b0e751f8 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fconfiguration.html @@ -0,0 +1,85 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Definition Component

Within the context of a plugin definition, new configuration keys can be defined like so:

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:

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:

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

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:

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:

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:

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/configuration.html +

+
diff --git a/devdocs/vagrant/plugins%2Fdevelopment-basics.html b/devdocs/vagrant/plugins%2Fdevelopment-basics.html new file mode 100644 index 00000000..bd12bb35 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fdevelopment-basics.html @@ -0,0 +1,35 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Plugins are written using Ruby and are packaged using RubyGems. Familiarity with Ruby is required, but the packaging and distribution 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:

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:

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:

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.

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 within the comments of their source.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/development-basics.html +

+
diff --git a/devdocs/vagrant/plugins%2Fguest-capabilities.html b/devdocs/vagrant/plugins%2Fguest-capabilities.html new file mode 100644 index 00000000..8dd11b82 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fguest-capabilities.html @@ -0,0 +1,22 @@ +

Plugin Development: Guest Capabilities

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Guest capabilities augment guests 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:

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:

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/guest-capabilities.html +

+
diff --git a/devdocs/vagrant/plugins%2Fguests.html b/devdocs/vagrant/plugins%2Fguests.html new file mode 100644 index 00000000..2aef797e --- /dev/null +++ b/devdocs/vagrant/plugins%2Fguests.html @@ -0,0 +1,23 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

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:

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:

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 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 system. Vagrant handles inheritance dispatch for you.

To subclass another guest, specify that guest's name as a second parameter in the guest definition:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/guests.html +

+
diff --git a/devdocs/vagrant/plugins%2Fhost-capabilities.html b/devdocs/vagrant/plugins%2Fhost-capabilities.html new file mode 100644 index 00000000..c41d3660 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fhost-capabilities.html @@ -0,0 +1,9 @@ +

Plugin Development: Host Capabilities

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Host capabilities augment hosts 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.

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:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/host-capabilities.html +

+
diff --git a/devdocs/vagrant/plugins%2Fhosts.html b/devdocs/vagrant/plugins%2Fhosts.html new file mode 100644 index 00000000..c5fd5344 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fhosts.html @@ -0,0 +1,23 @@ +

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

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 to perform these host OS-specific operations.

Definition Component

Within the context of a plugin definition, new hosts can be defined like so:

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.

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 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 system. Vagrant handles inheritance dispatch for you.

To subclass another host, specify that host's name as a second parameter in the host definition:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/hosts.html +

+
diff --git a/devdocs/vagrant/plugins%2Findex.html b/devdocs/vagrant/plugins%2Findex.html new file mode 100644 index 00000000..eb8b1e6d --- /dev/null +++ b/devdocs/vagrant/plugins%2Findex.html @@ -0,0 +1,6 @@ +

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. Since Vagrant dogfoods 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/ +

+
diff --git a/devdocs/vagrant/plugins%2Fpackaging.html b/devdocs/vagrant/plugins%2Fpackaging.html new file mode 100644 index 00000000..ff193fdb --- /dev/null +++ b/devdocs/vagrant/plugins%2Fpackaging.html @@ -0,0 +1,23 @@ +

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. Prior to reading this, you should be familiar with the plugin development basics.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

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.

By using Bundler 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 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 for a good example.

+

Do not depend on Vagrant 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.

+

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:

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:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/packaging.html +

+
diff --git a/devdocs/vagrant/plugins%2Fproviders.html b/devdocs/vagrant/plugins%2Fproviders.html new file mode 100644 index 00000000..ff311ae9 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fproviders.html @@ -0,0 +1,30 @@ +

Plugin Development: Providers

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.

Prior to developing a provider you should also be familiar with how providers work from a user standpoint.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

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

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. The documentation done on the class in the comments should be enough to understand what needs to be done.

Viewing the AWS provider class as well as the overall structure of the plugin 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.

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:

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.

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, 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. The AWS provider uses a similar process.

Built-in Middleware

To assist with common tasks, Vagrant ships with a set of built-in middleware. 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 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, 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. When defining the configuration component, name the configuration the same as the provider, and as a second parameter, specify :provider, like so:

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:

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

Best practice: Your provider should not require provider-specific configuration to function, if possible. Vagrant practices a strong convention over configuration philosophy. When a user installs your provider, they should ideally be able to vagrant up --provider=your_provider and have it just work.

+

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

provider("my_cloud", parallel: true) do
+  require_relative "provider"
+  Provider
+end
+
+

That is the only change that is needed to enable parallelization.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/providers.html +

+
diff --git a/devdocs/vagrant/plugins%2Fprovisioners.html b/devdocs/vagrant/plugins%2Fprovisioners.html new file mode 100644 index 00000000..e1deb123 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fprovisioners.html @@ -0,0 +1,12 @@ +

Plugin Development: Provisioners

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.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

+

Definition Component

Within the context of a plugin definition, new provisioners can be defined like so:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/provisioners.html +

+
diff --git a/devdocs/vagrant/plugins%2Fusage.html b/devdocs/vagrant/plugins%2Fusage.html new file mode 100644 index 00000000..c14b42d8 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fusage.html @@ -0,0 +1,15 @@ +

Plugin Usage

Installing a Vagrant plugin is easy, and should not take more than a few seconds.

Please refer to the documentation of any plugin you plan on using for more information on how to use it, but there is one common method for installation and plugin activation.

Warning! 3rd party plugins can introduce instabilities into Vagrant due to the nature of them being written by non-core users.

+

Installation

Plugins are installed using vagrant plugin install:

# 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:

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/plugins/usage.html +

+
diff --git a/devdocs/vagrant/providers%2Fbasic_usage.html b/devdocs/vagrant/providers%2Fbasic_usage.html new file mode 100644 index 00000000..4793dfe7 --- /dev/null +++ b/devdocs/vagrant/providers%2Fbasic_usage.html @@ -0,0 +1,27 @@ +

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 "precise64" box.

Installing boxes has not changed at all:

$ vagrant box add hashicorp/precise64
+
+

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
+precise64 (virtualbox)
+precise64 (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.

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 same machine with both VirtualBox and VMware Fusion. This is a limitation that will be removed in a future version of Vagrant.

+

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

Vagrant.configure("2") do |config|
+  # ... other config up here
+
+  # Prefer VMware Fusion before VirtualBox
+  config.vm.provider "vmware_fusion"
+  config.vm.provider "virtualbox"
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/basic_usage.html +

+
diff --git a/devdocs/vagrant/providers%2Fconfiguration.html b/devdocs/vagrant/providers%2Fconfiguration.html new file mode 100644 index 00000000..cfdc3f4c --- /dev/null +++ b/devdocs/vagrant/providers%2Fconfiguration.html @@ -0,0 +1,22 @@ +

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:

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:

Vagrant.configure("2") do |config|
+  config.vm.box = "precise64"
+
+  config.vm.provider "vmware_fusion" do |v, override|
+    override.vm.box = "precise64_fusion"
+  end
+end
+
+

In the above case, Vagrant will use the "precise64" box by default, but will use "precise64_fusion" if the VMware Fusion provider is used.

The Vagrant Way: 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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/configuration.html +

+
diff --git a/devdocs/vagrant/providers%2Fcustom.html b/devdocs/vagrant/providers%2Fcustom.html new file mode 100644 index 00000000..a123cfdc --- /dev/null +++ b/devdocs/vagrant/providers%2Fcustom.html @@ -0,0 +1,6 @@ +

Custom Provider

To learn how to make your own custom Vagrant providers, read the Vagrant plugin development guide on creating custom providers.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/custom.html +

+
diff --git a/devdocs/vagrant/providers%2Fdefault.html b/devdocs/vagrant/providers%2Fdefault.html new file mode 100644 index 00000000..85cbbbcc --- /dev/null +++ b/devdocs/vagrant/providers%2Fdefault.html @@ -0,0 +1,6 @@ +

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_fusion and it will be your default.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/default.html +

+
diff --git a/devdocs/vagrant/providers%2Findex.html b/devdocs/vagrant/providers%2Findex.html new file mode 100644 index 00000000..1931f338 --- /dev/null +++ b/devdocs/vagrant/providers%2Findex.html @@ -0,0 +1,6 @@ +

Providers

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.

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

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/ +

+
diff --git a/devdocs/vagrant/providers%2Finstallation.html b/devdocs/vagrant/providers%2Finstallation.html new file mode 100644 index 00000000..b183c4e6 --- /dev/null +++ b/devdocs/vagrant/providers%2Finstallation.html @@ -0,0 +1,6 @@ +

Provider Installation

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/providers/installation.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fansible.html b/devdocs/vagrant/provisioning%2Fansible.html new file mode 100644 index 00000000..70895a6b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible.html @@ -0,0 +1,64 @@ +

Ansible Provisioner

Provisioner name: ansible

The Vagrant Ansible provisioner allows you to provision the guest using Ansible playbooks by executing ansible-playbook from the Vagrant host.

Warning: If you are not familiar with Ansible and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.

+

Setup Requirements

If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the Ansible Local provisioner 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.

Simplest Configuration

To run Ansible against your Vagrant guest, the basic Vagrantfile configuration looks like:

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.

Tips and Tricks

Ansible Parallel Execution

Vagrant is designed to provision multi-machine environments in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:

# 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
+
+

Tip: 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. 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).

+

Force Paramiko Connection Mode

The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for 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:

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):

ansible.inventory_path = "./my-inventory"
+ansible.raw_arguments  = [
+  "--connection=paramiko",
+  "--private-key=/home/.../.vagrant/machines/.../private_key"
+]
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/ansible.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fansible_common.html b/devdocs/vagrant/provisioning%2Fansible_common.html new file mode 100644 index 00000000..70d86df8 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_common.html @@ -0,0 +1,72 @@ +

Shared Ansible Options

The following options are available to both Vagrant Ansible provisioners:

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.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/ansible_common.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fansible_intro.html b/devdocs/vagrant/provisioning%2Fansible_intro.html new file mode 100644 index 00000000..98427e42 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_intro.html @@ -0,0 +1,132 @@ +

Ansible and Vagrant

The information below is applicable to both Vagrant Ansible provisioners:

The list of common options for these two provisioners is documented in a separate documentation page.

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.

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 goes into great detail on how to author playbooks, and there are a number of best practices 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 that make running otherwise tedious tasks dead simple.

Running Ansible

The playbook option is strictly required by both Ansible provisioners (ansible and ansible_local), as illustrated in this basic Vagrantfile` configuration:

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 like this:

.
+|-- Vagrantfile
+|-- provisioning
+|   |-- group_vars
+|           |-- all
+|   |-- roles
+|           |-- bar
+|           |-- foo
+|   |-- playbook.yml
+
+

In such an arrangement, the ansible.playbook path should be adjusted accordingly:

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 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 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 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, e.g. /tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory.

Host Variables

As of Vagrant 1.8.0, the host_vars option can be used to set variables for individual hosts 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 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, and group members as host ranges (with numeric or alphabetic patterns).

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:

Static Inventory

The second option is for situations where you would like to have more control over the inventory management.

With the inventory_path option, you can reference a specific inventory resource (e.g. a static inventory file, a dynamic inventory script or even multiple inventories stored in the same directory). 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 Ansible Configuration File

Certain settings in Ansible are (only) adjustable via a configuration file, 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:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/ansible_intro.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fansible_local.html b/devdocs/vagrant/provisioning%2Fansible_local.html new file mode 100644 index 00000000..48742f8b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_local.html @@ -0,0 +1,99 @@ +

Ansible Local Provisioner

Provisioner name: ansible_local

The Vagrant Ansible Local provisioner allows you to provision the guest using Ansible playbooks by executing ansible-playbook directly on the guest machine.

Warning: If you are not familiar with Ansible and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.

+

Setup Requirements

The main advantage of the Ansible Local provisioner in comparison to the Ansible (remote) provisioner is that it does not require any additional software on your Vagrant host.

On the other hand, Ansible must obviously be installed 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.

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.

Simplest Configuration

To run Ansible from your Vagrant guest, the basic Vagrantfile configuration looks like:

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:

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.

Tips and Tricks

Install Galaxy Roles in a path owned by root

+
Disclaimer: 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.

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:

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.

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_ssh_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key
+node2      ansible_ssh_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 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
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/ansible_local.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fbasic_usage.html b/devdocs/vagrant/provisioning%2Fbasic_usage.html new file mode 100644 index 00000000..08a830b0 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fbasic_usage.html @@ -0,0 +1,83 @@ +

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.

Configuration

First, every provisioner is configured within your Vagrantfile using the config.vm.provision method call. For example, the Vagrantfile below enables shell provisioning:

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:

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:

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:

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:

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 definition, then maybe in a provider-specific override), then the outer scopes will always run before any inner scopes. For example, in the Vagrantfile below:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell", inline: "echo foo"
+
+  config.vm.define "web" do |web|
+    web.vm.provision "shell", inline: "echo bar"
+  end
+
+  config.vm.provision "shell", inline: "echo baz"
+end
+
+

The ordering of the provisioners will be to echo "foo", "baz", then "bar" (note the second one might not be what you expect!). Remember: ordering is outside in.

With multiple provisioners, use the --provision-with setting along with names to get more fine grained control over what is run and when.

Overriding Provisioner Settings

Warning: Advanced Topic! Provisioner overriding is an advanced topic that really only becomes useful if you are already using multi-machine and/or provider overrides. If you are just getting started with Vagrant, you can safely skip this.

+

When using features such as multi-machine or provider-specific overrides, 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.

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":

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:

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

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/basic_usage.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fcfengine.html b/devdocs/vagrant/provisioning%2Fcfengine.html new file mode 100644 index 00000000..95394d81 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fcfengine.html @@ -0,0 +1,43 @@ +

CFEngine Provisioner

Provisioner name: cfengine

The Vagrant CFEngine provisioner allows you to provision the guest using CFEngine. It can set up both CFEngine policy servers and clients. You can configure both the policy server and the clients in a single multi-machine Vagrantfile.

Warning: If you are not familiar with CFEngine and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn CFEngine.

+

Let us look at some common examples first. See the bottom of this document for a comprehensive list of options.

Setting up a CFEngine server and client

The CFEngine provisioner automatically installs the latest CFEngine Community packages on the VM, then configures and starts CFEngine according to your specification.

Configuring a VM as a CFEngine policy server is easy:

Vagrant.configure("2") do |config|
+  config.vm.provision "cfengine" do |cf|
+    cf.am_policy_hub = true
+  end
+end
+
+

The host will automatically be bootstrapped to itself to become a policy server.

If you already have a working CFEngine policy server, you can get a CFEngine client installed and bootstrapped by specifying its IP address:

Vagrant.configure("2") do |config|
+  config.vm.provision "cfengine" do |cf|
+    cf.policy_server_address = "10.0.2.15"
+  end
+end
+
+

Copying files to the VM

If you have some policy or other files that you want to install by default on a VM, you can use the files_path attribute:

Vagrant.configure("2") do |config|
+   config.vm.provision "cfengine" do |cf|
+      cf.am_policy_hub = true
+      cf.files_path = "cfengine_files"
+    end
+  end
+
+

Everything under cfengine_files/ in the Vagrant project directory will be recursively copied under /var/cfengine/ in the VM, on top of its default contents.

A common use case is to add your own files to /var/cfengine/masterfiles/ in the policy server. Assuming your extra files are stored under cfengine_files/masterfiles/, the line shown above will add them to the VM after CFEngine is installed, but before it is bootstrapped.

Modes of operation

The default mode of operation is :bootstrap, which results in CFEngine being bootstrapped according to the information provided in the Vagrantfile. You can also set mode to :single_run, which will run cf-agent once on the host to execute the file specified in the run_file parameter, but will not bootstrap it, so it will not be executed periodically.

The recommended mode of operation is :bootstrap, as you get the full benefits of CFEngine when you have it running periodically.

Running a standalone file

If you want to run a standalone file, you can specify the run_file parameter. The file will be copied to the VM and executed on its own using cf-agent. Note that the file needs to be a standalone policy, including its own body common control.

The run_file parameter is mandatory if mode is set to :single_run, but can also be specified when mode is set to :bootstrap - in this case the file will be executed after the host has been bootstrapped.

Full Alphabetical List of Configuration Options

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/cfengine.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fchef_apply.html b/devdocs/vagrant/provisioning%2Fchef_apply.html new file mode 100644 index 00000000..b701ee4e --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_apply.html @@ -0,0 +1,34 @@ +

Chef Apply Provisioner

Provisioner name: chef_apply

The Vagrant Chef Apply provisioner allows you to provision the guest using Chef, specifically with Chef Apply.

Chef Apply is ideal for people who are already experienced with Chef and the Chef ecosystem. Specifically, this documentation page does not cover how use Chef or how to write Chef recipes.

Warning: If you are not familiar with Chef and Vagrant already, we recommend starting with the shell provisioner.

+

Options

This section lists the complete set of available options for the Chef Apply provisioner. More detailed examples of how to use the provisioner are available below this section.

In addition to all the options listed above, the Chef Apply provisioner supports the common options for all Chef provisioners.

Specifying a Recipe

The easiest way to get started with the Chef Apply provisioner is to just specify an inline Chef recipe. For example:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_apply" do |chef|
+    chef.recipe = "package[apache2]"
+  end
+end
+
+

This causes Vagrant to run Chef Apply with the given recipe contents. If you are familiar with Chef, you know this will install the apache2 package from the system package provider.

Since single-line Chef recipes are rare, you can also specify the recipe using a "heredoc":

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_apply" do |chef|
+    chef.recipe = <<-RECIPE
+      package "apache2"
+
+      template "/etc/apache2/my.config" do
+        # ...
+      end
+    RECIPE
+  end
+end
+
+

Finally, if you would prefer to store the recipe as plain-text, you can set the recipe to the contents of a file:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_apply" do |chef|
+    chef.recipe = File.read("/path/to/my/recipe.rb")
+  end
+end
+
+

Roles

The Vagrant Chef Apply provisioner does not support roles. Please use a different Vagrant Chef provisioner if you need support for roles.

Data Bags

The Vagrant Chef Apply provisioner does not support data_bags. Please use a different Vagrant Chef provisioner if you need support for data_bags.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/chef_apply.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fchef_client.html b/devdocs/vagrant/provisioning%2Fchef_client.html new file mode 100644 index 00000000..520ffa4c --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_client.html @@ -0,0 +1,42 @@ +

Chef Client Provisioner

Provisioner name: chef_client

The Vagrant Chef Client provisioner allows you to provision the guest using Chef, specifically by connecting to an existing Chef Server and registering the Vagrant machine as a node within your infrastructure.

If you are just learning Chef for the first time, you probably want to start with the Chef Solo provisioner.

Warning: If you are not familiar with Chef and Vagrant already, I recommend starting with the shell provisioner.

+

Authenticating

The minimum required to use provision using Chef Client is to provide a URL to the Chef Server as well as the path to the validation key so that the node can register with the Chef Server:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    chef.chef_server_url = "http://mychefserver.com"
+    chef.validation_key_path = "validation.pem"
+  end
+end
+
+

The node will register with the Chef Server specified, download the proper run list for that node, and provision.

Specifying a Run List

Normally, the Chef Server is responsible for specifying the run list for the node. However, you can override what the Chef Server sends down by manually specifying a run list:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    # Add a recipe
+    chef.add_recipe "apache"
+
+    # Or maybe a role
+    chef.add_role "web"
+  end
+end
+
+

Remember, this will override the run list specified on the Chef server itself.

Environments

You can specify the environment for the node to come up in using the environment configuration option:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    # ...
+
+    chef.environment = "development"
+  end
+end
+
+

Other Configuration Options

There are a few more configuration options available. These generally do not need to be modified but are available if your Chef Server requires customization of these variables.

In addition to all the options listed above, the Chef Client provisioner supports the common options for all Chef provisioners.

Cleanup

When you provision your Vagrant virtual machine with Chef Server, it creates a new Chef "node" entry and Chef "client" entry on the Chef Server, using the hostname of the machine. After you tear down your guest machine, Vagrant can be configured to do it automatically with the following settings:

chef.delete_node = true
+chef.delete_client = true
+
+

If you do not specify it or set it to false, you must explicitly delete these entries from the Chef Server before you provision a new one with Chef Server. For example, using Chef's built-in knife tool:

$ knife node delete precise64
+$ knife client delete precise64
+
+

If you fail to do so, you will get the following error when Vagrant tries to provision the machine with Chef Client:

HTTP Request Returned 409 Conflict: Client already exists.
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/chef_client.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fchef_common.html b/devdocs/vagrant/provisioning%2Fchef_common.html new file mode 100644 index 00000000..5acd1f15 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_common.html @@ -0,0 +1,33 @@ +

Shared Chef Options

All Chef Provisioners

The following options are available to all Vagrant Chef provisioners. Many of these options are for advanced users only and should not be used unless you understand their purpose.

If you want to have https://example.com/install.sh as Omnibus script for your Linux/Unix installations, you should set this option to https://example.com

Runner Chef Provisioners

The following options are available to any of the Chef "runner" provisioners which include Chef Solo, Chef Zero, and Chef Client.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/chef_common.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fchef_solo.html b/devdocs/vagrant/provisioning%2Fchef_solo.html new file mode 100644 index 00000000..03c6e20b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_solo.html @@ -0,0 +1,71 @@ +

Chef Solo Provisioner

Provisioner name: chef_solo

The Vagrant Chef Solo provisioner allows you to provision the guest using Chef, specifically with Chef Solo.

Chef Solo is ideal for people who are already experienced with Chef, already have Chef cookbooks, or are looking to learn Chef. Specifically, this documentation page will not go into how to use Chef or how to write Chef cookbooks, since Chef is a complete system that is beyond the scope of a single page of documentation.

Warning: If you are not familiar with Chef and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Chef.

+

Options

This section lists the complete set of available options for the Chef Solo provisioner. More detailed examples of how to use the provisioner are available below this section.

In addition to all the options listed above, the Chef Solo provisioner supports the common options for all Chef provisioners.

Specifying a Run List

The easiest way to get started with the Chef Solo provisioner is to just specify a run list. This looks like:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.add_recipe "apache"
+  end
+end
+
+

This causes Vagrant to run Chef Solo with the "apache" cookbook. The cookbooks by default are looked for in the "cookbooks" directory relative to your project root. The directory structure ends up looking like this:

$ tree
+.
+|-- Vagrantfile
+|-- cookbooks
+|   |-- apache
+|       |-- recipes
+|           |-- default.rb
+
+

The order of the calls to add_recipe will specify the order of the run list. Earlier recipes added with add_recipe are run before later recipes added.

Custom Cookbooks Path

Instead of using the default "cookbooks" directory, a custom cookbooks path can also be set via the cookbooks_path configuration directive:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.cookbooks_path = "my_cookbooks"
+  end
+end
+
+

The path can be relative or absolute. If it is relative, it is relative to the project root.

The configuration value can also be an array of paths:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.cookbooks_path = ["cookbooks", "my_cookbooks"]
+  end
+end
+
+

Roles

Vagrant also supports provisioning with Chef roles. This is done by specifying a path to a roles folder where roles are defined and by adding roles to your run list:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.roles_path = "roles"
+    chef.add_role("web")
+  end
+end
+
+

Just like the cookbooks path, the roles path is relative to the project root if a relative path is given.

The configuration value can also be an array of paths on Chef 11.8.0 and newer. On older Chef versions only the first path is used.

Note: The name of the role file must be the same as the role name. For example the web role must be in the roles_path as web.json or web.rb. This is required by Chef itself, and is not a limitation imposed by Vagrant.

Data Bags

Data bags are also supported by the Chef Solo provisioner. This is done by specifying a path to your data bags directory:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.data_bags_path = "data_bags"
+  end
+end
+
+

Custom JSON Data

Additional configuration data for Chef attributes can be passed in to Chef Solo. This is done by setting the json property with a Ruby hash (dictionary-like object), which is converted to JSON and passed in to Chef:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    # ...
+
+    chef.json = {
+      "apache" => {
+        "listen_address" => "0.0.0.0"
+      }
+    }
+  end
+end
+
+

Hashes, arrays, etc. can be used with the JSON configuration object. Basically, anything that can be turned cleanly into JSON works.

Custom Node Name

You can specify a custom node name by setting the node_name property. This is useful for cookbooks that may depend on this being set to some sort of value. Example:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.node_name = "foo"
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/chef_solo.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fchef_zero.html b/devdocs/vagrant/provisioning%2Fchef_zero.html new file mode 100644 index 00000000..9adb69bf --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_zero.html @@ -0,0 +1,29 @@ +

Chef Zero Provisioner

Provisioner name: chef_zero

The Vagrant Chef Zero provisioner allows you to provision the guest using Chef, specifically with Chef Zero/local mode.

This new provisioner is a middle ground between running a full blown Chef Server and using the limited Chef Solo provisioner. It runs a local in-memory Chef Server and fakes the validation and client key registration.

Warning: If you are not familiar with Chef and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Chef.

+

Options

This section lists the complete set of available options for the Chef Zero provisioner. More detailed examples of how to use the provisioner are available below this section.

In addition to all the options listed above, the Chef Zero provisioner supports the common options for all Chef provisioners.

Usage

The Chef Zero provisioner is configured basically the same way as the Chef Solo provisioner. See the Chef Solo documentations for more information.

A basic example could look like this:

Vagrant.configure("2") do |config|
+  config.vm.provision "chef_zero" do |chef|
+    # Specify the local paths where Chef data is stored
+    chef.cookbooks_path = "cookbooks"
+    chef.data_bags_path = "data_bags"
+    chef.nodes_path = "nodes"
+    chef.roles_path = "roles"
+
+    # Add a recipe
+    chef.add_recipe "apache"
+
+    # Or maybe a role
+    chef.add_role "web"
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/chef_zero.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fdocker.html b/devdocs/vagrant/provisioning%2Fdocker.html new file mode 100644 index 00000000..7f4d00d2 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fdocker.html @@ -0,0 +1,66 @@ +

Docker Provisioner

Provisioner name: "docker"

The Vagrant Docker provisioner can automatically install Docker, pull Docker containers, and configure certain containers to run on boot.

The docker provisioner is ideal for organizations that are using Docker as a means to distribute things like their application or services. Or, if you are just getting started with Docker, the Docker provisioner provides the easiest possible way to begin using Docker since the provisioner automates installing Docker for you.

As with all provisioners, the Docker provisioner can be used along with all the other provisioners Vagrant has in order to setup your working environment the best way possible. For example, perhaps you use Puppet to install services like databases or web servers but use Docker to house your application runtime. You can use the Puppet provisioner along with the Docker provisioner.

Note: This documentation is for the Docker provisioner. If you are looking for the Docker provider, visit the Docker provider documentation.

+

Options

The docker provisioner takes various options. None are required. If no options are required, the Docker provisioner will only install Docker for you (if it is not already installed).

In addition to the options that can be set, various functions are available and can be called to configure other aspects of the Docker provisioner. Most of these functions have examples in more detailed sections below.

Building Images

The provisioner can automatically build images. Images are built prior to any configured containers to run, so you can build an image before running it. Building an image is easy:

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.build_image "/vagrant/app"
+  end
+end
+
+

The argument to build an image is the path to give to docker build. This must be a path that exists within the guest machine. If you need to get data to the guest machine, use a synced folder.

The build_image function accepts options as a second parameter. Here are the available options:

Pulling Images

The docker provisioner can automatically pull images from the Docker registry for you. There are two ways to specify images to pull. The first is as an array using images:

Vagrant.configure("2") do |config|
+  config.vm.provision "docker",
+    images: ["ubuntu"]
+end
+
+

This will cause Vagrant to pull the "ubuntu" image from the registry for you automatically.

The second way to pull images is to use the pull_images function. Each call to pull_images will append the images to be pulled. The images variable, on the other hand, can only be used once.

Additionally, the pull_images function cannot be used with the simple configuration method for provisioners (specifying it all in one line).

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.pull_images "ubuntu"
+    d.pull_images "vagrant"
+  end
+end
+
+

Running Containers

In addition to pulling images, the Docker provisioner can run and start containers for you. This lets you automatically start services as part of vagrant up.

Running containers can only be configured using the Ruby block syntax with the do...end blocks. An example of running a container is shown below:

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.run "rabbitmq"
+  end
+end
+
+

This will docker run a container with the "rabbitmq" image. Note that Vagrant uses the first parameter (the image name by default) to override any settings used in a previous run definition. Therefore, if you need to run multiple containers from the same image then you must specify the image option (documented below) with a unique name.

In addition to the name, the run method accepts a set of options, all optional:

For example, here is how you would configure Docker to run a container with the Vagrant shared directory mounted inside of it:

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.run "ubuntu",
+      cmd: "bash -l",
+      args: "-v '/vagrant:/var/www'"
+  end
+end
+
+

In case you need to run multiple containers based off the same image, you can do so by providing different names and specifying the image parameter to it:

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.run "db-1", image: "user/mysql"
+    d.run "db-2", image: "user/mysql"
+  end
+end
+
+

Other

This section documents some other things related to the Docker provisioner that are generally useful to know if you are using this provisioner.

Customize /etc/default/docker

To customize this file, use the post_install_provisioner shell provisioner.

Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.post_install_provision "shell", inline:"echo export http_proxy='http://127.0.0.1:3128/' >> /etc/default/docker"
+    d.run "ubuntu",
+      cmd: "bash -l",
+      args: "-v '/vagrant:/var/www'"
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/docker.html +

+
diff --git a/devdocs/vagrant/provisioning%2Ffile.html b/devdocs/vagrant/provisioning%2Ffile.html new file mode 100644 index 00000000..10cce357 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Ffile.html @@ -0,0 +1,53 @@ +

File Provisioner

Provisioner name: "file"

The Vagrant file provisioner allows you to upload a file or directory from the host machine to the guest machine.

File provisioning is a simple way to, for example, replicate your local ~/.gitconfig to the vagrant user's home directory on the guest machine so you will not have to run git config --global every time you provision a new VM.

Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
+end
+
+

If you want to upload a folder to your guest system, it can be accomplished by using a file provisioner seen below. When copied, the resulting folder on the guest will replace folder as newfolder and place its on the guest machine. Note that if you'd like the same folder name on your guest machine, make sure that the destination path has the same name as the folder on your host.

Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "file", source: "~/path/to/host/folder", destination: "$HOME/remote/newfolder"
+end
+
+

Prior to copying ~/path/to/host/folder to the guest machine:

    folder
+    ├── script.sh
+    ├── otherfolder
+    │   └── hello.sh
+    ├── goodbye.sh
+    ├── hello.sh
+    └── woot.sh
+
+    1 directory, 5 files
+
+

After to copying ~/path/to/host/folder into $HOME/remote/newfolder to the guest machine:

    newfolder
+    ├── script.sh
+    ├── otherfolder
+    │   └── hello.sh
+    ├── goodbye.sh
+    ├── hello.sh
+    └── woot.sh
+
+    1 directory, 5 files
+
+

Note that, unlike with synced folders, files or directories that are uploaded will not be kept in sync. Continuing with the example above, if you make further changes to your local ~/.gitconfig, they will not be immediately reflected in the copy you uploaded to the guest machine.

The file uploads by the file provisioner are done as the SSH or PowerShell user. This is important since these users generally do not have elevated privileges on their own. If you want to upload files to locations that require elevated privileges, we recommend uploading them to temporary locations and then using the shell provisioner to move them into place.

Options

The file provisioner takes only two options, both of which are required:

Caveats

While the file provisioner does support trailing slashes or "globing", this can lead to some confusing results due to the underlying tool used to copy files and folders between the host and guests. For example, if you have a source and destination with a trailing slash defined below:

config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/"
+
+

You are telling vagrant to upload ~/pathfolder under the remote dir /remote/newlocation, which will look like:

    newlocation
+    ├── pathfolder
+    │   └── file.sh
+
+    1 directory, 2 files
+
+

This behavior can also be achieved by defining your file provisioner below:

config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/pathfolder"
+
+

Another example is using globing on the host machine to grab all files within a folder, but not the top level folder itself:

config.vm.provision "file", source: "~/otherfolder/.", destination: "/remote/otherlocation"
+
+

The file provisioner is defined to include all files under ~/otherfolder to the new location /remote/otherlocation. This idea can be achieved by simply having your destination folder differ from the source folder:

config.vm.provision "file", source: "/otherfolder", destination: "/remote/otherlocation"
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/file.html +

+
diff --git a/devdocs/vagrant/provisioning%2Findex.html b/devdocs/vagrant/provisioning%2Findex.html new file mode 100644 index 00000000..8dbec953 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Findex.html @@ -0,0 +1,9 @@ +

Provisioning

Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the vagrant up process.

This is useful since boxes typically are not built perfectly for your use case. Of course, if you want to just use vagrant ssh and install the software by hand, that works. But by using the provisioning systems built-in to Vagrant, it automates the process so that it is repeatable. Most importantly, it requires no human interaction, so you can vagrant destroy and vagrant up and have a fully ready-to-go work environment with a single command. Powerful.

Vagrant gives you multiple options for provisioning the machine, from simple shell scripts to more complex, industry-standard configuration management systems.

If you've never used a configuration management system before, it is recommended you start with basic shell scripts for provisioning.

You can find the full list of built-in provisioners and usage of these provisioners in the navigational area to the left.

When Provisioning Happens

Provisioning happens at certain points during the lifetime of your Vagrant environment:

You can also bring up your environment and explicitly not run provisioners by specifying --no-provision.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/ +

+
diff --git a/devdocs/vagrant/provisioning%2Fpuppet_agent.html b/devdocs/vagrant/provisioning%2Fpuppet_agent.html new file mode 100644 index 00000000..629d5e30 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fpuppet_agent.html @@ -0,0 +1,31 @@ +

Puppet Agent Provisioner

Provisioner name: puppet_server

The Vagrant Puppet agent provisioner allows you to provision the guest using Puppet, specifically by calling puppet agent, connecting to a Puppet master, and retrieving the set of modules and manifests from there.

Warning: If you are not familiar with Puppet and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Puppet.

+

Options

The puppet_server provisioner takes various options. None are strictly required. They are listed below:

Specifying the Puppet Master

The quickest way to get started with the Puppet agent provisioner is to just specify the location of the Puppet master:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet_server" do |puppet|
+    puppet.puppet_server = "puppet.example.com"
+  end
+end
+
+

By default, Vagrant will look for the host named "puppet" on the local domain of the guest machine.

Configuring the Node Name

The node name that the agent registers as can be customized. Remember this is important because Puppet uses the node name as part of the process to compile the catalog the node will run.

The node name defaults to the hostname of the guest machine, but can be customized using the Vagrantfile:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet_server" do |puppet|
+    puppet.puppet_node = "node.example.com"
+  end
+end
+
+

Additional Options

Puppet supports a lot of command-line flags. Basically any setting can be overridden on the command line. To give you the most power and flexibility possible with Puppet, Vagrant allows you to specify custom command line flags to use:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet_server" do |puppet|
+    puppet.options = "--verbose --debug"
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/puppet_agent.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fpuppet_apply.html b/devdocs/vagrant/provisioning%2Fpuppet_apply.html new file mode 100644 index 00000000..1640e113 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fpuppet_apply.html @@ -0,0 +1,78 @@ +

Puppet Apply Provisioner

Provisioner name: puppet

The Vagrant Puppet provisioner allows you to provision the guest using Puppet, specifically by calling puppet apply, without a Puppet Master.

Warning: If you are not familiar with Puppet and Vagrant already, I recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Puppet.

+

Options

This section lists the complete set of available options for the Puppet provisioner. More detailed examples of how to use the provisioner are available below this section.

Bare Minimum

The quickest way to get started with the Puppet provisioner is to just enable it:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet"
+end
+
+

By default, Vagrant will configure Puppet to look for manifests in the "manifests" folder relative to the project root, and will use the "default.pp" manifest as an entry-point. This means, if your directory tree looks like the one below, you can get started with Puppet with just that one line in your Vagrantfile.

$ tree
+.
+|-- Vagrantfile
+|-- manifests
+|   |-- default.pp
+
+

Custom Manifest Settings

Of course, you are able to put and name your manifests whatever you would like. You can override both the directory where Puppet looks for manifests with manifests_path, and the manifest file used as the entry-point with manifest_file:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.manifests_path = "my_manifests"
+    puppet.manifest_file = "default.pp"
+  end
+end
+
+

The path can be relative or absolute. If it is relative, it is relative to the project root.

You can also specify a manifests path that is on the remote machine already, perhaps put in place by a shell provisioner. In this case, Vagrant will not attempt to upload the manifests directory. To specify a remote manifests path, use the following syntax:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.manifests_path = ["vm", "/path/to/manifests"]
+    puppet.manifest_file = "default.pp"
+  end
+end
+
+

It is a somewhat odd syntax, but the tuple (two-element array) says that the path is located in the "vm" at "/path/to/manifests".

Environments

If you are using Puppet 4 or higher, you can provision using Puppet Environments by specifying the name of the environment and the path on the local disk to the environment files:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.environment_path = "../puppet/environments"
+    puppet.environment = "testenv"
+  end
+end
+
+

The default manifest is the environment's manifests directory. If the environment has an environment.conf the manifest path is parsed from there. Relative paths are assumed to be relative to the directory of the environment. If the manifest setting in environment.conf use the Puppet variables $codedir or $environment they are resolved to the parent directory of environment_path and environment respectively.

Modules

Vagrant also supports provisioning with Puppet modules. This is done by specifying a path to a modules folder where modules are located. The manifest file is still used as an entry-point.

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.module_path = "modules"
+  end
+end
+
+

Just like the manifests path, the modules path is relative to the project root if a relative path is given.

Custom Facts

Custom facts to be exposed by Facter can be specified as well:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.facter = {
+      "vagrant" => "1"
+    }
+  end
+end
+
+

Now, the $vagrant variable in your Puppet manifests will equal "1".

Configuring Hiera

Hiera configuration is also supported. hiera_config_path specifies the path to the Hiera configuration file stored on the host. If the :datadir setting in the Hiera configuration file is a relative path, working_directory should be used to specify the directory in the guest that path is relative to.

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.hiera_config_path = "hiera.yaml"
+    puppet.working_directory = "/tmp/vagrant-puppet"
+  end
+end
+
+

hiera_config_path can be relative or absolute. If it is relative, it is relative to the project root. working_directory is an absolute path within the guest.

Additional Options

Puppet supports a lot of command-line flags. Basically any setting can be overridden on the command line. To give you the most power and flexibility possible with Puppet, Vagrant allows you to specify custom command line flags to use:

Vagrant.configure("2") do |config|
+  config.vm.provision "puppet" do |puppet|
+    puppet.options = "--verbose --debug"
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/puppet_apply.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fsalt.html b/devdocs/vagrant/provisioning%2Fsalt.html new file mode 100644 index 00000000..7d16bad3 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fsalt.html @@ -0,0 +1,75 @@ +

Salt Provisioner

Provisioner name: salt

The Vagrant Salt provisioner allows you to provision the guest using Salt states.

Salt states are YAML documents that describes the current state a machine should be in, e.g. what packages should be installed, which services are running, and the contents of arbitrary files.

NOTE: The Salt provisioner is builtin to Vagrant. If the vagrant-salt plugin is installed, it should be uninstalled to ensure expected behavior.

Masterless Quickstart

What follows is a basic Vagrantfile that will get salt working on a single minion, without a master:

  Vagrant.configure("2") do |config|
+    ## Choose your base box
+    config.vm.box = "precise64"
+
+    ## For masterless, mount your salt file root
+    config.vm.synced_folder "salt/roots/", "/srv/salt/"
+
+    ## Use all the defaults:
+    config.vm.provision :salt do |salt|
+
+      salt.masterless = true
+      salt.minion_config = "salt/minion"
+      salt.run_highstate = true
+
+    end
+  end
+
+

This sets up a shared folder for the salt root, and copies the minion file over, then runs state.highstate on the machine. Your minion file must contain the line file_client: local in order to work in a masterless setup.

Install Options

Minion Options

These only make sense when no_minion is false.

Master Options

These only make sense when install_master is true. Not supported on Windows guest machines.

Execute States

Either of the following may be used to actually execute states during provisioning.

Execute Runners

Either of the following may be used to actually execute runners during provisioning.

Output Control

These may be used to control the output of state execution:

Pillar Data

You can export pillar data for use during provisioning by using the pillar command. Each call will merge the data so you can safely call it multiple times. The data passed in should only be hashes and lists. Here is an example::

      config.vm.provision :salt do |salt|
+
+        # Export hostnames for webserver config
+        salt.pillar({
+          "hostnames" => {
+            "www" => "www.example.com",
+            "intranet" => "intranet.example.com"
+          }
+        })
+
+        # Export database credentials
+        salt.pillar({
+          "database" => {
+            "user" => "jdoe",
+            "password" => "topsecret"
+          }
+        })
+
+        salt.run_highstate = true
+
+      end
+
+

On Windows guests, this requires PowerShell 3.0 or higher.

Preseeding Keys

Preseeding keys is the recommended way to handle provisioning using a master. On a machine with salt installed, run salt-key --gen-keys=[minion_id] to generate the necessary .pub and .pem files

For an example of a more advanced setup, look at the original plugin.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/salt.html +

+
diff --git a/devdocs/vagrant/provisioning%2Fshell.html b/devdocs/vagrant/provisioning%2Fshell.html new file mode 100644 index 00000000..0b8112e5 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fshell.html @@ -0,0 +1,60 @@ +

Shell Provisioner

Provisioner name: "shell"

The Vagrant Shell provisioner allows you to upload and execute a script within the guest machine.

Shell provisioning is ideal for users new to Vagrant who want to get up and running quickly and provides a strong alternative for users who are not comfortable with a full configuration management system such as Chef or Puppet.

For POSIX-like machines, the shell provisioner executes scripts with SSH. For Windows guest machines that are configured to use WinRM, the shell provisioner executes PowerShell and Batch scripts over WinRM.

Options

The shell provisioner takes various options. One of inline or path is required:

The remainder of the available options are optional:

Inline Scripts

Perhaps the easiest way to get started is with an inline script. An inline script is a script that is given to Vagrant directly within the Vagrantfile. An example is best:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell",
+    inline: "echo Hello, World"
+end
+
+

This causes echo Hello, World to be run within the guest machine when provisioners are run.

Combined with a little bit more Ruby, this makes it very easy to embed your shell scripts directly within your Vagrantfile. Another example below:

$script = <<-SCRIPT
+echo I am provisioning...
+date > /etc/vagrant_provisioned_at
+SCRIPT
+
+Vagrant.configure("2") do |config|
+  config.vm.provision "shell", inline: $script
+end
+
+

I understand that if you are not familiar with Ruby, the above may seem very advanced or foreign. But do not fear, what it is doing is quite simple: the script is assigned to a global variable $script. This global variable contains a string which is then passed in as the inline script to the Vagrant configuration.

Of course, if any Ruby in your Vagrantfile outside of basic variable assignment makes you uncomfortable, you can use an actual script file, documented in the next section.

For Windows guest machines, the inline script must be PowerShell. Batch scripts are not allowed as inline scripts.

External Script

The shell provisioner can also take an option specifying a path to a shell script on the host machine. Vagrant will then upload this script into the guest and execute it. An example:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell", path: "script.sh"
+end
+
+

Relative paths, such as above, are expanded relative to the location of the root Vagrantfile for your project. Absolute paths can also be used, as well as shortcuts such as ~ (home directory) and .. (parent directory).

If you use a remote script as part of your provisioning process, you can pass in its URL as the path argument as well:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell", path: "https://example.com/provisioner.sh"
+end
+
+

If you are running a Batch or PowerShell script for Windows, make sure that the external path has the proper extension (".bat" or ".ps1"), because Windows uses this to determine what kind of file it is to execute. If you exclude this extension, it likely will not work.

To run a script already available on the guest you can use an inline script to invoke the remote script on the guest.

Vagrant.configure("2") do |config|
+  config.vm.provision "shell",
+    inline: "/bin/sh /path/to/the/script/already/on/the/guest.sh"
+end
+
+

Script Arguments

You can parameterize your scripts as well like any normal shell script. These arguments can be specified to the shell provisioner. They should be specified as a string as they'd be typed on the command line, so be sure to properly escape anything:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell" do |s|
+    s.inline = "echo $1"
+    s.args   = "'hello, world!'"
+  end
+end
+
+

You can also specify arguments as an array if you do not want to worry about quoting:

Vagrant.configure("2") do |config|
+  config.vm.provision "shell" do |s|
+    s.inline = "echo $1"
+    s.args   = ["hello, world!"]
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning/shell.html +

+
diff --git a/devdocs/vagrant/provisioning.html b/devdocs/vagrant/provisioning.html new file mode 100644 index 00000000..5af6b759 --- /dev/null +++ b/devdocs/vagrant/provisioning.html @@ -0,0 +1,9 @@ +

Provisioning

Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the vagrant up process.

This is useful since boxes typically are not built perfectly for your use case. Of course, if you want to just use vagrant ssh and install the software by hand, that works. But by using the provisioning systems built-in to Vagrant, it automates the process so that it is repeatable. Most importantly, it requires no human interaction, so you can vagrant destroy and vagrant up and have a fully ready-to-go work environment with a single command. Powerful.

Vagrant gives you multiple options for provisioning the machine, from simple shell scripts to more complex, industry-standard configuration management systems.

If you've never used a configuration management system before, it is recommended you start with basic shell scripts for provisioning.

You can find the full list of built-in provisioners and usage of these provisioners in the navigational area to the left.

When Provisioning Happens

Provisioning happens at certain points during the lifetime of your Vagrant environment:

You can also bring up your environment and explicitly not run provisioners by specifying --no-provision.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/provisioning +

+
diff --git a/devdocs/vagrant/push%2Fftp.html b/devdocs/vagrant/push%2Fftp.html new file mode 100644 index 00000000..06db78b1 --- /dev/null +++ b/devdocs/vagrant/push%2Fftp.html @@ -0,0 +1,22 @@ +

Vagrant Push

FTP & SFTP Strategy

Vagrant Push FTP and SFTP strategy pushes the code in your Vagrant development environment to a remote FTP or SFTP server.

The Vagrant Push FTP And SFTP strategy supports the following configuration options:

Usage

The Vagrant Push FTP and SFTP strategy is defined in the Vagrantfile using the ftp key:

config.push.define "ftp" do |push|
+  push.host = "ftp.company.com"
+  push.username = "username"
+  push.password = "password"
+end
+
+

And then push the application to the FTP or SFTP server:

$ vagrant push
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/push/ftp.html +

+
diff --git a/devdocs/vagrant/push%2Fheroku.html b/devdocs/vagrant/push%2Fheroku.html new file mode 100644 index 00000000..e9468d84 --- /dev/null +++ b/devdocs/vagrant/push%2Fheroku.html @@ -0,0 +1,15 @@ +

Vagrant Push

Heroku Strategy

Heroku is a public PAAS provider that makes it easy to deploy an application. The Vagrant Push Heroku strategy pushes your application's code to Heroku.

Warning: The Vagrant Push Heroku strategy requires you have configured your Heroku credentials and created the Heroku application. This documentation will not cover these prerequisites, but you can read more about them in the Heroku documentation.

+

Only files which are committed to the Git repository will be pushed to Heroku. Additionally, the current working branch is always pushed to the Heroku, even if it is not the "master" branch.

The Vagrant Push Heroku strategy supports the following configuration options:

Usage

The Vagrant Push Heroku strategy is defined in the Vagrantfile using the heroku key:

config.push.define "heroku" do |push|
+  push.app = "my_application"
+end
+
+

And then push the application to Heroku:

$ vagrant push
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/push/heroku.html +

+
diff --git a/devdocs/vagrant/push%2Findex.html b/devdocs/vagrant/push%2Findex.html new file mode 100644 index 00000000..86aa70fd --- /dev/null +++ b/devdocs/vagrant/push%2Findex.html @@ -0,0 +1,24 @@ +

Vagrant Push

As of version 1.7, Vagrant is capable of deploying or "pushing" application code in the same directory as your Vagrantfile to a remote such as an FTP server.

Pushes are defined in an application's Vagrantfile and are invoked using the vagrant push subcommand. Much like other components of Vagrant, each Vagrant Push plugin has its own configuration options. Please consult the documentation for your Vagrant Push plugin for more information. Here is an example Vagrant Push configuration section in a Vagrantfile:

config.push.define "ftp" do |push|
+  push.host = "ftp.company.com"
+  push.username = "..."
+  # ...
+end
+
+

When the application is ready to be deployed to the FTP server, just run a single command:

$ vagrant push
+
+

Much like Vagrant Providers, Vagrant Push also supports multiple backend declarations. Consider the common scenario of a staging and QA environment:

config.push.define "staging", strategy: "ftp" do |push|
+  # ...
+end
+
+config.push.define "qa", strategy: "ftp" do |push|
+  # ...
+end
+
+

In this scenario, the user must pass the name of the Vagrant Push to the subcommand:

$ vagrant push staging
+
+

Vagrant Push is the easiest way to deploy your application. You can read more in the documentation links on the sidebar.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/push/ +

+
diff --git a/devdocs/vagrant/push%2Flocal-exec.html b/devdocs/vagrant/push%2Flocal-exec.html new file mode 100644 index 00000000..e9df2f6f --- /dev/null +++ b/devdocs/vagrant/push%2Flocal-exec.html @@ -0,0 +1,28 @@ +

Vagrant Push

Local Exec Strategy

The Vagrant Push Local Exec strategy allows the user to invoke an arbitrary shell command or script as part of a push.

Warning: The Vagrant Push Local Exec strategy does not perform any validation on the correctness of the shell script.

+

The Vagrant Push Local Exec strategy supports the following configuration options:

Please note - only one of the script and inline options may be specified in a single push definition.

Usage

The Vagrant Push Local Exec strategy is defined in the Vagrantfile using the local-exec key:

Remote path:

config.push.define "local-exec" do |push|
+  push.inline = <<-SCRIPT
+    scp -r . server:/var/www/website
+  SCRIPT
+end
+
+

Local path:

config.push.define "local-exec" do |push|
+  push.inline = <<-SCRIPT
+    cp -r . /var/www/website
+  SCRIPT
+end
+
+

For more complicated scripts, you may store them in a separate file and read them from the Vagrantfile like so:

config.push.define "local-exec" do |push|
+  push.script = "my-script.sh"
+end
+
+

And then invoke the push with Vagrant:

$ vagrant push
+
+

Script Arguments

Refer to Shell Provisioner.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/push/local-exec.html +

+
diff --git a/devdocs/vagrant/share%2Fconnect.html b/devdocs/vagrant/share%2Fconnect.html new file mode 100644 index 00000000..6fb882d5 --- /dev/null +++ b/devdocs/vagrant/share%2Fconnect.html @@ -0,0 +1,6 @@ +

Vagrant Connect

Vagrant can share any or every port to your Vagrant environment, not just SSH and HTTP. The vagrant connect command gives the connecting person a static IP they can use to communicate to the shared Vagrant environment. Any TCP traffic sent to this IP is sent to the shared Vagrant environment.

Usage

Just call vagrant share --full. This will automatically share as many ports as possible for remote connections. Please see the Vagrant share security page for more information.

Note the share name at the end of calling vagrant share --full, and give this to the person who wants to connect to your machine. They simply have to call vagrant connect NAME. This will give them a static IP they can use to access your Vagrant environment.

How does it work?

vagrant connect works by doing what Vagrant does best: managing virtual machines. vagrant connect creates a tiny virtual machine that takes up only around 20 MB in RAM, using VirtualBox or VMware (more provider support is coming soon).

Any traffic sent to this tiny virtual machine is then proxied through to the shared Vagrant environment as if it were directed at it.

Beware: Vagrant Insecure Key

If the Vagrant environment or box you are using is protected with the Vagrant insecure keypair (most public boxes are), then SSH will be easily available to anyone who connects.

While hopefully you are sharing with someone you trust, in certain environments you might be sharing with a class, or a conference, and you do not want them to be able to SSH in.

In this case, we recommend changing or removing the insecure key from the Vagrant machine.

Finally, we want to note that we are working on making it so that when Vagrant share is used, the Vagrant private key is actively rejected unless explicitly allowed. This feature is not yet done, however.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/connect.html +

+
diff --git a/devdocs/vagrant/share%2Fhttp.html b/devdocs/vagrant/share%2Fhttp.html new file mode 100644 index 00000000..da7c50b7 --- /dev/null +++ b/devdocs/vagrant/share%2Fhttp.html @@ -0,0 +1,15 @@ +

HTTP Sharing

Vagrant Share can create a publicly accessible URL endpoint to access an HTTP server running in your Vagrant environment. This is known as "HTTP sharing," and is enabled by default when vagrant share is used.

Because this mode of sharing creates a publicly accessible URL, the accessing party does not need to have Vagrant installed in order to view your environment.

This has a number of useful use cases: you can test webhooks by exposing your Vagrant environment to the internet, you can show your work to clients, teammates, or managers, etc.

Usage

To use HTTP sharing, simply run vagrant share:

$ vagrant share
+==> default: Detecting network information for machine...
+default: Local machine address: 192.168.84.130
+default: Local HTTP port: 9999
+default: Local HTTPS port: disabled
+==> default: Creating Vagrant Share session...
+==> default: HTTP URL: http://b1fb1f3f.ngrok.io
+
+

Vagrant detects where your HTTP server is running in your Vagrant environment and outputs the endpoint that can be used to access this share. Just give this URL to anyone you want to share it with, and they will be able to access your Vagrant environment!

If Vagrant has trouble detecting the port of your servers in your environment, use the --http and/or --https flags to be more explicit.

The share will be accessible for the duration that vagrant share is running. Press Ctrl-C to quit the sharing session.

Warning: This URL is accessible by anyone who knows it, so be careful if you are sharing sensitive information.

+

Disabling

If you want to disable the creation of the publicly accessible endpoint, run vagrant share with the --disable-http flag. This will share your environment using one of the other methods available, and will not create the URL endpoint.

Missing Assets

Shared web applications must use relative paths for loading any local assets such as images, stylesheets, javascript.

The web application under development will be accessed remotely. This means that if you have any hardcoded asset (images, stylesheets, etc.) URLs such as <img src="http://127.0.0.1/header.png">, then they will not load for people accessing your share.

Most web frameworks or toolkits have settings or helpers to generate relative paths. For example, if you are a WordPress developer, the Root Relative URLs plugin will automatically do this for you.

Relative URLs to assets is generally a best practice in general, so you should do this anyways!

HTTPS (SSL)

Vagrant Share can also expose an SSL port that can be accessed over SSL. Creating an HTTPS share requires a non-free ngrok account.

vagrant share by default looks for any SSL traffic on port 443 in your development environment. If it cannot find any, then SSL is disabled by default.

The HTTPS share can be explicitly disabled using the --disable-https flag.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/http.html +

+
diff --git a/devdocs/vagrant/share%2Findex.html b/devdocs/vagrant/share%2Findex.html new file mode 100644 index 00000000..32c7b0e5 --- /dev/null +++ b/devdocs/vagrant/share%2Findex.html @@ -0,0 +1,11 @@ +

Vagrant Share

Vagrant Share allows you to share your Vagrant environment with anyone in the world, enabling collaboration directly in your Vagrant environment in almost any network environment with just a single command: vagrant share.

Vagrant share has three primary modes or features. These features are not mutually exclusive, meaning that any combination of them can be active at any given time:

The details of each are covered in their specific section in the sidebar to the left. We also have a section where we go into detail about the security implications of this feature.

Installation

Vagrant Share is a Vagrant plugin that must be installed. It is not included with Vagrant system packages. To install the Vagrant Share plugin, run the following command:

$ vagrant plugin install vagrant-share
+
+

Vagrant Share requires ngrok to be used.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/ +

+
diff --git a/devdocs/vagrant/share%2Fprovider.html b/devdocs/vagrant/share%2Fprovider.html new file mode 100644 index 00000000..d4c491d0 --- /dev/null +++ b/devdocs/vagrant/share%2Fprovider.html @@ -0,0 +1,8 @@ +

Custom Provider

Warning: Advanced Topic! This topic is related to developing Vagrant plugins. If you are not interested in this or you are just starting with Vagrant, it is safe to skip this page.

+

If you are developing a custom Vagrant provider, you will need to do a tiny bit more work in order for it to work well with Vagrant Share.

For now, this is only one step:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/provider.html +

+
diff --git a/devdocs/vagrant/share%2Fsecurity.html b/devdocs/vagrant/share%2Fsecurity.html new file mode 100644 index 00000000..9b90f755 --- /dev/null +++ b/devdocs/vagrant/share%2Fsecurity.html @@ -0,0 +1,10 @@ +

Security

Sharing your Vagrant environment understandably raises a number of security concerns.

The primary security mechanism for Vagrant Share is security through obscurity along with an encryption key for SSH. Additionally, there are several configuration options made available to help control access and manage security:

In addition to these options, there are other features we've built to help:

Most importantly, you must understand that by running vagrant share, you are making your Vagrant environment accessible by anyone who knows the share name. When share is not running, it is not accessible.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/security.html +

+
diff --git a/devdocs/vagrant/share%2Fssh.html b/devdocs/vagrant/share%2Fssh.html new file mode 100644 index 00000000..92c6a700 --- /dev/null +++ b/devdocs/vagrant/share%2Fssh.html @@ -0,0 +1,62 @@ +

SSH Sharing

Vagrant share makes it trivially easy to allow remote SSH access to your Vagrant environment by supplying the --ssh flag to vagrant share.

Easy SSH sharing is incredibly useful if you want to give access to a colleague for troubleshooting ops issues. Additionally, it enables pair programming with a Vagrant environment, if you want!

SSH sharing is disabled by default as a security measure. To enable SSH sharing, simply supply the --ssh flag when calling vagrant share.

Usage

Just run vagrant share --ssh!

When SSH sharing is enabled, Vagrant generates a brand new keypair for SSH access. The public key portion is automatically inserted into the Vagrant machine, and the private key portion is provided to the user connecting to the Vagrant share. This private key is encrypted using a password that you will be prompted for. This password is never transmitted across the network by Vagrant, and is an extra layer of security preventing anyone who may know your share name from easily accessing your machine.

After running vagrant share --ssh, it will output the name of your share:

$ vagrant share --ssh
+==> default: Detecting network information for machine...
+default: Local machine address: 192.168.84.130
+==> default: Generating new SSH key...
+default: Please enter a password to encrypt the key:
+default: Repeat the password to confirm:
+default: Inserting generated SSH key into machine...
+default: Local HTTP port: disabled
+default: Local HTTPS port: disabled
+default: SSH Port: 2200
+==> default: Creating Vagrant Share session...
+share: Cloning VMware VM: 'hashicorp/vagrant-share'. This can take some time...
+share: Verifying vmnet devices are healthy...
+share: Preparing network adapters...
+share: Starting the VMware VM...
+share: Waiting for machine to boot. This may take a few minutes...
+share: SSH address: 192.168.84.134:22
+share: SSH username: tc
+share: SSH auth method: password
+share:
+share: Inserting generated public key within guest...
+share: Removing insecure key from the guest if it's present...
+share: Key inserted! Disconnecting and reconnecting using new SSH key...
+share: Machine booted and ready!
+share: Forwarding ports...
+share: -- 31338 => 65534
+share: -- 22 => 2202
+share: SSH address: 192.168.84.134:22
+share: SSH username: tc
+share: SSH auth method: password
+share: Configuring network adapters within the VM...
+==> share:
+==> share: Your Vagrant Share is running! Name: bazaar_wolf:sultan_oasis
+==> share:
+==> share: You're sharing with SSH access. This means that another can SSH to
+==> share: your Vagrant machine by running:
+==> share:
+==> share:   vagrant connect --ssh bazaar_wolf:sultan_oasis
+==> share:
+
+

Anyone can then SSH directly to your Vagrant environment by running vagrant connect --ssh NAME where NAME is the name of the share outputted previously.

$ vagrant connect --ssh bazaar_wolf:sultan_oasis
+Loading share 'bazaar_wolf:sultan_oasis'...
+The SSH key to connect to this share is encrypted. You will
+require the password entered when creating the share to
+decrypt it. Verify you have access to this password before
+continuing.
+
+Press enter to continue, or Ctrl-C to exit now.
+Password for the private key:
+Executing SSH...
+Welcome to Ubuntu 12.04.3 LTS (GNU/Linux 3.8.0-29-generic x86_64)
+
+ * Documentation:  https://help.ubuntu.com/
+Last login: Fri Mar  7 17:44:50 2014 from 192.168.163.1
+vagrant@vagrant:~$
+
+

If the private key is encrypted (the default behavior), then the connecting person will be prompted for the password to decrypt the private key.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/share/ssh.html +

+
diff --git a/devdocs/vagrant/synced-folders%2Fbasic_usage.html b/devdocs/vagrant/synced-folders%2Fbasic_usage.html new file mode 100644 index 00000000..a15af212 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fbasic_usage.html @@ -0,0 +1,31 @@ +

Basic Usage

Configuration

Synced folders are configured within your Vagrantfile using the config.vm.synced_folder method. Usage of the configuration directive is very simple:

Vagrant.configure("2") do |config|
+  # other config here
+
+  config.vm.synced_folder "src/", "/srv/website"
+end
+
+

The first parameter is a path to a directory on the host machine. If the path is relative, it is relative to the project root. The second parameter must be an absolute path of where to share the folder within the guest machine. This folder will be created (recursively, if it must) if it does not exist. By default, Vagrant mounts the synced folders with the owner/group set to the SSH user and any parent folders set to root.

Options

You may also specify additional optional parameters when configuring synced folders. These options are listed below. More detailed examples of using some of these options are shown below this section, note the owner/group example supplies two additional options separated by commas.

In addition to these options, the specific synced folder type might allow more options. See the documentation for your specific synced folder type for more details. The built-in synced folder types are documented in other pages available in the navigation for these docs.

Enabling

Synced folders are automatically setup during vagrant up and vagrant reload.

Disabling

Synced folders can be disabled by adding the disabled option to any definition:

Vagrant.configure("2") do |config|
+  config.vm.synced_folder "src/", "/srv/website", disabled: true
+end
+
+

Disabling the default /vagrant share can be done as follows:

config.vm.synced_folder ".", "/vagrant", disabled: true
+
+

Modifying the Owner/Group

Sometimes it is preferable to mount folders with a different owner/group than the default SSH user. Keep in mind that these options will only affect the synced folder itself. If you want to modify the owner/group of the synced folder's parent folders use a script. It is possible to set these options:

config.vm.synced_folder "src/", "/srv/website",
+  owner: "root", group: "root"
+
+

NOTE: Owner and group IDs defined within mount_options will have precedence over the owner and group options.

For example, given the following configuration:

config.vm.synced_folder ".", "/vagrant", owner: "vagrant",
+  group: "vagrant", mount_options: ["uid=1234", "gid=1234"]
+
+

the mounted synced folder will be owned by the user with ID 1234 and the group with ID 1234. The owner and group options will be ignored.

Support for symbolic links across synced folder implementations and host/guest combinations is not consistent. Vagrant does its best to make sure symbolic links work by configuring various hypervisors (such as VirtualBox), but some host/guest combinations still do not work properly. This can affect some development environments that rely on symbolic links.

The recommendation is to make sure to test symbolic links on all the host/guest combinations you sync folders on if this is important to you.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/basic_usage.html +

+
diff --git a/devdocs/vagrant/synced-folders%2Findex.html b/devdocs/vagrant/synced-folders%2Findex.html new file mode 100644 index 00000000..dc0a3b00 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Findex.html @@ -0,0 +1,6 @@ +

Synced Folders

Synced folders enable Vagrant to sync a folder on the host machine to the guest machine, allowing you to continue working on your project's files on your host machine, but use the resources in the guest machine to compile or run your project.

By default, Vagrant will share your project directory (the directory with the Vagrantfile) to /vagrant.

Read the basic usage page to get started with synced folders.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/ +

+
diff --git a/devdocs/vagrant/synced-folders%2Fnfs.html b/devdocs/vagrant/synced-folders%2Fnfs.html new file mode 100644 index 00000000..1c564eb0 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fnfs.html @@ -0,0 +1,57 @@ +

NFS

In some cases the default shared folder implementations (such as VirtualBox shared folders) have high performance penalties. If you are seeing less than ideal performance with synced folders, NFS can offer a solution. Vagrant has built-in support to orchestrate the configuration of the NFS server on the host and guest for you.

Prerequisites

Before using synced folders backed by NFS, the host machine must have nfsd installed, the NFS server daemon. This comes pre-installed on Mac OS X, and is typically a simple package install on Linux.

Additionally, the guest machine must have NFS support installed. This is also usually a simple package installation away.

If you are using the VirtualBox provider, you will also need to make sure you have a private network set up. This is due to a limitation of VirtualBox's built-in networking. With VMware, you do not need this.

Enabling NFS Synced Folders

To enable NFS, just add the type: "nfs" flag onto your synced folder:

Vagrant.configure("2") do |config|
+  config.vm.synced_folder ".", "/vagrant", type: "nfs"
+end
+
+

If you add this to an existing Vagrantfile that has a running guest machine, be sure to vagrant reload to see your changes.

NFS Synced Folder Options

NFS synced folders have a set of options that can be specified that are unique to NFS. These are listed below. These options can be specified in the final part of the config.vm.synced_folder definition, along with the type option.

NFS Global Options

There are also more global NFS options you can set with config.nfs in the Vagrantfile. These are documented below:

Specifying NFS Arguments

In addition to the options specified above, it is possible for Vagrant to specify alternate NFS arguments when mounting the NFS share by using the mount_options key. For example, to use the actimeo=2 client mount option:

config.vm.synced_folder ".", "/vagrant",
+  type: "nfs",
+  mount_options: ['actimeo=2']
+
+

This would result in the following mount command being executed on the guest:

mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant
+
+

You can also tweak the arguments specified in the /etc/exports template when the mount is added, by using the OS-specific linux__nfs_options or bsd__nfs_options keys. Note that these options completely override the default arguments that are added by Vagrant automatically. For example, to make the NFS share asynchronous:

config.vm.synced_folder ".", "/vagrant",
+  type: "nfs",
+  linux__nfs_options: ['rw','no_subtree_check','all_squash','async']
+
+

This would result in the following content in /etc/exports on the host (note the added async flag):

# VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
+"/path/to/vagrantfile" 172.28.128.5(rw,no_subtree_check,all_squash,async,anonuid=21171,anongid=660,fsid=3382034405)
+# VAGRANT-END: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
+
+

Root Privilege Requirement

To configure NFS, Vagrant must modify system files on the host. Therefore, at some point during the vagrant up sequence, you may be prompted for administrative privileges (via the typical sudo program). These privileges are used to modify /etc/exports as well as to start and stop the NFS server daemon.

If you do not want to type your password on every vagrant up, Vagrant uses thoughtfully crafted commands to make fine-grained sudoers modifications possible to avoid entering your password.

Below, we have a couple example sudoers entries. Note that you may have to modify them slightly on certain hosts because the way Vagrant modifies /etc/exports changes a bit from OS to OS. If the commands below are located in non-standard paths, modify them as appropriate.

For *nix users, make sure to edit your /etc/sudoers file with visudo. It protects you against syntax errors which could leave you without the ability to gain elevated privileges.

All of the snippets below require Vagrant version 1.7.3 or higher.

+

For OS X, sudoers should have this entry:

Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports
+Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart
+Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports
+%admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE
+
+

For Ubuntu Linux , sudoers should look like this:

Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
+Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
+Cmnd_Alias VAGRANT_NFSD_CHECK = /etc/init.d/nfs-kernel-server status
+Cmnd_Alias VAGRANT_NFSD_START = /etc/init.d/nfs-kernel-server start
+Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
+%sudo ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
+
+

For Fedora Linux, sudoers might look like this (given your user belongs to the vagrant group):

Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
+Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
+Cmnd_Alias VAGRANT_NFSD_CHECK = /usr/bin/systemctl status --no-pager nfs-server.service
+Cmnd_Alias VAGRANT_NFSD_START = /usr/bin/systemctl start nfs-server.service
+Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
+%vagrant ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
+
+

If you don't want to edit /etc/sudoers directly, you can create /etc/sudoers.d/vagrant-syncedfolders with the appropriate entries, assuming /etc/sudoers.d has been enabled.

Other Notes

Encrypted folders: If you have an encrypted disk, then NFS very often will refuse to export the filesystem. The error message given by NFS is often not clear. One error message seen is <path> does not support NFS. There is no workaround for this other than sharing a directory which is not encrypted.

Version 4: UDP is generally not a valid transport protocol for NFSv4. Early implementations of NFS 4.0 still allowed UDP which allows the UDP transport protocol to be used in rare cases. RFC5661 explicitly states UDP alone should not be used for the transport protocol in NFS 4.1. Errors due to unsupported transport protocols for specific versions of NFS are not always clear. A common error message when attempting to use UDP with NFSv4:

mount.nfs: an incorrect mount option was specified
+
+

When using NFSv4, ensure the nfs_udp option is set to false. For example:

config.vm.synced_folder ".", "/vagrant",
+  type: "nfs",
+  nfs_version: 4,
+  nfs_udp: false
+
+

For more information about transport protocols and NFS version 4 see:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/nfs.html +

+
diff --git a/devdocs/vagrant/synced-folders%2Frsync.html b/devdocs/vagrant/synced-folders%2Frsync.html new file mode 100644 index 00000000..6e38d611 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Frsync.html @@ -0,0 +1,22 @@ +

RSync

Synced folder type: rsync

Vagrant can use rsync as a mechanism to sync a folder to the guest machine. This synced folder type is useful primarily in situations where other synced folder mechanisms are not available, such as when NFS or VirtualBox shared folders are not available in the guest machine.

The rsync synced folder does a one-time one-way sync from the machine running to the machine being started by Vagrant.

The rsync and rsync-auto commands can be used to force a resync and to automatically resync when changes occur in the filesystem. Without running these commands, Vagrant only syncs the folders on vagrant up or vagrant reload.

Prerequisites

To use the rsync synced folder type, the machine running Vagrant must have rsync (or rsync.exe) on the path. This executable is expected to behave like the standard rsync tool.

On Windows, rsync installed with Cygwin or MinGW will be detected by Vagrant and works well.

The destination machine must also have rsync installed, but Vagrant can automatically install rsync into many operating systems. If Vagrant is unable to automatically install rsync for your operating system, it will tell you.

The destination folder will be created as the user initiating the connection, this is vagrant by default. This user requires the appropriate permissions on the destination folder.

Options

The rsync synced folder type accepts the following options:

Example

The following is an example of using RSync to sync a folder:

Vagrant.configure("2") do |config|
+  config.vm.synced_folder ".", "/vagrant", type: "rsync",
+    rsync__exclude: ".git/"
+end
+
+

Rsync to a restricted folder

If required to copy to a destination where vagrant user does not have permissions, use "--rsync-path='sudo rsync'" to run rsync with sudo on the guest

Vagrant.configure("2") do |config|
+  config.vm.synced_folder "bin", "/usr/local/bin", type: "rsync",
+    rsync__exclude: ".git/",
+    rsync__args: ["--verbose", "--rsync-path='sudo rsync'", "--archive", "--delete", "-z"]
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/rsync.html +

+
diff --git a/devdocs/vagrant/synced-folders%2Fsmb.html b/devdocs/vagrant/synced-folders%2Fsmb.html new file mode 100644 index 00000000..ea6e6d16 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fsmb.html @@ -0,0 +1,26 @@ +

SMB

Synced folder type: smb

Vagrant can use SMB as a mechanism to create a bi-directional synced folder between the host machine and the Vagrant machine.

SMB is built-in to Windows machines and provides a higher performance alternative to some other mechanisms such as VirtualBox shared folders.

SMB is currently only supported when the host machine is Windows or macOS. The guest machine can be Windows, Linux, or macOS.

+

Prerequisites

Windows Host

To use the SMB synced folder type on a Windows host, the machine must have PowerShell version 3 or later installed. In addition, when Vagrant attempts to create new SMB shares, or remove existing SMB shares, Administrator privileges will be required. Vagrant will request these privileges using UAC.

macOS Host

To use the SMB synced folder type on a macOS host, file sharing must be enabled for the local account. Enable SMB file sharing by following the instructions below:

When Vagrant attempts to create new SMB shares, or remove existing SMB shares, root access will be required. Vagrant will request these privileges using sudo to run the /usr/sbin/sharing command. Adding the following to the system's sudoers configuration will allow Vagrant to manage SMB shares without requiring a password each time:

Cmnd_Alias VAGRANT_SMB_ADD = /usr/sbin/sharing -a * -S * -s * -g * -n *
+Cmnd_Alias VAGRANT_SMB_REMOVE = /usr/sbin/sharing -r *
+Cmnd_Alias VAGRANT_SMB_LIST = /usr/sbin/sharing -l
+Cmnd_Alias VAGRANT_SMB_PLOAD = /bin/launchctl load -w /System/Library/LaunchDaemons/com.apple.smb.preferences.plist
+Cmnd_Alias VAGRANT_SMB_DLOAD = /bin/launchctl load -w /System/Library/LaunchDaemons/com.apple.smbd.plist
+Cmnd_Alias VAGRANT_SMB_DSTART = /bin/launchctl start com.apple.smbd
+%admin ALL=(root) NOPASSWD: VAGRANT_SMB_ADD, VAGRANT_SMB_REMOVE, VAGRANT_SMB_LIST, VAGRANT_SMB_PLOAD, VAGRANT_SMB_DLOAD, VAGRANT_SMB_DSTART
+
+

Guests

The destination machine must be able to mount SMB filesystems. On Linux the package to do this is usually called smbfs or cifs. Vagrant knows how to automatically install this for some operating systems.

Options

The SMB synced folder type has a variety of options it accepts:

Example

The following is an example of using SMB to sync a folder:

Vagrant.configure("2") do |config|
+  config.vm.synced_folder ".", "/vagrant", type: "smb"
+end
+
+

Preventing Idle Disconnects

On Windows, if a file is not accessed for some period of time, it may disconnect from the guest and prevent the guest from accessing the SMB-mounted share. To prevent this, the following command can be used in a superuser shell. Note that you should research if this is the right option for you.

net config server /autodisconnect:-1
+
+

Common Issues

"wrong fs type" Error

If during mounting on Linux you are seeing an error message that includes the words "wrong fs type," this is because the SMB kernel extension needs to be updated in the OS.

If updating the kernel extension is not an option, you can workaround the issue by specifying the following options on your synced folder:

mount_options: ["username=USERNAME","password=PASSWORD"]
+
+

Replace "USERNAME" and "PASSWORD" with your SMB username and password.

Vagrant 1.8 changed SMB mounting to use the more secure credential file mechanism. However, many operating systems ship with an outdated filesystem type for SMB out of the box which does not support this. The above workaround reverts Vagrant to the insecure before, but causes it work.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/smb.html +

+
diff --git a/devdocs/vagrant/synced-folders%2Fvirtualbox.html b/devdocs/vagrant/synced-folders%2Fvirtualbox.html new file mode 100644 index 00000000..37f4f1ff --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fvirtualbox.html @@ -0,0 +1,10 @@ +

VirtualBox

If you are using the Vagrant VirtualBox provider, then VirtualBox shared folders are the default synced folder type. These synced folders use the VirtualBox shared folder system to sync file changes from the guest to the host and vice versa.

Options

Caveats

There is a VirtualBox bug related to sendfile which can result in corrupted or non-updating files. You should deactivate sendfile in any web servers you may be running.

In Nginx:

sendfile off;
+
+

In Apache:

EnableSendfile Off
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/synced-folders/virtualbox.html +

+
diff --git a/devdocs/vagrant/triggers%2Fconfiguration.html b/devdocs/vagrant/triggers%2Fconfiguration.html new file mode 100644 index 00000000..2406f7ea --- /dev/null +++ b/devdocs/vagrant/triggers%2Fconfiguration.html @@ -0,0 +1,36 @@ +

Configuration

Vagrant Triggers has a few options to define trigger behavior.

Options

The trigger class takes various options.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/triggers/configuration.html +

+
diff --git a/devdocs/vagrant/triggers%2Findex.html b/devdocs/vagrant/triggers%2Findex.html new file mode 100644 index 00000000..9ec41dd2 --- /dev/null +++ b/devdocs/vagrant/triggers%2Findex.html @@ -0,0 +1,52 @@ +

Vagrant Triggers

As of version 2.1.0, Vagrant is capable of executing machine triggers before or after Vagrant commands.

Each trigger is expected to be given a command key for when it should be fired during the Vagrant command lifecycle. These could be defined as a single key or an array which acts like a whitelist for the defined trigger.

# single command trigger
+config.trigger.after :up do |trigger|
+...
+end
+
+# multiple commands for this trigger
+config.trigger.before [:up, :destroy, :halt, :package] do |trigger|
+...
+end
+
+# or defined as a splat list
+config.trigger.before :up, :destroy, :halt, :package do |trigger|
+...
+end
+
+

Alternatively, the key :all could be given which would run the trigger before or after every Vagrant command. If there is a command you don't want the trigger to run on, you can ignore that command with the ignore option.

# single command trigger
+config.trigger.before :all do |trigger|
+  trigger.info = "Running a before trigger!"
+  trigger.ignore = [:destroy, :halt]
+end
+
+

Note: If a trigger is defined on a command that does not exist, a warning will be displayed.

Triggers can be defined as a block or hash in a Vagrantfile. The example below will result in the same trigger:

config.trigger.after :up do |trigger|
+  trigger.name = "Finished Message"
+  trigger.info = "Machine is up!"
+end
+
+config.trigger.after :up,
+  name: "Finished Message",
+  info: "Machine is up!"
+
+

Triggers can also be defined within the scope of guests in a Vagrantfile. These triggers will only run on the configured guest. An example of a guest only trigger:

config.vm.define "ubuntu" do |ubuntu|
+  ubuntu.vm.box = "ubuntu"
+  ubuntu.trigger.before :destroy do |trigger|
+    trigger.warn = "Dumping database to /vagrant/outfile"
+    trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"}
+  end
+end
+
+

Global and machine-scoped triggers will execute in the order that they are defined within a Vagrantfile. Take for example an abstracted Vagrantfile:

Vagrantfile
+  global trigger 1
+  global trigger 2
+  machine defined
+    machine trigger 3
+  global trigger 4
+end
+
+

In this generic case, the triggers would fire in the order: 1 -> 2 -> 3 -> 4

For more information about what options are available for triggers, see the configuration section.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/triggers/ +

+
diff --git a/devdocs/vagrant/triggers%2Fusage.html b/devdocs/vagrant/triggers%2Fusage.html new file mode 100644 index 00000000..1a369d26 --- /dev/null +++ b/devdocs/vagrant/triggers%2Fusage.html @@ -0,0 +1,81 @@ +

Basic Usage

Below are some very simple examples of how to use Vagrant Triggers.

Examples

The following is a basic example of two global triggers. One that runs before the :up command and one that runs after the :up command:

Vagrant.configure("2") do |config|
+  config.trigger.before :up do |trigger|
+    trigger.name = "Hello world"
+    trigger.info = "I am running before vagrant up!!"
+  end
+
+  config.trigger.after :up do |trigger|
+    trigger.name = "Hello world"
+    trigger.info = "I am running after vagrant up!!"
+  end
+
+  config.vm.define "ubuntu" do |ubuntu|
+    ubuntu.vm.box = "ubuntu"
+  end
+end
+
+

These will run before and after each defined guest in the Vagrantfile.

Running a remote script to save a database on your host before destroying a guest:

Vagrant.configure("2") do |config|
+  config.vm.define "ubuntu" do |ubuntu|
+    ubuntu.vm.box = "ubuntu"
+
+    ubuntu.trigger.before :destroy do |trigger|
+      trigger.warn = "Dumping database to /vagrant/outfile"
+      trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"}
+    end
+  end
+end
+
+

Now that the trigger is defined, running the destroy command will fire off the defined trigger before Vagrant destroys the machine.

$ vagrant destroy ubuntu
+
+

An example of defining three triggers that start and stop tinyproxy on your host machine using homebrew:

#/bin/bash
+# start-tinyproxy.sh
+brew services start tinyproxy
+
+
#/bin/bash
+# stop-tinyproxy.sh
+brew services stop tinyproxy
+
+
Vagrant.configure("2") do |config|
+  config.vm.define "ubuntu" do |ubuntu|
+    ubuntu.vm.box = "ubuntu"
+
+    ubuntu.trigger.before :up do |trigger|
+      trigger.info = "Starting tinyproxy..."
+      trigger.run = {path: "start-tinyproxy.sh"}
+    end
+
+    ubuntu.trigger.after :destroy, :halt do |trigger|
+      trigger.info = "Stopping tinyproxy..."
+      trigger.run = {path: "stop-tinyproxy.sh"}
+    end
+  end
+end
+
+

Running vagrant up would fire the before trigger to start tinyproxy, where as running either vagrant destroy or vagrant halt would stop tinyproxy.

Ruby Option

Triggers can also be defined to run Ruby, rather than bash or powershell. An example of this might be using a Ruby option to get more information from the VBoxManage tool. In this case, we are printing the ostype defined for thte guest after it has been brought up.

Vagrant.configure("2") do |config|
+  config.vm.define "ubuntu" do |ubuntu|
+    ubuntu.vm.box = "ubuntu"
+
+    ubuntu.trigger.after :up do |trigger|
+      trigger.info = "More information with ruby magic"
+      trigger.ruby do |env,machine|
+        puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype`
+      end
+    end
+  end
+end
+
+

If you are defining your triggers using the hash syntax, you must use the Proc type for defining a ruby trigger.

Vagrant.configure("2") do |config|
+  config.vm.define "ubuntu" do |ubuntu|
+    ubuntu.vm.box = "ubuntu"
+
+    ubuntu.trigger.after :up,
+      info: "More information with ruby magic",
+      ruby: proc{|env,machine| puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype`}
+  end
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/triggers/usage.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Findex.html b/devdocs/vagrant/vagrantfile%2Findex.html new file mode 100644 index 00000000..732bb9ac --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Findex.html @@ -0,0 +1,14 @@ +

Vagrantfile

The primary function of the Vagrantfile is to describe the type of machine required for a project, and how to configure and provision these machines. Vagrantfiles are called Vagrantfiles because the actual literal filename for the file is Vagrantfile (casing does not matter unless your file system is running in a strict case sensitive mode).

Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile is supposed to be committed to version control. This allows other developers involved in the project to check out the code, run vagrant up, and be on their way. Vagrantfiles are portable across every platform Vagrant supports.

The syntax of Vagrantfiles is Ruby, but knowledge of the Ruby programming language is not necessary to make modifications to the Vagrantfile, since it is mostly simple variable assignment. In fact, Ruby is not even the most popular community Vagrant is used within, which should help show you that despite not having Ruby knowledge, people are very successful with Vagrant.

Lookup Path

When you run any vagrant command, Vagrant climbs up the directory tree looking for the first Vagrantfile it can find, starting first in the current directory. So if you run vagrant in /home/mitchellh/projects/foo, it will search the following paths in order for a Vagrantfile, until it finds one:

/home/mitchellh/projects/foo/Vagrantfile
+/home/mitchellh/projects/Vagrantfile
+/home/mitchellh/Vagrantfile
+/home/Vagrantfile
+/Vagrantfile
+
+

This feature lets you run vagrant from any directory in your project.

You can change the starting directory where Vagrant looks for a Vagrantfile by setting the VAGRANT_CWD environmental variable to some other path.

Load Order and Merging

An important concept to understand is how Vagrant loads Vagrantfiles. Vagrant actually loads a series of Vagrantfiles, merging the settings as it goes. This allows Vagrantfiles of varying level of specificity to override prior settings. Vagrantfiles are loaded in the order shown below. Note that if a Vagrantfile is not found at any step, Vagrant continues with the next step.

  1. Vagrantfile packaged with the box that is to be used for a given machine.
  2. Vagrantfile in your Vagrant home directory (defaults to ~/.vagrant.d). This lets you specify some defaults for your system user.
  3. Vagrantfile from the project directory. This is the Vagrantfile that you will be modifying most of the time.
  4. +Multi-machine overrides if any.
  5. +Provider-specific overrides, if any.

At each level, settings set will be merged with previous values. What this exactly means depends on the setting. For most settings, this means that the newer setting overrides the older one. However, for things such as defining networks, the networks are actually appended to each other. By default, you should assume that settings will override each other. If the behavior is different, it will be noted in the relevant documentation section.

Within each Vagrantfile, you may specify multiple Vagrant.configure blocks. All configurations will be merged within a single Vagrantfile in the order they're defined.

Available Configuration Options

You can learn more about the available configuration options by clicking the relevant section in the left navigational area.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/ +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fmachine_settings.html b/devdocs/vagrant/vagrantfile%2Fmachine_settings.html new file mode 100644 index 00000000..0a9082dc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fmachine_settings.html @@ -0,0 +1,31 @@ +

Machine Settings

Config namespace: config.vm

The settings within config.vm modify the configuration of the machine that Vagrant manages.

Available Settings

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/machine_settings.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fssh_settings.html b/devdocs/vagrant/vagrantfile%2Fssh_settings.html new file mode 100644 index 00000000..97042727 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fssh_settings.html @@ -0,0 +1,32 @@ +

SSH Settings

Config namespace: config.ssh

The settings within config.ssh relate to configuring how Vagrant will access your machine over SSH. As with most Vagrant settings, the defaults are typically fine, but you can fine tune whatever you would like.

Available Settings

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/ssh_settings.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Ftips.html b/devdocs/vagrant/vagrantfile%2Ftips.html new file mode 100644 index 00000000..c16e3e16 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Ftips.html @@ -0,0 +1,27 @@ +

Tips & Tricks

The Vagrantfile is a very flexible configuration format. Since it is just Ruby, there is a lot you can do with it. However, in that same vein, since it is Ruby, there are a lot of ways you can shoot yourself in the foot. When using some of the tips and tricks on this page, please take care to use them correctly.

Loop Over VM Definitions

If you want to apply a slightly different configuration to many multi-machine machines, you can use a loop to do this. For example, if you wanted to create three machines:

(1..3).each do |i|
+  config.vm.define "node-#{i}" do |node|
+    node.vm.provision "shell",
+      inline: "echo hello from node #{i}"
+  end
+end
+
+ 
# THIS DOES NOT WORK!
+for i in 1..3 do
+  config.vm.define "node-#{i}" do |node|
+    node.vm.provision "shell",
+      inline: "echo hello from node #{i}"
+  end
+end
+
+

The for i in ... construct in Ruby actually modifies the value of i for each iteration, rather than making a copy. Therefore, when you run this, every node will actually provision with the same text.

This is an easy mistake to make, and Vagrant cannot really protect against it, so the best we can do is mention it here.

Overwrite host locale in ssh session

Usually, host locale environment variables are passed to guest. It may cause failures if the guest software do not support host locale. One possible solution is override locale in the Vagrantfile:

ENV["LC_ALL"] = "en_US.UTF-8"
+
+Vagrant.configure("2") do |config|
+  # ...
+end
+
+

The change is only visible within the Vagrantfile.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/tips.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html b/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html new file mode 100644 index 00000000..9c467317 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html @@ -0,0 +1,20 @@ +

Vagrant Settings

Config namespace: config.vagrant

The settings within config.vagrant modify the behavior of Vagrant itself.

Available Settings

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/vagrant_settings.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fvagrant_version.html b/devdocs/vagrant/vagrantfile%2Fvagrant_version.html new file mode 100644 index 00000000..762454fc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fvagrant_version.html @@ -0,0 +1,9 @@ +

Minimum Vagrant Version

A set of Vagrant version requirements can be specified in the Vagrantfile to enforce that people use a specific version of Vagrant with a Vagrantfile. This can help with compatibility issues that may otherwise arise from using a too old or too new Vagrant version with a Vagrantfile.

Vagrant version requirements should be specified at the top of a Vagrantfile with the Vagrant.require_version helper:

Vagrant.require_version ">= 1.3.5"
+
+

In the case above, the Vagrantfile will only load if the version loading it is Vagrant 1.3.5 or greater.

Multiple requirements can be specified as well:

Vagrant.require_version ">= 1.3.5", "< 1.4.0"
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/vagrant_version.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fversion.html b/devdocs/vagrant/vagrantfile%2Fversion.html new file mode 100644 index 00000000..81ea1ecc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fversion.html @@ -0,0 +1,18 @@ +

Configuration Version

Configuration versions are the mechanism by which Vagrant 1.1+ is able to remain backwards compatible with Vagrant 1.0.x Vagrantfiles, while introducing dramatically new features and configuration options.

If you run vagrant init today, the Vagrantfile will be in roughly the following format:

Vagrant.configure("2") do |config|
+  # ...
+end
+
+

The "2" in the first line above represents the version of the configuration object config that will be used for configuration for that block (the section between the do and the end). This object can be very different from version to version.

Currently, there are only two supported versions: "1" and "2". Version 1 represents the configuration from Vagrant 1.0.x. "2" represents the configuration for 1.1+ leading up to 2.0.x.

When loading Vagrantfiles, Vagrant uses the proper configuration object for each version, and properly merges them, just like any other configuration.

The important thing to understand as a general user of Vagrant is that within a single configuration section, only a single version can be used. You cannot use the new config.vm.provider configurations in a version 1 configuration section. Likewise, config.vm.forward_port will not work in a version 2 configuration section (it was renamed).

If you want, you can mix and match multiple configuration versions in the same Vagrantfile. This is useful if you found some useful configuration snippet or something that you want to use. Example:

Vagrant.configure("1") do |config|
+  # v1 configs...
+end
+
+Vagrant.configure("2") do |config|
+  # v2 configs...
+end
+
+

What is Vagrant::Config.run? You may see this in Vagrantfiles. This was actually how Vagrant 1.0.x did configuration. In Vagrant 1.1+, this is synonymous with Vagrant.configure("1").

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/version.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html b/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html new file mode 100644 index 00000000..066a2352 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html @@ -0,0 +1,18 @@ +

WinRM Settings

Config namespace: config.winrm

The settings within config.winrm relate to configuring how Vagrant will access your Windows guest over WinRM. As with most Vagrant settings, the defaults are typically fine, but you can fine tune whatever you would like.

These settings are only used if you've set your communicator type to :winrm.

Available Settings

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/winrm_settings.html +

+
diff --git a/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html b/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html new file mode 100644 index 00000000..76ace77b --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html @@ -0,0 +1,20 @@ +

WinSSH

The WinSSH communicator is built specifically for the Windows native port of OpenSSH. It does not rely on a POSIX-like environment which removes the requirement of extra software installation (like cygwin) for proper functionality.

For more information, see the Win32-OpenSSH project page.

WinSSH Settings

The WinSSH communicator uses the same connection configuration options as the SSH communicator. These settings provide the information for the communicator to establish a connection to the VM.

The configuration options below are specific to the WinSSH communicator.

Config namespace: config.winssh

Available Settings

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vagrantfile/winssh_settings.html +

+
diff --git a/devdocs/vagrant/virtualbox%2Fboxes.html b/devdocs/vagrant/virtualbox%2Fboxes.html new file mode 100644 index 00000000..bb4e4bad --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fboxes.html @@ -0,0 +1,34 @@ +

Creating a Base Box

As with every Vagrant provider, the Vagrant VirtualBox 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. 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.

Advanced topic! 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.

+

Virtual Machine

The virtual machine created in VirtualBox can use any configuration you would like, but Vagrant has some hard requirements:

Other than the above, you are free to customize the base virtual machine as you see fit.

Additional Software

In addition to the software that should be installed based on the general guide to creating base boxes, VirtualBox base boxes require some additional software.

VirtualBox Guest Additions

VirtualBox Guest Additions must be installed so that things such as shared folders can function. Installing guest additions also usually improves performance since the guest OS can make some optimizations by knowing it is running within VirtualBox.

Before installing the guest additions, you will need the linux kernel headers and the basic developer tools. On Ubuntu, you can easily install these like so:

$ sudo apt-get install linux-headers-$(uname -r) build-essential dkms
+
+

To install via the GUI:

Next, make sure that the guest additions image is available by using the GUI and clicking on "Devices" followed by "Install Guest Additions". Then mount the CD-ROM to some location. On Ubuntu, this usually looks like this:

$ sudo mount /dev/cdrom /media/cdrom
+
+

Finally, run the shell script that matches your system to install the guest additions. For example, for Linux on x86, it is the following:

$ sudo sh /media/cdrom/VBoxLinuxAdditions.run
+
+

If the command succeeds, then the guest additions are now installed!

To install via the command line:

You can find the appropriate guest additions version to match your VirtualBox version by selecting the appropriate version here. The examples below use 4.3.8, which was the latest VirtualBox version at the time of writing.

wget http://download.virtualbox.org/virtualbox/4.3.8/VBoxGuestAdditions_4.3.8.iso
+sudo mkdir /media/VBoxGuestAdditions
+sudo mount -o loop,ro VBoxGuestAdditions_4.3.8.iso /media/VBoxGuestAdditions
+sudo sh /media/VBoxGuestAdditions/VBoxLinuxAdditions.run
+rm VBoxGuestAdditions_4.3.8.iso
+sudo umount /media/VBoxGuestAdditions
+sudo rmdir /media/VBoxGuestAdditions
+
+

If you did not install a Desktop environment when you installed the operating system, as recommended to reduce size, the install of the VirtualBox additions should warn you about the lack of OpenGL or Window System Drivers, but you can safely ignore this.

If the commands succeed, then the guest additions are now installed!

Packaging the Box

Vagrant includes a simple way to package VirtualBox base boxes. Once you've installed all the software you want to install, you can run this command:

$ vagrant package --base my-virtual-machine
+
+

Where "my-virtual-machine" is replaced by the name of the virtual machine in VirtualBox to package as a base box.

It will take a few minutes, but after it is complete, a file "package.box" should be in your working directory which is the new base box. At this point, you've successfully created a base box!

Raw Contents

This section documents the actual raw contents of the box file. This is not as useful when creating a base box but can be useful in debugging issues if necessary.

A VirtualBox base box is an archive of the resulting files of exporting a VirtualBox virtual machine. Here is an example of what is contained in such a box:

$ tree
+.
+|-- Vagrantfile
+|-- box-disk1.vmdk
+|-- box.ovf
+|-- metadata.json
+
+0 directories, 4 files
+
+

In addition to the files from exporting a VirtualBox VM, there is the "metadata.json" file used by Vagrant itself.

Also, there is a "Vagrantfile." This contains some configuration to properly set the MAC address of the NAT network device, since VirtualBox requires this to be correct in order to function properly. If you are not using vagrant package --base above, you will have to set the config.vm.base_mac setting in this Vagrantfile to the MAC address of the NAT device without colons.

When bringing up a VirtualBox backed machine, Vagrant imports the "box.ovf" file found in the box contents.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/boxes.html +

+
diff --git a/devdocs/vagrant/virtualbox%2Fcommon-issues.html b/devdocs/vagrant/virtualbox%2Fcommon-issues.html new file mode 100644 index 00000000..83185b6b --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fcommon-issues.html @@ -0,0 +1,6 @@ +

Common Issues

This page lists some common issues people run into with Vagrant and VirtualBox as well as solutions for those issues.

Hanging on Windows

If Vagrant commands are hanging on Windows because they're communicating to VirtualBox, this may be caused by a permissions issue with VirtualBox. This is easy to fix. Starting VirtualBox as a normal user or as an administrator will prevent you from using it in the opposite way. Please keep in mind that when Vagrant interacts with VirtualBox, it will interact with it with the same access level as the console running Vagrant.

To fix this issue, completely shut down all VirtualBox machines and GUIs. Wait a few seconds. Then, launch VirtualBox only with the access level you wish to use.

DNS Not Working

If DNS is not working within your VM, then you may need to enable a DNS proxy (built-in to VirtualBox). Please see the StackOverflow answers here for a guide on how to do that.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/common-issues.html +

+
diff --git a/devdocs/vagrant/virtualbox%2Fconfiguration.html b/devdocs/vagrant/virtualbox%2Fconfiguration.html new file mode 100644 index 00000000..4f2b5631 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fconfiguration.html @@ -0,0 +1,33 @@ +

Configuration

The VirtualBox provider exposes some additional configuration options that allow you to more finely control your VirtualBox-powered Vagrant environments.

GUI vs. Headless

By default, VirtualBox machines are started in headless mode, meaning there is no UI for the machines visible on the host machine. Sometimes, you want to have a UI. Common use cases include wanting to see a browser that may be running in the machine, or debugging a strange boot issue. You can easily tell the VirtualBox provider to boot with a GUI:

config.vm.provider "virtualbox" do |v|
+  v.gui = true
+end
+
+

Virtual Machine Name

You can customize the name that appears in the VirtualBox GUI by setting the name property. By default, Vagrant sets it to the containing folder of the Vagrantfile plus a timestamp of when the machine was created. By setting another name, your VM can be more easily identified.

config.vm.provider "virtualbox" do |v|
+  v.name = "my_vm"
+end
+
+

Linked Clones

By default new machines are created by importing the base box. For large boxes this produces a large overhead in terms of time (the import operation) and space (the new machine contains a copy of the base box's image). Using linked clones can drastically reduce this overhead.

Linked clones are based on a master VM, which is generated by importing the base box only once the first time it is required. For the linked clones only differencing disk images are created where the parent disk image belongs to the master VM.

config.vm.provider "virtualbox" do |v|
+  v.linked_clone = true
+end
+
+

To have backward compatibility:

config.vm.provider 'virtualbox' do |v|
+  v.linked_clone = true if Gem::Version.new(Vagrant::VERSION) >= Gem::Version.new('1.8.0')
+end
+
+

If you do not want backward compatibility and want to force users to support linked cloning, you can use Vagrant.require_version with 1.8.

Note: the generated master VMs are currently not removed automatically by Vagrant. This has to be done manually. However, a master VM can only be removed when there are no linked clones connected to it.

+

VBoxManage Customizations

VBoxManage is a utility that can be used to make modifications to VirtualBox virtual machines from the command line.

Vagrant exposes a way to call any command against VBoxManage just prior to booting the machine:

config.vm.provider "virtualbox" do |v|
+  v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
+end
+
+

In the example above, the VM is modified to have a host CPU execution cap of 50%, meaning that no matter how much CPU is used in the VM, no more than 50% would be used on your own host machine. Some details:

There are some convenience shortcuts for memory and CPU settings:

config.vm.provider "virtualbox" do |v|
+  v.memory = 1024
+  v.cpus = 2
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/configuration.html +

+
diff --git a/devdocs/vagrant/virtualbox%2Findex.html b/devdocs/vagrant/virtualbox%2Findex.html new file mode 100644 index 00000000..8e4969b0 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Findex.html @@ -0,0 +1,6 @@ +

VirtualBox

Vagrant comes with support out of the box for VirtualBox, a free, cross-platform consumer virtualization product.

The VirtualBox provider is compatible with VirtualBox versions 4.0.x, 4.1.x, 4.2.x, 4.3.x, 5.0.x, 5.1.x, and 5.2.x. Other versions are unsupported and the provider will display an error message. Please note that beta and pre-release versions of VirtualBox are not supported and may not be well-behaved.

VirtualBox must be installed on its own prior to using the provider, or the provider will display an error message asking you to install it. VirtualBox can be installed by downloading a package or installer for your operating system and using standard procedures to install that package.

Use the navigation to the left to find a specific VirtualBox topic to read more about.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/ +

+
diff --git a/devdocs/vagrant/virtualbox%2Fnetworking.html b/devdocs/vagrant/virtualbox%2Fnetworking.html new file mode 100644 index 00000000..0290178f --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fnetworking.html @@ -0,0 +1,20 @@ +

Networking

VirtualBox Internal Network

The Vagrant VirtualBox provider supports using the private network as a VirtualBox internal network. By default, private networks are host-only networks, because those are the easiest to work with. However, internal networks can be enabled as well.

To specify a private network as an internal network for VirtualBox use the virtualbox__intnet option with the network. The virtualbox__ (double underscore) prefix tells Vagrant that this option is only for the VirtualBox provider.

Vagrant.configure("2") do |config|
+  config.vm.network "private_network", ip: "192.168.50.4",
+    virtualbox__intnet: true
+end
+
+

Additionally, if you want to specify that the VirtualBox provider join a specific internal network, specify the name of the internal network:

Vagrant.configure("2") do |config|
+  config.vm.network "private_network", ip: "192.168.50.4",
+    virtualbox__intnet: "mynetwork"
+end
+
+

VirtualBox NIC Type

You can specify a specific NIC type for the created network interface by using the nic_type parameter. This is not prefixed by virtualbox__ for legacy reasons, but is VirtualBox-specific.

This is an advanced option and should only be used if you know what you are using, since it can cause the network device to not work at all.

Example:

Vagrant.configure("2") do |config|
+  config.vm.network "private_network", ip: "192.168.50.4",
+    nic_type: "virtio"
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/networking.html +

+
diff --git a/devdocs/vagrant/virtualbox%2Fusage.html b/devdocs/vagrant/virtualbox%2Fusage.html new file mode 100644 index 00000000..3a6e2959 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fusage.html @@ -0,0 +1,6 @@ +

Usage

The Vagrant VirtualBox provider is used just like any other provider. Please read the general basic usage page for providers.

The value to use for the --provider flag is virtualbox.

The Vagrant VirtualBox provider does not support parallel execution at this time. Specifying the --parallel option will have no effect.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/virtualbox/usage.html +

+
diff --git a/devdocs/vagrant/vmware%2Fboxes.html b/devdocs/vagrant/vmware%2Fboxes.html new file mode 100644 index 00000000..09791970 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fboxes.html @@ -0,0 +1,40 @@ +

Boxes

As with every Vagrant provider, the Vagrant VMware providers have a custom box format.

This page documents the format so that you can create your own base boxes. Note that currently you must make these base boxes by hand. A future release of Vagrant will provide additional mechanisms for automatically creating such images.

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

+

Prior to reading this page, please understand the basics of the box file format.

Contents

A VMware base box is a compressed archive of the necessary contents of a VMware "vmwarevm" file. Here is an example of what is contained in such a box:

$ tree
+.
+|-- disk-s001.vmdk
+|-- disk-s002.vmdk
+|-- ...
+|-- disk.vmdk
+|-- metadata.json
+|-- precise64.nvram
+|-- precise64.vmsd
+|-- precise64.vmx
+|-- precise64.vmxf
+
+0 directories, 17 files
+
+

The files that are strictly required for a VMware machine to function are: nvram, vmsd, vmx, vmxf, and vmdk files.

There is also the "metadata.json" file used by Vagrant itself. This file contains nothing but the defaults which are documented on the box format page.

When bringing up a VMware backed machine, Vagrant copies all of the contents in the box into a privately managed "vmwarevm" folder, and uses the first "vmx" file found to control the machine.

Vagrant 1.8 and higher support linked clones. Prior versions of Vagrant do not support linked clones. For more information on linked clones, please see the documentation.

+

VMX Whitelisting

Settings in the VMX file control the behavior of the VMware virtual machine when it is booted. In the past Vagrant has removed the configured network device when creating a new instance and inserted a new configuration. With the introduction of "predictable network interface names" this approach can cause unexpected behaviors or errors with VMware Vagrant boxes. While some boxes that use the predictable network interface names are configured to handle the VMX modifications Vagrant makes, it is better if Vagrant does not make the modification at all.

Vagrant will now warn if a whitelisted setting is detected within a Vagrant box VMX file. If it is detected, a warning will be shown alerting the user and providing a configuration snippet. The configuration snippet can be used in the Vagrantfile if Vagrant fails to start the virtual machine.

Making compatible boxes

These are the VMX settings the whitelisting applies to:

If the newly created box does not depend on Vagrant's existing behavior of modifying this setting, it can disable Vagrant from applying the modification by adding a Vagrantfile to the box with the following content:

Vagrant.configure("2") do |config|
+  ["vmware_workstation", "vmware_fusion"].each do |vmware_provider|
+    config.vm.provider(vmware_provider) do |vmware|
+      vmware.whitelist_verified = true
+    end
+  end
+end
+
+

This will prevent Vagrant from displaying a warning to the user as well as disable the VMX settings modifications.

Installed Software

Base boxes for VMware should have the following software installed, as a bare minimum:

Optimizing Box Size

Prior to packaging up a box, you should shrink the hard drives as much as possible. This can be done with vmware-vdiskmanager which is usually found in /Applications/VMware Fusion.app/Contents/Library for VMware Fusion. You first want to defragment then shrink the drive. Usage shown below:

$ vmware-vdiskmanager -d /path/to/main.vmdk
+...
+$ vmware-vdiskmanager -k /path/to/main.vmdk
+...
+
+

Packaging

Remove any extraneous files from the "vmwarevm" folder and package it. Be sure to compress the tar with gzip (done below in a single command) since VMware hard disks are not compressed by default.

$ cd /path/to/my/vm.vmwarevm
+$ tar cvzf custom.box ./*
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/boxes.html +

+
diff --git a/devdocs/vagrant/vmware%2Fconfiguration.html b/devdocs/vagrant/vmware%2Fconfiguration.html new file mode 100644 index 00000000..f3fb0b16 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fconfiguration.html @@ -0,0 +1,39 @@ +

Configuration

While Vagrant VMware Desktop provider is a drop-in replacement for VirtualBox, there are some additional features that are exposed that allow you to more finely configure VMware-specific aspects of your machines.

Configuration settings for the provider are set in the Vagrantfile:

Vagrant.configure("2") do |config|
+  config.vm.box = "my-box"
+  config.vm.provider "vmware_desktop" do |v|
+    v.gui = true
+  end
+end
+
+

Provider settings

VM Clone Directory

By default, the VMware provider will clone the VMware VM in the box to the ".vagrant" folder relative to the folder where the Vagrantfile is. Usually, this is fine. For some people, for example those who use a differential backup software such as Time Machine, this is very annoying because you cannot regularly ignore giant virtual machines as part of backups.

The directory where the provider clones the virtual machine can be customized by setting the VAGRANT_VMWARE_CLONE_DIRECTORY environmental variable. This does not need to be unique per project. Each project will get a different sub-directory within this folder. Therefore, it is safe to set this systemwide.

Linked Clones

By default new machines are created using a linked clone to the base box. This reduces the time and required disk space incurred by directly importing the base box.

Linked clones are based on a master VM, which is generated by importing the base box only once the first time it is required. For the linked clones only differencing disk images are created where the parent disk image belongs to the master VM. To disable linked clones:

config.vm.provider "vmware_desktop" do |v|
+  v.linked_clone = false
+end
+
+

VMX Customization

If you want to add or remove specific keys from the VMX file, you can do that:

config.vm.provider "vmware_desktop" do |v|
+  v.vmx["custom-key"]  = "value"
+  v.vmx["another-key"] = nil
+end
+
+

In the example above, the "custom-key" key will be set to "value" and the "another-key" key will be removed from the VMX file.

VMX customization is done as the final step before the VMware machine is booted, so you have the ability to possibly undo or misconfigure things that Vagrant has set up itself.

VMX is an undocumented format and there is no official reference for the available keys and values. This customization option is exposed for people who have knowledge of exactly what they want.

The most common keys people look for are setting memory and CPUs. The example below sets both:

config.vm.provider "vmware_desktop" do |v|
+  v.vmx["memsize"] = "1024"
+  v.vmx["numvcpus"] = "2"
+end
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/configuration.html +

+
diff --git a/devdocs/vagrant/vmware%2Findex.html b/devdocs/vagrant/vmware%2Findex.html new file mode 100644 index 00000000..c1de079c --- /dev/null +++ b/devdocs/vagrant/vmware%2Findex.html @@ -0,0 +1,6 @@ +

VMware

HashiCorp develops an official VMware Fusion and VMware Workstation provider for Vagrant. This provider allows Vagrant to power VMware based machines and take advantage of the improved stability and performance that VMware software offers.

Learn more about the VMware providers on the VMware provider page on the Vagrant website.

This provider is a drop-in replacement for VirtualBox, meaning that every VirtualBox feature that Vagrant supports is fully functional in VMware as well. However, there are some VMware-specific things such as box formats, configurations, etc. that are documented here.

For the most up-to-date information on compatibility and supported versions of VMware Fusion and VMware Workstation, please visit the Vagrant VMware product page. Please note that VMware Fusion and VMware Workstation are third-party products that must be purchased and installed separately prior to using the provider.

Use the navigation to the left to find a specific VMware topic to read more about.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/ +

+
diff --git a/devdocs/vagrant/vmware%2Finstallation.html b/devdocs/vagrant/vmware%2Finstallation.html new file mode 100644 index 00000000..30a8a80a --- /dev/null +++ b/devdocs/vagrant/vmware%2Finstallation.html @@ -0,0 +1,24 @@ +

Installation

If you are upgrading from the Vagrant VMware Workstation or Vagrant VMware Fusion plugins, please halt or destroy all VMware VMs currently being managed by Vagrant. Then continue with the instructions below.

Installation of the Vagrant VMware provider requires two steps. First the Vagrant VMware Utility must be installed. This can be done by downloading and installing the correct system package from the Vagrant VMware Utility downloads page.

Next, install the Vagrant VMware provider plugin using the standard plugin installation procedure:

$ vagrant plugin install vagrant-vmware-desktop
+
+

For more information on plugin installation, please see the Vagrant plugin usage documentation.

The Vagrant VMware plugin is a commercial product provided by HashiCorp and require the purchase of a license to operate. To purchase a license, please visit the Vagrant VMware provider page. Upon purchasing a license, you will receive a license file in your inbox. Download this file and save it to a temporary location on your computer.

Warning! You cannot use your VMware product license as a Vagrant VMware plugin license. They are separate commercial products, each requiring their own license.

+

After installing the Vagrant VMware Desktop plugin for your system, you will need to install the license:

$ vagrant plugin license vagrant-vmware-desktop ~/license.lic
+
+

The first parameter is the name of the plugin, and the second parameter is the path to the license file on disk. Please be sure to replace ~/license.lic with the path where you temporarily saved the downloaded license file to disk. After you have installed the plugin license, you may remove the temporary file.

To verify the license installation, run:

$ vagrant
+
+

If the license is not installed correctly, you will see an error message.

Upgrading to v1.x

It is extremely important that the VMware plugin is upgraded to 1.0.0 or above. This release resolved critical security vulnerabilities. To learn more, please read our release announcement.

After upgrading, please verify that the following paths are empty. The upgrade process should remove these for you, but for security reasons it is important to double check. If you're a new user or installing the VMware provider on a new machine, you may skip this step. If you're a Windows user, you may skip this step as well.

The path ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} should no longer exist. The gem vagrant-vmware-desktop may exist since this is the name of the new plugin. If the old directories exist, remove them. An example for a Unix-like shell is shown below:

# Check if they exist and verify that they're the correct paths as shown below.
+$ ls ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}
+...
+
+# Remove them
+$ rm -rf ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}
+
+

Updating the Vagrant VMware Desktop plugin

The Vagrant VMware Desktop plugin can be updated directly from Vagrant. Run the following command to update Vagrant to the latest version of the Vagrant VMware Desktop plugin:

$ vagrant plugin update vagrant-vmware-desktop
+
+

Frequently Asked Questions

Q: I purchased a Vagrant VMware plugin license, but I did not receive an email?
First, please check your JUNK or SPAM folders. Since the license comes from an automated system, it might have been flagged as spam by your email provider. If you do not see the email there, please contact support and include the original order number.

Q: Do I need to keep the Vagrant VMware plugin license file on disk?
After you have installed the Vagrant VMware plugin license, it is safe to remove your copy from disk. Vagrant copies the license into its structure for reference on boot.

Q: I lost my original email, where can I download my Vagrant VMware plugin license again?
Please contact support. Note: please contact support using the email address with which you made the original purchase. If you use an alternate email, you will be asked to verify that you are the owner of the requested license.

Q: I upgraded my VMware product and now my license is invalid?
The Vagrant VMware plugin licenses are valid for specific VMware product versions at the time of purchase. When new versions of VMware products are released, significant changes to the plugin code are often required to support this new version. For this reason, you may need to upgrade your current license to work with the new version of the VMware product. Customers can check their license upgrade eligibility by visiting the License Upgrade Center and entering the email address with which they made the original purchase.

Your existing license will continue to work with all previous versions of the VMware products. If you do not wish to update at this time, you can rollback your VMware installation to an older version.

Q: Why is the Vagrant VMware plugin not working with my trial version of VMware Fusion/Workstation?
The Vagrant VMware Fusion and Vagrant VMware Workstation plugins are not compatible with trial versions of the VMware products. We apologize for the inconvenience.

Q: How do I upgrade my currently installed Vagrant VMware plugin?
You can update the Vagrant VMware plugin to the latest version by re-running the install command:

$ vagrant plugin install vagrant-vmware-desktop
+
+

Support

If you have any issues purchasing, installing, or using the Vagrant VMware plugins, please contact support. To expedite the support process, please include the Vagrant debug output as a Gist if applicable. This will help us more quickly diagnose your issue.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/installation.html +

+
diff --git a/devdocs/vagrant/vmware%2Fkernel-upgrade.html b/devdocs/vagrant/vmware%2Fkernel-upgrade.html new file mode 100644 index 00000000..69eacfc3 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fkernel-upgrade.html @@ -0,0 +1,21 @@ +

Kernel Upgrade

If as part of running your Vagrant environment with VMware, you perform a kernel upgrade, it is likely that the VMware guest tools will stop working. This breaks features of Vagrant such as synced folders and sometimes networking as well.

This page documents how to upgrade your kernel and keep your guest tools functioning. If you are not planning to upgrade your kernel, then you can safely skip this page.

Enable Auto-Upgrade of VMware Tools

If you are running a common OS, VMware tools can often auto-upgrade themselves. This setting is disabled by default. The Vagrantfile settings below will enable auto-upgrading:

# Ensure that VMWare Tools recompiles kernel modules
+# when we update the linux images
+$fix_vmware_tools_script = <<SCRIPT
+sed -i.bak 's/answer AUTO_KMODS_ENABLED_ANSWER no/answer AUTO_KMODS_ENABLED_ANSWER yes/g' /etc/vmware-tools/locations
+sed -i 's/answer AUTO_KMODS_ENABLED no/answer AUTO_KMODS_ENABLED yes/g' /etc/vmware-tools/locations
+SCRIPT
+
+Vagrant.configure("2") do |config|
+  # ...
+
+  config.vm.provision "shell", inline: $fix_vmware_tools_script
+end
+
+

Note that this does not work for every OS, so vagrant up with the above settings, do a kernel upgrade, and do a vagrant reload. If HGFS (synced folders) and everything appears to be working, great! If not, then read on...

Manually Reinstalling VMware Tools

At this point, you will have to manually reinstall VMware tools. The best source of information for how to do this is the VMware documentation.

There are some gotchas:

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/kernel-upgrade.html +

+
diff --git a/devdocs/vagrant/vmware%2Fknown-issues.html b/devdocs/vagrant/vmware%2Fknown-issues.html new file mode 100644 index 00000000..ee179d50 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fknown-issues.html @@ -0,0 +1,6 @@ +

Known Issues

This page tracks some known issues or limitations of the VMware provider. Note that none of these are generally blockers to using the provider, but are good to know.

Network disconnect

When Vagrant applies port forwarding rules while bring up a guest instance, other running VMware VMs may experience a loss of network connectivity. The cause of this connectivity issue is the restarting of the VMware NAT service to apply new port forwarding rules. Since new rules cannot be applied to the NAT service while it is running, it is required to restart the service, which results in the loss of connectivity.

Forwarded Ports Failing in Workstation on Windows

VMware Workstation has a bug on Windows where forwarded ports do not work properly. Vagrant actually works around this bug and makes them work. However, if you run the virtual network editor on Windows, the forwarded ports will suddenly stop working.

In this case, run vagrant reload and things will begin working again.

This issue has been reported to VMware, but a fix has not been released yet.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/known-issues.html +

+
diff --git a/devdocs/vagrant/vmware%2Fusage.html b/devdocs/vagrant/vmware%2Fusage.html new file mode 100644 index 00000000..1450b4d6 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fusage.html @@ -0,0 +1,13 @@ +

Usage

The Vagrant VMware provider is used just like any other provider. Please read the general basic usage page for providers.

The value to use for the --provider flag is vmware_desktop. For compatibility with older versions of the plugin, vmware_fusion can be used for VMware Fusion, and vmware_workstation for VMware Workstation.

The Vagrant VMware provider does not support parallel execution at this time. Specifying the --parallel option will have no effect.

To get started, create a new Vagrantfile that points to a VMware box:

# vagrant init hashicorp/precise64
+Vagrant.configure("2") do |config|
+  config.vm.box = "hashicorp/precise64"
+end
+
+

Then run:

$ vagrant up --provider vmware_desktop
+
+

This will download and bring up a new VMware Fusion/Workstation virtual machine in Vagrant.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/usage.html +

+
diff --git a/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html b/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html new file mode 100644 index 00000000..8fe34df7 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html @@ -0,0 +1,23 @@ +

Vagrant VMware Utility Installation

System Packages

The Vagrant VMware Utility is provided as a system package. To install the utility, download and install the correct system package from the downloads page.

+
Download 1.0.5

Manual Installation

If there is no officially supported system package of the utility available, it may be possible to manually install utility. This applies to Linux platforms only. First, download the latest zip package from the releases page.

Next create a directory for the executable and unpack the executable as root.

sudo mkdir /opt/vagrant-vmware-utility/bin
+sudo unzip -d /opt/vagrant-vmware-utility/bin vagrant-vmware-utility_1.0.0_x86_64.zip
+
+

After the executable has been installed, the utility setup tasks must be run. First, generate the required certificates:

sudo /opt/vagrant-vmware-utility/bin/vagrant-vmware-utility certificate generate
+
+

The path provided from this command can be used to set the utility_certificate_path in the Vagrantfile configuration if installing to a non-standard path.

Finally, install the service. This will also enable the service.

sudo /usr/local/vagrant-vmware-utility/vagrant-vmware-utility service install
+
+

Usage

The Vagrant VMware Utility provides the Vagrant VMware provider plugin access to various VMware functionalities. The Vagrant VMware Utility is required by the Vagrant VMware Desktop provider plugin.

Vagrant VMware Utility Access

The Vagrant VMware Utility provides support for all users on the system using the Vagrant VMware Desktop plugin. If access restrictions to the Utility need to be applied to users on the system, this can be accomplished by restricting user access to the certificates used for connecting to the service.

On Windows platforms these certificates can be found at:

On POSIX platforms these certificates can be found at:

Vagrant VMware Utility Service

The Vagrant VMware Utility consists of a small service which runs on the host platform. When the utility installer package is installed, the service is configured to automatically start. If the plugin reports errors communicating with the service, it may have stopped for some reason. The most common cause of the service not being in a running state is the VMware application not being installed. The service can be started again by using the proper command below:

Windows

On Windows platforms a service is created called vagrant-vmware-utility. The service can be manually started using the services GUI (services.msc) or by running the following command from a cmd.exe in administrator mode:

> net.exe start vagrant-vmware-utility
+
+

macOS 

> sudo launchctl load -w /Library/LaunchDaemons/com.vagrant.vagrant-vmware-utility.plist
+
+

Linux systemd 

> sudo systemctl start vagrant-vmware-utility
+
+

Linux SysVinit 

> sudo /etc/init.d/vagrant-vmware-utility start
+
+

Linux runit 

> sudo sv start vagrant-vmware-utility
+
+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware/vagrant-vmware-utility.html +

+
diff --git a/devdocs/vagrant/vmware.html b/devdocs/vagrant/vmware.html new file mode 100644 index 00000000..21fcfee4 --- /dev/null +++ b/devdocs/vagrant/vmware.html @@ -0,0 +1,6 @@ +

VMware

HashiCorp develops an official VMware Fusion and VMware Workstation provider for Vagrant. This provider allows Vagrant to power VMware based machines and take advantage of the improved stability and performance that VMware software offers.

Learn more about the VMware providers on the VMware provider page on the Vagrant website.

This provider is a drop-in replacement for VirtualBox, meaning that every VirtualBox feature that Vagrant supports is fully functional in VMware as well. However, there are some VMware-specific things such as box formats, configurations, etc. that are documented here.

For the most up-to-date information on compatibility and supported versions of VMware Fusion and VMware Workstation, please visit the Vagrant VMware product page. Please note that VMware Fusion and VMware Workstation are third-party products that must be purchased and installed separately prior to using the provider.

Use the navigation to the left to find a specific VMware topic to read more about.

+

+ © 2010–2018 Mitchell Hashimoto
Licensed under the MPL 2.0 License.
+ https://www.vagrantup.com/docs/vmware +

+
-- cgit v1.2.3