NAME

dhcp-eval - ISC DHCP conditional evaluation

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.

REFERENCE: CONDITIONAL BEHAVIOUR

Conditional behaviour may be specified using the if statement and the else or elsif statements or the switch and case 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.

CONDITIONAL BEHAVIOUR: IF

A typical conditional if statement in a server might be:

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;
}

On the client side, an example of conditional evaluation might be:

# 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;
}

The if statement and the 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 if statement are executed, and all subsequent elsif and else clauses are skipped. Otherwise, each subsequent 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 elsif and else clauses are skipped. If all the if and elsif clauses are checked but none of their expressions evaluate true, then if there is an else clause, the statements enclosed in braces following the else are evaluated. Boolean expressions that evaluate to null are treated as false in conditionals.

CONDITIONAL BEHAVIOUR: SWITCH

The above example can be rewritten using a switch construct as well.

switch (option dhcp-user-class) {
  case "accounting":
    max-lease-time 17600;
    option domain-name "accounting.example.org";
    option domain-name-servers ns1.accounting.example.org,
			       ns2.accounting.example.org;
  case "sales":
    max-lease-time 17600;
    option domain-name "sales.example.org";
    option domain-name-servers ns1.sales.example.org,
			       ns2.sales.example.org;
    break;
  case "engineering":
    max-lease-time 17600;
    option domain-name "engineering.example.org";
    option domain-name-servers ns1.engineering.example.org,
			       ns2.engineering.example.org;
    break;
  default:
    max-lease-time 600;
    option domain-name "misc.example.org";
    option domain-name-servers ns1.misc.example.org,
			       ns2.misc.example.org;
    break;
}

The switch statement and the case statements can both be data expressions or numeric expressions. Within a switch statement they all must be the same type. The server evaluates the expression from the switch statement and then it evaluates the expressions from the case statements until it finds a match.

If it finds a match it starts executing statements from that case until the next break statement. If it doesn't find a match it starts from the default statement and again proceeds to the next break statement. If there is no match and no default it does nothing.

BOOLEAN EXPRESSIONS

The following is the current list of boolean expressions that are supported by the DHCP distribution.

data-expression-1 = data-expression-2

data-expression-1 ~= data-expression-2 data-expression-1 ~~ data-expression-2

boolean-expression-1 and boolean-expression-2

boolean-expression-1 or boolean-expression-2

not boolean-expression

exists option-name

DATA EXPRESSIONS

Several of the boolean expressions above depend on the results of evaluating data expressions. A list of these expressions is provided here.

substring (data-expr, offset, length)

suffix (data-expr, length)

lcase (data-expr)

ucase (data-expr)

option option-name

config-option option-name

gethostname()

hardware

packet (offset, length)

string

colon-separated hexadecimal list

concat (data-expr1, ..., data-exprN)

reverse (numeric-expr1, data-expr2)

leased-address

binary-to-ascii (numeric-expr1, numeric-expr2, data-expr1, data-expr2)

        concat (binary-to-ascii (10, 8, ".",
                                 reverse (1, leased-address)),
                ".in-addr.arpa.");

encode-int (numeric-expr, width)

pick-first-value (data-expr1 [ ... exprn ] )

host-decl-name

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.

In addition to the following operators several standard math functions are available. They are:

operation    symbol
add            +
subtract       -
divide         /
multiply       *
modulus        %
bitwise and    &
bitwise or     |
bitwise xor    ^

extract-int (data-expr, width)

lease-time

number

client-state

REFERENCE: ACTION EXPRESSIONS

log (priority, data-expr)

execute (command-path [, data-expr1, ... data-exprN]);

parse-vendor-option;

REFERENCE: DYNAMIC DNS UPDATES

See the dhcpd.conf and dhclient.conf man pages for more information about DDNS.

SEE ALSO

dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-options(5), dhcpd(8), dhclient(8), RFC2132, RFC2131.

AUTHOR

Information about Internet Systems Consortium can be found at https://www.isc.org.