From: dsd@gentoo.org Date: Sat, 26 Jun 2004 08:18:12 +0000 (-0700) Subject: [PATCH] Writing udev rules doc update X-Git-Tag: 028~5 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=c59a72105d0ff8a47b31f1829dd3c166ebd859d0;hp=c5d046b6c7f4dbd2072933b792f95f2793b28178 [PATCH] Writing udev rules doc update Here's an update to the documentation. It makes a few minor corrections and adds info about multiple-symlinks. It also seems that the patch I sent on April 27th (patching v0.53 to 0.54) was not applied, so this patch includes that update too, which was also just some small corrections plus added info on renaming network devices. --- diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index 1a2702aea..939618436 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -8,7 +8,7 @@

Writing udev rules

by Daniel Drake (dsd)
-Version 0.53

+Version 0.55

The most recent version of this document can always be found at:
http://www.reactivated.net/udevrules.php @@ -32,14 +32,16 @@ The most recent version of this document can always be found at:
  • 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
    • +
  • Using multiple SYMLINK style rules
  • udev vs Nvidia's graphics drivers
  • 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 +53,21 @@ This document assumes that you have udev/hotplug installed and running OK with d

    History

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

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

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

    +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
    +Linux Kernel 2.6.7
    +udev 027
    hotplug 20040401

    @@ -84,26 +87,24 @@ 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.

    The basics of writing rules

    -When populating /dev, udev decides which nodes to include, and how to name them, by reading a rules file. This rules file is processed from top to bottom, and udev will stop processing rules for a device once it finds one that matches.

    - -Default udev rules are stored in /etc/udev/udev.rules. The default 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. You should write your rules in this file, above the examples and default devfs-style rules.

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

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

    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.

    @@ -271,7 +272,13 @@ You will notice that a lot of information is not relevant for writing basic rule I will show three examples of this rule writing based on udevinfo output process below. I will then attempt to list some device-dependant tips and tricks for locating the correct info.

    -A reader wrote to me and informed me that he found KDE's control centre useful for writing rules. Apparently, information about USB devices (and others) can be found in the "Info Centre" section of the KDE Control Centre. This interface shows information such as serial number, vendor ID, etc. If you prefer a GUI-like approach, you might want to investigate this. +A reader wrote to me and informed me that he found KDE's control centre useful for writing rules. Apparently, information about USB devices (and others) can be found in the "Info Centre" section of the KDE Control Centre. This interface shows information such as serial number, vendor ID, etc. If you prefer a GUI-like approach, you might want to investigate this.

    + +The current releases of gnome-volume-manager are unable to treat symlink-nodes as real devices. Conversely as described above, you may wish to specify your own naming in the NAME parameter and specify %k in the SYMLINK parameter.

    + +The behaviour of your own rules masking the defaults can be overcome if you write multiple-SYMLINK style rules. + +

    Example: Writing a rule for my USB printer

    @@ -301,22 +308,17 @@ And my printer nodes exist at /dev/lp0 (or /dev/lp1 if another pri Quick Intro: My camera identifies itself as an external SCSI hard disk (it uses the usb-storage driver which is also used by devices such as USB hard disks and flash-card readers). I can then mount the partition on that disk and copy images over. Not all cameras work like this - many require external software (e.g. gphoto2) to be able to access photos.

    -This one is a bit tricky. Two nodes are created by default when my camera is connected : /dev/sda and /dev/sda1. sda1 is the node that I would like as my /dev/camera, as that is what gets mounted. The problem is that there are only small details which can be used as udev rules to show the difference between sda and sda1.

    +This one is a bit tricky. Several nodes are created by default when my camera is connected : /dev/sda and /dev/sda1, and possibly even /dev/sg1. This is an example where specifity is important - if your rule is not specific enough, it could match any of the above 3 nodes.

    -As these nodes (sda, sda1) are treated as block devices, looking in /sys/block would be a good place to start.

    +sda1 is the node that I would like as my /dev/camera, as that is what gets mounted. udevinfo did not point out any useful differences between sda, sda1, and sg1. I decided that a reliable way to differentiate between these 3 nodes would be to look at the KERNEL name.

    -In my /sys/block, I have a directory named sda. In my /sys/block/sda, I have a directory named sda1. Both of these directories have dev files in, so they are OK for udev rules. Running the following dumps a lot of information about my camera and the USB ports it is connected through. +A key such as KERNEL="sd?1" would match KERNEL names such as "sda1", "sdb1", "sdc1", and equally importantly, it will not match KERNEL names such as sda, sdb, or sg1. The purpose of this key is to ignore the /dev/sda and /dev/sg1 nodes. The device is a digital camera - I would not dream of fdisking it or anything like that, so these 2 nodes are pretty useless to me. The key attempts to capture the /dev/sda1 node, which is mountable and therefore useful!

    -
    -# udevinfo -a -p /sys/block/sda
-# udevinfo -a -p /sys/block/sda/sda1
-
    - -The output of both of these command was almost identical, so that does not help in writing keys to differentiate between sda and sda1.
    +As this node (sda1) is treated as a block device, looking in /sys/block would be a good place to start.

    -To differentiate between sda and sda1, I decided that matching KERNEL names would be most appropriate here. Some examples of KERNEL names for this type of device are: sda, sda1, sdb, sdb1, sdc, ...

    +In my /sys/block, I have a directory named sda. In my /sys/block/sda, I have a directory named sda1. Both of these directories have dev files in, so they are OK to run udevinfo on. Running the following dumps a lot of information about my camera and the USB port it is connected through. -udev's support for wildcards in key expressions comes in handy here. A key such as KERNEL="sd?1" would match KERNEL names such as "sda1", "sdb1", "sdc1", and equally importantly, it will not match KERNEL names such as sda, sdb (because the name must have a "1" on the end). The purpose of this key is to ignore the /dev/sda node. The device is a digital camera - I would not dream of fdisking it or anything like that, so this node is pretty useless to me. The key attempts to capture the /dev/sda1 node, which is mountable and therefore useful!

    +
    # udevinfo -a -p /sys/block/sda/sda1
    In the udevinfo output, I also noticed this bit of useful and understandable information: 
    SYSFS{product}="USB 2.0M DSC"
    @@ -324,7 +326,7 @@ In the udevinfo output, I also noticed this bit of useful and understandable inf So that gives me my rule. For completeness, I also include a BUS key (this was also found in the udevinfo output). 
    BUS="usb", SYSFS{product}="USB 2.0M DSC", KERNEL="sd?1", NAME="%k", SYMLINK="camera"
    -Now, when my camera is plugged in, it will be named /dev/sda1 (or, if sda1 isnt available, it might be called /dev/sdb1) and will always be correctly linked to from /dev/camera. The /dev/sda (or sdb) node still appears as normal, but the important thing is that my custom persistant "camera" symlink points to the mountable partition.

    +Now, when my camera is plugged in, it will be named /dev/sda1 (or, if sda1 isnt available, it might be called /dev/sdb1) and will always be correctly linked to from /dev/camera. The /dev/sda (or sdb) node still appears as normal, but the important thing is that my custom persistent "camera" symlink points to the mountable partition.

    Additional notes on writing rules for USB storage

    @@ -349,7 +351,7 @@ This problem also applies to other USB disks - e.g. if you create a new partitio udev provides a solution here - it is able to create nodes for all partitions of a block device. For every rule that you specify, the block device will have all 16 partition nodes created. To achieve this, you can simply modify the NAME key, as shown below:
    -
    BUS="usb", SYSFS{product}="USB 2.0 Storage Device", NAME{all_partitions}="usbhd%n"
    +
    BUS="usb", SYSFS{product}="USB 2.0 Storage Device", NAME{all_partitions}="usbhd"
    You will now have nodes named: usbhd, usbhd1, usbhd2, usbhd3, ..., usbhd15.

    @@ -359,13 +361,31 @@ I have two CD drives in my PC - a DVD reader, and a CD rewriter. My DVD is hdc a Still, some people (myself included) like to have nodes such as /dev/dvd and /dev/cdrw for convenience. Since we know the "hdX" values for these drives, writing rules is simple. The examples below should be self explanatory. - 
     BUS="ide", KERNEL="hdc", NAME="%k", SYMLINK="dvd cdroms/cdrom%n"
 BUS="ide", KERNEL="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n"
    -You may have noticed that the default udev.rules file contains a rule which runs a script to produces names for block devices. Do not be confused by this - as usual, because your own rules are located at the top of the rules file, they are processed before the default rules, so the default rules will not be used when naming the hardware you have written rules for.

    +You may have noticed that the default 50-udev.rules file contains a rule which runs a script to produces names for block devices. Do not be confused by this - as usual, because your own rules are located in a file which is processed before the default rules, the defaults will not be used when naming the hardware you have written rules for.

    + + +

    Example: Writing a rule to name my network interface

    +An interesting new feature in recent udev versions is the ability to write rules to name your network interfaces. Network interfaces do not show up in /dev, but they are generally referenced by names (e.g. with ifconfig). Despite the differences, the rule writing process is almost identical.

    + +As usual, udevinfo comes to our aid in rule-writing. In my example, I wish to rename my "eth0" network device (the following output is snipped): + +
    +# udevinfo -a -p /sys/class/net/eth0/
+  looking at class device '/sys/class/net/eth0':
+    SYSFS{address}="00:52:8b:d5:04:48"
+
    + +Every network adapter has its own unique MAC-address, so I chose to use this when writing my rule. This will not change, unless you change your network card. An example rule is shown below: + +
    KERNEL="eth*", SYSFS{address}="00:52:8b:d5:04:48", NAME="lan"
    + +You will need to reload the net driver for this rule to take effect. You can either unload and reload the module, or simply reboot the system. You will also need to reconfigure your system to use "lan" rather than "eth0". I had some troubles getting this going (the interface wasn't being renamed) until I had completely dropped all references to eth0.
    +After that, you should be able to use "lan" instead of "eth0" in any calls to ifconfig or similar utilities.

    Tips for finding the appropriate places in SYSFS

    @@ -383,6 +403,18 @@ BUS="ide", KERNEL="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n"
  • Remember that unfortunately, the kernel does not export information for all devices into sysfs, meaning that you simply can't write rules for some devices yet. On 20/02/04, the udev author stated that there are 162 drivers left to convert to sysfs.
    • + +

    Using multiple SYMLINK style rules

    +Another recent feature is the ability to write rules that do not specify a NAME, but instead they simply specify SYMLINK keys. This allows you to avoid the issue where your own rules effectively mask the udev defaults.

    + +Take the rule:
    +
    KERNEL="hdc", SYMLINK="dvd"
    + +When udev finds this rule, it will take a mental note of it. Upon finding another rule matching the same device which also includes a NAME parameter, udev will create the node as specified by the NAME parameter, plus symbolic links as specified by the SYMLINK parameters of both rules.
    +To put it into practical terms, when udev is naming nodes for my hdc device, it will use the default rules for block devices as usual, with the addition of my personal symlink "dvd".

    + +Similarly to normal rules, rules of this type will only take effect if udev is able to find them before it finds a rule specifying a NAME parameter.

    +

    udev vs Nvidia's graphics drivers

    @@ -390,9 +422,9 @@ BUS="ide", KERNEL="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n" Nvidia's graphics drivers (the closed-source ones, not the ones that come with XFree) do not work with a default installation of udev - you are unable to start X. This is because the nvidia module is loaded by X, but the /dev/nvidia* nodes are not created quick enough, so X bails out.

    -The solution to this problem is to autoload the nvidia module on bootup. Yes - you are *supposed* to do this - the NVidia FAQ confirms this! On devfs-based systems, devfs did this automatically at bootup anyway. Your linux distribution will have created a file which you can list modules to be loaded on bootup (e.g. /etc/modules.autoload.d/kernel-2.6 for Gentoo).

    +The solution to this problem is to autoload the nvidia module on bootup. Yes - you are *supposed* to do this - the NVidia FAQ confirms this! On devfs-based systems, devfs did this automatically at bootup anyway. Your linux distribution will have created a file which you can list modules to be loaded on bootup (e.g. /etc/modules.autoload.d/kernel-2.6 for Gentoo, /etc/modules for Debian).

    -This isn't all - you will also need to patch the nvidia kernel interface to export some basic info to SYSFS so that udev will create the devices. Martin Schlemmer has written a patch against the 1.0.5336 version of the nvidia drivers, which can be found here. The Gentoo package nvidia-kernel-1.0.5336-r1 contains this patch.

    +This isn't all - you will also need to patch the nvidia kernel interface to export some basic info to SYSFS so that udev will create the devices. Martin Schlemmer has written a patch against the 1.0.5336 version of the nvidia drivers, which can be found here. The Gentoo package nvidia-kernel-1.0.5336-r4 contains this patch.

    Another solution is to simply create the nvidia specific nodes on bootup. X will then load the module when required, and as the nodes are already in existance, you will not run into the problem described above. Place these commands in a file that is automatically executed on bootup (e.g. /etc/conf.d/local.start for Gentoo): 
    @@ -412,10 +444,12 @@ Additional thanks to:
 
  • The udev developers!
    • 
 
  • agrippa_cash (usb-storage info)
    • 
 
  • Carl Streeter (usb-storage info)
    • 
+
  • David Watson
    • 
 
  • Decibels
    • 
 
  • Frank Pieczynski
    • 
 
  • Feth Arezki
    • 
 
  • Jim (KDE info)
    • 
+
  • Johannes Jordens
    • 
 
  • Kay Sievers
    • 
 
  • Patrick Dreker
    • 
 
  • Todd Musall
    •