Droms R. The DHCP handbook

Подождите немного. Документ загружается.

An if statement can have an else clause. If boolean-expression turns out to be

false, the statements following the

if statement are skipped but the statements

within braces following the

else clause are executed.

The elsif Clause

if boolean-expression-1 {

[ statements-1 ]

} elsif boolean-expression-2 {

[ statements-2 ]

} else {

[ statements-3 ]

}

It is possible to chain a series of conditionals so that only one group of statements

out of a set is executed. In the preceding syntax diagram, if

boolean-expression-1

evaluates to true, the collection of statements labeled statements-1 is executed, and

statements-2 and statements-3 are skipped, regardless of what the result of evaluat-

ing

boolean-expression-2 might have been. boolean-expression-2 is evaluated

only if

boolean-expression-1 evaluates to false. If boolean-expression-2 evaluates

true, the collection of statements labeled statements-2 is executed. Otherwise,

the statements labeled

statements-3 are executed. An elsif clause doesn’t have to

be followed by an

else clause, but if there is an else clause, it must be the last

clause in the chain. It is possible to chain together an arbitrary number of

elsif

clauses.

The switch Statement

switch ( expression-1 ) {

case expression-2:

[ statements ]

case expression-3:

[ statements ]

break;

...

default:

[ statements ]

}

A switch statement allows the user to direct the DHCP program to compute the

value of an expression and then compare it against a series of expressions, one in

each

case statement, until it finds one that matches. Execution of the statements

within the

switch statement begins after the matching case statement. If no case

APPENDIX B ISC DHCP Server Configuration File Reference476

032 3273 App B 10/3/02 5:04 PM Page 476

statement matches, then execution begins after the default statement, if there is

one. The syntax is much like that of the C

switch statement, but the semantics are a

bit different. The expression in each

case statement is evaluated at runtime; it does

not have to be a constant. Like the C

switch/case statement, though, a break state-

ment is required to exit the

switch statement; otherwise, once execution of the

switch statement has begun, it continues through case statements and default

statements until the end of the switch statement is reached.

The on Statement

on event [ | event [ | event ]]{

[ statements ]

}

The on statement allows the user to specify an action that will occur when a certain

event happens. This is generally useful in the DHCP server. The

expiry, release, and

commit events are supported. When a client acquires or renews a lease, the commit

event happens. When a client releases a lease, the release event happens. When a

lease expires on its own, the

expiry event happens. The actions to perform when

events occur are stored in the lease database, so they occur even if the server is

stopped and restarted between the time when the event is set and the time when it

happens. This is most useful for doing DNS updates, although it can also be useful

with the

log statement.

The log Statement

log ( priority, expression );

The log statement causes the DHCP server to log the result of evaluating expression

to the system logger at the priority specified by priority. The expression must evalu-

ate to a printable ASCII string. The

log statement is intended for debugging and does

not make things easy for the user.

The set Statement

set variable = expression;

The set statement stores the result of evaluating expression in a variable named

variable. This variable is recorded on the lease that is being processed, if a lease is

being processed, and persists across restarts of the DHCP server. If no lease is being

processed, the

set statement has no effect.

After a variable has been set on a lease, even the expiration of the lease cannot erase

the variable; only the

unset statement can remove it. Currently only integer and

Programming Statements 477

032 3273 App B 10/3/02 5:04 PM Page 477

string values can be stored in variables. Variables are scoped to the lease, so every

lease can have a variable with the same name, and each of these variables will be

distinct.

The unset Statement

unset variable;

The unset statement removes the variable named variable from the lease that is

being processed, if a lease is being processed. If a lease is not being processed, this

statement has no meaning.

Expressions

The DHCP server can evaluate expressions while executing statements. The DHCP

server’s expression evaluator currently supports expressions that return the following

types:

•A Boolean is a true or false, on or off value.

•Aninteger is a 32-bit quantity that can be treated as signed or unsigned,

depending on the context.

•A string of data is a collection of zero or more bytes. Any byte value is valid in a

