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.
 162 .TP
 163 .B SYMLINK
 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.
 168 .TP
 169 .B OWNER, GROUP, MODE
 170 The permissions for the device node. Every specified value overwrites the
 171 compiled-in default value.
 172 .TP
 173 .B RUN
 174 Add a program to the list of programs to be executed for a specific device.
 175 .TP
 176 .B OPTIONS
 177 .B last_rule
 178 stops further rules application. No later rules will have any effect.
 179 .sp
 180 .B ignore_device
 181 will ignore this device. No node will be created or program executed.
 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.
 193 .P
 194 .RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP
 195 fields support simple printf-like string substitutions:
 196 .TP
 197 .B %n
 198 The "kernel number" of the device.
 199 For example, 'sda3' has a "kernel number" of '3'.
 200 .TP
 201 .B %k
 202 The "kernel name" for the device.
 203 .TP
 204 .B %p
 205 The devpath for the device.
 206 .TP
 207 .B %M
 208 The kernel major number for the device.
 209 .TP
 210 .B %m
 211 The kernel minor number for the device.
 212 .TP
 213 .B %b
 214 The bus id for the device.
 215 .TP
 216 .B %c
 217 The string returned by the external program, specified in
 218 .B PROGRAM
 219 (This does not work within the
 220 .B PROGRAM
 221 field for the obvious reason.)
 222 .br
 223 A single part of the string, separated by a space character
 224 may be selected by specifying the part number as an attribute:
 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+ }
 229 .TP
 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
 234 .B %P
 235 The node name of the parent device.
 236 .TP
 237 .BI %s{ filename }
 238 The content of a sysfs attribute.
 239 .TP
 240 .B %r
 241 The udev_root value.
 242 .TP
 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.
 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.
 257 .TP
 258 .B %%
 259 The '%' character itself.
 260 .P
 261 The count of characters to insert may be limited by specifying
 262 the format length value. For example, '%3s{file}' will only insert
 263 the first three characters of the sysfs attribute.
 264 .P
 265 .RI "A sample " udev.rules " file might look like this:"
 266 .sp
 267 .nf
 268 # if /sbin/scsi_id returns "OEM 0815", the device will be called disk1
 269 BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1"
 270
 271 # USB printer to be called lp_color
 272 BUS=="usb", SYSFS{serial}=="W09090207101241330", NAME="lp_color"
 273
 274 # SCSI disk with a specific vendor and model number will be called boot
 275 BUS=="scsi", SYSFS{vendor}=="IBM", SYSFS{model}=="ST336", NAME="boot%n"
 276
 277 # sound card with PCI bus id 00:0b.0 to be called dsp
 278 BUS=="pci", ID=="00:0b.0", NAME="dsp"
 279
 280 # USB mouse at third port of the second hub to be called mouse1
 281 BUS=="usb", ID=="2.3", NAME="mouse1"
 282
 283 # ttyUSB1 should always be called pda with two additional symlinks
 284 KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld"
 285
 286 # multiple USB webcams with symlinks to be called webcam0, webcam1, ...
 287 BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n"
 288 .fi
 289 .P
 290 A number of different fields in the above configuration files support a simple
 291 form of shell style pattern matching. It supports the following pattern characters:
 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
 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
 303 the range of all digits, the pattern [0\-9] would be used. If the first character
 304 following the '[' is a '!', any characters not enclosed are matched.
 305 .P
 306 After device node creation, removal, or network device renaming,
 307 .B udev
 308 executes the programs located in the directory tree under
 309 .IR /etc/dev.d/ .
 310 The name of a program must have the suffix
 311 .I .dev
 312 to be recognized.
 313 .br
 314 In addition to the kernel provided hotplug environment variables,
 315 .B UDEV_LOG
 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.
 319 .B DEVNAME
 320 is exported to make the name of the created node, or the name the network
 321 device is renamed to, available to the executed program. The programs in every
 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
 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
 350 .B UDEV_LOG
 351 Overrides the log priority specified in the config file.
 352 .TP
 353 .B UDEV_RUN
 354 If set to "0", it disables the execution of programs added by rules.
 355 .TP
 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.
 364 .SH "FILES"
 365 .nf
 366 /sbin/udev                           udev program
 367 /etc/udev/*                          udev config files
 368 /etc/dev.d/*                         programs invoked by udev
 369 .fi
 370 .SH "SEE ALSO"
 371 .BR udevinfo (8),
 372 .BR udevd (8),
 373 .BR hotplug (8)
 374 .PP
 375 .B Web resources:
 376 .nf
 377 .I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
 378 .I http://linux\-hotplug.sourceforge.net/
 379 .fi
 380 .SH AUTHORS
 381 .B udev
 382 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
 383 Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and
 384 many others.