X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=udev.8;h=9dae378086ce906d8bdf9c54c525e05449ae8000;hb=420a506ef00b011ddb50249c0c53c07cbc37e04c;hp=84b08488fe48eaa62511404597c44d3fa7bec146;hpb=bef370d6ebd6707cc2ef183c2dc83f4a62d8111b;p=elogind.git diff --git a/udev.8 b/udev.8 index 84b08488f..9dae37808 100644 --- a/udev.8 +++ b/udev.8 @@ -2,165 +2,139 @@ .SH NAME 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. +.BI udev .SH "DESCRIPTION" .B udev -creates or removes device node files usually located in the /dev directory. -It provides a dynamic device directory that contains only the files for -devices that are actually present. +provides a dynamic device directory containing only the files for actually +present devices. It creates or removes device node files usually located in +the /dev directory, or it renames network interfaces. +.br .P As part of the .B hotplug subsystem, .B udev is executed if a kernel device is added or removed from the system. -On device creation, +A list of rules is used to match against specific device attributes. +.br +On device addition, .B udev -reads the sysfs directory of the given device to collect device attributes -like label, serial number or bus device number. -These attributes may used as keys to determine a -unique name for device file creation. +matches its configured rules against the available device attributes to +uniquely name the device. .B udev -maintains a database for devices present on the system. +maintains its own database for devices present on the system. This database +can be queried for the relationship of the kernel device path and the +name of the device file. .br On device removal, .B udev queries its database for the name of the device file to be deleted. +.br +After the device node handling, a list of collected programs specific to this +device is executed. .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. +configuration files consist of a set of lines of text. All empty +lines or lines beginning with '#' will be ignored. .P - .B udev 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: +The file consists of a set of variables and values allowing the user to +override default udev values. The following variables can be overridden +in this file: .TP .B udev_root -This is the where in the filesystem to place the device nodes. The default -value for this is -.IR /udev/ . +Indicates where to place the device nodes in the filesystem. The default +value is +.IR @udevdir@/ . .TP .B udev_db -The name and location of the udev database. The default value for this is -.IR /udev/.udev.tdb . +The name and location of the udev database. The default value is +.IR @udevdir@/.udevdb . .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. +The name of the udev rules file or directory to look for files with the suffix +.IR .rules . +All rule files are read in lexical order. The default value is +.IR /etc/udev/rules.d/ . .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 +The logging priority which can be set to +.IR "err " , "info " +or the corresponding numerical +.BR syslog (3) +value. +The default value is +.IR err . .P -.RI "A sample " udev.conf " might look like this: +.RI "A sample " udev.conf " file 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/" +# Where in the filesystem to place the device nodes +udev_root="@udevdir@" -# udev_permissions - The name and location of the udev permission file -udev_permissions="/etc/udev/udev.permissions" +# The name and location of the udev database. +udev_db="@udevdir@/.udevdb" -# udev_log - set to "yes" if you want logging, else "no" -udev_log="yes" +# The name and location of the udev rules file(s). +udev_rules="@configdir@/rules.d" -# 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" +# The syslog(3) priority: "err", "info", or the numerical value. +udev_log="err" .fi .P -The rules for udev to use when naming devices may specified at -.I /etc/udev/udev.rules -or specified by the +The rules for device naming are read from the files located in the +.I /etc/udev/rules.d/ +directory, or at the location specified by the .I udev_rules value in the .I /etc/udev/udev.conf file. -.P +.br 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. One or more optional symlinks -targeting the node may be specified. +and the device name. One or 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 to name the device file or the network interface. .br If no matching rule is found, the default kernel device name is used. .P -The line format is: +Every rule consists of a list of comma separated key value fields: .sp -.I key,[key,...] name [, symlink] +.IR "key " ,[ "key " ,...] +.P +Each key has the following format: .sp -where keys are: +.IR "name op value" +.P +There are distinct key operation types, depending on the type of the key, it +does a comparison or an assignment. +.P +Comparison operators are: +.TP +.B == +Compare for equality. +.TP +.B != +Compare for non-equality. +.P +Assignment operators are: +.TP +.B += +Add the value to a key that holds a list of entries. +.TP +.B := +Assign a value to a key finally; disallow any later changes, which +is useful to prevent changes by any later rules. +.TP +.B = +Asign a value to a key. Keys that represent a list, are reset and only this +single value is assigned. While this operator still works inplicitely as +comparison on keys that can't get a value assigned, its usage as an comparison +operator is deprecated. +.P +The following key names can be used to match against device properties: .TP .B BUS Match the bus type of the device. @@ -169,52 +143,98 @@ Match the bus type of the device. .B KERNEL Match the kernel device name. .TP +.B SUBSYSTEM +Match the kernel subsystem name. +.TP +.B ACTION +Match the kernel action name. +.TP +.B DRIVER +Match the kernel driver name. +.TP .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 .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. +Match sysfs device attribute like vendor and product id's, USB serial number +or the SCSI disk model number. Up to 5 different sysfs files can be checked, +with all of the values being required to match the rule. +.br +Trailing whitespace characters in the sysfs attribute value are ignored, if +the key doesn't have any trailing whitespace characters by itself. +.TP +.BI ENV{ variable } +Match an environment variable. Up to 5 different environment variables can be +checked, with all of the values being required to match the rule. .TP .B PROGRAM Call external program. This key is valid if the program returns successful. -A few command line options may specified, but shell characters like pipe, -diversion or similiar options are not available. The environment variables of +The environment variables of .B udev -are also available for the program. +are also available to the program. .br -The string returned by the program may additionally matched with the +The string returned by the program may be additionally matched with the .B RESULT -key. +key in the same or any later rule. .TP .B RESULT Match the returned string of the last .B PROGRAM -call. This key may used in any following rule after a +call. This key can be used in the same or in any later rule after a .B PROGRAM call. .P -The +The following keys can get values assigned: +.TP .B NAME -field given with the attribute -.BR NAME{ all_partitions } -will create all 15 partitions of a blockdevice. -This may be useful for removable media devices. +The name of the node to be created, or the name, the network interface +should be renamed to. Only one rule can set the a name, all later rules +with a NAME key will be ignored. +.TP +.B SYMLINK +The name of a symlink targeting the node. Every matching rule can add +this value to the list of symlinks to be created along with the device node. +Multiple symlinks may be specified by separating the names by the space +character. +.TP +.B OWNER, GROUP, MODE +The permissions for the device node. Every specified value overwrites the +compiled-in default value. +.TP +.B RUN +Add a program to the list of programs to be executed for a specific device. +.TP +.B OPTIONS +.B last_rule +stops further rules application. No later rules will have any effect. +.sp +.B ignore_device +will ignore this device. No node will be created or program executed. +.sp +.B ignore_remove +will ignore any later remove event for this device. +This may be useful as a workaround for broken device drivers. +.sp +.B all_partitions +will create device nodes for all available partitions of a blockdevice. +This may be useful for removable media devices which do not detect a media +change. +.sp +Multiple attributes may be separated by comma. .P -.RB "The " NAME " ," SYMLINK " and " PROGRAM -fields support simple printf-like string substitution: +.RB "The " NAME ", " SYMLINK ", " PROGRAM ", " OWNER " and " GROUP +fields support simple printf-like string substitutions: .TP .B %n The "kernel number" of the device. -for example, 'sda3' has a "kernel number" of '3' +For example, 'sda3' has a "kernel number" of '3'. .TP .B %k The "kernel name" for the device. .TP +.B %p +The devpath for the device. +.TP .B %M The kernel major number for the device. .TP @@ -225,68 +245,77 @@ The kernel minor number for the device. The bus id for the device. .TP .B %c -The +The string returned by the external program, specified in .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 } +A single part of the string, separated by a space character +may be selected by specifying the part number as an attribute: +.BI %c{ N } +If the number is followed by the + char this part plus +all remaining parts of the result string are substituted: +.BI %c{ N+ } +.TP +.B %N +The name of a created temporary device node to provide access to the +device from a external program. +.TP +.B %P +The node name of the parent device. .TP .BI %s{ filename } The content of a sysfs attribute. .TP +.B %r +The udev_root value. +.TP +.B %e +If a device node already exists with the name, the smallest positive +decimal integer N is substituted such that the resulting name doesn't +match an existing device node. Otherwise nothing is substituted. This +can be used to create compatibility symlinks and enumerate devices of +the same type originating from different kernel subsystems. +.sp +Note: The use of the enumeration facility is unreliable outside of +udevstart where the node creation is serialized and predictable. +The returned numbers rely on the order devices are probed on the +system. If more than one device requests an enumeration for the same +name at the same time, it may be possible that both requests receive the +same name back from the database. The use of enumerations in todays setups +where device can come and go at any time is not recomended. +.TP .B %% -The '%' char itself. +The '%' character itself. +.P +The count of characters 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 -.RI "A sample " udev.rules " might look like this:" +.RI "A sample " udev.rules " file 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" +# if /sbin/scsi_id returns "OEM 0815", the device will be called disk1 +BUS=="scsi", PROGRAM=="/sbin/scsi_id", RESULT=="OEM 0815", NAME="disk1" # USB printer to be called lp_color -BUS="usb", SYSFS{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" +# SCSI disk with a specific vendor and model number will 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 -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 -BUS="usb", PLACE="2.3", NAME="mouse1" +BUS=="usb", ID=="2.3", NAME="mouse1" # ttyUSB1 should always be called pda with two additional symlinks -KERNEL="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" +KERNEL=="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" # 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 -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 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 -.RI "A sample " udev.permissions " might look like this:" -.sp -.nf -#name:user:group:mode -input/*:root:root:644 -ttyUSB1:0:8:0660 -video*:root:video:0660 -dsp1:::0666 +BUS=="usb", SYSFS{model}=="XV3", NAME=="video%n", SYMLINK="webcam%n" .fi .P A number of different fields in the above configuration files support a simple @@ -300,25 +329,64 @@ 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. +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 '!', any characters not enclosed are matched. +.P +After device node creation, removal, or network device renaming, +.B udev +executes the programs specified by the +.B RUN +key. +.br +In addition to the kernel provided hotplug environment variables, +.B UDEV_LOG +is set and contains the numerical priority value, if udev is configured to use +.BR syslog (3). +Executed programs may want to follow that setting. +.B DEVNAME +is exported to make the name of the created node, or the name the network +device is renamed to, available to the executed programs. +.SH "ENVIRONMENT" +.P +The following variables are read from the environment: +.TP +.B ACTION +.IR add " or " remove +signifies the addition or the removal of a device. +.TP +.B DEVPATH +The sysfs devpath of the device without the mountpoint but a leading slash. +.TP +.B SUBSYSTEM +The subsystem the device belongs to. Alternatively the subsystem may +be passed as the first argument. +.TP +.B UDEV_CONFIG_FILE +Overrides the default location of the +.B udev +config file. +.TP +.B UDEV_LOG +Overrides the log priority specified in the config file. +.TP +.B UDEV_RUN +If set to "0", it disables the execution of programs added by rules. .SH "FILES" .nf /sbin/udev udev program /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/ -web site. +.B Web resources: +.nf +.I http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html +.I http://linux\-hotplug.sourceforge.net/ +.fi .SH AUTHORS .B udev was developed by Greg Kroah-Hartman with much help from