Documentation

Exposing a service from a Windows machine

If your are web developer who works on Windows, you can use sshreach.me to show your work in progress to your client or to test your web application's webhooks. You might also use sshreach.me to provide your clients technical support with VNC.

For Windows XP and newer (with python 2.7)

Windows does not support python and ssh out-of-the-box and there are some additional steps to take before you can run sshreach.me on Windows. Here's the quick overview of the steps:

  1. Download and install python 2.7 for Windows
  2. Use pip to install psutil package
  3. Download plink, the ssh alternative for Windows
  4. Use puttygen to convert your private key to a format that plink recognises
  5. Change the script so that it can find your sshreach.me client directory and plink.exe
  6. Add sshreachme.py python script to your startup folder

Detailed steps:

  1. In order to run a python script, you need to download and install python interpreter on your Windows machine. You can download python from the official python site. This script is compatible with python2, so you should download python version 2.7.
  2. After you've downloaded and installed python, start command prompt and go to your python folder (usually "c:\python27") and from there go to the "scripts" subdirectory. From there, you can install the psutil package by typing pip install psutil (Windows XP users should type pip install psutil==3.4.2 as newer versions of psutil do not work with Windows XP).
  3. Create a folder for your sshreachme.py script and download plink.exe into it.
  4. Download puttygen.exe into the same directory. Start it and click on conversions/import key. From there, find your private key file (most probably named id_rsa) and load it. After your key has been imported, click on the save private key button which will save it in .ppk format that can be used by plink.exe. Once the first tunnel is created you will not need puttygen.exe anymore, so you might as well delete it.
  5. Open your sshreachme.py script and find the following code:
# for windows users: change these two values to match your settings PLINK_PATH = 'c:\sshreachme' # folder where your plink.exe is located PLINK_EXECUTABLE = 'plink.exe' # name of plink executable

Change PLINK_PATH to the folder where you've downloaded your plink.exe to.

You can now start your python client script from command prompt with the following command: c:\python27\python.exe c:\YOUR_SSHREACHME_PATH\sshreachme.py c:\YOUR_SSHREACHME_PATH\private_key.ppk

Your client should now show as active in web interface. You should now start the tunnel which will get you the following prompt:

  The server's host key is not cached in the registry. You have no guarantee that the server is the computer you think it is.
  The server's ssh-ed25519 key fingerprint is: ssh-ed25519 256 5c:a0:04:94:74:74:ab:91:90:59:2c:26:64:e8:73:ec
  If you trust this host, enter "y" to add the key to PuTTY's cache and carry on connecting.
  If you want to carry on connecting just once, without adding the key to the cache, enter "n".
  If you do not trust this host, press Return to abandon the connection.
  Store key in cache? (y/n)

Type "y" to allow the connection to proceed and to add the key to your system.

Your connection is now configured. The only thing left is to set up your python script to start after os boot. The easiest way to do it is to make a .bat file (for this purpose use pythonw.exe instead of python.exe) and to create a shortcut in your startup folder.

For Windows 10 with python 3

Windows does not support python and ssh out-of-the-box and there are some additional steps to take before you can run sshreach.me on Windows. Here's the quick overview of the steps:

  1. Download and install the latest python 3 for Windows
  2. Install Microsoft Visual Studio Build tools
  3. Use pip to install psutil package
  4. Download plink, the ssh alternative for Windows
  5. Use puttygen to convert your private key to a format that plink recognises
  6. Change the script so that it can find your sshreach.me client directory and plink.exe
  7. Add sshreachme.py python script to your startup folder

Detailed steps:

  1. In order to run a python script, you need to download and install python interpreter on your Windows machine. You can download python from the official python site. Download and install the latest version of python 3 (we recommend that you click the "Add Python 3.XX to PATH" option).
  2. In order to install a python module you will need to install Microsoft Visual Studio Build tools. You can download it here. Download the Visual Studio Installer and install the Visual Studio Build Tools.
  3. You can now install the psutil package by typing pip install psutil in the command line.
  4. Create a folder for your sshreachme.py script and download plink.exe into it.
  5. Download puttygen.exe into the same directory. Start it and click on conversions/import key. From there, find your private key file (most probably named id_rsa) and load it. After your key has been imported, click on the save private key button which will save it in .ppk format that can be used by plink.exe. Once the first tunnel is created you will not need puttygen.exe anymore, so you might as well delete it.
  6. Open your sshreachme.py script and find the following code:
# for windows users: change these two values to match your settings PLINK_PATH = 'c:\sshreachme' # folder where your plink.exe is located PLINK_EXECUTABLE = 'plink.exe' # name of plink executable

Change PLINK_PATH to the folder where you've downloaded your plink.exe to.

You can now start your python client script from command prompt with the following command: python.exe c:\YOUR_SSHREACHME_PATH\sshreachme.py c:\YOUR_SSHREACHME_PATH\private_key.ppk

Your client should now show as active in web interface. You should now start the tunnel which will get you the following prompt:

  The server's host key is not cached in the registry. You have no guarantee that the server is the computer you think it is.
  The server's ssh-ed25519 key fingerprint is: ssh-ed25519 256 5c:a0:04:94:74:74:ab:91:90:59:2c:26:64:e8:73:ec
  If you trust this host, enter "y" to add the key to PuTTY's cache and carry on connecting.
  If you want to carry on connecting just once, without adding the key to the cache, enter "n".
  If you do not trust this host, press Return to abandon the connection.
  Store key in cache? (y/n)

Type "y" to allow the connection to proceed and to add the key to your system.

Your connection is now configured. The only thing left is to set up your python script to start after os boot. The easiest way to do it is to make a .bat file (for this purpose use pythonw.exe instead of python.exe) and to create a shortcut in your startup folder.

With Windows 10 and Windows Subsystem for Linux

Since the introduction of Windows Subsystem for Linux in Windows 10, sshreach.me can also be used to expose a Windows service to the world using bash in Windows 10

  1. Activate Windows subsystem for Linux (here’s how).
  2. Once it’s activated, download the sshreachme.py script for the client and copy it to your bash home directory together with your private key file. (bash home directory in Windows 10 is located in %localappdata%\Lxss\rootfs or C:\Users\Username\AppData\Local\Lxss\rootfs).
  3. Go to your start menu and start Bash.
  4. Go to folder which contains sshreachme.py script and type the following: python sshreach.me /path/to/your_private_key &.
  5. Go to sshreach.me and you should now see that your client is activated. From the web interface you can now start and stop the tunnel to your computer.