mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-11 22:49:54 +00:00
Gabriel CoradoandPaul Gottschling
892e13904f
* refactor(docs): update docs to include debug service usage * docs: code review suggestions * docs: update debug service intro definitions * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * docs(diagnostics): move teleport-debug-config section up in the guide --------- Co-authored-by: Paul Gottschling <[email protected]>
237 lines
6.4 KiB
Plaintext
237 lines
6.4 KiB
Plaintext
---
|
|
title: Teleport Configuration Reference
|
|
description: The detailed guide and reference documentation for configuring Teleport for SSH and Kubernetes access.
|
|
keywords: [config, file, reference, yaml, etc]
|
|
tocDepth: 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
|
|
|
|
<Notice type="danger">
|
|
|
|
Do not use this example configuration in production.
|
|
|
|
</Notice>
|
|
|
|
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:
|
|
|
|
```code
|
|
$ 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](cli/teleport.mdx).
|
|
|
|
<Notice type="warning">
|
|
|
|
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.
|
|
|
|
</Notice>
|
|
|
|
## 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):
|
|
|
|
```yaml
|
|
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`|❌|
|
|
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/instance-wide.yaml!)
|
|
```
|
|
|
|
### Proxy Service
|
|
|
|
These settings apply to the Teleport Proxy Service:
|
|
|
|
<Notice type="tip">
|
|
Teleport Enterprise Cloud manages the Proxy Service for you, so you do not need
|
|
to specify these configuration settings.
|
|
</Notice>
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/proxy-service.yaml!)
|
|
```
|
|
|
|
### Auth Service
|
|
|
|
These settings apply to the Teleport Auth Service:
|
|
|
|
<Notice type="tip">
|
|
Teleport Enterprise Cloud manages the Auth Service for you, so you do not need
|
|
to specify these configuration settings.
|
|
</Notice>
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/auth-service.yaml!)
|
|
```
|
|
|
|
### SSH Service
|
|
|
|
These settings apply to the Teleport SSH Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/ssh-service.yaml!)
|
|
```
|
|
|
|
### Kubernetes Service
|
|
|
|
These settings apply to the Teleport Kubernetes Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/kubernetes-config.yaml!)
|
|
```
|
|
|
|
### Application Service
|
|
|
|
These settings apply to the Teleport Application Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/app-service.yaml!)
|
|
```
|
|
|
|
### Database Service
|
|
|
|
These settings apply to the Teleport Database Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/database-config.yaml!)
|
|
```
|
|
|
|
### Discovery Service
|
|
|
|
These settings apply to the Teleport Discovery Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/discovery/discovery-config.yaml!)
|
|
```
|
|
|
|
### Windows Desktop Service
|
|
|
|
These settings apply to the Windows Desktop Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/desktop-config.yaml!)
|
|
```
|
|
|
|
### Jamf Service
|
|
|
|
These settings apply to the Jamf Service:
|
|
|
|
```yaml
|
|
(!docs/pages/includes/config-reference/jamf-service.yaml!)
|
|
```
|
|
|
|
### Debug Service
|
|
|
|
These settings apply to the Debug Service
|
|
|
|
```yaml
|
|
(!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.
|
|
|
|
```diff
|
|
-version: v2
|
|
+version: v3
|
|
teleport:
|
|
- auth_servers: [ teleport.example.com:443 ]
|
|
+ proxy_server: teleport.example.com:443
|
|
```
|