Fork me on GitHub
Teleport

Database Access CLI Reference

Improve

This reference shows you how to run common commands for managing Teleport Database Access, 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 connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

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

    Cluster teleport.example.com

    Version 9.3.7

    CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    You can run subsequent tctl commands in this guide on your local machine.

    For full privileges, you can also run tctl commands on your Auth Service host.

    To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

    tsh login --proxy=myinstance.teleport.sh [email protected]
    tctl status

    Cluster myinstance.teleport.sh

    Version 9.3.8

    CA pin sha256:sha-hash-here

    You must run subsequent tctl commands in this guide on your local machine.

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

teleport db start

Starts Teleport Database Service agent.

teleport db start \ --token=/path/to/token \ --auth-server=proxy.example.com:3080 \ --name=example \ --protocol=postgres \ --uri=postgres.example.com: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
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 the agent will discover for RDS/Aurora instances.
--redshift-discoveryList of AWS regions the agent will discover for Redshift instances.
--ca-pinCA pin to validate the Auth Service (can be repeated for multiple pins).
--nameName of the proxied database.
--protocolProxied database protocol. Supported are: [postgres mysql mongodb cockroachdb redis sqlserver].
--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 -o=stdout, the default config file with -o=file, or a custom path with -o=file:///path

teleport db configure bootstrap

Bootstrap the necessary configuration for the database agent. It reads the provided agent 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.

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 Database Access with self-hosted database instances.

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
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.
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-userOptionally, set default database account name to connect as.
--db-nameOptionally, set default database name to connect to.

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
Note

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

FlagDescription
--db-userOptionally, set database user name to connect as.
--db-nameOptionally, set database name to connect to.

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.