SSH Protocol: A Complete Reference Guide

Introduction to the SSH Protocol

The Secure Shell (SSH) protocol is a cryptographic network protocol that enables secure communication between two computers over an unsecured network. Originally designed as a replacement for insecure protocols like Telnet, rlogin, and FTP, SSH has become the de facto standard for remote administration of servers, secure file transfers, and tunneling network traffic. For developers, system administrators, and DevOps engineers, mastering SSH is not optional — it is a fundamental skill that underpins almost every aspect of modern infrastructure management.

SSH operates on a client-server model. The SSH client initiates a connection to an SSH server, which typically listens on port 22. Once the connection is established, SSH uses strong encryption to ensure that all data exchanged between the client and server — including passwords, commands, and file contents — remains confidential and tamper-proof. The current version of the protocol, SSH-2, was introduced in 2006 and is defined in a series of RFC documents (RFC 4250 through RFC 4256).

Why SSH Matters

In an era where cyber threats are increasingly sophisticated, the importance of secure remote communication cannot be overstated. SSH matters for several critical reasons:

• Encryption: All traffic between client and server is encrypted, protecting sensitive data from eavesdropping and man-in-the-middle attacks.
• Authentication: SSH supports multiple authentication methods, including password-based, public key-based, and multi-factor authentication, providing flexible and robust identity verification.
• Integrity: SSH uses cryptographic hash functions to detect any tampering with data in transit, ensuring that commands and files arrive unaltered.
• Versatility: Beyond remote shell access, SSH supports secure file transfer (SCP, SFTP), port forwarding, tunneling, and even proxying, making it a Swiss Army knife for network operations.
• Automation: SSH key-based authentication enables passwordless logins, which are essential for automated deployment scripts, CI/CD pipelines, and configuration management tools like Ansible.

How SSH Works: The Technical Architecture

Understanding the inner workings of SSH helps developers use it more effectively and troubleshoot issues when they arise. The SSH protocol operates in three distinct layers, each serving a specific purpose.

The Transport Layer

The transport layer is responsible for establishing the initial secure connection between the client and server. When a client connects, the two parties perform a handshake that involves negotiating encryption algorithms, exchanging keys, and authenticating the server to the client. This layer uses asymmetric cryptography (typically RSA, ECDSA, or Ed25519) to establish a shared secret, which is then used to derive symmetric encryption keys for the session.

The Authentication Layer

Once the transport layer has established a secure channel, the authentication layer takes over. The client must prove its identity to the server. SSH supports several authentication methods, and the server may require one or more of them:

• Password authentication: The client sends a password over the encrypted channel. While secure in transit, this method is vulnerable to brute-force attacks.
• Public key authentication: The client proves possession of a private key corresponding to a public key registered on the server. This is the preferred method for both security and automation.
• Host-based authentication: The server trusts the client based on the client's host identity. This is rarely used in practice due to security concerns.
• Keyboard-interactive authentication: A flexible method that supports challenge-response authentication, often used for multi-factor authentication.

The Connection Layer

The connection layer multiplexes multiple logical channels over the single encrypted SSH connection. This allows a single SSH session to support multiple simultaneous operations, such as running a shell session, transferring files, and forwarding ports, all over the same connection.

Installing and Verifying SSH

On most Linux and macOS systems, the SSH client is pre-installed. On Windows, modern versions include OpenSSH as an optional feature. Here is how to check whether SSH is available and install it if necessary.

# Check if SSH client is installed
ssh -V

# On Ubuntu/Debian, install OpenSSH client and server
sudo apt update
sudo apt install openssh-client openssh-server

# On CentOS/RHEL/Fedora
sudo dnf install openssh-clients openssh-server

# On macOS (typically pre-installed, but can install via Homebrew)
brew install openssh

# On Windows (PowerShell as Administrator)
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

Once installed, you can verify the SSH server is running on the target machine:

# Check SSH service status on Linux
sudo systemctl status sshd

# Start and enable SSH service
sudo systemctl start sshd
sudo systemctl enable sshd

# Verify SSH is listening on port 22
sudo ss -tlnp | grep ssh

Generating SSH Keys

Public key authentication is the cornerstone of secure SSH usage. Instead of relying on passwords, you generate a key pair — a private key that stays on your machine and a public key that you place on remote servers. The private key should never be shared or transmitted.

Generating an Ed25519 Key Pair

Ed25519 is the recommended key type as of 2024. It offers strong security with small key sizes and excellent performance.

# Generate an Ed25519 key pair with a comment
ssh-keygen -t ed25519 -C "your_email@example.com"

# The output will look like:
# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/home/user/.ssh/id_ed25519):
# Enter passphrase (empty for no passphrase):
# Enter same passphrase again:
# Your identification has been saved in /home/user/.ssh/id_ed25519
# Your public key has been saved in /home/user/.ssh/id_ed25519.pub

Generating an RSA Key Pair

If you need compatibility with older systems that do not support Ed25519, RSA is the fallback. Always use at least 4096 bits.

# Generate a 4096-bit RSA key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Copying Your Public Key to a Remote Server

The easiest way to install your public key on a remote server is using the ssh-copy-id utility:

# Copy public key to remote server
ssh-copy-id username@remote_host

# Specify a custom port
ssh-copy-id -p 2222 username@remote_host

# Specify a specific key file
ssh-copy-id -i ~/.ssh/id_ed25519.pub username@remote_host

If ssh-copy-id is not available, you can do it manually:

# Manually append your public key to the remote authorized_keys file
cat ~/.ssh/id_ed25519.pub | ssh username@remote_host \
  "mkdir -p ~/.ssh && chmod 700 ~/.ssh && \
   cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Connecting to Remote Servers

The basic syntax for connecting to a remote server via SSH is straightforward:

# Basic SSH connection
ssh username@remote_host

# Connect using a specific private key
ssh -i ~/.ssh/id_ed25519 username@remote_host

# Connect to a non-default port
ssh -p 2222 username@remote_host

# Execute a single command and exit
ssh username@remote_host "ls -la /var/www"

# Connect with verbose output for debugging
ssh -v username@remote_host

# Connect with X11 forwarding (for GUI applications)
ssh -X username@remote_host

# Force SSH to use a specific key exchange algorithm
ssh -o KexAlgorithms=curve25519-sha256 username@remote_host

Understanding the First Connection Prompt

When you connect to a server for the first time, SSH will display a message like the following:

The authenticity of host 'remote_host (192.168.1.100)' can't be established.
ED25519 key fingerprint is SHA256:abc123def456ghi789jkl012mno345pqr678stu901.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

This is the host key verification step. SSH is asking you to confirm that the server's fingerprint matches what you expect. Once you confirm, the server's host key is saved in ~/.ssh/known_hosts, and future connections will verify against this stored key. If the key ever changes, SSH will warn you loudly, which could indicate a man-in-the-middle attack or a legitimate server reinstall.

The SSH Configuration File

Typing long SSH commands with multiple flags quickly becomes tedious. The SSH client configuration file (~/.ssh/config) allows you to define aliases and default settings for each host you connect to. This is one of the most powerful and underutilized features of SSH.

# ~/.ssh/config

# Default settings for all hosts
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

# Production web server
Host prod-web
    HostName 192.168.1.100
    User deploy
    Port 2222
    IdentityFile ~/.ssh/prod_web_key
    ForwardAgent yes

# Staging server with jump host
Host staging
    HostName staging.example.com
    User ubuntu
    ProxyJump bastion.example.com

# GitHub
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_key
    IdentitiesOnly yes

# AWS EC2 instance
Host aws-prod
    HostName ec2-54-123-45-67.compute-1.amazonaws.com
    User ec2-user
    IdentityFile ~/.ssh/aws_prod_key.pem

With this configuration in place, you can connect to any of these servers using a simple alias:

# Connect to the production web server
ssh prod-web

# Connect to staging through the bastion host
ssh staging

# Run a command on the AWS instance
ssh aws-prod "sudo systemctl status nginx"

SSH Port Forwarding

Port forwarding, also known as SSH tunneling, is one of the most powerful features of SSH. It allows you to securely tunnel network traffic from one port to another through an encrypted SSH connection. There are three types of port forwarding: local, remote, and dynamic.

Local Port Forwarding

Local port forwarding forwards a port on your local machine to a port on the remote server (or a host accessible from the remote server). This is useful for accessing services that are only accessible from the remote network, such as a database running on a private subnet.

# Forward local port 5432 to remote PostgreSQL on port 5432
ssh -L 5432:localhost:5432 username@remote_host

# Access a remote web service that only listens on localhost
ssh -L 8080:localhost:80 username@remote_host

# Forward to a different host accessible from the remote server
ssh -L 5432:db.internal.example.com:5432 username@bastion.example.com

# Run in background without executing a remote command
ssh -fN -L 5432:localhost:5432 username@remote_host

Remote Port Forwarding

Remote port forwarding does the reverse: it forwards a port on the remote server to a port on your local machine (or a host accessible from your local machine). This is useful for exposing a local development server to the outside world through a remote server.

# Forward remote port 8080 to local port 3000
ssh -R 8080:localhost:3000 username@remote_host

# Allow anyone on the remote network to access the forwarded port
ssh -R 0.0.0.0:8080:localhost:3000 username@remote_host

Dynamic Port Forwarding (SOCKS Proxy)

Dynamic port forwarding creates a SOCKS proxy that can tunnel traffic to any destination through the SSH server. This is useful for browsing the web through a secure tunnel or accessing multiple services on a remote network.

# Create a SOCKS proxy on local port 1080
ssh -D 1080 username@remote_host

# Then configure your browser or application to use SOCKS5 proxy at localhost:1080
# For example, with curl:
curl --socks5-hostname localhost:1080 http://internal-service.example.com

SSH Agent and Key Management

The SSH agent is a background process that holds your private keys in memory so you do not have to type your passphrase every time you connect. This is especially useful when you have multiple keys or when you need to forward your authentication credentials to jump hosts.

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your default key to the agent
ssh-add

# Add a specific key to the agent
ssh-add ~/.ssh/prod_web_key

# List all keys currently loaded in the agent
ssh-add -l

# Remove a specific key from the agent
ssh-add -d ~/.ssh/prod_web_key

# Remove all keys from the agent
ssh-add -D

# Kill the SSH agent
ssh-agent -k

Agent Forwarding

Agent forwarding allows you to use your local SSH keys on a remote server without copying the private key to that server. This is useful when you need to SSH from one server to another (e.g., pulling code from GitHub on a production server).

# Enable agent forwarding for a single connection
ssh -A username@remote_host

# Enable agent forwarding in ~/.ssh/config
Host prod-web
    HostName 192.168.1.100
    User deploy
    ForwardAgent yes

Be cautious with agent forwarding on untrusted servers. A compromised server could potentially use your forwarded agent to authenticate to other servers while you are connected. Only enable agent forwarding on servers you trust.

SCP and SFTP for Secure File Transfer

SSH provides two mechanisms for secure file transfer: SCP (Secure Copy Protocol) and SFTP (SSH File Transfer Protocol). Both operate over the same encrypted SSH channel.

Using SCP

# Copy a file from local to remote
scp /path/to/local/file.txt username@remote_host:/path/to/remote/

# Copy a file from remote to local
scp username@remote_host:/path/to/remote/file.txt /path/to/local/

# Copy an entire directory recursively
scp -r /path/to/local/dir username@remote_host:/path/to/remote/

# Copy between two remote servers
scp username@host1:/path/to/file username@host2:/path/to/destination

# Use a custom port
scp -P 2222 file.txt username@remote_host:/path/

# Use a specific identity file
scp -i ~/.ssh/special_key file.txt username@remote_host:/path/

# Compress data during transfer
scp -C large_file.bin username@remote_host:/path/

Using SFTP

SFTP provides an interactive file transfer session with commands similar to FTP:

# Start an interactive SFTP session
sftp username@remote_host

# Common SFTP commands:
sftp> ls                    # List remote files
sftp> lls                   # List local files
sftp> cd /path/to/remote    # Change remote directory
sftp> lcd /path/to/local    # Change local directory
sftp> put file.txt          # Upload a file
sftp> get file.txt          # Download a file
sftp> put -r local_dir      # Upload a directory recursively
sftp> get -r remote_dir     # Download a directory recursively
sftp> pwd                   # Show remote working directory
sftp> lpwd                  # Show local working directory
sftp> mkdir new_dir         # Create remote directory
sftp> rm file.txt           # Delete remote file
sftp> exit                  # Close session

# Non-interactive SFTP batch mode
sftp -b batchfile.txt username@remote_host

SSH Best Practices

Following security best practices when configuring and using SSH is critical for protecting your infrastructure. Below are the most important recommendations.

Server-Side Hardening

The SSH server configuration file is located at /etc/ssh/sshd_config. Here are the key settings you should adjust:

# /etc/ssh/sshd_config

# Disable root login over SSH
PermitRootLogin no

# Disable password authentication (require key-based auth)
PasswordAuthentication no
PubkeyAuthentication yes

# Change the default port (security through obscurity, reduces noise)
Port 2222

# Limit which users can SSH in
AllowUsers deploy admin

# Or limit by group
AllowGroups ssh-users

# Set idle timeout (in seconds)
ClientAliveInterval 300
ClientAliveCountMax 0

# Disable X11 forwarding if not needed
X11Forwarding no

# Limit authentication attempts
MaxAuthTries 3

# Disable empty passwords
PermitEmptyPasswords no

# Use SSH protocol 2 only (protocol 1 is deprecated)
Protocol 2

# Disable host-based authentication
HostbasedAuthentication no

# Set a login grace period (seconds before authentication must complete)
LoginGraceTime 30

After making changes, validate the configuration and restart the service:

# Validate configuration syntax
sudo sshd -t

# Restart SSH service
sudo systemctl restart sshd

Client-Side Best Practices

