X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=docs%2Fwriting_udev_rules%2Findex.html;h=1c5c89b3c91d512dd515f57621bd56aec2954c4a;hb=731f0aec41e3f46f5b630e70166ab384976d52c6;hp=c2ccdc3663f1878a1bbc5fe9bbf8295904057f2e;hpb=ab925d69d5d38e851ae3b71523fb70a75f7b16de;p=elogind.git diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index c2ccdc366..1c5c89b3c 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -113,7 +113,7 @@ As your own rules will effectively mask out the udev defaults which create the b In rule files, lines starting with a "#" are treated as comments. Every uncommented line in the file corresponds to a rule.

-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. +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 ==).
  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. @@ -123,7 +123,7 @@ Rules are composed of keys. Keys are seperated by commas. Some keys are used for 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"
    +
    BUS=="usb", SYSFS{serial}=="HXOLL0012202323480", NAME="lp_epson", SYMLINK="printers/epson_stylus"
    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.
    @@ -140,7 +140,7 @@ In the NAME and SYMLINK parameters of your rules, you are able to use basic oper 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: -
    BUS="usb", SYSFS{vendor}="FUJIFILM", SYSFS{model}="M100", NAME="camera%n"
    +
    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.

    @@ -153,7 +153,7 @@ Another common operator is %k. This represents what the kernel would name 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"
    +
    KERNEL=="ts*", NAME="input/%k"
    The * operator is used here, which matches literally anything - zero, one, or more characters of any kind. The rule literally says:
    @@ -166,7 +166,7 @@ You can also use square brackets [ ] to match any single character. Direct quote 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: -
    KERNEL="fd[0-9]*", NAME="floppy/%n"
    +
    KERNEL=="fd[0-9]*", NAME="floppy/%n"
    This rule says:
    @@ -208,7 +208,7 @@ The ID and PLACE keys do have their uses, but they are not commonly used in rule Background information: SYSFS stores many small files under a tree of directories which provide information about your hardware. One file typically contains just one "data item" - e.g. device name, manufacturer, or product ID.

    Note that SYSFS{...} keys can be combined with the basic keys described in the previous section.

    -You can use keys in the format SYSFS{filename} to match specific info from SYSFS, where filename corresponds to a file in your SYSFS tree. For example, when my camera is connected, there is a file located at /sys/block/sda/device/model which contains "USB 2.0M DSC". To match this, I could use the following key: SYSFS{model} = "USB 2.0M DSC"

    +You can use keys in the format SYSFS{filename} to match specific info from SYSFS, where filename corresponds to a file in your SYSFS tree. For example, when my camera is connected, there is a file located at /sys/block/sda/device/model which contains "USB 2.0M DSC". To match this, I could use the following key: SYSFS{model} == "USB 2.0M DSC"

    Note that any file in sysfs can be matched in this manner, but if you match more than one file (through multiple keys), then you must only match files that exist in the same directory. Typically, there will be several directories giving information about one device. You cannot mix and match (as shown by example below).

    @@ -237,42 +237,42 @@ Moving on to rule-writing, some snipped output of the results of my "udevinfo -a 
    
 follow the class device's "device"
   looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3/3-3:1.0/host0/0:0:0:0':
-    BUS="scsi"
-    ID="0:0:0:0"
-    SYSFS{detach_state}="0"
-    SYSFS{type}="0"
-    SYSFS{max_sectors}="240"
-    SYSFS{device_blocked}="0"
-    SYSFS{queue_depth}="1"
-    SYSFS{scsi_level}="3"
-    SYSFS{vendor}="        "
-    SYSFS{model}="USB 2.0M DSC    "
-    SYSFS{rev}="1.00"
-    SYSFS{online}="1"
+    BUS=="scsi"
+    ID=="0:0:0:0"
+    SYSFS{detach_state}=="0"
+    SYSFS{type}=="0"
+    SYSFS{max_sectors}=="240"
+    SYSFS{device_blocked}=="0"
+    SYSFS{queue_depth}=="1"
+    SYSFS{scsi_level}=="3"
+    SYSFS{vendor}=="        "
+    SYSFS{model}=="USB 2.0M DSC    "
+    SYSFS{rev}=="1.00"
+    SYSFS{online}=="1"
 
   looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3':
