{"id":18690441,"url":"https://github.com/kvaps/usbredirtools","last_synced_at":"2026-03-27T03:10:16.695Z","repository":{"id":80916129,"uuid":"42306145","full_name":"kvaps/usbredirtools","owner":"kvaps","description":"Collection of scripts for passing through the usb-devices to VMs","archived":false,"fork":false,"pushed_at":"2019-08-18T17:33:19.000Z","size":39,"stargazers_count":18,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T05:54:42.038Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/kvaps.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":"2015-09-11T12:03:58.000Z","updated_at":"2023-12-24T16:22:49.000Z","dependencies_parsed_at":"2023-03-20T15:19:05.759Z","dependency_job_id":null,"html_url":"https://github.com/kvaps/usbredirtools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kvaps/usbredirtools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvaps%2Fusbredirtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvaps%2Fusbredirtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvaps%2Fusbredirtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvaps%2Fusbredirtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kvaps","download_url":"https://codeload.github.com/kvaps/usbredirtools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvaps%2Fusbredirtools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31013961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T02:58:54.984Z","status":"ssl_error","status_checked_at":"2026-03-27T02:58:46.993Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-07T10:47:35.598Z","updated_at":"2026-03-27T03:10:16.678Z","avatar_url":"https://github.com/kvaps.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"usbredirtools\n=============\nThese scripts help you passthrough many identical usb-devices (with the same vendorid:productid pair) for selected virtual machines, using [usbredir](http://www.spice-space.org/page/UsbRedir) protocol in daemon mode, without using spice.\n\n## USB Server install\n  - Install **usbredirserver**, **inotifywait** and **fuser** packages, it is required\n  - Install units and script:\n```bash\ncurl -o /etc/systemd/system/usbredirserver\\@.service https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredirserver%40.service\ncurl -o /etc/systemd/system/usbredirserver.service https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredirserver.service\ncurl -o /bin/usbredirserver.sh https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredirserver.sh\nchmod +x /bin/usbredirserver.sh\n```\n  - `mkdir /var/lib/usbredirserver/`\n\n#### Export usb-devce\n  - run `lsusb`, find your device:\n```\nBus 003 Device 090: ID 125f:c82a A-DATA Technology Co., Ltd. \n```\n  - run `udevadm info -a -n /dev/bus/usb/003/090 | grep 'ATTR{serial}\\|KERNEL[^S]'`\n```\nKERNEL==\"3-2\"\nATTR{serial}==\"11C130317234004B\"\n```\n  - `vim /etc/udev/rules.d/99-usb-serial.rules`\n```\n# by serial number\nACTION==\"add\", ATTR{serial}==\"11C130317234004B\", RUN+=\"/bin/bash -c 'PORT=4000; echo -e BUS=$attr{busnum}\\\\nDEV=$attr{devnum} \u003e /var/lib/usbredirserver/$PORT'\"\n# by phisical port\nACTION==\"add\", KERNEL==\"3-2\", RUN+=\"/bin/bash -c 'PORT=4000; echo -e BUS=$attr{busnum}\\\\nDEV=$attr{devnum} \u003e /var/lib/usbredirserver/$PORT'\"\n```\n  - `udevadm control --reload-rules`\n  - Start and enable usbredirserver service:\n```bash\nsystemctl start usbredirserver.service\nsystemctl enable usbredirserver.service\n```\n\n## Hypervisor install (opennebula)\n\n#### hook setup\n  - `curl https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredir_hook.sh -o /var/lib/one/remotes/hooks/usbredir_hook.sh`\n  - `chmod +x /var/lib/one/remotes/hooks/usbredir_hook.sh`\n  - Declare hook in `/etc/one/oned.conf`:\n```\nVM_HOOK = [\n    name      = \"usbredir_connect\",\n    on        = \"RUNNING\",\n    command   = \"usbredir_hook.sh\",\n    arguments = \"connect $ID $TEMPLATE\" ]\n\nVM_HOOK = [\n    name      = \"usbredir_disconnect\",\n    on        = \"CUSTOM\",\n    state     = \"ACTIVE\",\n    lcm_state = \"SAVE_SUSPEND\",\n    command   = \"usbredir_hook.sh\",\n    arguments = \"disconnect $ID $TEMPLATE\" ]\n```\n  - `systemctl restart opennebula` \n\n#### vm setup\n  - add this code to your template, into kvm raw data section:\n```xml\n\u003cdevices\u003e\n\u003ccontroller type='usb' index='0' model='ich9-ehci1'\u003e\u003caddress type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x7'/\u003e\u003c/controller\u003e\n\u003ccontroller type='usb' index='0' model='ich9-uhci1'\u003e\u003cmaster startport='0'/\u003e\u003caddress type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x0' multifunction='on'/\u003e\u003c/controller\u003e\n\u003ccontroller type='usb' index='0' model='ich9-uhci2'\u003e\u003cmaster startport='2'/\u003e\u003caddress type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x1'/\u003e\u003c/controller\u003e\n\u003ccontroller type='usb' index='0' model='ich9-uhci3'\u003e\u003cmaster startport='4'/\u003e\u003caddress type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x2'/\u003e\u003c/controller\u003e\n\u003c/devices\u003e\n```\n  - add your usb devices into your template, like:\n```\nUSBREDIR0=\"192.168.1.123:4000\"\nUSBREDIR1=\"192.168.1.123:4001\"\n```\n\n\n## Hypervisor install (proxmox)\n\n#### qemu setup\n  - `curl http://cgit.freedesktop.org/spice/qemu/plain/docs/ich9-ehci-uhci.cfg --create-dirs -o /etc/qemu/ich9-ehci-uhci.cfg`\n\n#### vm setup\n  - add this options to start command in virtual machine config file into `args` section:\n```\n  -readconfig /etc/qemu/ich9-ehci-uhci.cfg\n  -chardev socket,id=charredir3,port=4000,host=192.168.1.123\n  -device usb-redir,chardev=charredir3,id=redir3,bus=usb.0\n```\n\n## Watchdog service\n\nOptionally, you may install usbredirwatchdog service on your hypervisors, it will reconnect the usb-devices if they was disconnected for some reasons.\n\nIt works this way:\nEvery `n` times, watchdog script calls `ps aux` and checks for running virtual machines with chadredir parameters.\nAfter this watchdog script check the status of each chardev and reconnect it if it does not exist or disconnected.\nThe frequency is configured as the first script argument, by default it is 10 seconds.\nWarning: this watchdog does not work with devices connected via opennebula hook.\n\n#### Install instructions\n  - For proxmox you need install **expect** package.\n  - `curl https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredirwatchdog.sh -o /usr/local/bin/usbredirwatchdog.sh`\n  - `chmod +x /usr/local/bin/usbredirwatchdog.sh`\n  - `curl https://raw.githubusercontent.com/kvaps/usbredirtools/master/usbredirwatchdog.service -o /etc/systemd/system/usbredirwatchdog.service`\n  - `systemctl enable usbredirwatchdog`\n  - `systemctl start usbredirwatchdog`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvaps%2Fusbredirtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkvaps%2Fusbredirtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvaps%2Fusbredirtools/lists"}