SSH Access to a Host via Teleport

Use this guide to initiate an SSH session via Teleport using the tsh CLI. If you prefer, you can alternatively open a session directly through the web UI.

Always follow the change management process

To make changes in production, open a change request in #production using /change declare. An SRE will execute the steps on your behalf. See the change management process for details.

Prerequisites

• Teleport access via Okta. If you do not have this yet, follow the getting access guide first.
• tsh is installed. See installation instructions.

Process

Default access

Most non-production hosts are accessible by default, so skip the Request Access steps and go straight to Log in.

Request access

Request access via the web interface

This runbook outlines how to issue an access request via the Teleport CLI, however they can also be made via Teleport’s web interface. Refer to Role-based access for the steps.

1. Log in to Teleport:

tsh login --proxy=production.teleport.gitlab.net

2. Identify the name of the node:

The name of the Teleport node must be provided in order to log in. This is usually equal to the hostname, but in some cases it may be the fully-qualified domain name.

tsh ls --search redis   # search by node name
tsh ls                  # all hosts
tsh ls env=gstg         # filter by environment
tsh ls env=gprd

3. Request access to the resource:

Important

The Reason field must contain a permanent link to a GitLab issue (or similar) outlining why you need access, or your request will be rejected (see Teleport Approver Workflow).

tsh request create \
  --resource=<node name> \
  --reason="<GitLab issue URL / ZenDesk ticket URL>"

4. Ask an Engineering or Security manager to review the request. You may direct them to the Teleport Approver Workflow in case they are unfamiliar with the process.

5. Once approved, log in with tsh using the request ID to assume the role:

tsh login --request-id=<request-id>

Tip

The --proxy=production.teleport.gitlab.net flag must be provided the first time you use tsh, after which it will be remembered and does not need to be provided again.

Log in

1. Connect to the host:

tsh ssh <username>@<hostname>

Next Steps

• Access expires after 12 hours. Renew it before or after expiration using the same request process.
• Learn about tsh’s features in Teleport’s docs.

Support

• For help with Teleport or the approval process, ask in #security_help.
• To report a Teleport bug, open an issue with Infrastructure Security.

Troubleshooting

tsh request create timed out

tsh request create will wait for approval and return once the request is approved, denied, or expires.

If it times out before a decision, check #teleport-requests slack channel or the Teleport Web UI for the request ID — you don’t need to re-request if it was approved.

failed to add one or more keys to the agent

See getting_access.md — Troubleshooting.

Verbose output

tsh --debug ssh <user>@<hostname>