{"id":18519296,"url":"https://github.com/linux-surface/aarch64-arch-mkimg","last_synced_at":"2026-01-04T00:28:06.617Z","repository":{"id":44725771,"uuid":"512559458","full_name":"linux-surface/aarch64-arch-mkimg","owner":"linux-surface","description":"Scripts to create Arch Linux AArch64 disk images (e.g. for flashing to a USB stick), adapted for the Surface Pro X","archived":false,"fork":false,"pushed_at":"2025-03-09T02:49:30.000Z","size":54,"stargazers_count":16,"open_issues_count":1,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-24T04:05:35.879Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/linux-surface.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}},"created_at":"2022-07-10T23:14:10.000Z","updated_at":"2025-03-09T02:49:26.000Z","dependencies_parsed_at":"2023-02-17T12:45:30.730Z","dependency_job_id":null,"html_url":"https://github.com/linux-surface/aarch64-arch-mkimg","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-surface%2Faarch64-arch-mkimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-surface%2Faarch64-arch-mkimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-surface%2Faarch64-arch-mkimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-surface%2Faarch64-arch-mkimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-surface","download_url":"https://codeload.github.com/linux-surface/aarch64-arch-mkimg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248003316,"owners_count":21031770,"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-11-06T17:16:00.030Z","updated_at":"2026-01-04T00:28:06.591Z","avatar_url":"https://github.com/linux-surface.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AArch64 Arch Linux Bootable Disk Image Utility\n\nUtility to create a bootable and easily customizable AArch64 Arch Linux disk image.\nSupports running on x86 hosts via `binfmt_misc` and `qemu-user-static`.\n\n\n## Usage\n\nThe `aarch64-arch-mkimage` utility allows for multiple profiles, which, in essence, shape the generated disk image.\nSee notes below for running on an x86 host system.\n\nRunning the script directly requires an Arch Linux host system.\nTo build a disk image or file system trees, run\n```\nsudo ./aarch64-arch-mkimg \u003cprofile\u003e\n```\nwhere `\u003cprofile\u003e` is the desired profile.\nOutputs and intermediate build files are stored in `./build`.\nDisk images are written to `./build/disk.img` and final file system trees to `./build/disk/root` for the root partition and `./build/disk/efi` for the EFI/EFS partition.\n\nYou can also run the script via the provided Docker container (e.g. in case you do not have access to an Arch Linux host system).\nA pre-built container for an x86 host can be obtained via\n```\ndocker pull ghcr.io/linux-surface/aarch64-arch-mkimg\n```\nDisk images can then be generated via\n```\ndocker run --rm --privileged                  \\\n    --mount type=tmpfs,destination=/run/shm   \\\n    -v /dev:/dev                              \\\n    -v \"${PWD}/build\":/build                  \\\n    aarch64-arch-mkimg \u003cprofile\u003e\n```\n\nDefault login credentials are the ones provided by the Arch Linux ARM root file system, i.e. user/password `alarm`/`alarm` and `root`/`root`.\nNote that, by default, an OpenSSH server is running.\nTherefore, please do not connect this machine directly to the internet (without firewall) before changing those.\n\n\n### Running on an x86 Host\n\nTo run this script on an x86 host, emulation for AArch64 is needed.\nThis can be set up via `binfmt_misc` and `qemu-user-static`.\nSee e.g. https://github.com/multiarch/qemu-user-static for details on how to set this up.\nIn short, running\n```\ndocker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n```\nshould set everything up for you.\n\n\n### Details\n\nThe `aarch64-arch-mkimage` utility works in three major steps:\n1. The basic root file system (rootfs) is prepared using the official Arch Linux ARM root archive and base files specified in the profile (`profiles/\u003cname\u003e/base`, these are simply copied to the rootfs tree).\n2. The utility switches into the prepared root tree via `arch-chroot`.\n   Here, requested packages (`profiles/name/packages`) are installed or uninstalled and customizations to the rootfs specified via the respective profile modules (`profiles/\u003cname\u003e/modules`) are applied.\n3. Depending on the profile, a disk image and/or root and EFI file system trees are generated from the final rootfs.\n   These are provided in `build/disk.img` and `build/disk/efi` as well as `build/disk/root`.\n\n\n## Profiles\n\n- `default`: This profile builds an initramfs from the rootfs and packs this up inside an otherwise small boot partition.\n  The resulting image boots fully in ram, however, boot times will be slow and the system might seem stuck during boot at times.\n  This also means that any changes you make will not persist across reboots.\n  This is mostly intended as a basic installation media.\n\n  To use this profile, simply flash the created `build/disk.img` to a USB stick, e.g. via\n  ```\n  dd if=build/disk.img of=/dev/sdX bs=1m \u0026\u0026 sync\n  ```\n\n- `persistent`: This profile generates EFI and root partition file systems intended for use in a persistent scenario.\n  Unfortunately, this means that a full disk image cannot be created automatically (the file system sizes are unknown).\n  Therefore, this profile outputs only file system trees at `build/disk/efi` and `build/disk/root`.\n\n  To use this profile, format the USB stick, e.g. via `gdisk` and create an EFI (`gdisk` type `ef00`) partition with 128Mib and a root partition (`gdisk` type `8300` or `8304`).\n  You can adapt the partition sizes as needed.\n  Assuming the USB stick is present as `/dev/sdX`, this translates to the following `sgdisk` commands:\n  ```\n  sgdisk /dev/sdX -n 0:0:+128MiB -t 0:ef00 -c 0:efi\n  sgdisk /dev/sdX -n 0:0:+ -t 0:8300 -c 0:boot\n  partprobe\n  ```\n\n  Thereafter, format partitions, e.g. via\n  ```\n  mkfs.fat -F 32 /dev/sdX1\n  mkfs.ext4 /dev/sdX2\n  ```\n\n  Finally, mount EFI and root partitions and copy over the respective file system trees, e.g. via\n  ```\n  # mount partitions\n  mkdir -p /mnt/{efi,root}\n  mount /dev/sdX1 /mnt/efi\n  mount /dev/sdX2 /mnt/root\n\n  # copy files\n  cp -a build/disk/efi/. /mnt/efi     # EFI partition\n  cp -a build/disk/root/. /mnt/root   # root partition\n  sync\n\n  # unmount partitions\n  umount /dev/sdX1\n  umount /dev/sdX2\n  rm -rf /mnt/{efi,root}\n  ```\n\n\n## Customization\n\nYou can create or adapt custom profiles.\nEach profile provides:\n\n- A `profile.sh` script detailing the build steps.\n\n- A `base` directory, containing additional or replacement files copied directly to the rootfs.\n  Files provided here are copied over the Arch Linux ARM rootfs.\n\n- A `packages` directory specifying the packages to install or uninstall\n  The `packages/install` file contains a list of packages to be installed.\n  The `packages/uninstall` file contains a list of packages to be uninstalled.\n  The `packages/custom` directory can contain optional pre-built packages.\n  Packages will first be uninstalled, then the chroot system will be updated, new packages will be installed, and finally any custom pre-built packages will be installed.\n\n- A `modules` directory containing module files for rootfs customization.\n  Each module can provide a `setup()` and an `install()` function.\n  Both will be called in the chroot environment.\n  The `setup()` function will be called before any packages are installed and can e.g. be used to add custom repositories.\n  The `install()` function will be called after the requested packages have been installed.\n\nSee the provided profiles for examples.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-surface%2Faarch64-arch-mkimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-surface%2Faarch64-arch-mkimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-surface%2Faarch64-arch-mkimg/lists"}