<p>It used to be quite simple: software equivalents existed for Windows for everything we needed. Since Spring 2018, we unfortunately have to use ssh keys. This has simply added an extra step for most things, but has made one thing (rsync) really quite hard to get working.
<p>What makes this all much more tiresome is that Microsoft are introducing some cool new ways of interacting with Linux systems but these are new and need some effort to get configured correctly. See the end of this page for more details.
- well not "hard" exactly, but complicated with lot of steps that are easy to get wrong and with poor feedback as to whether you have done each step correctly.
<p>Most Windows software that we recommend "just works" if you have set up PuTTy and have done the <ahref="keyexchange.html">key-pair setup</a> and are running a local ssh agent (pagent) automatically at boot up on your laptop.
<p>Some software, such as the commercial (but free) GitKraken, requires that you click a checkbox to say that you are "using local SSH agent" rather than specifying ssh private keys explicitly (File->Preferences->Authentication in GitKraken).
<p>Brendan wrote a guide to using putty and git for expo on a Windows machine. It's worth reading and it has lots of screenshots: <ahref="/expofiles/documents/idiots-guide-expo-git.pdf">Idiots guide to accessing expo git.pdf</a>.
<p>Read the online instructions abut using <ahref="https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview">OpenSSH in Windows</a> as an alternative. (Then write them up and edit this handbook to be more useful.)
<p>Linux allows characters in filenames which Windows doesn't. There are also apparently normal filenames which Windows rejects (such as "<ahref="https://answers.microsoft.com/en-us/windows/forum/windows_7-files/why-cant-i-create-a-folder-with-name/23c86662-4988-4c7d-9c2d-3e33d4413de3">CON</a>") for historical reasons. Linux filenames are case-senstitive and Windows filenames aren't: beware.
<p>Linux people like to use <em>links</em>. This is where there is really only one file, but it is referred to by different names. This is particularly useful when a file is moved, but you want people who have got the old location to still be able to find it. This happens quite a lot when updating handbooks.
<p>
The links you are most likely to come across are that what looks like
<spanstyle="font-family:monospace; size=x-small; background-color: lightgray">/home/expo/expoweb</span> is really just a link to the folder <spanstyle="font-family:monospace; size=x-small; background-color: lightgray">/home/expo/repositories/git/expoweb</span>, <br/>
is a link to the file <spanstyle="font-family:monospace; size=x-small; background-color: lightgray">/home/expo/expofiles/gpslogs/essentials/essentials2019.gpx</span>
<p>But that example is in the <spanstyle="font-family:monospace; size=x-small; background-color: lightgray">:expoweb:</span> repository, so you won't be using sFTP to download it. Instead you will be using the version control software which handles it without problems. But we use it as an example of what to look out for when using sFTP.
There are two types of linux links: hard links and symbolic links. Symbolic links are much the same thing as Window's "Shortcuts" but there is no equivalent on Windows to Linux hard links. Fortunately we don't <em>seem</em> to have any hard links anywhere.
<p>What really makes things unpleasant is that sFTP software won't tell you when it comes across a link and will just do something stupid. Our recommended sFTP software - Filezilla - is guilty of this,as it pftp (PuTTy) working in eith sFTP or scp mode.. So what happens is that when you download a load of files onto your laptop using Filezilla it will simply turn every link it finds into a complete copy of the file. Then when you upload those files to the server, the copied file overwrites the link. So the server now has two files with the same content - which is a maintenance nightmare. This is painfully stupid because if it is a symbolic link there is no reason why Filezilla couldn't just create a Windows Shortcut which would do exactly the same thing. But it doesn't.
<p>So the ordinary user won't notice any problems, but the nerds behind the scenes start to cuss and shout and generally carry-on in an expletive-heavy manner.
<p>What is even more irritating is that Filezilla displays an link (<spanstyle="font-family:monospace; size=x-small; background-color: lightgray">essentials.gpx</span> in the image) with a little arrow - it knows perfectly well that it is a symbolic link (although it does display it with a folder icon) - but it downloads it as a file copy.
<li>When using the git version control systems the download of a link works fine. But be careful not to edit the link file downloaded (it is just a text file holding the path of the file holding the actual contents) because then the version control client would upload it to the server and overwrite the link on the server with something that isn't a link. It also won't work as a Windows shortcut, but at least the default behaviour isn't actively dangerous.
<li>When using sFTP, manually check whether any files you are copying from the server are links - look at the symbol in Filezilla.
<li>Be careful not to copy any links using sFTP and instead recreate them manually on the Windows filesystem using right-click "Create shortcut".
<li>You will have to find out what to make the shortcut link to by logging in to the server (using a PuTTy ssh logon) and doing <spanstyle="font-family:monospace; size=x-small; background-color: lightgray">"ls -l"</span> in the folder where the link is.
<li>But later, when re-uploading edited files from Windows to the server, Filezilla will see the Windows shortcut as a ".lnk" file which it will upload, but which will mean nothing to the linux server receiving it. So you would have to manually recreate the symbolic link by logging into the server using ssh and using the "ln -s" command. Yuk.
<li>Even if you use scp instead of sFTP, it does the same stupid thing when copying from a linux filesystem to a Windows filesystem. The PuTTy package includes <spanstyle="font-family:monospace; size=x-small; background-color: lightgray">pscp.exe</span> but even if you force it to use the scp protocol like this:
it downloads a <em>copy</em> of the contents of essentials.gpx and not a link.
<li>A possible fix in the future might be to keep all your expo files in a separate partition of your hard disc which is formatted with a linux filesystem (such as ext4) and run the <ahref="https://www.ext2fsd.com/">ext2ntfs</a> driver to mount this fielsystem read-write from Windows. Probably not a good idea as the driver is a bit flaky in read-write mode and you could lose everything.
hacks are to use the obsolescent cygwin rsync or the rsync packaged within bash within more recent versions of 'Git for Windows' (which is built on <ahref="https://www.msys2.org/docs/what-is-msys2/">MYSYS2</a>.
If you are already familiar with any of these, then use them and not WSL.]
The generated key is in the current directory and you need to move them to ~/.ssh/ as is standard on Linux (which is not at all the same place that PuTTy uses to keep keys on Windows).
<p>Now you have to complete the <ahref="keyexchange.html">key-pair setup</a> with the new key "id_ras_wsl.pub". But you don't need anyone else's help this time as you can use PuTTy to ssh into the server and copy your key to the right place yourself.
<p>Having happily used WSL1 in this manner for a couple of years, it was a rude awakening to try this with a new laptop with a small
hard-drive, so all the expo code was mounted on a plugged-in SD card. The problem of permissions that seemed to be a WSL2 issue reappeared with
a vengence on WSL1.
<p>The recommended WSL procedure (Jan.2018) said to mount the drive using
<ahref="https://devblogs.microsoft.com/commandline/chmod-chown-wsl-improvements/">a new 'metadata' setting</a>:
<pre><code>sudo umount /mnt/d
sudo mount -t drvfs D: /mnt/d -o metadata,uid=1000,gid=1000,umask=22,fmask=111</code></pre>
<p>This is probably why there is a difference between automatically-mounted drives (e.g. C:, /mnt/c) and plug-in drives:
"<em>By default, WSL will set the uid and gid to the default user with drives that are auto-mounted during instance start. If you mount manually, you will
have to set these explicitly (the default user that gets created when WSL is first installed has a uid=1000 and gid=1000).</em>"
<p>And of course you will need to arrange that this happens automatically whenever you start WSL, so you will need to set
<ahref="https://help.ubuntu.com/community/Fstab"><var>/etc/fstab</var></a>, so ensure that the relevant line says:
rsync package you will be able to run the rysnc executable, but it won't have access to the cyptographic key so it can't connect to the expo server (but
you can make it work by using it with ssh from OpenSSH).
<li>WSL <ahref="https://docs.microsoft.com/en-us/windows/wsl/install">Install it like this</a>. This does what we need. This works using a key generated
by its own version of ssh-keygen if you follow the instructions above about putting it in the right place.
<li>WSL: <ahref="https://hackaday.com/2019/12/23/linux-fu-wsl-tricks-blur-the-windows-linux-line/"> Converting Windows paths to Linux paths and
vice-versa</a>.
<li>In WSL you can choose whether to store the files in the WSL view of NTFS, e.g. /mnt/c/expo/ or in an ext4 filesystem e.g.
\\wsl$\Ubuntu-20.04\home\expo . Our experience is with WSL1 with the files on NFTS e.g. /mnt/d/expo/ .
<li>Not all machines are compatible with WSL1 though, see <ahref="wsllaptop.html">WSL in more depth</a> and WSL2 differences.
Even if you have the hardware, you may have to enable it in
advantage that you don't have to partitition your hard drive but the disadvantage that you may not have easy access to the files from Windows (a feature
