From 64c0434527f75626e0b9d06d93f9c7fe35412ee8 Mon Sep 17 00:00:00 2001 From: Zac Bergquist Date: Fri, 4 Oct 2024 13:59:24 -0600 Subject: [PATCH] docs: update `tsh play` description - Improve examples - Add new --format options --- docs/pages/connect-your-client/tsh.mdx | 3 ++- docs/pages/reference/cli/tsh.mdx | 26 ++++++++++++++++---------- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/pages/connect-your-client/tsh.mdx b/docs/pages/connect-your-client/tsh.mdx index 74a94a0f2b11..eea0a3a42f9b 100644 --- a/docs/pages/connect-your-client/tsh.mdx +++ b/docs/pages/connect-your-client/tsh.mdx @@ -942,13 +942,14 @@ the session recording backend. This requires either a self-hosted Teleport cluster or [external audit storage](../admin-guides/management/external-audit-storage.mdx). -The `tsh play` command can print recordings in three formats, depending on the +The `tsh play` command can print recordings in several formats, depending on the kind of resource the recorded session interacts with. To choose a format, use the `--format` flag of `tsh play`: | `--format` value | Supported resources | Description | |------------------|---------------------|-------------| | `pty` (default) | Servers, Kubernetes clusters | `tsh` opens a pseudo-terminal to play each command executed in the session. | +| `text` | Servers, Kubernetes clusters | `tsh` dumps the entire recording directly to standard out. Timing data is ignored. | | `json` | Servers, Kubernetes clusters, applications, databases | `tsh` prints a JSON-serialized list of audit events, separated by newlines. | | `yaml` | Servers, Kubernetes clusters, applications, databases | `tsh` prints a YAML-serialized list of audit events, separated by `---` characters. | diff --git a/docs/pages/reference/cli/tsh.mdx b/docs/pages/reference/cli/tsh.mdx index a511d1d1702f..d5f91affbc85 100644 --- a/docs/pages/reference/cli/tsh.mdx +++ b/docs/pages/reference/cli/tsh.mdx @@ -499,22 +499,23 @@ $ tsh mfa rm Plays back a prior session: ```code -$ tsh play [] +$ tsh play [] ``` ### Arguments -`` +`` -- `session-id` The UUID of a past Teleport Session obtained by `teleport status` within - the session or from the Web UI. +- `id-or-file` The UUID of a past Teleport session, or the path to a local recording file. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | - | - | - | - | -| `--cluster` | none | a cluster_name | Specify the cluster to connect | -| `--format` | `pty` | json, pty | Format for playback | +| `--cluster` | none | a cluster_name | Specify the cluster to connect | +| `--format` | `pty` | `json`, `yaml`, `pty`, `text` | Format for playback | +| `--speed` | `1x` | `0.5x`, `1x`, `2x`, `4x`, `8x` | Playback speed | +| `--skip-idle-time` | `false` | `true, `false` | Skip idle time during playback | ### Global flags @@ -526,11 +527,17 @@ Run `tsh help ` or see the [Global Flags section](#tsh-global-flags) ```code $ tsh --proxy proxy.example.com play -# Playing back a session using pty format using a downloaded session recording. -$ tsh play --format=pty 1fe153d1-ce8b-4ef4-9908-6539457ba4ad.tar +# Playing back a session streamed from the server. +$ tsh play 1fe153d1-ce8b-4ef4-9908-6539457ba4ad -# Playing back a session in json format using jq to filter on events +# Playing back a local session in JSON format using jq to filter on events $ tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event + +# Playing back a session at 2x speed while also skipping idle time +$ tsh play --speed=2x --skip-idle-time 1fe153d1-ce8b-4ef4-9908-6539457ba4ad + +# Dump an SSH session recording to standard out, without respecting timing data. +$ tsh play --format=text 1fe153d1-ce8b-4ef4-9908-6539457ba4ad ``` ## tsh proxy app @@ -1192,4 +1199,3 @@ Only display the `tsh` binary version: $ tsh version --client Teleport v(=teleport.version=) git: go(=teleport.golang=) ``` -