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. tctl is supported on macOS and Linux machines.

  For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.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

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

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

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.

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.

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

tctl create -f db-impersonator.yaml

TELEPORT_USER=<your user>
tctl get user/${TELEPORT_USER?} > myuser.yaml

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

tctl create -f myuser.yaml

tctl db ls

Administrative command to list all databases registered with the cluster.

tctl db ls
tctl db ls --format=yaml

tctl get db

Prints the list of all configured database resources.

tctl get db/database-resource-name

Prints details about database-resource-name database resource.

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

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

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