![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Teleport Recording Proxy Mode
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Teleport Recording Proxy Mode was added to allow Teleport users
to enable session recording for servers running sshd
, which is helpful
when gradually transitioning large server fleets to Teleport.
Teleport Cloud only supports session recording at the Node level. If you are interested in setting up session recording, read our Server Access Getting Started Guide so you can start replacing your OpenSSH servers with Teleport Nodes.
We consider Recording Proxy Mode to be less secure than recording at the Node level for two reasons:
- It grants additional privileges to the Teleport Proxy Service. In the default Node Recording mode, the Proxy Service stores no secrets and cannot "see" the decrypted data. This makes a Proxy Server less critical to the security of the overall cluster. But if an attacker gains physical access to a Proxy Server running in Proxy Recording mode, they will be able to see the decrypted traffic and client keys stored in the Proxy Server's process memory.
- Recording Proxy Mode requires the use of SSH agent forwarding. Agent forwarding is required because without it, a Proxy Server will not be able to establish a second connection to the destination node.
The Teleport Proxy Service should be available to clients and set up with TLS.
Prerequisites
-
A running self-hosted Teleport cluster. If you want to get started with self-hosted Teleport Enterprise, contact Sales. You can also set up a demo environment with Teleport Community Edition.
-
The
tctl
admin tool andtsh
client tool version >= 16.2.1.Visit Installation for instructions on downloading
tctl
andtsh
.
- A host where you will run an OpenSSH server.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/3. Configure Teleport
When running Teleport in production, you should adhere to the following best practices to avoid security incidents:
- Avoid using
sudo
in production environments unless it's necessary. - Create new, non-root, users and use test instances for experimenting with Teleport.
- Run Teleport's services as a non-root user unless required. Only the SSH
Service requires root access. Note that you will need root permissions (or
the
CAP_NET_BIND_SERVICE
capability) to make Teleport listen on a port numbered <1024
(e.g.443
). - Follow the principle of least privilege. Don't give users
permissive roles when more a restrictive role will do.
For example, don't assign users the built-in
access,editor
roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions. - When you enroll Teleport resources—for example, new databases or applications—you
should save the invitation token to a file.
If you enter the token directly on the command line, a malicious user could view
it by running the
history
command on a compromised system.
You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.
Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.
Enable Proxy Recording Mode
To enable session recording for sshd
nodes, the cluster must be switched to
Recording Proxy Mode. In this mode, the recording will be done on the Proxy level.
Edit the Auth Service configuration file as follows:
# snippet from /etc/teleport.yaml
auth_service:
# Session Recording must be set to Proxy to work with OpenSSH
session_recording: "proxy" # can also be "off" and "node" (default)
Optional insecure step: Disable strict host checking
When in recording mode, Teleport will check that the host certificate of any Node a user connects to is signed by a Teleport CA. By default, this is a strict check. If the Node presents just a key or a certificate signed by a different CA, Teleport will reject this connection with the error message:
ssh: handshake failed: remote host presented a public key, expected a host
certificate
You can disable strict host checks as shown below. However, this opens the possibility for Person-in-the-Middle attacks and is not recommended.
# snippet from /etc/teleport.yaml
auth_service:
proxy_checks_host_keys: no
Step 2/3. Configure sshd
sshd
must be told to allow users to log in with certificates generated
by the Teleport User CA. Start by exporting the Teleport CA public key.
On your Teleport Node, export the Teleport Certificate Authority certificate into a file and update your SSH configuration to trust Teleport's CA. Assign proxy to the address of your Teleport Proxy Service:
curl 'https://proxy/webapi/auth/export?type=user' | sed s/cert-authority\ // > teleport_user_ca.pubsudo mv ./teleport_user_ca.pub /etc/ssh/teleport_user_ca.pubecho "TrustedUserCAKeys /etc/ssh/teleport_user_ca.pub" | sudo tee -a /etc/ssh/sshd_config
Restart sshd
.
Now, sshd
will trust users who present a Teleport-issued certificate.
The next step is to configure host authentication.
The recommended solution is to ask Teleport to issue valid host certificates for all OpenSSH nodes. To generate a host certificate, run this on your Teleport Auth Server:
Creating host certs, with an array of every host to be accessed.
Wildcard certs aren't supported by OpenSSH. The domain must be fully
qualified.
Management of the host certificates can become complex. This is another
reason we recommend using Teleport SSH on nodes.
sudo tctl auth sign \ --host=api.example.com,ssh.example.com,64.225.88.175,64.225.88.178 \ --format=openssh \ --out=api.example.com
The credentials have been written to api.example.com, api.example.com-cert.pubYou can use ssh-keygen to verify the contents.
ssh-keygen -L -f api.example.com-cert.pubapi.example.com-cert.pub:
Type: [email protected] host certificate
Public key: RSA-CERT SHA256:ireEc5HWFjhYPUhmztaFud7EgsopO8l+GpxNMd3wMSk
Signing CA: RSA SHA256:/6HSHsoU5u+r85M26Ut+M9gl+HventwSwrbTvP/cmvo
Key ID: ""
Serial: 0
Valid: after 2020-07-29T20:26:24
Principals:
api.example.com
ssh.example.com
64.225.88.175
64.225.88.178
Critical Options: (none)
Extensions:
x-teleport-authority UNKNOWN OPTION (len 47)
x-teleport-role UNKNOWN OPTION (len 8)
Then add the following lines to /etc/ssh/sshd_config
on all OpenSSH nodes, and
restart sshd
.
HostKey /etc/ssh/api.example.com
HostCertificate /etc/ssh/api.example.com-cert.pub
Step 3/3. Use Proxy Recording Mode
Now you can use the tsh ssh
command to log in to any sshd
node in the
cluster, and the session will be recorded.
tsh ssh to use default ssh port:22
tsh ssh --port=22 [email protected]Example for a Amazon EC2 Host
tsh ssh --port=22 [email protected]
If you want to use the OpenSSH ssh
client for logging into sshd
servers behind a proxy
in "recording mode", you have to tell the ssh
client to use a jump host and
enable SSH agent forwarding, otherwise, a recording proxy will not be able to
terminate the SSH connection to record it:
Note that agent forwarding is enabled twice: one from a client to a proxy
(mandatory if using a recording proxy), and then optionally from a proxy
to the end server if you want your agent running on the end server
ssh -o "ForwardAgent yes" \ -o "ProxyCommand ssh -o 'ForwardAgent yes' -p 3023 %[email protected] -s proxy:%h:%p" \ [email protected]
To avoid typing all this and use the usual ssh [email protected]
, users can update their ~/.ssh/config
file.
Verify that a Teleport certificate is loaded into the agent after logging in:
Login as Joe
tsh login --proxy=proxy.example.com --user=joesee if the certificate is present (look for "teleport:joe") at the end of the cert
ssh-add -L
It is well known that the Gnome Keyring SSH agent, used by many popular Linux desktops like Ubuntu, and gpg-agent
from GnuPG do not support SSH
certificates. We recommend using the ssh-agent
from OpenSSH.
Alternatively, you can disable the SSH agent integration entirely using the
--no-use-local-ssh-agent
flag or TELEPORT_USE_LOCAL_SSH_AGENT=false
environment variable with tsh
.
OpenSSH rate limiting
When using a Teleport proxy in "recording mode", be aware of OpenSSH's built-in rate-limiting. On large numbers of Proxy Service connections, you may encounter errors like:
channel 0: open failed: connect failed: ssh: handshake failed: EOF
See the MaxStartups
setting in man sshd_config
. This setting means that by
default, OpenSSH only allows 10 unauthenticated connections at a time and starts
dropping connections 30% of the time when the number of connections goes over 10.
When it hits 100 authentication connections, all new connections are
dropped.
To increase the concurrency level, increase the value to something like
MaxStartups 50:30:100
. This allows 50 concurrent connections and a max of 100.