path: root/chapter07/network.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-scripts-network">
  <?dbhtml filename="network.html"?>

  <title>General Network Configuration</title>

  <indexterm zone="ch-scripts-network">
    <primary sortas="d-network">network</primary>
  <secondary>configuring</secondary></indexterm>

  <para>This section only applies if a network card is to be
  configured.</para>

  <para>If a network card will not be used, there is likely no need to create
  any configuration files relating to network cards. If that is the case, you
  will need to remove the <filename class="symlink">network</filename> symlinks
  from all run-level directories (<filename
  class="directory">/etc/rc.d/rc*.d</filename>) after the bootscripts are
  installed in <xref linkend="ch-scripts-bootscripts"/>.</para>

  <sect2 id='stable-net-names'>
    <title>Creating stable names for network interfaces</title>

    <para>If there is only one network interface in the system to be
    configured, this section is optional, although it will never be wrong to do
    it.  In many cases (e.g. a laptop with a wireless and a wired interface),
    accomplishing the configuration in this section is necessary.</para>

    <para>With Udev and modular network drivers, the network interface numbering
    is not persistent across reboots by default, because the drivers are loaded
    in parallel and, thus, in random order. For example, on a computer having
    two network cards made by Intel and Realtek, the network card manufactured
    by Intel may become <filename class="devicefile">eth0</filename> and the
    Realtek card becomes  <filename class="devicefile">eth1</filename>. In some
    cases, after a reboot the cards get renumbered the other way around. To
    avoid this, Udev comes with a script and some rules to assign stable names
    to network cards based on their MAC address.</para>

    <para>If using the traditional network interface names such as eth0 is desired,
    generate a custom Udev rule:</para>

<screen><userinput>bash /lib/udev/init-net-rules.sh</userinput></screen>    

    <para> Now, inspect the
    <filename>/etc/udev/rules.d/70-persistent-net.rules</filename> file, to
    find out which name was assigned to which network device:</para>

