Linux Tips for KeepKey

This guide covers essential Linux configuration for using your KeepKey device, including udev rules and file permissions.

Why Linux Configuration is Needed

KeepKey devices communicate with your computer via USB, and Linux requires specific permissions to access USB devices. Without proper configuration, you may encounter permission errors or the device won’t be recognized.

Understanding udev Rules

udev rules are Linux system configurations that define how devices are handled when they’re connected. For KeepKey, these rules ensure:

Proper permissions: Your user account can access the device
Consistent naming: The device gets a predictable name
Security: Only authorized users can access the device

KeepKey udev Rules

The official KeepKey udev rules support both HID and WebUSB firmware modes:


# KeepKey: Your Private Bitcoin Vault
# http://www.keepkey.com/
# Put this file into /usr/lib/udev/rules.d or /etc/udev/rules.d
 
# KeepKey HID Firmware/Bootloader
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
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 Rule Does

SUBSYSTEM=="usb": Applies to USB devices
ATTR{idVendor}=="2b24": KeepKey’s vendor ID
ATTR{idProduct}=="0001": HID firmware product ID
ATTR{idProduct}=="0002": WebUSB firmware product ID
MODE="0666": Sets read/write permissions for all users
GROUP="plugdev": Adds device to plugdev group
TAG+="uaccess": Enables user access control
SYMLINK+="keepkey%n": Creates a symbolic link for easy access

Step-by-Step Installation

Method 1: Using wget (Recommended)


# Download the udev rules file
sudo wget -O /etc/udev/rules.d/51-usb-keepkey.rules https://raw.githubusercontent.com/keepkey/udev-rules/master/51-usb-keepkey.rules
 
# Set proper permissions on the rules file
sudo chmod 644 /etc/udev/rules.d/51-usb-keepkey.rules
 
# Reload udev rules (no reboot needed)
sudo udevadm control --reload-rules
sudo udevadm trigger

Method 2: Manual Installation


# Create the rules file
sudo nano /etc/udev/rules.d/51-usb-keepkey.rules
 
# Copy and paste the rules content above
# Save and exit (Ctrl+X, Y, Enter in nano)
 
# Set proper permissions
sudo chmod 644 /etc/udev/rules.d/51-usb-keepkey.rules
 
# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Adding User to plugdev Group

For the rules to work properly, your user needs to be in the plugdev group:


# Add your user to the plugdev group
sudo usermod -a -G plugdev $USER
 
# Verify the group was added
groups $USER

Note: You’ll need to log out and back in for the group changes to take effect.

Understanding chmod -x

The chmod -x command removes execute permissions from a file. This is sometimes needed for security reasons:


# Remove execute permission from a file
chmod -x filename
 
# Remove execute permission from all files in a directory
chmod -x *
 
# Check current permissions
ls -la filename

When You Might Need chmod -x

Security: Removing execute permissions from downloaded files
File type: Ensuring a file is treated as data, not executable
Troubleshooting: If a file has unexpected execute permissions

Verification Steps

After installing the udev rules, verify everything is working:


# Check if the rules file exists
ls -la /etc/udev/rules.d/51-usb-keepkey.rules
 
# Verify file permissions
ls -la /etc/udev/rules.d/51-usb-keepkey.rules
 
# Check if you're in the plugdev group
groups $USER
 
# Test device detection (plug in your KeepKey first)
lsusb | grep 2b24

Troubleshooting

Device Not Recognized


# Check if the device is detected
lsusb
 
# Look for KeepKey entries
lsusb | grep -i keepkey
 
# Check udev rules are loaded
sudo udevadm test /sys/class/usb_device/$(lsusb | grep 2b24 | cut -d' ' -f4 | cut -d':' -f1)

Permission Denied Errors


# Check device permissions
ls -la /dev/hidraw*
 
# Verify group membership
groups $USER
 
# Check udev rules syntax
sudo udevadm verify /etc/udev/rules.d/51-usb-keepkey.rules

Common Error Messages

“Permission denied”: User not in plugdev group or rules not loaded
“Device not found”: udev rules not installed or device not connected
“Operation not permitted”: Insufficient permissions on rules file

Reboot Requirements

Good news: You typically don’t need to reboot after installing udev rules. The udevadm commands reload the rules immediately.

However, you may need to:

Log out and back in if you added yourself to the plugdev group
Unplug and reconnect your KeepKey device
Restart your wallet application to pick up the new permissions

Security Considerations

The udev rules give broad permissions (0666) to KeepKey devices. This is normal and necessary for the device to function properly. The rules are specific to KeepKey’s vendor ID, so they won’t affect other USB devices.

Distribution-Specific Notes

Ubuntu/Debian

Rules work out of the box
plugdev group exists by default

Arch Linux

May need to install udev package
plugdev group might not exist (create it if needed)

Fedora/RHEL

Rules work out of the box
SELinux might require additional configuration

Raspberry Pi

Same installation process
May need to run as root for initial setup

Next Steps

After configuring Linux permissions:

Test your KeepKey: Connect it and verify it’s recognized
Install wallet software: Download your preferred wallet application
Initialize device: Follow the setup guide for your specific wallet
Create backup: Always write down your recovery phrase

Support

If you continue to have issues after following this guide:

Check the KeepKey Support page
Verify your device is genuine KeepKey hardware
Try a different USB cable or port
Check your wallet application’s Linux compatibility