# Linux Tips

import StepVideo from '@/components/StepVideo'

# 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."

<StepVideo id="01-3-connect-linux" />

## The short version

If you just want it to work:

```bash
# 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:

```bash
# 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)

```bash
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

```bash
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:

```bash
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:

```bash
# 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

```bash
# 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:

```bash
# 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.

```bash
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

```bash
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](https://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.