cloudos handbook

installing cloudos 1.0 on x86_64.

1. about cloudos

cloudos is a minimal linux that you build yourself. after installation the system has only a console.

1.1 what you need

the numbers are approximate, there are no hard checks.

1.2 what is inside stage 3

stage 3 is built from scratch following lfs 12.4 (sysv variant) and extended with everything needed for installation and building packages. versions are given for cloudos 1.0.

1.3 what the system does not have

• graphics and desktop environments. after installation there is only a console
• man pages. help is this handbook and the key --help
• an ssh server and a firewall
• sudo. doas is used instead
• users other than root, locales and swap. you create them yourself
• a bootloader and a kernel. you build the kernel and install the bootloader through the package manager

1.4 installation order

1. boot from the live iso, check the network and boot mode
2. partition the disk and create the filesystems
3. download and unpack stage 3
4. enter chroot and set up the build
5. build the kernel
6. make the initramfs, fstab and install limine
7. set a password, enable services and reboot
8. set up the system after the first boot

1.5 how to use the handbook

at the top of the left panel there is a switch between uefi and bios. choose your mode and only the needed commands will remain in the handbook. the choice is remembered in the browser.

search opens with the button in the header or with the keys ctrl + k. every command block has a copy button at the top right.

commands contain placeholders, replace them with your own values:

2. preparation

boot from the cloudos live iso and check the network.

dhcpcd
ping -c1 github.com

determine the boot mode.

[ -d /sys/firmware/efi ] && echo uefi || echo bios

2.1 date and time

if the system date is wrong, https certificates will fail verification and downloads will fail with confusing errors. check the date:

date

if it differs a lot from the real one, set it manually (format year-month-day hour:minutes:seconds):

date -s "YYYY-MM-DD HH:MM:SS"

2.2 disks

look at the disks and partitions. the disk name you need is then used everywhere instead of /dev/sda.

lsblk -f

sata and usb disks are called sda, sdb, nvme is nvme0n1, virtual vda. you can tell which one is the live iso stick by its size.

2.3 network

check that the interface is visible and got an address:

ip link
ip addr

if there is no address, run dhcpcd again for the needed interface (see the name in ip link):

dhcpcd eth0

only wired network is set up out of the box. wifi is not configured in the live iso.

2.4 if sites do not open

github, kernel.org and some mirrors may be unavailable from your network. then download the file on another device and move it with a usb stick:

mkdir -p /mnt/usb
mount /dev/sdb1 /mnt/usb
ls /mnt/usb

instead of /dev/sdb1 put the partition of your second usb stick from lsblk. there are mirrors for the kernel, see 7.3.

3. disk and filesystems

3.1 partitioning

cfdisk /dev/sda

3.2 filesystems

mkfs.fat -F32 /dev/sda1

mkfs.fat -F32 /dev/sda1

format the root partition as ext4:

mkfs.ext4 /dev/sda2

or as btrfs:

mkfs.btrfs /dev/sda2

3.3 mounting

mkdir -p /mnt/cloudos
mount /dev/sda2 /mnt/cloudos
mkdir -p /mnt/cloudos/boot
mount /dev/sda1 /mnt/cloudos/boot

3.4 example layout

if you need a swap partition, make it the third, not the first. more about swap in 10.7. swap can also be a file after installation, then a separate partition is not needed.

3.5 checking

make sure everything is mounted as it should be:

lsblk -f
findmnt /mnt/cloudos
findmnt /mnt/cloudos/boot

the root should be on the second partition, /boot on the first. if one of the commands printed nothing, the partition is not mounted.

4. stage 3

stage 3 is a ready base cloudos system without a kernel and bootloader. the files are in the releases section of the repository.

github.com/wh1laye/cloudos-repo/releases

cloudos-stage3-1.0-x86_64.tar.xz
cloudos-stage3-1.0-x86_64.tar.xz.sha256

4.1 verification (can be skipped)

sha256sum -c cloudos-stage3-1.0-x86_64.tar.xz.sha256

4.2 unpacking

tar xpvf cloudos-stage3-1.0-x86_64.tar.xz --xattrs-include='*.*' --numeric-owner -C /mnt/cloudos

4.3 downloading

download straight onto the root partition, the live system has little memory:

