-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
re-add agentless node manual installation docs (#31647)
* re-add agentless node manual installation docs * fix linter issues * Add missing closing paren Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * use tabs in manual install guide * removed more ScopedBlocks I missed * add note about upgrading to v14 * add redirect and notes linking the two guides to one another * addressed feedback * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * fix links --------- Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
- Loading branch information
1 parent
a1ac96a
commit 492e3b3
Showing
5 changed files
with
907 additions
and
321 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,322 +1,9 @@ | ||
| --- | ||
| title: Using Teleport with OpenSSH in agentless mode | ||
| description: This guide shows you how to set up Teleport in agentless mode to enable secure access to OpenSSH servers so you can protect systems that do not run a Teleport binary. | ||
| keywords: [openssh, teleport, agentless] | ||
| videoBanner: x0eYFUEIOrM | ||
| title: OpenSSH Guides | ||
| description: Teleport Agentless OpenSSH integration guides. | ||
| layout: tocless-doc | ||
| --- | ||
|
|
||
| In this guide, we will show you how to configure Teleport in agentless mode and | ||
| have the OpenSSH server `sshd` join a Teleport cluster. Existing fleets of | ||
| OpenSSH servers can be configured to accept SSH certificates dynamically issued | ||
| by a Teleport CA. | ||
|
|
||
| Using Teleport and OpenSSH has the advantage of getting you up | ||
| and running, but in the long run, we would recommend replacing `sshd` with `teleport`. | ||
| `teleport` SSH servers have support for multiple features that are incompatible with OpenSSH: | ||
|
|
||
| - RBAC and resource filtering based on [dynamically updated labels](../../management/admin/labels.mdx) | ||
| - [Session recording without SSH connection termination](recording-proxy-mode.mdx) | ||
| - [Session sharing](../../connect-your-client/tsh.mdx) | ||
| - [Advanced session recording](bpf-session-recording.mdx) | ||
| - [Restricting outbound network connections in SSH sessions](restricted-session.mdx) | ||
|
|
||
| Teleport supports OpenSSH by proxying SSH connections through the Proxy Service. When a Teleport user requests to connect to an OpenSSH node, the Proxy Service checks the user's Teleport roles. | ||
|
|
||
| If the RBAC checks succeed, the Proxy Service authenticates to the OpenSSH node with a dynamically generated certificate signed by a Teleport CA. This allows the | ||
| Proxy Service to record and audit connections to OpenSSH nodes. | ||
|
|
||
| The Proxy Service prevents Teleport users from bypassing auditing by requiring | ||
| a certificate signed by a Teleport CA that only the Auth Service possesses. | ||
|
|
||
| In this setup, the Teleport SSH Service performs RBAC checks as well as audits and records sessions on its host, which eliminates the need for connection termination when recording SSH sessions. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - OpenSSH version 6.9 or above on your local machine. View your OpenSSH version | ||
| with the command: | ||
|
|
||
| ```code | ||
| $ ssh -V | ||
| ``` | ||
|
|
||
| (!docs/pages/includes/edition-prereqs-tabs.mdx!) | ||
|
|
||
| - A Linux host with the OpenSSH server `sshd` version 7.4 or above installed, | ||
| but not Teleport. The SSH port on this host must be open to traffic from the | ||
| Teleport Proxy Service host. | ||
| - (!docs/pages/includes/tctl.mdx!) | ||
|
|
||
| ## Step 1/3. Configure `sshd` | ||
|
|
||
| Teleport only allows access to resources in your infrastructure via Teleport | ||
| processes that that have joined the cluster. | ||
|
|
||
| To register the OpenSSH node, you must have a valid auth token to connect to the cluster. | ||
| You can generate the token by running the following command against your Teleport Auth Service: | ||
|
|
||
| ```code | ||
| $ tctl tokens add --type=node --format=text | ||
| (=presets.tokens.first=) | ||
| ``` | ||
|
|
||
| Copy the `teleport` binary to your `sshd` host. Configure `sshd` and create a node | ||
| resource on your cluster with the following command: | ||
|
|
||
| ```code | ||
| $ sudo teleport join openssh \ | ||
| --address <Var name="server1.example.com:22" /> \ | ||
| --proxy-server <Var name="teleport.example.com:443" /> \ | ||
| --join-method token \ | ||
| --token <Var name="token" /> \ | ||
| --labels env=dev | ||
| ``` | ||
|
|
||
| Change the command-line options to assign the following values: | ||
| - Set to the address and port of your Teleport Proxy Service. | ||
| - Set to the address and port of the node that will join the cluster. | ||
| - Set to the token value. | ||
|
|
||
| Check that your new node is listed with `tsh ls` or in the Web UI. You can edit the | ||
| hostname and labels with `tctl edit nodes/<hostname>`. If the hostname isn't unique, get the UUID | ||
| from `tctl nodes ls -v` and edit with `tctl edit nodes/<uuid>`. | ||
|
|
||
| ## Step 2/3. Generate an SSH client configuration | ||
|
|
||
| The next step is to configure your OpenSSH client to connect to your `sshd` host | ||
| using credentials managed by Teleport. This configuration will use your user's | ||
| Teleport-issued certificate to authenticate to the `sshd` host. It will also | ||
| authenticate the `sshd` host using the host certificate you generated earlier. | ||
|
|
||
| First, make sure you have logged in to your Teleport cluster: | ||
|
|
||
| <Tabs> | ||
| <TabItem scope={["oss"]} label="Teleport Community Edition"> | ||
|
|
||
| ```code | ||
| $ tsh status | ||
| > Profile URL: https://teleport.example.com:443 | ||
| Logged in as: myuser | ||
| Cluster: teleport.example.com | ||
| Roles: access, auditor, editor, host-certifier | ||
| Logins: ubuntu, root | ||
| Kubernetes: enabled | ||
| Valid until: 2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s] | ||
| Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem scope={["enterprise"]} label="Teleport Enterprise"> | ||
|
|
||
| ```code | ||
| $ tsh status | ||
| > Profile URL: https://teleport.example.com:443 | ||
| Logged in as: myuser | ||
| Cluster: teleport.example.com | ||
| Roles: access, auditor, editor, reviewer, host-certifier | ||
| Logins: ubuntu, root | ||
| Kubernetes: enabled | ||
| Valid until: 2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s] | ||
| Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem scope={["cloud"]} label="Teleport Enterprise Cloud"> | ||
|
|
||
| ```code | ||
| $ tsh status | ||
| > Profile URL: https://mytenant.teleport.sh:443 | ||
| Logged in as: myuser | ||
| Cluster: mytenant.teleport.sh | ||
| Roles: access, auditor, editor, reviewer, host-certifier | ||
| Logins: ubuntu, root | ||
| Kubernetes: enabled | ||
| Valid until: 2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s] | ||
| Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| On your local machine, run the following `tsh` command. This will print a | ||
| configuration block that tells your SSH client to use credentials managed by | ||
| Teleport to connect to hosts in your cluster. | ||
|
|
||
| ```code | ||
| $ tsh config > ssh_config_teleport | ||
| ``` | ||
|
|
||
| This command creates an SSH configuration file at a nonstandard location in | ||
| order to make it easier to clean up, but you can append the output of | ||
| `tsh config` to the default SSH config file (`~/.ssh/config`) if you wish. | ||
|
|
||
|
|
||
| <Details title="How does the config work?"> | ||
|
|
||
| Teleport implements an SSH server that includes several **subsystems**, or | ||
| predefined commands that are run when the server handles a connection. The Proxy | ||
| Service implements a `proxy` subsystem that forwards SSH traffic to remote hosts | ||
| and Trusted Clusters. | ||
|
|
||
| Here is a brief explanation of the configuration that `tsh config` generates: | ||
|
|
||
| ``` | ||
| # Common flags for all {{ .ClusterName }} hosts | ||
| Host *.{{ .ClusterName }} {{ .ProxyHost }} | ||
| UserKnownHostsFile "{{ .KnownHostsPath }}" | ||
| IdentityFile "{{ .IdentityFilePath }}" | ||
| CertificateFile "{{ .CertificateFilePath }}" | ||
| ``` | ||
|
|
||
| If the host you are `ssh`ing into belongs to your Teleport cluster (i.e., its | ||
| address is a subdomain of your cluster's domain), use a Teleport-managed known | ||
| hosts file, private key, and certificate that are stored in the `.tsh` | ||
| directory. | ||
|
|
||
| ``` | ||
| # Flags for all {{ .ClusterName }} hosts except the proxy | ||
| Host *.{{ .ClusterName }} !{{ .ProxyHost }} | ||
| Port 3022 | ||
| ProxyCommand "{{ .TSHPath }}" proxy ssh --cluster={{ .ClusterName }} --proxy={{ .ProxyHost }} %r@%h:%p | ||
| ``` | ||
|
|
||
| If the host that you are `ssh`ing into belongs to your Teleport cluster, the | ||
| OpenSSH client will first execute a command, the `ProxyCommand`, that | ||
| establishes an SSH connection to the Proxy Service. This command, | ||
| `tsh proxy ssh`, requests the `proxy` subsystem in order to forward SSH traffic | ||
| through the Proxy Service to your chosen host (including a host in a Trusted | ||
| Cluster). | ||
|
|
||
| The `tsh proxy ssh` command requests the `proxy` subsystem through a command | ||
| similar to the following, which assumes you are logging in to a node called | ||
| `mynode` as `root` with a cluster called `teleport.example.com`: | ||
|
|
||
| ```code | ||
| $ /usr/bin/ssh -l root -A -o UserKnownHostsFile=/root/.tsh/known_hosts -p 11105 teleport.example.com -s proxy:mynode:3022@teleport.example.com | ||
| ``` | ||
|
|
||
| Notice that the `known_hosts` file used by the command is managed by `tsh`. | ||
| Since the `sshd` host's information is listed in this file, your SSH client can | ||
| authenticate the host via the certificate we generated earlier. | ||
|
|
||
| </Details> | ||
|
|
||
| <Details title="Using PowerShell on Windows?"> | ||
|
|
||
| If using PowerShell on Windows, note that normal shell redirection may write | ||
| the file with the incorrect encoding. To ensure it's written properly, try the | ||
| following: | ||
|
|
||
| ```code | ||
| $ tsh.exe config | out-file .ssh\config -encoding utf8 -append | ||
| ``` | ||
|
|
||
| </Details> | ||
|
|
||
| <Details title="Dialing uppercase hostnames with OpenSSH"> | ||
| Routing in Teleport clusters is case-sensitive by default, but OpenSSH always lowercases hostnames. If you | ||
| are using an OpenSSH client and have hosts with uppercase letters in their hostnames, you may need to set | ||
| `case_insensitive_routing: true` in either the `auth_service` block of your Teleport config, or in the | ||
| `cluster_networking_config` resource. | ||
| </Details> | ||
|
|
||
| <Admonition | ||
| type="tip" | ||
| title="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 are added or removed, be sure to re-run | ||
| `tsh config` and replace the previous configuration. | ||
|
|
||
| </Admonition> | ||
|
|
||
| ## Step 3/3. Connect to your `sshd` host | ||
|
|
||
| Once you have appended the new text to your OpenSSH client configuration file, | ||
| you can log in to your `sshd` host using the configuration we generated earlier. | ||
|
|
||
| First, define environment variables for the address of your Teleport cluster, | ||
| the username you will use to log in to your `sshd` host, and the port on your | ||
| `sshd` host you are using for SSH traffic: | ||
|
|
||
| <Tabs> | ||
| <TabItem scope={["oss", "enterprise"]} label="Self-Hosted"> | ||
|
|
||
| ```code | ||
| # See the available logins you can use to access your sshd host | ||
| $ tsh status | grep Logins | ||
| Logins: ubuntu, root | ||
| $ USER=ubuntu | ||
| $ CLUSTER=teleport.example.com | ||
| $ PORT=22 | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem scope={["cloud"]} label="Teleport Enterprise Cloud"> | ||
|
|
||
| ```code | ||
| # See the available logins you can use to access your sshd host | ||
| $ tsh status | grep Logins | ||
| Logins: ubuntu, root | ||
| $ USER=ubuntu | ||
| $ CLUSTER=mytenant.teleport.sh | ||
| $ PORT=22 | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| Next, SSH in to your remote host: | ||
|
|
||
| ```code | ||
| $ ssh -p ${PORT?} -F ssh_config_teleport "${USER?}@${ADDR?}.${CLUSTER?}" | ||
| ``` | ||
|
|
||
| This name does not need to be resolvable via DNS as the connection will be | ||
| routed through your Teleport Proxy Service. | ||
|
|
||
| <Details title="Why are we overriding the port here?"> | ||
|
|
||
| By default, the OpenSSH client configuration generated by `tsh config` directs | ||
| the Teleport Proxy Service to dial port 3022 of a node in your Teleport cluster. | ||
| This works if the node's SSH Service is listening on port 3022, and means that | ||
| you can connect to the Teleport SSH Service via your OpenSSH client. | ||
|
|
||
| When you join a Teleport node to a cluster, the node creates a reverse tunnel | ||
| to the cluster's Proxy Service. When you run an `ssh` command to access a host | ||
| in your Teleport cluster using the configuration we generated, the Teleport | ||
| Proxy Service will attempt to connect to the host via this reverse tunnel and, | ||
| if that fails, try directly dialing the address. | ||
|
|
||
| In our case, the `sshd` host is not running Teleport, so no reverse tunnel will | ||
| exist. Instead, the Proxy Service will establish a direct connection on the | ||
| host's SSH port. | ||
|
|
||
| </Details> | ||
|
|
||
| <Details title="Using Trusted Clusters?"> | ||
|
|
||
| You can log in to a host in a Trusted Cluster by placing the name of the cluster | ||
| between the name of the node and the name of your root Teleport cluster: | ||
|
|
||
| ```code | ||
| $ ssh -F ssh_config_teleport ${USER?}@node2.leafcluster.${CLUSTER} | ||
| ``` | ||
|
|
||
| </Details> | ||
|
|
||
| <Admonition | ||
| type="tip" | ||
| title="Note" | ||
| > | ||
|
|
||
| Teleport uses OpenSSH certificates instead of keys. When you connect to a | ||
| remote host, OpenSSH verifies that the address of the host is listed under the | ||
| `Principals` section of the OpenSSH certificate. Usually, this is a fully | ||
| qualified domain name, rather than an IP address. | ||
|
|
||
| </Admonition> | ||
| - [Agentless OpenSSH Integration](./openssh/openssh.mdx): How to use Teleport in agentless mode on systems with OpenSSH and `sshd`. | ||
| - [Agentless OpenSSH Integration (Manual Installation)](./openssh/openssh-manual-install.mdx): How to use Teleport in agentless mode | ||
| on systems with OpenSSH and `sshd` that can't run `teleport`. |
Oops, something went wrong.