Teleport
Database Access CLI Reference
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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 managedb
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 runtctl
commands using your current credentials.For example:
tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster 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 subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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
Flag | Description |
---|---|
-d/--debug | Enable verbose logging to stderr. |
--pid-file | Full path to the PID file. By default no PID file will be created. |
--auth-server | Address of the Teleport Proxy Service. |
--token | Invitation token to register with the Auth Service. |
--ca-pin | CA pin to validate the Auth Service. |
-c/--config | Path to a configuration file (default /etc/teleport.yaml ). |
--labels | Comma-separated list of labels for this node, for example env=dev,app=web . |
--fips | Start Teleport in FedRAMP/FIPS 140-2 mode. |
--name | Name of the proxied database. |
--description | Description of the proxied database. |
--protocol | Proxied database protocol. Supported are: postgres and mysql . |
--uri | Address the proxied database is reachable at. |
--ca-cert | Database 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-2teleport 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-2teleport 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
Flag | Description |
---|---|
--proxy | Teleport Proxy Service address to connect to. Default: 0.0.0.0:3080 . |
--token | Invitation token to register with the Auth Service. Default: none. |
--rds-discovery | List of AWS regions in which the agent will discover RDS/Aurora instances. |
--rdsproxy-discovery | List of AWS regions in which the agent will discover RDS Proxies. |
--redshift-discovery | List of AWS regions in which the agent will discover Redshift instances. |
--redshift-serverless-discovery | List of AWS regions in which the agent will discover Redshift Serverless instances. |
--elasticache-discovery | List 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-discovery | List of AWS regions in which the agent will discover MemoryDB clusters. |
--azure-mysql-discovery | List of Azure regions in which the agent will discover MySQL servers. |
--azure-postgres-discovery | List of Azure regions in which the agent will discover Postgres servers. |
--azure-redis-discovery | List of Azure regions in which the agent will discover Azure Cache For Redis servers. |
--azure-subscription | List of Azure subscription IDs for Azure discoveries. Default is "*". |
--azure-resource-group | List 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-pin | CA pin to validate the Auth Service (can be repeated for multiple pins). |
--name | Name of the proxied database. |
--protocol | Proxied database protocol. Refer to the configuration reference for supported values. |
--uri | Address the proxied database is reachable at. |
--labels | Comma-separated list of labels for the database, for example env=dev,dept=it |
-o/--output | Write to stdout with --output=stdout , the default config file with --output=file , or a custom path with --output=file:///path |
--dynamic-resources-labels | Comma-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 TeleportUserteleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRoleteleport db configure bootstrap -c /etc/teleport.yaml --manual
Flag | Description |
---|---|
-c/--config | Path to a configuration file. Default: /etc/teleport.yaml . |
--manual | When executed in "manual" mode, this command will print the instructions to complete the configuration instead of applying them directly. |
--policy-name | Name of the Teleport Database Service policy. Default: DatabaseAccess |
--confirm | Do not prompt the user and auto-confirm all actions. |
--attach-to-role | Role 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-user | User 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 rdsteleport db configure aws print-iam --types rds,redshift --role my-db-service-roleteleport db configure aws print-iam --types redshift-serverless --assumes-roles my-access-role --policy
Flag | Description |
---|---|
-r/--types | Comma-separated list of database types to include in the policy. Any of rds , rdsproxy , redshift , redshift-serverless , elasticache , memorydb , keyspace , dynamodb , opensearch . |
--role | IAM role name to attach policy to. Mutually exclusive with --user. |
--user | IAM user name to attach policy to. Mutually exclusive with --role. |
--[no-]policy | Only print an IAM policy document. |
--[no-]boundary | Only print an IAM boundary policy document. |
--assumes-roles | Comma-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.
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=2190htctl 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.
Flag | Description |
---|---|
--format | When given value db , produces secrets in database compatible format. Use mongodb when generating MongoDB secrets. |
--host | Comma-separated SANs to encode in the certificate. Must contain the hostname Teleport will use to connect to the database. |
--out | Name prefix for output files. |
--ttl | Certificate 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.
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 lstctl db ls --format=yaml
Flag | Description |
---|---|
--format | Output format, one of text , yaml or json . Defaults to text . |
tctl get db
Prints the list of all configured database resources.
Flag | Description |
---|---|
--format | Output format, one of text , yaml or json . Defaults to yaml . |
tctl get db/database-resource-name
Prints details about database-resource-name
database resource.
Flag | Description |
---|---|
--format | Output 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 exampletsh db login --db-user=postgres --db-name=postgres example
Flag | Description |
---|---|
--db-user | The database user to log in as. |
--db-name | The database name to log in to. |
--db-roles | Comma-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 exampletsh db logout
tsh db connect
Connect to a database using its CLI client.
Short syntax when only logged into a single database.
tsh db connectSpecify database service to connect to explicitly.
tsh db connect exampleProvide database user and name to connect to.
tsh db connect --db-user=alice --db-name=db exampleSelect a subset of allowed database roles.
tsh db connect --db-user=alice --db-name=db --db-roles reader example
Respective database CLI clients (psql
, mysql
, mongo
or mongosh
) should be
available in PATH.
Flag | Description |
---|---|
--db-user | The database user to log in as. |
--db-name | The database name to log in to. |
--db-roles | Comma-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 envtsh db env exampleeval $(tsh db env)
tsh db config
Prints database connection information. Useful when configuring GUI clients.
tsh db configtsh db config exampletsh db config --format=cmd example
Flag | Description |
---|---|
--format | Output format: text is default, cmd to print native database client connect command. |