docs/handbook/handbook-network-dhcp.mdwn

   1 ## DHCP \r
   2 ***Written by Greg Sutter. ***\r
   3 \r
   4 ### What Is DHCP? \r
   5 DHCP, the Dynamic Host Configuration Protocol, describes the means by which a system can connect to a network and obtain the necessary information for communication upon that network. DragonFly uses the ISC (Internet Software Consortium) DHCP implementation, so all implementation-specific information here is for use with the ISC distribution.\r
   6 \r
   7 ### What This Section Covers \r
   8 This section describes both the client-side and server-side components of the ISC DHCP system. The client-side program, `dhclient`, and the server, come integrated within DragonFly. The [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhclient&section8), [dhcp-options(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhcp-options&section=5), and [dhclient.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient.conf&section=5) manual pages, in addition to the references below, are useful resources.\r
   9 \r
  10 ### How It Works \r
  11 When `dhclient`, the DHCP client, is executed on the client machine, it begins broadcasting requests for configuration information. By default, these requests are on UDP port 68. The server replies on UDP 67, giving the client an IP address and other relevant network information such as netmask, router, and DNS servers. All of this information comes in the form of a DHCP ***lease*** and is only valid for a certain time (configured by the DHCP server maintainer). In this manner, stale IP addresses for clients no longer connected to the network can be automatically reclaimed.\r
  12 \r
  13 DHCP clients can obtain a great deal of information from the server. An exhaustive list may be found in [dhcp-options(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhcp-options&section5).\r
  14 \r
  15 ### DragonFly Integration \r
  16 DragonFly fully integrates the ISC DHCP client, `dhclient`. DHCP client support is provided within both the installer and the base system, obviating the need for detailed knowledge of network configurations on any network that runs a DHCP server.\r
  17 \r
  18 There are two things you must do to have your system use DHCP upon startup:\r
  19 \r
  20
  21 * Make sure that the `bpf` device is compiled into your kernel. To do this, add `pseudo-device bpf` to your kernel configuration file, and rebuild the kernel. For more information about building kernels, look [here](kernelconfig.html). The `bpf` device is already part of the `GENERIC` kernel that is supplied with DragonFly, so if you do not have a custom kernel, you should not need to create one in order to get DHCP working.  **Note:** For those who are particularly security conscious, you should be warned that `bpf` is also the device that allows packet sniffers to work correctly (although they still have to be run as `root`). `bpf` ***is*** required to use DHCP, but if you are very sensitive about security, you probably should not add `bpf` to your kernel in the expectation that at some point in the future you will be using DHCP.\r
  22
  23 * Edit your `/etc/rc.conf` to include the following:\r
  24      \r
  25       ifconfig_fxp0="DHCP"\r
  26     \r
  27 \r
  28   **Note:** Be sure to replace `fxp0` with the designation for the interface that you wish to dynamically configure, as described in [the Network setup section](config-network-setup.html). If you are using a different location for `dhclient`, or if you wish to pass additional flags to `dhclient`, also include the following (editing as necessary):\r
  29      \r
  30       dhclient_program="/sbin/dhclient"\r
  31       dhclient_flags=""\r
  32     \r
  33 \r
  34 \r
  35 ### Files \r
  36
  37 * `/etc/dhclient.conf` `dhclient` requires a configuration file, `/etc/dhclient.conf`. Typically the file contains only comments, the defaults being reasonably sane. This configuration file is described by the [dhclient.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhclient.conf&section5) manual page.\r
  38
  39 * `/sbin/dhclient` `dhclient` is statically linked and resides in `/sbin`. The [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhclient&section8) manual page gives more information about `dhclient`.\r
  40
  41 * `/sbin/dhclient-script` `dhclient-script` is the DragonFly-specific DHCP client configuration script. It is described in [dhclient-script(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhclient-script&section8), but should not need any user modification to function properly.\r
  42
  43 * `/var/db/dhclient.leases` The DHCP client keeps a database of valid leases in this file, which is written as a log. [dhclient.leases(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#dhclient.leases&section5) gives a slightly longer description.\r
  44 \r
  45 ### Further Reading \r
  46 The DHCP protocol is fully described in [RFC 2131](http://www.freesoft.org/CIE/RFC/2131/). An informational resource has also been set up at [dhcp.org](http://www.dhcp.org/).\r
  47 \r
  48 ### Installing and Configuring a DHCP Server \r
  49 #### What This Section Covers \r
  50 This section provides information on how to configure a DragonFly system to act as a DHCP server using the ISC (Internet Software Consortium) implementation of the DHCP suite.\r
  51 \r
  52 #### DHCP Server Installation \r
  53 The DHCP server,  **dhcpd** , is included as part of the [net/isc-dhcpd4](http://pkgsrc.se/net/isc-dhcpd4) package in the pkgsrc collection. This package contains the ISC DHCP server and documentation.\r
  54 \r
  55 In order to configure your DragonFly system as a DHCP server, you will need to ensure that the [bpf(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#bpf&section4) device is compiled into your kernel. To do this, add `pseudo-device bpf` to your kernel configuration file, and rebuild the kernel. For more information about building kernels, look [here](kernelconfig.html).  The `bpf` device is already part of the `GENERIC` kernel that is supplied with DragonFly, so you do not need to create a custom kernel in order to get DHCP working.\r
  56 \r
  57  **Note:**  Those who are particularly security conscious should note that `bpf` is also the device that allows packet sniffers to work correctly (although such programs still need privileged access). `bpf` ***is*** required to use DHCP, but if you are very sensitive about security, you probably should not include `bpf` in your kernel purely because you expect to use DHCP at some point in the future.\r
  58 \r
  59 The next thing that you will need to do is edit the sample `dhcpd.conf` which was installed by the [net/isc-dhcpd4](http://pkgsrc.se/net/isc-dhcpd4) port. By default, this will be `/usr/pkg/etc/dhcpd.conf.sample`, and you should copy this to `/usr/pkg/etc/dhcpd.conf` before proceeding to make changes.\r
  60 \r
  61 #### Configuring the DHCP Server \r
  62 `dhcpd.conf` is comprised of declarations regarding subnets and hosts, and is perhaps most easily explained using an example :\r
  63 \r
  64     \r
  65     option domain-name "example.com";               (1)\r
  66     option domain-name-servers 192.168.4.100;       (2)\r
  67     option subnet-mask 255.255.255.0;               (3)\r
  68     \r
  69     default-lease-time 3600;                        (4)\r
  70     max-lease-time 86400;                           (5)\r
  71     ddns-update-style none;                         (6)\r
  72     \r
  73     subnet 192.168.4.0 netmask 255.255.255.0 {\r
  74       range 192.168.4.129 192.168.4.254;            (7)\r
  75       option routers 192.168.4.1;                   (8)\r
  76     }\r
  77     \r
  78     host mailhost {\r
  79       hardware ethernet 02:03:04:05:06:07;          (9)\r
  80       fixed-address mailhost.example.com;           (10)\r
  81     }\r
  82 \r
  83  1. This option specifies the domain that will be provided to clients as the default search domain. See [resolv.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#resolv.conf&section5) for more information on what this means.\r
  84  1. This option specifies a comma separated list of DNS servers that the client should use.\r
  85  1. The netmask that will be provided to clients.\r
  86  1. A client may request a specific length of time that a lease will be valid. Otherwise the server will assign a lease with this expiry value (in seconds).\r
  87  1. This is the maximum length of time that the server will lease for. Should a client request a longer lease, a lease will be issued, although it will only be valid for `max-lease-time` seconds.\r
  88  1. This option specifies whether the DHCP server should attempt to update DNS when a lease is accepted or released. In the ISC implementation, this option is ***required***.\r
  89  1. This denotes which IP addresses should be used in the pool reserved for allocating to clients. IP addresses between, and including, the ones stated are handed out to clients.\r
  90  1. Declares the default gateway that will be provided to clients.\r
  91  1. The hardware MAC address of a host (so that the DHCP server can recognize a host when it makes a request).\r
  92  1. Specifies that the host should always be given the same IP address. Note that using a hostname is correct here, since the DHCP server will resolve the hostname itself before returning the lease information.\r
  93 \r
  94 Once you have finished writing your `dhcpd.conf`, you can proceed to start the server by issuing the following command:\r
  95 \r
  96     \r
  97     # /usr/pkg/etc/share/examples/rc.d/isc-dhcpd.sh start\r
  98 \r
  99 Should you need to make changes to the configuration of your server in the future, it is important to note that sending a `SIGHUP` signal to  **dhcpd**  does ***not*** result in the configuration being reloaded, as it does with most daemons. You will need to send a `SIGTERM` signal to stop the process, and then restart it using the command above.\r
 100 \r
 101 #### Files \r
 102
 103 * `/usr/sbin/dhcpd`  **dhcpd**  is statically linked and resides in `/usr/local/sbin`. The dhcpd(8) manual page installed with the port gives more information about  **dhcpd** .\r
 104
 105 * `/etc/dhcpd.conf`  **dhcpd**  requires a configuration file, `/usr/pkg/etc/dhcpd.conf` before it will start providing service to clients. This file needs to contain all the information that should be provided to clients that are being serviced, along with information regarding the operation of the server. This configuration file is described by the dhcpd.conf(5) manual page installed by the package.\r
 106
 107 * `/var/db/dhcpd.leases` The DHCP server keeps a database of leases it has issued in this file, which is written as a log. The manual page dhcpd.leases(5), installed by the package gives a slightly longer description.\r
 108
 109 * `/usr/sbin/dhcrelay`  **dhcrelay**  is used in advanced environments where one DHCP server forwards a request from a client to another DHCP server on a separate network.\r
 110 \r
 111 CategoryHandbook CategoryHandbook-advancednetworking\r