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 The following key names can be used to match against device properties:
 108 .TP
 109 .B BUS
 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
 116 .B SUBSYSTEM
 117 Match the kernel subsystem name.
 118 .TP
 119 .B ACTION
 120 Match the kernel action name.
 121 .TP
 122 .B DRIVER
 123 Match the kernel driver name.
 124 .TP
 125 .B ID
 126 Match the device number on the bus, like PCI bus id.
 127 .TP
 128 .BI SYSFS{ filename }
 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.
 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.
 135 .TP
 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
 140 .B PROGRAM
 141 Call external program. This key is valid if the program returns successful.
 142 The environment variables of
 143 .B udev
 144 are also available to the program.
 145 .br
 146 The string returned by the program may be additionally matched with the
 147 .B RESULT
 148 key in the same or any later rule.
 149 .TP
 150 .B RESULT
 151 Match the returned string of the last
 152 .B PROGRAM
 153 call. This key can be used in the same or in any later rule after a
 154 .B PROGRAM
 155 call.
 156 .P
 157 The following keys can get values assigned:
 158 .TP
 159 .B NAME
 160 The name of the node to be created, or the name, the network interface
 161 should be renamed to. Only one rule can set the a name, all later rules
 162 with a NAME key will be ignored.
 163 .TP
 164 .B SYMLINK
 165 The name of a symlink targeting the node. Every matching rule can add
 166 this value to the list of symlinks to be created along with the device node.
 167 Multiple symlinks may be specified by separating the names by the space
 168 character.
 169 .TP
 170 .B OWNER, GROUP, MODE
 171 The permissions for the device node. Every specified value overwrites the
 172 compiled-in default value.
 173 .TP
 174 .B RUN
 175 Add a program to the list of programs to be executed for a specific device.
 176 .TP
 177 .B OPTIONS
 178 .B last_rule
 179 stops further rules application. No later rules will have any effect.
 180 .sp
 181 .B ignore_device
 182 will ignore this device. No node will be created or program executed.
 183 .sp
 184 .B ignore_remove
 185 will ignore any later remove event for this device.
 186 This may be useful as a workaround for broken device drivers.
 187 .sp
 188 .B all_partitions
 189 will create device nodes for all available partitions of a blockdevice.
 190 This may be useful for removable media devices which do not detect a media
 191 change.
 192 .sp
 193 Multiple attributes may be separated by comma.
 194 .P
 195 .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP
 196 fields support simple printf-like string substitutions:
 197 .TP
 198 .B %n
 199 The "kernel number" of the device.
 200 For example, 'sda3' has a "kernel number" of '3'.
 201 .TP
 202 .B %k
 203 The "kernel name" for the device.
 204 .TP
 205 .B %p
 206 The devpath for the device.
 207 .TP
 208 .B %M
 209 The kernel major number for the device.
 210 .TP
 211 .B %m
 212 The kernel minor number for the device.
 213 .TP
 214 .B %b
 215 The bus id for the device.
 216 .TP
 217 .B %c
 218 The string returned by the external program, specified in
 219 .B PROGRAM
 220 (This does not work within the
 221 .B PROGRAM
 222 field for the obvious reason.)
 223 .br
 224 A single part of the string, separated by a space character
 225 may be selected by specifying the part number as an attribute:
 226 .BI %c{ N }
 227 If the number is followed by the + char this part plus
 228 all remaining parts of the result string are substituted:
 229 .BI %c{ N+ }
 230 .TP
 231 .B %N
 232 The name of a created temporary device node to provide access to the
 233 device from a external program.
 234 .TP
 235 .B %P
 236 The node name of the parent device.
 237 .TP
 238 .BI %s{ filename }
 239 The content of a sysfs attribute.
 240 .TP
 241 .B %r
 242 The udev_root value.
 243 .TP
 244 .B %e
 245 If a device node already exists with the name, the smallest positive
 246 decimal integer N is substituted such that the resulting name doesn't
 247 match an existing device node. Otherwise nothing is substituted. This
 248 can be used to create compatibility symlinks and enumerate devices of
 249 the same type originating from different kernel subsystems.
 250 .sp
 251 Note: The use of the enumeration facility is unreliable outside of
 252 udevstart where the node creation is serialized and predictable.
 253 The returned numbers rely on the order devices are probed on the
 254 system. If more than one device requests an enumeration for the same
 255 name at the same time, it may be possible that both requests receive the
 256 same name back from the database. The use of enumerations in todays setups
 257 where device can come and go at any time is not recomended.
 258 .TP
 259 .B %%
 260 The '%' character itself.
 261 .P
 262 The count of characters to insert may be limited by specifying
 263 the format length value. For example, '%3s{file}' will only insert
 264 the first three characters of the sysfs attribute.
 265 .P
 266 .RI "A sample " udev.rules " file might look like this:"
 267 .sp
 268 .nf
 269 # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1
 270 BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1"
 271
 272 # USB printer to be called lp_color
 273 BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color"
 274
 275 # SCSI disk with a specific vendor and model number will be called boot
 276 BUS=="scsi", SYSFS{vendor}=="IBM", SYSFS{model}=="ST336", NAME="boot%n"
 277
 278 # sound card with PCI bus id 00:0b.0 to be called dsp
 279 BUS=="pci", ID=="00:0b.0", NAME="dsp"
 280
 281 # USB mouse at third port of the second hub to be called mouse1
 282 BUS=="usb", ID=="2.3", NAME="mouse1"
 283
 284 # ttyUSB1 should always be called pda with two additional symlinks
 285 KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld"
 286
 287 # multiple USB webcams with symlinks to be called webcam0, webcam1, ...
 288 BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n"
 289 .fi
 290 .P
 291 A number of different fields in the above configuration files support a simple
 292 form of shell style pattern matching. It supports the following pattern characters:
 293 .TP
 294 .B *
 295 Matches zero, one, or more characters.
 296 .TP
 297 .B ?
 298 Matches any single character, but does not match zero characters.
 299 .TP
 300 .B [ ]
 301 Matches any single character specified within the brackets. For example, the
 302 pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also
 303 supported within this match with the '\-' character. For example, to match on
 304 the range of all digits, the pattern [0\-9] would be used. If the first character
 305 following the '[' is a '!', any characters not enclosed are matched.
 306 .P
 307 After device node creation, removal, or network device renaming,
 308 .B udev
 309 executes the programs specified by the
 310 .B RUN
 311 key.
 312 .br
 313 In addition to the kernel provided hotplug environment variables,
 314 .B UDEV_LOG
 315 is set and contains the numerical priority value, if udev is configured to use
 316 .BR syslog (3).
 317 Executed programs may want to follow that setting.
 318 .B DEVNAME
 319 is exported to make the name of the created node, or the name the network
 320 device is renamed to, available to the executed programs.
 321 .SH "ENVIRONMENT"
 322 .P
 323 The following variables are read from the environment:
 324 .TP
 325 .B ACTION
 326 .IR add " or " remove
 327 signifies the addition or the removal of a device.
 328 .TP
 329 .B DEVPATH
 330 The sysfs devpath of the device without the mountpoint but a leading slash.
 331 .TP
 332 .B SUBSYSTEM
 333 The subsystem the device belongs to. Alternatively the subsystem may
 334 be passed as the first argument.
 335 .TP
 336 .B UDEV_CONFIG_FILE
 337 Overrides the default location of the
 338 .B udev
 339 config file.
 340 .TP
 341 .B UDEV_LOG
 342 Overrides the log priority specified in the config file.
 343 .TP
 344 .B UDEV_RUN
 345 If set to "0", it disables the execution of programs added by rules.
 346 .SH "FILES"
 347 .nf
 348 /sbin/udev                           udev program
 349 /etc/udev/*                          udev config files
 350 .fi
 351 .SH "SEE ALSO"
 352 .BR udevinfo (8),
 353 .BR udevd (8),
 354 .BR hotplug (8)
 355 .PP
 356 .B Web resources:
 357 .nf
 358 .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
 359 .I http://linux\-hotplug.sourceforge.net/
 360 .fi
 361 .SH AUTHORS
 362 .B udev
 363 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
 364 Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and
 365 many others.