X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=udev.8;h=c0dc68b80360a2454a882ec319d2c255dde03a87;hp=e46caaf3226d62fde14fb96417230e407b58559d;hb=27c3403dd810e53f6c9b8dffe34af7798a4b52d3;hpb=d0a4a110b719faafb07aa6e7a2bd5a131e8af38f diff --git a/udev.8 b/udev.8 index e46caaf32..c0dc68b80 100644 --- a/udev.8 +++ b/udev.8 @@ -3,11 +3,34 @@ udev \- Linux configurable dynamic device naming support .SH SYNOPSIS .BI udev " hotplug-subsystem" +.P +The environment must provide the following variables: +.TP +.B ACTION +.IR add " or " remove +signifies the connection or disconnection of a device. +.TP +.B DEVPATH +The sysfs devpath of the device without the mountpoint but a leading slash. +.P +Additional optional environment variables are: +.TP +.B UDEV_CONFIG_FILE +Overrides the default location of the +.B udev +config file. +.TP +.B UDEV_NO_SLEEP +The default behavior of +.B udev +is to wait until all the sysfs files of the device chain are populated. If set +.B udev +will will continue, regardless of the state of the device representation. .SH "DESCRIPTION" .B udev creates or removes device node files usually located in the /dev directory. -Its goal is to provide a dynamic device directory that contains only the files -for devices that are actually present. +It provides a dynamic device directory that contains only the files for +devices that are actually present. .P As part of the .B hotplug @@ -18,133 +41,305 @@ On device creation, .B udev reads the sysfs directory of the given device to collect device attributes like label, serial number or bus device number. -These attributes are treated as a key -to determine a unique name for device file creation. +These attributes may used as keys to determine a +unique name for device file creation. .B udev maintains a database for devices present on the system. .br On device removal, .B udev -queries the internal database for the name of the device file to be deleted. +queries its database for the name of the device file to be deleted. .SH "CONFIGURATION" +All +.B udev +configuration files consist of a set of lines of text. All empty +lines, and lines beginning with a '#' will be ignored. +.P + .B udev -expects its configuration at -.I /etc/udev/udev.config. -The file consists of a set of lines. All empty lines and -lines beginning with a '#' will be ignored. +expects its main configuration file at +.IR /etc/udev/udev.conf . +The file consists of a set of variables and values that allow the user to +override default udev values. The current set of variables that can be +overridden in this file is: +.TP +.B udev_root +This is the where in the filesystem to place the device nodes. The default +value for this is +.IR /udev/ . +.TP +.B udev_db +The name and location of the udev database. The default value for this is +.IR /udev/.udev.tdb . +.TP +.B udev_rules +This is the location of the udev rules file. The default value for this is +.IR /etc/udev/udev.rules . +If a directory is specified, the whole directory is +scanned for files ending with +.I .rules +and all rule files are read in lexical order. +.TP +.B udev_permissions +This is the location of the udev permission file. The default value for this is +.IR /etc/udev/udev.permissions . +If a directory is specified, the whole directory is scanned for files ending with +.I .permissions +and all permission files are read in lexical order. +.TP +.B udev_log +If you want udev to log some information to the syslog for every node created or +removed. The default value for this is +.IR yes . +.TP +.B default_mode +This is the default mode for all nodes that have no explicit match in the +permissions file. The default value for this is +.IR 0666 . +.TP +.B default_owner +This is the default owner for all nodes that have no explicit match in the +permissions file. The default value for this is +.IR root . +.TP +.B default_group +This is the default group for all nodes that have no explicit match in the +permissions file. The default value for this is +.IR root . +.br +.P +.RI "A sample " udev.conf " might look like this: +.sp +.nf +# udev_root - where in the filesystem to place the device nodes +udev_root="/udev/" + +# udev_db - The name and location of the udev database. +udev_db="/udev/.udev.tdb" + +# udev_rules - The location of the directory where to look for files + which names ending with .rules +udev_rules="/etc/udev/" + +# udev_permissions - The name and location of the udev permission file +udev_permissions="/etc/udev/udev.permissions" + +# udev_log - set to "yes" if you want logging, else "no" +udev_log="yes" + +# default_mode - set the default mode for all nodes that have no +# explicit match in the permissions file +default_mode="0666" + +# default_owner - set the default owner for all nodes that have no +# explicit match in the permissions file +default_owner="root" + +# default_group - set the default group for all nodes that have no +# explicit match in the permissions file +default_group="root" +.fi +.P +The rules for udev to use when naming devices may specified at +.I /etc/udev/udev.rules +or specified by the +.I udev_rules +value in the +.I /etc/udev/udev.conf +file. +.P +Every line in the rules file defines the mapping between device attributes +and the device file name. One ore more keys are specified to match a rule +with the current device. If all keys are matching, the rule will be applied +and the name is used for the device node. .br -Every line defines the mapping between device attributes and the device file -name. It starts with a keyword defining the method used to match, followed by -one ore more keys to compare and the filename for the device. If no matching -configuration is found, the default kernel device name is used. +If no matching rule is found, the default kernel device name is used. .P -The line format is: -.RS +Every rule consists of a list a comma separated fields: .sp -.I method, key,[key,...] name +.IR "key " ,[ "key " ,...] " name " [, " symlink" ] .sp -.RE -where valid methods with corresponding keys are: +where possible fields are: .TP -.B LABEL -device label or serial number, like USB serial number, SCSI UUID or -file system label -.br -keys: \fBBUS\fP, \fIsysfs_attribute\fP +.B BUS +Match the bus type of the device. +(The sysfs device bus must be able to be determined by a "device" symlink.) .TP -.B NUMBER -device number on the bus, like PCI bus id -.br -keys: \fBBUS\fP, \fBID\fP +.B KERNEL +Match the kernel device name. .TP -.B TOPOLOGY -device position on bus, like physical port of USB device -.br -keys: \fBBUS\fP, \fBPLACE\fP +.B ID +Match the device number on the bus, like PCI bus id. +.TP +.B PLACE +Match the topological position on bus, like physical port of USB device .TP -.B REPLACE -string replacement of the kernel device name +.BI SYSFS{ filename } +Match sysfs device attribute like label, vendor, USB serial number, SCSI UUID +or file system label. Up to 5 different sysfs files can be checked, with +all of the values being required in order to match the rule. +.TP +.B PROGRAM +Call external program. This key is valid if the program returns successful. +The environment variables of +.B udev +are also available for the program. .br -key: \fBKERNEL_NAME\fP +The string returned by the program may additionally matched with the +.B RESULT +key. .TP -.B CALLOUT -calling external program, that returns a string to match +.B RESULT +Match the returned string of the last +.B PROGRAM +call. This key may used in any following rule after a +.B PROGRAM +call. +.TP +.B NAME +The name of the node to be created. If the name field is omitted or its +value is empty, the device will be ignored and no node will be created. .br -keys: \fBBUS\fP, \fBPROGRAM\fP, \fBID\fP +If given with the attribute +.BR NAME{ all_partitions } +it will create all 15 partitions of a blockdevice. +This may be useful for removable media devices. +.TP +.B SYMLINK +The name of a symlink targeting the node. Multiple symlinks may be +specified by separating the names by the space character. .P -The name field supports simple printf-like string subtitution: -.RS +.RB "The " NAME " ," SYMLINK " and " PROGRAM +fields support simple printf-like string substitution: .TP .B %n -the "kernel number" of the device -for example, 'sda3' has a "kernel number" of '3' +The "kernel number" of the device. +For example, 'sda3' has a "kernel number" of '3'. +.TP +.B %k +The "kernel name" for the device. .TP .B %M -the kernel major number for the device +The kernel major number for the device. .TP .B %m -the kernel minor number for the device +The kernel minor number for the device. .TP .B %b -the bus id for the device -.RE +The bus id for the device. +.TP +.B %c +The +.B PROGRAM +returned string. +(This does not work within the +.B PROGRAM +field for the obvious reason.) +.br +A single part of the string, separated by the space character +my be selected by specifying the part number as a attribute: +.BI %c{ part } +.TP +.BI %s{ filename } +The content of a sysfs attribute. +.TP +.B %% +The '%' character itself. +.P +The count of charcters to insert may be limited by specifying +the format length value. For example, '%3s{file}' will only insert +the first three characters of the sysfs attribute. .P -A sample \fIudev.conf\fP might look like this: +.RI "A sample " udev.rules " might look like this:" .sp .nf +# if /sbin/scsi_id returns "OEM 0815" device will be called disk1 +BUS="scsi", PROGRAM="/sbin/scsi_id", RESULT="OEM 0815", NAME="disk1" + # USB printer to be called lp_color -LABEL, BUS="usb", serial="W09090207101241330", NAME="lp_color" +BUS="usb", SYSFS{serial}="W09090207101241330", NAME="lp_color" + +# SCSI disk with a specific vendor and model number is to be called boot +BUS="scsi", SYSFS{vendor}="IBM", SYSFS{model}="ST336", NAME="boot%n" # sound card with PCI bus id 00:0b.0 to be called dsp -NUMBER, BUS="pci", ID="00:0b.0", NAME="dsp" +BUS="pci", ID="00:0b.0", NAME="dsp" # USB mouse at third port of the second hub to be called mouse1 -TOPOLOGY, BUS="usb", PLACE="2.3", NAME="mouse1" +BUS="usb", PLACE="2.3", NAME="mouse1" -# ttyUSB1 should always be called pda -REPLACE, KERNEL="ttyUSB1", NAME="pda" +# ttyUSB1 should always be called pda with two additional symlinks +KERNEL="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" -# if /sbin/scsi_id returns "OEM 0815" device will be called disk1 -CALLOUT, PROGRAM="/sbin/scsi_id" BUS="scsi", ID="OEM 0815" NAME="disk1" - -# USB webcams to be called webcam0, webcam1, ... -LABEL, BUS="usb", model="WebCam Version 3", NAME="webcam%n" +# multiple USB webcams with symlinks to be called webcam0, webcam1, ... +BUS="usb", SYSFS{model}="XV3", NAME="video%n", SYMLINK="webcam%n" .fi .P Permissions and ownership for the created device files may specified at -.I /etc/udev/udev.permissions. -The file consists of a set of lines. All empty lines and -lines beginning with a '#' will be ignored. +.I /etc/udev/udev.permissions +or specified by the +.I udev_permission +value in the +.I /etc/udev/udev.conf +file. .br -Every line lists a device name followed by numeric owner, group and permission -mode. All values are separated by colons. The name field may end with a -wildcard to apply the values to a whole class of devices. +Every line lists a device name followed by owner, group and permission +mode. All values are separated by colons. The name field may contain a +pattern to apply the values to a whole class of devices. .sp -A sample \fIudev.permissions\fP might look like this: +.RI "A sample " udev.permissions " might look like this:" .sp .nf #name:user:group:mode +input/*:root:root:644 ttyUSB1:0:8:0660 -video*:500:500:0660 +video*:root:video:0660 dsp1:::0666 .fi - +.P +The value +.I $local +can be substituted for a specific username. In that case, udev will determine +the current local user at the time of device node creation and substitute +that username as the owner of the new device node. This is useful, for +example, to let hot-plugged devices, such as cameras, be owned by the user at +the current console. Note that if no user is currently logged in, or if udev +otherwise fails to determine a current user, the +.I default_owner +value is used in lieu. +.P +A number of different fields in the above configuration files support a simple +form of shell style pattern matching. It supports the following pattern characters: +.TP +.B * +Matches zero, one, or more characters. +.TP +.B ? +Matches any single character, but does not match zero characters. +.TP +.B [ ] +Matches any single character specified within the brackets. For example, the +pattern string "tty[SR]" would match either "ttyS" or "ttyR". Ranges are also +supported within this match with the '\-' character. For example, to match on +the range of all digits, the pattern [0\-9] would be used. If the first character +following the '[' is a '!' then any character not enclosed is matched. .SH "FILES" .nf -.ft B -.ft /sbin/udev udev program -/etc/udev/* udev config and database files +/etc/udev/* udev config files /etc/hotplug.d/default/udev.hotplug hotplug symlink to udev program .fi .LP .SH "SEE ALSO" +.BR udevinfo (8), +.BR udevd (8), .BR hotplug (8) .PP The -.I http://linux-hotplug.sourceforge.net/ +.I http://linux\-hotplug.sourceforge.net/ web site. .SH AUTHORS .B udev was developed by Greg Kroah-Hartman with much help from -Dan Stekloff and many others. +Dan Stekloff , Kay Sievers , and +many others.