How to SSH to Raspberry Pi 5: Headless Setup, Debugging & UART Fallback

To SSH into a Raspberry Pi 5 running Raspberry Pi OS (Bookworm or newer), you must enable the SSH daemon before first boot via the Raspberry Pi Imager's OS customization menu, connect the board to your local network, and run ssh your_username@<IP-address> from your host machine. The legacy default pi user and raspberry password are permanently deprecated; you must define a custom username and password during imaging.

While getting a basic SSH connection is straightforward, embedded projects often run headless in remote locations where a monitor and keyboard aren't an option. When network configurations fail or the SSH daemon crashes, you need a robust debugging strategy. This guide covers the exact headless setup for the Pi 5, a GPIO-based hardware status indicator, exact error string troubleshooting, and the ultimate fallback: the UART serial console.

Parts List & Hardware Spec Sheet

This guide targets the Raspberry Pi 5 (8GB variant) running the 64-bit version of Raspberry Pi OS (Bookworm). The 8GB variant is recommended for embedded projects running Docker containers or local MQTT brokers alongside the SSH service.

Step-by-Step Headless SSH Configuration

The most common point of failure for headless setups is the OS imaging phase. Do not skip the customization menu.

1. Flash the OS: Open Raspberry Pi Imager, select Raspberry Pi 5, choose Raspberry Pi OS (64-bit), and select your SanDisk microSD card.
2. Open OS Customization: Click NEXT, then click EDIT SETTINGS when prompted to apply OS customization.
3. Set Credentials: Enter a custom username (e.g., admin) and a strong password. Do not use 'pi'.
4. Configure WiFi (If applicable): Enter your SSID and password. Ensure the country code matches your region to unlock correct 5GHz channels.
5. Enable SSH: Navigate to the SERVICES tab, select Enable SSH, and choose Use password authentication (or paste your public ED25519 key for better security).
6. Flash and Boot: Write the image, insert the card into the Pi 5, connect power, and wait 60-90 seconds for the first-boot partition resize.

GPIO Pin Mapping for Hardware Debugging

When running headless, a physical indicator of the SSH daemon's status saves you from blindly rebooting the board. We will map the primary UART for serial fallback and a standard GPIO for our status LED.

Note: The Raspberry Pi 5 also features a dedicated 3-pin JST debug connector on the board. If you have the official Pi 5 debug cable, use that instead of GPIO 14/15 to free up those pins for other peripherals.

Python SSH Service Monitor Script

This script polls the systemd manager to check if the ssh.service is active. If it is, the LED on GPIO 17 turns solid green. If the service crashes or stops, the LED blinks rapidly to alert you of a failure. This code targets the Pi 5 and uses the gpiozero library, which is pre-installed on Raspberry Pi OS.

import subprocess
import time
import signal
import sys
from gpiozero import LED

# --- Pin Definitions ---
SSH_STATUS_LED_PIN = 17

# --- Hardware Setup ---
status_led = LED(SSH_STATUS_LED_PIN)

def get_ssh_service_status():
    """Checks systemd for the active state of the SSH daemon."""
    try:
        result = subprocess.run(
            ['systemctl', 'is-active', 'ssh.service'],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            check=False
        )
        return result.stdout.strip()
    except Exception as e:
        print(f"Error querying systemctl: {e}")
        return "unknown"

def cleanup_and_exit(signum, frame):
    """Ensures LED is turned off on script termination."""
    print("\nReceived exit signal. Turning off LED and exiting.")
    status_led.off()
    sys.exit(0)

# Register signal handlers for graceful shutdown
signal.signal(signal.SIGINT, cleanup_and_exit)
signal.signal(signal.SIGTERM, cleanup_and_exit)

print(f"Monitoring SSH service status on GPIO {SSH_STATUS_LED_PIN}...")

try:
    while True:
        status = get_ssh_service_status()
        
        if status == "active":
            # SSH is running: Solid ON
            status_led.on()
            time.sleep(2)
        else:
            # SSH is down/failed: Rapid Blink
            print(f"Warning: SSH service status is '{status}'")
            status_led.blink(on_time=0.2, off_time=0.2, n=5, background=False)
            time.sleep(1)
            
except KeyboardInterrupt:
    cleanup_and_exit(None, None)

Save this as ssh_monitor.py and run it via python3 ssh_monitor.py. For production, wrap it in a systemd service so it starts on boot.

