Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Teleport Cloud instructions to two guides #11381

Merged
merged 3 commits into from
Apr 14, 2022
Merged

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Mar 23, 2022

See #10634

Restricted Sessions for SSH

While this already includes a compatibility note, I wanted to ensure
that users would only see information relevant to the scope they had
selected. Changes made:

  • Added a tabbed Prerequisites section

  • Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  • Misc style/grammar/clarity edits

BPF Session Recording

  • Add scoped tabs
  • Merge steps 2 and 3, which both involved examining the audit log to
    verify that Enhanced Session Recording is enabled
  • Misc style/grammar/clarity tweaks

Copy link
Contributor

@ulysseskan ulysseskan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These look good to me.

This wasn't part of the changes, but I wonder if this should be changed in any example teleport.yaml config files:

  # Replace with IP of Teleport Auth server.
  - 127.0.0.1:3025

Can't the auth_servers value also be a fully qualified domain name? So they wouldn't necessarily need to use the IP. Maybe say Replace with IP or fully qualified domain name of the Teleport Auth server.

@ptgott ptgott force-pushed the paul.gottschling/10634-1 branch from 78990ea to 8a7dc9b Compare March 25, 2022 20:43
@ptgott
Copy link
Contributor Author

ptgott commented Mar 25, 2022

@ulysseskan I've suggested using the more vague "address"

@ptgott ptgott force-pushed the paul.gottschling/10634-1 branch 2 times, most recently from 9543976 to a517feb Compare March 30, 2022 19:23

<Notice type="tip">

Our Standard Session Recording works with older Linux Kernels. View
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kernel or kernel? We use both in this doc and should probably choose one and be consistent.


```yaml
# Example config to be saved as etc/teleport.yaml
teleport:
nodename: graviton-node
auth_token: exampletoken
auth_servers:
# Replace with IP of Teleport Auth server.
# Replace with the address of the Teleport Auth Server.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to only show the config block related to enhanced recording?

For example, this field can be the auth server or the proxy server. We cover this in other documentations, and going into detail about that here would distract from enhanced recording.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the advantage of using this approach is that the user can paste everything in this snippet into the config file on the Node, make minor adjustments, and proceed to the next step, without having to navigate through the docs. The current Step 2 is incomplete, so I've fleshed it out.


The resulting enhanced session recording will be shown in [Teleport's Audit Log](../../architecture/authentication.mdx#audit-log).
If you would like to examine your audit log on the Teleport Auth Service host,
you can examine the contents of `/var/lib/teleport/log` as shown below:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: This only applies if using a file-based event log. (Not when using S3 or other cloud storage for audit events)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a Details section about this

@ptgott ptgott force-pushed the paul.gottschling/10634-1 branch from a517feb to 54c0057 Compare April 6, 2022 21:56
@ptgott ptgott requested a review from zmb3 April 6, 2022 21:56
@ptgott ptgott force-pushed the paul.gottschling/10634-1 branch 3 times, most recently from f7d3c82 to fc88777 Compare April 12, 2022 18:36
## Step 1/3. Install and configure Teleport node
(!docs/pages/includes/tctl.mdx!)

## Background
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It feels like this section is too far down on the page. Most readers aren't going to know by default what "Enhanced Session Recording" is or why they would want it.

Should we move some or all of this to the intro before the pre-requisites so we don't lose readers?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've restored the original introductory section with some light copy-edits.

Comment on lines 62 to 63
The disadvantage is that session recordings can be bypassed using several
techniques:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe reword this? The sessions are still recorded, so I'm not sure I would describe it as session recording being bypassed.

The disadvantage is really that the users true actions can be hidden or obfuscated in such a way that it's hard to determine what actually happened by watching the recording (even though the recording does accurately reflect the session).

advanced security, greater logging capabilities, and better correlates a user
with their activities.

## Step 1/2. Configure a Teleport Node
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This whole section is mostly prerequisites and not related to enhanced recording. Is the intent that every guide involving SSH nodes should include steps for installing teleport, creating a join token, and joining the cluster? Or can we just document that process in one place and have guides assume you have a node running?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to make this more like our Database Access guides (e.g., https://goteleport.com/docs/database-access/guides/mongodb-atlas/) where we include as much information as possible in a single guide so users don't need to break focus to follow the guide (https://goteleport.com/docs/contributing/documentation/style-guide/#how-to-guides).

ptgott added 3 commits April 14, 2022 12:24
See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks
- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs
Restore the introductory section with minor copy-edits.
@ptgott ptgott force-pushed the paul.gottschling/10634-1 branch from fc88777 to 0358013 Compare April 14, 2022 16:24
@ptgott ptgott enabled auto-merge (squash) April 14, 2022 16:25
@ptgott ptgott merged commit 4a08d46 into master Apr 14, 2022
@ptgott ptgott deleted the paul.gottschling/10634-1 branch April 14, 2022 16:29
ptgott added a commit that referenced this pull request Apr 14, 2022
Backports #11381

* Add Teleport Cloud instructions to two guides

See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks

* Respond to PR feedback

- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs

* Respond to PR feedback

Restore the introductory section with minor copy-edits.
ptgott added a commit that referenced this pull request Apr 14, 2022
Backports #11381

* Add Teleport Cloud instructions to two guides

See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks

* Respond to PR feedback

- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs

* Respond to PR feedback

Restore the introductory section with minor copy-edits.
ptgott added a commit that referenced this pull request Apr 15, 2022
* Add Teleport Cloud instructions to two guides

See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks

* Respond to PR feedback

- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs

* Respond to PR feedback

Restore the introductory section with minor copy-edits.
ptgott added a commit that referenced this pull request Apr 15, 2022
* Add Teleport Cloud instructions to two guides

See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks

* Respond to PR feedback

- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs

* Respond to PR feedback

Restore the introductory section with minor copy-edits.
@webvictim webvictim mentioned this pull request Apr 19, 2022
@webvictim webvictim mentioned this pull request Jun 8, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants