Skip to content

docs: instruct users to use apt/yum/dnf instead of dpkg/rpm #25700

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hugoShaka merged 15 commits into from
May 9, 2023
Merged

docs: instruct users to use apt/yum/dnf instead of dpkg/rpm #25700

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
74db179
docs: instruct users to use `apt`/`yum`/`dnf` instead of `dpkg`/`rpm`
hugoShaka May 5, 2023
029fb47
fixup! docs: instruct users to use `apt`/`yum`/`dnf` instead of `dpkg…
hugoShaka May 5, 2023
4a9d9e8
fixup! fixup! docs: instruct users to use `apt`/`yum`/`dnf` instead o…
hugoShaka May 5, 2023
0d401c0
Apply suggestions from code review
hugoShaka May 5, 2023
66a1be2
docs: document linux distribution support and fix apt/yum instructions
hugoShaka May 5, 2023
f5abcbc
docs feedback pt.2
hugoShaka May 8, 2023
33fe438
address roman's feedback
hugoShaka May 8, 2023
c50dc50
Merge branch 'master' into hugo/docs-use-apt-instead-of-dpkg
stevenGravy May 8, 2023
3200892
Update docs/pages/installation.mdx
hugoShaka May 9, 2023
c78920c
docs feedback: simplify installation partial
hugoShaka May 9, 2023
79e3af5
links are not supported in partials :upside_down:
hugoShaka May 9, 2023
79b5d62
Merge branch 'master' into hugo/docs-use-apt-instead-of-dpkg
hugoShaka May 9, 2023
f94cc52
Merge branch 'master' into hugo/docs-use-apt-instead-of-dpkg
hugoShaka May 9, 2023
b917fb6
Merge branch 'master' into hugo/docs-use-apt-instead-of-dpkg
hugoShaka May 9, 2023
b7fa346
make linter happy
hugoShaka May 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/pages/application-access/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Alternatively, log in to the Teleport Web Interface at `https://teleport.example

Dive deeper into the topics relevant to your Application Access use-case:

- Learn in more detail about [connecting applications](./guides/connecting-apps.mdx) with Application Access.
- Learn in more detail about [connecting applications](./guides/connecting-apps.mdx).
- Learn about integrating with [JWT tokens](./jwt/introduction.mdx) for auth.
- Learn how to use application access with [RESTful APIs](./guides/api-access.mdx).
- See full configuration and CLI [reference](./reference.mdx).
Expand Down
221 changes: 135 additions & 86 deletions docs/pages/includes/install-linux.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,9 @@
<ScopedBlock scope={["enterprise"]}>

