CUCC Expedition Handbook - Windows Bulk Updates

A Windows Bulk Update laptop

First read the generic instructions for all the software installations you will need:
Setting up a basic Expo laptop
Setting up a 'survey laptop' for Expo survey processing

Unlike a Linux machine, on Windows there are two distinct levels of 'bulk update laptop' capability:

1. Keys and key management, simple file transfer, scp, ftp
2. Synchronisation of entire file heirarchies: installation and use of rsync
   TLDR; While it can be done, just don't do this in Windows. It's too fiddly and prone to error. If you really want to synchronise a large file heirarchy, use a Linux machine.

Level 01 - Windows Bulk Update

• Things that already work well with any Windows laptop
  - Editing the handbook webpages, typing up SVX files and transcribing the logbook,
  - Anything where the file-transfer to the expo server is via the git version control software
• Things that cause problems
  - filenames and unintentional duplication because links are not understood by Windows,
  - sFTP or scp for more than a handful of files
• Things that are really hard
  - large-scale updating of several folders at once on expofiles without overwriting other people's work
  - 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.
  - That is what you ned a Level 2 machine for.

Software

• Key management, either PuTTY or OpenSSH. You need one of these to generate and to use ssh keys on Windows. Otherwise none of git, scp, ftp (or rsync) will work.
  • OpenSSH for Windows is new (fully working since 2021).
    - Use the Microsoft documented install method which puts the executables in windows\system32\openssh\.
    See also https://learn.microsoft.com/... openssh_overview
    - We need a volunteer to produce documentation on installing and using OpenSSL/Windows. Currently all our Windows documn. used PuTty and all our Linux documentaiotn uses OpenSSL. See also how-to-install-openssl-on-windows-10-11/.
    - We haven't got documentation for using OpenSSL with Filezilla yet. Please write it if you do this.
    OpenSSL integrates well with Github for Windows.
    
  • PuTTY It includes command line tools ssh, scp (pscp) and sFTP (psftp). The PuTTY installation includes puttygen and pagent which you also need. Version 0.77 was released on 2022-05-27.
• GitHub Desktop for Windows - yes this works with the expo server git even though we don't use GitHub itself for expo software.
• VS Code is a free (but not FOSS) editor with in-built git capability and plug-ins ("Git History", "GitLens") which render git branches graphically. Also available for Linux.
• Git for Windows - not as simple to use as it looks
• GitKraken - Very pretty GUI interface to git, also Linux version. Times-out for our server unless you buy it but free for university people.
• WinScp can be used as an alternative to Filezilla if you like (like Filezilla, it uses PuTTY ssh keys). It has a GUI similar to Filezilla
• java - needed for GPSprune and CaveConverter. Has to be installed separately on a Windows machine.
• Notepad++ or any other syntax-highlighting code editor for HTML and python. We have a syntax-highlighter to colourize .svx files, download it: survex.xml (no dark-mode yet though).

Visual Studio Code editor

If you use VS Code here are some relevant extras. Not really for beginners but here are instructions for configuring it for python. On Windows you run VS Code as a Windows app but it communicates directly ("remotely") with the WSL Linux environment.

You will definitely want the "Git History" extension and probably the "GitLens" extension too.

It is entirely feasible (and on a slow machine, recommended) to use VS Code only for git management, and using a faster Windows-native editor, such as Notepad++, for actually editing code and text.

Configuration

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: Idiots guide to accessing expo git.pdf.

Key management and configuration

You need to register a key with the expo server to get upload (i.e. read/write) access. Do this first, Without it none of git, scp, ftp (or rsync) will work. You can do this entirely on your own if you have access to the expo laptop to upload and install the public key generated by your laptop.

On a Windows machine with PuTTY you will need to configure pageant (the puTTY authentication agent) to run at startup to load your key. Note that you are loading your private key, the .ppk file, into pageant and that this key never leaves your laptop.

Full illustrated instructions:

• Installing puTTY on Windows.
• Read the online instructions about using OpenSSH key management (several webpages). (Then write them up and edit this handbook to be more useful.)
• Installing Filezilla.

