From 5aeea7b1f7880fbcb58df1cf60f75881ce607ca1 Mon Sep 17 00:00:00 2001 From: Daniel Drake Date: Sat, 10 Jun 2006 23:46:15 +0200 Subject: update "writing udev rules" --- docs/writing_udev_rules/index.html | 951 +++++++++++++++++++++++++------------ 1 file changed, 650 insertions(+), 301 deletions(-) diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index 1c5c89b3c9..ce33bbb011 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -1,341 +1,627 @@ - + + + + Writing udev rules -

Writing udev rules

by Daniel Drake (dsd)
-Version 0.6

+Version 0.7

The most recent version of this document can always be found at:
-http://www.reactivated.net/udevrules.php + +http://www.reactivated.net/writing_udev_rules.html

Contents

-
    -
  1. About this document
    2. -
  2. History
    3. -
  3. Software versions used at time of writing
    4. -
  4. Terminology: devfs, sysfs, nodes, etc.
    5. - -
  5. Why? (The purpose of this document)
    6. -
  6. The basics of writing rules
    7. -
  7. Additional automated customisation for NAME and SYMLINK parameters
    8. -
  8. Using shell-style pattern matching in keys
    9. -
  9. Key-writing basics
    10. -
  10. Identifying devices through basic keys
    11. -
  11. Identifying devices through SYSFS files
    12. -
  12. Using multiple SYMLINK style rules
    13. -
  13. Controlling ownership and permissions
    14. -
  14. Example: Writing a rule for my USB printer
    15. -
  15. Example: Writing a rule for my USB-Storage digital camera
    16. - -
  16. Additional notes on writing rules for USB storage
    17. -
  17. Example: Writing convenience rules for my CD drives
    18. -
  18. Example: Writing a rule to name my network interface
    19. -
  19. Tips for finding the appropriate places in SYSFS
    20. -
  20. Debugging your rules
    21. -
  21. Author and credits
    22. -
+ + +

Introduction

-

About this document

-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.

+

About this document

-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.

+

+udev is targeted 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. +

-I'm all open to feedback - please contact me with any comments, problems, and suggested improvements.

+

+Over the years, the things that you might use udev rules for has changed, as well as the flexibility of rules themselves. On a modern system, udev provides persistent naming for some device types out-of-the-box, eliminating the need for custom rules for those devices. However, some users will still require the extra level of customisation. +

