2024 Secure Infrastructure Access Report: Key Insights and Trends
Oct 30
Virtual
Register Today
Teleport logoTry For Free
Fork me on GitHub

Teleport

Database Access CLI Reference

This reference shows you how to run common commands for managing Teleport the Database Service, including:

  • The teleport daemon command, which is executed on the host where you will run the Teleport Database Service.

  • The tctl administration tool, which you use to manage db resources that represent databases known to your Teleport cluster.

    To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

    For example:

    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 16.4.2

    CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

  • The tsh client tool, which end-users run in order to access databases in your cluster.

teleport db start

Starts Teleport Database Service.

teleport db start \ --token=/path/to/token \ --auth-server=proxy.example.com:3080 \ --name=example \ --protocol=postgres \ --uri=postgres.example.com:5432
teleport db start \ --token=/path/to/token \ --auth-server=mytenant.teleport.sh:443 \ --name=example \ --protocol=postgres \ --uri=postgres.mytenant.teleport.sh:5432
FlagDescription
-d/--debugEnable verbose logging to stderr.
--pid-fileFull path to the PID file. By default no PID file will be created.
--auth-serverAddress of the Teleport Proxy Service.
--tokenInvitation token to register with the Auth Service.
--ca-pinCA pin to validate the Auth Service.
-c/--configPath to a configuration file (default /etc/teleport.yaml).
--labelsComma-separated list of labels for this node, for example env=dev,app=web.
--fipsStart Teleport in FedRAMP/FIPS 140-2 mode.
--nameName of the proxied database.
--descriptionDescription of the proxied database.
--protocolProxied database protocol. Supported are: postgres and mysql.
--uriAddress the proxied database is reachable at.
--ca-certDatabase CA certificate path.
--aws-region(Only for RDS, Aurora or Redshift) AWS region RDS, Aurora or Redshift database instance is running in.
--aws-redshift-cluster-id(Only for Redshift) Redshift database cluster identifier.
--gcp-project-id(Only for Cloud SQL) GCP Cloud SQL project identifier.
--gcp-instance-id(Only for Cloud SQL) GCP Cloud SQL instance identifier.

teleport db configure create

Creates a sample Database Service configuration.

teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2
teleport db configure create \ --token=/tmp/token \ --proxy=proxy.example.com:3080 \ --name=example \ --protocol=postgres \ --uri=postgres://postgres.example.com:5432 \ --labels=env=prod
teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2
teleport db configure create \ --token=/tmp/token \ --proxy=mytenant.teleport.sh:443 \ --name=example \ --protocol=postgres \ --uri=postgres://postgres.mytenant.teleport.sh:5432 \ --labels=env=prod
FlagDescription
--proxyTeleport Proxy Service address to connect to. Default: 0.0.0.0:3080.
--tokenInvitation token to register with the Auth Service. Default: none.
--rds-discoveryList of AWS regions in which the agent will discover RDS/Aurora instances.
--rdsproxy-discoveryList of AWS regions in which the agent will discover RDS Proxies.
--redshift-discoveryList of AWS regions in which the agent will discover Redshift instances.
--redshift-serverless-discoveryList of AWS regions in which the agent will discover Redshift Serverless instances.
--elasticache-discoveryList of AWS regions in which the agent will discover ElastiCache Redis clusters.
--aws-tags(Only for AWS discoveries) Comma-separated list of AWS resource tags to match, for example env=dev,dept=it
--memorydb-discoveryList of AWS regions in which the agent will discover MemoryDB clusters.
--azure-mysql-discoveryList of Azure regions in which the agent will discover MySQL servers.
--azure-postgres-discoveryList of Azure regions in which the agent will discover Postgres servers.
--azure-redis-discoveryList of Azure regions in which the agent will discover Azure Cache For Redis servers.
--azure-subscriptionList of Azure subscription IDs for Azure discoveries. Default is "*".
--azure-resource-groupList of Azure resource groups for Azure discoveries. Default is "*".
--azure-tags(Only for Azure discoveries) Comma-separated list of Azure resource tags to match, for example env=dev,dept=it
--ca-pinCA pin to validate the Auth Service (can be repeated for multiple pins).
--nameName of the proxied database.
--protocolProxied database protocol. Refer to the configuration reference for supported values.
--uriAddress the proxied database is reachable at.
--labelsComma-separated list of labels for the database, for example env=dev,dept=it
-o/--outputWrite to stdout with --output=stdout, the default config file with --output=file, or a custom path with --output=file:///path
--dynamic-resources-labelsComma-separated list(s) of labels to match dynamic resources, for example env=dev,dept=it. Required to enable dynamic resources matching.

teleport db configure bootstrap

Bootstrap the necessary configuration for the Database Service. It reads the provided configuration to determine what will be bootstrapped.

teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser
teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole
teleport db configure bootstrap -c /etc/teleport.yaml --manual
FlagDescription
-c/--configPath to a configuration file. Default: /etc/teleport.yaml.
--manualWhen executed in "manual" mode, this command will print the instructions to complete the configuration instead of applying them directly.
--policy-nameName of the Teleport Database Service policy. Default: DatabaseAccess
--confirmDo not prompt the user and auto-confirm all actions.
--attach-to-roleRole name to attach the policy to. Mutually exclusive with --attach-to-user. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials.
--attach-to-userUser name to attach the policy to. Mutually exclusive with --attach-to-role. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials.

teleport db configure aws print-iam

Print the necessary IAM permissions required for the Database Service based on provided database types.

