unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-3.1)
Page:
Section:
Apropos / Subsearch:
optional field

UDEV(8)                  Linux Administrator's Manual                  UDEV(8)



NAME
       udev - Linux configurable dynamic device naming support

SYNOPSIS
       udev hotplug-subsystem

DESCRIPTION
       udev  provides a dynamic device directory containing only the files for
       actually present devices. It creates or removes device node files  usu-
       ally located in the /dev directory, or it renames network interfaces.

       As  part  of the hotplug subsystem, udev is executed if a kernel device
       is added or removed from the system.  On device  creation,  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.  udev main-
       tains a database for devices present on the system.
       On device removal, udev queries its database for the name of the device
       file to be deleted.

CONFIGURATION
       All  udev  configuration  files  consist of a set of lines of text. All
       empty lines or lines beginning with '#' will be ignored.

       udev expects its main configuration file at  /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:

       udev_root
              Indicates where to place the device nodes in the filesystem. The
              default value is /dev/.

       udev_db
              The name and location of the udev database. The default value is
              /dev/.udevdb.

       udev_rules
              The  name  of the udev rules file or directory to look for files
              with the suffix .rules.  All rule  files  are  read  in  lexical
              order. The default value is /etc/udev/rules.d/.

       udev_log
              The  switch  to  enable/disable  logging of udev information The
              default value is yes.

       A sample udev.conf file might look like this:

       # 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/.udevdb"

       # udev_rules - The name of the udev rules file or directory to look
                      for files with the suffix .rules
       udev_rules="/etc/udev/rules.d/"

       # udev_log - set to "yes" if you want logging, else "no"
       udev_log="yes"

       The rules for device naming are read from  the  files  located  in  the
       /etc/udev/rules.d/  directory,  or  at  the  location  specified by the
       udev_rules value in the /etc/udev/udev.conf file.
       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.
       If no matching rule is found, the default kernel device name is used.

       Every rule consists of a list of comma separated key value fields:

       key ,[key ,...]

       The following key names can be used to match against device properties:

       BUS    Match the bus type of the device.  (The sysfs device bus must be
              able to be determined by a "device" symlink.)

       KERNEL Match the kernel device name.

       SUBSYSTEM
              Match the kernel subsystem name.

       DRIVER Match the kernel driver name.

       ID     Match the device number on the bus, like PCI bus id.

       SYSFS{filename}
              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.
              Trailing whitespace characters in the sysfs attribute value  are
              ignored, if the key doesn't have any trailing whitespace charac-
              ters by itself.

       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.

       PROGRAM
              Call external program. This key is valid if the program  returns
              successful.   The  environment variables of udev are also avail-
              able to the program.
              The string returned by the program may be  additionally  matched
              with the RESULT key in the same or any later rule.

       RESULT Match the returned string of the last PROGRAM call. This key can
              be used in the same or in any later rule after a PROGRAM call.

       The following keys can get values assigned:

       NAME   The name of the node to be created, or  the  name,  the  network
              interface should be renamed to.

       SYMLINK
              The  name of a symlink targeting the node. Multiple symlinks may
              be specified by separating the names by the space character.
              If both the name and the symlink fields are omitted or its  val-
              ues  are  empty,  the device will be ignored and no node will be
              created.
              If only the symlink field is given and the name field  is  omit-
              ted,  the  rule will not be applied immediately, 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.

       OWNER, GROUP, MODE
              The permissions for the device node. Every specified value over-
              writes the compiled-in default value.

       OPTIONS
              last_rule will be the last rule applied.  No  later  rules  will
              have any effect.

              OPTIONS  ignore_device  will ignore this device. No node will be
              created.

              ignore_remove will  ignore  any  later  remove  event  for  this
              device.   This  may  be useful as a workaround for broken device
              drivers.

              all_partitions will create device nodes for all available parti-
              tions  of a blockdevice.  This may be useful for removable media
              devices which do not detect a media change.

              Multiple attributes may be separated by comma.

       The NAME, SYMLINK, PROGRAM,  OWNER  and  GROUP  fields  support  simple
       printf-like string substitutions:

       %n     The  "kernel  number"  of the device.  For example, 'sda3' has a
              "kernel number" of '3'.

       %k     The "kernel name" for the device.

       %p     The devpath for the device.

       %M     The kernel major number for the device.

       %m     The kernel minor number for the device.

       %b     The bus id for the device.

       %c     The string returned by the external program, specified  in  PRO-
              GRAM  (This does not work within the PROGRAM field for the obvi-
              ous reason.)
              A single part of the string, separated by a space character  may
              be selected by specifying the part number as an attribute: %c{N}
              If the number is followed by the  +  char  this  part  plus  all
              remaining parts of the result string are substituted: %c{N+}

       %N     The name of a created temporary device node to provide access to
              the device from a external program.

       %P     The node name of the parent device.

       %s{filename}
              The content of a sysfs attribute.

       %e     If a device node already exists with the name, the smallest pos-
              itive  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  differ-
              ent kernel subsystems.

              Note:  The use of the enumeration facility is unreliable outside
              of udevstart where the node  creation  is  serialized  and  pre-
              dictable.   The  returned  numbers rely on the order devices are
              probed on the system. If more than one device requests  an  enu-
              meration  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.

       %%     The '%' character itself.

       The count of charcters to insert may be limited by specifying the  for-
       mat  length  value. For example, '%3s{file}' will only insert the first
       three characters of the sysfs attribute.

       A sample udev.rules file might look like this:

       # 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"

       # 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", ID=="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"

       # grouping of optical drives from multiple kernel subsystems
       KERNEL=="sr*", NAME="%k", SYMLINK="cdrom%e"
       KERNEL=="scd*", NAME="%k", SYMLINK="cdrom%e"
       KERNEL=="pcd*", NAME="%k", SYMLINK="cdrom%e"
       KERNEL=="hd[a-z]", PROGRAM=="/bin/cat /proc/ide/%k/media", RESULT=="cdrom",
         NAME="%k", SYMLINK="cdrom%e"

       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:

       *      Matches zero, one, or more characters.

       ?      Matches any single character, but does not  match  zero  charac-
              ters.

       [ ]    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 follow-
              ing the '[' is a '!', any characters not enclosed are matched.

       After device node creation, removal, or network device  renaming,  udev
       executes  the programs located in the directory tree under /etc/dev.d/.
       The name of a program must have the suffix .dev to be recognized.
       In addition to the hotplug environment variables, UDEV_LOG  is  set  if
       udev  is  configured  to use the syslog facility. Executed programs may
       want to follow that setting.  DEVNAME is exported to make the  name  of
       the  created node, or the name the network device is renamed to, avail-
       able to the executed program.  The  programs  in  every  directory  are
       sorted in lexical order, while the directories are searched in the fol-
       lowing order:

       /etc/dev.d/$(DEVNAME)/*.dev
       /etc/dev.d/$(SUBSYSTEM)/*.dev
       /etc/dev.d/default/*.dev

ENVIRONMENT
       The following variables are read from the environment:

       ACTION add or remove signifies the addition or the removal of a device.

       DEVPATH
              The sysfs devpath of the device without  the  mountpoint  but  a
              leading slash.

       SUBSYSTEM
              The subsystem the device belongs to. Alternatively the subsystem
              may be passed as the first argument.

       UDEV_CONFIG_FILE
              Overrides the default location of the udev config file.

       UDEV_NO_DEVD
              The default behavior of udev  is  to  execute  programs  in  the
              /etc/dev.d/  directory  after device handling. If set, udev will
              skip this step.

FILES
       /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

SEE ALSO
       udevinfo(8), udevd(8), hotplug(8)

       Web resources:
       http://linux-hotplug.sourceforge.net/
       http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html

AUTHORS
       udev was developed by Greg  Kroah-Hartman  <gregATkroah.com>  with  much
       help  from  Dan  Stekloff <dsteklofATus.com>, Kay Sievers <kay.siev-
       ersATvrfy.org>, and many others.



                                 October 2003                          UDEV(8)