-This document assumes that you have udev/hotplug installed and running OK with default configurations. If you do not yet have udev configured and running, I would suggest that you follow Decibels udev Primer to get to this stage (contains some Gentoo Linux specifics, but should be useful for other distro's too).

+

+This document assumes that you have udev installed and running OK with default configurations. This is usually handled by your Linux distribution. +

+ +

+This document does not cover every single detail of rule writing, but does aim to introduce all of the main concepts. The finer details can be found in the udev man page. +

+ +

+This document uses various examples (many of which are entirely fictional) to illustrate ideas and concepts. Not all syntax is explicitly described in the accompanying text, be sure to look at the example rules to get a complete understanding. +

+

History

-

History

- -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.11
-udev 056

+ + +

The concepts

-

Terminology: devfs, sysfs, nodes, etc.

-A basic introduction only, might not be totally accurate.

+

Terminology: devfs, sysfs, nodes, etc.

+ +

+A basic introduction only, might not be totally accurate. +

-On typical linux-based systems, the /dev directory is used to store file-like device nodes which refer to certain devices in the system. Each node points to a part of the system (a device), which might or might not exist. Userspace applications can use these device nodes to interface with the systems hardware, for example, XFree86 will "listen to" /dev/input/mice so that it can relate the users mouse movements to moving the visual mouse pointer.

+

+On typical Linux-based systems, the /dev directory is used to store file-like device nodes which refer to certain devices in the system. Each node points to a part of the system (a device), which might or might not exist. Userspace applications can use these device nodes to interface with the systems hardware, for example, the X server will "listen to" /dev/input/mice so that it can relate the user's mouse movements to moving the visual mouse pointer. +

-The original /dev directories were just populated with every device that might possibly appear in the system. /dev directories were typically very large because of this. devfs came along to provide a more managable approach (noticably, it only populated /dev with hardware that is plugged into the system), as well as some other functionality, but the system proved to have problems which could not be easily fixed.

+

+The original /dev directories were just populated with every device that might possibly appear in the system. /dev directories were typically very large because of this. devfs came along to provide a more manageable approach (noticeably, it only populated /dev with hardware that is plugged into the system), as well as some other functionality, but the system proved to have problems which could not be easily fixed. +

-udev is the "new" way of managing /dev directories, designed to clear up some issues with previous /dev implementations, and provide a robust path forward. In order to create and name /dev device nodes corresponding to devices that are present in the system, udev relies on matching information provided by sysfs with rules provided by the user. This documentation aims to detail the process of rule-writing, one of the only udev-related tasks that must (optionally) be performed by the user.

+

+udev is the "new" way of managing /dev directories, designed to clear up some issues with previous /dev implementations, and provide a robust path forward. In order to create and name /dev device nodes corresponding to devices that are present in the system, udev relies on matching information provided by sysfs with rules provided by the user. This documentation aims to detail the process of rule-writing, one of the only udev-related tasks that must (optionally) be performed by the user. +

-sysfs is a new filesystem to the 2.6 kernels. It is managed by the kernel, and exports basic information about the devices currently plugged into your system. udev can use this information to create device nodes corresponding to your hardware. sysfs is mounted at /sys and is browsable. You may wish to investigate some of the files stored there before getting to grips with udev. Throughout this document, I will use the terms /sys and SYSFS interchangeably.


+

+sysfs is a new filesystem to the 2.6 kernels. It is managed by the kernel, and exports basic information about the devices currently plugged into your system. udev can use this information to create device nodes corresponding to your hardware. sysfs is mounted at /sys and is browseable. You may wish to investigate some of the files stored there before getting to grips with udev. Throughout this document, I will use the terms /sys and sysfs interchangeably. +

-

Why?

+

Why?

+ +

+udev rules are flexible and very powerful. Here are some of the things you can use rules to achieve: +

+ + -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.

+

+Writing rules is not a workaround for the problem where no device nodes for your particular device exist. Even if there are no matching rules, udev will create the device node with the default name supplied by the kernel. +

-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.

+

+Having persistently named device nodes has several advantages. Assume you own two USB storage devices: a digital camera and a USB flash disk. These devices are typically assigned device nodes /dev/sda and /dev/sdb but the exact assignment depends on the order which they were originally connected. This may cause problems to some users, who would benefit greatly if each device could be named persistently every time, e.g. /dev/camera and /dev/flashdisk. +

-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.
+ +

Built-in persistent naming schemes

-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.

+

+udev provides persistent naming for some device types out of the box. This is a very useful feature, and in many circumstances means that your journey ends here: you do not have to write any rules. +

-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.

+

+udev provides out-of-the-box persistent naming for storage devices in the /dev/disk directory. To view the persistent names which have been created for your storage hardware, you can use the following command: +

-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.

+
# ls -lR /dev/disk
-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.

+

+This works for all storage types. As an example, udev has created /dev/disk/by-id/scsi-SATA_ST3120827AS_4MS1NDXZ-part3 which is a persistent-named symbolic link to my root partition. udev creates /dev/disk/by-id/usb-Prolific_Technology_Inc._USB_Mass_Storage_Device-part1 when I plug my USB flash disk in, which is also a persistent name. +

- -

The basics of writing rules

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

+

Rule writing

-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.

+ +

Rule files and semantics

-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.

+

+When deciding how to name a device and which additional actions to perform, udev reads a series of rules files. These files are kept in the /etc/udev/rules.d directory, and they all must have the .rules suffix. +

-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.

+

+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. +

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

+

+Files in /etc/udev/rules.d/ are parsed in lexical order, and in some circumstances, the order in which rules are parsed is important. In general, you want your own rules to be parsed before the defaults, so I suggest you create a file at /etc/udev/rules.d/10-local.rules and write all your rules into this file. +

-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. Matches and assignments are carried out with the expected operators (= and ==). +

+In a rules file, lines starting with "#" are treated as comments. Every other non-blank line is a rule. Rules cannot span multiple lines. +

-
    -
  1. 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.
    2. -
  2. 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.
    3. -
+

+One device can be matched by more than one rule. This has it's practical advantages, for example, we can write two rules which match the same device, where each one provides its own alternate name for the device. Both alternate names will be created, even if the rules are in separate files. It is important to understand that udev will not stop processing when it finds a matching rule, it will continue searching and attempt to apply every rule that it knows about. +

-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.

+ +

Rule syntax

-I'll take a slightly modified udev example rule to illustrate this: -
BUS=="usb", SYSFS{serial}=="HXOLL0012202323480", NAME="lp_epson", SYMLINK="printers/epson_stylus"
+

+Each rule is constructed from a series of key-value pairs, which are separated by commas. match keys are conditions used to identify the device which the rule is acting upon. When all match keys in a rule correspond to the device being handled, then the rule is applied and the actions of the assignment keys are invoked. Every rule should consist of at least one match key and at least one assignment key. +

-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.
+

+Here is an example rule to illustrate the above: +

-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.

+
KERNEL=="hdb", NAME="my_spare_disk"
-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
+

+The above rule includes one match key (KERNEL) and one assignment key (NAME). The semantics of these keys and their properties will be detailed later. It is important to note that the match key is related to its value through the equality operator (==), whereas the assignment key is related to its value through the assignment operator (=). +

- -

Additional automated customisation for NAME and SYMLINK parameters

+ -In the NAME and SYMLINK parameters of your rules, you are able to use basic operators to assist the naming of devices. Hackers will know this sort of thing as printf-like string substitution. + +

Basic Rules

-There are a number of operators which can compose some or all of your NAME/SYMLINK parameters. These operators refer to kernel-data relating to the device. Take this example: +

+udev provides several different match keys which can be used to write rules which match devices very precisely. Some of the most common keys are introduced below, others will be introduced later in this document. For a complete list, see the udev man page. +

-
BUS=="usb", SYSFS{vendor}=="FUJIFILM", SYSFS{model}=="M100", NAME="camera%n"
+ -The %n operator will be replaced with the "kernel number" for the camera device, to produce a NAME such as camera0, camera1, etc.

+

+After you have used a series of match keys to precisely match a device, udev gives you fine control over what happens next, through a range of assignment keys. For a complete list of possible assignment keys, see the udev man page. The most basic assignment keys are introduced below. Others will be introduced later in this document. +

-Another common operator is %k. This represents what the kernel would name the device, e.g. "hda1". You may often see rules which have NAME="%k" to produce the default names for the hardware. In these rules, customisation is usually done through the SYMLINK parameter.

+ -A full list of operators, with explanations, can be found in the udev man page.

+

+As hinted above, udev only creates one true device node for one device. If you wish to provide alternate names for this device node, you use the symbolic link functionality. With the SYMLINK assignment, you are actually maintaining a list of symbolic links, all of which will be pointed at the real device node. To manipulate these links, we introduce a new operator for appending to lists: +=. You can append multiple symlinks to the list from any one rule by separating each one with a space. +

- -

Using shell-style pattern matching in keys

+
KERNEL=="hdb", NAME="my_spare_disk"
-You can use shell style pattern matching to provide even more flexibility when writing keys. Taking a default udev rule: +

+The above rule says: match a device which was named by the kernel as hdb, and instead of calling it hdb, name the device node as my_spare_disk. The device node appears at /dev/my_spare_disk. +

-
KERNEL=="ts*", NAME="input/%k"
+
KERNEL=="hdb", DRIVER=="ide-disk", SYMLINK+="sparedisk"
-The * operator is used here, which matches literally anything - zero, one, or more characters of any kind. The rule literally says:
+

+The above rule says: match a device which was named by the kernel as hdb AND where the driver is ide-disk. Name the device node with the default name and create a symbolic link to it named sparedisk. Note that we did not specify a device node name, so udev uses the default. In order to preserve the standard /dev layout, your own rules will typically leave the NAME alone but create some SYMLINKs and/or perform other assignments. +

-
Match a device identified by a KERNEL name starting with the letters "ts" optionally followed by anything at all, and name it with the KERNEL name (%k) under the input directory.
+
KERNEL=="hdc", SYMLINK+="cdrom cdrom0"
-The ? operator is similar, and matches any single character (but not zero characters).

+

+The above rule is probably more typical of the types of rules you might be writing. It creates two symbolic links at /dev/cdrom and /dev/cdrom0, both of which point at /dev/hdc. Again, no NAME assignment was specified, so the default kernel name (hdc) is used. +

-You can also use square brackets [ ] to match any single character. Direct quote from udev man page:
-
For example, the pattern string "tty[SR]" would match either "ttyS" or "ttyR".
+ +

Matching sysfs attributes

-You can also specify ranges that can be matched, e.g. [0-9] would match any single digit. Using an example rule from a default udev installation: +

+The match keys introduced so far only provide limited matching capabilities. Realistically we require much finer control: we want to identify devices based on advanced properties such as vendor codes, exact product numbers, serial numbers, storage capacities, number of partitions, etc. +

-
KERNEL=="fd[0-9]*", NAME="floppy/%n"
+

+Many drivers export information like this into sysfs, and udev allows us to incorporate sysfs-matching into our rules, using the SYSFS key with a slightly different syntax. +

-This rule says:
+

+Here are some examples of rules which match data from sysfs. Further detail will be provided later in this document which will aid you in writing rules based on sysfs attributes. +

-
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.
+
+KERNEL=="sda", SYSFS{model}=="ST3120827AS", SYMLINK+="my_hard_disk"
+SUBSYSTEM=="block", SYSFS{size}=="234441648", SYMLINK+="my_disk"
+BUS=="usb", SYSFS{manufacturer}=="OLYMPUS", SYSFS{product}=="X250,D560Z,C350Z", SYMLINK+="camera"
+
-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).