• Always use a passphrase on your private keys. If your private key is stolen, the passphrase provides an additional layer of protection.
• Use the SSH agent to avoid typing passphrases repeatedly. This gives you the security of a passphrase with the convenience of passwordless logins.
• Use Ed25519 keys when possible. They are faster, smaller, and more secure than RSA keys.
• Use IdentitiesOnly yes when connecting to services like GitHub. This prevents SSH from offering all your keys, which can lead to "too many authentication failures" errors.
• Protect your ~/.ssh directory with proper permissions. The directory should be 700, private keys should be 600, and the config file should be 600.
• Never share or commit your private keys. Add them to .gitignore and never paste them in chat, email, or documentation.

# Set proper permissions on SSH directory and files
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

# Install Fail2Ban on Ubuntu/Debian
sudo apt install fail2ban

# Create a local configuration
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

# Edit the SSH jail settings
sudo nano /etc/fail2ban/jail.local

# Example SSH jail configuration:
# [sshd]
# enabled = true
# port = 2222
# maxretry = 3
# bantime = 3600
# findtime = 600

# Restart Fail2Ban
sudo systemctl restart fail2ban
sudo systemctl enable fail2ban

# Check Fail2Ban status
sudo fail2ban-client status sshd

# ansible.cfg
[defaults]
inventory = ./hosts
remote_user = deploy
private_key_file = ~/.ssh/ansible_key
host_key_checking = False
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o ForwardAgent=yes

# Enable SSH multiplexing for faster execution
[ssh_connection]
pipelining = True
control_path = ~/.ssh/ansible-%%r@%%h:%%p

# Example Ansible inventory file
[webservers]
web1.example.com ansible_host=192.168.1.101 ansible_user=deploy
web2.example.com ansible_host=192.168.1.102 ansible_user=deploy

[databases]
db1.example.com ansible_host=10.0.0.51 ansible_user=postgres ansible_port=2222

[webservers:vars]
ansible_ssh_private_key_file=~/.ssh/web_key

# ~/.ssh/config - Using ProxyJump

# Bastion host (accessible from internet)
Host bastion
    HostName bastion.example.com
    User admin
    IdentityFile ~/.ssh/bastion_key

# Private server accessible only through bastion
Host private-server
    HostName 10.0.1.50
    User deploy
    IdentityFile ~/.ssh/private_key
    ProxyJump bastion

# Multiple jump hosts (chained)
Host deep-server
    HostName 10.0.2.100
    User deploy
    ProxyJump bastion, middle-server

# Connect through a jump host from command line
ssh -J admin@bastion.example.com deploy@10.0.1.50

# Copy files through a jump host
scp -o ProxyJump=admin@bastion.example.com file.txt deploy@10.0.1.50:/path/

# Check if your key is being offered
ssh -v username@remote_host 2>&1 | grep "Offering"

# Verify permissions on the remote server
ssh username@remote_host "ls -la ~/.ssh/"
# authorized_keys should be 600
# .ssh directory should be 700

# Check the SSH server log for details
sudo tail -f /var/log/auth.log    # Debian/Ubuntu
sudo tail -f /var/log/secure      # CentOS/RHEL

# Fix permissions on the remote server
ssh username@remote_host "chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"

# Check if SSH is running on the remote server
sudo systemctl status sshd

# Check if SSH is listening on the expected port
sudo ss -tlnp | grep ssh

# Check firewall rules
sudo ufw status          # Ubuntu
sudo firewall-cmd --list-all  # CentOS/RHEL

# Allow SSH through the firewall
sudo ufw allow 2222/tcp
sudo firewall-cmd --permanent --add-port=2222/tcp
sudo firewall-cmd --reload

# Test basic connectivity
ping remote_host

# Test if the SSH port is reachable
nc -zv remote_host 22
# or
telnet remote_host 22

# Use SSH with maximum verbosity
ssh -vvv username@remote_host

# Check if the host is blocking your IP
# (You may need to contact the server administrator)

# Use IdentitiesOnly
ssh -o IdentitiesOnly=yes -i ~/.ssh/specific_key username@remote_host

# Or add to ~/.ssh/config
Host problem-host
    HostName remote_host
    User username
    IdentityFile ~/.ssh/specific_key
    IdentitiesOnly yes

# ~/.ssh/config
Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

# Create the sockets directory
mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets

# Server side: edit /etc/ssh/sshd_config
Port 2222

# Client side: connect on custom port
ssh -p 2222 username@remote_host

# Or in ~/.ssh/config
Host my-server
    HostName remote_host
    Port 2222
    User username

# Clone a repository over SSH
git clone git@github.com:username/repository.git

# Change remote URL from HTTPS to SSH
git remote set-url origin git@github.com:username/repository.git

# Test GitHub SSH connection
ssh -T git@github.com

# Use a specific key for GitHub
# ~/.ssh/config
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_key
    IdentitiesOnly yes