Open Small Linux

Mini-handbook

A short reference for Open Small Linux 0.8: how to try it, install it, and live with it. Everything below is exactly what the system ships today.

1. Requirements

The live system runs entirely from RAM (the initramfs is ~300 MB), so do not try it on a machine with 256 MB of memory.

2. Live mode

Write the ISO to a USB stick and boot from it:

dd if=osl-v0_8.iso of=/dev/sdX bs=4M status=progress
sync

Welcome to Open Small Linux 0.8
osl login: root          # <- no password

The live system is read-only in spirit: everything you change lives in RAM and disappears on reboot. To keep anything, install to a disk.

3. Installation

The installer does not partition the disk for you: split it yourself first, then let osl-install do the rest (format, copy, boot code).

cfdisk /dev/vda             # 1) DOS/MBR layout for BIOS
                            #    or: cfdisk --label gpt /dev/vda for UEFI
osl-install                 # 2) run the installer as root

What the installer asks:

Then it runs, without asking anything else:

1. mke2fs -F on the chosen partition;
2. copies the whole system (cp -a of bin sbin lib etc usr boot ...);
3. writes /etc/fstab (and /boot/efi entry in UEFI mode);
4. generates /boot/grub/grub.cfg with the right root=/dev/... and set root='hd0,msdos1' / 'hd0,gptN';
5. installs the boot code by hand:
   • BIOS: first 440 bytes of boot.img into the MBR (partition table untouched!) and core.img into the gap at sector 1;
   • UEFI: formats the ESP as FAT32 and copies EFI/BOOT/BOOTX64.EFI.

Requirement: the first partition must start at sector 2048 (1 MiB alignment) so that core.img fits into the MBR gap. The installer checks this and refuses to proceed otherwise.

Reboot, remove the USB stick, done.

4. First steps after installation

osl-sysinfo            # does everything look right?
osl-net status         # interfaces, addresses, default route
osl-net ping 1.1.1.1   # connectivity check
passwd                 # SET a root password, the default is empty!

5. Built-in tools

6. Packages (opkg)

opkg is included in every image. Honest note for 0.8: no package feed is configured yet — there is no /etc/opkg.conf and no package database, so opkg update will fail until the official repository launches. Installing a package from a local file works:

opkg install ./some-package.ipk

After the official repository appears, the usual workflow will be:

opkg update
opkg search <keyword>
opkg install <package>
opkg remove  <package>
opkg list-installed

See also the Repository page.

7. Boot & GRUB

There is no grub-install and no grub-mkconfig in OSL. The installer writes everything itself, which means the bootloader is fully manual — and fully predictable:

An example menu entry:

set default="0"
set timeout="3"

menuentry "Open Small Linux" {
    insmod ext2
    set root='hd0,msdos1'
    linux /boot/bzImage root=/dev/vda1 rw console=tty1
}

Notes:

• GRUB modules are not stored on the disk; everything needed (normal, ext2, linux, search...) is embedded into core.img. So insmod ext2 in the menu works, but insmod of anything else will fail with "file not found" unless you copy the modules to /boot/grub/i386-pc/ yourself.
• Both boot images contain a small early config that runs search --file /boot/grub/grub.cfg, so GRUB finds the menu on any partition, no matter how it is numbered.
• The default root password is empty. Set one with passwd right after installation.

8. Troubleshooting

This handbook describes Open Small Linux 0.8. Foundry programs are not yet part of the image.