Home · Getting Started · Cluster Guide · Troubleshooting · About
Goal: every node can reach the internet and has a fixed IP address, every node can reach the others by name, and master can log in to every node with an SSH key.
Run on: your own computer and master, as each step says.
The Pis talk to each other over a local area network (LAN): all five plug into the switch, and the switch plugs into your router for internet access.
Each Pi needs the internet for software updates and downloads. Ethernet is the recommended connection for a cluster: it’s faster and steadier than Wi-Fi, and the nodes already need it to talk to each other.
You need:
There is nothing to configure: Raspberry Pi OS asks the router for an address automatically (DHCP) as soon as the cable is plugged in. Fixed addresses come next.
Only use Wi-Fi for a single Pi you’re testing, or if the cluster can’t be wired to your router. The Raspberry Pi 4 and Pi 5 have built-in Wi-Fi.
Easiest: set the network name (SSID), password and Wi-Fi country in Raspberry Pi Imager’s customization step when you flash the card (Install OS).
On a running Pi: Raspberry Pi OS manages networks with NetworkManager.
List nearby networks:
nmcli device wifi list
Connect, replacing the name and password:
sudo nmcli device wifi connect "Your Network" password "your-password"
The connection is saved and reconnects after a reboot.
If you prefer menus, sudo nmtui opens a text interface for the same settings. If Wi-Fi is turned off, set your country first in sudo raspi-config under Localisation Options, then WLAN Country: Wi-Fi stays blocked until a country is set.
Older guides edit /etc/wpa_supplicant/wpa_supplicant.conf. Current Raspberry Pi OS ignores that file.
ip -4 addr show eth0 # or wlan0 for Wi-Fi
ping -c 3 raspberrypi.com
The first command should show an inet line with an address such as 192.168.0.101/24. The second should show three replies. If there’s an address but no replies, the problem is between your router and the internet; if there’s no address, check the cable, the switch lights and the router.
| Pi | Interface | IP address | Hostname | Role |
|---|---|---|---|---|
| 0 | eth0 | 192.168.0.100 | master | Runs the HDFS NameNode and Spark master; sends commands |
| 1 | eth0 | 192.168.0.101 | worker1 | Stores data and runs work |
| 2 | eth0 | 192.168.0.102 | worker2 | Stores data and runs work |
| 3 | eth0 | 192.168.0.103 | worker3 | Stores data and runs work |
| 4 | eth0 | 192.168.0.104 | worker4 | Stores data and runs work |
Use your router’s network, not necessarily these numbers. Find it on any node:
ip route | grep default
If it prints default via 192.168.1.1 ..., your network is 192.168.1.x: use 192.168.1.100 to 192.168.1.104 and gateway 192.168.1.1 everywhere this guide says 192.168.0.x. Also pick addresses your router doesn’t hand out to other devices (outside its DHCP range, which its admin page shows).
The hostnames were set when you flashed the cards (Install OS). Check with hostname on each node.
Hadoop and Spark find nodes by name, and the names below map to fixed addresses. If a node’s address changed after a reboot, the cluster would lose it. Pick one of these two options.
Nothing to change on the Pis, and it survives reflashing a card.
Find each node’s hardware (MAC) address:
cat /sys/class/net/eth0/address
sudo reboot.Check: ip -4 addr show eth0 on each node shows its address from the table.
Current Raspberry Pi OS manages the network with NetworkManager, so use nmcli. Editing /etc/dhcpcd.conf, as older guides say, has no effect anymore.
Run on each node, with that node’s address from the table. The first line finds the name of the wired connection, which differs between OS versions:
CON="$(nmcli -g NAME,DEVICE connection show --active | awk -F: '$2=="eth0"{print $1}')"
sudo nmcli connection modify "$CON" \
ipv4.method manual \
ipv4.addresses 192.168.0.101/24 \
ipv4.gateway 192.168.0.1 \
ipv4.dns 192.168.0.1
sudo nmcli connection up "$CON"
/24 matches a subnet mask of 255.255.255.0, which home routers use. The gateway and DNS server are your router.
If you’re logged in over SSH, your session freezes when the address changes. Close it and log in again with the new address.
Check: reboot, then ip -4 addr show eth0 shows the new address and ping -c 3 raspberrypi.com gets replies.
Every node needs the same table of names and addresses, so master can reach worker3 by name and the other way around. It lives in /etc/hosts.
Current Raspberry Pi OS rebuilds /etc/hosts from a template at every boot, so edits made only to /etc/hosts disappear after a reboot. The file also maps each node’s own name to 127.0.1.1, which would make Hadoop listen only to itself. scripts/setup_hosts.sh handles both: it writes the block below to /etc/hosts and to the template, and removes the 127.0.1.1 line.
# pi-cluster network
192.168.0.100 master
192.168.0.101 worker1
192.168.0.102 worker2
192.168.0.103 worker3
192.168.0.104 worker4
# end pi-cluster network
Keep the first and last comment lines exactly as written: the cluster commands use them to find the node list.
On your computer, download the script and edit the addresses at its top if your network differs:
curl -fsSLO https://raw.githubusercontent.com/gitluis/pi-cluster/master/scripts/setup_hosts.sh
Copy it to every node and run it there (you’ll be asked for your password for sudo on each):
for h in master worker1 worker2 worker3 worker4; do
scp setup_hosts.sh alice@$h.local: && ssh -t alice@$h.local 'sudo bash setup_hosts.sh'
done
If .local names don’t work on your network, run it once per node with its IP address instead of $h.local.
Check: on any node, getent hosts worker3 prints 192.168.0.103 worker3, and ping -c 1 master replies from 192.168.0.100. Reboot one node and check again: the block must still be there.
Imager already installed your computer’s key on every node. master needs its own key on every node too, because Hadoop and Spark start their services on the workers by logging in from master over SSH. That includes master itself.
Your nodes accept keys only, not passwords, so ssh-copy-id from master won’t work. Copy the key through your computer, which can already log in everywhere.
Make a key on master, without a passphrase so services can start unattended:
ssh alice@master.local 'ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519'
From your computer, add master’s public key to every node, master included:
KEY="$(ssh alice@master.local 'cat ~/.ssh/id_ed25519.pub')"
for h in master worker1 worker2 worker3 worker4; do
ssh alice@$h.local "grep -qxF '$KEY' ~/.ssh/authorized_keys || echo '$KEY' >> ~/.ssh/authorized_keys"
done
On master, connect to every node once so it records their fingerprints:
for h in master worker1 worker2 worker3 worker4; do
ssh -o StrictHostKeyChecking=accept-new $h hostname
done
Check: step 3 prints all five hostnames without asking for a password or confirmation.
The private key ~/.ssh/id_ed25519 on master lets anyone who has it into every node. Never copy or share it; only the .pub file goes to other machines.
Step 3 of 9 · ← Step 2: Install OS · Step 4: Cluster Commands →