chiark / gitweb /
more distro rules updates
[elogind.git] / udev.8.in
1 .TH UDEV 8 "October 2003" "" "Linux Administrator's Manual"
2 .SH NAME
3 udev \- Linux configurable dynamic device naming support
4 .SH SYNOPSIS
5 .BI udev
6 .SH "DESCRIPTION"
7 .B udev
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.
11 .br
12 .P
13 As part of the
14 .B hotplug
15 subsystem,
16 .B udev
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.
19 .br
20 On device addition,
21 .B udev
22 matches its configured rules against the available device attributes to
23 uniquely name the device.
24 .B udev
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.
28 .br
29 On device removal,
30 .B udev
31 queries its database for the name of the device file to be deleted.
32 .br
33 After the device node handling, a list of collected programs specific to this
34 device is executed.
35 .SH "CONFIGURATION"
36 All
37 .B udev
38 configuration files consist of a set of lines of text. All empty
39 lines or lines beginning with '#' will be ignored.
40 .P
41 .B udev
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
46 in this file:
47 .TP
48 .B udev_root
49 Indicates where to place the device nodes in the filesystem. The default
50 value is
51 .IR @udevdir@/ .
52 .TP
53 .B udev_db
54 The name and location of the udev database. The default value is
55 .IR @udevdir@/.udevdb .
56 .TP
57 .B udev_rules
58 The name of the udev rules file or directory to look for files with the suffix
59 .IR .rules .
60 All rule files are read in lexical order. The default value is
61 .IR /etc/udev/rules.d/ .
62 .TP
63 .B udev_log
64 The logging priority which can be set to
65 .IR "err " , "info "
66 or the corresponding numerical
67 .BR syslog (3)
68 value.
69 The default value is
70 .IR err .
71 .P
72 .RI "A sample " udev.conf " file might look like this:
73 .sp
74 .nf
75 # Where in the filesystem to place the device nodes
76 udev_root="@udevdir@"
77
78 # The name and location of the udev database.
79 udev_db="@udevdir@/.udevdb"
80
81 # The name and location of the udev rules file(s).
82 udev_rules="@configdir@/rules.d"
83
84 # The syslog(3) priority: "err", "info", or the numerical value.
85 udev_log="err"
86 .fi
87 .P
88 The rules for device naming are read from the files located in the
89 .I /etc/udev/rules.d/
90 directory, or at the location specified by the
91 .I udev_rules
92 value in the
93 .I /etc/udev/udev.conf
94 file.
95 .br
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.
100 .br
101 If no matching rule is found, the default kernel device name is used.
102 .P
103 Every rule consists of a list of comma separated key value fields:
104 .sp
105 .IR "key " ,[ "key " ,...]
106 .P
107 Each key has the following format:
108 .sp
109 .IR "name op value"
110 .P
111 There are distinct key operation types, depending on the type of the key, it
112 does a comparison or an assignment.
113 .P
114 Comparison operators are:
115 .TP
116 .B ==
117 Compare for equality.
118 .TP
119 .B !=
120 Compare for non-equality.
121 .P
122 Assignment operators are:
123 .TP
124 .B +=
125 Add the value to a key that holds a list of entries.
126 .TP
127 .B :=
128 Assign a value to a key finally; disallow any later changes, which
129 is useful to prevent changes by any later rules.
130 .TP
131 .B =
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.
136 .P
137 The following key names can be used to match against device properties:
138 .TP
139 .B BUS
140 Match the bus type of the device.
141 (The sysfs device bus must be able to be determined by a "device" symlink.)
142 .TP
143 .B KERNEL
144 Match the kernel device name.
145 .TP
146 .B SUBSYSTEM
147 Match the kernel subsystem name.
148 .TP
149 .B ACTION
150 Match the kernel action name.
151 .TP
152 .B DRIVER
153 Match the kernel driver name.
154 .TP
155 .B ID
156 Match the device number on the bus, like PCI bus id.
157 .TP
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.
162 .br
163 Trailing whitespace characters in the sysfs attribute value are ignored, if
164 the key doesn't have any trailing whitespace characters by itself.
165 .TP
166 .BI ENV{ variable }
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.
169 .TP
170 .B PROGRAM
171 Call external program. This key is valid if the program returns successful.
172 The environment variables of
173 .B udev
174 are also available to the program.
175 .br
176 The string returned by the program may be additionally matched with the
177 .B RESULT
178 key in the same or any later rule.
179 .TP
180 .B RESULT
181 Match the returned string of the last
182 .B PROGRAM
183 call. This key can be used in the same or in any later rule after a
184 .B PROGRAM
185 call.
186 .P
187 The following keys can get values assigned:
188 .TP
189 .B NAME
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.
193 .TP
194 .B SYMLINK
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
198 character.
199 .TP
200 .B OWNER, GROUP, MODE
201 The permissions for the device node. Every specified value overwrites the
202 compiled-in default value.
203 .TP
204 .B RUN
205 Add a program to the list of programs to be executed for a specific device.
206 .TP
207 .B OPTIONS
208 .B last_rule
209 stops further rules application. No later rules will have any effect.
210 .sp
211 .B ignore_device
212 will ignore this device. No node will be created or program executed.
213 .sp
214 .B ignore_remove
215 will ignore any later remove event for this device.
216 This may be useful as a workaround for broken device drivers.
217 .sp
218 .B all_partitions
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
221 change.
222 .sp
223 Multiple attributes may be separated by comma.
224 .P
225 .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP
226 fields support simple printf-like string substitutions:
227 .TP
228 .B %n
229 The "kernel number" of the device.
230 For example, 'sda3' has a "kernel number" of '3'.
231 .TP
232 .B %k
233 The "kernel name" for the device.
234 .TP
235 .B %p
236 The devpath for the device.
237 .TP
238 .B %M
239 The kernel major number for the device.
240 .TP
241 .B %m
242 The kernel minor number for the device.
243 .TP
244 .B %b
245 The bus id for the device.
246 .TP
247 .B %c
248 The string returned by the external program, specified in
249 .B PROGRAM
250 (This does not work within the
251 .B PROGRAM
252 field for the obvious reason.)
253 .br
254 A single part of the string, separated by a space character
255 may be selected by specifying the part number as an attribute:
256 .BI %c{ N }
257 If the number is followed by the + char this part plus
258 all remaining parts of the result string are substituted:
259 .BI %c{ N+ }
260 .TP
261 .B %N
262 The name of a created temporary device node to provide access to the
263 device from a external program.
264 .TP
265 .B %P
266 The node name of the parent device.
267 .TP
268 .BI %s{ filename }
269 The content of a sysfs attribute.
270 .TP
271 .B %r
272 The udev_root value.
273 .TP
274 .B %e
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.
280 .sp
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.
288 .TP
289 .B %%
290 The '%' character itself.
291 .P
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.
295 .P
296 .RI "A sample " udev.rules " file might look like this:"
297 .sp
298 .nf
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"
301
302 # USB printer to be called lp_color
303 BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color"
304
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"
307
308 # sound card with PCI bus id 00:0b.0 to be called dsp
309 BUS=="pci", ID=="00:0b.0", NAME="dsp"
310
311 # USB mouse at third port of the second hub to be called mouse1
312 BUS=="usb", ID=="2.3", NAME="mouse1"
313
314 # ttyUSB1 should always be called pda with two additional symlinks
315 KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld"
316
317 # multiple USB webcams with symlinks to be called webcam0, webcam1, ...
318 BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n"
319 .fi
320 .P
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:
323 .TP
324 .B *
325 Matches zero, one, or more characters.
326 .TP
327 .B ?
328 Matches any single character, but does not match zero characters.
329 .TP
330 .B [ ]
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.
336 .P
337 After device node creation, removal, or network device renaming,
338 .B udev
339 executes the programs specified by the
340 .B RUN
341 key.
342 .br
343 In addition to the kernel provided hotplug environment variables,
344 .B UDEV_LOG
345 is set and contains the numerical priority value, if udev is configured to use
346 .BR syslog (3).
347 Executed programs may want to follow that setting.
348 .B DEVNAME
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.
351 .SH "ENVIRONMENT"
352 .P
353 The following variables are read from the environment:
354 .TP
355 .B ACTION
356 .IR add " or " remove
357 signifies the addition or the removal of a device.
358 .TP
359 .B DEVPATH
360 The sysfs devpath of the device without the mountpoint but a leading slash.
361 .TP
362 .B SUBSYSTEM
363 The subsystem the device belongs to. Alternatively the subsystem may
364 be passed as the first argument.
365 .TP
366 .B UDEV_CONFIG_FILE
367 Overrides the default location of the
368 .B udev
369 config file.
370 .TP
371 .B UDEV_LOG
372 Overrides the log priority specified in the config file.
373 .TP
374 .B UDEV_RUN
375 If set to "0", it disables the execution of programs added by rules.
376 .SH "FILES"
377 .nf
378 /sbin/udev                           udev program
379 /etc/udev/*                          udev config files
380 .fi
381 .SH "SEE ALSO"
382 .BR udevinfo (8),
383 .BR udevd (8),
384 .BR hotplug (8)
385 .PP
386 .B Web resources:
387 .nf
388 .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
389 .I http://linux\-hotplug.sourceforge.net/
390 .fi
391 .SH AUTHORS
392 .B udev
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
395 many others.