Skip to content

Latest commit

 

History

History
272 lines (196 loc) · 8.14 KB

config.mdx

File metadata and controls

272 lines (196 loc) · 8.14 KB
title h1 description keywords tocDepth
Teleport Configuration
Teleport Configuration Reference
The detailed guide and reference documentation for configuring Teleport for SSH and Kubernetes access.
config
file
reference
yaml
etc
3

Teleport uses the YAML file format for configuration. A full configuration reference file is shown below. This provides comments and all available options for teleport.yaml.

By default, Teleport reads its configuration from /etc/teleport.yaml.

Before using this reference

Do not use this example configuration in production.

You must edit your configuration file to meet the needs of your environment. Using a copy of the reference configuration will have unintended effects. To create a configuration file that you can use as a starting point, run the following command:

$ teleport configure -o file

There are also configure commands available for the SSH Service and Database Service. See our documentation on teleport node configure and teleport db configure in the Teleport CLI Reference.

You should back up your configuration file before making changes. This will enable you to roll back to the previous configuration if you need to.

Enabling Teleport services

The teleport process can run multiple services.

For some services, you must enable the service within your Teleport configuration in order to start it. Other services are enabled by default.

To enable or disable a service, include the following in your Teleport configuration, replacing service_name with the name of your service (service names are listed below):

service_name:
  enabled: "no"

Teleport supports the following services:

Service Configuration section Enabled by default
Application Service app_service ❌
Auth Service auth_service ✅
Database Service db_service ❌
Discovery Service discovery_service ❌
Kubernetes Service kubernetes_service ❌
Proxy Service proxy_service ✅
SSH Service ssh_service ✅
Desktop Service windows_desktop_service ❌
Jamf Service jamf_service ❌
Debug Service debug_service ✅

Teleport Cloud manages the Auth Service and Proxy Service for you. Instances of Teleport services (e.g., the Application Service and Database Service) should include the following configuration options to avoid unintended effects:

auth_service:
  enabled: false

proxy_service:
  enabled: false

Reference configurations

These example configurations include all possible configuration options in YAML format to demonstrate proper use of indentation.

Choose a Teleport service to view the application configuration options:

Instance-wide settings

These settings apply to any teleport instance:

(!docs/pages/includes/config-reference/instance-wide.yaml!)

Further reading:

Proxy Service

These settings apply to the Teleport Proxy Service:

Teleport Enterprise Cloud manages the Proxy Service for you, so you do not need to specify these configuration settings. 
(!docs/pages/includes/config-reference/proxy-service.yaml!)

Auth Service

These settings apply to the Teleport Auth Service:

Teleport Enterprise Cloud manages the Auth Service for you, so you do not need to specify these configuration settings. 
(!docs/pages/includes/config-reference/auth-service.yaml!)

Further reading:

  • Storage Backends reference: instructions on configuring DynamoDB, S3, etcd, and other highly available backends.
  • Passwordless: More information about the passwordless authentication option.
  • Headless WebAuthn: The headless authentication option.
  • Single Sign-On: Configuring SSO so you can configure Teleport to use a specific SSO authentication connector.
  • Locking: Configuring the locking_mode option.
  • Device Trust: Configuring the device_trust section.
  • Recording Proxy Mode: If you configure Recording Proxy Mode, consider enabling proxy_checks_host_keys.

SSH Service

These settings apply to the Teleport SSH Service:

(!docs/pages/includes/config-reference/ssh-service.yaml!)

Further reading:

Kubernetes Service

These settings apply to the Teleport Kubernetes Service:

(!docs/pages/includes/config-reference/kubernetes-config.yaml!)

Application Service

These settings apply to the Teleport Application Service:

(!docs/pages/includes/config-reference/app-service.yaml!)

Database Service

These settings apply to the Teleport Database Service:

(!docs/pages/includes/config-reference/database-config.yaml!)

Discovery Service

These settings apply to the Teleport Discovery Service:

(!docs/pages/includes/discovery/discovery-config.yaml!)

Windows Desktop Service

These settings apply to the Windows Desktop Service:

(!docs/pages/includes/config-reference/desktop-config.yaml!)

Jamf Service

These settings apply to the Jamf Service:

(!docs/pages/includes/config-reference/jamf-service.yaml!)

Debug Service

These settings apply to the Debug Service

(!docs/pages/includes/config-reference/debug-service.yaml!)

Configuration versions

In order to avoid breaking existing configurations, Teleport's configuration is versioned. The newer configuration version is v3. If a version is not specified in the configuration file, v1 is assumed.

Some new Teleport features require users to opt-in by explicitly upgrading their configuration to a newer version.

Config v1

v1 is the original version of Teleport's file configuration. It is still supported today, but most new users should start with the latest configuration version.

Config v2

Configuration version v2 was introduced in Teleport 8 as part of Teleport's TLS routing feature. With TLS routing, Teleport's proxy listens on a single port and uses ALPN and SNI to route incoming traffic to the correct Teleport service rather than listening on multiple protocol-specific ports.

For backwards compatibility, configuration version v1 always listens on these protocol-specific ports. When Teleport is using configuration version v2, the individual protocol-specific ports are not opened unless explicitly set.

Config v3

Configuration version v3 was introduced with Teleport 11. In version 3, the auth_servers field is no longer supported, and agents must specify one of auth_server or proxy_server to indicate which endpoint to use for joining a Teleport cluster.

Previous versions of Teleport allowed for auth_servers to point to Auth Servers or Proxy Servers. As a result, Teleport would try to connect in multiple different modes, resulting in confusing error messages. With config version 3, Teleport only attempts to connect in a single mode, which is both more efficient and easier to troubleshoot.

For example, this excerpt from a v2 config can be converted to v3 with the following changes.

-version: v2
+version: v3
teleport:
-  auth_servers: [ teleport.example.com:443 ]
+  proxy_server: teleport.example.com:443