{"id":44916426,"url":"https://github.com/amoyrtil/talos-ufs","last_synced_at":"2026-04-01T19:22:32.107Z","repository":{"id":338040427,"uuid":"1155954532","full_name":"amoyrtil/talos-ufs","owner":"amoyrtil","description":"Talos Linux with UFS storage support for x86_64 devices (Intel Alder Lake-N, etc.)","archived":false,"fork":false,"pushed_at":"2026-03-20T04:28:59.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T20:56:55.849Z","etag":null,"topics":["kubernetes","mini-pc","talos-linux","ufs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amoyrtil.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T05:00:14.000Z","updated_at":"2026-02-14T08:02:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amoyrtil/talos-ufs","commit_stats":null,"previous_names":["amoyrtil/talos-ufs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/amoyrtil/talos-ufs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoyrtil%2Ftalos-ufs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoyrtil%2Ftalos-ufs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoyrtil%2Ftalos-ufs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoyrtil%2Ftalos-ufs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amoyrtil","download_url":"https://codeload.github.com/amoyrtil/talos-ufs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoyrtil%2Ftalos-ufs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","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":["kubernetes","mini-pc","talos-linux","ufs"],"created_at":"2026-02-18T02:00:21.279Z","updated_at":"2026-04-01T19:22:32.101Z","avatar_url":"https://github.com/amoyrtil.png","language":"Shell","funding_links":[],"categories":["Table of Contents"],"sub_categories":[],"readme":"# Talos Linux with UFS Support\n\nAutomated builds of [Talos Linux](https://www.talos.dev/) with UFS (Universal Flash Storage) driver support for x86_64 devices.\n\nStandard Talos Linux does not include UFS drivers, making it impossible to install on devices with UFS storage. This project provides custom builds with UFS drivers built into the kernel and an enlarged EFI partition for 4096-byte sector compatibility.\n\n## Supported Hardware\n\nAll x86_64 devices with PCI-connected UFS controllers supported by the Linux `ufshcd-pci` driver:\n\n| Vendor | Device ID | Description |\n|--------|-----------|-------------|\n| Intel | 0x54FF | Alder Lake-N UFS Controller |\n| Intel | 0x4B41, 0x4B43 | Elkhart Lake UFS |\n| Qualcomm | Various | Qualcomm UFS controllers |\n\n### Verified Devices\n\n| Device | CPU | UFS | Status |\n|--------|-----|-----|--------|\n| MINISFORUM S100-WLP | Intel N100 (Alder Lake-N) | 256GB UFS 2.1 | ✅ Verified |\n\nWe welcome hardware compatibility reports! See [Contributing](#contributing).\n\n## Quick Start\n\n### 1. Download and Boot\n\nDownload `metal-amd64.iso` from the [latest release](../../releases/latest), write it to a USB drive, and boot your device with Secure Boot disabled.\n\n### 2. Verify UFS Detection\n\nOnce the device enters Talos maintenance mode, confirm UFS storage is detected:\n\n```bash\ntalosctl get disks --insecure --nodes \u003cIP\u003e\n```\n\n### 3. Generate and Apply Config\n\n```bash\ntalosctl gen config my-cluster https://\u003cCONTROL_PLANE_IP\u003e:6443\n```\n\nEdit the generated config to use the UFS installer:\n\n```yaml\nmachine:\n  install:\n    disk: /dev/sda  # Your UFS device\n    image: ghcr.io/amoyrtil/talos-ufs-installer:\u003cversion\u003e\n```\n\nApply and bootstrap:\n\n```bash\ntalosctl apply-config --insecure --nodes \u003cIP\u003e --file controlplane.yaml\ntalosctl bootstrap --nodes \u003cIP\u003e  # After reboot\n```\n\nFor detailed installation steps, see the [Talos Getting Started Guide](https://www.talos.dev/latest/introduction/getting-started/).\n\n## Container Images\n\nEach release publishes three container images:\n\n| Image | Purpose |\n|-------|---------|\n| `ghcr.io/amoyrtil/talos-ufs-installer:\u003cversion\u003e` | Installer for machine config |\n| `ghcr.io/amoyrtil/talos-ufs-imager:\u003cversion\u003e` | Generate custom ISOs with system extensions |\n| `ghcr.io/amoyrtil/talos-ufs-kernel:\u003cversion\u003e` | Custom kernel with UFS drivers |\n\n## Custom ISO Generation\n\nUse the published imager to generate ISOs with system extensions:\n\n```bash\ndocker run --rm -t -v /dev:/dev --privileged \\\n  ghcr.io/amoyrtil/talos-ufs-imager:\u003cversion\u003e \\\n  metal --system-extension-image \u003cextension-image\u003e\n```\n\n## Changes from Upstream\n\n1. **Kernel**: UFS drivers built-in (`CONFIG_SCSI_UFSHCD=y`, `CONFIG_SCSI_UFS_BSG=y`, `CONFIG_SCSI_UFS_HWMON=y`, `CONFIG_SCSI_UFSHCD_PCI=y`) with required dependencies (`CONFIG_PM_DEVFREQ`, `CONFIG_PM_OPP`)\n2. **EFI Partition**: Size increased from 100MiB to 512MiB for FAT32 compatibility with 4096-byte sectors\n\n## Local Build\n\n### Prerequisites\n\n- Docker with Buildx support\n- GNU Make (`brew install make` on macOS, use `gmake`)\n- ~50GB free disk space\n- ~4-6 hours build time (kernel build is the bottleneck)\n\n### Build Steps\n\n```bash\n# 1. Set up a local registry\ndocker run -d -p 5005:5000 --name registry registry:2\n\n# 2. Configure buildx for insecure local registry\ncat \u003e /tmp/buildkitd.toml \u003c\u003c 'EOF'\n[registry.\"host.docker.internal:5005\"]\n  http = true\n  insecure = true\n[registry.\"localhost:5005\"]\n  http = true\n  insecure = true\nEOF\n\ndocker buildx create --name talos-builder --driver docker-container \\\n  --driver-opt network=host --config /tmp/buildkitd.toml --use\n\n# 3. Clone repositories\ngit clone --branch \u003ctalos-version\u003e https://github.com/siderolabs/talos.git /tmp/talos\n# Resolve pkgs version: grep '^PKGS ?=' /tmp/talos/Makefile\ngit clone --branch \u003cpkgs-version\u003e https://github.com/siderolabs/pkgs.git /tmp/pkgs\n\n# 4. Apply patches\n./scripts/apply-patches.sh /tmp/pkgs /tmp/talos\n\n# 5. Build kernel (2-3 hours)\ncd /tmp/pkgs\ndocker buildx build --no-cache --file=Pkgfile --platform=linux/amd64 \\\n  --target=kernel --tag=localhost:5005/siderolabs/kernel:custom --push .\n\n# 6. Build imager, installer-base, and installer\ncd /tmp/talos\ngmake imager \\\n  PKG_KERNEL=host.docker.internal:5005/siderolabs/kernel:custom \\\n  PLATFORM=linux/amd64 REGISTRY=localhost:5005 PUSH=true INSTALLER_ARCH=amd64\n\ngmake installer-base \\\n  PKG_KERNEL=host.docker.internal:5005/siderolabs/kernel:custom \\\n  PLATFORM=linux/amd64 REGISTRY=localhost:5005 PUSH=true INSTALLER_ARCH=amd64\n\ngmake installer \\\n  PKG_KERNEL=host.docker.internal:5005/siderolabs/kernel:custom \\\n  PLATFORM=linux/amd64 REGISTRY=localhost:5005 PUSH=true INSTALLER_ARCH=amd64\n\n# 7. Generate ISO\nmkdir -p output\ndocker run --rm --platform linux/amd64 -v $(pwd)/output:/out --privileged \\\n  localhost:5005/siderolabs/imager:\u003ctag\u003e iso --arch amd64\n\n# 8. Verify UFS drivers are included\n./scripts/verify-build.sh output/metal-amd64.iso\n```\n\n## Troubleshooting\n\n### UFS storage not detected after booting ISO\n\nVerify the ISO contains UFS drivers:\n\n```bash\n./scripts/verify-build.sh metal-amd64.iso\n```\n\nExpected output should show `ufshcd-core.ko` and `ufshcd-pci.ko` in `modules.builtin`.\n\n### UFS drivers built as modules (=m) don't work\n\nTalos does not auto-load kernel modules in maintenance mode unless they are listed in `hack/modules-amd64.txt`. UFS drivers must be built-in (`=y`), not modules.\n\n### FAT32 errors on EFI partition\n\nThe default 100MiB EFI partition is too small for 4096-byte sector devices. This build increases it to 512MiB. If you see FAT32-related errors, ensure you're using this custom build.\n\n### Kernel config changes not reflected in ISO\n\nDocker Buildx may cache kernel build layers. Always use `--no-cache` when building the kernel after config changes.\n\n### \"TLS config specified for non-HTTPS registry\"\n\nWhen using a local HTTP registry, only configure `mirrors` in machine config. Do not add `config.tls.insecureSkipVerify` for HTTP registries.\n\n## How It Works\n\nThis project uses GitHub Actions to:\n\n1. **Monitor upstream releases** (`check-release.yml`): Daily check for new stable Talos releases\n2. **Build custom images** (`build.yml`): Apply patches, build kernel, imager, installer, and generate ISO\n3. **Test patches** (`test.yml`): Validate patches apply cleanly on PRs, with optional kernel build\n\nThe pkgs version is automatically resolved from the Talos `Makefile` (`PKGS ?=` variable) to ensure the custom kernel is built against the exact version Talos expects.\n\n## Contributing\n\n### Hardware Reports\n\nIf you have a UFS-equipped x86_64 device, please report compatibility:\n\n1. Open an [Issue](../../issues/new) with:\n   - Device name and model\n   - Output of `lspci -nn | grep -i ufs`\n   - UFS storage capacity and model\n   - Whether Talos installed and booted successfully\n\n### Patch Updates\n\nWhen upstream Talos changes break patches:\n\n1. Clone this repo and the upstream repos\n2. Update patch files in `patches/`\n3. Test with `./scripts/apply-patches.sh`\n4. Submit a PR (patches are automatically validated)\n\n## License\n\n[MPL-2.0](LICENSE) (matching Talos Linux)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoyrtil%2Ftalos-ufs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famoyrtil%2Ftalos-ufs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoyrtil%2Ftalos-ufs/lists"}