{"id":13711129,"url":"https://github.com/JamiKettunen/initramfs-tools","last_synced_at":"2025-05-06T20:31:58.215Z","repository":{"id":65818210,"uuid":"361414382","full_name":"JamiKettunen/initramfs-tools","owner":"JamiKettunen","description":"Create small and adaptable Linux initramfs' mainly intended for embedded (e.g. Android) devices.","archived":false,"fork":false,"pushed_at":"2023-05-16T01:31:04.000Z","size":135,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-03T23:23:16.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JamiKettunen.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":"2021-04-25T11:51:11.000Z","updated_at":"2024-07-25T05:34:20.000Z","dependencies_parsed_at":"2024-05-08T00:46:35.644Z","dependency_job_id":null,"html_url":"https://github.com/JamiKettunen/initramfs-tools","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/JamiKettunen%2Finitramfs-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamiKettunen%2Finitramfs-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamiKettunen%2Finitramfs-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamiKettunen%2Finitramfs-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JamiKettunen","download_url":"https://codeload.github.com/JamiKettunen/initramfs-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224528341,"owners_count":17326346,"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":"2024-08-02T23:01:04.813Z","updated_at":"2024-11-13T21:31:31.606Z","avatar_url":"https://github.com/JamiKettunen.png","language":"Shell","funding_links":[],"categories":["Projects"],"sub_categories":[],"readme":"# initramfs-tools\nCreate small and adaptable Linux initramfs' mainly intended for embedded (e.g. Android) devices.\n\n## Building\nCreate a `config.custom.sh`, tweak options defined in [`config.sh`](config.sh) as you please \u0026 simply run the [`build.sh`](build.sh) script:\n```\n$ ./build.sh\n```\nFor e.g. scripting you can additionally add the `-N` flag to avoid interactive actions (or `-c alternate_config.sh` to override [`config.sh`](config.sh) defaults).\n\n## Features\n* An easily configurable environment based around [Buildroot](https://buildroot.org) \u0026 [BusyBox](https://busybox.net)\n* Kernel module support\n* Shell script hook system with ordering and early/late triggers\n  * Execution order is decided by the numbering of the hook filenames\n  * Early triggers run as soon as the initramfs is reached\n  * Late triggers run **after** a rootfs is mounted and **right before** `switch_root`\n  * Optionally extra hooks can be added and triggered manually via kernel cmdline\n* Produced `cpio` archives can be compressed with either `gzip` or `lz4`\n* Optional PPM image splash screens ([or even boot animations with some limitations](https://github.com/JamiKettunen/initramfs-tools/blob/0e66266/config.sh#L87-L107))\n* Ideally boots any OS (distro) using the Linux kernel\n\n## Runtime configuration\nA bunch of the initramfs features can be configured via kernel cmdline using the following options:\n|Option|Example values|Comment|\n|------|--------------|-------|\n|`rd.rootfs`|`/dev/sde21`, `nbd:rootfs:512`|Rootfs location (mandatory!)|\n|`rd.extra_hooks`|`late/extra-hook`, `a,b,c`|Additional hooks to run in initramfs|\n|`rd.mass_storage_rw`|`0` (default) or `1`|Mount all mass storage devices as read-write|\n|`rd.silent_boot`|`0` (default) or `1`|Silence logs from kernel and initramfs, implied on when splash image set|\n|`rd.no_clear`|`0` (default) or `1`|Don't clear console on initramfs enter|\n|`rd.no_fwdcon`|`0` (default) or `1`|Don't forward kernel messages to `tty8` while starting|\n\n## Booting\n* Block device: `rd.rootfs=/dev/sde21`\n* Block device by UUID: e.g. `rd.rootfs=uuid:abcd-1234` or `rd.rootfs=uuid:abcd-1234/rootfs.img`\n* Block device by label: e.g. `rd.rootfs=label:system` or `rd.rootfs=label:system/rootfs.img` \u003csup\u003e1\u003c/sup\u003e\n* Image on a block device: `rd.rootfs=/dev/sda13/rootfs.img`\n* Directory on a block device: `rd.rootfs=/dev/sda13/rootfs_dir`\n* Network Block Device (NBD): `rd.rootfs=nbd` or e.g. `rd.rootfs=nbd:rootfs:512` \u003csup\u003e2\u003c/sup\u003e\n  * A default export name of `rootfs` is assumed unless specified otherwise after the first colon (`:`)\n  * A default block-size of `512` is assumed (choices: `512`, `1024`, `2048` or `4096`) unless specified otherwise after the second colon (`:`)\n* Dynpart under Android super partition: `rd.rootfs=super:system_a` \u003csup\u003e3\u003c/sup\u003e\n\n\u003csup\u003e1\u003c/sup\u003e **NOTE:** Filesystem labels containing `/` aren't supported!\n\u003csup\u003e2\u003c/sup\u003e **WARNING:** Make sure you don't (re)configure USB ConfigFS from userspace, or the network connection will cut out!\u003cbr\u003e\n\u003csup\u003e3\u003c/sup\u003e **NOTE:** Remember to add `BR2_CONFIGS+=\",super_par_mount\"` to your config to build the required extra utilities!\n\n### NBD server example\nHere is an example tree of a NBD server setup I've used successfully:\n```\n├── allowed_clients\n├── nbd_config\n└── rootfs.img\n```\n`allowed_clients`:\n```sh\n# subnet of initramfs RNDIS connection\n172.16.42.0/24\n```\n`nbd_config`:\n```ini\n[generic]\nauthfile = allowed_clients\ncopyonwrite = false\nallowlist = true\nmax_threads = 16\nmaxconnections = 1\ntimeout = 5\n\n[rootfs]\nexportname = \u003cabsolute-path-to-rootfs.img-here\u003e\n```\nWith those files in place you can start a server with `nbd-server -C nbd_config`, confirm output of `nbd-client -l 127.0.0.1` and test network-booting a target device!\n\n## Kernel requirements\nCore\n* `CONFIG_RD_GZIP=y` (if using `gzip` compression)\n* `CONFIG_RD_LZ4=y` (if using `lz4` compression)\n* `CONFIG_DEVTMPFS=y` (populate `/dev` automatically when `devtmpfs` is mounted)\n\nBooting\n* `CONFIG_BLK_DEV_LOOP=m` (booting from loopback images)\n* `CONFIG_BLK_DEV_NBD=m` (NBD rootfs booting)\n\nUSB\n* `CONFIG_USB_GADGET=y` (UDC core driver)\n* `CONFIG_USB_CONFIGFS=m` (configure USB via ConfigFS)\n* `CONFIG_USB_CONFIGFS_RNDIS=y` (enable RNDIS access)\n* `CONFIG_USB_CONFIGFS_MASS_STORAGE=y` (enable Mass Storage access)\n\n## Debugging\nIf you have a working virtual console, you should have logs visible on the display itself.\n\nOtherwise assuming the `configfs`, `rndis` and `telnet` hooks are on the initramfs, you should be able to use `telnet 172.16.42.1` to gain an ash shell on the target device.\n\nTo view the boot console (display) from telnet, you can use `conspy`.\n\n## Silent boot\nAdding `console=tty2 vt.global_cursor_default=0` to kernel cmdline appears to have helped with Void \u0026 Arch Linux at least and allowed the boot splash to show up without issues.\n\nKeep in mind if disabling global VT cursor you should re-enable it on a per-rootfs basis with the following:\n```\n# setterm -cursor on \u003e\u003e /etc/issue\n```\n\nAdding `audit=0` might also help especially on distros using systemd init.\n\n## License\nAll code in this repository is licensed under a [`GPL-3.0-only`](LICENSE) license.\n\n## To-Do\n* Fix [`list_pars()`](functions/blk.sh) to work with eMMC partitions\n* Minimal BusyBox config\n* Recursive hook depdendencies\n* Booting from a block devices based on UUID?\n* Booting from subpartitions (e.g. stock postmarketOS setup) via e.g. `rd.rootfs.subpars`\n* Booting LVM/LUKS2 encrypted root?\n* Mount options for root via e.g. `rd.mount_opts`\n* x86 support?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJamiKettunen%2Finitramfs-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJamiKettunen%2Finitramfs-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJamiKettunen%2Finitramfs-tools/lists"}