From 7e49c6a6093b5d50463976654d62b2b5067826aa Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Mon, 8 May 2017 15:23:06 -0700 Subject: [PATCH] Add documentation for WSL --- website/source/docs/other/wsl.html.md | 118 ++++++++++++++++++++++++++ website/source/layouts/docs.erb | 1 + 2 files changed, 119 insertions(+) create mode 100644 website/source/docs/other/wsl.html.md diff --git a/website/source/docs/other/wsl.html.md b/website/source/docs/other/wsl.html.md new file mode 100644 index 000000000..0e5e3d46d --- /dev/null +++ b/website/source/docs/other/wsl.html.md @@ -0,0 +1,118 @@ +--- +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_. + +
+ 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. +
+ + +# 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] [] +``` + +# 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 +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 5239cc8d6..59e16b863 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -211,6 +211,7 @@