udev



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




NAME

       udev - Linux configurable dynamic device naming support


SYNOPSIS

       udev


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.  A list of rules is used to  match
       against specific device attributes.
       On  device  addition,  udev  matches  its  configured rules against the
       available device attributes to uniquely name the  device.   udev  main-
       tains 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.
       On device removal, udev queries its database for the name of the device
       file to be deleted.
       After the device node handling, a list of collected  programs  specific
       to this device is executed.


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 logging priority which can be set to err ,info or the corre-
              sponding numerical syslog(3) value.  The default value is err.

       A sample udev.conf file might look like this:

       # Where in the filesystem to place the device nodes
       udev_root="/dev"

       # The name and location of the udev database.
       udev_db="/dev/.udevdb"

       # The name and location of the udev rules file(s).
       udev_rules="@configdir@/rules.d"

       # The syslog(3) priority: "err", "info", or the numerical value.
       udev_log="err"

       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.

       ACTION Match the kernel action 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.  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.

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

       RUN    Add a program to the list of programs to be executed for a  spe-
              cific device.

       OPTIONS
              last_rule  stops  further rules application. No later rules will
              have any effect.

              ignore_device will ignore this device. No node will  be  created
              or program executed.

              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.

       %r     The udev_root value.

       %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 characters 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"

       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  kernel  provided  hotplug environment variables,
       UDEV_LOG is set and contains the numerical priority value, if  udev  is
       configured to use syslog(3).  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, available to the executed
       program. The programs in every directory are sorted in  lexical  order,
       while the directories are searched in the following 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_LOG
              Overrides the log priority specified in the config file.

       UDEV_RUN
              If set to "0", it disables the execution of  programs  added  by
              rules.

       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/dev.d/*                         programs invoked by udev


SEE ALSO

       udevinfo(8), udevd(8), hotplug(8)

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


AUTHORS

       udev  was  developed  by  Greg Kroah-Hartman <greg@kroah.com> with much
       help from Dan Stekloff <dsteklof@us.ibm.com>,  Kay  Sievers  <kay.siev-
       ers@vrfy.org>, and many others.



                                 October 2003                          UDEV(8)

Man(1) output converted with man2html