]>
Commit | Line | Data |
---|---|---|
ba2dd567 | 1 | .\" $Id: dhcp-eval.5,v 1.33 2012/05/17 15:50:14 sar Exp $ |
6b74a7a8 | 2 | .\" |
49a7fb58 | 3 | .\" Copyright (C) 2009-2022 Internet Systems Consortium, Inc. ("ISC") |
5a38e43f | 4 | .\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC") |
98311e4b | 5 | .\" Copyright (c) 1996-2003 by Internet Software Consortium |
6b74a7a8 | 6 | .\" |
98311e4b DH |
7 | .\" Permission to use, copy, modify, and distribute this software for any |
8 | .\" purpose with or without fee is hereby granted, provided that the above | |
9 | .\" copyright notice and this permission notice appear in all copies. | |
6b74a7a8 | 10 | .\" |
98311e4b DH |
11 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES |
12 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
13 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR | |
14 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
15 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
16 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT | |
17 | .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
6b74a7a8 | 18 | .\" |
98311e4b | 19 | .\" Internet Systems Consortium, Inc. |
429a56d7 TM |
20 | .\" PO Box 360 |
21 | .\" Newmarket, NH 03857 USA | |
98311e4b | 22 | .\" <info@isc.org> |
2c85ac9b | 23 | .\" https://www.isc.org/ |
98311e4b | 24 | .\" |
5a38e43f SR |
25 | .\" Support and other services are available for ISC products - see |
26 | .\" https://www.isc.org for more information or to learn more about ISC. | |
27 | .\" | |
17238faf | 28 | .TH dhcp-eval 5 |
6b74a7a8 | 29 | .SH NAME |
17238faf | 30 | dhcp-eval - ISC DHCP conditional evaluation |
6b74a7a8 | 31 | .SH DESCRIPTION |
98311e4b | 32 | The Internet Systems Consortium DHCP client and server both provide |
6b74a7a8 | 33 | the ability to perform conditional behavior depending on the contents |
a0497ac5 | 34 | of packets they receive. The syntax for specifying this conditional |
6b74a7a8 TL |
35 | behaviour is documented here. |
36 | .SH REFERENCE: CONDITIONAL BEHAVIOUR | |
97d44aab SR |
37 | Conditional behaviour may be specified using the if statement and the else |
38 | or elsif statements or the switch and case statements. | |
39 | A conditional statement can appear anywhere | |
6b74a7a8 | 40 | that a regular statement (e.g., an option statement) can appear, and |
97d44aab SR |
41 | can enclose one or more such statements. |
42 | .PP | |
43 | .B CONDITIONAL BEHAVIOUR: IF | |
44 | .PP | |
45 | A typical conditional if statement in a server might be: | |
6b74a7a8 TL |
46 | .PP |
47 | .nf | |
48 | if option dhcp-user-class = "accounting" { | |
49 | max-lease-time 17600; | |
50 | option domain-name "accounting.example.org"; | |
a0497ac5 | 51 | option domain-name-servers ns1.accounting.example.org, |
6b74a7a8 TL |
52 | ns2.accounting.example.org; |
53 | } elsif option dhcp-user-class = "sales" { | |
54 | max-lease-time 17600; | |
55 | option domain-name "sales.example.org"; | |
a0497ac5 | 56 | option domain-name-servers ns1.sales.example.org, |
6b74a7a8 TL |
57 | ns2.sales.example.org; |
58 | } elsif option dhcp-user-class = "engineering" { | |
59 | max-lease-time 17600; | |
60 | option domain-name "engineering.example.org"; | |
a0497ac5 | 61 | option domain-name-servers ns1.engineering.example.org, |
6b74a7a8 TL |
62 | ns2.engineering.example.org; |
63 | } else { | |
64 | max-lease-time 600; | |
65 | option domain-name "misc.example.org"; | |
a0497ac5 | 66 | option domain-name-servers ns1.misc.example.org, |
6b74a7a8 TL |
67 | ns2.misc.example.org; |
68 | } | |
69 | .fi | |
70 | .PP | |
71 | On the client side, an example of conditional evaluation might be: | |
72 | .PP | |
73 | .nf | |
74 | # example.org filters DNS at its firewall, so we have to use their DNS | |
a0497ac5 | 75 | # servers when we connect to their network. If we are not at |
6b74a7a8 TL |
76 | # example.org, prefer our own DNS server. |
77 | if not option domain-name = "example.org" { | |
78 | prepend domain-name-servers 127.0.0.1; | |
79 | } | |
a0497ac5 | 80 | .fi |
6b74a7a8 TL |
81 | .PP |
82 | The | |
83 | .B if | |
84 | statement and the | |
85 | .B elsif | |
86 | continuation statement both take boolean expressions as their | |
a0497ac5 SR |
87 | arguments. That is, they take expressions that, when evaluated, |
88 | produce a boolean result. If the expression evaluates to true, then | |
89 | the statements enclosed in braces following the | |
6b74a7a8 TL |
90 | .B if |
91 | statement are executed, and all subsequent | |
92 | .B elsif | |
93 | and | |
94 | .B else | |
f6b8f48d | 95 | clauses are skipped. Otherwise, each subsequent |
6b74a7a8 TL |
96 | .B elsif |
97 | clause's expression is checked, until an elsif clause is encountered | |
a0497ac5 | 98 | whose test evaluates to true. If such a clause is found, the |
6b74a7a8 TL |
99 | statements in braces following it are executed, and then any |
100 | subsequent | |
101 | .B elsif | |
102 | and | |
103 | .B else | |
f6b8f48d | 104 | clauses are skipped. If all the |
6b74a7a8 TL |
105 | .B if |
106 | and | |
107 | .B elsif | |
108 | clauses are checked but none | |
109 | of their expressions evaluate true, then if there is an | |
110 | .B else | |
111 | clause, the statements enclosed in braces following the | |
112 | .B else | |
a0497ac5 | 113 | are evaluated. Boolean expressions that evaluate to null are |
6b74a7a8 | 114 | treated as false in conditionals. |
97d44aab SR |
115 | .PP |
116 | .B CONDITIONAL BEHAVIOUR: SWITCH | |
117 | .PP | |
118 | The above example can be rewritten using a switch construct as well. | |
119 | .PP | |
120 | .nf | |
121 | switch (option dhcp-user-class) { | |
122 | case "accounting": | |
123 | max-lease-time 17600; | |
124 | option domain-name "accounting.example.org"; | |
125 | option domain-name-servers ns1.accounting.example.org, | |
126 | ns2.accounting.example.org; | |
127 | case "sales": | |
128 | max-lease-time 17600; | |
129 | option domain-name "sales.example.org"; | |
130 | option domain-name-servers ns1.sales.example.org, | |
131 | ns2.sales.example.org; | |
132 | break; | |
133 | case "engineering": | |
134 | max-lease-time 17600; | |
135 | option domain-name "engineering.example.org"; | |
136 | option domain-name-servers ns1.engineering.example.org, | |
137 | ns2.engineering.example.org; | |
138 | break; | |
139 | default: | |
140 | max-lease-time 600; | |
141 | option domain-name "misc.example.org"; | |
142 | option domain-name-servers ns1.misc.example.org, | |
143 | ns2.misc.example.org; | |
144 | break; | |
145 | } | |
146 | .fi | |
147 | .PP | |
148 | The | |
149 | .B switch | |
150 | statement and the | |
151 | .B case | |
152 | statements can both be data expressions or numeric expressions. Within | |
f6b8f48d | 153 | a switch statement they all must be the same type. The server |
97d44aab SR |
154 | evaluates the expression from the switch statement and then it evaluates |
155 | the expressions from the case statements until it finds a match. | |
156 | .PP | |
157 | If it finds a match it starts executing statements from that case | |
158 | until the next break statement. If it doesn't find a match it | |
159 | starts from the default statement and again proceeds to the next | |
160 | break statement. If there is no match and no default it does nothing. | |
161 | .PP | |
6b74a7a8 TL |
162 | .SH BOOLEAN EXPRESSIONS |
163 | The following is the current list of boolean expressions that are | |
164 | supported by the DHCP distribution. | |
165 | .PP | |
dd328225 | 166 | .I data-expression-1 \fB=\fR \fIdata-expression-2\fR |
6b74a7a8 TL |
167 | .RS 0.25i |
168 | .PP | |
169 | The \fB=\fR operator compares the values of two data expressions, | |
a0497ac5 | 170 | returning true if they are the same, false if they are not. If |
6b74a7a8 TL |
171 | either the left-hand side or the right-hand side are null, the |
172 | result is also null. | |
173 | .RE | |
174 | .PP | |
dd328225 DH |
175 | .I data-expression-1 \fB~=\fR \fIdata-expression-2\fR |
176 | .I data-expression-1 \fB~~\fR \fIdata-expression-2\fR | |
177 | .RS 0.25i | |
178 | .PP | |
179 | The \fB~=\fR and \fB~~\fR operators (not available on all systems) perform | |
180 | extended regex(7) matching of the values of two data expressions, returning | |
181 | true if \fIdata-expression-1\fR matches against the regular expression | |
182 | evaluated by \fIdata-expression-2\fR, or false if it does not match or | |
a0497ac5 | 183 | encounters some error. If either the left-hand side or the right-hand side |
c535de44 SR |
184 | are null or empty strings, the result is also false. The \fB~~\fR operator |
185 | differs from the \fB~=\fR operator in that it is case-insensitive. | |
dd328225 DH |
186 | .RE |
187 | .PP | |
188 | .I boolean-expression-1 \fBand\fR \fIboolean-expression-2\fR | |
6b74a7a8 TL |
189 | .PP |
190 | .RS 0.25i | |
191 | The \fBand\fR operator evaluates to true if the boolean expression on | |
192 | the left-hand side and the boolean expression on the right-hand side | |
193 | both evaluate to true. Otherwise, it evaluates to false. If either | |
194 | the expression on the left-hand side or the expression on the | |
195 | right-hand side are null, the result is null. | |
196 | .RE | |
197 | .PP | |
dd328225 | 198 | .I boolean-expression-1 \fBor\fR \fIboolean-expression-2\fR |
6b74a7a8 TL |
199 | .PP |
200 | .RS 0.25i | |
201 | The \fBor\fR operator evaluates to true if either the boolean | |
202 | expression on the left-hand side or the boolean expression on the | |
203 | right-hand side evaluate to true. Otherwise, it evaluates to false. | |
204 | If either the expression on the left-hand side or the expression on | |
205 | the right-hand side are null, the result is null. | |
206 | .RE | |
207 | .PP | |
208 | .B not \fIboolean-expression | |
209 | .PP | |
210 | .RS 0.25i | |
211 | The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR | |
212 | evaluates to false, and returns false if \fIboolean-expression\fR evaluates | |
a0497ac5 | 213 | to true. If \fIboolean-expression\fR evaluates to null, the result |
6b74a7a8 TL |
214 | is also null. |
215 | .RE | |
216 | .PP | |
217 | .B exists \fIoption-name\fR | |
218 | .PP | |
219 | .RS 0.25i | |
220 | The \fBexists\fR expression returns true if the specified option | |
221 | exists in the incoming DHCP packet being processed. | |
222 | .RE | |
0c643a7e TL |
223 | .B known |
224 | .PP | |
225 | .RS 0.25i | |
226 | The \fBknown\fR expression returns true if the client whose request is | |
227 | currently being processed is known - that is, if there's a host | |
228 | declaration for it. | |
229 | .RE | |
1c5d5731 TL |
230 | .B static |
231 | .PP | |
232 | .RS 0.25i | |
233 | The \fBstatic\fR expression returns true if the lease assigned to the | |
234 | client whose request is currently being processed is derived from a static | |
235 | address assignment. | |
236 | .RE | |
6b74a7a8 TL |
237 | .SH DATA EXPRESSIONS |
238 | Several of the boolean expressions above depend on the results of | |
a0497ac5 | 239 | evaluating data expressions. A list of these expressions is provided |
6b74a7a8 TL |
240 | here. |
241 | .PP | |
242 | .B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR | |
243 | .PP | |
244 | .RS 0.25i | |
245 | The \fBsubstring\fR operator evaluates the data expression and returns | |
246 | the substring of the result of that evaluation that starts | |
247 | \fIoffset\fR bytes from the beginning, continuing for \fIlength\fR | |
248 | bytes. \fIOffset\fR and \fIlength\fR are both numeric expressions. | |
249 | If \fIdata-expr\fR, \fIoffset\fR or \fIlength\fR evaluate to null, | |
250 | then the result is also null. If \fIoffset\fR is greater than or | |
251 | equal to the length of the evaluated data, then a zero-length data | |
252 | string is returned. If \fIlength\fI is greater then the remaining | |
253 | length of the evaluated data after \fIoffset\fR, then a data string | |
254 | containing all data from \fIoffset\fR to the end of the evaluated data | |
255 | is returned. | |
256 | .RE | |
257 | .PP | |
258 | .B suffix (\fIdata-expr\fB, \fIlength\fB)\fR | |
259 | .PP | |
260 | .RS 0.25i | |
261 | The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the | |
a0497ac5 | 262 | last \fIlength\fR bytes of the result of that evaluation. \fILength\fR |
6b74a7a8 TL |
263 | is a numeric expression. If \fIdata-expr\fR or \fIlength\fR evaluate |
264 | to null, then the result is also null. If \fIsuffix\fR evaluates to a | |
265 | number greater than the length of the evaluated data, then the | |
266 | evaluated data is returned. | |
267 | .RE | |
268 | .PP | |
2727c1cf DH |
269 | .B lcase (\fIdata-expr\fB)\fR |
270 | .PP | |
271 | .RS 0.25i | |
272 | The \fBlcase\fR function returns the result of evaluating | |
a0497ac5 | 273 | \fIdata-expr\fR converted to lower case. If \fIdata-expr\fR evaluates |
2727c1cf DH |
274 | to null, then the result is also null. |
275 | .RE | |
276 | .PP | |
277 | .B ucase (\fIdata-expr\fB)\fR | |
278 | .PP | |
279 | .RS 0.25i | |
280 | The \fBucase\fR function returns the result of evaluating | |
a0497ac5 | 281 | \fIdata-expr\fR converted to upper case. If \fIdata-expr\fR evaluates |
2727c1cf DH |
282 | to null, then the result is also null. |
283 | .RE | |
284 | .PP | |
6b74a7a8 TL |
285 | .B option \fIoption-name\fR |
286 | .PP | |
287 | .RS 0.25i | |
288 | The \fBoption\fR operator returns the contents of the specified option in | |
289 | the packet to which the server is responding. | |
290 | .RE | |
291 | .PP | |
98311e4b DH |
292 | .B config-option \fIoption-name\fR |
293 | .PP | |
294 | .RS 0.25i | |
295 | The \fBconfig-option\fR operator returns the value for the specified option | |
296 | that the DHCP client or server has been configured to send. | |
297 | .RE | |
298 | .PP | |
33ea4622 DH |
299 | .B gethostname() |
300 | .PP | |
301 | .RS 0.25i | |
302 | The \fBgethostname()\fR function returns a data string whose contents are a | |
303 | character string, the results of calling gethostname() on the local | |
304 | system with a size limit of 255 bytes (not including NULL terminator). This | |
305 | can be used for example to configure dhclient to send the local hostname | |
306 | without knowing the local hostname at the time dhclient.conf is written. | |
307 | .RE | |
308 | .PP | |
6b74a7a8 TL |
309 | .B hardware |
310 | .PP | |
311 | .RS 0.25i | |
312 | The \fBhardware\fR operator returns a data string whose first element | |
3c8a36ab | 313 | is the type of network interface indicated in packet being considered, |
a0497ac5 | 314 | and whose subsequent elements are client's link-layer address. If |
3c8a36ab | 315 | there is no packet, or if the RFC2131 \fIhlen\fR field is invalid, |
a0497ac5 SR |
316 | then the result is null. Hardware types include ethernet (1), |
317 | token-ring (6), and fddi (8). Hardware types are specified by the | |
3c8a36ab TL |
318 | IETF, and details on how the type numbers are defined can be found in |
319 | RFC2131 (in the ISC DHCP distribution, this is included in the doc/ | |
320 | subdirectory). | |
6b74a7a8 TL |
321 | .RE |
322 | .PP | |
323 | .B packet (\fIoffset\fB, \fIlength\fB)\fR | |
324 | .PP | |
325 | .RS 0.25i | |
326 | The \fBpacket\fR operator returns the specified portion of the packet | |
327 | being considered, or null in contexts where no packet is being | |
a0497ac5 | 328 | considered. \fIOffset\fR and \fIlength\fR are applied to the |
6b74a7a8 TL |
329 | contents packet as in the \fBsubstring\fR operator. |
330 | .RE | |
331 | .PP | |
332 | .I string | |
333 | .PP | |
334 | .RS 0.25i | |
335 | A string, enclosed in quotes, may be specified as a data expression, | |
a0497ac5 | 336 | and returns the text between the quotes, encoded in ASCII. The |
98311e4b DH |
337 | backslash ('\\') character is treated specially, as in C programming: '\\t' |
338 | means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means | |
a0497ac5 | 339 | bell. Any octal value can be specified with '\\nnn', where nnn is any |
98311e4b DH |
340 | positive octal number less than 0400. Any hexadecimal value can be |
341 | specified with '\\xnn', where nn is any positive hexadecimal number less | |
342 | than or equal to 0xff. | |
6b74a7a8 TL |
343 | .RE |
344 | .PP | |
98311e4b | 345 | .I colon-separated hexadecimal list |
6b74a7a8 TL |
346 | .PP |
347 | .RS 0.25i | |
98311e4b | 348 | A list of hexadecimal octet values, separated by colons, may be |
6b74a7a8 TL |
349 | specified as a data expression. |
350 | .RE | |
351 | .PP | |
6499fe27 | 352 | .B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR |
7ff63eb0 | 353 | .RS 0.25i |
6499fe27 | 354 | The expressions are evaluated, and the results of each evaluation are |
a0497ac5 | 355 | concatenated in the sequence that the subexpressions are listed. If |
b5b7abf8 TL |
356 | any subexpression evaluates to null, the result of the concatenation |
357 | is null. | |
7ff63eb0 TL |
358 | .RE |
359 | .PP | |
8ca01a7e TL |
360 | .B reverse (\fInumeric-expr1\fB, \fIdata-expr2\fB)\fR |
361 | .RS 0.25i | |
362 | The two expressions are evaluated, and then the result of evaluating | |
363 | the data expression is reversed in place, using hunks of the size | |
a0497ac5 SR |
364 | specified in the numeric expression. For example, if the numeric |
365 | expression evaluates to four, and the data expression evaluates to | |
8ca01a7e | 366 | twelve bytes of data, then the reverse expression will evaluate to |
8e112e2b | 367 | twelve bytes of data, consisting of the last four bytes of the |
8ca01a7e TL |
368 | input data, followed by the middle four bytes, followed by the first |
369 | four bytes. | |
370 | .RE | |
371 | .PP | |
372 | .B leased-address | |
373 | .RS 0.25i | |
374 | In any context where the client whose request is being processed has | |
375 | been assigned an IP address, this data expression returns that IP | |
2bddf829 DH |
376 | address. In any context where the client whose request is being |
377 | processed has not been assigned an ip address, if this data expression | |
378 | is found in executable statements executed on that client's behalf, | |
379 | a log message indicating "there is no lease associated with this client" | |
380 | is syslogged to the debug level (this is considered dhcpd.conf debugging | |
381 | information). | |
8ca01a7e TL |
382 | .RE |
383 | .PP | |
384 | .B binary-to-ascii (\fInumeric-expr1\fB, \fInumeric-expr2\fB, | |
385 | .B \fIdata-expr1\fB,\fR \fIdata-expr2\fB)\fR | |
386 | .RS 0.25i | |
387 | Converts the result of evaluating data-expr2 into a text string | |
388 | containing one number for each element of the result of evaluating | |
a0497ac5 SR |
389 | data-expr2. Each number is separated from the other by the result of |
390 | evaluating data-expr1. The result of evaluating numeric-expr1 | |
8ca01a7e | 391 | specifies the base (2 through 16) into which the numbers should be |
a0497ac5 | 392 | converted. The result of evaluating numeric-expr2 specifies the |
8ca01a7e TL |
393 | width in bits of each number, which may be either 8, 16 or 32. |
394 | .PP | |
395 | As an example of the preceding three types of expressions, to produce | |
396 | the name of a PTR record for the IP address being assigned to a | |
397 | client, one could write the following expression: | |
398 | .RE | |
399 | .PP | |
400 | .nf | |
401 | concat (binary-to-ascii (10, 8, ".", | |
402 | reverse (1, leased-address)), | |
403 | ".in-addr.arpa."); | |
404 | ||
405 | .fi | |
2727c1cf | 406 | .RE |
8ca01a7e | 407 | .PP |
7ff63eb0 TL |
408 | .B encode-int (\fInumeric-expr\fB, \fIwidth\fB)\fR |
409 | .RS 0.25i | |
410 | Numeric-expr is evaluated and encoded as a data string of the | |
411 | specified width, in network byte order (most significant byte first). | |
412 | If the numeric expression evaluates to the null value, the result is | |
413 | also null. | |
98311e4b | 414 | .RE |
e9b754bf TL |
415 | .PP |
416 | .B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR | |
417 | .RS 0.25i | |
418 | The pick-first-value function takes any number of data expressions as | |
a0497ac5 | 419 | its arguments. Each expression is evaluated, starting with the first |
e9b754bf | 420 | in the list, until an expression is found that does not evaluate to a |
a0497ac5 SR |
421 | null value. That expression is returned, and none of the subsequent |
422 | expressions are evaluated. If all expressions evaluate to a null | |
e9b754bf TL |
423 | value, the null value is returned. |
424 | .RE | |
425 | .PP | |
426 | .B host-decl-name | |
427 | .RS 0.25i | |
428 | The host-decl-name function returns the name of the host declaration | |
429 | that matched the client whose request is currently being processed, if | |
a0497ac5 | 430 | any. If no host declaration matched, the result is the null value. |
e9b754bf | 431 | .RE |
6b74a7a8 | 432 | .SH NUMERIC EXPRESSIONS |
a0497ac5 | 433 | Numeric expressions are expressions that evaluate to an integer. In |
6b74a7a8 TL |
434 | general, the maximum size of such an integer should not be assumed to |
435 | be representable in fewer than 32 bits, but the precision of such | |
436 | integers may be more than 32 bits. | |
437 | .PP | |
97d44aab SR |
438 | In addition to the following operators several standard math functions |
439 | are available. They are: | |
440 | .nf | |
441 | operation symbol | |
442 | add \fB+\fR | |
443 | subtract \fB-\fR | |
444 | divide \fB/\fR | |
445 | multiply \fB*\fR | |
446 | modulus \fB%\fR | |
447 | bitwise and \fB&\fR | |
448 | bitwise or \fB|\fR | |
449 | bitwise xor \fB^\fR | |
450 | .fi | |
451 | .PP | |
6b74a7a8 TL |
452 | .B extract-int (\fIdata-expr\fB, \fIwidth\fB)\fR |
453 | .PP | |
454 | .RS 0.25i | |
455 | The \fBextract-int\fR operator extracts an integer value in network | |
456 | byte order from the result of evaluating the specified data | |
a0497ac5 SR |
457 | expression. Width is the width in bits of the integer to extract. |
458 | Currently, the only supported widths are 8, 16 and 32. If the | |
6b74a7a8 TL |
459 | evaluation of the data expression doesn't provide sufficient bits to |
460 | extract an integer of the specified size, the null value is returned. | |
461 | .RE | |
462 | .PP | |
e9b754bf TL |
463 | .B lease-time |
464 | .PP | |
465 | .RS 0.25i | |
466 | The duration of the current lease - that is, the difference between | |
467 | the current time and the time that the lease expires. | |
468 | .RE | |
469 | .PP | |
6b74a7a8 TL |
470 | .I number |
471 | .PP | |
472 | .RS 0.25i | |
473 | Any number between zero and the maximum representable size may be | |
7ff63eb0 | 474 | specified as a numeric expression. |
6b74a7a8 | 475 | .RE |
752214df TL |
476 | .PP |
477 | .B client-state | |
478 | .PP | |
479 | .RS 0.25i | |
a0497ac5 SR |
480 | The current state of the client instance being processed. This is |
481 | only useful in DHCP client configuration files. Possible values are: | |
752214df TL |
482 | .TP 2 |
483 | .I \(bu | |
484 | Booting - DHCP client is in the INIT state, and does not yet have an | |
a0497ac5 | 485 | IP address. The next message transmitted will be a DHCPDISCOVER, |
752214df TL |
486 | which will be broadcast. |
487 | .TP | |
488 | .I \(bu | |
a0497ac5 SR |
489 | Reboot - DHCP client is in the INIT-REBOOT state. It has an IP |
490 | address, but is not yet using it. The next message to be transmitted | |
491 | will be a DHCPREQUEST, which will be broadcast. If no response is | |
752214df TL |
492 | heard, the client will bind to its address and move to the BOUND state. |
493 | .TP | |
494 | .I \(bu | |
495 | Select - DHCP client is in the SELECTING state - it has received at | |
496 | least one DHCPOFFER message, but is waiting to see if it may receive | |
a0497ac5 | 497 | other DHCPOFFER messages from other servers. No messages are sent in |
543ce4f8 TL |
498 | the SELECTING state. |
499 | .TP | |
500 | .I \(bu | |
501 | Request - DHCP client is in the REQUESTING state - it has received at | |
502 | least one DHCPOFFER message, and has chosen which one it will | |
a0497ac5 | 503 | request. The next message to be sent will be a DHCPREQUEST message, |
543ce4f8 | 504 | which will be broadcast. |
752214df TL |
505 | .TP |
506 | .I \(bu | |
a0497ac5 | 507 | Bound - DHCP client is in the BOUND state - it has an IP address. No |
752214df TL |
508 | messages are transmitted in this state. |
509 | .TP | |
510 | .I \(bu | |
511 | Renew - DHCP client is in the RENEWING state - it has an IP address, | |
a0497ac5 | 512 | and is trying to contact the server to renew it. The next message to |
752214df TL |
513 | be sent will be a DHCPREQUEST message, which will be unicast directly |
514 | to the server. | |
515 | .TP | |
516 | .I \(bu | |
517 | Rebind - DHCP client is in the REBINDING state - it has an IP address, | |
a0497ac5 | 518 | and is trying to contact any server to renew it. The next message to |
752214df TL |
519 | be sent will be a DHCPREQUEST, which will be broadcast. |
520 | .RE | |
253c8b6a | 521 | .SH REFERENCE: ACTION EXPRESSIONS |
b543fea9 | 522 | .PP |
253c8b6a | 523 | .B log (\fIpriority\fB, \fIdata-expr\fB)\fR |
b543fea9 DH |
524 | .RS 0.25i |
525 | .PP | |
253c8b6a EH |
526 | Logging statements may be used to send information to the standard logging |
527 | channels. A logging statement includes an optional priority (\fBfatal\fR, | |
528 | \fBerror\fR, \fBinfo\fR, or \fBdebug\fR), and a data expression. | |
529 | .PP | |
530 | Logging statements take only a single data expression argument, so if you | |
531 | want to output multiple data values, you will need to use the \fBconcat\fR | |
532 | operator to concatenate them. | |
533 | .RE | |
534 | .PP | |
535 | .B execute (\fIcommand-path\fB [, \fIdata-expr1\fB, ... \fIdata-exprN\fB]);\fR | |
536 | .RS 0.25i | |
b543fea9 | 537 | .PP |
253c8b6a EH |
538 | The \fBexecute\fR statement runs an external command. The first argument |
539 | is a string literal containing the name or path of the command to run. | |
540 | The other arguments, if present, are either string literals or data- | |
541 | expressions which evaluate to text strings, to be passed as command-line | |
542 | arguments to the command. | |
543 | .PP | |
544 | \fBexecute\fR is synchronous; the program will block until the external | |
545 | command being run has finished. Please note that lengthy program | |
b543fea9 DH |
546 | execution (for example, in an "on commit" in dhcpd.conf) may result in |
547 | bad performance and timeouts. Only external applications with very short | |
548 | execution times are suitable for use. | |
549 | .PP | |
550 | Passing user-supplied data to an external application might be dangerous. | |
551 | Make sure the external application checks input buffers for validity. | |
552 | Non-printable ASCII characters will be converted into dhcpd.conf language | |
ba2dd567 | 553 | octal escapes ("\\nnn"), make sure your external command handles them as |
b543fea9 DH |
554 | such. |
555 | .PP | |
253c8b6a | 556 | It is possible to use the execute statement in any context, not only |
a0497ac5 | 557 | on events. If you put it in a regular scope in the configuration file |
b543fea9 DH |
558 | you will execute that command every time a scope is evaluated. |
559 | .RE | |
45c332f0 SR |
560 | .PP |
561 | .B parse-vendor-option;\fR | |
562 | .RS 0.25i | |
563 | .PP | |
564 | The \fBparse-vendor-option\fR statement attempts to parse a vendor | |
565 | option (code 43). It is only useful while processing a packet on the server | |
566 | and requires that the administrator has already used the | |
567 | \fBvendor-option-space\fR statement to select a valid vendor space. | |
568 | .PP | |
569 | This functionality may be used if the server needs to take different | |
570 | actions depending on the values the client placed in the vendor option | |
571 | and the sub-options are not at fixed locations. It is handled as an | |
572 | action to allow an administrator to examine the incoming options and | |
573 | choose the correct vendor space. | |
574 | .RE | |
3c8a36ab TL |
575 | .SH REFERENCE: DYNAMIC DNS UPDATES |
576 | .PP | |
f30e2771 SR |
577 | See the dhcpd.conf and dhclient.conf man pages for more information |
578 | about DDNS. | |
6b74a7a8 | 579 | .SH SEE ALSO |
3a16098f | 580 | dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-options(5), dhcpd(8), |
6b74a7a8 TL |
581 | dhclient(8), RFC2132, RFC2131. |
582 | .SH AUTHOR | |
98311e4b | 583 | Information about Internet Systems Consortium can be found at |
2c85ac9b | 584 | .B https://www.isc.org. |