data string—the DHCP server maintains a length rather than depending on a

NUL termination.

•A DNS value is a special data structure used exclusively by the ns-update opera-

tor in performing DNS updates.

Expression evaluation is performed whenever statements that use expressions are

evaluated—typically when a request is received from a DHCP client, when an event

occurs, and on startup. When a request is received from a client, values in the packet

the client sends can be extracted and used to determine what to send back to the

client. If you can refer to a value in the client packet for which there is no value,

the result is the null value. If you try to get data from a client packet in a context

where no client packet has been received, you might see an error message. Null

values are treated specially in expression evaluation. The precise way in which

null values are handled varies according to the operator. In general, a Boolean

expression that returns a null value is considered false. A data expression that returns

a null value generally results in the statement using the value not having any effect.

APPENDIX B ISC DHCP Server Configuration File Reference478

032 3273 App B 10/3/02 5:04 PM Page 478

Indeterminate Operators

This section defines all the operators the ISC DHCP server currently supports that

return an indeterminate type.

The

( ) Operator

( expression )

The ( ) operator returns the result of evaluating expression. This operator can be

useful for clarifying code or for overriding operator precedence.

The

variable Operator

variable

If a variable appears in an expression, it returns the contents of that variable in the

current lease. If there is no current lease, or if there is no such variable in the current

lease, this operator returns the null value.

The

null Operator

null

The null operator returns the null value.

Boolean Operators

This section defines all the operators the ISC DHCP server currently supports that

return Boolean values.

The

static Operator

static

The static operator evaluates to true if an address is being assigned to the DHCP

client from a fixed-address declaration.

The

= Operator

data-expression-1 = data-expression-2

The = operator compares the result of evaluating data-expression-1 and data-

expression-2. If they are the same, the result is true; otherwise, it is false. If either

data-expression-1 or data-expression-2 evaluates to the null value, the result is

also null.

The

and Operator

boolean-expression-1 and boolean-expression-2

Expressions 479

032 3273 App B 10/3/02 5:04 PM Page 479

The and operator evaluates to true if boolean-expression-1 and boolean-

expression-2 both evaluate to true. If either expression evaluates to the null value,

the result is null. If either expression evaluates to

false, the result is false.

The

or Operator

boolean-expression-1 or boolean-expression-2

The or operator evaluates to true if either boolean-expression-1 or boolean-

expression-2 evaluates to true. If both expressions evaluate to false, or to the null

value, the result is false.

The

not Operator

not boolean-expression

The not operator evaluates to true if boolean-expression evaluates to false, and it

evaluates to

false if boolean-expression evaluates to true. If boolean-expression

evaluates to the null value, the result is also null.

The

exists Operator

exists option-name

The exists operator returns true if the specified option exists in the DHCP packet

that is being examined. Otherwise, it evaluates to

false.

The

known Operator

known

The known operator evaluates to true if the client whose request is currently being

processed is known—that is, if there is a

host declaration for it. Otherwise, it evalu-

ates to

false.

The

defined Operator

defined ( variable )

The defined operator evaluates to true if a variable named variable is defined on

the lease that is currently being processed. If no lease is being processed, the result is

the null value. If the variable is not defined, the result of the evaluation is

false.

Data Operators

This section describes all the operators that the ISC DHCP server currently supports

that return strings of data.

APPENDIX B ISC DHCP Server Configuration File Reference480

032 3273 App B 10/3/02 5:04 PM Page 480

The substring Operator

substring (data-expr, offset, length)

The substring operator evaluates the data expression and returns the substring of

the result of the evaluation that starts

offset bytes from the beginning, continuing

for

length bytes. offset and length are both numeric expressions. If data-expr,

offset,orlength evaluates to the null value, the result is also null. If offset is

greater than or equal to the length of the evaluated data, a zero-length data string is

returned. If

length is greater than the remaining length of the evaluated data after

offset, a data string containing all data from offset to the end of the data is

returned.

The

suffix Operator

suffix (data-expr, length)

The suffix operator evaluates data-expr and returns the last length bytes of the

