{"id":47356677,"url":"https://github.com/fabianishere/udm-kernel-tools","last_synced_at":"2026-04-01T07:00:59.071Z","repository":{"id":38356643,"uuid":"340867405","full_name":"fabianishere/udm-kernel-tools","owner":"fabianishere","description":"Tools for bootstrapping custom kernels on the UniFi Dream Machine","archived":false,"fork":false,"pushed_at":"2023-04-02T17:30:42.000Z","size":300,"stargazers_count":334,"open_issues_count":10,"forks_count":22,"subscribers_count":19,"default_branch":"master","last_synced_at":"2026-02-25T01:21:26.459Z","etag":null,"topics":["kernel","linux","udm","udm-pro","unifi"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabianishere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"custom":"https://www.buymeacoffee.com/fabianishere"}},"created_at":"2021-02-21T09:54:29.000Z","updated_at":"2026-02-22T21:40:11.000Z","dependencies_parsed_at":"2023-01-28T16:01:26.578Z","dependency_job_id":null,"html_url":"https://github.com/fabianishere/udm-kernel-tools","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/fabianishere/udm-kernel-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianishere%2Fudm-kernel-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianishere%2Fudm-kernel-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianishere%2Fudm-kernel-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianishere%2Fudm-kernel-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabianishere","download_url":"https://codeload.github.com/fabianishere/udm-kernel-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianishere%2Fudm-kernel-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31269194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T06:57:45.811Z","status":"ssl_error","status_checked_at":"2026-04-01T06:57:42.389Z","response_time":53,"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":["kernel","linux","udm","udm-pro","unifi"],"created_at":"2026-03-18T03:00:18.694Z","updated_at":"2026-04-01T07:00:59.058Z","avatar_url":"https://github.com/fabianishere.png","language":"Shell","funding_links":["https://www.buymeacoffee.com/fabianishere"],"categories":["Dream Machine Utilities"],"sub_categories":["Other Platforms"],"readme":"# udm-kernel-tools [![Release](https://github.com/fabianishere/udm-kernel-tools/actions/workflows/release.yml/badge.svg)](https://github.com/fabianishere/udm-kernel-tools/actions/workflows/release.yml)\nTools for bootstrapping custom Linux kernels on the Ubiquiti UniFi Dream\nMachine (Pro).\n\n## Introduction\nThe Ubiquiti [UniFi Dream Machine](https://unifi-network.ui.com/dreammachine)\n(UDM) and UDM Pro are a class of all-in-one network appliances built by Ubiquiti.\nThese devices are powered by UbiOS, which uses Linux kernel under the hood.\n\nHowever, the stock kernel on these devices lacks some important functionality\nneeded for common use-cases (such as WireGuard as VPN or multicast routing support for IPTV).\nIn many cases, this functionality can be enabled with a custom Linux kernel.\n\nThis repository provides tools to bootstrap a custom Linux kernel on the UDM/P.\nTo prevent bricking your device, this tool does not overwrite the firmware of\nthe device.\nInstead, it boots directly into the custom kernel from the stock kernel\nusing [kexec](https://en.wikipedia.org/wiki/Kexec) (see [How it works](#how-it-works)).\n\n## Use-cases\nThere are currently several use-cases for using a custom kernel on the\nUniFi Dream Machine (Pro). These use-cases include:\n\n1. **In-kernel [WireGuard](https://wireguard.com) support**  \n   Although you can already run a WireGuard server on your UDM/P using `wireguard-go` (see \n   [udm-utilities](https://github.com/boostchicken/udm-utilities)), its performance\n   will be reduced due to it running in user-space. A custom kernel enables your \n   WireGuard VPN server to utilize the kernel implementation and run at full speed.\n2. **Multicast routing support**  \n   The stock kernel of the UDM/P does not support multicast routing which is\n   needed for running `igmpproxy`. In turn, `igmpproxy` is needed to route\n   multicast traffic between WAN and LAN, which is necessary for IPTV.\n   See the [following guide](https://github.com/fabianishere/udm-iptv) for more information.\n3. [**Early boot modifications**](#overriding-files-on-root-pre-boot)  \n   Since changes to root filesystem on the UDM/P are non-persistent. It is not\n   possible with the stock kernel to perform modification to the early boot\n   process (since the [on-boot-script](https://github.com/boostchicken/udm-utilities/blob/master/on-boot-script/README.md) only runs after UniFi OS is started).\n   This project enables you to modify the root filesystem before UbiOS is started.\n   See [Overriding files on root pre-boot](#overriding-files-on-root-pre-boot) for more information. \n\n## Getting Started\n### Disclaimer \nAlthough these tools do not modify any firmware on your device, using them might\nlead to **system instability** or **data loss**.\nMake sure you know what you are doing and ensure you have a **backup**! \nI take no responsibility for any damage that might occur as result of using this\nproject.\n\n### Entering UniFi OS\nTo start, SSH into your UniFi Dream Machine (Pro) and enter the UniFi OS shell\nas follows:\n```bash\nunifi-os shell\n```\n\n### Installing udm-kernel-tools\nSelect from the [Releases](https://github.com/fabianishere/udm-kernel-tools/releases) page\nthe package version you want to install and download the selected Debian package,\nfor instance:\n\n```bash\nwget https://github.com/fabianishere/udm-kernel-tools/releases/download/v1.1.7/udm-kernel-tools_1.1.7_arm64.deb\napt install ./udm-kernel-tools_1.1.7_arm64.deb\n```\n\n### Installing a custom kernel\nTo obtain and install a custom Linux kernel for the UniFi Dream Machine (Pro),\nvisit the [udm-kernel](https://github.com/fabianishere/udm-kernel) repository.\nThis repository contains instructions for installing the pre-built kernels as\nwell as instructions for building custom kernels yourself.\n\n### Booting into a custom kernel \nFirst, list the kernels you have installed on your system as follows:\n```bash\nudm-bootctl list\n```\n\nBooting into a custom kernel is then done as follows:\n```bash\nudm-bootctl boot KERNEL_VERSION\n```\nAlternatively, you may specify the path to the kernel image.\n**Note** that after executing this command, the SSH connection might become \nunresponsive or might even be killed with an error message. This is expected\nbehavior and after a minute, you should be able to log back into your device\nvia SSH.\n\nOnce the system is back online, verify that you are running the correct kernel:\n```bash\nuname -a\n```\n\n### Auto-booting into the custom kernel\nSince the custom kernel does not persist across reboots due to the use of _kexec_,\nyou need to perform the boot procedure after every reboot. \nWe provide a `udm-autoboot.service` to automate this process.\n\nFirst, select the default kernel you want to boot into:\n```bash\nudm-bootctl set-default KERNEL_VERSION\n```\nThen, enable the `udm-autoboot.service` to run during system startup:\n```bash\nsystemctl enable udm-autoboot.service\n```\n\n**Disabling auto-boot**  \nTo disable this functionality again, run the following command:\n```bash\nsystemctl disable udm-autoboot.service\n```\n\n### Overriding files on root pre-boot\nSome users may wish to modify files on the root filesystem before UniFi OS boots\n(e.g., to hook into the early boot process).\nIn order to facilitate this, `udm-kernel-tools` allows users to override files\nfrom the root filesystem using an overlay located  at `/mnt/data/udm-kernel-tools/root`,\n\nThe overlay filesystem will be mounted *only* after running \n`mkdir -p /overlay/root_ro/mnt/data/udm-kernel-tools/root` from within the *UniFi OS* shell\nor when running `mkdir -p /data/udm-kernel-tools/root` from outside UniFi OS. \n\nNote that changes to this directory only appear on the root filesystem after\nreboot.\n\n### Restoring the stock kernel\nIf you are running a custom kernel and wish to return the stock kernel, simply\nreboot the device (from UbiOS):\n```bash\nreboot\n```\n\n### Removing udm-kernel-tools\nTo remove `udm-kernel-tools` and the custom kernels you have installed, run\nthe following command in UniFi OS:\n\n```bash\napt remove 'udm-kernel*'\n```\n\nThis will remove the artifacts on your device related to this project.\n\n## Compatibility\nSince the project requires firmware-specific binaries (e.g., kernel modules), you\npossibly need to upgrade the tools after you have upgraded to a new firmware version.\nCurrently, the releases of this project support the following firmware versions:\n\n- 1.8.6\n- 1.9.3\n- 1.10.0\n- 1.10.4\n- 1.11.0\n- 1.11.4\n- 1.12.22\n- 1.12.30\n- 1.12.33\n\nTo build the project for custom firmware versions, please refer to the [Maintenance Guide](MAINTENANCE.md).\n\n## Troubleshooting\nBelow is a non-exhaustive list of issues that might occur while using these\ntools. Please check these instructions before reporting an issue on issue tracker.\n\n**Device reboots into stock kernel**  \nWhen your device still reports after the boot procedure that it is running the\nstock kernel, check the logs for errors:\n```bash\n# Check ramoops\ncat /sys/fs/pstore/*\n# Check kernel log\ndmesg\n```\n\n**Device appears to be stuck**  \nWhen you cannot connect to your device a few minutes after performing the boot\nprocedure, the device might be stuck. Power cycle the device to restore\nthe stock kernel.\n\n**SSH session exits with error after boot command**  \nAfter executing the `boot` command, your SSH connection might become unresponsive\nor even exit with an error message. This is expected behavior, and you should\nbe able to log back in to your device after a minute.\n\n## Contributing\nQuestions, suggestions and contributions are welcome and appreciated!\nYou can contribute in various meaningful ways:\n\n* Report a bug through [Github issues](https://github.com/fabianishere/udm-kernel-tools/issues).\n* Propose and document use-cases for using this project.\n* Contribute improvements to the documentation.  \n* Provide feedback about how we can improve the project.\n* Help answer questions on our [Discussions](https://github.com/fabianishere/udm-kernel-tools/discussions) page.\n\nAdvanced users may also be interested in the [Maintenance Guide](MAINTENANCE.md).\n\n## How it works\nBootstrapping a custom Linux kernel on the UDM/P is not trivial. By default,\nUniFi OS restricts user capabilities on Linux significantly, to such an extent\nthat even changes to the root filesystem are not persistent without [a workaround](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script).\n\nAlthough [udm-unlock](https://github.com/fabianishere/udm-unlock) can be used\nto overwrite the kernel boot image or root filesystem, such an approach is fragile\nand might lead to a bricked device.  \n\nTo prevent touching the UDM/P firmware for booting a custom Linu kernel, we can\nemploy Linux' [kexec](https://en.wikipedia.org/wiki/Kexec) functionality, which\nenables Linux to act as a second stage bootloader for a custom kernel. \n\nSince _kexec_ is not supported natively by the stock kernel running on the\nUDM/P, I have backported this functionality as a \n[loadable kernel module](https://github.com/fabianishere/kexec-mod).\nThese tools use the _kexec_ backport to load a custom kernel into memory and boot\ndirectly into the custom kernel. With this, we do not need to modify the device\nfirmware and in case of issues, we can simply power-cycle the device.\n\nWhile we can now boot into a custom Linux kernel, we will find that UbiOS requires\nseveral proprietary kernel modules to properly function. To address this issue,\nduring the [initramfs phase](https://en.wikipedia.org/wiki/Initial_ramdisk), we\nprepare a workaround that force-inserts the proprietary modules into the kernel,\neven when the versions do not match (see [here](https://github.com/fabianishere/udm-kernel-tools/blob/32f0816089c5187f4ff13e3c68f9ea2f6325c591/udm-init#L45) for the implementation).\n\n## License\nThe code is released under the GPLv2 license. See [COPYING.txt](/COPYING.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabianishere%2Fudm-kernel-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabianishere%2Fudm-kernel-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabianishere%2Fudm-kernel-tools/lists"}