teleport db configure aws print-iam --types rds
teleport db configure aws print-iam --types rds,redshift --role my-db-service-role
teleport db configure aws print-iam --types redshift-serverless --assumes-roles my-access-role --policy
FlagDescription
-r/--typesComma-separated list of database types to include in the policy. Any of rds, rdsproxy, redshift, redshift-serverless, elasticache, memorydb, keyspace, dynamodb, opensearch.
--roleIAM role name to attach policy to. Mutually exclusive with --user.
--userIAM user name to attach policy to. Mutually exclusive with --role.
--[no-]policyOnly print an IAM policy document.
--[no-]boundaryOnly print an IAM boundary policy document.
--assumes-rolesComma-separated list of additional IAM roles that the IAM identity should be able to assume. Each role can be either an IAM role ARN or the name of a role in the identity's account.

tctl auth sign

When invoked with a --format=db (or --format=mongodb for MongoDB) flag, produces a CA certificate, a client certificate and a private key file used for configuring the Database Service with self-hosted database instances.

Note

For database formats, tctl must be run on an Auth Service host or the remote user must be be able to impersonate the built-in Db role and user. See the impersonation guide for details on how to allow impersonation.

tctl auth sign --format=db --host=db.example.com --out=db --ttl=2190h
tctl auth sign --format=db --host=host1,localhost,127.0.0.1 --out=db --ttl=2190h

In this example, db.example.com is the hostname where the Teleport Database Service can reach the database server. The second example assumes a database running on the same host as Teleport.

FlagDescription
--formatWhen given value db, produces secrets in database compatible format. Use mongodb when generating MongoDB secrets.
--hostComma-separated SANs to encode in the certificate. Must contain the hostname Teleport will use to connect to the database.
--outName prefix for output files.
--ttlCertificate validity period.

The tctl user must have permissions to impersonate the Teleport Database Service role, Db, in order to generate a signed database certificate. To add these impersonation privileges to your Teleport user, run the following commands.

First, define a role that can impersonate the Db user. Add the following content to a file called db-impersonator.yaml:

kind: role
version: v5
metadata:
  name: db-impersonator
spec:
  options:
  allow:
    impersonate:
      users: ['Db']
      roles: ['Db']

Create the role:

tctl create -f db-impersonator.yaml

Open your Teleport user's dynamic configuration resource in your editor so you can add the db-impersonator role:

TELEPORT_USER=<your user>
tctl edit user/${TELEPORT_USER?}

Add the db-impersonator role:

spec:
   - access
   - auditor
   - editor
+  - db-impersonator
   status:
     is_locked: false

Update your user by saving and closing the file in your editor.

Log out of your Teleport cluster and log in again. You will now be able to run tctl auth sign for database-specific certificate formats.

TTL

We recommend using a shorter TTL, but keep mind that you'll need to update the database server certificate before it expires to not lose the ability to connect. Pick the TTL value that best fits your use-case.

tctl db ls

Administrative command to list all databases registered with the cluster.

tctl db ls
tctl db ls --format=yaml
FlagDescription
--formatOutput format, one of text, yaml or json. Defaults to text.

tctl get db

Prints the list of all configured database resources.

FlagDescription
--formatOutput format, one of text, yaml or json. Defaults to yaml.

tctl get db/database-resource-name

Prints details about database-resource-name database resource.

FlagDescription
--formatOutput format, one of text, yaml or json. Defaults to yaml.

tctl rm db/database-resource-name

Removes database resource called database-resource-name.

tsh db ls

Lists available databases and their connection information.

tsh db ls

Displays only the databases a user has access to (see RBAC).

tsh db login

Retrieves database credentials.

tsh db login example
tsh db login --db-user=postgres --db-name=postgres example
FlagDescription
--db-userThe database user to log in as.
--db-nameThe database name to log in to.
--db-rolesComma-separated list of database roles to use for auto-provisioned user. If not provided, all database roles will be assigned.

If --db-user or --db-name are required, then default settings are chosen from either an active database certificate obtained via a prior use of tsh db login or from the user's allowed db_users or db_names.

The database user is always required. The database name is required for PostgreSQL, MongoDB, and Oracle databases.

tsh db logout

Removes database credentials.

tsh db logout example
tsh db logout

tsh db connect

Connect to a database using its CLI client.

Short syntax when only logged into a single database.

tsh db connect

Specify database service to connect to explicitly.

tsh db connect example

Provide database user and name to connect to.

tsh db connect --db-user=alice --db-name=db example

Select a subset of allowed database roles.

tsh db connect --db-user=alice --db-name=db --db-roles reader example
Note

Respective database CLI clients (psql, mysql, mongo or mongosh) should be available in PATH.

FlagDescription
--db-userThe database user to log in as.
--db-nameThe database name to log in to.
--db-rolesComma-separated list of database roles to use for auto-provisioned user. If not provided, all database roles will be assigned.

If --db-user or --db-name are required, then default settings are chosen from either an active database certificate obtained via a prior use of tsh db login or from the user's allowed db_users or db_names.

The database user is always required. The database name is required for PostgreSQL, MongoDB, and Oracle databases.

tsh db env

Outputs environment variables for a particular database.

tsh db env
tsh db env example
eval $(tsh db env)

tsh db config

Prints database connection information. Useful when configuring GUI clients.

tsh db config
tsh db config example
tsh db config --format=cmd example
FlagDescription
--formatOutput format: text is default, cmd to print native database client connect command.