1UDEV(7) udev UDEV(7)
2
6 udev - Linux dynamic device management
7
9 udev supplies the system software with device events, manages
10 permissions of device nodes and may create additional symlinks in the
11 /dev directory, or renames network interfaces. The kernel usually just
12 assigns unpredictable device names based on the order of discovery.
13 Meaningful symlinks or network device names provide a way to reliably
14 identify devices based on their properties or current configuration.
15 The udev daemon udevd(8) receives device uevents directly from the
17 kernel whenever a device is added or removed from the system, or it
18 changes its state. When udev receives a device event, it matches its
19 configured set of rules against various device attributes to identify
20 the device. Rules that match, may provide additional device information
21 to be stored in the udev database, or information to be used to create
22 meaningful symlink names.
23 All device information udev processes, is stored in the udev database
25 and sent out to possible event subscribers. Access to all stored data
26 and the event sources are provided by the library libudev.
27
29 udev configuration files are placed in /etc/udev/ and /lib/udev/. All
30 empty lines, or lines beginning with '#' will be ignored.
31 Configuration file
33 udev expects its main configuration file at /etc/udev/udev.conf. It
34 consists of a set of variables allowing the user to override default
35 udev values. The following variables can be set:
36 udev_root
38 Specifies where to place the device nodes in the filesystem. The
39 default value is /dev.
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 default rules
47 directory /lib/udev/rules.d/, the custom rules directory
48 /etc/udev/rules.d/ and the temporary rules directory
49 /dev/.udev/rules.d/. All rule files are sorted and processed in lexical
50 order, regardless in which of these directories they live. Files in
51 /etc/udev/rules.d/ have precedence over files with the same name in
52 /lib/udev/rules.d/. This can be used to ignore a default rules file if
53 needed.
54 Rule files must end in .rules, other extensions are ignored.
56 Every line in the rules file contains at least one key value pair.
58 There are two kind of keys, match and assignment keys. If all match
59 keys are matching against its value, the rule gets applied and the
60 assign keys get the specified value assigned.
61 A matching rule may rename a network interface, add symlinks pointing
63 to the device node, or run a specified program as part of the event
64 handling.
65 A rule consists of a list of one or more key value pairs separated by a
67 comma. Each key has a distinct operation, depending on the used
68 operator. Valid operators are:
69 ==
71 Compare for equality.
72 !=
74 Compare for inequality.
75 =
77 Assign a value to a key. Keys that represent a list, are reset and
78 only this single value is assigned.
79 +=
81 Add the value to a key that holds a list of entries.
82 :=
84 Assign a value to a key finally; disallow any later changes, which
85 may be used to prevent changes by any later rules.
86 The following key names can be used to match against device properties.
88 Some of the keys also match against properties of the parent devices in
89 sysfs, not only the device that has generated the event. If multiple
90 keys that match a parent device are specified in a single rule, all
91 these keys must match at one and the same parent device.
92 ACTION
94 Match the name of the event action.
95 DEVPATH
97 Match the devpath of the event device.
98 KERNEL
100 Match the name of the event device.
101 NAME
103 Match the name of the node or network interface. It can be used
104 once the NAME key has been set in one of the preceding rules.
105 SYMLINK
107 Match the name of a symlink targeting the node. It can be used once
108 a SYMLINK key has been set in one of the preceding rules. There may
109 be multiple symlinks; only one needs to match.
110 SUBSYSTEM
112 Match the subsystem of the event device.
113 DRIVER
115 Match the driver name of the event device. Only set for devices
116 which are bound to a driver at the time the event is generated.
117 ATTR{filename}
119 Match sysfs attribute values of the event device. Trailing
120 whitespace in the attribute values is ignored, if the specified
121 match value does not contain trailing whitespace itself.
122 KERNELS
124 Search the devpath upwards for a matching device name.
125 SUBSYSTEMS
127 Search the devpath upwards for a matching device subsystem name.
128 DRIVERS
130 Search the devpath upwards for a matching device driver name.
131 ATTRS{filename}
133 Search the devpath upwards for a device with matching sysfs
134 attribute values. If multiple ATTRS matches are specified, all of
135 them must match on the same device. Trailing whitespace in the
136 attribute values is ignored, if the specified match value does not
137 contain trailing whitespace itself.
138 ENV{key}
140 Match against a device property value.
141 TAG
143 Match against a device tag.
144 TEST{octal mode mask}
146 Test the existence of a file. An octal mode mask can be specified
147 if needed.
148 PROGRAM
150 Execute a program. The key is true, if the program returns
151 successfully. The device properties are made available to the
152 executed program in the environment. The program's output printed
153 to stdout, is available in the RESULT key.
154 RESULT
156 Match the returned string of the last PROGRAM call. This key can be
157 used in the same or in any later rule after a PROGRAM call.
158 Most of the fields support a shell style pattern matching. The
160 following pattern characters are supported:
161 *
163 Matches zero, or any number of characters.
164 ?
166 Matches any single character.
167 []
169 Matches any single character specified within the brackets. For
170 example, the pattern string 'tty[SR]' would match either 'ttyS' or
171 'ttyR'. Ranges are also supported within this match with the '-'
172 character. For example, to match on the range of all digits, the
173 pattern [0-9] would be used. If the first character following the
174 '[' is a '!', any characters not enclosed are matched.
175 The following keys can get values assigned:
177 NAME
179 The name, a network interface should be renamed to. Or as a
180 temporary workaraound, the name a device node should be named.
181 Usually the kernel provides the defined node name, or even creates
182 and removes the node before udev even receives any event. Changing
183 the node name from the kernel's default creates inconsistencies and
184 is not supported. If the kernel and NAME specify different names,
185 an error will be logged. Udev is only expected to handle device
186 node permissions and to create additional symlinks, not to change
187 kernel-provided device node names. Instead of renaming a device
188 node, SYMLINK should be used. Symlink names must never conflict
189 with device node names, it will result in unpredictable behavior.
190 SYMLINK
192 The name of a symlink targeting the node. Every matching rule will
193 add this value to the list of symlinks to be created. Multiple
194 symlinks may be specified by separating the names by the space
195 character. In case multiple devices claim the same name, the link
196 will always point to the device with the highest link_priority. If
197 the current device goes away, the links will be re-evaluated and
198 the device with the next highest link_priority will own the link.
199 If no link_priority is specified, the order of the devices, and
200 which one of them will own the link, is undefined. Claiming the
201 same name for a symlink, which is or might be used for a device
202 node, may result in unexpected behavior and is not supported.
203 OWNER, GROUP, MODE
205 The permissions for the device node. Every specified value
206 overwrites the compiled-in default value.
207 ATTR{key}
209 The value that should be written to a sysfs attribute of the event
210 device.
211 ENV{key}
213 Set a device property value. Property names with a leading '.' are
214 not stored in the database or exported to external tool or events.
215 TAG
217 Attach a tag to a device. This is used to filter events for users
218 of libudev's monitor functionality, or to enumerate a group of
219 tagged devices. The implementation can only work efficiently if
220 only a few tags are attached to a device. It is only meant to be
221 used in contexts with specific device filter requirements, and not
222 as a general-purpose flag. Excessive use might result in
223 inefficient event handling.
224 RUN
226 Add a program to the list of programs to be executed for a specific
227 device. This can only be used for very short running tasks. Running
228 an event process for a long period of time may block all further
229 events for this or a dependent device. Long running tasks need to
230 be immediately detached from the event process itself. If the
231 option RUN{fail_event_on_error} is specified, and the executed
232 program returns non-zero, the event will be marked as failed for a
233 possible later handling.
234 If no absolute path is given, the program is expected to live in
236 /lib/udev, otherwise the absolute path must be specified. Program
237 name and arguments are separated by spaces. Single quotes can be
238 used to specify arguments with spaces.
239 LABEL
241 Named label where a GOTO can jump to.
242 GOTO
244 Jumps to the next LABEL with a matching name
245 IMPORT{type}
247 Import a set of variables as device properties, depending on type:
248 program
250 Execute an external program specified as the assigned value and
251 import its output, which must be in environment key format.
252 Path specification, command/argument separation, and quoting
253 work like in RUN.
254 file
256 Import a text file specified as the assigned value, which must
257 be in environment key format.
258 db
260 Import a single property specified as the assigned value from
261 the current device database. This works only if the database is
262 already populated by an earlier event.
263 cmdline
265 Import a single property from the kernel commandline. For
266 simple flags the value of the property will be set to '1'.
267 parent
269 Import the stored keys from the parent device by reading the
270 database entry of the parent device. The value assigned to
271 IMPORT{parent} is used as a filter of key names to import (with
272 the same shell-style pattern matching used for comparisons).
273 If no option is given, udev will choose between program and file
275 based on the executable bit of the file permissions.
276 WAIT_FOR
278 Wait for a file to become available or until a 10 seconds timeout
279 expires.
280 OPTIONS
282 Rule and device options:
283 link_priority=value
285 Specify the priority of the created symlinks. Devices with
286 higher priorities overwrite existing symlinks of other devices.
287 The default is 0.
288 event_timeout=
290 Number of seconds an event will wait for operations to finish,
291 before it will terminate itself.
292 string_escape=none|replace
294 Usually control and other possibly unsafe characters are
295 replaced in strings used for device naming. The mode of
296 replacement can be specified with this option.
297 static_node=
299 Apply the permissions specified in this rule to a static device
300 node with the specified name. Static device nodes might be
301 provided by kernel modules, or copied from /lib/udev/devices.
302 These nodes might not have a corresponding kernel device at the
303 time udevd is started, and allow to trigger automatic kernel
304 module on-demand loading.
305 watch
307 Watch the device node with inotify, when closed after being
308 opened for writing, a change uevent will be synthesised.
309 nowatch
311 Disable the watching of a device node with inotify.
312 The NAME, SYMLINK, PROGRAM, OWNER, GROUP, MODE and RUN fields support
314 simple printf-like string substitutions. The RUN format chars gets
315 applied after all rules have been processed, right before the program
316 is executed. It allows the use of device properties set by earlier
317 matching rules. For all other fields, substitutions are applied while
318 the individual rule is being processed. The available substitutions
319 are:
320 $kernel, %k
322 The kernel name for this device.
323 $number, %n
325 The kernel number for this device. For example, 'sda3' has kernel
326 number of '3'
327 $devpath, %p
329 The devpath of the device.
330 $id, %b
332 The name of the device matched while searching the devpath upwards
333 for SUBSYSTEMS, KERNELS, DRIVERS and ATTRS.
334 $driver
336 The driver name of the device matched while searching the devpath
337 upwards for SUBSYSTEMS, KERNELS, DRIVERS and ATTRS.
338 $attr{file}, %s{file}
340 The value of a sysfs attribute found at the device, where all keys
341 of the rule have matched. If the matching device does not have such
342 an attribute, and a previous KERNELS, SUBSYSTEMS, DRIVERS, or ATTRS
343 test selected a parent device, use the attribute from that parent
344 device. If the attribute is a symlink, the last element of the
345 symlink target is returned as the value.
346 $env{key}, %E{key}
348 A device property value.
349 $major, %M
351 The kernel major number for the device.
352 $minor, %m
354 The kernel minor number for the device.
355 $result, %c
357 The string returned by the external program requested with PROGRAM.
358 A single part of the string, separated by a space character may be
359 selected by specifying the part number as an attribute: %c{N}. If
360 the number is followed by the '+' char this part plus all remaining
361 parts of the result string are substituted: %c{N+}
362 $parent, %P
364 The node name of the parent device.
365 $name
367 The current name of the device node. If not changed by a rule, it
368 is the name of the kernel device.
369 $links
371 The current list of symlinks, separated by a space character. The
372 value is only set if an earlier rule assigned a value, or during a
373 remove events.
374 $root, %r
376 The udev_root value.
377 $sys, %S
379 The sysfs mount point.
380 $tempnode, %N
382 The name of a created temporary device node to provide access to
383 the device from a external program before the real node is created.
384 %%
386 The '%' character itself.
387 $$
389 The '$' character itself.
390
392 Written by Greg Kroah-Hartman greg@kroah.com and Kay Sievers
393 kay.sievers@vrfy.org. With much help from Dan Stekloff and many others.
394
396 udevd(8), udevadm(8)
397udev 08/29/2011 UDEV(7)