Calling Ucampas from Windows

When formatting pages for the filer-hosted departmental web server (www.cl.cam.ac.uk), rather than running Ucampas under Windows, it is better to use SSH to call Ucampas on a Linux server. This is because of differences between the Windows/SMB and Linux/NFS views of the departmental file space (especially with regard to symbolic links), and the Linux/NFS view is what matters for the the web server.

The instructions below help you to configure Windows such that calling Ucampas on a Linux server becomes very easy, by configuring SSH and installing a Windows Shell Extension, such that when you right-click in File Explorer on any .html file, you will see a shortcut menu item (verb) “ucampas” that, when selected, will run Ucampas for you on this file on a Linux server. However, for this to work, you need to navigate to the file via a UNC path starting with \\filer.cl.cam.ac.uk\..., such that the Linux server can translate that path into the corresponding Linux path. (Remember that the Linux server will not know about your local Windows drive mappings.)

Setting up Kerberos and SSH

First, make sure that you have a Windows version installed that comes with OpenSSH for Windows 8.1 or newer. This will be the case for Windows 10 version 21H1 or newer.

Next we need to ensure that Kerberos (GSSAPI) authentication and delegation works for you from Windows, such that the following exact command gives you a Linux prompt:

C:\Users\abc123> ssh -K ely.cl.cam.ac.uk

Unless your Windows computer is connected to a departmental subnet, you will need to activate a Computer Laboratory VPN or VPN2 connection to the department for “ssh -K” to work.

Unless your Windows computer is managed by the department (joined to the DC.CL.CAM.AC.UK domain), you will also have to store (a key derived from) your Kerberos domain password as a Windows credential, to be used when authenticating to any .cl.cam.ac.uk server. If you haven’t done this already (you can check with cmdkey /list), there are two ways to do this:

• Either use the following command line and type in your Kerberos password when prompted:

  C:\Users\abc123> cmdkey /add:*.cl.cam.ac.uk /user:your-crsid@DC.CL.CAM.AC.UK /pass
  

• Or type into the task-bar search box “credential manager”, open the Credential Manager control panel, select “Windows Credentials” / “Add a Windows credential” and then enter as as network address “*.cl.cam.ac.uk”, as user name “your-crsid@DC.CL.CAM.AC.UK”, as well as your Kerberos password, as in:

  

  The result should look like

  

Which password: The password to give to Credential Manager is the same you use to log into any Linux or Windows computer managed by the department. This is (hopefully) not your Raven password. Credential Manager just stores your password persistently on your disk. It does not actually test whether your password is correct, so you won’t get an immediate error message if you entered the wrong password. All that happens if you entered the wrong password is that ssh will later fail to authenticate.

Security note: Credential Manager has now stored your departmental password on your computer as a “Windows Credential”. Do not forget to remove that password credential before giving your computer away. If you lose your computer or get some malware on it, change your departmental password immediately, as it may have been compromised.

Next, we need to tell SSH to use your CRSId when logging into one of the slogin servers. This is likely to be needed either because you may not be using your CRSId as the username on a personal Windows computer, or, if you are on a domain-joined machine, because your username may be prefixed there with DC\ (the domain’s NetBIOS name), neither of which would be understood by the departmental Linux servers.

Use a text editor (e.g., Notepad, Notepad++, Visual Studio Code) to open the file %USERPROFILE%\.ssh\config and add the following lines (replacing “your-crsid” with your departmental user name):

Host slogin-serv.cl.cam.ac.uk slogin.cl.cam.ac.uk svr-ssh-*.cl.cam.ac.uk ssh-remote-*.cl.cam.ac.uk ely.cl.cam.ac.uk
  PubkeyAuthentication no
  GSSAPIAuthentication yes
  GSSAPIDelegateCredentials yes
  User your-crsid

Alternatively, if you hadn’t already an SSH config file with other settings that you need, simply use the following command in cmd.exe:

C:\Users\abc123> echo User your-crsid >%USERPROFILE%\.ssh\config

Now test to confirm that typing the above ssh -K ely.cl.cam.ac.uk command line into a cmd.exe window gives you a Linux shell prompt (and ssh -K ely.cl.cam.ac.uk klist shows you a fresh Kerberos ticket).

Having installed your password credential and activated the VPN should also allow you now to open UNC filer paths such as \\filer.cl.cam.ac.uk\webserver\www\tools.

Installing the Windows Shell extension

Now open the folder \\filer.cl.cam.ac.uk\webserver\www\tools\windows and double-click there on the file ucampas.reg. This will add some entries to your registry and will therefore require you to give permission (several dialog boxes will show up). (If you find registry changes worrying, you can create a system restore point first.)

After you have completed this registry addition, when you right-click in Explorer on any HTML file (or press the menu key), you should now see several new actions on offer in the context menu that appears:

View on webserver (cl-web-view)

This tries to find a https://www.cl.cam.ac.uk/... URL associated with the selected file (if there is any), and opens that in the local default web browser. (Uses the /anfs/www/tools/bin/cl-web-view script on a Linux server.)

Run Makefile on Linux server

This runs the command make (with no arguments) in the folder where the selected file is located. (Useful in folders where there is more to call than just ucampas.)

Run ucampas on Linux server

This runs ucampas on the selected file. You can select either the *-b.html input file or the *.html output file; ucampas will figure out which file to process in either case.

In case you wondered why the “Run Makefile” action is only available by right-clicking on a HTML file: this is because (with the simple Explorer extension mechanism used here) such actions can only be added for files with a given extension, but neither Makefile or the folder itself have such an extension. Hence this slight hack of adding this action also to the .html extension, like the others. It doesn’t matter which .html file you activate “Run Makefile” from; only the folder in which it is located matters here.

If you hold the shift key while right-clicking, you will get two more “extended” actions:

Run ucampas -r on Linux server

This causes Ucampas not only to format the selected page, but also to process (recursively) all its sub-pages.

Run ucampas-clean on Linux server

The ucampas-clean script deletes all ucampas-generated output files in a folder (and its subfolders), i.e. each *.html file for which there exists a *-b.html source in the same folder.

These actions only work for files located on the departmental filer, not for any files on a local disk of our PC. They depend on the tool /anfs/www/tools/bin/filerpath to translate Windows/SMB UNC filer paths into corresponding Linux/Unix/NFS/autofs paths.

Uninstalling this extension

Should you later want remove these registry entries again, use the commands

C:\> reg delete "HKEY_CURRENT_USER\Software\Classes\SystemFileAssociations\.html\shell"
C:\> reg delete "HKEY_CURRENT_USER\Software\Microsoft\Command Processor"

How does this magic work

The ucampas.reg file is a Unicode plaintext file (UTF-16LE with BOM encoded) in the format expected by the Windows command-line tool reg import ucampas.reg. It contains a list of registry keys and associated values to be added to your registry. It makes two changes:

• It adds the key HKEY_CURRENT_USER\Software\Classes\SystemFileAssociations\.html\shell and several sub keys that define new verbs in the Explorer context menu for file type “.html”. It associates cmd.exe command lines with these verbs that all call BAT files located in \\filer.cl.cam.ac.uk\webserver\www\tools\windows. These BAT files do the actual work of SSH-ing into ely and calling the relevant Linux scripts there.
• It also adds to the registry entry HKEY_CURRENT_USER\Software\Microsoft\Command Processor the value DisableUNCCheck=1 such that the CMD command-line interpreter no longer complains about the current working directory being a UNC path.

Can I also use this in a TortoiseSVN working copy?

If you use TortoiseSVN to edit web pages, we normally recommend that you keep your working copy on a local disk (e.g., your C: or D: drive). This is because the TortoiseSVN FAQ recommends against storing working copies on a network share. But the ucampas.reg shell extension will not work for files on your local disk, because the Linux server called has no access there.

