Provided by: dhcp_2.0pl5-19.4_i386 bug

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-insensitive.   Comments may be placed anywhere within the file
       (except within quotes).   Comments begin with the # character  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 gateway 220.177.244.7).

       Declarations  are  used  to  describe  the  topology of the network, 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 declaration.    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
       parameters  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 subnet 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
       ethernet 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 declaration.

       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 departments on the same subnet.   For clients which will be
       declared explicitly with host declarations, these declarations  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  declaration  (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 network 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 parameters as shown
       in Figure 1 is that each subnet, of necessity, 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 legitimate 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  provides  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
       supplied 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 mechanism, 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-Terminals.   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 physical 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-specific  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 declaration,  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  dynamically,  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  single  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 specified.

       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 otherwise, then a host  statement
       must be specified without a fixed-address clause.  hostname should be a
       name identifying 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 network 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)  separated  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 booting, that client will not
       match the host declaration  containing  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 number 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 supplied 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 configuration 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
       forget 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 authoritative 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 declarations 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 specified 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  recommended  -  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
       network 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 appropriate 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(8), dhcpd.leases(5), RFC2132, RFC2131.

AUTHOR

       dhcpd(8), which uses the configuration file described in this man page,
       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.  Information about the Internet Software Consortium can be
       found at http://www.isc.org/isc.

                                                                 dhcpd.conf(5)