diff options
Diffstat (limited to 'udev.8.in')
| -rw-r--r-- | udev.8.in | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/udev.8.in b/udev.8.in new file mode 100644 index 0000000000..680587a270 --- /dev/null +++ b/udev.8.in @@ -0,0 +1,397 @@ +.TH UDEV 8 "October 2003" "" "Linux Administrator's Manual" +.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: +.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 continue, regardless of the state of the device representation. +.TP +.B UDEV_NO_DEVD +The default behavior of +.B udev +is to execute programs in the +.I /etc/dev.d/ +directory after device handling. If set, +.B udev +will skip this step. +.SH "DESCRIPTION" +.B udev +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, +.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 be used as keys to determine a +unique name for the device. +.B udev +maintains a database for devices present on the system. +.br +On device removal, +.B udev +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 main configuration file at +.IR /etc/udev/udev.conf . +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 +Indicates where to place the device nodes in the filesystem. The default +value is +.IR /udev/ . +.TP +.B udev_db +The name and location of the udev database. The default value 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 device handled. +The default value is +.IR yes . +.TP +.B default_mode +This is the default mode for all nodes not explicitely matching in the +permissions file. The default value is +.IR 0666 . +.TP +.B default_owner +This is the default owner for all nodes not explicitely matching in the +permissions file. The default value is +.IR root . +.TP +.B default_group +This is the default group for all nodes not explicitely matching in the +permissions file. The default value is +.IR root . +.br +.P +.RI "A sample " udev.conf " might look like this: +.sp +.nf +# udev_root - where to place the device nodes in the filesystem +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 not +# explicitely matching in the permissions file +default_mode="0666" + +# default_owner - set the default owner for all nodes not +# explicitely matching in the permissions file +default_owner="root" + +# default_group - set the default group for all nodes not +# explicitely matching in the permissions file +default_group="root" +.fi +.P +The rules for udev to use when naming devices may specified in +.I /etc/udev/udev.rules +or 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 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 +Every rule consists of a list of comma separated fields: +.sp +.IR "key " ,[ "key " ,...] " name " [, " symlink" ] +.sp +where fields are: +.TP +.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 KERNEL +Match the kernel device 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 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 +.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 +The string returned by the program may be additionally matched with the +.B RESULT +key. +.TP +.B RESULT +Match the returned string of the last +.B PROGRAM +call. This key may be used in any following rule after a +.B PROGRAM +call. +.TP +.B NAME +The name of the node to be created, or the name, the network interface +should be renamed to. +.br +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. +.br +If both the name and the symlink fields are omitted or its +values empty, the device will be ignored and no node will be created. +.br +If only the symlink field is given and the name field is omitted, +the rule will not be applied immediatly, but the symlink field is added +to the symlink list of the rule which will create the node. +This makes it possible to specify additional symlinks in a possibly +separate rules file, while the device nodes are maintained by the +distribution provided rules file. +.TP +.B OWNER, GROUP, MODE +The permissions for this device. Every specified value overwrites the value +given in the permissions file. +.P +.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'. +.TP +.B %k +The "kernel name" for the device. +.TP +.B %M +The kernel major number for the device. +.TP +.B %m +The kernel minor number for the device. +.TP +.B %b +The bus id for the device. +.TP +.B %c +The string returned from the execution of +.B PROGRAM +(This does not work within the +.B PROGRAM +field for the obvious reason.) +.br +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 +.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 +.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 +BUS="usb", SYSFS{serial}="W09090207101241330", NAME="lp_color" + +# 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" + +# USB mouse at third port of the second hub to be called mouse1 +BUS="usb", PLACE="2.3", NAME="mouse1" + +# ttyUSB1 should always be called pda with two additional symlinks +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 in +.I /etc/udev/udev.permissions +or 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 +.fi +.P +The value +.I $local +can be used instead of 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 '!', any character not enclosed is matched. +.P +After device node creation, removal, or network device renaming, +.B udev +executes the programs in the directory tree under +.IR /etc/dev.d/ . +The name of a program must end with +.I .dev +suffix, to be recognized. +.br +In addition to the hotplug environment variables, +.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 program. The programs in every +directory are sorted in lexical order, while the directories are searched in +the following order: +.sp +.nf +/etc/dev.d/$(DEVNAME)/*.dev +/etc/dev.d/$(SUBSYSTEM)/*.dev +/etc/dev.d/default/*.dev +.fi +.SH "FILES" +.nf +/sbin/udev udev program +/etc/udev/* udev config files +/etc/hotplug.d/default/udev.hotplug hotplug symlink to udev program +/etc/dev.d/* programs invoked by udev +.fi +.LP +.SH "SEE ALSO" +.BR udevinfo (8), +.BR udevd (8), +.BR hotplug (8) +.PP +The +.I http://linux\-hotplug.sourceforge.net/ +web site. +.SH AUTHORS +.B udev +was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from +Dan Stekloff <dsteklof@us.ibm.com>, Kay Sievers <kay.sievers@vrfy.org>, and +many others. |