119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Vagrant and Windows Subsystem for Linux"
|
|
sidebar_current: "other-wsl"
|
|
description: |-
|
|
An overview of using Vagrant on Windows within the Windows Subsystem
|
|
for Linux.
|
|
---
|
|
|
|
# Vagrant and Windows Subsystem for Linux
|
|
|
|
Windows has recently introduced a new feature called the Windows Subsystem
|
|
for Linux (WSL). This is a beta feature available in developer mode on recent
|
|
releases of Windows 10. It is important to note that this feature is still
|
|
in _beta_ on Windows, and Vagrant support should be considered _alpha_.
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning: Advanced Topic!</strong> Using Vagrant within the Windows
|
|
Subsystem for Linux is an advanced topic that only experienced Vagrant users
|
|
who are reasonably comfortable with Windows, WSL, and Linux should approach.
|
|
</div>
|
|
|
|
|
|
# Installation
|
|
|
|
Installation requires WSL, Ubuntu on Windows, and Vagrant. Read on for installation
|
|
instructions for each item.
|
|
|
|
## Windows Subsystem for Linux and Ubuntu on Windows
|
|
|
|
First install the Windows Subsystem for Linux, followed by Ubuntu on Windows. This guide
|
|
from Microsoft walks through the process:
|
|
|
|
* https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
|
|
|
|
## Vagrant Installation
|
|
|
|
Vagrant _must_ be installed within Ubuntu on Windows. Even though the `vagrant.exe`
|
|
file can be executed from within the WSL, it will not function as expected. To
|
|
install Vagrant into the WSL, follow these steps:
|
|
|
|
* Download the 64-bit Debian package from the downloads page.
|
|
* Open a `cmd` or `powershell` window
|
|
* Enter the command: `bash`
|
|
* Install vagrant: `sudo dpkg -i vagrant_VERSION_x86_64.deb`
|
|
|
|
```
|
|
C:\Users\vagrant> bash
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ sudo dpkg -i vagrant_VERSION_x86_64.deb
|
|
[sudo] password for vagrant:
|
|
(Reading database ... 31885 files and directories currently installed.)
|
|
Preparing to unpack vagrant_VERSION_x86_64.deb ...
|
|
Unpacking vagrant (1:VERSION) ...
|
|
Setting up vagrant (1:VERSION) ...
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ vagrant help
|
|
Usage: vagrant [options] <command> [<args>]
|
|
```
|
|
|
|
# Vagrant Usage
|
|
|
|
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.
|
|
|
|
## Windows Access
|
|
|
|
Working within the WSL provides a layer of isolation from the actual
|
|
Windows system. In some cases, a user may be using Vagrant in a regular
|
|
Windows environment, and then transition to using Vagrant within the
|
|
WSL. Using Vagrant within the WSL will appear to be isolated from
|
|
the Windows system. A new `VAGRANT_HOME` directory will be created within
|
|
the WSL (meaning all boxes will require re-downloading). Vagrant will also
|
|
lose the ability to control Vagrant managed machines within Windows (due
|
|
to user ID mismatches).
|
|
|
|
Vagrant supports enabling user access to provide seamless behavior and
|
|
control between Vagrant on Windows and Vagrant on WSL. By setting the
|
|
`VAGRANT_WSL_ACCESS_WINDOWS_USER` environment variable, Vagrant will
|
|
allow access to Vagrant managed machines in that user's home path, as
|
|
well as share the `VAGRANT_HOME` directory. Below is a demonstration
|
|
of the behavior:
|
|
|
|
```
|
|
C:\Users\vagrant> bash
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ mkdir test
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ cd test
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant/test$ vagrant init hashicorp/precisec4
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ vagrant up
|
|
Vagrant will not operate outside the Windows Subsystem for Linux unless explicitly
|
|
instructed. Due to the inability to enforce expected Linux file ownership and
|
|
permissions on the Windows system, Vagrant will not make modifications to prevent
|
|
unexpected errors. To learn more about this, and the options that are available,
|
|
please refer to the Vagrant documentation:
|
|
|
|
https://www.vagrantup.com/docs/other/wsl
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ export VAGRANT_WSL_ACCESS_WINDOWS_USER=vagrant
|
|
vagrant@vagrant-10:/mnt/c/Users/vagrant$ vagrant up
|
|
Bringing machine 'default' up with 'virtualbox' provider...
|
|
```
|
|
|
|
It is important to note that file permissions cannot be enforced when Vagrant
|
|
modifies the Windows file system. It is for this reason that you must explicitly
|
|
enable this functionality with the express knowledge of the implication. If you
|
|
are unsure of how this may affect your system, do not enable this feature.
|
|
|
|
## Using Docker
|
|
|
|
The docker daemon cannot be run in side 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
|
|
```
|