udev-demo

This repository demonstrates how setup_devtmpfs in a privileged container makes hotplugged devices easier to handle at runtime.

Why this exists

Containers are not primarily designed for dynamic hardware enumeration. In many deployments, the device namespace visible in a container is effectively fixed at container start. That can make runtime attach/detach events hard to handle cleanly.

This project uses a dedicated devtmpfs mount and runs udevd inside the container so device nodes and udev event handling are managed in a way that is much closer to host behavior.

devtmpfs (device temporary filesystem) is a Linux virtual filesystem in RAM that the kernel automatically manages to create and maintain device nodes under /dev.

In practice, this means device node creation/removal can track hardware events as they happen, instead of relying on a static /dev layout from container startup. The kernel provides the base device nodes through devtmpfs, and udev applies policy on top (permissions, ownership, symlinks, and event-driven actions). Together, that makes runtime hotplug behavior more predictable for containerized applications.

How setup_devtmpfs helps

The function in entrypoint.sh:

1. mounts a fresh devtmpfs at /tmp/dev
2. moves required mounts (/dev/console, /dev/pts, /dev/shm, etc.) into it
3. replaces /dev with that new mount
4. restores /dev/ptmx symlink

After that, udevd --daemon is started and your main command runs. This setup improves handling of hardware that appears/disappears while the container is already running.

Runtime flow in this repo

• entrypoint.sh configures /dev with setup_devtmpfs, starts udevd, then executes the container command.
• idle.sh reloads udev rules, triggers initial events, and keeps the container alive.
• 48-usb-hid.rules is the active demo rule installed into /etc/udev/rules.d/ by the Docker image.

Platform notes

• Primary target: balenaOS and native Linux environments where privileged containers and host device/sysfs integration are expected.
• macOS/Docker Desktop caveat: Docker Desktop runs Linux in a VM, so host USB hotplug and udev behavior can differ from native Linux. Treat local macOS runs as partial validation only.

Additional examples

The repository includes more rule examples under additional_examples/, organized by device type:

• usb-device
• camera
• screen-drm
• usb-serial
• input-touch

Each directory includes commented .rules files showing matching patterns and common actions for that device class.

These examples are not active by default. To use one, copy the selected .rules file into /etc/udev/rules.d/, then reload rules:

udevadm control --reload-rules
udevadm trigger

Usage

From the repository root, where myFleet is your balenaCloud fleet name:

balena push myFleet