Among other operating systems Windows is the most inconvenient to set up and prepare all the necessary tools. It requires a couple of extra steps, but it is still nothing that can't be done.
The main problem is that Windows does not have any of the necessary tools by default and does not have an easy way to install and run them. There is no way to run rsync on Windows natively, and the OpenSSH version that is shipped with Windows 10 and above does not support all the features and CAN NOT be used with a Plugin. TL;DR - you will have to use Linux tools on Windows, and there are two main approaches of how that can be done:
- Cygwin - third-party toolkit that brings a UNIX-like environment and a set of command-line tools for the Windows platform, basically "Bash for Windows"
- WSL - Windows Subsystem for Linux by Microsoft, basically a tightly integrated VM running a Linux distro in the container on Windows.
Currently, only the Cygwin approach is supported, WSL support will be added in future versions.
Go to the official site of the Cygwin project and download the installer (setup-x86_64.exe). Run it, it will guide you through the installation process. Click Next on the first screen. Choose Install from Internet on the next screen. Leave the default root install directory (C:\cygwin64) and installation type All Users. Leave the default Local Package Directory on the next screen. Leave the default Use System Proxy Settings on the next screen. On the next screen choose some mirror URL (doesn't really matter which one). Now you will see a screen with a list of packages that can be installed. Cygwin installs a lot of UNIX-like tools by default, but you will have to pick a few extra points manually.
You will need to choose these extra packages from the list to install in your new environment:
- openssh
- rsync
- librsync2
Type package names into Search text field to find the required stuff. Make sure to choose the version (pick the latest one) in the drop-down menu that is in the field to the right of the package name. After all three packages are marked to be installed, click the button to continue, then Next and Cygwin will be installed on your system with all the packages you need. Check the Create icon on Desktop box on the last screen, then Complete. After installation process is complete, you will get a new icon Cygwin64 Terminal on your desktop.
Now you have to edit the PATH environment value. The thing is - since Windows 10, Microsoft ships OpenSSH inside the Windows distribution, however, that binary is limited and WILL NOT WORK with the plugin, so you have to update the PATH to make sure that the system will use Cywgin's binary and not the original Windows binary when you execute ssh command. To do so, in the "Start" menu, find the System (Control panel) and run it, or click the right mouse button on a computer in Windows Explorer and select Properties in the drop-down menu. There you should find Advanced system settings, click it. Now find the Environment Variables button and click it. In the list of SYSTEM variables (the lower one in Windows 10) find the PATH variable and click Edit. You will be shown a list of values in Path variable. Click Create button and insert a new value in the list - C:\cygwin64\bin, that will point to Cygwin's binaries folder. Among other values, you will see this one: %SystemRoot%\System32\OpenSSH, remember it. Now on the right side, there are buttons UP and DOWN which can be used to move certain records above or below others. Your newly added record will be at the very bottom of the list. By using UP button, put your new C:\cygwin64\bin record so that it will be ABOVE the %SystemRoot%\System32\OpenSSH, and also ABOVE %SystemRoot%\System32, just in case. It should eventually look like this:
This is critical because the existence of the binaries is checked in the directories mentioned in that environment value, and the directories are checked sequentially, from the first value to the last, and where the first match is found, the binary from that directory is going to be used.
After you are done, click OK button in all the windows you have opened to properly save the changes.
Open the terminal (Windows CMD.exe). You must make sure that your environment points to your newly installed binaries correctly. You can do this by running
$ ssh -V
This command should clearly return OpenSSH_(VERSION) and NOT OpenSSH_for_Windows_(VERSION). Please make sure this is true, otherwise, the Plugin will not be able to work properly. Also check the location of the binary:
$ which ssh
This command should return /usr/bin/ssh and NOT something like C:\Windows\System32\OpenSSH\ssh.exe. Please make sure this is true before proceeding further.
Now check the rsync binary. This one is simple. Windows does not have any default version of it, so if the binary is found and you get an output like this, then everything is good:
$ which rsync
/usr/bin/rsync
$ rsync --version
rsync version 3.2.7 protocol version 31
Now with all the binaries are properly installed, let's set up the connection properly. By this time, you should already have a prepared remote server with a properly configured openssh server. If not, check out this instruction.
First, the plugin REQUIRES you to connect to a remote server using public key authentication, and I highly recommend creating a dedicated key pair for this instead of using your normal one. So, if you haven't already created a key pair, let's do this. I recommend using the ED25519 algorithm because of its reliability and incredible performance. So, open a Cygwin64 Terminal and create a keypair with a command like this:
$ ssh-keygen -o -t ed25519 -f /home/pavel/.ssh/id_ed25519_android_builds_server -C "key_for_android_build_server" -P ""
Note that you should insert your username instead of mine, of course. And if you do not have ~/.ssh folder for some reason, you should create it (mkdir -p ~/.ssh) before running the command above.
Now, after keys have been created, upload your public key (cat /.ssh/id_ed25519_android_builds_server.pub) onto the server. It should be added to the file /.ssh/authorized_keys on your server.
Now, you should create a connection configuration with an alias. It should be added to the file ~/.ssh/config on your local computer. If you do not yet have that file, then create it first: touch ~/.ssh/config, if you do, just append the record to the existing file contents and save the file. The record should look like this (put your IP address instead of the one from the example below):
Host android_builds_server
HostName 12.34.56.78
Port 34567
User builder
IdentityFile ~/.ssh/id_ed25519_android_builds_server
IdentitiesOnly yes
Compression yes
IMPORTANT! Make sure that you have created a file properly. If you used Windows Explorer, it could create your file with the name config.txt, not just config. The file name should be just config, without any extensions!
IMPORTANT! Make sure that your key pair files (id_ed25519_android_builds_server and id_ed25519_android_builds_server.pub), as well as your config file, are stored in the correct directory, which path is seen as /home/pavel/.ssh (insert your user name or course) in the Cygwin bash terminal, and NOT in the C:\Users\pavel.ssh. This is critical because the new ssh binary will only look into /home/pavel/.ssh.
If you have mistakenly created all the files in C:\Users\pavel.ssh, not in /home/pavel/.ssh, then you can easily copy them to the right place. Open the Cygwin Bash terminal and run the following command:
cp -R /cygdrive/c/Users/pavel/.ssh /home/pavel
After that, close the Cygwin64 Terminal and reopen the Windows CMD.exe. If you did everything correctly, you should be able to connect to the server using an alias. Try this:
$ ssh android_builds_server
You should successfully connect to the server. If not, please carefully check out, you could miss something in one of the previous steps. Configuring a Windows computer is more difficult than other operating systems, but fortunately, you will probably need to do this just once.
Congratulations! Everything is done. Your local computer is configured. Now proceed to plugin usage instructions