.\" 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 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 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.