cd /mnt/cloudos
curl -LO https://github.com/wh1laye/cloudos-repo/releases/download/cloudos/cloudos-stage3-1.0-x86_64.tar.xz
curl -LO https://github.com/wh1laye/cloudos-repo/releases/download/cloudos/cloudos-stage3-1.0-x86_64.tar.xz.sha256

then do the verification from 4.1 and the unpacking from 4.2. run the unpacking from the same folder where the archive is.

4.4 after unpacking

the archive is no longer needed, delete it so it does not take space:

rm /mnt/cloudos/cloudos-stage3-1.0-x86_64.tar.xz*
ls /mnt/cloudos

the list should contain bin, boot, etc, usr, var and other system folders. if the folder is empty, the archive was unpacked to the wrong place.

5. entering chroot

mount --types proc /proc /mnt/cloudos/proc
mount --rbind /sys /mnt/cloudos/sys
mount --make-rslave /mnt/cloudos/sys
mount --rbind /dev /mnt/cloudos/dev
mount --make-rslave /mnt/cloudos/dev
cp --dereference /etc/resolv.conf /mnt/cloudos/etc/
chroot /mnt/cloudos /bin/bash
source /etc/profile

5.1 what the commands do

5.2 prompt

so you do not forget you are in chroot, change the prompt:

export PS1="(cloudos chroot) $PS1"

5.3 entering again

if you rebooted the live iso or left chroot, mount the partitions again and repeat the entry. you do not need to unpack the archive again:

mount /dev/sda2 /mnt/cloudos
mount /dev/sda1 /mnt/cloudos/boot
mount --types proc /proc /mnt/cloudos/proc
mount --rbind /sys /mnt/cloudos/sys
mount --make-rslave /mnt/cloudos/sys
mount --rbind /dev /mnt/cloudos/dev
mount --make-rslave /mnt/cloudos/dev
cp --dereference /etc/resolv.conf /mnt/cloudos/etc/
chroot /mnt/cloudos /bin/bash
source /etc/profile

you enter the system the same way for repair if it stopped booting, see 14.9.

5.4 leaving

exit
umount -R /mnt/cloudos

if unmounting says target is busy, close all terminal windows where you were in chroot and repeat.

6. build setup

build flags are set in one file, /etc/cloudpkg/make.conf:

CC="gcc"
CFLAGS="-O2 -march=native"
MAKEOPTS="-j$(nproc)"
USE=""

for clang set CC="clang". then update the recipe list:

cloudpkg sync

6.1 locales

echo "en_US.UTF-8 UTF-8" > /etc/locale.gen
localedef -i en_US -f UTF-8 en_US.UTF-8
echo "LANG=en_US.UTF-8" > /etc/locale.conf

6.2 build flags

if you build on the same machine where you will work, leave -march=native. if you later move the disk to another computer, change it to -march=x86-64. stage 3 itself is built with generic flags.

6.3 parallel build

-j$(nproc) starts as many jobs as the cpu has threads. with little ram the build may fail with the message killed. then reduce the number:

MAKEOPTS="-j2"

6.4 gcc 15 and build errors

gcc 15 uses the c23 standard by default, and some old packages do not build with it. typical signs: errors about bool, true, false or function declarations without arguments. in that case return the previous standard:

CC="gcc -std=gnu17"

change the value CC in /etc/cloudpkg/make.conf and repeat the package installation.

7. kernel

the kernel is taken from kernel.org and configured by hand

cd /usr/src
curl -LO https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.18.10.tar.xz
tar xf linux-6.18.10.tar.xz
cd linux-6.18.10
make menuconfig
make -j$(nproc)
make modules_install
cp arch/x86/boot/bzImage /boot/vmlinuz-6.18.10

7.1 what to enable in menuconfig

in make menuconfig search opens with the key /, there you can find any option by name. a kernel without the needed drivers will not boot, so check at least these items. an asterisk [*] means built into the kernel, M means a module.

a convenient start: if the live iso is built with support for /proc/config.gz, take its config as a base and add to it:

zcat /proc/config.gz > .config
make olddefconfig
make menuconfig

7.2 what the build commands do

save the config and the symbol map, they will be useful when updating the kernel:

cp .config /boot/config-6.18.10
cp System.map /boot/System.map-6.18.10

7.3 kernel mirrors

if cdn.kernel.org does not open, download the same archive from a mirror:

curl -LO https://mirrors.aliyun.com/linux-kernel/v6.x/linux-6.18.10.tar.xz
curl -LO https://mirrors.ustc.edu.cn/kernel.org/linux/kernel/v6.x/linux-6.18.10.tar.xz

