GNU Linux-libre 6.6.34-gnu
[releases.git] / 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