[PATCH] Writing udev rules doc update

[Daniel Drake <dan@reactivated.net>]

[-- Attachment #1: Type: text/plain, Size: 222 bytes --]

Hi,

Here's a patch to update the writing udev rules doc. Just a few 
corrections/improvements, updates to fit with the new default configuration, 
plus some information about naming network devices.

Please apply

Daniel

[-- Attachment #2: writing_udev_rules-0.54.patch --]
[-- Type: text/plain, Size: 11652 bytes --]

--- udev-bk/docs/writing_udev_rules/index.html.v0.53	2004-04-17 01:00:33.000000000 +0100
+++ udev-bk/docs/writing_udev_rules/index.html	2004-04-27 10:23:42.000000000 +0100
@@ -8,7 +8,7 @@
 
 <h1>Writing udev rules</h1>
 by Daniel Drake (dsd)<br />
-Version 0.53<br /><br />
+Version 0.54<br /><br />
 
 The most recent version of this document can always be found at: <br />
 <a href="http://www.reactivated.net/udevrules.php">http://www.reactivated.net/udevrules.php</a>
@@ -32,6 +32,7 @@
 
 <li><a href="#usbstorage-extra">Additional notes on writing rules for USB storage</a></li>
 <li><a href="#example-cdrom">Example: Writing convenience rules for my CD drives</a></li>
+<li><a href="#example-iface">Example: Writing a rule to name my network interface</a></li>
 <li><a href="#tips">Tips for finding the appropriate places in SYSFS</a></li>
 <li><a href="#nvidia">udev vs Nvidia's graphics drivers</a></li>
 <li><a href="#author">Author and credits</a></li>
@@ -51,20 +52,21 @@
 
 <h2>History</h2>
 
-April 15th 2004: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.<br /><br />
-April 14th 2004: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.<br /><br />
-April 6th 2004: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".<br /><br />
-April 3rd 2004: Minor cleanups and preparations for possible inclusion in the udev distribution.<br /><br />
-February 15th 2004: Initial publication.<br /><br />
-February 18th 2004: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section  on nvidia.<br /><br />
-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.<br /><br />
-March 20th 2004: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.<br /><br />
+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.<br /><br />
+April 15th 2004 v0.53: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.<br /><br />
+April 14th 2004 v0.52: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.<br /><br />
+April 6th 2004 v0.51: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".<br /><br />
+April 3rd 2004 v0.5: Minor cleanups and preparations for possible inclusion in the udev distribution.<br /><br />
+March 20th 2004 v0.4: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.<br /><br />
+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.<br /><br />
+February 18th 2004 v0.2: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.<br /><br />
+February 15th 2004 v0.1: Initial publication.<br /><br />
 
 <a name="versions"></a>
 <h2>Software versions used at time of writing</h2>
-Linux Kernel 2.6.5-rc3<br />
+Linux Kernel 2.6.5<br />
 
-udev 024</b><br />
+udev 025</b><br />
 hotplug 20040401<br /><br />
 
 <a name="terminology"></a>
@@ -99,11 +101,9 @@
 
 When populating <i>/dev</i>, 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.<br /><br />
 
-Default udev rules are stored in <i>/etc/udev/udev.rules</i>. 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, <b>above</b> the examples and default devfs-style rules.<br /><br />
+Default udev rules are stored in <i>/etc/udev/rules.d/50-udev.rules</i>. 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.<br /><br />
 
-<!-- Default udev rules are stored in <i>/etc/udev/udev.rules</i>. 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.<br /><br />
-
-Files in <i>/etc/udev</i> are parsed in <b>lexical</b> 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 <i>/etc/udev/local.rules</i> (this doesn't exist by default - create it). As L comes before U, you know that your rules will be looked at first.<br /><br /> -->
+Files in <i>/etc/udev/rules.d/</i> are parsed in <b>lexical</b> 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 <i>/etc/udev/rules.d/10-local.rules</i> (this doesn't exist by default - create it). As 10 comes before 50, you know that your rules will be looked at first.<br /><br />
 
 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.<br /><br />
 
@@ -349,7 +349,7 @@
 
 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:<br />
 
-<blockquote><pre>BUS="usb", SYSFS{product}="USB 2.0 Storage Device", NAME{all_partitions}="usbhd%n"</pre></blockquote>
+<blockquote><pre>BUS="usb", SYSFS{product}="USB 2.0 Storage Device", NAME{all_partitions}="usbhd"</pre></blockquote>
 
 You will now have nodes named: usbhd, usbhd1, usbhd2, usbhd3, ..., usbhd15.<br /><br />
 
@@ -359,13 +359,31 @@
 
 Still, some people (myself included) like to have nodes such as <i>/dev/dvd</i> and <i>/dev/cdrw</i> for convenience. Since we know the "hdX" values for these drives, writing rules is simple. The examples below should be self explanatory.
 
-
 <blockquote><pre>
 BUS="ide", KERNEL="hdc", NAME="%k", SYMLINK="dvd cdroms/cdrom%n"
 BUS="ide", KERNEL="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n"
 </pre></blockquote>
 
-<font size="2">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 <b>before</b> the default rules, so the default rules will not be used when naming the hardware you have written rules for.</font><br /><br />
+<font size="2">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 <b>before</b> the default rules, the defaults will not be used when naming the hardware you have written rules for.</font><br /><br />
+
+<a name="example-iface"></a>
+<h2>Example: Writing a rule to name my network interface</h2>
+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 <i>/dev</i>, but they are generally referenced by names (e.g. with <i>ifconfig</i>). Despite the differences, the rule writing process is almost identical.<br /><br />
+
+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):
+
+<blockquote><pre>
+# udevinfo -a -p /sys/class/net/eth0/
+  looking at class device '/sys/class/net/eth0':
+    SYSFS{address}="00:52:8b:d5:04:48"
+</pre></blockquote>
+
+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:
+
+<blockquote><pre>KERNEL="eth*", SYSFS{address}="00:52:8b:d5:04:48", NAME="lan"</pre></blockquote>
+
+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.<br />
+After that, you should be able to use "lan" instead of "eth0" in any calls to <i>ifconfig</i> or similar utilities.<br /><br />
 
 <a name="tips"></a>
 <h2>Tips for finding the appropriate places in SYSFS</h2>
@@ -390,7 +408,7 @@
 
 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 <i>nvidia</i> module is loaded by X, but the <i>/dev/nvidia*</i> nodes are not created quick enough, so X bails out.<br /><br />
 
-The solution to this problem is to autoload the <i>nvidia</i> module on bootup. Yes - you are *supposed* to do this - the <a href="ftp://download.nvidia.com/XFree86/Linux-x86/1.0-5336/README">NVidia FAQ</a> 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. <i>/etc/modules.autoload.d/kernel-2.6</i> for Gentoo).<br /><br />
+The solution to this problem is to autoload the <i>nvidia</i> module on bootup. Yes - you are *supposed* to do this - the <a href="ftp://download.nvidia.com/XFree86/Linux-x86/1.0-5336/README">NVidia FAQ</a> 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. <i>/etc/modules.autoload.d/kernel-2.6</i> for Gentoo, <i>/etc/modules</i> for Debian).<br /><br />
 
 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 <a href="http://marc.theaimsgroup.com/?l=linux-kernel&m=107564944926119&w=2">here</a>. The Gentoo package <i>nvidia-kernel-1.0.5336-r1</i> contains this patch.<br /><br />