[BACK]Return to dhcp-eval.5 CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / common

Diff for /embedaddon/dhcp/common/dhcp-eval.5 between versions 1.1 and 1.1.1.1

version 1.1, 2012/02/21 22:30:18 version 1.1.1.1, 2012/10/09 09:06:54
Line 1 Line 1
 .\"     $Id$  .\"     $Id$
 .\"  .\"
.\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC").\" Copyright (c) 2009-2012 by Internet Systems Consortium, Inc. ("ISC")
 .\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")  .\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
 .\" Copyright (c) 1996-2003 by Internet Software Consortium  .\" Copyright (c) 1996-2003 by Internet Software Consortium
 .\"  .\"
Line 34  dhcp-eval - ISC DHCP conditional evaluation Line 34  dhcp-eval - ISC DHCP conditional evaluation
 .SH DESCRIPTION  .SH DESCRIPTION
 The Internet Systems Consortium DHCP client and server both provide  The Internet Systems Consortium DHCP client and server both provide
 the ability to perform conditional behavior depending on the contents  the ability to perform conditional behavior depending on the contents
of packets they receive.   The syntax for specifying this conditionalof packets they receive.  The syntax for specifying this conditional
 behaviour is documented here.  behaviour is documented here.
 .SH REFERENCE: CONDITIONAL BEHAVIOUR  .SH REFERENCE: CONDITIONAL BEHAVIOUR
 Conditional behaviour is specified using the if statement and the else  Conditional behaviour is specified using the if statement and the else
or elsif statements.   A conditional statement can appear anywhereor elsif statements.  A conditional statement can appear anywhere
 that a regular statement (e.g., an option statement) can appear, and  that a regular statement (e.g., an option statement) can appear, and
can enclose one or more such statements.   A typical conditionalcan enclose one or more such statements.  A typical conditional
 statement in a server might be:  statement in a server might be:
 .PP  .PP
 .nf  .nf
 if option dhcp-user-class = "accounting" {  if option dhcp-user-class = "accounting" {
   max-lease-time 17600;    max-lease-time 17600;
   option domain-name "accounting.example.org";    option domain-name "accounting.example.org";
  option domain-name-servers ns1.accounting.example.org,   option domain-name-servers ns1.accounting.example.org,
                              ns2.accounting.example.org;                               ns2.accounting.example.org;
 } elsif option dhcp-user-class = "sales" {  } elsif option dhcp-user-class = "sales" {
   max-lease-time 17600;    max-lease-time 17600;
   option domain-name "sales.example.org";    option domain-name "sales.example.org";
  option domain-name-servers ns1.sales.example.org,   option domain-name-servers ns1.sales.example.org,
                              ns2.sales.example.org;                               ns2.sales.example.org;
 } elsif option dhcp-user-class = "engineering" {  } elsif option dhcp-user-class = "engineering" {
   max-lease-time 17600;    max-lease-time 17600;
   option domain-name "engineering.example.org";    option domain-name "engineering.example.org";
  option domain-name-servers ns1.engineering.example.org,   option domain-name-servers ns1.engineering.example.org,
                              ns2.engineering.example.org;                               ns2.engineering.example.org;
 } else {  } else {
   max-lease-time 600;    max-lease-time 600;
   option domain-name "misc.example.org";    option domain-name "misc.example.org";
  option domain-name-servers ns1.misc.example.org,   option domain-name-servers ns1.misc.example.org,
                              ns2.misc.example.org;                               ns2.misc.example.org;
 }  }
 .fi  .fi
Line 71  On the client side, an example of conditional evaluati Line 71  On the client side, an example of conditional evaluati
 .PP  .PP
 .nf  .nf
 # example.org filters DNS at its firewall, so we have to use their DNS  # 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# servers when we connect to their network.  If we are not at
 # example.org, prefer our own DNS server.  # example.org, prefer our own DNS server.
 if not option domain-name = "example.org" {  if not option domain-name = "example.org" {
   prepend domain-name-servers 127.0.0.1;    prepend domain-name-servers 127.0.0.1;
 }  }
.fi  .fi
 .PP  .PP
 The  The
 .B if  .B if
 statement and the  statement and the
 .B elsif  .B elsif
 continuation statement both take boolean expressions as their  continuation statement both take boolean expressions as their
