1
.\" $Id: dhcp-eval.5,v 1.27 2007/06/07 15:52:29 dhankins Exp $
3
.\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
4
.\" Copyright (c) 1996-2003 by Internet Software Consortium
6
.\" Permission to use, copy, modify, and distribute this software for any
7
.\" purpose with or without fee is hereby granted, provided that the above
8
.\" copyright notice and this permission notice appear in all copies.
10
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18
.\" Internet Systems Consortium, Inc.
19
.\" 950 Charter Street
20
.\" Redwood City, CA 94063
22
.\" http://www.isc.org/
24
.\" This software has been written for Internet Systems Consortium
25
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26
.\" To learn more about Internet Systems Consortium, see
27
.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
28
.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
29
.\" ``http://www.nominum.com''.
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, the result is also false. The \fB~~\fR operator differs from the
136
\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 then 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 \fBhardware\fR operator returns a data string whose first element
254
is the type of network interface indicated in packet being considered,
255
and whose subsequent elements are client's link-layer address. If
256
there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,
257
then the result is null. Hardware types include ethernet (1),
258
token-ring (6), and fddi (8). Hardware types are specified by the
259
IETF, and details on how the type numbers are defined can be found in
260
RFC2131 (in the ISC DHCP distribution, this is included in the doc/
264
.B packet (\fIoffset\fB, \fIlength\fB)\fR
267
The \fBpacket\fR operator returns the specified portion of the packet
268
being considered, or null in contexts where no packet is being
269
considered. \fIOffset\fR and \fIlength\fR are applied to the
270
contents packet as in the \fBsubstring\fR operator.
276
A string, enclosed in quotes, may be specified as a data expression,
277
and returns the text between the quotes, encoded in ASCII. The
278
backslash ('\\') character is treated specially, as in C programming: '\\t'
279
means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means
280
bell. Any octal value can be specified with '\\nnn', where nnn is any
281
positive octal number less than 0400. Any hexadecimal value can be
282
specified with '\\xnn', where nn is any positive hexadecimal number less
283
than or equal to 0xff.
286
.I colon-separated hexadecimal list
289
A list of hexadecimal octet values, separated by colons, may be
290
specified as a data expression.
293
.B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR
295
The expressions are evaluated, and the results of each evaluation are
296
concatenated in the sequence that the subexpressions are listed. If
297
any subexpression evaluates to null, the result of the concatenation
301
.B reverse (\fInumeric-expr1\fB, \fIdata-expr2\fB)\fR
303
The two expressions are evaluated, and then the result of evaluating
304
the data expression is reversed in place, using hunks of the size
305
specified in the numeric expression. For example, if the numeric
306
expression evaluates to four, and the data expression evaluates to
307
twelve bytes of data, then the reverse expression will evaluate to
308
twelve bytes of data, consisting of the last four bytes of the the
309
input data, followed by the middle four bytes, followed by the first
315
In any context where the client whose request is being processed has
316
been assigned an IP address, this data expression returns that IP
317
address. In any context where the client whose request is being
318
processed has not been assigned an ip address, if this data expression
319
is found in executable statements executed on that client's behalf,
320
a log message indicating "there is no lease associated with this client"
321
is syslogged to the debug level (this is considered dhcpd.conf debugging
325
.B binary-to-ascii (\fInumeric-expr1\fB, \fInumeric-expr2\fB,
326
.B \fIdata-expr1\fB,\fR \fIdata-expr2\fB)\fR
328
Converts the result of evaluating data-expr2 into a text string
329
containing one number for each element of the result of evaluating
330
data-expr2. Each number is separated from the other by the result of
331
evaluating data-expr1. The result of evaluating numeric-expr1
332
specifies the base (2 through 16) into which the numbers should be
333
converted. The result of evaluating numeric-expr2 specifies the
334
width in bits of each number, which may be either 8, 16 or 32.
336
As an example of the preceding three types of expressions, to produce
337
the name of a PTR record for the IP address being assigned to a
338
client, one could write the following expression:
342
concat (binary-to-ascii (10, 8, ".",
343
reverse (1, leased-address)),
349
.B encode-int (\fInumeric-expr\fB, \fIwidth\fB)\fR
351
Numeric-expr is evaluated and encoded as a data string of the
352
specified width, in network byte order (most significant byte first).
353
If the numeric expression evaluates to the null value, the result is
357
.B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR
359
The pick-first-value function takes any number of data expressions as
360
its arguments. Each expression is evaluated, starting with the first
361
in the list, until an expression is found that does not evaluate to a
362
null value. That expression is returned, and none of the subsequent
363
expressions are evaluated. If all expressions evaluate to a null
364
value, the null value is returned.
369
The host-decl-name function returns the name of the host declaration
370
that matched the client whose request is currently being processed, if
371
any. If no host declaration matched, the result is the null value.
373
.SH NUMERIC EXPRESSIONS
374
Numeric expressions are expressions that evaluate to an integer. In
375
general, the maximum size of such an integer should not be assumed to
376
be representable in fewer than 32 bits, but the precision of such
377
integers may be more than 32 bits.
379
.B extract-int (\fIdata-expr\fB, \fIwidth\fB)\fR
382
The \fBextract-int\fR operator extracts an integer value in network
383
byte order from the result of evaluating the specified data
384
expression. Width is the width in bits of the integer to extract.
385
Currently, the only supported widths are 8, 16 and 32. If the
386
evaluation of the data expression doesn't provide sufficient bits to
387
extract an integer of the specified size, the null value is returned.
393
The duration of the current lease - that is, the difference between
394
the current time and the time that the lease expires.
400
Any number between zero and the maximum representable size may be
401
specified as a numeric expression.
407
The current state of the client instance being processed. This is
408
only useful in DHCP client configuration files. Possible values are:
411
Booting - DHCP client is in the INIT state, and does not yet have an
412
IP address. The next message transmitted will be a DHCPDISCOVER,
413
which will be broadcast.
416
Reboot - DHCP client is in the INIT-REBOOT state. It has an IP
417
address, but is not yet using it. The next message to be transmitted
418
will be a DHCPREQUEST, which will be broadcast. If no response is
419
heard, the client will bind to its address and move to the BOUND state.
422
Select - DHCP client is in the SELECTING state - it has received at
423
least one DHCPOFFER message, but is waiting to see if it may receive
424
other DHCPOFFER messages from other servers. No messages are sent in
428
Request - DHCP client is in the REQUESTING state - it has received at
429
least one DHCPOFFER message, and has chosen which one it will
430
request. The next message to be sent will be a DHCPREQUEST message,
431
which will be broadcast.
434
Bound - DHCP client is in the BOUND state - it has an IP address. No
435
messages are transmitted in this state.
438
Renew - DHCP client is in the RENEWING state - it has an IP address,
439
and is trying to contact the server to renew it. The next message to
440
be sent will be a DHCPREQUEST message, which will be unicast directly
444
Rebind - DHCP client is in the REBINDING state - it has an IP address,
445
and is trying to contact any server to renew it. The next message to
446
be sent will be a DHCPREQUEST, which will be broadcast.
448
.SH REFERENCE: ACTION EXPRESSIONS
450
.B log (\fIpriority\fB, \fIdata-expr\fB)\fR
453
Logging statements may be used to send information to the standard logging
454
channels. A logging statement includes an optional priority (\fBfatal\fR,
455
\fBerror\fR, \fBinfo\fR, or \fBdebug\fR), and a data expression.
457
Logging statements take only a single data expression argument, so if you
458
want to output multiple data values, you will need to use the \fBconcat\fR
459
operator to concatenate them.
462
.B execute (\fIcommand-path\fB [, \fIdata-expr1\fB, ... \fIdata-exprN\fB]);\fR
465
The \fBexecute\fR statement runs an external command. The first argument
466
is a string literal containing the name or path of the command to run.
467
The other arguments, if present, are either string literals or data-
468
expressions which evaluate to text strings, to be passed as command-line
469
arguments to the command.
471
\fBexecute\fR is synchronous; the program will block until the external
472
command being run has finished. Please note that lengthy program
473
execution (for example, in an "on commit" in dhcpd.conf) may result in
474
bad performance and timeouts. Only external applications with very short
475
execution times are suitable for use.
477
Passing user-supplied data to an external application might be dangerous.
478
Make sure the external application checks input buffers for validity.
479
Non-printable ASCII characters will be converted into dhcpd.conf language
480
octal escapes ("\777"), make sure your external command handles them as
483
It is possible to use the execute statement in any context, not only
484
on events. If you put it in a regular scope in the configuration file
485
you will execute that command every time a scope is evaluated.
487
.SH REFERENCE: DYNAMIC DNS UPDATES
489
The DHCP client and server have the ability to dynamically update the
490
Domain Name System. Within the configuration files, you can define
491
how you want the Domain Name System to be updated. These updates are
492
RFC 2136 compliant so any DNS server supporting RFC 2136 should be
493
able to accept updates from the DHCP server.
495
Support for TSIG and DNSSEC is not yet available. When you set your
496
DNS server up to allow updates from the DHCP server or client, you may
497
be exposing it to unauthorized updates. To avoid this, the best you
498
can do right now is to use IP address-based packet filtering to
499
prevent unauthorized hosts from submitting update requests.
500
Obviously, there is currently no way to provide security for client
501
updates - this will require TSIG or DNSSEC, neither of which is yet
502
available in the DHCP distribution.
504
Dynamic DNS (DDNS) updates are performed by using the \fBdns-update\fR
505
expression. The \fBdns-update\fR expression is a boolean expression
506
that takes four parameters. If the update succeeds, the result is
507
true. If it fails, the result is false. The four parameters that the
508
are the resource record type (RR), the left hand side of the RR, the
509
right hand side of the RR and the ttl that should be applied to the
510
record. The simplest example of the use of the function can be found
511
in the reference section of the dhcpd.conf file, where events are
512
described. In this example several statements are being used to make
513
the arguments to the \fBdns-update\fR.
515
In the example, the first argument to the first \f\Bdns-update\fR
516
expression is a data expression that evaluates to the A RR type. The
517
second argument is constructed by concatenating the DHCP host-name
518
option with a text string containing the local domain, in this case
519
"ssd.example.net". The third argument is constructed by converting
520
the address the client has been assigned from a 32-bit number into an
521
ascii string with each byte separated by a ".". The fourth argument,
522
the TTL, specifies the amount of time remaining in the lease (note
523
that this isn't really correct, since the DNS server will pass this
524
TTL out whenever a request comes in, even if that is only a few
525
seconds before the lease expires).
527
If the first \fBdns-update\fR statement succeeds, it is followed up
528
with a second update to install a PTR RR. The installation of a PTR
529
record is similar to installing an A RR except that the left hand side
530
of the record is the leased address, reversed, with ".in-addr.arpa"
531
concatenated. The right hand side is the fully qualified domain name
532
of the client to which the address is being leased.
534
dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-options(5), dhcpd(8),
535
dhclient(8), RFC2132, RFC2131.
537
The Internet Systems Consortium DHCP Distribution was written by Ted
538
Lemon under a contract with Vixie Labs. Funding for
539
this project was provided through Internet Systems Consortium.
540
Information about Internet Systems Consortium can be found at
541
.B http://www.isc.org.
added
removed
common/dhcp-eval.5
