From 264bc1bfecfa0d7af1cb095146bb2e5180d9a107 Mon Sep 17 00:00:00 2001 From: Justin Lin Date: Tue, 15 Jul 2025 15:17:48 -0700 Subject: [PATCH 1/4] Updating SSH tips for password-based ssh --- pods/configuration/use-ssh.mdx | 203 ++++++++++++++++++++++++++++++++ pods/storage/transfer-files.mdx | 18 ++- 2 files changed, 219 insertions(+), 2 deletions(-) diff --git a/pods/configuration/use-ssh.mdx b/pods/configuration/use-ssh.mdx index aa602474..cae4f93a 100644 --- a/pods/configuration/use-ssh.mdx +++ b/pods/configuration/use-ssh.mdx @@ -8,8 +8,211 @@ Connecting to a Pod through an SSH (Secure Shell) terminal provides a secure and Every Pod offers the ability to connect through SSH using the [basic proxy method](#basic-ssh-connection) below (which does not support commands like SCP or SFTP), but not all Pods support the [full public IP method](#full-ssh-connection-via-public-ip). +There are two methods to cover: +1. Password based SSH +This is best for an already running pod and to avoid SSH key configurations and complexity. Recommended if you just need a quick-and-easy way to get SSH running. + +2. SSH Key +This is best for long-term usage. If you plan to SSH into your pods frequently such as setting up to work with VSCode or to manage your pods through terminal then this is recommended. + +## Password-based SSH + + +**Prerequisites for password-based SSH:** +- Your Pod must have a public IP address (available on most GPU instances) +- Your Pod template must expose TCP port 22 (SSH will be accessible on a mapped external port) + +Note: While SSH runs on port 22 inside your Pod, RunPod maps it to a different external port. The script will automatically uses the correct external port from the `RUNPOD_TCP_PORT_22` environment variable. + +If you see "Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing" when running the script you might be missing one of the prerequisites. + + +To quickly set up password-based SSH, copy and paste this one-liner into your Pod's terminal: + +```bash expandable Password-based SSH Script +cat > /tmp/setup_ssh.sh << 'EOF' && chmod +x /tmp/setup_ssh.sh && /tmp/setup_ssh.sh +#!/bin/bash + +# Function to print in color +print_color() { + COLOR=$1 + TEXT=$2 + case $COLOR in + "green") echo -e "\e[32m$TEXT\e[0m" ;; + "red") echo -e "\e[31m$TEXT\e[0m" ;; + "yellow") echo -e "\e[33m$TEXT\e[0m" ;; + "blue") echo -e "\e[34m$TEXT\e[0m" ;; + *) echo "$TEXT" ;; + esac +} + +# Function to prompt for password +get_password() { + while true; do + print_color "blue" "Enter a password for root user:" + read -s root_password + echo + + print_color "blue" "Confirm password:" + read -s confirm_password + echo + + if [ "$root_password" = "$confirm_password" ]; then + print_color "green" "Password confirmed successfully." + break + else + print_color "red" "Passwords do not match. Please try again." + fi + done +} + +# Check for OS Type +print_color "blue" "Detecting Linux Distribution..." +os_info=$(cat /etc/*release) +print_color "yellow" "OS Detected: $os_info" + +# Check for SSH Server and install if necessary +if ! command -v sshd >/dev/null; then + print_color "yellow" "SSH server not found. Installing..." + if [[ $os_info == *"debian"* || $os_info == *"ubuntu"* ]]; then + apt-get update && apt-get install -y openssh-server + elif [[ $os_info == *"redhat"* || $os_info == *"centos"* ]]; then + yum install -y openssh-server + else + print_color "red" "Unsupported Linux distribution for automatic SSH installation." + exit 1 + fi + print_color "green" "SSH Server Installed Successfully." +else + print_color "green" "SSH Server is already installed." +fi + +# Configure SSH to allow root login +print_color "blue" "Configuring SSH to allow root login with a password..." +sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config +sed -i 's/#PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config +service ssh restart +print_color "green" "SSH Configuration Updated." + +# Get custom password from user +get_password + +# Set the custom password for root +print_color "blue" "Setting custom password for root..." +echo "root:$root_password" | chpasswd +echo $root_password > /workspace/root_password.txt +print_color "green" "Root password set and saved in /workspace/root_password.txt" + +# Check if environment variables are set +print_color "blue" "Checking environment variables..." +if [ -z "$RUNPOD_PUBLIC_IP" ] || [ -z "$RUNPOD_TCP_PORT_22" ]; then + print_color "red" "Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing." + exit 1 +fi +print_color "green" "Environment variables are set." + +# Create connection script for Windows (.bat) +print_color "blue" "Creating connection script for Windows..." +echo "@echo off" > /workspace/connect_windows.bat +echo "echo ========================================" >> /workspace/connect_windows.bat +echo "echo SSH CONNECTION" >> /workspace/connect_windows.bat +echo "echo ========================================" >> /workspace/connect_windows.bat +echo "echo Root password: $root_password" >> /workspace/connect_windows.bat +echo "echo." >> /workspace/connect_windows.bat +echo "echo To connect via SSH:" >> /workspace/connect_windows.bat +echo "echo ssh root@$RUNPOD_PUBLIC_IP -p $RUNPOD_TCP_PORT_22" >> /workspace/connect_windows.bat +echo "echo." >> /workspace/connect_windows.bat +echo "echo ========================================" >> /workspace/connect_windows.bat +echo "echo FILE TRANSFER EXAMPLES (SCP)" >> /workspace/connect_windows.bat +echo "echo ========================================" >> /workspace/connect_windows.bat +echo "echo." >> /workspace/connect_windows.bat +echo "echo Copy file TO pod:" >> /workspace/connect_windows.bat +echo "echo scp -P $RUNPOD_TCP_PORT_22 yourfile.txt root@$RUNPOD_PUBLIC_IP:/workspace/" >> /workspace/connect_windows.bat +echo "echo." >> /workspace/connect_windows.bat +echo "echo Copy file FROM pod:" >> /workspace/connect_windows.bat +echo "echo scp -P $RUNPOD_TCP_PORT_22 root@$RUNPOD_PUBLIC_IP:/workspace/yourfile.txt ." >> /workspace/connect_windows.bat +echo "echo." >> /workspace/connect_windows.bat +echo "echo Copy entire folder TO pod:" >> /workspace/connect_windows.bat +echo "echo scp -P $RUNPOD_TCP_PORT_22 -r yourfolder root@$RUNPOD_PUBLIC_IP:/workspace/" >> /workspace/connect_windows.bat +echo "echo ========================================" >> /workspace/connect_windows.bat +print_color "green" "Windows connection script created in /workspace." + +# Create connection script for Linux/Mac (.sh) +print_color "blue" "Creating connection script for Linux/Mac..." +echo "#!/bin/bash" > /workspace/connect_linux.sh +echo "echo '========================================'" >> /workspace/connect_linux.sh +echo "echo 'SSH CONNECTION'" >> /workspace/connect_linux.sh +echo "echo '========================================'" >> /workspace/connect_linux.sh +echo "echo 'Root password: $root_password'" >> /workspace/connect_linux.sh +echo "echo ''" >> /workspace/connect_linux.sh +echo "echo 'To connect via SSH:'" >> /workspace/connect_linux.sh +echo "echo 'ssh root@$RUNPOD_PUBLIC_IP -p $RUNPOD_TCP_PORT_22'" >> /workspace/connect_linux.sh +echo "echo ''" >> /workspace/connect_linux.sh +echo "echo '========================================'" >> /workspace/connect_linux.sh +echo "echo 'FILE TRANSFER EXAMPLES (SCP)'" >> /workspace/connect_linux.sh +echo "echo '========================================'" >> /workspace/connect_linux.sh +echo "echo ''" >> /workspace/connect_linux.sh +echo "echo 'Copy file TO pod:'" >> /workspace/connect_linux.sh +echo "echo 'scp -P $RUNPOD_TCP_PORT_22 yourfile.txt root@$RUNPOD_PUBLIC_IP:/workspace/'" >> /workspace/connect_linux.sh +echo "echo ''" >> /workspace/connect_linux.sh +echo "echo 'Copy file FROM pod:'" >> /workspace/connect_linux.sh +echo "echo 'scp -P $RUNPOD_TCP_PORT_22 root@$RUNPOD_PUBLIC_IP:/workspace/yourfile.txt .'" >> /workspace/connect_linux.sh +echo "echo ''" >> /workspace/connect_linux.sh +echo "echo 'Copy entire folder TO pod:'" >> /workspace/connect_linux.sh +echo "echo 'scp -P $RUNPOD_TCP_PORT_22 -r yourfolder root@$RUNPOD_PUBLIC_IP:/workspace/'" >> /workspace/connect_linux.sh +echo "echo '========================================'" >> /workspace/connect_linux.sh +chmod +x /workspace/connect_linux.sh +print_color "green" "Linux/Mac connection script created in /workspace." + +print_color "green" "Setup Completed Successfully!" +echo "" +print_color "yellow" "========================================" +print_color "yellow" "SSH CONNECTION" +print_color "yellow" "========================================" +print_color "yellow" "Connect using: ssh root@$RUNPOD_PUBLIC_IP -p $RUNPOD_TCP_PORT_22" +print_color "yellow" "Password: $root_password" +echo "" +print_color "blue" "========================================" +print_color "blue" "FILE TRANSFER EXAMPLES (SCP)" +print_color "blue" "========================================" +print_color "blue" "Copy file TO pod:" +echo "scp -P $RUNPOD_TCP_PORT_22 yourfile.txt root@$RUNPOD_PUBLIC_IP:/workspace/" +echo "" +print_color "blue" "Copy file FROM pod:" +echo "scp -P $RUNPOD_TCP_PORT_22 root@$RUNPOD_PUBLIC_IP:/workspace/yourfile.txt ." +echo "" +print_color "blue" "Copy entire folder TO pod:" +echo "scp -P $RUNPOD_TCP_PORT_22 -r yourfolder root@$RUNPOD_PUBLIC_IP:/workspace/" +echo "" +print_color "green" "Connection scripts saved in /workspace/connect_windows.bat and /workspace/connect_linux.sh" +EOF +``` + +After pasting the script into your terminal and following the prompt for password, you'll see example commands you can use for SSH or SCP. +```bash +======================================== +SSH CONNECTION +======================================== +Connect using: ssh root@38.80.152.73 -p 32061 +Password: helloworld + +======================================== +FILE TRANSFER EXAMPLES (SCP) +======================================== +Copy file TO pod: +scp -P 32061 yourfile.txt root@38.80.152.73:/workspace/ + +Copy file FROM pod: +scp -P 32061 root@38.80.152.73:/workspace/yourfile.txt . + +Copy entire folder TO pod: +scp -P 32061 -r yourfolder root@38.80.152.73:/workspace/ +``` + ## Generate an SSH key and add it to your Runpod account +This is best for long term usage of SSH as every time you start up a pod, the SSH key will be set to the environment variable of the pod. + 1. Generate an SSH key using this command on your local terminal: ```sh diff --git a/pods/storage/transfer-files.mdx b/pods/storage/transfer-files.mdx index 56473c13..9835f371 100644 --- a/pods/storage/transfer-files.mdx +++ b/pods/storage/transfer-files.mdx @@ -10,6 +10,18 @@ Learn to transfer files to and from Runpod. +## Overview + +There are several methods to transfer files between your local machine and Pods. Each method has different advantages depending on your use case: + +**runpodctl** is the simplest option for occasional small file transfers. It's pre-installed on all Pods, requires no setup, and uses secure one-time codes for authentication. Best for quick transfers of individual files or small datasets. + +**SCP** provides a standard, reliable way to transfer files over SSH. It works well for both individual files and directories, and is ideal for users already familiar with command-line tools. Requires SSH configuration on your Pod. + +**rsync** offers the most advanced features, including incremental transfers, compression, and detailed progress reporting. It's perfect for large datasets, regular synchronization tasks, or when you need to preserve file attributes. Also requires SSH configuration. + +**Cloud sync** enables direct synchronization with cloud storage providers like AWS S3, Google Cloud Storage, or Dropbox. Best for backing up data or sharing files across multiple environments. + ## Prerequisites * If you intend to use `runpodctl`, make sure it's installed on your machine, see [install runpodctl](/runpodctl/install-runpodctl) @@ -22,7 +34,7 @@ Learn to transfer files to and from Runpod. ## Transferring with [runpodctl](/runpodctl/overview#data-transfer) -The Runpod CLI (runpodctl) provides simple commands for transferring data between your machine and Runpod. **It’s preinstalled on all Runpod Pods** and uses one-time codes for secure authentication, so no API keys are required. +The Runpod CLI (runpodctl) provides simple commands for transferring data between your machine and Runpod. **It’s preinstalled on all Runpod Pods** and uses one-time codes for secure authentication, so no API keys are required. If you are transferring large files, it is recommended to use the other methods such as ssh/scp. #### Sending a File @@ -69,7 +81,9 @@ scp -P 43201 -i ~/.ssh/id_ed25519 /local/file/path root@194.26.196.6:/destinatio -If your private key file is in a location other than `~/.ssh/id_ed25519` or you're using the Windows Command Prompt, make sure you update this path accordingly in your command. +If your private key file is in a location other than `~/.ssh/id_ed25519` or you're using the Windows Command Prompt, make sure you update this path accordingly in your command. + +It is also recommended to look to the [password based ssh](/pods/configuration/use-ssh#password-based-ssh) if you just need a quick-one-time setup. From 51b9a0bc0458463d1bc76ec68de2544a8a3f1eb7 Mon Sep 17 00:00:00 2001 From: Mo King Date: Wed, 16 Jul 2025 14:38:38 -0400 Subject: [PATCH 2/4] Reorder sections --- pods/configuration/use-ssh.mdx | 240 +++++++++++++++++---------------- 1 file changed, 121 insertions(+), 119 deletions(-) diff --git a/pods/configuration/use-ssh.mdx b/pods/configuration/use-ssh.mdx index cae4f93a..c398757f 100644 --- a/pods/configuration/use-ssh.mdx +++ b/pods/configuration/use-ssh.mdx @@ -15,6 +15,122 @@ This is best for an already running pod and to avoid SSH key configurations and 2. SSH Key This is best for long-term usage. If you plan to SSH into your pods frequently such as setting up to work with VSCode or to manage your pods through terminal then this is recommended. +## Generate an SSH key and add it to your Runpod account + +This is best for long term usage of SSH as every time you start up a pod, the SSH key will be set to the environment variable of the pod. + +1. Generate an SSH key using this command on your local terminal: + + ```sh + ssh-keygen -t ed25519 -C "YOUR_EMAIL@DOMAIN.COM" + ``` + + This saves your public/private key pair to `~/.ssh/id_ed25519.pub` and `~/.ssh/id_ed25519` respectively. + + + + If you are using Command Prompt on Windows instead of the Linux terminal or WSL, your public and private key pair will be saved to `C:\Users\YOUR_USER_ACCOUNT\.ssh\id_ed25519.pub` and `C:\Users\YOUR_USER_ACCOUNT\.ssh\id_ed25519`, respectively. + + + +2. Retrieve your public SSH key by running this command: + + ```sh + cat ~/.ssh/id_ed25519.pub + ``` + + This will output something similar to this: + + ```sh + ssh-ed25519 AAAAC4NzaC1lZDI1JTE5AAAAIGP+L8hnjIcBqUb8NRrDiC32FuJBvRA0m8jLShzgq6BQ YOUR_EMAIL@DOMAIN.COM + ``` + +3. Copy and paste the output into the **SSH Public Keys** field in your [Runpod user account settings](https://www.console.runpod.io/user/settings). + + +If you need to add multiple SSH keys to your Runpod account, make sure that each key pair is on its own line in the **SSH Public Keys** field. + + +### Override public key for a specific Pod + +Runpod will attempt to automatically inject the public SSH keys added in your account settings for authentication when connecting using the [basic terminal method](#basic-ssh-connection). If you prefer to use a different public key for a specific Pod, you can override the default by setting the `SSH_PUBLIC_KEY` environment variable for that Pod. + +## Basic SSH connection + +All Pods provide a basic SSH connection that is proxied through Runpod's systems. This method does not support commands like SCP (Secure Copy Protocol) or SFTP (SSH File Transfer Protocol). + +To connect using this method: + +1. Ensure you have an [SSH key pair](#generate-an-ssh-key-and-add-it-to-your-runpod-account) generated on your local machine and added to your Runpod account. +2. Navigate to the [Pods page](https://console.runpod.io/pods) in the Runpod console. +3. Expand your Pod and select **Connect**. +4. Select the SSH tab. Copy the command listed under **SSH**. It should look something like this: + + ```sh + ssh 8y5rumuyb50m78-6441103b@ssh.runpod.io -i ~/.ssh/id_ed25519 + ``` + + + If you saved your key to a custom location, use that specific path after the `-i` flag instead. + + +5. Run the copied command in your local terminal to connect to your Pod. + +## Full SSH connection via public IP + +For full SSH capabilities, including SCP and SFTP for file transfers, you need to rent an instance that supports a public IP address and ensure an SSH daemon is running within your Pod. + +If you're using a Runpod official template such as Runpod PyTorch or Stable Diffusion, no additional setup is required, as full SSH access is already configured for you. + +However, if you're using a custom template, ensure that TCP port 22 is exposed and that the SSH daemon is running inside your Pod. If it isn't, add the Docker command below to your template (or, if you already have a custom start command, replace `sleep infinity` at the end of your command with this one): + +```sh +bash -c 'apt update;DEBIAN_FRONTEND=noninteractive apt-get install openssh-server -y;mkdir -p ~/.ssh;cd $_;chmod 700 ~/.ssh;echo "$PUBLIC_KEY" >> authorized_keys;chmod 700 authorized_keys;service ssh start;sleep infinity' +``` + +Once you're sure that the SSH daemon is running, you can connect to your Pod by following these steps: + +1. Ensure you have an [SSH key pair](#generate-an-ssh-key-and-add-it-to-your-runpod-account) generated on your local machine and added to your Runpod account. +2. An SSH daemon must be started in your Pod. Runpod official templates, such as "Runpod PyTorch", often have this pre-configured. If you're using a custom template, ensure TCP port 22 is exposed and the SSH daemon is started. Refer to the [Use SSH guide](/pods/configuration/use-ssh) for commands to include in your custom Docker template. +3. Navigate to the [Pods page](https://console.runpod.io/pods) in the Runpod console. +4. Expand your Pod and select **Connect**. +5. Select the SSH tab. Copy the command listed under **SSH over exposed TCP**. It should look something like this: + + ```sh + ssh root@213.173.108.12 -p 17445 -i ~/.ssh/id_ed25519 + ``` + + + If you saved your key to a custom location, use that specific path after the `-i` flag instead. + + +6. Run the copied command in your local terminal to connect to your Pod. + +The SSH command above has the following structure: + +```sh +ssh root@[POD_IP_ADDRESS] -p [SSH_PORT] -i [PATH_TO_SSH_KEY] +``` + +Where: +* `root`: Your assigned username for the Pod (typically `root`). +* `[POD_IP_ADDRESS]`: The public IP address of your Pod. +* `[SSH_PORT]`: The designated public SSH port for your Pod. +* `[PATH_TO_SSH_KEY]`: The local file path to your private SSH key. + +## Troubleshooting + +If you're asked for a password when connecting to your Pod via SSH, this means something is not set up correctly. Runpod does not require a password for SSH connections, as authentication is handled entirely through your SSH key pair. This prompt usually indicates a problem with your SSH key configuration. + +Here are some common reasons why this might happen: + +- If you copy and paste the key *fingerprint* (which starts with `SHA256:`) into your Runpod user settings instead of the actual public key (the contents of your `id_ed25519.pub` file), authentication will fail. +- If you omit the encryption type at the beginning of your public key when pasting it into your Runpod user settings (for example, leaving out `ssh-ed25519`), the key will not be recognized. +- If you add multiple public keys to your Runpod user settings but do not separate them with a newline, only the first key will work. Each key must be on its own line. +- If you specify the wrong file path to your private key when connecting, SSH will not be able to find the correct key (`No such file or directory` error). +- If your private key file is accessible by other users on your machine, SSH may refuse to use it for security reasons (`bad permissions` error). +- If your SSH configuration file (`~/.ssh/config`) points to the wrong private key, you will also be prompted for a password. Make sure the `IdentityFile` entry in your config file matches the private key that corresponds to the public key you added to your Runpod account. + ## Password-based SSH @@ -22,9 +138,11 @@ This is best for long-term usage. If you plan to SSH into your pods frequently s - Your Pod must have a public IP address (available on most GPU instances) - Your Pod template must expose TCP port 22 (SSH will be accessible on a mapped external port) -Note: While SSH runs on port 22 inside your Pod, RunPod maps it to a different external port. The script will automatically uses the correct external port from the `RUNPOD_TCP_PORT_22` environment variable. + +While SSH runs on port 22 inside your Pod, Runpod maps it to a different external port. The script will automatically use the correct external port from the `RUNPOD_TCP_PORT_22` environment variable. -If you see "Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing" when running the script you might be missing one of the prerequisites. +If you see `Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing` when running the script you might be missing one of the prerequisites. + To quickly set up password-based SSH, copy and paste this one-liner into your Pod's terminal: @@ -207,120 +325,4 @@ scp -P 32061 root@38.80.152.73:/workspace/yourfile.txt . Copy entire folder TO pod: scp -P 32061 -r yourfolder root@38.80.152.73:/workspace/ -``` - -## Generate an SSH key and add it to your Runpod account - -This is best for long term usage of SSH as every time you start up a pod, the SSH key will be set to the environment variable of the pod. - -1. Generate an SSH key using this command on your local terminal: - - ```sh - ssh-keygen -t ed25519 -C "YOUR_EMAIL@DOMAIN.COM" - ``` - - This saves your public/private key pair to `~/.ssh/id_ed25519.pub` and `~/.ssh/id_ed25519` respectively. - - - - If you are using Command Prompt on Windows instead of the Linux terminal or WSL, your public and private key pair will be saved to `C:\Users\YOUR_USER_ACCOUNT\.ssh\id_ed25519.pub` and `C:\Users\YOUR_USER_ACCOUNT\.ssh\id_ed25519`, respectively. - - - -2. Retrieve your public SSH key by running this command: - - ```sh - cat ~/.ssh/id_ed25519.pub - ``` - - This will output something similar to this: - - ```sh - ssh-ed25519 AAAAC4NzaC1lZDI1JTE5AAAAIGP+L8hnjIcBqUb8NRrDiC32FuJBvRA0m8jLShzgq6BQ YOUR_EMAIL@DOMAIN.COM - ``` - -3. Copy and paste the output into the **SSH Public Keys** field in your [Runpod user account settings](https://www.console.runpod.io/user/settings). - - -If you need to add multiple SSH keys to your Runpod account, make sure that each key pair is on its own line in the **SSH Public Keys** field. - - -### Override public key for a specific Pod - -Runpod will attempt to automatically inject the public SSH keys added in your account settings for authentication when connecting using the [basic terminal method](#basic-ssh-connection). If you prefer to use a different public key for a specific Pod, you can override the default by setting the `SSH_PUBLIC_KEY` environment variable for that Pod. - -## Basic SSH connection - -All Pods provide a basic SSH connection that is proxied through Runpod's systems. This method does not support commands like SCP (Secure Copy Protocol) or SFTP (SSH File Transfer Protocol). - -To connect using this method: - -1. Ensure you have an [SSH key pair](#generate-an-ssh-key-and-add-it-to-your-runpod-account) generated on your local machine and added to your Runpod account. -2. Navigate to the [Pods page](https://console.runpod.io/pods) in the Runpod console. -3. Expand your Pod and select **Connect**. -4. Select the SSH tab. Copy the command listed under **SSH**. It should look something like this: - - ```sh - ssh 8y5rumuyb50m78-6441103b@ssh.runpod.io -i ~/.ssh/id_ed25519 - ``` - - - If you saved your key to a custom location, use that specific path after the `-i` flag instead. - - -5. Run the copied command in your local terminal to connect to your Pod. - -## Full SSH connection via public IP - -For full SSH capabilities, including SCP and SFTP for file transfers, you need to rent an instance that supports a public IP address and ensure an SSH daemon is running within your Pod. - -If you're using a Runpod official template such as Runpod PyTorch or Stable Diffusion, no additional setup is required, as full SSH access is already configured for you. - -However, if you're using a custom template, ensure that TCP port 22 is exposed and that the SSH daemon is running inside your Pod. If it isn't, add the Docker command below to your template (or, if you already have a custom start command, replace `sleep infinity` at the end of your command with this one): - -```sh -bash -c 'apt update;DEBIAN_FRONTEND=noninteractive apt-get install openssh-server -y;mkdir -p ~/.ssh;cd $_;chmod 700 ~/.ssh;echo "$PUBLIC_KEY" >> authorized_keys;chmod 700 authorized_keys;service ssh start;sleep infinity' -``` - -Once you're sure that the SSH daemon is running, you can connect to your Pod by following these steps: - -1. Ensure you have an [SSH key pair](#generate-an-ssh-key-and-add-it-to-your-runpod-account) generated on your local machine and added to your Runpod account. -2. An SSH daemon must be started in your Pod. Runpod official templates, such as "Runpod PyTorch", often have this pre-configured. If you're using a custom template, ensure TCP port 22 is exposed and the SSH daemon is started. Refer to the [Use SSH guide](/pods/configuration/use-ssh) for commands to include in your custom Docker template. -3. Navigate to the [Pods page](https://console.runpod.io/pods) in the Runpod console. -4. Expand your Pod and select **Connect**. -5. Select the SSH tab. Copy the command listed under **SSH over exposed TCP**. It should look something like this: - - ```sh - ssh root@213.173.108.12 -p 17445 -i ~/.ssh/id_ed25519 - ``` - - - If you saved your key to a custom location, use that specific path after the `-i` flag instead. - - -6. Run the copied command in your local terminal to connect to your Pod. - -The SSH command above has the following structure: - -```sh -ssh root@[POD_IP_ADDRESS] -p [SSH_PORT] -i [PATH_TO_SSH_KEY] -``` - -Where: -* `root`: Your assigned username for the Pod (typically `root`). -* `[POD_IP_ADDRESS]`: The public IP address of your Pod. -* `[SSH_PORT]`: The designated public SSH port for your Pod. -* `[PATH_TO_SSH_KEY]`: The local file path to your private SSH key. - -## Troubleshooting - -If you're asked for a password when connecting to your Pod via SSH, this means something is not set up correctly. Runpod does not require a password for SSH connections, as authentication is handled entirely through your SSH key pair. This prompt usually indicates a problem with your SSH key configuration. - -Here are some common reasons why this might happen: - -- If you copy and paste the key *fingerprint* (which starts with `SHA256:`) into your Runpod user settings instead of the actual public key (the contents of your `id_ed25519.pub` file), authentication will fail. -- If you omit the encryption type at the beginning of your public key when pasting it into your Runpod user settings (for example, leaving out `ssh-ed25519`), the key will not be recognized. -- If you add multiple public keys to your Runpod user settings but do not separate them with a newline, only the first key will work. Each key must be on its own line. -- If you specify the wrong file path to your private key when connecting, SSH will not be able to find the correct key (`No such file or directory` error). -- If your private key file is accessible by other users on your machine, SSH may refuse to use it for security reasons (`bad permissions` error). -- If your SSH configuration file (`~/.ssh/config`) points to the wrong private key, you will also be prompted for a password. Make sure the `IdentityFile` entry in your config file matches the private key that corresponds to the public key you added to your Runpod account. \ No newline at end of file +``` \ No newline at end of file From a0499d73b1bac4a8cb36e680191aa4caa95cd5ec Mon Sep 17 00:00:00 2001 From: Mo King Date: Thu, 17 Jul 2025 12:38:49 -0400 Subject: [PATCH 3/4] Rewrite password-based SSH section and intro --- pods/configuration/use-ssh.mdx | 39 +++++++++++++--------------------- 1 file changed, 15 insertions(+), 24 deletions(-) diff --git a/pods/configuration/use-ssh.mdx b/pods/configuration/use-ssh.mdx index c398757f..e08b7778 100644 --- a/pods/configuration/use-ssh.mdx +++ b/pods/configuration/use-ssh.mdx @@ -6,14 +6,9 @@ description: "Connect to your Pods with SSH to manage long-running processes and Connecting to a Pod through an SSH (Secure Shell) terminal provides a secure and reliable method for interacting with your instance. Use this to manage long-running processes, critical tasks, and when you need the full capabilities of a shell environment. -Every Pod offers the ability to connect through SSH using the [basic proxy method](#basic-ssh-connection) below (which does not support commands like SCP or SFTP), but not all Pods support the [full public IP method](#full-ssh-connection-via-public-ip). +Every Pod offers the ability to connect through SSH using the [basic proxy method](#basic-ssh-with-key-authentication) below (which does not support commands like SCP or SFTP), but not all Pods support the [full public IP method](#full-ssh-via-public-ip-with-key-authentication). -There are two methods to cover: -1. Password based SSH -This is best for an already running pod and to avoid SSH key configurations and complexity. Recommended if you just need a quick-and-easy way to get SSH running. - -2. SSH Key -This is best for long-term usage. If you plan to SSH into your pods frequently such as setting up to work with VSCode or to manage your pods through terminal then this is recommended. +You can also SSH into a Pod using a [password-based method](#password-based-ssh) if you want a simple and fast way to enable SSH access without setting up SSH keys. However, SSH key authentication is recommended for most use cases, as it provides greater security and convenience for repeated use. ## Generate an SSH key and add it to your Runpod account @@ -55,7 +50,7 @@ If you need to add multiple SSH keys to your Runpod account, make sure that each Runpod will attempt to automatically inject the public SSH keys added in your account settings for authentication when connecting using the [basic terminal method](#basic-ssh-connection). If you prefer to use a different public key for a specific Pod, you can override the default by setting the `SSH_PUBLIC_KEY` environment variable for that Pod. -## Basic SSH connection +## Basic SSH with key authentication All Pods provide a basic SSH connection that is proxied through Runpod's systems. This method does not support commands like SCP (Secure Copy Protocol) or SFTP (SSH File Transfer Protocol). @@ -76,7 +71,7 @@ To connect using this method: 5. Run the copied command in your local terminal to connect to your Pod. -## Full SSH connection via public IP +## Full SSH via public IP with key authentication For full SSH capabilities, including SCP and SFTP for file transfers, you need to rent an instance that supports a public IP address and ensure an SSH daemon is running within your Pod. @@ -118,7 +113,7 @@ Where: * `[SSH_PORT]`: The designated public SSH port for your Pod. * `[PATH_TO_SSH_KEY]`: The local file path to your private SSH key. -## Troubleshooting +## Troubleshooting SSH key authentication If you're asked for a password when connecting to your Pod via SSH, this means something is not set up correctly. Runpod does not require a password for SSH connections, as authentication is handled entirely through your SSH key pair. This prompt usually indicates a problem with your SSH key configuration. @@ -132,20 +127,9 @@ Here are some common reasons why this might happen: - If your SSH configuration file (`~/.ssh/config`) points to the wrong private key, you will also be prompted for a password. Make sure the `IdentityFile` entry in your config file matches the private key that corresponds to the public key you added to your Runpod account. ## Password-based SSH +To use this method, your Pod must have a public IP address and expose TCP port 22. SSH will be accessible through a mapped external port. - -**Prerequisites for password-based SSH:** -- Your Pod must have a public IP address (available on most GPU instances) -- Your Pod template must expose TCP port 22 (SSH will be accessible on a mapped external port) - - -While SSH runs on port 22 inside your Pod, Runpod maps it to a different external port. The script will automatically use the correct external port from the `RUNPOD_TCP_PORT_22` environment variable. - -If you see `Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing` when running the script you might be missing one of the prerequisites. - - - -To quickly set up password-based SSH, copy and paste this one-liner into your Pod's terminal: +To quickly set up password-based SSH, copy and paste this code into your Pod's terminal: ```bash expandable Password-based SSH Script cat > /tmp/setup_ssh.sh << 'EOF' && chmod +x /tmp/setup_ssh.sh && /tmp/setup_ssh.sh @@ -306,7 +290,14 @@ print_color "green" "Connection scripts saved in /workspace/connect_windows.bat EOF ``` -After pasting the script into your terminal and following the prompt for password, you'll see example commands you can use for SSH or SCP. + +While SSH operates on port 22 within your Pod, Runpod assigns a different external port for access. The setup script below automatically detects and uses the correct external port by referencing the `RUNPOD_TCP_PORT_22` environment variable. + +If you see the message `Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing` when running the script, it means one or more of the required environment variables are not set. Please ensure you have met all the necessary requirements described above. + + +After pasting the script into your terminal and entering a password, you'll see example commands for SSH or SCP: + ```bash ======================================== SSH CONNECTION From 2cfa4090d016f21d83e7a691b2353d8558f7b41b Mon Sep 17 00:00:00 2001 From: Mo King Date: Thu, 17 Jul 2025 12:45:45 -0400 Subject: [PATCH 4/4] Clarify how password-based SSH is used --- pods/configuration/use-ssh.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pods/configuration/use-ssh.mdx b/pods/configuration/use-ssh.mdx index e08b7778..d301040c 100644 --- a/pods/configuration/use-ssh.mdx +++ b/pods/configuration/use-ssh.mdx @@ -129,7 +129,7 @@ Here are some common reasons why this might happen: ## Password-based SSH To use this method, your Pod must have a public IP address and expose TCP port 22. SSH will be accessible through a mapped external port. -To quickly set up password-based SSH, copy and paste this code into your Pod's terminal: +To quickly set up password-based SSH, copy and paste this code into your Pod's web terminal: ```bash expandable Password-based SSH Script cat > /tmp/setup_ssh.sh << 'EOF' && chmod +x /tmp/setup_ssh.sh && /tmp/setup_ssh.sh @@ -296,7 +296,7 @@ While SSH operates on port 22 within your Pod, Runpod assigns a different extern If you see the message `Environment variables RUNPOD_PUBLIC_IP or RUNPOD_TCP_PORT_22 are missing` when running the script, it means one or more of the required environment variables are not set. Please ensure you have met all the necessary requirements described above. -After pasting the script into your terminal and entering a password, you'll see example commands for SSH or SCP: +After pasting the script into your terminal and entering a password, you'll see example commands for SSH or SCP which you can use to connect to your Pod and transfer files from your local machine: ```bash ========================================