Installation Instructions

KO4OS uses a host Linux distribution or almost any distro’s LiveCD. Debian and Fedora are known to work, Ubuntu is a little weird with errors but does work.

This install page does not go into detail and makes a lot of assumptions, like that you are using English with a US keyboard. If you’re not, pay attention and adjust the scripts as needed.

Again, this is intended for people who are experienced with the Linux From Scratch book, Arch, and/or Gentoo. If you are not please check out the Linux From Scratch book, it’s excellent.

If any errors arise, check out the Wikis of the above projects and search help topics related to them.

---

Got it working? Or attempted? I’d love to hear about it.

ko4fzg@ko4fzg.com

---

System Requirements

TODO Requirements.

A modern system or LiveCD.

• PHP 8.1 or above with the following extensions:
  • pdo
  • pdo_sqlite
  • json
  • posix
  • pcre
• SQLite 3.x
• git
• bash
• tar
• wget
• curl
• Internet Connection

---

Creating Disks and Partitions

KO4OS installation makes a lot of assumptions, one of them is that you are using GPT tables for your partitions. If you plan on using MBR please adjust accordingly.

NOTE: KO4OS does not support Secure Boot of any kind. Please disable it.

First find the drive that you want to use, using these commands WILL clear the whole drive so please be sure to use the right one. I’m going to assume that you are using a host OS, in these instructions I am going to use /dev/sdb so please adjust accordingly.

lsblk

Will show a list of drives, carefully inspect to find the right one to use. Then:

fdisk /dev/sdb

p 

This will show the current partition table, if you do not plan on clearing the whole disk, do NOT do the following. If you are planning on it, which you should be, do:

Press g to create a new GPT table

-----------

Press n for new partition
Partition Number: 1
First Sector: enter
Last Sector: +1G

-----------

Press n for new partition
Partition Number: 2
First Sector: enter
Last Sector: +8G (Equal to system ram or whatever you want it to be).

-----------

Press n for new partition
Partition Number: 3
First Sector: enter
Last Sector: enter

This will create the three partitions that you need, 1 is the EFI partition, 2 is the Swap, and 3 is the root. Now we need to make them official and change which type they are.

Press t
Selected Partition 1
Partition type: 1

You should see: Changed type of partition 'Linux filesystem' to 'EFI System'.

-----------

Press t
Selected Partition 2
Partition type: 19

You should see: Changed type of partition 'Linux filesystem' to 'Linux swap'.

-----------

Press t
Selected Partition 3
Partition type: 23

You should see: Changed type of partition 'Linux filesystem' to 'Linux root (x86-64)'.

Now lets make it official:

Press p - Make sure it looks right.

Press w

exit

Now lets create the filesystems:

mkswap /dev/sdb2

/sbin/swapon -v /dev/sdb2

mkfs -v -t ext4 /dev/sdb3

mkfs.vfat /dev/sdb1

---

Mounting Partitions

Exporting the KO4OS is very important, please occasionally check with “echo $KO4OS” to make sure it is set, if it’s not its going to cause a whole lot of mess.

export KO4OS=/mnt/ko4os

umask 022

mkdir -pv $KO4OS

mount -v -t ext4 /dev/sdb3 $KO4OS

mount --mkdir -v -t vfat /dev/sdb1 -o codepage=437,iocharset=iso8859-1 /boot/efi

---

Create Directories and Initial Files

chown root:root $KO4OS

chmod 755 $KO4OS

mkdir -pv $KO4OS/{etc,var} $KO4OS/usr/{bin,lib,sbin}

for i in bin lib sbin; do
ln -sv usr/$i $KO4OS/$i
done

case $(uname -m) in
x86_64) mkdir -pv $KO4OS/lib64 ;;
esac

groupadd ko4os

useradd -s /bin/bash -g ko4os -m -k /dev/null ko4os

