Fix udev rules for virtual gamepad nodes

Extend udev rule reloading to cover hidraw and input subsystems so permissions are applied to dynamically created libvirtualhid gamepad child nodes, not just /dev/uinput and /dev/uhid.

Also:
- Always install the udev rules file regardless of whether libudev is detected at build time
- Add Homebrew postinst support to copy rules to host-monitored directories
- Trigger udevadm reload on rule removal (AppImage, Flatpak)
- Update comments to say "gamepad emulation" instead of "DS5 emulation"
- Add docs clarifying that manual chmod/setfacl changes are lost on reconnect and how to reload rules

Author: ReenigneArcher

.github/workflows/ci-archlinux.yml

@@ -149,6 +149,15 @@ jobs:
             _support_headless_testing="${_support_headless_testing}" \
             makepkg -si --noconfirm
 
+          # Native packages must install the host rule used by dynamically
+          # created libvirtualhid hidraw and input event nodes.
+          test -f /usr/lib/udev/rules.d/60-sunshine.rules
+          grep -Fq 'IMPORT{parent}="HID_*"' \
+            /usr/lib/udev/rules.d/60-sunshine.rules
+          grep -Fq 'ENV{HID_PHYS}=="libvirtualhid/uhid/*"' \
+            /usr/lib/udev/rules.d/60-sunshine.rules
+          udevadm verify /usr/lib/udev/rules.d/60-sunshine.rules
+
           # Remove debug package
           rm -f sunshine-debug*.pkg.tar.zst
 

.github/workflows/ci-linux.yml

@@ -103,6 +103,11 @@ jobs:
         run: |
           # install sunshine to the DESTDIR
           DESTDIR=AppDir ninja install
+          test -f AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
+          grep -Fq 'IMPORT{parent}="HID_*"' \
+            AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
+          grep -Fq 'ENV{HID_PHYS}=="libvirtualhid/uhid/*"' \
+            AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
 
           # custom AppRun file
           cp -f ../packaging/linux/AppImage/AppRun ./AppDir/

.github/workflows/ci-macos.yml

@@ -58,9 +58,11 @@ jobs:
           - os: "macos-14"
             name: "macOS-arm64"
             arch: "arm64"
+            build_docs: "ON"
           - os: "macos-15-intel"
             name: "macOS-x86_64"
             arch: "x86_64"
+            build_docs: "OFF"
     steps:
       - name: Install Apple certificate
         uses: apple-actions/import-codesign-certs@5142e029c445c10ffc7149d172e540235a065466  # v7.0.0
@@ -121,6 +123,7 @@ jobs:
           cmake \
             -B build \
             -S . \
+            -DBUILD_DOCS="${{ matrix.build_docs }}" \
             -DBUILD_WERROR=ON \
             -DCMAKE_BUILD_TYPE=Release \
             -DICU_ROOT="$(brew --prefix icu4c@78 2>/dev/null)" \

cmake/packaging/linux.cmake

@@ -30,9 +30,15 @@ else()
     find_package(Udev)
 
     if(UDEV_FOUND)