paths on mirrors sometimes change. if the link does not work, open the mirror directory in the browser and find the file by hand.

7.4 another kernel version

in all commands replace 6.18.10 with your version. the file names in /boot, in initramfs and in limine.conf must match.

8. bootloader

8.1 initramfs

cloudpkg install dracut
dracut --kver 6.18.10 /boot/initramfs-6.18.10.img

8.2 fstab

partition uuids are shown by blkid. the file /etc/fstab for uefi:

UUID=ROOT_UUID  /      ext4  defaults  0 1
UUID=ESP_UUID   /boot  vfat  defaults  0 2

for bios:

UUID=ROOT_UUID  /      ext4  defaults  0 1
UUID=BOOT_UUID  /boot  vfat  defaults  0 2

if the root is on btrfs, replace ext4 in the first line with btrfs.

8.3 limine

cloudpkg install limine

the file /boot/limine.conf is the same for uefi and bios:

timeout: 5

/CloudOS
    protocol: linux
    path: boot():/vmlinuz-6.18.10
    cmdline: root=UUID=ROOT_UUID rw
    module_path: boot():/initramfs-6.18.10.img

mkdir -p /boot/EFI/BOOT
cp /usr/share/limine/BOOTX64.EFI /boot/EFI/BOOT/BOOTX64.EFI

cp /usr/share/limine/limine-bios.sys /boot/
limine bios-install /dev/ (your disk name /dev/sda1 /dev/sdb1 /dev/nvme0n1)

8.4 check before rebooting

look at what is in /boot:

ls -l /boot

compare the uuids in the configs with the real ones:

blkid
grep UUID /etc/fstab /boot/limine.conf

the uuid of the root partition in limine.conf and in fstab must match the output of blkid. most failed first boots are due to a typo here.

8.5 writing to nvram (uefi only, optional)

efibootmgr --create --disk /dev/sda --part 1 --loader '\EFI\BOOT\BOOTX64.EFI' --label CloudOS

8.6 several kernels

before updating the kernel add a second entry to /boot/limine.conf, and do not delete the old one. if the new kernel does not boot, you pick the old one in the menu:

timeout: 5

/CloudOS
    protocol: linux
    path: boot():/vmlinuz-NEW
    cmdline: root=UUID=ROOT_UUID rw
    module_path: boot():/initramfs-NEW.img

/CloudOS (old kernel)
    protocol: linux
    path: boot():/vmlinuz-OLD
    cmdline: root=UUID=ROOT_UUID rw
    module_path: boot():/initramfs-OLD.img

instead of NEW and OLD put the kernel versions.

8.7 grub instead of limine

if you prefer grub, install it instead of limine (inside chroot, after the kernel and initramfs are installed):

cloudpkg sync
cloudpkg install sys-boot/grub

grub-install --target=x86_64-efi --efi-directory=/boot --boot-directory=/boot --removable

grub-install --target=i386-pc --boot-directory=/boot /dev/sda

the config is written by hand to /boot/grub/grub.cfg:

set timeout=5
menuentry "CloudOS" {
    search --no-floppy --fs-uuid --set=root ESP_UUID
    linux /vmlinuz-6.18.10 root=UUID=ROOT_UUID rw
    initrd /initramfs-6.18.10.img
}

9. finishing

enable the network and the log, set the root password:

cloudpkg install dhcpcd
cloudpkg install syslog-ng
rc-update add dhcpcd default
rc-update add syslog-ng default
passwd

leave chroot, unmount and reboot:

exit
umount -R /mnt/cloudos
reboot

9.1 checking services

before rebooting make sure the services are added:

rc-update show

the list should contain dhcpcd and the log at the level default.

9.2 first boot

after the reboot remove the usb stick and choose the disk in the boot menu if it was not chosen by itself. the prompt will appear login: on tty1. enter root and the password you set with the command passwd.

then set up the system, it is described in chapter 10.

10. first boot

after installation the system has only a console and root. this chapter is about what is worth doing right away.

10.1 login

at the prompt login: , enter root and the password you set in chapter 9. if you did not set one, the password is empty, set it right away with the command passwd.

10.2 user and doas

working as root all the time is unsafe. create a regular user and allow the wheel group to use doas:

grep wheel /etc/group || groupadd wheel
useradd -m -G wheel -s /bin/bash name
passwd name
echo "permit :wheel" > /etc/doas.conf
chmod 0400 /etc/doas.conf

instead of name put your own. after that, commands as root are run like this:

doas cloudpkg install nano

if you do not want to type the password every time, replace the rule with permit nopass :wheel. this is more convenient, but safer with a password.

10.3 computer name

echo "cloudos" > /etc/hostname
echo 'hostname="cloudos"' > /etc/conf.d/hostname
rc-update add hostname boot

if the service hostname is already enabled, the last command will report that and change nothing. instead of cloudos you can write any name in latin letters.

10.4 time zone

ls /usr/share/zoneinfo
ln -sfv /usr/share/zoneinfo/Europe/Moscow /etc/localtime

instead of Europe/Moscow choose your zone from the list. check the result with the command date.

10.5 network

dhcpcd gets the address and dns automatically. check:

ip addr
ping -c1 github.com

if you need a permanent address, add to /etc/dhcpcd.conf (see the interface name in ip link):

interface eth0
static ip_address=192.168.1.50/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8

then restart the service: rc-service dhcpcd restart.

10.6 openrc services

levels: boot for what is needed early (for example the computer name), default for ordinary services.

10.7 swap

swap is not required, but it helps when building big packages with little ram. the easiest way is a file.

for ext4:

dd if=/dev/zero of=/swapfile bs=1M count=4096 status=progress
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

for btrfs (also works for ext4):

btrfs filesystem mkswapfile --size 4g /swapfile
swapon /swapfile

so that swap turns on by itself, add a line to /etc/fstab:

/swapfile  none  swap  defaults  0 0

a swap partition is made like this: mkswap /dev/sda3, swapon /dev/sda3 and a fstab line with UUID=... instead of /swapfile.

11. packages and cloudpkg

all packages in cloudos are built from source. this is done by the manager cloudpkg. its recipes are taken from gentoo.

11.1 commands

11.2 how the installation goes

1. the package recipe and its dependency list are read
2. the sources are downloaded through curl
3. sha256 is checked
4. the package is built with your flags from /etc/cloudpkg/make.conf
5. the result is installed into the system

a build takes time and disk space. big packages such as compilers build for a long time, this is normal.

11.3 examples

cloudpkg sync
cloudpkg install limine
cloudpkg install dracut
cloudpkg install nano

11.4 if a package failed to build

1. read the last lines with error
2. if the error is about the c standard, set CC="gcc -std=gnu17", see 6.4
3. if the build fails with killed, reduce -j in MAKEOPTS
4. try cloudpkg sync and repeat, maybe the recipe is already fixed
5. write on the forum in the questions section, attaching the last 10-15 lines of output

12. maintenance

12.1 updating packages

cloudpkg sync
cloudpkg upgrade
cloudpkg clean

12.2 updating the kernel

a new version is installed next to the old one. do not delete the old kernel until you are sure the new one boots.

1. download and unpack the new kernel into /usr/src, as in chapter 7
2. take the old config as a base and pull in the new options:

cd /usr/src/linux-NEW
cp /boot/config-OLD .config
make olddefconfig

3. build and install:

make -j$(nproc)
make modules_install
cp arch/x86/boot/bzImage /boot/vmlinuz-NEW
cp .config /boot/config-NEW
dracut --kver NEW /boot/initramfs-NEW.img

4. add a second entry to /boot/limine.conf, as in 8.6, and reboot
5. if everything works, the old files can be deleted:

rm /boot/vmlinuz-OLD /boot/initramfs-OLD.img /boot/config-OLD
rm -r /lib/modules/OLD

instead of NEW and OLD put the versions, for example 6.18.10.

12.3 backup

a full copy of the system in one archive with the same keys as when unpacking stage 3. save it to another disk or usb stick:

tar cpf /mnt/usb/cloudos-backup.tar.xz --xattrs-include='*.*' --numeric-owner --one-file-system -I xz /

btrfs has snapshots, they are faster and take less space, see appendix b.

12.4 freeing space

