Skip to Content
DocumentationDesktop ApplicationLinux Tips

Linux Tips

KeepKey devices communicate with your computer via USB, and Linux requires specific permissions to access USB devices. Without the right udev rules and group membership, you’ll hit permission errors or the device won’t be recognized at all.

This guide gets you from “device not detected” to “everything works.”

The short version

If you just want it to work:

# Install the official KeepKey udev rules
sudo curl -fsSL https://raw.githubusercontent.com/keepkey/udev-rules/master/51-usb-keepkey.rules \
  -o /etc/udev/rules.d/51-usb-keepkey.rules
 
# Make sure the rules file is readable
sudo chmod 644 /etc/udev/rules.d/51-usb-keepkey.rules
 
# Reload udev — no reboot needed
sudo udevadm control --reload-rules
sudo udevadm trigger
 
# Add yourself to the plugdev group
sudo usermod -a -G plugdev $USER

Log out and back in (for the group change to take effect), unplug and reconnect your KeepKey, then launch the desktop application. Device should be detected.

The rest of this page explains what those commands actually do and how to troubleshoot when they don’t work.

Why udev rules are needed

udev is the Linux subsystem that handles devices when they’re plugged in. By default, unrecognized USB devices can only be accessed by root — which is why the KeepKey desktop application can’t see your device until you add rules that explicitly grant user access.

The rules do three things:

  • Grant permissions — your user account can read and write the device.
  • Assign a group — the device belongs to the plugdev group, so any user in that group can use it.
  • Create a predictable symlink — /dev/keepkey0, /dev/keepkey1, etc.

The rules file

The official rules support both HID and WebUSB firmware modes:

# KeepKey HID firmware / bootloader (product ID 0x0001)
SUBSYSTEM=="usb", ATTR{idVendor}=="2b24", ATTR{idProduct}=="0001", MODE="0666", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl", SYMLINK+="keepkey%n"
KERNEL=="hidraw*", ATTRS{idVendor}=="2b24", ATTRS{idProduct}=="0001", MODE="0666", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl"
 
# KeepKey WebUSB firmware / bootloader (product ID 0x0002)
SUBSYSTEM=="usb", ATTR{idVendor}=="2b24", ATTR{idProduct}=="0002", MODE="0666", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl", SYMLINK+="keepkey%n"
KERNEL=="hidraw*", ATTRS{idVendor}=="2b24", ATTRS{idProduct}=="0002", MODE="0666", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl"

What each piece means:

  • SUBSYSTEM=="usb" — matches USB devices
  • ATTR{idVendor}=="2b24" — KeepKey’s vendor ID (all KeepKeys)
  • ATTR{idProduct}=="0001" or "0002" — KeepKey product IDs (HID firmware or WebUSB firmware)
  • MODE="0666" — read/write permissions for all users
  • GROUP="plugdev" — assigns the device to the plugdev group
  • TAG+="uaccess" — enables per-user access via systemd
  • SYMLINK+="keepkey%n" — creates /dev/keepkey0, /dev/keepkey1, etc.

Installation

Option 1 — download the official rules (recommended)

sudo curl -fsSL https://raw.githubusercontent.com/keepkey/udev-rules/master/51-usb-keepkey.rules \
  -o /etc/udev/rules.d/51-usb-keepkey.rules
sudo chmod 644 /etc/udev/rules.d/51-usb-keepkey.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Option 2 — create the file manually

sudo nano /etc/udev/rules.d/51-usb-keepkey.rules
# Paste the rules from above, save and exit
sudo chmod 644 /etc/udev/rules.d/51-usb-keepkey.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Adding yourself to the plugdev group

For the rules to grant you access, your user needs to be in the plugdev group:

sudo usermod -a -G plugdev $USER
groups $USER   # verify 'plugdev' is in the output

You must log out and back in for the group change to take effect. Running newgrp plugdev in a single shell works too, but only for that shell.

Verification

After installing the rules and logging back in, check everything:

# Is the rules file in place?
ls -la /etc/udev/rules.d/51-usb-keepkey.rules
 
# Are you in the plugdev group?
groups $USER
 
# Is the KeepKey being detected by the USB subsystem?
lsusb | grep 2b24

If lsusb shows your KeepKey (vendor ID 2b24), you’re in good shape. Launch the desktop application — it should detect the device immediately.

Troubleshooting

”Device not detected” in the desktop application

# 1. Is the device visible to USB at all?
lsusb
 
# Look for a line with vendor ID 2b24 — KeepKey's ID
lsusb | grep 2b24

If lsusb shows nothing, the problem is lower than udev — try a different USB cable, port, or (worst case) a different computer to rule out hardware.

If lsusb shows the device but the desktop application still can’t see it, the rules aren’t being applied:

# Check that rules are loaded
sudo udevadm test /sys/class/usb_device/$(lsusb | grep 2b24 | awk '{print $4}' | tr -d ':') 2>&1 | tail

“Permission denied” when the desktop application tries to open the device

Usually means your user isn’t in plugdev, or you haven’t logged back in since adding yourself.

groups $USER | grep plugdev || echo "NOT in plugdev — run: sudo usermod -a -G plugdev \$USER"
ls -la /dev/hidraw*

/dev/hidraw* should be owned by group plugdev with mode 660 or 666. If it’s owned by root:root with 600, the udev rules aren’t being applied — run sudo udevadm control --reload-rules && sudo udevadm trigger and unplug/replug the device.

Rules file syntax errors

sudo udevadm verify /etc/udev/rules.d/51-usb-keepkey.rules

Distribution-specific notes

  • Ubuntu / Debian — works out of the box. plugdev group exists by default.
  • Arch Linux — plugdev may not exist. Create it if needed: sudo groupadd plugdev.
  • Fedora / RHEL — works out of the box. If you run into issues, SELinux shouldn’t interfere, but ausearch -m avc -ts recent will tell you if it is.
  • Raspberry Pi OS — same as Debian. Watch out for USB power supply — the Pi can under-power the KeepKey if your power brick is marginal.

Why the permissions are broad

The rules use MODE="0666", which grants read/write to everyone on the system. This is intentional and safe because the rules are scoped to only KeepKey’s vendor ID — no other USB device gets these permissions. If you’re on a single-user machine, the broad mode is fine. If you’re on a shared machine, you can tighten it to MODE="0660" and rely on the plugdev group membership to gate access.

Still stuck?

Open an issue at github.com/keepkey/keepkey-vault/issues  with:

  • Your distribution and version (cat /etc/os-release)
  • The output of lsusb | grep 2b24
  • The output of ls -la /dev/hidraw*
  • The output of groups $USER

That’s usually enough to diagnose any remaining permission problem.

Last updated on
InstallOnboarding