Skip to content

Commit

Permalink
docs: update tsh play description (#47226)
Browse files Browse the repository at this point in the history
- Improve examples
- Add new --format options
  • Loading branch information
zmb3 authored Oct 4, 2024
1 parent 4c5970e commit e1e563f
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 11 deletions.
3 changes: 2 additions & 1 deletion docs/pages/connect-your-client/tsh.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

Expand Down
26 changes: 16 additions & 10 deletions docs/pages/reference/cli/tsh.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -499,22 +499,23 @@ $ tsh mfa rm <device-name>
Plays back a prior session:

```code
$ tsh play [<flags>] <session-id>
$ tsh play [<flags>] <id-or-file>
```

### Arguments

`<session-id>`
`<id-or-file>`

- `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

Expand All @@ -526,11 +527,17 @@ Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags)
```code
$ tsh --proxy proxy.example.com play <session-id>
# 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
Expand Down Expand Up @@ -1192,4 +1199,3 @@ Only display the `tsh` binary version:
$ tsh version --client
Teleport v(=teleport.version=) git: go(=teleport.golang=)
```

0 comments on commit e1e563f

Please sign in to comment.