]>
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" |
4070d2fe KS |
6 | .br |
7 | .B udev | |
8 | .RI "[-q " sysfs_path "] [-rVh]" | |
04db8c9e GKH |
9 | .SH "DESCRIPTION" |
10 | .B udev | |
d3db5e5e | 11 | creates or removes device node files usually located in the /dev directory. |
eb13ff87 KS |
12 | Its goal is to provide a dynamic device directory that contains only the files |
13 | for devices that are actually present. | |
14 | .P | |
d3db5e5e | 15 | As part of the |
16 | .B hotplug | |
17 | subsystem, | |
18 | .B udev | |
eb13ff87 | 19 | is executed if a kernel device is added or removed from the system. |
d3db5e5e | 20 | On device creation, |
21 | .B udev | |
eb13ff87 | 22 | reads the sysfs directory of the given device to collect device attributes |
d3db5e5e | 23 | like label, serial number or bus device number. |
d94df232 | 24 | These attributes are treated as a key |
d4112087 | 25 | to determine a unique name for device file creation. |
da86c7f0 KS |
26 | .B udev |
27 | maintains a database for devices present on the system. | |
eb13ff87 | 28 | .br |
d3db5e5e | 29 | On device removal, |
30 | .B udev | |
d4112087 | 31 | queries the internal database for the name of the device file to be deleted. |
4070d2fe KS |
32 | .SH "OPTIONS" |
33 | .B udev | |
34 | normally is called by | |
35 | .B hotplug | |
36 | with the subsystem as argument and various environment variables set. | |
37 | .br | |
38 | It may also called with the following options: | |
39 | .TP | |
40 | .B -V | |
41 | Print the version information. | |
42 | .TP | |
43 | .B -r | |
44 | Print the the | |
45 | .B udev | |
46 | root directory. | |
47 | .TP | |
48 | .BI -q " sysfs_path" | |
49 | Query with the sysfs path as argument for the name of the created device node. | |
50 | .TP | |
51 | .B -h | |
52 | Print help text. | |
eb13ff87 | 53 | .SH "CONFIGURATION" |
83fa40fc KS |
54 | All |
55 | .B udev | |
56 | configuration files consist of a set of lines of text. All empty | |
4865de44 GKH |
57 | lines, and lines beginning with a '#' will be ignored. |
58 | .P | |
59 | ||
da86c7f0 | 60 | .B udev |
4865de44 GKH |
61 | expects its main configuration file at |
62 | .I /etc/udev/udev.conf. | |
63 | The file consists of a set of variables and values that allow the user to | |
64 | override default udev values. The current set of variables that can be | |
65 | overridden in this file is: | |
66 | .TP | |
67 | .B udev_root | |
68 | This is the where in the filesystem to place the device nodes. The default | |
69 | value for this is | |
70 | .I /udev/ | |
71 | .TP | |
72 | .B udev_db | |
73 | The name and location of the udev database. The default value for this is | |
74 | .I /udev/.udev.tdb | |
75 | .TP | |
76 | .B udev_rules | |
77 | This is the location of the udev rules file. The default value for this is | |
78 | .I /etc/udev/udev.rules | |
79 | .TP | |
80 | .B udev_permissions | |
81 | This is the location of the udev permission file. The default value for this is | |
82 | .I /etc/udev/udev.permissions | |
83 | .TP | |
84 | .B default_mode | |
85 | This is the default mode for all nodes that have no explicit match in the | |
86 | permissions file. The default value for this is | |
87 | .I 0666 | |
d3db5e5e | 88 | .br |
4865de44 | 89 | .P |
c6c13c31 | 90 | .RI "A sample " udev.conf " might look like this: |
4865de44 GKH |
91 | .sp |
92 | .nf | |
93 | # udev_root - where in the filesystem to place the device nodes | |
94 | udev_root="/udev/" | |
95 | ||
96 | # udev_db - The name and location of the udev database. | |
97 | udev_db="/udev/.udev.tdb" | |
98 | ||
99 | # udev_rules - The name and location of the udev rules file | |
100 | udev_rules="/etc/udev/udev.rules" | |
101 | ||
102 | # udev_permissions - The name and location of the udev permission file | |
103 | udev_permissions="/etc/udev/udev.permissions" | |
104 | ||
e15b5ed5 | 105 | # default_mode - set the default mode for all nodes that have no |
4865de44 GKH |
106 | # explicit match in the permissions file |
107 | default_mode="0666" | |
108 | .fi | |
109 | .P | |
110 | The rules for udev to use when naming devices may specified at | |
111 | .I /etc/udev/udev.rules | |
c6c13c31 | 112 | or specified by the |
4865de44 | 113 | .I udev_rules |
d94df232 | 114 | value in the |
4865de44 GKH |
115 | .I /etc/udev/udev.conf |
116 | file. | |
117 | .P | |
118 | Every line in the rules file define the mapping between device attributes and | |
119 | the device file name. It starts with a keyword defining the method used to | |
120 | match, followed by one ore more keys to compare and the filename for the | |
26004fcc | 121 | device. One ore more optional symlinks targeting the node may be specified. |
c6c13c31 KS |
122 | .br |
123 | If no matching configuration is found, the default kernel device name | |
4865de44 | 124 | is used. |
3370fb21 | 125 | .P |
eb13ff87 | 126 | The line format is: |
eb13ff87 | 127 | .sp |
c6c13c31 | 128 | .I method, key,[key,...] name [, symlink] |
eb13ff87 | 129 | .sp |
eb13ff87 | 130 | where valid methods with corresponding keys are: |
d3db5e5e | 131 | .TP |
67922099 | 132 | .B CALLOUT |
e15b5ed5 KS |
133 | calling external program, that returns a string to match. The |
134 | .B BUS | |
a38401d3 | 135 | key is optional, but if specified, the sysfs device bus must be able to be |
e15b5ed5 | 136 | determined by a "device" symlink. |
67922099 | 137 | .br |
c6c13c31 | 138 | .RB "keys: " BUS ", " PROGRAM ", " ID |
67922099 | 139 | .TP |
d3db5e5e | 140 | .B LABEL |
141 | device label or serial number, like USB serial number, SCSI UUID or | |
aa9c2a1e | 142 | file system label. Up to 5 different sysfs files can be checked, with |
e15b5ed5 KS |
143 | all of the values being required in order to match the rule. The |
144 | .B BUS | |
2b8b6441 GKH |
145 | key is optional, but if specified, the sysfs device bus must be able to be |
146 | detemined by a "device" symlink. | |
3370fb21 | 147 | .br |
d94df232 | 148 | .RB "keys: " BUS ", " SYSFS_ |
d3db5e5e | 149 | .TP |
150 | .B NUMBER | |
151 | device number on the bus, like PCI bus id | |
3370fb21 | 152 | .br |
c6c13c31 | 153 | .RB "keys: " BUS ", " ID |
d3db5e5e | 154 | .TP |
155 | .B TOPOLOGY | |
156 | device position on bus, like physical port of USB device | |
3370fb21 | 157 | .br |
c6c13c31 | 158 | .RB "keys: " BUS ", " PLACE |
d3db5e5e | 159 | .TP |
160 | .B REPLACE | |
161 | string replacement of the kernel device name | |
3370fb21 | 162 | .br |
d94df232 | 163 | .RB "key: " KERNEL |
f1db055a | 164 | .TP |
165 | .B IGNORE | |
166 | tell udev to not care about creation of this device, e.g. because the | |
167 | device is already handled by another program | |
168 | .br | |
169 | .RB "key: " KERNEL | |
67922099 GKH |
170 | .P |
171 | The methods are applied in the following order: | |
f1db055a | 172 | .BR IGNORE ", " CALLOUT ", " LABEL ", " NUMBER ", " TOPOLOGY ", " REPLACE "." |
eb13ff87 | 173 | .P |
c6c13c31 | 174 | .RB "The " NAME " ," SYMLINK " and " PROGRAM |
83fa40fc | 175 | fields support simple printf-like string substitution: |
4b710f03 KS |
176 | .TP |
177 | .B %n | |
c6c13c31 | 178 | The "kernel number" of the device. |
4b710f03 KS |
179 | for example, 'sda3' has a "kernel number" of '3' |
180 | .TP | |
170ae44e GKH |
181 | .B %k |
182 | The "kernel name" for the device. | |
183 | .TP | |
4b710f03 | 184 | .B %M |
c6c13c31 | 185 | The kernel major number for the device. |
4b710f03 KS |
186 | .TP |
187 | .B %m | |
c6c13c31 | 188 | The kernel minor number for the device. |
4b710f03 KS |
189 | .TP |
190 | .B %b | |
c6c13c31 | 191 | The bus id for the device. |
67922099 GKH |
192 | .TP |
193 | .B %c | |
c6c13c31 KS |
194 | The CALLOUT program returned string. |
195 | (This does not work within the PROGRAM field for the obvious reason.) | |
36043f84 GKH |
196 | .TP |
197 | .B %D | |
198 | Use the devfs style disk name for this device. | |
199 | For partitions, this will result in 'part%n' | |
525d07e7 | 200 | If this is not a partition, it will result in 'disc'. |
4b710f03 | 201 | .P |
c6c13c31 | 202 | .RI "A sample " udev.rules " might look like this:" |
eb13ff87 | 203 | .sp |
d3db5e5e | 204 | .nf |
67922099 GKH |
205 | # if /sbin/scsi_id returns "OEM 0815" device will be called disk1 |
206 | CALLOUT, BUS="scsi", PROGRAM="/sbin/scsi_id", ID="OEM 0815", NAME="disk1" | |
207 | ||
d3db5e5e | 208 | # USB printer to be called lp_color |
d94df232 | 209 | LABEL, BUS="usb", SYSFS_serial="W09090207101241330", NAME="lp_color" |
d3db5e5e | 210 | |
aa9c2a1e GKH |
211 | # SCSI disk with a specific vendor and model number is to be called boot |
212 | LABEL, BUS="scsi", SYSFS_vendor="IBM", SYSFS_model="ST336", NAME="boot%n" | |
213 | ||
d3db5e5e | 214 | # sound card with PCI bus id 00:0b.0 to be called dsp |
3370fb21 | 215 | NUMBER, BUS="pci", ID="00:0b.0", NAME="dsp" |
d3db5e5e | 216 | |
217 | # USB mouse at third port of the second hub to be called mouse1 | |
3370fb21 | 218 | TOPOLOGY, BUS="usb", PLACE="2.3", NAME="mouse1" |
d3db5e5e | 219 | |
26004fcc KS |
220 | # ttyUSB1 should always be called pda with two additional symlinks |
221 | REPLACE, KERNEL="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" | |
3370fb21 | 222 | |
26004fcc | 223 | # multiple USB webcams with symlinks to be called webcam0, webcam1, ... |
4868e8fb | 224 | LABEL, BUS="usb", SYSFS_model="XV3", NAME="video%n", SYMLINK="webcam%n" |
d3db5e5e | 225 | .fi |
eb13ff87 KS |
226 | .P |
227 | Permissions and ownership for the created device files may specified at | |
4865de44 | 228 | .I /etc/udev/udev.permissions |
c6c13c31 | 229 | or specified by the |
4865de44 | 230 | .I udev_permission |
c6c13c31 | 231 | value in the |
4865de44 GKH |
232 | .I /etc/udev/udev.conf |
233 | file. | |
eb13ff87 | 234 | .br |
5b8ba50a | 235 | Every line lists a device name followed by owner, group and permission |
07d7cfd1 | 236 | mode. All values are separated by colons. The name field may contain a |
83fa40fc | 237 | pattern to apply the values to a whole class of devices. |
67922099 | 238 | .br |
5b8ba50a KS |
239 | If |
240 | .B udev | |
241 | was built using klibc or is used before the user database is accessible (e.g. | |
c6c13c31 | 242 | .BR initrd "(4)), only numeric owner and group values may be used." |
eb13ff87 | 243 | .sp |
c6c13c31 | 244 | .RI "A sample " udev.permissions " might look like this:" |
eb13ff87 KS |
245 | .sp |
246 | .nf | |
247 | #name:user:group:mode | |
5b8ba50a | 248 | input/*:root:root:644 |
d0a4a110 | 249 | ttyUSB1:0:8:0660 |
5b8ba50a | 250 | video*:root:video:0660 |
eb13ff87 KS |
251 | dsp1:::0666 |
252 | .fi | |
07d7cfd1 GKH |
253 | .P |
254 | A number of different fields in the above configuration files support a simple | |
83fa40fc | 255 | form of shell style pattern matching. It supports the following pattern characters: |
07d7cfd1 GKH |
256 | .TP |
257 | .B * | |
258 | Matches zero, one, or more characters. | |
259 | .TP | |
260 | .B ? | |
261 | Matches any single character, but does not match zero characters. | |
262 | .TP | |
263 | .B [ ] | |
264 | Matches any single character specified within the brackets. For example, the | |
265 | pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also | |
266 | supported within this match with the '-' character. For example, to match on | |
83fa40fc KS |
267 | the range of all digits, the pattern [0-9] would be used. If the first character |
268 | following the '[' is a '!' then any character not enclosed is matched. | |
04db8c9e GKH |
269 | .SH "FILES" |
270 | .nf | |
04db8c9e | 271 | /sbin/udev udev program |
4865de44 | 272 | /etc/udev/* udev config files |
04db8c9e GKH |
273 | /etc/hotplug.d/default/udev.hotplug hotplug symlink to udev program |
274 | .fi | |
275 | .LP | |
276 | .SH "SEE ALSO" | |
eb13ff87 | 277 | .BR hotplug (8) |
04db8c9e GKH |
278 | .PP |
279 | The | |
280 | .I http://linux-hotplug.sourceforge.net/ | |
281 | web site. | |
282 | .SH AUTHORS | |
da86c7f0 KS |
283 | .B udev |
284 | was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from | |
fc1f0d43 GKH |
285 | Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and |
286 | many others. |