-        install(FILES "${SUNSHINE_SOURCE_ASSETS_DIR}/linux/misc/60-sunshine.rules"
-                DESTINATION "${UDEV_RULES_INSTALL_DIR}")
+        set(SUNSHINE_UDEV_RULES_INSTALL_DIR "${UDEV_RULES_INSTALL_DIR}")
+    else()
+        set(SUNSHINE_UDEV_RULES_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/udev/rules.d")
+        message(WARNING
+                "Could not determine the host udev rules directory; "
+                "installing Sunshine rules to ${SUNSHINE_UDEV_RULES_INSTALL_DIR}")
     endif()
+    install(FILES "${SUNSHINE_SOURCE_ASSETS_DIR}/linux/misc/60-sunshine.rules"
+            DESTINATION "${SUNSHINE_UDEV_RULES_INSTALL_DIR}")
     if(SYSTEMD_FOUND)
         install(FILES "${CMAKE_CURRENT_BINARY_DIR}/app-${PROJECT_FQDN}.service"
                 DESTINATION "${SYSTEMD_USER_UNIT_INSTALL_DIR}")

docs/getting_started.md

@@ -265,6 +265,9 @@ flatpak install --user ./sunshine_{arch}.flatpak
 ```
 
 ##### Additional installation (required)
+Run this command after installing or updating the Flatpak so the privileged host
+udev rules stay synchronized with Sunshine:
+
 ```bash
 flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine
 ```
@@ -293,6 +296,7 @@ brew update
 brew upgrade
 brew tap LizardByte/homebrew
 brew install sunshine
+sudo "$(brew --prefix sunshine)/bin/postinst"
 ```
 
 ##### Uninstall

docs/troubleshooting.md

@@ -188,6 +188,18 @@ flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine
 After installation, the `udev` rules need to be reloaded. Our post-install script tries to do this for you
 automatically, but if it fails, you may need to restart your system.
 
+Sunshine recreates virtual gamepad device nodes for each streaming session. Manual `chmod` or `setfacl`
+changes therefore disappear when the client reconnects. Confirm that the installed Sunshine rule contains the
+parent-property import and `libvirtualhid/uhid/*` match, then reload it and reapply it to existing gamepad nodes:
+
+```bash
+grep -R -E 'IMPORT\{parent\}="HID_\*"|ENV\{HID_PHYS\}=="libvirtualhid/uhid/\*"' \
+  /etc/udev/rules.d /usr/lib/udev/rules.d /lib/udev/rules.d 2>/dev/null
+sudo udevadm control --reload-rules
+sudo udevadm trigger --subsystem-match=hidraw
+sudo udevadm trigger --subsystem-match=input
+```
+
 If the input is still not working, you may need to add your user to the `input` group.
 
 ```bash

packaging/linux/AppImage/AppRun

@@ -28,7 +28,7 @@ echo "
  ------            # This message
 
          $ARGV0  --install, -i
-                   # Install input rules sunshine.service files. Restart required.
+                   # Install or update input rules and sunshine.service files.
 
          $ARGV0  --remove, -r
                    # Remove input rules sunshine.service files.
@@ -52,6 +52,8 @@ function install() {
   sudo udevadm control --reload-rules
   sudo udevadm trigger --property-match=DEVNAME=/dev/uinput
   sudo udevadm trigger --property-match=DEVNAME=/dev/uhid
+  sudo udevadm trigger --subsystem-match=hidraw
+  sudo udevadm trigger --subsystem-match=input
 
   # sunshine service
   mkdir -p ~/.config/systemd/user
@@ -66,6 +68,7 @@ function install() {
 function remove() {
   # remove input rules
   sudo rm -f /etc/udev/rules.d/60-sunshine.rules
+  sudo udevadm control --reload-rules
 
   # remove uhid module loading config
   sudo rm -f /etc/modules-load.d/60-sunshine.conf

packaging/linux/Arch/sunshine.install

@@ -1,11 +1,15 @@
+# shellcheck shell=bash
+
 do_setcap() {
-  setcap cap_sys_admin,cap_sys_nice+p $(readlink -f usr/bin/sunshine)
+  setcap cap_sys_admin,cap_sys_nice+p "$(readlink -f usr/bin/sunshine)"
 }
 
 do_udev_reload() {
   udevadm control --reload-rules
   udevadm trigger --property-match=DEVNAME=/dev/uinput
   udevadm trigger --property-match=DEVNAME=/dev/uhid
+  udevadm trigger --subsystem-match=hidraw
+  udevadm trigger --subsystem-match=input
   modprobe uinput || true
   modprobe uhid || true
 }

packaging/linux/copr/Sunshine.spec

@@ -414,21 +414,23 @@ cd %{_builddir}/Sunshine/build
 %post
 # Note: this is copied from the postinst script
 
-# Load uhid (DS5 emulation)
-echo "Loading uhid kernel module for DS5 emulation."
+# Load uhid for descriptor-driven gamepad emulation
+echo "Loading uhid kernel module for gamepad emulation."
 modprobe uhid
 
 # Check if we're in an rpm-ostree environment
 if [ ! -x "$(command -v rpm-ostree)" ]; then
   echo "Not in an rpm-ostree environment, proceeding with post install steps."
 
-  # Trigger udev rule reload for /dev/uinput and /dev/uhid
+  # Reload the rules and reapply them to virtual gamepad child nodes.
   path_to_udevadm=$(which udevadm)
   if [ -x "$path_to_udevadm" ]; then
     echo "Reloading udev rules."
     $path_to_udevadm control --reload-rules
     $path_to_udevadm trigger --property-match=DEVNAME=/dev/uinput
     $path_to_udevadm trigger --property-match=DEVNAME=/dev/uhid
+    $path_to_udevadm trigger --subsystem-match=hidraw
+    $path_to_udevadm trigger --subsystem-match=input
     echo "Udev rules reloaded successfully."
   else
     echo "error: udevadm not found or not executable."

packaging/linux/flatpak/scripts/additional-install.sh

@@ -6,14 +6,19 @@ cp "/app/share/sunshine/systemd/user/app-dev.lizardbyte.app.Sunshine.service" "$
 echo "Sunshine User Service has been installed."
 echo "Use [systemctl --user enable app-dev.lizardbyte.app.Sunshine] once to autostart Sunshine on login."
 
-# Load uhid (DS5 emulation)
+# Load uhid for descriptor-driven gamepad emulation
 UHID=$(cat /app/share/sunshine/modules-load.d/60-sunshine.conf)
-echo "Enabling DS5 emulation."
+echo "Enabling gamepad emulation."
 flatpak-spawn --host pkexec sh -c "echo '$UHID' > /etc/modules-load.d/60-sunshine.conf"
 flatpak-spawn --host pkexec modprobe uhid
 
 # Udev rule
 UDEV=$(cat /app/share/sunshine/udev/rules.d/60-sunshine.rules)
-echo "Configuring mouse permission."
+echo "Configuring virtual input permissions."
 flatpak-spawn --host pkexec sh -c "echo '$UDEV' > /etc/udev/rules.d/60-sunshine.rules"
-echo "Restart computer for mouse permission to take effect."
+flatpak-spawn --host pkexec udevadm control --reload-rules
+flatpak-spawn --host pkexec udevadm trigger --property-match=DEVNAME=/dev/uinput
+flatpak-spawn --host pkexec udevadm trigger --property-match=DEVNAME=/dev/uhid
+flatpak-spawn --host pkexec udevadm trigger --subsystem-match=hidraw
+flatpak-spawn --host pkexec udevadm trigger --subsystem-match=input
+echo "Virtual input permissions have been updated."