Add tsh config helper to generate OpenSSH client configuration

docs/pages/server-access/guides/openssh.mdx

@@ -222,6 +222,75 @@ It is possible to use the OpenSSH client `ssh` to connect to nodes within a
 Teleport cluster. Teleport supports SSH subsystems and includes a `proxy` subsystem that can be used like `netcat` is with `ProxyCommand` to connect
 through a jump host.
 
+OpenSSH client configuration may be generated automatically by `tsh`, or it can
+be configured manually. In either case, make sure you are running OpenSSH's
+`ssh-agent`, and have logged in to the Teleport proxy:
+
+```bash
+eval `ssh-agent`
+tsh --proxy=root.example.com login
+```
+
+`ssh-agent` will print environment variables into the console. Either `eval` the
+output as in the example above, or copy and paste the output into the shell you
+will be using to connect to a Teleport node. The output exports the
+`SSH_AUTH_SOCK` and `SSH_AGENT_PID` environment variables that allow OpenSSH
+clients to find the SSH agent.
+
+### Automatic Setup
+
+<Admonition
+  type="warning"
+  title="Warning"
+>
+  At this time, automatic OpenSSH client configuration is only supported on
+  Linux and macOS.
+</Admonition>
+
+`tsh` can automatically generate the necessary OpenSSH client configuration to
+connect using the standard OpenSSH client:
+
+```bash
+# on the machine where you want to run the ssh client
+tsh --proxy=root.example.com config
+```
+
+This will generate an OpenSSH client configuration block for the root cluster
+and all currently-known leaf clusters. Append this to your local OpenSSH config
+file (usually `~/.ssh/config`) using your text editor of choice.
+
+Once configured, log into any node in the `root.example.com` cluster as any
+principal listed in your Teleport profile:
+
+```bash
+ssh [email protected]
+```
+
+If any [trusted clusters](../../trustedclusters.mdx) exist, they are also configured:
+```bash
+ssh [email protected]
+```
+
+When connecting to nodes with Teleport daemons running on non-standard ports
+(other than `3022`), a port may be specified:
+```yaml
+ssh -p 4022 [email protected]
+```
+
+<Admonition
+  type="tip"
+  title="Automatic OpenSSH and Multiple Clusters"
+>
+  If you switch between multiple Teleport proxy servers, you'll need to re-run 
+  `tsh config` for each to generate the cluster-specific configuration.
+
+  Similarly, if [trusted clusters](../../trustedclusters.mdx) are added or
+  removed, be sure to re-run the above command and replace the previous
+  configuration.
+</Admonition>
+
+### Manual Setup
+
 On your client machine, you need to import the public key of Teleport's host
 certificate. This will allow your OpenSSH client to verify that host certificates
 are signed by Teleport's trusted host CA:
@@ -250,20 +319,6 @@ certificate authorities for each cluster individually.
   from the root auth server only.
 </Admonition>
 
-Make sure you are running OpenSSH's `ssh-agent`, and have logged in to the
-Teleport proxy:
-
-```bash
-eval `ssh-agent`
-tsh --proxy=root.example.com login
-```
-
-`ssh-agent` will print environment variables into the console. Either `eval` the
-output as in the example above, or copy and paste the output into the shell you
-will be using to connect to a Teleport node. The output exports the
-`SSH_AUTH_SOCK` and `SSH_AGENT_PID` environment variables that allow OpenSSH
-clients to find the SSH agent.
-
 Lastly, configure the OpenSSH client to use the Teleport proxy when connecting
 to nodes with matching names. Edit `~/.ssh/config` for your user or
 `/etc/ssh/ssh_config` for global changes:

lib/client/keyagent.go

@@ -287,7 +287,7 @@ func (a *LocalKeyAgent) AddHostSignersToCache(certAuthorities []auth.TrustedCert
 			return trace.Wrap(err)
 		}
 		a.log.Debugf("Adding CA key for %s", ca.ClusterName)
-		err = a.keyStore.AddKnownHostKeys(ca.ClusterName, publicKeys)
+		err = a.keyStore.AddKnownHostKeys(ca.ClusterName, a.proxyHost, publicKeys)
 		if err != nil {
 			return trace.Wrap(err)
 		}
@@ -380,7 +380,7 @@ func (a *LocalKeyAgent) checkHostKey(addr string, remote net.Addr, key ssh.Publi
 
 	// If the user trusts the key, store the key in the local known hosts
 	// cache ~/.tsh/known_hosts.
-	err = a.keyStore.AddKnownHostKeys(addr, []ssh.PublicKey{key})
+	err = a.keyStore.AddKnownHostKeys(addr, a.proxyHost, []ssh.PublicKey{key})
 	if err != nil {
 		a.log.Warnf("Failed to save the host key: %v.", err)
 		return trace.Wrap(err)

lib/client/keyagent_test.go

@@ -247,7 +247,7 @@ func (s *KeyAgentTestSuite) TestHostCertVerification(c *check.C) {
 	c.Assert(err, check.IsNil)
 	caPublicKey, _, _, _, err := ssh.ParseAuthorizedKey(caPub)
 	c.Assert(err, check.IsNil)
-	err = lka.keyStore.AddKnownHostKeys("example.com", []ssh.PublicKey{caPublicKey})
+	err = lka.keyStore.AddKnownHostKeys("example.com", s.hostname, []ssh.PublicKey{caPublicKey})
 	c.Assert(err, check.IsNil)
 
 	// Generate a host certificate for node with role "node".

lib/client/keystore.go

@@ -75,7 +75,7 @@ type LocalKeyStore interface {
 
 	// AddKnownHostKeys adds the public key to the list of known hosts for
 	// a hostname.
-	AddKnownHostKeys(hostname string, keys []ssh.PublicKey) error
+	AddKnownHostKeys(hostname, proxyHost string, keys []ssh.PublicKey) error
 
 	// GetKnownHostKeys returns all public keys for a hostname.
 	GetKnownHostKeys(hostname string) ([]ssh.PublicKey, error)
@@ -513,7 +513,7 @@ func (fs *fsLocalNonSessionKeyStore) kubeCertPath(idx KeyIndex, kubename string)
 }
 
 // AddKnownHostKeys adds a new entry to `known_hosts` file.
-func (fs *fsLocalNonSessionKeyStore) AddKnownHostKeys(hostname string, hostKeys []ssh.PublicKey) (retErr error) {
+func (fs *fsLocalNonSessionKeyStore) AddKnownHostKeys(hostname, proxyHost string, hostKeys []ssh.PublicKey) (retErr error) {
 	fp, err := os.OpenFile(fs.knownHostsPath(), os.O_CREATE|os.O_RDWR, 0640)
 	if err != nil {
 		return trace.ConvertSystemError(err)
@@ -536,13 +536,28 @@ func (fs *fsLocalNonSessionKeyStore) AddKnownHostKeys(hostname string, hostKeys
 	}
 	// add every host key to the list of entries
 	for i := range hostKeys {
-		fs.log.Debugf("Adding known host %s with key: %v", hostname, sshutils.Fingerprint(hostKeys[i]))
+		fs.log.Debugf("Adding known host %s with proxy %s and key: %v", hostname, proxyHost, sshutils.Fingerprint(hostKeys[i]))
 		bytes := ssh.MarshalAuthorizedKey(hostKeys[i])
-		line := strings.TrimSpace(fmt.Sprintf("%s %s", hostname, bytes))
+
+		// Write keys in an OpenSSH-compatible format. A previous format was not
+		// quite OpenSSH-compatible, so we may write a duplicate entry here. Any
+		// duplicates will be pruned below.
+		// We include both the proxy server and original hostname as well as the
+		// root domain wildcard. OpenSSH clients match against both the proxy
+		// host and nodes (via the wildcard). Teleport itself occasionally uses
+		// the root cluster name.
+		line := fmt.Sprintf(
+			"@cert-authority %s,%s,*.%s %s type=host",
+			proxyHost, hostname, hostname, strings.TrimSpace(string(bytes)),
+		)
 		if _, exists := entries[line]; !exists {
 			output = append(output, line)
 		}
 	}
+	// Prune any duplicate host entries for migrated hosts. Note that only
+	// duplicates matching the current hostname/proxyHost will be pruned; others
+	// will be cleaned up at subsequent logins.
+	output = pruneOldHostKeys(output)
 	// re-create the file:
 	_, err = fp.Seek(0, 0)
 	if err != nil {
@@ -557,6 +572,33 @@ func (fs *fsLocalNonSessionKeyStore) AddKnownHostKeys(hostname string, hostKeys
 	return fp.Sync()
 }
 
+// matchesWildcard ensures the given `hostname` matches the given `pattern`.
+// The `pattern` may be prefixed with `*.` which will match exactly one domain
+// segment, meaning `*.example.com` will match `foo.example.com` but not
+// `foo.bar.example.com`.
+func matchesWildcard(hostname, pattern string) bool {
+	// Don't allow non-wildcard patterns.
+	if !strings.HasPrefix(pattern, "*.") {
+		return false
+	}
+
+	// Never match a top-level hostname.
+	if !strings.Contains(hostname, ".") {
+		return false
+	}
+
+	// Don't allow empty matches.
+	pattern = pattern[2:]
+	if strings.TrimSpace(pattern) == "" {
+		return false
+	}
+
+	hostnameParts := strings.Split(hostname, ".")
+	hostnameRoot := strings.Join(hostnameParts[1:], ".")
+
+	return hostnameRoot == pattern
+}
+
 // GetKnownHostKeys returns all known public keys from `known_hosts`.
 func (fs *fsLocalNonSessionKeyStore) GetKnownHostKeys(hostname string) ([]ssh.PublicKey, error) {
 	bytes, err := ioutil.ReadFile(fs.knownHostsPath())
@@ -578,7 +620,7 @@ func (fs *fsLocalNonSessionKeyStore) GetKnownHostKeys(hostname string) ([]ssh.Pu
 			hostMatch = (hostname == "")
 			if !hostMatch {
 				for i := range hosts {
-					if hosts[i] == hostname {
+					if hosts[i] == hostname || matchesWildcard(hostname, hosts[i]) {
 						hostMatch = true
 						break
 					}
@@ -667,7 +709,7 @@ func (noLocalKeyStore) DeleteUserCerts(idx KeyIndex, opts ...CertOption) error {
 	return errNoLocalKeyStore
 }
 func (noLocalKeyStore) DeleteKeys() error { return errNoLocalKeyStore }
-func (noLocalKeyStore) AddKnownHostKeys(hostname string, keys []ssh.PublicKey) error {
+func (noLocalKeyStore) AddKnownHostKeys(hostname, proxyHost string, keys []ssh.PublicKey) error {
 	return errNoLocalKeyStore
 }
 func (noLocalKeyStore) GetKnownHostKeys(hostname string) ([]ssh.PublicKey, error) {

lib/client/keystore_test.go

@@ -164,11 +164,11 @@ func TestKnownHosts(t *testing.T) {
 	_, p2, _ := s.keygen.GenerateKeyPair("")
 	pub2, _, _, _, _ := ssh.ParseAuthorizedKey(p2)
 
-	err = s.store.AddKnownHostKeys("example.com", []ssh.PublicKey{pub})
+	err = s.store.AddKnownHostKeys("example.com", "proxy.example.com", []ssh.PublicKey{pub})
 	require.NoError(t, err)
-	err = s.store.AddKnownHostKeys("example.com", []ssh.PublicKey{pub2})
+	err = s.store.AddKnownHostKeys("example.com", "proxy.example.com", []ssh.PublicKey{pub2})
 	require.NoError(t, err)
-	err = s.store.AddKnownHostKeys("example.org", []ssh.PublicKey{pub2})
+	err = s.store.AddKnownHostKeys("example.org", "proxy.example.org", []ssh.PublicKey{pub2})
 	require.NoError(t, err)
 
 	keys, err := s.store.GetKnownHostKeys("")
@@ -178,9 +178,9 @@ func TestKnownHosts(t *testing.T) {
 
 	// check against dupes:
 	before, _ := s.store.GetKnownHostKeys("")
-	err = s.store.AddKnownHostKeys("example.org", []ssh.PublicKey{pub2})
+	err = s.store.AddKnownHostKeys("example.org", "proxy.example.org", []ssh.PublicKey{pub2})
 	require.NoError(t, err)
-	err = s.store.AddKnownHostKeys("example.org", []ssh.PublicKey{pub2})
+	err = s.store.AddKnownHostKeys("example.org", "proxy.example.org", []ssh.PublicKey{pub2})
 	require.NoError(t, err)
 	after, _ := s.store.GetKnownHostKeys("")
 	require.Equal(t, len(before), len(after))
@@ -191,6 +191,14 @@ func TestKnownHosts(t *testing.T) {
 	keys, _ = s.store.GetKnownHostKeys("example.org")
 	require.Equal(t, len(keys), 1)
 	require.True(t, apisshutils.KeysEqual(keys[0], pub2))
+
+	// check for proxy and wildcard as well:
+	keys, _ = s.store.GetKnownHostKeys("proxy.example.org")
+	require.Equal(t, 1, len(keys))
+	require.True(t, apisshutils.KeysEqual(keys[0], pub2))
+	keys, _ = s.store.GetKnownHostKeys("*.example.org")
+	require.Equal(t, 1, len(keys))
+	require.True(t, apisshutils.KeysEqual(keys[0], pub2))
 }
 
 // TestCheckKey makes sure Teleport clients can load non-RSA algorithms in
@@ -226,7 +234,7 @@ func TestProxySSHConfig(t *testing.T) {
 	caPub, _, _, _, err := ssh.ParseAuthorizedKey(CAPub)
 	require.NoError(t, err)
 
-	err = s.store.AddKnownHostKeys("127.0.0.1", []ssh.PublicKey{caPub})
+	err = s.store.AddKnownHostKeys("127.0.0.1", idx.ProxyHost, []ssh.PublicKey{caPub})
 	require.NoError(t, err)
 
 	clientConfig, err := key.ProxyClientSSHConfig(s.store)
@@ -538,3 +546,22 @@ func TestMemLocalKeyStore(t *testing.T) {
 	require.Error(t, err)
 	require.Nil(t, retrievedKey)
 }
+
+func TestMatchesWildcard(t *testing.T) {
+	// Not a wildcard pattern.
+	require.False(t, matchesWildcard("foo.example.com", "example.com"))
+
+	// Not a match.
+	require.False(t, matchesWildcard("foo.example.org", "*.example.com"))
+
+	// Too many levels deep.
+	require.False(t, matchesWildcard("a.b.example.com", "*.example.com"))
+
+	// Single-part hostnames never match.
+	require.False(t, matchesWildcard("example", "*.example.com"))
+
+	// Valid wildcard matches.
+	require.True(t, matchesWildcard("foo.example.com", "*.example.com"))
+	require.True(t, matchesWildcard("bar.example.com", "*.example.com"))
+	require.True(t, matchesWildcard("bar.foo", "*.foo"))
+}