df -h
cloudpkg clean
du -sh /usr/src/* /var/* 2>/dev/null

the old kernel folders in /usr/src can be deleted if you have their configs saved in /boot.

13. what next

cloudos is installed minimal. everything else you add as needed.

13.1 other locales

in chapter 6.1 one locale was created. to add another, for example russian:

localedef -i ru_RU -f UTF-8 ru_RU.UTF-8
echo "LANG=ru_RU.UTF-8" > /etc/locale.conf

in the kernel console cyrillic may display incorrectly without a separate font, so for the console it is safer to keep en_US.UTF-8.

13.2 help and feedback

• questions and discussion on the forum
• new versions and images on the releases page
• bugs and suggestions in issues on github

14. errors and fixes

click the error text to see the cause and what to do. if your error is not in the list, use search.

14.1 live iso, network and time

ip link
dhcpcd eth0

14.2 partitioning and filesystems

14.3 downloading and unpacking

14.4 chroot

14.5 building packages

14.6 kernel

14.7 booting

14.8 after booting

14.9 emergency system access

if the system does not boot, it can almost always be repaired from the live iso:

1. boot from the live iso and check the network
2. mount the partitions and enter chroot per 5.3
3. fix the config, rebuild initramfs with the command dracut --kver 6.18.10 /boot/initramfs-6.18.10.img --force or fix limine.conf
4. leave chroot, unmount and reboot

14.10 how to report an error

so that you get help quickly, attach:

• which chapter of the handbook you were doing and on which command it failed
• the lines with error or the last 10-15 lines of output
• boot mode (uefi or bios), disk name (sda or nvme) and the root filesystem
• the output of dmesg | tail -50, if the error is after booting

14.11 installer wizard and grub

lsblk
partprobe /dev/sda

bash /root/cloudos-s1.sh

ls /usr/share/limine
command -v grub-install

ls /sys/firmware/efi
mountpoint /mnt/cloudos/boot

ls
set root=(hd0,msdos1)
set prefix=(hd0,msdos1)/grub
insmod normal
normal

ls
set root=(hd0,msdos1)
linux /vmlinuz-6.18.10 root=/dev/sda2 rw
initrd /initramfs-6.18.10.img
boot

ls /boot
nano /boot/grub/grub.cfg

14.12 cloudpkg and portage

cloudpkg sync
cloudpkg doctor

ln -sfn /var/db/repos/gentoo/profiles/default/linux/amd64/23.0 /etc/portage/make.profile

python3 -m pip install --force-reinstall --index-url https://mirrors.aliyun.com/pypi/simple/ portage

doas cloudpkg install name

cloudpkg search name
cloudpkg install category/name

cloudpkg install -t category/name

echo "sys-libs/glibc-2.42" >> /etc/portage/profile/package.provided
cloudpkg install -p name

cloudpkg clean
cloudpkg install name

tail -n 30 /var/tmp/portage/category/name/temp/build.log

15. cheat sheet

15.1 disks

15.2 network

15.3 system

15.4 files and archives

15.5 btrfs

15.6 cloudpkg

openrc services are collected in the table 10.6.

16. questions and answers

appendix a. disk names

the partition name depends on the disk type. for nvme the letter is added before the partition number: p.

if you install on nvme, replace /dev/sda1 with /dev/nvme0n1p1 and /dev/sda2 with /dev/nvme0n1p2 in all commands.

appendix b. btrfs with subvolumes

optional. subvolumes allow fast system snapshots and rollbacks. described for the layout from 3.4.

b.1 creating subvolumes

mkfs.btrfs /dev/sda2
mount /dev/sda2 /mnt/cloudos
btrfs subvolume create /mnt/cloudos/@
btrfs subvolume create /mnt/cloudos/@home
umount /mnt/cloudos

b.2 mounting

mount -o subvol=@ /dev/sda2 /mnt/cloudos
mkdir -p /mnt/cloudos/boot /mnt/cloudos/home
mount /dev/sda1 /mnt/cloudos/boot
mount -o subvol=@home /dev/sda2 /mnt/cloudos/home

b.3 fstab and bootloader

UUID=ROOT_UUID  /      btrfs  subvol=@,noatime      0 0
UUID=ROOT_UUID  /home  btrfs  subvol=@home,noatime  0 0
UUID=ESP_UUID   /boot  vfat   defaults              0 2

in /boot/limine.conf in the line cmdline add the subvolume parameter:

cmdline: root=UUID=ROOT_UUID rootflags=subvol=@ rw

b.4 system snapshot

mkdir -p /mnt/top
mount -o subvolid=5 /dev/sda2 /mnt/top
btrfs subvolume snapshot -r /mnt/top/@ /mnt/top/@-snap-1
umount /mnt/top

the snapshot lies next to the subvolume @ and takes no space until the data changes.

appendix c. glossary