112 lines
4.5 KiB
Markdown
112 lines
4.5 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 most cases Vagrant will need access to the actual
|
|
Windows system to function correctly. As most Vagrant providers will
|
|
need to be installed on Windows directly (not within the WSL) Vagrant
|
|
will require Windows access. Access to the Windows system is controlled
|
|
via an environment variable: `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS`. If
|
|
this environment variable is set, Vagrant will access the Windows system
|
|
to run executables and enable things like synced folders. When running
|
|
in a bash shell within WSL, the environment variable can be setup like so:
|
|
|
|
```
|
|
$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
|
|
```
|
|
|
|
This will enable Vagrant to access the Windows system outside of the
|
|
WSL and properly interact with Windows executables. This will automatically
|
|
modify the `VAGRANT_HOME` environment variable if it is not already defined,
|
|
setting it to be within the user's home directory on Windows.
|
|
|
|
It is important to note that paths shared with the Windows system will
|
|
not have Linux permissions enforced. For example, when a directory within
|
|
the WSL is synced to a guest using the VirtualBox provider, any local
|
|
permissions defined on that directory (or its contents) will not be
|
|
visible from the guest. Likewise, any files created from the guest within
|
|
the synced folder will be world readable/writeable in WSL.
|
|
|
|
Other useful WSL related environment variables:
|
|
|
|
* `VAGRANT_WSL_WINDOWS_ACCESS_USER` - Override current Windows username
|
|
* `VAGRANT_WSL_DISABLE_VAGRANT_HOME` - Do not modify the `VAGRANT_HOME` variable
|
|
* `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` - Custom Windows system home path
|
|
|
|
## 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
|
|
```
|