result of that evaluation.

length is a numeric expression. If data-expr or length

evaluates to the null value, the result is also null. If length evaluates to a number

greater than the length of the data, all the data is returned.

The

pick Operator

pick (first-data-expr , data-expr [ ... , last-data-expr ])

The pick operator evaluates each data-expr in succession, from left to right, until

one of them evaluates to something other than the null value. The result of that

evaluation is the result of evaluating the

pick operator. The pick operator can

choose among any number of expressions.

The

binary-to-ascii Operator

binary-to-ascii (base, width, separator, expression)

The binary-to-ascii operator evaluates the numeric expressions base and width

and the data expressions separator and expression. If any of these expressions eval-

uates to the null value, the result is null. Otherwise, the binary data that results from

evaluating

expression is broken up into chunks that are width bits wide. Each chunk

is converted to a printable ASCII representation of the number in the base specified

base and then they are all concatenated together, separated by the result of evalu-

ating

separator, and this becomes the result of the evaluation. width must be a

multiple of 8.

Expressions 481

032 3273 App B 10/3/02 5:04 PM Page 481

The reverse Operator

reverse (width, expression)

The reverse operator evaluates the numeric expression width and the data expres-

sion

expression. If either of these expressions evaluates to the null value, the result

is null. Otherwise, the binary data that results from evaluating

expression is broken

up into chunks that are

width bits wide. The chunks are then concatenated back

together in reverse order, and that is the result of the evaluation.

width must be a

multiple of 8.

The

option Operator

option option-name

The option operator returns the contents of the specified option in the packet that is

being considered. If no such option appears in the packet, or if the expression is

evaluated in a situation where no packet exists, the result of the evaluation is the

null value. If no option space is specified, the

dhcp option space is used.

The

config-option Operator

config-option option-name

The config-option operator returns the contents of the specified option as it has

been determined from processing the configuration file. If no such option appears in

the configuration, the result of the evaluation is the null value. If no option space is

specified, the

server option space is used.

The

hardware Operator

hardware

The hardware operator returns a data string whose first element is the htype field of

the packet that is being considered and whose subsequent elements are first

hlen

bytes of the chaddr field of the packet, as described in Appendix C, “The DHCP

Message Format.” If no packet exists, or if the

hlen field in the packet is invalid, the

result is null.

The

packet Operator

packet (offset, length)

The packet operator returns the specified portion of the packet that is being exam-

ined, or null in contexts in which no packet exists.

offset and length are applied to

the contents of the packet, as with the

substring operator. The beginning of the

packet is actually the first byte of payload in the UDP packet, so it is not possible to

examine the link-layer, IP, or UDP headers.

APPENDIX B ISC DHCP Server Configuration File Reference482

032 3273 App B 10/3/02 5:04 PM Page 482

The leased-address Operator

leased-address

The leased-address operator evaluates to a data string that contains the IP address

that is being leased to the client, represented as binary data in network byte order. If

no IP address is being leased to the client, the result of the evaluation is the null

value.

The

host-decl-name Operator

host-decl-name

The host-decl-name operator evaluates to a data string that contains the name of the

host declaration that has matched the client. If no host declaration has matched the

client, or if no client request is being processed, the result of the evaluation is the

null value.

The

text Operator

“text”

A text string, enclosed in quotes, can be specified as a data expression. It evaluates to

an ASCII-encoded data string that contains the text between the quotes.

The

string Operator

byte-1 [ ... : byte-n ]

A list of hexadecimal byte values, separated by colons, can be specified as a data

expression. A single hexadecimal number, appearing where a data string is expected,

is interpreted as a data string that contains a single byte.

The

concat Operator

concat (data-expr1, data-expr2)

With the concat operator, data-expr1 and data-expr2 are evaluated, and the result

of concatenating the results of the two evaluations is returned. If either data expres-

sion evaluates to the null value, the result is null.

The

encode-int Operator

encode-int (numeric-expr, width)

With the encode-int operator, numeric-expr is evaluated and encoded as a data

