From 973cb74493a31c16853e0ea345de55c8d63f88d8 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Wed, 15 Mar 2023 13:51:22 -0300 Subject: [PATCH] docs: Add instructions on uninstalling Teleport (#22989) * docs: Add instructions on uninstalling Teleport * Add standalone RPM/DEB instructions and clarification for different OSes * Language * Suggestions from code review * Add more specifics for Teleport Connect * Address PR feedback --- docs/config.json | 4 + docs/pages/installation.mdx | 14 +- docs/pages/management/admin.mdx | 5 +- .../management/admin/uninstall-teleport.mdx | 502 ++++++++++++++++++ 4 files changed, 517 insertions(+), 8 deletions(-) create mode 100644 docs/pages/management/admin/uninstall-teleport.mdx diff --git a/docs/config.json b/docs/config.json index 4e5d5e7b30f..a081b218c66 100644 --- a/docs/config.json +++ b/docs/config.json @@ -486,6 +486,10 @@ { "title": "Run Teleport with Self-Signed Certificates", "slug": "/management/admin/self-signed-certs/" + }, + { + "title": "Uninstall Teleport", + "slug": "/management/admin/uninstall-teleport/" } ] }, diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index fcff6fbf7bd..2296cdbd72d 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -116,12 +116,12 @@ chart. |[`teleport-(=teleport.version=).pkg`](https://cdn.teleport.dev/teleport-(=teleport.version=).pkg)|`teleport`
`tctl`
`tsh`
`tbot`| |[`tsh-(=teleport.version=).pkg`](https://cdn.teleport.dev/tsh-(=teleport.version=).pkg)|`tsh`| - You can also fetch an installer via the command line: + You can also fetch an installer via the command line: ```code $ curl -O https://cdn.teleport.dev/teleport-(=teleport.version=).pkg # Installs on Macintosh HD - $ sudo installer -pkg teleport-(=teleport.version=).pkg -target / + $ sudo installer -pkg teleport-(=teleport.version=).pkg -target / # Password: # installer: Package name is teleport-(=teleport.version=) # installer: Upgrading at base path / @@ -171,7 +171,7 @@ against `tsh version` and `tctl version`. (!docs/pages/includes/enterprise/install-macos.mdx!) - (!docs/pages/includes/enterprise/install-macos.mdx!) + (!docs/pages/includes/enterprise/install-macos.mdx!) @@ -201,13 +201,17 @@ shown in the installation examples. ```code $ export version=v(=teleport.version=) # 'darwin' 'linux' or 'windows' -$ export os=linux +$ export os=linux # '386' 'arm' on linux or 'amd64' for all distros -$ export arch=amd64 +$ export arch=amd64 $ curl https://get.gravitational.com/teleport-$version-$os-$arch-bin.tar.gz.sha256 # ``` +## Uninstalling Teleport + +If you wish to uninstall Teleport at any time, see our documentation on [Uninstalling Teleport](./management/admin/uninstall-teleport.mdx). + ## Next steps Now that you know how to install Teleport, you can enable access to all of your diff --git a/docs/pages/management/admin.mdx b/docs/pages/management/admin.mdx index 718459b9dbb..8fd43553d55 100644 --- a/docs/pages/management/admin.mdx +++ b/docs/pages/management/admin.mdx @@ -16,7 +16,7 @@ cluster maintenance tasks. - [Teleport Daemon](./admin/daemon.mdx): Set up Teleport as a daemon on Linux with systemd. - [Upgrade the Teleport Binary](./admin/upgrading-the-teleport-binary.mdx): Upgrade the `teleport` binary without losing connections. -- [Run Teleport with Self-Signed Certificates](./admin/self-signed-certs.mdx): Set up Teleport in a local +- [Run Teleport with Self-Signed Certificates](./admin/self-signed-certs.mdx): Set up Teleport in a local environment without configuring TLS certificates. ## Manage users and resources @@ -30,5 +30,4 @@ environment without configuring TLS certificates. ## Troubleshoot issues - [Troubleshooting](./admin/troubleshooting.mdx): Collect metrics and diagnostic information from Teleport. - - +- [Uninstall Teleport](./admin/uninstall-teleport.mdx): Uninstall Teleport from your system. diff --git a/docs/pages/management/admin/uninstall-teleport.mdx b/docs/pages/management/admin/uninstall-teleport.mdx new file mode 100644 index 00000000000..2f893abdcff --- /dev/null +++ b/docs/pages/management/admin/uninstall-teleport.mdx @@ -0,0 +1,502 @@ +--- +title: Uninstall Teleport +description: How to remove Teleport from your system +--- + +This guide explains how to uninstall Teleport binaries completely. + +## Prerequisites + +- A system with Teleport installed. + + +These instructions only apply to non-containerized installations of Teleport. + +If you are running Teleport in Kubernetes, you should uninstall the Helm chart release instead: + +```code +# Example: uninstall the Helm release named 'teleport-kube-agent' in the 'teleport' namespace +$ helm uninstall --namespace teleport teleport-kube-agent +``` + +If you are running Teleport in Docker, you should stop the Teleport Docker container: + +```code +# Example: Stop the Docker container named 'teleport' +$ docker stop teleport +``` + + +## Step 1/3. Stop any running Teleport processes + + + + Instruct `systemd` to stop the Teleport process, and disable it from automatically starting: + + ```code + $ sudo systemctl stop teleport + $ sudo systemctl disable teleport + ``` + + If these `systemd` commands do not work, you can "kill" all the running Teleport processes instead: + + ```code + $ sudo killall teleport + ``` + + + + Instruct `launchd` to stop the Teleport process, and disable it from automatically starting: + + ```code + $ sudo launchctl unload -w /Library/LaunchDaemons/com.goteleport.teleport.plist + $ sudo rm -f /Library/LaunchDaemons/com.goteleport.teleport.plist + ``` + + If these commands do not work, you can "kill" all the running Teleport processes instead: + + ```code + $ sudo killall teleport + ``` + + + + + There are currently no long-running Teleport processes on Windows machines. + + + + +## Step 2/3. Remove Teleport binaries + + + + + + + Uninstall the Teleport binary using APT: + + ```code + $ sudo apt-get -y remove teleport + ``` + + Uninstall the Teleport APT repo: + + ```code + $ sudo rm -f /etc/apt/sources.list.d/teleport.list + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone DEB package. Remove it with: + + ```code + $ sudo dpkg -r teleport + ``` + + + + + + Uninstall the Teleport binary using YUM: + + ```code + $ sudo yum -y remove teleport + # Optional: Use DNF on newer distributions + # $ sudo dnf -y remove teleport + ``` + + Uninstall the Teleport YUM repo: + + ```code + $ sudo rm -f /etc/yum.repos.d/teleport.repo + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone RPM package. Remove it with: + + ```code + $ sudo rpm -e teleport + ``` + + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + If you installed the MacOS `tsh`-only package and/or Teleport Connect for MacOS, you can optionally remove those too: + + ```code + $ sudo rm -f /Applications/tsh.app + $ sudo rm -f /Applications/Teleport\ Connect.app + ``` + + + + + + Remove the `tsh.exe` binary from the machine: + + ```code + $ del C:\Path\To\tsh.exe + ``` + + You can uninstall Teleport Connect from the "Apps and Features" section of the Control Panel. + + For reference, Teleport Connect binaries are installed to `%LOCALAPPDATA%\Programs\teleport-connect`. + + + + + + + + + + Uninstall the Teleport binary using APT: + + ```code + $ sudo apt-get -y remove teleport-ent + # Optional: If using the Teleport FIPS package + # $ sudo apt-get -y remove teleport-ent-fips + ``` + + Uninstall the Teleport APT repo: + + ```code + $ sudo rm -f /etc/apt/sources.list.d/teleport.list + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone DEB package. Remove it with: + + ```code + # Enterprise + $ sudo dpkg -r teleport-ent + # Enterprise FIPS + # $ sudo dpkg -r teleport-ent-fips + ``` + + + + + + Uninstall the Teleport binary using YUM: + + ```code + $ sudo yum -y remove teleport-ent + # Optional: Use DNF on newer distributions + # $ sudo dnf -y remove teleport-ent + # Optional: If using the Teleport FIPS package + # $ sudo yum -y remove teleport-ent-fips + # $ sudo dnf -y remove teleport-ent-fips + ``` + + Uninstall the Teleport YUM repo: + + ```code + $ sudo rm -f /etc/yum.repos.d/teleport.repo + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone RPM package. Remove it with: + + ```code + # Enterprise + $ sudo rpm -e teleport-ent + # Enterprise FIPS + # $ sudo rpm -e teleport-ent-fips + ``` + + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + If you installed the MacOS `tsh` client-only package and/or Teleport Connect for MacOS, you can optionally remove those too: + + ```code + $ sudo rm -f /Applications/tsh.app + $ sudo rm -f /Applications/Teleport\ Connect.app + ``` + + + + + + Remove the `tsh.exe` binary from the machine: + + ```code + $ del C:\Path\To\tsh.exe + ``` + + You can uninstall Teleport Connect from the "Apps and Features" section of the Control Panel. + + For reference, Teleport Connect binaries are installed to `%LOCALAPPDATA%\Programs\teleport-connect`. + + + + + + + + + + Uninstall the Teleport binary using APT: + + ```code + $ sudo apt-get -y remove teleport-ent + # NOTE: Older Cloud users may be running OSS binaries instead + # $ sudo apt-get -y remove teleport + ``` + + Uninstall the Teleport APT repo: + + ```code + $ sudo rm -f /etc/apt/sources.list.d/teleport.list + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone DEB package. Remove it with: + + ```code + $ sudo dpkg -r teleport-ent + # NOTE: Older Cloud users may be running OSS binaries instead + # $ sudo dpkg -r teleport + ``` + + + + + + Uninstall the Teleport binary using YUM: + + ```code + $ sudo yum -y remove teleport-ent + # Optional: Use DNF on newer distributions + # $ sudo dnf -y remove teleport-ent + # NOTE: Older Cloud users may be running OSS binaries instead + # $ sudo yum -y remove teleport + # $ sudo dnf -y remove teleport + ``` + + Uninstall the Teleport YUM repo: + + ```code + $ sudo rm -f /etc/yum.repos.d/teleport.repo + ``` + + + If the commands above do not work, you may have installed Teleport using a standalone RPM package. Remove it with: + + ```code + $ sudo rpm -e teleport-ent + # NOTE: Older Cloud users may be running OSS binaries instead + # $ sudo rpm -e teleport + ``` + + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + + + + These are the default paths to the Teleport binaries. If you have changed these from the defaults on your system, substitute those paths here. + You can use `dirname $(which teleport)` to look this up automatically. + + + Remove the Teleport binaries from the machine: + + ```code + $ sudo rm -f /usr/local/bin/tbot + $ sudo rm -f /usr/local/bin/tctl + $ sudo rm -f /usr/local/bin/teleport + $ sudo rm -f /usr/local/bin/tsh + ``` + + + If you installed the MacOS `tsh` client-only package and/or Teleport Connect for MacOS, you can optionally remove those too: + + ```code + $ sudo rm -f /Applications/tsh.app + $ sudo rm -f /Applications/Teleport\ Connect.app + ``` + + + + + + Remove the `tsh.exe` binary from the machine: + + ```code + $ del C:\Path\To\tsh.exe + ``` + + You can uninstall Teleport Connect from the "Apps and Features" section of the Control Panel. + + For reference, Teleport Connect binaries are installed to `%LOCALAPPDATA%\Programs\teleport-connect`. + + + + + + +## Step 3/3. Remove Teleport data and configuration files + + + + + These are the default paths to the Teleport config files and data directory. + If you have changed these from the defaults on your system, substitute those paths here. + + + Remove the Teleport config file: + + ```code + $ sudo rm -f /etc/teleport.yaml + # Optional: Also remove the Machine ID config file, if you used it + # $ sudo rm -f /etc/tbot.yaml + ``` + + Remove the Teleport data directory: + + ```code + $ sudo rm -rf /var/lib/teleport + ``` + + Optionally, also remove the global config file and local user data directory for `tsh`: + + ```code + $ sudo rm -f /etc/tsh.yaml + $ sudo rm -rf ~/.tsh + ``` + + + + These are the default paths to the Teleport config files and data directory. + If you have changed these from the defaults on your system, substitute those paths here. + + + Remove the Teleport config file: + + ```code + $ sudo rm -f /etc/teleport.yaml + # Optional: Also remove the Machine ID config file, if you used it + # $ sudo rm -f /etc/tbot.yaml + ``` + + Remove the Teleport data directory: + + ```code + $ sudo rm -rf /var/lib/teleport + ``` + + Optionally, also remove: + - the global config file and local user data directory for `tsh` + - the local user data directory for Teleport Connect + + ```code + # tsh + $ sudo rm -f /etc/tsh.yaml + $ sudo rm -rf ~/.tsh + # Teleport Connect + $ sudo rm -rf ~/Library/Application\ Support/Teleport\ Connect + ``` + + + + Remove the local user data directory for `tsh`: + + ```code + $ rmdir /s /q %USERPROFILE%\.tsh + ``` + + Optionally, also remove the local user data directory for Teleport Connect: + + ```code + $ rmdir /s /q "%APPDATA%\Teleport Connect" + ``` + + + + +Teleport is now removed from your system. + +Any Teleport Services will stop appearing in your Teleport Web UI or the output of `tsh ls` once their last heartbeat has timed out. This usually occurs within 10-15 minutes of stopping the Teleport process.