From fc8fdd2bf418583c7253a88a7aa40936536c8e4a Mon Sep 17 00:00:00 2001 From: Be Date: Thu, 20 May 2021 17:04:08 -0500 Subject: [PATCH] improve documentation for udev rule files on Linux (#276) - use TAG+="uaccess" instead of overly broad MODE="0666" by default example as advised by Debian: https://lists.debian.org/debian-devel-announce/2016/11/msg00008.html Adding the uaccess tag to udev rules ------------------------------------ Packages containing udev rules that use GROUP="plugdev" should also add TAG+="uaccess" so that all users that are physically present can access the relevant devices, instead of just users in the plugdev group (GROUP="plugdev"). Some packages use MODE="666" to allow all users (including remote users) to access devices. For almost all devices it is probably more appropriate to switch from MODE="666" to GROUP="plugdev", MODE="660", TAG+="uaccess" so that remote users cannot access local devices. Check the wiki page for USB gadgets[13] for more hints. There is a lintian warning in progress[14] for these issues. -- Paul Wise & Petter Reinholdtsen [] https://wiki.debian.org/USB/GadgetSetup [] https://bugs.debian.org/841670 - remove documentation for Linux <2.6.24 --- README.md | 5 +++++ udev/69-hid.rules | 33 +++++++++++++++++++++++++++++++++ udev/99-hid.rules | 33 --------------------------------- 3 files changed, 38 insertions(+), 33 deletions(-) create mode 100644 udev/69-hid.rules delete mode 100644 udev/99-hid.rules diff --git a/README.md b/README.md index 67fa8e7..f6d8329 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,11 @@ built by default. It is up to the application linking to hidapi to choose the backend at link time by linking to either `libhidapi-libusb` or `libhidapi-hidraw`. +Note that you will need to install a udev rule file with your application +for unprivileged users to be able to access HID devices with hidapi. Refer +to the [69-hid-udev.rules](udev/69-hid-udev.rules) file in the `udev` directory +for an example. + __Linux/hidraw__ (`linux/hid.c`): This back-end uses the hidraw interface in the Linux kernel, and supports diff --git a/udev/69-hid.rules b/udev/69-hid.rules new file mode 100644 index 0000000..dc2df90 --- /dev/null +++ b/udev/69-hid.rules @@ -0,0 +1,33 @@ +# This is a sample udev file for HIDAPI devices which lets unprivileged +# users who are physically present at the system (not remote users) access +# HID devices. + +# If you are using the libusb implementation of hidapi (libusb/hid.c), then +# use something like the following line, substituting the VID and PID with +# those of your device. + +# HIDAPI/libusb +SUBSYSTEM=="usb", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="003f", TAG+="uaccess" + +# If you are using the hidraw implementation (linux/hid.c), then do something +# like the following, substituting the VID and PID with your device. + +# HIDAPI/hidraw +KERNEL=="hidraw*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="003f", TAG+="uaccess" + +# Once done, optionally rename this file for your application, and drop it into +# /etc/udev/rules.d. Note that these rules must have priorty before 70-uaccess.rules +# for example, name the file /etc/udev/rules.d/69-my-application-hid.rules. +# Then, replug your device or run: +# sudo udevadm control --reload-rules && sudo udevadm trigger + +# Note that the hexadecimal values for VID and PID are case sensitive and +# must be lower case. + +# TAG+="uaccess" only gives permission to physically present users, which +# is appropriate in most scenarios. If you require remote access to the +# device, add +# GROUP="plugdev", MODE="660" +# to the end of the udev rule lines, add your user to the plugdev group with: +# usermod -aG plugdev USERNAME +# then log out and log back in (or restart the system). diff --git a/udev/99-hid.rules b/udev/99-hid.rules deleted file mode 100644 index 0385f50..0000000 --- a/udev/99-hid.rules +++ /dev/null @@ -1,33 +0,0 @@ -# This is a sample udev file for HIDAPI devices which changes the permissions -# to 0666 (world readable/writable) for a specified device on Linux systems. - - -# If you are using the libusb implementation of hidapi (libusb/hid.c), then -# use something like the following line, substituting the VID and PID with -# those of your device. Note that for kernels before 2.6.24, you will need -# to substitute "usb" with "usb_device". It shouldn't hurt to use two lines -# (one each way) for compatibility with older systems. - -# HIDAPI/libusb -SUBSYSTEM=="usb", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="003f", MODE="0666" - - -# If you are using the hidraw implementation (linux/hid.c), then do something -# like the following, substituting the VID and PID with your device. Busnum 1 -# is USB. - -# HIDAPI/hidraw -KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="003f", MODE="0666" - -# Once done, optionally rename this file for your device, and drop it into -# /etc/udev/rules.d and unplug and re-plug your device. This is all that is -# necessary to see the new permissions. Udev does not have to be restarted. - -# Note that the hexadecimal values for VID and PID are case sensitive and -# must be lower case. - -# If you think permissions of 0666 are too loose, then see: -# http://reactivated.net/writing_udev_rules.html for more information on finer -# grained permission setting. For example, it might be sufficient to just -# set the group or user owner for specific devices (for example the plugdev -# group on some systems).