From b5e0dcac37857140b6f559ab22b259ba5564389b Mon Sep 17 00:00:00 2001 From: "STeve (Xin) Huang" Date: Thu, 22 May 2025 11:13:15 -0400 Subject: [PATCH 1/2] [doc] database "multi-session" MFA --- .../guides/per-session-mfa.mdx | 27 ++++++++++ .../database-access-reference/cli.mdx | 49 ++++++++++++++++++- 2 files changed, 74 insertions(+), 2 deletions(-) diff --git a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx index d22683be7adcb..c6081cbf4ff66 100644 --- a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx @@ -199,6 +199,29 @@ $ tsh db connect prod-mysql-instance # mysql> ``` +Jerry can also execute a query against multiple databases with a single MFA check +using the `tsh db exec` command: +```code +$ tsh db exec "select 1" --labels env=prod --db-user teleport-user --output-dir=logs +Searching databases ... +Found 2 database(s): + +Name Description Protocol Labels +--------------------- ----------- -------- -------- +prod-mysql-instance-1 mysql env=prod +prod-mysql-instance-2 mysql env=prod + +Do you want to proceed with 2 database(s)? [y/N]: y +Executing command for "prod-mysql-instance-1". Output will be saved at "logs/prod-mysql-instance-1.output". +MFA is required to access Database "prod-mysql-instance-1" +Tap any security key +Detected security key tap +Executing command for "prod-mysql-instance-2". Output will be saved at "logs/prod-mysql-instance-2.output". + +Summary: 2 of 2 succeeded. +Summary is saved at "logs/summary.json". +``` + ## Limitations @@ -213,6 +236,10 @@ Current limitations for this feature are: [multi-port](../../../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports) TCP application through [VNet](../../../connect-your-client/vnet.mdx), the first connection over each port triggers an MFA check. +- For the `tsh db exec` command, only WebAuthn devices are supported. A single + MFA check can be reused for multiple connections within a `tsh db exec` + command, but only up to 5 minutes. After the 5-minutes window, a new MFA check + will be requested for new connections. ## Next steps diff --git a/docs/pages/reference/agent-services/database-access-reference/cli.mdx b/docs/pages/reference/agent-services/database-access-reference/cli.mdx index f35f791ad0c70..31886e32a7950 100644 --- a/docs/pages/reference/agent-services/database-access-reference/cli.mdx +++ b/docs/pages/reference/agent-services/database-access-reference/cli.mdx @@ -295,13 +295,28 @@ Removes database resource called `database-resource-name`. ## tsh db ls -Lists available databases and their connection information. +Lists available databases and their connection information. Displays only the +databases a user has access to (see +[RBAC](../../../enroll-resources/database-access/rbac.mdx)). ```code +# List all databases. $ tsh db ls +# Search databases with keywords. +$ tsh db ls --search foo,bar +# Filter databases with labels. +$ tsh db ls key1=value1,key2=value2 +# List databases from all clusters with extra fields. +$ tsh db ls --all -v +# Get database names using "jq". +$ tsh db ls --format json | jq -r '.[].metadata.name' ``` -Displays only the databases a user has access to (see [RBAC](../../../enroll-resources/database-access/rbac.mdx)). +| Flag | Description | +| - | - | +| `--search` | List of comma separated search keywords or phrases enclosed in quotations (e.g. `--search=foo,bar,"some phrase"`). | +| `--query` | Query by predicate language enclosed in single quotes. (e.g. `--query='labels["key1"] == "value1" && labels["key2"] != "value2"')`. | +| `--format` | Format output (`text`, `json`, `yaml`). | ## tsh db login @@ -357,6 +372,36 @@ $ tsh db connect --db-user=alice --db-name=db --db-roles reader example (!docs/pages/includes/db-user-name-flags.mdx!) +## tsh db exec + +Execute database commands on target database services. +```code +# Search databases with labels. +$ tsh db exec "source my_script.sql" --db-user mysql --labels key1=value1,key2=value2 +# Search databases with keywords. +$ tsh db exec "select 1" --db-user mysql --db-name mysql --search foo,bar +# Execute a command on specified target databases without confirmation. +$ tsh db exec "select @@hostname" --db-user mysql --dbs mydb1,mydb2,mydb3 --no-confirm +# Run commands in parallel, and save outputs to files. +$ tsh db exec "select 1" --db-user mysql --labels env=dev --parallel=5 --output-dir=exec-outputs +``` + + + Currently only PostgreSQL and MySQL databases are supported. Respective + database CLI clients (`psql`, `mysql`) 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` | List of comma separate database roles to use for auto-provisioned user. | +| `--dbs` | List of comma separated target database services. Mutually exclusive with `--search` or `--labels`. | +| `--search` | List of comma separated search keywords or phrases enclosed in quotations (e.g. `--search=foo,bar,"some phrase"`). | +| `--labels` | List of comma separated labels to filter by labels (e.g. `key1=value1,key2=value2`). | +| `--output-dir` | Directory to store command output per target database service. A summary is saved as "summary.json". | +| `--[no-]confirm` | Confirm selected database services before executing command. | + ## tsh db env Outputs environment variables for a particular database. From 513480c4db3dca16928af11f805ec4caa786f8f1 Mon Sep 17 00:00:00 2001 From: "STeve (Xin) Huang" Date: Tue, 3 Jun 2025 14:47:26 -0400 Subject: [PATCH 2/2] address feedback --- .../access-controls/guides/per-session-mfa.mdx | 8 ++++---- .../agent-services/database-access-reference/cli.mdx | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx index c6081cbf4ff66..9c3f8f6a219b6 100644 --- a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx @@ -222,6 +222,9 @@ Summary: 2 of 2 succeeded. Summary is saved at "logs/summary.json". ``` +Note that each MFA check remains valid for up to 5 minutes. After the 5-minutes +window, a new MFA check will be requested for new connections. + ## Limitations @@ -236,10 +239,7 @@ Current limitations for this feature are: [multi-port](../../../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports) TCP application through [VNet](../../../connect-your-client/vnet.mdx), the first connection over each port triggers an MFA check. -- For the `tsh db exec` command, only WebAuthn devices are supported. A single - MFA check can be reused for multiple connections within a `tsh db exec` - command, but only up to 5 minutes. After the 5-minutes window, a new MFA check - will be requested for new connections. +- For the `tsh db exec` command, only WebAuthn devices are supported. ## Next steps diff --git a/docs/pages/reference/agent-services/database-access-reference/cli.mdx b/docs/pages/reference/agent-services/database-access-reference/cli.mdx index 31886e32a7950..860aee6538f3d 100644 --- a/docs/pages/reference/agent-services/database-access-reference/cli.mdx +++ b/docs/pages/reference/agent-services/database-access-reference/cli.mdx @@ -295,9 +295,9 @@ Removes database resource called `database-resource-name`. ## tsh db ls -Lists available databases and their connection information. Displays only the -databases a user has access to (see -[RBAC](../../../enroll-resources/database-access/rbac.mdx)). +Lists the databases available to the user based on +[RBAC](../../../enroll-resources/database-access/rbac.mdx) and their connection +information. ```code # List all databases.