Teleport teleport.yaml Configuration File Reference

Teleport reads its configuration from a YAML file, typically located at /etc/teleport.yaml. This file controls which services the process runs, how they communicate, and where state is stored. Every setting that can appear in teleport.yaml can also be overridden by an environment variable of the form TELEPORT_<SECTION>_<KEY> — for example, the auth service’s listen address becomes TELEPORT_AUTH_SERVICE_LISTEN_ADDR. When you run multiple services on the same machine (the most common production pattern), each service section is enabled under the same configuration file and Teleport starts them all in a single process.

After editing teleport.yaml, restart the teleport service (sudo systemctl restart teleport) for changes to take effect.

Top-level structure

# /etc/teleport.yaml
teleport:         # global node settings
  nodename: ...

auth_service:     # Auth Service (cluster control plane)
  enabled: true

proxy_service:    # Proxy Service (public-facing gateway)
  enabled: true

ssh_service:      # SSH Service (Linux server access)
  enabled: true

kubernetes_service:  # Kubernetes Service
  enabled: false

db_service:       # Database Service
  enabled: false

app_service:      # Application Service
  enabled: false

windows_desktop_service:   # Windows Desktop Service
  enabled: false

`teleport` section

The teleport block configures node-wide identity and storage.

teleport — global settings

Field	Type	Default	Description
`nodename`	string	system hostname	Unique name for this Teleport instance in the cluster.
`data_dir`	string	`/var/lib/teleport`	Directory for persistent state, certificates, and SQLite cache.
`pid_file`	string	(none)	Path to write the process PID file.
`advertise_ip`	string	(auto-detected)	Public IP address announced to other cluster members.
`auth_token`	string	(none)	Static token used to join a cluster (prefer `join_params`).
`join_params.token_name`	string	(none)	Name of a provisioning token for joining.
`join_params.method`	string	`token`	Join method: `token`, `iam`, `ec2`, `github`, `gcp`, `azure`, `kubernetes`.
`log.output`	string	`stderr`	Log destination: `stderr`, `stdout`, or a file path.
`log.severity`	string	`INFO`	Log level: `DEBUG`, `INFO`, `WARN`, `ERROR`.
`log.format.output`	string	`text`	Log format: `text` or `json`.
`ca_pin`	string	(none)	SHA-256 fingerprint of the cluster CA, used for first-time join.
`diag_addr`	string	(none)	Address for the `/healthz` and `/readyz` diagnostic endpoints.

teleport:
  nodename: node-01
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
    format:
      output: json
  join_params:
    token_name: my-join-token
    method: token
  diag_addr: "0.0.0.0:3000"

`auth_service` section

The Auth Service is the cluster certificate authority and the single source of truth for all access decisions.

auth_service — authentication and certificate authority

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Auth Service on this node.
`listen_addr`	string	`0.0.0.0:3025`	Address the Auth Service binds on.
`cluster_name`	string	(required)	Unique cluster name; cannot be changed after initial setup.
`tokens`	list	`[]`	Static join tokens (format: `"role:token_value"`). Prefer dynamic tokens.
`authentication.type`	string	`local`	Authentication backend: `local`, `github`, `oidc`, `saml`.
`authentication.second_factor`	string	`otp`	Second factor: `off`, `otp`, `webauthn`, `on` (best available).
`authentication.webauthn.rp_id`	string	(proxy domain)	WebAuthn relying party ID (typically your proxy domain).
`authentication.require_session_mfa`	string	`no`	Cluster-wide per-session MFA: `no`, `yes`, `hardware_key`.
`session_recording`	string	`node`	Where sessions are recorded: `node`, `proxy`, `off`, `node-sync`, `proxy-sync`.
`storage.type`	string	`dir`	State backend: `dir` (SQLite), `dynamodb`, `firestore`, `etcd`.
`storage.region`	string	(AWS region)	Region for DynamoDB or Firestore.
`storage.table_name`	string	(none)	DynamoDB table name.
`audit_events_uri`	list	`[]`	Destinations for audit events (e.g., `dynamodb://table`, `s3://bucket`, `file:///path`).
`audit_sessions_uri`	string	(none)	S3/GCS URI for session recordings.
`client_idle_timeout`	duration	`never`	Disconnect idle clients.
`disconnect_expired_cert`	bool	`false`	Disconnect sessions when the client certificate expires.

auth_service:
  enabled: true
  listen_addr: 0.0.0.0:3025
  cluster_name: example.teleport.sh
  authentication:
    type: local
    second_factor: webauthn
    webauthn:
      rp_id: example.teleport.sh
  session_recording: node
  storage:
    type: dynamodb
    region: us-east-1
    table_name: teleport-state
  audit_events_uri:
    - dynamodb://teleport-events
    - s3://my-audit-bucket/events
  audit_sessions_uri: s3://my-audit-bucket/recordings

`proxy_service` section

The Proxy Service is the public-facing gateway that routes traffic to the Auth Service, SSH nodes, Kubernetes clusters, databases, and applications.

proxy_service — public gateway

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Proxy Service.
`listen_addr`	string	`0.0.0.0:3023`	Address for SSH proxy connections.
`web_listen_addr`	string	`0.0.0.0:3080`	Address for the Web UI and HTTPS API.
`tunnel_listen_addr`	string	`0.0.0.0:3024`	Reverse tunnel listener for agents.
`public_addr`	string	(none)	Publicly reachable address (host:port). Used in issued certificates.
`https_keypairs`	list	`[]`	TLS certificate/key pairs for the Web UI.
`acme.enabled`	bool	`false`	Obtain Let’s Encrypt certificates automatically.
`acme.email`	string	(none)	Email for Let’s Encrypt ACME registration.
`kube_listen_addr`	string	`0.0.0.0:3026`	Address for Kubernetes proxy connections.
`mysql_listen_addr`	string	`0.0.0.0:3036`	Address for MySQL database proxy.
`postgres_listen_addr`	string	(none)	Override address for PostgreSQL proxy (default shares web port).
`trusted_cluster_token`	string	(none)	Token for connecting leaf clusters.

proxy_service:
  enabled: true
  public_addr: example.teleport.sh:443
  listen_addr: 0.0.0.0:3023
  web_listen_addr: 0.0.0.0:443
  tunnel_listen_addr: 0.0.0.0:3024
  acme:
    enabled: true
    email: ops@example.com

`ssh_service` section

The SSH Service turns the node into a Teleport-managed SSH server.

ssh_service — SSH node

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the SSH Service.
`listen_addr`	string	`0.0.0.0:3022`	Address for inbound SSH connections.
`labels`	map	`{}`	Static labels applied to this node. Used for RBAC.
`commands`	list	`[]`	Shell commands whose output becomes dynamic labels.
`permit_user_env`	bool	`false`	Allow users to pass environment variables through SSH.
`pam.enabled`	bool	`false`	Enable PAM integration for session creation.
`pam.service_name`	string	`sshd`	PAM service name.
`enhanced_recording.enabled`	bool	`false`	Enable BPF-based enhanced session recording.

ssh_service:
  enabled: true
  listen_addr: 0.0.0.0:3022
  labels:
    env: production
    team: platform
  commands:
    - name: arch
      command: [uname, -p]
      period: 1h
  enhanced_recording:
    enabled: true

`kubernetes_service` section

The Kubernetes Service proxies access to Kubernetes API servers.

kubernetes_service — Kubernetes proxy

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Kubernetes Service.
`listen_addr`	string	`0.0.0.0:3026`	Address to listen for Kubernetes API connections.
`kubeconfig_file`	string	(in-cluster)	Path to a kubeconfig granting access to Kubernetes clusters.
`kube_cluster_name`	string	(none)	Name of the in-cluster Kubernetes cluster to register.
`labels`	map	`{}`	Labels applied to the Kubernetes cluster resource.
`resources`	list	`[]`	Dynamic clusters discovered via label selectors.

kubernetes_service:
  enabled: true
  kube_cluster_name: my-eks-cluster
  labels:
    env: production
    cloud: aws

`db_service` section

The Database Service proxies connections to databases (PostgreSQL, MySQL, MongoDB, and more).

db_service — database proxy

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Database Service.
`databases`	list	`[]`	Statically enrolled databases.
`databases[*].name`	string	(required)	Unique resource name of the database.
`databases[*].protocol`	string	(required)	Protocol: `postgres`, `mysql`, `mongodb`, `sqlserver`, `redis`, etc.
`databases[*].uri`	string	(required)	Connection endpoint (host:port).
`databases[*].description`	string	(none)	Human-readable description.
`databases[*].labels`	map	`{}`	Labels for RBAC matching.
`databases[*].tls.mode`	string	`verify-full`	TLS mode: `verify-full`, `verify-ca`, `insecure`.
`databases[*].aws.region`	string	(none)	AWS region for IAM-authenticated RDS/Aurora databases.

db_service:
  enabled: true
  databases:
    - name: prod-postgres
      description: "Production PostgreSQL"
      protocol: postgres
      uri: "pg.internal:5432"
      labels:
        env: production
    - name: analytics-mysql
      protocol: mysql
      uri: "mysql.internal:3306"
      labels:
        env: production
        team: data

`app_service` section

The Application Service exposes web applications and cloud provider APIs through Teleport.

app_service — web application and API proxy

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Application Service.
`apps`	list	`[]`	Statically enrolled applications.
`apps[*].name`	string	(required)	Unique application name (used in the URL).
`apps[*].uri`	string	(required)	Internal URL of the application.
`apps[*].public_addr`	string	(none)	Custom public address, otherwise `<name>.<proxy_addr>`.
`apps[*].description`	string	(none)	Human-readable description.
`apps[*].labels`	map	`{}`	Labels for RBAC matching.
`apps[*].insecure_skip_verify`	bool	`false`	Skip TLS certificate verification for the upstream app.
`apps[*].rewrite.headers`	list	`[]`	HTTP headers to inject or rewrite.
`apps[*].cloud`	string	(none)	Cloud API proxy: `AWS`, `GCP`, `Azure`.