chown -v ko4os $KO4OS/{usr{,/*},var,etc}
case $(uname -m) in
x86_64) chown -v ko4os $KO4OS/lib64 ;;
esac

su - ko4os

cat > ~/.bash_profile << "EOF"
exec env -i HOME=$HOME TERM=$TERM PS1='\u:\w\$ ' /bin/bash
EOF

cat > ~/.bashrc << "EOF"
set +h
umask 022
KO4OS=/mnt/ko4os
LC_ALL=POSIX
KO4OS_TGT=$(uname -m)-ko4os-linux-gnu
PATH=/usr/bin
if [ ! -L /bin ]; then PATH=/bin:$PATH; fi
PATH=$KO4OS/tools/bin:$PATH
CONFIG_SITE=$KO4OS/usr/share/config.site
export KO4OS LC_ALL KO4OS_TGT PATH CONFIG_SITE
EOF

cat >> ~/.bashrc << "EOF"
export MAKEFLAGS=-j$(nproc)
EOF

source ~/.bash_profile

---

Installing Software 1

git clone https://github.com/KO4FZG/KO4
cd KO4
bash install.sh
ko4 repo add main https://repo.ko4os.com
ko4 sync
cd ..

TODO

---

Chroot

chown --from ko4os -R root:root $KO4OS/{usr,var,etc,tools}
case $(uname -m) in
x86_64) chown --from ko4os -R root:root $KO4OS/lib64 ;;
esac

mkdir -pv $KO4OS/{dev,proc,sys,run}

mount -v --bind /dev $KO4OS/dev
mount -vt devpts devpts -o gid=5,mode=0620 $KO4OS/dev/pts
mount -vt proc proc $KO4OS/proc
mount -vt sysfs sysfs $KO4OS/sys
mount -vt tmpfs tmpfs $KO4OS/run

if [ -h $KO4OS/dev/shm ]; then
install -v -d -m 1777 $KO4OS$(realpath /dev/shm)
else
mount -vt tmpfs -o nosuid,nodev tmpfs $KO4OS/dev/shm
fi

chroot "$KO4OS" /usr/bin/env -i \
HOME=/root \
TERM="$TERM" \
PS1='(ko4os chroot) \u:\w\$ ' \
PATH=/usr/bin:/usr/sbin \
MAKEFLAGS="-j$(nproc)" \
TESTSUITEFLAGS="-j$(nproc)" \
/bin/bash --login

---

Installing Software 2

First we need to create a few more folders and files:

mkdir -pv /{boot,home,mnt,opt,srv}

mkdir -pv /etc/{opt,sysconfig}
mkdir -pv /lib/firmware
mkdir -pv /media/{floppy,cdrom}
mkdir -pv /usr/{,local/}{include,src}
mkdir -pv /usr/lib/locale
mkdir -pv /usr/local/{bin,lib,sbin}
mkdir -pv /usr/{,local/}share/{color,dict,doc,info,locale,man}
mkdir -pv /usr/{,local/}share/{misc,terminfo,zoneinfo}
mkdir -pv /usr/{,local/}share/man/man{1..8}
mkdir -pv /var/{cache,local,log,mail,opt,spool}
mkdir -pv /var/lib/{color,misc,locate}
ln -sfv /run /var/run
ln -sfv /run/lock /var/lock
install -dv -m 0750 /root
install -dv -m 1777 /tmp /var/tmp


ln -sv /proc/self/mounts /etc/mtab


cat > /etc/hosts << EOF
127.0.0.1 localhost $(hostname)
::1 localhost
EOF


cat > /etc/passwd << "EOF"
root:x:0:0:root:/root:/bin/bash
bin:x:1:1:bin:/dev/null:/usr/bin/false
daemon:x:6:6:Daemon User:/dev/null:/usr/bin/false
messagebus:x:18:18:D-Bus Message Daemon User:/run/dbus:/usr/bin/false
systemd-journal-gateway:x:73:73:systemd Journal Gateway:/:/usr/bin/false
systemd-journal-remote:x:74:74:systemd Journal Remote:/:/usr/bin/false
systemd-journal-upload:x:75:75:systemd Journal Upload:/:/usr/bin/false
systemd-network:x:76:76:systemd Network Management:/:/usr/bin/false
systemd-resolve:x:77:77:systemd Resolver:/:/usr/bin/false
systemd-timesync:x:78:78:systemd Time Synchronization:/:/usr/bin/false
systemd-coredump:x:79:79:systemd Core Dumper:/:/usr/bin/false
uuidd:x:80:80:UUID Generation Daemon User:/dev/null:/usr/bin/false
systemd-oom:x:81:81:systemd Out Of Memory Daemon:/:/usr/bin/false
nobody:x:65534:65534:Unprivileged User:/dev/null:/usr/bin/false
EOF


cat > /etc/group << "EOF"
root:x:0:
bin:x:1:daemon
sys:x:2:
kmem:x:3:
tape:x:4:
tty:x:5:
daemon:x:6:
floppy:x:7:
disk:x:8:
lp:x:9:
dialout:x:10:
audio:x:11:
video:x:12:
utmp:x:13:
clock:x:14:
cdrom:x:15:
adm:x:16:
messagebus:x:18:
systemd-journal:x:23:
input:x:24:
mail:x:34:
kvm:x:61:
systemd-journal-gateway:x:73:
systemd-journal-remote:x:74:
systemd-journal-upload:x:75:
systemd-network:x:76:
systemd-resolve:x:77:
systemd-timesync:x:78:
systemd-coredump:x:79:
uuidd:x:80:
systemd-oom:x:81:
wheel:x:97:
users:x:999:
nogroup:x:65534:
EOF


exec /usr/bin/bash --login


touch /var/log/{btmp,lastlog,faillog,wtmp}
chgrp -v utmp /var/log/lastlog
chmod -v 664 /var/log/lastlog
chmod -v 600 /var/log/btmp

TODO Software 2

STOP: Optional Software

Here is a great time to install some optional software if you want it, like sudo.

---

Configuration

echo "ko4os" > /etc/hostname


cat > /etc/hosts << "EOF"
# Begin /etc/hosts
127.0.0.1   localhost localhost.localdomain
::1         localhost localhost.localdomain
# End /etc/hosts
EOF


cat > /etc/vconsole.conf << "EOF"
EYMAP="us"
FONT="eurlatgr"
EOF


cat > /etc/locale.conf << "EOF"
LANG="en_US.UTF-8"
EOF


cat > /etc/profile << "EOF"
# Begin /etc/profile
for i in $(locale); do
unset ${i%=*}
done
if [[ "$TERM" = linux ]]; then
export LANG=C.UTF-8
else
source /etc/locale.conf
for i in $(locale); do
key=${i%=*}
if [[ -v $key ]]; then
export $key
fi
done
fi
# End /etc/profile
EOF


cat > /etc/inputrc << "EOF"
# Begin /etc/inputrc
# Modified by Chris Lynn <roryo@roryo.dynup.net>
# Allow the command prompt to wrap to the next line
set horizontal-scroll-mode Off
# Enable 8-bit input
set meta-flag On
set input-meta On
# Turns off 8th bit stripping
set convert-meta Off
# Keep the 8th bit for display
set output-meta On
# none, visible or audible
set bell-style none
# All of the following map the escape sequence of the value
# contained in the 1st argument to the readline specific functions
"\eOd": backward-word
"\eOc": forward-word
# for linux console
"\e[1~": beginning-of-line
"\e[4~": end-of-line
"\e[5~": beginning-of-history
"\e[6~": end-of-history
"\e[3~": delete-char
"\e[2~": quoted-insert
# for xterm
"\eOH": beginning-of-line
"\eOF": end-of-line
# for Konsole
"\e[H": beginning-of-line
"\e[F": end-of-line
# End /etc/inputrc
EOF


cat > /etc/shells << "EOF"
# Begin /etc/shells
/bin/sh
/bin/bash
# End /etc/shells
EOF

---

Fstab

Option 1: Use the script to generate a /etc/fstab automatically.

Double check that all partitions are mounted, if they are not the script will miss them.

It’s pretty simple so for more options and arguments please visit the GitHub page.

curl -O https://raw.githubusercontent.com/KO4FZG/genfstab/main/genfstab.sh
chmod +x genfstab.sh

./genfstab.sh -U -n

Examine the output and make sure it looks right, if it does run it again with:

./genfstab.sh -U

Option 2: Create one manually

Read this Gentoo Wiki article to see examples and how.

---

Grub

grub-install --target=x86_64-efi --removable

cat > /boot/grub/grub.cfg << EOF
# Begin /boot/grub/grub.cfg
set default=0
set timeout=5

insmod part_gpt
insmod ext2
set root=(hd1,2)

insmod efi_gop
insmod efi_uga
if loadfont /boot/grub/fonts/unicode.pf2; then
  terminal_output gfxterm
fi

menuentry "GNU/Linux, Linux 6.16.1-ko4os-12.4" {
  linux   /boot/vmlinuz-6.16.1-ko4os-12.4 root=/dev/sdb2 ro
}

menuentry "Firmware Setup" {
  fwsetup
}
EOF

TODO: What to do about upgrades to the kernel here

You can also use “grub-mkconfig” I’ve found it works well but will overwrite everything.

Reboot

Whew, now we can unmount everything and reboot. Hopefully it boots, if it doesn’t start researching the error you get within the help from the Linux From Scratch, Gentoo, and Arch wikis. You can reach out to me at ko4fzg@ko4fzg.com but it’s unlikely I can help.

See you on the other side!