MENTALNET-INSTALL(1)

Install & Test Guide — Mentalnet GNU/Linux R1 "FirstStorm" · Buildroot 2025.02.17 · kernel 6.12.104-mentalnet-intel32 · login root / mnlinux · hostname mentalnet

NAME

mentalnet-install — install Mentalnet GNU/Linux from the live CD to a hard disk. The ISO is a live CD: the entire system runs from the CD with a read-only root filesystem, and the same CD carries the built-in hard disk installer.

SYSTEM REQUIREMENTS

Running the live CD

Component	Requirement
CPU	i586 (Pentium / Pentium MMX) or any newer x86; `uname -m` reports at least `i586` or newer
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	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+ (incl. QEMU/Proxmox emulation), 3Com 3c59x, virtio-net

Installing to a hard disk

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

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 and the /var subdirs are tmpfs). 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.

Default kernel command line

i8042.nomux i8042.noloop noapic acpi=off i8042.dumbkbd=1

Option	Purpose
`i8042.nomux` / `i8042.noloop`	skip the i8042 controller probe steps most known to confuse old or emulated keyboard controllers
`noapic`	use the legacy 8259 PIC instead of the IO-APIC — avoids IRQ routing/storm issues on era boards, which mostly predate the IO-APIC anyway
`acpi=off`	era BIOSes (1994–1997) have broken or absent ACPI; skipping it avoids the table-parsing minefield. Power management is disabled (era-appropriate)
`i8042.dumbkbd=1`	do not program keyboard LEDs or expect controller ACKs — conservative mode for flaky 8042 clones (Caps Lock light will not toggle)

To troubleshoot a specific machine, edit the boot entry at the GRUB menu with the e key, change the linux line, and boot with Ctrl-X or F10.

INSTALLATION

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

Boot & log in

Boot the machine from the CD (El Torito boot). Expect the GRUB menu ("Mentalnet GNU/Linux", 10 s timeout) and a kernel boot to a login prompt on the VGA console.
Log in as root (password mnlinux).
Run: mentalnet-install

Installer prompts

Disk to install to (e.g. sda): sda
Type YES to continue: YES
Proceed with installation? [y/N]: y

Disk to install to — e.g. sda (the installer lists detected disks with their sizes first)
Type YES — destroys everything on that disk
the new partition table is then shown — sanity-check the disk size before continuing
Proceed? [y/N] — final confirmation before anything is written to the disk

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
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!, run poweroff, remove the CD and power on — the machine now boots from its own disk. The installed GRUB menu has a 5 s timeout and boots automatically.

POST-INSTALL

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, and logs persist under /var/log. 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. DHCP DNS works the same way (resolv.conf symlink into tmpfs).

Security after install

The default root password is mnlinux — change it after installing (passwd). Then, for day-to-day use, create a regular user and give it sudo privileges (sudo is included in the build):

user@mentalnet:~$ adduser myuser

add the user to the sudo group, which the shipped sudoers file already trusts: addgroup myuser sudo; or
enable the classic wheel group with visudo (uncomment the %wheel line) and add the user to it.

Verify that sudo works for the new user before locking root — log in as the user and run, for example, sudo ls /. Once sudo is confirmed working, lock the root account:

user@mentalnet:~$ passwd -l root

TESTING IN QEMU

# live CD, graphical window
qemu-system-i386 -m 128 -cdrom output/images/rootfs.iso9660

# headless (serial console); exit with Ctrl-A x
qemu-system-i386 -m 128 -nographic \
  -kernel output/images/bzImage \
  -append "console=ttyS0 root=/dev/sr0 ro" \
  -cdrom output/images/rootfs.iso9660

# low-memory margin test: same but with -m 64

# NE2000 network test (after login, `ip link` should show eth0 up)
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

Full installer end-to-end test:

qemu-img create -f qcow2 /tmp/mn-test.qcow2 512M
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, run mentalnet-install, then poweroff and boot only the disk:
qemu-system-i386 -m 128 -nographic \
  -drive file=/tmp/mn-test.qcow2,format=qcow2,if=ide

The serial console should show EXT4-fs (sda1): mounted ... r/w and Run /sbin/init as init process.

BUILDING FROM SOURCE

The repository is not a full Buildroot tree — it is an overlay meant to be applied on top of a pristine Buildroot 2025.02.17 checkout:

wget https://buildroot.org/downloads/buildroot-2025.02.17.tar.gz
tar xf buildroot-2025.02.17.tar.gz
cd buildroot-2025.02.17
# copy from the Mentalnet repo onto the tree:
#   board/mentalnet/            -> board/mentalnet/
#   fs/iso9660/grub.cfg         -> fs/iso9660/grub.cfg (overwrites upstream)
#   .config                     -> .config
make

Outputs land in output/images/: rootfs.iso9660 (the bootable live CD / installer ISO), bzImage (the kernel), rootfs.ext2 (a 2 GB raw disk image variant for QEMU testing) and GRUB core images. A full build takes a while; rebuilds after config changes are much faster.

TROUBLESHOOTING

Symptom	Fix
Boots on Pentium Pro/i686 but hangs at kernel start on Pentium/Pentium MMX (i586)	Fixed: the kernel is built for `CONFIG_M586` with `CONFIG_X86_GENERIC` (no CMOV). Older builds used the i686 default and crash with an invalid opcode on real i586 CPUs.
Terminal garbled / typed text repeats after a full-screen app (htop, neofetch)	Fixed: earlier builds set `TERM=vt100` on the VGA console. If it persists, the CPU may simply be too slow to keep up with the OS.
Phantom keystrokes / junk commands during or after the install	Interrupt storms from APIC/ACPI quirks starving the keyboard controller. Fixed builds ship `noapic acpi=off i8042.dumbkbd=1` on both boot paths plus per-directory progress with an input drain. On older builds: let it finish, run `reset`, avoid typing during the copy.
Booting the CD runs an older install instead of the live system	Fixed: the live CD's GRUB core hardcodes `root=(cd)`, so the chain never touches any attached disk.
GRUB menu does not appear 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 — 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.
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 1 GiB is needed.
Forgot the password	It is `mnlinux`.
No network	Check the NIC against the supported list. QEMU/Proxmox: `rtl8139`, `virtio-net-pci`, `ne2k_pci` or the default e1000 all work.
Proxmox: VM boots an older build despite uploading a new ISO	Proxmox stores each upload as a separate volume; a VM's CD/DVD drive points at a specific volume. Delete the stale volume, upload the unique-named ISO and re-attach it in Hardware; check Boot Order.

How to tell which build a VM is running: the login prompt prints the build stamp, or check BUILD_ID= in /etc/os-release or cat /proc/version inside the guest.