Changeset 7924

Show
Ignore:
Timestamp:
02/17/07 17:40:32 (1 year ago)
Author:
bryan
Message:

Use upstream Udev rule_generator setup for NIC naming; fixes #1912. Also fix a validation error in r7923.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/BOOK/chapter01/changelog.xml

    r7923 r7924  
    4141      <itemizedlist> 
    4242        <listitem> 
     43          <para>[bryan] - Use upstream's rule_generator rules exclusively for 
     44          NIC naming, and generate the rules before configuring the network 
     45          script, so the user knows what NIC names to use.</para> 
     46        </listitem> 
     47        <listitem> 
    4348          <para>[bryan] - Change from writing CD symlink rules files directly 
    4449          to configuring the file installed by Udev's rule_generator. Fixes 

  • trunk/BOOK/chapter07/network.xml

    r7854 r7924  
    2727    <title>Creating stable names for network interfaces</title> 
    2828 
    29     <para>Instructions in this section are optional if you have only one 
    30     network card.</para> 
    31  
    3229    <para>With Udev and modular network drivers, the network interface numbering 
    3330    is not persistent across reboots by default, because the drivers are loaded 
    …… 
    3734    Realtek card becomes  <filename class="devicefile">eth1</filename>. In some 
    3835    cases, after a reboot the cards get renumbered the other way around. To 
    39     avoid this, create Udev rules that assign stable names to network cards 
    40     based on their MAC addresses or bus positions.</para> 
     36    avoid this, Udev comes with a script and some rules to assign stable names 
     37    to network cards based on their MAC address.</para> 
    4138 
    42     <para>If you are going to use MAC addresses to identify your network 
    43     cards, find the addresses with the following command:</para> 
     39    <para>Pre-generate the rules to ensure the same names get assigned to the 
     40    same devices at every boot, including the first:</para> 
    4441 
    45 <screen role="nodump"><userinput>grep -H . /sys/class/net/*/address</userinput></screen> 
     42<screen><userinput>/lib/udev/write_net_rules all_interfaces</userinput></screen> 
    4643 
    47     <para>For each network card (but not for the loopback interface), 
    48     invent a descriptive name, such as <quote>realtek</quote>, and create 
    49     Udev rules similar to the following:</para> 
     44    <para>Now, inspect the <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> 
     45    file, to find out which name was assigned to which network device:</para> 
    5046 
    51 <screen role="nodump"><userinput>cat &gt; /etc/udev/rules.d/70-persistent-net.rules &lt;&lt; EOF 
    52 <literal>ACTION=="add", SUBSYSTEM=="net", SYSFS{address}=="<replaceable>00:e0:4c:12:34:56</replaceable>", \ 
    53     NAME="<replaceable>realtek</replaceable>" 
    54 ACTION=="add", SUBSYSTEM=="net", SYSFS{address}=="<replaceable>00:a0:c9:78:9a:bc</replaceable>", \ 
    55     NAME="<replaceable>intel</replaceable>"</literal> 
    56 EOF</userinput></screen> 
     47<screen><userinput>cat /etc/udev/rules.d/70-persistent-net.rules</userinput></screen> 
    5748 
    58 <!-- Yes, I know that VLANs are beyond BLFS. This is not the reason to get them 
    59      incorrect by default when every distro does this right. --> 
     49    <para>Each NIC takes up two lines in the file. The first line is a 
     50    description of the NIC itself, showing its hardware IDs (e.g. its PCI 
     51    vendor and device IDs, if it's a PCI card), along with its driver in 
     52    parentheses, if the driver can be found. This line is a comment; neither 
     53    the hardware ID nor the driver is used to determine which name to give an 
     54    interface. The second line is the Udev rule that matches this NIC and 
     55    actually assigns it a name.</para> 
    6056 
    61     <note> 
    62       <para>Be aware that Udev does not recognize the backslash for line 
    63       continuation.  The examples in this book work properly because both 
    64       the backslash and newline are ignored by the shell.  This makes the 
    65       shell send each rule to cat on only one line.  (The shell ignores 
    66       this sequence because the EOF string used in the here-document 
    67       redirection is not enclosed in either double or single quotes.  For 
    68       more details, see the bash(1) manpage, and search it for "Here 
    69       Documents".)</para> 
    70       <para>If modifying Udev rules with an editor, be sure to leave each 
    71       rule on one physical line.</para> 
    72     </note> 
     57    <para>All Udev rules are made up of several keys, separated by commas and 
     58    optional whitespace. This rule's keys and an explanations of each of them 
     59    are as follows:</para> 
    7360 
    74     <para>If you are going to use the bus position as the key, find the 
    75     position of each card with the following commands:</para> 
    76  
    77 <screen role="nodump"><userinput>for dir in /sys/class/net/* ; do 
    78     [ -e $dir/device ] &amp;&amp; { 
    79         basename $dir ; readlink -f $dir/device 
    80     } 
    81 done</userinput></screen> 
    82  
    83     <para>This will yield output similar to:</para> 
    84  
    85 <screen role="nodump"><userinput><replaceable>eth0</replaceable> 
    86 /sys/devices/pci0000:00/<replaceable>0000:00:0c.0</replaceable> 
    87 <replaceable>eth1</replaceable> 
    88 /sys/devices/pci0000:00/<replaceable>0000:00:0d.0</replaceable></userinput></screen> 
    89  
    90     <para>In this example, <replaceable>eth0</replaceable> has PCI bus position 
    91     <replaceable>0000:00:0c.0</replaceable> (domain 0000, bus 00, device 0c, 
    92     function 0), and <replaceable>eth1</replaceable> has PCI bus position 
    93     <replaceable>0000:00:0d.0</replaceable> (domain 0000, bus 00, device 0d, 
    94     function 0).</para> 
    95    
    96     <para>Now create Udev rules similar to the following:</para> 
    97  
    98 <screen role="nodump"><userinput>cat &gt; /etc/udev/rules.d/70-persistent-net.rules &lt;&lt; EOF 
    99 <literal>ACTION=="add", SUBSYSTEM=="net", BUS=="<replaceable>pci</replaceable>", KERNELS=="<replaceable>0000:00:0c.0</replaceable>", \ 
    100     NAME="<replaceable>realtek</replaceable>" 
    101 ACTION=="add", SUBSYSTEM=="net", BUS=="<replaceable>pci</replaceable>", KERNELS=="<replaceable>0000:00:0d.0</replaceable>", \ 
    102     NAME="<replaceable>intel</replaceable>"</literal> 
    103 EOF</userinput></screen> 
    104  
    105     <para>Udev has installed a rule_generator rules file that uses MAC 
    106     addresses, not bus positions.  Rules generated by this file will conflict 
    107     with the rules you just created, so delete the file:</para> 
    108  
    109 <screen role="nodump"><userinput>rm /etc/udev/rules.d/75-persistent-net-generator.rules</userinput></screen> 
    110  
    111     <note> 
    112       <para>You will also have to remember to create a new bus-position-based 
    113       rule each time you plug in an additional network card.  In a MAC address 
    114       based persistence scheme, the rule_generator rules file would do this 
    115       automatically.</para> 
    116     </note> 
    117  
    118     <para>Regardless of which method you use, these rules will always rename 
    119     the network cards to <quote>realtek</quote> and <quote>intel</quote>, 
    120     independently of the original numbering provided by the kernel (i.e.: the 
    121     original <quote>eth0</quote> and <quote>eth1</quote> interfaces will no 
    122     longer exist, unless you put such <quote>descriptive</quote> names in the 
    123     NAME key). Use the descriptive names from the Udev rules instead of 
    124     <quote>eth0</quote> in the network interface configuration files 
    125     below.</para> 
    126  
    127     <para>Note that the rules above don't work for every setup. For example, 
    128     MAC-based rules break when bridges or VLANs are used, because bridges and 
    129     VLANs have the same MAC address as the network card. One wants to rename 
    130     only the network card interface, not the bridge or VLAN interface, but the 
    131     example rule matches both. If you use such virtual interfaces, you have two 
    132     potential solutions. One is to add the DRIVER=="?*" key after 
    133     SUBSYSTEM=="net" in MAC-based rules which will stop matching the virtual 
    134     interfaces.  This is known to fail with some older Ethernet cards because 
    135     they don't have the DRIVER variable in the uevent and thus the rule does 
    136     not match with such cards. Another solution is to switch to rules that use 
    137     the bus position as a key.</para> 
    138  
    139     <para>The second known non-working case is with wireless cards using the 
    140     MadWifi or HostAP drivers, because they create at least two interfaces with 
    141     the same MAC address and bus position. For example, the Madwifi driver 
    142     creates both an athX and a wifiX interface where X is a digit.  To 
    143     differentiate these interfaces, add an appropriate KERNEL parameter such as 
    144     KERNEL=="ath*" after SUBSYSTEM=="net".</para> 
    145  
    146     <para>There may be other cases where the rules above don't work. Currently, 
    147     bugs on this topic are still being reported to Linux distributions, and no 
    148     solution that covers every case is available.</para> 
     61    <itemizedlist> 
     62      <listitem> 
     63        <para><literal>SUBSYSTEM=="net"</literal> - This tells Udev to ignore 
     64        devices that are not network cards.</para> 
     65      </listitem> 
     66      <listitem> 
     67        <para><literal>DRIVERS=="?*"</literal> - This exists so that Udev will 
     68        ignore VLAN or bridge sub-interfaces (because these sub-interfaces do 
     69        not have drivers). These sub-interfaces are skipped because the name 
     70        that would be assigned would collide with their parent devices.</para> 
     71      </listitem> 
     72      <listitem> 
     73        <para><literal>ATTRS{type}=="1"</literal> - Optional. This key will 
     74        only be added if this NIC is a wireless NIC whose driver creates 
     75        multiple virtual interfaces; it ensures the rule only matches the 
     76        primary interface. The secondary interfaces are not matched for the 
     77        same reason that VLAN and bridge sub-interfaces are not matched: there 
     78        would be a name collision.</para> 
     79      </listitem> 
     80      <listitem> 
     81        <para><literal>ATTRS{address}</literal> - The value of this key is the 
     82        NIC's MAC address.</para> 
     83      </listitem> 
     84      <listitem> 
     85        <para><literal>NAME</literal> - The value of this key is the name that 
     86        Udev will assign to this interface.</para> 
     87      </listitem> 
     88    </itemizedlist> 
     89     
     90    <para>The value of <literal>NAME</literal> is the important part. Make sure 
     91    you know which name has been assigned to each of your network cards before 
     92    proceeding, and be sure to use that <literal>NAME</literal> value when 
     93    creating your configuration files below.</para> 
    14994 
    15095  </sect2> 

  • trunk/BOOK/chapter07/symlinks.xml

    r7923 r7924  
    5050     to libata for IDE drives, but that is not for the book. --> 
    5151 
    52     <important>External devices (for example, a USB-connected CD drive) should 
    53     not use by-path persistence, because each time the device is plugged into a 
    54     new external port, its physical path will change. All externally-connected 
    55     devices will have this problem if you write Udev rules to recognize them 
    56     by their physical path; the problem is not limited to CD and DVD drives.</important> 
     52    <important><para>External devices (for example, a USB-connected CD drive) 
     53    should not use by-path persistence, because each time the device is plugged 
     54    into a new external port, its physical path will change. All 
     55    externally-connected devices will have this problem if you write Udev rules 
     56    to recognize them by their physical path; the problem is not limited to CD 
     57    and DVD drives.</para></important> 
    5758 
    5859    <para>If you wish to see the values that the Udev scripts will use, then