ErgoTechWiki

User Tools

Site Tools

Trace:
baseraspberrypisetupbookworm

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
baseraspberrypisetupbookworm [2026/10/26 15:45] – [Wired Ethernet] tputmanbaseraspberrypisetupbookworm [2026/10/27 16:55] (current) – tputman
Line 4: Line 4:
  
 Complete this setup before installing MIX or the TransSECS built deployment. Complete this setup before installing MIX or the TransSECS built deployment.
 +
 +This guide was validated using a **Raspberry Pi 4 with Raspberry Pi OS Bookworm Legacy 64-bit Lite** installed through Raspberry Pi Imager. Current MIX and TransSECS deployments were validated on this system using **Java 25**. Sections describing Raspberry Pi 5 hardware, command-line imaging, or MIX-specific network configuration are retained as reference information but were not part of this validation.
  
 ===== 1. Hardware ===== ===== 1. Hardware =====
Line 9: Line 11:
 For a new installation, use a **Raspberry Pi 4 or Raspberry Pi 5**. For a new installation, use a **Raspberry Pi 4 or Raspberry Pi 5**.
  
-A TransSECS Devices system can normally run on a 1 GB Pi or better (2GB or 4GB, for example). If the Raspberry Pi will also display a MIX or MIStudio user interface in a browser, use **4 GB or more**.+A TransSECS Devices system can normally run on a 1 GB Pi or better (2 GB or 4 GB, for example). If the Raspberry Pi will also display a MIX user interface in a browser, use **4 GB or more**.
  
 If your Raspberry Pi came with an OS installed on its microSD Card, you may start with this installation or you may start with a new SD Card and keep this bundled SD Card for reference. If your Raspberry Pi came with an OS installed on its microSD Card, you may start with this installation or you may start with a new SD Card and keep this bundled SD Card for reference.
Line 39: Line 41:
   - Choose your Raspberry Pi model.   - Choose your Raspberry Pi model.
   - Choose the appropriate Raspberry Pi OS **Bookworm** image.   - Choose the appropriate Raspberry Pi OS **Bookworm** image.
-      - Raspberry Pi 4 or 5, headless: Raspberry Pi OS (Legacy, 64-bit) Lite+    - Raspberry Pi 4 or 5, headless: **Raspberry Pi OS (Legacy, 64-bit) Lite**
   - Use **Lite** when the Pi will run TransSECS or MIX without its own graphical display (running headless).   - Use **Lite** when the Pi will run TransSECS or MIX without its own graphical display (running headless).
   - Use **Desktop** when the Raspberry Pi itself will drive a screen, although the kiosk article also describes installing only the graphical packages which are needed.   - Use **Desktop** when the Raspberry Pi itself will drive a screen, although the kiosk article also describes installing only the graphical packages which are needed.
Line 72: Line 74:
 Then connect Ethernet if needed and apply power. Then connect Ethernet if needed and apply power.
  
-===== 3. Command-line alternative using dd =====+===== 3. Command-line image setup alternative =====
  
-Experienced Linux users may write a downloaded ''%%.img.xz%%'' image directly using dd.+This section is an alternative for experienced Linux users and was not part of the Raspberry Pi 4 validation described above.
  
-When using ''%%dd%%'', create the SSH and user configuration on the boot partition after imaging:+Experienced Linux users may write a downloaded ''%%.img.xz%%'' image directly using their normal Linux imaging workflow. 
 + 
 +After imaging, create the SSH and user configuration on the boot partition:
  
 <code text> <code text>
 sudo touch /media/$USER/bootfs/ssh sudo touch /media/$USER/bootfs/ssh
 echo "mix:$(echo 'ErgoErgo' | openssl passwd -6 -stdin)" | sudo tee /media/$USER/bootfs/userconf.txt echo "mix:$(echo 'ErgoErgo' | openssl passwd -6 -stdin)" | sudo tee /media/$USER/bootfs/userconf.txt
-sudo umount /media/$USER/bootfs 
 </code> </code>
 +
 +The boot partition mount path varies by Linux distribution. Replace ''%%/media/$USER/bootfs%%'' with the actual mount point of the SD card's ''%%bootfs%%'' partition if necessary.
 +
 +Safely unmount or eject the microSD card before removing it from the computer.
  
 After the first login, set the hostname and correct time zone: After the first login, set the hostname and correct time zone:
Line 97: Line 104:
 ===== 4. First login with SSH ===== ===== 4. First login with SSH =====
  
-Connect Ethernet and power, then allow about a minute for the first boot.+Connect the Raspberry Pi to the network using Ethernet or the WiFi configuration created in Raspberry Pi Imager, then apply power. Allow about a minute for the first boot.
  
 From Windows Command Prompt, PowerShell, Linux, or macOS: From Windows Command Prompt, PowerShell, Linux, or macOS:
Line 171: Line 178:
   * A Raspberry Pi 4 or 5 using the 64-bit image reports ''%%aarch64%%''.   * A Raspberry Pi 4 or 5 using the 64-bit image reports ''%%aarch64%%''.
   * The reported Raspberry Pi model matches the hardware being configured.   * The reported Raspberry Pi model matches the hardware being configured.
 +
 ===== 5. Give the Pi a fixed IP address ===== ===== 5. Give the Pi a fixed IP address =====
  
Line 179: Line 187:
 ==== Wired Ethernet ==== ==== Wired Ethernet ====
  
-For a TransSECS-only system using wired Ethernet:+For a system using wired Ethernet:
  
 <code text> <code text>
Line 193: Line 201:
 </code> </code>
  
-After saving, restart the connection:+After saving, restart the connection. 
 + 
 +Replace ''%%Wired connection 1%%'' with the actual wired connection name shown by ''%%nmcli connection show%%'' if it is different.
  
 <code text> <code text>
Line 244: Line 254:
  
 Choose **Network Configuration**. Choose **Network Configuration**.
 +
 +This MIX setup-page method was not part of the base Raspberry Pi validation described above.
 +
 ===== 6. Check the hostname configuration ===== ===== 6. Check the hostname configuration =====
  
Line 295: Line 308:
  
 The Linux login username does not need to change when the hostname changes. The Linux login username does not need to change when the hostname changes.
 +
 ===== 7. Network interfaces ===== ===== 7. Network interfaces =====
  
Line 318: Line 332:
  
 For MIX systems, network configuration can also be managed through the MIX setup page. For MIX systems, network configuration can also be managed through the MIX setup page.
 +
 ===== 8. Update Linux and install supporting packages ===== ===== 8. Update Linux and install supporting packages =====
  
Line 343: Line 358:
 active active
 </code> </code>
 +
 ===== 9. Disable Automatic Software Updates ===== ===== 9. Disable Automatic Software Updates =====
  
Line 461: Line 477:
  
 These changes do not prevent an administrator from installing updates manually later. Updates can still be performed deliberately during a maintenance period after they have been reviewed and tested. These changes do not prevent an administrator from installing updates manually later. Updates can still be performed deliberately during a maintenance period after they have been reviewed and tested.
-===== 10. Install Java 8 ===== 
  
-ErgoTech applications covered by this guide use **Java 8** unless ErgoTech support specifies otherwise.+===== 10. Install Java 25 =====
  
-For a 64-bit Raspberry Pi OS installation:+Current MIX and TransSECS deployments validated with this guide require **Java 25**. 
 + 
 +The validated Raspberry Pi installation used **Azul Zulu OpenJDK 25.0.3 LTS for ARM64**. 
 + 
 +The Java installation used during validation is:
  
 <code text> <code text>
-cd /tmp +/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
-wget -O java8.tar.gz "https://api.adoptium.net/v3/binary/latest/8/ga/linux/aarch64/jre/hotspot/normal/eclipse" +
-sudo mkdir -p /opt/java +
-sudo tar -xzf java8.tar.gz -C /opt/java +
-ls /opt/java+
 </code> </code>
  
-The ''%%ls%%'' command shows the folder which was extracted.+Create the Java installation directory if it does not already exist: 
 + 
 +<code text> 
 +sudo mkdir -p /opt/java 
 +</code>
  
-For example, the folder may look similar to:+Install or extract the approved Java 25 ARM64 package under:
  
 <code text> <code text>
-jdk8u504-b01-jre+/opt/java
 </code> </code>
  
