markmental f2e7864a00 Add build tagging and rtl8139 network card kernel drivers

2026-09-10 21:51:07 -04:00

11 KiB

Raw Blame History

Mentalnet GNU/Linux — Install & Test Guide

Mentalnet GNU/Linux is a small, TTY-only distribution for 90s Intel Pentium-class PCs, built with Buildroot 2025.02.17. The ISO is a live CD: the entire system runs from the CD with a read-only root, and the same CD carries a built-in hard disk installer (mentalnet-install).

Kernel: 6.12.104-mentalnet-intel32 (slimmed i386 config)
Login: root / mnlinux
Hostname: mentalnet
Live CD size: ~100 MB

1. System requirements

Running the live CD

Component	Requirement
CPU	i586 (generic Pentium) or any newer x86
RAM	128 MB minimum (64 MB usually works)
CD drive	IDE/ATAPI CD-ROM (PIIX-era ATA controller)
Display	VGA text console, PS/2 keyboard/mouse
USB	USB keyboards, mice and mass storage (UHCI/OHCI/EHCI)
Serial	8250 UART (kernel log is mirrored to COM1)
NICs (opt.)	NE2000-PCI clones (RTL8029 etc.), Intel e100/e1000/e1000e, Realtek 8139 / 8139C+ (rtl8139, incl. QEMU/Proxmox emulation), 3Com 3c59x, virtio-net (virtualized environments)

Installing to a hard disk

IDE/ATA disk with at least 400 MB free (the whole disk is wiped)
The machine must be able to boot from CD (El Torito, BIOS boot)

2. What's on the media

The live system mounts its root filesystem read-only from the CD. Everything writable lives in RAM:

/tmp, /run, /dev/shm are tmpfs
/var/log, /var/run, /var/cache, /var/spool, /var/tmp are symlinks into those tmpfs areas

Services started at boot:

Service	Purpose
DHCP	`eth0` configured via udhcpc
syslogd	kernel + system logging (to `/tmp/log`)
lighttpd	web server, port 80
dropbear	SSH server, port 22
chronyd	NTP time sync
crond	cron daemon
iptables	firewall rules

DNS from DHCP works on the live CD too: /etc/resolv.conf is a symlink into tmpfs that udhcpc writes through.

3. Building from source

The build tree is a standard Buildroot 2025.02.17 checkout with the Mentalnet configuration applied. Install the usual Buildroot host dependencies (see docs/manual/prerequisite.txt in the Buildroot manual), then:

make

Build outputs land in output/images/:

File	Purpose
`rootfs.iso9660`	the bootable live CD / installer ISO
`bzImage`	the kernel (also inside the ISO and ext2 image)
`rootfs.ext2`	2 GB raw disk image variant (for QEMU testing)
`grub-eltorito.img` / `grub.img`	GRUB core images (used by the ISO)

A full build takes a while; rebuilds after config changes are much faster. After editing kernel fragments or the overlay, plain make picks the changes up.

Every build also publishes the ISO under a unique name and prints its SHA256 at the end of the build log:

Published: .../output/images/mentalnet-gnulinux-intel32-20260910-212811.iso
0dcfbcb0...c308c69  output/images/mentalnet-gnulinux-intel32-20260910-212811.iso

Upload that file to hypervisors — see the Proxmox pitfall in the troubleshooting section before attaching it to an existing VM.

4. Testing in QEMU

All commands are run from the Buildroot tree root. Exit a -nographic session with Ctrl-A x.

4.1 Live CD, graphical window

qemu-system-i386 -m 128 -cdrom output/images/rootfs.iso9660

Expect the GRUB menu ("Mentalnet GNU/Linux", 10s timeout), a kernel boot and a login prompt on the VGA console.

4.2 Headless (serial console)

qemu-system-i386 -m 128 -nographic \
  -kernel output/images/bzImage \
  -append "console=ttyS0 root=/dev/sr0 ro" \
  -cdrom output/images/rootfs.iso9660

This bypasses GRUB and shows the whole boot on the terminal.

4.3 Low-memory margin test

Same as 4.2 but with -m 64. The live system should still come up.

4.4 NE2000 network test

qemu-system-i386 -m 128 -nographic -nic model=ne2k_pci \
  -kernel output/images/bzImage \
  -append "console=ttyS0 root=/dev/sr0 ro" \
  -cdrom output/images/rootfs.iso9660

After login, ip link should show a configured eth0.

4.5 Disk image variant

qemu-system-i386 -m 128 -nographic \
  -kernel output/images/bzImage \
  -append "console=ttyS0 root=/dev/sda1 rootwait rw" \
  -drive file=output/images/rootfs.ext2,format=raw,if=ide

(rootfs.ext2 also contains /boot/bzImage and a GRUB config for disk boot.)

4.6 Full installer end-to-end test

# 1. create a throwaway disk
qemu-img create -f qcow2 /tmp/mn-test.qcow2 512M

# 2. boot the live CD with the test disk attached
qemu-system-i386 -m 128 -nographic \
  -kernel output/images/bzImage \
  -append "console=ttyS0 root=/dev/sr0 ro" \
  -cdrom output/images/rootfs.iso9660 \
  -drive file=/tmp/mn-test.qcow2,format=qcow2,if=ide

