dhcp-eval.5

DHCP服务器源码

.\"	$Id: dhcp-eval.5,v 1.17.2.7 2004/06/10 17:59:15 dhankins Exp $
.\"
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"   Internet Systems Consortium, Inc.
.\"   950 Charter Street
.\"   Redwood City, CA 94063
.\"   <[e-mail]>
.\"   http://www.isc.org/
.\"
.\" This software has been written for Internet Systems Consortium
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
.\" To learn more about Internet Systems Consortium, see
.\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
.\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
.\" ``http://www.nominum.com''.
.TH dhcp-eval 5
.SH NAME
dhcp-eval - ISC DHCP conditional evaluation
.SH DESCRIPTION
The Internet Systems 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
.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
.B static
.PP
.RS 0.25i
The \fBstatic\fR expression returns true if the lease assigned to the
client whose request is currently being processed is derived from a static
address assignment.
.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 config-option \fIoption-name\fR
.PP
.RS 0.25i
The \fBconfig-option\fR operator returns the value for the specified option
that the DHCP client or server has been configured to send.
.RE
.PP
.B hardware
.PP
.RS 0.25i
The \fBhardware\fR operator returns a data string whose first element
is the type of network interface indicated in packet being considered,
and whose subsequent elements are client's link-layer address.   If
there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,
then the result is null.   Hardware types include ethernet (1),
token-ring (6), and fddi (8).   Hardware types are specified by the
IETF, and details on how the type numbers are defined can be found in
RFC2131 (in the ISC DHCP distribution, this is included in the doc/
subdirectory).
.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