udev.8

   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 " hotplug-subsystem"
   6 .SH "DESCRIPTION"
   7 .B udev
   8 creates or removes device node files usually located in the /dev directory.
   9 Its goal is to provide a dynamic device directory that contains only the files
  10 for devices that are actually present.
  11 .P
  12 As part of the
  13 .B hotplug
  14 subsystem,
  15 .B udev
  16 is executed if a kernel device is added or removed from the system.
  17 On device creation,
  18 .B udev
  19 reads the sysfs directory of the given device to collect device attributes
  20 like label, serial number or bus device number.
  21 These attributes are treated as a key
  22 to determine a unique name for device file creation.
  23 .B udev
  24 maintains a database for devices present on the system.
  25 .br
  26 On device removal,
  27 .B udev
  28 queries the internal database for the name of the device file to be deleted.
  29 .SH "CONFIGURATION"
  30 All udev configuration files consist of a set of lines of text.  All empty
  31 lines, and lines beginning with a '#' will be ignored.
  32 .P
  33
  34 .B udev
  35 expects its main configuration file at
  36 .I /etc/udev/udev.conf.
  37 The file consists of a set of variables and values that allow the user to
  38 override default udev values.  The current set of variables that can be
  39 overridden in this file is:
  40 .TP
  41 .B udev_root
  42 This is the where in the filesystem to place the device nodes.  The default
  43 value for this is
  44 .I /udev/
  45 .TP
  46 .B udev_db
  47 The name and location of the udev database.  The default value for this is
  48 .I /udev/.udev.tdb
  49 .TP
  50 .B udev_rules
  51 This is the location of the udev rules file.  The default value for this is
  52 .I /etc/udev/udev.rules
  53 .TP
  54 .B udev_permissions
  55 This is the location of the udev permission file.  The default value for this is
  56 .I /etc/udev/udev.permissions
  57 .TP
  58 .B default_mode
  59 This is the default mode for all nodes that have no explicit match in the
  60 permissions file.  The default value for this is
  61 .I 0666
  62 .br
  63 .P
  64 A sample \fIudev.conf\fP might look like this:
  65 .sp
  66 .nf
  67 # udev_root - where in the filesystem to place the device nodes
  68 udev_root="/udev/"
  69
  70 # udev_db - The name and location of the udev database.
  71 udev_db="/udev/.udev.tdb"
  72
  73 # udev_rules - The name and location of the udev rules file
  74 udev_rules="/etc/udev/udev.rules"
  75
  76 # udev_permissions - The name and location of the udev permission file
  77 udev_permissions="/etc/udev/udev.permissions"
  78
  79 # default_mode - set the default mode for all nodes that have no
  80 #                explicit match in the permissions file
  81 default_mode="0666"
  82 .fi
  83 .P
  84 The rules for udev to use when naming devices may specified at
  85 .I /etc/udev/udev.rules
  86 or specified by the
  87 .I udev_rules
  88 value in the
  89 .I /etc/udev/udev.conf
  90 file.
  91 .P
  92 Every line in the rules file define the mapping between device attributes and
  93 the device file name. It starts with a keyword defining the method used to
  94 match, followed by one ore more keys to compare and the filename for the
  95 device. If no matching configuration is found, the default kernel device name
  96 is used.
  97 .P
  98 The line format is:
  99 .RS
 100 .sp
 101 .I method, key,[key,...] name
 102 .sp
 103 .RE
 104 where valid methods with corresponding keys are:
 105 .TP
 106 .B CALLOUT
 107 calling external program, that returns a string to match
 108 .br
 109 keys: \fBBUS\fP, \fBPROGRAM\fP, \fBID\fP
 110 .TP
 111 .B LABEL
 112 device label or serial number, like USB serial number, SCSI UUID or
 113 file system label
 114 .br
 115 keys: \fBBUS\fP, \fIsysfs_attribute\fP
 116 .TP
 117 .B NUMBER
 118 device number on the bus, like PCI bus id
 119 .br
 120 keys: \fBBUS\fP, \fBID\fP
 121 .TP
 122 .B TOPOLOGY
 123 device position on bus, like physical port of USB device
 124 .br
 125 keys: \fBBUS\fP, \fBPLACE\fP
 126 .TP
 127 .B REPLACE
 128 string replacement of the kernel device name
 129 .br
 130 key: \fBKERNEL_NAME\fP
 131 .P
 132 The methods are applied in the following order:
 133 .B CALLOUT
 134 ,
 135 .B LABEL
 136 ,
 137 .B NUMBER
 138 ,
 139 .B TOPOLOGY
 140 ,
 141 .B REPLACE
 142 .P
 143 The
 144 .B NAME
 145 and
 146 .B PROGRAM
 147 fields support simple printf-like string subtitution:
 148 .RS
 149 .TP
 150 .B %n
 151 the "kernel number" of the device
 152 for example, 'sda3' has a "kernel number" of '3'
 153 .TP
 154 .B %M
 155 the kernel major number for the device
 156 .TP
 157 .B %m
 158 the kernel minor number for the device
 159 .TP
 160 .B %b
 161 the bus id for the device
 162 .TP
 163 .B %c
 164 the CALLOUT program returned string
 165 (this does not work within the PROGRAM field for the obvious reason.)
 166 .TP
 167 .B %D
 168 Use the devfs style disk name for this device.
 169 For partitions, this will result in 'part%n'
 170 If this is not a partition, it will result in 'disk'
 171 .RE
 172 .P
 173 A sample \fIudev.rules\fP might look like this:
 174 .sp
 175 .nf
 176 # if /sbin/scsi_id returns "OEM 0815" device will be called disk1
 177 CALLOUT, BUS="scsi", PROGRAM="/sbin/scsi_id", ID="OEM 0815", NAME="disk1"
 178
 179 # USB printer to be called lp_color
 180 LABEL, BUS="usb", serial="W09090207101241330", NAME="lp_color"
 181
 182 # sound card with PCI bus id 00:0b.0 to be called dsp
 183 NUMBER, BUS="pci", ID="00:0b.0", NAME="dsp"
 184
 185 # USB mouse at third port of the second hub to be called mouse1
 186 TOPOLOGY, BUS="usb", PLACE="2.3", NAME="mouse1"
 187
 188 # ttyUSB1 should always be called pda
 189 REPLACE, KERNEL="ttyUSB1", NAME="pda"
 190
 191 # USB webcams to be called webcam0, webcam1, ...
 192 LABEL, BUS="usb", model="WebCam Version 3", NAME="webcam%n"
 193 .fi
 194 .P
 195 Permissions and ownership for the created device files may specified at
 196 .I /etc/udev/udev.permissions
 197 or specified by the
 198 .I udev_permission
 199 value in the
 200 .I /etc/udev/udev.conf
 201 file.
 202 The file consists of a set of lines. All empty lines and
 203 lines beginning with a '#' will be ignored.
 204 .br
 205 Every line lists a device name followed by owner, group and permission
 206 mode. All values are separated by colons. The name field may end with a
 207 wildcard to apply the values to a whole class of devices.
 208 .br
 209 If
 210 .B udev
 211 was built using klibc or is used before the user database is accessible (e.g.
 212 .B initrd
 213 ), only numeric owner and group values may be used.
 214 .sp
 215 A sample \fIudev.permissions\fP might look like this:
 216 .sp
 217 .nf
 218 #name:user:group:mode
 219 input/*:root:root:644
 220 ttyUSB1:0:8:0660
 221 video*:root:video:0660
 222 dsp1:::0666
 223 .fi
 224 .SH "FILES"
 225 .nf
 226 .ft B
 227 .ft
 228 /sbin/udev                           udev program
 229 /etc/udev/*                          udev config files
 230 /etc/hotplug.d/default/udev.hotplug  hotplug symlink to udev program
 231 .fi
 232 .LP
 233 .SH "SEE ALSO"
 234 .BR hotplug (8)
 235 .PP
 236 The
 237 .I http://linux-hotplug.sourceforge.net/
 238 web site.
 239 .SH AUTHORS
 240 .B udev
 241 was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
 242 Dan Stekloff <dsteklof@us.ibm.com> and many others.