X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=docs%2Fwriting_udev_rules%2Findex.html;h=c2ccdc3663f1878a1bbc5fe9bbf8295904057f2e;hp=0e4d54cfaf61a4c4d7ae2bcb47b54326d525a1d6;hb=7fe082a8a42baa45ef45d82edde4f893410ebeea;hpb=b1ea9f3ef5aad038b4d31cb3e79749de9afb41f8 diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index 0e4d54cfa..c2ccdc366 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -1,6 +1,6 @@ -Writing udev rules [reactivated.net] +Writing udev rules @@ -8,7 +8,7 @@

Writing udev rules

by Daniel Drake (dsd)
-Version 0.51

+Version 0.6

The most recent version of this document can always be found at:
http://www.reactivated.net/udevrules.php @@ -23,23 +23,26 @@ The most recent version of this document can always be found at:
  • Why? (The purpose of this document)
  • The basics of writing rules
  • Additional automated customisation for NAME and SYMLINK parameters
    • -
  • Using regular expressions and wildcards in keys
    • +
  • Using shell-style pattern matching in keys
  • Key-writing basics
  • Identifying devices through basic keys
  • Identifying devices through SYSFS files
    • +
  • Using multiple SYMLINK style rules
    • +
  • Controlling ownership and permissions
  • Example: Writing a rule for my USB printer
  • Example: Writing a rule for my USB-Storage digital camera
  • Additional notes on writing rules for USB storage
  • Example: Writing convenience rules for my CD drives
    • +
  • Example: Writing a rule to name my network interface
  • Tips for finding the appropriate places in SYSFS
    • -
  • udev vs Nvidia's graphics drivers
    • +
  • Debugging your rules
  • Author and credits

    • About this document

    -udev is targetted at Linux kernels 2.6 and beyond to provide a userspace solution for a dynamic /dev directory, with persistant device naming. The previous /dev implementation, devfs, is now deprecated, and udev is seen as the successor. udev vs devfs is a sensitive area of conversation - you should read this document before making comparisons.

    +udev is targetted at Linux kernels 2.6 and beyond to provide a userspace solution for a dynamic /dev directory, with persistent device naming. The previous /dev implementation, devfs, is now deprecated, and udev is seen as the successor. udev vs devfs is a sensitive area of conversation - you should read this document before making comparisons.

    udev is a well thought out solution, but I was initially very confused how I might customise it for my system. This document attempts to make the process of rule writing a little bit clearer.

    @@ -51,20 +54,22 @@ This document assumes that you have udev/hotplug installed and running OK with d

    History

    -April 6th 2004: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".

    - -April 3rd 2004: Minor cleanups and preparations for possible inclusion in the udev distribution.

    -February 15th 2004: Initial publication.

    -February 18th 2004: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.

    -February 23rd 2004: Rewrote some parts to emphasise how sysfs naming works, and how it can be matched. Updated rule-writing parts to represent udev 018s new SYSFS{filename} naming scheme. Improved sectioning, and clarified many points. Added info about KDE.

    -March 20th 2004: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.

    +May 9th 2005 v0.6: Misc updates, including information about udevinfo, groups and permissions, logging, and udevtest.

    +June 20th 2004 v0.55: Added info on multiple symlinks, and some minor changes/updates.

    +April 26th 2004 v0.54: Added some Debian info. Minor corrections. Re-reverted information about what to call your rule file. Added info about naming network interfaces.

    +April 15th 2004 v0.53: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.

    +April 14th 2004 v0.52: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.

    +April 6th 2004 v0.51: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".

    +April 3rd 2004 v0.5: Minor cleanups and preparations for possible inclusion in the udev distribution.

    +March 20th 2004 v0.4: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.

    +February 23rd 2004 v0.3: Rewrote some parts to emphasise how sysfs naming works, and how it can be matched. Updated rule-writing parts to represent udev 018s new SYSFS{filename} naming scheme. Improved sectioning, and clarified many points. Added info about KDE.

    +February 18th 2004 v0.2: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.

    +February 15th 2004 v0.1: Initial publication.

    Software versions used at time of writing

    -Linux Kernel 2.6.5-rc3
    - -udev 024
    -hotplug 20040401

    +Linux Kernel 2.6.11
    +udev 056

    Terminology: devfs, sysfs, nodes, etc.

    @@ -83,48 +88,51 @@ The original /dev directories were just populated with every device that As stated above, writing rules for udev is an optional process. By default, you can plug a device in, and the a relevant node (e.g. /dev/sda for a mass-storage device) will be there, just like in previous /dev implementations.

    -However, udev allows you to customise the naming of device nodes. There are two reasons why you might want to do this: convenience, and persistant naming.

    +However, udev allows you to customise the naming of device nodes. There are two reasons why you might want to do this: convenience, and persistent naming.

    -Take the example of using udev, so that when your printer is plugged in, it gets named as /dev/printer and also as the usual /dev/lp0. It's not only convenience (e.g. reading and interpreting "printer" as opposed to "lp0"), its a solution for non-persistant naming. Say that I have two printers - a HP laser printer and an Epson inkjet. When they are both plugged in and on, I have /dev/lp0 and /dev/lp1.
    +Take the example of using udev, so that when your printer is plugged in, it gets named as /dev/printer and also as the usual /dev/lp0. It's not only convenience (e.g. reading and interpreting "printer" as opposed to "lp0"), its a solution for non-persistent naming. Say that I have two printers - a HP laser printer and an Epson inkjet. When they are both plugged in and on, I have /dev/lp0 and /dev/lp1.
    How do I know which node refers to which printer? There is no easy way. The first printer that got connected was assigned name "lp0", and the second "lp1". Plugging in my printers in a different order would swap the names here, and that would mess up my scripts that always expect my HP laser printer to be lp1.

    -However, if my HP laser printer got named lp_hp (as well as lpX) and my other printer got named lp_epson (as well as lpY), then my scripts could just refer to those names. udev magic can control this and ensure that these persistant names always point to the device that I intended.

    +However, if my HP laser printer got named lp_hp (as well as lpX) and my other printer got named lp_epson (as well as lpY), then my scripts could just refer to those names. udev magic can control this and ensure that these persistent names always point to the device that I intended.

    -For external mass-storage devices (e.g. usb hard disks), persistant naming is very helpful in that it allows you to hardcode accurate device paths into your /etc/fstab.

    +For external mass-storage devices (e.g. usb hard disks), persistent naming is very helpful in that it allows you to hardcode accurate device paths into your /etc/fstab.

    + +It is important to understand that writing rules is simply a means of customizing udev behaviour. Writing rules is not a workaround for the problem where no device nodes for your particular device exist. If no matching rules exist, udev will create the node anyway, using the name that was supplied by the kernel.

    The basics of writing rules

    -When populating /dev, udev decides which nodes to include, and how to name them, by reading a rules file. The default rules file includes some examples, and defaults to giving a devfs-style layout. The examples may safely be removed, but it is generally sensible to keep the devfs rules and simply make your own amendments and modifications.

    +When populating /dev, udev decides which nodes to include, and how to name them, by reading a series of rules files.

    -Default udev rules are stored in /etc/udev/udev.rules. You may find it interesting to look over this file - it includes a few examples, and then some default rules proving a devfs-style /dev layout. However, you should not write rules into this file directly, to reduce hassle while updating your udev installation in the future.

    +Default udev rules are stored in /etc/udev/rules.d/50-udev.rules. You may find it interesting to look over this file - it includes a few examples, and then some default rules proving a devfs-style /dev layout. However, you should not write rules into this file directly, to reduce hassle while updating your udev installation in the future.

    -Files in /etc/udev are parsed in lexical order. udev will stop processing rules as soon as it finds a matching rule in a file for the new item of hardware that has been detected. It is important that your own rules get processed before the udev defaults, otherwise your own naming schemes will not take effect! I suggest that you keep your own rules in a file at /etc/udev/local.rules (this doesn't exist by default - create it). As L comes before U, you know that your rules will be looked at first.

    +Files in /etc/udev/rules.d/ are parsed in lexical order. udev will stop processing rules as soon as it finds a matching rule in a file for the new item of hardware that has been detected. It is important that your own rules get processed before the udev defaults, otherwise your own naming schemes will not take effect! I suggest that you keep your own rules in a file at /etc/udev/rules.d/10-local.rules (this doesn't exist by default - create it). As 10 comes before 50, you know that your rules will be looked at first. It is important that the filenames of your rule files end with the .rules suffix, otherwise they will not be used.

    As your own rules will effectively mask out the udev defaults which create the base /dev layout, it is recommended that you also specify devfs-style names/symlinks for the rules you write, so that you get the sensible defaults plus your own names.

    In rule files, lines starting with a "#" are treated as comments. Every uncommented line in the file corresponds to a rule.

    -The basic form for a rule is: -
    key,[key,...] name [, symlink]
    +Rules are composed of keys. Keys are seperated by commas. Some keys are used for reading and matching information, others are used for assigning information and performing actions.
      -
    1. At least one key must be specified. Keys are used to identify which devices the rule matches.
      2. -
    2. The name parameter is required. It tells udev what that device should be named as in the /dev tree. It is written in the format NAME="X", where X is what the node will be named. You can specify multiple symlinks here, seperate them with a space.
      3. -
    3. The symlink parameter (optional) allows for you to specify additional places where this node will be linked.
      4. +
    4. At least one identification key should be provided, which will match the rule to any number of devices in the system. These are listed in the later section: Identifying devices through basic keys.
      5. +
    5. At least one assignment key should be provided, to control how the resultant device node is created. These include NAME, SYMLINK, OWNER, GROUP and MODE, all of which are described in this document.
    -Remember that udev will only create one node for one device. If you want it to be accessible through multiple nodes, then you have to specify the other nodes in the SYMLINK parameter.

    +Common rules will use basic identification keys to determine the device to name, and then have a NAME assignement key to define the device node name. udev will only create one node for one device, so if you want it to be accessible through multiple nodes, then you have to specify the other nodes in the SYMLINK assignment key.

    I'll take a slightly modified udev example rule to illustrate this: 
    BUS="usb", SYSFS{serial}="HXOLL0012202323480", NAME="lp_epson", SYMLINK="printers/epson_stylus"
    -The keys here are the BUS and SYSFS{serial} parameters. udev will match this rule against a device that is connected through the USB bus and with a serial number of HXOLL0012202323480. Note that all (as opposed to any) specified keys must be matched for udev to use the rule to name a device.
    +The identification keys here are BUS and SYSFS{serial}. The assignment keys here are NAME and SYMLINK. udev will match this rule against a device that is connected through the USB bus and with a serial number of HXOLL0012202323480. Note that all (as opposed to any) specified keys must be matched for udev to use the rule to name a device.
    udev will name this node lp_epson, and it will be located at /dev/lp_epson.
    udev will also create a symlink to /dev/lp_epson, located at /dev/printers/epson_stylus (the printers directory will be automatically created). You can now print to your Epson printer by sending data to /dev/printers/epson_stylus or /dev/lp_epson.

    +Any rules that you have added or modified will not take effect until you notify udev of this. Make sure you remember to run the following every time you modify any rule files: +
    # udevstart
    +

    Additional automated customisation for NAME and SYMLINK parameters

    @@ -141,9 +149,9 @@ Another common operator is %k. This represents what the kernel would name A full list of operators, with explanations, can be found in the udev man page.

    -

    Using regular expressions and wildcards in keys

    +

    Using shell-style pattern matching in keys

    -You can use wildcards and basic regular-expression style matching to provide even more flexibility when writing keys. Taking a default udev rule: +You can use shell style pattern matching to provide even more flexibility when writing keys. Taking a default udev rule: 
    KERNEL="ts*", NAME="input/%k"
    @@ -164,7 +172,7 @@ This rule says:
    Match a device identified by a KERNEL name starting with the letters "fd", followed by any single digit, optionally followed by anything at all. Name the device with the kernel number of the device (%n) under the floppy directory.
    -You can use these wildcards/regular-expression matches in any type of key, including both basic keys and sysfs-based identification (see below for explanations of these key types).

    +You can use these wildcards/pattern matches in any type of key, including both basic keys and sysfs-based identification (see below for explanations of these key types).

    I have purposely left out some information on this topic (particularly the flexibility of using [ ] operators) that is out of the scope of basic rule-writing documentation. More information on this topic can be found in the udev man page.

    @@ -183,6 +191,8 @@ You may be wondering, "How do I find the serial number of my printer? What is th The valid keys are: