Software: Apache/2.2.3 (CentOS). PHP/5.1.6 uname -a: Linux mx-ll-110-164-51-230.static.3bb.co.th 2.6.18-194.el5PAE #1 SMP Fri Apr 2 15:37:44 uid=48(apache) gid=48(apache) groups=48(apache) Safe-mode: OFF (not secure) /usr/share/doc/udev-095/writing_udev_rules/ drwxr-xr-x | |
| Viewing file: Select action/file-type: Writing udev rulesby Daniel Drake (dsd)Version 0.7 The most recent version of this document can always be found at: http://www.reactivated.net/writing_udev_rules.html Contents
IntroductionAbout this documentudev 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. 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 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
The conceptsTerminology: 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, 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 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. 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?udev rules are flexible and very powerful. Here are some of the things you can use rules to achieve:
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. 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. Built-in persistent naming schemesudev 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. 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: # ls -lR /dev/disk 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. Rule writingRule files and semanticsWhen 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. 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. 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. In a rules file, lines starting with "#" are treated as comments. Every other non-blank line is a rule. Rules cannot span multiple lines. 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. Rule syntaxEach 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. Here is an example rule to illustrate the above: KERNEL=="hdb", NAME="my_spare_disk" 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 (=). Basic Rulesudev 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.
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.
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. KERNEL=="hdb", NAME="my_spare_disk" 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=="hdb", DRIVER=="ide-disk", SYMLINK+="sparedisk" 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. KERNEL=="hdc", SYMLINK+="cdrom cdrom0" 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. Matching sysfs attributesThe 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. 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. 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. String substitutionsWhen 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. 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 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 $$. To illustrate the concept of string substitution, some example rules are shown below. 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. 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. String matchingAs well as matching strings exactly, udev allows you to use shell-style pattern matching. There are 3 patterns supported:
Here are some examples which incorporate the above patterns. Note the use of the string substitution operators. KERNEL=="fd[0-9]*", NAME="floppy/%n", SYMLINK+="%k" KERNEL=="hiddev*", NAME="usb/%k" The first rule matches all floppy disk drives, and ensures that the device nodes are placed in the /dev/floppy directory, as well as creating a symbolic link from the default name. The second rule ensures that hiddev devices are only present in the /dev/usb directory. Finding information from sysfsThe sysfs treeThe concept of using interesting information from sysfs was briefly touched upon above. In order to write rules based on this information, you first need to know the names of the attributes and their current values. sysfs is actually a very simple structure. It is logically divided into directories. Each directory contains a number of files (attributes) which typically contain just one value. Some symbolic links are present, which link various parts of the tree together. Some directories are referred to as top-level device paths. These directories act as the top-level glue which chain other parts of sysfs to the device in question. Top-level device paths can be classified as sysfs directories which contain a dev file, the following command will list these for you: # find /sys -name dev For example, on my system, the /sys/block/sda directory is the device path for my hard disk. It is chained to the controller through the /sys/block/sda/device/ symbolic link, which is in turn chained to the device driver through the /sys/block/sda/device/driver/ symbolic link. When you write rules based on sysfs information, you are simply matching attribute contents of some files in one part of the chain. For example, I can read the size of my hard disk as follows: # cat /sys/block/sda/size 234441648 In a udev rule, I could use SYSFS{size}=="234441648" to identify this disk. As udev iterates through the entire device chain, I could alternatively opt to match attributes in another part of the chain (e.g. attributes in /sys/class/block/sda/device/), however there are some caveats when dealing with different parts of the chain which are described later. Although this serves as a useful introduction as to the structure of sysfs and exactly how udev matches values, manually trawling through sysfs is both time consuming and unnecessary. udevinfoEnter udevinfo, which is probably the most straightforward tool you can use to construct rules. All you need to know is the sysfs device path of the device in question. A trimmed example is shown below: # udevinfo -a -p /sys/block/sda looking at device '/block/sda': KERNEL=="sda" SUBSYSTEM=="block" SYSFS{stat}==" 128535 2246 2788977 766188 73998 317300 3132216 5735004 0 516516 6503316" SYSFS{size}=="234441648" SYSFS{removable}=="0" SYSFS{range}=="16" SYSFS{dev}=="8:0" looking at device '/devices/pci0000:00/0000:00:07.0/host0/target0:0:0/0:0:0:0': ID=="0:0:0:0" BUS=="scsi" DRIVER=="sd" SYSFS{ioerr_cnt}=="0x0" SYSFS{iodone_cnt}=="0x31737" SYSFS{iorequest_cnt}=="0x31737" SYSFS{iocounterbits}=="32" SYSFS{timeout}=="30" SYSFS{state}=="running" SYSFS{rev}=="3.42" SYSFS{model}=="ST3120827AS " SYSFS{vendor}=="ATA " SYSFS{scsi_level}=="6" SYSFS{type}=="0" SYSFS{queue_type}=="none" SYSFS{queue_depth}=="1" SYSFS{device_blocked}=="0" As you can see, udevinfo simply produces a list of attributes you can use as-is as match keys in your udev rules. From the above example, I could produce (e.g.) either of the following two rules for this device: SUBSYSTEM=="block", SYSFS{size}=="234441648", NAME="my_hard_disk" BUS=="scsi", SYSFS{model}=="ST3120827AS", NAME="my_hard_disk" You may have noted the use of colour in the above examples. This is to demonstrate that you generally can not mix-and-match attributes from different sections of the udevinfo output - your rule will not work. For example, the following rule is invalid: SUBSYSTEM=="block", SYSFS{size}=="234441648", SYSFS{model}=="ST3120827AS", NAME="my_hard_disk" You are usually provided with a large number of attributes, and you must pick a number of them (from the same section) to construct your rule. In general, you want to choose attributes which identify your device in a persistent and human-recognisable way. In the examples above, I chose the size of my disk and its model number. I did not use meaningless numbers such as SYSFS{iodone_cnt}=="0x31737". Another point to note is that it is common for text attributes to appear in the udevinfo output to be padded with spaces (e.g. see ST3120827AS above). In your rules, you can either specify the extra spaces, or you can cut them off as I have done. The only complication with using udevinfo is that you are required to know the top-level device path (/sys/block/sda in the example above). This is not always obvious. However, as you are generally writing rules for device nodes which already exist, you can use udevinfo to look up the device path for you: # udevinfo -a -p $(udevinfo -q path -n /dev/sda) Alternative methodsAlthough udevinfo is almost certainly the most straightforward way of listing the exact attributes you can build rules from, some users are happier with other tools. Utilities such as usbview display a similar set of information, most of which can be used in rules. Advanced topicsControlling permissions and ownershipudev allows you to use additional assignments in rules to control ownership and permission attributes on each device. The GROUP assignment allows you to define which Unix group should own the device node. Here is an example rule which defines that the video group will own the framebuffer devices: KERNEL=="fb[0-9]*", NAME="fb/%n", SYMLINK+="%k", GROUP="video" The OWNER key, perhaps less useful, allows you to define which Unix user should have ownership permissions on the device node. Assuming the slightly odd situation where you would want john to own your floppy devices, you could use: KERNEL=="fd[0-9]*", OWNER="john" udev defaults to creating nodes with Unix permissions of 0660 (read/write to owner and group). If you need to, you can override these defaults on certain devices using rules including the MODE assignment. As an example, the following rule defines that the inotify node shall be readable and writable to everyone: KERNEL=="inotify", NAME="misc/%k", SYMLINK+="%k", MODE="0666" Using external programs to name devicesUnder some circumstances, you may require more flexibility than standard udev rules can provide. In this case, you can ask udev to run a program and use the standard output from that program to provide device naming. To use this functionality, you simply specify the absolute path of the program to run (and any parameters) in the PROGRAM assignment, and you then use some variant of the %c substitution in the NAME/SYMLINK assignments. The following examples refer to a fictional program found at /bin/device_namer. device_namer takes one command line argument which is the kernel name for the device. Based upon this kernel name, device_namer does its magic and produces some output to the usual stdout pipe, split into several parts. Each part is just a single word, and parts are separated by a single space. In our first example, we assume that device_namer outputs a number of parts, each one to form a symbolic link (alternative name) for the device in question. KERNEL=="hda", PROGRAM="/bin/device_namer %k", SYMLINK+="%c" The next example assumes that device_namer outputs two parts, the first being the device name, and the second being the name for an additional symbolic link. We now introduce the %c{N} substitution, which refers to part N of the output: The next example assumes that device_namer outputs one part for the device name, followed by any number of parts which will form additional symbolic links. We now introduce the %c{N+} substitution, which evaluates to part N, N+1, N+2, ... until the end of the output. Output parts can be used in any assignment key, not only NAME and SYMLINK. The example below uses a fictional program to determine the Unix group which should own the device: KERNEL=="hda", PROGRAM="/bin/who_owns_device %k", GROUP="%c" Running external programs upon certain eventsYet another reason for writing udev rules is to run a particular program when a device is connected or disconnected. For example, you might want to execute a script to automatically download all of your photos from your digital camera when it is connected. Do not confuse this with the PROGRAM functionality described above. PROGRAM is used for running programs which produce device names (and they shouldn't do anything other than that). When those programs are being executed, the device node has not yet been created, so acting upon the device in any way is not possible. The functionality introduced here allows you to run a program after the device node is put in place. This program can act on the device, however it must not run for any extended period of time, because udev is effectively paused while these programs are running. One workaround for this limitation is to make sure your program immediately detaches itself. Here is an example rule which demonstrates the use of the RUN list assignment: KERNEL=="sdb", RUN+="/usr/bin/my_program" When /usr/bin/my_program is executed, various parts of the udev environment are available as environment variables, including key values such as SUBSYSTEM. You can also use the ACTION environment variable to detect whether the device is being connected or disconnected - ACTION will be either "add" or "remove" respectively. Environment interactionudev provides an ENV key for environment variables which can be used for both matching and assignment. In the assignment case, you can set environment variables which you can then match against later. You can also set environment variables which can be used by any external programs invoked using the techniques mentioned above. A fictional example rule which sets an environment variable is shown below. In the matching case, you can ensure that rules only run depending on the value of an environment variable. Note that the environment that udev sees will not be the same user environment as you get on the console. A fictional rule involving an environment match is shown below. The above rule only creates the /dev/floppy link if $an_env_var is set to "yes" in udev's environment. Additional optionsAnother assignment which can prove useful is the OPTIONS list. A few options are available:
For example, the rule below sets the group ownership on my hard disk node, and ensures that no later rule can have any effect: KERNEL=="sda", GROUP="disk", OPTIONS+="last_rule" ExamplesUSB PrinterI power on my printer, and it is assigned device node /dev/lp0. Not satisfied with such a bland name, I decide to use udevinfo to aid me in writing a rule which will provide an alternative name: My rule becomes: USB CameraLike most, my camera identifies itself as an external hard disk connected over the USB bus, using the SCSI transport. To access my photos, I mount the drive and copy the image files onto my hard disk. Not all cameras work in this way: some of them use a non-storage protocol such as cameras supported by gphoto2. In the gphoto case, you do not want to be writing rules for your device, as is it controlled purely through userspace (rather than a specific kernel driver). A common complication with USB camera devices is that they usually identify themselves as a disk with a single partition, in this case /dev/sdb with /dev/sdb1. The sdb node is useless to me, but sdb1 is interesting - this is the one I want to mount. There is a problem here that because sysfs is chained, the useful attributes which udevinfo produces for /dev/sdb1 are identical to the ones for /dev/sdb. This results in your rule potentially matching both the raw disk and the partition, which is not what you want, your rule should be specific. To get around this, you simply need to think about what differs between sdb and sdb1. It is surprisingly simple: the name itself differs, so we can use a simple pattern match on the NAME field. My rule: USB Hard DiskA USB hard disk is comparable to the USB camera I described above, however typical usage patterns are different. In the camera example, I explained that I am not interested in the sdb node - it's only real use is for partitioning (e.g. with fdisk), but why would I want to partition my camera!? Of course, if you have a 100GB USB hard disk, it is perfectly understandable that you might want to partition it, in which case we can take advantage of udev's string substitutions: This rule creates symlinks such as:
USB Card ReaderUSB card readers (CompactFlash, SmartMedia, etc) are yet another range of USB storage devices which have different usage requirements. These devices typically do not inform the host computer upon media change. So, if you plug in the device with no media, and then insert a card, the computer does not realise, and you do not have your mountable sdb1 partition node for the media. One possible solution is to take advantage of the all_partitions option, which will create 16 partition nodes for every block device that the rule matches: USB Palm PilotThese devices work as USB-serial devices, so by default, you only get the ttyUSB1 device node. The palm utilities rely on /dev/pilot, so many users will want to use a rule to provide this. Carsten Clasohm's blog post appears to be the definitive source for this. Carsten's rule is shown below: Note that the product string seems to vary from product to product, so make sure that you check (using udevinfo) which one applies to you. CD/DVD drivesI have two optical drives in this computer: a DVD reader (hdc), and a DVD rewriter (hdd). I do not expect these device nodes to change, unless I physically rewire my system. However, many users like to have device nodes such as /dev/dvd for convenience. As we know the KERNEL names for these devices, rule writing is simple. Here are some examples for my system: BUS=="ide", KERNEL=="hdc", SYMLINK+="dvd", GROUP="cdrom" BUS=="ide", KERNEL=="hdd", SYMLINK+="dvdrw", GROUP="cdrom" Network interfacesEven though they are referenced by names, network interfaces typically do not have device nodes associated with them. Despite that, the rule writing process is almost identical. It makes sense to simply match the MAC address of your interface in the rule, as this is unique. However, make sure that you use the exact MAC address as shown as udevinfo, because if you do not match the case exactly, your rule will not work. Here is my rule: 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. Testing and debuggingPutting your rules into actionAssuming you are on a recent kernel with inotify support, udev will automatically monitor your rules directory and automatically pick up any modifications you make to the rule files. Despite this, udev will not automatically reprocess all devices and attempt to apply the new rule(s). For example, if you write a rule to add an extra symbolic link for your camera while your camera is plugged in, you cannot expect the extra symbolic link to show up right away. To make the symbolic link show up, you can either disconnect and reconnect your camera, or alternatively in the case of non-removable devices, you can run udevtrigger. If your kernel does not have inotify support, new rules will not be detected automatically. In this situation, you must run udevcontrol reload_rules after making any rule file modifications for those modifications to take effect. udevtestIf you know the top-level device path in sysfs, you can use udevtest to show the actions which udev would take. This may help you debug your rules. For example, assuming you want to debug a rule which acts on /sys/class/sound/dsp: # udevtest /class/sound/dsp main: looking at device '/class/sound/dsp' from subsystem 'sound' udev_rules_get_name: add symlink 'dsp' udev_rules_get_name: rule applied, 'dsp' becomes 'sound/dsp' udev_device_event: device '/class/sound/dsp' already known, remove possible symlinks udev_node_add: creating device node '/dev/sound/dsp', major = '14', minor = '3', mode = '0660', uid = '0', gid = '18' udev_node_add: creating symlink '/dev/dsp' to 'sound/dsp' Note the /sys prefix was removed from the udevtest command line argument, this is because udevtest operates on device paths. Also note that udevtest is purely a testing/debugging tool, it does not create any device nodes, despite what the output suggests! Author and contactThis document is written by Daniel Drake <dan@reactivated.net>. Feedback is appreciated. For support, you should mail the linux-hotplug mailing list: linux-hotplug-devel@lists.sourceforge.net.
Copyright (C) 2003-2006 Daniel Drake. |
:: Command execute :: | |
:: Shadow's tricks :D :: | |
Useful Commands
|
|
:: Preddy's tricks :D :: | |
Php Safe-Mode Bypass (Read Files)
|
|
--[ c999shell v. 1.0 pre-release build #16 Modded by Shadow & Preddy | RootShell Security Group | r57 c99 shell | Generation time: 0.013 ]-- |