glfs/networking/connect/dhcp.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;

  <!ENTITY dhcp-download-http "https://ftp.isc.org/isc/dhcp/&dhcp-version;/dhcp-&dhcp-version;.tar.gz">
  <!ENTITY dhcp-download-ftp  "ftp://ftp.isc.org/isc/dhcp/&dhcp-version;/dhcp-&dhcp-version;.tar.gz">
  <!ENTITY dhcp-md5sum        "3089a1ebd20a802ec0870ae337d43907">
  <!ENTITY dhcp-size          "9.4 MB">
  <!ENTITY dhcp-buildsize     "115 MB">
  <!ENTITY dhcp-time          "0.4 SBU">
]>

<sect1 id="dhcp" xreflabel="DHCP-&dhcp-version;">
  <?dbhtml filename="dhcp.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>DHCP-&dhcp-version;</title>

  <indexterm zone="dhcp">
    <primary sortas="a-DHCP">DHCP</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to ISC DHCP</title>

    <para>
      The <application>ISC DHCP</application> package contains both the client
      and server programs for DHCP. <command>dhclient</command> (the client) is
      used for connecting to a network which uses DHCP to assign network
      addresses. <command>dhcpd</command> (the server) is used for assigning
      network addresses on private networks.
    </para>

    &lfs101_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&dhcp-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&dhcp-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &dhcp-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &dhcp-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &dhcp-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &dhcp-time;
        </para>
      </listitem>
    </itemizedlist>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/dhcp-&dhcp-version;-client_script-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional patch:
          <ulink url="&patch-root;/dhcp-&dhcp-version;-missing_ipv6-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/dhcp"/>
    </para>
  </sect2>

  <sect2 role="kernel" id="dhcp-kernel">
    <title>Kernel Configuration</title>

    <para>
      You must have Packet Socket support.  IPv6 support is optional.
    </para>

<screen><literal>[*] Networking support ---&gt;        [CONFIG_NET]
      Networking options ---&gt;
        &lt;*&gt; Packet socket          [CONFIG_PACKET]
        &lt;*&gt; The IPv6 Protocol ---&gt; [CONFIG_IPV6]</literal></screen>
<!--
    <para>
      If you do not have IPv6 support:
    </para>

<screen><literal>[*] Networking support - - -&gt;          [CONFIG_NET]
      Networking Options - - -&gt;
        &lt;*&gt; The IPv6 Protocol - - -&gt;   [CONFIG_IPV6]</literal></screen>

    <para>
       compiled in, then you must use the <quote>missing_ipv6</quote> patch.
    </para>
-->
    <indexterm zone="dhcp dhcp-kernel">
      <primary sortas="d-DHCP">DHCP</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of ISC DHCP</title>

    <para>
      First, fix a build issue with GCC 10 and later:
    </para>

<screen><userinput>sed -i '/o.*dhcp_type/d' server/mdb.c &amp;&amp;
sed -r '/u.*(local|remote)_port/d'    \
    -i client/dhclient.c              \
       relay/dhcrelay.c</userinput></screen>

    <note>
      <para>
        This package does not support parallel build.
      </para>
    </note>
<!--  This should not be needed any more.  Visual check appears to handle it.
    <para>
      If you have not compiled IPv6 support into the kernel, apply the
      missing_ipv6 patch:
    </para>

<screen><userinput>patch -Np1 -i ../dhcp-&dhcp-version;-missing_ipv6-1.patch</userinput></screen>
-->
    <note>
      <para>
        Be careful with the instructions below. The single and
        double quotes are important because the defined
        variables are used verbatim in the code.
      </para>
    </note>

    <para>
      Install <application>ISC DHCP</application> by running
      the following commands:
    </para>

<!--
   Running ( export CFLAGS=... ./configure ... ) in a subshell
   preserves CFLAGS if they are set in environment
-->
<screen><userinput>( export CFLAGS="${CFLAGS:--g -O2} -Wall -fno-strict-aliasing                 \
        -D_PATH_DHCLIENT_SCRIPT='\"/usr/sbin/dhclient-script\"'     \
        -D_PATH_DHCPD_CONF='\"/etc/dhcp/dhcpd.conf\"'               \
        -D_PATH_DHCLIENT_CONF='\"/etc/dhcp/dhclient.conf\"'"        &amp;&amp;

./configure --prefix=/usr                                           \
            --sysconfdir=/etc/dhcp                                  \
            --localstatedir=/var                                    \
            --with-srv-lease-file=/var/lib/dhcpd/dhcpd.leases       \
            --with-srv6-lease-file=/var/lib/dhcpd/dhcpd6.leases     \
            --with-cli-lease-file=/var/lib/dhclient/dhclient.leases \
            --with-cli6-lease-file=/var/lib/dhclient/dhclient6.leases
) &amp;&amp;
make -j1</userinput></screen>

    <para>
      <!-- Note: make check builds a library, but otherwise does nothing. -->
      This package does not come with a test suite.
    </para>

    <para>
      If you only want to install the <application>ISC DHCP</application> client,
      issue the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make -C client install             &amp;&amp;
install -v -m755 client/scripts/linux /usr/sbin/dhclient-script</userinput></screen>

    <para>
      Skip to <xref linkend="dhclient-config"/> in order to configure the
      client
    </para>

    <para>
      If you only want to install the <application>ISC DHCP</application> server,
      issue the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make -C server install</userinput></screen>

    <para>
      Skip to <xref linkend="dhcpd-config"/> in order to configure the server.
    </para>

    <para>
      Alternatively, you can install whole package which includes the client,
      server, relay, static libraries and development headers by running the
      following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 client/scripts/linux /usr/sbin/dhclient-script</userinput></screen>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring ISC DHCP</title>

    <sect3 id="dhcp-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/dhcp/dhclient.conf</filename> and
        <filename>/etc/dhcp/dhcpd.conf</filename>
      </para>

      <indexterm zone="dhcp dhcp-config">
        <primary sortas="e-etc-dhcp-dhclient.conf">/etc/dhcp/dhclient.conf</primary>
      </indexterm>

      <indexterm zone="dhcp dhcp-config">
        <primary sortas="e-etc-dhcp-dhcpd.conf">/etc/dhcp/dhcpd.conf</primary>
      </indexterm>

    </sect3>

    <sect3 id="dhclient-config">
      <title>Client Configuration</title>

      <para>
        Create a basic <filename>/etc/dhcp/dhclient.conf</filename>
        by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>install -vdm755 /etc/dhcp &amp;&amp;
cat &gt; /etc/dhcp/dhclient.conf &lt;&lt; "EOF"
<literal># Begin /etc/dhcp/dhclient.conf
#
# Basic dhclient.conf(5)

#prepend domain-name-servers 127.0.0.1;
request subnet-mask, broadcast-address, time-offset, routers,
        domain-name, domain-name-servers, domain-search, host-name,
        netbios-name-servers, netbios-scope, interface-mtu,
        ntp-servers;
require subnet-mask, domain-name-servers;
#timeout 60;
#retry 60;
#reboot 10;
#select-timeout 5;
#initial-interval 2;

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

      <para>
        See <command>man 5 dhclient.conf</command> for additional options.
      </para>

      <para>
        Now create the <filename class="directory">/var/lib/dhclient</filename>
        directory which will contain DHCP Client leases by running the following
        command as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>install -v -dm 755 /var/lib/dhclient</userinput></screen>

      <para id="dhclient-service-sysd" revision="systemd">
        If you want to configure network interfaces at boot using
        <command>dhclient</command>, you need to install the
        <filename>dhclient@.service</filename> unit included in the
        <xref linkend="systemd-units"/> package by running the following
        command as the <systemitem class="username">root</systemitem> user:
      </para>

      <indexterm zone="dhcp dhclient-service-sysd" revision="systemd">
        <primary sortas="f-dhclient">dhclient@.service</primary>
      </indexterm>

<screen role="root" revision="systemd"><userinput>make install-dhclient</userinput></screen> 

      <note revision="systemd">
        <para>
          Make sure that you disable the <command>systemd-networkd</command>
          service or configure it not to manage the interfaces you want to
          manage with <command>dhclient</command>.
        </para>
      </note>

      <para>
        At this point you can test if <command>dhclient</command> is
        behaving as expected by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root" revision="sysv"><userinput>dhclient <replaceable>&lt;eth0&gt;</replaceable></userinput></screen>

<screen role="root" revision="systemd"><userinput>systemctl start dhclient@<replaceable>eth0</replaceable></userinput></screen>

      <para revision="sysv">
        Replace <replaceable>&lt;eth0&gt;</replaceable> with your
        desired interface. If you want more verbose output, add the
        <command>-v</command> parameter to the command above.
      </para>

      <para id="dhclient-service" revision="sysv">
        If you want to configure network interfaces at boot using
        <command>dhclient</command>, you need to install the
        <filename>/lib/services/dhclient</filename> script
        included in <xref linkend="bootscripts"/> package:
      </para>

<screen role="root" revision="sysv"><userinput>make install-service-dhclient</userinput></screen>

      <indexterm zone="dhcp dhclient-service" revision="sysv">
        <primary sortas="f-dhclient">dhclient (service script)</primary>
      </indexterm>

      <para id="dhclient-ifconfig" revision="sysv">
        Next, create the <filename>/etc/sysconfig/ifconfig.eth0</filename>
        configuration file with the following commands as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root" revision="sysv"><userinput>cat &gt; /etc/sysconfig/ifconfig.eth0 &lt;&lt; "EOF"
<literal>ONBOOT="yes"
IFACE="eth0"
SERVICE="dhclient"
DHCP_START=""
DHCP_STOP=""

# Set PRINTIP="yes" to have the script print
# the DHCP assigned IP address
PRINTIP="no"

# Set PRINTALL="yes" to print the DHCP assigned values for
# IP, SM, DG, and 1st NS. This requires PRINTIP="yes".
PRINTALL="no"</literal>
EOF</userinput></screen>

      <indexterm zone="dhcp dhclient-ifconfig" revision="sysv">
        <primary sortas="e-etc-sysconfig-...-dhclient">/etc/sysconfig/ifconfig.eth0</primary>
      </indexterm>

      <para revision="sysv">
        Adjust the file to suit your needs.
      </para>

      <para revision="sysv">
        For more information on the appropriate <envar>DHCP_START</envar>
        and <envar>DHCP_STOP</envar> values see
        <command>man 8 dhclient</command>.
      </para>

      <para revision="systemd">
        To start <command>dhclient</command> on a specific interface
        at boot, enable the previously installed systemd unit by
        running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root" revision="systemd"><userinput>systemctl enable dhclient@<replaceable>eth0</replaceable></userinput></screen>

      <para revision="systemd">
        Replace <replaceable>eth0</replaceable> with the actual interface name.
      </para>

    </sect3>

    <sect3 id="dhcpd-config">
      <title>Server Configuration</title>

      <para>
        Note that you only need the DHCP server if you want to issue
        LAN addresses over your network. The DHCP client doesn't need
        the server in order to function properly.
      </para>

      <para>
        Start with creating <filename>/etc/dhcp/dhcpd.conf</filename>
        by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>cat &gt; /etc/dhcp/dhcpd.conf &lt;&lt; "EOF"
<literal># Begin /etc/dhcp/dhcpd.conf
#
# Example dhcpd.conf(5)

# Use this to enable / disable dynamic dns updates globally.
ddns-update-style none;

# option definitions common to all supported networks...
option domain-name "example.org";
option domain-name-servers ns1.example.org, ns2.example.org;

default-lease-time 600;
max-lease-time 7200;

# This is a very basic subnet declaration.
subnet 10.254.239.0 netmask 255.255.255.224 {
  range 10.254.239.10 10.254.239.20;
  option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;
}

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

      <para>
        Adjust the file to suit your needs. See
        <command>man 5 dhcpd.conf</command> for additional options.
      </para>

      <para>
        Now create the <filename class="directory">/var/lib/dhcpd</filename>
        directory which will contain DHCP Server leases by running the following
        command as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>install -v -dm 755 /var/lib/dhcpd</userinput></screen>

       <para>
        If you want to start the DHCP Server at boot, install the
        <phrase revision="sysv"><filename>/etc/rc.d/init.d/dhcpd</filename>
        inti script</phrase>
        <phrase revision="systemd"><filename>dhcpd.service</filename>
        unit</phrase> included in the
        <xref linkend="bootscripts" revision="sysv"/>
        <xref linkend="systemd-units" revision="systemd"/>
        package:
      </para>

<screen role="root"><userinput>make install-dhcpd</userinput></screen>

      <indexterm zone="dhcp dhcpd-config">
        <primary sortas="f-dhcpd">dhcpd</primary>
      </indexterm>

      <para>
        You will need to edit the
        <phrase revision="sysv"><filename>/etc/sysconfig/dhcpd</filename></phrase>
        <phrase revision="systemd"><filename>/etc/default/dhcpd</filename></phrase>
        in order to set the interface on which <command>dhcpd</command>
        will serve the DHCP requests.
      </para>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          dhclient, dhclient-script, dhcpd, dhcrelay and omshell
        </seg>
        <seg>
          libdhcpctl.a and libomapi.a
        </seg>
        <seg>
          /etc/dhcp,
          /usr/include/dhcpctl,
          /usr/include/isc-dhcp,
          /usr/include/omapip,
          /var/lib/dhclient and
          /var/lib/dhcpd
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="dhclient">
        <term><command>dhclient</command></term>
        <listitem>
          <para>
            is the implementation of the DHCP client
          </para>
          <indexterm zone="dhcp dhclient">
            <primary sortas="b-dhclient">dhclient</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dhclient-script">
        <term><command>dhclient-script</command></term>
        <listitem>
          <para>
            is used by dhclient to (re)configure interfaces. It can make
            extra changes by invoking custom dhclient-{entry,exit}-hooks
          </para>
          <indexterm zone="dhcp dhclient-script">
            <primary sortas="b-dhclient-script">dhclient-script</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dhcpd">
        <term><command>dhcpd</command></term>
        <listitem>
          <para>
            implements Dynamic Host Configuration Protocol (DHCP) and
            Internet Bootstrap Protocol (BOOTP) requests for network
            addresses
          </para>
          <indexterm zone="dhcp dhcpd">
            <primary sortas="b-dhcpd">dhcpd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dhcrelay">
        <term><command>dhcrelay</command></term>
        <listitem>
          <para>
            provides a means to accept DHCP and BOOTP requests on a subnet
            without a DHCP server and relay them to a DHCP server on another
            subnet
          </para>
          <indexterm zone="dhcp dhcrelay">
            <primary sortas="b-dhcrelay">dhcrelay</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="omshell">
        <term><command>omshell</command></term>
        <listitem>
          <para>
            provides an interactive way to connect to, query and
            possibly change the ISC DHCP Server's state via OMAPI, the
            Object Management API
          </para>
          <indexterm zone="dhcp omshell">
            <primary sortas="b-omshell">omshell</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>