]>
Commit | Line | Data |
---|---|---|
d3db5e5e | 1 | .TH UDEV 8 "October 2003" "" "Linux Administrator's Manual" |
04db8c9e | 2 | .SH NAME |
d3db5e5e | 3 | udev \- Linux configurable dynamic device naming support |
04db8c9e | 4 | .SH SYNOPSIS |
6b493a20 | 5 | .BI udev |
04db8c9e GKH |
6 | .SH "DESCRIPTION" |
7 | .B udev | |
fc238cff KS |
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 | |
eb13ff87 | 12 | .P |
d3db5e5e | 13 | As part of the |
14 | .B hotplug | |
15 | subsystem, | |
16 | .B udev | |
eb13ff87 | 17 | is executed if a kernel device is added or removed from the system. |
5165d1dc KS |
18 | A list of rules is used to match against specific device attributes. |
19 | .br | |
20 | On device addition, | |
d3db5e5e | 21 | .B udev |
5165d1dc KS |
22 | matches its configured rules against the available device attributes to |
23 | uniquely name the device. | |
da86c7f0 | 24 | .B udev |
5165d1dc KS |
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. | |
eb13ff87 | 28 | .br |
d3db5e5e | 29 | On device removal, |
30 | .B udev | |
4bd46ac7 | 31 | queries its database for the name of the device file to be deleted. |
5165d1dc KS |
32 | .br |
33 | After the device node handling, a list of collected programs specific to this | |
34 | device is executed. | |
eb13ff87 | 35 | .SH "CONFIGURATION" |
83fa40fc KS |
36 | All |
37 | .B udev | |
3ac03269 | 38 | configuration files consist of a set of lines of text. All empty |
5bc597fe | 39 | lines or lines beginning with '#' will be ignored. |
4865de44 | 40 | .P |
da86c7f0 | 41 | .B udev |
4865de44 | 42 | expects its main configuration file at |
167a27e7 | 43 | .IR /etc/udev/udev.conf . |
b86f56ff KS |
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: | |
4865de44 GKH |
47 | .TP |
48 | .B udev_root | |
b86f56ff KS |
49 | Indicates where to place the device nodes in the filesystem. The default |
50 | value is | |
aef6bb13 | 51 | .IR @udevdir@/ . |
4865de44 GKH |
52 | .TP |
53 | .B udev_db | |
b86f56ff | 54 | The name and location of the udev database. The default value is |
2b41e68a | 55 | .IR @udevdir@/.udevdb . |
4865de44 GKH |
56 | .TP |
57 | .B udev_rules | |
a5327755 KS |
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 | |
aef6bb13 | 61 | .IR /etc/udev/rules.d/ . |
4865de44 | 62 | .TP |
0c040e8d | 63 | .B udev_log |
6b493a20 KS |
64 | The logging priority which can be set to |
65 | .IR "err " , "info " | |
66 | or the corresponding numerical | |
67 | .BR syslog (3) | |
68 | value. | |
fc238cff | 69 | The default value is |
6b493a20 | 70 | .IR err . |
4865de44 | 71 | .P |
3ac03269 | 72 | .RI "A sample " udev.conf " file might look like this: |
4865de44 GKH |
73 | .sp |
74 | .nf | |
6b493a20 KS |
75 | # Where in the filesystem to place the device nodes |
76 | udev_root="@udevdir@" | |
4865de44 | 77 | |
6b493a20 KS |
78 | # The name and location of the udev database. |
79 | udev_db="@udevdir@/.udevdb" | |
4865de44 | 80 | |
6b493a20 KS |
81 | # The name and location of the udev rules file(s). |
82 | udev_rules="@configdir@/rules.d" | |
4865de44 | 83 | |
6b493a20 KS |
84 | # The syslog(3) priority: "err", "info", or the numerical value. |
85 | udev_log="err" | |
4865de44 GKH |
86 | .fi |
87 | .P | |
5bc597fe | 88 | The rules for device naming are read from the files located in the |
aef6bb13 KS |
89 | .I /etc/udev/rules.d/ |
90 | directory, or at the location specified by the | |
4865de44 | 91 | .I udev_rules |
d94df232 | 92 | value in the |
4865de44 GKH |
93 | .I /etc/udev/udev.conf |
94 | file. | |
aef6bb13 | 95 | .br |
4bd46ac7 | 96 | Every line in the rules file defines the mapping between device attributes |
fc238cff KS |
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. | |
c6c13c31 | 100 | .br |
4bd46ac7 | 101 | If no matching rule is found, the default kernel device name is used. |
3370fb21 | 102 | .P |
28ce66de | 103 | Every rule consists of a list of comma separated key value fields: |
eb13ff87 | 104 | .sp |
28ce66de KS |
105 | .IR "key " ,[ "key " ,...] |
106 | .P | |
107 | The following key names can be used to match against device properties: | |
d3db5e5e | 108 | .TP |
e15b5ed5 | 109 | .B BUS |
4bd46ac7 KS |
110 | Match the bus type of the device. |
111 | (The sysfs device bus must be able to be determined by a "device" symlink.) | |
112 | .TP | |
113 | .B KERNEL | |
114 | Match the kernel device name. | |
115 | .TP | |
6818c51d | 116 | .B SUBSYSTEM |
2092fbcd | 117 | Match the kernel subsystem name. |
6818c51d | 118 | .TP |
821d0ec8 KS |
119 | .B ACTION |
120 | Match the kernel action name. | |
121 | .TP | |
2092fbcd KS |
122 | .B DRIVER |
123 | Match the kernel driver name. | |
6818c51d | 124 | .TP |
4bd46ac7 KS |
125 | .B ID |
126 | Match the device number on the bus, like PCI bus id. | |
127 | .TP | |
16378373 | 128 | .BI SYSFS{ filename } |
3e5958de KS |
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. | |
d5f91372 KS |
132 | .br |
133 | Trailing whitespace characters in the sysfs attribute value are ignored, if | |
134 | the key doesn't have any trailing whitespace characters by itself. | |
4bd46ac7 | 135 | .TP |
3e5958de KS |
136 | .BI ENV{ variable } |
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. | |
139 | .TP | |
4bd46ac7 KS |
140 | .B PROGRAM |
141 | Call external program. This key is valid if the program returns successful. | |
dde05ccb | 142 | The environment variables of |
bef370d6 | 143 | .B udev |
28ce66de | 144 | are also available to the program. |
bef370d6 | 145 | .br |
b86f56ff | 146 | The string returned by the program may be additionally matched with the |
4bd46ac7 | 147 | .B RESULT |
28ce66de | 148 | key in the same or any later rule. |
4bd46ac7 KS |
149 | .TP |
150 | .B RESULT | |
151 | Match the returned string of the last | |
152 | .B PROGRAM | |
28ce66de | 153 | call. This key can be used in the same or in any later rule after a |
4bd46ac7 KS |
154 | .B PROGRAM |
155 | call. | |
28ce66de KS |
156 | .P |
157 | The following keys can get values assigned: | |
311e9ae6 | 158 | .TP |
16378373 | 159 | .B NAME |
fc238cff KS |
160 | The name of the node to be created, or the name, the network interface |
161 | should be renamed to. | |
311e9ae6 KS |
162 | .TP |
163 | .B SYMLINK | |
5165d1dc KS |
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 | |
167 | character. | |
e41016d3 KS |
168 | .TP |
169 | .B OWNER, GROUP, MODE | |
9f8dfa19 | 170 | The permissions for the device node. Every specified value overwrites the |
3908058c | 171 | compiled-in default value. |
fd9efc00 | 172 | .TP |
821d0ec8 KS |
173 | .B RUN |
174 | Add a program to the list of programs to be executed for a specific device. | |
175 | .TP | |
fd9efc00 | 176 | .B OPTIONS |
28ce66de | 177 | .B last_rule |
5165d1dc | 178 | stops further rules application. No later rules will have any effect. |
28ce66de | 179 | .sp |
fd9efc00 | 180 | .B ignore_device |
5165d1dc | 181 | will ignore this device. No node will be created or program executed. |
fd9efc00 KS |
182 | .sp |
183 | .B ignore_remove | |
184 | will ignore any later remove event for this device. | |
185 | This may be useful as a workaround for broken device drivers. | |
186 | .sp | |
187 | .B all_partitions | |
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 | |
190 | change. | |
191 | .sp | |
192 | Multiple attributes may be separated by comma. | |
16378373 | 193 | .P |
9f8dfa19 | 194 | .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP |
5bc597fe | 195 | fields support simple printf-like string substitutions: |
4b710f03 KS |
196 | .TP |
197 | .B %n | |
c6c13c31 | 198 | The "kernel number" of the device. |
63ead27c | 199 | For example, 'sda3' has a "kernel number" of '3'. |
4b710f03 | 200 | .TP |
170ae44e GKH |
201 | .B %k |
202 | The "kernel name" for the device. | |
203 | .TP | |
c1ab0461 KS |
204 | .B %p |
205 | The devpath for the device. | |
206 | .TP | |
4b710f03 | 207 | .B %M |
c6c13c31 | 208 | The kernel major number for the device. |
4b710f03 KS |
209 | .TP |
210 | .B %m | |
c6c13c31 | 211 | The kernel minor number for the device. |
4b710f03 KS |
212 | .TP |
213 | .B %b | |
c6c13c31 | 214 | The bus id for the device. |
67922099 GKH |
215 | .TP |
216 | .B %c | |
5bc597fe | 217 | The string returned by the external program, specified in |
e68faf51 | 218 | .B PROGRAM |
e68faf51 KS |
219 | (This does not work within the |
220 | .B PROGRAM | |
221 | field for the obvious reason.) | |
ad63031e | 222 | .br |
b86f56ff | 223 | A single part of the string, separated by a space character |
c5828665 | 224 | may be selected by specifying the part number as an attribute: |
558f80ba KS |
225 | .BI %c{ N } |
226 | If the number is followed by the + char this part plus | |
227 | all remaining parts of the result string are substituted: | |
228 | .BI %c{ N+ } | |
ad63031e | 229 | .TP |
c1ab0461 KS |
230 | .B %N |
231 | The name of a created temporary device node to provide access to the | |
232 | device from a external program. | |
233 | .TP | |
69aa6dfb KS |
234 | .B %P |
235 | The node name of the parent device. | |
236 | .TP | |
ad63031e KS |
237 | .BI %s{ filename } |
238 | The content of a sysfs attribute. | |
36043f84 | 239 | .TP |
821d0ec8 KS |
240 | .B %r |
241 | The udev_root value. | |
242 | .TP | |
0a8dd7f3 DZ |
243 | .B %e |
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. | |
29e8ed4c KS |
249 | .sp |
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. | |
0a8dd7f3 | 257 | .TP |
b6864b4b | 258 | .B %% |
63ead27c KS |
259 | The '%' character itself. |
260 | .P | |
5165d1dc | 261 | The count of characters to insert may be limited by specifying |
63ead27c KS |
262 | the format length value. For example, '%3s{file}' will only insert |
263 | the first three characters of the sysfs attribute. | |
4b710f03 | 264 | .P |
3ac03269 | 265 | .RI "A sample " udev.rules " file might look like this:" |
eb13ff87 | 266 | .sp |
d3db5e5e | 267 | .nf |
5bc597fe | 268 | # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1 |
28ce66de | 269 | BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1" |
67922099 | 270 | |
d3db5e5e | 271 | # USB printer to be called lp_color |
28ce66de | 272 | BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color" |
d3db5e5e | 273 | |
b86f56ff | 274 | # SCSI disk with a specific vendor and model number will be called boot |
28ce66de | 275 | BUS=="scsi", SYSFS{vendor}=="IBM", SYSFS{model}=="ST336", NAME="boot%n" |
aa9c2a1e | 276 | |
d3db5e5e | 277 | # sound card with PCI bus id 00:0b.0 to be called dsp |
28ce66de | 278 | BUS=="pci", ID=="00:0b.0", NAME="dsp" |
d3db5e5e | 279 | |
280 | # USB mouse at third port of the second hub to be called mouse1 | |
28ce66de | 281 | BUS=="usb", ID=="2.3", NAME="mouse1" |
d3db5e5e | 282 | |
26004fcc | 283 | # ttyUSB1 should always be called pda with two additional symlinks |
28ce66de | 284 | KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" |
3370fb21 | 285 | |
26004fcc | 286 | # multiple USB webcams with symlinks to be called webcam0, webcam1, ... |
28ce66de | 287 | BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n" |
d3db5e5e | 288 | .fi |
eb13ff87 | 289 | .P |
07d7cfd1 | 290 | A number of different fields in the above configuration files support a simple |
83fa40fc | 291 | form of shell style pattern matching. It supports the following pattern characters: |
07d7cfd1 GKH |
292 | .TP |
293 | .B * | |
294 | Matches zero, one, or more characters. | |
295 | .TP | |
296 | .B ? | |
297 | Matches any single character, but does not match zero characters. | |
298 | .TP | |
299 | .B [ ] | |
300 | Matches any single character specified within the brackets. For example, the | |
3ac03269 TK |
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 | |
758f236f | 303 | the range of all digits, the pattern [0\-9] would be used. If the first character |
5bc597fe | 304 | following the '[' is a '!', any characters not enclosed are matched. |
fc238cff KS |
305 | .P |
306 | After device node creation, removal, or network device renaming, | |
307 | .B udev | |
3ac03269 | 308 | executes the programs located in the directory tree under |
fc238cff | 309 | .IR /etc/dev.d/ . |
5bc597fe | 310 | The name of a program must have the suffix |
fc238cff | 311 | .I .dev |
5bc597fe | 312 | to be recognized. |
fc238cff | 313 | .br |
81af4e05 | 314 | In addition to the kernel provided hotplug environment variables, |
a0294b76 | 315 | .B UDEV_LOG |
6b493a20 KS |
316 | is set and contains the numerical priority value, if udev is configured to use |
317 | .BR syslog (3). | |
318 | Executed programs may want to follow that setting. | |
fc238cff KS |
319 | .B DEVNAME |
320 | is exported to make the name of the created node, or the name the network | |
3ac03269 | 321 | device is renamed to, available to the executed program. The programs in every |
fc238cff KS |
322 | directory are sorted in lexical order, while the directories are searched in |
323 | the following order: | |
324 | .sp | |
325 | .nf | |
326 | /etc/dev.d/$(DEVNAME)/*.dev | |
327 | /etc/dev.d/$(SUBSYSTEM)/*.dev | |
328 | /etc/dev.d/default/*.dev | |
329 | .fi | |
3ac03269 TK |
330 | .SH "ENVIRONMENT" |
331 | .P | |
332 | The following variables are read from the environment: | |
333 | .TP | |
334 | .B ACTION | |
335 | .IR add " or " remove | |
336 | signifies the addition or the removal of a device. | |
337 | .TP | |
338 | .B DEVPATH | |
339 | The sysfs devpath of the device without the mountpoint but a leading slash. | |
340 | .TP | |
341 | .B SUBSYSTEM | |
342 | The subsystem the device belongs to. Alternatively the subsystem may | |
343 | be passed as the first argument. | |
344 | .TP | |
345 | .B UDEV_CONFIG_FILE | |
346 | Overrides the default location of the | |
347 | .B udev | |
348 | config file. | |
349 | .TP | |
6b493a20 KS |
350 | .B UDEV_LOG |
351 | Overrides the log priority specified in the config file. | |
352 | .TP | |
821d0ec8 KS |
353 | .B UDEV_RUN |
354 | If set to "0", it disables the execution of programs added by rules. | |
355 | .TP | |
3ac03269 TK |
356 | .B UDEV_NO_DEVD |
357 | The default behavior of | |
358 | .B udev | |
359 | is to execute programs in the | |
360 | .I /etc/dev.d/ | |
361 | directory after device handling. If set, | |
362 | .B udev | |
363 | will skip this step. | |
04db8c9e GKH |
364 | .SH "FILES" |
365 | .nf | |
04db8c9e | 366 | /sbin/udev udev program |
4865de44 | 367 | /etc/udev/* udev config files |
fc238cff | 368 | /etc/dev.d/* programs invoked by udev |
04db8c9e | 369 | .fi |
04db8c9e | 370 | .SH "SEE ALSO" |
05c0c9da | 371 | .BR udevinfo (8), |
bef370d6 | 372 | .BR udevd (8), |
eb13ff87 | 373 | .BR hotplug (8) |
04db8c9e | 374 | .PP |
3ac03269 TK |
375 | .B Web resources: |
376 | .nf | |
3ac03269 | 377 | .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html |
6b493a20 | 378 | .I http://linux\-hotplug.sourceforge.net/ |
3ac03269 | 379 | .fi |
04db8c9e | 380 | .SH AUTHORS |
da86c7f0 KS |
381 | .B udev |
382 | was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from | |
fc1f0d43 GKH |
383 | Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and |
384 | many others. |