Visit your [Teleport account](https://teleport.sh) and select the URL for your package of choice.

</ScopedBlock>

<ScopedBlock scope={["cloud"]}>

Visit the [Downloads Page](/docs/choose-an-edition/teleport-cloud/downloads.mdx)
and select the URL for your package of choice.

</ScopedBlock>

Use the appropriate commands for your environment to install your package.

<Tabs dropdownView dropdownCaption="Teleport Edition">
<TabItem label="Open Source" scope="oss">
<Tabs>
<TabItem label="Debian/Ubuntu (DEB)" scope="oss">

Add the Teleport repository to your repository list:
<TabItem label="Debian 8+/Ubuntu 16.04+ (apt)" scope="oss">

```code
# Download Teleport's PGP public key
Expand All @@ -28,9 +13,6 @@ Use the appropriate commands for your environment to install your package.
$ source /etc/os-release
# Add the Teleport APT repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v(=teleport.major_version=)" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
Expand All @@ -40,52 +22,50 @@ Use the appropriate commands for your environment to install your package.
```

</TabItem>
<TabItem label="Amazon Linux 2/RHEL (RPM)" scope="oss">
<TabItem label="Amazon Linux 2/RHEL 7 (yum)" scope="oss">

```code
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
# Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
# and the codename your distro was forked from instead of '$ID'
# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
$ sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v(=teleport.major_version=)/teleport.repo")
$ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v(=teleport.major_version=)/teleport.repo")"
$ sudo yum install teleport
#
# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
#
# Optional: Use DNF on newer distributions
# $ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
# $ sudo dnf install teleport
```

<Admonition type="warning" title="Amazon Linux 2023 Installations">
Amazon Linux 2023 users should utilize the tarball or RPM file to install Teleport.
You can download the matching RPM architecture for your instance
from the [Teleport Downloads page](https://goteleport.com/download) and install with the example command below.
</TabItem>
<TabItem label="AmazonLinux 2023/RHEL 8+ (dnf)" scope="oss">

```code
# Replace <arch> with the architecture type (amd64, arm64,...)
$ rpm -i teleport-(=teleport.version=)-1.<arch>.rpm
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
# Use the dnf config manager plugin to add the teleport RPM repo
$ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v(=teleport.major_version=)/teleport.repo")"

# Install teleport
$ sudo dnf install teleport

# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
```
</Admonition>

</TabItem>
<TabItem label="Tarball" scope="oss">

In the example commands below, update `$SYSTEM-ARCH` with the appropriate
In the example commands below, update `$SYSTEM_ARCH` with the appropriate
Comment thread
hugoShaka marked this conversation as resolved.
value (`amd64`, `arm64`, or `arm`). All example commands using this variable
will update after one is filled out.

```code
$ curl https://get.gravitational.com/teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH" description="The CPU architecture of the system Teleport will be installed on"/>-bin.tar.gz.sha256
$ curl https://get.gravitational.com/teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH" description="The CPU architecture of the system Teleport will be installed on"/>-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ shasum -a 256 teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ curl -O https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
$ shasum -a 256 teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ tar -xvf teleport-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
$ cd teleport
$ sudo ./install
```
Expand All @@ -94,46 +74,90 @@ Use the appropriate commands for your environment to install your package.
</Tabs>
</TabItem>
<TabItem label="Enterprise" scope="enterprise">
<Tabs>
<TabItem label="Debian 8+/Ubuntu 16.04+ (apt)" scope="enterprise">

In the example commands below, update `$SYSTEM-ARCH` with the appropriate
value (`amd64`, `arm64`, or `arm`). All example commands using this variable
will update after one is filled out.
```code
# Download Teleport's PGP public key
$ sudo curl https://apt.releases.teleport.dev/gpg \
-o /usr/share/keyrings/teleport-archive-keyring.asc
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport APT repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v(=teleport.major_version=)" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

<Tabs>
<TabItem label="Debian/Ubuntu (DEB)" scope="enterprise">
$ sudo apt-get update
$ sudo apt-get install teleport-ent
```

After Downloading the `.deb` file for your system architecture, install it with
`dpkg`. The example below assumes the `root` user:
For FedRAMP/FIPS-compliant installations, install the `teleport-ent-fips` package instead:

```code
$ dpkg -i ~/Downloads/teleport-ent_(=teleport.version=)_<Var name="$SYSTEM-ARCH" description="The CPU architecture of the system Teleport will be installed on"/>.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_(=teleport.version=)_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent (=teleport.version=) ...
Setting up teleport-ent (=teleport.version=) ...
$ sudo apt-get install teleport-ent-fips
```

</TabItem>
<TabItem label="Amazon Linux 2/RHEL (RPM)" scope="enterprise">
<TabItem label="AmazonLinux 2/RHEL 7 (yum)" scope="enterprise">

After Downloading the `.rpm` file for your system architecture, install it with `rpm`:
```code
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
$ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v(=teleport.major_version=)/teleport.repo")"
$ sudo yum install teleport-ent
#
# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
```

For FedRAMP/FIPS-compliant installations, install the `teleport-ent-fips` package instead:

```code
$ rpm -i ~/Downloads/teleport-ent-(=teleport.version=).<Var name="$SYSTEM-ARCH"/>.rpm
warning: teleport-ent-(=teleport.version=).$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
$ sudo yum install teleport-ent-fips
```

</TabItem>
<TabItem label="AmazonLinux 2023/RHEL 8+ (dnf)" scope="enterprise">

```code
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v(=teleport.major_version=). You'll need to update this
# file for each major release of Teleport.
# Use the dnf config manager plugin to add the teleport RPM repo
$ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v(=teleport.major_version=)/teleport.repo")"

# Install teleport
$ sudo dnf install teleport-ent

# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
```

For FedRAMP/FIPS-compliant installations, install the `teleport-ent-fips` package instead:

```code
$ sudo dnf install teleport-ent-fips
```

</TabItem>
<TabItem label="Tarball" scope="enterprise">

Comment thread
hugoShaka marked this conversation as resolved.
In the example commands below, update `$SYSTEM_ARCH` with the appropriate
value (`amd64`, `arm64`, or `arm`). All example commands using this variable
will update after one is filled out.

```code
$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz.sha256
$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ curl -O https://cdn.teleport.dev/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz
$ tar -xvf teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz
$ cd teleport-ent
$ sudo ./install
```
Expand All @@ -142,12 +166,12 @@ Use the appropriate commands for your environment to install your package.
will be slightly different:

```code
$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-fips-bin.tar.gz.sha256
$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-fips-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-fips-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-fips-bin.tar.gz
$ curl -O https://cdn.teleport.dev/teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-fips-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-fips-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM-ARCH"/>-fips-bin.tar.gz
$ tar -xvf teleport-ent-v(=teleport.version=)-linux-<Var name="$SYSTEM_ARCH"/>-fips-bin.tar.gz
$ cd teleport-ent
$ sudo ./install
```
Expand All @@ -156,41 +180,66 @@ Use the appropriate commands for your environment to install your package.
</Tabs>
</TabItem>
<TabItem label="Cloud" scope="cloud">

In the example commands below, update `$SYSTEM-ARCH` with the appropriate
value (`amd64`, `arm64`, or `arm`). All example commands using this variable
will update after one is filled out.

<Tabs>
<TabItem label="Debian/Ubuntu (DEB)" scope="cloud">
<TabItem label="Debian 8+/Ubuntu 16.04+ (apt)" scope="cloud">

After Downloading the `.deb` file for your system architecture, install it with
`dpkg`. The example below assumes the `root` user:
Add the Teleport repository to your repository list:

```code
$ dpkg -i ~/Downloads/teleport-ent_(=cloud.version=)_<Var name="$SYSTEM-ARCH"/>.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_(=cloud.version=)_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent (=cloud.version=) ...
Setting up teleport-ent (=cloud.version=) ...
# Download Teleport's PGP public key
$ sudo curl https://apt.releases.teleport.dev/gpg \
-o /usr/share/keyrings/teleport-archive-keyring.asc
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport apt repository for cloud.
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

$ sudo apt-get update
$ sudo apt-get install teleport-ent
```

</TabItem>
<TabItem label="Amazon Linux 2/RHEL (RPM)" scope="cloud">
<TabItem label="AmazonLinux 2/RHEL 7 (yum)" scope="cloud">

After Downloading the `.rpm` file for your system architecture, install it with `rpm`:
```code
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport yum repository for cloud.
$ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport.repo")"
$ sudo yum install teleport-ent
#
# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
```

</TabItem>
<TabItem label="AmazonLinux 2023/RHEL 8+ (dnf)" scope="oss">

```code
$ rpm -i ~/Downloads/teleport-ent-(=cloud.version=).<Var name="$SYSTEM-ARCH"/>.rpm
warning: teleport-ent-(=cloud.version=).$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport yum repository for cloud.
# Use the dnf config manager plugin to add the teleport RPM repo
$ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport.repo")"

# Install teleport
$ sudo dnf install teleport-ent

# Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
# echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
```

</TabItem>
<TabItem label="Tarball" scope="cloud">

Comment thread
hugoShaka marked this conversation as resolved.
In the example commands below, update `$SYSTEM_ARCH` with the appropriate
value (`amd64`, `arm64`, or `arm`). All example commands using this variable
will update after one is filled out.

```code
$ curl https://get.gravitational.com/teleport-ent-v(=cloud.version=)-linux-<Var name="$SYSTEM-ARCH"/>-bin.tar.gz.sha256
$ curl https://get.gravitational.com/teleport-ent-v(=cloud.version=)-linux-<Var name="$SYSTEM_ARCH"/>-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v(=cloud.version=)-linux-amd64-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=cloud.version=)-linux-amd64-bin.tar.gz
Expand Down
27 changes: 27 additions & 0 deletions docs/pages/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,33 @@ supports most features on Windows 10 and later.*

All installations include `teleport`, `tsh`, `tctl`, and `tbot`.

### Feature support

Some Teleport features have additional requirements:

| Feature | Requirement | Debian | Ubuntu | CentOS/RHEL | AmazonLinux |
|--------------------------------------------------------------------------------|---------------|--------------------------|----------|-------------|------------------------|
| [Enhanced Session Recording](./server-access/guides/bpf-session-recording.mdx) | Kernel v5.8+ | 11, or 10 with backports | 20.04.2+ | 9+ | 2 (post 11/2021), 2023 |
| Automatic Updates | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 |
| Installation through apt/yum repos | systemd-based | 8+ | 16.04+ | 7+ | 2, 2023 |

<Admonition type="note">
`apt` and `yum` repos don't expose packages for all distribution variants.
When following installation instructions, you might need to replace `ID` with
`ID_LIKE` to install packages of the closest supported distribution.

Currently supported distributions (and `ID`) are:
- RHEL >= 7 (`rhel`)
- CentOS >= 7 (`centos`)
- Debian >= 8 (`debian`)
- Ubuntu >= 16.04 (`ubuntu`)
- Amazon Linux 2 and 2023 (`amzn`)

</Admonition>


### Installation instructions

(!docs/pages/includes/permission-warning.mdx!)

(!docs/pages/includes/install-linux.mdx!)
Expand Down