diff options
Diffstat (limited to 'usr.sbin/dhcp/server/dhcpd.conf.5')
| -rw-r--r-- | usr.sbin/dhcp/server/dhcpd.conf.5 | 1384 |
1 files changed, 776 insertions, 608 deletions
diff --git a/usr.sbin/dhcp/server/dhcpd.conf.5 b/usr.sbin/dhcp/server/dhcpd.conf.5 index 78063db1728..3f2e86e6bcb 100644 --- a/usr.sbin/dhcp/server/dhcpd.conf.5 +++ b/usr.sbin/dhcp/server/dhcpd.conf.5 @@ -1,4 +1,4 @@ -.\" dhcpd.conf.5 +.\" $OpenBSD: dhcpd.conf.5,v 1.10 2003/06/25 09:27:57 jmc Exp $ .\" .\" Copyright (c) 1995, 1996, 1997, 1998, 1998, 1999 .\" The Internet Software Consortium. All rights reserved. @@ -35,221 +35,273 @@ .\" Enterprises. To learn more about the Internet Software Consortium, .\" see ``http://www.isc.org/isc''. To learn more about Vixie .\" Enterprises, see ``http://www.vix.com''. -.TH dhcpd.conf 5 -.SH NAME -dhcpd.conf - dhcpd configuration file -.SH DESCRIPTION -The dhcpd.conf file contains configuration information for -.IR dhcpd, +.\" +.Dd January 1, 1995 +.Dt DHCPD.CONF 5 +.Os +.Sh NAME +.Nm dhcpd.conf +.Nd dhcpd configuration file +.Sh DESCRIPTION +The +.Nm +file contains configuration information for +.Xr dhcpd 8 , the Internet Software Consortium DHCP Server. -.PP -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. -.PP -The file essentially consists of a list of statements. Statements -fall into two broad categories - parameters and declarations. -.PP -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 +.Pp +The +.Nm +file is a free-form ASCII text file. +It is parsed by the recursive-descent parser built into +.Xr dhcpd 8 . +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 +.Sq # +character and end at the end of the line. +.Pp +The file essentially consists of a list of statements. +Statements fall into two broad categories \- parameters and declarations. +.Pp +Parameter statements say how to do something (e.g., how long a +lease to offer), whether to do something (e.g., should +.Xr dhcpd 8 +provide addresses to unknown clients), or what parameters to provide to the client (e.g., use gateway 220.177.244.7). -.PP +.Pp 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. -.PP +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. +.Pp Declarations about network topology include the - \fIshared-network\fR and the \fIsubnet\fR -declarations. If clients on a subnet are to be assigned addresses -dynamically, a \fIrange\fR declaration must appear within the -\fIsubnet\fR declaration. For clients with statically assigned -addresses, or for installations where only known clients will be -served, each such client must have a \fIhost\fR declaration. If -parameters are to be applied to a group of declarations which are not -related strictly on a per-subnet basis, the \fIgroup\fR declaration -can be used. -.PP +.Ic shared-network +and the +.Ic subnet +declarations. +If clients on a subnet are to be assigned addresses dynamically, a +.Ic range +declaration must appear within the +.Ic subnet +declaration. +For clients with statically assigned addresses, or for installations where +only known clients will be served, each such client must have a +.Ic host +declaration. +If parameters are to be applied to a group of declarations which are not +related strictly on a per-subnet basis, the +.Ic group +declaration can be used. +.Pp For every subnet which will be served, and for every subnet -to which the dhcp server is connected, there must be one \fIsubnet\fR -declaration, which tells dhcpd how to recognize that an address is on -that subnet. A \fIsubnet\fR declaration is required for each subnet -even if no addresses will be dynamically allocated on that subnet. -.PP +to which the dhcp server is connected, there must be one +.Ic subnet +declaration, which tells +.Xr dhcpd 8 +how to recognize that an address is on that subnet. +A +.Ic subnet +declaration is required for each subnet even if no addresses will be +dynamically allocated on that subnet. +.Pp 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 \fIsubnet\fR declarations for these two networks may be -enclosed in a \fIshared-network\fR declaration. -.PP +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 +.Ic subnet +declarations for these two networks may be enclosed in a +.Ic shared-network +declaration. +.Pp 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 \fIhost\fR declarations, these -declarations can be enclosed in a \fIgroup\fR declaration along with -the parameters which are common to that department. For clients -whose addresses will be dynamically assigned, there is currently no +clients from other departments on the same subnet. +For clients which will be declared explicitly with +.Ic host +declarations, these declarations can be enclosed in a +.Ic 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. -.PP +.Pp When a client is to be booted, its boot parameters are determined by -first consulting that client's \fIhost\fR declaration (if any), then -consulting the \fIgroup\fR declaration (if any) which enclosed that -\fIhost\fR declaration, then consulting the \fIsubnet\fR declaration -for the subnet on which the client is booting, then consulting the -\fIshared-network\fR declaration (if any) containing that subnet, and -finally consulting the top-level parameters which may be specified -outside of any declaration. -.PP -When dhcpd tries to find a \fIhost\fR declaration for a client, it -first looks for a \fIhost\fR declaration which has a -\fIfixed-address\fR 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 \fIfixed-address\fR -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. -.SH EXAMPLES -.PP -A typical dhcpd.conf file will look something like this: -.nf - -.I global parameters... +first consulting that client's +.Ic host +declaration (if any), then consulting the +.Ic group +declaration (if any) which enclosed that +.Ic host +declaration, then consulting the +.Ic subnet +declaration for the subnet on which the client is booting, then consulting the +.Ic shared-network +declaration (if any) containing that subnet, and finally consulting the +top-level parameters which may be specified outside of any declaration. +.Pp +When +.Xr dhcpd 8 +tries to find a +.Ic host +declaration for a client, it first looks for a +.Ic host +declaration which has a +.Ar 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 +.Ar fixed-address +parameter. +If no such entry is found, then +.Xr dhcpd 8 +acts as if there is no entry in the +.Nm +file for that client, even if there is an entry for that client on a +different subnet or shared network. +.Sh EXAMPLES +A typical +.Nm +file will look something like this: +.Pp +Example 1 +.Bd -unfilled -offset indent +.Ar global parameters... shared-network ISC-BIGGIE { - \fIshared-network-specific parameters...\fR +.Ar \ \&\ \&shared-network-specific parameters... subnet 204.254.239.0 netmask 255.255.255.224 { - \fIsubnet-specific parameters...\fR +.Ar \ \&\ \&\ \&\ \&subnet-specific parameters... range 204.254.239.10 204.254.239.30; } subnet 204.254.239.32 netmask 255.255.255.224 { - \fIsubnet-specific parameters...\fR +.Ar \ \&\ \&\ \&\ \&subnet-specific parameters... range 204.254.239.42 204.254.239.62; } } subnet 204.254.239.64 netmask 255.255.255.224 { - \fIsubnet-specific parameters...\fR +.Ar \ \&\ \&subnet-specific parameters... range 204.254.239.74 204.254.239.94; } group { - \fIgroup-specific parameters...\fR +.Ar \ \&\ \&group-specific parameters... host zappo.test.isc.org { - \fIhost-specific parameters...\fR +.Ar \ \&\ \&\ \&\ \&host-specific parameters... } host beppo.test.isc.org { - \fIhost-specific parameters...\fR +.Ar \ \&\ \&\ \&\ \&host-specific parameters... } host harpo.test.isc.org { - \fIhost-specific parameters...\fR +.Ar \ \&\ \&\ \&\ \&host-specific parameters... } } - -.ce 1 -Figure 1 - -.fi -.PP +.Ed +.Pp 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: -.nf - - option domain-name "isc.org"; - option domain-name-servers ns1.isc.org, ns2.isc.org; - -.ce 1 -Figure 2 -.fi -.PP -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 +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: +.Pp +Example 2 +.Bd -literal -offset indent +option domain-name \&"isc.org\&"; +option domain-name-servers ns1.isc.org, ns2.isc.org; +.Ed +.Pp +As you can see in Example 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. -.PP -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 \fIISC-BIGGIE\fR supports an entire department - -perhaps the accounting department. If accounting has its own domain, -then a shared-network-specific parameter might be: -.nf - - option domain-name "accounting.isc.org"; -.fi -.PP +.Pp +In Example 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: +.Pp +.Dl option domain-name \&"accounting.isc.org\&"; +.Pp 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". -.PP +would then have the domain-name option set to +.Dq accounting.isc.org +instead of just +.Dq isc.org . +.Pp 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: -.nf - - option routers 204.254.239.1; -.fi -.PP -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. -.PP -In Figure 1 there is also a \fIgroup\fR statement, which provides -common parameters for a set of three hosts - zappo, beppo and harpo. +shown in Example 1 is that each subnet, of necessity, has its own router. +So for the first subnet, for example, there should be something like: +.Pp +.Dl option routers 204.254.239.1; +.Pp +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. +.Pp +In Example 1 there is also a +.Ic 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: -.nf - - option domain-name "test.isc.org"; -.fi -.PP +.Pp +.Dl option domain-name \&"test.isc.org\&"; +.Pp 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: - -.nf - max-lease-time 120; - default-lease-time 120; -.fi -.PP +.Pp +.Bd -literal -offset indent +max-lease-time 120; +default-lease-time 120; +.Ed +.Pp You may have noticed that while some parameters start with the -\fIoption\fR keyword, some do not. Parameters starting with the -\fIoption\fR 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 +.Ic option +keyword, some do not. +Parameters starting with the +.Ic 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 +.Xr dhcpd 8 +will give out), or specify client parameters that are not optional in the DHCP protocol (for example, server-name and filename). -.PP -In Figure 1, each host had \fIhost-specific parameters\fR. These -could include such things as the \fIhostname\fR option, the name of a -file to upload (the \fIfilename\fR parameter) and the address of the -server from which to upload the file (the \fInext-server\fR -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. -.PP -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 model. One way to do this would be to have host -declarations for each server and group them by model: -.nf - +.Pp +In Example 1, each host had +.Ar host-specific parameters . +These could include such things as the +.Ic hostname +option, the name of a file to upload (the +.Ar filename +parameter) and the address of the server from which to upload the file (the +.Ar 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. +.Pp +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 model. +One way to do this would be to have host declarations for each server +and group them by model: +.Pp +.Bd -literal -offset indent group { filename "Xncd19r"; next-server ncd-booter; @@ -271,510 +323,626 @@ 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; } + host ncd5 { hardware ethernet 0:c0:c3:11:90:23; } + host ncd6 { hardware ethernet 0:c0:c3:91:a7:8; } + host ncd7 { hardware ethernet 0:c0:c3:cc:a:8f; } +} +.Ed +.Sh REFERENCE: DECLARATIONS +The +.Ic shared-network +statement +.Pp +.Bd -unfilled -offset indent +.Ic shared-network Ar name No { +.Pf \ \&\ \& Op Ar parameters +.Pf \ \&\ \& Op Ar declarations } -.fi -.SH REFERENCE: DECLARATIONS -.PP -.B The -.I shared-network -.B statement -.PP -.nf - \fBshared-network\fR \fIname\fR \fB{\fR - [ \fIparameters\fR ] - [ \fIdeclarations\fR ] - \fB}\fR -.fi -.PP -The \fIshared-network\fR 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 -\fIshared-network\fR statement. Parameters specified in the -\fIshared-network\fR 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. +.Ed +.Pp +The +.Ic 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 +.Ic shared-network +statement. +Parameters specified in the +.Ic 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. -.PP -.I 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 +.Pp +.Ar 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. -.PP -.B The -.I subnet -.B statement -.PP -.nf - \fBsubnet\fR \fIsubnet-number\fR \fBnetmask\fR \fInetmask\fR \fB{\fR - [ \fIparameters\fR ] - [ \fIdeclarations\fR ] - \fB}\fR -.fi -.PP -The \fIsubnet\fR statement is used to provide dhcpd with enough -information to tell whether or not an IP address is on that subnet. +.Pp +The +.Ic subnet +statement +.Pp +.Bd -unfilled -offset indent +.Ic subnet Ar subnet-number Ic netmask Ar netmask No { +.Pf \ \&\ \& Op Ar parameters +.Pf \ \&\ \& Op Ar declarations +} +.Ed +.Pp +The +.Ic subnet +statement is used to provide +.Xr dhcpd 8 +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 \fIrange\fR +on that subnet. +Such addresses are specified using the +.Ic range declaration. -.PP +.Pp The -.I subnet-number +.Ar subnet-number should be an IP address or domain name which resolves to the subnet -number of the subnet being described. The -.I netmask +number of the subnet being described. +The +.Ar 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. -.PP +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. +.Pp 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. -.PP -.B The -.I range -.B statement -.PP -.nf - \fBrange\fR [ \fBdynamic-bootp\fR ] \fIlow-address\fR [ \fIhigh-address\fR]\fB;\fR -.fi -.PP +.Pp +The +.Ic range +statement +.Pp +.Xo +.Ic range Op Ic dynamic-bootp +.Ar low-address Oo Ar high-address Oc ; +.Xc +.Pp For any subnet on which addresses will be assigned dynamically, there -must be at least one \fIrange\fR 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 -\fIrange\fR statement is declared. The \fIdynamic-bootp\fR 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, \fIhigh-address\fR can be omitted. -.PP -.B The -.I host -.B statement -.PP -.nf - \fBhost\fR \fIhostname\fR { - [ \fIparameters\fR ] - [ \fIdeclarations\fR ] - \fB}\fR -.fi -.PP +must be at least one +.Ic 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 +.Ic range +statement is declared. +The +.Ic 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, +.Ar high-address +can be omitted. +.Pp +The +.Ic host +statement +.Pp +.Bd -unfilled -offset indent +.Ic host Ar hostname No { +.Pf \ \&\ \& Op Ar parameters +.Pf \ \&\ \& Op Ar declarations +} +.Ed +.Pp There must be at least one -.B host -statement for every BOOTP client that is to be served. -.B host +.Ic host +statement for every BOOTP client that is to be served. +.Ic host statements may also be specified for DHCP clients, although this is not required unless booting is only enabled for known hosts. -.PP +.Pp 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 -.I fixed-address +.Ar fixed-address parameter, or more than one -.B host +.Ic host statement may be specified. -.PP +.Pp If client-specific boot parameters must change based on the network -to which the client is attached, then multiple -.B host -statements should -be used. -.PP +to which the client is attached, then multiple +.Ic host +statements should be used. +.Pp 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 -.B host +.Ic host statement must be specified without a -.B fixed-address +.Ar fixed-address clause. -.I hostname -should be a name identifying the host. If a \fIhostname\fR option is -not specified for the host, \fIhostname\fR is used. -.PP -\fIHost\fR declarations are matched to actual DHCP or BOOTP clients -by matching the \fRdhcp-client-identifier\fR option specified in the -\fIhost\fR declaration to the one supplied by the client, or, if the -\fIhost\fR declaration or the client does not provide a -\fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR -parameter in the \fIhost\fR declaration to the network hardware -address supplied by the client. BOOTP clients do not normally -provide a \fIdhcp-client-identifier\fR, so the hardware address must -be used for all clients that may boot using the BOOTP protocol. -.PP -.B The -.I group -.B statement -.PP -.nf - \fBgroup\fR { - [ \fIparameters\fR ] - [ \fIdeclarations\fR ] - \fB}\fR -.fi -.PP -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. -.SH REFERENCE: ALLOW and DENY -.PP -The -.I allow +.Ar hostname +should be a name identifying the host. +If a +.Ar hostname +option is not specified for the host, +.Ar hostname +is used. +.Pp +.Ic host +declarations are matched to actual DHCP or BOOTP clients by matching the +.Ic dhcp-client-identifier +option specified in the +.Ic host +declaration to the one supplied by the client, or, if the +.Ic host +declaration or the client does not provide a +.Ic dhcp-client-identifier +option, by matching the +.Ar hardware +parameter in the +.Ic host +declaration to the network hardware address supplied by the client. +BOOTP clients do not normally provide a +.Ar dhcp-client-identifier , +so the hardware address must be used for all clients that may boot using +the BOOTP protocol. +.Pp +The +.Ic group +statement +.Pp +.Bd -unfilled -offset indent +.Ic group No { +.Pf \ \&\ \& Op Ar parameters +.Pf \ \&\ \& Op Ar declarations +} +.Ed +.Pp +The +.Ic 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. +.Sh REFERENCE: ALLOW and DENY +The +.Ic allow and -.I deny -statements can be used to control the behaviour of dhcpd to various -sorts of requests. -.PP -.PP -.B The -.I unknown-clients -.B keyword -.PP - \fBallow unknown-clients;\fR - \fBdeny unknown-clients;\fR -.PP -The \fBunknown-clients\fR flag is used to tell dhcpd whether -or not to dynamically assign addresses to unknown clients. Dynamic -address assignment to unknown clients is \fBallow\fRed by default. -.PP -.B The -.I bootp -.B keyword -.PP - \fBallow bootp;\fR - \fBdeny bootp;\fR -.PP -The \fBbootp\fR flag is used to tell dhcpd whether -or not to respond to bootp queries. Bootp queries are \fBallow\fRed -by default. -.PP -.B The -.I booting -.B keyword -.PP - \fBallow booting;\fR - \fBdeny booting;\fR -.PP -The \fBbooting\fR 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 -\fBallow\fRed, but if it is disabled for a particular client, then -that client will not be able to get an address from the DHCP server. -.SH REFERENCE: PARAMETERS -.PP -.B The -.I default-lease-time -.B statement -.PP - \fBdefault-lease-time\fR \fItime\fR\fB;\fR -.PP -.I Time +.Ic deny +statements can be used to control the behaviour of +.Xr dhcpd 8 +to various sorts of requests. +.Pp +The +.Ar unknown-clients +keyword +.Pp +.Bd -literal -offset indent +allow unknown-clients; +deny unknown-clients; +.Ed +.Pp +The +.Ar unknown-clients +flag is used to tell +.Xr dhcpd 8 +whether or not to dynamically assign addresses to unknown clients. +Dynamic address assignment to unknown clients is allowed by default. +.Pp +The +.Ar bootp +keyword +.Pp +.Bd -literal -offset indent +allow bootp; +deny bootp; +.Ed +.Pp +The +.Ar bootp +flag is used to tell +.Xr dhcpd 8 +whether or not to respond to bootp queries. +Bootp queries are allowed by default. +.Pp +The +.Ar booting +keyword +.Pp +.Bd -literal -offset indent +allow booting; +deny booting; +.Ed +.Pp +The +.Ar booting +flag is used to tell +.Xr dhcpd 8 +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 an address from the DHCP server. +.Sh REFERENCE: PARAMETERS +The +.Ic default-lease-time +statement +.Pp +.D1 Ic default-lease-time Ar time ; +.Pp +.Ar 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. -.PP -.B The -.I max-lease-time -.B statement -.PP - \fBmax-lease-time\fR \fItime\fR\fB;\fR -.PP -.I Time +the client requesting the lease does not ask for a specific expiration time. +.Pp +The +.Ic max-lease-time +statement +.Pp +.D1 Ic max-lease-time Ar time ; +.Pp +.Ar 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. -.PP -.B The -.I hardware -.B statement -.PP - \fBhardware\fR \fIhardware-type\fR \fIhardware-address\fR\fB;\fR -.PP +lease if the client requesting the lease asks for a specific expiration time. +.Pp +The +.Ic hardware +statement +.Pp +.D1 Ic hardware Ar hardware-type hardware-address ; +.Pp In order for a BOOTP client to be recognized, its network hardware -address must be declared using a \fIhardware\fR clause in the -.I host +address must be declared using a +.Ic hardware +clause in the +.Ic host statement. -.I hardware-type -must be the name of a physical hardware interface type. Currently, -only the -.B ethernet +.Ar hardware-type +must be the name of a physical hardware interface type. +Currently, only the +.Ar ethernet and -.B token-ring -types are recognized, although support for a -.B fddi +.Ar token-ring +types are recognized, although support for an +.Ar fddi hardware type (and others) would also be desirable. The -.I hardware-address +.Ar hardware-address should be a set of hexadecimal octets (numbers from 0 through ff) -separated by colons. The \fIhardware\fR statement may also be used -for DHCP clients. -.PP -.B The -.I filename -.B statement -.PP - \fBfilename\fR \fB"\fR\fIfilename\fR\fB";\fR -.PP -The \fIfilename\fR statement can be used to specify the name of the -initial boot file which is to be loaded by a client. The -.I filename +separated by colons. +The +.Ic hardware +statement may also be used for DHCP clients. +.Pp +The +.Ic filename +statement +.Pp +.D1 Ic filename Ar \&"filename\&" ; +.Pp +The +.Ic filename +statement can be used to specify the name of the initial boot file which +is to be loaded by a client. +The +.Ar filename should be a filename recognizable to whatever file transfer protocol the client can be expected to use to load the file. -.PP -.B The -.I server-name -.B statement -.PP - \fBserver-name\fR \fB"\fR\fIname\fR\fB";\fR -.PP -The \fIserver-name\fR statement can be used to inform the client of -the name of the server from which it is booting. \fIName\fR should -be the name that will be provided to the client. -.PP -.B The -.I next-server -.B statement -.PP - \fBnext-server\fR \fIserver-name\fR\fB;\fR -.PP -The \fInext-server\fR statement is used to specify the host address of +.Pp +The +.Ic server-name +statement +.Pp +.D1 Ic server-name Ar \&"name\&" ; +.Pp +The +.Ic server-name +statement can be used to inform the client of the name of the server +from which it is booting. +.Ar name +should be the name that will be provided to the client. +.Pp +The +.Ic next-server +statement +.Pp +.D1 Ic next-server Ar server-name ; +.Pp +The +.Ic next-server +statement is used to specify the host address of the server from which the initial boot file (specified in the -\fIfilename\fR statement) is to be loaded. \fIServer-name\fR should -be a numeric IP address or a domain name. If no \fInext-server\fR -parameter applies to a given client, the DHCP server's IP address is -used. -.PP -.B The -.I fixed-address -.B statement -.PP - \fBfixed-address\fR \fIaddress\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR -.PP -The \fIfixed-address\fR statement is used to assign one or more fixed -IP addresses to a client. It should only appear in a \fIhost\fR -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 -\fIfixed-address\fR statement are on the network on which the client -is booting, that client will not match the \fIhost\fR declaration -containing that \fIfixed-address\fR statement. Each \fIaddress\fR +.Ic filename +statement) is to be loaded. +.Ar server-name +should be a numeric IP address or a domain name. +If no +.Ic next-server +parameter applies to a given client, the DHCP server's IP address is used. +.Pp +The +.Ic fixed-address +statement +.Pp +.Xo +.Ic \ \&fixed-address Ar address +.Op , Ar address ... ; +.Xc +.Pp +The +.Ic fixed-address +statement is used to assign one or more fixed IP addresses to a client. +It should only appear in a +.Ic 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 +.Ic fixed-address +statement are on the network on which the client is booting, that client will +not match the +.Ic host +declaration containing that +.Ic fixed-address +statement. +Each +.Ar address should be either an IP address or a domain name which resolves to one or more IP addresses. -.PP -.B The -.I dynamic-bootp-lease-cutoff -.B statement -.PP - \fBdynamic-bootp-lease-cutoff\fR \fIdate\fR\fB;\fR -.PP -The \fIdynamic-bootp-lease-cutoff\fR 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 +.Pp +The +.Ic dynamic-bootp-lease-cutoff +statement +.Pp +.D1 Ic dynamic-bootp-lease-cutoff Ar date ; +.Pp +The +.Ic 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 +.Xr dhcpd 8 +assigns 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. -.PP -.I Date -should be the date on which all assigned BOOTP leases will end. The -date is specified in the form: -.PP -.ce 1 -W YYYY/MM/DD HH:MM:SS -.PP -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. -.PP -.B The -.I dynamic-bootp-lease-length -.B statement -.PP - \fBdynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR -.PP -The \fIdynamic-bootp-lease-length\fR 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 +.Pp +.Ar date +should be the date on which all assigned BOOTP leases will end. +The date is specified in the form: +.Pp +.Dl W YYYY/MM/DD HH:MM:SS +.Pp +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 Coordinated Universal Time (UTC), not local time. +.Pp +The +.Ic dynamic-bootp-lease-length +statement +.Pp +.D1 Ic dynamic-bootp-lease-length Ar length ; +.Pp +The +.Ic 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 \fIlength\fR as a -number of seconds. If a client reboots using BOOTP during the -timeout period, the lease duration is reset to \fIlength\fR, so a -BOOTP client that boots frequently enough will never lose its lease. -Needless to say, this parameter should be adjusted with extreme -caution. -.PP -.B The -.I get-lease-hostnames -.B statement -.PP - \fBget-lease-hostnames\fR \fIflag\fR\fB;\fR -.PP -The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether -or not to look up the domain name corresponding to the IP address of +a certain time period. +The period is specified in +.Ar length +as a number of seconds. +If a client reboots using BOOTP during the timeout period, the lease +duration is reset to +.Ar 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. +.Pp +The +.Ic get-lease-hostnames +statement +.Pp +.D1 Ic get-lease-hostnames Ar flag ; +.Pp +The +.Ic get-lease-hostnames +statement is used to tell +.Xr dhcpd 8 +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 -\fIhostname\fR option. If \fIflag\fR is true, then this lookup is -done for all addresses in the current scope. By default, or if -\fIflag\fR is false, no lookups are done. -.PP -.B The -.I use-host-decl-names -.B statement -.PP - \fBuse-host-decl-names\fR \fIflag\fR\fB;\fR -.PP -If the \fIuse-host-decl-names\fR 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, -.PP -.nf - group { - use-host-decl-names on; - - host joe { - hardware ethernet 08:00:2b:4c:29:32; - fixed-address joe.fugue.com; - } - } +.Ic hostname +option. +If +.Ar flag +is true, then this lookup is done for all addresses in the current scope. +By default, or if +.Ar flag +is false, no lookups are done. +.Pp +The +.Ic use-host-decl-names +statement +.Pp +.D1 Ic use-host-decl-names Ar flag ; +.Pp +If the +.Ic 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, +.Pp +.Bd -literal -offset indent +group { + use-host-decl-names on; + host joe { + hardware ethernet 08:00:2b:4c:29:32; + fixed-address joe.fugue.com; + } +} +.Ed +.Pp is equivalent to - - host joe { - hardware ethernet 08:00:2b:4c:29:32; - fixed-address joe.fugue.com; - option host-name "joe"; - } -.fi -.PP -An \fIoption host-name\fR statement within a host declaration will -override the use of the name in the host declaration. -.PP -.B The -.I authoritative -.B statement -.PP - \fBauthoritative;\fR -.PP - \fBnot authoritative;\fR -.PP +.Pp +.Bd -literal -offset indent + host joe { +hardware ethernet 08:00:2b:4c:29:32; +fixed-address joe.fugue.com; + option host-name "joe"; + } +.Ed +.Pp +An +.Ic option host-name +statement within a host declaration will override the use of the name +in the host declaration. +.Pp +The +.Ic authoritative +statement +.Pp +.D1 Ic authoritative ; +.Pp +.D1 Ic not authoritative ; +.Pp 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. -.PP +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. +.Pp 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. -.PP -Usually, writing \fBnot authoritative;\fR 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. -.PP +level of authority, then the statement +.Dq not authoritative +should be written in the appropriate scope in the configuration file. +.Pp +Usually, writing +.Em 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. +.Pp Note that the most specific scope for which the concept of authority -makes any sense is the physical network segment - either a +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. -.PP -.B The -.I use-lease-addr-for-default-route -.B statement -.PP - \fBuse-lease-addr-for-default-route\fR \fIflag\fR\fB;\fR -.PP -If the \fIuse-lease-addr-for-default-route\fR 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. -.PP -If use-lease-addr-for-default-route is enabled and an option routers -statement are both in scope, the routers option will be preferred. +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. +.Pp +The +.Ic use-lease-addr-for-default-route +statement +.Pp +.D1 Ic use-lease-addr-for-default-route Ar flag ; +.Pp +If the +.Ic 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. +.Pp +If +.Ic 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 your +Windows 95 machines, and you want to override it for a few other machines. +Unfortunately, if the opposite happens to be true for your site, you are probably better off not trying to use this flag. -.PP -.B The -.I always-reply-rfc1048 -.B statement -.PP - \fBalways-reply-rfc1048\fR \fIflag\fR\fB;\fR -.PP -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. -.PP -If you want to send rfc1048 options to such a client, you can set the -.B always-reply-rfc1048 +.Pp +The +.Ic always-reply-rfc1048 +statement +.Pp +.D1 Ic always-reply-rfc1048 Ar flag ; +.Pp +Some BOOTP clients expect RFC 1048-style responses, but do not follow +RFC 1048 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 +.Dq (non-rfc1048) +printed with each BOOTREQUEST that is logged. +.Pp +If you want to send RFC 1048 options to such a client, you can set the +.Ic 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. -.PP -.B The -.I server-identifier -.B statement -.PP - \fBserver-identifier \fIhostname\fR\fB;\fR -.PP -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 \fBmust\fR be an IP address for the DHCP server, and -must be reachable by all clients served by a particular scope. -.PP -The use of the server-identifier statement is not recommended - the only +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. +.Pp +The +.Ic server-identifier +statement +.Pp +.D1 Ic server-identifier Ar hostname ; +.Pp +The +.Ic 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 +.Em must +be an IP address for the DHCP server, and must be reachable by all +clients served by a particular scope. +.Pp +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. -.PP +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. +.Pp The usual case where the -\fIserver-identifier\fR 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. +.Ic 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. -.PP -Supplying a value for the dhcp-server-identifier option is equivalent -to using the server-identifier statement. -.SH REFERENCE: OPTION STATEMENTS -.PP +.Pp +Supplying a value for the +.Ic dhcp-server-identifier +option is equivalent to using the +.Ic server-identifier +statement. +.Sh REFERENCE: OPTION STATEMENTS DHCP option statements are documented in the -.B dhcp-options(5) +.Xr dhcp-options 5 manual page. -.SH SEE ALSO -dhcpd.conf(5), dhcpd.leases(5), RFC2132, RFC2131. -.SH AUTHOR -.B 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. +.Sh SEE ALSO +.Xr dhcp-options 5 , +.Xr dhcpd.leases 5 , +.Xr dhcpd 8 +.Pp +RFC 2132, RFC 2131. +.Sh AUTHORS +.Xr dhcpd 8 +was written by +.An Ted Lemon Aq 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 -.B http://www.isc.org/isc. +.Pa http://www.isc.org/isc . |