SSH for Raspberry Pi: Headless Access in the Field

How to enable, connect, and troubleshoot SSH on a Raspberry Pi — from first boot to headless field deployments. No monitor required.

You plug in the Pi, wait for it to boot, open a terminal, type `ssh pi@raspberrypi.local`, and get nothing. Connection refused. Or worse: it just hangs. You check the IP address. You ping it. The ping works, so the Pi is alive, but SSH is not responding. This is the first wall most people hit, and it has a specific cause: **SSH is disabled by default on Raspberry Pi OS.**

This guide covers how to enable SSH, how to connect from any OS, how to find the Pi on the network when you do not know its IP, how to set up key-based authentication so you never type a password again, and what to do when things go wrong in a remote or headless context where you cannot plug in a monitor.

Why SSH is Disabled by Default

In 2016, the Raspberry Pi Foundation disabled SSH by default after a large number of Pis were exposed to the internet with the default `pi`/`raspberry` credentials unchanged. The decision was defensible. It forced users to make a deliberate choice before opening a network service.

The consequence is that a freshly imaged Pi will not accept SSH connections until you explicitly enable it. There are three ways to do that, depending on what access you have to the device.

Enabling SSH Before First Boot (The Right Way)

If you are imaging a new SD card, enable SSH before the card goes into the Pi. This is the correct approach for any headless deployment, including [Raspberry Pi SSH setup for headless CM4 deployments](raspberry-pi-ssh-setup-headless-cm4).

**Using Raspberry Pi Imager (recommended).** The official imager (version 1.7 and later) has an 'OS Customisation' panel. Open it with Ctrl+Shift+X or click the gear icon. Enable SSH from that panel. You can also set a username, password, hostname, and Wi-Fi credentials here. Write the image. SSH will be active on first boot, no extra steps required.

**Manually placing the SSH file.** After writing the image, the boot partition will be visible as a drive called `bootfs` (previously `boot`). Create an empty file named exactly `ssh` with no extension in the root of that partition. On Linux or macOS: `touch /Volumes/bootfs/ssh`. On Windows, create a new text file in File Explorer and delete the `.txt` extension. The presence of this file tells the Pi to enable SSH on first boot, then the file is deleted.

The file must be named `ssh` with no extension, not `ssh.txt`. Windows hides known file extensions by default. Enable 'Show file extensions' in File Explorer before creating it.

**Using `userconf.txt` for credentials.** On Raspberry Pi OS Bullseye and later, there is no default `pi` user. If you set up SSH manually via the `ssh` file without using the imager, you also need a `userconf.txt` file in the boot partition. Its contents should be a single line: `username:hashed_password`. Generate the hash with `echo 'yourpassword' | openssl passwd -6 -stdin`. Without a valid user, the Pi will boot but you will not be able to log in.

Enabling SSH on a Running Pi

If you have a monitor and keyboard attached, enabling SSH takes seconds.

1. Open a terminal on the Pi.
2. Run `sudo raspi-config`.
3. Navigate to 'Interface Options', then 'SSH'.
4. Select 'Yes' to enable. Exit and reboot if prompted.

Alternatively, from the terminal: `sudo systemctl enable ssh && sudo systemctl start ssh`. This enables SSH immediately and sets it to start on every boot.

Finding the Pi on Your Network

SSH requires an IP address or hostname. On a fresh Pi connected by Ethernet or Wi-Fi, finding it is the next obstacle.

**mDNS / hostname.** By default, the Pi broadcasts itself as `raspberrypi.local` (or whatever hostname you set in the imager). From a Mac or Linux machine, `ssh pi@raspberrypi.local` often works directly. On Windows, mDNS resolution depends on Bonjour being installed (it comes with iTunes, or can be installed separately). If you changed the hostname to `sensor-node`, use `sensor-node.local`.

**Network scanner.** If mDNS is not resolving, find the Pi's IP by scanning the local subnet. On Linux/macOS: `nmap -sn 192.168.1.0/24` (replace with your actual subnet). On Windows, `arp -a` lists recently seen devices. Look for a MAC address starting with `DC:A6:32`, `B8:27:EB`, or `E4:5F:01` — those are Raspberry Pi Foundation prefixes. The router's DHCP client list is often the fastest method.

Set a static IP or a DHCP reservation for any Pi that needs reliable SSH access. A changing IP after every reboot makes scripted access and monitoring unreliable.

**Direct Ethernet connection.** Connect the Pi directly to a laptop with an Ethernet cable (no switch or router). Configure the laptop's Ethernet interface to link-local addressing (`169.254.x.x` on Windows, or share the connection on macOS). The Pi's mDNS hostname will resolve over link-local. This is useful when there is no network available at a deployment site.

Connecting via SSH

**From Linux or macOS.** Open a terminal and run: `ssh username@ip_address`. For example: `ssh pi@192.168.1.45` or `ssh pi@raspberrypi.local`. The default port is 22. If you changed the port (common hardening practice), specify it with `-p`: `ssh -p 2222 pi@192.168.1.45`.

**From Windows.** Windows 10 (1809+) and Windows 11 include the OpenSSH client. Open PowerShell or Command Prompt and use the same `ssh` command as above. For older Windows versions, PuTTY is the standard client. Enter the IP address, set the port to 22, and connect.

On first connection, SSH will display a host fingerprint and ask you to confirm. Type `yes`. The fingerprint is saved in `~/.ssh/known_hosts`. If you re-image the Pi and SSH shows a fingerprint mismatch warning, that is expected. Remove the old entry: `ssh-keygen -R raspberrypi.local` or `ssh-keygen -R ip_address`.

Key-Based Authentication: Skip the Password

Password authentication is adequate for development. For any system that needs automated access, script-based connections, or consistent security, key-based authentication is the right approach. It also eliminates brute-force password risk.

1. Generate a key pair on your local machine (not the Pi): `ssh-keygen -t ed25519 -C 'your-label'`. Accept the default path. Set a passphrase or leave it blank for fully automated access.
2. Copy the public key to the Pi: `ssh-copy-id pi@raspberrypi.local`. This appends your public key to `~/.ssh/authorized_keys` on the Pi.
3. Test the connection: `ssh pi@raspberrypi.local`. You should connect without being asked for a password.
4. Optionally disable password authentication on the Pi entirely. Edit `/etc/ssh/sshd_config`, set `PasswordAuthentication no`, then restart SSH: `sudo systemctl restart ssh`.

If `ssh-copy-id` is not available (Windows without WSL), manually copy the contents of `~/.ssh/id_ed25519.pub` and append it to `~/.ssh/authorized_keys` on the Pi, creating the file and directory if they do not exist. Permissions matter: `chmod 700 ~/.ssh` and `chmod 600 ~/.ssh/authorized_keys`.

SSH Config File: Stop Typing Long Commands

If you manage more than one Pi, an SSH config file keeps connections manageable. On your local machine, edit or create `~/.ssh/config`:

`Host sensor-node` ` HostName 192.168.1.45` ` User pi` ` IdentityFile ~/.ssh/id_ed25519` ` Port 22`

After saving, connect with just `ssh sensor-node`. For fleets with many nodes, this becomes essential. You can define as many hosts as needed, each with its own key, user, and port.

Transferring Files Over SSH

SSH also handles file transfer without additional tools.

**SCP (Secure Copy).** Copy a file to the Pi: `scp localfile.txt pi@192.168.1.45:/home/pi/`. Copy from the Pi: `scp pi@192.168.1.45:/home/pi/log.txt ./`. SCP is straightforward but does not handle incremental sync.

**SFTP.** An interactive FTP-like session over SSH. Start it with `sftp pi@192.168.1.45`. Commands like `put`, `get`, `ls`, and `cd` work as expected. GUI clients like FileZilla and Cyberduck support SFTP and give you a drag-and-drop interface.

**rsync.** For syncing directories or large transfers: `rsync -avz ./localdir/ pi@192.168.1.45:/home/pi/remotedir/`. rsync transfers only changed blocks on subsequent runs, which is efficient for log retrieval or code deployment.

SSH Tunneling and Port Forwarding

SSH can forward ports, which is useful when the Pi is running a web service or other TCP service you want to access from your local machine without exposing it publicly.

**Local port forwarding.** Access a service on the Pi's port 8080 via your local port 9090: `ssh -L 9090:localhost:8080 pi@192.168.1.45`. Open `http://localhost:9090` in a browser to reach the Pi's service.

**Reverse SSH tunnel.** When the Pi is behind NAT or a firewall with no inbound access, a reverse tunnel lets you reach it anyway. The Pi initiates a connection to a server you control: `ssh -R 2222:localhost:22 user@your-server.com`. From the server, you then `ssh -p 2222 pi@localhost` to reach the Pi. This is a common pattern for [Raspberry Pi SSH access for unattended remote nodes](raspberry-pi-ssh-unattended-remote-nodes) where the device is behind a cellular gateway or restrictive corporate firewall.

Use `autossh` instead of bare `ssh` for persistent reverse tunnels. It monitors the connection and restarts it if it drops, which matters for long-lived deployments.

Troubleshooting SSH Connection Failures

Most SSH failures fall into a small number of categories.

• **Connection refused.** SSH is not running. Either it was not enabled before imaging, or the service stopped. If you have physical access, enable it via raspi-config. If you do not, you need another path in -- see below.
• **Connection timed out.** The Pi is not reachable at that IP. Confirm it is powered, booted, and on the correct network. Check the IP address.
• **Host key mismatch.** You re-imaged the Pi. Run `ssh-keygen -R hostname_or_ip` to clear the old fingerprint.
• **Permission denied (publickey).** Your key is not in the Pi's `authorized_keys`, or `PasswordAuthentication` is disabled and there is no matching key. Copy the key with `ssh-copy-id` or re-enable password auth temporarily.
• **Permission denied (password).** Wrong username or password. Raspberry Pi OS no longer has a default `pi` user unless you created it during imaging.

For headless systems where you cannot plug in a monitor, troubleshooting SSH failures is harder. If the Pi boots but SSH does not respond, options include: mounting the SD card on another machine and checking `/etc/ssh/sshd_config`, using a UART serial adapter on the GPIO pins for console access, or reading the boot logs by examining the SD card's filesystem. For CM4-based deployments, [IP KVM on CM4 for headless remote access](ip-kvm-cm4-headless-remote-access) covers out-of-band access options that do not depend on SSH being functional.

Hardening SSH for Remote and Field Deployments

A Pi on a local LAN has limited exposure. A Pi accessible over the internet or a public network needs additional hardening. These are not optional for anything internet-facing.

• **Disable password authentication.** Use keys only. Set `PasswordAuthentication no` in `/etc/ssh/sshd_config`.
• **Change the default SSH port.** Not a security measure on its own, but it eliminates noise from automated scanners. Set `Port 2222` (or any unused port) in sshd_config.
• **Disable root login.** Set `PermitRootLogin no` in sshd_config.
• **Use fail2ban.** Install with `sudo apt install fail2ban`. Default configuration bans IPs after repeated failed logins.
• **Firewall with ufw.** `sudo ufw allow 22/tcp` (or your chosen port), then `sudo ufw enable`. Restrict to specific source IPs if the deployment context allows it.
• **Use ed25519 keys.** They are smaller and faster than RSA-4096, and there is no reason to use RSA for new keys.

For production field nodes, the surface area should be minimal. Only the services required for the deployment should be exposed. SSH access should require a key, logged, and ideally rate-limited at the network level. The principles around [raspberry pi SSH access in headless field deployments](raspberry-pi-ssh-headless-field-deployments) go further into operational patterns for long-lived nodes.

SSH Without a Monitor: What Changes

When there is no monitor, keyboard, or local access to the device, SSH is not just convenient -- it is the only management channel. This changes the stakes for every failure mode. If SSH breaks, the device is effectively unreachable until someone visits it physically.

The patterns that matter most in headless operation: always test SSH before sealing a device into an enclosure or shipping it to a site; use a static IP or DHCP reservation so the address is predictable; set up a reverse tunnel or VPN for devices behind NAT; use `autossh` or a systemd service to keep tunnel connections alive; and configure the Pi to restart SSH automatically if it crashes (`sudo systemctl enable ssh`).

For fully headless deployments where even SD card removal is impractical, detailed pre-flight configuration is the only reliable strategy. See [how to SSH to Raspberry Pi without a monitor](how-to-ssh-raspberry-pi-no-monitor) for a step-by-step checklist covering imaging, first-boot validation, and network configuration before a device leaves the bench.

For production infrastructure built on the Compute Module 4, boards like the [Poepi CM4 carrier](raspberry-pi-ssh-setup-headless-cm4) are designed from the start for single-cable PoE deployments with predictable boot behavior -- removing several of the common failure points that break SSH access in the field.