diff --git a/docs/config.json b/docs/config.json index 0187ae18f88..fd30209b330 100644 --- a/docs/config.json +++ b/docs/config.json @@ -16,7 +16,6 @@ }, { "title": "Installation", "slug": "/installation/" }, { "title": "User Manual", "slug": "/user-manual/" }, - { "title": "Admin Manual", "slug": "/admin-guide/" }, { "title": "Production Guide", "slug": "/production/" }, { "title": "FAQ", "slug": "/faq/" }, { "title": "Changelog", "slug": "/changelog/" } @@ -49,6 +48,16 @@ { "title": "IBM", "slug": "/setup/deployments/ibm/" } ] }, + { + "title": "Operations", + "slug": "/setup/operations/", + "entries": [ + { "title": "Scaling", "slug": "/setup/operations/scaling/" }, + { "title": "Upgrading", "slug": "/setup/operations/upgrading/" }, + { "title": "Backup and Restore", "slug": "/setup/operations/backup-restore/" }, + { "title": "Cert Authority Rotation", "slug": "/setup/operations/ca-rotation/" } + ] + }, { "title": "Integrations", "slug": "/setup/guides/", @@ -67,7 +76,12 @@ { "title": "Config Resources", "slug": "/setup/reference/resources/" }, { "title": "Command Line", "slug": "/setup/reference/cli/" }, { "title": "Metrics", "slug": "/setup/reference/metrics/" }, - { "title": "Terraform Resources", "slug": "/setup/reference/terraform-provider/" } + { "title": "Terraform Resources", "slug": "/setup/reference/terraform-provider/" }, + { "title": "Audit Events and Records", "slug": "/setup/reference/audit/" }, + { "title": "Authentication", "slug": "/setup/reference/authentication/" }, + { "title": "Storage Backends", "slug": "/setup/reference/backends/" }, + { "title": "Networking", "slug": "/setup/reference/networking/" }, + { "title": "Enterprise License File", "slug": "/setup/reference/license/" } ] } ] @@ -102,6 +116,7 @@ "title": "Guides", "slug": "/server-access/guides/", "entries": [ + { "title": "Ansible", "slug": "/server-access/guides/ansible/" }, { "title": "Using Teleport with PAM", "slug": "/server-access/guides/ssh-pam/" }, { "title": "OpenSSH Guide", "slug": "/server-access/guides/openssh/" }, {"title": "BPF Session Recording", "slug": "/server-access/guides/bpf-session-recording/"}, @@ -350,6 +365,11 @@ } }, "redirects": [ + { + "source": "/admin-guide/", + "destination": "/setup/admin/", + "permanent": true + }, { "source": "/trustedclusters/", "destination": "/setup/admin/trustedclusters/", diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 37103cd4a77..9f218c522e6 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -14,7 +14,7 @@ that protects users against compromises of their on-disk Teleport certificates. Per-session U2F checks don't apply to regular Teleport logins (`tsh login` or logging into the Web UI). We encourage you to enable login MFA in your SSO provider and/or for all [local Teleport - users](../../admin-guide.mdx#local-connector). + users](../../setup/reference/authentication.mdx#local). diff --git a/docs/pages/access-controls/guides/u2f.mdx b/docs/pages/access-controls/guides/u2f.mdx index 879a17822c6..de63abe5da9 100644 --- a/docs/pages/access-controls/guides/u2f.mdx +++ b/docs/pages/access-controls/guides/u2f.mdx @@ -116,7 +116,7 @@ $ tsh login --proxy=example.com U2F for logging into Teleport is only required for [local -users](../../admin-guide.mdx#local-connector). SSO users should configure +users](../../setup/reference/authentication.mdx#local). SSO users should configure multi-factor authentication in their SSO provider. diff --git a/docs/pages/admin-guide.mdx b/docs/pages/admin-guide.mdx deleted file mode 100644 index fa8b19a3228..00000000000 --- a/docs/pages/admin-guide.mdx +++ /dev/null @@ -1,1183 +0,0 @@ ---- -title: Teleport Admin Manual -description: Admin manual for how to configure identity-aware SSH, certificate-based SSH authentication, set up SSO for SSH, SSO for Kubernetes, and more. ---- - -This manual covers the installation and configuration of Teleport and the ongoing management of a Teleport cluster. It assumes that the reader has a good understanding of Linux administration. - -## Definitions - -Before diving into configuring and running Teleport, it helps to take a look at the [Teleport Architecture](architecture/overview.mdx) and review the key concepts this document will be referring to: - -| Concept | Description | -| - | - | -| Node | Synonym to "server" or "computer", something one can "SSH to". A node must be running the [`teleport`](./setup/reference/cli.mdx#teleport) daemon with "node" role/service turned on. | -| Certificate Authority (CA) | A pair of public/private keys Teleport uses to manage access. A CA can sign a public key of a user or node, establishing their cluster membership. | -| Teleport Cluster | A Teleport Auth Service contains two CAs. One is used to sign user keys and the other signs node keys. A collection of nodes connected to the same CA is called a "cluster". | -| Cluster Name | Every Teleport cluster must have a name. If a name is not supplied via `teleport.yaml` configuration file, a GUID will be generated. **IMPORTANT:** renaming a cluster invalidates its keys and all certificates it had created. | -| Trusted Cluster | Teleport Auth Service can allow 3rd party users or nodes to connect 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. | - -### Ports - -Teleport services listen on several ports. This table shows the default port numbers. - -| Port | Service | Description | -| - | - | - | -| 3022 | Node | SSH port. This is Teleport's equivalent of port `#22` for SSH. | -| 3023 | Proxy | SSH port clients connect to. A proxy will forward this connection to port `#3022` on the destination node. | -| 3024 | Proxy | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server. | -| 3025 | Auth | SSH port used by the Auth Service to serve its API to other nodes in a cluster. | -| 3080 | Proxy | HTTPS connection to authenticate `tsh` users and web users into the cluster. The same connection is used to serve a Web UI. | -| 3026 | Kubernetes | HTTPS Kubernetes proxy `proxy_service.kube_listen_addr` | -| 3027 | Kubernetes | Kubernetes Service `kubernetes_service.listen_addr` | - -### Filesystem layout - -By default, a Teleport node has the following files present. The location of all -of them is configurable. - -| Full path | Purpose | -| - | - | -| `/etc/teleport.yaml` | Teleport configuration file (optional). | -| `/usr/local/bin/teleport` | Teleport daemon binary. | -| `/usr/local/bin/tctl` | Teleport admin tool. It is only needed for auth servers. | -| `/var/lib/teleport` | Teleport data directory. Nodes keep their keys and certificates there. Auth servers store the audit log and the cluster keys there, but the audit log storage can be further configured via `auth_service` section in the config file. | - -## Configuration - -You should use a [configuration file](#configuration-file) to configure the [`teleport`](setup/reference/cli.mdx#teleport) daemon. For simple experimentation, you can -use command line flags with the [`teleport start`](./setup/reference/cli.mdx#teleport-start) command. Read about all the allowed flags in the [CLI Docs](./setup/reference/cli.mdx#teleport-start) or run `teleport start --help` - -### Configuration File - -Teleport uses the YAML file format for configuration. A sample configuration -file is shown below. By default, it is stored in `/etc/teleport.yaml`, below is -an expanded and commented version from `teleport configure`. - -The default path Teleport uses to look for a config file is `/etc/teleport.yaml`. You can override -this path and set it explicitly using the `-c` or `--config` flag to `teleport start`: - -```code -sudo teleport start --config=/etc/teleport.yaml -``` - -For a complete reference, see our [Configuration Reference - teleport.yaml](./setup/reference/config.mdx#teleportyaml) - - - When editing YAML configuration, please pay attention to how your editor handles white space. YAML requires consistent handling of tab characters. - - -```yaml -# -# Sample Teleport configuration file -# Creates a single proxy, auth, and node server. -# -# Things to update: -# 1. ca_pin: Obtain the CA pin hash for joining more nodes by running 'tctl status' -# on the auth server once Teleport is running. -# 2. license-if-using-teleport-enterprise.pem: If you are an Enterprise customer, -# obtain this from https://dashboard.gravitational.com/web/login -# -teleport: - # nodename allows to assign an alternative name this node can be reached by. - # by default it's equal to hostname - nodename: NODE_NAME - data_dir: /var/lib/teleport - - # Invitation token used to join a cluster. it is not used on - # subsequent starts - auth_token: xxxx-token-xxxx - - # Optional CA pin of the auth server. This enables a more secure way of adding new - # nodes to a cluster. See "Adding Nodes to the Cluster" - # (https://goteleport.com/teleport/docs/admin-guide/#adding-nodes-to-the-cluster). - ca_pin: "sha256:ca-pin-hash-goes-here" - - # Auth Server address and port to connect to. If you configure teleport auth to run in High - # Availability configuration the address should point to a Load Balancer. - # If adding a node located behind NAT, use the Proxy URL. e.g. - # auth_servers: - # - teleport-proxy.example.com:443 - auth_servers: - - 10.1.0.5:3025 - - - # Logging configuration. Possible output values to disk via '/var/lib/teleport/teleport.log', - # 'stdout', 'stderr' and 'syslog'. Possible severity values are INFO, WARN - # and ERROR (default). - log: - output: stderr - severity: INFO - -auth_service: - enabled: "yes" - # A cluster name is used as part of a signature in certificates - # generated by this CA. - # - # We strongly recommend explicitly set it to something meaningful as it - # becomes important when configuring trust between multiple clusters. - # - # By default an automatically generated name is used (not recommended) - # - # IMPORTANT: if you change cluster_name, it will invalidate all generated - # certificates and keys (may need to wipe out /var/lib/teleport directory) - cluster_name: "teleport-aws-us-east-1" - - # IP and the port to bind to. Other Teleport nodes will be connecting to - # this port (AKA "Auth API" or "Cluster API") to validate client - # certificates - listen_addr: 0.0.0.0:3025 - - tokens: - - proxy,node:xxxx-token-xxxx - # license_file: /path/to/license-if-using-teleport-enterprise.pem - - authentication: - # Default authentication type. possible values are 'local' and 'github' for OSS - # and 'oidc', 'saml' and 'false' for Enterprise. - type: local - # second_factor can be off, on, optional, otp, or u2f - second_factor: otp - - # If running the auth service behind a load balancer, it is highly recommended to have the keepalive settings - # on your Teleport cluster match the value set on your load balancers. - # The default keep alive interval is 300 seconds. - keep_alive_interval: 1m - keep_alive_count_max: 3 - -ssh_service: - enabled: "yes" - labels: - teleport: static-label-example - commands: - - name: hostname - command: [/usr/bin/hostname] - period: 1m0s - - name: arch - command: [/usr/bin/uname, -p] - period: 1h0m0s -proxy_service: - enabled: "yes" - listen_addr: 0.0.0.0:3023 - web_listen_addr: 0.0.0.0:3080 - tunnel_listen_addr: 0.0.0.0:3024 - - # Expose a k8s listening port on the proxy if using Kubernetes - kube_listen_addr: 0.0.0.0:3026 - - # The DNS name of the proxy HTTPS endpoint as accessible by cluster users. - # Defaults to the proxy's hostname if not specified. If running multiple - # proxies behind a load balancer, this name must point to the load balancer - # See the "Public Addr" section for more details - # (https://goteleport.com/teleport/docs/admin-guide/#public-addr). - public_addr: TELEPORT_PUBLIC_DNS_NAME:3080 - - # TLS certificate for the HTTPS connection. Configuring these properly is - # critical for Teleport security. - https_keypairs: - - key_file: /var/lib/teleport/webproxy_key.pem - cert_file: /var/lib/teleport/webproxy_cert.pem -``` - -#### Public address - -Notice that all three Teleport services (proxy, auth, node) have an optional -`public_addr` property. The public address can take an IP or a DNS name. It can -also be a list of values: - -```yaml -public_addr: ["proxy-one.example.com", "proxy-two.example.com"] -``` - -Specifying a public address for a Teleport service may be useful in the -following use cases: - -- You have multiple identical services, like proxies, behind a load balancer. -- You want Teleport to issue an SSH certificate for the service with the additional - principals, e.g.host names. - -## Authentication - -Teleport uses the concept of "authentication connectors" to authenticate users -when they execute [`tsh login`](./setup/reference/cli.mdx#tsh-login) command. There are three -types of authentication connectors: - -### Local connector - -Local authentication is used to authenticate against a local Teleport user -database. This database is managed by [`tctl users`](./setup/reference/cli.mdx#tctl-users-add) -command. Teleport also supports second-factor authentication (2FA) for the local -connector. There are several possible values (types) of 2FA: - -- `otp` is the default. It implements [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) - standard. You can use [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) - or [Authy](https://www.authy.com/) or any other TOTP client. -- `u2f` implements the [U2F](https://en.wikipedia.org/wiki/Universal\_2nd_Factor) - standard for utilizing hardware (USB) keys for the second factor. You can use [YubiKeys](https://www.yubico.com/), - [SoloKeys](https://solokeys.com/) or any other hardware token which implements the FIDO U2F standard. -- `on` enables both TOTP and U2F, and all local users are required to have at least one 2FA device registered. -- `optional` enables both TOTP and U2F but makes it optional for users. Local users that register a 2FA device will be prompted for it during login. This option is useful when you need to gradually enable 2FA usage before switching the value to `on`. -- `off` turns off second-factor authentication. - -Here is an example of this setting in the `teleport.yaml` : - -```yaml -auth_service: - authentication: - type: local - second_factor: off -``` - - - SSO users can also register 2FA devices, but Teleport will not prompt them for 2FA during login. Login 2FA for SSO users should be handled by the SSO - provider. - - -### GitHub OAuth 2.0 connector - -This connector implements Github OAuth 2.0 authentication flow. Please refer to GitHub documentation on [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) -to learn how to create and register an OAuth app. - -Here is an example of this setting in the `teleport.yaml` : - -```yaml -auth_service: - authentication: - type: github -``` - -See [Github OAuth 2.0](./setup/admin/github-sso.mdx) for details on how to configure it. - -### SAML - -This connector type implements SAML authentication. It can be configured against any external identity manager like Okta or Auth0. This feature is only available for Teleport Enterprise. - -Here is an example of this setting in the `teleport.yaml` : - -```yaml -auth_service: - authentication: - type: saml -``` - -### OIDC - -Teleport implements OpenID Connect (OIDC) authentication, which is similar to SAML in principle. This feature is only available for Teleport Enterprise. - -Here is an example of this setting in the `teleport.yaml` : - -```yaml -auth_service: - authentication: - type: oidc -``` - - -## Audit Log - -Teleport logs every SSH event into its audit log. There are two components of -the audit log: - -1. **SSH Events:** Teleport logs events like successful user logins along with the metadata like remote IP address, time, and the session ID. -2. **Recorded Sessions:** Every SSH shell session is recorded and can be replayed later. The recording is done by the nodes themselves, by default, - but can be configured to be done by the proxy. -3. **Optional: [Enhanced Session Recording](./server-access/guides/bpf-session-recording.mdx)** - -Refer to the ["Audit Log" chapter in the Teleport -Architecture](architecture/authentication.mdx#audit-log) to learn more about how the Audit Log and Session Recording are designed. - -### Events - -Teleport supports multiple storage back-ends for storing the SSH, Application, and Kubernetes events. -The section below uses the `dir` backend as an example. `dir` backend uses the local -filesystem of an auth server using the configurable `data_dir` directory. - -For High Availability configurations, users can refer to our -[DynamoDB](#using-dynamodb) or [Firestore](#using-firestore) chapters for information -on how to configure the SSH events and recorded sessions to be stored on -network storage. It is even possible to store the audit log in multiple places at the -same time - see `audit_events_uri` setting in the sample configuration file above for -how to do that. - -Let's examine the Teleport audit log using the `dir` backend. The event log is -stored in `data_dir` under `log` directory, usually `/var/lib/teleport/log` . -Each day is represented as a file: - -```code -$ ls -l /var/lib/teleport/log/ - -# total 104 -# -rw-r----- 1 root root 31638 Jan 22 20:00 2017-01-23.00:00:00.log -# -rw-r----- 1 root root 91256 Jan 31 21:00 2017-02-01.00:00:00.log -# -rw-r----- 1 root root 15815 Feb 32 22:54 2017-02-03.00:00:00.log -``` - -The log files use JSON format. They are human-readable but can also be -programmatically parsed. Each line represents an event and has the following -format: - -```javascript -{ - // Event type. See below for the list of all possible event types - "event": "session.start", - // uid: A unique ID for the event log. Useful for deduplication. - "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef", - // Teleport user name - "user": "ekontsevoy", - // OS login - "login": "root", - // Server namespace. This field is reserved for future use. - "namespace": "default", - // Unique server ID. - "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f", - // Server Labels. - "server_labels": { - "datacenter": "us-east-1", - "label-b": "x" - } - // Session ID. Can be used to replay the session. - "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931", - // Address of the SSH node - "addr.local": "10.5.l.15:3022", - // Address of the connecting client (user) - "addr.remote": "73.223.221.14:42146", - // Terminal size - "size": "80:25", - // Timestamp - "time": "2017-02-03T06:54:05Z" -} -``` - -The possible event types are: - -| Event Type | Description | -| - | - | -| auth | Authentication attempt. Adds the following fields: `{"success": "false", "error": "access denied"}` | -| session.start | Started an interactive shell session. | -| session.end | An interactive shell session has ended. | -| session.join | A new user has joined the existing interactive shell session. | -| session.leave | A user has left the session. | -| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. | -| session.network | A list of network connections made during the session. *Requires Enhanced Session Recording*. | -| session.command | A list of commands ran during the session. *Requires Enhanced Session Recording*. | -| exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /`. The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` | -| scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` | -| resize | Terminal has been resized. | -| user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` . | -| app.session.start | A user accessed an application | -| app.session.chunk | A record of activity during an app session | - -### Recorded sessions - -In addition to logging `session.start` and `session.end` events, Teleport also records the entire stream of bytes going to/from standard input and standard the output of an SSH session. - -Teleport can store the recorded sessions in an [AWS S3 bucket](#using-dynamodb) -or in a local filesystem (including NFS). - -The recorded sessions are stored as raw bytes in the `sessions` directory under -`log`. Each session consists of two files, both are named after the session ID: - -1. `.bytes` file or `.chunks.gz` compressed format represents the raw session bytes and is somewhat - human-readable, although you are better off using [`tsh play`](./setup/reference/cli.mdx#tsh-play) - or the Web UI to replay it. -2. `.log` file or `.events.gz` compressed file contains the copies of the event log entries that are related to this session. - -```code -$ ls /var/lib/teleport/log/sessions/default -# -rw-r----- 1 root root 506192 Feb 4 00:46 4c146ec8-eab6-11e6-b1b3-40167e68e931.session.bytes -# -rw-r----- 1 root root 44943 Feb 4 00:46 4c146ec8-eab6-11e6-b1b3-40167e68e931.session.log -``` - -To replay this session via CLI: - -```code -$ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 -``` - - -## HTTP CONNECT proxies - -Some networks funnel all connections through a proxy server where they can be -audited and access control rules are applied. For these scenarios, Teleport supports HTTP CONNECT tunneling. - -To use HTTP CONNECT tunneling, simply set either the `HTTPS_PROXY` or `HTTP_PROXY` environment variables and when Teleport builds and establishes the reverse tunnel to the main cluster, it will funnel all traffic through the proxy. Specifically, if using the default configuration, Teleport will tunnel ports `3024` (SSH, reverse tunnel) and `3080` (HTTPS, establishing trust) through the proxy. - -The value of `HTTPS_PROXY` or `HTTP_PROXY` should be in the format -`scheme://host:port` where scheme is either `https` or `http` . If the value is -`host:port` , Teleport will prepend `http` . - -It's important to note that for Teleport to use HTTP CONNECT -tunneling, the `HTTP_PROXY` and `HTTPS_PROXY` environment variables must be set -within Teleport's environment. You can also optionally set the `NO_PROXY` -environment variable to avoid use of the proxy when accessing specified -hosts/netmasks. When launching Teleport with `systemd`, this will probably involve -adding some lines to your `systemd` unit file: - -``` -[Service] -Environment="HTTP_PROXY=http://proxy.example.com:8080/" -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" -``` - - - `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. - - -## Certificate rotation - -Take a look at the [Certificates chapter](architecture/authentication.mdx#authentication-in-teleport) in the -architecture document to learn how the certificate rotation works. This section -will show you how to implement certificate rotation in practice. - -The easiest way to start the rotation is to execute this command on a cluster's -*auth server*: - -```code -$ tctl auth rotate -``` - -This will trigger a rotation process for both hosts and users with a *grace -period* of 48 hours. - -This can be customized, i.e. - -```code -# Rotate only user certificates with a grace period of 200 hours: -$ tctl auth rotate --type=user --grace-period=200h - -# Rotate only host certificates with a grace period of 8 hours: -$ tctl auth rotate --type=host --grace-period=8h -``` - -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. - - - 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 come back only after the grace period has ended, they will be - forced to leave the cluster, i.e. users will no longer be allowed to SSH - into them. - - -To check the status of certificate rotation: - -```code -$ tctl status -``` - - - If you are using [CA Pinning](./setup/admin/adding-nodes.mdx#untrusted-auth-servers) when adding new nodes, the CA pin will change after the rotation. Make sure you use the - *new* CA pin when adding nodes after rotation. - - -## Storage backends - -A Teleport cluster stores different types of data in different locations. By -default everything is stored in a local directory at the Auth server. -Integration with other storage types is implemented based on the nature of the -stored data (size, read/write ratio, mutability, etc.). - -| Data type | Description | Supported storage backends | -| - | - | - | -| core cluster state | Cluster configuration (e.g. users, roles, auth connectors) and identity (e.g. certificate authorities, registered nodes, trusted clusters). | Local directory (SQLite), etcd, AWS DynamoDB, GCP Firestore | -| audit events | JSON-encoded events from the audit log (e.g. user logins, RBAC changes) | Local directory, AWS DynamoDB, GCP Firestore | -| session recordings | Raw terminal recordings of interactive user sessions | Local directory, AWS S3 (and any S3-compatible product), GCP Cloud Storage | -| teleport instance state | ID and credentials of a non-auth teleport instance (e.g. node, proxy) | Local directory | - -The [High Availability](#high-availability) section describes how to configure -non-default storage backends. - -## High Availability - - - Before continuing, please make sure to take a look at the [Cluster State section](architecture/nodes.mdx#cluster-state) - in the Teleport Architecture documentation. - - -Usually there are two ways to achieve High Availability. You can "outsource" -this function to the infrastructure. For example, using a highly available -network-based disk volumes (similar to AWS EBS) and by migrating a failed VM to -a new host. In this scenario, there's nothing Teleport-specific to be done. - -If High Availability cannot be provided by the infrastructure (perhaps you're -running Teleport on a bare metal cluster), you can still configure Teleport to -run in a highly available fashion. - -### Auth server High Availability - -To run multiple instances of Teleport Auth Server, you must switch to a High Availability secrets back-end first. Also, you must tell each node in a cluster that there is more than one auth server available. There are two ways to do this: - -- Use a load balancer to create a single auth API access point (AP) and specify this AP in `auth_servers` section of Teleport configuration for all nodes in a cluster. This load balancer should do TCP level forwarding. -- If a load balancer is not an option, you must specify each instance of an auth server in `auth_servers` section of Teleport configuration. - -**IMPORTANT:** with multiple instances of the auth servers running, special -attention needs to be paid to keeping their configuration identical. Settings -like `cluster_name` , `tokens` , `storage` , etc must be the same. - -### Teleport Proxy High Availability - -The Teleport Proxy is stateless which makes running multiple instances trivial. -If using the [default configuration](#ports), configure your load balancer to -forward ports `3023` and `3080` to the servers that run the Teleport proxy. If -you have configured your proxy to use non-default ports, you will need to -configure your load balancer to forward the ports you specified for -`listen_addr` and `web_listen_addr` in `teleport.yaml`. The load balancer for -`web_listen_addr` can terminate TLS with your own certificate that is valid 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. - - - If you terminate TLS with your own certificate at a load - balancer you'll need to run Teleport with `--insecure-no-tls` - - -If your load balancer supports HTTP health checks, configure it to hit the -`/readyz` [diagnostics endpoint](./setup/reference/metrics.mdx) on machines running Teleport. This endpoint -must be enabled by using the `--diag-addr` flag to teleport start: `teleport start --diag-addr=127.0.0.1:3000` -The [http://127.0.0.1:3000/readyz](http://127.0.0.1:3000/readyz) endpoint will reply `{"status":"ok"}` if the Teleport service -is running without problems. - - - 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. - - -We'll cover how to use `etcd`, DynamoDB, and Firestore storage back-ends to make Teleport -highly available below. - -### Teleport scalability tweaks - -When running Teleport at scale (for example in the case where there are 10,000+ nodes connected -to a cluster via [node tunneling mode](./setup/admin/adding-nodes.mdx#adding-a-node-located-behind-nat), the following settings -should be set on Teleport auth and proxies: - -#### Proxy servers - -These settings alter Teleport's [default connection limit](https://github.com/gravitational/teleport/blob/5cd212fecda63ec6790cc5ffe508a626c56e2b2c/lib/defaults/defaults.go#L385) from 15000 to 65000. - -```yaml -# Teleport Proxy -teleport: - cache: - # Use an in-memory cache to speed up the connection of many teleport nodes - # back to proxy. - type: in-memory - # Set up connection limits to prevent throttling of many IoT nodes connecting to proxies - connection_limits: - max_connections: 65000 - max_users: 1000 -``` - -#### Auth Servers - -```yaml -# Teleport Auth -teleport: - connection_limits: - max_connections: 65000 - max_users: 1000 -``` - -### Using etcd - -Teleport can use [etcd](https://etcd.io/) as a storage backend to -achieve highly available deployments. You must take steps to protect access to -`etcd` in this configuration because that is where Teleport secrets like keys -and user records will be stored. - - - `etcd` can only currently be used to store Teleport's internal database in a - highly-available way. This will allow you to have multiple auth servers in your - cluster for an High Availability deployment, but it will not also store Teleport audit events - for you in the same way that [DynamoDB](#using-dynamodb) or - [Firestore](#using-firestore) will. `etcd` is not designed to handle large volumes of time series data like audit events. - - -To configure Teleport for using etcd as a storage backend: - -- Make sure you are using **etcd versions 3.3** or newer. -- Install etcd and configure peer and client TLS authentication using the [etcd - security guide](https://etcd.io/docs/v3.4.0/op-guide/security/). - - You can use [this script provided by - etcd](https://github.com/etcd-io/etcd/tree/master/hack/tls-setup) if you - don't already have a TLS setup. -- Configure all Teleport Auth servers to use etcd in the "storage" section of the config file as shown below. -- Deploy several auth servers connected to etcd backend. -- Deploy several proxy nodes that have `auth_servers` pointed to the list of auth - servers to connect to. - -```yaml -teleport: - storage: - type: etcd - - # List of etcd peers to connect to: - peers: ["https://172.17.0.1:4001", "https://172.17.0.2:4001"] - - # Required path to TLS client certificate and key files to connect to etcd. - # - # To create these, follow - # https://coreos.com/os/docs/latest/generate-self-signed-certificates.html - # or use the etcd-provided script - # https://github.com/etcd-io/etcd/tree/master/hack/tls-setup. - tls_cert_file: /var/lib/teleport/etcd-cert.pem - tls_key_file: /var/lib/teleport/etcd-key.pem - - # Optional file with trusted CA authority - # file to authenticate etcd nodes - # - # If you used the script above to generate the client TLS certificate, - # this CA certificate should be one of the other generated files - tls_ca_file: /var/lib/teleport/etcd-ca.pem - - # Alternative password-based authentication, if not using TLS client - # certificate. - # - # See https://etcd.io/docs/v3.4.0/op-guide/authentication/ for setting - # up a new user. - username: username - password_file: /mnt/secrets/etcd-pass - - # etcd key (location) where teleport will be storing its state under. - # make sure it ends with a '/'! - prefix: /teleport/ - - # NOT RECOMMENDED: enables insecure etcd mode in which self-signed - # certificate will be accepted - insecure: false - - # Optionally sets the limit on the client message size. - # This is usually used to increase the default which is 2MiB - # (1.5MiB server's default + gRPC overhead bytes). - # Make sure this does not exceed the value for the etcd - # server specified with `--max-request-bytes` (1.5MiB by default). - # Keep the two values in sync. - # - # See https://etcd.io/docs/v3.4.0/dev-guide/limit/ for details - # - # This bumps the size to 15MiB as an example: - etcd_max_client_msg_size_bytes: 15728640 -``` - -### Using Amazon S3 - - - Before continuing, please make sure to take a look at the [Cluster State section](architecture/nodes.mdx#cluster-state) - in Teleport Architecture documentation. - - - - 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 use the instance IAM role. - Teleport also will pick up AWS credentials from the `~/.aws` folder, just like the AWS CLI tool. - - -S3 buckets can only be used as storage for the recorded sessions. S3 cannot -store the audit log or the cluster state. Below is an example of how to -configure a Teleport auth server to store the recorded sessions in an S3 bucket. - -```yaml -teleport: - storage: - # The region setting sets the default AWS region for all AWS services - # Teleport may consume (DynamoDB, S3) - region: us-east-1 - - # Path to S3 bucket to store the recorded sessions in. - audit_sessions_uri: "s3://Example_TELEPORT_S3_BUCKET/records" - - # Teleport assumes credentials. Using provider chains, assuming IAM role or - # standard .aws/credentials in the home folder. -``` - -The AWS authentication settings above can be omitted if the machine itself is -running on an EC2 instance with an IAM role. - -These optional `GET` parameters control how Teleport interacts with an S3 endpoint, including S3-compatible endpoints. - -`s3://bucket/path?region=us-east-1&endpoint=mys3.example.com&insecure=false&disablesse=false` - -- `region=us-east-1` - set the Amazon region to use. -- `endpoint=mys3.example.com` - connect to a custom S3 endpoint. -- `insecure=true` - set to `true` or `false`. If `true`, TLS will be disabled. -- `disablesse=true` - set to `true` or `false`. If `true`, S3 server-side encryption will be disabled. If `false`, aws:kms (Key Management Service) will be used for server-side encryption. Other SSE types are not supported at this time. - -### Using DynamoDB - - - Before continuing, please make sure to take a look at the [Cluster State section](architecture/nodes.mdx#cluster-state) - in Teleport Architecture documentation. - - -If you are running Teleport on AWS, you can use -[DynamoDB](https://aws.amazon.com/dynamodb/) as a storage back-end to achieve -High Availability. DynamoDB backend supports two types of Teleport data: - -- Cluster state -- Audit log events - -DynamoDB cannot store the recorded sessions. You are advised to use AWS S3 for -that as shown above. To configure Teleport to use DynamoDB: - -- Make sure you have AWS access key and a secret key that give you access to - DynamoDB account. If you're using (as recommended) an IAM role for this, the policy with the necessary permissions is listed below. -- Configure all Teleport Auth servers to use DynamoDB back-end in the "storage" - section of `teleport.yaml` as shown below. -- Deploy several auth servers connected to DynamoDB storage back-end. -- Deploy several proxy nodes. -- Make sure that all Teleport nodes have `auth_servers` configuration setting - populated with the auth servers. - -```yaml -teleport: - storage: - type: dynamodb - # Region location of dynamodb instance, https://docs.aws.amazon.com/en_pv/general/latest/gr/rande.html#ddb_region - region: us-east-1 - - # Name of the DynamoDB table. If it does not exist, Teleport will create it. - table_name: Example_TELEPORT_DYNAMO_TABLE_NAME - - # This setting configures Teleport to send the audit events to three places: - # To keep a copy in DynamoDB, a copy on a local filesystem, and also output the events to stdout. - # NOTE: The DynamoDB events table has a different schema to the regular Teleport - # database table, so attempting to use the same table for both will result in errors. - # When using highly available storage like DynamoDB, you should make sure that the list always specifies - # the High Availability storage method first, as this is what the Teleport web UI uses as its source of events to display. - audit_events_uri: ['dynamodb://events_table_name', 'file:///var/lib/teleport/audit/events', 'stdout://'] - - # This setting configures Teleport to save the recorded sessions in an S3 bucket: - audit_sessions_uri: s3://Example_TELEPORT_S3_BUCKET/records -``` - -- Replace `us-east-1` and `Example_TELEPORT_DYNAMO_TABLE_NAME` - with your own settings. Teleport will create the table automatically. -- `Example_TELEPORT_DYNAMO_TABLE_NAME` and `events_table_name` **must** be different - DynamoDB tables. The schema is different for each. Using the same table name for both will result in errors. -- The AWS authentication setting above can be omitted if the machine itself is running on an EC2 instance with an IAM role. -- Audit log settings above are optional. If specified, Teleport will store the - audit log in DynamoDB and the session recordings **must** be stored in an S3 - bucket, i.e. both `audit_xxx` settings must be present. If they are not set, - Teleport will default to a local file system for the audit log, i.e. - `/var/lib/teleport/log` on an auth server. -- 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. - - - Make sure that the IAM role assigned to - Teleport is configured with sufficient access to DynamoDB. Below is the - example of the IAM policy you can use: - - -```js -{ - "Version": "2012-10-17", - "Statement": [{ - "Sid": "AllAPIActionsOnTeleportAuth", - "Effect": "Allow", - "Action": "dynamodb:*", - "Resource": "arn:aws:dynamodb:eu-west-1:123456789012:table/prod.teleport.auth" - }, - { - "Sid": "AllAPIActionsOnTeleportStreams", - "Effect": "Allow", - "Action": "dynamodb:*", - "Resource": "arn:aws:dynamodb:eu-west-1:123456789012:table/prod.teleport.auth/stream/*" - } - ] -} -``` - -#### DynamoDB autoscaling - -When setting up DynamoDB it's important to set up backup and autoscaling. We make setup simpler by allowing AWS DynamoDB settings to be set automatically during Teleport startup. - -**DynamoDB Continuous Backups** - -- [AWS Blog Post - Amazon DynamoDB Continuous Backup](https://aws.amazon.com/blogs/aws/new-amazon-dynamodb-continuous-backups-and-point-in-time-recovery-pitr/) - -**DynamoDB Autoscaling Options** - -- [AWS Docs - Managing Throughput Capacity Automatically with DynamoDB Auto Scaling](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AutoScaling.html) - -```yaml -# ... -teleport: - storage: - type: "dynamodb" - [...] - - # continuous_backups is used to optionally enable continuous backups. - # default: false - continuous_backups: [true|false] - - # auto_scaling is used to optionally enable (and define settings for) auto scaling. - # default: false - auto_scaling: [true|false] - # Minimum/maximum read capacity in units - read_min_capacity: int - read_max_capacity: int - read_target_value: float - # Minimum/maximum write capacity in units - write_min_capacity: int - write_max_capacity: int - write_target_value: float -``` - -To enable these options you will need to update the IAM Role for Teleport. - -```json -{ - "Action": [ - "application-autoscaling:PutScalingPolicy", - "application-autoscaling:RegisterScalableTarget" - ], - "Effect": "Allow", - "Resource": "*" -}, -{ - "Action": [ - "iam:CreateServiceLinkedRole" - ], - "Condition": { - "StringEquals": { - "iam:AWSServiceName": [ - "dynamodb.application-autoscaling.amazonaws.com" - ] - } - }, - "Effect": "Allow", - "Resource": "*" -} -``` - -### Using GCS - - - Before continuing, please make sure to take a look at the [Cluster State section](architecture/nodes.mdx#cluster-state) - in Teleport Architecture documentation. - - -Google Cloud Storage (GCS) can only be used as storage for the recorded -sessions. GCS cannot store the audit log or the cluster state. Below is an -example of how to configure a Teleport auth server to store the recorded -sessions in a GCS bucket. - -```yaml -teleport: - storage: - # Path to GCS to store the recorded sessions in. - audit_sessions_uri: "gs://Example_TELEPORT_STORAGE/records" - credentials_path: /var/lib/teleport/gcs_creds -``` - -### Using Firestore - - - Before continuing, please make sure to take a look at the [Cluster State section](architecture/nodes.mdx#cluster-state) - in Teleport Architecture documentation. - - -If you are running Teleport on GCP, you can use -[Firestore](https://cloud.google.com/firestore/) as a storage back-end to achieve -high availability. Firestore backend supports two types of Teleport data: - -- Cluster state -- Audit log events - -Firestore cannot store the recorded sessions. You are advised to use Google -Cloud Storage (GCS) for that as shown above. To configure Teleport to use -Firestore: - -- Configure all Teleport Auth servers to use Firestore back-end in the "storage" - section of `teleport.yaml` as shown below. -- Deploy several auth servers connected to Firestore storage back-end. -- Deploy several proxy nodes. -- Make sure that all Teleport nodes have `auth_servers` configuration setting - populated with the auth servers or use a load balancer for the auth servers in - high availability mode. - -```yaml -teleport: - storage: - type: firestore - # Project ID https://support.google.com/googleapi/answer/7014113?hl=en - project_id: Example_GCP_Project_Name - - # Name of the Firestore table. If it does not exist, Teleport won't start - collection_name: Example_TELEPORT_FIRESTORE_TABLE_NAME - - credentials_path: /var/lib/teleport/gcs_creds - - # This setting configures Teleport to send the audit events to three places: - # To keep a copy in Firestore, a copy on a local filesystem, and also write the events to stdout. - # NOTE: The Firestore events table has a different schema to the regular Teleport - # database table, so attempting to use the same table for both will result in errors. - # When using highly available storage like Firestore, you should make sure that the list always specifies - # the High Availability storage method first, as this is what the Teleport web UI uses as its source of events to display. - audit_events_uri: ['firestore://Example_TELEPORT_FIRESTORE_EVENTS_TABLE_NAME', 'file:///var/lib/teleport/audit/events', 'stdout://'] - - # This setting configures Teleport to save the recorded sessions in GCP storage: - audit_sessions_uri: gs://Example_TELEPORT_S3_BUCKET/records -``` - -- Replace `Example_GCP_Project_Name` and `Example_TELEPORT_FIRESTORE_TABLE_NAME` - with your own settings. Teleport will create the table automatically. -- `Example_TELEPORT_FIRESTORE_TABLE_NAME` and `Example_TELEPORT_FIRESTORE_EVENTS_TABLE_NAME` - **must** be different Firestore tables. The schema is different for each. Using the same table name for both will result in errors. -- The GCP authentication setting above can be omitted if the machine itself is - running on a GCE instance with a Service Account that has access to the - Firestore table. -- Audit log settings above are optional. If specified, Teleport will store the audit log in Firestore and the session recordings **must** be stored in a GCP - bucket, i.e.both `audit_xxx` settings must be present. If they are not set, - Teleport will default to a local file system for the audit log, i.e. - `/var/lib/teleport/log` on an auth server. - -### Production releases - -First of all, avoid running pre-releases (release candidates) in production -environments. The Teleport development team uses [Semantic -Versioning](https://semver.org/) which makes it easy to tell if a specific -version is recommended for production use. - -### Component compatibility - -When running multiple binaries of Teleport within a cluster (nodes, proxies, -clients, etc), the following rules apply: - -**Before 5.0.0** - -- **Only patch** versions are always compatible, for example, any 4.0.1 component will work with any 4.0.3 component. -- Minor versions are always compatible with the **previous** minor release. This means you must not attempt to upgrade from 4.1.x straight to 4.3.x. You must upgrade to 4.2.x first. -- Teleport clients [`tsh`](./setup/reference/cli.mdx#tsh) for users and [`tctl`](./setup/reference/cli.mdx#tctl) for admins - may not be compatible with different versions of the `teleport` service. - -**After 5.0.0** - -- **Patch and minor** versions are always compatible, for example, any 5.0.1 component will work with any 5.0.3 component and 6.1.0 component will work with any 6.7.0 component. -- Major versions are always compatible with the **previous** major release. This means you must not attempt to upgrade from 5.x.x straight to 7.x.x. You must upgrade to 6.x.x first. -- The above applies to both clients and servers. For example, a 6.x.x proxy is - compatible with 5.x.x nodes and 5.x.x `tsh`. But we don't guarantee that a - 7.x.x `tsh` will work with a 5.x.x proxy. - -As an extra precaution, you might want to backup your application before upgrading. We provide more instructions in [Backup before upgrading](#backup-before-upgrading). - - - 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) - - If upgrading you might want to consider rotating CA to SHA-256 or SHA-512 for RSA - SSH certificate signatures. The previous default was SHA-1, which is now considered weak against brute-force attacks. SHA-1 certificate signatures are also no longer accepted by OpenSSH versions 8.2 and above. All new Teleport clusters will default - to SHA-512 based signatures. To upgrade an existing cluster, set the following in - your teleport.yaml: - - ```yaml - teleport: - ca_signature_algo: "rsa-sha2-512" - ``` - - After updating to 4.3+ rotate the cluster CA [following these docs](#certificate-rotation). - - -### Backup Before Upgrading - -As an extra precaution, you might want to backup your application before upgrading. We have more instructions in [Backing up Teleport](#backing-up-teleport). - -### Upgrade Sequence - -When upgrading a single Teleport cluster: - -1. **Upgrade the auth server first**. The auth server keeps the cluster state and if there are data format changes introduced in the new version this will perform necessary migrations. -2. Then, upgrade the proxy servers. The proxy servers are stateless and can be upgraded in any sequence or at the same time. -3. Finally, upgrade the SSH nodes in any sequence or at the same time. - - - If several auth servers are running in High Availability configuration - (for example, in AWS auto-scaling group) you have to shrink the group to - **just one auth server** before 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: - -1. First, upgrade the main cluster, i.e. the one which other clusters trust. -2. Upgrade the trusted clusters. - -## Backing up Teleport - -When planning a backup of Teleport, it's important to know what is where and the -importance of each component. Teleport's Proxies and Nodes are stateless, and thus -only `teleport.yaml` should be backed up. - -The Auth server is Teleport's brains, and depending on the backend should be backed up -regularly. - -For example, a customer running Teleport on AWS with DynamoDB have these key items of data: - -| What | Where ( Example AWS Customer ) | -| - | - | -| Local Users ( not SSO ) | DynamoDB | -| Certificate Authorities | DynamoDB | -| Trusted Clusters | DynamoDB | -| Connectors: SSO | DynamoDB / File System | -| RBAC | DynamoDB / File System | -| teleport.yaml | File System | -| teleport.service | File System | -| license.pem | File System | -| TLS key/certificate | ( File System / Outside Scope ) | -| Audit log | DynamoDB | -| Session recordings | S3 | - -For this customer, we would recommend using [AWS best practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) for backing up DynamoDB. If DynamoDB is used for -the audit log, logged events have a TTL of 1 year. - -| Backend | Recommended backup strategy | -| - | - | -| dir ( local filesystem ) | Backup `/var/lib/teleport/storage` directory and the output of `tctl get all --with-secrets`. | -| DynamoDB | [Follow AWS Guidelines for Backup & Restore](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) | -| etcd | [Follow etcD Guidleines for Disaster Recovery](https://etcd.io/docs/v2/admin_guide) | -| Firestore | [Follow GCP Guidlines for Automated Backups](https://firebase.google.com/docs/database/backups) | - -### Teleport resources - -Teleport uses YAML resources for roles, trusted clusters, local users, and auth connectors. -These could be created via `tctl` or the UI. - -## GitOps - -If you're running Teleport at scale, your teams need to have an automated way to restore Teleport. At a high level, this is our recommended approach: - -- Persist and backup your backend -- Share that backend among auth servers -- Store your configs as discrete files in VCS -- Have your CI run `tctl create -f *.yaml` from that git directory - -## Migrating backends - -As of version v4.1, you can now quickly export a collection of resources from -Teleport. This feature was designed to help customers migrate from local storage -to etcd. - -Using `tctl get all --with-secrets` will retrieve the below items: - -- Users -- Certificate Authorities -- Trusted Clusters -- Connectors: - - Github - - SAML \[Teleport Enterprise] - - OIDC \[Teleport Enterprise] - - Roles \[Teleport Enterprise] - -When migrating backends, you should back up your auth server's `data_dir/storage` directly. - -**Example of backing up and restoring a cluster.** - -```code -# Export dynamic configuration state from old cluster -$ tctl get all --with-secrets > state.yaml - -# Prepare a new uninitialized backend (make sure to port -# any non-default config values from the old config file) -$ mkdir fresh && cat > fresh.yaml << EOF -teleport: - data_dir: fresh -EOF - -# bootstrap fresh server (kill the old one first!) -$ sudo teleport start --config fresh.yaml --bootstrap state.yaml - -# from another terminal, verify state transferred correctly -$ tctl --config fresh.yaml get all -# -``` - -The `--bootstrap` flag has no effect, except during backend initialization (performed -by auth server on first start), so it is safe for use in supervised/High Availability contexts. - -**Limitations** - -- The `--bootstrap` flag doesn't re-trigger trusted cluster handshakes, so trusted cluster resources need to be recreated manually. -- All the same limitations around modifying the config file of an existing cluster also apply to a new cluster being bootstrapped from the state of an old cluster. Of particular note: - - Changing cluster name will break your CAs (this will be caught and teleport will refuse to start). - - Some user authentication mechanisms (e.g. u2f) require that the public endpoint of the web ui remains the same (this can't be caught by teleport, be careful!). -- Any node whose invite token is defined statically (in the config file of the auth server) will be able to join automatically, but nodes that were added dynamically will need to be re-invited - - -## License file - -Commercial Teleport subscriptions require a valid license. The license file can -be downloaded from the [Teleport Customer -Portal](https://dashboard.gravitational.com/web/login). - -The Teleport license file contains a X.509 certificate and the corresponding private key in PEM format. Place the downloaded file on Auth servers and set the `license_file` configuration parameter of your `teleport.yaml` to point to the file location: - -```yaml -auth_service: - license_file: /var/lib/teleport/license.pem -``` - -The `license_file` path can be either absolute or relative to the configured -`data_dir`. If the license file path is not set, Teleport will look for the -`license.pem` file in the configured `data_dir`. - - - Only Auth servers require the license. Proxies and Nodes that do not also have Auth role enabled do not need the license. - diff --git a/docs/pages/api/getting-started.mdx b/docs/pages/api/getting-started.mdx index 1ba694a72cc..2f7c5372413 100644 --- a/docs/pages/api/getting-started.mdx +++ b/docs/pages/api/getting-started.mdx @@ -115,4 +115,4 @@ $ go run main.go - Read about Teleport [API architecture](./architecture.mdx) for an in-depth overview of the API and API clients. - Read [API authorization](./architecture.mdx#authorization) to learn more about defining custom roles for your API client. - Review the `client` [pkg.go reference documentation](https://pkg.go.dev/github.com/gravitational/teleport/api/client) for more information about working with the Teleport API programmatically. -- Familiarize yourself with the [admin manual](../admin-guide.mdx) to make the best use of the API. +- Familiarize yourself with the [admin manual](../setup/admin.mdx) to make the best use of the API. diff --git a/docs/pages/architecture/authentication.mdx b/docs/pages/architecture/authentication.mdx index 28851efad7e..61d9e6a7a0e 100644 --- a/docs/pages/architecture/authentication.mdx +++ b/docs/pages/architecture/authentication.mdx @@ -129,7 +129,7 @@ administrator on one of a cluster's Auth Servers, the following happens: This process is repeated twice, once for the node CA and once for the user CA. -Take a look at the [Certificate Guide](../admin-guide.mdx#certificate-rotation) to +Take a look at the [Certificate Rotation Guide](../setup/operations/ca-rotation.mdx) to learn how to do certificate rotation in practice. ## Auth API @@ -144,8 +144,7 @@ Clients can also connect to the auth API through the Teleport proxy to use a lim The Auth service maintains state using a database of users, credentials, certificates, and audit logs. The default storage location is -`/var/lib/teleport` or an [admin-configured storage -destination](../admin-guide.mdx#high-availability). +`/var/lib/teleport` or an [admin-configured storage destination](../setup/reference/backends.mdx). There are three types of data stored by the auth server: @@ -155,7 +154,7 @@ There are three types of data stored by the auth server: - List of locally stored users - RBAC configuration (roles and permissions). - Other dynamic configuration. -- **Audit Log** When users log into a Teleport cluster, execute remote commands, and log out, that activity is recorded in the audit log. See Audit Log for more details. More on this in the [Audit Log section below](#audit-log). +- **Audit Log** When users log into a Teleport cluster, execute remote commands, and log out, that activity is recorded in the audit log. See Audit Log for more details. More on this in the [Audit Log section](../setup/reference/audit.mdx). - **Recorded Sessions** When Teleport users launch remote shells via `tsh ssh` command, their interactive sessions are recorded and stored by the auth server. Each recorded session is a file that is saved in /var/lib/teleport by default but can also be saved in external storage, like an AWS S3 bucket. ## Audit log @@ -179,7 +178,7 @@ events and submits them to the auth server. The events recorded include: Only an SSH server can report what's happening to the Teleport auth server. The audit log is a JSON file that is by default stored on the auth server's filesystem under `/var/lib/teleport/log`. The format of the file is documented -in the [Admin Manual](../admin-guide.mdx#audit-log). +in the [Admin Manual](../setup/reference/audit.mdx). Teleport users are encouraged to export the events into external, long term storage. @@ -191,7 +190,7 @@ storage. If multiple Teleport auth servers are used to service the same cluster (High Availability 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. [Learn how to deploy Teleport in High Availability Mode.](../admin-guide.mdx#high-availability). + same audit log. [Learn how to deploy Teleport in High Availability Mode.](../setup/reference/backends.mdx). ## Storage back-ends @@ -220,7 +219,7 @@ it allows them to run Teleport clusters completely devoid of local state. title="NOTE" > For High Availability in production, a Teleport cluster can be - serviced by multiple auth servers running in sync. Check [High Availability configuration](../admin-guide.mdx#high-availability) in the Admin Guide. + serviced by multiple auth servers running in sync. Check [High Availability configuration](../setup/reference/backends.mdx) in the Admin Guide. ## More concepts diff --git a/docs/pages/architecture/overview.mdx b/docs/pages/architecture/overview.mdx index 06fac980862..0f99afdf639 100644 --- a/docs/pages/architecture/overview.mdx +++ b/docs/pages/architecture/overview.mdx @@ -6,7 +6,7 @@ h1: Architecture Introduction This guide is for those looking for a deeper understanding of Teleport. If you are looking for hands-on instructions on how to set up Teleport for your team, -check out the [Admin Guide](../admin-guide.mdx) +check out the [Admin Guide](../setup/admin.mdx) ## What makes Teleport different @@ -184,7 +184,7 @@ sending the session history to the auth server to be stored. title="Note" > Teleport may also be configured to have the session recording - occur on the proxy, see [Audit Log](../admin-guide.mdx#audit-log) for more + occur on the proxy, see [Audit Reference](../setup/reference/audit.mdx) for more information. @@ -243,13 +243,13 @@ nodes and users in the cluster. `tctl` is also a tool that can be used to modify the dynamic configuration of the cluster, like creating new user roles or connecting trusted clusters. -You can learn more about `tctl` in the [Admin Manual](../admin-guide.mdx). +You can learn more about `tctl` in the [Admin Manual](../setup/admin.mdx). ## Next steps - If you haven't already, read the [Getting Started Guide](../getting-started.mdx) to run a minimal setup of Teleport yourself. -- Set up Teleport for your team with the [Admin Guide](../admin-guide.mdx). +- Set up Teleport for your team with the [Admin Guide](../setup/admin.mdx). Read the rest of the Architecture Guides: diff --git a/docs/pages/architecture/proxy.mdx b/docs/pages/architecture/proxy.mdx index 4eac29143ba..d4f8817a0d1 100644 --- a/docs/pages/architecture/proxy.mdx +++ b/docs/pages/architecture/proxy.mdx @@ -113,7 +113,7 @@ prevent sessions logs from reaching the Auth Service. With sessions recorded at the proxy, users with root privileges on Nodes have no way of disabling the audit. -See the [admin guide](../admin-guide.mdx#recorded-sessions) to learn how to turn +See the [reference](../setup/reference/audit.mdx#recorded-sessions) to learn how to turn on the recording proxy mode. Note that the recording mode is configured on the Auth Service. diff --git a/docs/pages/enterprise/getting-started.mdx b/docs/pages/enterprise/getting-started.mdx index 460bd743811..243bcb6468a 100644 --- a/docs/pages/enterprise/getting-started.mdx +++ b/docs/pages/enterprise/getting-started.mdx @@ -175,7 +175,7 @@ You can review the logs of the Teleport service with `journalctl -fu teleport` a with `sudo systemctl status teleport`. You can use `netstat -lptne` to review the port that Teleport is -listening on on [TCP/IP ports](../admin-guide.mdx#ports). On *auth.example.com*, it should +listening on on [TCP/IP ports](../setup/reference/networking.mdx#ports). On *auth.example.com*, it should look something like this: ```bsh diff --git a/docs/pages/enterprise/soc2.mdx b/docs/pages/enterprise/soc2.mdx index b8509602ceb..c984ecfe4bf 100644 --- a/docs/pages/enterprise/soc2.mdx +++ b/docs/pages/enterprise/soc2.mdx @@ -58,18 +58,18 @@ Each principle has many “Points of Focus” which will apply differently to di | CC6.3 - Removes Access to Protected Information Assets | Processes are in place to remove access to protected information assets when an individual no longer requires access. | Teleport uses temporary credentials and can be integrated with your version control system or even your HR system to [revoke access with the Access requests API](../api/introduction.mdx) | | CC6.3 - Uses Role-Based Access Controls | Role-based access control is utilized to support segregation of incompatible functions. | [Role based access control ("RBAC") allows Teleport administrators to grant granular access permissions to users.](../access-controls/introduction.mdx) | | CC6.3 - Reviews Access Roles and Rules | The appropriateness of access roles and access rules is reviewed on a periodic basis for unnecessary and inappropriate individuals with access and access rules are modified as appropriate. | 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. | -| CC6.6 - Restricts Access | The types of activities that can occur through a communication channel (for example, FTP site, router port) are restricted. | Teleport makes it easy to restrict access to common ports like 21, 22 and instead have users [tunnel to the server](../faq.mdx#can-i-connect-to-nodes-behind-a-firewall) using Teleport. [Teleport uses the following default ports.](../admin-guide.mdx#ports) | +| CC6.6 - Restricts Access | The types of activities that can occur through a communication channel (for example, FTP site, router port) are restricted. | Teleport makes it easy to restrict access to common ports like 21, 22 and instead have users [tunnel to the server](../faq.mdx#can-i-connect-to-nodes-behind-a-firewall) using Teleport. [Teleport uses the following default ports.](../setup/reference/networking.mdx#ports) | | CC6.6 - Protects Identification and Authentication Credentials | Identification and authentication credentials are protected during transmission outside system boundaries. | [Yes, Teleport protects credentials outside your network allowing for Zero Trust network architecture](https://goteleport.com/blog/applying-principles-of-zero-trust-to-ssh/) | | CC6.6 - Requires Additional Authentication or Credentials | Additional authentication information or credentials are required when accessing the system from outside its boundaries. | [Yes, Teleport can manage MFA with TOTP or U2F Standards or connect to your Identity Provider using SAML, OAUTH or OIDC](./sso.mdx) | | CC6.6 - Implements Boundary Protection Systems | Boundary protection systems (for example, firewalls, demilitarized zones, and intrusion detection systems) are implemented to protect external access points from attempts and unauthorized access and are monitored to detect such attempts. | [Trusted clusters](../setup/admin/trustedclusters.mdx) | | CC6.7 - Uses Encryption Technologies or Secure Communication Channels to Protect Data | Encryption technologies or secured communication channels are used to protect transmission of data and other communications beyond connectivity access points. | [Teleport has strong encryption including a FedRAMP compliant FIPS mode](./fedramp.mdx#starting-teleport-in-fips-mode) | -| CC7.2 - Implements Detection Policies, Procedures, and Tools | Processes are in place to detect changes to software and configuration parameters that may be indicative of unauthorized or malicious software. | [Teleport creates detailed SSH Audit Logs with Metadata](../admin-guide.mdx#audit-log) | [Use BPF Session Recording to catch malicious program execution](../server-access/guides/bpf-session-recording.mdx) | | | | +| CC7.2 - Implements Detection Policies, Procedures, and Tools | Processes are in place to detect changes to software and configuration parameters that may be indicative of unauthorized or malicious software. | [Teleport creates detailed SSH Audit Logs with Metadata](../setup/reference/audit.mdx) | [Use BPF Session Recording to catch malicious program execution](../server-access/guides/bpf-session-recording.mdx) | | | | | CC7.2 - Designs Detection Measures | Detection measures are designed to identify anomalies that could result from actual or attempted (1) compromise of physical barriers; (2) unauthorized actions of authorized personnel; (3) use of compromised identification and authentication credentials; (4) unauthorized access from outside the system boundaries; (5) compromise of authorized external parties; and (6) implementation or connection of unauthorized hardware and software. | [Use Enhanced Session Recording to catch malicious program execution, capture TCP connections and log programs accessing files on the system the should not be accessing.](../server-access/guides/bpf-session-recording.mdx) | | CC7.3 - Communicates and Reviews Detected Security Events | Detected security events are communicated to and reviewed by the individuals responsible for the management of the security program and actions are taken, if necessary. | [Use Session recording to replay and review suspicious sessions](../architecture/nodes.mdx#session-recording). | | CC7.3 - Develops and Implements Procedures to Analyze Security Incidents | Procedures are in place to analyze security incidents and determine system impact. | [Analyze detailed logs and replay recorded sessions to determine impact. See exactly what files were accessed during an incident.](../server-access/guides/bpf-session-recording.mdx) | | CC7.4 - Contains Security Incidents | Procedures are in place to contain security incidents that actively threaten entity objectives. | [Use Teleport to quickly revoke access and contain an active incident](../access-controls/guides/locking.mdx) | [Use Shared Sessions so Multiple On-Call Engineers can collaborate and fight fires together.](../user-manual.mdx#sharing-sessions) | | | | | CC7.4 - Ends Threats Posed by Security Incidents | Procedures are in place to mitigate the effects of ongoing security incidents. | [Use Teleport to quickly revoke access and contain an active incident](../access-controls/guides/locking.mdx) | -| CC7.4 - Obtains Understanding of Nature of Incident and Determines Containment Strategy | An understanding of the nature (for example, the method by which the incident occurred and the affected system resources) and severity of the security incident is obtained to determine the appropriate containment strategy, including (1) a determination of the appropriate response time frame, and (2) the determination and execution of the containment approach. | [Use Teleport’s Session Recording and Replay along with logs to understand what actions led to an incident.](../admin-guide.mdx#recorded-sessions) | +| CC7.4 - Obtains Understanding of Nature of Incident and Determines Containment Strategy | An understanding of the nature (for example, the method by which the incident occurred and the affected system resources) and severity of the security incident is obtained to determine the appropriate containment strategy, including (1) a determination of the appropriate response time frame, and (2) the determination and execution of the containment approach. | [Use Teleport’s Session Recording and Replay along with logs to understand what actions led to an incident.](../setup/reference/audit.mdx#recorded-sessions) | | CC7.4 - Evaluates the Effectiveness of Incident Response | The design of incident-response activities is evaluated for effectiveness on a periodic basis. | [Use audit logs and session recordings to find pain points in your incident response plan and improve effectiveness](../server-access/guides/bpf-session-recording.mdx). | | CC7.4 - Periodically Evaluates Incidents | Periodically, management reviews incidents related to security, availability, processing integrity, confidentiality, and privacy and identifies the need for system changes based on incident patterns and root causes. | [Use Session recording and audit logs to find patterns that lead to incidents.](../server-access/guides/bpf-session-recording.mdx) | | CC7.5 - Determines Root Cause of the Event | The root cause of the event is determined. | [Use Session recording and audit logs to find root cause.](../server-access/guides/bpf-session-recording.mdx) | diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index 2502138bf4e..db4c055f591 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -23,9 +23,7 @@ available unless the Teleport SSH daemon is present on all cluster nodes. ### Can I use OpenSSH with a Teleport cluster? Yes, this question comes up often and is related to the previous one. Take a -look at [Using OpenSSH client](user-manual.mdx#using-openssh-client) -section in the User Manual and [Using OpenSSH servers](admin-guide.mdx) in the -Admin Manual. +look at [Using OpenSSH Guide](./server-access/guides/openssh.mdx). ### Can I connect to nodes behind a firewall? @@ -118,17 +116,6 @@ Teleport provides three offerings: -### What are Teleport's scalability and hardware recommendations? - -We recommend setting up Teleport with a [High Availability configuration](admin-guide.mdx#high-availability). Below is our -recommended hardware for the Proxy and Auth server. If you plan to connect more than 10,000 nodes, please -[get in touch](mailto:info@goteleport.com) and we can help architect the best solution for you. - -| Scenario | Max Recommended Count | Proxy | Auth server | -| - | - | - | - | -| Teleport nodes connected to auth server | 10,000 | 2x 2-4 vCPUs/8GB RAM | 2x 4-8 vCPUs/16GB RAM | -| Teleport nodes connected to proxy server (IoT) | 2,000\* | 2x 2-4 vCPUs/8GB RAM | 2x 4-8 vCPUs/16+GB RAM | - ## Which version of Teleport is supported? Teleport provides security-critical support for the current and two previous releases. With our typical release cadence, this means a release is usually supported for 9 months. @@ -164,7 +151,7 @@ mode by pressing `[`. When in text selection mode: ### What TCP ports does Teleport use? -Please refer to the [Ports](admin-guide.mdx#ports) section of the Admin Manual. +Please refer to the [Ports](./setup/reference/networking.mdx) section of the Admin Manual. ### Does Teleport support authentication via OAuth, SAML, or Active Directory? diff --git a/docs/pages/getting-started/linux-server.mdx b/docs/pages/getting-started/linux-server.mdx index 3f4b2577df0..d2f8608a060 100644 --- a/docs/pages/getting-started/linux-server.mdx +++ b/docs/pages/getting-started/linux-server.mdx @@ -163,7 +163,7 @@ Here's a selection of compatible two-factor authentication apps: If you choose to use Homebrew, you must verify that the versions of `tsh` and `tctl` are compatible with the versions you run server-side. Homebrew usually ships the latest release of Teleport, which may be incompatible with older - versions. See our [compatibility policy](../admin-guide.mdx#component-compatibility) for details. + versions. See our [compatibility policy](../setup/operations/upgrading.mdx#component-compatibility) for details. @@ -311,7 +311,7 @@ Add a new application: Check out our collection of step-by-step guides for common Teleport tasks. - [Install Teleport](../installation.mdx) -- [Admin Guide](../admin-guide.mdx) +- [Admin Guides](../setup/admin.mdx) - [Share Sessions](../user-manual.mdx#sharing-sessions) - [Manage Users](../setup/admin/users.mdx) - [Github SSO](../setup/admin/github-sso.mdx) diff --git a/docs/pages/includes/database-access/rotation-note.mdx b/docs/pages/includes/database-access/rotation-note.mdx index 0422b5f52f5..c59915f4c75 100644 --- a/docs/pages/includes/database-access/rotation-note.mdx +++ b/docs/pages/includes/database-access/rotation-note.mdx @@ -1,5 +1,5 @@ Teleport signs database certificates with the host authority. As such, - when performing [host certificates rotation](../../admin-guide.mdx#certificate-rotation), + when performing [host certificates rotation](../../setup/operations/ca-rotation.mdx), the database certificates must be updated as well. diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 220f75872e9..704c0b13c08 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -68,10 +68,10 @@ Teleport is a Certificate Authority and an Access Plane for your infrastructure. Collaborate through session sharing. - + Discover servers and clusters with dynamic node labels. - + Connect to computing resources located behind firewalls or without static IPs. diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index ebdd0e76da4..3a8301c064b 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -121,7 +121,7 @@ $ helm install teleport teleport/teleport `tctl` are compatible with the versions you run server-side. Homebrew usually ships the latest release of Teleport, which may be incompatible with older versions. See our [compatibility - policy](admin-guide.mdx#component-compatibility) for details. + policy](./setup/operations/upgrading.mdx) for details. diff --git a/docs/pages/kubernetes-access/helm/reference.mdx b/docs/pages/kubernetes-access/helm/reference.mdx index b55eb4e7d50..e7f4ba61eac 100644 --- a/docs/pages/kubernetes-access/helm/reference.mdx +++ b/docs/pages/kubernetes-access/helm/reference.mdx @@ -325,7 +325,7 @@ You can set `volumeSize` to request a different size of persistent volume when i | Can be used in `custom` mode? | `teleport.yaml` equivalent | | - | - | -| ❌ | See [Using DynamoDB](../../admin-guide.mdx#using-dynamodb) and [Using Amazon S3](../../admin-guide.mdx#using-amazon-s3) for details | +| ❌ | See [Using DynamoDB](../../setup/reference/backends.mdx#dynamodb) and [Using Amazon S3](../../setup/reference/backends.mdx#s3) for details | `aws` settings are described in the AWS guide: [Running an HA Teleport cluster using an AWS EKS Cluster](./guides/aws.mdx) @@ -333,7 +333,7 @@ You can set `volumeSize` to request a different size of persistent volume when i | Can be used in `custom` mode? | `teleport.yaml` equivalent | | - | - | -| ❌ | See [Using Firestore](../../admin-guide.mdx#using-firestore) and [Using GCS](../../admin-guide.mdx#using-gcs) for details | +| ❌ | See [Using Firestore](../../setup/reference/backends.mdx#dynamodb) and [Using GCS](../../setup/reference/backends.mdx#gcs) for details | `gcp` settings are described in the GCP guide: [Running an HA Teleport cluster using a Google Cloud GKE cluster](./guides/gcp.mdx) diff --git a/docs/pages/preview/upcoming-releases.mdx b/docs/pages/preview/upcoming-releases.mdx index da07b4e763e..cb0ef7ce668 100644 --- a/docs/pages/preview/upcoming-releases.mdx +++ b/docs/pages/preview/upcoming-releases.mdx @@ -80,6 +80,6 @@ They are not ready for production: Releases are ready for production use. - Releases `5.0.0` and `6.0.0` are major releases. We publish 4 major releases each year. - Read more about upgrades and compatibility [here](../admin-guide.mdx#component-compatibility). + Read more about upgrades and compatibility [here](../setup/operations/upgrading.mdx). - Releases `5.1.0` are minor releases. They contain minor backwards-compatible improvements and backports. - Versions like `5.0.1` are quick patches. They contain backwards-compatible fixes. diff --git a/docs/pages/production.mdx b/docs/pages/production.mdx index b57984d73ad..a1a3dcbe488 100644 --- a/docs/pages/production.mdx +++ b/docs/pages/production.mdx @@ -74,8 +74,8 @@ In production, we recommend starting teleport daemon via an init system like `sy There are a couple of important things to notice about this file: -1. The start command in the unit file specifies `--config` as a file and there are very few flags passed to the `teleport` binary. Most of the configuration for Teleport should be done in the [configuration file](admin-guide.mdx#configuration). -2. The **ExecReload** command allows admins to run `systemctl reload teleport`. This will attempt to perform a graceful restart of Teleport **but it only works if network-based backend storage like [DynamoDB](admin-guide.mdx#using-dynamodb) or [etc 3.3](admin-guide.mdx#using-etcd) is configured**. Graceful Restarts will fork a new process to handle new incoming requests and leave the old daemon process running until existing clients disconnect. +1. The start command in the unit file specifies `--config` as a file and there are very few flags passed to the `teleport` binary. Most of the configuration for Teleport should be done in the [configuration file](./setup/reference/config.mdx). +2. The **ExecReload** command allows admins to run `systemctl reload teleport`. This will attempt to perform a graceful restart of Teleport **but it only works if network-based backend storage like [DynamoDB](./setup/reference/backends.mdx#dynamodb) or [etcd](./setup/reference/backends.mdx#etcd) is configured**. Graceful Restarts will fork a new process to handle new incoming requests and leave the old daemon process running until existing clients disconnect. ### Start the Teleport service @@ -192,12 +192,6 @@ setting up the proxy nodes start Teleport with: `teleport start --insecure --roles=proxy --config=/etc/teleport.yaml` -See [Teleport Proxy High Availability](admin-guide.mdx#teleport-proxy-high-availability) for more info. - -{ - /* TODO SSL for Webproxy & Auth Section */ -} - ### CA pinning Teleport nodes use the HTTPS protocol to offer the join tokens to the auth diff --git a/docs/pages/server-access/getting-started.mdx b/docs/pages/server-access/getting-started.mdx index 76baf43d9d6..4ea5d86a74d 100644 --- a/docs/pages/server-access/getting-started.mdx +++ b/docs/pages/server-access/getting-started.mdx @@ -334,7 +334,7 @@ Feel free to shut down, clean up, and delete your resources or use them in furth - Learn more about Teleport `tsh` through the [reference documentation](../setup/reference/cli.mdx#tsh-ssh). - Learn more about [Teleport Nodes](../architecture/nodes.mdx#connecting-to-nodes) -- For a complete list of ports used by Teleport, read [The Admin Guide](../admin-guide.mdx#ports). +- For a complete list of ports used by Teleport, read [The Admin Guide](../setup/reference/networking.mdx). ## Resources diff --git a/docs/pages/server-access/guides/bpf-session-recording.mdx b/docs/pages/server-access/guides/bpf-session-recording.mdx index 668834fbffb..f3a2c39d5f3 100644 --- a/docs/pages/server-access/guides/bpf-session-recording.mdx +++ b/docs/pages/server-access/guides/bpf-session-recording.mdx @@ -59,7 +59,7 @@ $ uname -r Follow our [installation instructions](../../installation.mdx) to install Teleport Auth, Proxy and Nodes. -Set up the Teleport node with this `etc/teleport.yaml`. See our [configuration file setup](../../admin-guide.mdx#configuration) for more instructions. +Set up the Teleport node with this `etc/teleport.yaml`. See our [configuration file setup](../../setup/reference/config.mdx) for more instructions. ```yaml # Example config to be saved as etc/teleport.yaml diff --git a/docs/pages/server-access/guides/openssh.mdx b/docs/pages/server-access/guides/openssh.mdx index 74dc9e8dea4..842b50884f3 100644 --- a/docs/pages/server-access/guides/openssh.mdx +++ b/docs/pages/server-access/guides/openssh.mdx @@ -57,7 +57,7 @@ Teleport OpenSSH supports: ## Set up OpenSSH recording proxy mode -The first step is install and setup Teleport, we recommend starting with our [Getting Started Guide](../../getting-started.mdx) and [Admin Manual](../../admin-guide.mdx). +The first step is install and setup Teleport, we recommend starting with our [Getting Started Guide](../../getting-started.mdx) and [Admin Manual](../../setup/admin.mdx). (!docs/pages/includes/permission-warning.mdx!) diff --git a/docs/pages/server-access/guides/restricted-session.mdx b/docs/pages/server-access/guides/restricted-session.mdx index 188083e32e6..7cc616d682f 100644 --- a/docs/pages/server-access/guides/restricted-session.mdx +++ b/docs/pages/server-access/guides/restricted-session.mdx @@ -50,7 +50,7 @@ Network restrictions work similar to a firewall but with several differences: Follow our [installation instructions](../../installation.mdx) to install Teleport Auth, Proxy and Nodes. -Set up the Teleport node with this `/etc/teleport.yaml`. See our [configuration file setup](../../admin-guide.mdx#configuration) for more instructions. +Set up the Teleport node with this `/etc/teleport.yaml`. See our [configuration file setup](../../setup/reference/config.mdx) for more instructions. Restricted Session requires Enhanced Recording to be enabled as well. This requirement will be removed in the future. diff --git a/docs/pages/server-access/guides/ssh-pam.mdx b/docs/pages/server-access/guides/ssh-pam.mdx index 59ccaf3d6d1..79909ce293d 100644 --- a/docs/pages/server-access/guides/ssh-pam.mdx +++ b/docs/pages/server-access/guides/ssh-pam.mdx @@ -307,7 +307,7 @@ biometrics. Note that Teleport enables strong SSH authentication out of the box using certificates. For most users, hardening [the initial Teleport -authentication](../../admin-guide.mdx#authentication) (e.g. `tsh login`) is preferred. +authentication](../../setup/reference/authentication.mdx) (e.g. `tsh login`) is preferred. By default, `auth` modules are not used to avoid the default system behavior (usually using local Unix passwords). You can enable them by setting diff --git a/docs/pages/setup/admin.mdx b/docs/pages/setup/admin.mdx index e41a88e125a..161e95bac35 100644 --- a/docs/pages/setup/admin.mdx +++ b/docs/pages/setup/admin.mdx @@ -4,23 +4,29 @@ description: Teleport Cluster Administration Guides. layout: tocless-doc --- - - - Setup single sign-on with Github. - - - How to add new nodes to the cluster. - - - Collect metrics and diagnostic information from Teleport. - - - Setup and configure Teleport Linux Daemon as as Systemd unit. - - - Send signals to configure and restart Teleport without loosing connections. - - - Connect multiple Teleport clusters using Trusted Clusters. - - +
    +
  • + [Github SSO](./admin/github-sso.mdx). Setup single sign-on with Github. +
    • +
  • + [Adding nodes](./admin/adding-nodes.mdx). How to add new nodes to the cluster. +
    • +
  • + [Trusted Clusters](./admin/trustedclusters.mdx). Connect multiple Teleport clusters using Trusted Clusters. +
    • +
  • + [Labels](./admin/labels.mdx). Manage nodes metadata with resource labels. +
    • +
  • + [Local Users](./admin/users.mdx). Manage local user accounts. +
    • +
  • + [Troubleshooting](./admin/troubleshooting.mdx). Collect metrics and diagnostic information from Teleport. +
    • +
  • + [Signals and Graceful Restarts](./admin/graceful-restarts.mdx). Send signals to configure and restart Teleport without loosing connections. +
    • +
  • + [Teleport Daemon](./admin/daemon.mdx). Setup and configure Teleport Linux Daemon as as Systemd unit. +
    • +
diff --git a/docs/pages/setup/deployments.mdx b/docs/pages/setup/deployments.mdx index 43577893c61..c400d4be4e0 100644 --- a/docs/pages/setup/deployments.mdx +++ b/docs/pages/setup/deployments.mdx @@ -4,14 +4,14 @@ description: Teleport Installation and Configuration Reference Deployment Guides layout: tocless-doc --- - - - Deploy HA Teleport with Terraform Provider on AWS. - - - Deploy HA Teleport on GCP. - - - Deploy HA Teleport on IBM cloud. - - +
    +
  • + [AWS Terraform](./deployments/aws-terraform.mdx). Deploy HA Teleport with Terraform Provider on AWS. +
    • +
  • + [GCP](./deployments/gcp.mdx). Deploy HA Teleport on GCP. +
    • +
  • + [IBM Cloud](./deployments/ibm.mdx). Deploy HA Teleport on IBM cloud. +
    • +
diff --git a/docs/pages/setup/deployments/aws-terraform.mdx b/docs/pages/setup/deployments/aws-terraform.mdx index ab8ffaea098..cffe8e67d0a 100644 --- a/docs/pages/setup/deployments/aws-terraform.mdx +++ b/docs/pages/setup/deployments/aws-terraform.mdx @@ -706,7 +706,7 @@ To add new nodes/EC2 servers that you can "SSH into" you'll need to: - [Install the Teleport binary on the Server](../../installation.mdx) - [Run Teleport - we recommend using systemd](../admin/daemon.mdx#systemd-unit-file) -- [Set the correct settings in /etc/teleport.yaml](../../admin-guide.mdx#configuration-file) +- [Set the correct settings in /etc/teleport.yaml](../reference/config.mdx) - [Add nodes to the Teleport cluster](../admin/adding-nodes.mdx#adding-nodes-to-the-cluster) ### Getting the CA pin hash diff --git a/docs/pages/setup/deployments/ibm.mdx b/docs/pages/setup/deployments/ibm.mdx index 1ecb6b0c7a1..5904f78e1d9 100644 --- a/docs/pages/setup/deployments/ibm.mdx +++ b/docs/pages/setup/deployments/ibm.mdx @@ -181,8 +181,7 @@ $ teleport start --config=/etc/teleport.yaml -d ### Network: IBM Cloud DNS Services We recommend using [IBM Cloud DNS](https://cloud.ibm.com/catalog/services/dns-services) for -the Teleport Proxy public address. See the [Admin Guide](../../admin-guide.mdx) for more -information. +the Teleport Proxy public address. ```yaml # The DNS name the proxy HTTPS endpoint as accessible by cluster users. diff --git a/docs/pages/setup/guides.mdx b/docs/pages/setup/guides.mdx index 537de37791a..3eaa8e95b5c 100644 --- a/docs/pages/setup/guides.mdx +++ b/docs/pages/setup/guides.mdx @@ -4,17 +4,17 @@ description: Teleport Installation and Configuration Guides. layout: tocless-doc --- - - - How to configure Teleport Cloud, Open Source, and Enterprise with Terraform Provider. - - - Getting started with Teleport Open Source using Docker. - - - Forwarding events with Fluentd and Teleport Events Handler. - - - How to setup Teleport node labels based on EC2 tags. - - +
    +
  • + [Terraform Provider](./guides/terraform-provider.mdx). How to configure Teleport Cloud, Open Source, and Enterprise with Terraform Provider. +
    • +
  • + [Docker](./guides/docker.mdx). Getting started with Teleport Open Source using Docker. +
    • +
  • + [Fluentd Event Forwarder](./guides/fluentd.mdx). Forwarding events with Fluentd and Teleport Events Handler. +
    • +
  • + [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to setup Teleport node labels based on EC2 tags. +
    • +
diff --git a/docs/pages/setup/operations.mdx b/docs/pages/setup/operations.mdx new file mode 100644 index 00000000000..d2ca5c5650a --- /dev/null +++ b/docs/pages/setup/operations.mdx @@ -0,0 +1,20 @@ +--- +title: Operations +description: Teleport Operations - Scaling and High-Availability. +layout: tocless-doc +--- + +
    +
  • + [Scaling](./operations/scaling.mdx). How to configure Teleport for large-scale deployments. +
    • +
  • + [Upgrading](./operations/upgrading.mdx). Learn about components version compatibility and upgrade sequence. +
    • +
  • + [Backup and Restore](./operations/backup-restore.mdx). Backing up and restoring the cluster. +
    • +
  • + [CA Rotation](./operations/ca-rotation.mdx). Rotating certificates and certificate authorities. +
    • +
diff --git a/docs/pages/setup/operations/backup-restore.mdx b/docs/pages/setup/operations/backup-restore.mdx new file mode 100644 index 00000000000..5b85fe3558a --- /dev/null +++ b/docs/pages/setup/operations/backup-restore.mdx @@ -0,0 +1,102 @@ +--- +title: Backup and Restore +description: How to backup and restore Teleport cluster state. +--- + +When planning a backup of Teleport, it's important to know what is where and the +importance of each component. Teleport's Proxies and Nodes are stateless, and thus +only `teleport.yaml` should be backed up. + +The Auth server is Teleport's brains, and depending on the backend should be backed up +regularly. + +For example, a customer running Teleport on AWS with DynamoDB have these key items of data: + +| What | Where ( Example AWS Customer ) | +| - | - | +| Local Users ( not SSO ) | DynamoDB | +| Certificate Authorities | DynamoDB | +| Trusted Clusters | DynamoDB | +| Connectors: SSO | DynamoDB / File System | +| RBAC | DynamoDB / File System | +| teleport.yaml | File System | +| teleport.service | File System | +| license.pem | File System | +| TLS key/certificate | ( File System / Outside Scope ) | +| Audit log | DynamoDB | +| Session recordings | S3 | + +For this customer, we would recommend using [AWS best practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) for backing up DynamoDB. If DynamoDB is used for +the audit log, logged events have a TTL of 1 year. + +| Backend | Recommended backup strategy | +| - | - | +| dir ( local filesystem ) | Backup `/var/lib/teleport/storage` directory and the output of `tctl get all --with-secrets`. | +| DynamoDB | [Follow AWS Guidelines for Backup & Restore](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) | +| etcd | [Follow etcD Guidleines for Disaster Recovery](https://etcd.io/docs/v2/admin_guide) | +| Firestore | [Follow GCP Guidlines for Automated Backups](https://firebase.google.com/docs/database/backups) | + +### Teleport resources + +Teleport uses YAML resources for roles, trusted clusters, local users, and auth connectors. +These could be created via `tctl` or the UI. + +## GitOps + +If you're running Teleport at scale, your teams need to have an automated way to restore Teleport. At a high level, this is our recommended approach: + +- Persist and backup your backend +- Share that backend among auth servers +- Store your configs as discrete files in VCS +- Have your CI run `tctl create -f *.yaml` from that git directory + +## Migrating backends + +As of version v4.1, you can now quickly export a collection of resources from +Teleport. This feature was designed to help customers migrate from local storage +to etcd. + +Using `tctl get all --with-secrets` will retrieve the below items: + +- Users +- Certificate Authorities +- Trusted Clusters +- Connectors: + - Github + - SAML \[Teleport Enterprise] + - OIDC \[Teleport Enterprise] + - Roles \[Teleport Enterprise] + +When migrating backends, you should back up your auth server's `data_dir/storage` directly. + +**Example of backing up and restoring a cluster.** + +```code +# Export dynamic configuration state from old cluster +$ tctl get all --with-secrets > state.yaml + +# Prepare a new uninitialized backend (make sure to port +# any non-default config values from the old config file) +$ mkdir fresh && cat > fresh.yaml << EOF +teleport: + data_dir: fresh +EOF + +# bootstrap fresh server (kill the old one first!) +$ sudo teleport start --config fresh.yaml --bootstrap state.yaml + +# from another terminal, verify state transferred correctly +$ tctl --config fresh.yaml get all +# +``` + +The `--bootstrap` flag has no effect, except during backend initialization (performed +by auth server on first start), so it is safe for use in supervised/High Availability contexts. + +**Limitations** + +- The `--bootstrap` flag doesn't re-trigger trusted cluster handshakes, so trusted cluster resources need to be recreated manually. +- All the same limitations around modifying the config file of an existing cluster also apply to a new cluster being bootstrapped from the state of an old cluster. Of particular note: + - Changing cluster name will break your CAs (this will be caught and teleport will refuse to start). + - Some user authentication mechanisms (e.g. u2f) require that the public endpoint of the web ui remains the same (this can't be caught by teleport, be careful!). +- Any node whose invite token is defined statically (in the config file of the auth server) will be able to join automatically, but nodes that were added dynamically will need to be re-invited diff --git a/docs/pages/setup/operations/ca-rotation.mdx b/docs/pages/setup/operations/ca-rotation.mdx new file mode 100644 index 00000000000..0d60d5c8763 --- /dev/null +++ b/docs/pages/setup/operations/ca-rotation.mdx @@ -0,0 +1,317 @@ +--- +title: Cert Authority Rotation +description: How to rotate Teleport's certificate authority +--- + +## Prerequisites + +- Installed [Teleport](../../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=) +- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=) + +(!docs/pages/includes/tctl.mdx!) + + +For cloud, login with a teleport user with editor privileges: +```code +# tsh logs you in and receives short-lived certificates +$ tsh login --proxy=myinstance.teleport.sh --user=email@example.com +# try out the connection +$ tctl get nodes +``` + + +## Certificate Authority Rotation + +Take a look at the [Certificates chapter](../../architecture/authentication.mdx#authentication-in-teleport) in the +architecture document to learn how the certificate authority rotation works. + +This section will show you how to implement certificate rotation in practice. + +During manual and semi-automatic certificate authority rotation, Teleport generates a new certificate +authority and issues certificates for auth servers, proxies, nodes and users. + +Rotation consists of several phases: + +- `standby` All operations have completed or haven't started yet. +- `init` - All components are notified of the rotation. A new certificate authority is issued, but not used. + It is necessary for remote trusted clusters to fetch the new certificate authority, otherwise the new clients + will reject it. +- `update_clients` - internal clients certs are updated and reloaded. + Servers will use and respond with old credentials because clients have no idea about new certificates at first. +- `update_servers` Servers will reload and would start serving +TLS and SSH certificates signed by the new certificate authority, but will still accept certificates +issued by old certificate authority. +- `rollback` rotation is rolling back to the old certificate authority. + +Both in manual and semi-automatic rotation, cluster goes through the states above in sequence: + +- `standby` -> `init` -> `update_clients` -> `update_servers` -> `standby` + +Administrators can rollback all the changes before rotation is completed by entering `standby`. + +For example, if admin has detected that some nodes failed to upgrade during `update_servers`, +they can rollback to the previous certificate authority: + +- `update_servers` -> `rollback` -> `standby`. + + +Try rotation/rollback in manual mode first to understand all the edge-cases +and gotchas before going with semi-automatic version. + + +## Manual rotation + +In manual mode, we would transition between phases while monitoring the state of the cluster. + +**Start the rotation** + +Initiate the manual rotation of host certificate authorities: + +```code +$ tctl auth rotate --phase=init --manual --type=host +Updated rotation phase to "init". To check status use 'tctl status' +``` + +Cluster status will reflect active rotation in progress: + +```code +$ tctl status +# Cluster acme.cluster +# Version (=teleport.version=) +# Host CA initialized (mode: manual, started: Sep 20 01:44:36 UTC, ending: Sep 21 07:44:36 UTC) +# User CA rotated Sep 20 01:42:54 UTC +# Jwt CA rotated Sep 20 01:42:54 UTC +# CA pin sha256:hash +``` + +Check the status of connected nodes: + +```code +# Check rotation status of the nodes +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "in_progress", + "phase": "init" +} +``` + +Host `terminal` has updated it status to phase `init`. It has downloaded a new CA public key and is ready +for state transitions. + + +If some nodes are offline during rotation or have failed to update the status, +you will loose connectivity after the transition `update_servers` -> `standby`. Make sure that all +nodes are up to date with the transitions. + + +**Update clients** + +Execute transition `init` -> `update_clients`: + +```code +$ tctl auth rotate --phase=update_clients --manual +# Updated rotation phase to "init". To check status use 'tctl status' +$ tctl status +# Cluster acme.cluster +# Version (=teleport.version=) +# Host CA rotating clients (mode: manual, started: Sep 20 01:44:36 UTC, ending: Sep 21 07:44:36 UTC) +``` + + +Clients will temporarily loose connectivity during proxy and auth servers restarts. + + +Verify that nodes have caught up and now see the current cluster state: + +```code +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "in_progress", + "phase": "update_clients" +} +``` + +**Update servers** + +All nodes have caught up. Execute the transition `update_clients` -> `update_servers`: + +```code +$ tctl auth rotate --phase=update_servers --manual +# Updated rotation phase to "init". To check status use 'tctl status' + +$ tctl status +# Cluster acme.cluster +# Version (=teleport.version=) +# Host CA rotating servers (mode: manual, started: Sep 20 01:44:36 UTC, ending: Sep 21 07:44:36 UTC) +``` + + +Usually if things go wrong, they go wrong at this transition. If you have lost connectivity to nodes, +[rollback](#rollback) to the old certificate authority. + + +Verify that nodes have caught up: + +```code +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "in_progress", + "phase": "update_servers" +} +``` + +**Finish the rotation** + +Before wrapping up, verify that you have not lost any nodes and can connect to them, for example: + +```code +$ tsh ssh hello@terminal hostname +``` + + +This is the last stage when you can rollback. If you have lost connectivity to nodes, +[rollback](#rollback) to the old certificate authority. + + +```code +$ tctl auth rotate --phase=standby --manual +# Updated rotation phase to "init". To check status use 'tctl status' + +$ tctl status +# Cluster acme.cluster +# Version (=teleport.version=) +# Host CA rotating servers (mode: manual, started: Sep 20 01:44:36 UTC, ending: Sep 21 07:44:36 UTC) +``` + +Cluster status should indicate succesffully completed rotation. + +```code +tctl status +Cluster acme.cluster +Version (=teleport.version=) +Host CA rotated Sep 20 02:11:25 UTC +User CA rotated Sep 20 01:42:54 UTC +Jwt CA rotated Sep 20 01:42:54 UTC +CA pin sha256:hash +``` + +Nodes should catch up and be on standby: + +```code +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "standby", + "phase": "standby" +} +``` + + +If you are using [CA Pinning](../admin/adding-nodes.mdx#untrusted-auth-servers) when adding new nodes, the CA pin will change after the rotation. +Make sure you use the *new* CA pin when adding nodes after rotation. + + +## Semi-Automatic rotation + + +Semi-automatic rotation executes the same steps as the manual rotation, but with a grace period between them. +It currently does not track the states of the nodes and you can loose connectivity if things go wrong. + + +You can trigger semi-automatic rotation: + +```code +$ tctl auth rotate +``` + +This will trigger a rotation process for both hosts and users with a *grace period* of 48 hours. +During the grace period, certificates issued both by old and new certificate authority work. + +You can customize grace period: + +```code +# Rotate only user certificates with a grace period of 200 hours: +$ tctl auth rotate --type=user --grace-period=200h + +# Rotate only host certificates with a grace period of 8 hours: +$ tctl auth rotate --type=host --grace-period=8h +``` + +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. + + + 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 come back only after the grace period has ended, they will be + forced to leave the cluster, i.e. users will no longer be allowed to SSH + into them. + + +Check the cluster status of rotation: + +```code +tctl status +Cluster acme.cluster +Version (=teleport.version=) +Host CA initialized (mode: manual, started: Sep 20 01:44:36 UTC, ending: Sep 21 07:44:36 UTC) +``` + + + If you are using [CA Pinning](../admin/adding-nodes.mdx#untrusted-auth-servers) when adding new nodes, the CA pin will change after the rotation. Make sure you use the + *new* CA pin when adding nodes after rotation. + + +Check the status of individual nodes: + +```code +# Check rotation status of the nodes +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "in_progress", + "phase": "init" +} +``` + +Host `terminal` has updated it status to phase `init`. It has downloaded a new CA public key and is ready +for state transitions. + +## Rollback + +Rollback is only possible before rotation enters `standby` state. + +First, override the rotation to the manual rollback: + +```code +$ tctl auth rotate --phase=rollback --manual +# Updated rotation phase to "rollback". To check status use 'tctl status' +``` + +Make sure that nodes that have updated have caught up: + +```code +# Check rotation status of the nodes +$ tctl get nodes --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}' +{ + "hostname": "terminal", + "rotation": "in_progress", + "phase": "rollback" +} +``` + +If any of the nodes were lost and using the old cert authority, they should reconnect +once you switch the control plane to the old cert authority. diff --git a/docs/pages/setup/operations/scaling.mdx b/docs/pages/setup/operations/scaling.mdx new file mode 100644 index 00000000000..e7fd3835342 --- /dev/null +++ b/docs/pages/setup/operations/scaling.mdx @@ -0,0 +1,66 @@ +--- +title: Scaling +description: How to configure Teleport for large-scale deployments +--- + +This section covers recommended configurations for large-scale +deployments of Teleport. + +## Prerequisites + +- Teleport v(=teleport.version=) Open Source or Enterprise. + +## Hardware recommendations + +Set up Teleport with a [High Availability configuration](../reference/backends.mdx). + +| Scenario | Max Recommended Count | Proxy | Auth server | AWS Instance Types | +| - | - | - | - | - | +| Teleport nodes connected to auth server. | 10,000 | 2x 4 vCPUs, 8GB RAM | 2x 8 vCPUs, 16GB RAM | m4.2xlarge | +| Teleport nodes connected to proxy server through reverse tunnels. | 2,000\* | 2x 4 vCPUs, 8GB RAM | 2x 8 vCPUs, 16+GB RAM | m4.2xlarge | + +## Proxy Configuration + +Upgrade Teleport's connection limits from default connection limit from `15000` to `65000` +and use in-memory cache instead of default SQLite persistent cache. + +```yaml +teleport: + cache: + # Use an in-memory cache to speed up the connection of many teleport nodes + # back to proxy. + type: in-memory + # Set up connection limits to prevent throttling of many nodes connecting to proxies + connection_limits: + max_connections: 65000 + max_users: 1000 +``` + +## Auth Configuration + +Upgrade Teleport's connection limits from default connection limit from `15000` to `65000`. + +```yaml +# Teleport Auth +teleport: + connection_limits: + max_connections: 65000 + max_users: 1000 +``` + +## Kernel parameters + +Tweak Teleport's systemd unit parameters to allow higher amount of open files: + +```txt +[Service] +LimitNOFILE=65536 +``` + +Verify that Teleport's process has high enough file limits: + +```code +$ cat /proc/$(pidof teleport)/limits +# Limit Soft Limit Hard Limit Units +# Max open files 65536 65536 files +``` diff --git a/docs/pages/setup/operations/upgrading.mdx b/docs/pages/setup/operations/upgrading.mdx new file mode 100644 index 00000000000..a50c7ed9cfc --- /dev/null +++ b/docs/pages/setup/operations/upgrading.mdx @@ -0,0 +1,91 @@ +--- +title: Upgrading +description: How to upgrade Teleport components +--- + +## Production releases + + +Avoid running pre-releases (release candidates) in production environments. + + +The Teleport development team uses [Semantic Versioning](https://semver.org/) which makes it easy to tell if a specific +version is recommended for production use. + +## Component compatibility + +When running multiple binaries of Teleport within a cluster (nodes, proxies, +clients, etc), the following rules apply: + +**Before 5.0.0** + +- **Only patch** versions are always compatible, for example, any 4.0.1 component will work with any 4.0.3 component. +- Minor versions are always compatible with the **previous** minor release. This means you must not attempt to upgrade from 4.1.x straight to 4.3.x. You must upgrade to 4.2.x first. +- Teleport clients [`tsh`](../reference/cli.mdx#tsh) for users and [`tctl`](../reference/cli.mdx#tctl) for admins + may not be compatible with different versions of the `teleport` service. + +**After 5.0.0** + +- **Patch and minor** versions are always compatible, for example, any 5.0.1 component will work with any 5.0.3 component and 6.1.0 component will work with any 6.7.0 component. +- Major versions are always compatible with the **previous** major release. This means you must not attempt to upgrade from 5.x.x straight to 7.x.x. You must upgrade to 6.x.x first. +- The above applies to both clients and servers. For example, a 6.x.x proxy is + compatible with 5.x.x nodes and 5.x.x `tsh`. But we don't guarantee that a + 7.x.x `tsh` will work with a 5.x.x proxy. + +## Backup + +Backup before upgrading. We have more instructions in [Backing up Teleport](./backup-restore.mdx). + +## Upgrade Sequence + +When upgrading a single Teleport cluster: + +1. **Upgrade the auth server first**. The auth server keeps the cluster state and if there are data format changes introduced in the new version this will perform necessary migrations. +2. Then, upgrade the proxy servers. The proxy servers are stateless and can be upgraded in any sequence or at the same time. +3. Finally, upgrade the SSH nodes in any sequence or at the same time. + + + If several auth servers are running in High Availability configuration + (for example, in AWS auto-scaling group) you have to shrink the group to + **just one auth server** before 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: + +1. First, upgrade the main cluster, i.e. the one which other clusters trust. +2. Upgrade the trusted clusters. + +## 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` + +Whenever Teleport is using those cipher suites, it will experience connectivity issues between components starting 4.0+. + +```yaml + # remove those two ciphersuites from the + ciphersuites: + - tls-rsa-with-aes-128-gcm-sha256 + - tls-rsa-with-aes-256-gcm-sha384 +``` + + +Rotate CA to `SHA-256` or `SHA-512` for RSA SSH certificate signatures. + +The previous default was `SHA-1`, which is now considered weak against brute-force attacks. +`SHA-1` certificate signatures are also no longer accepted by `OpenSSH` versions `8.2` and above. + +All new Teleport clusters will default to `SHA-512` based signatures. + +To upgrade an existing cluster, set the following in auth server's `teleport.yaml`: + +```yaml +teleport: + ca_signature_algo: "rsa-sha2-512" +``` + +Finally, rotate the cluster CA [following these docs](./ca-rotation.mdx). diff --git a/docs/pages/setup/reference.mdx b/docs/pages/setup/reference.mdx index 9d01088daec..b40e8f6f1e5 100644 --- a/docs/pages/setup/reference.mdx +++ b/docs/pages/setup/reference.mdx @@ -4,20 +4,38 @@ description: Teleport Installation and Configuration Reference. layout: tocless-doc --- - - - Dynamic cluster configuration resources. - - - Teleport daemon static configuration file. - - - Configuration resources and parameters supported by terraform provider. - - - Command line flags and parameters. - - - Prometheus metrics. - - +
    +
  • + [Config Resources](./reference/resources.mdx). Dynamic cluster configuration resources. +
    • +
  • + [Config File](./reference/config.mdx). Teleport daemon static configuration file. +
    • +
  • + [Terraform Provider](./reference/terraform-provider.mdx). Configuration resources and parameters supported by terraform provider. +
    • +
  • + [CLI](./reference/cli.mdx). Command line flags and parameters. +
    • +
  • + [Metrics](./reference/metrics.mdx). Prometheus metrics. +
    • +
  • + [Audit Records](./reference/audit.mdx). Audit events and records. +
    • +
  • + [Audit Records](./reference/audit.mdx). Audit events and records. +
    • +
  • + [Authentication](./reference/authentication.mdx). Cluster authentication options. +
    • +
  • + [Backends](./reference/backends.mdx). Supported storage backends. +
    • +
  • + [Networking](./reference/networking.mdx). Ports, protocols and networking requirements. +
    • +
  • + [License](./reference/license.mdx). Enterprise license file. +
    • +
diff --git a/docs/pages/setup/reference/audit.mdx b/docs/pages/setup/reference/audit.mdx new file mode 100644 index 00000000000..b9cac06cd1d --- /dev/null +++ b/docs/pages/setup/reference/audit.mdx @@ -0,0 +1,120 @@ +--- +title: Audit Events and Records +description: Reference of Teleport Audit Events and Session Records +--- + +Teleport logs every SSH event into its audit log. There are two components of +the audit log: + +1. **Cluster Events:** Teleport logs events like successful user logins along with the metadata like remote IP address, time, and the session ID. +2. **Recorded Sessions:** Every SSH or Kubernetes shell session is recorded and can be replayed later. The recording is done by the nodes themselves, by default, + but can be configured to be done by the proxy. +3. **Optional: [BPF Session Recording](../../server-access/guides/bpf-session-recording.mdx)** + +Refer to the ["Audit Log" chapter in the Teleport +Architecture](../../architecture/authentication.mdx#audit-log) to learn more about how the Audit Log and Session Recording are designed. + +## Events + +Teleport supports multiple storage back-ends for storing the SSH, Application, and Kubernetes events. +The section below uses the `dir` backend as an example. `dir` backend uses the local +filesystem of an auth server using the configurable `data_dir` directory. + +For High Availability configurations, users can refer to our +[DynamoDB](./backends.mdx#dynamodb) or [Firestore](./backends.mdx#firestore) chapters for information +on how to configure the SSH events and recorded sessions to be stored on +network storage. It is even possible to store the audit log in multiple places at the +same time - see `audit_events_uri` setting in the sample configuration file above for +how to do that. + +Let's examine the Teleport audit log using the `dir` backend. The event log is +stored in `data_dir` under `log` directory, usually `/var/lib/teleport/log` . +Each day is represented as a file: + +```code +$ ls -l /var/lib/teleport/log/ + +# total 104 +# -rw-r----- 1 root root 31638 Jan 22 20:00 2017-01-23.00:00:00.log +# -rw-r----- 1 root root 91256 Jan 31 21:00 2017-02-01.00:00:00.log +# -rw-r----- 1 root root 15815 Feb 32 22:54 2017-02-03.00:00:00.log +``` + +The log files use JSON format. They are human-readable but can also be +programmatically parsed. Each line represents an event and has the following +format: + +```javascript +{ + // Event type. See below for the list of all possible event types + "event": "session.start", + // uid: A unique ID for the event log. Useful for deduplication. + "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef", + // Teleport user name + "user": "ekontsevoy", + // OS login + "login": "root", + // Server namespace. This field is reserved for future use. + "namespace": "default", + // Unique server ID. + "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f", + // Server Labels. + "server_labels": { + "datacenter": "us-east-1", + "label-b": "x" + } + // Session ID. Can be used to replay the session. + "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931", + // Address of the SSH node + "addr.local": "10.5.l.15:3022", + // Address of the connecting client (user) + "addr.remote": "73.223.221.14:42146", + // Terminal size + "size": "80:25", + // Timestamp + "time": "2017-02-03T06:54:05Z" +} +``` + +The possible event types are: + +| Event Type | Description | +| - | - | +| auth | Authentication attempt. Adds the following fields: `{"success": "false", "error": "access denied"}` | +| session.start | Started an interactive shell session. | +| session.end | An interactive shell session has ended. | +| session.join | A new user has joined the existing interactive shell session. | +| session.leave | A user has left the session. | +| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. | +| session.network | A list of network connections made during the session. *Requires Enhanced Session Recording*. | +| session.command | A list of commands ran during the session. *Requires Enhanced Session Recording*. | +| exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /`. The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` | +| scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` | +| resize | Terminal has been resized. | +| user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` . | +| app.session.start | A user accessed an application | +| app.session.chunk | A record of activity during an app session | + +## Recorded sessions + +In addition to logging `session.start` and `session.end` events, Teleport also records the entire stream of bytes going to/from standard input and standard the output of an SSH session. + +Teleport can store the recorded sessions in an [AWS S3 bucket](./backends.mdx#s3) +or in a local filesystem (including NFS). + +The recorded sessions are stored as raw bytes in the `sessions` directory under +`log`. Each session is a binary protobuf-encoded stream of data. + +You can decode events using [`tsh play`](./cli.mdx#tsh-play) or the Web UI to replay it. + +For example, replay a session via CLI: + +```code +$ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 +``` + +Print the session events in json to stdout: + +```code +$ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json +``` diff --git a/docs/pages/setup/reference/authentication.mdx b/docs/pages/setup/reference/authentication.mdx new file mode 100644 index 00000000000..e1f54d28b2e --- /dev/null +++ b/docs/pages/setup/reference/authentication.mdx @@ -0,0 +1,114 @@ +--- +title: Authentication options +description: Teleport enterprise license file configuration parameters and requirements +--- + +Teleport uses the concept of "authentication connectors" to authenticate users +when they execute [`tsh login`](./cli.mdx#tsh-login) command. There are three +types of authentication connectors: + +## Local + +Local authentication is used to authenticate against a local Teleport user +database. This database is managed by [`tctl users`](./cli.mdx#tctl-users-add) +command. Teleport also supports second-factor authentication (2FA) for the local +connector. There are several possible values (types) of 2FA: + +- `otp` is the default. It implements [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) + standard. You can use [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) + or [Authy](https://www.authy.com/) or any other TOTP client. +- `u2f` implements the [U2F](https://en.wikipedia.org/wiki/Universal\_2nd_Factor) + standard for utilizing hardware (USB) keys for the second factor. You can use [YubiKeys](https://www.yubico.com/), + [SoloKeys](https://solokeys.com/) or any other hardware token which implements the FIDO U2F standard. +- `on` enables both TOTP and U2F, and all local users are required to have at least one 2FA device registered. +- `optional` enables both TOTP and U2F but makes it optional for users. Local users that register a 2FA device will be prompted for it during login. This option is useful when you need to gradually enable 2FA usage before switching the value to `on`. +- `off` turns off second-factor authentication. + + +You can modify these settings in the static config `teleport.yaml` or using dynamic configuration resources: + + + + ```yaml + auth_service: + authentication: + type: local + second_factor: off + ``` + + + Create a file `cap.yaml`: + ```yaml + kind: cluster_auth_preference + metadata: + name: cluster-auth-preference + spec: + type: local + u2f: + app_id: 'https://example.teleport.sh' + facets: + - 'https://example.teleport.sh:443' + - 'https://example.teleport.sh' + - 'example.teleport.sh' + version: v2 + ``` + + Create a resource: + + ```code + $ tctl create -f cap.yaml + ``` + + + + + SSO users can also register 2FA devices, but Teleport will not prompt them for 2FA during login. Login 2FA for SSO users should be handled by the SSO + provider. + + +## GitHub + +This connector implements Github OAuth 2.0 authentication flow. Please refer to GitHub documentation on [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) +to learn how to create and register an OAuth app. + +Here is an example of this setting in the `teleport.yaml` : + +```yaml +auth_service: + authentication: + type: github +``` + +See [Github OAuth 2.0](../admin/github-sso.mdx) for details on how to configure it. + +## SAML + + +You need Enterprise edition of Teleport for this option. + + +This connector type implements SAML authentication. It can be configured against any external identity manager like Okta or Auth0. This feature is only available for Teleport Enterprise. + +Here is an example of this setting in the `teleport.yaml` : + +```yaml +auth_service: + authentication: + type: saml +``` + +### OIDC + + +You need Enterprise edition of Teleport for this option. + + +Teleport implements OpenID Connect (OIDC) authentication, which is similar to SAML in principle. + +Here is an example of this setting in the `teleport.yaml` : + +```yaml +auth_service: + authentication: + type: oidc +``` diff --git a/docs/pages/setup/reference/backends.mdx b/docs/pages/setup/reference/backends.mdx new file mode 100644 index 00000000000..40841086205 --- /dev/null +++ b/docs/pages/setup/reference/backends.mdx @@ -0,0 +1,460 @@ +--- +title: Storage backends +description: How to configure Teleport deployment for high-availability using storage backends +--- + +A Teleport cluster stores different types of data in different locations. By +default everything is stored in a local directory at the Auth server. +Integration with other storage types is implemented based on the nature of the +stored data (size, read/write ratio, mutability, etc.). + +| Data type | Description | Supported storage backends | +| - | - | - | +| core cluster state | Cluster configuration (e.g. users, roles, auth connectors) and identity (e.g. certificate authorities, registered nodes, trusted clusters). | Local directory (SQLite), etcd, AWS DynamoDB, GCP Firestore | +| audit events | JSON-encoded events from the audit log (e.g. user logins, RBAC changes) | Local directory, AWS DynamoDB, GCP Firestore | +| session recordings | Raw terminal recordings of interactive user sessions | Local directory, AWS S3 (and any S3-compatible product), GCP Cloud Storage | +| teleport instance state | ID and credentials of a non-auth teleport instance (e.g. node, proxy) | Local directory | + + + Before continuing, please make sure to take a look at the [Cluster State section](../../architecture/nodes.mdx#cluster-state) + in the Teleport Architecture documentation. + + +There are two ways to achieve High Availability. You can "outsource" +this function to the infrastructure. For example, using a highly available +network-based disk volumes (similar to AWS EBS) and by migrating a failed VM to +a new host. In this scenario, there's nothing Teleport-specific to be done. + +If High Availability cannot be provided by the infrastructure (perhaps you're +running Teleport on a bare metal cluster), you can still configure Teleport to +run in a highly available fashion. + +## Auth Server State + +To run multiple instances of Teleport Auth Server, you must switch to a High Availability secrets back-end first. Also, you must tell each node in a cluster that there is more than one auth server available. There are two ways to do this: + +- Use a load balancer to create a single auth API access point (AP) and specify this AP in `auth_servers` section of Teleport configuration for all nodes in a cluster. This load balancer should do TCP level forwarding. +- If a load balancer is not an option, you must specify each instance of an auth server in `auth_servers` section of Teleport configuration. + +**IMPORTANT:** with multiple instances of the auth servers running, special +attention needs to be paid to keeping their configuration identical. Settings +like `cluster_name` , `tokens` , `storage` , etc must be the same. + +## Proxy State + +The Teleport Proxy is stateless which makes running multiple instances trivial. +If using the [default configuration](./networking.mdx), configure your load balancer to +forward ports `3023` and `3080` to the servers that run the Teleport proxy. If +you have configured your proxy to use non-default ports, you will need to +configure your load balancer to forward the ports you specified for +`listen_addr` and `web_listen_addr` in `teleport.yaml`. The load balancer for +`web_listen_addr` can terminate TLS with your own certificate that is valid 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. + + + If you terminate TLS with your own certificate at a load + balancer you'll need to run Teleport with `--insecure-no-tls` + + +If your load balancer supports HTTP health checks, configure it to hit the +`/readyz` [diagnostics endpoint](../reference/metrics.mdx) on machines running Teleport. This endpoint +must be enabled by using the `--diag-addr` flag to teleport start: `teleport start --diag-addr=127.0.0.1:3000` +The [http://127.0.0.1:3000/readyz](http://127.0.0.1:3000/readyz) endpoint will reply `{"status":"ok"}` if the Teleport service +is running without problems. + + + 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. + + +We'll cover how to use `etcd`, DynamoDB, and Firestore storage back-ends to make Teleport +highly available below. + +## Etcd + +Teleport can use [etcd](https://etcd.io/) as a storage backend to +achieve highly available deployments. You must take steps to protect access to +`etcd` in this configuration because that is where Teleport secrets like keys +and user records will be stored. + + + `etcd` can only currently be used to store Teleport's internal database in a + highly-available way. This will allow you to have multiple auth servers in your + cluster for an High Availability deployment, but it will not also store Teleport audit events + for you in the same way that [DynamoDB](#dynamodb) or + [Firestore](#firestore) will. `etcd` is not designed to handle large volumes of time series data like audit events. + + +To configure Teleport for using etcd as a storage backend: + +- Make sure you are using **etcd versions 3.3** or newer. +- Install etcd and configure peer and client TLS authentication using the [etcd + security guide](https://etcd.io/docs/v3.4.0/op-guide/security/). + - You can use [this script provided by + etcd](https://github.com/etcd-io/etcd/tree/master/hack/tls-setup) if you + don't already have a TLS setup. +- Configure all Teleport Auth servers to use etcd in the "storage" section of the config file as shown below. +- Deploy several auth servers connected to etcd backend. +- Deploy several proxy nodes that have `auth_servers` pointed to the list of auth + servers to connect to. + +```yaml +teleport: + storage: + type: etcd + + # List of etcd peers to connect to: + peers: ["https://172.17.0.1:4001", "https://172.17.0.2:4001"] + + # Required path to TLS client certificate and key files to connect to etcd. + # + # To create these, follow + # https://coreos.com/os/docs/latest/generate-self-signed-certificates.html + # or use the etcd-provided script + # https://github.com/etcd-io/etcd/tree/master/hack/tls-setup. + tls_cert_file: /var/lib/teleport/etcd-cert.pem + tls_key_file: /var/lib/teleport/etcd-key.pem + + # Optional file with trusted CA authority + # file to authenticate etcd nodes + # + # If you used the script above to generate the client TLS certificate, + # this CA certificate should be one of the other generated files + tls_ca_file: /var/lib/teleport/etcd-ca.pem + + # Alternative password-based authentication, if not using TLS client + # certificate. + # + # See https://etcd.io/docs/v3.4.0/op-guide/authentication/ for setting + # up a new user. + username: username + password_file: /mnt/secrets/etcd-pass + + # etcd key (location) where teleport will be storing its state under. + # make sure it ends with a '/'! + prefix: /teleport/ + + # NOT RECOMMENDED: enables insecure etcd mode in which self-signed + # certificate will be accepted + insecure: false + + # Optionally sets the limit on the client message size. + # This is usually used to increase the default which is 2MiB + # (1.5MiB server's default + gRPC overhead bytes). + # Make sure this does not exceed the value for the etcd + # server specified with `--max-request-bytes` (1.5MiB by default). + # Keep the two values in sync. + # + # See https://etcd.io/docs/v3.4.0/dev-guide/limit/ for details + # + # This bumps the size to 15MiB as an example: + etcd_max_client_msg_size_bytes: 15728640 +``` + +## S3 + + + Before continuing, please make sure to take a look at the [Cluster State section](../../architecture/nodes.mdx#cluster-state) + in Teleport Architecture documentation. + + + + 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 use the instance IAM role. + Teleport also will pick up AWS credentials from the `~/.aws` folder, just like the AWS CLI tool. + + +S3 buckets can only be used as storage for the recorded sessions. S3 cannot +store the audit log or the cluster state. Below is an example of how to +configure a Teleport auth server to store the recorded sessions in an S3 bucket. + +```yaml +teleport: + storage: + # The region setting sets the default AWS region for all AWS services + # Teleport may consume (DynamoDB, S3) + region: us-east-1 + + # Path to S3 bucket to store the recorded sessions in. + audit_sessions_uri: "s3://Example_TELEPORT_S3_BUCKET/records" + + # Teleport assumes credentials. Using provider chains, assuming IAM role or + # standard .aws/credentials in the home folder. +``` + +The AWS authentication settings above can be omitted if the machine itself is +running on an EC2 instance with an IAM role. + +These optional `GET` parameters control how Teleport interacts with an S3 endpoint, including S3-compatible endpoints. + +`s3://bucket/path?region=us-east-1&endpoint=mys3.example.com&insecure=false&disablesse=false` + +- `region=us-east-1` - set the Amazon region to use. +- `endpoint=mys3.example.com` - connect to a custom S3 endpoint. +- `insecure=true` - set to `true` or `false`. If `true`, TLS will be disabled. +- `disablesse=true` - set to `true` or `false`. If `true`, S3 server-side encryption will be disabled. If `false`, aws:kms (Key Management Service) will be used for server-side encryption. Other SSE types are not supported at this time. + +## DynamoDB + + + Before continuing, please make sure to take a look at the [Cluster State section](../../architecture/nodes.mdx#cluster-state) + in Teleport Architecture documentation. + + +If you are running Teleport on AWS, you can use +[DynamoDB](https://aws.amazon.com/dynamodb/) as a storage back-end to achieve +High Availability. DynamoDB backend supports two types of Teleport data: + +- Cluster state +- Audit log events + +DynamoDB cannot store the recorded sessions. You are advised to use AWS S3 for +that as shown above. To configure Teleport to use DynamoDB: + +- Make sure you have AWS access key and a secret key that give you access to + DynamoDB account. If you're using (as recommended) an IAM role for this, the policy with the necessary permissions is listed below. +- Configure all Teleport Auth servers to use DynamoDB back-end in the "storage" + section of `teleport.yaml` as shown below. +- Deploy several auth servers connected to DynamoDB storage back-end. +- Deploy several proxy nodes. +- Make sure that all Teleport nodes have `auth_servers` configuration setting + populated with the auth servers. + +```yaml +teleport: + storage: + type: dynamodb + # Region location of dynamodb instance, https://docs.aws.amazon.com/en_pv/general/latest/gr/rande.html#ddb_region + region: us-east-1 + + # Name of the DynamoDB table. If it does not exist, Teleport will create it. + table_name: Example_TELEPORT_DYNAMO_TABLE_NAME + + # This setting configures Teleport to send the audit events to three places: + # To keep a copy in DynamoDB, a copy on a local filesystem, and also output the events to stdout. + # NOTE: The DynamoDB events table has a different schema to the regular Teleport + # database table, so attempting to use the same table for both will result in errors. + # When using highly available storage like DynamoDB, you should make sure that the list always specifies + # the High Availability storage method first, as this is what the Teleport web UI uses as its source of events to display. + audit_events_uri: ['dynamodb://events_table_name', 'file:///var/lib/teleport/audit/events', 'stdout://'] + + # This setting configures Teleport to save the recorded sessions in an S3 bucket: + audit_sessions_uri: s3://Example_TELEPORT_S3_BUCKET/records +``` + +- Replace `us-east-1` and `Example_TELEPORT_DYNAMO_TABLE_NAME` + with your own settings. Teleport will create the table automatically. +- `Example_TELEPORT_DYNAMO_TABLE_NAME` and `events_table_name` **must** be different + DynamoDB tables. The schema is different for each. Using the same table name for both will result in errors. +- The AWS authentication setting above can be omitted if the machine itself is running on an EC2 instance with an IAM role. +- Audit log settings above are optional. If specified, Teleport will store the + audit log in DynamoDB and the session recordings **must** be stored in an S3 + bucket, i.e. both `audit_xxx` settings must be present. If they are not set, + Teleport will default to a local file system for the audit log, i.e. + `/var/lib/teleport/log` on an auth server. +- 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. + + + Make sure that the IAM role assigned to + Teleport is configured with sufficient access to DynamoDB. Below is the + example of the IAM policy you can use: + + +```js +{ + "Version": "2012-10-17", + "Statement": [{ + "Sid": "AllAPIActionsOnTeleportAuth", + "Effect": "Allow", + "Action": "dynamodb:*", + "Resource": "arn:aws:dynamodb:eu-west-1:123456789012:table/prod.teleport.auth" + }, + { + "Sid": "AllAPIActionsOnTeleportStreams", + "Effect": "Allow", + "Action": "dynamodb:*", + "Resource": "arn:aws:dynamodb:eu-west-1:123456789012:table/prod.teleport.auth/stream/*" + } + ] +} +``` + +### DynamoDB autoscaling + +When setting up DynamoDB it's important to set up backup and autoscaling. We make setup simpler by allowing AWS DynamoDB settings to be set automatically during Teleport startup. + +**DynamoDB Continuous Backups** + +- [AWS Blog Post - Amazon DynamoDB Continuous Backup](https://aws.amazon.com/blogs/aws/new-amazon-dynamodb-continuous-backups-and-point-in-time-recovery-pitr/) + +**DynamoDB Autoscaling Options** + +- [AWS Docs - Managing Throughput Capacity Automatically with DynamoDB Auto Scaling](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AutoScaling.html) + +```yaml +# ... +teleport: + storage: + type: "dynamodb" + [...] + + # continuous_backups is used to optionally enable continuous backups. + # default: false + continuous_backups: [true|false] + + # auto_scaling is used to optionally enable (and define settings for) auto scaling. + # default: false + auto_scaling: [true|false] + # Minimum/maximum read capacity in units + read_min_capacity: int + read_max_capacity: int + read_target_value: float + # Minimum/maximum write capacity in units + write_min_capacity: int + write_max_capacity: int + write_target_value: float +``` + +To enable these options you will need to update the IAM Role for Teleport. + +```json +{ + "Action": [ + "application-autoscaling:PutScalingPolicy", + "application-autoscaling:RegisterScalableTarget" + ], + "Effect": "Allow", + "Resource": "*" +}, +{ + "Action": [ + "iam:CreateServiceLinkedRole" + ], + "Condition": { + "StringEquals": { + "iam:AWSServiceName": [ + "dynamodb.application-autoscaling.amazonaws.com" + ] + } + }, + "Effect": "Allow", + "Resource": "*" +} +``` + +## GCS + + + Before continuing, please make sure to take a look at the [Cluster State section](../../architecture/nodes.mdx#cluster-state) + in Teleport Architecture documentation. + + +Google Cloud Storage (GCS) can only be used as storage for the recorded +sessions. GCS cannot store the audit log or the cluster state. Below is an +example of how to configure a Teleport auth server to store the recorded +sessions in a GCS bucket. + +```yaml +teleport: + storage: + # Path to GCS to store the recorded sessions in. + audit_sessions_uri: "gs://Example_TELEPORT_STORAGE/records" + credentials_path: /var/lib/teleport/gcs_creds +``` + +## Firestore + + + Before continuing, please make sure to take a look at the [Cluster State section](../../architecture/nodes.mdx#cluster-state) + in Teleport Architecture documentation. + + +If you are running Teleport on GCP, you can use +[Firestore](https://cloud.google.com/firestore/) as a storage back-end to achieve +high availability. Firestore backend supports two types of Teleport data: + +- Cluster state +- Audit log events + +Firestore cannot store the recorded sessions. You are advised to use Google +Cloud Storage (GCS) for that as shown above. To configure Teleport to use +Firestore: + +- Configure all Teleport Auth servers to use Firestore back-end in the "storage" + section of `teleport.yaml` as shown below. +- Deploy several auth servers connected to Firestore storage back-end. +- Deploy several proxy nodes. +- Make sure that all Teleport nodes have `auth_servers` configuration setting + populated with the auth servers or use a load balancer for the auth servers in + high availability mode. + +```yaml +teleport: + storage: + type: firestore + # Project ID https://support.google.com/googleapi/answer/7014113?hl=en + project_id: Example_GCP_Project_Name + + # Name of the Firestore table. If it does not exist, Teleport won't start + collection_name: Example_TELEPORT_FIRESTORE_TABLE_NAME + + credentials_path: /var/lib/teleport/gcs_creds + + # This setting configures Teleport to send the audit events to three places: + # To keep a copy in Firestore, a copy on a local filesystem, and also write the events to stdout. + # NOTE: The Firestore events table has a different schema to the regular Teleport + # database table, so attempting to use the same table for both will result in errors. + # When using highly available storage like Firestore, you should make sure that the list always specifies + # the High Availability storage method first, as this is what the Teleport web UI uses as its source of events to display. + audit_events_uri: ['firestore://Example_TELEPORT_FIRESTORE_EVENTS_TABLE_NAME', 'file:///var/lib/teleport/audit/events', 'stdout://'] + + # This setting configures Teleport to save the recorded sessions in GCP storage: + audit_sessions_uri: gs://Example_TELEPORT_S3_BUCKET/records +``` + +- Replace `Example_GCP_Project_Name` and `Example_TELEPORT_FIRESTORE_TABLE_NAME` + with your own settings. Teleport will create the table automatically. +- `Example_TELEPORT_FIRESTORE_TABLE_NAME` and `Example_TELEPORT_FIRESTORE_EVENTS_TABLE_NAME` + **must** be different Firestore tables. The schema is different for each. Using the same table name for both will result in errors. +- The GCP authentication setting above can be omitted if the machine itself is + running on a GCE instance with a Service Account that has access to the + Firestore table. +- Audit log settings above are optional. If specified, Teleport will store the audit log in Firestore and the session recordings **must** be stored in a GCP + bucket, i.e.both `audit_xxx` settings must be present. If they are not set, + Teleport will default to a local file system for the audit log, i.e. + `/var/lib/teleport/log` on an auth server. diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index 1266ca7da6c..d400ba97976 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -144,7 +144,7 @@ information about the cluster. | `-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 | -| `--auth` | `local` | any defined [authentication connector](../../admin-guide.mdx#authentication) | Specify the type of authentication connector to use. | +| `--auth` | `local` | any defined [authentication connector](./authentication.mdx) | Specify the type of authentication connector to use. | | `--skip-version-check` | none | none | Skip version checking between server and client. | | `-d, --debug` | none | none | Verbose logging to stdout | | `-J, --jumphost` | none | A jump host | SSH jumphost | diff --git a/docs/pages/setup/reference/license.mdx b/docs/pages/setup/reference/license.mdx new file mode 100644 index 00000000000..273c4e4663f --- /dev/null +++ b/docs/pages/setup/reference/license.mdx @@ -0,0 +1,26 @@ +--- +title: Enterprise License File +description: Teleport enterprise license file configuration parameters and requirements +--- + +Commercial Teleport subscriptions require a valid license. The license file can +be downloaded from the [Teleport Customer +Portal](https://dashboard.gravitational.com/web/login). + +The Teleport license file contains a X.509 certificate and the corresponding private key in PEM format. Place the downloaded file on Auth servers and set the `license_file` configuration parameter of your `teleport.yaml` to point to the file location: + +```yaml +auth_service: + license_file: /var/lib/teleport/license.pem +``` + +The `license_file` path can be either absolute or relative to the configured +`data_dir`. If the license file path is not set, Teleport will look for the +`license.pem` file in the configured `data_dir`. + + + Only Auth servers require the license. Proxies and Nodes that do not also have Auth role enabled do not need the license. + diff --git a/docs/pages/setup/reference/networking.mdx b/docs/pages/setup/reference/networking.mdx new file mode 100644 index 00000000000..8ada9b0e4aa --- /dev/null +++ b/docs/pages/setup/reference/networking.mdx @@ -0,0 +1,68 @@ +--- +title: Networking +description: Teleport ports and networking requirements +--- + +## Public address + +All three Teleport services (proxy, auth, node) have an optional +`public_addr` property. The public address can take an IP or a DNS name. It can +also be a list of values: + +```yaml +public_addr: ["proxy-one.example.com", "proxy-two.example.com"] +``` + +Specifying a public address for a Teleport service may be useful in the +following use cases: + +- You have multiple identical services, like proxies, behind a load balancer. +- You want Teleport to issue an SSH certificate for the service with the additional + principals, e.g.host names. + +## HTTP CONNECT proxies + +Some networks funnel all connections through a proxy server where they can be +audited and access control rules are applied. For these scenarios, Teleport supports HTTP CONNECT tunneling. + +To use HTTP CONNECT tunneling, simply set either the `HTTPS_PROXY` or `HTTP_PROXY` environment variables and when Teleport builds and establishes the reverse tunnel to the main cluster, it will funnel all traffic through the proxy. Specifically, if using the default configuration, Teleport will tunnel ports `3024` (SSH, reverse tunnel) and `3080` (HTTPS, establishing trust) through the proxy. + +The value of `HTTPS_PROXY` or `HTTP_PROXY` should be in the format +`scheme://host:port` where scheme is either `https` or `http` . If the value is +`host:port` , Teleport will prepend `http` . + +It's important to note that for Teleport to use HTTP CONNECT +tunneling, the `HTTP_PROXY` and `HTTPS_PROXY` environment variables must be set +within Teleport's environment. You can also optionally set the `NO_PROXY` +environment variable to avoid use of the proxy when accessing specified +hosts/netmasks. When launching Teleport with `systemd`, this will probably involve +adding some lines to your `systemd` unit file: + +``` +[Service] +Environment="HTTP_PROXY=http://proxy.example.com:8080/" +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" +``` + + + `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. + + +## Ports + +Teleport services listen on several ports. This table shows the default port numbers. + +| Port | Service | Description | +| - | - | - | +| 3022 | Node | SSH port. This is Teleport's equivalent of port `#22` for SSH. | +| 3023 | Proxy | SSH port clients connect to. A proxy will forward this connection to port `#3022` on the destination node. | +| 3024 | Proxy | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server. | +| 3025 | Auth | SSH port used by the Auth Service to serve its API to other nodes in a cluster. | +| 3080 | Proxy | HTTPS connection to authenticate `tsh` users and web users into the cluster. The same connection is used to serve a Web UI. | +| 3026 | Kubernetes | HTTPS Kubernetes proxy `proxy_service.kube_listen_addr` | +| 3027 | Kubernetes | Kubernetes Service `kubernetes_service.listen_addr` | +| 3036 | MySQL | MySQL port `proxy_service.mysql_addr` |