suggested SSH client configuration

_toc.yml

@@ -13,6 +13,7 @@ parts:
           - file: user-guide/evolution_for_o365
           - file: user-guide/thunderbird_for_o365
           - file: user-guide/ssh_host_key_certificates
+          - file: user-guide/ssh_client_config
           - file: user-guide/firefox_profile_per_host
           - file: user-guide/putty
 

user-guide/index.md

@@ -17,5 +17,6 @@ This guide contains tricks and recipies for end users using Red Hat Enterprise L
 - [Connect Evolution with Office365](evolution_for_o365)
 - [Connect Thunderbird with Office365](thunderbird_for_o365)
 - SSH asks to accept key on unknown host -> [SSH Host Key Certificates](ssh_host_key_certificates)
+- [SSH Client Configuration](ssh_client_config)
 - Firefox refuses to start with home directory on the network drive -> [Per Host Default Profile for Firefox](firefox_profile_per_host) 
 - AFS `permission denied` when using Putty -> [SSH Access from Windows using Putty](putty)

user-guide/ssh_client_config.md

@@ -0,0 +1,105 @@
+# SSH Client Configuration
+
+Here you find suggestions and best practices for a SSH client configuration file `~/.ssh/config`.
+The assumption is that you are working at the PSI campus or are connected over VPN using `AnyConnect` or `openconnect`.
+
+A good SSH config is a rather personal thing. First there are useful defaults, then starting points for common use cases.
+The last chapter contains the details and explanations useful for a even more streamlined configuration.
+
+## TLDR; start with the defaults
+```
+# useful defaults
+ControlPersist 3h
+ControlPath ~/.ssh/controlmasters/%r@%h:%p
+HashKnownHosts no
+AddKeysToAgent yes
+ServerAliveInterval 300
+ServerAliveCountMax 2
+```
+These are suitable everywhere.
+
+## TLDR; I work on a beamline
+```
+# beamline x09lb
+Host x09lb-* !x09lb-gw*
+    ProxyJump x09lb-gw.psi.ch
+    GSSAPIDelegateCredentials yes
+    ForwardAgent yes
+    ForwardX11Trusted yes
+    ControlMaster auto
+```
+Add all the machines of your beamline (* and ? wildcards allowed) at the host selection line and exclude the gateway at the end. Then update at "ProxyJump" the gateway accordingly.
+
+## TLDR; I run a few servers
+
+```
+Host wmgt0*
+    ControlMaster auto
+
+# my trusted machines I usually connect as root
+Host lx-*
+    User root
+    ProxyJump wmgt02.psi.ch
+    GSSAPIDelegateCredentials yes
+    ForwardAgent yes
+    ControlMaster auto
+```
+
+## TLDR; I connect to all over the PSI
+```
+Host wmgt0*
+    ControlMaster auto
+    GSSAPIDelegateCredentials no
+    ForwardAgent no
+
+# gateways
+Host *-gw* cptgate* ucsgw*
+    ProxyJump wmgt02.psi.ch
+
+# beamlines
+Host x09lb-* !x09lb-gw*
+    ProxyJump x09lb-gw
+
+# more of them...
+
+# default fallback Jumphost
+Host pc* mpc* vpc* vmpc*
+    ProxyJump wmgt02.psi.ch
+
+# do trusted connecion by using FQDN (needed for AFS access, etc.)
+Host *.psi.ch
+    GSSAPIDelegateCredentials yes
+    ForwardAgent yes
+
+```
+
+Here we by default do not trust the machines we connect to, e.g. we do not delegate the Kerberos TGT, do not forward the SSH agent and do not do X forwarding, stuff which could be abused when the destination machine is compromised or run by an hostile admin.
+The "trusted" connection are selected on a case by case basis when needed (e.g. for AFS) by using their FQDN instead of just the short name.
+
+Alternatively you might use
+- `ssh -K` for `GSSAPIDelegateCredentials yes` (Kerberos TGT delegation)
+- `ssh -A` for `ForwardAgent yes`
+- `ssh -X` for `ForwardX11 yes`
+- `ssh -Y` for `ForwardX11Trusted yes`
+
+But note that for tools like scp or rsync these options are difficult to pass in.
+
+If you have trusted servers and/or beamlines, just include for them the according parts of the previous chapters.
+
+## All the Glory Details
+
+The full feature set you get at [`ssh_config(5)`](https://man.openbsd.org/ssh_config).
+
+
+### Multiplexing Master Connection
+
+The master connection (`ControlMaster auto`) multiplexes several connections to one the first connection. This means that the connection setup and authentication step is only done once and so you get a single-signon behaviour (especially useful for `wmgt01` and `wmgt02`) and a faster connection setup for subsequent connections. The `ControlPersist` setting defines for how long the master connection will stay after the last user connection has been closed.
+
+
+### Stale Connection Detection
+A stale connection will be closed after 10 minutes with the suggested default settings:
+```
+ServerAliveInterval 300
+ServerAliveCountMax 2
+```
+When there is no traffic it will send an alive message every 5 minutes and when two of them did not get a response it closes the connection.