Setting up the software

There are three different methods to setup the ClusterCTRL software - you only need to follow ONE of these guides below (Simple/Intermediate/Manual).

The pre-created images (Simple/Intermediate) for each node (Raspberry Pi Zero/Compute Module/A+) and the Controller below are currently based on Raspberry Pi OS Bookworm with Desktop and Lite (2024-07-04).

NEW It's now possible to mix/match booting nodes with or without an SD card. See the HOWTO for details on setting this up once you're running one of the CBRIDGE or CNAT images below on the controller.

 

Download an image for each Pi (Controller/P1/P2/P3/P4) and write to the SD cards. We have Controller versions available as Bookworm with desktop Graphical interface Bookworm with desktop and Bookworm Lite (LITE), you only need to download one version for the controller.

The CBRIDGE images below bridge the USB Gadget Ethernet from the Pi Zeros to eth0 on the Controller allowing them to obtain an IP address from a DHCP server on your local Ethernet connected network (Bridging does not work with WiFi, please use the CNAT images).

The CNAT image uses NAT (Network Address Translation) to automatically share either Ethernet or Wifi connection on the Controller with the Pi Zeros. See the official documentation for details on how to setup WiFi on the controller. The Pi Zeros will automatically be assigned a 172.19.181.X IP address where X is the pX number (172.19.181.254 will be used on the controller).

64-bit for Pi 5/4/400/CM4/CM4S/3/3+/CM3/Zero2 models

  • CBRIDGE - Desktop Controller - Desktop Bookworm image for the controller. (3/3+/4/400)
  • CNAT - Desktop Controller - Desktop Bookworm image for the controller (3/3+/4/400).
  • CBRIDGE - Lite Controller - Lite Bookworm image for the controller (3/3+/4/400).
  • CNAT - Lite Controller - Lite Bookworm image for the controller (3/3+/4/400).
  • P1 - Lite Bookworm image (Zero 2/A3+/CM3/CM4 only) P1.
  • P2 - Lite Bookworm image (Zero 2/A3+/CM3/CM4 only) P2.
  • P3 - Lite Bookworm image (Zero 2/A3+/CM3/CM4 only) P3.
  • P4 - Lite Bookworm image (Zero 2/A3+/CM3/CM4 only) P4.
  • P5 - Lite Bookworm image (Zero 2/A3+/CM3/CM4 only) P5 (for use with the A+6 or Triple).

32-bit for all Pi (5/4/400/CM4/CM4S/3/3+/CM3/2/A+/B+/Zero/Zero2) models

For old releases, USBBOOT/RPIBOOT archives and test images (when available) please browse the download area.

See the HOWTO if you wish to boot the Pi Zero/Pi Zero 2 without SD cards.

Follow the standard instructions to write each of the above images to the corresponding SD Card.

Default User/Password for Bookworm images

The bullseye/bookworm images do not have default usernames or passwords. You can either use the Raspberry Pi Imager or manually add details to a userconf.txt file in the boot partition to set the initial username/password. Please see the official blog post for more details.

The Bookworm/Bullseye usbboot archives also need a userconf.txt. Once the usbboot archive has been extracted you can use something like this to create a password for p1.

# NOT NEEDED WHEN USING SD CARDS (for USBBOOT archives when booting without SD cards in Pi Zeros)
set +o history # Turn off bash history temporarily
# Replace myusername and mypassword with your details and pX with the node (p1/p2/etc.).
echo "myusername:"$(echo 'mypassword' | openssl passwd -6 -stdin) | sudo tee /var/lib/clusterctrl/nfs/pX/boot/userconf.txt
set -o history # Turn history back on again
You can then "touch boot/ssh" to enable SSH if needed and run "usbboot-init 1" as normal and it's ready to power on p1.

Default User/Password for Buster and earlier images

The default login details arei
Username: pi
Password: clusterctrl
We strongly advise changing the pi users password using the raspi-config tool on your first login.

SSH

SSH is no longer enabled by default on any of the images, to enable SSH you will need to enable it using the Pi Imager or create a file named "ssh" in the boot partition (see the Raspberry Pi blog entry for more details). SSH needs to be enabled on both Controller and Pi Zero images (from the Controller Pi the Pi Zeros can be accessed via the serial console if SSH is disabled).

 

Follow the standard instructions to write the images to your SD Cards for Controller/P1/P2/P3/P4.

To convert the controller image you need to append " quiet init=/sbin/reconfig-clusterctrl TYPE" to the cmdline.txt file in the boot (first) partition using either a Windows, Mac or Linux machine. Replacing "TYPE" with either "cnat" for a controller with NAT (Network Address Translation), "cbridge" for CBRIDGE (Pi Zero network bridged with the controllers Ethernet port) or "p1", "p2", "p3, "p4", etc. for a Pi Zero nodes.

See the HOWTO if you wish to boot the Pi Zeros without SD cards.

Username: pi
Password: clusterctrl

We strongly advise changing the pi users password and resizing the filesystem using the raspi-config tool on your first login.

SSH

SSH is no longer enabled by default on any of the images, to enable SSH you will need to create a file named "ssh" in the boot partition - see the Raspberry Pi blog entry for more details, this needs to be done on both Controller and Pi Zero images (from the Controller Pi the Pi Zeros can be accessed via the serial console when SSH is disabled).

The images above are configured to obtain an IP address automatically using DHCP (Pi Zero network is bridged to eth0 on the Controller Pi).

 

Manually configure the software for Controller/P1/P2/P3/P4, this can be used to customise your own images or to "port" to different distributions.

Below are a list of steps we take when creating a new image. You should be able to follow these as a base to create/modify your own custom images.

  • Copy base Raspberry Pi OS image file and rename for the controller.
  • Setup variables for the build.
  • Use losetup to create a loop device for the new file.
  • Enable access to the partitions on the loop device using kpartx
  • mount both root and boot filesystems
  • Install any updates, remove dhcpcd5 and install required tools
  • Force boot to be text mode
  • Setup getty on ttyGS0 (The USB gadget device)
  • Setup the hostname and /etc/hosts file
  • Download/Extract ClusterHAT software/config files
  • Copy controller config file into place
  • Disable auto filesystem resize
  • Setup /boot/config.txt file
  • Cleanup
  • Unmount, cleanup partitions and loop devices
  • Copy the controller image for p1/p2/p3/p4
  • Use losetup to create a loop device for the new file.
  • Enable access to the partitions on the loop device using kpartx
  • mount both root and boot filesystems
  • Setup the cmdline.txt for P1 or P2/P3/P4.
  • Unmount, cleanup partitions and loop devices

The build script can be downloaded/viewed here.

Once the controller image has been created this can be modified to change into images for p1/p2/p3/p4 by editing the cmdline.txt file.

The scripts above should not be ran before reviewing the code and understanding exactly what they're going to do on your system. AKA don't blame me if they cause data loss/etc.


Use of our images is optional if you prefer to setup the OS/network to your requirements. A copy of our controller script is available to download