This repository contains all that is needed to build the Zero-OS kernel and initramfs to start our root filesystem.
In order to compile all the initramfs without issues, you'll need to install build-time dependencies.
Please check the build process and use the dependencies listed there (see autobuild
directory).
If you want to install dependencies required inside an ubuntu 18.04 docker, you can use theses helpers:
. autobuild/tf-build-deps.sh
. autobuild/tf-build-settings.sh
The first script will install dependencies, the second one will source and export needed variables.
There is a special autobuild/tf-build-deps-clean.sh
which doesn't install Go nor Rust.
Use it if you installed them already.
You need to have root privilege to be able to execute all the scripts.
Some parts need to chown/setuid/chmod/mknod
files as root.
Not running it as root will fails the build process.
lsblk
, ...)0-fs
corex
(container remote control)Just type: bash initramfs.sh
and everything should be done in one shot.
The initramfs.sh
script accepts multiple options:
-d --download only download and extract archives
-b --busybox only (re)build busybox
-t --tools only (re)build tools (ssl, fuse, ...)
-c --cores only (re)build core0 and coreX
-k --kernel only (re)build kernel (produce final image)
-M --modules only (re)build kernel modules
-e --extensions only (re)build extensions
-n --nomirror don't use a mirror to download files (use upstream)
-l --clean only clean staging files (extracted sources)
-m --mrproper only remove staging files and clean the root
-r --release force a release build
-h --help display this help message
The option --kernel
is useful if you changes something on the root directory and want to rebuild the kernel (with the initramfs).
This will produce a new image with the latest changes.
In order to see how to use theses steps in a maintained way, please check GitHub Action build: .github/workflows/kernel.yaml
file.
By default, initramfs will compiles in debug
mode, which contains some extra debug options.
To produce a release
(aka production build), there is two options:
--release
option during buildBUILDMODE
variable defined on the top of initramfs.sh
This is obvious but, do not use a debug version in a production environment.
By default, all files (except git upstream repositories) use a mirror to download files. This mirror url is set on the initramfs.sh script itself.
You can use the --nomirror
flag to disable mirror and use upstream website. If you want to build
your own mirror, you can simply use this flag to create your local mirror (--download --nomirror
flags).
You just need to expose the archives
directory to a via a http server to provide a mirror.
Create a docker container
docker run -ti --name zero-os-builder ubuntu:18.04 /bin/bash
ubuntu:18.04
, this is the only image we supports/0-initramfs
autobuild/tf-build.sh
script. This script will install dependencies and build everythingstaging/vmlinuz.efi
Warning: if you don't use Ubuntu 18.04 (at least for now), some build and runtime issue can occures.
Just boot it. The kernel image is EFI bootable.
If you have an EFI Shell, just run the kernel like any EFI executable.
If you don't have the shell or want to boot it automaticaly, put the kernel in /EFI/BOOT/BOOTX64.EFI
in a FAT partition.
You can run the kernel and get the kernel output on your console from qemu directly
qemu-system-x86_64 -kernel vmlinuz.efi -m 2048 -enable-kvm -cpu host -net nic,model=e1000 -net bridge,br=vm0 -nographic -serial null -serial mon:stdio -append console=ttyS1,115200n8
Install xhyve.
xhyve -m 1G -c 2 -s 0:0,hostbridge -s 31,lpc -l com1 -l com2,stdio -s 2:0,virtio-net -f kexec,vmlinuz.efi,,earlyprintk=serial console=ttyS1 acpi=off
dd if=/dev/zero of=/tmp/zero-os.img bs=1M count=256
mkfs.vfat /tmp/zero-os.iso
mkdir -p /mnt/zero-os-iso
mount Zero-OS.iso /mnt/zero-os-iso
mkdir -p /mnt/zero-os-iso/EFI/BOOT
cp staging/vmlinuz.efi /mnt/EFI/BOOT/BOOTX64.EFI
umount /mnt/zero-os-iso
You can add your own building extension-scripts to customize the initramfs.
During the build process, after cores
and before kernel
process, all directories under extensions
folder will be
parsed and executed. To make a working extension, you just need a extension-name.sh
script on the root directory of your extension.
Exemple:
extensions/
my-extension/
some-stuff/
another-stuff/
my-extension.sh
another-extension/
README.md
another-extension.sh
During the extension build phase, your extension script will be sourced
, not forked, which means that you have access
to all the variables used during the build script process.
You can use this extension way to copy extra configuration files, edit some default value on files, etc.
Here are some useful variables you can use on your extension, they all points to a directory:
DISTFILES - sources archive downloaded
WORKDIR - extracted (and compiled) sources
ROOTDIR - the target root directory (contains the initramfs contents)
Be careful, you could override some variable used by initramfs.sh
itself and break the build process.
You can rebuild extensions by calling initramfs.sh --extensions
Rebuilding the vmlinuz can take relatively long time, when you want to only change one config file or do some small changes to the root image, this can become really painful to rebuild it each time.
In debug mode (enabled by default now), you can override the root filesystem, the step before core0
starts, which
means that you can even overwrite core0
binary.
The /init-debug
script is executed just before /init
does the switch_root
to the real filesystem, this script
will search if /dev/sda1
exists, if it exists, mounting it as vfat
filesystem in read-only mode, checking for debug
files then copying them.
vfat
filesystem on /dev/sda1
.zero-os-debug
on the root of /dev/sda1
/dev/sda1
will be copied (overwriting existing files) on the real rootThis way enable you to easily overwrite the system with your debug file from your local machine, with qemu.
Add -drive file=fat:/debug-files,format=raw
as first drive argument to your qemu command line.
mkdir /tmp/zero-os-debug/
touch /tmp/zero-os-debug/.zero-os-debug
echo World > /tmp/zero-os-debug/hello
qemu-system-x86_64 -drive file=fat:rw:/tmp/zero-os-debug,format=raw $QEMU_CMD_LINE
This will add /hello
to your running Zero-OS.
To simplify some binaries update and compatibility for some container, some binaries (like corex
) needs
to be compiled as fully static. The best way to get a well-working static binary is using, eg, musl as
libc to staticly compile the binary. We now support this.
There are some special packages compiled using musl, theses packages ends with -musl
name and a special
root directory (defined by MUSLROOTDIR
) create a root directory where a musl subsystem can be used.
You can take a look at corex-musl
or zlib-musl
to understand how this works.
Kernel configuration is based on Arch Linux default kernel config file.
Here is what we changed:
zero-os
Zero-OS
../../root
to include our root systemSound drivers
disabledMultimedia drivers
disabledMice
, Joystick
, Touchscreen
, Tablets
and Miscellaneous devices
disabledSpecial HID drivers
CAN bus subsystem
disabledAmateur Radio support
disabledIrDA (infrared)
and NFC subsystem
disabledBluetooth
and CAIF
disabledWireless
, WiMAX
and RF switch
disabledData acquision support (comedi)
disabledext4
, Raiserfs
, JFS
, XFS
, GFS2
, OCFS2
, NILFS2
, F2FS
, NTFS
disabled