SSH Access to a Host via Teleport

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.

Use this guide to initiate an SSH session using Teleport’s tsh command-line tool. If you prefer, you can alternatively open a session directly through the web UI.

Prerequisites

• Teleport access via Okta (see getting access).
• tsh is installed (see installation instructions).

Process

Request access

Important

When requesting access, the Reason field must contain a permanent link to a GitLab issue (or similar) outlining what access you require and why you need it.

Otherwise your request will be rejected (see Teleport Approver Workflow).

Request access via the web interface

This runbook uses the Teleport CLI, however it may sometimes be convenient to instead use Teleport’s web interface to make an access request.

Navigate to https://production.teleport.gitlab.net/web/requests and click New Access Request.

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:

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

4. An automated message will appear in the #teleport-requests Slack channel. If you’re a member of Engineering or Security, tag your direct manager to review the request. Otherwise, ask in the #eng-managers channel for review by any available engineering manager.

   For more information, refer to the Teleport Approver Workflow.

5. Once approved, the Slack bot will notify you in #teleport-requests.

6. Log in to tsh again, providing the ID of your approved access request

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

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>