1UDEV(7) udev UDEV(7)
2
6 udev - dynamic device management
7
9 udev provides a dynamic device directory containing only the files for
10 actually present devices. It creates or removes device node files in
11 the /dev directory, or it renames network interfaces.
12 Usually udev runs as udevd(8) and receives uevents directly from the
14 kernel if a device is added or removed from the system.
15 If udev receives a device event, it matches its configured rules
17 against the available device attributes provided in sysfs to identify
18 the device. Rules that match may provide additional device information
19 or specify a device node name and multiple symlink names and instruct
20 udev to run additional programs as part of the device event handling.
21
23 All udev configuration files are placed in /etc/udev/*. Every file
24 consists of a set of lines of text. All empty lines or lines beginning
25 with ´#´ will be ignored.
26 Configuration file
28 udev expects its main configuration file at /etc/udev/udev.conf. It
29 consists of a set of variables allowing the user to override default
30 udev values. The following variables can be set:
31 udev_root
33 Specifies where to place the device nodes in the filesystem. The
34 default value is /dev.
35 udev_rules
37 The name of the udev rules file or directory to look for files with
38 the suffix .rules. Multiple rule files are read in lexical order.
39 The default value is /etc/udev/rules.d.
40 udev_log
42 The logging priority. Valid values are the numerical syslog
43 priorities or their textual representations: err, info and debug.
44 Rules files
46 The udev rules are read from the files located in the /etc/udev/rules.d
47 directory or at the location specified value in the configuration file.
48 Every line in the rules file contains at least one key value pair.
49 There are two kind of keys, match and assignment keys. If all match
50 keys are matching against its value, the rule gets applied and the
51 assign keys get the specified value assigned.
52 A matching rule may specify the name of the device node, add a symlink
54 pointing to the node, or run a specified program as part of the event
55 handling. If no matching rule is found, the default device node name is
56 used.
57 A rule may consist of a list of one or more key value pairs separated
59 by a comma. Each key has a distinct operation, depending on the used
60 operator. Valid operators are:
61 ==
63 Compare for equality.
64 !=
66 Compare for non-equality.
67 =
69 Assign a value to a key. Keys that represent a list, are reset and
70 only this single value is assigned.
71 +=
73 Add the value to a key that holds a list of entries.
74 :=
76 Assign a value to a key finally; disallow any later changes, which
77 may be used to prevent changes by any later rules.
78 The following key names can be used to match against device properties.
80 Some of the keys also match against properties of the parent devices in
81 sysfs, not only the device that has generated the event. If multiple
82 keys that match a parent device are specified in a single rule, all
83 these keys must match at one and the same parent device.
84 ACTION
86 Match the name of the event action.
87 DEVPATH
89 Match the devpath of the event device.
90 KERNEL
92 Match the name of the event device.
93 SUBSYSTEM
95 Match the subsystem of the event device.
96 DRIVER
98 Match the driver name of the event device. Only set for devices
99 which are bound to a driver at the time the event is generated.
100 ATTR{filename}
102 Match sysfs attribute values of the event device. Up to five ATTR
103 keys can be specified per rule. Trailing whitespace in the
104 attribute values is ignored, if the specified match value does not
105 contain trailing whitespace itself. Depending on the type of
106 operator, this key is also used to set the value of a sysfs
107 attribute.
108 KERNELS
110 Search the devpath upwards for a matching device name.
111 SUBSYSTEMS
113 Search the devpath upwards for a matching device subsystem name.
114 DRIVERS
116 Search the devpath upwards for a matching device driver name.
117 ATTRS{filename}
119 Search the devpath upwards for a device with matching sysfs
120 attribute values. Up to five ATTRS keys can be specified per rule,
121 but all of them must match on the same device. Trailing whitespace
122 in the attribute values is ignored, if the specified match value
123 does not contain trailing whitespace itself.
124 ENV{key}
126 Match against the value of an environment variable. Up to five ENV
127 keys can be specified per rule. Depending on the type of operator,
128 this key is also used to export a variable to the environment.
129 TEST{octal mode mask}
131 Test the existence of a file. An octal mode mask can be specified
132 if needed.
133 PROGRAM
135 Execute external program. The key is true, if the program returns
136 with exit code zero. The whole event environment is available to
137 the executed program. The program´s output printed to stdout, is
138 available in the RESULT key.
139 RESULT
141 Match the returned string of the last PROGRAM call. This key can be
142 used in the same or in any later rule after a PROGRAM call.
143 Most of the fields support a shell style pattern matching. The
145 following pattern characters are supported:
146 *
148 Matches zero, or any number of characters.
149 ?
151 Matches any single character.
152 []
154 Matches any single character specified within the brackets. For
155 example, the pattern string ´tty[SR]´ would match either ´ttyS´ or
156 ´ttyR´. Ranges are also supported within this match with the ´-´
157 character. For example, to match on the range of all digits, the
158 pattern [0-9] would be used. If the first character following the
159 ´[´ is a ´!´, any characters not enclosed are matched.
160 The following keys can get values assigned:
162 NAME
164 The name of the node to be created, or the name the network
165 interface should be renamed to. Only one rule can set the node
166 name, all later rules with a NAME key will be ignored.
167 SYMLINK
169 The name of a symlink targeting the node. Every matching rule can
170 add this value to the list of symlinks to be created along with the
171 device node. Multiple symlinks may be specified by separating the
172 names by the space character.
173 OWNER, GROUP, MODE
175 The permissions for the device node. Every specified value
176 overwrites the compiled-in default value.
177 ATTR{key}
179 The value that should be written to a sysfs attribute of the event
180 device. Depending on the type of operator, this key is also used to
181 match against the value of a sysfs attribute.
182 ENV{key}
184 Export a variable to the environment. Depending on the type of
185 operator, this key is also to match against an environment
186 variable.
187 RUN
189 Add a program to the list of programs to be executed for a specific
190 device. This can only be used for very short running tasks. Running
191 an event process for a long period of time may block all further
192 events for this or a dependent device. Long running tasks need to
193 be immediately detached from the event process itself.
194 LABEL
196 Named label where a GOTO can jump to.
197 GOTO
199 Jumps to the next LABEL with a matching name
200 IMPORT{type}
202 Import a set of variables into the event environment, depending on
203 type:
204 program
206 Execute an external program specified as the assigned value and
207 import its output, which must be in environment key format.
208 file
210 Import a text file specified as the assigned value, which must
211 be in environment key format.
212 parent
214 Import the stored keys from the parent device by reading the
215 database entry of the parent device. The value assigned to
216 IMPORT{parent} is used as a filter of key names to import (with
217 the same shell-style pattern matching used for comparisons).
218 If no option is given, udev will choose between program and file
220 based on the executable bit of the file permissions.
221 WAIT_FOR_SYSFS
223 Wait for the specified sysfs file of the device to be created. Can
224 be used to fight against kernel sysfs timing issues.
225 OPTIONS
227 Rule and device options:
228 last_rule
230 Stops further rules application. No later rules will have any
231 effect.
232 ignore_device
234 Ignore this event completely.
235 ignore_remove
237 Do not remove the device node when the device goes away. This
238 may be useful as a workaround for broken device drivers.
239 link_priority=value
241 Specify the priority of the created symlinks. Devices with
242 higher priorities overwrite existing symlinks of other devices.
243 all_partitions
245 Create the device nodes for all available partitions of a block
246 device. This may be useful for removable media devices where
247 media changes are not detected.
248 string_escape=none|replace
250 Usually control and other possibly unsafe characters are
251 replaced in strings used for device naming. The mode of
252 replacement can be specified with this option.
253 The NAME, SYMLINK, PROGRAM, OWNER, GROUP and RUN fields support simple
255 printf-like string substitutions. The RUN format chars gets applied
256 after all rules have been processed, right before the program is
257 executed. It allows the use of the complete environment set by earlier
258 matching rules. For all other fields, substitutions are applied while
259 the individual rule is being processed. The available substitutions
260 are:
261 $kernel, %k
263 The kernel name for this device.
264 $number, %n
266 The kernel number for this device. For example, ´sda3´ has kernel
267 number of ´3´
268 $devpath, %p
270 The devpath of the device.
271 $id, %b
273 The name of the device matched while searching the devpath upwards
274 for SUBSYSTEMS, KERNELS, DRIVERS and ATTRS.
275 $driver
277 The driver name of the device matched while searching the devpath
278 upwards for SUBSYSTEMS, KERNELS, DRIVERS and ATTRS.
279 $attr{file}, %s{file}
281 The value of a sysfs attribute found at the device, where all keys
282 of the rule have matched. If the matching device does not have such
283 an attribute, all devices along the chain of parents are searched
284 for a matching attribute. If the attribute is a symlink, the last
285 element of the symlink target is returned as the value.
286 $env{key}, %E{key}
288 The value of an environment variable.
289 $major, %M
291 The kernel major number for the device.
292 $minor, %m
294 The kernel minor number for the device.
295 $result, %c
297 The string returned by the external program requested with PROGRAM.
298 A single part of the string, separated by a space character may be
299 selected by specifying the part number as an attribute: %c{N}. If
300 the number is followed by the ´+´ char this part plus all remaining
301 parts of the result string are substituted: %c{N+}
302 $parent, %P
304 The node name of the parent device.
305 $name
307 The name of the device node. The value is only set if an earlier
308 rule assigned a value, or during a remove events.
309 $root, %r
311 The udev_root value.
312 $sys, %S
314 The sysfs mount point.
315 $tempnode, %N
317 The name of a created temporary device node to provide access to
318 the device from a external program before the real node is created.
319 %%
321 The ´%´ character itself.
322 $$
324 The ´$´ character itself.
325 The count of characters to be substituted may be limited by specifying
327 the format length value. For example, ´%3s{file}´ will only insert the
328 first three characters of the sysfs attribute
329
331 Written by Greg Kroah-Hartman <greg@kroah.com> and Kay Sievers
332 <kay.sievers@vrfy.org>. With much help from Dan Stekloff
333 <dsteklof@us.ibm.com> and many others.
334
336 udevd(8), udevinfo(8), udevmonitor(8)
337udev August 2005 UDEV(7)