diff --git a/docs/pages/enterprise/getting-started.mdx b/docs/pages/enterprise/getting-started.mdx index 3e5056f57dc59..81ca90c76795c 100644 --- a/docs/pages/enterprise/getting-started.mdx +++ b/docs/pages/enterprise/getting-started.mdx @@ -401,18 +401,7 @@ We currently only offer Docker images for `x86_64` architectures. ### Pick your image -This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are -automatically rebuilt every night. These nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. -They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date. - -| Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Image base | -| - | - | - | - | - | -| `(=teleport.latest_ent_docker_image=)` | Enterprise | The latest version of Teleport Enterprise (=version=) | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -| `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The latest version of Teleport Enterprise (=version=) FIPS | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -| `quay.io/gravitational/teleport-ent:(=teleport.version=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -| `quay.io/gravitational/teleport-ent:(=teleport.version=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | - -For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`. +(!docs/pages/includes/enterprise/docker-images.mdx!) ### Quickstart using docker-compose diff --git a/docs/pages/includes/enterprise/docker-images.mdx b/docs/pages/includes/enterprise/docker-images.mdx new file mode 100644 index 0000000000000..de8e82edd6815 --- /dev/null +++ b/docs/pages/includes/enterprise/docker-images.mdx @@ -0,0 +1,14 @@ +This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are +automatically rebuilt every night. + +Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. +They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date. + +| Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Image base | +| - | - | - | - | - | +| `(=teleport.latest_ent_docker_image=)` | Enterprise | The latest version of Teleport Enterprise (=version=) | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | +| `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The latest version of Teleport Enterprise (=version=) FIPS | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | +| `quay.io/gravitational/teleport-ent:(=teleport.version=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | +| `quay.io/gravitational/teleport-ent:(=teleport.version=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | + +For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`. \ No newline at end of file diff --git a/docs/pages/includes/image.mdx b/docs/pages/includes/image.mdx deleted file mode 100644 index 128246e773d86..0000000000000 --- a/docs/pages/includes/image.mdx +++ /dev/null @@ -1,25 +0,0 @@ -We provide pre-built Docker images for every version of Teleport. - -These images are hosted on quay.io. All tags under `quay.io/gravitational/teleport` [are Teleport Open Source images](https://quay.io/repository/gravitational/teleport?tag=latest\&tab=tags). - - - You will need a recent version of [Docker](https://hub.docker.com/search?q=\&type=edition\&offering=community) installed to follow this section of the quick start guide. We currently only offer Docker images for `x86_64` architectures. - - -The table below gives an idea of how our image naming scheme works. We offer images that -point to a static version of Teleport, as well as images that are automatically rebuilt -every night. These nightly images point to the latest version of Teleport from the -three most recent release branches. They are stable, and we recommend their use to -keep your Teleport installation up to date. - - - - - - - - - -
Image nameTeleport versionImage automatically updated?Image base
`(=teleport.latest_oss_docker_image=)`The latest version of Teleport Open Source (=version=)Yes[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)
`quay.io/gravitational/teleport:(=teleport.version=)`The version specified in the image's tag (i.e. (=teleport.version=))No[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)
- -For testing, we always recommend that you use the latest release version of Teleport, which is currently `(=teleport.latest_oss_docker_image=)`. diff --git a/docs/pages/setup/guides/docker.mdx b/docs/pages/setup/guides/docker.mdx index 30ef543c9af0b..5bd92415e0251 100644 --- a/docs/pages/setup/guides/docker.mdx +++ b/docs/pages/setup/guides/docker.mdx @@ -1,18 +1,27 @@ --- -title: Getting started with Teleport using Docker -description: How to get started with Teleport Open Source Edition using Docker locally. +title: How to Run Teleport Using Docker +description: How to run Teleport using Docker. h1: Run Teleport using Docker --- -This section will cover: +This guide will explain how to run a container using one of Teleport's Docker +images and execute commands on that container via Teleport's `tsh` client. -- Getting started with a local Teleport using Docker. -- Using Teleport with Teleport's native client, `tsh`. + + +Since all of Teleport's services are run from the same binary, you can +use our Docker image to run services like the Database Service or App +Service or explore the Auth and Proxy Services locally. + + ## Prerequisites -- Teleport v(=teleport.version=) Open Source or Enterprise. -- Docker v(=docker.version=) or later. + + + +- Docker v(=docker.version=) or later. We currently only offer Docker images for + `x86_64` architectures. ```code $ docker version @@ -20,24 +29,77 @@ $ docker version # Version: (=docker.version=) ``` +- The `tsh` client tool, which ships with the `teleport` binary. Visit [Download Teleport](/teleport/download/) to download `tsh`. + + + + +- Docker v(=docker.version=) or later. We currently only offer Docker images for + `x86_64` architectures. + +```code +$ docker version +# Client: Docker Engine - Community +# Version: (=docker.version=) +``` + +- The `tsh` client tool, which ships with the `teleport` binary. Visit the [customer portal](https://dashboard.gravitational.com/web/login) to download Teleport. + + + + ## Step 1/4. Pick your image -(!docs/pages/includes/image.mdx!) + + +We provide pre-built Docker images for every version of Teleport. + +These images are hosted on quay.io. All tags under `quay.io/gravitational/teleport` [are Teleport Open Source images](https://quay.io/repository/gravitational/teleport?tag=latest\&tab=tags). + +The table below gives an idea of how our image naming scheme works. We offer images that +point to a static version of Teleport, as well as images that are automatically rebuilt +every night. These nightly images point to the latest version of Teleport from the +three most recent release branches. They are stable, and we recommend their use to +keep your Teleport installation up to date. + + + + + + + + + +
Image nameTeleport versionImage automatically updated?Image base
`(=teleport.latest_oss_docker_image=)`The latest version of Teleport Open Source (=version=)Yes[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)
`quay.io/gravitational/teleport:(=teleport.version=)`The version specified in the image's tag (i.e. (=teleport.version=))No[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)
+ +For testing, we always recommend that you use the latest release version of Teleport, which is currently `(=teleport.latest_oss_docker_image=)`. + + +We provide pre-built Docker images for every version of Teleport. + +(!docs/pages/includes/enterprise/docker-images.mdx!) -## Step 2/4. Start teleport + + -Create teleport configs and start the process with sample `docker run` commands: +## Step 2/4. Start Teleport + + + + +Create Teleport configs and start the process with the following `docker run` commands: ```code -# Create local config and data directories for teleport, which will be mounted into the container +# Create local config and data directories for Teleport, which will be mounted +# into the container. $ mkdir -p ~/teleport/config ~/teleport/data -# Generate a sample teleport config and write it to the local config directory. -# This container will write the config and immediately exit - this is expected. +# Generate a sample Teleport config and write it to the local config directory. +# This container will write the config and immediately exit--this is expected. $ docker run --hostname localhost --rm \ --entrypoint=/bin/sh \ -v ~/teleport/config:/etc/teleport \ - (=teleport.latest_oss_docker_image=) -c "teleport configure > /etc/teleport/teleport.yaml" -# Start teleport with mounted config and data directories, plus all ports + (=teleport.latest_oss_docker_image=) bash -c "teleport configure > /etc/teleport/teleport.yaml" +# Start Teleport with mounted config and data directories, plus all ports $ docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ @@ -45,11 +107,37 @@ $ docker run --hostname localhost --name teleport \ (=teleport.latest_oss_docker_image=) ``` + + + +Create Teleport configs and start the process with the following `docker run` commands: + +```code +# Create local config and data directories for Teleport, which will be mounted +# into the container. +$ mkdir -p ~/teleport/config ~/teleport/data +# Generate a sample Teleport config and write it to the local config directory. +# This container will write the config and immediately exit--this is expected. +$ docker run --hostname localhost --rm \ + --entrypoint=/bin/sh \ + -v ~/teleport/config:/etc/teleport \ + (=teleport.latest_ent_docker_image=) bash -c "teleport configure > /etc/teleport/teleport.yaml" +# Start Teleport with mounted config and data directories, plus all ports +$ docker run --hostname localhost --name teleport \ + -v ~/teleport/config:/etc/teleport \ + -v ~/teleport/data:/var/lib/teleport \ + -p 3023:3023 -p 3025:3025 -p 3080:3080 \ + (=teleport.latest_ent_docker_image=) +``` + + + + ## Step 3/4. Creating a Teleport user To create a user inside your Teleport container, use `docker exec`. -This example command will create a Teleport user called `testuser` which is allowed to log in as either operating system user `root` or `ubuntu`: +This example command will create a Teleport user called `testuser` which is allowed to log in as either `root` or `ubuntu` on the host operating system: ```code $ docker exec teleport tctl users add testuser --roles=editor,access --logins=root,ubuntu,ec2-user @@ -69,11 +157,9 @@ The Web UI will be available at the displayed URL. ## Step 4/4. tsh into your Teleport container -Finish signing up and creating your user using the generated link created previously. - -[Download and install](https://goteleport.com/teleport/download) a copy of Teleport locally. Doing so will install the `tsh` tool so you can interact with Docker containers. - -Open a second terminal and issue the command: +After you have finished creating your user, open a second terminal and issue the +command, which will log in to your Teleport cluster via the Proxy Service at +`localhost`. ```code $ tsh login --proxy=localhost --insecure --user=testuser @@ -115,7 +201,7 @@ $ tsh ls # localhost 127.0.0.1:3022 env=example, hostname=localhost ``` -To SSH into the local Node `localhost` (running in your Docker container) issue the following `tsh` command: +To SSH into the local Node called `localhost`: ```code $ tsh ssh root@localhost diff --git a/docs/pages/setup/guides/ec2-tags.mdx b/docs/pages/setup/guides/ec2-tags.mdx index 645bff9936ea5..cf593de6dc77a 100644 --- a/docs/pages/setup/guides/ec2-tags.mdx +++ b/docs/pages/setup/guides/ec2-tags.mdx @@ -1,20 +1,25 @@ --- -title: EC2 Tags as Teleport node labels -description: How to setup Teleport node labels based on EC2 tags -h1: Sync EC2 Tags and Teleport node labels +title: EC2 Tags as Teleport Node Labels +description: How to set up Teleport Node labels based on EC2 tags +h1: Sync EC2 Tags and Teleport Node Labels --- -This section will explain how to setup Teleport node labels based on EC2 tags. +This guide will explain how to set up Teleport Node labels based on Amazon EC2 tags. ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- An AWS EC2 instance running a Teleport node +- One Teleport Node running on an Amazon EC2 instance. See + [Adding Nodes](../admin/adding-nodes.mdx) for how to set up a Teleport Node. +- The following software installed on your Teleport Node: `curl`, `python`, and + the `aws` CLI, which comes from the `awscli` Python package. ## Step 1/3. Deploy the script -You’ll need a script on your instance which can query the AWS API and get the values of tags for you. +You’ll need a script on your EC2 instance that can query the AWS API and get the +values of your instance's tags for you. The Teleport Node will then use these +values to execute RBAC rules. Here’s one you can use: @@ -46,13 +51,7 @@ Run the command below to make it executable: $ chmod +x /usr/local/bin/get-tag.sh ``` - -For the script to work, you’ll need `curl`, `python` and the `aws` command line tool installed. -`aws` comes from the awscli Python package, so you can install it using `pip3 install awscli` or similar. -If you don’t have `python`, `pip3` or curl installed, look for them in your OS’s package manager. - - -## Step 2/3. Setup IAM role +## Step 2/3. Set up an IAM role Grant your EC2 instance an IAM role which will allow it to query tags values for EC2 instances. @@ -79,7 +78,7 @@ Once this is done, query the value of the test tag on your EC2 instance by runni tagValue ``` -## Step 3/3. Modify config file +## Step 3/3. Modify the Teleport Node config file Modify your Teleport config file `/etc/teleport.yaml` to add commands to run on your node: @@ -125,6 +124,11 @@ spec: port_forwarding: true ``` -When assigned to Teleport users, this role will only allow them to log into Teleport nodes which have the `aws_tag_test` label with the value of tagValue, effectively gating access to infrastructure based on the value of the EC2 test tag. +When assigned to Teleport users, this role will only allow them to log in to +Teleport Nodes which have the `aws_tag_test` label with the value of `tagValue`, +effectively gating access to infrastructure based on the value of the EC2 `test` +tag. -By adding multiple commands to a Teleport node set to the values of different tags and then adding Teleport roles which reference them, you can build quite complex RBAC systems based off your EC2 tagging structure. +By adding multiple commands to a Teleport Node, setting the values of different +tags, then adding Teleport roles that reference these tags, you can build +fine-grained RBAC systems based on your EC2 tagging structure. diff --git a/docs/pages/setup/reference/audit.mdx b/docs/pages/setup/reference/audit.mdx index b9cac06cd1dff..82a541865be24 100644 --- a/docs/pages/setup/reference/audit.mdx +++ b/docs/pages/setup/reference/audit.mdx @@ -3,32 +3,65 @@ 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: +Teleport logs SSH, Kubernetes, desktop, and database events 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, + + + + +1. **Cluster Events:** Teleport logs events like successful user logins along + with metadata like remote IP address, time, and the session ID. +2. **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and + can be replayed later. By default, the recording is done by Teleport Nodes, 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. + + + + +1. **Cluster Events:** Teleport logs events like successful user logins along + with metadata like remote IP address, time, and the session ID. +2. **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and + can be replayed later. Teleport Cloud manages the storage of session + recording data. + + + + + + +You can use +[Enhanced Session Recording with BPF](../../server-access/guides/bpf-session-recording.mdx) +to get even more comprehensive audit logs with advanced security. + + + +Refer to the +["Audit Log" section](../../architecture/authentication.mdx#audit-log) in the +Teleport architecture guide 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. + + + +Teleport supports multiple storage backends for storing audit events. The `dir` +backend uses the local filesystem of an Auth Service host. 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. +[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 audit logs in multiple places at the same time. +For more information on how to configure the audit log, refer to the `storage` +section of the example configuration file in the +[Teleport Configuration Reference](./config.mdx). 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` . +stored in the `data_dir` under `log` directory, usually `/var/lib/teleport/log`. Each day is represented as a file: ```code @@ -40,15 +73,26 @@ $ ls -l /var/lib/teleport/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 + + + +Teleport Cloud manages the storage of audit logs for you. You can access your +audit logs via the Teleport Web UI by clicking: + +**Activity** > **Audit Log** + + + + +Audit logs 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 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. + // A unique ID for the event log. Useful for deduplication. "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef", // Teleport user name "user": "ekontsevoy", @@ -56,9 +100,9 @@ format: "login": "root", // Server namespace. This field is reserved for future use. "namespace": "default", - // Unique server ID. + // Unique server ID "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f", - // Server Labels. + // Server Labels "server_labels": { "datacenter": "us-east-1", "label-b": "x" @@ -76,6 +120,8 @@ format: } ``` +## Event types + The possible event types are: | Event Type | Description | @@ -96,8 +142,12 @@ The possible event types are: | 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 the standard input and standard +output of an SSH session. -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). @@ -105,7 +155,8 @@ 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. +You can replay recorded sessions using the [`tsh play`](./cli.mdx#tsh-play) command or the Web +UI. For example, replay a session via CLI: @@ -113,8 +164,31 @@ For example, replay a session via CLI: $ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 ``` -Print the session events in json to stdout: +Print the session events in JSON to stdout: ```code $ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json ``` + + + + +Teleport Cloud automatically stores recorded sessions. + +You can replay recorded sessions using the [`tsh play`](./cli.mdx#tsh-play) command or the Web +UI. + +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 +``` + + + \ No newline at end of file diff --git a/docs/pages/setup/reference/backends.mdx b/docs/pages/setup/reference/backends.mdx index acd627ff75809..5cf1e20d68182 100644 --- a/docs/pages/setup/reference/backends.mdx +++ b/docs/pages/setup/reference/backends.mdx @@ -8,6 +8,13 @@ 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.). + + +Teleport Cloud manages Auth Service and Proxy Service data for you, so there is +no need to configure a backend. + + + | 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 | diff --git a/docs/pages/setup/reference/config.mdx b/docs/pages/setup/reference/config.mdx index 4258f20e1202c..1bd5d369a3c69 100644 --- a/docs/pages/setup/reference/config.mdx +++ b/docs/pages/setup/reference/config.mdx @@ -9,10 +9,57 @@ Teleport uses the YAML file format for configuration. A full configuration refer file is shown below, this provides comments and all available options for `teleport.yaml` By default, it is stored in `/etc/teleport.yaml`. -(!docs/pages/includes/backup-warning.mdx!) + + + + +- **Do not use this example configuration in production.** + + You must edit your configuration file to meet the needs of your environment. + Using a copy of the reference configuration will have unintended effects. To + create a configuration file that you can use as a starting point, run the + following command: + + ```code + $ teleport configure -o file + ``` + +- You should back up your configuration file before making changes. This will + enable you to roll back to the previous configuration if you need to. + + + + +- **Do not use this example configuration in production.** + + You must edit your configuration file to meet the needs of your environment. + Using a copy of the reference configuration will have unintended effects. To + create a configuration file that you can use as a starting point, run the + following command: + + ```code + $ teleport configure -o file + ``` + +- You should back up your configuration file before making changes. This will + enable you to roll back to the previous configuration if you need to. + +- Teleport Cloud manages the Auth Service and Proxy Service for you. Your + Teleport Nodes should include the following configuration options to avoid + unintended effects: + + ```yaml + auth_service: + enabled: no + + proxy_service: + enabled: no + ``` + + + + -This document aims to be a reference rather than a starting point for a real cluster. To -get a good starting file, run `teleport configure -o teleport.yaml`. ```yaml # By default, this file should be stored in /etc/teleport.yaml