1 .TH UDEV 8 "October 2003" "" "Linux Administrator's Manual"
3 udev \- Linux configurable dynamic device naming support
5 .BI udev " hotplug-subsystem"
7 The following variables are read from the environment:
11 signifies the addition or the removal of a device.
14 The sysfs devpath of the device without the mountpoint but a leading slash.
17 The subsystem the device belongs to. Alternatively the subsystem may
18 be passed as the first argument.
21 Overrides the default location of the
26 The default behavior of
28 is to execute programs in the
30 directory after device handling. If set,
35 provides a dynamic device directory containing only the files for actually
36 present devices. It creates or removes device node files usually located in
37 the /dev directory, or it renames network interfaces.
44 is executed if a kernel device is added or removed from the system.
47 reads the sysfs directory of the given device to collect device attributes
48 like label, serial number or bus device number.
49 These attributes may be used as keys to determine a
50 unique name for the device.
52 maintains a database for devices present on the system.
56 queries its database for the name of the device file to be deleted.
60 configuration files consist of a set of lines of text. All empty
61 lines or lines beginning with '#' will be ignored.
65 expects its main configuration file at
66 .IR /etc/udev/udev.conf .
67 The file consists of a set of variables and values allowing the user to
68 override default udev values. The following variables can be overridden
72 Indicates where to place the device nodes in the filesystem. The default
77 The name and location of the udev database. The default value is
78 .IR @udevdir@/.udevdb .
81 The name of the udev rules file or directory to look for files with the suffix
83 All rule files are read in lexical order. The default value is
84 .IR /etc/udev/rules.d/ .
87 The name of the udev permission file or directory to look for files with the
90 All permission files are read in lexical order. The default value is
91 .IR /etc/udev/permissions.d/ .
94 The switch to enable/disable logging of udev information
99 The default mode for all nodes not explicitly matching in the permissions
100 file. The default value is
104 The default owner for all nodes not explicitly matching in the permissions
105 file. The default value is
109 The default group for all nodes not explicitly matching in the permissions
110 file. The default value is
114 .RI "A sample " udev.conf " might look like this:
117 # udev_root - where to place the device nodes in the filesystem
120 # udev_db - The name and location of the udev database
121 udev_db="/udev/.udevdb"
123 # udev_rules - The name of the udev rules file or directory to look
124 for files with the suffix .rules
125 udev_rules="/etc/udev/rules.d/"
127 # udev_permissions - The name of the udev permission file or directory
128 to look for files with the suffix .permissions
129 udev_permissions="/etc/udev/udev.permissions"
131 # udev_log - set to "yes" if you want logging, else "no"
134 # default_mode - set the default mode for all nodes not
135 # explicitly matching in the permissions file
138 # default_owner - set the default owner for all nodes not
139 # explicitly matching in the permissions file
142 # default_group - set the default group for all nodes not
143 # explicitly matching in the permissions file
147 The rules for device naming are read from the files located in the
148 .I /etc/udev/rules.d/
149 directory, or at the location specified by the
152 .I /etc/udev/udev.conf
155 Every line in the rules file defines the mapping between device attributes
156 and the device name. One or more keys are specified to match a rule with
157 the current device. If all keys are matching, the rule will be applied and
158 the name is used to name the device file or the network interface.
160 If no matching rule is found, the default kernel device name is used.
162 Every rule consists of a list of comma separated fields:
164 .IR "key " ,[ "key " ,...] " name " [, " symlink" ]
169 Match the bus type of the device.
170 (The sysfs device bus must be able to be determined by a "device" symlink.)
173 Match the kernel device name.
176 Match the kernel subsystem name.
179 Match the kernel driver name.
182 Match the device number on the bus, like PCI bus id.
185 Match the topological position on bus, like physical port of USB device
187 .BI SYSFS{ filename }
188 Match sysfs device attribute like label, vendor, USB serial number, SCSI UUID
189 or file system label. Up to 5 different sysfs files can be checked, with
190 all of the values being required to match the rule.
192 Trailing whitespace characters in the sysfs attribute value are ignored, if
193 the key doesn't have any trailing whitespace characters by itself.
196 Call external program. This key is valid if the program returns successful.
197 The environment variables of
199 are also available for the program.
201 The string returned by the program may be additionally matched with the
206 Match the returned string of the last
208 call. This key may be used in any following rule after a
213 The name of the node to be created, or the name, the network interface
214 should be renamed to.
216 If given with the attribute
217 .BR NAME{ all_partitions }
218 it will create all 15 partitions of a blockdevice.
219 This may be useful for removable media devices.
221 If given with the attribute
222 .BR NAME{ ignore_remove }
223 it will will ignore any later remove event for this device.
224 This may be useful as a workaround for broken device drivers.
226 Multiple attributes may be separated by comma.
229 The name of a symlink targeting the node. Multiple symlinks may be
230 specified by separating the names by the space character.
232 If both the name and the symlink fields are omitted or its
233 values are empty, the device will be ignored and no node will be created.
235 If only the symlink field is given and the name field is omitted,
236 the rule will not be applied immediately, but the symlink field is added
237 to the symlink list of the rule which will create the node.
238 This makes it possible to specify additional symlinks in a possibly
239 separate rules file, while the device nodes are maintained by the
240 distribution provided rules file.
242 .B OWNER, GROUP, MODE
243 The permissions for this device. Every specified value overwrites the value
244 given in the permissions file.
246 .RB "The " NAME " ," SYMLINK " and " PROGRAM
247 fields support simple printf-like string substitutions:
250 The "kernel number" of the device.
251 For example, 'sda3' has a "kernel number" of '3'.
254 The "kernel name" for the device.
257 The kernel major number for the device.
260 The kernel minor number for the device.
263 The bus id for the device.
266 The string returned by the external program, specified in
268 (This does not work within the
270 field for the obvious reason.)
272 A single part of the string, separated by a space character
273 may be selected by specifying the part number as an attribute:
275 If the number is followed by the + char this part plus
276 all remaining parts of the result string are substituted:
280 The content of a sysfs attribute.
283 If a device node already exists with the name, the smallest positive
284 decimal integer N is substituted such that the resulting name doesn't
285 match an existing device node. Otherwise nothing is substituted. This
286 can be used to create compatibility symlinks and enumerate devices of
287 the same type originating from different kernel subsystems.
290 The '%' character itself.
292 The count of charcters 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 " 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", PLACE="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"
320 # grouping of optical drives from multiple kernel subsystems
321 KERNEL="sr*", NAME="%k", SYMLINK="cdrom%e"
322 KERNEL="scd*", NAME="%k", SYMLINK="cdrom%e"
323 KERNEL="pcd*", NAME="%k", SYMLINK="cdrom%e"
324 KERNEL="hd[a-z]", PROGRAM="/bin/cat /proc/ide/%k/media", RESULT="cdrom",
325 NAME="%k", SYMLINK="cdrom%e"
329 The permissions and ownership of the created device file are read from
330 the files located in the
331 .I /etc/udev/permissions.d/
332 directory, or at the location specified by the
335 .I /etc/udev/udev.conf
338 Every line lists a device name followed by owner, group and permission
339 mode. All values are separated by colons. The name field may contain a
340 pattern to apply the values to a whole class of devices.
342 .RI "A sample " udev.permissions " might look like this:"
345 #name:user:group:mode
346 input/*:root:root:644
348 video*:root:video:0660
352 A number of different fields in the above configuration files support a simple
353 form of shell style pattern matching. It supports the following pattern characters:
356 Matches zero, one, or more characters.
359 Matches any single character, but does not match zero characters.
362 Matches any single character specified within the brackets. For example, the
363 pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also
364 supported within this match with the '\-' character. For example, to match on
365 the range of all digits, the pattern [0\-9] would be used. If the first character
366 following the '[' is a '!', any characters not enclosed are matched.
368 After device node creation, removal, or network device renaming,
370 executes the programs in the directory tree under
372 The name of a program must have the suffix
376 In addition to the hotplug environment variables,
378 is set if udev is configured to use the syslog facility. Executed programs may
379 want to follow that setting.
381 is exported to make the name of the created node, or the name the network
382 device is renamed to, available to the executed program. The programs in every
383 directory are sorted in lexical order, while the directories are searched in
387 /etc/dev.d/$(DEVNAME)/*.dev
388 /etc/dev.d/$(SUBSYSTEM)/*.dev
389 /etc/dev.d/default/*.dev
393 /sbin/udev udev program
394 /etc/udev/* udev config files
395 /etc/hotplug.d/default/udev.hotplug hotplug symlink to udev program
396 /etc/dev.d/* programs invoked by udev
405 .I http://linux\-hotplug.sourceforge.net/
409 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
410 Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and