arguments.   That is, they take expressions that, when evaluated,arguments.  That is, they take expressions that, when evaluated,
produce a boolean result.   If the expression evaluates to true, thenproduce a boolean result.  If the expression evaluates to true, then
the statements enclosed in braces following the the statements enclosed in braces following the
 .B if  .B if
 statement are executed, and all subsequent  statement are executed, and all subsequent
 .B elsif  .B elsif
 and  and
 .B else  .B else
clauses are skipped.   Otherwise, each subsequent clauses are skipped.  Otherwise, each subsequent 
 .B elsif  .B elsif
 clause's expression is checked, until an elsif clause is encountered  clause's expression is checked, until an elsif clause is encountered
whose test evaluates to true.   If such a clause is found, thewhose test evaluates to true.  If such a clause is found, the
 statements in braces following it are executed, and then any  statements in braces following it are executed, and then any
 subsequent  subsequent
 .B elsif  .B elsif
 and  and
 .B else  .B else
clauses are skipped.   If all the clauses are skipped.  If all the 
 .B if  .B if
 and  and
 .B elsif  .B elsif
Line 109  of their expressions evaluate true, then if there is a Line 109  of their expressions evaluate true, then if there is a
 .B else  .B else
 clause, the statements enclosed in braces following the  clause, the statements enclosed in braces following the
 .B else  .B else
are evaluated.   Boolean expressions that evaluate to null areare evaluated.  Boolean expressions that evaluate to null are
 treated as false in conditionals.  treated as false in conditionals.
 .SH BOOLEAN EXPRESSIONS  .SH BOOLEAN EXPRESSIONS
 The following is the current list of boolean expressions that are  The following is the current list of boolean expressions that are
Line 119  supported by the DHCP distribution. Line 119  supported by the DHCP distribution.
 .RS 0.25i  .RS 0.25i
 .PP  .PP
 The \fB=\fR operator compares the values of two data expressions,  The \fB=\fR operator compares the values of two data expressions,
returning true if they are the same, false if they are not.   Ifreturning 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  either the left-hand side or the right-hand side are null, the
 result is also null.  result is also null.
 .RE  .RE
