Skip to content

Commit

Permalink
Edit four docs guides for Cloud users (#10738)
Browse files Browse the repository at this point in the history 
See #10633

Labels

- Turn the Prerequisites into a Tabs box for different editions.
  This means that users of one edition will not need to see
  information intended for users of another edition.

- Add misc. clarity, grammar, and style edits.

Local Users

- Use Tabs for the Prerequisites so users of one edition don't see
  information for another edition
- SSO was briefly mentioned without elaboration, so I added this to a
  Further Reading section with scoped tabs
- Use Tabs for Proxy connection instructions

Troubleshooting

- Add a note re: the relevance of the guide for Cloud users
- Add Tabs for the Getting help section so commercial or OSS users
  don't see irrelevant information
- General clarity, grammar, and style tweaks

Graceful Restarts

- Add a notice indicating how this guide is relevant for Cloud users
- Misc clarity, grammar, and style tweaks
  • Loading branch information
@ptgott
ptgott authored Apr 14, 2022
1 parent b9829d1 commit d3bade5
Show file tree
Hide file tree
Showing 4 changed files with 138 additions and 64 deletions.
38 changes: 25 additions & 13 deletions docs/pages/setup/admin/graceful-restarts.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,17 @@ title: Graceful Restarts
description: Graceful restarts of Teleport.
---

<Notice scope={["cloud"]} type="tip">

These instructions apply to `teleport` processes running on Teleport Nodes. In
Teleport Cloud, the Auth and Proxy Services are monitored and managed for you.

</Notice>

## Signals

You can send signals to a Teleport daemon to get diagnostic or gracefully shut it down:
You can send signals to a `teleport` process to get diagnostic information or
gracefully shut it down:

| Signal | Teleport Daemon Behavior |
| - | - |
Expand All @@ -28,21 +36,21 @@ $ pidof teleport
235119
```

Unpack a new binary and replace a binary without stopping a server.
Preserve the old binary, just in case if the upgrade goes wrong.
Unpack a new binary and replace a binary without stopping a `teleport` process.
Preserve the old binary, just in case the upgrade goes wrong.

```code
$ mv /usr/bin/teleport /usr/bin/teleport.bak
$ cp /new/binary/teleport /usr/bin/teleport
```

Fork a new teleport process:
Fork a new `teleport` process:

```code
$ kill -USR2 $(pidof teleport)
```

The original teleport process forked a new child process and passed existing file descriptors
The original `teleport` process forked a new child process and passed existing file descriptors
to the child. You now have two processes handling requests on the same socket:

```code
Expand All @@ -53,7 +61,7 @@ $ pidof teleport
In our example, `235276` is a PID of the child process, and `235119` is a PID of the parent.

In the logs you will see that the parent process reports that it has forked a new child
process, and the child accepts file descriptors from it's parent.
process, and the child accepts file descriptors from its parent.

```txt
2021-08-19T10:16:51-07:00 [PROC:1] INFO Forked new child process. path:/usr/local/teleport service/signals.go:457
Expand Down Expand Up @@ -85,9 +93,13 @@ Examine the logs and use the system. You have two options:
type="danger"
title="WARNING"
>
If you are upgrading the Teleport using SSH connection using Teleport,
make sure to re-establish a new connection to the new teleport instance and launch shut down from it.
You can always see which node process handles the connection by using `pstree`:

If you are upgrading a `teleport` daemon using an SSH connection established
via Teleport, make sure to connect to the newly upgraded `teleport` process
and shut down the previous `teleport` process from it.

You can see which `teleport` process handles the connection by using
`pstree`:

```code
$ pstree -aps $$
Expand All @@ -105,21 +117,21 @@ Examine the logs and use the system. You have two options:
$ kill -QUIT 235119
```

The parent process will log graceful shutdown:
The parent process will log a graceful shutdown:

```txt
2021-08-19T10:32:10-07:00 INFO [PROXY:SER] Shutting down gracefully. service/service.go:2952
```

In a couple of minutes all existing connections drain off and the parent will exit:
In a couple of minutes, all existing connections drain off and the parent will exit:

```code
$ pidof teleport
# 235276
```

If for some reason, the parent process gets stuck, for example waiting on existing connections to finish,
you can shut it down non-gracefully:
If for some reason, the parent process gets stuck (e.g., waiting for
existing connections to finish), you can shut it down non-gracefully:

```code
$ kill -TERM 235119
Expand Down
60 changes: 36 additions & 24 deletions docs/pages/setup/admin/labels.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,36 @@ title: Labels
description: Labeling Nodes and Applications
---

This guide explains how to label nodes with Open Source, Enterprise Teleport,
self-hosted or cloud editions.
This guide explains how to label Teleport Nodes.

## Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

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

## Labeling Nodes and Applications
## Labeling nodes and applications

In addition to specifying a custom nodename, Teleport also allows for the
application of arbitrary key-value pairs to each node or app, called labels. There are two kinds of labels:
In addition to specifying a custom name for each Node, Teleport also allows for
the application of arbitrary key-value pairs to each Node or app, called labels.
There are two kinds of labels:

1. `static labels` do not change over time, while [`teleport`](../reference/cli.mdx#teleport) the process is running. Examples of static labels are the physical location of nodes, the name of the environment (staging vs production), etc.
2. `dynamic labels` also known as "label commands" allow to generate labels at runtime. Teleport will execute an external command on a node at a configurable frequency and the output of the command becomes the label value. Examples include reporting load averages, presence of a process, time after the last reboot, etc.
- **static labels** do not change over time while the `teleport` process is
running. Examples of static labels are the physical location of Nodes and the
name of the environment (e.g., staging vs. production).
- **dynamic labels**, also known as "label commands," allow you to generate
labels at runtime. Teleport will execute an external command on a Node at a
configurable frequency and the output of the command becomes the label value.
Examples include reporting load averages, the presence of a process, and the time after
the last reboot.

There are two ways to configure node labels.
There are two ways to configure Node labels.

1. Via command line, by using `--labels` flag to `teleport start` command.
2. Using `/etc/teleport.yaml` configuration file on the nodes.
- Via command line, by using the `--labels` flag with the `teleport start`
command.
- Using the `/etc/teleport.yaml` configuration file on a Node.

To define labels as command line arguments, use `--labels` flag like shown
To define labels as command line arguments, use the `--labels` flag as shown
below. This method works well for static labels or simple commands:

```code
Expand Down Expand Up @@ -60,8 +67,8 @@ ssh_service:
period: 1m0s
- name: arch
command: [uname, -p]
# This setting tells teleport to execute the command above
# once an hour. this value cannot be less than one minute.
# This setting tells Teleport to execute the command above
# once an hour. This value cannot be less than one minute.
period: 1h0m0s
app_service:
enabled: "yes"
Expand All @@ -73,24 +80,29 @@ app_service:
period: 1m0s
```

`/path/to/executable` must be a valid executable command (i.e. executable bit
must be set) which also includes shell scripts with a proper [shebang
line](https://en.wikipedia.org/wiki/Shebang_\(Unix\)).
Notice that the `command` setting is an array where the first element
is a valid executable and each subsequent element is an argument.

<Admonition type="tip">
Notice that `command` setting is an array where the first element
is a valid executable and each subsequent element is an argument, i.e:
This is valid syntax:

```yaml
# Valid syntax:
command: ["/bin/uname", "-m"]
```

This is invalid syntax:

# INVALID syntax:
```yaml
command: ["/bin/uname -m"]
```

# If you want to pipe several bash commands together, here's how to do it:
# notice how ' and " are interchangeable and you can use it for quoting:
If you want to pipe several bash commands together, here's how to do it. Notice
how `'` and `"` are interchangeable, so you can use them for nested quotations.

```yaml
command: ["/bin/sh", "-c", "uname -a | egrep -o '[0-9]+\\.[0-9]+\\.[0-9]+'"]
```
</Admonition>

The executable named in the `command` field must be the path to a valid
executable command. The executable permission bit must be set and shell scripts
must have a [shebang line](https://en.wikipedia.org/wiki/Shebang_\(Unix\)).

40 changes: 27 additions & 13 deletions docs/pages/setup/admin/troubleshooting.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,50 @@
title: Troubleshooting
description: Troubleshooting and Collecting Metrics of Teleport Processes
---
<Notice scope={["cloud"]} type="tip">

These instructions apply to `teleport` processes running on your own
infrastructure in order to access specific resources. In Teleport Cloud, the
Auth and Proxy Services are monitored and managed for you.

</Notice>

## Troubleshooting

To diagnose problems you can configure [`teleport`](../reference/cli.mdx#teleport) to
run with verbose logging enabled by passing it `-d` flag.
To diagnose problems you can configure the `teleport` process to run with
verbose logging enabled by passing it the `-d` flag.

<Admonition
type="tip"
title="NOTE"
<Notice
type="warning"
>
It is not recommended to run Teleport in production with verbose logging as it generates a substantial amount of data.
</Admonition>
</Notice>

Sometimes you may want to reset [`teleport`](../reference/cli.mdx#teleport) to a
clean state. This can be accomplished by erasing everything under the `data_dir`
directory, which defaults to `/var/lib/teleport/`.

## Debug dump

You can get a goroutine dump of a running process by sending it `USR1` signal.
You can get a goroutine dump of a running `teleport` process by sending it
`USR1` signal.

Locate a running teleport daemon PID:
Locate a running `teleport` daemon PID:

```code
# Locate teleport process PID
$ pidof teleport
235119
```

Send a `USR1` signal to teleport process:
Send a `USR1` signal to a `teleport` process:

```code
$ kill -USR1 $(pidof teleport)
```

Teleport will print the debug information to `stderr`. Here what you will see in the logs:
Teleport will print the debug information to `stderr`. Here what you will see in
the logs:

```txt
INFO [PROC:1] Got signal "user defined signal 1", logging diagnostic info to stderr. service/signals.go:99
Expand All @@ -52,9 +60,15 @@ runtime/pprof.writeGoroutineStacks(0x3c2ffc0, 0xc0001a8010, 0xc001011a38, 0x4bcf
```

## Getting help
<Tabs>
<TabItem scope={["cloud", "enterprise"]} label="Commercial">
If you need help, please ask on our [community forum](https://github.com/gravitational/teleport/discussions). You can also open an [issue on GitHub](https://github.com/gravitational/teleport/issues) or create a ticket through the [customer dashboard](https://dashboard.gravitational.com/web/login).

If you need help, please ask on our [community forum](https://github.com/gravitational/teleport/discussions). You can also open an [issue on Github](https://github.com/gravitational/teleport/issues).

For commercial support, you can create a ticket through the [customer dashboard](https://dashboard.gravitational.com/web/login).
</TabItem>
<TabItem scope={["oss"]} label="Open Source">
If you need help, please ask on our [community forum](https://github.com/gravitational/teleport/discussions). You can also open an [issue on GitHub](https://github.com/gravitational/teleport/issues).

For more information about custom features, or to try our [Enterprise edition](../../enterprise/introduction.mdx) of Teleport, please reach out to us at [sales](https://goteleport.com/signup/enterprise/).
</TabItem>
</Tabs>

64 changes: 50 additions & 14 deletions docs/pages/setup/admin/users.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
title: Local users
title: Local Users
description: Adding and deleting local users
---

This guide covers inviting and managing local user accounts.
This guide explains how to invite users and manage local user accounts.

## Prerequisites

Expand All @@ -15,28 +15,25 @@ This guide covers inviting and managing local user accounts.

Teleport's local user accounts are created and stored in Teleport's internal storage.

Local user accounts can be used alongside external user accounts managed using Github for the open source edition
and OIDC and SAML 2.0 for the enterprise.

A user identity in Teleport exists in the scope of a cluster.
A Teleport administrator creates Teleport user accounts and maps them to the roles they can use.

Let's look at this table:

| Teleport User | Allowed OS Logins | Description |
| - | - | - |
| joe | joe, root | Teleport user 'joe' can log in into member nodes as OS user 'joe' or 'root' |
| bob | bob | Teleport user 'bob' can log in into member nodes only as OS user 'bob' |
| ross | | If no OS login is specified, it defaults to the same name as the Teleport user - 'ross'. |
| `joe` | `joe`, `root` | Teleport user `joe` can log in into member Nodes as OS user `joe` or `root` |
| `bob` | `bob` | Teleport user `bob` can log in into member Nodes only as OS user `bob` |
| `ross` | | If no OS login is specified, it defaults to the same name as the Teleport user `ross`. |

Let's add a new user to Teleport using the [`tctl`](../reference/cli.mdx#tctl) tool:
Let's add a new user to Teleport using the `tctl` tool:

```code
$ tctl users add joe --logins=joe,root --roles=access,editor
```

Teleport generates an auto-expiring token (with a TTL of 1 hour) and prints the
token URL which must be used before the TTL expires.
token URL, which must be used before the TTL expires.

```code
# Signup token has been created. Share this URL with the user:
Expand All @@ -45,8 +42,15 @@ token URL which must be used before the TTL expires.
# NOTE: make sure the <proxy> host is accessible.
```

The user completes registration by visiting this URL in their web browser, picking a password, and configuring the 2nd-factor authentication.
If the credentials are correct, the auth server generates and signs a new certificate, and the client stores this key and will use it for subsequent logins. The key will automatically expire after 12 hours by default after which the user will need to log back in with her credentials. This TTL can be configured to a different value.
The user completes registration by visiting this URL in their web browser,
picking a password, and configuring second-factor authentication. If the
credentials are correct, the Teleport Auth Server generates and signs a new
certificate, and the client stores this key and will use it for subsequent
logins.

The key will automatically expire after 12 hours by default, after which
the user will need to log back in with their credentials. This TTL can be
configured to a different value.

Once authenticated, the account will become visible via `tctl`:

Expand All @@ -60,11 +64,25 @@ $ tctl users ls
# joe joe,root
```

Joe would then use the `tsh` client tool to log in to member node "luna" via bastion "work" *as root*:
<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
Joe can then use the `tsh` client tool to log in to the Teleport Node "luna" via
bastion "work" as `root`:

```code
$ tsh --proxy=work --user=joe root@luna
```
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Cloud">

Joe can then use the `tsh` client tool to log in to the Teleport Node "luna" via
Teleport Cloud as `root`. Joe's Teleport Cloud tenant URL is `mytenant.teleport.sh`.

```code
$ tsh --proxy=mytenant.teleport.sh --user=joe root@luna
```
</TabItem>
</Tabs>

To delete this user:

Expand All @@ -82,7 +100,7 @@ For example, to see the full list of user records, an administrator can execute:
$ tctl get users
```

To edit the user "joe":
To edit the user `joe`:

```code
# Dump the user definition into a file:
Expand All @@ -92,3 +110,21 @@ $ tctl get user/joe > joe.yaml
# Update the user record:
$ tctl create -f joe.yaml
```

## Further reading

<Tabs>
<TabItem scope={["enterprise", "cloud"]} label="Commercial">
You can configure Teleport so that users can log in using an SSO provider.
For more information, see:

- [Single Sign-On](../../enterprise/sso.mdx)
- [GitHub SSO](./github-sso.mdx)
</TabItem>
<TabItem scope={["oss"]} label="Open Source">

You can configure Teleport so that users can log in using GitHub. For more
information, see [GitHub SSO](./github-sso.mdx).

</TabItem>
</Tabs>

0 comments on commit d3bade5

Please sign in to comment.