---
title: Machine ID Configuration Reference
description: Configuration reference for Teleport Machine ID.
---

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`.

```yaml
# Debug enables verbose logging to stderr.
debug: true

# Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.
auth_server: "auth.example.com:3025" # or "example.teleport.sh:443" 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.
onboarding:
    # 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.
    ca_pins:
        - "(=presets.ca_pin=)"
        - "(=presets.ca_pin=)"

# Storage defines where Machine ID internal data is stored.
storage:
    # 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.
destinations:
    # 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.
      database:
          # 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.
      configs:
          # Requests an SSH host certificate. Requires a role granting the `create` verb on `host_cert` resources.
          - ssh_host_cert:
              principals: [my.machineid.domain.com]
          # 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 ...`:

```code
$ tbot start \
   --destination-dir=./tbot-user \
   --token=00000000000000000000000000000000 \
   --ca-pin=(=presets.ca_pin=) \
   --auth-server=auth.example.com:3025
```

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

```yaml
auth_server: auth.example.com:3025

onboarding:
    join_method: "token"
    token: "(=presets.tokens.first=)"
    ca_pins:
        - "(=presets.ca_pin=)"

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

destinations:
    - directory:
          path: ./tbot-user
```