{"id":13509735,"url":"https://github.com/u-root/webboot","last_synced_at":"2025-03-30T14:31:47.470Z","repository":{"id":36591021,"uuid":"196050970","full_name":"u-root/webboot","owner":"u-root","description":"Tools to let a u-root instance boot signed live distro images over the web","archived":true,"fork":false,"pushed_at":"2023-02-05T20:04:49.000Z","size":40763,"stargazers_count":109,"open_issues_count":14,"forks_count":25,"subscribers_count":59,"default_branch":"main","last_synced_at":"2025-01-31T04:27:24.406Z","etag":null,"topics":["custom-kernel","hacktoberfest2020","initramfs","kernel","kexec","webboot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/u-root.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-09T17:07:09.000Z","updated_at":"2024-11-02T08:24:54.000Z","dependencies_parsed_at":"2023-02-19T01:46:07.479Z","dependency_job_id":null,"html_url":"https://github.com/u-root/webboot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fwebboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fwebboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fwebboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fwebboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/u-root","download_url":"https://codeload.github.com/u-root/webboot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246332206,"owners_count":20760438,"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":["custom-kernel","hacktoberfest2020","initramfs","kernel","kexec","webboot"],"created_at":"2024-08-01T02:01:12.141Z","updated_at":"2025-03-30T14:31:42.460Z","avatar_url":"https://github.com/u-root.png","language":"Go","readme":"# About\n\n`webboot` offers tools to let a u-root instance boot signed live distro images over the web.\n\n## Concept\n\nThe `webboot` bootloader works as follows:\n\n1. fetch an OS distro release ISO from the web\n2. save the ISO to a local cache (ex. USB stick)\n3. mount the ISO and copy out the kernel and initrd\n4. load the extracted kernel with the initrd\n5. kexec that kernel with parameters to tell the next distro where to locate its ISO file (ex. iso-scan/filename=)\n\nThe current version offers a user interface based on [termui](https://github.com/gizak/termui) to help locate and boot the ISO file.\n\nFor reference, webboot developers should familiarize themselves with:\n\n- [cpio tutorial](https://www.gnu.org/software/cpio/manual/html_node/Tutorial.html)\n- [initrd usage](https://www.kernel.org/doc/html/latest/admin-guide/initrd.html)\n- [kernel parameters](https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html)\n\n\n## Supported Operating Systems\n\n### Requirements\nISOs must have the following to be fully compatible with `webboot`.\n\n1. 64-bit kernel\n2. Parsable `grub` or `syslinux` config file\n3. Init process than can locate an ISO file (ex. casper's iso-scan)\n\nAdditional operating systems can be added by appending an entry to the `supportedDistros` map in `/cmds/webboot/types.go`.\n\nIf the config file is not compatible with our parser, we can manually specify the configuration by adding a `Config` object to the distro's entry in `supportedDistros`. See the entries for Arch and Manjaro as an example.\n\n### Currently Supported\n| Name | Required Kernel Parameters | Notes |\n| ----- | ------ | ----- |\n| Arch | `img_dev=/dev/disk/by-uuid/UUID img_loop=PATH_TO_ISO` | Unable to parse config file. Configuration is specified in a `Config` object.\n| CentOS | `iso-scan/filename=PATH_TO_ISO` | CentOS 7 supports live mode. CentOS 8 will boot to the graphical installer.\n| Debian | `findiso=PATH_TO_ISO` |\n| Fedora | `iso-scan/filename=PATH_TO_ISO` |\n| Kali | `findiso=PATH_TO_ISO` |\n| Linux Mint | `iso-scan/filename=PATH_TO_ISO` |\n| Manjaro | `img_dev=/dev/disk/by-uuid/UUID img_loop=PATH_TO_ISO` | Unable to parse config file. Configuration is specified in a `Config` object.\n| Tinycore | `iso=UUID/PATH_TO_ISO` |\n| Ubuntu | `iso-scan/filename=PATH_TO_ISO` |\n\n### In Progress\n| Name | Required Kernel Parameters | Issue |\n| --- | --- | --- |\n| OpenSUSE | `root=live:CDLABEL=ISO_LABEL iso-scan/filename=PATH_TO_ISO` | `grub` config file is too complicated for our parser. We could specify the configuration manually, but that would involve hardcoding the ISO_LABEL (see [Issue 185](https://github.com/u-root/webboot/issues/185)).|\n\n## Usage\n\n### Build initramfs with added webboot commands\n\nDownload u-root with `GO111MODULE=off go get github.com/u-root/u-root`.\n\nRun `GO111MODULE=off go run .` in the source directory of webboot to build the\ninitramfs.\n\nThis runs [u-root](https://github.com/u-root/u-root) under the hood. To pass\nextra options, such as to include extra files, use the `-u` switch, e.g.,\n`GO111MODULE=off go run buildimage.go -u \"-files path/to/bzImage:bzImage\"` to\nadd a custom kernel which can be used to test whether kexec works in a small\nsetup. That saves a lot of time, because a full webboot flow would always need\nto download large ISO files, copy them, mount and decompress.\n\n#### Convenience\n\nFor convenience, you can\n\n- skip the inclusion of Wi-Fi tools by passing `-wifi false`\n- add a custom kernel for within the initramfs via `-bzImage path/to/bzImage`\n- add an ISO file to the initramfs via `-iso path/to/os-distro.iso`\n    * boot that ISO via `webboot -dhcp4=false -dhcp6-false local` later, which\n      requires passing a pmem-enabled kernel via `-bzImage` as described above\n\n#### Compression\n\nYou can optionally compress the initramfs with `lzma` or any other compression\nmethod you configure your kernel for.\n\n```sh\nlzma -f /tmp/initramfs.linux_amd64.cpio\n```\n\nRefer to [u-root's documentation](https://github.com/u-root/u-root#compression)\nfor more details on compression.\n\n#### Customization\n\nThe `buildimage.go` utility is really just a helper tool. Instead of using it,\nyou can build a custom u-root image as you like and add the `webboot` binary to\nit.\nRefer to [u-root's usage documentation](https://github.com/u-root/u-root#usage)\nfor details.\n\n### Building a kernel for webboot\n\nwebboot uses a standard Linux kernel which should be fairly portable, based on a\nLong Term Stable (LTS) release. It has worked on every Chromebook we tried.\n\nThis kernel is built using a config originally from\n[NiChromeOS](github.com/NiChrome/NiChrome).\nIf we are building a bootable USB stick formatted with vfat, we don't have the\nspace constraints of NiChrome, so we expect this to diverge over time.\n\nNevertheless, to keep it all simple, we build it as a non-modular kernel with\nWi-fi firmware built-in. We no longer build the initramfs into the kernel, as\nthat's not needed.\n\nMake sure the kernel configuration includes the firmware for your network device.\nFor instance, the Thinkpad x240 with Intel Corporation Wireless 7260 uses\niwlwifi-7260-17.ucode. If you look at the kernel config file, this firmware name\nis included under `CONFIG_EXTRA_FIRMWARE=`.\n\nTo build, first be sure you're in a directory you want to be in!\nYou can actually do the work in the webboot root directory because the\n`.gitignore` file ignores the two directories you create when following the\ninstructions here.\n\n#### Prerequisites\n\nYou need to have the following packages installed if on Ubuntu:\n```sh\nsudo apt install libssl-dev build-essential wireless-tools kexec-tools libelf-dev libnl-3-dev libnl-genl-3-dev\n```\n\n#### Fetching, configuring and compiling the kernel\n\n```sh\ngit clone --depth 1 -b v5.6.14 \\\n  git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git linux\ngit clone \\\n  git://git.kernel.org/pub/scm/linux/kernel/git/iwlwifi/linux-firmware.git\ncp config-5.6.14 linux/.config\n(cd linux \u0026\u0026 make bzImage)\nGO111MODULE=off go run .\n```\n\n### Testing in QEMU\n\nInstall QEMU with\n```sh\nsudo apt-get install qemu-system-x86\n```\n\nRun the following, and a QEMU window should pop up:\n\nTip: Don't use the `-nographic` option for u-root in QEMU as you want to boot\ninto a graphical interface.\n\n#### Acceleration\n\nIf you have KVM in your host system, you can add `-enable-kvm` for speedup.\n\n```sh\nqemu-system-x86_64 \\\n  -enable-kvm \\\n  -m 2G \\\n  -kernel linux/arch/x86/boot/bzImage \\\n  -append 'console=ttyS0 console=tty1 memmap=1G!1G' \\\n  -initrd /tmp/initramfs.linux_amd64.cpio \\\n  -device virtio-rng-pci \\\n  -netdev user,id=network0 \\\n  -device rtl8139,netdev=network0\n```\n\nTip: Don't use the `-nographic` option for u-root in QEMU as you want to boot\ninto a graphical interface.\n\nIn the QEMU terminal, run\n```sh\ndhclient -ipv6=f\n```\nand then run\n```sh\nwebboot\n```\n\nRefer to\n[u-root's documentation](https://github.com/u-root/u-root#testing-in-qemu) for\nmore details on virtualization.\n\n### Testing with a USB stick\n\nYou can try out webboot from a USB stick. That means that you could run it when\nstarting a machine by choosing to boot from USB, which requires a bootloader.\nAlthough any bootloader would do, we will focus on one here named `syslinux`.\nFurthermore, we will focus on specific preconditions, although there are many\ndifferent ways to create a bootable USB stick.\n\nIn the root directory of this repository, there is an example configuration file\nnamed `syslinux.cfg.example`. If you look at it, you will see that it resembles\nwebboot very much: It lists a kernel, an initrd, and extra arguments to append.\n\nBefore you continue, please make sure to meet the following conditions:\n\n- your system can boot from MBR (possibly through UEFI CSM)\n- You have a directory `/mnt/usb` to mount the partition to\n\nTo [install](https://wiki.syslinux.org/wiki/index.php?title=Install) syslinux as\na bootloader and configure it, four steps are necessary:\n\n1. Write a Volume Boot Record (VBR) to the stick\n2. Write a Master Boot Record (MBR) to it\n3. Mark the first partition as bootable\n4. Copy the config file, Linux kernel, and initcpio\n\nThe following instructions will walk you through these four steps.\nTip: You may need to replace `sdb1` with the name of your partition.\n\nInstall syslinux with\n```sh\nsudo apt-get install syslinux\n```\n\nTo prepare your USB stick, run `sudo fdisk /dev/sdb` and use the fdisk instructions to complete the following:\n1. Delete all existing partitions (d)\n2. Add one new partition (n, p, 1)\n3. Change partition type (t) to EFI (ef)\n4. Make partition 1 bootable (a)\n5. Save (w)\n\nHere is a sample fdisk output:\n```sh\n$ sudo fdisk /dev/sdb\n\nWelcome to fdisk (util-linux 2.36.1).\nChanges will remain in memory only, until you decide to write them.\nBe careful before using the write command.\n\n\nCommand (m for help): d\nSelected partition 1\nPartition 1 has been deleted.\n\nCommand (m for help): n\nPartition type\n   p   primary (0 primary, 0 extended, 4 free)\n   e   extended (container for logical partitions)\nSelect (default p): p\nPartition number (1-4, default 1): 1\nFirst sector (2048-121061375, default 2048):\nLast sector, +/-sectors or +/-size{K,M,G,T,P} (2048-121061375, default 121061375):\n\nCreated a new partition 1 of type 'Linux' and of size 57.7 GiB.\n\nCommand (m for help): t\nSelected partition 1\nHex code or alias (type L to list all): L\n\n00 Empty            24 NEC DOS          81 Minix / old Lin  bf Solaris\n01 FAT12            27 Hidden NTFS Win  82 Linux swap / So  c1 DRDOS/sec (FAT-\n02 XENIX root       39 Plan 9           83 Linux            c4 DRDOS/sec (FAT-\n03 XENIX usr        3c PartitionMagic   84 OS/2 hidden or   c6 DRDOS/sec (FAT-\n04 FAT16 \u003c32M       40 Venix 80286      85 Linux extended   c7 Syrinx\n05 Extended         41 PPC PReP Boot    86 NTFS volume set  da Non-FS data\n06 FAT16            42 SFS              87 NTFS volume set  db CP/M / CTOS / .\n07 HPFS/NTFS/exFAT  4d QNX4.x           88 Linux plaintext  de Dell Utility\n08 AIX              4e QNX4.x 2nd part  8e Linux LVM        df BootIt\n09 AIX bootable     4f QNX4.x 3rd part  93 Amoeba           e1 DOS access\n0a OS/2 Boot Manag  50 OnTrack DM       94 Amoeba BBT       e3 DOS R/O\n0b W95 FAT32        51 OnTrack DM6 Aux  9f BSD/OS           e4 SpeedStor\n0c W95 FAT32 (LBA)  52 CP/M             a0 IBM Thinkpad hi  ea Linux extended\n0e W95 FAT16 (LBA)  53 OnTrack DM6 Aux  a5 FreeBSD          eb BeOS fs\n0f W95 Ext'd (LBA)  54 OnTrackDM6       a6 OpenBSD          ee GPT\n10 OPUS             55 EZ-Drive         a7 NeXTSTEP         ef EFI (FAT-12/16/\n11 Hidden FAT12     56 Golden Bow       a8 Darwin UFS       f0 Linux/PA-RISC b\n12 Compaq diagnost  5c Priam Edisk      a9 NetBSD           f1 SpeedStor\n14 Hidden FAT16 \u003c3  61 SpeedStor        ab Darwin boot      f4 SpeedStor\n16 Hidden FAT16     63 GNU HURD or Sys  af HFS / HFS+       f2 DOS secondary\n17 Hidden HPFS/NTF  64 Novell Netware   b7 BSDI fs          fb VMware VMFS\n18 AST SmartSleep   65 Novell Netware   b8 BSDI swap        fc VMware VMKCORE\n1b Hidden W95 FAT3  70 DiskSecure Mult  bb Boot Wizard hid  fd Linux raid auto\n1c Hidden W95 FAT3  75 PC/IX            bc Acronis FAT32 L  fe LANstep\n1e Hidden W95 FAT1  80 Old Minix        be Solaris boot     ff BBT\n\nAliases:\n   linux          - 83\n   swap           - 82\n   extended       - 05\n   uefi           - EF\n   raid           - FD\n   lvm            - 8E\n   linuxex        - 85\nHex code or alias (type L to list all): EF\nChanged type of partition 'Linux' to 'EFI (FAT-12/16/32)'.\n\nCommand (m for help): a\nSelected partition 1\nThe bootable flag on partition 1 is enabled now.\n\nCommand (m for help): w\nThe partition table has been altered.\nCalling ioctl() to re-read partition table.\nSyncing disks.\n```\n\nGenerate the partition header\n```sh\nmkfs -t vfat /dev/sdb1\n```\n\nMount the USB and copy the config file, Linux kernel, and initcpio\n```sh\nsudo mount /dev/sdb1 /mnt/usb\ncp config-5.6.14 /mnt/usb/\ncp arch/x86/boot/bzImage /mnt/usb\ncp /tmp/initramfs.linux_amd64.cpio /mnt/usb\numount /mnt/usb\n```\n\nZip initramfs\n```sh\ngzip /tmp/initramfs.linux_amd64.cpio\n```\n\nNow the following commands would need to be run as root:\n\n```sh\nsyslinux -i /dev/sdb1\ndd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr/mbr.bin of=/dev/sdb\nparted /dev/sdb set 1 boot on\n# mount the stick and copy the files\nmount /dev/sdb1 /mnt/usb\ncp syslinux.cfg.example /mnt/usb/syslinux.cfg\nmkdir /mnt/usb/boot\ncp linux/arch/x86/boot/bzImage /mnt/usb/boot/webboot\ncp /tmp/initramfs.linux_amd64.cpio.gz /mnt/usb/boot/webboot.cpio.gz\n```\n\nFinally, we need to create a `/Images` directory at the root of the usb stick. Note that the \"I\" in \"Images\" needs to be capitalized.\n\n```sh\nmkdir /mnt/usb/Images\n```\n\nYou should be able to boot from the USB stick now. Depending on your firmware\nsetup, it might be necessary to get into a boot menu or make changes in the\nsettings.\n\nTo rebuild the USB stick, you can run \n```sh\nsh makeusb.sh sdb1\n```\n","funding_links":[],"categories":["Go","kernel"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-root%2Fwebboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fu-root%2Fwebboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-root%2Fwebboot/lists"}