1 .TH UDEV 8 "October 2003" "" "Linux Administrator's Manual"
3 udev \- Linux configurable dynamic device naming support
8 provides a dynamic device directory containing only the files for actually
9 present devices. It creates or removes device node files usually located in
10 the /dev directory, or it renames network interfaces.
17 is executed if a kernel device is added or removed from the system.
18 A list of rules is used to match against specific device attributes.
22 matches its configured rules against the available device attributes to
23 uniquely name the device.
25 maintains its own database for devices present on the system. This database
26 can be queried for the relationship of the kernel device path and the
27 name of the device file.
31 queries its database for the name of the device file to be deleted.
33 After the device node handling, a list of collected programs specific to this
38 configuration files consist of a set of lines of text. All empty
39 lines or lines beginning with '#' will be ignored.
42 expects its main configuration file at
43 .IR /etc/udev/udev.conf .
44 The file consists of a set of variables and values allowing the user to
45 override default udev values. The following variables can be overridden
49 Indicates where to place the device nodes in the filesystem. The default
54 The name and location of the udev database. The default value is
55 .IR @udevdir@/.udevdb .
58 The name of the udev rules file or directory to look for files with the suffix
60 All rule files are read in lexical order. The default value is
61 .IR /etc/udev/rules.d/ .
64 The logging priority which can be set to
66 or the corresponding numerical
72 .RI "A sample " udev.conf " file might look like this:
75 # Where in the filesystem to place the device nodes
78 # The name and location of the udev database.
79 udev_db="@udevdir@/.udevdb"
81 # The name and location of the udev rules file(s).
82 udev_rules="@configdir@/rules.d"
84 # The syslog(3) priority: "err", "info", or the numerical value.
88 The rules for device naming are read from the files located in the
90 directory, or at the location specified by the
93 .I /etc/udev/udev.conf
96 Every line in the rules file defines the mapping between device attributes
97 and the device name. One or more keys are specified to match a rule with
98 the current device. If all keys are matching, the rule will be applied and
99 the name is used to name the device file or the network interface.
101 If no matching rule is found, the default kernel device name is used.
103 Every rule consists of a list of comma separated key value fields:
105 .IR "key " ,[ "key " ,...]
107 Each key has the following format:
111 There are distinct key operation types, depending on the type of the key, it
112 does a comparison or an assignment.
114 Comparison operators are:
117 Compare for equality.
120 Compare for non-equality.
122 Assignment operators are:
125 Add the value to a key that holds a list of entries.
128 Assign a value to a key finally; disallow any later changes, which
129 is useful to prevent changes by any later rules.
132 Asign a value to a key. Keys that represent a list, are reset and only this
133 single value is assigned. While this operator still works inplicitely as
134 comparison on keys that can't get a value assigned, its usage as an comparison
135 operator is deprecated.
137 The following key names can be used to match against device properties:
140 Match the bus type of the device.
141 (The sysfs device bus must be able to be determined by a "device" symlink.)
144 Match the kernel device name.
147 Match the kernel subsystem name.
150 Match the kernel action name.
153 Match the kernel driver name.
156 Match the device number on the bus, like PCI bus id.
158 .BI SYSFS{ filename }
159 Match sysfs device attribute like vendor and product id's, USB serial number
160 or the SCSI disk model number. Up to 5 different sysfs files can be checked,
161 with all of the values being required to match the rule.
163 Trailing whitespace characters in the sysfs attribute value are ignored, if
164 the key doesn't have any trailing whitespace characters by itself.
167 Match an environment variable. Up to 5 different environment variables can be
168 checked, with all of the values being required to match the rule.
171 Call external program. This key is valid if the program returns successful.
172 The environment variables of
174 are also available to the program.
176 The string returned by the program may be additionally matched with the
178 key in the same or any later rule.
181 Match the returned string of the last
183 call. This key can be used in the same or in any later rule after a
187 The following keys can get values assigned:
190 The name of the node to be created, or the name, the network interface
191 should be renamed to. Only one rule can set the a name, all later rules
192 with a NAME key will be ignored.
195 The name of a symlink targeting the node. Every matching rule can add
196 this value to the list of symlinks to be created along with the device node.
197 Multiple symlinks may be specified by separating the names by the space
200 .B OWNER, GROUP, MODE
201 The permissions for the device node. Every specified value overwrites the
202 compiled-in default value.
205 Add a program to the list of programs to be executed for a specific device.
209 stops further rules application. No later rules will have any effect.
212 will ignore this device. No node will be created or program executed.
215 will ignore any later remove event for this device.
216 This may be useful as a workaround for broken device drivers.
219 will create device nodes for all available partitions of a blockdevice.
220 This may be useful for removable media devices which do not detect a media
223 Multiple attributes may be separated by comma.
225 .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP
226 fields support simple printf-like string substitutions:
229 The "kernel number" of the device.
230 For example, 'sda3' has a "kernel number" of '3'.
233 The "kernel name" for the device.
236 The devpath for the device.
239 The kernel major number for the device.
242 The kernel minor number for the device.
245 The bus id for the device.
248 The string returned by the external program, specified in
250 (This does not work within the
252 field for the obvious reason.)
254 A single part of the string, separated by a space character
255 may be selected by specifying the part number as an attribute:
257 If the number is followed by the + char this part plus
258 all remaining parts of the result string are substituted:
262 The name of a created temporary device node to provide access to the
263 device from a external program.
266 The node name of the parent device.
269 The content of a sysfs attribute.
275 If a device node already exists with the name, the smallest positive
276 decimal integer N is substituted such that the resulting name doesn't
277 match an existing device node. Otherwise nothing is substituted. This
278 can be used to create compatibility symlinks and enumerate devices of
279 the same type originating from different kernel subsystems.
281 Note: The use of the enumeration facility is unreliable outside of
282 udevstart where the node creation is serialized and predictable.
283 The returned numbers rely on the order devices are probed on the
284 system. If more than one device requests an enumeration for the same
285 name at the same time, it may be possible that both requests receive the
286 same name back from the database. The use of enumerations in todays setups
287 where device can come and go at any time is not recomended.
290 The '%' character itself.
292 The count of characters to insert may be limited by specifying
293 the format length value. For example, '%3s{file}' will only insert
294 the first three characters of the sysfs attribute.
296 .RI "A sample " udev.rules " file might look like this:"
299 # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1
300 BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1"
302 # USB printer to be called lp_color
303 BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color"
305 # SCSI disk with a specific vendor and model number will be called boot
306 BUS=="scsi", SYSFS{vendor}=="IBM", SYSFS{model}=="ST336", NAME="boot%n"
308 # sound card with PCI bus id 00:0b.0 to be called dsp
309 BUS=="pci", ID=="00:0b.0", NAME="dsp"
311 # USB mouse at third port of the second hub to be called mouse1
312 BUS=="usb", ID=="2.3", NAME="mouse1"
314 # ttyUSB1 should always be called pda with two additional symlinks
315 KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld"
317 # multiple USB webcams with symlinks to be called webcam0, webcam1, ...
318 BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n"
321 A number of different fields in the above configuration files support a simple
322 form of shell style pattern matching. It supports the following pattern characters:
325 Matches zero, one, or more characters.
328 Matches any single character, but does not match zero characters.
331 Matches any single character specified within the brackets. For example, the
332 pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also
333 supported within this match with the '\-' character. For example, to match on
334 the range of all digits, the pattern [0\-9] would be used. If the first character
335 following the '[' is a '!', any characters not enclosed are matched.
337 After device node creation, removal, or network device renaming,
339 executes the programs specified by the
343 In addition to the kernel provided hotplug environment variables,
345 is set and contains the numerical priority value, if udev is configured to use
347 Executed programs may want to follow that setting.
349 is exported to make the name of the created node, or the name the network
350 device is renamed to, available to the executed programs.
353 The following variables are read from the environment:
356 .IR add " or " remove
357 signifies the addition or the removal of a device.
360 The sysfs devpath of the device without the mountpoint but a leading slash.
363 The subsystem the device belongs to. Alternatively the subsystem may
364 be passed as the first argument.
367 Overrides the default location of the
372 Overrides the log priority specified in the config file.
375 If set to "0", it disables the execution of programs added by rules.
378 /sbin/udev udev program
379 /etc/udev/* udev config files
388 .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
389 .I http://linux\-hotplug.sourceforge.net/
393 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
394 Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and