Restructure ssh doc

source/content/certification/study-guide-cms/06-deploy.md

@@ -188,7 +188,7 @@ In this section, we will walk through the process of generating SSH keys and add
 
     **Multiple SSH Keys**
 
-    If you have multiple SSH keys for different purposes and want to tell all of your Pantheon sites to use a specific key, you can configure your local ssh setup to use one key for all Pantheon servers. Follow the instructions here: https://web.berkeley.edu/web-hosting-pantheon/hosting-your-site-pantheon/special-topics-pantheon-sites/using-ssh-keys
+    If you have multiple SSH keys for different purposes and want to tell all of your Pantheon sites to use a specific key, you can [configure your local ssh setup to use one key for all Pantheon servers](/ssh-keys/#manage-multiple-keys-optional).
 
 2. **Set a passphrase for better security.** We recommend using a passphrase, but it can conflict with some tools.
 

source/content/ssh-keys.md

@@ -2,7 +2,7 @@
 title: Generate and Add SSH Keys
 description: Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.
 tags: [security, dashboard, ssh]
-reviewed: "2022-03-04"
+reviewed: "2025-02-05"
 contenttype: [doc]
 innav: [true]
 categories: [security, git, config]
@@ -17,25 +17,22 @@ Interacting with remote Pantheon environments via Git, SFTP, WP-CLI, and Drush r
 
 Pantheon does not provide access to a shell environment over SSH. These directions allow you to authenticate operations on Pantheon like  Git, SFTP, WP-CLI or Drush via SSH keys.
 
+Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` keys.
+
 </Alert>
 
-## Generate an SSH Key
+## Generate an SSH key
 
 Use the steps in this section to generate your SSH key.
 
-<Alert title="Note"  type="info" >
-
-Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` keys.
-
-</Alert>
-
 <Accordion title="Watch: Generate a SSH Key and Add it to Your Dashboard" id="ssh-video" icon="facetime-video">
 
 <Youtube src="U8sfuvrjroY" title="Generate a SSH Key and Add it to Your Dashboard" />
 
 </Accordion>
 
-### MacOS/Linux
+### Create the key locally
+The following steps are compatible with MacOS, Linux, and the Windows Subsystem for Linux (WSL). Windows users must [install WSL](https://learn.microsoft.com/en-us/windows/wsl/) before proceeding to the steps below.
 
 1. Open your terminal and enter the following command to generate a key:
 
@@ -51,8 +48,6 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
 1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
 
-   MacOS users can `cat`the file to the terminal and copy the output:
-
    ```bash{promptUser: user}
    cat ~/.ssh/id_rsa.pub
    ```
@@ -70,39 +65,10 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
    ssh-add ~/.ssh/id_rsa
    ```
 
-### Windows
-
-1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:
-
-   ```bash{promptUser: winshell}
-   ssh-keygen -t rsa -m PEM
-   ```
-
-  Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
-
-1. Set a passphrase for better security.
-
-   We recommend using a passphrase, but it can conflict with some tools.
+## Add your SSH key to Pantheon
+<TabList>
 
-1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
-
-   ```bash{promptUser: winshell}
-   type .ssh\id_rsa.pub
-   ```
-
-1.  Run `start-ssh-agent` to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.
-
-      ```bash{promptUser: winshell}{outputLines: 2,3,5}
-      start-ssh-agent
-      Removing old ssh-agent sockets
-      Starting ssh-agent:  done
-      Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
-      Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])
-      ```
-
-## Add Your SSH Key to Pantheon
-
-### Add SSH Key - New Dashboard
+<Tab title="New Dashboard" id="phoebe-add-key" active={true}>
 
 1. Log in to your Pantheon Dashboard.
 
@@ -116,7 +82,9 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
   Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.
 
-### Add SSH Key - Classic Dashboard
+</Tab>
+
+<Tab title="Legacy Dashboard" id="hermes-add-key">
 
 1. Log in to your Pantheon Dashboard.
 
@@ -130,19 +98,68 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
 1. Click the **Add Key** button.
 
-  Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.
+  Your local machine is now set up to securely connect to remote Pantheon environments. This page will show you all keys associated with your user account.
+
+</Tab>
+</TabList>
+
 
-### Clone Your Site Code
+### Test your new key (optional)
 
-You can use your Dev environment to clone your site code to your workstation:
+Try out your new key by interacting with your site using any one of the following methods:
+* [Use git to clone your site repository locally](/guides/git/git-config#clone-your-site-codebase)
+* [Use your preferred SFTP client to connect to a remote Pantheon environment](/guides/sftp/sftp-connection-info#sftp-connection-info)
+* Use [Terminus](/terminus/install) to invoke WP-CLI or Drush commands:
+
+   <TabList>
+
+   <Tab title="WP-CLI" id="wpcli" active={true}>
+
+   Replace `<site>` with your sitename:
+
+   ```bash
+   terminus wp <site>.dev -- cli version
+   ```
 
-1. Use Terminal to copy the **SSH clone URL** from the site's **Connection Info**.
+   </Tab>
 
-1. Enter the passphrase you set above, if prompted.
+   <Tab title="Drush" id="drush">
+
+   Replace `<site>` with your sitename:
+
+   ```bash
+   terminus drush <site>.dev -- status
+   ```
+
+   </Tab>
+   </TabList>
+
+### Manage multiple keys (optional)
+If you use multiple SSH keys to routinely authenticate your machine with other platforms or services other than Pantheon, you may benefit by configuring specific keys according to their specific usage.
+
+For example, the following configuration tells your Pantheon sites to use your Pantheon key, while using a separate key for GitHub:
+
+```bash:title=~/.ssh/config
+Host github
+    User git
+    Hostname github.com
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/github_rsa
+
+Host codeserver.*.drush.in
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/pantheon_rsa
+```
 
 ## Remove SSH Key from Pantheon
+After removing SSH Keys from your user account, you will not be able to interact with remote Pantheon application and codeservers via Git, SFTP, Drush, or WP-CLI.
+
+Removing SSH keys is separate from [revoking the machine tokens used by Terminus](/machine-tokens#revoke-a-machine-token) to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.
+
+<TabList>
+
+<Tab title="New Dashboard" id="phoebe-revoke-key" active={true}>
 
-### Revoke SSH Key from Pantheon - New Dashboard
 
 1. Log in to your Pantheon Dashboard.
 
@@ -154,15 +171,15 @@ You can use your Dev environment to clone your site code to your workstation:
 
 1. Check the box in the confirmation prompt and click continue.
 
-
-### Remove SSH Key from Pantheon - Classic Dashboard
+</Tab>
+<Tab title="Legacy Dashboard" id="hermes-revoke-key">
 
 1. Navigate to the **<Icon icon="gear" /> Account** tab of your User Dashboard and click **SSH Keys**.
 
 1. Click the **Remove** button next to the key you want to delete:
 
-### Site Access After Removing Keys
-After removing SSH Keys from your user account, you will not be able to interact with the application and codeservers directly through command line interfaces like Git, SFTP, WP-CLI, and Drush. However removing SSH keys is separate from revoking the machine tokens used by Terminus to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.
+</Tab>
+</TabList>
 
 ## Troubleshooting
 
@@ -230,3 +247,40 @@ Host *.drush.in
  Pantheon does not have access to keys that only exist on the host machine. You must ensure that your keys and, if applicable, your key agent are made available to the application running in the container, if you're using Lando, Docksal, or DDEV.
 
 </Alert>
+
+### What if I can't install the Windows Subsystem for Linux?
+Consider that [Terminus, Pantheon's command-line interface, requires WSL for compatibility](/terminus/install#compatibility-and-requirements). This is why the [process above](#create-the-key-locally) expects WSL to be installed, however it is not a hard required for generating SSH keys.
+
+If you are a Windows user and you are unable to install WSL on your machine, you may use the following process as an alternative:
+
+<Accordion title="Alternative steps to generate SSH keys on Windows" id="windows-no-wsl" icon="question-sign">
+
+1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:
+
+   ```bash{promptUser: winshell}
+   ssh-keygen -t rsa -m PEM
+   ```
+
+  Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
+
+1. Set a passphrase for better security.
+
+   We recommend using a passphrase, but it can conflict with some tools.
+
+1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
+
+   ```bash{promptUser: winshell}
+   type .ssh\id_rsa.pub
+   ```
+
+1.  Run `start-ssh-agent` to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.
+
+      ```bash{promptUser: winshell}{outputLines: 2,3,5}
+      start-ssh-agent
+      Removing old ssh-agent sockets
+      Starting ssh-agent:  done
+      Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
+      Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])
+      ```
+
+</Accordion>