Merge pull request #48 from macmpi/dev

macmpi · web-flow · commit d8fbe8d286a1 · 2025-08-27T14:46:08.000+02:00
Version 1.3
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,4 @@
+[submodule "xg_multi"]
+	path = xg_multi
+	url = ../xg_multi
+	branch = main
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2023 macmpi
+Copyright (c) 2022-2025, macmpi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
@@ -9,13 +9,13 @@ An optional script may also be launched during that same initial bootstrap, to p
 
 ## Setup procedure:
 Please follow [Alpine Linux Wiki](https://wiki.alpinelinux.org/wiki/Installation#Installation_Overview) to download & create installation media for the target platform.\
-Tools provided here can be used on any plaform for any install modes (diskless, data disk, system disk).
+Tools provided here can be used on any hardware platform to prepare for any install modes (diskless, data disk, system disk).
 
 Just add [**headless.apkovl.tar.gz**](https://is.gd/apkovl_master)[^2] overlay file *as-is* at the root of Alpine Linux boot media (or onto any custom side-media) and boot-up the system.\
 With default DCHP-based network interface definitions (and [SSID/pass](#extra-configuration) file if using wifi), system can then be remotely accessed with: `ssh root@<IP>`\
 (system IP address may be determined with any IP scanning tools such as `nmap`).
 
-As with Alpine Linux initial bring-up, `root` account has no password initially (change that during target setup!).\
+As with Alpine Linux initial bring-up, `root` account has no password initially.\
 From there, actual system install can be performed as usual with `setup-alpine` for instance (check [wiki](https://wiki.alpinelinux.org/wiki/Alpine_setup_scripts#setup-alpine) for details).
 
 ## Extra configuration:
@@ -26,17 +26,18 @@ Extra files may be added next to `headless.apkovl.tar.gz` to customise boostrapp
 - `authorized_keys` (*optional*): provide client's public SSH key to secure `root` ssh login.
 - `ssh_host_*_key*` (*optional*): provide server's custom ssh keys to be injected (may be stored), instead of using bundled ones[^2] (not stored). Providing an empty key file will trigger new keys generation (ssh server may take longer to start).
 - `opt-out` (*optional*): dummy file to opt-out internet features (connection status, version check, auto-update) and related links usage anonymous [telemetry](https://is.gd/privacy.php).
-- `auto-updt` (*optional*): allow apkovl file automatic update with latest from master branch. If it contains *reboot* keyword all in one line, system will reboot after succesful update (unless ssh session is active or `unattended.sh` script is available).
+- `auto-updt` (*optional*): enable automatic `headless.apkovl.tar.gz` file update with latest from master branch. If it contains `reboot` keyword all in one line, system will reboot after succesful update (unless ssh session is active or `unattended.sh` script is available).
 
 Main execution steps are logged: `cat /var/log/messages | grep headless`.
 
 ## Goody:
-Seamless USB-serial & USB-ethernet gadget mode (*e.g. PiZero*):
-- Make sure dwc2/dwc3 driver is loaded accordingly, and device configuration is set to `peripheral` mode: this may be hardware (including cable) and/or software driven.\
-(on supporting Pi devices, just add `dtoverlay=dwc2,dr_mode=peripheral` in `usercfg.txt` (or `config.txt`) to force by software)
+Seamless USB-gadget mode: serial console, ethernet and mass-storage (*e.g. on PiZero*), leveraging [xg_multi](https://github.com/macmpi/xg_multi/).
+- Make sure `dwc2` (or `dwc3`) driver is previously loaded on device, and configuration is set to **OTG peripheral** mode: this may be driven by hardware (including cable) and/or software.\
+(on supporting Pi devices, just add `dtoverlay=dwc2,dr_mode=peripheral` in `usercfg.txt` (or `config.txt`) to force both by software)
 - Plug USB cable into host Computer port before boot.\
-Serial terminal can then be connected-to from host Computer (e.g. `cu -l ttyACM0` on Linux. xon/xoff flow control).\
-Alternatively, with host Computer set-up to share networking with USB interface as 10.42.0.1 gateway, one can log into device from host with: `ssh root@10.42.0.2`.
+-- serial terminal can then be connected-to from host Computer (e.g. `cu -l ttyACM0` on Linux. xon/xoff flow control).\
+-- alternatively, with host Computer ECM/RNDIS interface set-up as 10.42.0.1 (sharing internet or not), one can log into device from host with: `ssh root@10.42.0.2`.\
+-- volume containing `headless.apkovl.tar.gz` file may be accessed/mounted from host, and config files easily edited. Make sure to unmount properly before removing USB plug.
 
 [^1]: Initial boot fully preserves system's original state (config files & installed packages): a fresh system will therefore come-up as unconfigured.
 
@@ -54,4 +55,3 @@ Execute `./make.sh` to rebuild `headless.apkovl.tar.gz` after changes.\
 
 ## Credits
 Thanks for the initial guides & scripts from @sodface and @davidmytton.
-
diff --git a/headless.apkovl.tar.gz b/headless.apkovl.tar.gz
diff --git a/headless.apkovl.tar.gz.sha512 b/headless.apkovl.tar.gz.sha512
@@ -1 +1 @@
-fecc6b66f1b08a959c6509334b5c1942b8df76ba6b7d51c54630f0c502706650b9d345bab71cd3d787681113eb5c1a40b2f6bc238ca6e4137fd00de8a6bc8a17  headless.apkovl.tar.gz
+7d72e7a46066aebb0572f1431d6e9f354b3d0df4fce0a05090c1667f68738e876c195460d294a0c279c86d02b65d101625ed9c86a1f465c2f2f29ee59bdde5fa  headless.apkovl.tar.gz
diff --git a/make.sh b/make.sh
@@ -1,6 +1,6 @@
 #!/bin/busybox sh
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 # Script meant to be run on Alpine (busybox) or on Ubuntu.
@@ -18,6 +18,7 @@ if [ -n "$build_path" ]; then
 	# prefer timestamp option for touch as it works on directories too
 	t_stamp="$( TZ=UTC date +%Y%m%d0000.00 )"
 	cp -a overlay "$build_path"/.
+	cp xg_multi/xg_multi "$build_path"/overlay/usr/local/bin/.
 	find "$build_path"/overlay/ -exec sh -c 'TZ=UTC touch -chm -t "$0" "$1"' "$t_stamp" {} \;
 	# setting modes and owner/groups for runtime (won't affect mtime)
 	find "$build_path"/overlay/etc -type d -exec chmod 755 {} \;
diff --git a/overlay/etc/init.d/headless_bootstrap b/overlay/etc/init.d/headless_bootstrap
@@ -1,6 +1,6 @@
 #!/sbin/openrc-run
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 description="Headless main boostrappring script"
diff --git a/overlay/etc/init.d/headless_cleanup b/overlay/etc/init.d/headless_cleanup
@@ -1,6 +1,6 @@
 #!/sbin/openrc-run
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 description="Headless cleanup script"
diff --git a/overlay/etc/init.d/headless_unattended b/overlay/etc/init.d/headless_unattended
@@ -1,6 +1,6 @@
 #!/sbin/openrc-run
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 description="Headless unattended setup script (optional)"
diff --git a/overlay/etc/modprobe.d/headless_gadget.conf b/overlay/etc/modprobe.d/headless_gadget.conf
diff --git a/overlay/usr/local/bin/headless_bootstrap b/overlay/usr/local/bin/headless_bootstrap
@@ -1,9 +1,9 @@
 #!/bin/sh
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
-HDLSBSTRP_VERSION="1.2.3"
+HDLSBSTRP_VERSION="1.3"
 
 _apk() {
 	local cmd="$1"
@@ -35,8 +35,11 @@ _preserve() {
 _restore() {
 # Remove element (file, folder, symlink) and replace by
 # previous back-up if available.
+# shellcheck disable=SC2317  # known special case
 	[ -z "${1}" ] && return 1
+# shellcheck disable=SC2317  # known special case
 	rm -rf "${1}"
+# shellcheck disable=SC2317  # known special case
 	[ -e "${1}".orig ] && mv -f "${1}".orig "${1}"
 }
 
@@ -62,11 +65,11 @@ cat <<-EOF >>/tmp/.trash/headless_cleanup
 	_apk del wpa_supplicant
 	_restore "/etc/network/interfaces"
 	_restore "/etc/hostname"
-	rm -f /etc/modprobe.d/headless_gadget.conf
 
 	# Remove from boot service to avoid spurious openrc recalls from unattended script.
 	rm -f /etc/runlevels/default/headless_bootstrap
 	rm -f /usr/local/bin/headless_bootstrap
+	rm -f /usr/local/bin/xg_multi
 
 	# Run unattended script if available.
 	install -m755 ${ovlpath}/unattended.sh /tmp/headless_unattended >/dev/null 2>&1 && \
@@ -76,11 +79,11 @@ cat <<-EOF >>/tmp/.trash/headless_cleanup
 	rm -f /etc/init.d/headless_*
 	_logger "Clean-up done, enjoy !"
 	cat /tmp/.trash/banner >/dev/console
-	if [ -c /dev/ttyGS${gdgt_id} ]; then
+	if [ -c /dev/ttyGS0 ]; then
 		# Enabling terminal login into valid serial port:
 		# no choice than making permanent change to /etc/securetty (Alpine 3.19 already has ttyGS0).
-		grep -q "ttyGS${gdgt_id}" /etc/securetty || echo "ttyGS${gdgt_id}" >>/etc/securetty
-		/sbin/getty -L 115200 /dev/ttyGS${gdgt_id} vt100 &
+		grep -q "ttyGS0" /etc/securetty || echo "ttyGS0" >>/etc/securetty
+		/sbin/getty -L 115200 /dev/ttyGS0 vt100 &
 	fi
 	exit 0
 	EOF
@@ -122,9 +125,10 @@ fi
 # Define sshd-session & al files new location into sshd_config
 for f in /tmp/.trash/ssh/sshd-*; do
 	[ -e "$f" ] || continue # protect failing glob
-	name=$(echo $(basename $f) | cut -c6-)
-	initial=$(echo $name | cut -c1 | tr [a-z] [A-Z])
-	final=$(echo $name | cut -c2-)
+	name=$(basename "$f" | cut -c6-)
+	# shellcheck disable=SC2018,SC2019
+	initial=$(echo "$name" | cut -c1 | tr 'a-z' 'A-Z')
+	final=$(echo "$name" | cut -c2-)
 	echo "Sshd${initial}${final}Path $f" >>/etc/ssh/sshd_config
 done
 
@@ -262,7 +266,7 @@ if ! install -m644 "${ovlpath}"/interfaces /etc/network/interfaces >/dev/null 2>
 				# According to below we could rely on DEVTYPE for wlan devices
 				# https://lists.freedesktop.org/archives/systemd-devel/2014-January/015999.html
 				# but...some wlan might still be ill-behaved: use wlan_lst
-				# shellcheck disable=SC2169  # ash does support string replacement.
+				# shellcheck disable=SC3060  # ash does support string replacement.
 				_has_wifi && ! [ "${wlan_lst/$INTERFACE/}" = "$wlan_lst" ] && \
 					cat <<-EOF >>/etc/network/interfaces
 						auto $INTERFACE
@@ -271,7 +275,7 @@ if ! install -m644 "${ovlpath}"/interfaces /etc/network/interfaces >/dev/null 2>
 						EOF
 				# Ensure considered gadget interface is actually the connected one (may have several).
 				[ "$DEVTYPE" = "gadget" ] && \
-					find /sys/class/udc/*/device/gadget."${gdgt_id}"/net/"$INTERFACE" -maxdepth 0 >/dev/null 2>&1 && \
+					grep -vwq "0" /sys/class/net/"$INTERFACE"/carrier_up_count && \
 							cat <<-EOF >>/etc/network/interfaces && cat <<-EOF >/etc/resolv.conf
 								auto $INTERFACE
 								iface $INTERFACE inet static
@@ -310,37 +314,7 @@ hostname -F /etc/hostname
 rc-service networking restart
 }
 
-_setup_gadget() {
-## Load composite USB Serial/USB Ethernel driver & setup terminal.
-_logger "Enabling USB-gadget Serial and Ethernet ports"
-# Remove conflicting modules in case they were initially loaded (cmdline.txt).
-modprobe -r g_serial g_ether g_cdc
-modprobe g_cdc
-# Wait for g_cdc to settle and serial ports become available
-timeout 1 sh <<-EOF
-	while ! grep -q "ttyGS" /proc/devices; do sleep 0.2; done
-	EOF
 
-# Determine which gadget ID is connected with USB cable (assume just one max).
-# (setting console to unconnected serial port would block boot)
-gdgt_id="$( find /sys/class/udc/*/current_speed -exec \
-	sh -c 'grep -vq "UNKNOWN" "$0" && find ${0/current_speed/}device/gadget.* -maxdepth 0' {} \; \
-		| sed 's/\/.*gadget\.//' )"
-if [ -c /dev/ttyGS"${gdgt_id}" ]; then
-	# Default serial config: xon/xoff flow control.
-	stty -F /dev/ttyGS"${gdgt_id}"
-	setconsole /dev/ttyGS"${gdgt_id}"
-	# Notes to users willing to connect from Linux Ubuntu-based host terminal:
-	# - user on host needs to be part of dialout group (reboot required), and
-	# - disable spurious AT commands from ModemManager on host-side Gadget serial port
-	# one may create a /etc/udev/rules.d/99-ttyacms-gadget.rules as per:
-	# https://linux-tips.com/t/prevent-modem-manager-to-capture-usb-serial-devices/284/2
-	# ATTRS{idVendor}=="0525" ATTRS{idProduct}=="a4aa", ENV{ID_MM_DEVICE_IGNORE}="1"
-else
-	_logger "USB-gadget port not connected !"
-	modprobe -r g_cdc
-fi
-}
 
 
 #############################################################################
@@ -353,13 +327,6 @@ _logger "Alpine Linux headless bootstrap v$HDLSBSTRP_VERSION by macmpi"
 # Help randomness for wpa_supplicant and sshd (urandom until 3.16).
 rc-service seedrng restart || rc-service urandom restart
 
-# Setup USB gadget ports if some ports are enabled in peripheral mode.
-# Note: we assume dwc2/dwc3 is pre-loaded, we just check mode.
-gdgt_id=""
-find /sys/class/udc/*/is_a_peripheral -print0 2>/dev/null | \
-	xargs -0 cat 2>/dev/null | grep -q "0" && \
-		_setup_gadget
-
 # Determine ovl file location.
 # Grab used ovl filename from dmesg.
 ovl="$( dmesg | grep -o 'Loading user settings from .*:' | awk '{print $5}' | sed 's/:.*$//' )"
@@ -372,6 +339,22 @@ else
 	ovl="${ovlpath}/${ovl}"
 fi
 
+## Setup USB gadget ports if any connected
+/usr/local/bin/xg_multi -V "$( df | grep "$ovlpath" | awk '{print $1}' )" >/dev/null 2>&1
+# Setting console to connected serial port when available
+if [ -c /dev/ttyGS0 ]; then
+	# Default serial config: xon/xoff flow control.
+	stty -F /dev/ttyGS0
+	setconsole /dev/ttyGS0
+	# Notes to users willing to connect from Linux Ubuntu-based host terminal:
+	# - user on host needs to be part of dialout group (reboot required), and
+	# - disable spurious AT commands from ModemManager on host-side gadget serial port
+	# one may create a /etc/udev/rules.d/99-ttyacms-gadget.rules as per:
+	# https://linux-tips.com/t/prevent-modem-manager-to-capture-usb-serial-devices/284/2
+	# ATTRS{idVendor}=="1d6b" ATTRS{idProduct}=="0104", ENV{ID_MM_DEVICE_IGNORE}="1"
+fi
+
+
 # Create banner file.
 warn=""
 grep -q "${ovlpath}.*[[:space:]]ro[[:space:],]" /proc/mounts; is_ro=$?
@@ -381,7 +364,7 @@ _is_ro && warn="(remount partition rw!)"
 cat <<-EOF >/tmp/.trash/banner
 
 	Alpine Linux headless bootstrap v$HDLSBSTRP_VERSION by macmpi
-	
+
 	You may want to delete/rename .apkovl file before reboot ${warn}:
 	${ovl}
 	(can be done automatically with unattended script - see sample snippet)
diff --git a/sample_auto-updt b/sample_auto-updt
@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 # Automated reboot after update is cancelled if:
diff --git a/sample_interfaces b/sample_interfaces
@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 # Sample network interfaces file
diff --git a/sample_unattended.sh b/sample_unattended.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 ## collection of few code snippets as sample unnatteded actions some may find usefull
diff --git a/sample_wpa_supplicant.conf b/sample_wpa_supplicant.conf
@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright 2022-2023, macmpi
+# SPDX-FileCopyrightText: Copyright 2022-2025, macmpi
 # SPDX-License-Identifier: MIT
 
 # Sample wpa_supplicant.conf
diff --git a/xg_multi b/xg_multi
@@ -0,0 +1 @@
+Subproject commit 13a734f18c1592f71710185f4ec55fe6c6dbaa62

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-fecc6b66f1b08a959c6509334b5c1942b8df76ba6b7d51c54630f0c502706650b9d345bab71cd3d787681113eb5c1a40b2f6bc238ca6e4137fd00de8a6bc8a17 headless.apkovl.tar.gz`
	`1`	`+7d72e7a46066aebb0572f1431d6e9f354b3d0df4fce0a05090c1667f68738e876c195460d294a0c279c86d02b65d101625ed9c86a1f465c2f2f29ee59bdde5fa headless.apkovl.tar.gz`