-The exact Java version changes over time. Use the **actual folder name shown by ''%%ls /opt/java%%''** in the next command rather than copying the example version literally.+If the Java package is supplied as a ''%%.tar.gz%%'' archive, extract it into ''%%/opt/java%%'' and then check the resulting directory name.
  
 For example: For example:
  
 <code text> <code text>
-sudo update-alternatives --install /usr/bin/java java /opt/java/jdk8u504-b01-jre/bin/java 100+cd /tmp 
 +wget -O zulu25.tar.gz "https://cdn.azul.com/zulu/bin/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64.tar.gz" 
 +sudo mkdir -p /opt/java 
 +sudo tar -xzf zulu25.tar.gz -C /opt/java 
 +ls /opt/java
 </code> </code>
  
-Replace ''%%jdk8u504-b01-jre%%'' with the directory which was actually extracted on the system. +For the validated installation, the Java directory is:
- +
-Verify the Java version:+
  
 <code text> <code text>
-java -version+zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
 </code> </code>
  
-The version should begin with:+Verify Java directly from that installation:
  
 <code text> <code text>
-openjdk version "1.8.0_+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
 </code> </code>
  
-Also verify which Java executable is selected:+The validated installation reports:
  
 <code text> <code text>
-readlink -f /usr/bin/java+openjdk version "25.0.3" 
 +OpenJDK Runtime Environment Zulu25.34+17-CA 
 +OpenJDK 64-Bit Server VM Zulu25.34+17-CA
 </code> </code>
  
-The path should point to the Java 8 installation under:+Also verify that the Java executable exists:
  
 <code text> <code text>
-/opt/java/+ls -l /opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
 </code> </code>
  
-If Java 17, Java 21, or another version is still selected:+MIX and TransSECS select this Java installation explicitly. 
 + 
 +MIX uses ''%%MIX_JAVA_HOME%%'':
  
 <code text> <code text>
-sudo update-alternatives --config java+MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
 </code> </code>
  
-Choose the Java 8 entry under ''%%/opt/java%%'', then run:+A TransSECS deployment can use the same Java installation by placing its ''%%bin%%'' directory first in ''%%PATH%%'':
  
 <code text> <code text>
-java -version +PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH
-readlink -f /usr/bin/java+
 </code> </code>
  
-again to verify the selection.+The MIX and TransSECS installation procedures configure these Java settings when their services are installed.
  
-==== Java 11 when specifically required ====+It is not necessary to change the Raspberry Pi's system-wide ''%%java%%'' selection for MIX or TransSECS to use Java 25.
  
-Only install or select Java 11 when ErgoTech support asks for it.+Java 8 is not required as part of the current Raspberry Pi base setup. During current TransSECS validation, the deployed runtime could not start using Java 8 because the deployed classes require Java 25.
  
-<code text> +Older ErgoTech software releases may have different Java requirements. Follow the requirements for the specific software release when maintaining an older system.
-cd /tmp +
-wget -O java11.tar.gz "https://api.adoptium.net/v3/binary/latest/11/ga/linux/aarch64/jre/hotspot/normal/eclipse" +
-sudo tar -xzf java11.tar.gz -C /opt/java +
-ls /opt/java +
-</code>+
  
-Register the extracted Java 11 installation using its actual folder name and a lower priority than Java 8. 
 ===== 11. Keep Linux system logs from filling the SD card ===== ===== 11. Keep Linux system logs from filling the SD card =====
  
Line 564: Line 582:
 The exact layout can vary between Raspberry Pi OS versions. The exact layout can vary between Raspberry Pi OS versions.
  
-On current Raspberry Pi OS Bookworm Lite, the configuration may contain one combined block similar to:+On the Bookworm Lite system used for this validation, the configuration contained one combined block similar to:
  
 <code text> <code text>
Line 587: Line 605:
 </code> </code>
  
-In this layout, there may be no existing ''%%size%%'' or ''%%maxsize%%'' setting and ''%%/var/log/daemon.log%%'' may not exist.+There was no existing ''%%size%%'' or ''%%maxsize%%'' setting and ''%%/var/log/daemon.log%%'' was not present.
  
 Edit the configuration: Edit the configuration:
Line 595: Line 613:
 </code> </code>
  
-For the combined Bookworm block, add:+For this combined Bookworm block, add:
  
 <code text> <code text>
