# 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; common 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.
Features requiring trust 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.

## 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 over 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.