.TH DHCP.CONF 5 .SH NAME dhcp.conf \- dynamic host configuration protocol configuration .SH SYNOPSIS .B /etc/dhcp.conf .SH DESCRIPTION .de SP .if t .sp 0.4 .if n .sp .. The file .B /etc/dhcp.conf contains the configuration for the DHCP client/server program .BR dhcpd . This text is a long summation of all the elements that can be found in this configuration file. For a more "just tell me what to do" approach see .BR boot (8). .PP The syntax used is that of the common configuration file described in .BR configfile (5). .PP To find information for a client we first need its IP address. Occasionally this IP address is already known (the special "INFORM" query), but normally we have to make a first pass through the configuration file for a .B client entry. If that fails then we use an IP address from the pool file. If we now have an IP address then the real information gathering can begin. .PP The DHCP daemon reads the configuration file from beginning to end and gathers all information that matches, and information from all macros that are mentioned within the elements that match. If we end up with DHCP information that includes at least a netmask definition, and is good for the network the request came in from, then it is returned to the client. If a DHCP tag is specified twice then the last one wins. .PP In the description below we use [ and ] to denote optional things, and | to show a choice between two things. .PP Client IDs can be either ordinary Ethernet addresses, that are treated as a seven octet string (01 followed by the Ethernet address), or any random octet string in hexadecimal. .PP IP addresses can be simply that, or host names. These host names are searched in .B /etc/hosts by .B dhcpd itself using a domain based prefix match, i.e. you can use "flotsam" for "flotsam.example.com", but not "alpha" for "alphabeta". Once the program decides to be a server it will also look up names normally in the DNS. If a host has more than one IP address then the address on the network the query was seen on is used. .PP Case isn't important in the configuration file, "client", "CLIENT" and "ClIeNt" are all treated the same. .PP Some elements may optionally name a macro or a curly braces enclosed parameter list of more elements. If the element matches then the data in the macro body or parameter list is gathered. .PP The following elements can be used: .PP .B client .I client-ID .RB [ ip #] .I host .RI [ macro |{ params }]; .PP .RS Defines a client with a given client ID that is to have the IP address denoted by .I host . On the first pass only the client ID is matched looking for an IP address that lies on the network the request came in on. On the information gathering pass both client ID and IP address must match. If a machine has the same Ethernet address on two or more interfaces then the IP address given out is the one on the same network as the request came in on. The optional interface name .RB ( ip #) must be used if the DHCP daemon is gathering data for itself at boot time to differentiate interfaces with the same ethernet addresses. This is only necessary under Minix-vmd when ethernets on different VLANs share the same physical ethernet. The interface name is only used for a machine's own networks, it ignored on entries for other hosts. .RE .PP .B class .IR class-name " ..." .IR macro |{ params }; .PP .RS Includes the macro or parameters if one of the class names is matched. A host normally includes a class ID in its request. MINIX 3 and Minix-vmd use "Minix" as the class name. For Windows the class ID starts with "MSFT", and Solaris' starts with "SUNW". (Use .B dhcpd \-d3 to find out what the full IDs are exactly.) The class names are matched if a .I class-name is a prefix of the class ID sent by the client. .RE .PP .B host .I host-spec .IR macro |{ params }; .PP .RS Includes the macro or parameters if the IP address of the client matches the host specification. This can either be an ordinary hostname, or a netblock in CIDR notation, e.g. 172.35.0.0/16. The example includes all IP addresses whose top 16 bits are the same as the top 16 bits of 172.35.0.0. Such a netblock automatically defines a netmask (255.255.0.0 in the example) if no netmask has been specified yet. .RE .PP .B interface .BR ip # .I host .RI [ macro |{ params }]; .PP .RS Makes .B dhcpd set the IP address of interface .BR ip # (where # is a number) to the IP address denoted by .IR host . This element should only be used for interfaces that are not true Ethernets, and so do not have a unique Ethernet address that can be used for a client element. If the machine has at least one true Ethernet then all interface elements should be added to the parameter list of a host or client element for that Ethernet interface. This binds them to that machine and allows a single configuration file to be shared among machines. Especially a server should never have "free" interface elements. The macro or parameters are only evaluated if data is gathered for the given interface. (Note that they will be hidden by a client element for another interface.) .RE .PP .B macro .IR macro-name ; .PP .RS Include the parameter list of the macro named .I macro-name defined elsewhere. (This means that "host flotsam stuff" is just short for "host flotsam { macro stuff; }".) .RE .PP .B macro .I macro-name .RI { params }; .PP .RS Defines a macro with the given parameter list. Whenever the macro is used the parameter list is substituted instead. A macro can not be defined within another parameter list. .RE .PP .B option .RB [ ip #] .B server .RB [ inform ]; .br .B option .RB [ ip #] .B relay .IR host ; .br .B option .RB [ ip #] .BR possessive ; .br .B option .RB [ ip #] .B hostname .IR name ; .PP .RS Makes .B dhcpd set special options for the interface that it is gathering data for, or the interface denoted by the optional .BR ip # argument. The options are: .SP .B server .RB [ inform ] .RS Be a DHCP server on the network connected to the interface. Add the word .B inform if DHCPINFORM requests must be answered for hosts we don't have an address for. .RE .SP .B relay .I host .RS Be a DHCP relay to the indicated host. .RE .SP .B possessive .RS Do not disable the interface if the DHCP lease expires. Useful if the DHCP server of the provider is unreliable, crashing a lot and causing the lease to expire. (Think twice before turning this option on. You have to be absolutely sure that it's the DHCP server that's the culprit and not a flaky network. You don't want an IP address conflict to be your fault.) .RE .SP .B hostname .I name .RS Use the given name as our hostname in the DHCP queries. Some sites key on that bit of information instead of a client ID. .RE .RE .PP .B tag .I number name type granularity .IR max ; .PP .RS Defines a DHCP tag for the given tag number and gives it a name. The name can be used in the configuration file to set tag values when gathering data. The .I type field can be one of .BR ascii , .BR boolean , .BR ip , .BR number or .BR octet to specify the type of the tag as a simple string, a boolean, an IP address, a number, or a string of octet values. The .I granularity field specifies that that number of items must be given or a multiple thereof, unless the type is a number, then it is the size of the number (1, 2 or 4). The .I max field tells the maximum number of items that may be used with the tag, with 0 meaning "unlimited". .SP Three tags, the ones that MINIX 3 really cares about, have been predefined, and there are also a few pseudotags predefined for the static fields in a DHCP packet that one may want to set: .SP .RS .nf tag ? siaddr ip 1 1; tag ? sname ascii 1 64; tag ? file ascii 1 128; tag 1 netmask ip 1 1; tag 3 gateway ip 1 0; tag 6 DNSserver ip 1 0; .fi .RE .SP The file .B /usr/etc/dhcptags.conf contains tag definitions for all standard DHCP tags. It is wise to include this file at the top of any DHCP configuration file. .RE .PP .B no .IR tag-name ; .PP .RS Removes a tag with the given name from the data gathered at this point. Useful if one host is different from all others, for instance if it doesn't need a gateway definition, because it happens to be the gateway. .RE .PP .IR "ascii-tag string" ; .PP .RS Adds an ASCII tag to the gathered data. The string can be a simple word, or a quoted string. .RE .PP .I boolean-tag .BR false | true ; .PP .RS Set a boolean tag to be false or true. (Encoded as a octet of value 0 or 1. Note that if you prefer to use 0 or 1 instead of false or true then you can define a boolean tag as a size 1 number instead.) .RE .PP .IR "ip-tag host" " ...;" .PP .RS Sets a tag that needs one or more IP addresses. The host names are translated as usual. To make it easier to specify netmasks one can use a slash followed by a number, e.g. .BR "netmask /27" , which is a handy alternative for .BR "netmask 255.255.255.224" . .RE .PP .IR "number-tag number" " ...;" .PP .RS Set a number tag. .RE .PP .IR "octet-tag hexdigits" ; .PP .RS Set an octet string tag. .I Hexdigits is a series of hexadecimal digits that are two by two used to set the octets. .RE .PP .SH EXAMPLE As an example the DHCP configuration used by the author of this document is included. His network at home consists of a number of PCs, an ISDN router named rhone and a PC named saone serving as router/tunnel to/via a cable ISP. Both the rhone and the saone connect the home net to the network of the Vrije Universiteit, but the rhone is only active if the cable doesn't work. .PP The saone is a DHCP server, and one of the ordinary PCs is a backup DHCP server. Both use the same configuration file, which is added below, with extra commentary introduced by .B ## at a deeper indent level: .RS .de xS \" Example start .sp .nf .ft C .. .de xE \" Example end .fi .ft R .. .de cS \" Commentary start .sp .in +12m .ti -\w'## 'u ##\ \c .. .de cE \" Commentary end .in -12m .. .xS .ta +8m +16m include /usr/etc/dhcptags.conf; .xE .cS With the help of the tag definitions we can use tags like "DHCPlease". .cE .xS host 130.37.102.64/27 { DNSserver saone darask; host 130.37.102.88/29 { DHCPlease 259200; } }; .xE .cS This defines the network 130.37.102.64/27, with netmask 255.255.255.224 (implicit from the network definition). The DNS servers for this net are saone and darask. A smaller subrange of addresses is used as an address pool on the saone, so a lease of 259200 seconds (3 days) is defined. The netmask is still /27, as set by the outer network definition. .cE .xS host 130.37.102.248/30 {}; .xE .cS A network of two addresses for routing tests. .cE .xS host saone { option server; option ip1 possessive; interface ip2 saone-net2; DNSserver 130.37.24.3 130.37.24.6; }; .xE .cS With the network definitions done we turn our attention to the hosts. Saone is a DHCP server on its main interface. The second interface .RB ( ip1 ) is connected to the cable modem. It gets its address from the cableco's DHCP server, and if that server decides to go deaf then the saone keeps the interface up ("possessive") even if the lease expires. The pseudo IP interface .B ip2 is set to the IP address of .BR saone-net2 , one side of the encrypted tunnel over the cable to a Minix-vmd box at the VU. The DNS servers specified override the default setting for the network, naming two external servers at the VU that know the world. .cE .xS host darask { option server; DNSserver saone; class MINIX 3 { DNSserver saone 130.37.24.3 130.37.24.6; }; }; .xE .cS The darask is also a server, the backup for saone on the odd chance that it is unavailable. It uses saone and the external name servers, but only when it is running MINIX 3. When running Windows it only uses saone. .cE .xS .ta +32m +16m client 0:1:1b:a:68:ce darask; # NE2000 client 0:1:1b:a:77:23 burask; # NE2000 #lient 0:0:c0:b0:da:64 burask; # WD8013EWC client 8:0:5a:38:b2:f finiah; # PCMCIA NE2000 client 0:0:c0:3a:12:10 bardelask; # WD8003 #lient 2:60:8c:ab:8a:6d bardelask; # 3C503 client 0:a0:c5:20:9:6d rhone; client 0:1:1b:a:4c:3b saone; # NE2000 #lient 0:0:c0:fb:2:6a saone-net1; # WD8013EWC .xE .cS Lastly the ethernet addresses of all the hosts are listed, so that they can be translated to IP addresses. The lines that are commented out are for extra network cards that are currently unused. The last is used to connect to the cable modem, so it's only here because it's nice to have the ethernet address written down somewhere. .cE .RE .PP The host names shown above are translated by DHCP using this .BR /etc/hosts : .RS .xS .ta +\w'130.37.102.249mm'u 604800 %ttl 2419200 %stale 130.37.102.65 darask.kjb.upwind.org 130.37.102.66 burask.kjb.upwind.org 130.37.102.67 finiah.kjb.upwind.org 130.37.102.68 bardelask.kjb.upwind.org 130.37.102.69 roniah.kjb.upwind.org 130.37.102.70 saone.kjb.upwind.org 130.37.102.2 saone-net2.kjb.upwind.org 130.37.102.88 rhone.kjb.upwind.org 130.37.102.89 dyn89.kjb.upwind.org 130.37.102.90 dyn90.kjb.upwind.org 130.37.102.91 dyn91.kjb.upwind.org 130.37.102.92 dyn92.kjb.upwind.org 130.37.102.93 dyn93.kjb.upwind.org 130.37.102.94 dyn94.kjb.upwind.org 130.37.102.249 tst1.kjb.upwind.org 130.37.102.250 tst2.kjb.upwind.org .xE .RE .SH FILES .TP .B /usr/etc/dhcptags.conf A supplied list of standard tag definitions as per RFC-1533. (Well, the tag numbers and their meaning are standard, the names are made up.) .SH "SEE ALSO" .BR RFC-2131 , .BR RFC-1533 , .BR configfile (5), .BR hosts (5), .BR boot (8), .BR dhcpd (8). .SH NOTES The amount of memory .B dhcpd needs increases with the size of configuration file. MINIX 3 can handle .B dhcptags.conf and a modest sized .BR dhcp.conf . You have to increase the stack size to accommodate more. (No problem under Minix-vmd, of course.) .SH NOTES Items that are only necessary for a certain host should only be specified for that host. Items for a whole network are best added to a netblock specification. Use class elements for a certain type of host, and macros for exceptions. Try to limit information as much as possibly to those hosts that need it. (Don't go overboard. A MINIX 3 machine won't be bothered by a few NetBIOS tags.) .PP DHCPINFORM requests should always be answered when being a server, but J. Random Sysadmin trying to diagnose problems doesn't like it when little MINIX 3 machines show up in a packet trace unexpectedly. It's best to be inconspicuous on a network you don't own. .SH BUGS There are a few too many subtle mistakes one can make. .SH AUTHOR Kees J. Bot