source: networking/connect/dhcp.xml@ ecc6758

<?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;
  <!-- isc have a weird way of offering the tarballs and without dots in version!
    FIXME - change hardcoded 423s in http url and version in ftp when upgrading -->
  <!ENTITY dhcp-download-http " ">
  <!ENTITY dhcp-download-ftp "ftp://ftp.isc.org/isc/dhcp/&dhcp-version;/dhcp-&dhcp-version;.tar.gz">
  <!ENTITY dhcp-md5sum "14f57fd580d01633d0fad4809007a801">
  <!ENTITY dhcp-size "9.1 MB">
  <!ENTITY dhcp-buildsize "192 MB (client and server), 140MB client only, 172MB server only">
  <!ENTITY dhcp-time "0.7 SBU (client and server, or server), 0.6 SBU client only ">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <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 DHCP</title>

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

    &lfs70_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>Recommended Patch (for client):
        <ulink url="&patch-root;/dhcp-&dhcp-version;-iproute2-1.patch"/></para>
      </listitem>
      <listitem>
        <para>Optional Patch:
        <ulink url="&patch-root;/dhcp-&dhcp-version;-missing_ipv6-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">DHCP Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="net-tools"/> is required at runtime
    by <command>dhclient</command> if you do not use the iproute2 patch.</para>

    <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 (Networking
    Support &rArr; Networking Options &rArr; Packet Socket) compiled into
    the kernel.  If you do not have IPv6 support (Networking Support &rArr;
    Networking Options &rArr; The IPv6 Protocol) compiled in, then you
    must use the missing_ipv6 patch.</para>

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

  </sect2>

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

    <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>

    <para>If you are installing the client, apply the iproute2 patch unless you
    will have installed <application>net-tools</application> by the time you wish
    to use the client:</para>

<screen><userinput>patch -Np1 -i ../dhcp-&dhcp-version;-iproute2-1.patch</userinput></screen>

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

<screen><userinput>sed -i 's%\(^sbindir =\).*%\1 @prefix@@sbindir@%' server/Makefile.in &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \
            --sbindir=/sbin                                      \
            --with-srv-lease-file=/var/state/dhcp/dhcpd.leases   \
            --with-srv6-lease-file=/var/state/dhcp/dhcpd6.leases \
            --with-cli-lease-file=/var/state/dhclient.leases     \
            --with-cli6-lease-file=/var/state/dhclient6.leases   &amp;&amp;
sed -i 's/-Werror//' {client,common,dst,omapip,relay,server,tests}/Makefile</userinput></screen>

    <para>If you only wish to build the server, enter:</para>
<screen><userinput>sed -i 's/ client//' Makefile</userinput></screen>

    <para>If you only wish to build the client, enter:</para>
<screen><userinput>sed -i 's/ dhcpctl relay server//' Makefile</userinput></screen>

    <para>Build your chosen variant(s) with:</para>
<screen><userinput>make</userinput></screen>

    <para>To test the results, issue: <command>make check</command></para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

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

    <para>The supplied <filename>/etc/dhcpd.conf</filename> (server) and
    <filename>/etc/dhclient.conf</filename> (client) are examples for a
    specific <literal>BSD</literal> system. They are unlikely to be appropriate
    to your needs, but you may wish to read them for ideas before deleting them
    or moving them to a different location.</para>

    <para>Now create any needed directories for the leases.</para>

    <para>For the server:</para>

<screen role="root"><userinput>mkdir -pv /var/state/dhcp</userinput></screen>

    <para>For the client:</para>
<screen role="root"><userinput>mkdir -pv /var/state</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>sed -i 's%\(^sbindir =\).*%\1 @prefix@@sbindir@%' server/Makefile.in</command>
    This command moves the <command>dhcp</command> program to
    <filename class='directory'>/usr/sbin</filename> instead of
    <filename class='directory'>/sbin</filename> because it is not needed
    while the server is booting.</para>

    <para><command>--sbindir=/sbin</command> The <command>dhclient</command>
    program is moved to <filename class='directory'>/sbin</filename> instead of
    <filename class='directory'>/usr/sbin</filename> so that it is available
    during boot, e.g. if <filename class='directory'>/usr</filename> is to be
    an <literal>nfs</literal> mount.</para>

    <para><command>--with-*-lease-files=...</command> By default, lease files
    are placed in <filename class='directory'>/var/db</filename> which is an
    anachronism.</para>

    <para><command>sed -i 's/-Werror//' {client,common,...}/Makefile</command> -
    the Makefiles in this package add <literal>-Werror</literal> to the
    <literal>CFLAGS</literal>.  On recent versions of <application>gcc</application>
    more things, particularly unused variables, create warnings.  The
    <literal>-Werror</literal> flag causes warnings to break the build, so we
    remove it where necessary.</para>

    <para><command>sed -i 's/ something//' Makefile</command> - this stops the
    build from entering the director(y,ies) named here.</para>

    <para><option>rm -v /usr/lib/lib{dhcpctl,dst,omapi}.a</option> - there is
    no easy way to prevent these static libraries being installed, but they are
    only needed during the build of this package. <filename>libdhcpctl.a</filename>
    is only installed if you build the server.</para>

  </sect2>

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

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

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

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

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

    </sect3>

    <sect3 id='dhcp-init'>
      <title>Configuration Information</title>

      <para>Information on configuring the DHCP client can be
      found in <xref linkend="basicnet-connect"/>.</para>

      <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 this
      script to be used.  Also note that this script is coded for the
      <emphasis role="strong">eth1</emphasis> interface, which may need
      to be modified for your hardware configuration.</para>

      <para>Install the <filename>/etc/rc.d/init.d/dhcp</filename>
      init script included in the <xref linkend="bootscripts"/>
      package.</para>

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

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

      <para>The lease file must exist on startup. The following command will
      satisfy that requirement:</para>

<screen role="root"><userinput>touch /var/state/dhcp/dhcpd.leases</userinput></screen>

      <para>The following commands will create a base configuration file
      for a DHCP server.  There are several options that you may want to
      add (information that is passed back to the DHCP client) and those
      are covered in the man pages for <filename>dhcp.conf</filename>.</para>

<screen role="root"><userinput>cat &gt; /etc/dhcpd.conf &lt;&lt; "EOF"
<literal>default-lease-time 72000;
max-lease-time 144000;

subnet <replaceable>&lt;192.168.5.0&gt;</replaceable> netmask <replaceable>&lt;255.255.255.0&gt;</replaceable> {
  range <replaceable>&lt;192.168.5.10&gt; &lt;192.168.5.240&gt;</replaceable>;
  option broadcast-address <replaceable>&lt;192.168.5.255&gt;</replaceable>;
  option routers <replaceable>&lt;192.168.5.1&gt;</replaceable>;
}</literal>
EOF</userinput></screen>

      <para>All addresses should be changed to meet your circumstance.</para>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>dhcpd, dhcrelay, dhclient, dhclient-script, and omshell</seg>
        <seg>libbdhcpctl.a, libdst.a, libomapi.a</seg>
        <seg>/var/state/dhcp, /usr/include/omapip, and /usr/include/isi-dhcp</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>