Installer implemented in the live CD! However we still need to add some old realtek network card support for r1
This commit is contained in:
parent
0d300964f3
commit
1d86d4f1f9
4 changed files with 497 additions and 4 deletions
265
board/mentalnet/INSTALL-GUIDE.md
Normal file
265
board/mentalnet/INSTALL-GUIDE.md
Normal file
|
|
@ -0,0 +1,265 @@
|
|||
# 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, 3Com 3c59x |
|
||||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|---------|--------------------|
|
||||
| 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: use `-nic model=ne2k_pci` or the default e1000. |
|
||||
|
||||
---
|
||||
|
||||
## 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`) |
|
||||
| `localversion.config` | kernel version suffix (`-mentalnet-intel32`) |
|
||||
| `.config` | Buildroot configuration: GRUB2 embedded config path and module list, kernel fragment list, e2fsprogs/grub install tools |
|
||||
Loading…
Add table
Add a link
Reference in a new issue