SolarLinux Handbook (x86)


About Solar

Solar is a lightweight and flexible source-based Linux distribution. This is a guide to installing and configuring Solar.

The default configuration of Solar uses busybox, musl, runit, and gcc, but each part is interchangable (apart from, in some ways, gcc).

Installing Solar


Download the latest Solar image and write it to a flash drive (or burn it to a disk).

# curl -L https://SITE/solar/x86-64/solar.img | dd of=/dev/XXX

Boot from the device and login as root.

Create a partition to install Solar onto, create a filesystem on it, and mount it at /mnt. If you want to use any other partitions, create and mount them now as well. A swap partition is recommended, as is a seperate /boot (with a filesystem such as EXT2).

# fdisk /dev/XXX
# mkfs.XXXXX /dev/XXXX
# mount /dev/XXXX /mnt


Create the base filesystem hierarchy on your new partition.

# solar-rootfs /mnt

Download and extract a config bundle, which contains some basic configuration files for your system. Several bundles are available, and you should choose whichever suits your taste. The 'default' bundle is a good place to start, but if you have very particular tastes then an alternative bundle may suit you better. A full list with descriptions can be found here.

# cd /mnt
# curl https://SITE/solar/cfg/default.cpio | cpio -ov

If you intend to use a non-default base package collection, edit /etc/cs.conf to your liking. For changes like adding xorg later, you can leave it as is.


Download the package tree into /mnt/pkg, install your base set of packages (that will be used to compile the rest of the system), then chroot into the new system.

# cs -o /mnt/pkg
# pkg ir /mnt meta-sys busybox pkg make awk bison
# solar-chroot /mnt

Once chrooted, redownload the package tree to get a clean copy (remove patches needed only for cross-compiling).

chroot# cs -w
chroot# cs

Either install 'meta-base' to provide the rest of the default userland, or install your own custom set of packages; if you want to roll your own, you can view meta-base's dependencies with pkg qpd meta-base to get an idea of where to start.

chroot# pkg i meta-base

Some users may want to relink programs installed before the chroot in their new system; the live system will produce binaries statically-linked against musl, but the chroot (by default) will not. To do this, run the following:

chroot# pkg rd <packages>
chroot# pkg ib <packages>
chroot# pkg i <packages>


Set a password for root.

chroot# passwd

Edit /etc/fstab to configure filesystems.

chroot# vi /etc/fstab


Configure and build the kernel, then install it and its modules.

chroot# cd /src/linux-XXXXX
chroot# make menuconfig
chroot# make
chroot# make modules_install
chroot# cp arch/x86/boot/bzImage /boot/kernel


This section assumes you are using EXTLINUX (a SYSLINUX variant supporting Linux filesystems) as your bootloader, instructions will differ if not

In order to work with EXTLINUX, /boot must be on a partition formatted as FAT*, NTFS, ext*, btrfs, XFS, or UFS+FFS. The boot partition should have the active flag set (command 'a' in fdisk).

Write boot code to MBR and install EXTLINUX.

chroot# dd if=/share/syslinux/mbr.bin of=/dev/XXX
chroot# mkdir /boot/extlinux
chroot# extlinux -i /boot/extlinux

Configure EXTLINUX in /boot/extlinux/extlinux.conf. An example configuration follows, see here for full information.


LABEL solar
    LINUX /kernel
    APPEND root=/dev/sda2 ro quiet


Solar is now fully installed! Exit the chroot, unmount, reboot, and enjoy!

chroot# exit
# solar-chroot -u /mnt
# umount /mnt
# reboot