Documentation/admin-guide/device-mapper/dm-uevent.rst

   1 ====================
   2 device-mapper uevent
   3 ====================
   4
   5 The device-mapper uevent code adds the capability to device-mapper to create
   6 and send kobject uevents (uevents).  Previously device-mapper events were only
   7 available through the ioctl interface.  The advantage of the uevents interface
   8 is the event contains environment attributes providing increased context for
   9 the event avoiding the need to query the state of the device-mapper device after
  10 the event is received.
  11
  12 There are two functions currently for device-mapper events.  The first function
  13 listed creates the event and the second function sends the event(s)::
  14
  15   void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
  16                       const char *path, unsigned nr_valid_paths)
  17
  18   void dm_send_uevents(struct list_head *events, struct kobject *kobj)
  19
  20
  21 The variables added to the uevent environment are:
  22
  23 Variable Name: DM_TARGET
  24 ------------------------
  25 :Uevent Action(s): KOBJ_CHANGE
  26 :Type: string
  27 :Description:
  28 :Value: Name of device-mapper target that generated the event.
  29
  30 Variable Name: DM_ACTION
  31 ------------------------
  32 :Uevent Action(s): KOBJ_CHANGE
  33 :Type: string
  34 :Description:
  35 :Value: Device-mapper specific action that caused the uevent action.
  36         PATH_FAILED - A path has failed;
  37         PATH_REINSTATED - A path has been reinstated.
  38
  39 Variable Name: DM_SEQNUM
  40 ------------------------
  41 :Uevent Action(s): KOBJ_CHANGE
  42 :Type: unsigned integer
  43 :Description: A sequence number for this specific device-mapper device.
  44 :Value: Valid unsigned integer range.
  45
  46 Variable Name: DM_PATH
  47 ----------------------
  48 :Uevent Action(s): KOBJ_CHANGE
  49 :Type: string
  50 :Description: Major and minor number of the path device pertaining to this
  51               event.
  52 :Value: Path name in the form of "Major:Minor"
  53
  54 Variable Name: DM_NR_VALID_PATHS
  55 --------------------------------
  56 :Uevent Action(s): KOBJ_CHANGE
  57 :Type: unsigned integer
  58 :Description:
  59 :Value: Valid unsigned integer range.
  60
  61 Variable Name: DM_NAME
  62 ----------------------
  63 :Uevent Action(s): KOBJ_CHANGE
  64 :Type: string
  65 :Description: Name of the device-mapper device.
  66 :Value: Name
  67
  68 Variable Name: DM_UUID
  69 ----------------------
  70 :Uevent Action(s): KOBJ_CHANGE
  71 :Type: string
  72 :Description: UUID of the device-mapper device.
  73 :Value: UUID. (Empty string if there isn't one.)
  74
  75 An example of the uevents generated as captured by udevmonitor is shown
  76 below
  77
  78 1.) Path failure::
  79
  80         UEVENT[1192521009.711215] change@/block/dm-3
  81         ACTION=change
  82         DEVPATH=/block/dm-3
  83         SUBSYSTEM=block
  84         DM_TARGET=multipath
  85         DM_ACTION=PATH_FAILED
  86         DM_SEQNUM=1
  87         DM_PATH=8:32
  88         DM_NR_VALID_PATHS=0
  89         DM_NAME=mpath2
  90         DM_UUID=mpath-35333333000002328
  91         MINOR=3
  92         MAJOR=253
  93         SEQNUM=1130
  94
  95 2.) Path reinstate::
  96
  97         UEVENT[1192521132.989927] change@/block/dm-3
  98         ACTION=change
  99         DEVPATH=/block/dm-3
 100         SUBSYSTEM=block
 101         DM_TARGET=multipath
 102         DM_ACTION=PATH_REINSTATED
 103         DM_SEQNUM=2
 104         DM_PATH=8:32
 105         DM_NR_VALID_PATHS=1
 106         DM_NAME=mpath2
 107         DM_UUID=mpath-35333333000002328
 108         MINOR=3
 109         MAJOR=253
 110         SEQNUM=1131