+ +

String substitutions

-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.

+

+When writing rules which will potentially handle multiple similar devices, udev's printf-like string substitution operators are very useful. You can simply include these operators in any assignments your rule makes, and udev will evaluate them when they are executed. +

- -

Key-writing basics

+

+The most common operators are %k and %n. %k evaluates to the kernel name for the device, e.g. "sda3" for a device that would (by default) appear at /dev/sda3. %n evaluates to the kernel number for the device (the partition number for storage devices), e.g. "3" for /dev/sda3. +

-udev provides a few basic key matching methods, and also provides flexible ways of matching information in SYSFS. A typical rule will match both normal keys (e.g. BUS and KERNEL), as well as SYSFS keys to differentiate between different hardware plugged in throught the same port.

+

+udev also provides several other substitution operators for more advanced functionality. Consult the udev man page after reading the rest of this document. There is also an alternative syntax for these operators - $kernel and $number for the examples above. For this reason, if you wish to match a literal % in a rule then you must write %%, and if you wish to match a literal $ then you must write $$. +

-You may be wondering, "How do I find the serial number of my printer? What is the model of my camera?". Rule writing isn't as hard as it sounds. The trickiest bit is finding your device in /sys, and deciding which info to use.

+

+To illustrate the concept of string substitution, some example rules are shown below. +

- -

Identifying devices through basic keys

+
+KERNEL=="mice", NAME="input/%k"
+KERNEL=="loop0", NAME="loop/%n", SYMLINK+="%k"
+
+ +

+The first rule ensures that the mice device node appears exclusively in the /dev/input directory (by default it would be at /dev/mice). The second rule ensures that the device node named loop0 is created at /dev/loop/0 but also creates a symbolic link at /dev/loop0 as usual. +

-See the udev man page for more info on these keys.

+

+The use of the above rules is questionable, as they all could be rewritten without using any substitution operators. The true power of these substitutions will become apparent in the next section. +

-The valid keys are: -