Line 621: Line 639:
 </code> </code>
  
-If the system uses a different rsyslog layout with separate log blocks and existing ''%%size%%'' or ''%%maxsize%%'' settings, set the applicable system-log limits to **20M** while preserving the existing layout.+If the system uses a different rsyslog layout with separate log blocks and existing ''%%size%%'' or ''%%maxsize%%'' settings, preserve that layout rather than creating log files which do not already exist.
  
 Do not create ''%%/var/log/daemon.log%%'' solely because it is not present. Do not create ''%%/var/log/daemon.log%%'' solely because it is not present.
- 
-Do not change the other logrotate settings. 
  
 Save with **Ctrl+O**, **Enter**, **Ctrl+X**. Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
Line 637: Line 653:
 The ''%%-d%%'' option is a safe debug check. It does not actually rotate the logs. The ''%%-d%%'' option is a safe debug check. It does not actually rotate the logs.
  
-For a configuration using ''%%maxsize 20M%%'', the output should contain a line similar to:+For the validated configuration using ''%%maxsize 20M%%'', the output contained a line similar to:
  
 <code text> <code text>
Line 647: Line 663:
 ==== Limit the systemd journal ==== ==== Limit the systemd journal ====
  
-Also cap the systemd journal at 50 MB:+Cap the systemd journal at 50 MB:
  
 <code text> <code text>
Line 669: Line 685:
 </code> </code>
  
-The current journal may be much smaller than 50 MB. The setting limits future growth; it does not require the journal to already be near that size.+The journal on the validated system was well below this limit. The setting limits future growth; it does not require the journal to already be near 50 MB. 
 ===== 12. Add startup cleanup and recovery ===== ===== 12. Add startup cleanup and recovery =====
  
-''%%/etc/rc.local%%'' is a traditional Linux startup script which runs near the end of the boot process. On a Raspberry Pi it is useful for small recovery and housekeeping tasks after a power interruption.+''%%/etc/rc.local%%'' is a traditional Linux startup script which is useful for small recovery and housekeeping tasks after a power interruption.
  
-On Raspberry Pi OS Bookworm Lite, ''%%/etc/rc.local%%'' may not exist on a fresh installation. The systemd compatibility service is already provided and will automatically run ''%%/etc/rc.local%%'' at boot when the file exists and is executable.+On the Bookworm Lite system used for this validation, ''%%/etc/rc.local%%'' did not exist initially. Raspberry Pi OS already provided the systemd compatibility service needed to run the file once it existed and was executable.
  
 Check whether the file already exists: Check whether the file already exists:
Line 694: Line 711:
 </code> </code>
  
-Replace the file with:+Use:
  
 <code text> <code text>
Line 720: Line 737:
 # Trim oversized Linux system logs # Trim oversized Linux system logs
 find /var/log -maxdepth 1 -type f  find /var/log -maxdepth 1 -type f 
-  \( -name "syslog*" \ +  \( -name "syslog*"  
-  -o -name "daemon.log*" \ +  -o -name "daemon.log*"  
-  -o -name "auth.log*" \ +  -o -name "auth.log*"  
-  -o -name "kern.log*" \ +  -o -name "kern.log*"  
-  -o -name "messages*" \) \ +  -o -name "messages*" \)  
-  -size +20M \+  -size +20M 
   -exec truncate -s 5M {} \;   -exec truncate -s 5M {} \;
  
Line 768: Line 785:
 The test should complete without shell errors. The maintenance log should contain a start time, disk-usage information, and a finish time. The test should complete without shell errors. The maintenance log should contain a start time, disk-usage information, and a finish time.
  
-''%%rc-local.service%%'' is a static compatibility service on Raspberry Pi OS Bookworm. It does not need to be enabled manually. Once ''%%/etc/rc.local%%'' exists and is executable, systemd will run it automatically during boot.+On the validated Bookworm system, ''%%rc-local.service%%'' was a static compatibility service and did not need to be enabled manually. Once ''%%/etc/rc.local%%'' existed and was executable, it ran automatically during boot.
  
 Reboot to verify automatic startup: Reboot to verify automatic startup:
Line 783: Line 800:
 </code> </code>
  
-The service should show:+The validated system showed:
  
 <code text> <code text>
