{"id":27185027,"url":"https://github.com/threefoldtech/0-initramfs","last_synced_at":"2025-04-09T17:10:09.808Z","repository":{"id":38191483,"uuid":"142883374","full_name":"threefoldtech/0-initramfs","owner":"threefoldtech","description":"Zero-OS Initramfs Builder","archived":false,"fork":false,"pushed_at":"2025-03-04T11:36:18.000Z","size":1030,"stargazers_count":4,"open_issues_count":14,"forks_count":1,"subscribers_count":18,"default_branch":"development-zos-v3","last_synced_at":"2025-04-09T17:10:01.648Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"zero-os-no-longer-used/0-initramfs","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threefoldtech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-30T14:00:48.000Z","updated_at":"2025-02-19T15:29:19.000Z","dependencies_parsed_at":"2023-10-12T01:41:16.977Z","dependency_job_id":"2ff8b5bb-34f0-45b5-b4a7-6c2bb50c948f","html_url":"https://github.com/threefoldtech/0-initramfs","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2F0-initramfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2F0-initramfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2F0-initramfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2F0-initramfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threefoldtech","download_url":"https://codeload.github.com/threefoldtech/0-initramfs/tar.gz/refs/heads/development-zos-v3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074976,"owners_count":21043490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-09T17:10:08.754Z","updated_at":"2025-04-09T17:10:09.773Z","avatar_url":"https://github.com/threefoldtech.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zero-OS Initramfs Builder\nThis repository contains all that is needed to build the Zero-OS kernel and initramfs to start our root filesystem.\n\n# Dependencies\nIn order to compile all the initramfs without issues, you'll need to install build-time dependencies.\n\nPlease check the build process and use the dependencies listed there (see `autobuild` directory).\nIf you want to install dependencies required inside an ubuntu 18.04 docker, you can use theses helpers:\n```\n. autobuild/tf-build-deps.sh\n. autobuild/tf-build-settings.sh\n```\n\nThe first script will install dependencies, the second one will source and export needed variables.\n\nThere is a special `autobuild/tf-build-deps-clean.sh` which doesn't install Go nor Rust.\nUse it if you installed them already.\n\n## Privileges\n\nYou need to have root privilege to be able to execute all the scripts.\n\nSome parts need to `chown/setuid/chmod/mknod` files as root.\n\nNot running it as root will fails the build process.\n\n# What does this script do ?\n - First, download and check checksum of all archives needed\n - Extract the archives\n - Compiles third-party software:\n    - busybox (for full base system)\n    - fuse (library and userland tools)\n    - openssl and ssl certificates (ca-certificates)\n    - util-linux (for `lsblk`, ...)\n    - e2fs-progs (for recent mkfs, etc.)\n    - redis (only the server is used)\n    - btrfs (btrfs-progs)\n    - libvirt and qemu\n    - parted (partition management)\n    - dnsmasq (used for dhcp on containers)\n    - nftables (used for firewalling and routing)\n    - iproute2 (used for network namespace support)\n    - unionfs-fuse (used for internal fuse layers)\n    - eudev and kmod (used for hardware and modules management)\n    - smartmontools (used for S.M.A.R.T monitoring)\n    - dmidecode (optional dependency for libvirt and management)\n    - openssh (client and server, for debug purpose)\n    - netcat6 (needed by libvirt migration)\n    - curl (needed for libcurl by zflist)\n    - zflist (0-flist for flist on-the-fly creation)\n    - restic (for container backup and upload)\n    - rtinfo (for realtime monitoring out-of-box)\n    - seektime (small tool to detect disk type)\n    - wireguard (netgen vpn, modules and userland tools)\n    - zlib (compression library)\n - Integrate core stuff:\n    - Compile `0-fs`\n    - Compile `corex` (container remote control)\n - Clean, remove useless files, optimize (strip) files\n - Copy system's configuration and init script\n - Compile the kernel (and bundles initramfs in the kernel)\n\n\n# How to use it ?\n## Easy\nJust type: `bash initramfs.sh` and everything should be done in one shot.\n\n## Custom way\n\nThe `initramfs.sh` script accepts multiple options:\n```\n -d --download    only download and extract archives\n -b --busybox     only (re)build busybox\n -t --tools       only (re)build tools (ssl, fuse, ...)\n -c --cores       only (re)build core0 and coreX\n -k --kernel      only (re)build kernel (produce final image)\n -M --modules     only (re)build kernel modules\n -e --extensions  only (re)build extensions\n -n --nomirror    don't use a mirror to download files (use upstream)\n -l --clean       only clean staging files (extracted sources)\n -m --mrproper    only remove staging files and clean the root\n -r --release     force a release build\n -h --help        display this help message\n```\n\nThe option `--kernel` is useful if you changes something on the root directory and want to rebuild the kernel (with the initramfs).\n\nThis will produce a new image with the latest changes.\n\nIn order to see how to use theses steps in a maintained way, please check GitHub Action build: `.github/workflows/kernel.yaml` file.\n\n## Build mode\nBy default, initramfs will compiles in `debug` mode, which contains some extra debug options.\n\nTo produce a `release` (aka **production** build), there is two options:\n- Using `--release` option during build\n- Override `BUILDMODE` variable defined on the top of `initramfs.sh`\n\nThis is obvious but, **do not use a debug version in a production environment.**\n\n## Mirror\nBy default, all files (except git upstream repositories) use a mirror to download files.\nThis mirror url is set on the initramfs.sh script itself.\n\nYou can use the `--nomirror` flag to disable mirror and use upstream website. If you want to build\nyour own mirror, you can simply use this flag to create your local mirror (`--download --nomirror` flags).\n\nYou just need to expose the `archives` directory to a via a http server to provide a mirror.\n\n## Build using a docker container\n\nCreate a docker container\n```shell\ndocker run -ti --name zero-os-builder ubuntu:18.04 /bin/bash\n```\n\n- You need to use `ubuntu:18.04`, this is the only image we supports\n- Ensure to have the repository available on `/0-initramfs`\n- Run `autobuild/tf-build.sh` script. This script will install dependencies and build everything\n- The result of the build will be located in `staging/vmlinuz.efi`\n\n**Warning:** if you don't use Ubuntu 18.04 (at least for now), some build _and_ runtime issue can occures.\n\n# I have the kernel, what can I do with it ?\nJust boot it. The kernel image is EFI bootable.\n\nIf you have an EFI Shell, just run the kernel like any EFI executable.\nIf you don't have the shell or want to boot it automaticaly, put the kernel in `/EFI/BOOT/BOOTX64.EFI` in a FAT partition.\n\n## How to test the kernel with QEMU\nYou can run the kernel and get the kernel output on your console from qemu directly\n```\nqemu-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\n```\n\n## How to test the kernel with xhyve (OSX - no Apple Silicon chips)\nInstall [xhyve](https://github.com/mist64/xhyve#installation).\n```\nxhyve -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\n```\n\n\n## How to create a 'bootable' (EFI) image\n```shell\ndd if=/dev/zero of=/tmp/zero-os.img bs=1M count=256\nmkfs.vfat /tmp/zero-os.iso\nmkdir -p /mnt/zero-os-iso\nmount Zero-OS.iso /mnt/zero-os-iso\nmkdir -p /mnt/zero-os-iso/EFI/BOOT\ncp staging/vmlinuz.efi /mnt/EFI/BOOT/BOOTX64.EFI\numount /mnt/zero-os-iso\n```\n\n# Extensions\n\nYou can add your own building extension-scripts to customize the initramfs.\n\nDuring the build process, after `cores` and before `kernel` process, all directories under `extensions` folder will be\nparsed and executed. To make a working extension, you just need a `extension-name.sh` script on the root directory of your extension.\n\nExemple:\n```\nextensions/\n  my-extension/\n    some-stuff/\n    another-stuff/\n    my-extension.sh\n  another-extension/\n    README.md\n    another-extension.sh\n```\n\nDuring the extension build phase, your extension script will be `sourced`, not forked, which means that you have access\nto all the variables used during the build script process.\n\nYou can use this extension way to copy extra configuration files, edit some default value on files, etc.\n\nHere are some useful variables you can use on your extension, they all points to a directory:\n```\nDISTFILES  - sources archive downloaded\nWORKDIR    - extracted (and compiled) sources\nROOTDIR    - the target root directory (contains the initramfs contents)\n```\n\n**Be careful, you could override some variable used by `initramfs.sh` itself and break the build process.**\n\nYou can rebuild extensions by calling `initramfs.sh --extensions`\n\n# 'Hot' debug (inject files without rebuilding the vmlinuz)\nRebuilding the vmlinuz can take relatively long time, when you want to only change one config file\nor do some small changes to the root image, this can become really painful to rebuild it each time.\n\nIn debug mode (enabled by default now), you can override the root filesystem, the step before `core0` starts, which\nmeans that you can even overwrite `core0` binary.\n\nThe `/init-debug` script is executed just before `/init` does the `switch_root` to the real filesystem, this script\nwill search if `/dev/sda1` exists, if it exists, mounting it as `vfat` filesystem in read-only mode, checking for debug\nfiles then copying them.\n\n## Requirement\n- A `vfat` filesystem on `/dev/sda1`\n- A file called `.zero-os-debug` on the root of `/dev/sda1`\n- The whole content of `/dev/sda1` will be copied (overwriting existing files) on the real root\n\n## QEMU\nThis way enable you to easily overwrite the system with your debug file from your local machine, with qemu.\n\nAdd `-drive file=fat:/debug-files,format=raw` as **first** drive argument to your qemu command line.\n\n### Quick help\n```\nmkdir /tmp/zero-os-debug/\ntouch /tmp/zero-os-debug/.zero-os-debug\necho World \u003e /tmp/zero-os-debug/hello\n\nqemu-system-x86_64 -drive file=fat:rw:/tmp/zero-os-debug,format=raw $QEMU_CMD_LINE\n```\nThis will add `/hello` to your running Zero-OS.\n\n## Static build\nTo simplify some binaries update and compatibility for some container, some binaries (like `corex`) needs\nto be compiled as fully static. The best way to get a well-working static binary is using, eg, musl as\nlibc to staticly compile the binary. We now support this.\n\nThere are some special packages compiled using musl, theses packages ends with `-musl` name and a special\nroot directory (defined by `MUSLROOTDIR`) create a root directory where a musl subsystem can be used.\n\nYou can take a look at `corex-musl` or `zlib-musl` to understand how this works.\n\n## Kernel Configuration\nKernel configuration is based on Arch Linux default kernel config file.\n\nHere is what we changed:\n- Default kernel command line customized\n- Initramfs is compressed using XZ\n- Default hostname set to `zero-os`\n- Build version name set to `Zero-OS`\n- Change default initramfs path to `../../root` to include our root system\n- All `Sound drivers` disabled\n- All `Multimedia drivers` disabled\n- Inputs `Mice`, `Joystick`, `Touchscreen`, `Tablets` and `Miscellaneous devices` disabled\n- All `Special HID drivers`\n- All `CAN bus subsystem` disabled\n- All `Amateur Radio support` disabled\n- All `IrDA (infrared)` and `NFC subsystem` disabled\n- All `Bluetooth` and `CAIF` disabled\n- All `Wireless`, `WiMAX` and `RF switch` disabled\n- All `Data acquision support (comedi)` disabled\n- Filesystems `ext4`, `Raiserfs`, `JFS`, `XFS`, `GFS2`, `OCFS2`, `NILFS2`, `F2FS`, `NTFS` disabled\n- Modules are not compressed\n\n# Repository Owner\n- [Maxime Daniel](https://github.com/maxux), Telegram: [@maxux](http://t.me/maxux)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2F0-initramfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreefoldtech%2F0-initramfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2F0-initramfs/lists"}