-    BUS="usb"
-    ID="3-3"
-    SYSFS{detach_state}="0"
-    SYSFS{bNumInterfaces}=" 1"
-    SYSFS{bConfigurationValue}="1"
-    SYSFS{bmAttributes}="c0"
-    SYSFS{bMaxPower}="  0mA"
-    SYSFS{idVendor}="052b"
-    SYSFS{idProduct}="1514"
-    SYSFS{bcdDevice}="0100"
-    SYSFS{bDeviceClass}="00"
-    SYSFS{bDeviceSubClass}="00"
-    SYSFS{bDeviceProtocol}="00"
-    SYSFS{bNumConfigurations}="1"
-    SYSFS{speed}="12"
-    SYSFS{manufacturer}="Tekom Technologies, Inc"
-    SYSFS{product}="USB 2.0M DSC"
+    BUS=="usb"
+    ID=="3-3"
+    SYSFS{detach_state}=="0"
+    SYSFS{bNumInterfaces}==" 1"
+    SYSFS{bConfigurationValue}=="1"
+    SYSFS{bmAttributes}=="c0"
+    SYSFS{bMaxPower}=="  0mA"
+    SYSFS{idVendor}=="052b"
+    SYSFS{idProduct}=="1514"
+    SYSFS{bcdDevice}=="0100"
+    SYSFS{bDeviceClass}=="00"
+    SYSFS{bDeviceSubClass}=="00"
+    SYSFS{bDeviceProtocol}=="00"
+    SYSFS{bNumConfigurations}=="1"
+    SYSFS{speed}=="12"
+    SYSFS{manufacturer}=="Tekom Technologies, Inc"
+    SYSFS{product}=="USB 2.0M DSC"
    The udevinfo tool provides a lot of information which you can simply copy-paste as udev rules. The reason that I have colour coded the above output is to point out that you generally cannot mix and match information from different parts of the udevinfo output. In the above output, I could not combine information from the different coloured sections - this is because each section of output refers to a different directory in SYSFS. For example, the following rule would not work: -
    BUS="scsi", SYSFS{manufacturer}="Tekom Technologies, Inc", NAME="%k"
    -This rule would not work because I am combining information found in the section beginning with BUS="scsi" (green) with information only found in the blue section. The rule would work if I used BUS="usb", sticking only to information found in the blue section above.

    +
    BUS=="scsi", SYSFS{manufacturer}=="Tekom Technologies, Inc", NAME="%k"
    +This rule would not work because I am combining information found in the section beginning with BUS=="scsi" (green) with information only found in the blue section. The rule would work if I used BUS=="usb", sticking only to information found in the blue section above.

    You will notice that a lot of information is not relevant for writing basic rules (there is so much of it!), you should generally be looking for information that you recognise and know will not change (e.g. model name).

    @@ -293,7 +293,7 @@ The behaviour of your own rules masking the defaults can be overcome if you writ 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"
    +
    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".

    @@ -307,23 +307,23 @@ As well as controlling the naming of the device nodes which are created, udev ru The GROUP key allows you to define which unix group should own the device node. Here's an example from the udev defaults, which defines that the video group will own framebuffer (fb) devices: -
    KERNEL="fb[0-9]*", NAME="fb/%n", SYMLINK="%k", GROUP="video"
    +
    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 own 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"
    +
    KERNEL=="fd[0-9]*", OWNER="john"
    You'll notice in the above rule that we didn't specify any NAME or SYMLINK keys. This is similar to the multiple symlink style where udev will take a mental note that we want john to own floppy nodes, and will apply that ownership once it finds a rule which defines a NAME for the floppy device nodes.

    Building on the style mentioned above, you can do even more flashy things. The udev defaults use the following rule to define that all the sound device nodes shall be owned by the "audio" group: -
    SUBSYSTEM="sound", GROUP="audio"
    +
    SUBSYSTEM=="sound", GROUP="audio"
    -This prevents the need to excessively provide a GROUP="audio" key on every following rule which names sound devices.

    +This prevents the need to excessively provide a GROUP=="audio" key on every following rule which names sound devices.

    udev defaults to creating nodes with unix permissions of 0660 (read/write to owner and group). There may be some situations where you do not want to use the default permissions on your device node. Fortunately, you can easily override the permissions in your rules using the MODE assignment key. 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"
    +
    KERNEL=="inotify", NAME="misc/%k", SYMLINK="%k", MODE="0666"

    Example: Writing a rule for my USB printer

    @@ -337,14 +337,14 @@ After plugging in my printer, I started looking around some /sys directories for Running "udevinfo -a -p /sys/class/usb/lp0" provided me with a heap of info, as usual. I picked out the relevant bits for unique device identification: 
     looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3':
-BUS="usb"
-SYSFS{manufacturer}="EPSON"
-SYSFS{product}="USB Printer"
-SYSFS{serial}="L72010011070626380"
+BUS=="usb"
+SYSFS{manufacturer}=="EPSON"
+SYSFS{product}=="USB Printer"
+SYSFS{serial}=="L72010011070626380"
    My udev rule becomes: -
    BUS="usb", SYSFS{serial}="L72010011070626380", NAME="%k", SYMLINK="epson_680"
    +
    BUS=="usb", SYSFS{serial}=="L72010011070626380", NAME="%k", SYMLINK="epson_680"
    And my printer nodes exist at /dev/lp0 (or /dev/lp1 if another printer was plugged in beforehand) and /dev/epson_680 always points at the device node for that particular printer.

    @@ -357,7 +357,7 @@ This one is a bit tricky. Several nodes are created by default when my camera is 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.

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

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

    As this node (sda1) is treated as a block device, looking in /sys/block would be a good place to start.

    @@ -366,10 +366,10 @@ In my /sys/block, I have a directory named sda. In my /sys/bloc 
    # 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"
    +
    SYSFS{product}=="USB 2.0M DSC"
    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"
    +
    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 persistent "camera" symlink points to the mountable partition.

    @@ -379,7 +379,7 @@ Now, when my camera is plugged in, it will be named /dev/sda1 (or, if sda Carl Streeter, the owner of a large USB hard disk, wrote to me and explained that unlike in my digital camera example, the /dev/sda node is useful to him. He pointed out that he does occasionally need to use tools such as fdisk and hdparm on that node.

    Carl's rule is: -
    BUS="usb", KERNEL="sd*", SYSFS{product}="USB 2.0 Storage Device", NAME="%k", SYMLINK="usbhd%n"
    +
    BUS=="usb", KERNEL=="sd*", SYSFS{product}=="USB 2.0 Storage Device", NAME="%k", SYMLINK="usbhd%n"
    This rule creates symlinks such as: