]>
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 |
eb13ff87 | 5 | .BI udev " hotplug-subsystem" |
bef370d6 | 6 | .P |
a0294b76 | 7 | The following variables are read from the environment: |
bef370d6 KS |
8 | .TP |
9 | .B ACTION | |
10 | .IR add " or " remove | |
a0294b76 KS |
11 | signifies the addition or the removal of a device. |
12 | .P | |
bef370d6 KS |
13 | .B DEVPATH |
14 | The sysfs devpath of the device without the mountpoint but a leading slash. | |
15 | .P | |
a0294b76 KS |
16 | .B SUBSYSTEM |
17 | The subsystem the device belongs to. Alternatively the subsystem may | |
18 | be passed as the first argument. | |
19 | .P | |
bef370d6 KS |
20 | .B UDEV_CONFIG_FILE |
21 | Overrides the default location of the | |
22 | .B udev | |
23 | config file. | |
a0294b76 | 24 | .P |
fc238cff KS |
25 | .B UDEV_NO_DEVD |
26 | The default behavior of | |
27 | .B udev | |
28 | is to execute programs in the | |
29 | .I /etc/dev.d/ | |
30 | directory after device handling. If set, | |
31 | .B udev | |
32 | will skip this step. | |
04db8c9e GKH |
33 | .SH "DESCRIPTION" |
34 | .B udev | |
fc238cff KS |
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. | |
38 | .br | |
eb13ff87 | 39 | .P |
d3db5e5e | 40 | As part of the |
41 | .B hotplug | |
42 | subsystem, | |
43 | .B udev | |
eb13ff87 | 44 | is executed if a kernel device is added or removed from the system. |
d3db5e5e | 45 | On device creation, |
46 | .B udev | |
eb13ff87 | 47 | reads the sysfs directory of the given device to collect device attributes |
d3db5e5e | 48 | like label, serial number or bus device number. |
b86f56ff | 49 | These attributes may be used as keys to determine a |
fc238cff | 50 | unique name for the device. |
da86c7f0 KS |
51 | .B udev |
52 | maintains a database for devices present on the system. | |
eb13ff87 | 53 | .br |
d3db5e5e | 54 | On device removal, |
55 | .B udev | |
4bd46ac7 | 56 | queries its database for the name of the device file to be deleted. |
eb13ff87 | 57 | .SH "CONFIGURATION" |
83fa40fc KS |
58 | All |
59 | .B udev | |
60 | configuration files consist of a set of lines of text. All empty | |
5bc597fe | 61 | lines or lines beginning with '#' will be ignored. |
4865de44 GKH |
62 | .P |
63 | ||
da86c7f0 | 64 | .B udev |
4865de44 | 65 | expects its main configuration file at |
167a27e7 | 66 | .IR /etc/udev/udev.conf . |
b86f56ff KS |
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 | |
69 | in this file: | |
4865de44 GKH |
70 | .TP |
71 | .B udev_root | |
b86f56ff KS |
72 | Indicates where to place the device nodes in the filesystem. The default |
73 | value is | |
aef6bb13 | 74 | .IR @udevdir@/ . |
4865de44 GKH |
75 | .TP |
76 | .B udev_db | |
b86f56ff | 77 | The name and location of the udev database. The default value is |
2b41e68a | 78 | .IR @udevdir@/.udevdb . |
4865de44 GKH |
79 | .TP |
80 | .B udev_rules | |
a5327755 KS |
81 | The name of the udev rules file or directory to look for files with the suffix |
82 | .IR .rules . | |
83 | All rule files are read in lexical order. The default value is | |
aef6bb13 | 84 | .IR /etc/udev/rules.d/ . |
4865de44 GKH |
85 | .TP |
86 | .B udev_permissions | |
a5327755 KS |
87 | The name of the udev permission file or directory to look for files with the |
88 | suffix | |
89 | .IR .permissions . | |
90 | All permission files are read in lexical order. The default value is | |
aef6bb13 | 91 | .IR /etc/udev/permissions.d/ . |
4865de44 | 92 | .TP |
0c040e8d | 93 | .B udev_log |
5bc597fe | 94 | The switch to enable/disable logging of udev information |
fc238cff | 95 | The default value is |
167a27e7 | 96 | .IR yes . |
0c040e8d | 97 | .TP |
4865de44 | 98 | .B default_mode |
5bc597fe | 99 | The default mode for all nodes not explicitly matching in the permissions |
a5327755 | 100 | file. The default value is |
167a27e7 | 101 | .IR 0666 . |
765cbd97 KS |
102 | .TP |
103 | .B default_owner | |
5bc597fe | 104 | The default owner for all nodes not explicitly matching in the permissions |
a5327755 | 105 | file. The default value is |
167a27e7 | 106 | .IR root . |
765cbd97 KS |
107 | .TP |
108 | .B default_group | |
5bc597fe | 109 | The default group for all nodes not explicitly matching in the permissions |
a5327755 | 110 | file. The default value is |
167a27e7 | 111 | .IR root . |
d3db5e5e | 112 | .br |
4865de44 | 113 | .P |
c6c13c31 | 114 | .RI "A sample " udev.conf " might look like this: |
4865de44 GKH |
115 | .sp |
116 | .nf | |
b86f56ff | 117 | # udev_root - where to place the device nodes in the filesystem |
aef6bb13 | 118 | udev_root="/udev" |
4865de44 | 119 | |
b86f56ff | 120 | # udev_db - The name and location of the udev database |
2b41e68a | 121 | udev_db="/udev/.udevdb" |
4865de44 | 122 | |
a5327755 KS |
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/" | |
4865de44 | 126 | |
aef6bb13 KS |
127 | # udev_permissions - The name of the udev permission file or directory |
128 | to look for files with the suffix .permissions | |
4865de44 GKH |
129 | udev_permissions="/etc/udev/udev.permissions" |
130 | ||
0c040e8d GKH |
131 | # udev_log - set to "yes" if you want logging, else "no" |
132 | udev_log="yes" | |
133 | ||
b86f56ff | 134 | # default_mode - set the default mode for all nodes not |
5bc597fe | 135 | # explicitly matching in the permissions file |
4865de44 | 136 | default_mode="0666" |
765cbd97 | 137 | |
b86f56ff | 138 | # default_owner - set the default owner for all nodes not |
5bc597fe | 139 | # explicitly matching in the permissions file |
765cbd97 KS |
140 | default_owner="root" |
141 | ||
b86f56ff | 142 | # default_group - set the default group for all nodes not |
5bc597fe | 143 | # explicitly matching in the permissions file |
765cbd97 | 144 | default_group="root" |
4865de44 GKH |
145 | .fi |
146 | .P | |
5bc597fe | 147 | The rules for device naming are read from the files located in the |
aef6bb13 KS |
148 | .I /etc/udev/rules.d/ |
149 | directory, or at the location specified by the | |
4865de44 | 150 | .I udev_rules |
d94df232 | 151 | value in the |
4865de44 GKH |
152 | .I /etc/udev/udev.conf |
153 | file. | |
aef6bb13 | 154 | .br |
4bd46ac7 | 155 | Every line in the rules file defines the mapping between device attributes |
fc238cff KS |
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. | |
c6c13c31 | 159 | .br |
4bd46ac7 | 160 | If no matching rule is found, the default kernel device name is used. |
3370fb21 | 161 | .P |
c5828665 | 162 | Every rule consists of a list of comma separated fields: |
eb13ff87 | 163 | .sp |
311e9ae6 | 164 | .IR "key " ,[ "key " ,...] " name " [, " symlink" ] |
eb13ff87 | 165 | .sp |
b86f56ff | 166 | where fields are: |
d3db5e5e | 167 | .TP |
e15b5ed5 | 168 | .B BUS |
4bd46ac7 KS |
169 | Match the bus type of the device. |
170 | (The sysfs device bus must be able to be determined by a "device" symlink.) | |
171 | .TP | |
172 | .B KERNEL | |
173 | Match the kernel device name. | |
174 | .TP | |
6818c51d | 175 | .B SUBSYSTEM |
2092fbcd | 176 | Match the kernel subsystem name. |
6818c51d | 177 | .TP |
2092fbcd KS |
178 | .B DRIVER |
179 | Match the kernel driver name. | |
6818c51d | 180 | .TP |
4bd46ac7 KS |
181 | .B ID |
182 | Match the device number on the bus, like PCI bus id. | |
183 | .TP | |
184 | .B PLACE | |
185 | Match the topological position on bus, like physical port of USB device | |
186 | .TP | |
16378373 | 187 | .BI SYSFS{ filename } |
4bd46ac7 KS |
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 | |
b86f56ff | 190 | all of the values being required to match the rule. |
d5f91372 KS |
191 | .br |
192 | Trailing whitespace characters in the sysfs attribute value are ignored, if | |
193 | the key doesn't have any trailing whitespace characters by itself. | |
4bd46ac7 KS |
194 | .TP |
195 | .B PROGRAM | |
196 | Call external program. This key is valid if the program returns successful. | |
dde05ccb | 197 | The environment variables of |
bef370d6 KS |
198 | .B udev |
199 | are also available for the program. | |
200 | .br | |
b86f56ff | 201 | The string returned by the program may be additionally matched with the |
4bd46ac7 KS |
202 | .B RESULT |
203 | key. | |
204 | .TP | |
205 | .B RESULT | |
206 | Match the returned string of the last | |
207 | .B PROGRAM | |
b86f56ff | 208 | call. This key may be used in any following rule after a |
4bd46ac7 KS |
209 | .B PROGRAM |
210 | call. | |
311e9ae6 | 211 | .TP |
16378373 | 212 | .B NAME |
fc238cff KS |
213 | The name of the node to be created, or the name, the network interface |
214 | should be renamed to. | |
311e9ae6 KS |
215 | .br |
216 | If given with the attribute | |
16378373 | 217 | .BR NAME{ all_partitions } |
311e9ae6 | 218 | it will create all 15 partitions of a blockdevice. |
16378373 | 219 | This may be useful for removable media devices. |
7efa217d KS |
220 | .br |
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. | |
225 | .sp | |
226 | Multiple attributes may be separated by comma. | |
311e9ae6 KS |
227 | .TP |
228 | .B SYMLINK | |
229 | The name of a symlink targeting the node. Multiple symlinks may be | |
230 | specified by separating the names by the space character. | |
2bd07cf2 KS |
231 | .br |
232 | If both the name and the symlink fields are omitted or its | |
5bc597fe | 233 | values are empty, the device will be ignored and no node will be created. |
2bd07cf2 KS |
234 | .br |
235 | If only the symlink field is given and the name field is omitted, | |
5bc597fe | 236 | the rule will not be applied immediately, but the symlink field is added |
2bd07cf2 KS |
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. | |
e41016d3 KS |
241 | .TP |
242 | .B OWNER, GROUP, MODE | |
243 | The permissions for this device. Every specified value overwrites the value | |
244 | given in the permissions file. | |
16378373 | 245 | .P |
c6c13c31 | 246 | .RB "The " NAME " ," SYMLINK " and " PROGRAM |
5bc597fe | 247 | fields support simple printf-like string substitutions: |
4b710f03 KS |
248 | .TP |
249 | .B %n | |
c6c13c31 | 250 | The "kernel number" of the device. |
63ead27c | 251 | For example, 'sda3' has a "kernel number" of '3'. |
4b710f03 | 252 | .TP |
170ae44e GKH |
253 | .B %k |
254 | The "kernel name" for the device. | |
255 | .TP | |
4b710f03 | 256 | .B %M |
c6c13c31 | 257 | The kernel major number for the device. |
4b710f03 KS |
258 | .TP |
259 | .B %m | |
c6c13c31 | 260 | The kernel minor number for the device. |
4b710f03 KS |
261 | .TP |
262 | .B %b | |
c6c13c31 | 263 | The bus id for the device. |
67922099 GKH |
264 | .TP |
265 | .B %c | |
5bc597fe | 266 | The string returned by the external program, specified in |
e68faf51 | 267 | .B PROGRAM |
e68faf51 KS |
268 | (This does not work within the |
269 | .B PROGRAM | |
270 | field for the obvious reason.) | |
ad63031e | 271 | .br |
b86f56ff | 272 | A single part of the string, separated by a space character |
c5828665 | 273 | may be selected by specifying the part number as an attribute: |
558f80ba KS |
274 | .BI %c{ N } |
275 | If the number is followed by the + char this part plus | |
276 | all remaining parts of the result string are substituted: | |
277 | .BI %c{ N+ } | |
ad63031e KS |
278 | .TP |
279 | .BI %s{ filename } | |
280 | The content of a sysfs attribute. | |
36043f84 | 281 | .TP |
0a8dd7f3 DZ |
282 | .B %e |
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. | |
288 | .TP | |
b6864b4b | 289 | .B %% |
63ead27c KS |
290 | The '%' character itself. |
291 | .P | |
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. | |
4b710f03 | 295 | .P |
c6c13c31 | 296 | .RI "A sample " udev.rules " might look like this:" |
eb13ff87 | 297 | .sp |
d3db5e5e | 298 | .nf |
5bc597fe | 299 | # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1 |
4bd46ac7 | 300 | BUS="scsi", PROGRAM="/sbin/scsi_id", RESULT="OEM 0815", NAME="disk1" |
67922099 | 301 | |
d3db5e5e | 302 | # USB printer to be called lp_color |
16378373 | 303 | BUS="usb", SYSFS{serial}="W09090207101241330", NAME="lp_color" |
d3db5e5e | 304 | |
b86f56ff | 305 | # SCSI disk with a specific vendor and model number will be called boot |
16378373 | 306 | BUS="scsi", SYSFS{vendor}="IBM", SYSFS{model}="ST336", NAME="boot%n" |
aa9c2a1e | 307 | |
d3db5e5e | 308 | # sound card with PCI bus id 00:0b.0 to be called dsp |
4bd46ac7 | 309 | BUS="pci", ID="00:0b.0", NAME="dsp" |
d3db5e5e | 310 | |
311 | # USB mouse at third port of the second hub to be called mouse1 | |
4bd46ac7 | 312 | BUS="usb", PLACE="2.3", NAME="mouse1" |
d3db5e5e | 313 | |
26004fcc | 314 | # ttyUSB1 should always be called pda with two additional symlinks |
4bd46ac7 | 315 | KERNEL="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" |
3370fb21 | 316 | |
26004fcc | 317 | # multiple USB webcams with symlinks to be called webcam0, webcam1, ... |
16378373 | 318 | BUS="usb", SYSFS{model}="XV3", NAME="video%n", SYMLINK="webcam%n" |
0a8dd7f3 DZ |
319 | |
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" | |
326 | ||
d3db5e5e | 327 | .fi |
eb13ff87 | 328 | .P |
5bc597fe | 329 | The permissions and ownership of the created device file are read from |
aef6bb13 KS |
330 | the files located in the |
331 | .I /etc/udev/permissions.d/ | |
332 | directory, or at the location specified by the | |
4865de44 | 333 | .I udev_permission |
c6c13c31 | 334 | value in the |
4865de44 GKH |
335 | .I /etc/udev/udev.conf |
336 | file. | |
eb13ff87 | 337 | .br |
5b8ba50a | 338 | Every line lists a device name followed by owner, group and permission |
07d7cfd1 | 339 | mode. All values are separated by colons. The name field may contain a |
83fa40fc | 340 | pattern to apply the values to a whole class of devices. |
eb13ff87 | 341 | .sp |
c6c13c31 | 342 | .RI "A sample " udev.permissions " might look like this:" |
eb13ff87 KS |
343 | .sp |
344 | .nf | |
345 | #name:user:group:mode | |
5b8ba50a | 346 | input/*:root:root:644 |
d0a4a110 | 347 | ttyUSB1:0:8:0660 |
5b8ba50a | 348 | video*:root:video:0660 |
eb13ff87 KS |
349 | dsp1:::0666 |
350 | .fi | |
07d7cfd1 GKH |
351 | .P |
352 | A number of different fields in the above configuration files support a simple | |
83fa40fc | 353 | form of shell style pattern matching. It supports the following pattern characters: |
07d7cfd1 GKH |
354 | .TP |
355 | .B * | |
356 | Matches zero, one, or more characters. | |
357 | .TP | |
358 | .B ? | |
359 | Matches any single character, but does not match zero characters. | |
360 | .TP | |
361 | .B [ ] | |
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 | |
758f236f MI |
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 | |
5bc597fe | 366 | following the '[' is a '!', any characters not enclosed are matched. |
fc238cff KS |
367 | .P |
368 | After device node creation, removal, or network device renaming, | |
369 | .B udev | |
370 | executes the programs in the directory tree under | |
371 | .IR /etc/dev.d/ . | |
5bc597fe | 372 | The name of a program must have the suffix |
fc238cff | 373 | .I .dev |
5bc597fe | 374 | to be recognized. |
fc238cff KS |
375 | .br |
376 | In addition to the hotplug environment variables, | |
a0294b76 KS |
377 | .B UDEV_LOG |
378 | is set if udev is configured to use the syslog facility. Executed programs may | |
379 | want to follow that setting. | |
fc238cff KS |
380 | .B DEVNAME |
381 | is exported to make the name of the created node, or the name the network | |
a0294b76 | 382 | device is renamed to, available to the executed program. The programs in every |
fc238cff KS |
383 | directory are sorted in lexical order, while the directories are searched in |
384 | the following order: | |
385 | .sp | |
386 | .nf | |
387 | /etc/dev.d/$(DEVNAME)/*.dev | |
388 | /etc/dev.d/$(SUBSYSTEM)/*.dev | |
389 | /etc/dev.d/default/*.dev | |
390 | .fi | |
04db8c9e GKH |
391 | .SH "FILES" |
392 | .nf | |
04db8c9e | 393 | /sbin/udev udev program |
4865de44 | 394 | /etc/udev/* udev config files |
04db8c9e | 395 | /etc/hotplug.d/default/udev.hotplug hotplug symlink to udev program |
fc238cff | 396 | /etc/dev.d/* programs invoked by udev |
04db8c9e GKH |
397 | .fi |
398 | .LP | |
399 | .SH "SEE ALSO" | |
05c0c9da | 400 | .BR udevinfo (8), |
bef370d6 | 401 | .BR udevd (8), |
eb13ff87 | 402 | .BR hotplug (8) |
04db8c9e GKH |
403 | .PP |
404 | The | |
758f236f | 405 | .I http://linux\-hotplug.sourceforge.net/ |
04db8c9e GKH |
406 | web site. |
407 | .SH AUTHORS | |
da86c7f0 KS |
408 | .B udev |
409 | was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from | |
fc1f0d43 GKH |
410 | Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and |
411 | many others. |