From 92b876b8cff8cb83c4daa5ddeb9a26820bf9c984 Mon Sep 17 00:00:00 2001 From: Matthias Grob Date: Mon, 22 Jun 2026 15:17:33 +0200 Subject: [PATCH 1/2] docs: add instructions for Ubuntu and consistent steps for the required kernel BPF LSM feature --- docs/getting-started/installation.md | 83 +++++++++++++++++++++++++--- docs/getting-started/requirements.md | 13 ++--- 2 files changed, 81 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index c8ba206..861f888 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -8,12 +8,10 @@ using AUR: yay -S cardwire ``` -then enable and start the service +Then [enable BPF LSM](#enabling-bpf-lsm) and start the service: ```bash -sudo systemctl enable cardwired.service - -sudo systemctl start cardwired.service +sudo systemctl enable cardwired --now ``` ## Nix @@ -29,6 +27,8 @@ cardwire = { }; ``` +The NixOS module configures BPF LSM automatically — no manual kernel parameter changes needed. + configuration.nix: ```nix @@ -51,15 +51,82 @@ Using Terra ```bash sudo dnf install cardwire +``` + +Then [enable BPF LSM](#enabling-bpf-lsm) and start the service: + +```bash +sudo systemctl enable cardwired --now +``` + +## Ubuntu + +Install build dependencies: + +```bash +sudo apt install clang libbpf-dev linux-headers-$(uname -r) +``` + +Install Rust (if not already installed): + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Then clone and build: -sudo systemctl enable cardwired.service +```bash +git clone https://github.com/OpenGamingCollective/cardwire.git +make build +sudo make install +``` -sudo systemctl start cardwired.service +Then [enable BPF LSM](#enabling-bpf-lsm) and start the service: + +```bash +sudo systemctl enable cardwired --now +``` + +## Enabling BPF LSM (with GRUB) + +Check your kernel's default LSM list: + +On Ubuntu/Fedora: +```bash +grep CONFIG_LSM= /boot/config-$(uname -r) +``` + +On Arch and other distros: +```bash +zcat /proc/config.gz | grep CONFIG_LSM= +``` + +> Outputs e.g. `CONFIG_LSM="landlock,lockdown,yama,integrity,apparmor"` + +Edit `/etc/default/grub` and append `bpf` to `GRUB_CMDLINE_LINUX_DEFAULT`, keeping all existing entries: + +``` +GRUB_CMDLINE_LINUX_DEFAULT="quiet splash lsm=landlock,lockdown,yama,integrity,apparmor,bpf" +``` + +> [!IMPORTANT] +> Do not set `lsm=bpf` alone — that drops other active security policies. Always append `bpf` to the existing list from the command above. + +Apply and reboot: + +| Distro | Command | +|--------|---------| +| Ubuntu | `sudo update-grub` | +| Fedora | `sudo grub2-mkconfig -o /boot/grub2/grub.cfg` | +| Arch | `sudo grub-mkconfig -o /boot/grub/grub.cfg` | + +```bash +sudo reboot ``` ## Other distros -For now, other distros must clone the repo and use `make` to build and install Cardwire. +For now, other distros must clone the repo and use `make` to build and install Cardwire. You will also need to enable BPF LSM manually — see the [Enabling BPF LSM](#enabling-bpf-lsm) section above. Build dependencies: @@ -77,7 +144,7 @@ sudo make install > [!CAUTION] > Makefile wasn't tested, use with caution. -> [!IMPORTANT] +> [!IMPORTANT] > For mainstream distros, i will be making an official install methods, like a copr for Fedora and a .deb for Debian based. ## Non-systemd distros diff --git a/docs/getting-started/requirements.md b/docs/getting-started/requirements.md index f83c6be..a2db8b2 100644 --- a/docs/getting-started/requirements.md +++ b/docs/getting-started/requirements.md @@ -11,16 +11,15 @@ uname -r ``` Built with `CONFIG_BPF_LSM` enabled + +On e.g. Ubuntu/Fedora: ```bash -zcat /proc/config.gz | grep CONFIG_BPF_LSM +grep CONFIG_BPF_LSM /boot/config-$(uname -r) ``` -> returns `CONFIG_BPF_LSM=y` if it's enabled -Enabled in the boot cmdline +On other distros possibly: ```bash -cat /proc/cmdline +zcat /proc/config.gz | grep CONFIG_BPF_LSM ``` -> Must contains `lsm=bpf` (If empty/doesnt contain bpf, please read Caution) -> [!CAUTION] -> Most distros already enable bpf, only change the cmdline if cardwired doesnt launch +> returns `CONFIG_BPF_LSM=y` if it's enabled From fa4e24c77d97e37177ba8816191fcff19b5f9f05 Mon Sep 17 00:00:00 2001 From: Matthias Grob Date: Mon, 22 Jun 2026 15:19:14 +0200 Subject: [PATCH 2/2] docs: add a not that the approach blocks further access but doesn't revoke existing GPU file descriptors It can be further refined but this note at least helps dcument the reality that if gnome already holds the GPU it will not be freed immediately. --- docs/getting-started/usage.md | 47 +++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md index 53b357a..5676615 100644 --- a/docs/getting-started/usage.md +++ b/docs/getting-started/usage.md @@ -9,55 +9,58 @@ cardwire list ``` For each detected GPU, the command will return: -- An identifier (`ID`). These are used for manual blocking and unblocking. +- An identifier (`ID`). These are used for manual blocking and unblocking. - The GPU's name (`NAME`) -- The GPU's PCI address (`PCI`) +- The GPU's PCI address (`PCI`) - The associated render node (`RENDER`) -- The associated device node (`CARD`) -- Whether the GPU has been identified as the default GPU (`DEFAULT`). Default GPUs will remain available when cardwire is set to integrated. -- Whether the GPU is currently blocked (`BLOCKED`) +- The associated device node (`CARD`) +- Whether the GPU has been identified as the default GPU (`DEFAULT`). Default GPUs will remain available when cardwire is set to integrated. +- Whether the GPU is currently blocked (`BLOCKED`) -## Mode switching +## Mode switching -GPU modes can be switched using the `cardwire set` command. +GPU modes can be switched using the `cardwire set` command. -To have cardwire block all GPUs except the default GPU, use: +To have cardwire block all GPUs except the default GPU, use: ``` cardwire set integrated -``` +``` + +> [!NOTE] +> The block only applies to new file opens. Processes that already have the GPU open (e.g. the compositor) will keep their access until they restart. A session logout/login is required for the GPU to fully power down. Check `cardwire gpu --lsof 1` to verify thre's no process keeping e.g. the dedicated GPU awake. -To have cardwire allow access to all GPUs, use +To have cardwire allow access to all GPUs, use ``` -cardwire set hybrid -``` +cardwire set hybrid +``` -## Manual blocking and unblocking +## Manual blocking and unblocking -> [!IMPORTANT] +> [!IMPORTANT] > To prevent system breakage, cardwire will not block default GPUs, even when explicitly instructed to do so. -If more granular control over several GPUs is required, cardwire also allows manually blocking individual GPUs by ID. To do so, it needs to be set to manual mode: +If more granular control over several GPUs is required, cardwire also allows manually blocking individual GPUs by ID. To do so, it needs to be set to manual mode: ``` -cardwire set manual -``` +cardwire set manual +``` -Once set to manual, GPU states can then be set by ID; to find the correct ID, see [Querying GPUs](#Querying-GPUs). +Once set to manual, GPU states can then be set by ID; to find the correct ID, see [Querying GPUs](#Querying-GPUs). -To block the GPU with ID `1`: +To block the GPU with ID `1`: ``` cardwire gpu 1 --block ``` -To unblock: +To unblock: -``` +``` cardwire gpu 1 --unblock -``` +``` ## Battery Auto Switch Mode