Line 132  The \fB~=\fR and \fB~~\fR operators (not available on  Line 132  The \fB~=\fR and \fB~~\fR operators (not available on 
 extended regex(7) matching of the values of two data expressions, returning  extended regex(7) matching of the values of two data expressions, returning
 true if \fIdata-expression-1\fR matches against the regular expression  true if \fIdata-expression-1\fR matches against the regular expression
 evaluated by \fIdata-expression-2\fR, or false if it does not match or  evaluated by \fIdata-expression-2\fR, or false if it does not match or
encounters some error.  If either the left-hand side or the right-hand side encounters some error.  If either the left-hand side or the right-hand side
 are null or empty strings, the result is also false.  The \fB~~\fR operator  are null or empty strings, the result is also false.  The \fB~~\fR operator
 differs from the \fB~=\fR operator in that it is case-insensitive.  differs from the \fB~=\fR operator in that it is case-insensitive.
 .RE  .RE
Line 162  the right-hand side are null, the result is null. Line 162  the right-hand side are null, the result is null.
 .RS 0.25i  .RS 0.25i
 The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR  The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR
 evaluates to false, and returns false if \fIboolean-expression\fR evaluates  evaluates to false, and returns false if \fIboolean-expression\fR evaluates
to true.   If \fIboolean-expression\fR evaluates to null, the resultto true.  If \fIboolean-expression\fR evaluates to null, the result
 is also null.  is also null.
 .RE  .RE
 .PP  .PP
Line 188  address assignment. Line 188  address assignment.
 .RE  .RE
 .SH DATA EXPRESSIONS  .SH DATA EXPRESSIONS
 Several of the boolean expressions above depend on the results of  Several of the boolean expressions above depend on the results of
evaluating data expressions.   A list of these expressions is providedevaluating data expressions.  A list of these expressions is provided
 here.  here.
 .PP  .PP
 .B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR  .B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR
Line 211  is returned. Line 211  is returned.
 .PP  .PP
 .RS 0.25i  .RS 0.25i
 The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the  The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the
last \fIlength\fR bytes of the result of that evaluation. \fILength\fRlast \fIlength\fR bytes of the result of that evaluation.  \fILength\fR
 is a numeric expression.  If \fIdata-expr\fR or \fIlength\fR evaluate  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  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  number greater than the length of the evaluated data, then the
Line 222  evaluated data is returned. Line 222  evaluated data is returned.
 .PP  .PP
 .RS 0.25i  .RS 0.25i
 The \fBlcase\fR function returns the result of evaluating  The \fBlcase\fR function returns the result of evaluating
\fIdata-expr\fR converted to lower case.   If \fIdata-expr\fR evaluates\fIdata-expr\fR converted to lower case.  If \fIdata-expr\fR evaluates
 to null, then the result is also null.  to null, then the result is also null.
 .RE  .RE
 .PP  .PP
Line 230  to null, then the result is also null. Line 230  to null, then the result is also null.
 .PP  .PP
 .RS 0.25i  .RS 0.25i
 The \fBucase\fR function returns the result of evaluating  The \fBucase\fR function returns the result of evaluating
\fIdata-expr\fR converted to upper case.   If \fIdata-expr\fR evaluates\fIdata-expr\fR converted to upper case.  If \fIdata-expr\fR evaluates
 to null, then the result is also null.  to null, then the result is also null.
 .RE  .RE
 .PP  .PP
Line 253  that the DHCP client or server has been configured to  Line 253  that the DHCP client or server has been configured to 
 .RS 0.25i  .RS 0.25i
 The \fBhardware\fR operator returns a data string whose first element  The \fBhardware\fR operator returns a data string whose first element
 is the type of network interface indicated in packet being considered,  is the type of network interface indicated in packet being considered,
and whose subsequent elements are client's link-layer address.   Ifand whose subsequent elements are client's link-layer address.  If
 there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,  there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,
then the result is null.   Hardware types include ethernet (1),then the result is null.  Hardware types include ethernet (1),
token-ring (6), and fddi (8).   Hardware types are specified by thetoken-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  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/  RFC2131 (in the ISC DHCP distribution, this is included in the doc/
 subdirectory).  subdirectory).
Line 267  subdirectory). Line 267  subdirectory).
 .RS 0.25i  .RS 0.25i
 The \fBpacket\fR operator returns the specified portion of the packet  The \fBpacket\fR operator returns the specified portion of the packet
 being considered, or null in contexts where no packet is being  being considered, or null in contexts where no packet is being
considered.   \fIOffset\fR and \fIlength\fR are applied to theconsidered.  \fIOffset\fR and \fIlength\fR are applied to the
 contents packet as in the \fBsubstring\fR operator.  contents packet as in the \fBsubstring\fR operator.
 .RE  .RE
 .PP  .PP
Line 275  contents packet as in the \fBsubstring\fR operator. Line 275  contents packet as in the \fBsubstring\fR operator.
 .PP  .PP
 .RS 0.25i  .RS 0.25i
 A string, enclosed in quotes, may be specified as a data expression,  A string, enclosed in quotes, may be specified as a data expression,
and returns the text between the quotes, encoded in ASCII.   Theand returns the text between the quotes, encoded in ASCII.  The
 backslash ('\\') character is treated specially, as in C programming: '\\t'  backslash ('\\') character is treated specially, as in C programming: '\\t'
 means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means  means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means
bell.   Any octal value can be specified with '\\nnn', where nnn is anybell.  Any octal value can be specified with '\\nnn', where nnn is any
 positive octal number less than 0400.  Any hexadecimal value can be  positive octal number less than 0400.  Any hexadecimal value can be
 specified with '\\xnn', where nn is any positive hexadecimal number less  specified with '\\xnn', where nn is any positive hexadecimal number less
 than or equal to 0xff.  than or equal to 0xff.
Line 294  specified as a data expression. Line 294  specified as a data expression.
 .B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR  .B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR
 .RS 0.25i  .RS 0.25i
 The expressions are evaluated, and the results of each evaluation are  The expressions are evaluated, and the results of each evaluation are
concatenated in the sequence that the subexpressions are listed.   Ifconcatenated in the sequence that the subexpressions are listed.  If
 any subexpression evaluates to null, the result of the concatenation  any subexpression evaluates to null, the result of the concatenation
 is null.  is null.
 .RE  .RE
Line 303  is null. Line 303  is null.
 .RS 0.25i  .RS 0.25i
 The two expressions are evaluated, and then the result of evaluating  The two expressions are evaluated, and then the result of evaluating
 the data expression is reversed in place, using hunks of the size  the data expression is reversed in place, using hunks of the size
