1 .\" $NetBSD: dhcp-eval.5,v 1.1.1.3 2014/07/12 11:57:40 spz Exp $
3 .\" Id: dhcp-eval.5,v 1.33 2012/05/17 15:50:14 sar Exp
5 .\" Copyright (c) 2009-2012,2014 by Internet Systems Consortium, Inc. ("ISC")
6 .\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
7 .\" Copyright (c) 1996-2003 by Internet Software Consortium
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
19 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\" Internet Systems Consortium, Inc.
22 .\" 950 Charter Street
23 .\" Redwood City, CA 94063
25 .\" https://www.isc.org/
27 .\" Support and other services are available for ISC products - see
28 .\" https://www.isc.org for more information or to learn more about ISC.
32 dhcp-eval - ISC DHCP conditional evaluation
34 The Internet Systems Consortium DHCP client and server both provide
35 the ability to perform conditional behavior depending on the contents
36 of packets they receive. The syntax for specifying this conditional
37 behaviour is documented here.
38 .SH REFERENCE: CONDITIONAL BEHAVIOUR
39 Conditional behaviour is specified using the if statement and the else
40 or elsif statements. A conditional statement can appear anywhere
41 that a regular statement (e.g., an option statement) can appear, and
42 can enclose one or more such statements. A typical conditional
43 statement in a server might be:
46 if option dhcp-user-class = "accounting" {
48 option domain-name "accounting.example.org";
49 option domain-name-servers ns1.accounting.example.org,
50 ns2.accounting.example.org;
51 } elsif option dhcp-user-class = "sales" {
53 option domain-name "sales.example.org";
54 option domain-name-servers ns1.sales.example.org,
55 ns2.sales.example.org;
56 } elsif option dhcp-user-class = "engineering" {
58 option domain-name "engineering.example.org";
59 option domain-name-servers ns1.engineering.example.org,
60 ns2.engineering.example.org;
63 option domain-name "misc.example.org";
64 option domain-name-servers ns1.misc.example.org,
69 On the client side, an example of conditional evaluation might be:
72 # example.org filters DNS at its firewall, so we have to use their DNS
73 # servers when we connect to their network. If we are not at
74 # example.org, prefer our own DNS server.
75 if not option domain-name = "example.org" {
76 prepend domain-name-servers 127.0.0.1;
84 continuation statement both take boolean expressions as their
85 arguments. That is, they take expressions that, when evaluated,
86 produce a boolean result. If the expression evaluates to true, then
87 the statements enclosed in braces following the
89 statement are executed, and all subsequent
93 clauses are skipped. Otherwise, each subsequent
95 clause's expression is checked, until an elsif clause is encountered
96 whose test evaluates to true. If such a clause is found, the
97 statements in braces following it are executed, and then any
102 clauses are skipped. If all the
106 clauses are checked but none
107 of their expressions evaluate true, then if there is an
109 clause, the statements enclosed in braces following the
111 are evaluated. Boolean expressions that evaluate to null are
112 treated as false in conditionals.
113 .SH BOOLEAN EXPRESSIONS
114 The following is the current list of boolean expressions that are
115 supported by the DHCP distribution.
117 .I data-expression-1 \fB=\fR \fIdata-expression-2\fR
120 The \fB=\fR operator compares the values of two data expressions,
121 returning true if they are the same, false if they are not. If
122 either the left-hand side or the right-hand side are null, the
126 .I data-expression-1 \fB~=\fR \fIdata-expression-2\fR
127 .I data-expression-1 \fB~~\fR \fIdata-expression-2\fR
130 The \fB~=\fR and \fB~~\fR operators (not available on all systems) perform
131 extended regex(7) matching of the values of two data expressions, returning
132 true if \fIdata-expression-1\fR matches against the regular expression
133 evaluated by \fIdata-expression-2\fR, or false if it does not match or
134 encounters some error. If either the left-hand side or the right-hand side
135 are null or empty strings, the result is also false. The \fB~~\fR operator
136 differs from the \fB~=\fR operator in that it is case-insensitive.
139 .I boolean-expression-1 \fBand\fR \fIboolean-expression-2\fR
142 The \fBand\fR operator evaluates to true if the boolean expression on
143 the left-hand side and the boolean expression on the right-hand side
144 both evaluate to true. Otherwise, it evaluates to false. If either
145 the expression on the left-hand side or the expression on the
146 right-hand side are null, the result is null.
149 .I boolean-expression-1 \fBor\fR \fIboolean-expression-2\fR
152 The \fBor\fR operator evaluates to true if either the boolean
153 expression on the left-hand side or the boolean expression on the
154 right-hand side evaluate to true. Otherwise, it evaluates to false.
155 If either the expression on the left-hand side or the expression on
156 the right-hand side are null, the result is null.
159 .B not \fIboolean-expression
162 The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR
163 evaluates to false, and returns false if \fIboolean-expression\fR evaluates
164 to true. If \fIboolean-expression\fR evaluates to null, the result
168 .B exists \fIoption-name\fR
171 The \fBexists\fR expression returns true if the specified option
172 exists in the incoming DHCP packet being processed.
177 The \fBknown\fR expression returns true if the client whose request is
178 currently being processed is known - that is, if there's a host
184 The \fBstatic\fR expression returns true if the lease assigned to the
185 client whose request is currently being processed is derived from a static
189 Several of the boolean expressions above depend on the results of
190 evaluating data expressions. A list of these expressions is provided
193 .B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR
196 The \fBsubstring\fR operator evaluates the data expression and returns
197 the substring of the result of that evaluation that starts
198 \fIoffset\fR bytes from the beginning, continuing for \fIlength\fR
199 bytes. \fIOffset\fR and \fIlength\fR are both numeric expressions.
200 If \fIdata-expr\fR, \fIoffset\fR or \fIlength\fR evaluate to null,
201 then the result is also null. If \fIoffset\fR is greater than or
202 equal to the length of the evaluated data, then a zero-length data
203 string is returned. If \fIlength\fI is greater than the remaining
204 length of the evaluated data after \fIoffset\fR, then a data string
205 containing all data from \fIoffset\fR to the end of the evaluated data
209 .B suffix (\fIdata-expr\fB, \fIlength\fB)\fR
212 The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the
213 last \fIlength\fR bytes of the result of that evaluation. \fILength\fR
214 is a numeric expression. If \fIdata-expr\fR or \fIlength\fR evaluate
215 to null, then the result is also null. If \fIsuffix\fR evaluates to a
216 number greater than the length of the evaluated data, then the
217 evaluated data is returned.
220 .B lcase (\fIdata-expr\fB)\fR
223 The \fBlcase\fR function returns the result of evaluating
224 \fIdata-expr\fR converted to lower case. If \fIdata-expr\fR evaluates
225 to null, then the result is also null.
228 .B ucase (\fIdata-expr\fB)\fR
231 The \fBucase\fR function returns the result of evaluating
232 \fIdata-expr\fR converted to upper case. If \fIdata-expr\fR evaluates
233 to null, then the result is also null.
236 .B option \fIoption-name\fR
239 The \fBoption\fR operator returns the contents of the specified option in
240 the packet to which the server is responding.
243 .B config-option \fIoption-name\fR
246 The \fBconfig-option\fR operator returns the value for the specified option
247 that the DHCP client or server has been configured to send.
253 The \fBgethostname()\fR function returns a data string whose contents are a
254 character string, the results of calling gethostname() on the local
255 system with a size limit of 255 bytes (not including NULL terminator). This
256 can be used for example to configure dhclient to send the local hostname
257 without knowing the local hostname at the time dhclient.conf is written.
263 The \fBhardware\fR operator returns a data string whose first element
264 is the type of network interface indicated in packet being considered,
265 and whose subsequent elements are client's link-layer address. If
266 there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,
267 then the result is null. Hardware types include ethernet (1),
268 token-ring (6), and fddi (8). Hardware types are specified by the
269 IETF, and details on how the type numbers are defined can be found in
270 RFC2131 (in the ISC DHCP distribution, this is included in the doc/
274 .B packet (\fIoffset\fB, \fIlength\fB)\fR
277 The \fBpacket\fR operator returns the specified portion of the packet
278 being considered, or null in contexts where no packet is being
279 considered. \fIOffset\fR and \fIlength\fR are applied to the
280 contents packet as in the \fBsubstring\fR operator.
286 A string, enclosed in quotes, may be specified as a data expression,
287 and returns the text between the quotes, encoded in ASCII. The
288 backslash ('\\') character is treated specially, as in C programming: '\\t'
289 means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means
290 bell. Any octal value can be specified with '\\nnn', where nnn is any
291 positive octal number less than 0400. Any hexadecimal value can be
292 specified with '\\xnn', where nn is any positive hexadecimal number less
293 than or equal to 0xff.
296 .I colon-separated hexadecimal list
299 A list of hexadecimal octet values, separated by colons, may be
300 specified as a data expression.
303 .B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR
305 The expressions are evaluated, and the results of each evaluation are
306 concatenated in the sequence that the subexpressions are listed. If
307 any subexpression evaluates to null, the result of the concatenation
311 .B reverse (\fInumeric-expr1\fB, \fIdata-expr2\fB)\fR
313 The two expressions are evaluated, and then the result of evaluating
314 the data expression is reversed in place, using hunks of the size
315 specified in the numeric expression. For example, if the numeric
316 expression evaluates to four, and the data expression evaluates to
317 twelve bytes of data, then the reverse expression will evaluate to
318 twelve bytes of data, consisting of the last four bytes of the
319 input data, followed by the middle four bytes, followed by the first
325 In any context where the client whose request is being processed has
326 been assigned an IP address, this data expression returns that IP
327 address. In any context where the client whose request is being
328 processed has not been assigned an ip address, if this data expression
329 is found in executable statements executed on that client's behalf,
330 a log message indicating "there is no lease associated with this client"
331 is syslogged to the debug level (this is considered dhcpd.conf debugging
335 .B binary-to-ascii (\fInumeric-expr1\fB, \fInumeric-expr2\fB,
336 .B \fIdata-expr1\fB,\fR \fIdata-expr2\fB)\fR
338 Converts the result of evaluating data-expr2 into a text string
339 containing one number for each element of the result of evaluating
340 data-expr2. Each number is separated from the other by the result of
341 evaluating data-expr1. The result of evaluating numeric-expr1
342 specifies the base (2 through 16) into which the numbers should be
343 converted. The result of evaluating numeric-expr2 specifies the
344 width in bits of each number, which may be either 8, 16 or 32.
346 As an example of the preceding three types of expressions, to produce
347 the name of a PTR record for the IP address being assigned to a
348 client, one could write the following expression:
352 concat (binary-to-ascii (10, 8, ".",
353 reverse (1, leased-address)),
359 .B encode-int (\fInumeric-expr\fB, \fIwidth\fB)\fR
361 Numeric-expr is evaluated and encoded as a data string of the
362 specified width, in network byte order (most significant byte first).
363 If the numeric expression evaluates to the null value, the result is
367 .B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR
369 The pick-first-value function takes any number of data expressions as
370 its arguments. Each expression is evaluated, starting with the first
371 in the list, until an expression is found that does not evaluate to a
372 null value. That expression is returned, and none of the subsequent
373 expressions are evaluated. If all expressions evaluate to a null
374 value, the null value is returned.
379 The host-decl-name function returns the name of the host declaration
380 that matched the client whose request is currently being processed, if
381 any. If no host declaration matched, the result is the null value.
383 .SH NUMERIC EXPRESSIONS
384 Numeric expressions are expressions that evaluate to an integer. In
385 general, the maximum size of such an integer should not be assumed to
386 be representable in fewer than 32 bits, but the precision of such
387 integers may be more than 32 bits.
389 .B extract-int (\fIdata-expr\fB, \fIwidth\fB)\fR
392 The \fBextract-int\fR operator extracts an integer value in network
393 byte order from the result of evaluating the specified data
394 expression. Width is the width in bits of the integer to extract.
395 Currently, the only supported widths are 8, 16 and 32. If the
396 evaluation of the data expression doesn't provide sufficient bits to
397 extract an integer of the specified size, the null value is returned.
403 The duration of the current lease - that is, the difference between
404 the current time and the time that the lease expires.
410 Any number between zero and the maximum representable size may be
411 specified as a numeric expression.
417 The current state of the client instance being processed. This is
418 only useful in DHCP client configuration files. Possible values are:
421 Booting - DHCP client is in the INIT state, and does not yet have an
422 IP address. The next message transmitted will be a DHCPDISCOVER,
423 which will be broadcast.
426 Reboot - DHCP client is in the INIT-REBOOT state. It has an IP
427 address, but is not yet using it. The next message to be transmitted
428 will be a DHCPREQUEST, which will be broadcast. If no response is
429 heard, the client will bind to its address and move to the BOUND state.
432 Select - DHCP client is in the SELECTING state - it has received at
433 least one DHCPOFFER message, but is waiting to see if it may receive
434 other DHCPOFFER messages from other servers. No messages are sent in
438 Request - DHCP client is in the REQUESTING state - it has received at
439 least one DHCPOFFER message, and has chosen which one it will
440 request. The next message to be sent will be a DHCPREQUEST message,
441 which will be broadcast.
444 Bound - DHCP client is in the BOUND state - it has an IP address. No
445 messages are transmitted in this state.
448 Renew - DHCP client is in the RENEWING state - it has an IP address,
449 and is trying to contact the server to renew it. The next message to
450 be sent will be a DHCPREQUEST message, which will be unicast directly
454 Rebind - DHCP client is in the REBINDING state - it has an IP address,
455 and is trying to contact any server to renew it. The next message to
456 be sent will be a DHCPREQUEST, which will be broadcast.
458 .SH REFERENCE: ACTION EXPRESSIONS
460 .B log (\fIpriority\fB, \fIdata-expr\fB)\fR
463 Logging statements may be used to send information to the standard logging
464 channels. A logging statement includes an optional priority (\fBfatal\fR,
465 \fBerror\fR, \fBinfo\fR, or \fBdebug\fR), and a data expression.
467 Logging statements take only a single data expression argument, so if you
468 want to output multiple data values, you will need to use the \fBconcat\fR
469 operator to concatenate them.
472 .B execute (\fIcommand-path\fB [, \fIdata-expr1\fB, ... \fIdata-exprN\fB]);\fR
475 The \fBexecute\fR statement runs an external command. The first argument
476 is a string literal containing the name or path of the command to run.
477 The other arguments, if present, are either string literals or data-
478 expressions which evaluate to text strings, to be passed as command-line
479 arguments to the command.
481 \fBexecute\fR is synchronous; the program will block until the external
482 command being run has finished. Please note that lengthy program
483 execution (for example, in an "on commit" in dhcpd.conf) may result in
484 bad performance and timeouts. Only external applications with very short
485 execution times are suitable for use.
487 Passing user-supplied data to an external application might be dangerous.
488 Make sure the external application checks input buffers for validity.
489 Non-printable ASCII characters will be converted into dhcpd.conf language
490 octal escapes ("\\nnn"), make sure your external command handles them as
493 It is possible to use the execute statement in any context, not only
494 on events. If you put it in a regular scope in the configuration file
495 you will execute that command every time a scope is evaluated.
497 .SH REFERENCE: DYNAMIC DNS UPDATES
499 See the dhcpd.conf and dhclient.conf man pages for more information
502 dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-options(5), dhcpd(8),
503 dhclient(8), RFC2132, RFC2131.
505 Information about Internet Systems Consortium can be found at
506 .B https://www.isc.org.