Logo

Charles Steinkuehler's LEAF/LRP Website


 

dhcpd.conf.5




NAME

       dhcpd.conf - dhcpd configuration file


DESCRIPTION

       The dhcpd.conf file contains configuration information for
       dhcpd, the Internet Software Consortium DHCP Server.

       The dhcpd.conf file is a free-form ASCII text  file.    It
       is  parsed  by  the  recursive-descent  parser  built into
       dhcpd.   The file may contain extra tabs and newlines  for
       formatting purposes.  Keywords in the file are case-insen­
       sitive.   Comments may be placed anywhere within the  file
       (except  within quotes).   Comments begin with the # char­
       acter and end at the end of the line.

       The file essentially consists of  a  list  of  statements.
       Statements fall into two broad categories - parameters and
       declarations.

       Parameter statements either say how to do something (e.g.,
       how long a lease to offer), whether to do something (e.g.,
       should dhcpd provide addresses  to  unknown  clients),  or
       what  parameters to provide to the client (e.g., use gate­
       way 220.177.244.7).

       Declarations are used to describe the topology of the net­
       work,  to  describe  clients  on  the  network, to provide
       addresses that can be assigned to clients, or to  apply  a
       group  of  parameters to a group of declarations.   In any
       group of parameters and declarations, all parameters  must
       be specified before any declarations which depend on those
       parameters may be specified.

       Declarations about network topology include the
        shared-network and the subnet declarations.   If  clients
       on  a  subnet  are to be assigned addresses dynamically, a
       range declaration must appear within the  subnet  declara­
       tion.   For clients with statically assigned addresses, or
       for installations where only known clients will be served,
       each such client must have a host declaration.   If param­
       eters are to be applied to a group of  declarations  which
       are  not related strictly on a per-subnet basis, the group
       declaration can be used.

       For every subnet which will be served, and for every  sub­
       net  to  which the dhcp server is connected, there must be
       one subnet declaration, which tells dhcpd how to recognize
       that  an  address is on that subnet.  A subnet declaration
       is required for each subnet even if no addresses  will  be
       dynamically allocated on that subnet.

       Some  installations  have  physical networks on which more
       than one IP subnet operates.   For example, if there is  a
       site-wide requirement that 8-bit subnet masks be used, but
       a department  with  a  single  physical  ethernet  network
       expands  to the point where it has more than 254 nodes, it
       may be necessary to run two 8-bit subnets on the same eth­
       ernet  until  such  time  as a new physical network can be
       added.   In this case, the subnet declarations  for  these
       two  networks may be enclosed in a shared-network declara­
       tion.

       Some sites may have departments which have clients on more
       than  one  subnet,  but it may be desirable to offer those
       clients a uniform set of parameters  which  are  different
       than  what  would be offered to clients from other depart­
       ments on the same subnet.    For  clients  which  will  be
       declared explicitly with host declarations, these declara­
       tions can be enclosed in a group  declaration  along  with
       the  parameters which are common to that department.   For
       clients whose  addresses  will  be  dynamically  assigned,
       there  is  currently no way to group parameter assignments
       other than by network topology.

       When a client is to be booted,  its  boot  parameters  are
       determined by first consulting that client's host declara­
       tion (if any), then consulting the group  declaration  (if
       any) which enclosed that host declaration, then consulting
       the subnet declaration for the subnet on which the  client
       is booting, then consulting the shared-network declaration
       (if any) containing that subnet,  and  finally  consulting
       the top-level parameters which may be specified outside of
       any declaration.

       When dhcpd tries to find a host declaration for a  client,
       it  first  looks for a host declaration which has a fixed-
       address parameter which matches the subnet or shared  net­
       work  on which the client is booting.   If it doesn't find
       any such entry, it then tries to find an entry  which  has
       no  fixed-address  parameter.   If no such entry is found,
       then dhcpd acts as if there is no entry in the  dhcpd.conf
       file  for  that client, even if there is an entry for that
       client on a different subnet or shared network.