<screen role="nodump"><userinput>cat /etc/udev/rules.d/70-persistent-net.rules</userinput></screen>

    <note><para>In some cases such as when MAC addresess have been assigned to
    a network card manually or in a virtual environment such as Xen,
    the network rules file may not have been generated because addresses
    are not consistently assigned.  In these cases, just continue to
    the next section.</para></note>

    <para>The file begins with a comment block followed by two lines for each
    NIC. The first line for each NIC is a commented description showing its
    hardware IDs (e.g. its PCI vendor and device IDs, if it's a PCI card),
    along with its driver in parentheses, if the driver can be found. Neither
    the hardware ID nor the driver is used to determine which name to give an
    interface; this information is only for reference. The second line is the
    Udev rule that matches this NIC and actually assigns it a name.</para>

    <para>All Udev rules are made up of several keys, separated by commas and
    optional whitespace. This rule's keys and an explanation of each of them
    are as follows:</para>

    <itemizedlist>
      <listitem>
        <para><literal>SUBSYSTEM=="net"</literal> - This tells Udev to ignore
        devices that are not network cards.</para>
      </listitem>
      <listitem>
        <para><literal>ACTION=="add"</literal> - This tells Udev to ignore this
        rule for a uevent that isn't an add ("remove" and "change" uevents also
        happen, but don't need to rename network interfaces).</para>
      </listitem>
      <listitem>
        <para><literal>DRIVERS=="?*"</literal> - This exists so that Udev will
        ignore VLAN or bridge sub-interfaces (because these sub-interfaces do
        not have drivers). These sub-interfaces are skipped because the name
        that would be assigned would collide with their parent devices.</para>
      </listitem>
      <listitem>
        <para><literal>ATTR{address}</literal> - The value of this key is the
        NIC's MAC address.</para>
      </listitem>
      <listitem>
        <para><literal>ATTR{type}=="1"</literal> - This ensures the rule only
        matches the primary interface in the case of certain wireless drivers,
        which create multiple virtual interfaces. The secondary interfaces are
        skipped for the same reason that VLAN and bridge sub-interfaces are
        skipped: there would be a name collision otherwise.</para>
      </listitem>
      <listitem>
        <para><literal>KERNEL=="eth*"</literal> - This key was added to the
        Udev rule generator to handle machines that have multiple network
        interfaces, all with the same MAC address (the PS3 is one such
        machine).  If the independent interfaces have different basenames,
        this key will allow Udev to tell them apart.  This is generally not
        necessary for most Linux From Scratch users, but does not hurt.</para>
      </listitem>
      <listitem>
        <para><literal>NAME</literal> - The value of this key is the name that
        Udev will assign to this interface.</para>
      </listitem>
    </itemizedlist>

    <para>The value of <literal>NAME</literal> is the important part. Make sure
    you know which name has been assigned to each of your network cards before
    proceeding, and be sure to use that <literal>NAME</literal> value when
    creating your configuration files below.</para>

  </sect2>

  <sect2>
    <title>Creating Network Interface Configuration Files</title>

    <para>Which interfaces are brought up and down by the network script
    depends on the files in <filename
    class="directory">/etc/sysconfig/</filename>.  This directory should
    contain a file for each interface to be configured, such as
    <filename>ifconfig.xyz</filename>, where <quote>xyz</quote> is required to
    be a Network Card Interface name (e.g. eth0).  Inside this file are
    attributes to this interface, such as its IP address(es), subnet masks, and
    so forth.  It is necessary that the stem of the filename be
    <emphasis>ifconfig</emphasis>.</para>

    <note><para>If the procedure in the previous section was not used, Udev
    will assign network card interface names based on system physical
    characteristics such as enp2s1. If you are not sure what your interface
    name is, you can always run <command>ip link</command>  after you have
    booted your system.  Again, it is important that ifconfig.xyz is named
    after correct network card interface name (e.g. ifconfig.enp2s1 or
    ifconfig.eth0) or your network interface will not be initialized during
    the boot process.</para></note>

    <para>The following command creates a sample file for the
    <emphasis>eth0</emphasis> device with a static IP address:</para>

<screen><userinput>cd /etc/sysconfig/
cat &gt; ifconfig.eth0 &lt;&lt; "EOF"
<literal>ONBOOT=yes
IFACE=eth0
SERVICE=ipv4-static
IP=192.168.1.2
GATEWAY=192.168.1.1
PREFIX=24
BROADCAST=192.168.1.255</literal>
EOF</userinput></screen>

    <para>The values of these variables must be changed in every file to match
    the proper setup.</para>

    <para>If the <envar>ONBOOT</envar> variable is set to <quote>yes</quote> the
    System V network script will bring up the Network Interface Card (NIC) during
    booting of the system. If set to anything but <quote>yes</quote> the NIC
    will be ignored by the network script and not be automatically brought up.
    The interface can be manually started or stopped with the
    <command>ifup</command> and <command>ifdown</command> commands.</para>

    <para>The <envar>IFACE</envar> variable defines the interface name,
    for example, eth0.  It is required for all network device configuration
    files. </para>

    <para>The <envar>SERVICE</envar> variable defines the method used for
    obtaining the IP address. The LFS-Bootscripts package has a modular IP
    assignment format, and creating additional files in the <filename
    class="directory">/lib/services/</filename> directory allows other IP
    assignment methods. This is commonly used for Dynamic Host Configuration
    Protocol (DHCP), which is addressed in the BLFS book.</para>

    <para>The <envar>GATEWAY</envar> variable should contain the default
    gateway IP address, if one is present. If not, then comment out the
    variable entirely.</para>

    <para>The <envar>PREFIX</envar> variable contains the number of
    bits used in the subnet. Each octet in an IP address is 8 bits. If the
    subnet's netmask is 255.255.255.0, then it is using the first three octets
    (24 bits) to specify the network number. If the netmask is 255.255.255.240,
    it would be using the first 28 bits.  Prefixes longer than 24 bits are
    commonly used by DSL and cable-based Internet Service Providers (ISPs).
    In this example (PREFIX=24), the netmask is 255.255.255.0. Adjust the
    <envar>PREFIX</envar> variable according to your specific subnet.
    If omitted, the PREFIX defaults to 24.</para>

    <para>For more information see the <command>ifup</command> man page.</para>

  </sect2>

  <sect2 id="systemd-net-enable">
    <title>Configuring the Network Interface Card at boot (systemd)</title>

    <para>Enabling of the network interface card configuration 
    in systemd is done per interface. To enable network interface card
    configuration at boot, run:</para>

<screen><userinput>systemctl enable ifupdown@eth0</userinput></screen>

    <para>To disable a previously enabled network interface
    card configuration at boot, run:</para>

<screen><userinput>systemctl disable ifupdown@eth0</userinput></screen>

    <para>To manually start the network interface card configuration,
    run:</para>

<screen><userinput>systemctl start ifupdown@eth0</userinput></screen>

    <para>Replace eth0 with the correct network interface card
    name as described on the beginning of this page.</para>

    <note><para>The network card can also be started or stopped
    with the traditional <command>ifup &lt;device&gt;</command> or
    <command>ifdown &lt;device&gt;</command> commands.</para></note>

  </sect2>

  <sect2 id="resolv.conf">
    <title>Creating the /etc/resolv.conf File</title>

    <indexterm zone="resolv.conf">
      <primary sortas="e-/etc/resolv.conf">/etc/resolv.conf</primary>
    </indexterm>

    <para>If the system is going to be connected to the Internet, it will
    need some means of Domain Name Service (DNS) name resolution to
    resolve Internet domain names to IP addresses, and vice versa. This is
    best achieved by placing the IP address of the DNS server, available
    from the ISP or network administrator, into
    <filename>/etc/resolv.conf</filename>. Create the file by running the
    following:</para>

<screen><userinput>cat &gt; /etc/resolv.conf &lt;&lt; "EOF"
<literal># Begin /etc/resolv.conf

domain <replaceable>&lt;Your Domain Name&gt;</replaceable>
nameserver <replaceable>&lt;IP address of your primary nameserver&gt;</replaceable>
nameserver <replaceable>&lt;IP address of your secondary nameserver&gt;</replaceable>

# End /etc/resolv.conf</literal>
EOF</userinput></screen>

    <para>The <varname>domain</varname> statement can be omitted
    or replaced with a <varname>search</varname> statement.  See the man page for
    resolv.conf for more details.</para>

    <para>Replace <replaceable>&lt;IP address of the nameserver&gt;</replaceable>
    with the IP address of the DNS most appropriate for the setup. There will
    often be more than one entry (requirements demand secondary servers for
    fallback capability). If you only need or want one DNS server, remove the
    second <emphasis>nameserver</emphasis> line from the file. The IP address
    may also be a router on the local network.</para>

    <note><para>The Google Public IPv4 DNS addresses are 8.8.8.8 and 8.8.4.4.</para></note>

  </sect2>

</sect1>