specified in the numeric expression.   For example, if the numericspecified in the numeric expression.  For example, if the numeric
expression evaluates to four, and the data expression evaluates to expression evaluates to four, and the data expression evaluates to
 twelve bytes of data, then the reverse expression will evaluate to  twelve bytes of data, then the reverse expression will evaluate to
 twelve bytes of data, consisting of the last four bytes of the the  twelve bytes of data, consisting of the last four bytes of the the
 input data, followed by the middle four bytes, followed by the first  input data, followed by the middle four bytes, followed by the first
Line 328  information). Line 328  information).
 .RS 0.25i  .RS 0.25i
 Converts the result of evaluating data-expr2 into a text string  Converts the result of evaluating data-expr2 into a text string
 containing one number for each element of the result of evaluating  containing one number for each element of the result of evaluating
data-expr2.   Each number is separated from the other by the result ofdata-expr2.  Each number is separated from the other by the result of
evaluating data-expr1.   The result of evaluating numeric-expr1evaluating data-expr1.  The result of evaluating numeric-expr1
 specifies the base (2 through 16) into which the numbers should be  specifies the base (2 through 16) into which the numbers should be
converted.   The result of evaluating numeric-expr2 specifies theconverted.  The result of evaluating numeric-expr2 specifies the
 width in bits of each number, which may be either 8, 16 or 32.  width in bits of each number, which may be either 8, 16 or 32.
 .PP  .PP
 As an example of the preceding three types of expressions, to produce  As an example of the preceding three types of expressions, to produce
Line 358  also null. Line 358  also null.
 .B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR  .B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR
 .RS 0.25i  .RS 0.25i
 The pick-first-value function takes any number of data expressions as  The pick-first-value function takes any number of data expressions as
its arguments.   Each expression is evaluated, starting with the firstits arguments.  Each expression is evaluated, starting with the first
 in the list, until an expression is found that does not evaluate to a  in the list, until an expression is found that does not evaluate to a
null value.   That expression is returned, and none of the subsequentnull value.  That expression is returned, and none of the subsequent
expressions are evaluated.   If all expressions evaluate to a nullexpressions are evaluated.  If all expressions evaluate to a null
 value, the null value is returned.  value, the null value is returned.
 .RE  .RE
 .PP  .PP
Line 369  value, the null value is returned. Line 369  value, the null value is returned.
 .RS 0.25i  .RS 0.25i
 The host-decl-name function returns the name of the host declaration  The host-decl-name function returns the name of the host declaration
 that matched the client whose request is currently being processed, if  that matched the client whose request is currently being processed, if
any.   If no host declaration matched, the result is the null value.any.  If no host declaration matched, the result is the null value.
 .RE  .RE
 .SH NUMERIC EXPRESSIONS  .SH NUMERIC EXPRESSIONS
Numeric expressions are expressions that evaluate to an integer.   InNumeric expressions are expressions that evaluate to an integer.  In
 general, the maximum size of such an integer should not be assumed to  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  be representable in fewer than 32 bits, but the precision of such
 integers may be more than 32 bits.  integers may be more than 32 bits.
Line 382  integers may be more than 32 bits. Line 382  integers may be more than 32 bits.
 .RS 0.25i  .RS 0.25i
 The \fBextract-int\fR operator extracts an integer value in network  The \fBextract-int\fR operator extracts an integer value in network
 byte order from the result of evaluating the specified data  byte order from the result of evaluating the specified data
expression.   Width is the width in bits of the integer to extract.expression.  Width is the width in bits of the integer to extract.
Currently, the only supported widths are 8, 16 and 32.   If theCurrently, the only supported widths are 8, 16 and 32.  If the
 evaluation of the data expression doesn't provide sufficient bits to  evaluation of the data expression doesn't provide sufficient bits to
 extract an integer of the specified size, the null value is returned.  extract an integer of the specified size, the null value is returned.
 .RE  .RE
Line 405  specified as a numeric expression. Line 405  specified as a numeric expression.
 .B client-state  .B client-state
 .PP  .PP
 .RS 0.25i  .RS 0.25i
