diff --git a/docs/pages/setup/admin/graceful-restarts.mdx b/docs/pages/setup/admin/graceful-restarts.mdx index 0fef82ddaee91..b611bf5a5773e 100644 --- a/docs/pages/setup/admin/graceful-restarts.mdx +++ b/docs/pages/setup/admin/graceful-restarts.mdx @@ -3,9 +3,17 @@ title: Graceful Restarts description: Graceful restarts of Teleport. --- + + +These instructions apply to `teleport` processes running on Teleport Nodes. In +Teleport Cloud, the Auth and Proxy Services are monitored and managed for you. + + + ## 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 | | - | - | @@ -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 @@ -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 @@ -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 $$ @@ -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 diff --git a/docs/pages/setup/admin/labels.mdx b/docs/pages/setup/admin/labels.mdx index c6017465df1a3..1ff0d4c6250c7 100644 --- a/docs/pages/setup/admin/labels.mdx +++ b/docs/pages/setup/admin/labels.mdx @@ -3,8 +3,7 @@ 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 @@ -12,20 +11,28 @@ self-hosted or cloud editions. (!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 @@ -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" @@ -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. - -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]+'"] ``` - + +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\)). diff --git a/docs/pages/setup/admin/troubleshooting.mdx b/docs/pages/setup/admin/troubleshooting.mdx index a25257ebdedf4..57d9171fc735c 100644 --- a/docs/pages/setup/admin/troubleshooting.mdx +++ b/docs/pages/setup/admin/troubleshooting.mdx @@ -2,18 +2,24 @@ title: Troubleshooting description: Troubleshooting and Collecting Metrics of Teleport Processes --- + + +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. + + ## 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. - It is not recommended to run Teleport in production with verbose logging as it generates a substantial amount of data. - + 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` @@ -21,9 +27,10 @@ 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 @@ -31,13 +38,14 @@ $ 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 @@ -52,9 +60,15 @@ runtime/pprof.writeGoroutineStacks(0x3c2ffc0, 0xc0001a8010, 0xc001011a38, 0x4bcf ``` ## Getting help + + +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). + + +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/). + + + diff --git a/docs/pages/setup/admin/users.mdx b/docs/pages/setup/admin/users.mdx index 88e9b007631a1..fd232180f41a9 100644 --- a/docs/pages/setup/admin/users.mdx +++ b/docs/pages/setup/admin/users.mdx @@ -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 @@ -15,9 +15,6 @@ 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. @@ -25,18 +22,18 @@ 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: @@ -45,8 +42,15 @@ token URL which must be used before the TTL expires. # NOTE: make sure the 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`: @@ -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*: + + +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 ``` + + + +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 +``` + + To delete this user: @@ -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: @@ -92,3 +110,21 @@ $ tctl get user/joe > joe.yaml # Update the user record: $ tctl create -f joe.yaml ``` + +## Further reading + + + +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) + + + +You can configure Teleport so that users can log in using GitHub. For more +information, see [GitHub SSO](./github-sso.mdx). + + +