isc-dhcp/common/dhcp-eval.5

.\"	dhcp-eval.5
.\"
.\" Copyright (c) 1995, 1996, 1997, 1998, 1999
.\" The Internet Software Consortium.   All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of The Internet Software Consortium nor the names
.\"    of its contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" This software has been written for the Internet Software Consortium
.\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie
.\" Enterprises.  To learn more about the Internet Software Consortium,
.\" see ``http://www.isc.org/isc''.  To learn more about Vixie
.\" Enterprises, see ``http://www.vix.com''.
.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
.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
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 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.   Negative numbers are not
currently supported.
.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.