EXAMPLES

       A typical dhcpd.conf file will look something like this:

       global parameters...

       shared-network ISC-BIGGIE {
         shared-network-specific parameters...
         subnet 204.254.239.0 netmask 255.255.255.224 {
           subnet-specific parameters...
           range 204.254.239.10 204.254.239.30;
         }
         subnet 204.254.239.32 netmask 255.255.255.224 {
           subnet-specific parameters...
           range 204.254.239.42 204.254.239.62;

         }
       }

       subnet 204.254.239.64 netmask 255.255.255.224 {
         subnet-specific parameters...
         range 204.254.239.74 204.254.239.94;
       }

       group {
         group-specific parameters...
         host zappo.test.isc.org {
           host-specific parameters...
         }
         host beppo.test.isc.org {
           host-specific parameters...
         }
         host harpo.test.isc.org {
           host-specific parameters...
         }
       }

                                Figure 1

       Notice that at the beginning of the file, there's a  place
       for  global  parameters.    These might be things like the
       organization's domain name,  the  addresses  of  the  name
       servers  (if  they are common to the entire organization),
       and so on.   So, for example:

            option domain-name "isc.org";
            option domain-name-servers ns1.isc.org, ns2.isc.org;

                                Figure 2

       As you can see in Figure 2, it's  legal  to  specify  host
       addresses  in  parameters  as  domain names rather than as
       numeric IP addresses.  If a  given  hostname  resolves  to
       more  than  one  IP address (for example, if that host has
       two ethernet interfaces), both addresses are  supplied  to
       the client.

       In  Figure  1,  you  can  see that both the shared-network
       statement and the subnet statements can  have  parameters.
       Let  us say that the shared network ISC-BIGGIE supports an
       entire department -  perhaps  the  accounting  department.
       If  accounting  has its own domain, then a shared-network-
       specific parameter might be:

            option domain-name "accounting.isc.org";

       All subnet declarations appearing  in  the  shared-network
       declaration  would then have the domain-name option set to
       "accounting.isc.org" instead of just "isc.org".
       The most obvious reason for having subnet-specific parame­
       ters  as  shown in Figure 1 is that each subnet, of neces­
       sity, has its own router.   So for the first  subnet,  for
       example, there should be something like:

            option routers 204.254.239.1;

       Note  that  the  address  here  is  specified numerically.
       This is not required - if you have a different domain name
       for  each interface on your router, it's perfectly legiti­
       mate to use the domain name for that interface instead  of
       the numeric address.   However, in many cases there may be
       only one domain name for all of a router's  IP  addresses,
       and it would not be appropriate to use that name here.

       In  Figure  1  there is also a group statement, which pro­
       vides common parameters for a set of three hosts -  zappo,
       beppo  and  harpo.  As you can see, these hosts are all in
       the test.isc.org domain, so it  might  make  sense  for  a
       group-specific  parameter to override the domain name sup­
       plied to these hosts:

            option domain-name "test.isc.org";

       Also, given the domain they're in, these are probably test
       machines.   If  we  wanted to test the DHCP leasing mecha­
       nism, we might set the lease timeout somewhat shorter than
       the default:

            max-lease-time 120;
            default-lease-time 120;

       You may have noticed that while some parameters start with
       the option keyword, some  do  not.    Parameters  starting
       with the option keyword correspond to actual DHCP options,
       while parameters that do not start with the option keyword
       either control the behaviour of the DHCP server (e.g., how
       long a lease dhcpd  will  give  out),  or  specify  client
       parameters that are not optional in the DHCP protocol (for
       example, server-name and filename).

       In Figure  1,  each  host  had  host-specific  parameters.
       These  could  include  such things as the hostname option,
       the name of a file to upload (the filename parameter)  and
       the  address  of  the server from which to upload the file
       (the next-server parameter).   In general,  any  parameter
       can  appear anywhere that parameters are allowed, and will
       be applied according to the scope in which  the  parameter
       appears.

       Imagine  that  you  have a site with a lot of NCD X-Termi­
       nals.   These terminals come in a variety of  models,  and
       you  want to specify the boot files for each models.   One
       way to do this would be to have host declarations for each
       server and group them by model:

       group {
         filename "Xncd19r";
         next-server ncd-booter;

         host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }
         host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }
         host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }
       }

       group {
         filename "Xncd19c";
         next-server ncd-booter;

         host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
         host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
       }

       group {
         filename "XncdHMX";
         next-server ncd-booter;

         host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }
         host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }
         host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }
       }