Troubleshooting Exact SSH Error Strings

When your terminal throws an error, don't just reboot the Pi. Read the exact string. Here are the three most common failures, ranked by cause.

Error 1: ssh: connect to host 192.168.1.x port 22: Connection refused

What it means: Your computer successfully found the Pi on the network, but the Pi actively rejected the connection on port 22.

• Cause A (Most Likely): The SSH daemon is not enabled or not running. Fix: Access via UART or monitor and run sudo systemctl enable --now ssh.
• Cause B: A firewall rule (like ufw) is blocking port 22. Fix: Run sudo ufw allow 22/tcp.
• Cause C: You are trying to SSH into a different device that happens to hold that IP address, and that device doesn't run an SSH server.

Error 2: ssh: connect to host 192.168.1.x port 22: Connection timed out

What it means: Your computer sent packets into the network, but nothing ever came back. The Pi is unreachable at the IP layer.

• Cause A (Most Likely): The Pi is offline, crashed, or lost WiFi connectivity. Fix: Check power supply (brownouts cause WiFi drops) and reboot.
• Cause B: You are on the wrong subnet or VLAN. Fix: Verify your host machine's IP subnet matches the Pi's expected subnet.
• Cause C: The IP address changed via DHCP. Fix: Reserve a static DHCP lease in your router using the Pi's MAC address.

Error 3: WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

What it means: The Pi is reachable, and SSH is running, but the cryptographic fingerprint of the server doesn't match what your computer has saved in ~/.ssh/known_hosts.

• Cause A (Most Likely): You re-flashed the Pi's SD card. The new OS generated new SSH host keys. Fix: Run ssh-keygen -R 192.168.1.x on your host machine to clear the old key, then reconnect.
• Cause B: A different device was assigned the Pi's old IP address. Fix: Verify the MAC address of the device you are connecting to.
• Cause C (Security Risk): A man-in-the-middle attack. (Highly unlikely on a local home LAN, but this is why the warning exists).

The Ultimate Fallback: UART Serial Console

If you misconfigured NetworkManager, locked yourself out of SSH, and don't have a micro-HDMI cable handy, the UART serial console is your savior. It bypasses the network stack entirely.

1. Connect your 3.3V FTDI cable: TX to Pi GPIO 15 (RX), RX to Pi GPIO 14 (TX), and GND to Pi GND. Never connect the 5V red wire.
2. Plug the FTDI USB into your host computer.
3. Open your serial terminal (PuTTY on Windows, or screen on macOS/Linux).
4. Set the baud rate to 115200, data bits to 8, parity to None, stop bits to 1 (115200 8N1).
5. Press Enter. You should see the login prompt. Log in with your custom credentials and fix your network configuration using nmcli.

Frequently Asked Questions

How to SSH to Raspberry Pi without knowing the IP address?

Raspberry Pi OS supports mDNS (Multicast DNS) out of the box. Instead of typing the numeric IP address, you can use the hostname followed by .local. For example, if your hostname is weatherstation, simply type ssh admin@weatherstation.local. This works seamlessly across macOS, Linux, and modern Windows 11 installations. If mDNS fails, check your router's admin panel under "DHCP Clients" or "Connected Devices" to find the IP assigned to the Pi's MAC address.

How to SSH to Raspberry Pi from Windows 11?

Windows 11 includes the OpenSSH client natively. You do not need to install third-party software like PuTTY unless you prefer a GUI. Simply open Windows Terminal or PowerShell and type ssh your_username@raspberrypi.local. If you receive a warning about the host key, type yes to accept it. If you need to manage SSH keys graphically or use serial UART debugging, PuTTY remains an excellent, lightweight choice.

How to extend or simplify this build?

To simplify: If you don't need the hardware LED indicator, skip the Python script and GPIO wiring entirely. Rely on your router's dashboard to verify the Pi is online.
To extend: You can configure systemd to automatically restart the SSH service if it crashes by creating a drop-in override. Run sudo systemctl edit ssh.service and add Restart=always and RestartSec=5 under the [Service] block. For remote projects behind NAT firewalls, extend the build by installing Tailscale to create a secure, zero-config mesh VPN, allowing you to SSH into your Pi from anywhere in the world without port forwarding.

For more information on Bookworm networking changes, refer to the official Raspberry Pi OS release notes. For detailed UART and GPIO specifications, consult the Raspberry Pi Hardware Documentation.