github.com/kubiko/snapd@v0.0.0-20201013125620-d4f3094d9ddf/osutil/udev/README.md (about)

     1  # go-udev [![Go Report Card](https://goreportcard.com/badge/github.com/pilebones/go-udev)](https://goreportcard.com/report/github.com/pilebones/go-udev) [![GoDoc](https://godoc.org/github.com/pilebones/go-udev?status.svg)](https://godoc.org/github.com/pilebones/go-udev) [![Build Status](https://travis-ci.org/pilebones/go-udev.svg?branch=master)](https://travis-ci.org/pilebones/go-udev)
     2  
     3  Simple udev implementation in Golang developed from scratch.
     4  This library allow to listen and manage Linux-kernel (since version 2.6.10) Netlink messages to user space (ie: NETLINK_KOBJECT_UEVENT).
     5  
     6  Like [`udev`](https://en.wikipedia.org/wiki/Udev) you will be able to monitor, display and manage devices plug to the system.
     7  
     8  ## How to
     9  
    10  ### Get sources
    11  
    12  ```
    13  go get github.com/pilebones/go-udev
    14  ```
    15  
    16  ### Unit test
    17  
    18  ```
    19  go test ./...
    20  ```
    21  
    22  ### Compile
    23  
    24  ```
    25  go build
    26  ```
    27  
    28  ### Usage
    29  
    30  ```
    31  ./go-udev -<mode> [-file=<absolute_path>]
    32  ```
    33  
    34  Allowed mode: `info` or `monitor`
    35  File should contains matcher rules (see: "Advanced usage" section)
    36  
    37  ### Info Mode
    38  
    39  Crawl /sys/devices uevent struct to detect plugged devices:
    40  
    41  ```
    42  ./go-udev -info
    43  ```
    44  
    45  ### Monitor Mode
    46  
    47  Handle all kernel message to detect change about plugged or unplugged devices:
    48  
    49  ```
    50  ./go-udev -monitor
    51  ```
    52  
    53  #### Examples
    54  
    55  Example of output when a USB storage is plugged:
    56  ```
    57  2017/10/20 23:47:23 Handle netlink.UEvent{
    58      Action: "add",
    59      KObj:   "/devices/pci0000:00/0000:00:14.0/usb1/1-1",
    60      Env:    {"PRODUCT":"58f/6387/10b", "TYPE":"0/0/0", "BUSNUM":"001", "DEVNUM":"005", "SEQNUM":"2511", "DEVNAME":"bus/usb/001/005", "DEVPATH":"/devices/pci0000:00/0000:00:14.0/usb1/1-1", "SUBSYSTEM":"usb", "MAJOR":"189", "MINOR":"4", "DEVTYPE":"usb_device", "ACTION":"add"},
    61  }
    62  2017/10/20 23:47:23 Handle netlink.UEvent{
    63      Action: "add",
    64      KObj:   "/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0",
    65      Env:    {"SUBSYSTEM":"usb", "TYPE":"0/0/0", "INTERFACE":"8/6/80", "MODALIAS":"usb:v058Fp6387d010Bdc00dsc00dp00ic08isc06ip50in00", "SEQNUM":"2512", "DEVPATH":"/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0", "DEVTYPE":"usb_interface", "PRODUCT":"58f/6387/10b", "ACTION":"add"},
    66  }
    67  2017/10/20 23:47:23 Handle netlink.UEvent{
    68      Action: "add",
    69      KObj:   "/module/usb_storage",
    70      Env:    {"SEQNUM":"2513", "ACTION":"add", "DEVPATH":"/module/usb_storage", "SUBSYSTEM":"module"},
    71  }
    72  [...]
    73  ```
    74  
    75  Example of output when a USB storage is unplugged:
    76  ```
    77  [...]
    78  2017/10/20 23:47:29 Handle netlink.UEvent{
    79      Action: "remove",
    80      KObj:   "/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0/host4/target4:0:0/4:0:0:0/block/sdb",
    81      Env:    {"SUBSYSTEM":"block", "MAJOR":"8", "MINOR":"16", "DEVNAME":"sdb", "DEVTYPE":"disk", "SEQNUM":"2543", "ACTION":"remove", "DEVPATH":"/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0/host4/target4:0:0/4:0:0:0/block/sdb"},
    82  }
    83  [...]
    84  2017/10/20 23:47:29 Handle netlink.UEvent{
    85      Action: "remove",
    86      KObj:   "/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0",
    87      Env:    {"ACTION":"remove", "SUBSYSTEM":"usb", "DEVTYPE":"usb_interface", "SEQNUM":"2548", "MODALIAS":"usb:v058Fp6387d010Bdc00dsc00dp00ic08isc06ip50in00", "DEVPATH":"/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0", "PRODUCT":"58f/6387/10b", "TYPE":"0/0/0", "INTERFACE":"8/6/80"},
    88  }
    89  2017/10/20 23:47:29 Handle netlink.UEvent{
    90      Action: "remove",
    91      KObj:   "/devices/pci0000:00/0000:00:14.0/usb1/1-1",
    92      Env:    {"PRODUCT":"58f/6387/10b", "TYPE":"0/0/0", "DEVNUM":"005", "SEQNUM":"2549", "ACTION":"remove", "DEVPATH":"/devices/pci0000:00/0000:00:14.0/usb1/1-1", "SUBSYSTEM":"usb", "MAJOR":"189", "MINOR":"4", "DEVNAME":"bus/usb/001/005", "DEVTYPE":"usb_device", "BUSNUM":"001"},
    93  }
    94  ```
    95  
    96  Note: To implement your own monitoring system, please see `main.go` as a simple example.
    97  
    98  ### Advanced usage
    99  
   100  Is it possible to filter uevents/devices with a Matcher.
   101  
   102  A Matcher is a list of your own rules to match only relevant uevent kernel message (see: `matcher.sample`).
   103  
   104  You could pass this file using for both mode:
   105  ```
   106  ./go-udev -file  matcher.sample [...]
   107  
   108  ```
   109  
   110  ## Throubleshooting
   111  
   112  Don't hesitate to notice if you detect a problem with this tool or library.
   113  
   114  ## Links
   115  
   116  - Netlink Manual: http://man7.org/linux/man-pages/man7/netlink.7.html
   117  - Linux source code about: 
   118    * Struct sockaddr_netlink: http://elixir.free-electrons.com/linux/v3.12/source/lib/kobject_uevent.c#L45
   119    * KObject action: http://elixir.free-electrons.com/linux/v3.12/source/lib/kobject_uevent.c#L45
   120  
   121  ## Documentation
   122  - [GoDoc Reference](http://godoc.org/github.com/pilebones/go-udev).
   123  
   124  ## License
   125  
   126  go-udev is available under the [GNU GPL v3 - Clause License](https://opensource.org/licenses/GPL-3.0).