Skip to content

Latest commit

 

History

History
344 lines (264 loc) · 11.5 KB

cli.mdx

File metadata and controls

344 lines (264 loc) · 11.5 KB
Raw
title description
Database Access CLI Reference
CLI reference for Teleport Database Access.

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.

    (!docs/pages/includes/tctl.mdx!)

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

teleport db start

Starts Teleport Database Service.

<ScopedBlock scope={["oss", "enterprise"]}>

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

<ScopedBlock scope={["oss", "enterprise"]}>

$ 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
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. Supported are: [postgres mysql mongodb cockroachdb redis sqlserver snowflake].
--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 -o=stdout, the default config file with -o=file, or a custom path with -o=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 TeleportUser
$ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole
$ teleport 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.

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.

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](../../access-controls/guides/impersonation.mdx) 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
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

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

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

Edit myuser.yaml to add the db-impersonator role:

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

Update your user:

$ tctl create -f myuser.yaml

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.

(!docs/pages/includes/database-access/ttl-note.mdx!)

tctl db ls

Administrative command to list all databases registered with the cluster.

$ tctl db ls
$ tctl 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 example
$ tsh db login --db-user=postgres --db-name=postgres example
Flag Description
--db-user Optionally, set default database account name to connect as.
--db-name Optionally, 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
Respective database CLI clients (`psql`, `mysql`, `mongo` or `mongosh`) should be available in PATH.
Flag Description
--db-user Optionally, set database user name to connect as.
--db-name Optionally, 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
Flag Description
--format Output format: text is default, cmd to print native database client connect command.