REFERENCE: DECLARATIONS

       The shared-network statement

        shared-network name {
          [ parameters ]
          [ declarations ]
        }

       The  shared-network  statement  is used to inform the DHCP
       server that some IP subnets actually share the same physi­
       cal  network.   Any  subnets in a shared network should be
       declared within a  shared-network  statement.   Parameters
       specified  in  the  shared-network  statement will be used
       when booting clients on those  subnets  unless  parameters
       provided  at  the  subnet or host level override them.  If
       any subnet in a shared network has addresses available for
       dynamic  allocation,  those addresses are collected into a
       common pool  for  that  shared  network  and  assigned  to
       clients  as  needed.   There  is  no way to distinguish on
       which subnet of a shared network a client should boot.

       Name should be the name of the shared network.   This name
       is  used when printing debugging messages, so it should be
       descriptive for the shared network.   The  name  may  have
       the  syntax of a valid domain name (although it will never
       be used as  such),  or  it  may  be  any  arbitrary  name,
       enclosed in quotes.

       The subnet statement

        subnet subnet-number netmask netmask {
          [ parameters ]
          [ declarations ]
        }

       The  subnet statement is used to provide dhcpd with enough
       information to tell whether or not an  IP  address  is  on
       that  subnet.   It may also be used to provide subnet-spe­
       cific parameters and to  specify  what  addresses  may  be
       dynamically  allocated  to clients booting on that subnet.
       Such addresses are specified using the range  declaration.

       The  subnet-number  should be an IP address or domain name
       which resolves to the subnet number of  the  subnet  being
       described.   The netmask should be an IP address or domain
       name which resolves to the subnet mask of the subnet being
       described.   The subnet number, together with the netmask,
       are sufficient to determine whether any given  IP  address
       is on the specified subnet.

       Although  a netmask must be given with every subnet decla­
       ration, it is recommended that if there is any variance in
       subnet  masks at a site, a subnet-mask option statement be
       used in each subnet declaration to set the desired  subnet
       mask, since any subnet-mask option statement will override
       the subnet mask declared in the subnet statement.

       The range statement

        range [ dynamic-bootp ] low-address [ high-address];

       For any subnet on which addresses will be assigned dynami­
       cally,  there  must be at least one range statement.   The
       range statement gives the lowest and highest IP  addresses
       in  a  range.   All IP addresses in the range should be in
       the subnet in which the range statement is declared.   The
       dynamic-bootp  flag  may  be specified if addresses in the
       specified range  may  be  dynamically  assigned  to  BOOTP
       clients  as well as DHCP clients.   When specifying a sin­
       gle address, high-address can be omitted.

       The host statement

        host hostname {
          [ parameters ]
          [ declarations ]
        }

       There must be at least one host statement for every  BOOTP
       client  that is to be served.  host statements may also be
       specified for DHCP clients, although this is not  required
       unless booting is only enabled for known hosts.

       If  it  is  desirable  to  be able to boot a DHCP or BOOTP
       client on more than one subnet with fixed addresses,  more
       than  one  address  may  be specified in the fixed-address
       parameter, or more than one host statement may  be  speci­
       fied.

       If  client-specific  boot  parameters must change based on
       the network to which the client is attached, then multiple
       host statements should be used.

       If  a client is to be booted using a fixed address if it's
       possible, but should be allocated a dynamic address other­
       wise,  then  a  host statement must be specified without a
       fixed-address clause.  hostname should be a name identify­
       ing  the  host.  If a hostname option is not specified for
       the host, hostname is used.

       Host declarations are matched  to  actual  DHCP  or  BOOTP
       clients  by  matching  the  dhcp-client-identifier  option
       specified in the host declaration to the one  supplied  by
       the client, or, if the host declaration or the client does
       not provide a dhcp-client-identifier option,  by  matching
       the hardware parameter in the host declaration to the net­
       work hardware address  supplied  by  the  client.    BOOTP
       clients  do not normally provide a dhcp-client-identifier,
       so the hardware address must be used for all clients  that
       may boot using the BOOTP protocol.

       The group statement

        group {
          [ parameters ]
          [ declarations ]
        }

       The  group  statement  is used simply to apply one or more
       parameters to a group of declarations.   It can be used to
       group  hosts,  shared  networks,  subnets,  or  even other
       groups.


