How to Enable SSH on Raspberry Pi 5: Headless Setup & UART Debugging

To enable SSH on a Raspberry Pi before its first boot, create an empty file named ssh (with no file extension) in the root directory of the bootfs partition on your microSD card. Alternatively, if you are flashing the OS using the official Raspberry Pi Imager, click the gear icon (OS customization) on the final screen, check 'Enable SSH', and select 'Use password authentication'. This bypasses the default security posture of Raspberry Pi OS, which disables the SSH daemon out of the box to prevent unauthorized network access.

While enabling the software side takes seconds, headless deployments frequently fail at the network layer. When you cannot ping the board or the SSH daemon refuses connections, you need a hardware-level fallback. This guide covers the exact software configuration, the hardware UART serial console rescue method, and a Python-based GPIO status monitor to verify your daemon state without a monitor.

Board Variants and Network Specifications

Network behavior and default SSH states vary slightly across the Raspberry Pi lineup, particularly with the transition from dhcpcd to NetworkManager in the Bookworm OS release. Understanding your specific board's network interface is critical for predicting IP assignment behavior on a headless network.

Note: The Raspberry Pi 5 requires a 27W (5V/5A) USB-C PD power supply to prevent peripheral brownouts. If you use a standard 15W (5V/3A) charger, the Pi 5 will throttle USB current limits, which can cause TTL-to-USB serial adapters to disconnect randomly during UART debugging.

Hardware Fallback: Parts List and UART Pin Mapping

When a headless Pi fails to connect to Wi-Fi or Ethernet, SSH is useless. The industry-standard rescue method is connecting via the primary UART serial console. This bypasses the network stack entirely and gives you a direct root-level terminal.

Required Parts

• Target Board: Raspberry Pi 5 (8GB) or Raspberry Pi 4 Model B (4GB)
• Serial Adapter: CP2102 or PL2303 USB-to-TTL Serial Module (Must support 3.3V logic levels; never use a 5V adapter like some Arduino cables, or you will fry the Pi's SoC)
• Indicator LED: Standard 5mm Green LED with a 220Ω current-limiting resistor
• Wiring: Female-to-female Dupont jumper wires (24 AWG)

GPIO Pin Mapping Table

The Raspberry Pi uses specific GPIO pins for the primary UART console (serial0). Map your CP2102 adapter and status LED exactly as follows:

Step-by-Step Setup and First Boot Verification

1. Flash the OS: Open Raspberry Pi Imager. Select 'Raspberry Pi OS (64-bit)' and your specific Pi model.
2. Apply Customization: Click 'Next', then 'Edit Settings' on the OS Customization prompt. Set your hostname, username, and password.
3. Enable SSH: Navigate to the 'Services' tab, check 'Enable SSH', and select 'Use password authentication' (or paste your public RSA key for key-based auth).
4. Configure Wi-Fi (If applicable): Enter your SSID and password. Ensure the 'Wireless LAN country' code matches your physical location, or the 5GHz radios will remain disabled by the regulatory domain.
5. Flash and Boot: Write to a high-endurance microSD card (e.g., SanDisk High Endurance or Samsung PRO Endurance). Insert into the Pi and apply power.
6. Verify via Network: Wait 90 seconds for the first-boot host key generation. Open your router's DHCP lease table to find the Pi's assigned IP address.

Troubleshooting 'Connection Refused' and UART Rescue

If you attempt to connect and receive the following exact error string:

ssh: connect to host 192.168.1.42 port 22: Connection refused

This means the Pi is online and responding to ARP/ping requests, but the SSH daemon is either not running, not listening on port 22, or blocked by a local firewall. Here are the first three things to check when this fails:

1. The Boot Partition ssh File Extension: Windows often hides known file extensions. If you created a file named ssh.txt in Notepad, the OS will ignore it. Ensure the file is strictly named ssh with zero extensions.
2. Host Key Generation Timeout: On slow microSD cards, the Pi 5 may time out during the initial ssh-keygen process on first boot. If the keys fail to generate, sshd will crash on startup. A hard reboot usually resolves this.
3. NetworkManager vs. DHCP Race Condition: In Raspberry Pi OS Bookworm, NetworkManager handles connections. If Wi-Fi credentials are wrong, the Pi will not fall back to a link-local IP. Check your router's lease table to confirm an IP was actually handed out.

Executing the UART Rescue

If the network is entirely unreachable, plug your CP2102 adapter into your PC. Open a terminal emulator like PuTTY (Windows) or screen (macOS/Linux). Set the serial line to /dev/tty.usbserial-XXXX (or COM3), speed to 115200, 8 data bits, no parity, 1 stop bit. Power on the Pi. You will see the kernel boot logs scroll by, ending in a login prompt. Log in and run sudo systemctl status ssh to see exactly why the daemon failed to start.

Python SSH Status Monitor and Build Extensions

For permanent headless installations (like 3D printer farms or environmental sensors), relying on network pings is insufficient. The code below targets the Raspberry Pi 5 running Bookworm OS. It uses the gpiozero library (the modern replacement for the deprecated RPi.GPIO) to poll the sshd service state and illuminate the GPIO 18 LED when SSH is actively listening.

import time
import subprocess
import logging
from gpiozero import LED
from signal import pause

# --- Pin Definitions ---
SSH_STATUS_LED_PIN = 18
status_led = LED(SSH_STATUS_LED_PIN)

# Configure logging for headless debugging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

def check_ssh_daemon():
    """Checks if the sshd service is active via systemctl."""
    try:
        result = subprocess.run(
            ['systemctl', 'is-active', 'ssh'],
            capture_output=True,
            text=True,
            check=False
        )
        return result.stdout.strip() == 'active'
    except FileNotFoundError:
        logging.error('systemctl not found. Are you running a systemd-based OS?')
        return False
    except Exception as e:
        logging.error(f'Unexpected error checking SSH status: {e}')
        return False

def main():
    logging.info(f'SSH Monitor started. Status LED mapped to GPIO {SSH_STATUS_LED_PIN}.')
    try:
        while True:
            if check_ssh_daemon():
                if not status_led.is_lit:
                    logging.info('SSH daemon is ACTIVE. LED ON.')
                status_led.on()
            else:
                if status_led.is_lit:
                    logging.warning('SSH daemon is INACTIVE. LED OFF.')
                status_led.off()
            
            # Poll every 5 seconds to minimize CPU overhead
            time.sleep(5)
    except KeyboardInterrupt:
        logging.info('Monitor stopped by user.')
    finally:
        status_led.off()
        status_led.close()

if __name__ == '__main__':
    main()

How to Extend or Simplify the Build

To Simplify: If you do not need the hardware LED indicator and only want software-level monitoring, strip out the gpiozero imports and LED logic. You can run the check_ssh_daemon() function as a simple cron job that writes a timestamp to a log file only when the state changes.

To Extend: Integrate the MQTT protocol using the paho-mqtt Python library. Instead of just lighting an LED, publish the SSH daemon state to a Home Assistant MQTT broker. This allows you to trigger an automated alert to your phone if sshd crashes or is intentionally disabled by a malicious script. Additionally, you can wire a physical momentary push-button to GPIO 23; when pressed, the script can execute sudo systemctl restart ssh to attempt an automatic daemon recovery without needing to pull the power cord.