{"id":20981981,"url":"https://github.com/lowrisc/container-hotplug","last_synced_at":"2025-05-14T16:31:00.605Z","repository":{"id":61562880,"uuid":"551558149","full_name":"lowRISC/container-hotplug","owner":"lowRISC","description":"Hot-plug devices into a Docker container as they are plugged.","archived":false,"fork":false,"pushed_at":"2025-03-18T13:48:51.000Z","size":272,"stargazers_count":7,"open_issues_count":2,"forks_count":4,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-02T20:38:27.643Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lowRISC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-14T16:22:55.000Z","updated_at":"2025-03-18T13:48:55.000Z","dependencies_parsed_at":"2024-03-03T18:29:16.726Z","dependency_job_id":"6f03d9c2-0a22-46cc-b3a6-18425e225ea1","html_url":"https://github.com/lowRISC/container-hotplug","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowRISC%2Fcontainer-hotplug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowRISC%2Fcontainer-hotplug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowRISC%2Fcontainer-hotplug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowRISC%2Fcontainer-hotplug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lowRISC","download_url":"https://codeload.github.com/lowRISC/container-hotplug/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254182792,"owners_count":22028363,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T05:42:06.945Z","updated_at":"2025-05-14T16:31:00.077Z","avatar_url":"https://github.com/lowRISC.png","language":"Rust","readme":"# container-hotplug\n\nHot-plug (and unplug) devices into a container as they are (un)plugged.\n\n## Description\n\nDocker provides the `--device` flag to give a container access to a device.\nHowever the devices specified this way must be present when the container is created.\n\nFor dynamically created devices Docker provides the `--device-cgroup-rule`.\nHowever this requires knowing the device's major and minor numbers, which are dynamically allocated by the kernel.\nThe rule accepts a glob `*` to mean \"any minor\" or \"any major\".\nHowever this would still give the container access to all the devices handled by a particular driver.\n\nThis program tries to solve that problem by listening to udev events to detect when a device is (un)plugged.\nIt then interfaces directly with the container's cgroup to grant it access to that specific device.\n\nTo limit the devices the container can access, a _root device_ is specified.\nThe container will receive access to any device descending from the root device.\nThis is particularly useful if the root device is set to a USB hub.\nThe hub can be specified directly, or it can be specified as \"the parent of device X\",\ne.g., we can giving a container access to all devices connected to the same hub as an Arduino board.\n\nAnother concern is providing a container with well known paths for the devices.\nOn bare-metal systems this would usually be achieved with a `SYMLINK` directive in a udev rule.\nThis program tries to provide a similar functionality for containers, allowing you to specify symlinks for certain devices.\n\n## Usage\n\nThis tool wraps `runc` with the additional hotplug feature, therefore it can be used as a drop in replace for\nmany container managers/orchestrators such as Docker, Podman, and Kubernetes. You need to ensure `runc` is available in your `PATH`\nso `container-hotplug` can find it.\n\nIt supports two annotations, `org.lowrisc.hotplug.device` and `org.lowrisc.hotplug.symlinks`.\n\nFor Docker, you can specify an alternative runtime by [changing /etc/docker/daemon.json](https://docs.docker.com/engine/alternative-runtimes/#youki):\n```json\n{\n  \"runtimes\": {\n    \"hotplug\": {\n      \"path\": \"/path/to/container-hotplug/binary\"\n    }\n  }\n}\n```\nand use it with the `--runtime hotplug` flag and appropriate annotation, e.g.\n```bash\nsudo docker run --runtime hotplug -it --annotation org.lowrisc.hotplug.device=parent-of:usb:2b2e:c310 ubuntu:latest\n```\n\nFor podman, you can specify the path directly, by:\n```bash\nsudo podman run --runtime /path/to/container-hotplug/binary -it --annotation org.lowrisc.hotplug.device=parent-of:usb:2b2e:c310 ubuntu:latest\n```\n\nFor containerd (e.g. when using kubernetes), you can edit `/etc/containerd/config.toml` to add:\n```toml\n[plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.hotplug]\n  runtime_type = \"io.containerd.runc.v2\"\n  pod_annotations = [\"org.lowrisc.hotplug.*\"]\n\n[plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.hotplug.options]\n  SystemdCgroup = true\n  BinaryName = \"/path/to/container-hotplug/binary\"\n```\nthis would allow you to use `hotplug` as handler in k8s, e.g. add a runtime class with\n```yaml\napiVersion: node.k8s.io/v1\nkind: RuntimeClass\nmetadata:\n  name: hotplug\nhandler: hotplug\n```\nand use it in a pod with\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: ubuntu\n  annotations:\n    org.lowrisc.hotplug.device: parent-of:usb:0bda:5634\nspec:\n  runtimeClassName: hotplug\n  containers:\n  - name: ubuntu\n    image: ubuntu:latest\n    stdin: true\n    tty: true\n```\n\nIf you want symlinks to the `tty` devices created by interfaces 1 and 3 of the CW310, add\n```\n--annotation org.lowrisc.hotplug.symlinks=usb:2b3e:c310:1=/dev/ttyACM_CW310_0,usb:2b3e:c310:3=/dev/ttyACM_CW310_1\n```\nto docker/podman command line or\n```\norg.lowrisc.hotplug.symlinks: usb:2b3e:c310:1=/dev/ttyACM_CW310_0,usb:2b3e:c310:3=/dev/ttyACM_CW310_1\n```\nto k8s config.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowrisc%2Fcontainer-hotplug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flowrisc%2Fcontainer-hotplug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowrisc%2Fcontainer-hotplug/lists"}