isc-dhcp/common/dhcp-eval.5

.\"	dhcp-eval.5
.\"
.\" Copyright (c) 1996-1999 Internet Software Consortium.
.\" Use is subject to license terms which appear in the file named
.\" ISC-LICENSE that should have accompanied this file when you
.\" received it.   If a file named ISC-LICENSE did not accompany this
.\" file, or you are not sure the one you have is correct, you may
.\" obtain an applicable copy of the license at:
.\"
.\"             http://www.isc.org/isc-license-1.0.html. 
.\"
.\" This file is part of the ISC DHCP distribution.   The documentation
.\" associated with this file is listed in the file DOCUMENTATION,
.\" included in the top-level directory of this release.
.\"
.\" Support and other services are available for ISC products - see
.\" http://www.isc.org for more information.
.TH dhcpd-options 5
.SH NAME
dhcp-conditionals - ISC DHCP conditional evaluation
.SH DESCRIPTION
The Internet Software Consortium DHCP client and server both provide
the ability to perform conditional behavior depending on the contents
of packets they receive.   The syntax for specifying this conditional
behaviour is documented here.
.SH REFERENCE: CONDITIONAL BEHAVIOUR
Conditional behaviour is specified using the if statement and the else
or elsif statements.   A conditional statement can appear anywhere
that a regular statement (e.g., an option statement) can appear, and
can enclose one or more such statements.   A typical conditional
statement in a server might be:
.PP
.nf
if option dhcp-user-class = "accounting" {
  max-lease-time 17600;
  option domain-name "accounting.example.org";
  option domain-name-servers ns1.accounting.example.org, 
			     ns2.accounting.example.org;
} elsif option dhcp-user-class = "sales" {
  max-lease-time 17600;
  option domain-name "sales.example.org";
  option domain-name-servers ns1.sales.example.org, 
			     ns2.sales.example.org;
} elsif option dhcp-user-class = "engineering" {
  max-lease-time 17600;
  option domain-name "engineering.example.org";
  option domain-name-servers ns1.engineering.example.org, 
			     ns2.engineering.example.org;
} else {
  max-lease-time 600;
  option domain-name "misc.example.org";
  option domain-name-servers ns1.misc.example.org, 
			     ns2.misc.example.org;
}
.fi
.PP
On the client side, an example of conditional evaluation might be:
.PP
.nf
# example.org filters DNS at its firewall, so we have to use their DNS
# servers when we connect to their network.   If we are not at
# example.org, prefer our own DNS server.
if not option domain-name = "example.org" {
  prepend domain-name-servers 127.0.0.1;
}
.fi  
.PP
The
.B if
statement and the
.B elsif
continuation statement both take boolean expressions as their
arguments.   That is, they take expressions that, when evaluated,
produce a boolean result.   If the expression evaluates to true, then
the statements enclosed in braces following the 
.B if
statement are executed, and all subsequent
.B elsif
and
.B else
clauses are skipped.   Otherwise, each subsequent 
.B elsif
clause's expression is checked, until an elsif clause is encountered
whose test evaluates to true.   If such a clause is found, the
statements in braces following it are executed, and then any
subsequent
.B elsif
and
.B else
clauses are skipped.   If all the 
.B if
and
.B elsif
clauses are checked but none
of their expressions evaluate true, then if there is an
.B else
clause, the statements enclosed in braces following the
.B else
are evaluated.   Boolean expressions that evaluate to null are
treated as false in conditionals.
.SH BOOLEAN EXPRESSIONS
The following is the current list of boolean expressions that are
supported by the DHCP distribution.
.PP
.B check \fIclass-name\fR
.RS 0.25i
.PP
The check operator returns a true value if the packet being considered
comes from a client that falls into the specified
class.
.I Class-name
must be a string that corresponds to the name of a defined class.
Classes are only supported in the DHCP server.
.RE
.PP
.I data-expression-1 \fB=\fI data-expression-2\fR
.RS 0.25i
.PP
The \fB=\fR operator compares the values of two data expressions,
returning true if they are the same, false if they are not.   If
either the left-hand side or the right-hand side are null, the
result is also null.
.RE
.PP
.I boolean-expression-1 \fBand\fI boolean-expression-2\fR
.PP
.RS 0.25i
The \fBand\fR operator evaluates to true if the boolean expression on
the left-hand side and the boolean expression on the right-hand side
both evaluate to true.  Otherwise, it evaluates to false.  If either
the expression on the left-hand side or the expression on the
right-hand side are null, the result is null.
.RE
.PP
.I boolean-expression-1 \fBor\fI boolean-expression-2\fR
.PP
.RS 0.25i
The \fBor\fR operator evaluates to true if either the boolean
expression on the left-hand side or the boolean expression on the
right-hand side evaluate to true.  Otherwise, it evaluates to false.
If either the expression on the left-hand side or the expression on
the right-hand side are null, the result is null.
.RE
.PP
.B not \fIboolean-expression
.PP
.RS 0.25i
The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR
evaluates to false, and returns false if \fIboolean-expression\fR evaluates
to true.   If \fIboolean-expression\fR evaluates to null, the result
is also null.
.RE
.PP
.B exists \fIoption-name\fR
.PP
.RS 0.25i
The \fBexists\fR expression returns true if the specified option
exists in the incoming DHCP packet being processed.
.RE
.B known
.PP
.RS 0.25i
The \fBknown\fR expression returns true if the client whose request is
currently being processed is known - that is, if there's a host
declaration for it.
.RE
.SH DATA EXPRESSIONS
Several of the boolean expressions above depend on the results of
evaluating data expressions.   A list of these expressions is provided
here.
.PP
.B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR
.PP
.RS 0.25i
The \fBsubstring\fR operator evaluates the data expression and returns
the substring of the result of that evaluation that starts
\fIoffset\fR bytes from the beginning, continuing for \fIlength\fR
bytes.  \fIOffset\fR and \fIlength\fR are both numeric expressions.
If \fIdata-expr\fR, \fIoffset\fR or \fIlength\fR evaluate to null,
then the result is also null.  If \fIoffset\fR is greater than or
equal to the length of the evaluated data, then a zero-length data
string is returned.  If \fIlength\fI is greater then the remaining
length of the evaluated data after \fIoffset\fR, then a data string
containing all data from \fIoffset\fR to the end of the evaluated data
is returned.
.RE
.PP
.B suffix (\fIdata-expr\fB, \fIlength\fB)\fR
.PP
.RS 0.25i
The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the
last \fIlength\fR bytes of the result of that evaluation. \fILength\fR
is a numeric expression.  If \fIdata-expr\fR or \fIlength\fR evaluate
to null, then the result is also null.  If \fIsuffix\fR evaluates to a
number greater than the length of the evaluated data, then the
evaluated data is returned.
.RE
.PP
.B option \fIoption-name\fR
.PP
.RS 0.25i
The \fBoption\fR operator returns the contents of the specified option in
the packet to which the server is responding.
.RE
.PP
.B hardware
.PP
.RS 0.25i
The \fBhardware\fR operator returns a data string whose first element
is the \fIhtype\fR field of the packet being considered, and whose
subsequent elements are first \fIhlen\fR bytes of the \fIchaddr\fR
field of the packet, as specified in \fBRFC 2131\fR .  If there is no
packet, or if the \fIhlen\fR field is invalid, then the result is
null.
.RE
.PP
.B packet (\fIoffset\fB, \fIlength\fB)\fR
.PP
.RS 0.25i
The \fBpacket\fR operator returns the specified portion of the packet
being considered, or null in contexts where no packet is being
considered.   \fIOffset\fR and \fIlength\fR are applied to the
contents packet as in the \fBsubstring\fR operator.
.RE
.PP
.I string
.PP
.RS 0.25i
A string, enclosed in quotes, may be specified as a data expression,
and returns the text between the quotes, encoded in ASCII.
.RE
.PP
.I colon-seperated hexadecimal list
.PP
.RS 0.25i
A list of hexadecimal octet values, seperated by colons, may be
specified as a data expression.
.RE
.PP
.B concat (\fIdata-expr1\fB, \fIdata-expr2\fB)\fR
.RS 0.25i
The two expressions are evaluated, and the result of concatenating the
results of the two evaluations is returned.   If either subexpression
evaluates to null, then the result is the value of the other
expression.   If both expressions evaluate to null, then the result is
null.
.RE
.PP
.B encode-int (\fInumeric-expr\fB, \fIwidth\fB)\fR
.RS 0.25i
Numeric-expr is evaluated and encoded as a data string of the
specified width, in network byte order (most significant byte first).
If the numeric expression evaluates to the null value, the result is
also null.

.SH NUMERIC EXPRESSIONS
Numeric expressions are expressions that evaluate to an integer.   In
general, the maximum size of such an integer should not be assumed to
be representable in fewer than 32 bits, but the precision of such
integers may be more than 32 bits.
.PP
.B extract-int (\fIdata-expr\fB, \fIwidth\fB)\fR
.PP
.RS 0.25i
The \fBextract-int\fR operator extracts an integer value in network
byte order from the result of evaluating the specified data
expression.   Width is the width in bits of the integer to extract.
Currently, the only supported widths are 8, 16 and 32.   If the
evaluation of the data expression doesn't provide sufficient bits to
extract an integer of the specified size, the null value is returned.
.RE
.PP
.I number
.PP
.RS 0.25i
Any number between zero and the maximum representable size may be
specified as a numeric expression.
.RE
.SH SEE ALSO
dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-eval(5), dhcpd(8),
dhclient(8), RFC2132, RFC2131.
.SH AUTHOR
The Internet Software Consortium DHCP Distribution was written by Ted
Lemon <mellon@isc.org> under a contract with Vixie Labs.  Funding for
this project was provided through the Internet Software Consortium.
Information about the Internet Software Consortium can be found at
.B http://www.isc.org/isc.