Disk to install to (e.g. sda): sda
Type YES to continue: YES
Create a swap partition? [y/N]: y

When it prints Installation complete!:

poweroff

Then boot only the test disk (no -cdrom, no -kernel) — this exercises the installed GRUB in the MBR:

qemu-system-i386 -m 128 -nographic \
  -drive file=/tmp/mn-test.qcow2,format=qcow2,if=ide

The kernel log (mirrored to the serial console by the installed config) should show EXT4-fs (sda1): mounted ... r/w and Run /sbin/init as init process.

5. Installing to a hard disk (real hardware)

WARNING: the installer destroys ALL data on the target disk without further notice. Double-check the disk name before confirming.

Boot the machine from the CD (El Torito boot).
Log in as root (password mnlinux).
Run:
```
mentalnet-install
```
Answer the prompts:
- Disk to install to — e.g. sda (the installer lists detected disks with their sizes first)
- Type YES — destroys everything on that disk
- Create a swap partition? [y/N] — recommended on machines with little RAM; the swap is sized at 2x RAM, capped at 512 MB
The installer then:
- writes a fresh MBR partition table (root partition starts at sector 2048, leaving room for the GRUB core image)
- creates an ext4 filesystem labelled rootfs (+ swap if chosen)
- copies the whole system from the CD
- generates /etc/fstab
- installs GRUB to the MBR and writes the boot menu
When it prints Installation complete!:
```
poweroff
```
Remove the CD and power on — the machine now boots from its own disk.

The installed GRUB menu has a 5s timeout and boots automatically.

6. Post-install notes

The installed root filesystem is read-write, so all services behave normally: chrony keeps its drift file, dropbear generates SSH host keys on first boot, logs persist under /var/log.
DHCP DNS works the same way as on the live CD (resolv.conf symlink into tmpfs).
Kernel boot messages are mirrored to COM1 (ttyS0) — handy for debugging headless or semi-broken machines.
Login is root / mnlinux (same as the live system).

7. Troubleshooting

Symptom	Likely cause / fix
How to tell which build a VM is actually running	At the login prompt the build stamp is printed (`Mentalnet GNU/Linux build YYYYMMDD-HHMMSS`); inside the guest check `cat /etc/os-release` (`BUILD_ID=`) or `cat /proc/version`. Useful kernel build markers: `#3 ... 18:45:02` predates the rtl8139 fix, `#4 ... 20:24:17` is the first build with 8139cp.
Proxmox: VM boots an older build despite uploading a new ISO	Proxmox keeps every upload as a separate storage volume, and a VM's CD/DVD drive points at a specific volume — renaming or re-uploading a file never updates an existing drive (checksums of the new file do not help either). Delete the stale volume, upload the unique-named ISO from the build log, attach it in Hardware, and check Boot Order (an installed disk can also shadow the CD).
GRUB menu does not appear, or the machine reboots before booting, in QEMU	Try more RAM (`-m 256`). Memory pressure during development was the culprit more than once.
Kernel panic: `Unable to mount root fs`	The CD drive is on an unsupported controller. The kernel targets PIIX-era IDE/ATA; modern SATA-only setups are out of scope.
`Remounting root filesystem read-write ... failed` on live boot	Cosmetic. The CD root is read-only by design; all writes go to tmpfs.
Installer: `/dev/sdX1 did not appear after partitioning`	The kernel was still re-reading the partition table. Simply run the installer again.
Installer: `disk is too small`	At least 400 MB is needed.
Forgot the password	It is `mnlinux` (set at build time in the Buildroot config).
No network	Check the NIC against the supported list in section 1. QEMU/Proxmox: `rtl8139`, `virtio-net-pci`, `ne2k_pci` or the default e1000 all work.

8. Maintainer file map

Everything Mentalnet-specific lives here:

File	Purpose
`board/mentalnet/grub-embedded.cfg`	config embedded into the GRUB core image: searches for the medium containing `/boot/bzImage` instead of hardcoding a device
`board/mentalnet/linux-slim.config`	kernel config fragment: keeps the classic PCI NICs, ATA/ATAPI, USB HID/storage, serial and VGA console; drops wireless, sound, DRM, RAID, PCMCIA, debug
`board/mentalnet/overlay/usr/sbin/mentalnet-install`	the hard disk installer
`board/mentalnet/overlay/usr/share/mentalnet/grub-disk.cfg`	boot menu template written to installed systems (`@ROOTDEV@` is replaced)
`board/mentalnet/overlay/etc/resolv.conf`	symlink so DHCP DNS works on the read-only CD
`board/mentalnet/overlay/etc/lighttpd/`	web server configuration
`fs/iso9660/grub.cfg`	live CD boot menu (`root=/dev/sr0 ro`)
`board/mentalnet/post-build.sh`	stamps `BUILD_ID` into os-release and the login banner (wired via `BR2_ROOTFS_POST_BUILD_SCRIPT`)
`board/mentalnet/post-image.sh`	publishes the ISO under a unique dated name + SHA256 (wired via `BR2_ROOTFS_POST_IMAGE_SCRIPT`)
`localversion.config`	kernel version suffix (`-mentalnet-intel32`)
`.config`	Buildroot configuration: GRUB2 embedded config path and module list, kernel fragment list, e2fsprogs/grub install tools

11 KiB Raw Blame History