280 lines
11 KiB
Markdown
280 lines
11 KiB
Markdown
# 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
|
|
```
|
|
|
|
Log in and run `mentalnet-install`:
|
|
|
|
```
|
|
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.
|
|
|
|
1. Boot the machine from the CD (El Torito boot).
|
|
2. Log in as `root` (password `mnlinux`).
|
|
3. Run:
|
|
|
|
```
|
|
mentalnet-install
|
|
```
|
|
|
|
4. 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
|
|
|
|
5. 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
|
|
|
|
6. 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 |
|