Machine ID Configuration Reference

This reference documents the various options that can be configured in the tbot configuration file. This configuration file offers more control than configuring tbot using CLI parameters alone.

To configure tbot to use a configuration file, specify the path with the -c flag:

$ tbot -c ./tbot.yaml

In this reference, the term artifact refers an item that tbot writes to a destination as part of the process of generating an output. Examples of artifacts include configuration files, certificates, and cryptographic key material. Usually, artifacts are files, but this term is explicitly avoided because a destination isn't required to be a filesystem.

Configuration v2

From Teleport 14, tbot supports the v2 configuration version.

# version specifies the version of the configuration file in use. `v2` is the
# most recent and should be used for all new bots. The rest of this example
# is in the `v2` schema.
version: v2

# debug enables verbose logging to stderr. If unspecified, this defaults to
# false.
debug: true

# auth_server specifies the address of the Auth Service instance that `tbot` should connect
# to. You should prefer specifying `proxy_server` to specify the Proxy Service
# address.
auth_server: "teleport.example.com:3025"

# proxy_server specifies the address of the Teleport Proxy Service that `tbot` should
# connect to.
# It is recommended to use the address of your Teleport Proxy Service, or, if using
# Teleport Cloud, the address of your Teleport Cloud instance.
proxy_server: "teleport.example.com:443" # or "example.teleport.sh:443" for Teleport Cloud

# certificate_ttl specifies how long certificates generated by `tbot` should
# live for. It should be a positive, numeric value with an `m` (for minutes) or
# `h` (for hours) suffix. By default, this value is `1h`.
certificate_ttl: "1h"

# renewal_interval specifies how often `tbot` should aim to renew the
# outputs it has generated. It should be a positive, numeric value with an
# `m` (for minutes) or `h` (for hours) suffix. The default value is `20m`.
# This value must be lower than `certificate_ttl`.
# This value is ignored when using `tbot` is running in one-shot mode.
renewal_interval: "20m"

# oneshot configures `tbot` to exit immediately after generating the outputs.
# The default value is `false`. A value of `true` is useful in ephemeral environments, like
# CI/CD.
oneshot: false

# onboarding is a group of configuration options that control how `tbot` will
# authenticate with the Teleport cluster.
onboarding:
  # token specifies which join token, configured in the Teleport cluster,
  # should be used to join the Teleport cluster.
  #
  # This can also be an absolute path to a file containing the value you wish
  # to be used.
  # File path example:
  # token: /var/lib/teleport/tokenjoin
  token: "00000000000000000000000000000000"

  # join_method must be the join method associated with the specified token
  # above. This setting should match the value output when creating the bot using
  # `tctl`.
  #
  # Support values include:
  # - `token`
  # - `azure`
  # - `gcp`
  # - `circleci`
  # - `github`
  # - `gitlab`
  # - `iam`
  # - `ec2`
  # - `kubernetes`
  # - `spacelift`
  join_method: "token"

  # ca_pins are used to validate the identity of the Teleport Auth Service on
  # first connect. This should not be specified when using Teleport Cloud or
  # connecting through a Teleport Proxy.
  ca_pins:
    - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"
    - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"

  # ca_path is used to specify where a CA file can be found that can be used to
  # validate the identity of the Teleport Auth Service on first connect.
  # This should not be specified when using Teleport Cloud or connecting through a
  # Teleport Proxy. The ca_pins option should be preferred over ca_path.
  ca_path: "/path/to/ca.pem"

# storage specifies the destination that `tbot` should use to store its
# internal state. This state is sensitive, and you should ensure that the
# destination you specify here can only be accessed by `tbot`.
#
# If unspecified, storage is set to a directory destination with a path
# of `/var/lib/teleport/bot`.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
storage:
  type: directory
  path: /var/lib/teleport/bot

# outputs specifies what artifacts `tbot` should generate and renew when it
# runs.
#
# See the full list of supported outputs and their configuration options
# under the Outputs section of this reference page.
outputs:
  - type: identity
    destination:
      type: directory
      path: /opt/machine-id

If no configuration file is provided, a simple configuration is used based on the provided CLI flags. Given the following sample CLI from tctl bots add ...:

$ tbot start \
   --destination-dir=./tbot-user \
   --token=00000000000000000000000000000000 \
   --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \
   --proxy-server=example.teleport.sh:443

it uses a configuration equivalent to the following:

proxy_server: example.teleport.sh:443

onboarding:
  join_method: "token"
  token: "abcd123-insecure-do-not-use-this"
  ca_pins:
    - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"

storage:
  type: directory
  path: /var/lib/teleport/bot

outputs:
  - type: identity
    destination:
      type: directory
      path: ./tbot-user

Outputs

Outputs define what actions tbot should take when it runs. They describe the format of the certificates to be generated, the roles used to generate the certificates, and the destination where they should be written.

There are multiple types of output. Select the one that is most appropriate for your intended use-case.

identity

The identity output can be used to authenticate:

• SSH access to your Teleport servers, using tsh, openssh and tools like ansible.
• Administrative actions against your cluster using tools like tsh or tctl.
• Management of Teleport resources using the Teleport Terraform provider.
• Access to the Teleport API using the Teleport Go SDK.

See the Getting Started guide to see the identity output used in context.

# type specifies the type of the output. For the identity output, this will
# always be `identity`.
type: identity

# The following configuration fields are available across most output types.

# destination specifies where the output should write any generated artifacts
# such as certificates and configuration files.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
destination:
  type: directory
  path: /opt/machine-id
# roles specifies the roles that should be included in the certificates generated
# by the output. These roles must be roles that the bot has been granted
# permission to impersonate.
#
# if no roles are specified, all roles the bot is allowed to impersonate are used.
roles:
  - editor

application

The application output is used to generate credentials that can be used to access applications that have been configured with Teleport.

See the Machine ID with Application Access guide to see the application output used in context.

# type specifies the type of the output. For the application output, this will
# always be `application`.
type: application
# app_name specifies the application name, as configured in your Teleport
# cluster, that `tbot` should generate credentials for.
# This field must be specified.
app_name: grafana

# The following configuration fields are available across most output types.

# destination specifies where the output should write any generated artifacts
# such as certificates and configuration files.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
destination:
  type: directory
  path: /opt/machine-id
# roles specifies the roles that should be included in the certificates generated
# by the output. These roles must be roles that the bot has been granted
# permission to impersonate.
#
# if no roles are specified, all roles the bot is allowed to impersonate are used.
roles:
  - editor

database

The database output is used to generate credentials that can be used to access databases that have been configured with Teleport.

See the Machine ID with Database Access guide to see the database output used in context.

# type specifies the type of the output. For the database output, this will
# always be `database`.
type: database
# service is the name of the database server, as configured in Teleport, that
# the output should generate credentials for. This field must be specified.
service: my-postgres-server
# database is the name of the specific database on the specified database
# server to generate credentials for. This field doesn't need to be specified
# for database types that don't support multiple individual databases.
database: my-database
# username is the name of the user on the specified database server to
# generate credentials for. This field doesn't need to be specified
# for database types that don't have users.
username: my-user
# format specifies the format to use for output artifacts. If
# unspecified, a default format is used. See the table titled "Supported
# formats" below for the full list of supported values.
format: tls

# The following configuration fields are available across most output types.

# destination specifies where the output should write any generated artifacts
# such as certificates and configuration files.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
destination:
  type: directory
  path: /opt/machine-id
# roles specifies the roles that should be included in the certificates generated
# by the output. These roles must be roles that the bot has been granted
# permission to impersonate.
#
# if no roles are specified, all roles the bot is allowed to impersonate are used.
roles:
  - editor

Supported formats

You can provide the following values to the format configuration field in the database output type:

format	Description
Unspecified	Provides a certificate in tlscert, a private key in key and the CA in teleport-database-ca.crt. This is compatible with most clients and databases.
mongo	Provides mongo.crt and mongo.cas. This is designed to be used with MongoDB clients.
cockroach	Provides cockroach/node.key, cockroach/node.crt, and cockroach/ca.crt. This is designed to be used with CockroachDB clients.
tls	Provides tls.key, tls.crt, and tls.cas. This is for generic clients that require the specific file extensions.

kubernetes

The kubernetes output is used to generate credentials that can be used to access Kubernetes clusters that have been configured with Teleport.

It outputs a kubeconfig.yaml in the output destination, which can be used with kubectl.

See the Machine ID with Kubernetes Access guide to see the kubernetes output used in context.

# type specifies the type of the output. For the kubernetes output, this will
# always be `kubernetes`.
type: kubernetes
# kubernetes_cluster is the name of the Kubernetes cluster, as configured in
# Teleport, that the output should generate credentials and a kubeconfig for.
# This field must be specified.
kubernetes_cluster: my-cluster

# The following configuration fields are available across most output types.

# destination specifies where the output should write any generated artifacts
# such as certificates and configuration files.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
destination:
  type: directory
  path: /opt/machine-id
# roles specifies the roles that should be included in the certificates generated
# by the output. These roles must be roles that the bot has been granted
# permission to impersonate.
#
# if no roles are specified, all roles the bot is allowed to impersonate are used.
roles:
  - editor

ssh_host

The ssh_host output is used to generate the artifacts required to configure an OpenSSH server with Teleport in order to allow Teleport users to connect to it.

The output generates the following artifacts:

• ssh_host-cert.pub: an SSH certificate signed by the Teleport host certificate authority.
• ssh_host: the private key associated with the SSH host certificate.
• ssh_host-user-ca.pub: an export of the Teleport user certificate authority in an OpenSSH compatible format.

# type specifies the type of the output. For the ssh host output, this will
# always be `ssh_host`.
type: ssh_host
# principals is the list of host names to include in the host certificates.
# These names should match the names that clients use to connect to the host.
principals:
  - host.example.com

# The following configuration fields are available across most output types.

# destination specifies where the output should write any generated artifacts
# such as certificates and configuration files.
#
# See the full list of supported destinations and their configuration options
# under the Destinations section of this reference page.
destination:
  type: directory
  path: /opt/machine-id
# roles specifies the roles that should be included in the certificates generated
# by the output. These roles must be roles that the bot has been granted
# permission to impersonate.
#
# if no roles are specified, all roles the bot is allowed to impersonate are used.
roles:
  - editor

Services

Services are configurable long-lived components that run within tbot. Unlike Outputs, they may not necessarily generate artifacts. Typically, services provide supporting functionality for machine to machine access, for example, opening tunnels or providing APIs.

database-tunnel

The database-tunnel service opens a listener for a service that tunnels connections to a database server.

The tunnel authenticates connections for the client, meaning that any application which can connect to the listener will be able to connect to the database as the specified user. For this reason, we heavily recommend using the Unix socket listener type and configuring the permissions of the socket to ensure that only the intended applications can connect.

# type specifies the type of the service. For the database tunnel service, this
# will always be `database-tunnel`.
type: database-tunnel
# listen specifies the address that the service should listen on.
#
# Two types of listener are supported:
# - TCP: `tcp://<address>:<port>`
# - Unix socket: `unix:///<path>`
listen: tcp://127.0.0.1:25432
# service is the name of the database server, as configured in Teleport, that
# the service should open a tunnel to.
service: postgres-docker
# database is the name of the specific database on the specified database
# service.
database: postgres
# username is the name of the user on the specified database server to open a
# tunnel for.
username: postgres

Destinations

A destination is somewhere that tbot can read and write artifacts.

Destinations are used in two places in the tbot configuration:

• Specifying where tbot should store its internal state.
• Specifying where an output should write its generated artifacts.

Destinations come in multiple types. Usually, the directory type is the most appropriate.

directory

The directory destination type stores artifacts as files in a specified directory.

# type specifies the type of the destination. For the directory destination,
# this will always be `directory`.
type: directory

# path specifies the path to the directory that this destination should write
# to. This directory should already exist, or `tbot init` should be used to
# create it with the correct permissions.
path: /opt/machine-id

# symlinks configures the behaviour of symlink attack prevention.
# Requires Linux 5.6+.
# Supported values:
#   * try-secure (default): Attempt to securely read and write certificates
#     without symlinks, but fall back (with a warning) to insecure read
#     and write if the host doesn't support this.
#   * secure: Attempt to securely read and write certificates, with a hard error
#     if unsupported.
#   * insecure: Quietly allow symlinks in paths.
symlinks: try-secure
# acls configures whether Linux Access Control List (ACL) setup should occur for
# this destination.
# Requires Linux with a file system that supports ACLs.
# Supported values:
#   * try (default on Linux): Attempt to use ACLs, warn at runtime if ACLs
#     are configured but invalid.
#   * off (default on non-Linux): Do not attempt to use ACLs.
#   * required: Always use ACLs, produce a hard error at runtime if ACLs
#     are invalid.
acls: try

memory

The memory destination type stores artifacts in the process memory. When the process exits, nothing is persisted. This destination type is most suitable for ephemeral environments, but can also be used for testing.

Configuration:

# type specifies the type of the destination. For the memory destination, this
# will always be `memory`.
type: memory

kubernetes_secret

The kubernetes_secret destination type stores artifacts in a Kubernetes secret. This allows them to be mounted into other containers deployed in Kubernetes.

Prerequisites:

• tbot must be running in Kubernetes with at most one replica. If using a deployment, then the Recreate strategy must be used to ensure only one instance exists at any time. This is because multiple tbot agents configured with the same secret will compete to write to the secret and it may be left in an inconsistent state or the tbot agents may fail to write.
• The tbot pod must be configured with a service account that allows it to read and write from the configured secret.
• The POD_NAMESPACE environment variable must be configured with the name of the namespace that tbot is running in. This is best achieved with the Downward API.

There is no requirement that the secret already exists, one will be created if it does not exist. If a secret already exists, tbot will overwrite any other keys within the secret.

Configuration:

# type specifies the type of the destination. For the kubernetes_secret
# destination, this will always be `kubernetes_secret`.
type: kubernetes_secret
# name specifies the name of the Kubernetes Secret to write the artifacts to.
# This must be in the same namespace that `tbot` is running in.
name: my-secret