If you do keep your working copy on the filer, the TortoiseSVN overlay icons will not show up by default. You can fix that in TortoiseSVN | Settings | Look and Feel | Icon Overlays. Note that the TortoiseSVN FAQ warns that enabling overlays for network drives will slow down not only TortoiseSVN but the whole system.

Other Windows SVN clients are available, including the command-line tools that TortoiseSVN can optionally install. These may be safer to use on filer shares.

Troubleshooting

In case something doesn’t work, here is a checklist with some diagnostic steps that you can perform:

1. If you are outside the William Gates Building: are you sure your CL VPN or VPN2 is connected? If you are inside the WGB on Wifi: are you using the Internal-CL network? The UIS My IP address test page should say “Your IPv4 address as currently seen by servers inside the University is 128.232.xxx.yyy” with xxx < 128. Without using a departmental network connection, your computer will probably not be able to talk to the departmental Active Directory or file servers and will not be able to get a Kerberos ticket (due to firewall restrictions).
2. If you type into cmd.exe the command line ssh -K ely.cl.cam.ac.uk do you get a Linux prompt (Welcome to Ubuntu ...)? If not, something is wrong with your OpenSSH for Windows configuration:
   1. If on the Windows command line (in cmd.exe) you run the command ssh -V does it reply with version number OpenSSH_for_Windows_8.1p1 or newer? If you still have only an older (7.x) version of OpenSSH: use Windows Update to update your operating system to at least Windows 10 version 21H1 first. (Older OpenSSH for Windows versions lack Kerberos support.)
   2. After a failed ssh -K ely.cl.cam.ac.uk command: does the Windows command klist show that you have at least received a Kerberos ticket-granting-ticket as Client: your-crsid @ DC.CL.CAM.AC.UK for Server: krbtgt/DC.CL.CAM.AC.UK @ DC.CL.CAM.AC.UK and a service ticket for Server: host/ely.cl.cam.ac.uk @ DC.CL.CAM.AC.UK? If not: is your VPN running and have you set up the correct password as a Windows Credential in Credential Manager as described above?
   3. Does the command ssh -K your-crsid@ely.cl.cam.ac.uk work, but it fails if you do not provide your CRSId and @? In this case, you should place the line User your-crsid into your %userprofile%\.ssh\config file, such that ssh uses your CRSId as your user name to log in, and not your user name on the local windows machine, which may either be different or have other things (e.g. a NetBIOS name) attached. Just the line User your-crsid should be sufficient.
   4. What does activating the verbose mode with ssh -K -v ely.cl.cam.ac.uk show? It should say that you are logging in with your CRSId, using the gssapi-with-mic authentication method. It should also say that you are delegating credentials:

      debug1: Authenticating to ely.cl.cam.ac.uk:22 as 'mgk25'
      [...]
      debug1: Next authentication method: gssapi-with-mic
      debug1: Delegating credentials
      debug1: Authentication succeeded (gssapi-with-mic).
      

3. If you type into the search box \\filer.cl.cam.ac.uk\webserver\www\tools\bin\windows do you get an Explorer window showing some .bat files? If not, something is probably wrong with your VPN connection to the department or your Credential Manager configuration (see above) or your Active Directory domain account password.
   1. After a failed \\filer.cl.cam.ac.uk attempt: does the Windows command klist show that you have at least received a Kerberos ticket-granting-ticket as Client: your-crsid @ DC.CL.CAM.AC.UK for Server: krbtgt/DC.CL.CAM.AC.UK @ DC.CL.CAM.AC.UK and a service ticket for Server: cifs/filer.cl.cam.ac.uk @ DC.CL.CAM.AC.UK?

If none of the above helps, provide (copy and paste) to sys-admin the output of the following commands typed into cmd.exe, along with a reference to this web page, and forward the ticketing-system auto-response you get to mgk25:

ssh -Kv ely.cl.cam.ac.uk
dir \\filer.cl.cam.ac.uk\webserver\www\tools
klist
curl https://www.cl.cam.ac.uk/cgi-bin/mgk25-test/ip-address
type %userprofile%\.ssh\config