# udev_monitor
# Monitor linux udev events and execute actions on detection
## Designed to execute actions when USB devices are plugged-in / removed
[](https://opensource.org/licenses/BSD-3-Clause)
[](http://isitmaintained.com/project/netinvent/udev_monitor "Percentage of issues still open")
[](https://github.com/netinvent/udev_monitor/actions/workflows/pylint-linux.yaml)
[](https://github.com/netinvent/udev_monitor/releases/latest)
udev_monitor works with Linux udev and monitors it's events.
Upon a specific event for a given device (in VENDOR_ID:PRODUCT_ID format), it will execute an action.
udev_monitor has been used to:
- Re-attach USB devices to virtual machines after they're unplugged - plugged in again
- Run a full USB reset when device is plugged in (fixes some of the USB UPS that identify as Cypress Semiconductor USB to Serial)
# Setup
```
pip install udev_monitor
```
# Quickstart example
This is a realworld example to detect most USB UPS and execute a script upon plug-in.
Run script `/usr/local/bin/restart_nut_driver.sh` with argument `0665:5161` everytime USB device with vendor id 0665 and product id 5161 is added or removed
```
udev_monitor --devices 0665:5161 --udev-actions add,remove --filters=usb --action /usr/local/bin/restart_nut_driver.sh
```
# Full usage
```
--devices List of comma separated devices to monitor. Example:
'0665:5161, 8086:1234'
If no devices are given, all devices are monitored.
--udev-actions List of udev events which should trigger and action
Valid actions are: 'add', 'remove', 'change', 'online', 'offline'. Defaults to 'add, change, online'
--filters List of comma separated udev monitor filters. Filters are applied with OR logic. Example:
'usb,tty'
--action Path to script. Script will get detected device as only argument.
--timeout Maximum execution time for script
--config Optional path to config file
```
# Optional configuration file layout
```
[UDEV_MONITOR]
devices = '0665:5161'
filters = 'usb'
action = '/path/to/script.sh'
udev_events = 'add'
timeout = 3600
```
# Setting monitor up as a service
- copy file `scripts/udev_monitor@.service` to `/etc/systemd/system`
- Reload daemons
- Create configuration file in `/etc/udev_monitor` from example config in `scripts/udev_monitor.conf.example`
- Launch service
Example:
```
cp scripts/udev_monitor\@.service to /etc/systemd/system
systemctl daemon-reload
mkdir /etc/udev_monitor
cat << EOF > /etc/udev_monitor/udev_monitor1.conf
devices = '0665:5161'
filters = 'usb'
action = '/path/to/script.sh'
udev_events = 'add'
timeout = 3600
EOF
systemctl enable --now udev_monitor@udev_monitor1.conf
```
You can launch multiple udev_monitor instances by creating multiple conf files and loading them with:
```
systemctl enable --now udev_monitor@umy_ups.conf
systemctl enable --now udev_monitor@my_modem.conf
systemctl enable --now udev_monitor@my_harddrive.conf
```
## Further examples
### Automatically attach an USB device (4G modem) to a KVM virtual machine with libvirt and udev_monitor
Let's imagine we have a Sierra 4G model that identifies as 1199:9097, and we would like to attach it to VM modem.vm.local
Grab yourself a copy of usb_reset via `pip install usb_reset`
Create the following script as `/usr/local/bin/attach_modem.sh` and make it executable with `chmod +x /usr/local/bin/attach_modem.sh`
```
#!/usr/bin/env bash
# /usr/local/bin/usb_reset.py --reset-device --device 1199:9071
virsh detach-device sms.badmin.local /root/4G_modem.xml
virsh attach-device sms.badmin.local /root/4G_modem.xml
```
Create the file `/root/4G_modem.xml` containing:
```
<hostdev mode='subsystem' type='usb' managed='yes'>
<source>
<vendor id='0x1199'/>
<product id='0x9071'/>
</source>
</hostdev>
```
Now we must execute that script everytime the USB 4G modem is plugged-in, so we get to re-attach it to the VM.
In order to do so, let's create the following conf file in `/etc/udev_monitor/modem.conf`
```
[UDEV_MONITOR]
devices = 1199:9071
filters = usb
action = /usr/local/bin/attach_modem.sh
udev_events = add
timeout = 300
```
Now let's create a systemd service by copying `udev_monitor@.service` from this git repo to `/etc/systemd/system`
Once this is done, we just can activate the service with `systemctl enable --now udev_monitor@modem.conf`
### Reset a lawless UPS USB
Some of the USB uninterrupted power supplies (smaller devices) have a quite unreliable USB/Serial interface.
Sometimes it's needed to restart the usb port for the device to work properly.
In that case, we can use udev_monitor to trigger a usb reset on device plug-in.
Raw data
{
"_id": null,
"home_page": "https://github.com/netinvent/udev_monitor",
"name": "udev-monitor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "shell,udev,usb,event,connect,plugged,plug and pray",
"author": "NetInvent - Orsiris de Jong",
"author_email": "contact@netinvent.fr",
"download_url": "https://files.pythonhosted.org/packages/29/32/ea0f9f4bbdba4343d41fc6575aac7de34c86db80147a766aa909f8e81cb7/udev_monitor-1.3.0.tar.gz",
"platform": null,
"description": "# udev_monitor\r\n# Monitor linux udev events and execute actions on detection\r\n## Designed to execute actions when USB devices are plugged-in / removed\r\n\r\n\r\n[](https://opensource.org/licenses/BSD-3-Clause)\r\n[](http://isitmaintained.com/project/netinvent/udev_monitor \"Percentage of issues still open\")\r\n[](https://github.com/netinvent/udev_monitor/actions/workflows/pylint-linux.yaml)\r\n[](https://github.com/netinvent/udev_monitor/releases/latest)\r\n\r\n\r\nudev_monitor works with Linux udev and monitors it's events.\r\nUpon a specific event for a given device (in VENDOR_ID:PRODUCT_ID format), it will execute an action.\r\n\r\nudev_monitor has been used to:\r\n - Re-attach USB devices to virtual machines after they're unplugged - plugged in again\r\n - Run a full USB reset when device is plugged in (fixes some of the USB UPS that identify as Cypress Semiconductor USB to Serial)\r\n\r\n# Setup\r\n```\r\npip install udev_monitor\r\n```\r\n\r\n# Quickstart example\r\nThis is a realworld example to detect most USB UPS and execute a script upon plug-in.\r\n\r\nRun script `/usr/local/bin/restart_nut_driver.sh` with argument `0665:5161` everytime USB device with vendor id 0665 and product id 5161 is added or removed\r\n```\r\nudev_monitor --devices 0665:5161 --udev-actions add,remove --filters=usb --action /usr/local/bin/restart_nut_driver.sh\r\n```\r\n\r\n# Full usage\r\n```\r\n--devices List of comma separated devices to monitor. Example:\r\n '0665:5161, 8086:1234'\r\n If no devices are given, all devices are monitored.\r\n--udev-actions List of udev events which should trigger and action\r\n Valid actions are: 'add', 'remove', 'change', 'online', 'offline'. Defaults to 'add, change, online'\r\n--filters List of comma separated udev monitor filters. Filters are applied with OR logic. Example:\r\n 'usb,tty'\r\n--action Path to script. Script will get detected device as only argument.\r\n--timeout Maximum execution time for script\r\n--config Optional path to config file\r\n```\r\n\r\n# Optional configuration file layout\r\n```\r\n[UDEV_MONITOR]\r\ndevices = '0665:5161'\r\nfilters = 'usb'\r\naction = '/path/to/script.sh'\r\nudev_events = 'add'\r\ntimeout = 3600\r\n```\r\n\r\n# Setting monitor up as a service\r\n\r\n- copy file `scripts/udev_monitor@.service` to `/etc/systemd/system`\r\n- Reload daemons\r\n- Create configuration file in `/etc/udev_monitor` from example config in `scripts/udev_monitor.conf.example`\r\n- Launch service\r\n\r\nExample:\r\n```\r\ncp scripts/udev_monitor\\@.service to /etc/systemd/system\r\nsystemctl daemon-reload\r\n\r\nmkdir /etc/udev_monitor\r\ncat << EOF > /etc/udev_monitor/udev_monitor1.conf\r\ndevices = '0665:5161'\r\nfilters = 'usb'\r\naction = '/path/to/script.sh'\r\nudev_events = 'add'\r\ntimeout = 3600\r\nEOF\r\n\r\nsystemctl enable --now udev_monitor@udev_monitor1.conf\r\n```\r\n\r\nYou can launch multiple udev_monitor instances by creating multiple conf files and loading them with:\r\n```\r\nsystemctl enable --now udev_monitor@umy_ups.conf\r\nsystemctl enable --now udev_monitor@my_modem.conf\r\nsystemctl enable --now udev_monitor@my_harddrive.conf\r\n```\r\n\r\n## Further examples\r\n\r\n### Automatically attach an USB device (4G modem) to a KVM virtual machine with libvirt and udev_monitor\r\n\r\nLet's imagine we have a Sierra 4G model that identifies as 1199:9097, and we would like to attach it to VM modem.vm.local\r\n\r\nGrab yourself a copy of usb_reset via `pip install usb_reset`\r\n\r\nCreate the following script as `/usr/local/bin/attach_modem.sh` and make it executable with `chmod +x /usr/local/bin/attach_modem.sh`\r\n\r\n```\r\n#!/usr/bin/env bash\r\n\r\n# /usr/local/bin/usb_reset.py --reset-device --device 1199:9071\r\n\r\nvirsh detach-device sms.badmin.local /root/4G_modem.xml\r\nvirsh attach-device sms.badmin.local /root/4G_modem.xml\r\n```\r\n\r\nCreate the file `/root/4G_modem.xml` containing:\r\n```\r\n <hostdev mode='subsystem' type='usb' managed='yes'>\r\n <source>\r\n <vendor id='0x1199'/>\r\n <product id='0x9071'/>\r\n </source>\r\n </hostdev>\r\n```\r\n\r\nNow we must execute that script everytime the USB 4G modem is plugged-in, so we get to re-attach it to the VM.\r\n\r\nIn order to do so, let's create the following conf file in `/etc/udev_monitor/modem.conf`\r\n```\r\n[UDEV_MONITOR]\r\ndevices = 1199:9071\r\nfilters = usb\r\naction = /usr/local/bin/attach_modem.sh\r\nudev_events = add\r\ntimeout = 300\r\n```\r\n\r\nNow let's create a systemd service by copying `udev_monitor@.service` from this git repo to `/etc/systemd/system`\r\n\r\nOnce this is done, we just can activate the service with `systemctl enable --now udev_monitor@modem.conf`\r\n\r\n### Reset a lawless UPS USB\r\n\r\nSome of the USB uninterrupted power supplies (smaller devices) have a quite unreliable USB/Serial interface.\r\nSometimes it's needed to restart the usb port for the device to work properly.\r\n\r\nIn that case, we can use udev_monitor to trigger a usb reset on device plug-in.\r\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Monitor udev events like usb devices being connected, and execute actions upon event",
"version": "1.3.0",
"split_keywords": [
"shell",
"udev",
"usb",
"event",
"connect",
"plugged",
"plug and pray"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d1816bb57a4b90468306d965d82da46441fde83b84a0bed36667cb23c009d3da",
"md5": "83cdd15f0b63a205bf8be9a3b5170a22",
"sha256": "358edc493a2599e703fb536757d6e0313f17fa79a0da2d4dea7f0f3344ef6e0c"
},
"downloads": -1,
"filename": "udev_monitor-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83cdd15f0b63a205bf8be9a3b5170a22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7862,
"upload_time": "2023-03-30T19:21:17",
"upload_time_iso_8601": "2023-03-30T19:21:17.428537Z",
"url": "https://files.pythonhosted.org/packages/d1/81/6bb57a4b90468306d965d82da46441fde83b84a0bed36667cb23c009d3da/udev_monitor-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2932ea0f9f4bbdba4343d41fc6575aac7de34c86db80147a766aa909f8e81cb7",
"md5": "0b9f54dcb6250b75ec336b987c693d84",
"sha256": "6d16d78f8781b15fe38764b7f6af1f4b16d368ce4a8b99b4b748399203182696"
},
"downloads": -1,
"filename": "udev_monitor-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0b9f54dcb6250b75ec336b987c693d84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8225,
"upload_time": "2023-03-30T19:21:18",
"upload_time_iso_8601": "2023-03-30T19:21:18.616719Z",
"url": "https://files.pythonhosted.org/packages/29/32/ea0f9f4bbdba4343d41fc6575aac7de34c86db80147a766aa909f8e81cb7/udev_monitor-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-30 19:21:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "netinvent",
"github_project": "udev_monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "udev-monitor"
}
JSON
