wslbridge2

                   

Explore various ways to connect Windows Subsystem for Linux (WSL) with Windows terminal emulators and command line programs.

Requirements:

• Windows 10 version 1809 (build 17763) aka. October 2018 Update
• A POSIX-compatible environment - cygwin or msys2
• A terminal emulator - mintty or ConEmu
• For compiling - GCC, make, linux-headers

How to build

Clone this git repository. Run make in cygwin (or msys2) and WSL to make all. To build individual programs, go to src folder and run make command with the corresponding Makefile. By default the make command will create dynamically linked executables. For statically liked binaries, use make RELEASE=1 command. All binaries will be placed in bin folder.

How to use

Download the released stable binaries from Release page. Or to test nightly builds, download the wslbridge2.7z from this Appveyor project link.

hvsocket: sample C code using Hyper-V sockets

Pick up any one of 1. win_client & wsl_server 2. win_server & wsl_client. Run wsl.exe first. Paste the VM ID from the last argument of wslhost.exe process's command line. Compile the win_ part in cygwin or msys2 and the wsl_ part in WSL. Run the server part first. It will wait for the client.

rawpty: use pseudo console with terminal emulators

Run rawpty.exe wsl.exe command. This can also be any Windows console program. See the sample screenshot without headless mode.

wslbridge2: connect with WSL using network sockets

Place wslbridge2.exe and wslbridge2-backend in same Windows folder. Run wslbridge2.exe.

Options

Running wslbridge2.exe will open default shell in default WSL distribution. Here are the list of valid options:

• -b or --backend: Overrides the default path of backend binaries.
• -d or --distribution: Run the specified distribution.
• -e or --env: Copies Windows environment variable into the WSL.
• -h or --help: Show this usage information.
• -l or --login: Start a login shell in WSL.
• -u or --user: Run as the specified user in WSL.
• -w or --windir: Changes the working directory to a Windows path.
• -W or --wsldir: Changes the working directory to WSL path.
• -V or --wslver: Indicates the WSL version of the selected distribution.
• -x or --xmod: Shows hidden backend window and debug output.

Always use single quote or double quote to mention any folder path. For paths in WSL, "~" can also be used for user's home folder. If no command line is provided, this launches the default shell. The non-options arguments will be executed as is. For example, wslbridge2.exe ls will execute ls command in current working directory in default WSL distribution.

Frequently Asked Questions

See the FAQ page for the answers to commonly asked questions.

Caveats

• The graphics may lag sometimes due to multiple layers of data transitions between Windows and WSL side programs.

• There is no documented way to get VM ID from WSL2 Linux VM. See this issue. Hence GetVmId.cpp will change in future Windows 10 releases due to usage of undocumented COM methods.

Further Readings

• Make your own integration services
• Linux kernel: af_vsock.c
• Linux kernel: vm_sockets.h
• VMWare: VMCI Socket Programming Guide
• man7: vsock(7)
• wslbridge
• win32-console-docs
• XConPty

Acknowledgments

This is based on the Ryan Prichard's (@rprichard) wslbridge project. Also thanks to @mintty, @therealkenc, @dxhisboy and all contributors for helping with this project.

Contributions

Contributions are greatly appreciated. Please keep these following points:

• For a big change, try to add an issue before creating a pull request.
• Append a tag name in commit message, see previous commits as reference.
• Make the code easy to read and understand with proper syntax.
• If possible try to minimize memory usage.
• Use 4 spaces for indentation.
• If you are not programmer you can contribute to further improve or additions to documentations. Also share and discuss what features you like to have.

License

wslbridge2 is licensed under the GNU General Public License v3. A full copy of the license is provided in LICENSE.

wslbridge2 -- Explore various ways to connect WSL with Windows terminal emulators.
Copyright (C) Biswapriyo Nath

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.