source: chapter09/networkd.xml@ c53ff08

<?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-config-network" revision="systemd">
  <?dbhtml filename="network.html"?>

  <title>General Network Configuration</title>

  <indexterm zone="ch-config-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>

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

    <para>Starting with version 209, systemd ships a network configuration
    daemon called <command>systemd-networkd</command> which can be used for
    basic network configuration. Additionally, since version 213, DNS name
    resolution can be handled by <command>systemd-resolved</command> in place
    of a static <filename>/etc/resolv.conf</filename> file. Both services are
    enabled by default.</para>

    <para>Configuration files for <command>systemd-networkd</command> (and
    <command>systemd-resolved</command>) can be placed in
    <filename class="directory">/usr/lib/systemd/network</filename>
    or <filename class="directory">/etc/systemd/network</filename>. Files in
    <filename class="directory">/etc/systemd/network</filename> have a
    higher priority than the ones in
    <filename class="directory">/usr/lib/systemd/network</filename>.
    There are three types of configuration files:
    <filename class="extension">.link</filename>,
    <filename class="extension">.netdev</filename> and
    <filename class="extension">.network</filename> files. For detailed
    descriptions and example contents of these configuration files, consult 
    the <filename>systemd-link(5)</filename>,
    <filename>systemd-netdev(5)</filename> and
    <filename>systemd-network(5)</filename> manual pages.</para>

    <sect3 id="systemd-network-devices">
      <title>Network Device Naming</title>

      <para>
        Udev normally assigns network card interface names based
        on physical system 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.
      </para>

      <para>
        For most systems, there is only one network interface for
        each type of connection.  For example, the classic interface
        name for a wired connection is eth0.  A wireless connection
        will usually have the name wifi0 or wlan0. 
      </para>

      <para>
        If you prefer to use the classic or customized network interface names,
        there are three alternative ways to do that:</para>

      <itemizedlist>
        <listitem>
          <para>
            Mask udev's .link file for the default policy:
<screen role="nodump"><userinput>ln -s /dev/null /etc/systemd/network/99-default.link</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>
             Create a manual naming scheme, for example by naming the
             interfaces something like "internet0", "dmz0", or "lan0". 
             To do that, create .link files in /etc/systemd/network/ that 
             select an explicit name or a better naming scheme for your
             network interfaces. For example:
          </para>

<screen role="nodump"><userinput>cat &gt; /etc/systemd/network/10-ether0.link &lt;&lt; "EOF"
<literal>[Match]
# Change the MAC address as appropriate for your network device
MACAddress=12:34:45:78:90:AB

[Link]
Name=ether0</literal>
EOF</userinput></screen>

          <para>
             See the man page systemd.link(5) for more information. 
          </para>
        </listitem>

        <listitem>
          <para>
            In /boot/grub/grub.cfg, pass the option net.ifnames=0 on the 
            kernel command line.
          </para>
        </listitem>
      </itemizedlist>
    </sect3>

    <sect3 id="systemd-networkd-static">
      <title>Static IP Configuration</title>

      <para>The command below creates a basic configuration file for a
      Static IP setup (using both systemd-networkd and
      systemd-resolved):</para>
<!-- jhalfs relies on the values for Name, Address, etc. If you want to change
     them, please inform the jhalfs maintainer(s). -->
<screen><userinput>cat &gt; /etc/systemd/network/10-eth-static.network &lt;&lt; "EOF"
<literal>[Match]
Name=<replaceable>&lt;network-device-name&gt;</replaceable>

[Network]
Address=192.168.0.2/24
Gateway=192.168.0.1
DNS=192.168.0.1
Domains=<replaceable>&lt;Your Domain Name&gt;</replaceable></literal>
EOF</userinput></screen>

      <para>Multiple DNS entries can be added if you have more than one DNS
      server. Do not include DNS or Domains entries if you intend to use a
      static <filename>/etc/resolv.conf</filename> file.</para>

    </sect3>

    <sect3 id="systemd-networkd-dhcp">
      <title>DHCP Configuration</title>

      <para>The command below creates a basic configuration file for an IPv4
      DHCP setup:</para>

<screen role="nodump"><userinput>cat &gt; /etc/systemd/network/10-eth-dhcp.network &lt;&lt; "EOF"
<literal>[Match]
Name=&lt;network-device-name&gt;

[Network]
DHCP=ipv4

[DHCP]
UseDomains=true</literal>
EOF</userinput></screen>

    </sect3>

  </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>.</para>

    <sect3 id="resolv-conf-systemd-resolved">
      <title>systemd-resolved Configuration</title>

      <note><para>If using methods incompatible with systemd-resolved to
      configure your network interfaces (ex: ppp, etc.), or if using any
      type of local resolver (ex: bind, dnsmasq, unbound, etc.),
      or any other software that generates an <filename>/etc/resolv.conf</filename>
      (ex: a <command>resolvconf</command> program other than the one
      provided by systemd), the <command>systemd-resolved</command> service
      should not be used.</para></note>

      <para>When using <command>systemd-resolved</command> for DNS
      configuration, it creates the file
      <filename>/run/systemd/resolve/resolv.conf</filename>. Create a
      symlink in <filename>/etc</filename> to use the generated file:</para>

<screen><userinput>ln -sfv /run/systemd/resolve/resolv.conf /etc/resolv.conf</userinput></screen>

    </sect3>

    <sect3 id="resolv-conf-static">
      <title>Static resolv.conf Configuration</title>

      <para>If a static <filename>/etc/resolv.conf</filename> is desired,
      create it by running the following command:</para>

<screen role="nodump"><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 server most appropriate for your 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. Another option
      is to use the Google Public DNS service using the IP addresses below as
      nameservers.</para>

      <note><para>The Google Public IPv4 DNS addresses are
      <parameter>8.8.8.8</parameter> and <parameter>8.8.4.4</parameter>
      for IPv4, and <parameter>2001:4860:4860::8888</parameter> and
      <parameter>2001:4860:4860::8844</parameter> for IPv6.</para></note>

    </sect3>

  </sect2>

  <sect2 id="ch-config-hostname">
    <title>Configuring the system hostname</title>

    <indexterm zone="ch-config-hostname">
      <primary sortas="d-hostname">hostname</primary>
      <secondary>configuring</secondary>
    </indexterm>

     <para>During the boot process, the file <filename>/etc/hostname</filename>
     is used for establishing the system's hostname.</para>

     <para>Create the <filename>/etc/hostname</filename> file and enter a
     hostname by running:</para>

<screen><userinput>echo "<replaceable>&lt;lfs&gt;</replaceable>" &gt; /etc/hostname</userinput></screen>

     <para><replaceable>&lt;lfs&gt;</replaceable> needs to be replaced with the
     name given to the computer. Do not enter the Fully Qualified Domain Name
     (FQDN) here. That information is put in the
     <filename>/etc/hosts</filename> file.</para>

  </sect2>

  <sect2 id="ch-config-hosts">
     <title>Customizing the /etc/hosts File</title>

     <indexterm zone="ch-config-hosts">
       <primary sortas="e-/etc/hosts">/etc/hosts</primary>
     </indexterm>
   
     <indexterm zone="ch-config-hosts">
       <primary sortas="d-localnet">localnet</primary>
       <secondary>/etc/hosts</secondary>
     </indexterm>
   
     <indexterm zone="ch-config-hosts">
       <primary sortas="d-network">network</primary>
       <secondary>/etc/hosts</secondary>
     </indexterm>

     <para>Decide on a fully-qualified domain name (FQDN), and possible aliases
     for use in the <filename>/etc/hosts</filename> file. If using static IP
     addresses, you'll also need to decide on an IP address. The syntax
     for a hosts file entry is:</para>

<screen><literal>IP_address myhost.example.org aliases</literal></screen>

     <para>Unless the computer is to be visible to the Internet (i.e., there is
     a registered domain and a valid block of assigned IP addresses&mdash;most
     users do not have this), make sure that the IP address is in the private
     network IP address range. Valid ranges are:</para>

<screen><literal>Private Network Address Range      Normal Prefix
10.0.0.1 - 10.255.255.254           8
172.x.0.1 - 172.x.255.254           16
192.168.y.1 - 192.168.y.254         24</literal></screen>

     <para>x can be any number in the range 16-31. y can be any number in the
     range 0-255.</para>

     <para>A valid private IP address could be 192.168.1.1. A valid FQDN for
     this IP could be lfs.example.org.</para>

     <para>Even if not using a network card, a valid FQDN is still required.
     This is necessary for certain programs, such as MTAs, to operate properly.</para>

<!--
     <para>Create the /etc/hosts file using the following command:</para>

<screen role="nodump"><userinput>cat &gt; /etc/hosts &lt;&lt; "EOF"
<literal># Begin /etc/hosts

127.0.0.1 localhost.localdomain localhost
127.0.1.1 <replaceable>&lt;FQDN&gt;</replaceable> <replaceable>&lt;HOSTNAME&gt;</replaceable>
::1       localhost ip6-localhost ip6-loopback
ff02::1   ip6-allnodes
ff02::2   ip6-allrouters

# End /etc/hosts</literal>
EOF</userinput></screen>
-->

     <para>Create the <filename>/etc/hosts</filename> file using the following
     command:</para>

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

127.0.0.1 localhost.localdomain localhost
127.0.1.1 <replaceable>&lt;FQDN&gt;</replaceable> <replaceable>&lt;HOSTNAME&gt;</replaceable>
<replaceable>&lt;192.168.0.2&gt;</replaceable> <replaceable>&lt;FQDN&gt;</replaceable> <replaceable>&lt;HOSTNAME&gt;</replaceable> <replaceable>[alias1] [alias2] ...</replaceable>
::1       localhost ip6-localhost ip6-loopback
ff02::1   ip6-allnodes
ff02::2   ip6-allrouters

# End /etc/hosts</literal>
EOF</userinput></screen>

     <para>The <replaceable>&lt;192.168.0.2&gt;</replaceable>,
     <replaceable>&lt;FQDN&gt;</replaceable>, and
     <replaceable>&lt;HOSTNAME&gt;</replaceable> values need to be
     changed for specific uses or requirements (if assigned an IP address by a
     network/system administrator and the machine will be connected to an
     existing network). The optional alias name(s) can be omitted, and the
     <replaceable>&lt;192.168.0.2</replaceable> line can be omitted if you
     are using a connection configured with DHCP or IPv6 Autoconfiguration.</para>

     <para>The ::1 entry is the IPv6 counterpart of 127.0.0.1 and represents
     the IPv6 loopback interface. 127.0.1.1 is a loopback entry reserved
     specifically for the FQDN.</para>

   </sect2>

</sect1>