{"id":19638308,"url":"https://github.com/9001/asm","last_synced_at":"2025-10-05T20:21:07.507Z","repository":{"id":181809400,"uuid":"657975562","full_name":"9001/asm","owner":"9001","description":"scriptable runtime-writable livecd / hardware wrangler","archived":false,"fork":false,"pushed_at":"2025-04-23T18:48:29.000Z","size":309,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"hovudstraum","last_synced_at":"2025-04-23T19:47:40.876Z","etag":null,"topics":["alpine","livecd","liveusb","secureboot","uki"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/9001.png","metadata":{"files":{"readme":"README-asm.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,"zenodo":null}},"created_at":"2023-06-24T11:32:18.000Z","updated_at":"2025-04-23T18:48:33.000Z","dependencies_parsed_at":"2023-11-14T03:21:44.806Z","dependency_job_id":"37b12359-73fd-473d-89da-0c06721064bf","html_url":"https://github.com/9001/asm","commit_stats":null,"previous_names":["9001/asm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9001%2Fasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9001%2Fasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9001%2Fasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9001%2Fasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/9001","download_url":"https://codeload.github.com/9001/asm/tar.gz/refs/heads/hovudstraum","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251295085,"owners_count":21566394,"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":["alpine","livecd","liveusb","secureboot","uki"],"created_at":"2024-11-11T12:38:13.524Z","updated_at":"2025-10-05T20:21:02.456Z","avatar_url":"https://github.com/9001.png","language":"Shell","readme":"# alpine-service-mode\n\n* write this to a usb flashdrive and [`./sm/asm.sh`](./sm/asm.sh) will be executed on bootup\n* good for fixing headless boxes or just general hardware wrangling\n* based on [Alpine Linux](https://alpinelinux.org/), runs anywhere\n  * definitely supports `i386/x86` // `amd64/x64`\n  * probably supports `armv7` // `aarch64` // `ppc64le` // `s390x` // `loongarch`\n\n\n## what does it do\n\nthe example [`asm.sh`](./sm/asm.sh) shows a menu with some demo features:\n\n* `1` shows a list of local HDDs and asks for a selection\n  * maybe for entering a chroot or something\n* `i` collects a bunch of hardware info and saves it to `sm/infos` on the flashdrive\n* `n` starts networking and `sshd` after asking for `s`tatic or `d`ynamic IP\n* `z` exits to a shell with `exit 0`\n* `x` does an `exit 1` which also gives a shell but with `vim` and `tmux` preinstalled\n* `k` shutdown\n* `r` reboot\n\nit plays the [pc98 bootup bleep](https://www.youtube.com/watch?v=9qof0qye1ao#t=6m28s) to let you know it's at the menu in case you don't have a monitor\n\n* you can mute SFX by creating a file named `sm/quiet` on the flashdrive\n  * or beep even more with `grub_beep` in [post-build-2.sh](https://github.com/9001/asm/blob/hovudstraum/p/big/sm/post-build-2.sh)\n  * or if the beeps don't work, add `tinyalsa` to recommended_apks in your post-build-2\n\nsee [profiles](./p/) for additional examples including a chatserver, a disk wiper and a webkiosk\n\nsee [logging](./doc/notes.md#logging) to log stdout to serial and/or a file on the flashdrive, and/or launch interactive shells on consoles\n\n\n## secureboot\n\nthe [uki profile](./p/uki/) shows how to securely verify the integrity of all resources during boot, using secureboot and (a bespoke alternative to) measured boot\n\n\n# build it\n\nif you are on linux or macos,\n* install qemu and run [`./build.sh`](./build.sh)\n* you will get `asm.usb` which you can write to a usb flashdrive\n  * can additionally produce a hybrid ISO for burning to CD/DVD with `-oi`\n\noptionally specify `-cb alpine:latest` to disable qemu and use podman/docker instead; about 12 sec faster but has too many drawbacks to be recommended (cannot crosscompile, not as reliable or predictable, requires root + access to /dev for losetup, a typo in postbuild can wipe your HDD, is less cool)\n\nand, if all else fails, a very basic build can be made [manually](./doc/manual-build.md) instead of using [`./build.sh`](./build.sh) at all\n\n\n## write it to a flashdrive\n\n* on linux, `cat asm.usb \u003e/dev/sdi`\n* on windows, either use [rufus](https://github.com/pbatard/rufus/releases/) or [USBimager (Recommended)](https://bztsrc.gitlab.io/usbimager/)\n  * you want the `GDI wo` edition of USBimager -- the default choice when visiting that URL on windows\n  * usbimager v1.0.9 is 10x faster than rufus if you are repeatedly writing similar usb images to the same flashdrive\n  * rufus v3.15 permanently unmounts the flashdrive when done, so run [rufus-unhide.bat](./doc/rufus-unhide.bat) afterwards\n  * do not use balenaEtcher, it is spyware\n\n**tip:** if the flashdrive is larger than the image, it is safe and recommended to add a \"data\" partition to the flashdrive after writing the image:\n* on windows, use the win10 `Disk Management` utility, or better yet:\n* on linux, `echo ,,07 | sfdisk -a /dev/sdi` (followed by `mkfs.ntfs -fL ASM2 /dev/sdi2` if there is no existing filesystem to keep)\n  * linux-only bonus: you can write a new asm image onto the flashdrive without losing anything on the data partition, as long as the new build is the same size or smaller -- just need to issue the sfdisk command again\n    * linux-only because windows is very persistent in blanking any filesystem headers it can find\n\n\n## write it to a CD\n\n* if you haven't made an `asm.iso` yet, convert an existing `asm.usb` with `./u2i.sh asm.usb asm.iso`\n* optionally PGO the iso (runs 30% faster) by capturing the access pattern of a vm booting it\n  1. start the tracer: `./utils/isotrace.py asm.iso asm.wl`\n  2. start the vm: `qemu-system-x86_64 -enable-kvm -vga qxl -cpu host -m 1024 -audio pa,model=hda --drive file=nbd:127.0.0.1:2031`\n  3. do things you expect to do at runtime (install packages etc.) then alt-f4 the vm\n  4. build optimized iso: `./u2i.sh asm.usb asm.iso -wl asm.wl`\n* burn it: `wodim -dao speed=0 -v -data asm.iso`\n  * `-dao` runs better than `-tao` but some drives from the 90s can only read `-tao`\n\n\n## rapid prototyping\n\nif you are working on `asm.sh` and you're testing your image by repeatedly making an iso and booting that in virtualbox/vmware/bare-metal, it would be much faster to instead mount asm.usb and make changes directly inside the image, and then use `u2i.sh` to build the iso from the mounted folder instead of doing a full build:\n\n```bash\nmkdir -p m; mount -o offset=1048576,uid=1000 asm.usb m\n# make changes inside m, leave it mounted and\n# do the following to make an iso whenever:\n./u2i.sh m asm.iso\ncat \u003casm.iso \u003e/dev/sdx\n```\n\n* `cat \u003casm.iso \u003e/dev/sdx` can be replaced with `revert /dev/sdx \u003casm.iso` for much faster writes; see [revert](https://github.com/9001/usr-local-bin/blob/master/revert)\n* if you need secureboot / measured-boot, run this before u2i: `./mod.sh -u m -ak ~/keys/asm.key`\n* you still need to do a full build when you change the set of included packages or make changes to the initramfs\n\n\n# make it your own\n\nthe recommended / intended way to replace the demos / examples with your own stuff is to create [profiles/overlays](#profiles) with your logic and payloads -- see [the examples](./p/) for some inspiration\n\nyou should never have to modify [`./build.sh`](./build.sh) since that should JustWork, so let me know if there's something i've missed\n\n\n## custom build steps\n\n[`./sm/post-build.sh`](./sm/post-build.sh) is executed in the build-env right before the end\n\nby default it does nothing but it provides a library of helpers / examples,\n* an rshell for prototyping / debugging your extensions\n* shrinking the output image\n* adding more APKs\n\nsee how the profiles extend it by providing a `post-build-2.sh` which gets chainloaded:\n\n\n## [profiles](./p/)\n\nif you are building several images with different contents (bootscripts, initramfs, ...) you can use the `-p` option to specify a [profile/overlay](./p/) which will replace corresponding files inside `sm` and `etc` at build-time\n\n\n# compatibility\n\nshould work on most BIOS and UEFI boxes with a few exceptions;\n\n1. BIOS boxes too ancient and buggy, requiring a proper hybrid-iso\n  * **workaround:** use `-oi` to create a read-only hybrid iso\n\n2. UEFI-only boxes which refuse to boot from MBR\n  * **workaround:** modify the fdisk/sfdisk invocation to build a GPT-formatted flashdrive instead of MBR, killing BIOS support\n\n\n# alternatives\n\n* [mkosi](https://github.com/systemd/mkosi) ([article](https://fedoramagazine.org/create-images-directly-from-rhel-and-rhel-ubi-package-using-mkosi/)) looks interesting (but doesn't support alpine yet)\n\n\n# notes\n\n* [`./winpe/`](./winpe/) is unrelated bonus content\n\n* details on [how it works](./doc/how-it-works.md)\n\n* see [`./doc/notes.md`](./doc/notes.md) for more\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9001%2Fasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F9001%2Fasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9001%2Fasm/lists"}