{"id":30651149,"url":"https://github.com/fonic/arch-uki-luks2","last_synced_at":"2026-05-03T23:32:05.849Z","repository":{"id":305841978,"uuid":"1023708022","full_name":"fonic/arch-uki-luks2","owner":"fonic","description":"Hooks for pacman/pamac to automatically configure and generate Unified Kernel Images (UKIs) and for mkinitcpio to unlock dm-crypt/LUKS2 encrypted volumes during boot, allowing for a GRUB-less LUKS2 full disk encryption setup","archived":false,"fork":false,"pushed_at":"2025-07-26T08:58:48.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T06:13:21.238Z","etag":null,"topics":["arch-linux","archlinux","dm-crypt","encryption","fde","full-disk-encryption","grub","initcpio","linux","luks","luks2","manjaro","manjaro-linux","mkinitcpio","pacman","pamac","uki","unified-kernel-image"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fonic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-07-21T15:11:38.000Z","updated_at":"2025-08-21T18:52:17.000Z","dependencies_parsed_at":"2025-07-22T09:47:39.631Z","dependency_job_id":null,"html_url":"https://github.com/fonic/arch-uki-luks2","commit_stats":null,"previous_names":["fonic/arch-uki-luks2"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fonic/arch-uki-luks2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fonic%2Farch-uki-luks2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fonic%2Farch-uki-luks2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fonic%2Farch-uki-luks2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fonic%2Farch-uki-luks2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fonic","download_url":"https://codeload.github.com/fonic/arch-uki-luks2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fonic%2Farch-uki-luks2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32589069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["arch-linux","archlinux","dm-crypt","encryption","fde","full-disk-encryption","grub","initcpio","linux","luks","luks2","manjaro","manjaro-linux","mkinitcpio","pacman","pamac","uki","unified-kernel-image"],"created_at":"2025-08-31T06:02:24.516Z","updated_at":"2026-05-03T23:32:05.843Z","avatar_url":"https://github.com/fonic.png","language":"Shell","funding_links":["https://www.buymeacoffee.com/fonic","https://paypal.me/fonicmaxxim","https://ko-fi.com/fonic"],"categories":[],"sub_categories":[],"readme":"# Arch Linux / Manjaro with UKI and LUKS2 encryption\n\nHooks for `pacman`/`pamac` to automatically configure and generate [Unified\nKernel Images (UKIs)](https://wiki.archlinux.org/title/Unified_kernel_image)\nand for `mkinitcpio` to unlock _dm-crypt/LUKS2_ encrypted volumes during boot,\nallowing for a GRUB-less LUKS2 full disk encryption setup.\n\n\n## Donations\n\nI'm a strong supporter of [Free and open-source software (FOSS)](https://en.wikipedia.org/wiki/Free_and_open-source_software).\nDonations help keeping my projects alive and are highly appreciated.\n\n\u003ca href=\"https://www.buymeacoffee.com/fonic\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/fonic/donate-buttons/main/buymeacoffee-button.png\" alt=\"Buy Me A Coffee\" height=\"35\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://paypal.me/fonicmaxxim\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/fonic/donate-buttons/main/paypal-button.png\" alt=\"Donate via PayPal\" height=\"35\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://ko-fi.com/fonic\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/fonic/donate-buttons/main/kofi-button.png\" alt=\"Donate via Ko-fi\" height=\"35\"\u003e\u003c/a\u003e\n\n\n## Disclaimer\n\n**Use this at you own risk!** Only recommended for advanced users! Make sure\nto backup your system before applying any changes! Thoroughly review all code\nto make sure it does what you expect!\n\n\n## How it works\n\nThe `pacman`/`pamac` hooks monitor changes of Linux kernel packages (install,\nremove, upgrade). If a change is detected, the respective kernel is configured\nfor UKI use (by altering its `.preset` file in `/etc/mkinitcpio.d`) and two\nUKIs (_default_ for normal use, _fallback_ for recovery purposes) are generated\nvia `mkinitcpio` and installed to the EFI System Partition (ESP).\n\nThe `mkinitcpio` hook is similar to the stock `encrypt` hook, but features\nzero-config unlocking of encrypted volumes (by locating and unlocking all\n`TYPE=\"crypto_LUKS\"` volumes) in addition to renaming corresponding device\nmapper nodes based on file system labels (e.g. `/dev/mapper/luks-\u003cUUID\u003e` gets\nrenamed to `/dev/mapper/luks-root`). This is especially useful for systems\nwhich have _multiple_ encrypted volumes that all share the same password (e.g.\nroot + swap + home).\n\n\n## Pros and Cons\n\n**Pros UKI vs. GRUB:**\u003cbr/\u003e\n- [X] Unlocking LUKS2 volumes is supported without patching GRUB (or any other\n      components)\n- [X] No GRUB, i.e. one less component to worry about (which might have bugs or\n      expose vulnerabilities)\n- [X] Integrates perfectly with _Secure Boot_ (UKIs get signed automatically by\n      `sbctl` hooks without requiring any additional configuration)\n- [X] Well-suited if there is only a single OS installed that needs to be booted\n\n**Cons UKI vs. GRUB:**\u003cbr/\u003e\n- [ ] Kernel command line cannot be changed on demand (e.g. to fix boot issues\n      after system upgrades) **(\\*)**\n- [ ] Requires a larger ESP as UKIs can get quite large (depending on included\n      files/modules)\n- [ ] Some UEFIs have trouble maintaining their boot order when entries are\n      added/removed (e.g. due to kernel upgrades)\n- [ ] No fancy boot selection menu (unless the machine's UEFI itself provides\n      one)\n\n**(\\*)** The _fallback_ UKI provides a pre-configurable recovery option for\nthis scenario, though.\n\n\n## Installation\n\n1. Prepare a dm-crypt/LUKS2 encrypted disk containing Arch Linux / Manjaro:\u003cbr/\u003e\n   **Not covered here as detailed guides on that topic are widely available\n   (e.g. see [Arch Linux Wiki](https://wiki.archlinux.org/title/Dm-crypt/Encrypting_an_entire_system)).**\n   \n   **The easiest approach might be to use _two_ separate devices:**\u003cbr/\u003e\n   Perform a normal (unencrypted) installation to the first device, then\n   prepare the second encrypted device manually (erase, partition, encrypt,\n   unlock, create file systems, mount file systems), then migrate all OS\n   data from the first device to the newly set-up encrypted device (e.g.\n   using `rsync`).\n\n   The fully set-up encrypted disk might look like this:\n\n   ```\n   # fdisk -l /dev/nvme0n1\n\n   Device          Start  End  Sectors  Size  Type\n   /dev/nvme0n1p1    ...  ...      ...    1G  EFI System            -\u003e EFI System Partition (ESP)\n   /dev/nvme0n1p2    ...  ...      ...  100G  Linux filesystem      -\u003e Root Partition\n   /dev/nvme0n1p3    ...  ...      ...  1,5T  Linux filesystem      -\u003e Home Partition\n   /dev/nvme0n1p4    ...  ...      ...   64G  Linux filesystem      -\u003e Swap Partition\n   ```\n\n   ```\n   # blkid | grep nvme0n1\n\n   /dev/nvme0n1p1:  LABEL=\"efi\"  UUID=\"...\"  TYPE=\"vfat\"            -\u003e Unencrypted EFI System Partition (ESP)\n   /dev/nvme0n1p2:               UUID=\"...\"  TYPE=\"crypto_LUKS\"     -\u003e Encrypted Root Partition\n   /dev/nvme0n1p3:               UUID=\"...\"  TYPE=\"crypto_LUKS\"     -\u003e Encrypted Home Partition\n   /dev/nvme0n1p4:               UUID=\"...\"  TYPE=\"crypto_LUKS\"     -\u003e Encrypted Swap Partition\n   ```\n\n   ```\n   # blkid | grep mapper\n\n   /dev/mapper/luks-root:  LABEL=\"root\"  UUID=\"...\"  TYPE=\"ext4\"    -\u003e Unlocked Root Partition\n   /dev/mapper/luks-home:  LABEL=\"home\"  UUID=\"...\"  TYPE=\"ext4\"    -\u003e Unlocked Home Partition\n   /dev/mapper/luks-swap:  LABEL=\"swap\"  UUID=\"...\"  TYPE=\"swap\"    -\u003e Unlocked Swap Partition\n   ```\n\n   **NOTE:** UKIs can get quite large (depending on included files/modules),\n             thus the ESP should be **1G** or more in size (especially when\n             multiple kernels are installed at the same time)\u003cbr/\u003e\n   **NOTE:** make sure to assign file system labels if you want the mkinitcpio\n             hook (`encrypt-auto`) to rename device mapper nodes (optional)\n\n2. Download and extract a [release](https://github.com/fonic/arch-uki-luks2/releases)\n   of this project:\u003cbr/\u003e\n   [Link to latest release](https://github.com/fonic/arch-uki-luks2/releases/latest)\n\n3. Copy contents of folder `etc` to encrypted root file system (to install\n   the hooks):\n   ```\n   # cp -r arch-uki-luks2/etc /mnt/luks-root\n   ```\n   **NOTE:** this assumes the unlocked encrypted root file system\n             `/dev/mapper/luks-root` is mounted to `/mnt/luks-root`\n\n4. Edit `/etc/mkinitcpio.conf` and add hook `encrypt-auto` to `HOOKS=(...)`:\n   ```\n   HOOKS=(... mdadm_udev encrypt-auto resume filesystems fsck)\n   ```\n   **NOTE:** place `auto-encrypt` _after_ `mdadm_udev` if the system has\n             encrypted RAID arrays that shall be unlocked\u003cbr/\u003e\n   **NOTE:** place `auto-encrypt` _before_ `resume` to be able to resume\n             (from hibernation) from an encrypted swap partition\n\n5. Edit `/etc/pacman.d/hooks.bin/uki-manager.conf` and adjust these settings\n   to match your system:\n   ```\n   UBM_DISK=\"/dev/disk/by-id/\u003cdisk-id\u003e\"    # Disk where EFI System Partition (ESP) is located (via id)\n   UBM_PART=1                              # Partition number of EFI System Partition (ESP) on disk\n   ```\n   **NOTE:** it is highly recommended to use `/dev/disk/by-id/...` instead\n             of device nodes like `/dev/nvme0n1` or `/dev/sda` for `UBM_DISK`,\n             as the latter are **not** guaranteed to maintain their particular\n             order from one boot to another (e.g. devices referenced via\n             `/dev/nvme0n1` and `/dev/nvme1n1` might switch places)\n\n6. Edit `/etc/kernel/cmdline-default` and `/etc/kernel/cmdline-fallback` and\n   adjust their contents to match your system\u003cbr/\u003e\n   **NOTE:** these files contain the _kernel command line_ for the _default_\n             and _fallback_ UKIs\u003cbr/\u003e\n   **NOTE:** use `cat /proc/cmdline` to display your current kernel command\n             line\n\n7. Reinstall kernel package(s) to generate UKIs and install them to the ESP:\n   ```\n   # pacman -S linuxXY\n   ```\n   -or-\n   ```\n   $ pamac reinstall linuxXY\n   ```\n   **NOTE:** replace `XY` with your desired kernel version (e.g. `linux612`)\n\n8. Check if UKIs were properly generated and installed:\n   ```\n   # ls -lh /boot/efi/EFI/linux\n   ```\n   Output should look like this:\n   ```\n   -rwx------ 1 root root 30M Jul 20 18:00 linux-linux612-default.efi\n   -rwx------ 1 root root 30M Jul 20 18:00 linux-linux612-fallback.efi\n   ```\n\n9. Check if UKIs were properly added to UEFI boot table:\n   ```\n   # efibootmgr\n   ```\n   Output should look like this:\n   ```\n   BootOrder: 0001,0002\n   Boot0001*  Linux (6.12-x86_64) (default)   HD(1,GPT,...,0x800,0x200000)/\\EFI\\linux\\linux-linux612-default.efi\n   Boot0002*  Linux (6.12-x86_64) (fallback)  HD(1,GPT,...,0x800,0x200000)/\\EFI\\linux\\linux-linux612-fallback.efi\n   ```\n\n10. Reboot, enter UEFI setup and configure a `Linux (...) (default)` entry as\n    the default boot entry (optional)\n\n11. (Re-)Boot system using a `Linux (...) (default)` boot entry and check if\n    unlocking/booting works as expected\n\n12. **All done.** Everything should be maintained automatically from now on\n    (e.g. when performing system upgrades). Just make sure to keep an eye on\n    `efibootmgr` as some UEFIs tend to mess up the boot order when entries are\n    added/removed.\n\n##\n\n_Last updated: 07/25/25_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffonic%2Farch-uki-luks2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffonic%2Farch-uki-luks2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffonic%2Farch-uki-luks2/lists"}