self-hosted/teleport
self-hosted/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport synced 2024-10-22 02:03:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fixes broken HTML and markup in docs

Browse source
This commit is contained in:
Sasha Klizhentas 2020-12-16 16:44:13 -08:00 committed by Alexander Klizhentas
parent 4fc106553f
commit 7ef78a0eff
167 changed files with 1104 additions and 661 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
docs/3.1/admin-guide.md
View file

@ -59,7 +59,8 @@ The Teleport daemon is called `teleport` and it supports the following commands:
When experimenting, you can quickly start `teleport` with verbose logging by typing
`teleport start -d`.
!!! danger "WARNING":
!!! danger "WARNING"
Teleport stores data in `/var/lib/teleport`. Make sure that regular/non-admin users do not
have access to this folder on the Auth server.
@ -91,7 +92,8 @@ will perform a graceful restart, i.e. the Teleport daemon will fork a new
process to handle new incoming requests, leaving the old daemon process running
until existing clients disconnect.
!!! warning "Version warning":
!!! warning "Version warning"
Graceful restarts only work if Teleport is deployed using network-based storage
like DynamoDB or etcd 3.3+. Future versions of Teleport will not have this limitation.
@ -194,7 +196,8 @@ Let's cover some of these flags in more detail:
Teleport uses the YAML file format for configuration. A sample configuration file is shown below. By default, it is stored in `/etc/teleport.yaml`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
When editing YAML configuration, please pay attention to how your editor
handles white space. YAML requires consistent handling of tab characters.
@ -605,12 +608,13 @@ proxy, but this will prevent you from adding more proxies without changing the
`app_id`. For multi-proxy setups, the `app_id` should be an HTTPS URL pointing to
a JSON file that mirrors `facets` in the auth config.
!!! warning "Warning":
!!! warning "Warning"
The `app_id` must never change in the lifetime of the cluster. If the App ID
changes, all existing U2F key registrations will become invalid and all users
who use U2F as the second factor will need to re-register.
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
**Logging in with U2F**
@ -632,7 +636,8 @@ Then invoke `tsh ssh` as usual to authenticate:
tsh --proxy <proxy-addr> ssh <hostname>
```
!!! tip "Version Warning":
!!! tip "Version Warning"
External user identities are only supported in [Teleport Enterprise](/enterprise/). Please reach
out to `sales@gravitational.com` for more information.
@ -860,11 +865,13 @@ teleport:
- "10.12.0.6:3025"
```
!!! warning "Warning":
!!! warning "Warning"
If a CA pin not provided, Teleport node will join a cluster but it will print
a `WARN` message (warning) into it's standard error output.
!!! warning "Warning":
!!! warning "Warning"
The CA pin becomes invalid if a Teleport administrator performs the CA
rotation by executing `tctl auth rotate`.
@ -1157,7 +1164,8 @@ ssh -o "ForwardAgent yes" \
user@host.example.com
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing all this and use the usual `ssh user@host.example.com`, users can update their
`~/.ssh/config` file. See "Using Teleport with OpenSSH" chapter for more examples.
@ -1173,7 +1181,8 @@ $ tsh login --proxy=proxy.example.com joe
$ ssh-add -L
```
!!! warning "GNOME Keyring SSH Agent":
!!! warning "GNOME Keyring SSH Agent"
It is well-known that Gnome Keyring SSH agent, used by many popular Linux
desktops like Ubuntu, does not support SSH certificates. We recommend using
the `ssh-agent` command from `openssh-client` package.
@ -1228,7 +1237,8 @@ Command | Description | Examples
`tctl rm` | Delete a resource by type/name | `tctl rm user/joe`
`tctl create` | Create a new resource from a YAML file. Use `-f` to overide / update | `tctl create -f joe.yaml`
!!! warning "YAML Format":
!!! warning "YAML Format"
By default Teleport uses [YAML format](https://en.wikipedia.org/wiki/YAML)
to describe resources. YAML is a wonderful and very human-readable
alternative to JSON or XML, but it's sensitive to white space. Pay
@ -1266,7 +1276,8 @@ spec:
name: builtin-Admin
```
!!! tip "Note":
!!! tip "Note"
Some of the fields you will see when printing resources are used only
internally and are not meant to be changed. Others are reserved for future
use.
@ -1305,6 +1316,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.
@ -1375,7 +1387,8 @@ This setup works as follows:
2. **Accessibility only works in one direction.** The "east" cluster allows users from "main" to access its nodes but users in the "east" cluster can not access the "main" cluster.
3. When a user tries to connect to a node inside "east" using main's proxy, the reverse tunnel from step 1 is used to establish this connection shown as the green line above.
!!! tip "Load Balancers":
!!! tip "Load Balancers"
The scheme above also works even if the "main" cluster uses multiple
proxies behind a load balancer (LB) or a DNS entry with multiple values.
This works by "east" establishing a tunnel to _every_ proxy in "main",
@ -1451,7 +1464,8 @@ $ tctl create cluster.yaml
At this point the users of the main cluster should be able to see "east" in the
list of available clusters.
!!! warning "HTTPS configuration":
!!! warning "HTTPS configuration"
If the `web_proxy_addr` endpoint of the main cluster uses a self-signed or
invalid HTTPS certificate, you will get an error: _"the trusted cluster
uses misconfigured HTTP/TLS certificate"_. For ease of testing the teleport
@ -1573,6 +1587,7 @@ spec:
```
!!! note
For open-source Teleport the `logins` field contains a list of allowed OS
logins. For the commercial Teleport Enterprise offering, which supports
role-based access control, the same field is treated as a list of _roles_
@ -1591,6 +1606,7 @@ $ tctl create github.yaml
```
!!! tip
When going through the Github authentication flow for the first time,
the application must be granted the access to all organizations that
are present in the "teams to logins" mapping, otherwise Teleport will
@ -1625,7 +1641,8 @@ Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
```
!!! tip "Note":
!!! tip "Note"
`localhost` and `127.0.0.1` are invalid values for the proxy host. If for
some reason your proxy runs locally, you'll need to provide some other DNS
name or a private IP address for it.
@ -1728,7 +1745,8 @@ behind `work.example.com`:
$ ssh root@database.work.example.com
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport uses OpenSSH certificates instead of keys which means you can not connect
to a Teleport node by IP address. You have to connect by DNS name. This is because
OpenSSH ensures the DNS name of the node you are connecting is listed under
@ -1786,7 +1804,8 @@ The rotation takes time, especially for hosts, because each node in a cluster
needs to be notified that a rotation is taking place and request a new
certificate for itself before the grace period ends.
!!! warning "Warning":
!!! warning "Warning"
Be careful when choosing a grace period when rotating host certificates.
The grace period needs to be long enough for all nodes in a cluster to
request a new certificate. If some nodes go offline during the rotation and
@ -1800,7 +1819,8 @@ To check the status of certificate rotation:
$ tctl status
```
!!! danger "Version Warning":
!!! danger "Version Warning"
Certificate rotation can only be used with clusters running version 2.6 of
Teleport or newer. If trusted clusters are used, make sure _all_ connected
clusters are running version 2.6+. If one of the trusted clusters is running
@ -1808,6 +1828,7 @@ $ tctl status
lost.
!!! warning "CA Pinning Warning"
If you are using [CA Pinning](#untrusted-auth-servers) when adding new nodes,
the CA pin will changes after the rotation.
@ -1926,7 +1947,8 @@ $ tsh --proxy=main.example.com login east
## High Availability
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [Cluster State section](architecture/#cluster-state)
in the Teleport Architecture documentation.
@ -1971,7 +1993,8 @@ If your load balancer supports health checks, configure it to hit the
`/webapi/ping` endpoint on the proxy. This endpoint will reply `200 OK` if the
proxy is running without problems.
!!! tip "NOTE":
!!! tip "NOTE"
As the new auth servers get added to the cluster and the old servers get decommissioned, nodes and proxies will refresh the list of available auth servers and store it in their local cache `/var/lib/teleport/authservers.json`. The values from the cache file will take precedence over the configuration
file.
@ -2021,11 +2044,13 @@ teleport:
### Using Amazon S3
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
!!! tip "AWS Authentication":
!!! tip "AWS Authentication"
The configuration examples below contain AWS access keys and secret keys. They are optional,
they exist for your convenience but we DO NOT RECOMMEND usign them in
production. If Teleport is running on an AWS instance it will automatically
@ -2059,7 +2084,8 @@ running on an EC2 instance with an IAM role.
### Using DynamoDB
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
@ -2115,7 +2141,8 @@ teleport:
* If DynamoDB is used for the audit log, the logged events will be stored with
a TTL of 1 year. Currently this TTL is not configurable.
!!! warning "Access to DynamoDB":
!!! warning "Access to DynamoDB"
Make sure that the IAM role assigned to Teleport is configured with the
sufficient access to DynamoDB. Below is the example of the IAM policy you
can use:
@ -2171,8 +2198,9 @@ When upgrading a single Teleport cluster:
in any sequence or at the same time.
3. Finally, upgrade the SSH nodes in any sequence or at the same time.
!!! warning "Warning":
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
!!! warning "Warning"
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
When upgrading multiple clusters:
@ -2211,7 +2239,8 @@ The `license_file` path can be either absolute or relative to the configured
`data_dir`. If license file path is not set, Teleport will look for the
`license.pem` file in the configured `data_dir`.
!!! tip "NOTE":
!!! tip "NOTE"
Only Auth servers require the license. Proxies and Nodes that do not also
have Auth role enabled do not need the license.
@ -2220,7 +2249,8 @@ The `license_file` path can be either absolute or relative to the configured
To diagnose problems you can configure `teleport` to run with verbose logging enabled
by passing it `-d` flag.
!!! tip "NOTE":
!!! tip "NOTE"
It is not recommended to run Teleport in production with verbose logging
as it generates a substantial amount of data.

35
docs/3.1/architecture.md
View file

@ -69,7 +69,8 @@ Teleport supports two types of user accounts:
Github, Active Directory (AD) or any identity store with an OpenID/OAuth2 or SAML endpoint.
!!! tip "Version Warning":
!!! tip "Version Warning"
SAML, OIDC and Active Directory are only supported in Teleport Enterprise. Please
take a look at the [Teleport Enterprise](enterprise.md) chapter for more information.
@ -107,8 +108,9 @@ node:
Teleport uses [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
for the two-step authentication. The password + 2nd factor are submitted to a proxy via HTTPS, therefore it is critical for a secure configuration of Teleport to install a proper HTTPS certificate on a proxy.
!!! warning "Warning":
Do not use a self-signed certificate in production!
!!! warning "Warning"
Do not use a self-signed certificate in production!
If the credentials are correct, the auth server generates and signs a new certificate and returns
it to a client via the proxy. The client stores this key and will use it for subsequent
@ -124,7 +126,8 @@ logins. The key will automatically expire after 12 hours by default. This TTL ca
If the node is located, the proxy establishes the connection between the client and the
requested node. The destination node then begins recording the session, sending the session history to the auth server to be stored.
!!! note "Note":
!!! note "Note"
Teleport may also be configured to have the session recording occur on the proxy, see [Session Recording](architecture/#session-recording) for more information.
4) When the node receives a connection request, it also checks with the auth server to validate
@ -180,7 +183,8 @@ Cluster state | `dir`, `etcd`, `dynamodb` | If multi-server (HA) configuratio
Audit Log Events | `dir`, `dynamodb` | If `dynamodb` is used for the audit log events, `s3` back-end **must** be used for the recorded sessions.
Recorded Sessions| `dir`, `s3` | `s3` is mandatory if `dynamodb` is used for the audit log.
!!! tip "Note":
!!! tip "Note"
The reason Teleport designers split the audit log events and the recorded
sessions into different back-ends is because of the nature of the data. A
recorded session is a compressed binary stream (blob) while the event is a
@ -237,7 +241,8 @@ the node and signs its certificate.
To join a cluster for the first time, a node must present a "join token" to the auth server.
The token can be static (configured via a config file) or a dynamic, single-use token.
!!! tip "NOTE":
!!! tip "NOTE"
When using dynamic tokens, their default time to live (TTL) is 15 minutes, but it can be
reduced (not increased) via `tctl` flag.
@ -254,7 +259,8 @@ discover the member nodes of the cluster.
Cluster administration is performed using `tctl` command line tool.
!!! tip "NOTE":
!!! tip "NOTE"
For high availability in production, a Teleport cluster can be serviced by multiple auth servers
running in sync. Check [HA configuration](admin-guide.md#high-availability) in the
Admin Guide.
@ -279,7 +285,8 @@ recommended to have several of them running.
When you launch the Teleport Proxy for the first time, it will generate a self-signed HTTPS
certificate to make it easier to explore Teleport.
!!! warning "Warning":
!!! warning "Warning"
It is absolutely crucial to properly configure TLS for HTTPS when you use Teleport Proxy in production.
@ -298,7 +305,8 @@ In this mode, Teleport Proxy implements WSS (secure web sockets) to SSH proxy:
4. From the SSH node's perspective, it's a regular SSH client connection that is authenticated using an
OpenSSH certificate, so no special logic is needed.
!!! tip "NOTE":
!!! tip "NOTE"
When using the web UI, Teleport Proxy terminates the traffic and re-encodes for SSH client connection.
### SSH Proxy
@ -324,7 +332,8 @@ Once the client has obtained a short lived certificate, it can use it to authent
2. Proxy dials to the target TCP address and starts forwarding the traffic to the client.
3. SSH client uses established SSH tunnel to open a new SSH connection and authenticate with the target node using its client certificate.
!!! tip "NOTE":
!!! tip "NOTE"
Teleport's proxy command makes it compatible with [SSH jump hosts](https://wiki.gentoo.org/wiki/SSH_jump_host) implemented using OpenSSH's `ProxyCommand`
@ -399,7 +408,8 @@ The Teleport auth server keeps the audit log of SSH-related events that take
place on any node with a Teleport cluster. It is important to understand that
the SSH nodes emit audit events and submit them to the auth server.
!!! warning "Compatibility Warning":
!!! warning "Compatibility Warning"
Because all SSH events like `exec` or `session_start` are reported by the
Teleport node service, they will not be logged if you are using OpenSSH
`sshd` daemon on your nodes.
@ -412,7 +422,8 @@ in the [Admin Manual](admin-guide/#audit-log).
Teleport users are encouraged to export the events into external, long term
storage.
!!! info "Deployment Considerations":
!!! info "Deployment Considerations"
If multiple Teleport auth servers are used to service the same cluster (HA mode)
a network file system must be used for `/var/lib/teleport/log` to allow them
to combine all audit events into the same audit log.

6
docs/3.1/enterprise.md
View file

@ -13,7 +13,8 @@ benefits of Teleport Enterprise.
|[Single Sign-On (SSO)](#sso)| Allows Teleport to integrate with existing enterprise identity systems. Examples include Active Directory, Github, Google Apps and numerous identity middleware solutions like Auth0, Okta, and so on. Teleport supports SAML and OAuth/OpenID Connect protocols to interact with them.
|Commercial Support | In addition to these features, Teleport Enterprise also comes with a premium support SLA with guaranteed response times.
!!! tip "Contact Information":
!!! tip "Contact Information"
If you are interested in Teleport Enterprise, please reach out to
`sales@gravitational.com` for more information.
@ -81,5 +82,6 @@ to enforce SSH access policies like _"developers must not touch production data"
See the [SSO for SSH](ssh-sso.md) chapter for more details.
!!! tip "Contact Information":
!!! tip "Contact Information"
For more information about Teleport Enterprise or Telekube please reach out us to `sales@gravitational.com` or fill out the contact for on our [website](https://gravitational.com/demo)

9
docs/3.1/kubernetes-ssh.md
View file

@ -141,7 +141,8 @@ $ kubectl exec -ti <pod-name>
The `kubectl exec` request will be routed through the Teleport proxy and
Teleport will log the audit record and record the session.
!!! note:
!!! note
For more information on integrating Teleport with Github SSO, please see the [Github section in the Admin Manual](admin-guide/#github-oauth-20).
### Okta Auth
@ -178,7 +179,8 @@ $ tctl get roles/admin > admin.yaml
$ tctl create -f admin.yaml
```
!!! tip "Advanced Usage":
!!! tip "Advanced Usage"
`{{ external.trait_name }}` example is shown to demonstrate how to fetch
the Kubernetes groups dynamically from Okta during login. In this case, you
need to define Kubernetes group membership in Okta (as a trait) and use
@ -187,5 +189,6 @@ $ tctl create -f admin.yaml
Once this is complete, when users execute `tsh login` and go through the usual Okta login
sequence, their `kubeconfig` will be updated with their Kubernetes credentials.
!!! note:
!!! note
For more information on integrating Teleport with Okta, please see the [Okta integration guide](/ssh-okta/).

3
docs/3.1/oidc.md
View file

@ -9,7 +9,8 @@ administrators to define policies like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.

4
docs/3.1/quickstart-enterprise.md
View file

@ -201,6 +201,7 @@ Pay attention to the _allow/logins_ field in the role definition: by default, th
role only allows SSH logins as `root@host`.
!!! note "Note"
Ignore `{{internal.logins}}` "allowed login" for now. It exists for
compatibility purposes when upgrading existing open source Teleport
clusters.
@ -267,7 +268,8 @@ Note that "--user=joe" part can be omitted if `$USER` environment variable is "j
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy.
Never use `--insecure` in production. You must configure the HTTP/TLS proxy certificate.

12
docs/3.1/quickstart.md
View file

@ -111,7 +111,8 @@ $ tsh --proxy=localhost --insecure login
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport must to go through a proxy, sometimes called a "bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy.
Never use `--insecure` in production. You must configure the HTTP/TLS proxy certificate.
@ -125,7 +126,8 @@ With a certificate in place, a user can SSH into any host behind the proxy:
$ tsh ssh localhost
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing "tsh ssh" a user may rename `tsh` binary to `ssh` and use the familiar syntax as in `ssh localhost`.
## Adding Nodes to Cluster
@ -155,7 +157,8 @@ localhost xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.1:3022
new-node xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.2:3022
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport also supports static pre-defined invitation tokens which can be set in the [configuration file](admin-guide.md#adding-nodes-to-the-cluster)
## Using Node Labels
@ -233,7 +236,8 @@ Also, people can join your session via terminal assuming they have Teleport inst
$ tsh --proxy=teleport.example.com join 7645d523-60cb-436d-b732-99c5df14b7c4
```
!!! tip "NOTE":
!!! tip "NOTE"
For this to work, both of you must have proper user mappings allowing you access `db` under the same OS user.
## Running in Production

9
docs/3.1/ssh-adfs.md
View file

@ -10,7 +10,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -181,11 +182,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

12
docs/3.1/ssh-okta.md
View file

@ -8,7 +8,8 @@ like:
* Only members of "DBA" group can SSH into machines running PostgreSQL.
* Developers must never SSH into production servers.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -66,7 +67,8 @@ GROUP ATTRIBUTE STATEMENTS
![Configure APP](img/okta-saml-3.png)
!!! tip "Important":
!!! tip "Important"
Notice that we have set "NameID" to the email format and mappped the groups with
a wildcard regex in the Group Attribute statements. We have also set the "Audience"
and SSO URL to the same value.
@ -176,11 +178,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

18
docs/3.1/ssh-one-login.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -33,7 +34,8 @@ section:
![Create APP](img/onelogin-saml-1.png?raw=true)
!!! tip "Important":
!!! tip "Important"
Make sure to pick `SAML Test Connector (SP)` and not `SAML Test Connector (IdP)`,
because teleport only supports `SP` - service provider initiated SAML flows.
@ -50,7 +52,8 @@ exposed as SAML attribute statements:
![Configure APP](img/onelogin-saml-3.png)
![Configure APP](img/onelogin-saml-4.png)
!!! warning "Important":
!!! warning "Important"
Make sure to check `Include in SAML assertion` checkbox.
Add users to the application:
@ -90,7 +93,8 @@ To fill in the fields, open `SSO` tab:
* `issuer` - use value from `Issuer URL field`, e.g. `https://app.onelogin.com/saml/metadata/123456`
* `sso` - use the value from the value from field `SAML 2.0 Endpoint (HTTP)` but replace `http-post` with `http-redirect`, e.g. `https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456`
!!! tip "Important":
!!! tip "Important"
Make sure to replace `http-post` with `http-redirect`!
* `cert` - download certificate, by clicking "view details link" and add to `cert` section
@ -163,11 +167,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

3
docs/3.1/ssh-rbac.md
View file

@ -198,7 +198,8 @@ spec:
'workload': ['database', 'backup']
```
!!! tip "Dynamic RBAC":
!!! tip "Dynamic RBAC"
Node labels can be dynamic, i.e. determined at runtime by an output
of an executable. In this case, you can implement "permissions follow workload"
policies (eg., any server where PostgreSQL is running becomes _automatically_

11
docs/3.1/trustedclusters.md
View file

@ -68,7 +68,8 @@ This shared secret is called a "join token". There are two ways to create join
tokens: to statically define them in a configuration file, or to create them on
the fly using `tctl` tool.
!!! tip "Important":
!!! tip "Important"
It is important to realize that join tokens are only used to establish the
connection for the first time. The clusters will exchange certificates and
won't be using the token to re-establish the connection in the future.
@ -123,7 +124,8 @@ more complicated.
## RBAC
!!! warning "Version Warning":
!!! warning "Version Warning"
The RBAC section is applicable only to Teleport Enterprise. The open source
version does not suppport SSH roles.
@ -247,9 +249,10 @@ $ tsh ssh --cluster=east root@db1.east
```
!!! tip "Note":
!!! tip "Note"
Trusted clusters work only one way. So, in the example above users from "east"
cannot see or connect to the nodes in "main".
cannot see or connect to the nodes in "main".
### Disabling Trust

6
docs/3.1/user-manual.md
View file

@ -123,7 +123,8 @@ Subsequent `tsh ssh` commands will run without asking for credentials
until the temporary certificate expires. By default, Teleport issues user
certificates with a TTL (time to live) of 12 hours.
!!! tip "Tip":
!!! tip "Tip"
It is recommended to always use `tsh login` before using any other `tsh` commands.
This allows users to omit `--proxy` flag in subsequent tsh commands. For example
`tsh ssh user@host` will work.
@ -513,7 +514,8 @@ There are a few differences between Teleport's `tsh` and OpenSSH's `ssh` but mos
use `tsh login` before `tsh ssh`, your Teleport username will be stored in
`~/.tsh`
!!! tip "Tip":
!!! tip "Tip"
To avoid typing `tsh ssh user@host` when logging into servers, you can
create a symlink `ssh -> tsh` and execute the symlink. It will behave exactly
like a standard `ssh` command, i.e. `ssh login@host`. This is helpful with other

91
docs/3.2/admin-guide.md
View file

@ -59,7 +59,8 @@ The Teleport daemon is called `teleport` and it supports the following commands:
When experimenting, you can quickly start `teleport` with verbose logging by typing
`teleport start -d`.
!!! danger "WARNING":
!!! danger "WARNING"
Teleport stores data in `/var/lib/teleport`. Make sure that regular/non-admin users do not
have access to this folder on the Auth server.
@ -91,7 +92,8 @@ will perform a graceful restart, i.e. the Teleport daemon will fork a new
process to handle new incoming requests, leaving the old daemon process running
until existing clients disconnect.
!!! warning "Version warning":
!!! warning "Version warning"
Graceful restarts only work if Teleport is deployed using network-based storage
like DynamoDB or etcd 3.3+. Future versions of Teleport will not have this limitation.
@ -194,7 +196,8 @@ Let's cover some of these flags in more detail:
Teleport uses the YAML file format for configuration. A sample configuration file is shown below. By default, it is stored in `/etc/teleport.yaml`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
When editing YAML configuration, please pay attention to how your editor
handles white space. YAML requires consistent handling of tab characters.
@ -598,12 +601,13 @@ proxy, but this will prevent you from adding more proxies without changing the
`app_id`. For multi-proxy setups, the `app_id` should be an HTTPS URL pointing to
a JSON file that mirrors `facets` in the auth config.
!!! warning "Warning":
!!! warning "Warning"
The `app_id` must never change in the lifetime of the cluster. If the App ID
changes, all existing U2F key registrations will become invalid and all users
who use U2F as the second factor will need to re-register.
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
**Logging in with U2F**
@ -625,7 +629,8 @@ Then invoke `tsh ssh` as usual to authenticate:
tsh --proxy <proxy-addr> ssh <hostname>
```
!!! tip "Version Warning":
!!! tip "Version Warning"
External user identities are only supported in [Teleport Enterprise](/enterprise/). Please reach
out to `sales@gravitational.com` for more information.
@ -853,11 +858,13 @@ teleport:
- "10.12.0.6:3025"
```
!!! warning "Warning":
!!! warning "Warning"
If a CA pin not provided, Teleport node will join a cluster but it will print
a `WARN` message (warning) into it's standard error output.
!!! warning "Warning":
!!! warning "Warning"
The CA pin becomes invalid if a Teleport administrator performs the CA
rotation by executing `tctl auth rotate`.
@ -1150,7 +1157,8 @@ ssh -o "ForwardAgent yes" \
user@host.example.com
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing all this and use the usual `ssh user@host.example.com`, users can update their
`~/.ssh/config` file. See "Using Teleport with OpenSSH" chapter for more examples.
@ -1166,7 +1174,8 @@ $ tsh login --proxy=proxy.example.com joe
$ ssh-add -L
```
!!! warning "GNOME Keyring SSH Agent":
!!! warning "GNOME Keyring SSH Agent"
It is well-known that Gnome Keyring SSH agent, used by many popular Linux
desktops like Ubuntu, does not support SSH certificates. We recommend using
the `ssh-agent` command from `openssh-client` package.
@ -1221,7 +1230,8 @@ Command | Description | Examples
`tctl rm` | Delete a resource by type/name | `tctl rm user/joe`
`tctl create` | Create a new resource from a YAML file. Use `-f` to overide / update | `tctl create -f joe.yaml`
!!! warning "YAML Format":
!!! warning "YAML Format"
By default Teleport uses [YAML format](https://en.wikipedia.org/wiki/YAML)
to describe resources. YAML is a wonderful and very human-readable
alternative to JSON or XML, but it's sensitive to white space. Pay
@ -1259,7 +1269,8 @@ spec:
name: builtin-Admin
```
!!! tip "Note":
!!! tip "Note"
Some of the fields you will see when printing resources are used only
internally and are not meant to be changed. Others are reserved for future
use.
@ -1298,6 +1309,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.
@ -1368,7 +1380,8 @@ This setup works as follows:
2. **Accessibility only works in one direction.** The "east" cluster allows users from "main" to access its nodes but users in the "east" cluster can not access the "main" cluster.
3. When a user tries to connect to a node inside "east" using main's proxy, the reverse tunnel from step 1 is used to establish this connection shown as the green line above.
!!! tip "Load Balancers":
!!! tip "Load Balancers"
The scheme above also works even if the "main" cluster uses multiple
proxies behind a load balancer (LB) or a DNS entry with multiple values.
This works by "east" establishing a tunnel to _every_ proxy in "main",
@ -1444,7 +1457,8 @@ $ tctl create cluster.yaml
At this point the users of the main cluster should be able to see "east" in the
list of available clusters.
!!! warning "HTTPS configuration":
!!! warning "HTTPS configuration"
If the `web_proxy_addr` endpoint of the main cluster uses a self-signed or
invalid HTTPS certificate, you will get an error: _"the trusted cluster
uses misconfigured HTTP/TLS certificate"_. For ease of testing the teleport
@ -1566,6 +1580,7 @@ spec:
```
!!! note
For open-source Teleport the `logins` field contains a list of allowed OS
logins. For the commercial Teleport Enterprise offering, which supports
role-based access control, the same field is treated as a list of _roles_
@ -1584,6 +1599,7 @@ $ tctl create github.yaml
```
!!! tip
When going through the Github authentication flow for the first time,
the application must be granted the access to all organizations that
are present in the "teams to logins" mapping, otherwise Teleport will
@ -1618,7 +1634,8 @@ Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
```
!!! tip "Note":
!!! tip "Note"
`localhost` and `127.0.0.1` are invalid values for the proxy host. If for
some reason your proxy runs locally, you'll need to provide some other DNS
name or a private IP address for it.
@ -1721,7 +1738,8 @@ behind `work.example.com`:
$ ssh root@database.work.example.com
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport uses OpenSSH certificates instead of keys which means you can not connect
to a Teleport node by IP address. You have to connect by DNS name. This is because
OpenSSH ensures the DNS name of the node you are connecting is listed under
@ -1779,7 +1797,8 @@ The rotation takes time, especially for hosts, because each node in a cluster
needs to be notified that a rotation is taking place and request a new
certificate for itself before the grace period ends.
!!! warning "Warning":
!!! warning "Warning"
Be careful when choosing a grace period when rotating host certificates.
The grace period needs to be long enough for all nodes in a cluster to
request a new certificate. If some nodes go offline during the rotation and
@ -1793,7 +1812,8 @@ To check the status of certificate rotation:
$ tctl status
```
!!! danger "Version Warning":
!!! danger "Version Warning"
Certificate rotation can only be used with clusters running version 2.6 of
Teleport or newer. If trusted clusters are used, make sure _all_ connected
clusters are running version 2.6+. If one of the trusted clusters is running
@ -1801,6 +1821,7 @@ $ tctl status
lost.
!!! warning "CA Pinning Warning"
If you are using [CA Pinning](#untrusted-auth-servers) when adding new nodes,
the CA pin will changes after the rotation.
@ -1922,7 +1943,8 @@ $ tsh --proxy=main.example.com login east
## High Availability
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [Cluster State section](architecture/#cluster-state)
in the Teleport Architecture documentation.
@ -1963,7 +1985,8 @@ configure your load balancer to forward the ports you specified for
for your users, while the remaining ports should do TCP level forwarding, since
Teleport will handle its own SSL on top of that with its own certificates.
!!! tip "NOTE":
!!! tip "NOTE"
If you terminate TLS with your own certificate at a load balancer you'll need
to Teleport with `--insecure`
@ -1971,7 +1994,8 @@ If your load balancer supports health checks, configure it to hit the
`/webapi/ping` endpoint on the proxy. This endpoint will reply `200 OK` if the
proxy is running without problems.
!!! tip "NOTE":
!!! tip "NOTE"
As the new auth servers get added to the cluster and the old servers get decommissioned, nodes and proxies will refresh the list of available auth servers and store it in their local cache `/var/lib/teleport/authservers.json`. The values from the cache file will take precedence over the configuration
file.
@ -2021,11 +2045,13 @@ teleport:
### Using Amazon S3
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
!!! tip "AWS Authentication":
!!! tip "AWS Authentication"
The configuration examples below contain AWS access keys and secret keys. They are optional,
they exist for your convenience but we DO NOT RECOMMEND usign them in
production. If Teleport is running on an AWS instance it will automatically
@ -2059,7 +2085,8 @@ running on an EC2 instance with an IAM role.
### Using DynamoDB
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
@ -2115,7 +2142,8 @@ teleport:
* If DynamoDB is used for the audit log, the logged events will be stored with
a TTL of 1 year. Currently this TTL is not configurable.
!!! warning "Access to DynamoDB":
!!! warning "Access to DynamoDB"
Make sure that the IAM role assigned to Teleport is configured with the
sufficient access to DynamoDB. Below is the example of the IAM policy you
can use:
@ -2171,8 +2199,9 @@ When upgrading a single Teleport cluster:
in any sequence or at the same time.
3. Finally, upgrade the SSH nodes in any sequence or at the same time.
!!! warning "Warning":
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
!!! warning "Warning"
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
When upgrading multiple clusters:
@ -2211,7 +2240,8 @@ The `license_file` path can be either absolute or relative to the configured
`data_dir`. If license file path is not set, Teleport will look for the
`license.pem` file in the configured `data_dir`.
!!! tip "NOTE":
!!! tip "NOTE"
Only Auth servers require the license. Proxies and Nodes that do not also
have Auth role enabled do not need the license.
@ -2220,7 +2250,8 @@ The `license_file` path can be either absolute or relative to the configured
To diagnose problems you can configure `teleport` to run with verbose logging enabled
by passing it `-d` flag.
!!! tip "NOTE":
!!! tip "NOTE"
It is not recommended to run Teleport in production with verbose logging
as it generates a substantial amount of data.

33
docs/3.2/architecture.md
View file

@ -69,7 +69,8 @@ Teleport supports two types of user accounts:
Github, Active Directory (AD) or any identity store with an OpenID/OAuth2 or SAML endpoint.
!!! tip "Version Warning":
!!! tip "Version Warning"
SAML, OIDC and Active Directory are only supported in Teleport Enterprise. Please
take a look at the [Teleport Enterprise](enterprise.md) chapter for more information.
@ -107,7 +108,8 @@ node:
Teleport uses [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
for the two-step authentication. The password + 2nd factor are submitted to a proxy via HTTPS, therefore it is critical for a secure configuration of Teleport to install a proper HTTPS certificate on a proxy.
!!! warning "Warning":
!!! warning "Warning"
Do not use a self-signed certificate in production!
If the credentials are correct, the auth server generates and signs a new certificate and returns
@ -124,7 +126,8 @@ logins. The key will automatically expire after 12 hours by default. This TTL ca
If the node is located, the proxy establishes the connection between the client and the
requested node. The destination node then begins recording the session, sending the session history to the auth server to be stored.
!!! note "Note":
!!! note "Note"
Teleport may also be configured to have the session recording occur on the proxy, see [Session Recording](architecture/#session-recording) for more information.
4) When the node receives a connection request, it also checks with the auth server to validate
@ -180,7 +183,8 @@ Cluster state | `dir`, `etcd`, `dynamodb` | If multi-server (HA) configuratio
Audit Log Events | `dir`, `dynamodb` | If `dynamodb` is used for the audit log events, `s3` back-end **must** be used for the recorded sessions.
Recorded Sessions| `dir`, `s3` | `s3` is mandatory if `dynamodb` is used for the audit log.
!!! tip "Note":
!!! tip "Note"
The reason Teleport designers split the audit log events and the recorded
sessions into different back-ends is because of the nature of the data. A
recorded session is a compressed binary stream (blob) while the event is a
@ -237,7 +241,8 @@ the node and signs its certificate.
To join a cluster for the first time, a node must present a "join token" to the auth server.
The token can be static (configured via a config file) or a dynamic, single-use token.
!!! tip "NOTE":
!!! tip "NOTE"
When using dynamic tokens, their default time to live (TTL) is 15 minutes, but it can be
reduced (not increased) via `tctl` flag.
@ -254,7 +259,8 @@ discover the member nodes of the cluster.
Cluster administration is performed using `tctl` command line tool.
!!! tip "NOTE":
!!! tip "NOTE"
For high availability in production, a Teleport cluster can be serviced by multiple auth servers
running in sync. Check [HA configuration](admin-guide.md#high-availability) in the
Admin Guide.
@ -279,7 +285,8 @@ recommended to have several of them running.
When you launch the Teleport Proxy for the first time, it will generate a self-signed HTTPS
certificate to make it easier to explore Teleport.
!!! warning "Warning":
!!! warning "Warning"
It is absolutely crucial to properly configure TLS for HTTPS when you use Teleport Proxy in production.
@ -298,7 +305,8 @@ In this mode, Teleport Proxy implements WSS (secure web sockets) to SSH proxy:
4. From the SSH node's perspective, it's a regular SSH client connection that is authenticated using an
OpenSSH certificate, so no special logic is needed.
!!! tip "NOTE":
!!! tip "NOTE"
When using the web UI, Teleport Proxy terminates the traffic and re-encodes for SSH client connection.
### SSH Proxy
@ -324,7 +332,8 @@ Once the client has obtained a short lived certificate, it can use it to authent
2. Proxy dials to the target TCP address and starts forwarding the traffic to the client.
3. SSH client uses established SSH tunnel to open a new SSH connection and authenticate with the target node using its client certificate.
!!! tip "NOTE":
!!! tip "NOTE"
Teleport's proxy command makes it compatible with [SSH jump hosts](https://wiki.gentoo.org/wiki/SSH_jump_host) implemented using OpenSSH's `ProxyCommand`
@ -399,7 +408,8 @@ The Teleport auth server keeps the audit log of SSH-related events that take
place on any node with a Teleport cluster. It is important to understand that
the SSH nodes emit audit events and submit them to the auth server.
!!! warning "Compatibility Warning":
!!! warning "Compatibility Warning"
Because all SSH events like `exec` or `session_start` are reported by the
Teleport node service, they will not be logged if you are using OpenSSH
`sshd` daemon on your nodes.
@ -412,7 +422,8 @@ in the [Admin Manual](admin-guide/#audit-log).
Teleport users are encouraged to export the events into external, long term
storage.
!!! info "Deployment Considerations":
!!! info "Deployment Considerations"
If multiple Teleport auth servers are used to service the same cluster (HA mode)
a network file system must be used for `/var/lib/teleport/log` to allow them
to combine all audit events into the same audit log.

6
docs/3.2/enterprise.md
View file

@ -13,7 +13,8 @@ benefits of Teleport Enterprise.
|[Single Sign-On (SSO)](#sso)| Allows Teleport to integrate with existing enterprise identity systems. Examples include Active Directory, Github, Google Apps and numerous identity middleware solutions like Auth0, Okta, and so on. Teleport supports SAML and OAuth/OpenID Connect protocols to interact with them.
|Commercial Support | In addition to these features, Teleport Enterprise also comes with a premium support SLA with guaranteed response times.
!!! tip "Contact Information":
!!! tip "Contact Information"
If you are interested in Teleport Enterprise, please reach out to
`sales@gravitational.com` for more information.
@ -81,5 +82,6 @@ to enforce SSH access policies like _"developers must not touch production data"
See the [SSO for SSH](ssh-sso.md) chapter for more details.
!!! tip "Contact Information":
!!! tip "Contact Information"
For more information about Teleport Enterprise or Telekube please reach out us to `sales@gravitational.com` or fill out the contact for on our [website](https://gravitational.com/demo)

9
docs/3.2/kubernetes-ssh.md
View file

@ -175,7 +175,8 @@ $ kubectl exec -ti <pod-name>
The `kubectl exec` request will be routed through the Teleport proxy and
Teleport will log the audit record and record the session.
!!! note:
!!! note
For more information on integrating Teleport with Github SSO, please see the [Github section in the Admin Manual](admin-guide/#github-oauth-20).
### Okta Auth
@ -212,7 +213,8 @@ $ tctl get roles/admin > admin.yaml
$ tctl create -f admin.yaml
```
!!! tip "Advanced Usage":
!!! tip "Advanced Usage"
`{{ external.trait_name }}` example is shown to demonstrate how to fetch
the Kubernetes groups dynamically from Okta during login. In this case, you
need to define Kubernetes group membership in Okta (as a trait) and use
@ -221,5 +223,6 @@ $ tctl create -f admin.yaml
Once this is complete, when users execute `tsh login` and go through the usual Okta login
sequence, their `kubeconfig` will be updated with their Kubernetes credentials.
!!! note:
!!! note
For more information on integrating Teleport with Okta, please see the [Okta integration guide](/ssh-okta/).

3
docs/3.2/oidc.md
View file

@ -9,7 +9,8 @@ administrators to define policies like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.

4
docs/3.2/quickstart-enterprise.md
View file

@ -201,6 +201,7 @@ Pay attention to the _allow/logins_ field in the role definition: by default, th
role only allows SSH logins as `root@host`.
!!! note "Note"
Ignore `{{internal.logins}}` "allowed login" for now. It exists for
compatibility purposes when upgrading existing open source Teleport
clusters.
@ -267,7 +268,8 @@ Note that "--user=joe" part can be omitted if `$USER` environment variable is "j
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy.
Never use `--insecure` in production. You must configure the HTTP/TLS proxy certificate.

12
docs/3.2/quickstart.md
View file

@ -111,7 +111,8 @@ $ tsh --proxy=localhost --insecure login
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport must to go through a proxy, sometimes called a "bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy.
Never use `--insecure` in production. You must configure the HTTP/TLS proxy certificate.
@ -125,7 +126,8 @@ With a certificate in place, a user can SSH into any host behind the proxy:
$ tsh ssh localhost
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing "tsh ssh" a user may rename `tsh` binary to `ssh` and use the familiar syntax as in `ssh localhost`.
## Adding Nodes to Cluster
@ -155,7 +157,8 @@ localhost xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.1:3022
new-node xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.2:3022
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport also supports static pre-defined invitation tokens which can be set in the [configuration file](admin-guide.md#adding-nodes-to-the-cluster)
## Using Node Labels
@ -233,7 +236,8 @@ Also, people can join your session via terminal assuming they have Teleport inst
$ tsh --proxy=teleport.example.com join 7645d523-60cb-436d-b732-99c5df14b7c4
```
!!! tip "NOTE":
!!! tip "NOTE"
For this to work, both of you must have proper user mappings allowing you access `db` under the same OS user.
## Running in Production

9
docs/3.2/ssh-adfs.md
View file

@ -10,7 +10,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -181,11 +182,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

9
docs/3.2/ssh-okta.md
View file

@ -8,7 +8,8 @@ like:
* Only members of "DBA" group can SSH into machines running PostgreSQL.
* Developers must never SSH into production servers.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -176,11 +177,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

18
docs/3.2/ssh-one-login.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -33,7 +34,8 @@ section:
![Create APP](img/onelogin-saml-1.png?raw=true)
!!! tip "Important":
!!! tip "Important"
Make sure to pick `SAML Test Connector (SP)` and not `SAML Test Connector (IdP)`,
because teleport only supports `SP` - service provider initiated SAML flows.
@ -50,7 +52,8 @@ exposed as SAML attribute statements:
![Configure APP](img/onelogin-saml-3.png)
![Configure APP](img/onelogin-saml-4.png)
!!! warning "Important":
!!! warning "Important"
Make sure to check `Include in SAML assertion` checkbox.
Add users to the application:
@ -90,7 +93,8 @@ To fill in the fields, open `SSO` tab:
* `issuer` - use value from `Issuer URL field`, e.g. `https://app.onelogin.com/saml/metadata/123456`
* `sso` - use the value from the value from field `SAML 2.0 Endpoint (HTTP)` but replace `http-post` with `http-redirect`, e.g. `https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456`
!!! tip "Important":
!!! tip "Important"
Make sure to replace `http-post` with `http-redirect`!
* `cert` - download certificate, by clicking "view details link" and add to `cert` section
@ -163,11 +167,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

3
docs/3.2/ssh-rbac.md
View file

@ -215,7 +215,8 @@ spec:
'workload': ['database', 'backup']
```
!!! tip "Dynamic RBAC":
!!! tip "Dynamic RBAC"
Node labels can be dynamic, i.e. determined at runtime by an output
of an executable. In this case, you can implement "permissions follow workload"
policies (eg., any server where PostgreSQL is running becomes _automatically_

16
docs/3.2/trustedclusters.md
View file

@ -77,8 +77,9 @@ auth_service:
# certificates and keys (may need to wipe out /var/lib/teleport directory)
cluster_name: "production-aws"
```
!!! warning "Warning":
If you change cluster_name, it will invalidate all generated
!!! warning "Warning"
If you change cluster_name, it will invalidate all generated
certificates and keys (may need to wipe out /var/lib/teleport directory)
Once set you'll be able to see the cluster name in the Teleport UI.
@ -101,7 +102,8 @@ This shared secret is called a "join token". There are two ways to create join
tokens: to statically define them in a configuration file, or to create them on
the fly using `tctl` tool.
!!! tip "Important":
!!! tip "Important"
It is important to realize that join tokens are only used to establish the
connection for the first time. The clusters will exchange certificates and
won't be using the token to re-establish the connection in the future.
@ -156,7 +158,8 @@ more complicated.
## RBAC
!!! warning "Version Warning":
!!! warning "Version Warning"
The RBAC section is applicable only to Teleport Enterprise. The open source
version does not suppport SSH roles.
@ -280,9 +283,10 @@ $ tsh ssh --cluster=east root@db1.east
```
!!! tip "Note":
!!! tip "Note"
Trusted clusters work only one way. So, in the example above users from "east"
cannot see or connect to the nodes in "main".
cannot see or connect to the nodes in "main".
### Disabling Trust

6
docs/3.2/user-manual.md
View file

@ -123,7 +123,8 @@ Subsequent `tsh ssh` commands will run without asking for credentials
until the temporary certificate expires. By default, Teleport issues user
certificates with a TTL (time to live) of 12 hours.
!!! tip "Tip":
!!! tip "Tip"
It is recommended to always use `tsh login` before using any other `tsh` commands.
This allows users to omit `--proxy` flag in subsequent tsh commands. For example
`tsh ssh user@host` will work.
@ -513,7 +514,8 @@ There are a few differences between Teleport's `tsh` and OpenSSH's `ssh` but mos
use `tsh login` before `tsh ssh`, your Teleport username will be stored in
`~/.tsh`
!!! tip "Tip":
!!! tip "Tip"
To avoid typing `tsh ssh user@host` when logging into servers, you can
create a symlink `ssh -> tsh` and execute the symlink. It will behave exactly
like a standard `ssh` command, i.e. `ssh login@host`. This is helpful with other

98
docs/4.0/admin-guide.md
View file

@ -89,7 +89,8 @@ The Teleport daemon is called `teleport` and it supports the following commands:
When experimenting, you can quickly start `teleport` with verbose logging by typing
`teleport start -d`.
!!! danger "WARNING":
!!! danger "WARNING"
Teleport stores data in `/var/lib/teleport`. Make sure that regular/non-admin users do not
have access to this folder on the Auth server.
@ -121,7 +122,8 @@ will perform a graceful restart, i.e. the Teleport daemon will fork a new
process to handle new incoming requests, leaving the old daemon process running
until existing clients disconnect.
!!! warning "Version warning":
!!! warning "Version warning"
Graceful restarts only work if Teleport is deployed using network-based storage
like DynamoDB or etcd 3.3+. Future versions of Teleport will not have this limitation.
@ -230,7 +232,8 @@ Let's cover some of these flags in more detail:
Teleport uses the YAML file format for configuration. A sample configuration file is shown below. By default, it is stored in `/etc/teleport.yaml`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
When editing YAML configuration, please pay attention to how your editor
handles white space. YAML requires consistent handling of tab characters.
@ -634,12 +637,13 @@ proxy, but this will prevent you from adding more proxies without changing the
`app_id`. For multi-proxy setups, the `app_id` should be an HTTPS URL pointing to
a JSON file that mirrors `facets` in the auth config.
!!! warning "Warning":
!!! warning "Warning"
The `app_id` must never change in the lifetime of the cluster. If the App ID
changes, all existing U2F key registrations will become invalid and all users
who use U2F as the second factor will need to re-register.
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
When adding a new proxy server, make sure to add it to the list of "facets"
in the configuration file, but also to the JSON file referenced by `app_id`
**Logging in with U2F**
@ -661,7 +665,8 @@ Then invoke `tsh ssh` as usual to authenticate:
tsh --proxy <proxy-addr> ssh <hostname>
```
!!! tip "Version Warning":
!!! tip "Version Warning"
External user identities are only supported in [Teleport Enterprise](/enterprise/). Please reach
out to `sales@gravitational.com` for more information.
@ -892,7 +897,8 @@ teleport:
- "10.12.0.6:3025"
```
!!! warning "Warning":
!!! warning "Warning"
If a CA pin not provided, Teleport node will join a cluster but it will print
a `WARN` message (warning) into it's standard error output.
@ -1189,7 +1195,8 @@ ssh -o "ForwardAgent yes" \
user@host.example.com
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing all this and use the usual `ssh user@host.example.com`, users can update their
`~/.ssh/config` file. See "Using Teleport with OpenSSH" chapter for more examples.
@ -1205,7 +1212,8 @@ $ tsh login --proxy=proxy.example.com joe
$ ssh-add -L
```
!!! warning "GNOME Keyring SSH Agent":
!!! warning "GNOME Keyring SSH Agent"
It is well-known that Gnome Keyring SSH agent, used by many popular Linux
desktops like Ubuntu, does not support SSH certificates. We recommend using
the `ssh-agent` command from `openssh-client` package.
@ -1260,7 +1268,8 @@ Command | Description | Examples
`tctl rm` | Delete a resource by type/name | `tctl rm user/joe`
`tctl create` | Create a new resource from a YAML file. Use `-f` to override / update | `tctl create -f joe.yaml`
!!! warning "YAML Format":
!!! warning "YAML Format"
By default Teleport uses [YAML format](https://en.wikipedia.org/wiki/YAML)
to describe resources. YAML is a wonderful and very human-readable
alternative to JSON or XML, but it's sensitive to white space. Pay
@ -1298,7 +1307,8 @@ spec:
name: builtin-Admin
```
!!! tip "Note":
!!! tip "Note"
Some of the fields you will see when printing resources are used only
internally and are not meant to be changed. Others are reserved for future
use.
@ -1337,6 +1347,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.
@ -1407,7 +1418,8 @@ This setup works as follows:
2. **Accessibility only works in one direction.** The "east" cluster allows users from "main" to access its nodes but users in the "east" cluster can not access the "main" cluster.
3. When a user tries to connect to a node inside "east" using main's proxy, the reverse tunnel from step 1 is used to establish this connection shown as the green line above.
!!! tip "Load Balancers":
!!! tip "Load Balancers"
The scheme above also works even if the "main" cluster uses multiple
proxies behind a load balancer (LB) or a DNS entry with multiple values.
This works by "east" establishing a tunnel to _every_ proxy in "main",
@ -1483,7 +1495,8 @@ $ tctl create cluster.yaml
At this point the users of the main cluster should be able to see "east" in the
list of available clusters.
!!! warning "HTTPS configuration":
!!! warning "HTTPS configuration"
If the `web_proxy_addr` endpoint of the main cluster uses a self-signed or
invalid HTTPS certificate, you will get an error: _"the trusted cluster
uses misconfigured HTTP/TLS certificate"_. For ease of testing the teleport
@ -1605,6 +1618,7 @@ spec:
```
!!! note
For open-source Teleport the `logins` field contains a list of allowed OS
logins. For the commercial Teleport Enterprise offering, which supports
role-based access control, the same field is treated as a list of _roles_
@ -1623,6 +1637,7 @@ $ tctl create github.yaml
```
!!! tip
When going through the Github authentication flow for the first time,
the application must be granted the access to all organizations that
are present in the "teams to logins" mapping, otherwise Teleport will
@ -1657,7 +1672,8 @@ Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
```
!!! tip "Note":
!!! tip "Note"
`localhost` and `127.0.0.1` are invalid values for the proxy host. If for
some reason your proxy runs locally, you'll need to provide some other DNS
name or a private IP address for it.
@ -1712,9 +1728,10 @@ $ cat cluster_node_keys
@cert-authority *.graviton-auth ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDLNduBoHQaqi+kgkq3gLYjc6JIyBBnCFLgm63b5rtmWl/CJD7T9HWHxZphaS1jra6CWdboLeTp6sDUIKZ/Qw1MKFlfoqZZ8k6to43bxx7DvAHs0Te4WpuS/YRmWFhb6mMVOa8Rd4/9jE+c0f9O/t7X4m5iR7Fp7Tt+R/pjJfr03Loi6TYP/61AgXD/BkVDf+IcU4+9nknl+kaVPSGcPS9/Vbni1208Q+VN7B7Umy71gCh02gfv3rBGRgjT/cRAivuVoH/z3n5UwWg+9R3GD/l+XZKgv+pfe3OHoyDFxYKs9JaX0+GWc504y3Grhos12Lb8sNmMngxxxQ/KUDOV9z+R type=host
```
!!! tip "Note":
When sharing the @cert-authority make sure that the URL for the proxy is correct.
In the above example, `*.graviton-auth` should be changed to teleport.example.com.
!!! tip "Note"
When sharing the @cert-authority make sure that the URL for the proxy is correct.
In the above example, `*.graviton-auth` should be changed to teleport.example.com.
On your client machine, you need to import these keys. It will allow your OpenSSH client
to verify that host's certificates are signed by the trusted CA key:
@ -1769,7 +1786,8 @@ behind `work.example.com`:
$ ssh root@database.work.example.com
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport uses OpenSSH certificates instead of keys which means you can not connect
to a Teleport node by IP address. You have to connect by DNS name. This is because
OpenSSH ensures the DNS name of the node you are connecting is listed under
@ -1827,7 +1845,8 @@ The rotation takes time, especially for hosts, because each node in a cluster
needs to be notified that a rotation is taking place and request a new
certificate for itself before the grace period ends.
!!! warning "Warning":
!!! warning "Warning"
Be careful when choosing a grace period when rotating host certificates.
The grace period needs to be long enough for all nodes in a cluster to
request a new certificate. If some nodes go offline during the rotation and
@ -1841,7 +1860,8 @@ To check the status of certificate rotation:
$ tctl status
```
!!! danger "Version Warning":
!!! danger "Version Warning"
Certificate rotation can only be used with clusters running version 2.6 of
Teleport or newer. If trusted clusters are used, make sure _all_ connected
clusters are running version 2.6+. If one of the trusted clusters is running
@ -1849,6 +1869,7 @@ $ tctl status
lost.
!!! warning "CA Pinning Warning"
If you are using [CA Pinning](#untrusted-auth-servers) when adding new nodes,
the CA pin will changes after the rotation.
@ -1970,7 +1991,8 @@ $ tsh --proxy=main.example.com login east
## High Availability
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [Cluster State section](architecture/#cluster-state)
in the Teleport Architecture documentation.
@ -2011,7 +2033,8 @@ configure your load balancer to forward the ports you specified for
for your users, while the remaining ports should do TCP level forwarding, since
Teleport will handle its own SSL on top of that with its own certificates.
!!! tip "NOTE":
!!! tip "NOTE"
If you terminate TLS with your own certificate at a load balancer you'll need
to Teleport with `--insecure`
@ -2019,7 +2042,8 @@ If your load balancer supports health checks, configure it to hit the
`/webapi/ping` endpoint on the proxy. This endpoint will reply `200 OK` if the
proxy is running without problems.
!!! tip "NOTE":
!!! tip "NOTE"
As the new auth servers get added to the cluster and the old servers get decommissioned, nodes and proxies will refresh the list of available auth servers and store it in their local cache `/var/lib/teleport/authservers.json`. The values from the cache file will take precedence over the configuration
file.
@ -2069,11 +2093,13 @@ teleport:
### Using Amazon S3
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
!!! tip "AWS Authentication":
!!! tip "AWS Authentication"
The configuration examples below contain AWS access keys and secret keys. They are optional,
they exist for your convenience but we DO NOT RECOMMEND using them in
production. If Teleport is running on an AWS instance it will automatically
@ -2107,7 +2133,8 @@ running on an EC2 instance with an IAM role.
### Using DynamoDB
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the [cluster state section](architecture/#cluster-state)
in Teleport Architecture documentation.
@ -2163,7 +2190,8 @@ teleport:
* If DynamoDB is used for the audit log, the logged events will be stored with
a TTL of 1 year. Currently this TTL is not configurable.
!!! warning "Access to DynamoDB":
!!! warning "Access to DynamoDB"
Make sure that the IAM role assigned to Teleport is configured with the
sufficient access to DynamoDB. Below is the example of the IAM policy you
can use:
@ -2215,7 +2243,8 @@ clients, etc), the following rules apply:
* Teleport clients (`tsh` for users and `tctl` for admins) may not be compatible if older than the auth or the proxy server. They will print an error if there is an incompatibility.
* While 4.0 is a major release. 3.2 can be upgraded to 4.0 using the same upgrade sequence below.
!!! warning "Upgrading to Teleport 4.0+":
!!! warning "Upgrading to Teleport 4.0+"
Teleport 4.0+ switched to GRPC and HTTP/2 as an API protocol. The HTTP/2 spec bans
two previously recommended ciphers. `tls-rsa-with-aes-128-gcm-sha256` & `tls-rsa-with-aes-256-gcm-sha384`, make sure these are removed from `teleport.yaml`
[Visit our community for more details](https://community.gravitational.com/t/drop-ciphersuites-blacklisted-by-http-2-spec/446)
@ -2231,8 +2260,9 @@ When upgrading a single Teleport cluster:
in any sequence or at the same time.
3. Finally, upgrade the SSH nodes in any sequence or at the same time.
!!! warning "Warning":
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
!!! warning "Warning"
If several auth servers are running in HA configuration (for example, in AWS auto-scaling group) you have to shrink the group to **just one auth server** prior to performing an upgrade. While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server, as a precaution. This allows for a safe rollback in case the migration itself fails.
When upgrading multiple clusters:
@ -2271,7 +2301,8 @@ The `license_file` path can be either absolute or relative to the configured
`data_dir`. If license file path is not set, Teleport will look for the
`license.pem` file in the configured `data_dir`.
!!! tip "NOTE":
!!! tip "NOTE"
Only Auth servers require the license. Proxies and Nodes that do not also
have Auth role enabled do not need the license.
@ -2280,7 +2311,8 @@ The `license_file` path can be either absolute or relative to the configured
To diagnose problems you can configure `teleport` to run with verbose logging enabled
by passing it `-d` flag.
!!! tip "NOTE":
!!! tip "NOTE"
It is not recommended to run Teleport in production with verbose logging
as it generates a substantial amount of data.

33
docs/4.0/architecture.md
View file

@ -69,7 +69,8 @@ Teleport supports two types of user accounts:
Github, Active Directory (AD) or any identity store with an OpenID/OAuth2 or SAML endpoint.
!!! tip "Version Warning":
!!! tip "Version Warning"
SAML, OIDC and Active Directory are only supported in Teleport Enterprise. Please
take a look at the [Teleport Enterprise](/enterprise.md) chapter for more information.
@ -107,7 +108,8 @@ node:
Teleport uses [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
for the two-step authentication. The password + 2nd factor are submitted to a proxy via HTTPS, therefore it is critical for a secure configuration of Teleport to install a proper HTTPS certificate on a proxy.
!!! warning "Warning":
!!! warning "Warning"
Do not use a self-signed SSL/HTTPS certificates when creating production!
If the credentials are correct, the auth server generates and signs a new certificate and returns
@ -124,7 +126,8 @@ logins. The key will automatically expire after 12 hours by default. This TTL ca
If the node is located, the proxy establishes the connection between the client and the
requested node. The destination node then begins recording the session, sending the session history to the auth server to be stored.
!!! note "Note":
!!! note "Note"
Teleport may also be configured to have the session recording occur on the proxy, see [Session Recording](architecture/#session-recording) for more information.
4) When the node receives a connection request, it also checks with the auth server to validate
@ -180,7 +183,8 @@ Cluster state | `dir`, `etcd`, `dynamodb` | Multi-server (HA) configuration i
Audit Log Events | `dir`, `dynamodb` | If `dynamodb` is used for the audit log events, `s3` back-end **must** be used for the recorded sessions.
Recorded Sessions| `dir`, `s3` | `s3` is mandatory if `dynamodb` is used for the audit log.
!!! tip "Note":
!!! tip "Note"
The reason Teleport designers split the audit log events and the recorded
sessions into different back-ends is because of the nature of the data. A
recorded session is a compressed binary stream (blob) while the event is a
@ -237,7 +241,8 @@ the node and signs its certificate.
To join a cluster for the first time, a node must present a "join token" to the auth server.
The token can be static (configured via a config file) or a dynamic, single-use token.
!!! tip "NOTE":
!!! tip "NOTE"
When using dynamic tokens, their default time to live (TTL) is 15 minutes, but it can be
reduced (not increased) via `tctl` flag.
@ -254,7 +259,8 @@ discover the member nodes of the cluster.
Cluster administration is performed using `tctl` command line tool.
!!! tip "NOTE":
!!! tip "NOTE"
For high availability in production, a Teleport cluster can be serviced by multiple auth servers
running in sync. Check [HA configuration](/admin-guide.md#high-availability) in the
Admin Guide.
@ -279,7 +285,8 @@ recommended to have several of them running.
When you launch the Teleport Proxy for the first time, it will generate a self-signed HTTPS
certificate to make it easier to explore Teleport.
!!! warning "Warning":
!!! warning "Warning"
It is absolutely crucial to properly configure TLS for HTTPS when you use Teleport Proxy in production.
@ -298,7 +305,8 @@ In this mode, Teleport Proxy implements WSS (secure web sockets) to SSH proxy:
4. From the SSH node's perspective, it's a regular SSH client connection that is authenticated using an
OpenSSH certificate, so no special logic is needed.
!!! tip "NOTE":
!!! tip "NOTE"
When using the web UI, Teleport Proxy terminates the traffic and re-encodes for SSH client connection.
### SSH Proxy
@ -324,7 +332,8 @@ Once the client has obtained a short lived certificate, it can use it to authent
2. Proxy dials to the target TCP address and starts forwarding the traffic to the client.
3. SSH client uses established SSH tunnel to open a new SSH connection and authenticate with the target node using its client certificate.
!!! tip "NOTE":
!!! tip "NOTE"
Teleport's proxy command makes it compatible with [SSH jump hosts](https://wiki.gentoo.org/wiki/SSH_jump_host) implemented using OpenSSH's `ProxyCommand`
@ -399,7 +408,8 @@ The Teleport auth server keeps the audit log of SSH-related events that take
place on any node with a Teleport cluster. It is important to understand that
the SSH nodes emit audit events and submit them to the auth server.
!!! warning "Compatibility Warning":
!!! warning "Compatibility Warning"
Because all SSH events like `exec` or `session_start` are reported by the
Teleport node service, they will not be logged if you are using OpenSSH
`sshd` daemon on your nodes.
@ -412,7 +422,8 @@ in the [Admin Manual](/admin-guide/#audit-log).
Teleport users are encouraged to export the events into external, long term
storage.
!!! info "Deployment Considerations":
!!! info "Deployment Considerations"
If multiple Teleport auth servers are used to service the same cluster (HA mode)
a network file system must be used for `/var/lib/teleport/log` to allow them
to combine all audit events into the same audit log.

6
docs/4.0/aws-oss-guide.md
View file

@ -105,7 +105,8 @@ Teleport setup, S3 will provide storage for recorded sessions.
We recommend using Amazon S3 Standard.
!!! tip "Tip":
!!! tip "Tip"
S3 provides [Amazon S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html),
which is useful for customers deploying Teleport in regulated environments.
@ -205,7 +206,8 @@ Screenshot of where to put it in via AWS console.
![Config Instance Details](img/aws/adding-user-data.png)
!!! note "Note":
!!! note "Note"
`TELEPORT_DOMAIN_NAME` and `TELEPORT_EXTERNAL_HOSTNAME` are more or less the
same thing but we keep them separate just in case you want to use a load balancer
on a different hostname.

6
docs/4.0/enterprise.md
View file

@ -14,7 +14,8 @@ benefits of Teleport Enterprise.
|[FedRAMP/FIPS](#fedrampfips) | With Teleport 4.0, we have built out the foundation to help Teleport Enterprise customers build and meet the requirements in a FedRAMP System Security Plan (SSP). This includes a FIPS 140-2 friendly build of Teleport Enterprise as well as a variety of improvements to aid in complying with security controls even in FedRAMP High environments.
|Commercial Support | In addition to these features, Teleport Enterprise also comes with a premium support SLA with guaranteed response times.
!!! tip "Contact Information":
!!! tip "Contact Information"
If you are interested in Teleport Enterprise, please reach out to
`sales@gravitational.com` for more information.
@ -82,7 +83,8 @@ to enforce SSH access policies like _"developers must not touch production data"
See the [SSO for SSH](ssh-sso.md) chapter for more details.
!!! tip "Contact Information":
!!! tip "Contact Information"
For more information about Teleport Enterprise or Gravity please reach out us to `sales@gravitational.com` or fill out the contact for on our [website](https://gravitational.com/demo)

9
docs/4.0/kubernetes-ssh.md
View file

@ -175,7 +175,8 @@ $ kubectl exec -ti <pod-name>
The `kubectl exec` request will be routed through the Teleport proxy and
Teleport will log the audit record and record the session.
!!! note:
!!! note
For more information on integrating Teleport with Github SSO, please see the [Github section in the Admin Manual](admin-guide/#github-oauth-20).
### Okta Auth
@ -212,7 +213,8 @@ $ tctl get roles/admin > admin.yaml
$ tctl create -f admin.yaml
```
!!! tip "Advanced Usage":
!!! tip "Advanced Usage"
`{{ external.trait_name }}` example is shown to demonstrate how to fetch
the Kubernetes groups dynamically from Okta during login. In this case, you
need to define Kubernetes group membership in Okta (as a trait) and use
@ -221,5 +223,6 @@ $ tctl create -f admin.yaml
Once this is complete, when users execute `tsh login` and go through the usual Okta login
sequence, their `kubeconfig` will be updated with their Kubernetes credentials.
!!! note:
!!! note
For more information on integrating Teleport with Okta, please see the [Okta integration guide](/ssh-okta/).

3
docs/4.0/oidc.md
View file

@ -9,7 +9,8 @@ administrators to define policies like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.

4
docs/4.0/quickstart-enterprise.md
View file

@ -201,6 +201,7 @@ Pay attention to the _allow/logins_ field in the role definition: by default, th
role only allows SSH logins as `root@host`.
!!! note "Note"
Ignore `{{internal.logins}}` "allowed login" for now. It exists for
compatibility purposes when upgrading existing open source Teleport
clusters.
@ -267,7 +268,8 @@ Note that "--user=joe" part can be omitted if `$USER` environment variable is "j
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy. Your browser will
throw a warning **Your connection is not private**. Click Advanced, and **Proceed to 0.0.0.0 (unsafe)**

12
docs/4.0/quickstart.md
View file

@ -111,7 +111,8 @@ $ tsh --proxy=localhost --insecure login
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport must to go through a proxy, sometimes called a "bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy. Your browser will
throw a warning **Your connection is not private**. Click Advanced, and **Proceed to 0.0.0.0 (unsafe)**
@ -130,7 +131,8 @@ With a certificate in place, a user can SSH into any host behind the proxy:
$ tsh ssh localhost
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing "tsh ssh" a user may rename `tsh` binary to `ssh` and use the familiar syntax as in `ssh localhost`.
## Adding Nodes to Cluster
@ -160,7 +162,8 @@ localhost xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.1:3022
new-node xxxxx-xxxx-xxxx-xxxxxxx 10.0.10.2:3022
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport also supports static pre-defined invitation tokens which can be set in the [configuration file](admin-guide.md#adding-nodes-to-the-cluster)
## Adding a node located behind NAT
@ -265,7 +268,8 @@ Also, people can join your session via terminal assuming they have Teleport inst
$ tsh --proxy=teleport.example.com join 7645d523-60cb-436d-b732-99c5df14b7c4
```
!!! tip "NOTE":
!!! tip "NOTE"
For this to work, both of you must have proper user mappings allowing you access `db` under the same OS user.
## Running in Production

9
docs/4.0/ssh-adfs.md
View file

@ -10,7 +10,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -181,11 +182,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

7
docs/4.0/ssh-gsuite.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -61,6 +62,7 @@ spec:
```
!!! important
The groups will be fetched only if admins include special auth scope https://www.googleapis.com/auth/admin.directory.group.readonly in the scopes of the connector as shown in the example above.
@ -134,7 +136,8 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple OIDC connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`

12
docs/4.0/ssh-okta.md
View file

@ -8,7 +8,8 @@ like:
* Only members of "DBA" group can SSH into machines running PostgreSQL.
* Developers must never SSH into production servers.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -66,7 +67,8 @@ GROUP ATTRIBUTE STATEMENTS
![Configure APP](img/okta-saml-3.png)
!!! tip "Important":
!!! tip "Important"
Notice that we have set "NameID" to the email format and mapped the groups with
a wildcard regex in the Group Attribute statements. We have also set the "Audience"
and SSO URL to the same value.
@ -176,11 +178,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

18
docs/4.0/ssh-one-login.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide/#github-oauth-20) as
an SSO provider.
@ -33,7 +34,8 @@ section:
![Create APP](img/onelogin-saml-1.png?raw=true)
!!! tip "Important":
!!! tip "Important"
Make sure to pick `SAML Test Connector (SP)` and not `SAML Test Connector (IdP)`,
because teleport only supports `SP` - service provider initiated SAML flows.
@ -50,7 +52,8 @@ exposed as SAML attribute statements:
![Configure APP](img/onelogin-saml-3.png)
![Configure APP](img/onelogin-saml-4.png)
!!! warning "Important":
!!! warning "Important"
Make sure to check `Include in SAML assertion` checkbox.
Add users to the application:
@ -90,7 +93,8 @@ To fill in the fields, open `SSO` tab:
* `issuer` - use value from `Issuer URL field`, e.g. `https://app.onelogin.com/saml/metadata/123456`
* `sso` - use the value from the value from field `SAML 2.0 Endpoint (HTTP)` but replace `http-post` with `http-redirect`, e.g. `https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456`
!!! tip "Important":
!!! tip "Important"
Make sure to replace `http-post` with `http-redirect`!
* `cert` - download certificate, by clicking "view details link" and add to `cert` section
@ -163,11 +167,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

3
docs/4.0/ssh-rbac.md
View file

@ -215,7 +215,8 @@ spec:
'workload': ['database', 'backup']
```
!!! tip "Dynamic RBAC":
!!! tip "Dynamic RBAC"
Node labels can be dynamic, i.e. determined at runtime by an output
of an executable. In this case, you can implement "permissions follow workload"
policies (eg., any server where PostgreSQL is running becomes _automatically_

12
docs/4.0/trustedclusters.md
View file

@ -27,7 +27,8 @@ This guide's focus is on more in-depth coverage of trusted clusters features and
* Enable/disable trust between clusters.
* Establish permissions mapping between clusters using Teleport roles.
!!! tip "Teleport Node Tunneling":
!!! tip "Teleport Node Tunneling"
If you have a large amount of devices on different networks, such as
managed IoT devices or a couple of nodes on a different network you can utilize
the [Teleport Node Tunneling](quickstart/#adding-a-node-located-behind-nat-teleport-node-tunneling).
@ -91,7 +92,8 @@ the fly using `tctl` tool.
!!! tip "Important":
!!! tip "Important"
It is important to realize that join tokens are only used to establish the
connection for the first time. The clusters will exchange certificates and
won't be using the token to re-establish the connection in the future.
@ -146,7 +148,8 @@ more complicated.
## RBAC
!!! warning "Version Warning":
!!! warning "Version Warning"
The RBAC section is applicable only to Teleport Enterprise. The open source
version does not support SSH roles.
@ -297,7 +300,8 @@ $ tsh ssh --cluster=east root@db1.east
```
!!! tip "Note":
!!! tip "Note"
Trusted clusters work only one way. So, in the example above users from "east"
cannot see or connect to the nodes in "main".

6
docs/4.0/user-manual.md
View file

@ -126,7 +126,8 @@ Subsequent `tsh ssh` commands will run without asking for credentials
until the temporary certificate expires. By default, Teleport issues user
certificates with a TTL (time to live) of 12 hours.
!!! tip "Tip":
!!! tip "Tip"
It is recommended to always use `tsh login` before using any other `tsh` commands.
This allows users to omit `--proxy` flag in subsequent tsh commands. For example
`tsh ssh user@host` will work.
@ -537,7 +538,8 @@ There are a few differences between Teleport's `tsh` and OpenSSH's `ssh` but mos
use `tsh login` before `tsh ssh`, your Teleport username will be stored in
`~/.tsh`
!!! tip "Tip":
!!! tip "Tip"
To avoid typing `tsh ssh user@host` when logging into servers, you can
create a symlink `ssh -> tsh` and execute the symlink. It will behave exactly
like a standard `ssh` command, i.e. `ssh login@host`. This is helpful with other

90
docs/4.1/admin-guide.md
View file

@ -95,6 +95,7 @@ with verbose logging by typing [ `teleport start -d` ](cli-docs.md#teleport-star
.
!!! danger "WARNING"
Teleport stores data in `/var/lib/teleport` . Make sure that
regular/non-admin users do not have access to this folder on the Auth
server.
@ -128,6 +129,7 @@ new process to handle new incoming requests, leaving the old daemon process
running until existing clients disconnect.
!!! warning "Version warning"
Graceful restarts only work if Teleport is
deployed using network-based storage like DynamoDB or etcd 3.3+. Future
versions of Teleport will not have this limitation.
@ -181,7 +183,8 @@ Docs](cli-docs.md#teleport-start) or run `teleport start --help`
Teleport uses the YAML file format for configuration. A sample configuration
file is shown below. By default, it is stored in `/etc/teleport.yaml`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
When editing YAML configuration, please pay attention to how your
editor handles white space. YAML requires consistent handling of
tab characters.
@ -608,7 +611,8 @@ the proxy, but this will prevent you from adding more proxies without changing
the `app_id` . For multi-proxy setups, the `app_id` should be an HTTPS URL
pointing to a JSON file that mirrors `facets` in the auth config.
!!! warning "Warning":
!!! warning "Warning"
The `app_id` must never change in the lifetime of the
cluster. If the App ID changes, all existing U2F key registrations will
become invalid and all users who use U2F as the second factor will need to
@ -635,7 +639,7 @@ Then invoke `tsh ssh` as usual to authenticate:
tsh --proxy <proxy-addr> ssh <hostname>
```
!!! tip "Version Warning":
!!! tip "Version Warning"
External user identities are only supported in [Teleport Enterprise](enterprise/index.md).
@ -880,12 +884,14 @@ teleport:
```
!!! warning "Warning":
!!! warning "Warning"
If a CA pin not provided, Teleport node will join a
cluster but it will print a `WARN` message (warning) into it's standard
error output.
!!! warning "Warning":
!!! warning "Warning"
The CA pin becomes invalid if a Teleport administrator
performs the CA rotation by executing
[ `tctl auth rotate` ](cli-docs.md#tctl-auth-rotate) .
@ -925,6 +931,7 @@ Token 696c0471453e75882ff70a761c1a8bfa has been deleted
## Adding a node located behind NAT
!!! note
This feature is sometimes called "Teleport IoT" or node tunneling.
With the current setup, you've only been able to add nodes that have direct access to the
@ -1232,7 +1239,8 @@ ssh -o "ForwardAgent yes" \
user@host.example.com
```
!!! tip "Tip":
!!! tip "Tip"
To avoid typing all this and use the usual `ssh
user@host.example.com `, users can update their ` ~/.ssh/config` file. See
"Using Teleport with OpenSSH" chapter for more examples.
@ -1250,7 +1258,8 @@ $ tsh login --proxy=proxy.example.com joe
$ ssh-add -L
```
!!! warning "GNOME Keyring SSH Agent":
!!! warning "GNOME Keyring SSH Agent"
It is well-known that Gnome Keyring SSH
agent, used by many popular Linux desktops like Ubuntu, does not support SSH
certificates. We recommend using the `ssh-agent` command from
@ -1313,7 +1322,8 @@ be manipulated with just 3 CLI commands:
| [ `tctl rm` ](cli-docs.md#tctl-rm) | Delete a resource by type/name | `tctl rm user/joe` |
| [ `tctl create` ](cli-docs.md#tctl-create) | Create a new resource from a YAML file. Use `-f` to override / update | `tctl create -f joe.yaml` |
!!! warning "YAML Format":
!!! warning "YAML Format"
By default Teleport uses [YAML format](https://en.wikipedia.org/wiki/YAML)
to describe resources. YAML is a
wonderful and very human-readable alternative to JSON or XML, but it's
@ -1354,7 +1364,8 @@ spec:
name: builtin-Admin
```
!!! tip "Note":
!!! tip "Note"
Some of the fields you will see when printing resources are used
only internally and are not meant to be changed. Others are reserved for
future use.
@ -1393,6 +1404,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.
@ -1477,7 +1489,8 @@ This setup works as follows:
reverse tunnel from step 1 is used to establish this connection shown as the
green line above.
!!! tip "Load Balancers":
!!! tip "Load Balancers"
The scheme above also works even if the "main" cluster
uses multiple proxies behind a load balancer (LB) or a DNS entry with
multiple values. This works by "east" establishing a tunnel to _every_ proxy
@ -1557,7 +1570,8 @@ $ tctl create cluster.yaml
At this point the users of the main cluster should be able to see "east" in the
list of available clusters.
!!! warning "HTTPS configuration":
!!! warning "HTTPS configuration"
If the `web_proxy_addr` endpoint of the main
cluster uses a self-signed or invalid HTTPS certificate, you will get an
error: _"the trusted cluster uses misconfigured HTTP/TLS certificate"_. For
@ -1692,6 +1706,7 @@ spec:
```
!!! note
For open-source Teleport the `logins` field contains a list of allowed
OS logins. For the commercial Teleport Enterprise offering, which supports
role-based access control, the same field is treated as a list of _roles_
@ -1712,6 +1727,7 @@ $ tctl create github.yaml
```
!!! tip
When going through the Github authentication flow for the first time,
the application must be granted the access to all organizations that are
present in the "teams to logins" mapping, otherwise Teleport will not be
@ -1748,7 +1764,8 @@ Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
```
!!! tip "Note":
!!! tip "Note"
`localhost` and `127.0.0.1` are invalid values for the proxy
host. If for some reason your proxy runs locally, you'll need to provide
some other DNS name or a private IP address for it.
@ -1777,7 +1794,8 @@ removed if you uninstall `openssh-server` package. We recommend creating your
own PAM service file like `/etc/pam.d/teleport` and specifying it as
`service_name` above.
!!! tip "Note":
!!! tip "Note"
Teleport only supports the `account` and `session` stack. The `auth` PAM module is currently not supported with Teleport.
## Using Teleport with OpenSSH
@ -1809,7 +1827,8 @@ $ cat cluster_node_keys
@cert-authority *.graviton-auth ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDLNduBoHQaqi+kgkq3gLYjc6JIyBBnCFLgm63b5rtmWl/CJD7T9HWHxZphaS1jra6CWdboLeTp6sDUIKZ/Qw1MKFlfoqZZ8k6to43bxx7DvAHs0Te4WpuS/YRmWFhb6mMVOa8Rd4/9jE+c0f9O/t7X4m5iR7Fp7Tt+R/pjJfr03Loi6TYP/61AgXD/BkVDf+IcU4+9nknl+kaVPSGcPS9/Vbni1208Q+VN7B7Umy71gCh02gfv3rBGRgjT/cRAivuVoH/z3n5UwWg+9R3GD/l+XZKgv+pfe3OHoyDFxYKs9JaX0+GWc504y3Grhos12Lb8sNmMngxxxQ/KUDOV9z+R type=host
```
!!! tip "Note":
!!! tip "Note"
When sharing the @cert-authority make sure that the URL for the
proxy is correct. In the above example, `*.graviton-auth` should be changed to
teleport.example.com.
@ -1870,7 +1889,8 @@ behind `work.example.com` :
$ ssh root@database.work.example.com
```
!!! tip "NOTE":
!!! tip "NOTE"
Teleport uses OpenSSH certificates instead of keys which means
you can not connect to a Teleport node by IP address. You have to connect by
DNS name. This is because OpenSSH ensures the DNS name of the node you are
@ -1930,7 +1950,8 @@ The rotation takes time, especially for hosts, because each node in a cluster
needs to be notified that a rotation is taking place and request a new
certificate for itself before the grace period ends.
!!! warning "Warning":
!!! warning "Warning"
Be careful when choosing a grace period when rotating
host certificates. The grace period needs to be long enough for all nodes in
a cluster to request a new certificate. If some nodes go offline during the
@ -1944,7 +1965,8 @@ To check the status of certificate rotation:
$ tctl status
```
!!! danger "Version Warning":
!!! danger "Version Warning"
Certificate rotation can only be used with
clusters running version 2.6 of Teleport or newer. If trusted clusters are
used, make sure _all_ connected clusters are running version 2.6+. If one of
@ -1952,6 +1974,7 @@ $ tctl status
trust/connection to that cluster will be lost.
!!! warning "CA Pinning Warning"
If you are using [CA Pinning](#untrusted-auth-servers)
when adding new nodes, the CA pin will
changes after the rotation.
@ -2089,7 +2112,8 @@ $ tsh --proxy=main.example.com login east
## High Availability
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the
[Cluster State section](architecture/teleport-nodes.md#cluster-state) in the Teleport
Architecture documentation.
@ -2133,7 +2157,8 @@ configure your load balancer to forward the ports you specified for
your users, while the remaining ports should do TCP level forwarding, since
Teleport will handle its own SSL on top of that with its own certificates.
!!! tip "NOTE":
!!! tip "NOTE"
If you terminate TLS with your own certificate at a load
balancer you'll need to Teleport with `--insecure`
@ -2141,7 +2166,8 @@ If your load balancer supports health checks, configure it to hit the
`/webapi/ping` endpoint on the proxy. This endpoint will reply `200 OK` if the
proxy is running without problems.
!!! tip "NOTE":
!!! tip "NOTE"
As the new auth servers get added to the cluster and the old
servers get decommissioned, nodes and proxies will refresh the list of
available auth servers and store it in their local cache
@ -2199,12 +2225,14 @@ teleport:
### Using Amazon S3
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the
[cluster state section](architecture/teleport-nodes.md#cluster-state) in Teleport
Architecture documentation.
!!! tip "AWS Authentication":
!!! tip "AWS Authentication"
The configuration examples below contain AWS
access keys and secret keys. They are optional, they exist for your
convenience but we DO NOT RECOMMEND using them in production. If Teleport is
@ -2235,7 +2263,8 @@ running on an EC2 instance with an IAM role.
### Using DynamoDB
!!! tip "Tip":
!!! tip "Tip"
Before continuing, please make sure to take a look at the
[cluster state section](architecture/teleport-nodes.md#cluster-state) in Teleport Architecture documentation.
@ -2293,7 +2322,8 @@ teleport:
* If DynamoDB is used for the audit log, the logged events will be stored with a
TTL of 1 year. Currently this TTL is not configurable.
!!! warning "Access to DynamoDB":
!!! warning "Access to DynamoDB"
Make sure that the IAM role assigned to
Teleport is configured with the sufficient access to DynamoDB. Below is the
example of the IAM policy you can use:
@ -2351,7 +2381,8 @@ clients, etc), the following rules apply:
As an extra precaution you might want to backup your application prior to upgrading. We provide more instructions in [Backup before upgrading](#backup-before-upgrading).
!!! warning "Upgrading to Teleport 4.0+":
!!! warning "Upgrading to Teleport 4.0+"
Teleport 4.0+ switched to GRPC and HTTP/2 as an API protocol. The HTTP/2 spec bans
two previously recommended ciphers. `tls-rsa-with-aes-128-gcm-sha256` & `tls-rsa-with-aes-256-gcm-sha384`, make sure these are removed from `teleport.yaml`
[Visit our community for more details](https://community.gravitational.com/t/drop-ciphersuites-blacklisted-by-http-2-spec/446)
@ -2374,7 +2405,8 @@ When upgrading a single Teleport cluster:
3. Finally, upgrade the SSH nodes in any sequence or at the same time.
!!! warning "Warning":
!!! warning "Warning"
If several auth servers are running in HA configuration
(for example, in AWS auto-scaling group) you have to shrink the group to
**just one auth server** prior to performing an upgrade. While Teleport
@ -2474,7 +2506,8 @@ The `license_file` path can be either absolute or relative to the configured
`data_dir` . If license file path is not set, Teleport will look for the
`license.pem` file in the configured `data_dir` .
!!! tip "NOTE":
!!! tip "NOTE"
Only Auth servers require the license. Proxies and Nodes that do
not also have Auth role enabled do not need the license.
@ -2483,7 +2516,8 @@ The `license_file` path can be either absolute or relative to the configured
To diagnose problems you can configure [ `teleport` ](cli-docs.md#teleport) to
run with verbose logging enabled by passing it `-d` flag.
!!! tip "NOTE":
!!! tip "NOTE"
It is not recommended to run Teleport in production with verbose
logging as it generates a substantial amount of data.

9
docs/4.1/architecture/teleport-architecture-overview.md
View file

@ -76,6 +76,7 @@ The numbers correspond to the steps needed to connect a client to a node. These
steps are explained below the diagram.
!!! warning "Caution"
The teleport daemon calls services "roles" in the CLI
client. The `--roles` flag has no relationship to concept of User Roles or
permissions.
@ -88,6 +89,7 @@ steps are explained below the diagram.
4. Authorize Client Access to Node
!!! tip "Tip"
In the diagram above we show each Teleport service separately for
clarity, but Teleport services do not have to run on separate nodes.
Teleport can be run as a binary on a single-node cluster with no external
@ -104,6 +106,7 @@ steps are explained in detail below the diagram.
![Teleport Everything](../img/everything.svg)
!!! note "Caution"
The Teleport Admin tool, `tctl` , must be physically present
on the same machine where Teleport Auth is running. Adding new nodes or
inviting new users to the cluster is only possible using this tool.
@ -143,7 +146,8 @@ generator. The password + 2nd factor are submitted to a proxy via HTTPS,
therefore it is critical for a secure configuration of Teleport to install a
proper HTTPS certificate on a proxy.
!!! warning "Warning":
!!! warning "Warning"
Do not use self-signed SSL/HTTPS certificates in production!
If the credentials are correct, the auth server generates and signs a new
@ -168,7 +172,8 @@ If the node is located, the proxy establishes the connection between the client
and the requested node. The destination node then begins recording the session,
sending the session history to the auth server to be stored.
!!! note "Note":
!!! note "Note"
Teleport may also be configured to have the session recording
occur on the proxy, see [Audit Log](../admin-guide.md#audit-log) for more
information.

31
docs/4.1/architecture/teleport-auth.md
View file

@ -49,7 +49,7 @@ Authority. A certificate contains four important pieces of data:
Teleport uses SSH certificates to authenticate nodes and users within a cluster.
There are two CAs operating inside the Auth Server because nodes and users each
need their own certificates. <!--TODO: Why?-->
need their own certificates. <!-- TODO: Why? -->
* The **Node CA** issues certificates which identify a node (i.e. host, server,
computer). These certificates are used to add new nodes to a cluster and
@ -70,7 +70,8 @@ certificate on a node makes it a cluster member.
dynamic, single-use token generated by [`tctl nodes
add`](../cli-docs.md#tctl-nodes-add).
!!! tip "Token TTL":
!!! tip "Token TTL"
When using dynamic tokens, their default time to live (TTL) is 15
minutes, but it can be reduced (not increased) via
[`tctl nodes add --ttl`](../cli-docs.md#tctl-nodes-add) flag.
@ -84,8 +85,8 @@ certificate on a node makes it a cluster member.
![Node Authorization](../img/node_cluster_auth.svg)
All nodes in a cluster can connect to the [Auth Server's API](#auth-api)
<!--Docs about this--> implemented as an HTTP REST service running over the SSH
All nodes in a cluster can connect to the [Auth Server's API](#auth-api) <!-- Docs about this -->
implemented as an HTTP REST service running over the SSH
tunnel. This API connection is authenticated with the node certificate and the
encoded role is checked to enforce access control. For example, a client
connection using a certificate with only the `node` role won't be able to add
@ -112,8 +113,8 @@ by the system's SSH agent if it is running.
secure websocket session.
In addition to user's identity, user certificates also contain user roles and
SSH options, like "permit-agent-forwarding" <!--TODO: link to config/set options
here-->.
SSH options, like "permit-agent-forwarding".
<!-- TODO: link to config/set options here -->
This additional data is stored as a certificate extension and is protected by
the CA signature.
@ -146,8 +147,8 @@ administrator on one of cluster's Auth Servers, the following happens:
1. A new certificate authority (CA) key is generated.
2. The old CA will be considered valid _alongside_ the new CA for some period of
time. This period of time is called a _grace period_ <!--TODO: Link to
config/defaults.-->
time. This period of time is called a _grace period_.
<!-- TODO: Link to config/defaults. -->
3. During the grace period, all previously issued certificates will be
considered valid, assuming their TTL isn't expired.
4. After the grace period is over, the certificates issued by the old CA are no
@ -160,7 +161,7 @@ learn how to do certificate rotation in practice.
## Auth API
<!--TODO: Can we say more about this, abstract of routes provided-->
<!-- TODO: Can we say more about this, abstract of routes provided -->
Clients can also connect to the auth API through the Teleport proxy to use a
limited subset of the API to discover the member nodes of the cluster.
@ -201,7 +202,8 @@ events and submit them to the auth server. The events recorded include:
* session time
* session IDs
!!! warning "Compatibility Warning":
!!! warning "Compatibility Warning"
Because all SSH events like `exec` or `session_start` are reported by the
Teleport node service, they will not be logged if you are using OpenSSH
`sshd` daemon on your nodes.
@ -214,7 +216,8 @@ in the [Admin Manual](../admin-guide.md#audit-log).
Teleport users are encouraged to export the events into external, long term
storage.
!!! info "Deployment Considerations":
!!! info "Deployment Considerations"
If multiple Teleport auth servers are used
to service the same cluster (HA mode) a network file system must be used for
`/var/lib/teleport/log` to allow them to combine all audit events into the
@ -266,7 +269,8 @@ Cluster state | `dir`, `etcd`, `dynamodb` | Multi-server (HA) configuration i
Audit Log Events | `dir`, `dynamodb` | If `dynamodb` is used for the audit log events, `s3` back-end **must** be used for the recorded sessions.
Recorded Sessions| `dir`, `s3` | `s3` is mandatory if `dynamodb` is used for the audit log.
!!! tip "Note":
!!! tip "Note"
The reason Teleport designers split the audit log events and the recorded
sessions into different back-ends is because of the nature of the data. A
recorded session is a compressed binary stream (blob) while the event is a
@ -278,7 +282,8 @@ Recorded Sessions| `dir`, `s3` | `s3` is mandatory if `dynamodb` i
The combination of DynamoDB + S3 is especially popular among AWS users because
it allows them to run Teleport clusters completely devoid of local state.
!!! tip "NOTE":
!!! tip "NOTE"
For high availability in production, a Teleport cluster can be
serviced by multiple auth servers running in sync. Check [HA
configuration](../admin-guide.md#high-availability) in the Admin Guide.

4
docs/4.1/architecture/teleport-nodes.md
View file

@ -25,6 +25,7 @@ labels. Nodes can access the list of all Nodes in their cluster via the
[Auth Server API](teleport-auth.md#auth-api).
!!! tip "Tip"
In most environments we advise replacing the OpenSSH daemon `sshd`
with the Teleport Node Service unless there are existing workflows relying
on `ssh` or in special cases such as embedded devices that can't run
@ -59,6 +60,7 @@ Learn more about this process in the [Auth
Guide](teleport-auth.md#authentication-in-teleport).
!!! warning "Single-Node Clusters are Clusters"
Once a Node gets a signed certificate from the Node CA, the Node is considered a member of the cluster, even if that cluster has only one node.
## Connecting to Nodes
@ -115,7 +117,7 @@ nodes if their public keys are signed by a trusted CA. A "trusted cluster" is a
pair of public keys of the trusted CA. It can be configured via `teleport.yaml`
file.
<!--TODO: incomplete, write more on this-->
<!-- TODO: incomplete, write more on this -->
## More Concepts

4
docs/4.1/architecture/teleport-proxy.md
View file

@ -40,7 +40,7 @@ client SSH connection:
client connection that is authenticated using an OpenSSH certificate, so no
special logic is needed.
!!! note "SSL Encryption":
!!! note "SSL Encryption"
When using the web UI, the Teleport Proxy terminates SSL traffic and re-encodes data for the SSH client connection.
@ -89,7 +89,7 @@ client `ssh` or using `tsh`:
SSH connection. The client authenticates with the target Node using its
client certificate.
!!! tip "NOTE":
!!! tip "NOTE"
Teleport's proxy command makes it compatible with [SSH jump hosts](https://wiki.gentoo.org/wiki/SSH_jump_host) implemented using OpenSSH's `ProxyCommand`. also supports OpenSSH's ProxyJump/ssh -J implementation as of Teleport 4.1.

10
docs/4.1/architecture/teleport-users.md
View file

@ -1,6 +1,6 @@
## Teleport Users
<!--TODO: This doc is incomplete, pending addition of Enterprise topics-->
<!-- TODO: This doc is incomplete, pending addition of Enterprise topics -->
**Table of Contents**
@ -69,6 +69,7 @@ Teleport supports second factor authentication (2FA) when using a local auth
connector and it is enforced by default.
!!! info "2FA Support"
2FA is not supported with SSO providers such as Github or OKTA. To learn
more about SSO configuration check out the [SSO section of the Enterprise
Guide](../enterprise/index.md#sso)
@ -85,13 +86,14 @@ connector and it is enforced by default.
### External users
<!--TODO: Production topic-->
<!-- TODO: Production topic -->
External users are users stored elsewhere within an organization. Examples
include Github, Active Directory (AD), OIDC, or any identity store with an
OpenID/OAuth2 or SAML endpoint.
!!! tip "Version Warning":
External user storage is only supported in Teleport
Enterprise. Please take a look at the [Teleport
Enterprise](../enterprise/index.md) chapter for more information.
@ -102,7 +104,7 @@ It is possible to have multiple identity sources configured for a Teleport
cluster. In this case, an identity source (called a "connector") will have to be
passed to [ `tsh --auth=connector_name login` ](../cli-docs.md#tsh-login).
<!--TODO: Production Configuration-->
<!-- TODO: Production Configuration -->
The local users connector can be specified via [`tsh --auth=local
login`](../cli-docs.md#tsh-login).
@ -114,7 +116,7 @@ roles allows Teleport to implement role-based access control (RBAC), i.e. assign
users to groups (roles) and restrict each role to a subset of actions on a
subset of nodes in a cluster.
<!--TODO: Enterprise Topic-->
<!-- TODO: Enterprise Topic -->
## More Concepts

12
docs/4.1/aws-oss-guide.md
View file

@ -100,7 +100,8 @@ Teleport setup, S3 will provide storage for recorded sessions.
We recommend using Amazon S3 Standard.
!!! tip "Tip":
!!! tip "Tip"
S3 provides [Amazon S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html),
which is useful for customers deploying Teleport in regulated environments.
@ -149,7 +150,8 @@ An example policy is shown below:
]
}
```
!!! note "Note":
!!! note "Note"
`example.s3.bucket` will need to be replaced with your bucket name.
#### IAM for DynamoDB
@ -177,7 +179,8 @@ An example policy is shown below:
]
}
```
!!! note "Note":
!!! note "Note"
`eu-west-1:123456789012:table/prod.teleport.auth` will need to be replaced with your DynamoDB instance.
### ACM
@ -262,7 +265,8 @@ Screenshot of where to put it in via AWS console.
![Config Instance Details](img/aws/adding-user-data.png)
!!! note "Note":
!!! note "Note"
`TELEPORT_DOMAIN_NAME` and `TELEPORT_EXTERNAL_HOSTNAME` are more or less the
same thing but we keep them separate just in case you want to use a load balancer
on a different hostname.

54
docs/4.1/cli-docs.md
View file

@ -29,7 +29,7 @@ the following services.
| `--ca-pin` | none | **string** `sha256:<hash>` | set CA pin to validate the Auth Server. Generated by `tctl status`
| `--nodename` | `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to login. By default it's equal to the value returned by
| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!--TODO link how to configure this file-->
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!-- TODO link how to configure this file -->
| `--labels` | none | **string** comma-separated list | assigns a set of labels to a node. See the explanation of labeling mechanism in the [Labeling Nodes](admin-guide.md#labeling-nodes) section.
| `--insecure` | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service.
| `--fips` | none | none | start Teleport in FedRAMP/FIPS 140-2 mode.
@ -51,7 +51,7 @@ only available from inside of a recorded SSH session.
standard output.
**Caution**: This sample config is _not_ the default config and should be used
for reference only.<!--TODO Link to Config Doc-->
for reference only. <!-- TODO Link to Config Doc -->
## teleport version
@ -59,8 +59,8 @@ for reference only.<!--TODO Link to Config Doc-->
## teleport help
`teleport help` shows help `teleport` and its subcommands like this `teleport
help <subcommand>`
`teleport help` shows help `teleport` and its subcommands like this
`teleport help <subcommand>`
# tsh
@ -75,7 +75,7 @@ information about the cluster.
| `-l, --login` | none | an identity name | the login identity that the Teleport User should use
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | set SSH proxy address
| `--user` | `$USER` | none | the Teleport User name
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!--TODO Check this-->
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!-- TODO Check this -->
| `-i, --identity` | none | **string** filepath | Identity file
| `--cert-format` | `file` | `file` or `openssh` | SSH certificate format
| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments
@ -212,7 +212,7 @@ tsh --proxy proxy.example.com play <session-id>
Copies files from source to dest
**Usage** `usage: tsh scp [<flags>] <source>... <dest>`
<!--TODO Confirm which flags are supported, and whether supports multiple sources-->
<!-- TODO Confirm which flags are supported, and whether supports multiple sources -->
### Arguments
@ -245,8 +245,8 @@ $ tsh --proxy=proxy.example.com scp -P example.txt user@host/destination/dir
List cluster nodes
**Usage** `usage: tsh ls [<flags>] [<label>]` <!--TODO: label? or labels? seems
like it only supports one label at a time-->
**Usage** `usage: tsh ls [<flags>] [<label>]`
<!-- TODO: label? or labels? seems like it only supports one label at a time -->
### Arguments
@ -448,8 +448,8 @@ Generates a user invitation token.
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -497,8 +497,8 @@ Generate a node invitation token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -525,8 +525,8 @@ List all active SSH nodes within the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
## tctl tokens add
@ -538,14 +538,14 @@ Create an invitation token
| Name | Default Value(s) | Allowed Value(s) | Description
|------|---------|----------------|----------------------------|
| `--type` | none | `trusted_cluster` , `node` , `signup` <!--TODO Confirm this.are any other types valid in /Users/heather/teleport/roles.go--> | Type of token to add
| `--type` | none | `trusted_cluster` , `node` , `signup` <!-- TODO Confirm this.are any other types valid in /Users/heather/teleport/roles.go --> | Type of token to add
| `--value` | none | **string** token value | Value of token to add
| `--ttl` | 1h | relative duration like 5s, 2m, or 3h, **maximum 48h** | Set expiration time for token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -601,8 +601,8 @@ Export public cluster (CA) keys to stdout
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -619,8 +619,7 @@ $ tctl auth export --type tls
Create an identity file(s) for a given user
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host
<host>][--format] [<flags>]`
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host <host>][--format] [<flags>]`
### Flags
@ -635,8 +634,8 @@ Create an identity file(s) for a given user
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -675,7 +674,8 @@ Rotate certificate authorities in the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -708,7 +708,8 @@ See the [Resource Guide](admin-guide.md#resources) for complete docs on how to b
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -763,7 +764,8 @@ Print a YAML declaration of various Teleport resources
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples

6
docs/4.1/enterprise/index.md
View file

@ -13,7 +13,8 @@ The table below gives a quick overview of the benefits of Teleport Enterprise.
|[FedRAMP/FIPS](#fedrampfips) | With Teleport 4.0, we have built out the foundation to help Teleport Enterprise customers build and meet the requirements in a FedRAMP System Security Plan (SSP). This includes a FIPS 140-2 friendly build of Teleport Enterprise as well as a variety of improvements to aid in complying with security controls even in FedRAMP High environments.
|Commercial Support | In addition to these features, Teleport Enterprise also comes with a premium support SLA with guaranteed response times.
!!! tip "Contact Information":
!!! tip "Contact Information"
If you are interested in Teleport Enterprise, please reach out to
`sales@gravitational.com` for more information.
@ -81,7 +82,8 @@ to enforce SSH access policies like _"developers must not touch production data"
See the [SSO for SSH](ssh-sso.md) chapter for more details.
!!! tip "Contact Information":
!!! tip "Contact Information"
For more information about Teleport Enterprise or Gravity please reach out us to `sales@gravitational.com` or fill out the contact for on our [website](https://gravitational.com/demo)

4
docs/4.1/enterprise/quickstart-enterprise.md
View file

@ -202,6 +202,7 @@ Pay attention to the _allow/logins_ field in the role definition: by default, th
role only allows SSH logins as `root@host`.
!!! note "Note"
Ignore `{{internal.logins}}` "allowed login" for now. It exists for
compatibility purposes when upgrading existing open source Teleport
clusters.
@ -268,7 +269,8 @@ Note that "--user=joe" part can be omitted if `$USER` environment variable is "j
Notice that `tsh` client always needs `--proxy` flag because all client connections
in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the `--insecure` flag which allows
us to skip configuring the HTTP/TLS certificate for Teleport proxy. Your browser will
throw a warning **Your connection is not private**. Click Advanced, and **Proceed to 0.0.0.0 (unsafe)**

6
docs/4.1/enterprise/ssh-fips.md
View file

@ -13,14 +13,14 @@ government agencies.
| Control | Teleport Features |
|----------|---------------------|
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br>• Control which SSH nodes a user can or cannot access. <br>• Control cluster level configuration (session recording, configuration, etc.) <br>• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br />• Control which SSH nodes a user can or cannot access. <br />• Control cluster level configuration (session recording, configuration, etc.) <br />• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-17 Remote Access](https://nvd.nist.gov/800-53/Rev4/control/AC-17) | Teleport administrators create users with configurable roles that can be used to allow or deny access to system resources. |
| [AC-20 Use of External Information Systems](https://nvd.nist.gov/800-53/Rev4/control/AC-20) | Teleport supports connecting multiple independent clusters using a feature called [Trusted Clusters](../trustedclusters/). When allowing access from one cluster to another, roles are mapped according to a pre-defined relationship of the scope of access.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../architecture/teleport-auth/#audit-log) that records cluster-wide events such as: <br>• Failed login attempts.<br>• Commands that were executed (SSH “exec” commands).<br> • Ports that were forwarded. <br>• File transfers that were initiated.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../architecture/teleport-auth/#audit-log) that records cluster-wide events such as: <br />• Failed login attempts.<br />• Commands that were executed (SSH “exec” commands).<br /> • Ports that were forwarded. <br />• File transfers that were initiated.|
| [AU-10 Non-Repudiation](https://nvd.nist.gov/800-53/Rev4/control/AU-10) | Teleport audit logging supports both events as well as audit of an entire SSH session. For non-repudiation purposes a full session can be replayed back and viewed. |
| [CM-08 Information System Component Inventory](https://nvd.nist.gov/800-53/Rev4/control/CM-8) | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time.|
| [IA-03 Device Identification and Authentication](https://nvd.nist.gov/800-53/Rev4/control/IA-3) | Teleport requires valid x509 or SSH certificates issued by a Teleport Certificate Authority (CA) to establish a network connection for device-to-device network connection between Teleport components. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br>Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br>In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br />Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br />In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
Enterprise customers can download the custom FIPS package from the [Gravitational Dashboard](https://dashboard.gravitational.com/web/). Look for `Linux 64-bit (FedRAMP/FIPS)`. RPM and DEB packages are also available.

6
docs/4.1/enterprise/ssh-rbac.md
View file

@ -144,7 +144,8 @@ Variable | Description
`{{internal.logins}}` | Substituted with "allowed logins" parameter used in `tctl users add [user] <allowed logins>` command. This applies only to users stored in Teleport's own local database.
`{{external.trait_name}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on). For SAML, this will be expanded with the "trait_name" assertion value. For OIDC, this will be expanded with the value of the "trait_name" claim.
!!! tip "Internal vs external":
!!! tip "Internal vs external"
`internal.logins` is a special unique value which uses Teleport's own internal database, while `trait_name` in `external.trait_name` is intended to be replaced with the name of an actual SAML assertion or OIDC claim as sent by the identity provider.
Both variables above are there to deliver the same benefit: they allow Teleport
@ -218,7 +219,8 @@ spec:
'workload': ['database', 'backup']
```
!!! tip "Dynamic RBAC":
!!! tip "Dynamic RBAC"
Node labels can be dynamic, i.e. determined at runtime by an output
of an executable. In this case, you can implement "permissions follow workload"
policies (eg., any server where PostgreSQL is running becomes _automatically_

3
docs/4.1/installation.md
View file

@ -32,6 +32,7 @@ $ curl https://get.gravitational.com/teleport-$version-$os-$arch-bin.tar.gz.sha2
## Install Pre-built Binaries
!!! info "sudo"
You may need to use `sudo` to run the installation commands.
### Linux
@ -166,4 +167,4 @@ $ sudo chown $USER /var/lib/teleport
If the build succeeds the binaries `teleport, tsh`, and `tctl` are now in the
directory `$GOPATH/src/github.com/gravitational/teleport/build`
<!--Notes on what to do if the build does not succeed, troubleshooting-->
<!-- Notes on what to do if the build does not succeed, troubleshooting -->

9
docs/4.1/kubernetes-ssh.md
View file

@ -175,7 +175,8 @@ $ kubectl exec -ti <pod-name>
The `kubectl exec` request will be routed through the Teleport proxy and
Teleport will log the audit record and record the session.
!!! note:
!!! note
For more information on integrating Teleport with Github SSO, please see the [Github section in the Admin Manual](admin-guide.md#github-oauth-20).
### Okta Auth
@ -212,7 +213,8 @@ $ tctl get roles/admin > admin.yaml
$ tctl create -f admin.yaml
```
!!! tip "Advanced Usage":
!!! tip "Advanced Usage"
`{{ external.trait_name }}` example is shown to demonstrate how to fetch
the Kubernetes groups dynamically from Okta during login. In this case, you
need to define Kubernetes group membership in Okta (as a trait) and use
@ -221,5 +223,6 @@ $ tctl create -f admin.yaml
Once this is complete, when users execute `tsh login` and go through the usual Okta login
sequence, their `kubeconfig` will be updated with their Kubernetes credentials.
!!! note:
!!! note
For more information on integrating Teleport with Okta, please see the [Okta integration guide](ssh-okta.md).

3
docs/4.1/oidc.md
View file

@ -9,7 +9,8 @@ administrators to define policies like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
an SSO provider.

9
docs/4.1/quickstart.md
View file

@ -68,11 +68,13 @@ $ mkdir -p /var/lib/teleport
Now we are ready to start Teleport.
!!! tip "Background Process"
Avoid suspending your current shell session by
running the process in the background like so: `teleport start >
teleport.log 2>&1 & `. Access the process logs with ` less teleport.log`._
!!! tip
"Debugging/Verbose Output" If you encounter errors with any `teleport,
tsh ` or ` tctl ` command you can enable verbose logging with the ` -d,--debug`
flag.
@ -101,6 +103,7 @@ yet. Let's create one for your OS user. In this example the OS user is
`teleport` and the hostname of the node is `grav-00` .
!!! info "OS User Mappings"
The OS user `teleport` must exist! On Linux, if it
does not already exist create it with `adduser teleport` . If you do not have
the permission to create new users on the VM, run `tctl users add teleport
@ -137,7 +140,8 @@ open this URL in a web browser to complete the registration process.
Proxy via the host machine and port `3080` in a web browser. One simple way to
do this is to temporarily append `[HOST_IP] grav-00` to `/etc/hosts`
!!! warning "Warning":
!!! warning "Warning"
We haven't provisioned any SSL certs for Teleport yet.
Your browser will throw a warning **Your connection is not private**. Click
Advanced, and **Proceed to [HOST_IP] (unsafe)** to preview the Teleport UI.
@ -163,7 +167,8 @@ Let's login using the `tsh` command line tool. Just as in the previous step, you
will need to be able to resolve the **hostname** of the cluster to a network
accessible IP.
!!! warning "Warning":
!!! warning "Warning"
For the purposes of this quickstart we are using the
`--insecure-no-tls` flag which allows us to skip configuring the HTTP/TLS
certificate for Teleport proxy.

9
docs/4.1/ssh-adfs.md
View file

@ -10,7 +10,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
an SSO provider.
@ -181,11 +182,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

11
docs/4.1/ssh-gsuite.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires an enterprise version of Teleport 4.1.4 or greater. The open source
edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
an SSO provider.
@ -63,7 +64,8 @@ Leave Service account permissions as blank.
This JSON file will need to be uploaded to the Authentication server, and will be later referenced by
the OIDC Connector, under `google_service_account_uri`.
!!! note:
!!! note
Teleport requires the service account JSON to be uploaded to all Teleport authentication servers when setting
up in a HA config.
@ -177,7 +179,8 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple OIDC connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
@ -202,4 +205,4 @@ $ sudo journalctl -fu teleport
```
If you wish to increase the verbosity of Teleport's syslog, you can pass the
[`--debug`](cli-docs.md#teleport-start) flag to `teleport start` command.
[`--debug`](cli-docs.md#teleport-start) flag to `teleport start` command.

12
docs/4.1/ssh-okta.md
View file

@ -8,7 +8,8 @@ like:
* Only members of "DBA" group can SSH into machines running PostgreSQL.
* Developers must never SSH into production servers.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
an SSO provider.
@ -66,7 +67,8 @@ GROUP ATTRIBUTE STATEMENTS
![Configure APP](img/okta-saml-3.png)
!!! tip "Important":
!!! tip "Important"
Notice that we have set "NameID" to the email format and mapped the groups with
a wildcard regex in the Group Attribute statements. We have also set the "Audience"
and SSO URL to the same value.
@ -176,11 +178,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

18
docs/4.1/ssh-one-login.md
View file

@ -9,7 +9,8 @@ like:
* Developers must never SSH into production servers.
* ... and many others.
!!! warning "Version Warning":
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
an SSO provider.
@ -33,7 +34,8 @@ section:
![Create APP](img/onelogin-saml-1.png)
!!! tip "Important":
!!! tip "Important"
Make sure to pick `SAML Test Connector (SP)` and not `SAML Test Connector (IdP)`,
because teleport only supports `SP` - service provider initiated SAML flows.
@ -50,7 +52,8 @@ exposed as SAML attribute statements:
![Configure APP](img/onelogin-saml-3.png)
![Configure APP](img/onelogin-saml-4.png)
!!! warning "Important":
!!! warning "Important"
Make sure to check `Include in SAML assertion` checkbox.
Add users to the application:
@ -90,7 +93,8 @@ To fill in the fields, open `SSO` tab:
* `issuer` - use value from `Issuer URL field`, e.g. `https://app.onelogin.com/saml/metadata/123456`
* `sso` - use the value from the value from field `SAML 2.0 Endpoint (HTTP)` but replace `http-post` with `http-redirect`, e.g. `https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456`
!!! tip "Important":
!!! tip "Important"
Make sure to replace `http-post` with `http-redirect`!
* `cert` - download certificate, by clicking "view details link" and add to `cert` section
@ -163,11 +167,13 @@ $ tsh --proxy=proxy.example.com login
This command will print the SSO login URL (and will try to open it
automatically in a browser).
!!! tip "Tip":
!!! tip "Tip"
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT":
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

12
docs/4.1/trustedclusters.md
View file

@ -27,7 +27,8 @@ This guide's focus is on more in-depth coverage of trusted clusters features and
* Enable/disable trust between clusters.
* Establish permissions mapping between clusters using Teleport roles.
!!! tip "Teleport Node Tunneling":
!!! tip "Teleport Node Tunneling"
If you have a large amount of devices on different networks, such as
managed IoT devices or a couple of nodes on a different network you can utilize
the [Teleport Node Tunneling](admin-guide.md#adding-a-node-located-behind-nat).
@ -89,7 +90,8 @@ This shared secret is called a "join token". There are two ways to create join
tokens: to statically define them in a configuration file, or to create them on
the fly using `tctl` tool.
!!! tip "Important":
!!! tip "Important"
It is important to realize that join tokens are only used to establish the
connection for the first time. The clusters will exchange certificates and
won't be using the token to re-establish the connection in the future.
@ -144,7 +146,8 @@ more complicated.
## RBAC
!!! warning "Version Warning":
!!! warning "Version Warning"
The RBAC section is applicable only to Teleport Enterprise. The open source
version does not support SSH roles.
@ -295,7 +298,8 @@ $ tsh ssh --cluster=east root@db1.east
```
!!! tip "Note":
!!! tip "Note"
Trusted clusters work only one way. So, in the example above users from "east"
cannot see or connect to the nodes in "main".

2
docs/4.1/user-manual.md
View file

@ -178,7 +178,7 @@ total 8.0K
### SSH Certificates for Automation
<!--This seems more like an admin task-->
<!-- This seems more like an admin task -->
Regular users of Teleport must request an auto-expiring SSH certificate, usually
every day. This doesn't work for non-interactive scripts, like cron jobs or

2
docs/4.2/admin-guide.md
View file

@ -936,6 +936,7 @@ Token 696c0471453e75882ff70a761c1a8bfa has been deleted
## Adding a node located behind NAT
!!! note
This feature is sometimes called "Teleport IoT" or node tunneling.
With the current setup, you've only been able to add nodes that have direct access to the
@ -1411,6 +1412,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.

4
docs/4.2/architecture/teleport-architecture-overview.md
View file

@ -76,6 +76,7 @@ The numbers correspond to the steps needed to connect a client to a node. These
steps are explained below the diagram.
!!! warning "Caution"
The teleport daemon calls services "roles" in the CLI
client. The `--roles` flag has no relationship to concept of User Roles or
permissions.
@ -89,7 +90,6 @@ steps are explained below the diagram.
!!! tip "Tip"
In the diagram above we show each Teleport service separately for
clarity, but Teleport services do not have to run on separate nodes.
Teleport can be run as a binary on a single-node cluster with no external
@ -107,7 +107,6 @@ steps are explained in detail below the diagram.
!!! note "Caution"
The Teleport Admin tool, `tctl` , must be physically present
on the same machine where Teleport Auth is running. Adding new nodes or
inviting new users to the cluster is only possible using this tool.
@ -175,7 +174,6 @@ sending the session history to the auth server to be stored.
!!! note "Note"
Teleport may also be configured to have the session recording
occur on the proxy, see [Audit Log](../admin-guide.md#audit-log) for more
information.

15
docs/4.2/architecture/teleport-auth.md
View file

@ -47,7 +47,7 @@ Authority. A certificate contains four important pieces of data:
Teleport uses SSH certificates to authenticate nodes and users within a cluster.
There are two CAs operating inside the Auth Server because nodes and users each
need their own certificates. <!--TODO: Why?-->
need their own certificates. <!-- TODO: Why? -->
* The **Node CA** issues certificates which identify a node (i.e. host, server,
computer). These certificates are used to add new nodes to a cluster and
@ -69,6 +69,7 @@ certificate on a node makes it a cluster member.
add`](../cli-docs.md#tctl-nodes-add).
!!! tip "Token TTL"
When using dynamic tokens, their default time to live (TTL) is 15
minutes, but it can be reduced (not increased) via
[`tctl nodes add --ttl`](../cli-docs.md#tctl-nodes-add) flag.
@ -82,8 +83,8 @@ certificate on a node makes it a cluster member.
![Node Authorization](../img/node_cluster_auth.svg)
All nodes in a cluster can connect to the [Auth Server's API](#auth-api)
<!--Docs about this--> implemented as an HTTP REST service running over the SSH
All nodes in a cluster can connect to the [Auth Server's API](#auth-api) <!-- Docs about this -->
implemented as an HTTP REST service running over the SSH
tunnel. This API connection is authenticated with the node certificate and the
encoded role is checked to enforce access control. For example, a client
connection using a certificate with only the `node` role won't be able to add
@ -110,7 +111,7 @@ by the system's SSH agent if it is running.
secure websocket session.
In addition to a user's identity, user certificates also contain user roles and
SSH options, like "permit-agent-forwarding" <!--TODO: link to config/set options here-->.
SSH options, like "permit-agent-forwarding" <!-- TODO: link to config/set options here -->.
This additional data is stored as a certificate extension and is protected by
the CA signature.
@ -140,8 +141,8 @@ administrator on one of a cluster's Auth Servers, the following happens:
1. A new certificate authority (CA) key is generated.
2. The old CA will be considered valid _alongside_ the new CA for some period of
time. This period of time is called a _grace period_. <!--TODO: Link to
config/defaults.-->
time. This period of time is called a _grace period_. <!-- TODO: Link to
config/defaults. -->
3. During the grace period, all previously issued certificates will be
considered valid, assuming their TTL isn't expired.
4. After the grace period is over, the certificates issued by the old CA are no
@ -154,7 +155,7 @@ learn how to do certificate rotation in practice.
## Auth API
<!--TODO: Can we say more about this, abstract of routes provided-->
<!-- TODO: Can we say more about this, abstract of routes provided -->
Clients can also connect to the auth API through the Teleport proxy to use a
limited subset of the API to discover the member nodes of the cluster.

3
docs/4.2/architecture/teleport-nodes.md
View file

@ -25,6 +25,7 @@ labels. Nodes can access the list of all Nodes in their cluster via the
[Auth Server API](teleport-auth.md#auth-api).
!!! tip "Tip"
In most environments we advise replacing the OpenSSH daemon `sshd`
with the Teleport Node Service unless there are existing workflows relying
on `ssh` or in special cases such as embedded devices that can't run
@ -115,7 +116,7 @@ Teleport Auth Service can allow 3rd party users or nodes to connect to cluster
nodes if their certificates are signed by a trusted CA. A "trusted cluster" is
a public key of the trusted CA. It can be configured via `teleport.yaml` file.
<!--TODO: incomplete, write more on this-->
<!-- TODO: incomplete, write more on this -->
## More Concepts

9
docs/4.2/architecture/teleport-users.md
View file

@ -1,6 +1,6 @@
## Teleport Users
<!--TODO: This doc is incomplete, pending addition of Enterprise topics-->
<!-- TODO: This doc is incomplete, pending addition of Enterprise topics -->
**Table of Contents**
@ -69,6 +69,7 @@ Teleport supports second factor authentication (2FA) when using a local auth
connector and it is enforced by default.
!!! info "2FA Support"
2FA is not supported with SSO providers such as Github or OKTA. To learn
more about SSO configuration check out the [SSO section of the Enterprise
Guide](../enterprise/index.md#sso)
@ -84,7 +85,7 @@ connector and it is enforced by default.
### External users
<!--TODO: Production topic-->
<!-- TODO: Production topic -->
External users are users stored elsewhere within an organization. Examples
include Github, Active Directory (AD), OIDC, or any identity store with an
@ -102,7 +103,7 @@ It is possible to have multiple identity sources configured for a Teleport
cluster. In this case, an identity source (called a "connector") will have to be
passed to [ `tsh --auth=connector_name login` ](../cli-docs.md#tsh-login).
<!--TODO: Production Configuration-->
<!-- TODO: Production Configuration -->
The local users connector can be specified via [`tsh --auth=local
login`](../cli-docs.md#tsh-login).
@ -114,7 +115,7 @@ roles allows Teleport to implement role-based access control (RBAC), i.e. assign
users to groups (roles) and restrict each role to a subset of actions on a
subset of nodes in a cluster.
<!--TODO: Enterprise Topic-->
<!-- TODO: Enterprise Topic -->
## More Concepts

9
docs/4.2/aws-terraform-guide.md
View file

@ -160,13 +160,14 @@ The AWS account ID which publishes these AMIs is `126027368216`. You can list th
the example `awscli` commands below. The output is in JSON format by default.
!!! tip "List Gravitational AMIs"
OSS AMIs<br>
OSS AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-oss*'`
Enterprise AMIs<br>
Enterprise AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-ent*'`
List Enterprise FIPS 140-2 AMIs<br>
List Enterprise FIPS 140-2 AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-ent*-fips'`
@ -528,6 +529,7 @@ $ tsh ssh root@ip-172-31-11-69-ec2-internal
### LetsEncrypt
!!! note
You are using LetsEncrypt if your `use_acm` variable is set to `"false"`.
#### Auth service
@ -618,6 +620,7 @@ $ journalctl -u teleport-node.service
### ACM
!!! note
You are using ACM if your `use_acm` variable is set to `"true"`.
When using ACM, the service name for the proxy is different (`teleport-proxy-acm.service` vs `teleport-proxy.service`).

58
docs/4.2/cli-docs.md
View file

@ -1,7 +1,7 @@
# CLI Docs
[teleport](#teleport)<br>
[tsh](#tsh)<br>
[teleport](#teleport)<br />
[tsh](#tsh)<br />
[tctl](#tctl)
## teleport
@ -33,7 +33,7 @@ the following services.
| `--ca-pin` | none | **string** `sha256:<hash>` | set CA pin to validate the Auth Server. Generated by `tctl status`
| `--nodename` | `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to login. By default it's equal to the value returned by
| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!--TODO link how to configure this file-->
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!-- TODO link how to configure this file -->
| `--labels` | none | **string** comma-separated list | assigns a set of labels to a node. See the explanation of labeling mechanism in the [Labeling Nodes](admin-guide.md#labeling-nodes) section.
| `--insecure` | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service.
| `--fips` | none | none | start Teleport in FedRAMP/FIPS 140-2 mode.
@ -55,7 +55,7 @@ only available from inside of a recorded SSH session.
standard output.
**Caution**: This sample config is _not_ the default config and should be used
for reference only.<!--TODO Link to Config Doc-->
for reference only.<!-- TODO Link to Config Doc -->
## teleport version
@ -63,8 +63,8 @@ for reference only.<!--TODO Link to Config Doc-->
## teleport help
`teleport help` shows help `teleport` and its subcommands like this `teleport
help <subcommand>`
`teleport help` shows help `teleport` and its subcommands like this
`teleport help <subcommand>`
# tsh
@ -79,7 +79,7 @@ information about the cluster.
| `-l, --login` | none | an identity name | the login identity that the Teleport User should use
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | set SSH proxy address
| `--user` | `$USER` | none | the Teleport User name
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!--TODO Check this-->
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!-- TODO Check this -->
| `-i, --identity` | none | **string** filepath | Identity file
| `--cert-format` | `file` | `file` or `openssh` | SSH certificate format
| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments
@ -216,7 +216,7 @@ tsh --proxy proxy.example.com play <session-id>
Copies files from source to dest
**Usage** `usage: tsh scp [<flags>] <source>... <dest>`
<!--TODO Confirm which flags are supported, and whether supports multiple sources-->
<!-- TODO Confirm which flags are supported, and whether supports multiple sources -->
### Arguments
@ -249,8 +249,8 @@ $ tsh --proxy=proxy.example.com scp -P example.txt user@host/destination/dir
List cluster nodes
**Usage** `usage: tsh ls [<flags>] [<label>]` <!--TODO: label? or labels? seems
like it only supports one label at a time-->
**Usage** `usage: tsh ls [<flags>] [<label>]` <!-- TODO: label? or labels? seems
like it only supports one label at a time -->
### Arguments
@ -452,8 +452,8 @@ Generates a user invitation token.
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -555,8 +555,8 @@ Generate a node invitation token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -583,8 +583,8 @@ List all active SSH nodes within the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
## tctl tokens add
@ -596,14 +596,14 @@ Create an invitation token
| Name | Default Value(s) | Allowed Value(s) | Description
|------|---------|----------------|----------------------------|
| `--type` | none | `trusted_cluster` , `node` , `signup` <!--TODO Confirm this.are any other types valid in /Users/heather/teleport/roles.go--> | Type of token to add
| `--type` | none | `trusted_cluster` , `node` , `signup` <!-- TODO Confirm this.are any other types valid in /Users/heather/teleport/roles.go --> | Type of token to add
| `--value` | none | **string** token value | Value of token to add
| `--ttl` | 1h | relative duration like 5s, 2m, or 3h, **maximum 48h** | Set expiration time for token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -659,8 +659,8 @@ Export public cluster (CA) keys to stdout
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -677,8 +677,7 @@ $ tctl auth export --type tls
Create an identity file(s) for a given user
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host
<host>][--format] [<flags>]`
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host <host>][--format] [<flags>]`
### Flags
@ -695,8 +694,8 @@ Create an identity file(s) for a given user
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -738,7 +737,8 @@ Rotate certificate authorities in the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -771,7 +771,8 @@ See the [Resource Guide](admin-guide.md#resources) for complete docs on how to b
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -826,7 +827,8 @@ Print a YAML declaration of various Teleport resources
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples

2
docs/4.2/enterprise/index.md
View file

@ -201,7 +201,7 @@ Assuming approval, `tsh` will automatically manage a certificate re-issued with
Granting a role with administrative abilities could allow a user to **permanently** upgrade their privileges (e.g. if contractor was granted admin for some reason). We recommend only escalating to the next role of least privilege vs jumping directly to "Super Admin" role.
The `deny.request` block can help mitigate the risk of doing this by accident.
The `deny.request` block can help mitigate the risk of doing this by accident.
### Other features of Approval Workflows.

6
docs/4.2/enterprise/ssh-fips.md
View file

@ -13,14 +13,14 @@ government agencies.
| Control | Teleport Features |
|----------|---------------------|
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br>• Control which SSH nodes a user can or cannot access. <br>• Control cluster level configuration (session recording, configuration, etc.) <br>• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br />• Control which SSH nodes a user can or cannot access. <br />• Control cluster level configuration (session recording, configuration, etc.) <br />• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-17 Remote Access](https://nvd.nist.gov/800-53/Rev4/control/AC-17) | Teleport administrators create users with configurable roles that can be used to allow or deny access to system resources. |
| [AC-20 Use of External Information Systems](https://nvd.nist.gov/800-53/Rev4/control/AC-20) | Teleport supports connecting multiple independent clusters using a feature called [Trusted Clusters](../trustedclusters/). When allowing access from one cluster to another, roles are mapped according to a pre-defined relationship of the scope of access.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../architecture/teleport-auth/#audit-log) that records cluster-wide events such as: <br>• Failed login attempts.<br>• Commands that were executed (SSH “exec” commands).<br> • Ports that were forwarded. <br>• File transfers that were initiated.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../architecture/teleport-auth/#audit-log) that records cluster-wide events such as: <br />• Failed login attempts.<br />• Commands that were executed (SSH “exec” commands).<br /> • Ports that were forwarded. <br />• File transfers that were initiated.|
| [AU-10 Non-Repudiation](https://nvd.nist.gov/800-53/Rev4/control/AU-10) | Teleport audit logging supports both events as well as audit of an entire SSH session. For non-repudiation purposes a full session can be replayed back and viewed. |
| [CM-08 Information System Component Inventory](https://nvd.nist.gov/800-53/Rev4/control/CM-8) | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time.|
| [IA-03 Device Identification and Authentication](https://nvd.nist.gov/800-53/Rev4/control/IA-3) | Teleport requires valid x509 or SSH certificates issued by a Teleport Certificate Authority (CA) to establish a network connection for device-to-device network connection between Teleport components. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br>Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br>In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br />Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br />In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
| [AC-2 Account Management](https://nvd.nist.gov/800-53/Rev4/control/AC-2) | Audit events are emitted in the auth server when a user is created, updated, deleted, locked or unlocked. |
| [AC-2 (12) Account Management](https://nvd.nist.gov/800-53/Rev4/control/AC-2) | At the close of a connection the total data transmitted and received is emitted to the Audit Log. |

1
docs/4.2/enterprise/sso/ssh-adfs.md
View file

@ -12,7 +12,6 @@ like:
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](../../admin-guide.md#github-oauth-20) as
an SSO provider.

1
docs/4.2/enterprise/sso/ssh-azuread.md
View file

@ -101,6 +101,7 @@ Create the connector using `tctl` tool:
```bsh
$ tctl create azure-connector.yaml
```
!!! tip "FYI"
Teleport will automatically transform the contents of the connector when viewed from the web UI.

1
docs/4.2/enterprise/sso/ssh-one-login.md
View file

@ -157,6 +157,7 @@ automatically in a browser).
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

4
docs/4.2/features/enhanced-session-recording.md
View file

@ -17,7 +17,7 @@ ability for users to disable terminal echo. This is frequently used when request
Furthermore, due to their unstructured nature, session recordings are difficult to
ingest and perform monitoring/alerting on.
!!! Note
!!! note
Enhanced Session Recording requires all parts of the Teleport system to be running
4.2+.
@ -46,7 +46,7 @@ Linux ip-172-31-43-104.ec2.internal 4.19.72-25.58.amzn2.x86_64 x86_64 x86_64 x86
|---------------|------------------------|
| 8.0-1905 | 4.18.0.80 ✅ |
!!! Note
!!! note
At release we've only production tested Enhanced Session recording with CentOS
7 and 8. We welcome feedback for other Operating Systems, and simply require a

2
docs/4.2/features/ssh-pam.md
View file

@ -244,7 +244,7 @@ session required pam_motd.so
session required pam_permit.so
```
!!! Note
!!! note
Pay attention to the inclusion of `pam_motd.so` under the `session` facility. While `pam_motd.so` is
not required for user creation, Teleport requires at least one module to be set under both

3
docs/4.2/installation.md
View file

@ -29,6 +29,7 @@ $ curl https://get.gravitational.com/teleport-$version-$os-$arch-bin.tar.gz.sha2
## Install Pre-built Binaries
!!! info "sudo"
You may need to use `sudo` to run the installation commands.
### Linux
@ -168,4 +169,4 @@ $ sudo chown $USER /var/lib/teleport
If the build succeeds, the binaries `teleport, tsh`, and `tctl` are now in the
directory `$GOPATH/src/github.com/gravitational/teleport/build`
<!--Notes on what to do if the build does not succeed, troubleshooting-->
<!-- Notes on what to do if the build does not succeed, troubleshooting -->

4
docs/4.2/production.md
View file

@ -36,9 +36,9 @@ Teleport services listen on several ports. This table shows the default port num
| 3023 | Proxy | SSH port clients connect to after authentication. A proxy will forward this connection to port `3022` on the destination node. | Allow inbound traffic from SSH clients. | Allow outbound traffic to SSH clients.
| 3022 | Node | SSH port to the Node Service. This is Teleport's equivalent of port `22` for SSH. | Allow inbound traffic from proxy host. | Allow outbound traffic to the proxy host.
| 3025 | Auth | SSH port used by the Auth Service to serve its Auth API to other nodes in a cluster. | Allow inbound connections from all cluster nodes. | Allow outbound traffic to cluster nodes.
| 3024 | Proxy | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server. | <TODO> | <TODO>
| 3024 | Proxy | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server. | <!-- TODO --> | <!-- TODO -->
<!--TODO: Add several diagrams of firewall config examples-->
<!-- TODO: Add several diagrams of firewall config examples -->
## Installation

3
docs/4.2/quickstart.md
View file

@ -23,6 +23,7 @@ This guide is only meant to demonstrate how to run Teleport in a sandbox or demo
environment, and showcase a few basic tasks you can do with Teleport. For additional configuration examples, see [teleport/examples](https://github.com/gravitational/teleport/tree/master/examples), within the Teleport Github repository.
!!! note "IMPORTANT"
You should not follow this guide if you want to set up Teleport in production. Instead follow the [Production Guide](production.md).
## Step 1: Install Teleport
@ -70,12 +71,14 @@ $ teleport start # if you are not `root` you may need `sudo`
```
!!! tip "Background Process"
Avoid suspending your current shell session by
running the process in the background like so:
`teleport start > teleport.log 2>&1 &`.
Access the process logs with `less teleport.log`.
!!! tip "Debugging/Verbose Output"
If you encounter errors with any `teleport`, `tsh` or `tctl`
command you can enable verbose logging with the `-d, --debug`
flag.

2
docs/4.2/user-manual.md
View file

@ -178,7 +178,7 @@ total 8.0K
### SSH Certificates for Automation
<!--This seems more like an admin task-->
<!-- This seems more like an admin task -->
Regular users of Teleport must request an auto-expiring SSH certificate, usually
every day. This doesn't work for non-interactive scripts, like cron jobs or

2
docs/4.3/admin-guide.md
View file

@ -689,6 +689,7 @@ Token 696c0471453e75882ff70a761c1a8bfa has been deleted
## Adding a node located behind NAT
!!! note
This feature is sometimes called "Teleport IoT" or node tunneling.
With the current setup, you've only been able to add nodes that have direct access to the
@ -1041,6 +1042,7 @@ $ tctl rm users/admin
```
!!! note
Although `tctl get connectors` will show you every connector, when working with an individual
connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each
connector's `kind` at the top of its YAML output from `tctl get connectors`.

2
docs/4.3/api-reference.md
View file

@ -9,7 +9,7 @@ Teleport is currently working on documenting our API.
!!! warning
We are currently working on this project. If you have an API suggestion, [please complete our survey](https://docs.google.com/forms/d/1HPQu5Asg3lR0cu5crnLDhlvovGpFVIIbDMRvqclPhQg/edit).
We are currently working on this project. If you have an API suggestion, [please complete our survey](https://docs.google.com/forms/d/1HPQu5Asg3lR0cu5crnLDhlvovGpFVIIbDMRvqclPhQg/edit).
## Authentication
In order to interact with the Access Request API, you will need to provision appropriate

15
docs/4.3/architecture/authentication.md
View file

@ -51,7 +51,7 @@ Authority. A certificate contains four important pieces of data:
Teleport uses SSH certificates to authenticate nodes and users within a cluster.
There are two CAs operating inside the Auth Server because nodes and users each
need their own certificates. <!--TODO: Why?-->
need their own certificates. <!-- TODO: Why? -->
* The **Node CA** issues certificates which identify a node (i.e. host, server,
computer). These certificates are used to add new nodes to a cluster and
@ -73,6 +73,7 @@ certificate on a node makes it a cluster member.
add`](../cli-docs.md#tctl-nodes-add).
!!! tip "Token TTL"
When using dynamic tokens, their default time to live (TTL) is 15
minutes, but it can be reduced (not increased) via
[`tctl nodes add --ttl`](../cli-docs.md#tctl-nodes-add) flag.
@ -86,8 +87,8 @@ certificate on a node makes it a cluster member.
![Node Authorization](../img/node_cluster_auth.svg)
All nodes in a cluster can connect to the [Auth Server's API](#auth-api)
<!--Docs about this--> implemented as an HTTP REST service running over the SSH
All nodes in a cluster can connect to the [Auth Server's API](#auth-api) <!-- Docs about this -->
implemented as an HTTP REST service running over the SSH
tunnel. This API connection is authenticated with the node certificate and the
encoded role is checked to enforce access control. For example, a client
connection using a certificate with only the `node` role won't be able to add
@ -113,7 +114,7 @@ by the system's SSH agent if it is running.
is associated with a secure websocket session.
In addition to a user's identity, user certificates also contain user roles and
SSH options, like "permit-agent-forwarding" <!--TODO: link to config/set options here-->.
SSH options, like "permit-agent-forwarding". <!-- TODO: link to config/set options here -->
This additional data is stored as a certificate extension and is protected by
the CA signature.
@ -142,8 +143,8 @@ administrator on one of a cluster's Auth Servers, the following happens:
1. A new certificate authority (CA) key is generated.
2. The old CA will be considered valid _alongside_ the new CA for some period of
time. This period of time is called a _grace period_. <!--TODO: Link to
config/defaults.-->
time. This period of time is called a _grace period_.
<!-- TODO: Link to config/defaults.-->
3. During the grace period, all previously issued certificates will be
considered valid, assuming their TTL isn't expired.
4. After the grace period is over, the certificates issued by the old CA are no
@ -156,7 +157,7 @@ learn how to do certificate rotation in practice.
## Auth API
<!--TODO: Can we say more about this, abstract of routes provided-->
<!-- TODO: Can we say more about this, abstract of routes provided -->
Clients can also connect to the auth API through the Teleport proxy to use a
limited subset of the API to discover the member nodes of the cluster.

3
docs/4.3/architecture/nodes.md
View file

@ -28,6 +28,7 @@ labels. Nodes can access the list of all Nodes in their cluster via the
[Auth Server API](authentication.md#auth-api).
!!! tip "Tip"
In most environments we advise replacing the OpenSSH daemon `sshd`
with the Teleport Node Service unless there are existing workflows relying
on `ssh` or in special cases such as embedded devices that can't run
@ -118,7 +119,7 @@ Teleport Auth Service can allow 3rd party users or nodes to connect to cluster
nodes if their certificates are signed by a trusted CA. A "trusted cluster" is
a public key of the trusted CA. It can be configured via `teleport.yaml` file.
<!--TODO: incomplete, write more on this-->
<!-- TODO: incomplete, write more on this -->
## More Concepts

3
docs/4.3/architecture/overview.md
View file

@ -77,6 +77,7 @@ The numbers correspond to the steps needed to connect a client to a node. These
steps are explained below the diagram.
!!! warning "Caution"
The teleport daemon calls services "roles" in the CLI
client. The `--roles` flag has no relationship to concept of User Roles or
permissions.
@ -90,7 +91,6 @@ steps are explained below the diagram.
!!! tip "Tip"
In the diagram above we show each Teleport service separately for
clarity, but Teleport services do not have to run on separate nodes.
Teleport can be run as a binary on a single-node cluster with no external
@ -108,7 +108,6 @@ steps are explained in detail below the diagram.
!!! note "Caution"
The Teleport Admin tool, `tctl` , must be physically present
on the same machine where Teleport Auth is running. Adding new nodes or
inviting new users to the cluster is only possible using this tool.

9
docs/4.3/architecture/users.md
View file

@ -5,7 +5,7 @@ description: This chapter explains the concept of a Teleport User and how it's d
# Teleport Users
<!--TODO: This doc is incomplete, pending addition of Enterprise topics-->
<!-- TODO: This doc is incomplete, pending addition of Enterprise topics -->
## Types of Users
@ -71,6 +71,7 @@ Teleport supports second factor authentication (2FA) when using a local auth
connector and it is enforced by default.
!!! info "2FA Support"
2FA is not supported with SSO providers such as Github or OKTA. To learn
more about SSO configuration check out the [SSO section of the Enterprise
Guide](/enterprise/introduction.md#sso)
@ -86,7 +87,7 @@ connector and it is enforced by default.
### External users
<!--TODO: Production topic-->
<!-- TODO: Production topic -->
External users are users stored elsewhere within an organization. Examples
include Github, Active Directory (AD), OIDC, or any identity store with an
@ -104,7 +105,7 @@ It is possible to have multiple identity sources configured for a Teleport
cluster. In this case, an identity source (called a "connector") will have to be
passed to [ `tsh --auth=connector_name login` ](../cli-docs.md#tsh-login).
<!--TODO: Production Configuration-->
<!-- TODO: Production Configuration -->
The local users connector can be specified via [`tsh --auth=local
login`](../cli-docs.md#tsh-login).
@ -116,7 +117,7 @@ roles allows Teleport to implement role-based access control (RBAC), i.e. assign
users to groups (roles) and restrict each role to a subset of actions on a
subset of nodes in a cluster.
<!--TODO: Enterprise Topic-->
<!-- TODO: Enterprise Topic -->
## More Concepts

9
docs/4.3/aws-terraform-guide.md
View file

@ -166,13 +166,14 @@ The AWS account ID which publishes these AMIs is `126027368216`. You can list th
the example `awscli` commands below. The output is in JSON format by default.
!!! tip "List Gravitational AMIs"
OSS AMIs<br>
OSS AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-oss*'`
Enterprise AMIs<br>
Enterprise AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-ent*'`
List Enterprise FIPS 140-2 AMIs<br>
List Enterprise FIPS 140-2 AMIs<br />
`aws ec2 describe-images --owners 126027368216 --filters 'Name=name,Values=gravitational-teleport-ami-ent*-fips'`
@ -534,6 +535,7 @@ $ tsh ssh root@ip-172-31-11-69-ec2-internal
### LetsEncrypt
!!! note
You are using LetsEncrypt if your `use_acm` variable is set to `"false"`.
#### Auth service
@ -624,6 +626,7 @@ $ journalctl -u teleport-node.service
### ACM
!!! note
You are using ACM if your `use_acm` variable is set to `"true"`.
When using ACM, the service name for the proxy is different (`teleport-proxy-acm.service` vs `teleport-proxy.service`).

52
docs/4.3/cli-docs.md
View file

@ -40,7 +40,7 @@ the following services.
| `--ca-pin` | none | **string** `sha256:<hash>` | set CA pin to validate the Auth Server. Generated by `tctl status`
| `--nodename` | `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to login. By default it's equal to the value returned by
| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!--TODO link how to configure this file-->
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources <!-- TODO link how to configure this file -->
| `--labels` | none | **string** comma-separated list | assigns a set of labels to a node. See the explanation of labeling mechanism in the [Labeling Nodes](admin-guide.md#labeling-nodes) section.
| `--insecure` | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service.
| `--fips` | none | none | start Teleport in FedRAMP/FIPS 140-2 mode.
@ -62,7 +62,7 @@ only available from inside of a recorded SSH session.
standard output.
**Caution**: This sample config is _not_ the default config and should be used
for reference only.<!--TODO Link to Config Doc-->
for reference only. <!-- TODO Link to Config Doc -->
## teleport version
@ -70,8 +70,8 @@ for reference only.<!--TODO Link to Config Doc-->
## teleport help
`teleport help` shows help `teleport` and its subcommands like this `teleport
help <subcommand>`
`teleport help` shows help `teleport` and its subcommands like this
`teleport help <subcommand>`
# tsh
@ -86,7 +86,7 @@ information about the cluster.
| `-l, --login` | none | an identity name | the login identity that the Teleport User should use
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | set SSH proxy address
| `--user` | `$USER` | none | the Teleport User name
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!--TODO Check this-->
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset <!-- TODO Check this -->
| `-i, --identity` | none | **string** filepath | Identity file
| `--cert-format` | `file` | `file` or `openssh` | SSH certificate format
| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments
@ -226,7 +226,7 @@ tsh --proxy proxy.example.com play <session-id>
Copies files from source to dest
**Usage** `usage: tsh scp [<flags>] <source>... <dest>`
<!--TODO Confirm which flags are supported, and whether supports multiple sources-->
<!-- TODO Confirm which flags are supported, and whether supports multiple sources -->
### Arguments
@ -259,8 +259,8 @@ $ tsh --proxy=proxy.example.com scp -P example.txt user@host/destination/dir
List cluster nodes
**Usage** `usage: tsh ls [<flags>] [<label>]` <!--TODO: label? or labels? seems
like it only supports one label at a time-->
**Usage** `usage: tsh ls [<flags>] [<label>]`
<!-- TODO: label? or labels? seems like it only supports one label at a time -->
### Arguments
@ -470,8 +470,8 @@ Generates a user invitation token.
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -573,8 +573,8 @@ Generate a node invitation token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -601,8 +601,8 @@ List all active SSH nodes within the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
## tctl tokens add
@ -620,8 +620,8 @@ Create an invitation token
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -677,8 +677,8 @@ Export public cluster (CA) keys to stdout
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -695,8 +695,7 @@ $ tctl auth export --type tls
Create an identity file(s) for a given user
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host
<host>][--format] [<flags>]`
**Usage**: `tctl auth sign -o <filepath> [--user <user> | --host <host>][--format] [<flags>]`
### Flags
@ -716,8 +715,8 @@ Create an identity file(s) for a given user
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help
<subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -768,7 +767,8 @@ Rotate certificate authorities in the cluster
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -801,7 +801,8 @@ See the [Resource Guide](admin-guide.md#resources) for complete docs on how to b
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples
@ -856,7 +857,8 @@ Print a YAML declaration of various Teleport resources
### [Global Flags](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run `tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)
### Examples

3
docs/4.3/enterprise/quickstart-enterprise.md
View file

@ -334,9 +334,11 @@ We provide pre-built Docker images for every version of Teleport Enterprise. The
We currently only offer Docker images for `x86_64` architectures.
!!! note
You will need a recent version of [Docker](https://hub.docker.com/search?q=&type=edition&offering=community) installed to follow this section of the quick start guide.
!!! warning
This setup will not let you 'SSH into' the node that is running Teleport without additional configuration.
### Pick your image
@ -357,6 +359,7 @@ For testing, we always recommend that you use the latest release version of Tele
### Quickstart using docker-compose
!!! note
You will need a recent version of [`docker-compose`](https://docs.docker.com/compose/install/) installed to follow this section of the quick start guide.
The easiest way to start Teleport Enterprise quickly is to use `docker-compose` with our [`teleport-ent-quickstart.yml`](https://github.com/gravitational/teleport/blob/master/docker/teleport-ent-quickstart.yml) file:

6
docs/4.3/enterprise/ssh-kubernetes-fedramp.md
View file

@ -17,14 +17,14 @@ government agencies.
| Control | Teleport Features |
|----------|---------------------|
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br>• Control which SSH nodes a user can or cannot access. <br>• Control cluster level configuration (session recording, configuration, etc.) <br>• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-03 Access Enforcement](https://nvd.nist.gov/800-53/Rev4/control/AC-3) | Teleport Enterprise supports robust [Role-based Access Controls (RBAC)](./ssh-rbac.md) to: <br />• Control which SSH nodes a user can or cannot access. <br />• Control cluster level configuration (session recording, configuration, etc.) <br />• Control which UNIX logins a user is allowed to use when logging into a server. |
| [AC-17 Remote Access](https://nvd.nist.gov/800-53/Rev4/control/AC-17) | Teleport administrators create users with configurable roles that can be used to allow or deny access to system resources. |
| [AC-20 Use of External Information Systems](https://nvd.nist.gov/800-53/Rev4/control/AC-20) | Teleport supports connecting multiple independent clusters using a feature called [Trusted Clusters](../../trustedclusters/). When allowing access from one cluster to another, roles are mapped according to a pre-defined relationship of the scope of access.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../../architecture/authentication/#audit-log) that records cluster-wide events such as: <br>• Failed login attempts.<br>• Commands that were executed (SSH “exec” commands).<br> • Ports that were forwarded. <br>• File transfers that were initiated.|
| [AU-03 Audit and Accountability](https://nvd.nist.gov/800-53/Rev4/control/AU-3) – Content of Audit Records and [AU-12 Audit Generation](https://nvd.nist.gov/800-53/Rev4/control/AU-12) | Teleport contains an [Audit Log](../../architecture/authentication/#audit-log) that records cluster-wide events such as: <br />• Failed login attempts.<br />• Commands that were executed (SSH “exec” commands).<br /> • Ports that were forwarded. <br />• File transfers that were initiated.|
| [AU-10 Non-Repudiation](https://nvd.nist.gov/800-53/Rev4/control/AU-10) | Teleport audit logging supports both events as well as audit of an entire SSH session. For non-repudiation purposes a full session can be replayed back and viewed. |
| [CM-08 Information System Component Inventory](https://nvd.nist.gov/800-53/Rev4/control/CM-8) | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time.|
| [IA-03 Device Identification and Authentication](https://nvd.nist.gov/800-53/Rev4/control/IA-3) | Teleport requires valid x509 or SSH certificates issued by a Teleport Certificate Authority (CA) to establish a network connection for device-to-device network connection between Teleport components. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br>Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br>In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
| [SC-12 Cryptographic Key Establish and Management](https://nvd.nist.gov/800-53/Rev4/control/SC-12) | Teleport initializes cryptographic keys that act as a Certificate Authority (CA) to further issue x509 and SSH certificates. SSH and x509 user certificates that are issued are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically (a manual force rotation can also be performed).<br />Teleport Enterprise builds against a FIPS 140-2 compliant library (BoringCrypto) is available. <br />In addition, when Teleport Enterprise is in FedRAMP/FIPS 140-2 mode, Teleport will only start and use FIPS 140-2 compliant cryptography. |
| [AC-2 Account Management](https://nvd.nist.gov/800-53/Rev4/control/AC-2) | Audit events are emitted in the auth server when a user is created, updated, deleted, locked or unlocked. |
| [AC-2 (12) Account Management](https://nvd.nist.gov/800-53/Rev4/control/AC-2) | At the close of a connection the total data transmitted and received is emitted to the Audit Log. |

1
docs/4.3/enterprise/sso/oidc.md
View file

@ -46,6 +46,7 @@ Add your OIDC connector information to `teleport.yaml`. A few examples are
provided below.
!!! tip
For Google / G Suite please follow our dedicated [Guide](ssh-gsuite.md)
## OIDC Redirect URL

1
docs/4.3/enterprise/sso/ssh-adfs.md
View file

@ -20,7 +20,6 @@ like:
!!! warning "Version Warning"
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](../../admin-guide.md#github-oauth-20) as
an SSO provider.

1
docs/4.3/enterprise/sso/ssh-one-login.md
View file

@ -171,6 +171,7 @@ automatically in a browser).
can be passed via `tsh login --auth=connector_name`
!!! note "IMPORTANT"
Teleport only supports sending party initiated flows for SAML 2.0. This
means you can not initiate login from your identity provider, you have to
initiate login from either the Teleport Web UI or CLI.

2
docs/4.3/enterprise/workflow/ssh-approval-jira-cloud.md
View file

@ -10,6 +10,7 @@ description: How to configure SSH login approval using Jira and Teleport
This guide will talk through how to setup Teleport with Jira. Teleport to Jira integration allows you to treat Teleport access and permission requests using Jira tickets.
!!! warning
The Approval Workflow only works with Teleport Enterprise as it requires several roles.
## Setup
@ -65,6 +66,7 @@ $ tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=8760h
The above sequence should result in three PEM encoded files being generated: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when [configuring the plugins](#configuration-file).
!!! note "Certificate Lifetime"
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
## Setting up your Jira Project

11
docs/4.3/enterprise/workflow/ssh-approval-jira-server.md
View file

@ -10,14 +10,16 @@ description: How to configure SSH login approval using Jira Server and Teleport
This guide will talk through how to setup Teleport with Jira Server. Teleport to Jira Server integration allows you to treat Teleport access and permission requests as Jira Tasks.
!!! warning
The Approval Workflow only works with Teleport Enterprise as it requires several roles.
!!! note
Teleport's tsh request workflow is synchronous and needs to be approved within 1 hour of the request.
<video style="width:100%" controls>
<source src="../../../img/enterprise/plugins/jira/jira-server.mp4" type="video/mp4">
<source src="../../../img/enterprise/plugins/jira/jira-server.webm" type="video/webm">
<video controls>
<source src="../../../img/enterprise/plugins/jira/jira-server.mp4" type="video/mp4" />
<source src="../../../img/enterprise/plugins/jira/jira-server.webm" type="video/webm" />
Your browser does not support the video tag.
</video>
@ -73,7 +75,8 @@ $ tctl auth sign --format=tls --user=access-plugin-jira --out=auth --ttl=8760h
The above sequence should result in three PEM encoded files being generated: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when [configuring the plugins](#configuration-file).
!!! note "Certificate Lifetime"
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
### Setting up your Jira Server instance

8
docs/4.3/enterprise/workflow/ssh-approval-mattermost.md
View file

@ -10,13 +10,14 @@ Mattermost integration allows teams to approve or deny Teleport access requests
using [Mattermost](https://mattermost.com/) an open source messaging platform.
!!! warning
The Approval Workflow only works with Teleport Enterprise as it requires several roles.
#### Example Mattermost Request
<video style="width:100%" controls>
<source src="../../../img/enterprise/plugins/mattermost/mattermost.mp4" type="video/mp4">
<source src="../../../img/enterprise/plugins/mattermost/mattermost.webm" type="video/webm">
<video controls>
<source src="../../../img/enterprise/plugins/mattermost/mattermost.mp4" type="video/mp4" />
<source src="../../../img/enterprise/plugins/mattermost/mattermost.webm" type="video/webm" />
Your browser does not support the video tag.
</video>
@ -98,6 +99,7 @@ $ tctl auth sign --format=tls --user=access-plugin-mattermost --out=auth --ttl=8
The above sequence should result in three PEM encoded files being generated: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when [configuring the plugins](#configuring-mattermost-bot).
!!! note "Certificate Lifetime"
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
## Downloading and installing the plugin

8
docs/4.3/enterprise/workflow/ssh-approval-pagerduty.md
View file

@ -13,6 +13,7 @@ requests as Pagerduty incidents — notifying the appropriate team, and approve
or deny the requests via Pagerduty special action.
!!! warning
The Approval Workflow only works with Teleport Enterprise as it requires several roles.
## Setup
@ -69,6 +70,7 @@ $ tctl auth sign --format=tls --user=access-plugin-pagerduty --out=auth --ttl=87
The above sequence should result in three PEM encoded files being generated: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when [configuring the plugins](#editing-the-config-file).
!!! note "Certificate Lifetime"
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
### Setting up Pagerduty API key
@ -145,9 +147,9 @@ Save this as `teleport-pagerduty.service`.
#### Example PagerDuty Request
<video style="width:100%" controls>
<source src="../../../img/enterprise/plugins/pagerduty/pagerduty-demo.mp4" type="video/mp4">
<source src="../../../img/enterprise/plugins/pagerduty/pagerduty-demo.webm" type="video/webm">
<video controls>
<source src="../../../img/enterprise/plugins/pagerduty/pagerduty-demo.mp4" type="video/mp4" />
<source src="../../../img/enterprise/plugins/pagerduty/pagerduty-demo.webm" type="video/webm" />
Your browser does not support the video tag.
</video>

13
docs/4.3/enterprise/workflow/ssh-approval-slack.md
View file

@ -7,13 +7,14 @@ description: This guide explains how to setup a Slack plugin for Teleport for pr
This guide will talk through how to setup Teleport with Slack. Teleport to Slack integration allows you to treat Teleport access and permission requests via Slack message and inline interactive components.
!!! warning
The Approval Workflow only works with Teleport Enterprise as it requires several roles.
#### Example Slack Request
<video style="width:100%" controls>
<source src="../../../img/enterprise/plugins/slack/slack.mp4" type="video/mp4">
<source src="../../../img/enterprise/plugins/slack/slack.webm" type="video/webm">
<video controls>
<source src="../../../img/enterprise/plugins/slack/slack.mp4" type="video/mp4" />
<source src="../../../img/enterprise/plugins/slack/slack.webm" type="video/webm" />
Your browser does not support the video tag.
</video>
@ -59,6 +60,7 @@ $ tctl create -f rscs.yaml
```
!!! tip
If you're using other plugins, you might want to create different users and roles for different plugins
#### Export access-plugin Certificate
@ -73,6 +75,7 @@ The above sequence should result in three PEM encoded files being generated: aut
!!! note "Certificate Lifetime"
By default, [`tctl auth sign`](https://gravitational.com/teleport/docs/cli-docs/#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
### Create Slack App
@ -90,8 +93,8 @@ You'll need to:
Visit [https://api.slack.com/apps](https://api.slack.com/apps) to create a new Slack App.
**App Name:** Teleport<br>
**Development Slack Workspace:** Pick the workspace you'd like the requests to show up in. </br>
**App Name:** Teleport<br />
**Development Slack Workspace:** Pick the workspace you'd like the requests to show up in. <br />
**App Icon:** <a href="https://gravitational.com/teleport/docs/img/enterprise/plugins/teleport_bot@2x.png" download>Download Teleport Bot Icon</a>
![Create Slack App](../../img/enterprise/plugins/slack/Create-a-Slack-App.png)

2
docs/4.3/features/enhanced-session-recording.md
View file

@ -23,7 +23,7 @@ ability for users to disable terminal echo. This is frequently used when request
Furthermore, due to their unstructured nature, session recordings are difficult to
ingest and perform monitoring/alerting on.
!!! Note
!!! note
Enhanced Session Recording requires all parts of the Teleport system to be running
4.2+.

Some files were not shown because too many files have changed in this diff Show more