Line 792: Line 809:
  
 The [[SetupChromeKioskOnRpi]|MIX kiosk article]] adds two browser-specific cleanup commands to this file. The [[SetupChromeKioskOnRpi]|MIX kiosk article]] adds two browser-specific cleanup commands to this file.
- 
- 
  
 ===== 13. Timekeeping ===== ===== 13. Timekeeping =====
- 
  
 ==== Raspberry Pi 5 ==== ==== Raspberry Pi 5 ====
  
 The Pi 5 has a built-in real-time clock. With the official RTC battery installed, it can retain the time while power is off. The Pi 5 has a built-in real-time clock. With the official RTC battery installed, it can retain the time while power is off.
 +
 +This Raspberry Pi 5 path was not part of the Raspberry Pi 4 validation described above.
  
 Check: Check:
Line 814: Line 830:
 These models do not have a battery-backed real-time clock. ''%%fake-hwclock%%'' saves an approximate time which Linux can restore after a power interruption. These models do not have a battery-backed real-time clock. ''%%fake-hwclock%%'' saves an approximate time which Linux can restore after a power interruption.
  
-On Raspberry Pi OS Bookworm, ''%%fake-hwclock%%'' is installed with a systemd service and an hourly save task. ErgoTech systems save the clock more frequently so that less time is lost after an unexpected power interruption.+On the Raspberry Pi 4 used for validation, ''%%fake-hwclock%%'' was installed with a systemd service and an hourly save task. ErgoTech systems save the clock more frequently so that less time is lost after an unexpected power interruption.
  
 Save the clock every five minutes: Save the clock every five minutes:
Line 852: Line 868:
  
 <code text> <code text>
-CRON: (root) CMD (/usr/sbin/fake-hwclock)+CRON: (root) CMD (/sbin/fake-hwclock save)
 </code> </code>
  
Line 863: Line 879:
 </code> </code>
  
-On a Raspberry Pi 3 or 4, ''%%RTC time: n/a%%'' is normal because these models do not have a battery-backed real-time clock.+On the Raspberry Pi 4 used for validation, ''%%RTC time: n/a%%'' was normal.
  
 Verify that the time zone is correct and that the system clock is synchronized when a network time source is available. Verify that the time zone is correct and that the system clock is synchronized when a network time source is available.
  
-If the factory network has no Internet or local time server, the clock may drift. MIX provides another convenient way to set the system time by loading **Get Pre-License Key** on the setup page. In addition, for SECS/GEM tool applications, the host can also set the Pi's clock by sending the standard **S2F31 Date and Time Set Request** message. This updates the system clock in the same way which opening the MIX Get Pre-License Key page updates it from the browser. 
 ===== 14. Verify the base setup ===== ===== 14. Verify the base setup =====
  
Line 879: Line 894:
  
 <code text> <code text>
-java -version +/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
-readlink -f /usr/bin/java+
 cat /var/log/ergotech-boot-maintenance.log cat /var/log/ergotech-boot-maintenance.log
 df -h / df -h /
Line 890: Line 904:
 Verify: Verify:
  
-  * Java reports version ''%%1.8.0_...%%''. +  * Java 25 starts successfully from ''%%/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64%%''. 
-  * ''%%/usr/bin/java%%'' resolves to the Java 8 installation under ''%%/opt/java%%''.+  * Java reports version ''%%25.0.3%%'' for the validated installation.
   * The boot-maintenance log contains a new start and finish entry from the reboot.   * The boot-maintenance log contains a new start and finish entry from the reboot.
   * The root filesystem has plenty of free space.   * The root filesystem has plenty of free space.
Line 918: Line 932:
 If a fixed IP address was configured, reconnect using that address after the reboot to confirm that the network configuration persisted. If a fixed IP address was configured, reconnect using that address after the reboot to confirm that the network configuration persisted.
  
-At this point the SD card can be used as a **base master image** before TransSECS or MIX is installed.+At this point the SD card can be preserved as a **completed base image** before TransSECS or MIX is installed.
  
 Before removing the SD card, shut the Pi down cleanly: Before removing the SD card, shut the Pi down cleanly:
baseraspberrypisetupbookworm.1793043906.txt.gz · Last modified: by tputman
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki