Fork me on GitHub


Machine ID Configuration Reference


The following snippet shows full YAML configuration of the Machine ID client tbot. Assuming the file is written to tbot.yaml, it can be used with tbot -c /etc/tbot.yaml.

# Debug enables verbose logging to stderr.
debug: true

# Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.
auth_server: "" # or "" for Teleport Cloud

# TTL of short-lived machine certificates.
certificate_ttl: "5m"

# Interval at which short-lived certificates are renewed; must be less than
# the certificate TTL.
renewal_interval: "1m"

# If set, quit after the first renewal.
oneshot: true

# Onboarding values are only used on first connect.
    # Cluster join method. Can be "token" or "iam".
    join_method: "token"

    # Token used to join the cluster. (only required for join_method: token)
    # This can also be an absolute path to a file containing the token.
    # The token can live in a temporary file that's deleted after tbot is first launched, 
    # but if tbot has to re-authenticate with the Auth Service, it will fail.
    # File path example:
    # token: /var/lib/teleport/tokenjoin
    token: "00000000000000000000000000000000"

    # CA Path used to validate the identity of the Teleport Auth Server on first connect.
    ca_path: "/path/to/ca.pem"

    # CA Pins used to validate the identity of the Teleport Auth Server on first connect.
        - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"
        - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"

# Storage defines where Machine ID internal data is stored.
    # Directory to store internal bot data. Access to this directory should be
    # limited.
    directory: /var/lib/teleport/bot
    # Alternatively, internal data can be stored in memory. "directory" and
    # "memory" are mutually exclusive. Note that the bot will not be able to
    # restart without a new token if data is only stored in memory.
    memory: true

# Destinations specifies where short-lived certificates are stored.
    # Directory specifies a filesystem directory where short-lived certificates
    # are stored.
    - directory:
          # Configure the path at which to store certificates and other
          # artifacts.
          path: /opt/machine-id

          # Configure symlink attack prevention. Requires Linux 5.6+.
          # Possible 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
          # Configure ACL use. Requires Linux with a file system that supports ACLs.
          # Possible 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
      # One or more roles to request for this destination directory from among
      # the roles granted by `tctl bots add --roles=...`
      # By default, all roles specified during `tctl bots add ...` are
      # included. A subset of these may be specified here to write short-lived
      # certificates with different roles to different directories.
      roles: [a, b, c]

      # An optional database request. The database must exist, and no other
      # special certificate requests may be present for this destination, such
      # as apps or Kubernetes clusters.
          # The name of the database server as it exists in Teleport.
          service: example-server

          # The database user to connect as.
          username: alice

          # The database on the database server to use.
          database: example

      # A list of configuration templates to generate and write to this
      # destination.
          # Requests an SSH host certificate. Requires a role granting the `create` verb on `host_cert` resources.
          - ssh_host_cert:
              principals: []
          # ssh_client generates known_hosts and an ssh_config that can be
          # included.
          - ssh_client

          # The `mongo` template outputs specially-formatted certificates for
          # MongoDB.
          - mongo

          # The `cockroach` template generates specially-named certificates
          # for use with CockroachDB.
          - cockroach

          # The `tls` template generates tls.key, tls.crt, and tls.cas for apps
          # with file naming requirements. The always-present `tlscert` is
          # usually sufficient for most apps.
          - tls

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

tbot start \ --destination-dir=./tbot-user \ --token=00000000000000000000000000000000 \ --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \

... it uses a configuration equivalent to the following:


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

    directory: /var/lib/teleport/bot

    - directory:
          path: ./tbot-user