{"id":31796864,"url":"https://github.com/phantom-node/cryptreboot","last_synced_at":"2025-10-10T20:53:25.421Z","repository":{"id":179919826,"uuid":"645936233","full_name":"phantom-node/cryptreboot","owner":"phantom-node","description":"Convenient reboot for Linux systems with encrypted root partition.","archived":false,"fork":false,"pushed_at":"2025-04-07T17:08:25.000Z","size":32928,"stargazers_count":35,"open_issues_count":6,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-05T14:24:10.043Z","etag":null,"topics":["initramfs","kexec","luks","privacy","ruby"],"latest_commit_sha":null,"homepage":"https://phantomno.de/cryptreboot","language":"Ruby","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/phantom-node.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-05-26T19:55:22.000Z","updated_at":"2025-09-17T20:32:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"b59a4fdd-d521-443e-9fea-67518f1d163a","html_url":"https://github.com/phantom-node/cryptreboot","commit_stats":null,"previous_names":["phantom-node/cryptreboot"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/phantom-node/cryptreboot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantom-node%2Fcryptreboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantom-node%2Fcryptreboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantom-node%2Fcryptreboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantom-node%2Fcryptreboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phantom-node","download_url":"https://codeload.github.com/phantom-node/cryptreboot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantom-node%2Fcryptreboot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005255,"owners_count":26083864,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["initramfs","kexec","luks","privacy","ruby"],"created_at":"2025-10-10T20:52:57.609Z","updated_at":"2025-10-10T20:53:25.416Z","avatar_url":"https://github.com/phantom-node.png","language":"Ruby","readme":"# Cryptreboot\n\n[![Gem Version](https://badge.fury.io/rb/crypt_reboot.svg)](https://badge.fury.io/rb/crypt_reboot)\n\nConvenient reboot for Linux systems with encrypted root partition.\n\n\u003e Just type `cryptreboot` instead of `reboot`.\n\nIt asks for a passphrase and reboots the system afterward, automatically\nunlocking the drive on startup using\n[in-memory initramfs patching and kexec](https://www.pawelpokrywka.com/p/rebooting-linux-with-encrypted-disk).\nWithout explicit consent, no secrets are stored on disk, even temporarily.\n\nUseful when unlocking the drive at startup is difficult, such as on headless\nand remote systems.\n\nBy default, it uses the current kernel command line, `/boot/vmlinuz` as kernel\nand `/boot/initrd.img` as initramfs.\n\nWill work properly when using standard passphrase-based disk unlocking.\nFancy methods such as using an external USB with a passphrase file will fail.\n\n## Supported disk encryption methods\n\n### LUKS crypttab\nLUKS-based disk-encryption configured with `/etc/crypttab` file.\n\n### ZFS keystore\nNative ZFS encryption with LUKS-encrypted keystore volume.\n\n## Compatible Linux distributions\n\nCurrently, cryptreboot depends on `initramfs-tools` package which is available in\nDebian-based distributions. Therefore one should expect, this tool to work on\nDebian, Ubuntu, Linux Mint, Pop!_OS, etc.\n\nOn the other hand, do not expect it to work on other distributions now.\nBut support for them may come in upcoming versions.\n\nFollowing distributions were tested by the author on the AMD64 machine:\n\n- LUKS crypttab disk encryption method\n  - DappNode 0.2.75 is based on Debian 12, see below\n  - Debian 12 needs [symlinks for kernel and initramfs](#no-symlinks-to-most-recent-kernel-and-initramfs)\n  - Pop!_OS 22.04 LTS\n  - Ubuntu 24.04 LTS\n  - Ubuntu 23.04\n  - Ubuntu 22.04 LTS\n  - Ubuntu 20.04 LTS needs tiny adjustments to system settings,\n    specifically [changing compression](#lz4-initramfs-compression) and\n    [fixing systemd kexec support](#staged-kernel-not-being-executed-by-systemd), but still\n    [sometimes](#unable-to-kexec-on-reboot-using-old-systemd) reboot experience may be suboptimal\n  - ~~Ubuntu 18.04 LTS~~ is not supported (initramfs uses *pre-crypttab* format)\n\n- ZFS keystore disk encryption method\n  - Ubuntu 24.04 LTS\n  - Ubuntu 22.04 LTS\n\nIf you have successfully run cryptreboot on another distribution,\nplease contact me and I will update the list.\n\n## Requirements\n\nYou need to ensure those are installed:\n- `ruby` \u003e= 2.7\n- `kexec-tools`\n- `initramfs-tools` (other initramfs generators, such as `dracut` are\n  not supported yet)\n\nIf you use recent, mainstream Linux distribution, other requirements are\nprobably already met:\n- `kexec` support in the kernel\n- `ramfs` filesystem support in kernel\n- `cryptsetup` (if you use disk encryption, it should be installed)\n- `systemd` or another way to guarantee staged kernel is executed on reboot\n- `strace` (not required if `--skip-lz4-check` flag is specified)\n\nIf you use Debian-based distribution, use this command to install required packages:\n\n    $ sudo apt install --no-install-recommends cryptsetup-initramfs kexec-tools ruby strace systemd\n\nWhen asked if kexec should handle reboots, answer `yes` (however the answer probably\ndoesn't matter for cryptreboot to work).\n\n## Installation\n\nMake sure the required software is installed, then install the gem system-wide by executing:\n\n    $ sudo gem install crypt_reboot\n\nTo upgrade run:\n\n    $ sudo gem update crypt_reboot\n\n## Usage\n\nCryptreboot performs operations normally only available to the root user,\nso it is suggested to use sudo or a similar utility.\n\nTo perform a reboot type:\n\n    $ sudo cryptreboot\n\nTo see the usage, run:\n\n    $ cryptreboot --help\n\n## Troubleshooting\n\n### LZ4 initramfs compression\n\nIf you get:\n\n\u003e LZ4 compression is not allowed, change the compression algorithm in\ninitramfs.conf and regenerate the initramfs image\n\nit means initramfs was compressed using the LZ4 algorithm, which seems to\nhave issues with concatenating initramfs images.\n\nIn case you are 100% sure LZ4 won't cause problems, you can use\n`--skip-lz4-check` command line flag. This will make the error message\ngo away, but you risk automatic disk unlocking at startup to fail randomly.\n\nInstead, the recommended approach is to change the compression algorithm\nin `/etc/initramfs-tools/initramfs.conf` file. Look for `COMPRESS` and\nset it to some other value such as `gzip` (the safe choice), or `zstd`\n(the best compression, but your kernel and `initramfs-tools` need to support it).\n\nHere is a one-liner to change compression to `gzip`:\n\n    $ sudo sed -iE 's/^\\s*COMPRESS=.*$/COMPRESS=gzip/' /etc/initramfs-tools/initramfs.conf\n\nThen you need to regenerate all of your initramfs images:\n\n    $ sudo update-initramfs -k all -u\n\nThat's it.\n\nResources related to the issue:\n- [Appending files to initramfs image - reliable? (StackExchange)](https://unix.stackexchange.com/a/737219)\n- [What is the correct frame format for Linux (Lz4 issue)](https://github.com/lz4/lz4/issues/956)\n- [Initramfs unpacking failed (Ubuntu bug report)](https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1835660)\n\n### Staged kernel not being executed by systemd\n\nIf rebooting with cryptreboot doesn't seem to differ from a standard\nreboot, it may suggest staged kernel is not being executed by the\n`systemd` at the end of the shutdown procedure.\n\nThe solution I found is to execute `kexec -e` instead of\n`systemctl --force kexec` when the system is ready for a reboot.\nTo do that `systemd-kexec.service` has to be modified.\nTo make the change minimal, let's use `systemd drop-in` for that:\n\n    $ sudo mkdir -p /etc/systemd/system/systemd-kexec.service.d/\n    $ echo -e \"[Service]\\nExecStart=\\nExecStart=kexec -e\" | sudo tee /etc/systemd/system/systemd-kexec.service.d/override.conf\n\nThat should work.\n\nTo cancel the change, remove the file:\n\n    $ sudo rm /etc/systemd/system/systemd-kexec.service.d/override.conf\n\n### No symlinks to the most recent kernel and initramfs\n\nBy default, cryptreboot looks for kernel in `/boot/vmlinuz` and for initramfs\nin `/boot/initrd.img`. If those files are missing in your Linux distribution,\ncryptreboot will fail, unless you use `--kernel` and `--initramfs` command line\noptions.\n\n    $ sudo cryptreboot --kernel /boot/vmlinuz-`uname -r` --initramfs /boot/initrd.img-`uname -r`\n\nIf you don't want to specify options every time you reboot, add symlinks to\nthe currently running kernel and initramfs:\n\n    $ cd /boot\n    $ sudo ln -sf vmlinuz-`uname -r` vmlinuz\n    $ sudo ln -sf initrd.img-`uname -r` initrd.img\n\nUnfortunately, you need to rerun it after each kernel upgrade, otherwise,\ncryptreboot is going to boot the old kernel.\nUpcoming versions of cryptreboot will offer better solutions.\n\n### Problems with memory locking\n\nIf you get:\n\n\u003e Locking error: Failed to lock memory\n\nit means there was an error while locking memory to prevent a risk of sensitive data ending in a swap space.\n\nMake sure you have permission to lock memory. Root users have.\nIf permissions are ok, then please report a bug describing your setup.\n\nThe solution of last resort is to use `--insecure-memory` flag, which disables memory locking completely.\n\n### Unable to kexec on reboot using old systemd\n\nUbuntu 20.04 ships with `systemd` which may fall back to standard reboot instead of using `kexec`, because this utility\nis located on a filesystem being unmounted during the shutdown sequence.\n\nAs a result, using cryptreboot would feel like using normal reboot.\n\nTo tell if your system is affected, you have to check messages printed to the console after you run cryptreboot.\nThis message happens just before reboot, so you will have just a few milliseconds to notice it on screen:\n\n\u003e shutdown[1]: (sd-kexec) failed with exit status 1\n\n[There is a fix](https://bugs.launchpad.net/ubuntu/+source/systemd/+bug/1969365) waiting to be included in\na stable release update to `systemd` since 2023-07-21.\n\nIn the meantime, as a workaround, you can use `kexec` directly. **Warning: it will skip the standard shutdown procedure. Filesystems won't be unmounted, services won't be stopped, etc. It is like hitting `reset` button**.\nHowever, when you use a decent filesystem with journalling the risk of things going bad should not be high.\n\nGiven the above warning, to reboot skipping the shutdown procedure, run:\n\n    $ sudo cryptreboot -p\n    $ sudo kexec -e # will skip proper shutdown sequence\n\n## Development\n\nAfter checking out the repo, run `bundle install` to install\ndependencies. Then, run `rake spec` to run the tests. You can also\nrun `bin/console` for an interactive prompt that will allow you\nto experiment.\n\nTo build the gem, run `rake build`. To release a new version, update\nthe version number in `version.rb`, and then run `rake release`, which\nwill create a git tag for the version, push git commits and the created\ntag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/phantom-node/cryptreboot.\nThis project is intended to be a safe, welcoming space for collaboration,\nand contributors are expected to adhere to the\n[code of conduct](https://github.com/phantom-node/cryptreboot/blob/master/CODE_OF_CONDUCT.md).\n\n## Author\n\nMy name is Paweł Pokrywka and I'm the author of cryptreboot.\n\nIf you want to contact me or get to know me better, check out\n[my blog](https://www.pawelpokrywka.com).\n\nThank you for your interest in this project :)\n\n## License\n\nThe software is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Cryptreboot project's codebases, issue\ntrackers, chat rooms, and mailing lists is expected to follow the\n[code of conduct](https://github.com/phantom-node/cryptreboot/blob/master/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphantom-node%2Fcryptreboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphantom-node%2Fcryptreboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphantom-node%2Fcryptreboot/lists"}