1dhcp-eval(5) File Formats Manual dhcp-eval(5)
2
6 dhcp-eval - ISC DHCP conditional evaluation
7
9 The Internet Systems Consortium DHCP client and server both provide the
10 ability to perform conditional behavior depending on the contents of
11 packets they receive. The syntax for specifying this conditional be‐
12 haviour is documented here.
13
15 Conditional behaviour may be specified using the if statement and the
16 else or elsif statements or the switch and case statements. A condi‐
17 tional statement can appear anywhere that a regular statement (e.g., an
18 option statement) can appear, and can enclose one or more such state‐
19 ments.
20 CONDITIONAL BEHAVIOUR: IF
22 A typical conditional if statement in a server might be:
24 if option dhcp-user-class = "accounting" {
26 max-lease-time 17600;
27 option domain-name "accounting.example.org";
28 option domain-name-servers ns1.accounting.example.org,
29 ns2.accounting.example.org;
30 } elsif option dhcp-user-class = "sales" {
31 max-lease-time 17600;
32 option domain-name "sales.example.org";
33 option domain-name-servers ns1.sales.example.org,
34 ns2.sales.example.org;
35 } elsif option dhcp-user-class = "engineering" {
36 max-lease-time 17600;
37 option domain-name "engineering.example.org";
38 option domain-name-servers ns1.engineering.example.org,
39 ns2.engineering.example.org;
40 } else {
41 max-lease-time 600;
42 option domain-name "misc.example.org";
43 option domain-name-servers ns1.misc.example.org,
44 ns2.misc.example.org;
45 }
46 On the client side, an example of conditional evaluation might be:
48 # example.org filters DNS at its firewall, so we have to use their DNS
50 # servers when we connect to their network. If we are not at
51 # example.org, prefer our own DNS server.
52 if not option domain-name = "example.org" {
53 prepend domain-name-servers 127.0.0.1;
54 }
55 The if statement and the elsif continuation statement both take boolean
57 expressions as their arguments. That is, they take expressions that,
58 when evaluated, produce a boolean result. If the expression evaluates
59 to true, then the statements enclosed in braces following the if state‐
60 ment are executed, and all subsequent elsif and else clauses are
61 skipped. Otherwise, each subsequent elsif clause's expression is
62 checked, until an elsif clause is encountered whose test evaluates to
63 true. If such a clause is found, the statements in braces following it
64 are executed, and then any subsequent elsif and else clauses are
65 skipped. If all the if and elsif clauses are checked but none of their
66 expressions evaluate true, then if there is an else clause, the state‐
67 ments enclosed in braces following the else are evaluated. Boolean
68 expressions that evaluate to null are treated as false in conditionals.
69 CONDITIONAL BEHAVIOUR: SWITCH
71 The above example can be rewritten using a switch construct as well.
73 switch (option dhcp-user-class) {
75 case "accounting":
76 max-lease-time 17600;
77 option domain-name "accounting.example.org";
78 option domain-name-servers ns1.accounting.example.org,
79 ns2.accounting.example.org;
80 case "sales":
81 max-lease-time 17600;
82 option domain-name "sales.example.org";
83 option domain-name-servers ns1.sales.example.org,
84 ns2.sales.example.org;
85 break;
86 case "engineering":
87 max-lease-time 17600;
88 option domain-name "engineering.example.org";
89 option domain-name-servers ns1.engineering.example.org,
90 ns2.engineering.example.org;
91 break;
92 default:
93 max-lease-time 600;
94 option domain-name "misc.example.org";
95 option domain-name-servers ns1.misc.example.org,
96 ns2.misc.example.org;
97 break;
98 }
99 The switch statement and the case statements can both be data expres‐
101 sions or numeric expressions. Within a switch statement they all must
102 be the same type. The server evaluates the expression from the switch
103 statement and then it evaluates the expressions from the case state‐
104 ments until it finds a match.
105 If it finds a match it starts executing statements from that case until
107 the next break statement. If it doesn't find a match it starts from
108 the default statement and again proceeds to the next break statement.
109 If there is no match and no default it does nothing.
110
112 The following is the current list of boolean expressions that are sup‐
113 ported by the DHCP distribution.
114 data-expression-1 = data-expression-2
116 The = operator compares the values of two data expressions, returning
118 true if they are the same, false if they are not. If either the
119 left-hand side or the right-hand side are null, the result is also
120 null.
121 data-expression-1 ~= data-expression-2 data-expression-1 ~~ data-
123 expression-2
124 The ~= and ~~ operators (not available on all systems) perform
126 extended regex(7) matching of the values of two data expressions,
127 returning true if data-expression-1 matches against the regular
128 expression evaluated by data-expression-2, or false if it does not
129 match or encounters some error. If either the left-hand side or the
130 right-hand side are null or empty strings, the result is also false.
131 The ~~ operator differs from the ~= operator in that it is case-
132 insensitive.
133 boolean-expression-1 and boolean-expression-2
135 The and operator evaluates to true if the boolean expression on the
137 left-hand side and the boolean expression on the right-hand side both
138 evaluate to true. Otherwise, it evaluates to false. If either the
139 expression on the left-hand side or the expression on the right-hand
140 side are null, the result is null.
141 boolean-expression-1 or boolean-expression-2
143 The or operator evaluates to true if either the boolean expression on
145 the left-hand side or the boolean expression on the right-hand side
146 evaluate to true. Otherwise, it evaluates to false. If either the
147 expression on the left-hand side or the expression on the right-hand
148 side are null, the result is null.
149 not boolean-expression
151 The not operator evaluates to true if boolean-expression evaluates to
153 false, and returns false if boolean-expression evaluates to true. If
154 boolean-expression evaluates to null, the result is also null.
155 exists option-name
157 The exists expression returns true if the specified option exists in
159 the incoming DHCP packet being processed.
160 known
161 The known expression returns true if the client whose request is cur‐
163 rently being processed is known - that is, if there's a host declara‐
164 tion for it.
165 static
166 The static expression returns true if the lease assigned to the
168 client whose request is currently being processed is derived from a
169 static address assignment.
170
172 Several of the boolean expressions above depend on the results of eval‐
173 uating data expressions. A list of these expressions is provided here.
174 substring (data-expr, offset, length)
176 The substring operator evaluates the data expression and returns the
178 substring of the result of that evaluation that starts offset bytes
179 from the beginning, continuing for length bytes. Offset and length
180 are both numeric expressions. If data-expr, offset or length evalu‐
181 ate to null, then the result is also null. If offset is greater than
182 or equal to the length of the evaluated data, then a zero-length data
183 string is returned. If length is greater then the remaining length
184 of the evaluated data after offset, then a data string containing all
185 data from offset to the end of the evaluated data is returned.
186 suffix (data-expr, length)
188 The suffix operator evaluates data-expr and returns the last length
190 bytes of the result of that evaluation. Length is a numeric expres‐
191 sion. If data-expr or length evaluate to null, then the result is
192 also null. If suffix evaluates to a number greater than the length
193 of the evaluated data, then the evaluated data is returned.
194 lcase (data-expr)
196 The lcase function returns the result of evaluating data-expr con‐
198 verted to lower case. If data-expr evaluates to null, then the
199 result is also null.
200 ucase (data-expr)
202 The ucase function returns the result of evaluating data-expr con‐
204 verted to upper case. If data-expr evaluates to null, then the
205 result is also null.
206 option option-name
208 The option operator returns the contents of the specified option in
210 the packet to which the server is responding.
211 config-option option-name
213 The config-option operator returns the value for the specified option
215 that the DHCP client or server has been configured to send.
216 gethostname()
218 The gethostname() function returns a data string whose contents are a
220 character string, the results of calling gethostname() on the local
221 system with a size limit of 255 bytes (not including NULL termina‐
222 tor). This can be used for example to configure dhclient to send the
223 local hostname without knowing the local hostname at the time
224 dhclient.conf is written.
225 hardware
227 The hardware operator returns a data string whose first element is
229 the type of network interface indicated in packet being considered,
230 and whose subsequent elements are client's link-layer address. If
231 there is no packet, or if the RFC2131 hlen field is invalid, then the
232 result is null. Hardware types include ethernet (1), token-ring (6),
233 and fddi (8). Hardware types are specified by the IETF, and details
234 on how the type numbers are defined can be found in RFC2131 (in the
235 ISC DHCP distribution, this is included in the doc/ subdirectory).
236 packet (offset, length)
238 The packet operator returns the specified portion of the packet being
240 considered, or null in contexts where no packet is being considered.
241 Offset and length are applied to the contents packet as in the sub‐
242 string operator.
243 string
245 A string, enclosed in quotes, may be specified as a data expression,
247 and returns the text between the quotes, encoded in ASCII. The back‐
248 slash ('\') character is treated specially, as in C programming: '\t'
249 means TAB, '\r' means carriage return, '\n' means newline, and '\b'
250 means bell. Any octal value can be specified with '\nnn', where nnn
251 is any positive octal number less than 0400. Any hexadecimal value
252 can be specified with '\xnn', where nn is any positive hexadecimal
253 number less than or equal to 0xff.
254 colon-separated hexadecimal list
256 A list of hexadecimal octet values, separated by colons, may be spec‐
258 ified as a data expression.
259 concat (data-expr1, ..., data-exprN)
261 The expressions are evaluated, and the results of each evaluation are
262 concatenated in the sequence that the subexpressions are listed. If
263 any subexpression evaluates to null, the result of the concatenation
264 is null.
265 reverse (numeric-expr1, data-expr2)
267 The two expressions are evaluated, and then the result of evaluating
268 the data expression is reversed in place, using hunks of the size
269 specified in the numeric expression. For example, if the numeric
270 expression evaluates to four, and the data expression evaluates to
271 twelve bytes of data, then the reverse expression will evaluate to
272 twelve bytes of data, consisting of the last four bytes of the input
273 data, followed by the middle four bytes, followed by the first four
274 bytes.
275 leased-address
277 In any context where the client whose request is being processed has
278 been assigned an IP address, this data expression returns that IP
279 address. In any context where the client whose request is being pro‐
280 cessed has not been assigned an ip address, if this data expression
281 is found in executable statements executed on that client's behalf, a
282 log message indicating "there is no lease associated with this
283 client" is syslogged to the debug level (this is considered
284 dhcpd.conf debugging information).
285 binary-to-ascii (numeric-expr1, numeric-expr2, data-expr1, data-expr2)
287 Converts the result of evaluating data-expr2 into a text string con‐
288 taining one number for each element of the result of evaluating data-
289 expr2. Each number is separated from the other by the result of
290 evaluating data-expr1. The result of evaluating numeric-expr1 speci‐
291 fies the base (2 through 16) into which the numbers should be con‐
292 verted. The result of evaluating numeric-expr2 specifies the width
293 in bits of each number, which may be either 8, 16 or 32.
294 As an example of the preceding three types of expressions, to produce
296 the name of a PTR record for the IP address being assigned to a
297 client, one could write the following expression:
298 concat (binary-to-ascii (10, 8, ".",
300 reverse (1, leased-address)),
301 ".in-addr.arpa.");
302 encode-int (numeric-expr, width)
305 Numeric-expr is evaluated and encoded as a data string of the speci‐
306 fied width, in network byte order (most significant byte first). If
307 the numeric expression evaluates to the null value, the result is
308 also null.
309 pick-first-value (data-expr1 [ ... exprn ] )
311 The pick-first-value function takes any number of data expressions as
312 its arguments. Each expression is evaluated, starting with the first
313 in the list, until an expression is found that does not evaluate to a
314 null value. That expression is returned, and none of the subsequent
315 expressions are evaluated. If all expressions evaluate to a null
316 value, the null value is returned.
317 host-decl-name
319 The host-decl-name function returns the name of the host declaration
320 that matched the client whose request is currently being processed,
321 if any. If no host declaration matched, the result is the null
322 value.
323
325 Numeric expressions are expressions that evaluate to an integer. In
326 general, the maximum size of such an integer should not be assumed to
327 be representable in fewer than 32 bits, but the precision of such inte‐
328 gers may be more than 32 bits.
329 In addition to the following operators several standard math functions
331 are available. They are:
332 operation symbol
333 add +
334 subtract -
335 divide /
336 multiply *
337 modulus %
338 bitwise and &
339 bitwise or |
340 bitwise xor ^
341 extract-int (data-expr, width)
343 The extract-int operator extracts an integer value in network byte
345 order from the result of evaluating the specified data expression.
346 Width is the width in bits of the integer to extract. Currently, the
347 only supported widths are 8, 16 and 32. If the evaluation of the
348 data expression doesn't provide sufficient bits to extract an integer
349 of the specified size, the null value is returned.
350 lease-time
352 The duration of the current lease - that is, the difference between
354 the current time and the time that the lease expires.
355 number
357 Any number between zero and the maximum representable size may be
359 specified as a numeric expression.
360 client-state
362 The current state of the client instance being processed. This is
364 only useful in DHCP client configuration files. Possible values are:
365 · Booting - DHCP client is in the INIT state, and does not yet have
367 an IP address. The next message transmitted will be a DHCPDIS‐
368 COVER, which will be broadcast.
369 · Reboot - DHCP client is in the INIT-REBOOT state. It has an IP
371 address, but is not yet using it. The next message to be transmit‐
372 ted will be a DHCPREQUEST, which will be broadcast. If no response
373 is heard, the client will bind to its address and move to the BOUND
374 state.
375 · Select - DHCP client is in the SELECTING state - it has received at
377 least one DHCPOFFER message, but is waiting to see if it may
378 receive other DHCPOFFER messages from other servers. No messages
379 are sent in the SELECTING state.
380 · Request - DHCP client is in the REQUESTING state - it has received
382 at least one DHCPOFFER message, and has chosen which one it will
383 request. The next message to be sent will be a DHCPREQUEST mes‐
384 sage, which will be broadcast.
385 · Bound - DHCP client is in the BOUND state - it has an IP address.
387 No messages are transmitted in this state.
388 · Renew - DHCP client is in the RENEWING state - it has an IP
390 address, and is trying to contact the server to renew it. The next
391 message to be sent will be a DHCPREQUEST message, which will be
392 unicast directly to the server.
393 · Rebind - DHCP client is in the REBINDING state - it has an IP
395 address, and is trying to contact any server to renew it. The next
396 message to be sent will be a DHCPREQUEST, which will be broadcast.
397
399 log (priority, data-expr)
400 Logging statements may be used to send information to the standard
402 logging channels. A logging statement includes an optional priority
403 (fatal, error, info, or debug), and a data expression.
404 Logging statements take only a single data expression argument, so if
406 you want to output multiple data values, you will need to use the
407 concat operator to concatenate them.
408 execute (command-path [, data-expr1, ... data-exprN]);
410 The execute statement runs an external command. The first argument
412 is a string literal containing the name or path of the command to
413 run. The other arguments, if present, are either string literals or
414 data- expressions which evaluate to text strings, to be passed as
415 command-line arguments to the command.
416 execute is synchronous; the program will block until the external
418 command being run has finished. Please note that lengthy program
419 execution (for example, in an "on commit" in dhcpd.conf) may result
420 in bad performance and timeouts. Only external applications with
421 very short execution times are suitable for use.
422 Passing user-supplied data to an external application might be dan‐
424 gerous. Make sure the external application checks input buffers for
425 validity. Non-printable ASCII characters will be converted into
426 dhcpd.conf language octal escapes ("\nnn"), make sure your external
427 command handles them as such.
428 It is possible to use the execute statement in any context, not only
430 on events. If you put it in a regular scope in the configuration
431 file you will execute that command every time a scope is evaluated.
432 parse-vendor-option;
434 The parse-vendor-option statement attempts to parse a vendor option
436 (code 43). It is only useful while processing a packet on the server
437 and requires that the administrator has already used the vendor-
438 option-space statement to select a valid vendor space.
439 This functionality may be used if the server needs to take different
441 actions depending on the values the client placed in the vendor
442 option and the sub-options are not at fixed locations. It is handled
443 as an action to allow an administrator to examine the incoming
444 options and choose the correct vendor space.
445
447 See the dhcpd.conf and dhclient.conf man pages for more information
448 about DDNS.
449
451 dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-options(5),
452 dhcpd(8), dhclient(8), RFC2132, RFC2131.
453
455 Information about Internet Systems Consortium can be found at
456 https://www.isc.org.
457 dhcp-eval(5)