The above gets the command-line puTTY tools (ssd, sftp, pscp) running.

Most Windows software that we recommend "just works" if you have set up puTTY and have done the key-pair setup and are running a local ssh agent (pagent) automatically at boot up on your laptop.

Some software (such as Filezilla) defaults to using pageant and it "just works".

When using Windows please, please be excessively careful when naming files and survex names.

Configuring Filezilla or equivalents

• Installing Filezilla.

Filezilla defaults to using pageant and it "just works" if you used PuTTy.

Configuring git

Idiots guide to setting up git for expo - PDF - Brendan's guide. Uses puTTY and GitKraken on WIndows. Read this, but most people will need to use VS Code instead of Git Kraken.

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).

Things that cause problems

Filenames

Linux allows characters in filenames which Windows doesn't. There are also apparently normal filenames which Windows rejects (such as "CON") for historical reasons. Linux filenames are case-senstitive and Windows filenames aren't: beware.

Symbolic links and file-transfer

Linux people like to use links. 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.

The links you are most likely to come across are that what looks like /home/expo/expoweb is really just a link to the folder /home/expo/repositories/git/expoweb,
and that expoweb/essentials.gpx is a link to the file /home/expo/expofiles/gpslogs/essentials/essentials2019.gpx

But that example is in the :expoweb: 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 seem to have any hard links anywhere.

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.

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.

What is even more irritating is that Filezilla displays an link (essentials.gpx 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.

Symbolic links: the solution for Windows

• 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.
• When using sFTP, manually check whether any files you are copying from the server are links - look at the symbol in Filezilla.
• Be careful not to copy any links using sFTP and instead recreate them manually on the Windows filesystem using right-click "Create shortcut".
• 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 "ls -l" in the folder where the link is.
• 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.
  
• 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 pscp.exe but even if you force it to use the scp protocol like this: pscp -scp expo@expo.survex.com:expoweb/essentials.gpx . it downloads a copy of the contents of essentials.gpx and not a link.
• 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 ext2ntfs 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.

Level 02 - Windows Bulk Synchronisation with rsync

TLDR just don't do this: please.

When using Windows please, please

• be excessively careful when naming files and survex names and
• be exceptionally careful when using rsync.

rsync is a Linux command-line application, so we need a terminal window to run it and a Windows client executable. None of the packaged software already documented (Filezilla, PuTTY) includes a Windows rsync client.

Windows comes with a terminal window (cmd.exe) so we 'just' need a native Windows rsync executable rsync.exe.

• Install cwRsync which comes with no documentation so you have to already know how to use rsync in some detail.
• Cygwin .
  - You just need the following files: rsync.exe, cygwin1.dll and cygz.dll . Read the instructions
  - You will also have to install OpenSSH and configure the Cygwin system to use the OpenSSH ssh key.
• Install Git for Windows which includes an rsync executable, but you have to use its own bash terminal window. This may be something you don't want to do. This bash window is installed by default when you install gitforwindows. Unfortunately while this MINGW32 setup includes a command-line git executable it doesn't include rsync: you have to excavate it yourself, see a 2020 script, alternatively a 2017 recipe or recent experiments.
• Or you can use WSL: Windows System for Linux
  • This effectively installs a whole copy of Linux
  • Unfortunately this does not integrate with PuTTY at all
  • You will need to do the key management setup again, within the WSL environment.
  • WSL1 is much faster for Windows NTFS filesystems than WSL2, but is now deprecated.
  • WSL on anything other than drive C:\ may involve you with hard to diagnose file permissions problems
  • See our own expo page about setting up a WSL Expo Laptop.
• A full virtual Linux machine running using a hypervisor such as VirtualBox which has its own virtual Linux filesystem. This setup has the disadvantage that you may not have easy access to the files from Windows.

If you just want rsync, then please try the Cygwin method first. If you struggle with Cygwin, then you are unlikely to get any of the other methods to work either. So use Filezilla or WinScp.

If you don't like Cygwin, and want to use a bash terminal environment instead of Windows cmd.exe, then try the MINGW32 method.

Only install WSL if you are pretty sure that you want to use WSL for things other than rsync.