symlinks.xml 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294
  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  4. <!ENTITY % general-entities SYSTEM "../general.ent">
  5. %general-entities;
  6. ]>
  7. <sect1 id="ch-scripts-symlinks">
  8. <?dbhtml filename="symlinks.html"?>
  9. <title>Managing Devices</title>
  10. <sect2>
  11. <title>Network Devices</title>
  12. <para>Udev, by default, names network devices according to Firmware/BIOS
  13. data or physical characteristics like the bus, slot, or MAC address. The
  14. purpose of this naming convention is to ensure that network devices are
  15. named consistently and not based on the time the network card was
  16. discovered. For example, on a computer having two network cards made by
  17. Intel and Realtek, the network card manufactured by Intel may become eth0
  18. and the Realtek card becomes eth1. In some cases, after a reboot the cards
  19. get renumbered the other way around.</para>
  20. <para>In the new naming scheme, typical network device names would then
  21. be something like enp5s0 or wlp3s0. If this naming convention is not
  22. desired, the traditional naming scheme or a custom scheme can be
  23. implemented.</para>
  24. <sect3>
  25. <title>Disabling Persistent Naming on the Kernel Command Line</title>
  26. <para>The traditional naming scheme using eth0, eth1, etc can be
  27. restored by adding <userinput>net.ifnames=0</userinput> on the
  28. kernel command line. This is most appropriate for those systems
  29. that have only one ethernet device of the same type. Laptops
  30. often have multiple ethernet connections that are named eth0 and
  31. wlan0 and are also candidates for this method. The command line
  32. is passed in the GRUB configuration file.
  33. See <xref linkend="grub-cfg"/>.</para>
  34. </sect3>
  35. <sect3>
  36. <title>Creating Custom Udev Rules</title>
  37. <para>The naming scheme can be customized by creating custom Udev
  38. rules. A script has been included that generates the initial rules.
  39. Generate these rules by running:</para>
  40. <screen role="install"><userinput>bash /lib/udev/init-net-rules.sh</userinput></screen>
  41. <para> Now, inspect the
  42. <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> file, to
  43. find out which name was assigned to which network device:</para>
  44. <screen role="nodump"><userinput>cat /etc/udev/rules.d/70-persistent-net.rules</userinput></screen>
  45. <note><para>In some cases such as when MAC addresess have been assigned to
  46. a network card manually or in a virtual environment such as Qemu or Xen,
  47. the network rules file may not have been generated because addresses
  48. are not consistently assigned. In these cases, this method cannot
  49. be used.</para></note>
  50. <para>The file begins with a comment block followed by two lines for each
  51. NIC. The first line for each NIC is a commented description showing its
  52. hardware IDs (e.g. its PCI vendor and device IDs, if it's a PCI card),
  53. along with its driver in parentheses, if the driver can be found. Neither
  54. the hardware ID nor the driver is used to determine which name to give an
  55. interface; this information is only for reference. The second line is the
  56. Udev rule that matches this NIC and actually assigns it a name.</para>
  57. <para>All Udev rules are made up of several keys, separated by commas and
  58. optional whitespace. This rule's keys and an explanation of each of them
  59. are as follows:</para>
  60. <itemizedlist>
  61. <listitem>
  62. <para><literal>SUBSYSTEM=="net"</literal> - This tells Udev to ignore
  63. devices that are not network cards.</para>
  64. </listitem>
  65. <listitem>
  66. <para><literal>ACTION=="add"</literal> - This tells Udev to ignore this
  67. rule for a uevent that isn't an add ("remove" and "change" uevents also
  68. happen, but don't need to rename network interfaces).</para>
  69. </listitem>
  70. <listitem>
  71. <para><literal>DRIVERS=="?*"</literal> - This exists so that Udev will
  72. ignore VLAN or bridge sub-interfaces (because these sub-interfaces do
  73. not have drivers). These sub-interfaces are skipped because the name
  74. that would be assigned would collide with their parent devices.</para>
  75. </listitem>
  76. <listitem>
  77. <para><literal>ATTR{address}</literal> - The value of this key is the
  78. NIC's MAC address.</para>
  79. </listitem>
  80. <listitem>
  81. <para><literal>ATTR{type}=="1"</literal> - This ensures the rule only
  82. matches the primary interface in the case of certain wireless drivers,
  83. which create multiple virtual interfaces. The secondary interfaces are
  84. skipped for the same reason that VLAN and bridge sub-interfaces are
  85. skipped: there would be a name collision otherwise.</para>
  86. </listitem>
  87. <listitem>
  88. <para><literal>NAME</literal> - The value of this key is the name that
  89. Udev will assign to this interface.</para>
  90. </listitem>
  91. </itemizedlist>
  92. <para>The value of <literal>NAME</literal> is the important part. Make sure
  93. you know which name has been assigned to each of your network cards before
  94. proceeding, and be sure to use that <literal>NAME</literal> value when
  95. creating your configuration files below.</para>
  96. </sect3>
  97. <!--
  98. <sect3>
  99. <title>Custom Naming in Systemd</title>
  100. <para>Network interface names can also be customized with a set of
  101. files spcific to systemd. A file with a name such as 10-eth0.link
  102. in the /etc/systemd/network directory can set an interface name. All
  103. files in the directory will be applied in lexical order. Files
  104. in the /lib/systemd/network directory with the same name as those
  105. in /etc/systemd/network will be overridden. See the man page
  106. for systemd.link for a full explanation.</para>
  107. <para>An example file looks like:</para>
  108. <screen role="nodump">[Match]
  109. MACAddress=12:34:56:78:9a:bc
  110. Driver=brcmsmac
  111. Path=pci-0000:02:00.0-*
  112. Type=wlan
  113. Virtualization=no
  114. Host=my-laptop
  115. Architecture=x86-64
  116. [Link]
  117. Name=wireless0
  118. MTUBytes=1450
  119. BitsPerSecond=10M
  120. WakeOnLan=magic
  121. MACAddress=cb:a9:87:65:43:21</screen>
  122. <para>The [Match] section specifies when to apply the rule. In
  123. the example above, the entries can be shortened to the minimum
  124. needed to uniquely identify the network device. Similarly,
  125. the [Link] section only needs to specify the changes from the
  126. default that are desired. In many cases, the only thing needed is
  127. the Name entry.</para>
  128. </sect3>
  129. -->
  130. </sect2>
  131. <sect2>
  132. <title>CD-ROM symlinks</title>
  133. <para>Some software that you may want to install later (e.g., various
  134. media players) expect the <filename class="symlink">/dev/cdrom</filename>
  135. and <filename class="symlink">/dev/dvd</filename> symlinks to exist, and
  136. to point to a CD-ROM or DVD-ROM device. Also, it may be convenient to put
  137. references to those symlinks into <filename>/etc/fstab</filename>. Udev
  138. comes with a script that will generate rules files to create these symlinks
  139. for you, depending on the capabilities of each device, but you need to
  140. decide which of two modes of operation you wish to have the script use.</para>
  141. <para>First, the script can operate in <quote>by-path</quote> mode (used by
  142. default for USB and FireWire devices), where the rules it creates depend on
  143. the physical path to the CD or DVD device. Second, it can operate in
  144. <quote>by-id</quote> mode (default for IDE and SCSI devices), where the
  145. rules it creates depend on identification strings stored in the CD or DVD
  146. device itself. The path is determined by Udev's <command>path_id</command>
  147. script, and the identification strings are read from the hardware by its
  148. <command>ata_id</command> or <command>scsi_id</command> programs, depending
  149. on which type of device you have.</para>
  150. <para>There are advantages to each approach; the correct approach to use
  151. will depend on what kinds of device changes may happen. If you expect the
  152. physical path to the device (that is, the ports and/or slots that it plugs
  153. into) to change, for example because you plan on moving the drive to a
  154. different IDE port or a different USB connector, then you should use the
  155. <quote>by-id</quote> mode. On the other hand, if you expect the device's
  156. identification to change, for example because it may die, and you would
  157. replace it with a different device with the same capabilities and which
  158. is plugged into the same connectors, then you should use the
  159. <quote>by-path</quote> mode.</para>
  160. <para>If either type of change is possible with your drive, then choose a
  161. mode based on the type of change you expect to happen more often.</para>
  162. <!-- If you use by-id mode, the symlinks will survive even the transition
  163. to libata for IDE drives, but that is not for the book. -->
  164. <important><para>External devices (for example, a USB-connected CD drive)
  165. should not use by-path persistence, because each time the device is plugged
  166. into a new external port, its physical path will change. All
  167. externally-connected devices will have this problem if you write Udev rules
  168. to recognize them by their physical path; the problem is not limited to CD
  169. and DVD drives.</para></important>
  170. <para>If you wish to see the values that the Udev scripts will use, then
  171. for the appropriate CD-ROM device, find the corresponding directory under
  172. <filename class="directory">/sys</filename> (e.g., this can be
  173. <filename class="directory">/sys/block/hdd</filename>) and
  174. run a command similar to the following:</para>
  175. <screen role="nodump"><userinput>udevadm test /sys/block/hdd</userinput></screen>
  176. <para>Look at the lines containing the output of various *_id programs.
  177. The <quote>by-id</quote> mode will use the ID_SERIAL value if it exists and
  178. is not empty, otherwise it will use a combination of ID_MODEL and
  179. ID_REVISION. The <quote>by-path</quote> mode will use the ID_PATH value.</para>
  180. <para>If the default mode is not suitable for your situation, then the
  181. following modification can be made to the
  182. <filename>/etc/udev/rules.d/83-cdrom-symlinks.rules</filename> file,
  183. as follows (where <replaceable>mode</replaceable> is one of
  184. <quote>by-id</quote> or <quote>by-path</quote>):</para>
  185. <screen role="nodump"><userinput>sed -i -e 's/"write_cd_rules"/"write_cd_rules <replaceable>mode</replaceable>"/' \
  186. /etc/udev/rules.d/83-cdrom-symlinks.rules</userinput></screen>
  187. <para>Note that it is not necessary to create the rules files or symlinks
  188. at this time, because you have bind-mounted the host's
  189. <filename class="directory">/dev</filename> directory into the LFS system,
  190. and we assume the symlinks exist on the host. The rules and symlinks will
  191. be created the first time you boot your LFS system.</para>
  192. <para>However, if you have multiple CD-ROM devices, then the symlinks
  193. generated at that time may point to different devices than they point to on
  194. your host, because devices are not discovered in a predictable order. The
  195. assignments created when you first boot the LFS system will be stable, so
  196. this is only an issue if you need the symlinks on both systems to point to
  197. the same device. If you need that, then inspect (and possibly edit) the
  198. generated <filename>/etc/udev/rules.d/70-persistent-cd.rules</filename>
  199. file after booting, to make sure the assigned symlinks match what you need.</para>
  200. </sect2>
  201. <sect2>
  202. <title>Dealing with duplicate devices</title>
  203. <para>As explained in <xref linkend="ch-scripts-udev"/>, the order in
  204. which devices with the same function appear in
  205. <filename class="directory">/dev</filename> is essentially random.
  206. E.g., if you have a USB web camera and a TV tuner, sometimes
  207. <filename>/dev/video0</filename> refers to the camera and
  208. <filename>/dev/video1</filename> refers to the tuner, and sometimes
  209. after a reboot the order changes to the opposite one.
  210. For all classes of hardware except sound cards and network cards, this is
  211. fixable by creating Udev rules for custom persistent symlinks.
  212. The case of network cards is covered separately in
  213. <xref linkend="ch-scripts-network"/>, and sound card configuration can
  214. be found in <ulink url="&blfs-book;postlfs/devices.html">BLFS</ulink>.</para>
  215. <para>For each of your devices that is likely to have this problem
  216. (even if the problem doesn't exist in your current Linux distribution),
  217. find the corresponding directory under
  218. <filename class="directory">/sys/class</filename> or
  219. <filename class="directory">/sys/block</filename>.
  220. For video devices, this may be
  221. <filename
  222. class="directory">/sys/class/video4linux/video<replaceable>X</replaceable></filename>.
  223. Figure out the attributes that identify the device uniquely (usually,
  224. vendor and product IDs and/or serial numbers work):</para>
  225. <screen role="nodump"><userinput>udevadm info -a -p /sys/class/video4linux/video0</userinput></screen>
  226. <para>Then write rules that create the symlinks, e.g.:</para>
  227. <screen role="nodump"><userinput>cat &gt; /etc/udev/rules.d/83-duplicate_devs.rules &lt;&lt; "EOF"
  228. <literal>
  229. # Persistent symlinks for webcam and tuner
  230. KERNEL=="video*", ATTRS{idProduct}=="1910", ATTRS{idVendor}=="0d81", \
  231. SYMLINK+="webcam"
  232. KERNEL=="video*", ATTRS{device}=="0x036f", ATTRS{vendor}=="0x109e", \
  233. SYMLINK+="tvtuner"
  234. </literal>
  235. EOF</userinput></screen>
  236. <para>The result is that <filename>/dev/video0</filename> and
  237. <filename>/dev/video1</filename> devices still refer randomly to the tuner
  238. and the web camera (and thus should never be used directly), but there are
  239. symlinks <filename>/dev/tvtuner</filename> and
  240. <filename>/dev/webcam</filename> that always point to the correct
  241. device.</para>
  242. </sect2>
  243. </sect1>