REFERENCE: ALLOW and DENY

       The allow and deny statements can be used to  control  the
       behaviour of dhcpd to various sorts of requests.

       The unknown-clients keyword

        allow unknown-clients;
        deny unknown-clients;

       The  unknown-clients flag is used to tell dhcpd whether or
       not to dynamically assign addresses  to  unknown  clients.
       Dynamic  address  assignment to unknown clients is allowed
       by default.

       The bootp keyword

        allow bootp;
        deny bootp;

       The bootp flag is used to tell dhcpd  whether  or  not  to
       respond  to  bootp  queries.  Bootp queries are allowed by
       default.

       The booting keyword

        allow booting;
        deny booting;

       The booting flag is used to tell dhcpd whether or  not  to
       respond to queries from a particular client.  This keyword
       only has meaning when it appears in  a  host  declaration.
       By  default, booting is allowed, but if it is disabled for
       a particular client, then that client will not be able  to
       get and address from the DHCP server.


REFERENCE: PARAMETERS

       The default-lease-time statement

        default-lease-time time;

       Time should be the length in seconds that will be assigned
       to a lease if the client requesting the lease does not ask
       for a specific expiration time.

       The max-lease-time statement

        max-lease-time time;

       Time  should be the maximum length in seconds that will be
       assigned to a lease if the  client  requesting  the  lease
       asks for a specific expiration time.

       The hardware statement

        hardware hardware-type hardware-address;

       In  order for a BOOTP client to be recognized, its network
       hardware address must be declared using a hardware  clause
       in  the host statement.  hardware-type must be the name of
       a physical hardware interface type.   Currently, only  the
       ethernet  and  token-ring  types  are recognized, although
       support for a fddi hardware type (and others)  would  also
       be  desirable.   The  hardware-address  should be a set of
       hexadecimal octets (numbers from 0 through  ff)  seperated
       by  colons.    The hardware statement may also be used for
       DHCP clients.

       The filename statement

        filename "filename";

       The filename statement can be used to specify the name  of
       the  initial  boot file which is to be loaded by a client.
       The filename should be a filename recognizable to whatever
       file  transfer  protocol the client can be expected to use
       to load the file.

       The server-name statement

        server-name "name";

       The server-name statement can be used to inform the client
       of the name of the server from which it is booting.   Name
       should be the name that will be provided to the client.

       The next-server statement

        next-server server-name;

       The next-server statement is  used  to  specify  the  host
       address  of  the  server  from which the initial boot file
       (specified in the filename statement)  is  to  be  loaded.
       Server-name  should  be  a  numeric IP address or a domain
       name.   If no next-server parameter  applies  to  a  given
       client, the DHCP server's IP address is used.

       The fixed-address statement

        fixed-address address [, address ... ];

       The  fixed-address statement is used to assign one or more
       fixed IP addresses to a client.  It should only appear  in
       a host declaration.  If more than one address is supplied,
       then when the  client  boots,  it  will  be  assigned  the
       address  which  corresponds  to the network on which it is
       booting.  If none of the addresses  in  the  fixed-address
       statement  are on the network on which the client is boot­
       ing, that client will not match the host declaration  con­
       taining that fixed-address statement.  Each address should
       be either an IP address or a domain name which resolves to
       one or more IP addresses.

       The dynamic-bootp-lease-cutoff statement

        dynamic-bootp-lease-cutoff date;

       The  dynamic-bootp-lease-cutoff  statement sets the ending
       time for all leases assigned dynamically to BOOTP clients.
       Because  BOOTP  clients  do  not  have any way of renewing
       leases, and don't know that their leases could expire,  by
       default  dhcpd  assignes  infinite  leases  to  all  BOOTP
       clients.  However, it may make sense in some situations to
       set  a cutoff date for all BOOTP leases - for example, the
       end of a school term, or the time at night when a facility
       is closed and all machines are required to be powered off.

       Date should be the date on which all assigned BOOTP leases
       will end.  The date is specified in the form:

                         W YYYY/MM/DD HH:MM:SS

       W  is  the day of the week expressed as a number from zero
       (Sunday) to six (Saturday).  YYYY is the  year,  including
       the century.  MM is the month expressed as a number from 1
       to 12.  DD is the day of the month, counting from  1.   HH
       is  the hour, from zero to 23.  MM is the minute and SS is
       the second.  The time is always in  Universal  Coordinated
       Time (UTC), not local time.

       The dynamic-bootp-lease-length statement

        dynamic-bootp-lease-length length;

       The  dynamic-bootp-lease-length  statement  is used to set
       the  length  of  leases  dynamically  assigned  to   BOOTP
       clients.    At  some  sites,  it may be possible to assume
       that a lease is no longer in use if  its  holder  has  not
       used  BOOTP  or  DHCP  to get its address within a certain
       time period.   The period is specified in length as a num­
       ber  of  seconds.   If a client reboots using BOOTP during
       the timeout period, the lease duration is reset to length,
       so  a BOOTP client that boots frequently enough will never
       lose its lease.  Needless to say, this parameter should be
       adjusted with extreme caution.

       The get-lease-hostnames statement

        get-lease-hostnames flag;

       The  get-lease-hostnames  statement  is used to tell dhcpd
       whether or not to look up the domain name corresponding to
       the  IP  address of each address in the lease pool and use
       that address for the DHCP hostname  option.   If  flag  is
       true,  then  this  lookup is done for all addresses in the
       current scope.   By default,  or  if  flag  is  false,  no
       lookups are done.

       The use-host-decl-names statement

        use-host-decl-names flag;

       If  the  use-host-decl-names  parameter is true in a given
       scope, then for every host declaration within that  scope,
       the  name  provided  for the host declaration will be sup­
       plied to the client as its hostname.   So, for example,

           group {
             use-host-decl-names on;

             host joe {
            hardware ethernet 08:00:2b:4c:29:32;
            fixed-address joe.fugue.com;
             }
           }

       is equivalent to

             host joe {
            hardware ethernet 08:00:2b:4c:29:32;
            fixed-address joe.fugue.com;
               option host-name "joe";
             }

       An option host-name statement within  a  host  declaration
       will override the use of the name in the host declaration.

       The authoritative statement

        authoritative;

        not authoritative;

       The DHCP server will normally assume that  the  configura­
       tion information about a given network segment is known to
       be correct and is authoritative.   So if a client requests
       an  IP  address on a given network segment that the server
       knows is not valid  for  that  segment,  the  server  will
       respond with a DHCPNAK message, causing the client to for­
       get its IP address and try to get a new one.

       If a DHCP server is being configured by  somebody  who  is
       not  the  network administrator and who therefore does not
       wish to assert this level of authority, then the statement
       "not  authoritative"  should be written in the appropriate
       scope in the configuration file.

       Usually, writing not authoritative; at the  top  level  of
       the file should be sufficient.   However, if a DHCP server
       is to be set up so that it is aware of some  networks  for
       which  it  is authoritative and some networks for which it
       is not, it may be more appropriate to declare authority on
       a per-network-segment basis.

       Note that the most specific scope for which the concept of
       authority makes any sense is the physical network  segment
       -  either a shared-network statement or a subnet statement
       that is not contained within a  shared-network  statement.
       It is not meaningful to specify that the server is author­
       itative for some subnets within a shared network, but  not
       authoritative  for others, nor is it meaningful to specify
       that the server is authoritative for  some  host  declara­
       tions and not others.

       The use-lease-addr-for-default-route statement

        use-lease-addr-for-default-route flag;

       If  the use-lease-addr-for-default-route parameter is true
       in a given scope, then instead of sending the value speci­
       fied  in  the routers option (or sending no value at all),
       the IP address of the lease being assigned is sent to  the
       client.   This supposedly causes Win95 machines to ARP for
       all IP addresses, which can be helpful if your  router  is
       configured for proxy ARP.

       If  use-lease-addr-for-default-route  is  enabled  and  an
       option routers statement are both in  scope,  the  routers
       option  will be preferred.  The rationale for this is that
       in situations where you want  to  use  this  feature,  you
       probably  want  it enabled for a whole bunch of Windows 95
       machines, and you want to override  it  for  a  few  other
       machines.    Unfortunately,  if the opposite happens to be
       true for you site, you are probably better off not  trying
       to use this flag.

       The always-reply-rfc1048 statement

        always-reply-rfc1048 flag;

       Some  BOOTP clients expect RFC1048-style responses, but do
       not follow RFC1048 when sending their requests.   You  can
       tell  that  a  client  is having this problem if it is not
       getting the options you have configured for it and if  you
       see  in the server log the message "(non-rfc1048)" printed
       with each BOOTREQUEST that is logged.

       If you want to send rfc1048 options to such a client,  you
       can  set  the always-reply-rfc1048 option in that client's
       host declaration, and the DHCP server will respond with an
       RFC-1048-style  vendor  options  field.   This flag can be
       set in any scope, and will affect all clients  covered  by
       that scope.

       The server-identifier statement

        server-identifier hostname;

       The  server-identifier statement can be used to define the
       value that is sent in the DHCP  Server  Identifier  option
       for  a  given  scope.    The value specified must be an IP
       address for the DHCP server, and must be reachable by  all
       clients served by a particular scope.

       The  use  of the server-identifier statement is not recom­
       mended - the only reason to use it is  to  force  a  value
       other than the default value to be sent on occasions where
       the default value would be incorrect.   The default  value
       is  the first IP address associated with the physical net­
       work interface on which the request arrived.

       The usual case where the server-identifier statement needs
       to  be sent is when a physical interface has more than one
       IP address, and the one being sent by default isn't appro­
       priate  for  some or all clients served by that interface.
       Another common case is when an alias is  defined  for  the
       purpose  of  having  a  consistent IP address for the DHCP
       server, and it is desired that the  clients  use  this  IP
       address when contacting the server.

       Supplying a value for the dhcp-server-identifier option is
       equivalent to using the server-identifier statement.


REFERENCE: OPTION STATEMENTS

       DHCP  option  statements  are  documented  in  the   dhcp-
       options(5) manual page.


SEE ALSO

       dhcpd.conf(5), dhcpd.leases(5), RFC2132, RFC2131.


AUTHOR

       dhcpd(8) was written by Ted Lemon <mellon@vix.com> under a
       contract with Vixie Labs.   Funding for this  project  was
       provided  by  the Internet Software Corporation.  Informa­
       tion about the Internet Software Consortium can  be  found
       at http://www.isc.org/isc.


Man(1) output converted with man2html