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 The following key names can be used to match against device properties:
110 Match the bus type of the device.
111 (The sysfs device bus must be able to be determined by a "device" symlink.)
114 Match the kernel device name.
117 Match the kernel subsystem name.
120 Match the kernel action name.
123 Match the kernel driver name.
126 Match the device number on the bus, like PCI bus id.
128 .BI SYSFS{ filename }
129 Match sysfs device attribute like vendor and product id's, USB serial number
130 or the SCSI disk model number. Up to 5 different sysfs files can be checked,
131 with all of the values being required to match the rule.
133 Trailing whitespace characters in the sysfs attribute value are ignored, if
134 the key doesn't have any trailing whitespace characters by itself.
137 Match an environment variable. Up to 5 different environment variables can be
138 checked, with all of the values being required to match the rule.
141 Call external program. This key is valid if the program returns successful.
142 The environment variables of
144 are also available to the program.
146 The string returned by the program may be additionally matched with the
148 key in the same or any later rule.
151 Match the returned string of the last
153 call. This key can be used in the same or in any later rule after a
157 The following keys can get values assigned:
160 The name of the node to be created, or the name, the network interface
161 should be renamed to.
164 The name of a symlink targeting the node. Every matching rule can add
165 this value to the list of symlinks to be created along with the device node.
166 Multiple symlinks may be specified by separating the names by the space
169 .B OWNER, GROUP, MODE
170 The permissions for the device node. Every specified value overwrites the
171 compiled-in default value.
174 Add a program to the list of programs to be executed for a specific device.
178 stops further rules application. No later rules will have any effect.
181 will ignore this device. No node will be created or program executed.
184 will ignore any later remove event for this device.
185 This may be useful as a workaround for broken device drivers.
188 will create device nodes for all available partitions of a blockdevice.
189 This may be useful for removable media devices which do not detect a media
192 Multiple attributes may be separated by comma.
194 .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP
195 fields support simple printf-like string substitutions:
198 The "kernel number" of the device.
199 For example, 'sda3' has a "kernel number" of '3'.
202 The "kernel name" for the device.
205 The devpath for the device.
208 The kernel major number for the device.
211 The kernel minor number for the device.
214 The bus id for the device.
217 The string returned by the external program, specified in
219 (This does not work within the
221 field for the obvious reason.)
223 A single part of the string, separated by a space character
224 may be selected by specifying the part number as an attribute:
226 If the number is followed by the + char this part plus
227 all remaining parts of the result string are substituted:
231 The name of a created temporary device node to provide access to the
232 device from a external program.
235 The node name of the parent device.
238 The content of a sysfs attribute.
244 If a device node already exists with the name, the smallest positive
245 decimal integer N is substituted such that the resulting name doesn't
246 match an existing device node. Otherwise nothing is substituted. This
247 can be used to create compatibility symlinks and enumerate devices of
248 the same type originating from different kernel subsystems.
250 Note: The use of the enumeration facility is unreliable outside of
251 udevstart where the node creation is serialized and predictable.
252 The returned numbers rely on the order devices are probed on the
253 system. If more than one device requests an enumeration for the same
254 name at the same time, it may be possible that both requests receive the
255 same name back from the database. The use of enumerations in todays setups
256 where device can come and go at any time is not recomended.
259 The '%' character itself.
261 The count of characters to insert may be limited by specifying
262 the format length value. For example, '%3s{file}' will only insert
263 the first three characters of the sysfs attribute.
265 .RI "A sample " udev.rules " file might look like this:"
268 # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1
269 BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1"
271 # USB printer to be called lp_color
272 BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color"
274 # SCSI disk with a specific vendor and model number will be called boot
275 BUS=="scsi", SYSFS{vendor}=="IBM", SYSFS{model}=="ST336", NAME="boot%n"
277 # sound card with PCI bus id 00:0b.0 to be called dsp
278 BUS=="pci", ID=="00:0b.0", NAME="dsp"
280 # USB mouse at third port of the second hub to be called mouse1
281 BUS=="usb", ID=="2.3", NAME="mouse1"
283 # ttyUSB1 should always be called pda with two additional symlinks
284 KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld"
286 # multiple USB webcams with symlinks to be called webcam0, webcam1, ...
287 BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n"
290 A number of different fields in the above configuration files support a simple
291 form of shell style pattern matching. It supports the following pattern characters:
294 Matches zero, one, or more characters.
297 Matches any single character, but does not match zero characters.
300 Matches any single character specified within the brackets. For example, the
301 pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also
302 supported within this match with the '\-' character. For example, to match on
303 the range of all digits, the pattern [0\-9] would be used. If the first character
304 following the '[' is a '!', any characters not enclosed are matched.
306 After device node creation, removal, or network device renaming,
308 executes the programs located in the directory tree under
310 The name of a program must have the suffix
314 In addition to the kernel provided hotplug environment variables,
316 is set and contains the numerical priority value, if udev is configured to use
318 Executed programs may want to follow that setting.
320 is exported to make the name of the created node, or the name the network
321 device is renamed to, available to the executed program. The programs in every
322 directory are sorted in lexical order, while the directories are searched in
326 /etc/dev.d/$(DEVNAME)/*.dev
327 /etc/dev.d/$(SUBSYSTEM)/*.dev
328 /etc/dev.d/default/*.dev
332 The following variables are read from the environment:
335 .IR add " or " remove
336 signifies the addition or the removal of a device.
339 The sysfs devpath of the device without the mountpoint but a leading slash.
342 The subsystem the device belongs to. Alternatively the subsystem may
343 be passed as the first argument.
346 Overrides the default location of the
351 Overrides the log priority specified in the config file.
354 If set to "0", it disables the execution of programs added by rules.
357 The default behavior of
359 is to execute programs in the
361 directory after device handling. If set,
366 /sbin/udev udev program
367 /etc/udev/* udev config files
368 /etc/dev.d/* programs invoked by udev
377 .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
378 .I http://linux\-hotplug.sourceforge.net/
382 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
383 Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and