app_service:
  enabled: true
  apps:
    - name: grafana
      uri: "http://localhost:3000"
      description: "Internal Grafana"
      labels:
        env: production
    - name: jenkins
      uri: "https://jenkins.internal:8443"
      insecure_skip_verify: true
      labels:
        env: production

`windows_desktop_service` section

The Windows Desktop Service provides browser-based RDP access to Windows machines.

windows_desktop_service — Windows RDP proxy

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Windows Desktop Service.
`listen_addr`	string	`0.0.0.0:3028`	Address for desktop proxy connections.
`ldap.addr`	string	(none)	Active Directory LDAP address (host:port).
`ldap.username`	string	(none)	Service account UPN for LDAP bind.
`ldap.domain`	string	(none)	Active Directory domain.
`ldap.insecure_skip_verify`	bool	`false`	Skip LDAP TLS verification (development only).
`discovery.base_dn`	string	(none)	Base DN for AD computer object discovery.
`discovery.filters`	list	`[]`	LDAP filters for computer object discovery.
`hosts`	list	`[]`	Statically configured Windows hosts.
`hosts[*].name`	string	(required)	Unique resource name.
`hosts[*].addr`	string	(required)	IP or hostname of the Windows machine.
`labels`	map	`{}`	Labels applied to all desktops registered by this service.

windows_desktop_service:
  enabled: true
  ldap:
    addr: "dc.example.com:636"
    username: "svc-teleport@example.com"
    domain: example.com
  discovery:
    base_dn: "CN=Computers,DC=example,DC=com"
  labels:
    env: production

Complete multi-service example

The following is a complete, working teleport.yaml that runs the Auth Service, Proxy Service, SSH Service, and Database Service on the same host:

# /etc/teleport.yaml
teleport:
  nodename: teleport-all-in-one
  data_dir: /var/lib/teleport
  log:
    output: /var/log/teleport.log
    severity: INFO
    format:
      output: json
  diag_addr: "0.0.0.0:3000"

auth_service:
  enabled: true
  listen_addr: 0.0.0.0:3025
  cluster_name: example.teleport.sh
  authentication:
    type: local
    second_factor: webauthn
    webauthn:
      rp_id: example.teleport.sh
  session_recording: node
  storage:
    type: dir                      # use SQLite for small clusters
  audit_events_uri:
    - file:///var/lib/teleport/audit/events

proxy_service:
  enabled: true
  public_addr: example.teleport.sh:443
  web_listen_addr: 0.0.0.0:443
  listen_addr: 0.0.0.0:3023
  tunnel_listen_addr: 0.0.0.0:3024
  acme:
    enabled: true
    email: ops@example.com

ssh_service:
  enabled: true
  listen_addr: 0.0.0.0:3022
  labels:
    env: production
    role: controller

db_service:
  enabled: true
  databases:
    - name: pg-prod
      protocol: postgres
      uri: "pg.internal:5432"
      labels:
        env: production

app_service:
  enabled: false

kubernetes_service:
  enabled: false

windows_desktop_service:
  enabled: false

Environment variable overrides

Every configuration field can be overridden with an environment variable using the pattern TELEPORT_<SECTION>_<FIELD> (uppercase, underscores). This is useful for secrets in containerised deployments:

# Override the auth token without storing it in the config file
export TELEPORT_AUTH_TOKEN=my-secret-token

# Override log level
export TELEPORT_LOG_SEVERITY=DEBUG

# Override the data directory
export TELEPORT_DATA_DIR=/mnt/data/teleport

In Kubernetes, store sensitive values in Secrets and mount them as environment variables rather than baking them into the teleport.yaml ConfigMap.

CLI Reference

Configuration & API

Teleport teleport.yaml Configuration File Reference

Top-level structure

`teleport` section

`auth_service` section

`proxy_service` section

`ssh_service` section

`kubernetes_service` section

`db_service` section

`app_service` section

`windows_desktop_service` section

Complete multi-service example

Environment variable overrides

Build docs developers (and LLMs) love

CLI Reference

Configuration & API

Documentation Index

​Top-level structure

​teleport section

​auth_service section

​proxy_service section

​ssh_service section

​kubernetes_service section

​db_service section

​app_service section

​windows_desktop_service section

​Complete multi-service example

​Environment variable overrides

Build docs developers (and LLMs) love

Top-level structure

`teleport` section

`auth_service` section

`proxy_service` section

`ssh_service` section

`kubernetes_service` section

`db_service` section

`app_service` section

`windows_desktop_service` section

Complete multi-service example

Environment variable overrides