string of the specified

width, in network byte order (with the most significant byte

first). If

numeric-expr evaluates to the null value, the result is also the null value.

Expressions 483

032 3273 App B 10/3/02 5:04 PM Page 483

Numeric Operators

A numeric operator is an expression that evaluates to an integer. In general, the preci-

sion of numeric expressions is at least 32 bits, but the precision of numeric expres-

sions may be more than 32 bits with some CPU architectures. In addition to the

operators described in the following sections, the usual mathematical operations are

available: addition (

+), subtraction (-), division (/), multiplication (*), remainder of

division (

%), bitwise AND (&), bitwise OR (|), and bitwise XOR (^).

The

extract-int Operator

extract-int (data-expr, width)

The extract-int operator extracts an integer value in network byte order from the

result of evaluating

data-expr. 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

data-

expr doesn’t provide sufficient bits to extract an integer of the specified size, the null

value is returned.

The

number Operator

number

If a decimal number appears in an expression, it evaluates to the binary value of that

number, up to the maximum precision of numeric expressions—at least 32 bits.

The

lease-time Operator

lease-time

The lease-time operator evaluates to the duration of the lease being given to the

client, in seconds. If no lease is being given to the client, the result is the null value.

The

client-state Operator

client-state

The client-state operator evaluates to a number that represents the state that the

DHCP client is in. This operator is applicable only in the DHCP client. Constants are

defined for each of the possible states, which are

BOOTING, REBOOT, SELECT, REQUEST,

RENEW, and REBIND.

The

ns-update Operator

ns-update (dns-expr [ ... , last-dns-expr])

The ns-update operator performs the DNS update operation indicated by its argu-

ments, and it returns the result as an integer. Constants are defined for the possible

result values:

NS_NOERROR

NS_FORMERR

NS_NOTAUTH

NS_NOTIMP

NS_NOTZONE

NS_NXDOMAIN

APPENDIX B ISC DHCP Server Configuration File Reference484

032 3273 App B 10/3/02 5:04 PM Page 484

NS_NXRRSET

NS_REFUSED

NS_SERVFAIL

NS_YXDOMAIN

, and

NS_YXRRSET

. If any of the

expressions passed to

ns-update evaluates to null, the update is not done and

ns-update returns the null value.

DNS Operators

A DNS operator is an expression that evaluates to a data structure that can be used by

the

ns-update operator to perform a DNS update.

The

add Operator

add (class, type, name, value, ttl)

The add operator instructs ns-update to add a resource record in the specified class,

of the specified type, and with the specified value to the DNS at the specified name,

with the specified time to live (TTL). If any of these evaluates to the null value, the

add operator evaluates to the null value as well. class is normally

C_IN

, but other

classes can also be specified.

type is the resource record (RR) type to add, and is

usually either

T_A

T_PTR

. name is the name at which to add the RR, and it should be

a fully qualified domain name.

value is the value for the record. For A records, it is

the IP address represented as binary data in network byte order. For other records, it

is an ASCII text string.

ttl is specified as a number of seconds.

The

delete Operator

delete (class, type, name [, value ])

The delete operator operator instructs ns-update to delete a resource record or RR

set. The arguments correspond to the arguments for the

add operator, except that no

TTL should be specified. If

value is specified, only the RR matching the name and

value is deleted. If

value is not specified, the entire RR set is deleted.

The

exists Operator

exists (class, type, name [, value ])

The exists operator operator instructs ns-update to place a prerequisite on the DNS

update that is being constructed. If just

class, type, and name are specified, the

prerequisite is that an RR set of the specified type must be attached to the specified

name in the DNS. If

value is also specified, there must be an RR in the DNS on the

specified name, and it must have the specified value.

The

not exists Operator

not exists (class, type, name [, value ])

The not exists operator instructs ns-update to place a prerequisite on the DNS

update that is being constructed. If just

class, type, and name are specified, the

prerequisite is that an RR set of the specified type must not be attached to the

Expressions 485

032 3273 App B 10/3/02 5:04 PM Page 485