The current state of the client instance being processed.   This isThe current state of the client instance being processed.  This is
only useful in DHCP client configuration files.   Possible values are:only useful in DHCP client configuration files.  Possible values are:
 .TP 2  .TP 2
 .I \(bu  .I \(bu
 Booting - DHCP client is in the INIT state, and does not yet have an  Booting - DHCP client is in the INIT state, and does not yet have an
IP address.   The next message transmitted will be a DHCPDISCOVER,IP address.  The next message transmitted will be a DHCPDISCOVER,
 which will be broadcast.  which will be broadcast.
 .TP  .TP
 .I \(bu  .I \(bu
Reboot - DHCP client is in the INIT-REBOOT state.   It has an IPReboot - DHCP client is in the INIT-REBOOT state.  It has an IP
address, but is not yet using it.   The next message to be transmittedaddress, but is not yet using it.  The next message to be transmitted
will be a DHCPREQUEST, which will be broadcast.   If no response iswill be a DHCPREQUEST, which will be broadcast.  If no response is
 heard, the client will bind to its address and move to the BOUND state.  heard, the client will bind to its address and move to the BOUND state.
 .TP  .TP
 .I \(bu  .I \(bu
 Select - DHCP client is in the SELECTING state - it has received at  Select - DHCP client is in the SELECTING state - it has received at
 least one DHCPOFFER message, but is waiting to see if it may receive  least one DHCPOFFER message, but is waiting to see if it may receive
other DHCPOFFER messages from other servers.   No messages are sent inother DHCPOFFER messages from other servers.  No messages are sent in
 the SELECTING state.  the SELECTING state.
 .TP  .TP
 .I \(bu  .I \(bu
 Request - DHCP client is in the REQUESTING state - it has received at  Request - DHCP client is in the REQUESTING state - it has received at
 least one DHCPOFFER message, and has chosen which one it will  least one DHCPOFFER message, and has chosen which one it will
request.   The next message to be sent will be a DHCPREQUEST message,request.  The next message to be sent will be a DHCPREQUEST message,
 which will be broadcast.  which will be broadcast.
 .TP  .TP
 .I \(bu  .I \(bu
Bound - DHCP client is in the BOUND state - it has an IP address.   NoBound - DHCP client is in the BOUND state - it has an IP address.  No
 messages are transmitted in this state.  messages are transmitted in this state.
 .TP  .TP
 .I \(bu  .I \(bu
 Renew - DHCP client is in the RENEWING state - it has an IP address,  Renew - DHCP client is in the RENEWING state - it has an IP address,
and is trying to contact the server to renew it.   The next message toand is trying to contact the server to renew it.  The next message to
 be sent will be a DHCPREQUEST message, which will be unicast directly  be sent will be a DHCPREQUEST message, which will be unicast directly
 to the server.  to the server.
 .TP  .TP
 .I \(bu  .I \(bu
 Rebind - DHCP client is in the REBINDING state - it has an IP address,  Rebind - DHCP client is in the REBINDING state - it has an IP address,
and is trying to contact any server to renew it.   The next message toand is trying to contact any server to renew it.  The next message to
 be sent will be a DHCPREQUEST, which will be broadcast.  be sent will be a DHCPREQUEST, which will be broadcast.
 .RE  .RE
 .SH REFERENCE: ACTION EXPRESSIONS  .SH REFERENCE: ACTION EXPRESSIONS
Line 478  execution times are suitable for use. Line 478  execution times are suitable for use.
 Passing user-supplied data to an external application might be dangerous.  Passing user-supplied data to an external application might be dangerous.
 Make sure the external application checks input buffers for validity.  Make sure the external application checks input buffers for validity.
 Non-printable ASCII characters will be converted into dhcpd.conf language  Non-printable ASCII characters will be converted into dhcpd.conf language
octal escapes ("\777"), make sure your external command handles them asoctal escapes ("\\nnn"), make sure your external command handles them as
 such.  such.
 .PP  .PP
 It is possible to use the execute statement in any context, not only  It is possible to use the execute statement in any context, not only
on events. If you put it in a regular scope in the configuration fileon events.  If you put it in a regular scope in the configuration file
 you will execute that command every time a scope is evaluated.  you will execute that command every time a scope is evaluated.
 .RE  .RE
 .SH REFERENCE: DYNAMIC DNS UPDATES  .SH REFERENCE: DYNAMIC DNS UPDATES
Removed from v.1.1  
changed lines
  Added in v.1.1.1.1

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>