{"id":16391796,"url":"https://github.com/williamfzc/usb2container","last_synced_at":"2025-03-16T16:31:15.036Z","repository":{"id":51352684,"uuid":"218451819","full_name":"williamfzc/usb2container","owner":"williamfzc","description":"binding specific USB devices to container","archived":false,"fork":false,"pushed_at":"2024-04-25T05:03:21.000Z","size":20,"stargazers_count":21,"open_issues_count":2,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-13T09:45:55.279Z","etag":null,"topics":["container","devpath","docker","usb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamfzc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-10-30T05:43:54.000Z","updated_at":"2024-04-21T03:25:58.000Z","dependencies_parsed_at":"2024-10-11T04:47:24.162Z","dependency_job_id":"7c18cb81-33f7-44ed-9207-8576e9d5a0d4","html_url":"https://github.com/williamfzc/usb2container","commit_stats":{"total_commits":28,"total_committers":1,"mean_commits":28.0,"dds":0.0,"last_synced_commit":"f37f974345d8327f5b9cee12d12ee25f829a130d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fusb2container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fusb2container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fusb2container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamfzc%2Fusb2container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamfzc","download_url":"https://codeload.github.com/williamfzc/usb2container/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822283,"owners_count":20353499,"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":["container","devpath","docker","usb"],"created_at":"2024-10-11T04:47:22.380Z","updated_at":"2025-03-16T16:31:14.733Z","avatar_url":"https://github.com/williamfzc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e 2022/1/28: This project should only be used in a single node. In K8S, you 'd better consider persistent-volumes first.\n\n# usb2container\n\noffer a way binding specific USB devices to container\n\n## goal\n\nIt's hard for us to bind a specific USB device to a docker container which is also specific. As you can see, the recommended way (from [stackoverflow](https://stackoverflow.com/questions/24225647/docker-a-way-to-give-access-to-a-host-usb-or-serial-device)) to achieve is:\n\n```bash\ndocker run -t -i --privileged -v /dev/bus/usb:/dev/bus/usb ubuntu bash\n``` \n\nIt will bind all the devices to this container. It's unsafe. Every containers were granted to operate all of them.\n\nAnother way is binding devices by devpath. It may looks like:\n\n```bash\ndocker run -t -i --privileged -v /dev/bus/usb/001/002:/dev/bus/usb/001/002 ubuntu bash\n```\n\nor `--device` (better, no `privileged`):\n\n```bash\ndocker run -t -i --device /dev/bus/usb/001/002 ubuntu bash\n```\n\nMuch safer. But actually it is hard to know what the devpath of a specific device is.\n\n**This repo aims at offering a easy way for developers to get devpath of devices.**\n\n## usage\n\nby default, it will start a http server on port 9410.\n\n### start usb2container service\n\nAll the information can be accessed via HTTP request. So you should deploy HTTP server firstly. It is not difficult. \n\n#### normal way\n\n```bash\npip install usb2container\n```\n\nstart server:\n\n```bash\nusb2container start\n```\n\nor running on another port (eg: 9646):\n\n```bash\nusb2container start 9646\n```\n\n#### docker\n\n```bash\ndocker run -d --privileged \\\n    -v /dev/bus/usb:/dev/bus/usb \\\n    -v /run/udev:/run/udev:ro \\\n    --name usb2container \\\n    --restart always \\\n    --net=host \\\n    williamfzc/usb2container\n```\n\nbecause of `--net=host` (**it is necessary**), you can not use port mapping. if you wanna run it on another port, you may need to edit Dockerfile and build it by yourself.\n\n### access via HTTP\n\nif everything is fine, you will see:\n\n```text\nemail-validator not installed, email fields will be treated as str.\nTo install, run: pip install email-validator\n2019-11-08 07:50:03.861 | INFO     | pyudevmonitor.monitor:start:26 - udevadm process up\n2019-11-08 07:50:03.863 | INFO     | usb2container.server:start:42 - usb2container ver 0.1.1\nINFO:     Started server process [1]\nINFO:     Uvicorn running on http://0.0.0.0:9410 (Press CTRL+C to quit)\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\n```\n\nplug USB devices in after starting server, and then send a request to get all the devices:\n\n```bash\ncurl 127.0.0.1:9410/api/device\n```\n\nyou can access all the connected devices' info:\n\n```text\n{\n\t\"/devices/pci0000:00/0000:00:14.0/usb1/1-13\": {\n\t\t\"ACTION\": \"add\",\n\t\t\"DEVPATH\": \"/devices/pci0000:00/0000:00:14.0/usb1/1-13\",\n\t\t\"DEVTYPE\": \"usb_device\",\n\t\t\"DRIVER\": \"usb\",\n\t\t\"ID_BUS\": \"usb\",\n\t\t\"ID_FOR_SEAT\": \"xxxxx\",\n\t\t\"ID_MODEL\": \"xxxxx\",\n\t\t\"ID_MODEL_ID\": \"xxxxx\",\n\t\t\"ID_PATH\": \"xxxxx\",\n\t\t\"ID_PATH_TAG\": \"xxxxx\",\n\t\t\"ID_REVISION\": \"xxxxx\",\n\t\t\"ID_SERIAL\": \"xxxxx\",\n\t\t\"ID_SERIAL_SHORT\": \"xxxxx\",\n\t\t\"ID_USB_INTERFACES\": \"xxxxx\",\n\t\t\"ID_VENDOR\": \"xxxxx\",\n\t\t\"ID_VENDOR_ENC\": \"xxxxx\",\n\t\t\"ID_VENDOR_FROM_DATABASE\": \"\",\n\t\t\"ID_VENDOR_ID\": \"xxxxx\",\n\t\t\"INTERFACE\": \"\",\n\t\t\"MAJOR\": \"189\",\n\t\t\"MINOR\": \"119\",\n\t\t\"MODALIAS\": \"\",\n\t\t\"PRODUCT\": \"xxxxx\",\n\t\t\"SEQNUM\": \"xxxxx\",\n\t\t\"SUBSYSTEM\": \"usb\",\n\t\t\"TAGS\": \"\",\n\t\t\"TYPE\": \"0/0/0\",\n\t\t\"USEC_INITIALIZED\": \"xxxxx\",\n\t\t\"adb_user\": \"\",\n\t\t\"_empty\": false,\n\t\t\"DEVNAME\": \"/dev/bus/usb/001/120\",\n\t\t\"BUSNUM\": \"001\",\n\t\t\"DEVNUM\": \"120\",\n\t\t\"ID_MODEL_ENC\": \"xxxxx\"\n\t},\n    ...\n}\n```\n\nand bind them to your containers. For example, you can see the DEVNAME of this device is `/dev/bus/usb/001/120`:\n\n```bash\ndocker run -t -i --device /dev/bus/usb/001/120 ubuntu bash\n```\n\n## dependencies\n\n- [pyudevmonitor](https://github.com/williamfzc/pyudevmonitor)\n- [fastapi](https://github.com/tiangolo/fastapi)\n\n## license\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamfzc%2Fusb2container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamfzc%2Fusb2container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamfzc%2Fusb2container/lists"}