Skip to content

Running MentOS

Jump to bottom
Enrico Fraccaroli (Galfurian) edited this page Jan 29, 2026 · 5 revisions

Learn how to boot and interact with MentOS.

Quick Start (QEMU)

The simplest way to run MentOS:

cd build
make filesystem
make qemu

This launches QEMU with the bootloader.bin and filesystem.

Login

When MentOS boots, you'll be prompted for credentials.

Use one of the usernames from filesystem/etc/passwd:

  • root - Root user (full privileges)
  • user - Regular user

Passwords are enforced and stored as SHA-256 hashes in filesystem/etc/shadow. If you need to change credentials, edit the shadow file before rebuilding rootfs.img.

Shell Commands

Once logged in, you can use the MentOS shell:

ls              # List directory
cd /home/user   # Change directory
cat file.txt    # Display file contents
ps              # List processes
pwd             # Print working directory

For a full list of available commands, see Userspace Programs.

Running Methods

Method 1: Direct QEMU Boot (Recommended)

make qemu

Boots: Directly loads bootloader.bin
Fastest: Immediate boot, no GRUB delay
Use for: Development and testing

Method 2: GRUB Boot

make qemu-grub

Boots: Creates ISO image, boots via GRUB bootloader
Realistic: Mimics real hardware boot process
Use for: Testing GRUB compatibility, more realistic environment

Method 3: Testing Mode

make qemu-test

Boots: Runs runtests as init process instead of shell
Purpose: Runs all test programs automatically
Use for: Automated testing, CI/CD

Note: qemu-test runs QEMU in -nographic mode and writes serial output to build/test.log.

QEMU Options

Custom Memory Size

Edit the root CMakeLists (EMULATOR_FLAGS) or run QEMU manually:

qemu-system-i386 -m 256M -kernel build/mentos/bootloader.bin -drive file=build/rootfs.img,format=raw,if=ide,index=0,media=disk

Serial Output

Serial output is routed based on EMULATOR_OUTPUT_TYPE:

  • OUTPUT_STDIO (default): output appears directly in the terminal running make qemu.
  • OUTPUT_LOG: output is written to build/serial.log.

Exit QEMU

  • Press Ctrl+Alt+G to release mouse
  • Close QEMU window, or
  • Press Ctrl+C in the terminal running make qemu

GRUB Boot (Detailed)

Prerequisites

Install GRUB tools:

sudo apt-get install -y grub-common grub-pc-bin xorriso

Build and Boot

make qemu-grub

This:

  1. Builds bootloader.bin
  2. Creates iso/boot/grub/grub.cfg
  3. Generates cdrom.iso with GRUB
  4. Boots QEMU from ISO

GRUB Configuration

The GRUB config is in iso/boot/grub/grub.cfg:

menuentry "MentOS" {
    multiboot /boot/bootloader.bin
}

Running Programs

Once booted, run userspace programs:

# System info
uname
uptime
cpuid

# File operations
ls
cat /etc/passwd
mkdir mydir
touch myfile.txt

# Process management
ps
kill <pid>

# Testing
/bin/tests/t_fork
/bin/tests/t_mem

Running on Real Hardware

Warning: MentOS is experimental. Use only on dedicated hardware or VMs.

Create Bootable USB

  1. Build the ISO:

    make qemu-grub  # Generates cdrom.iso

  2. Write to USB:

    sudo dd if=build/cdrom.iso of=/dev/sdX bs=4M status=progress

    Replace /dev/sdX with your USB device (check with lsblk).

  3. Boot from USB on target machine

Boot from Existing GRUB

Copy bootloader.bin to /boot:

sudo cp build/mentos/bootloader.bin /boot/

Add to /etc/grub.d/40_custom:

menuentry "MentOS" {
    multiboot /boot/bootloader.bin
}

Update GRUB:

sudo update-grub

Reboot and select "MentOS" from GRUB menu.

Debugging While Running

Enable Debug Output

Kernel debug messages go to the serial console and follow the same EMULATOR_OUTPUT_TYPE routing described above.

Kernel Log Levels

See Debugging#Kernel Logging for controlling verbosity.

GDB Debugging

For interactive debugging:

make qemu-gdb

See Debugging for details.

Automated Testing

Run the test suite:

make qemu-test

This boots MentOS with runtests as the init process, which:

  1. Executes all tests in /bin/tests/
  2. Reports pass/fail results
  3. Exits when complete

Shutdown

To properly shut down MentOS:

poweroff

Or simply close the QEMU window.

Troubleshooting

"Kernel panic" on Boot

  • Check if make filesystem was run
  • Verify rootfs.img exists in build/
  • Try a clean rebuild: make clean && make && make filesystem

No Login Prompt

  • Check serial output for kernel errors
  • Try make qemu-gdb and debug boot process

Keyboard Not Working

  • Ensure QEMU window has focus
  • Check keyboard layout setting (KEYMAP_TYPE in CMake)

Screen Artifacts/Corruption

  • Video driver issue, reboot usually fixes it
  • Try different QEMU version

Programs Not Found

  • Run make filesystem after compiling programs
  • Check /bin directory contents: ls /bin

Performance

Slow Boot

  • This is normal for GRUB boot
  • Use make qemu for faster direct boot

Slow File Operations

  • EXT2 filesystem on emulated hardware is slow
  • This is expected behavior

Next Steps

Previous: Building MentOS | Next: Development Guide →

Clone this wiki locally