dhcp-eval(5)

🦋 dhcp-eval — ISC DHCP conditional evaluation 🦋

okay so this is dhcp-eval(5), filed under File Formats Manual, and honestly? it's giving "the DHCP glow-up nobody told you about." ✨

---

🌸 NAME 🌸

dhcp-eval — ISC DHCP conditional evaluation 💅

---

💜 DESCRIPTION 💜

so both the Internet Systems Consortium DHCP client and the ISC DHCP server have this whole ability to do conditional behaviour — like, they can change what they do depending on what's actually inside the packets they receive. 🎀 the syntax for telling them how to do that conditional thing? that's literally what this page is about. you're welcome bestie 🫶

---

✨ REFERENCE: CONDITIONAL BEHAVIOUR ✨

you've got a few ways to spell "if this, then that": the if statement, the else and elsif statements, or the switch and case statements. no cap.

and here's the slay part — a conditional statement can show up anywhere a regular statement (like, say, an option statement) can show up, and it can wrap one or more of those statements inside it. main character energy tbh 👑

🌈 CONDITIONAL BEHAVIOUR: IF 🌈

a typical if conditional on the server side looks like this:

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

and over on the client side, conditional evaluation can look like this:

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

okay so how does this actually work? 👀 the if statement and the elsif continuation statement both take boolean expressions as their arguments. translation: they take expressions that, when you evaluate them, hand you back a boolean result. true or false, no in-between, periodt.

if the expression evaluates to true, then the statements chillin' inside the braces after the if get executed, and every single elsif and else clause after that gets skipped entirely. bye 👋

otherwise? each following elsif clause's expression gets checked, one after another, until we hit an elsif whose test evaluates to true. if we find one, the statements in the braces after it run, and then any elsif and else clauses after that get skipped.

and if every if and elsif clause got checked and none of them evaluated true — then if there's an else clause, the statements inside its braces get evaluated. 🎀

one last thing, and it's important bestie: boolean expressions that evaluate to null get treated as false in conditionals. write that down. 📝

🧚 CONDITIONAL BEHAVIOUR: SWITCH 🧚

that whole example from before? yeah, you can rewrite it with a switch construct instead. look:

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

so the switch statement and the case statements — either one can be a data expression or a numeric expression. but here's the rule: inside a single switch statement, they all have to be the same type. no mixing, bestie, it's a vibe check and they all gotta pass. ✅

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 and keeps going 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. and if there's no match and no default? it just does nothing. 💀

---

⭐ BOOLEAN EXPRESSIONS ⭐

here's the current list of boolean expressions that the DHCP distribution supports, bestie. this is the whole roster. 👑

• data-expression-1 = data-expression-2 — the = operator compares the values of two data expressions and returns true if they're the same, false if they're not. and if either the left-hand side or the right-hand side is null, the result is also null. 🙈
• data-expression-1 ~= data-expression-2, data-expression-1 ~~ data-expression-2 — the ~= and ~~ operators (heads up: not available on all systems 🚨) do extended regex(7) matching on the values of two data expressions. they return true if data-expression-1 matches against the regular expression evaluated by data-expression-2, or false if it doesn't match or hits some error. and if either the left-hand side or the right-hand side is null or an empty string, the result is also false. the ~~ operator differs from ~= in that it's case-insensitive. 💅
• boolean-expression-1 and boolean-expression-2 — the and 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. and if either the expression on the left-hand side or the expression on the right-hand side is null, the result is null. 🎀
• boolean-expression-1 or boolean-expression-2 — the or operator evaluates to true if either the boolean expression on the left-hand side or the boolean expression on the right-hand side evaluates to true. otherwise it evaluates to false. and if either the expression on the left-hand side or the expression on the right-hand side is null, the result is null. ✨
• not boolean-expression — the not operator evaluates to true if boolean-expression evaluates to false, and returns false if boolean-expression evaluates to true. and if boolean-expression evaluates to null, the result is also null. 🔄
• exists option-name — the exists expression returns true if the specified option exists in the incoming DHCP packet being processed. 👀
• known — the known expression returns true if the client whose request is currently being processed is known — that is, if there's a host declaration for it. 🫶
• static — the static expression returns true if the lease assigned to the client whose request is currently being processed is derived from a static address assignment. 🌟

🌈 DATA EXPRESSIONS 🌈

ok so bestie, some of those boolean expressions up there? they're literally just out here waiting on the results of data expressions. so here's the full roster, no gatekeeping 💅

---

• substring (data-expr, offset, length) — this one evaluates data-expr and hands you back the chunk that starts offset bytes in from the beginning and keeps going for length bytes. both offset and length are numeric expressions, fyi. if data-expr, offset, or length evaluate to null, then boom — the result is null too. if offset is greater than or equal to the length of the evaluated data, you get a zero-length data string back. and if length is bigger than whatever's left after offset, then it just returns everything from offset to the end of the evaluated data. generous queen 💖
• suffix (data-expr, length) — returns the last length bytes of whatever data-expr evaluates to. length is a numeric expression. if data-expr or length evaluate to null, result is null. and if suffix evaluates to a number bigger than the length of the evaluated data? then you just get the whole evaluated data back, no drama 🫶
• lcase (data-expr) — returns data-expr converted to lower case. if data-expr is null, result is null. simple, iconic ✨
• ucase (data-expr) — same vibe but upper case. if data-expr evaluates to null, result is null. periodt 💅
• option option-name — returns the contents of the specified option in the packet the server is responding to.
• config-option option-name — returns the value for the specified option that the DHCP client or server has been configured to send.
• gethostname() — returns a data string whose contents are a character string: the result of calling gethostname() on the local system, with a size limit of 255 bytes (not counting the NULL terminator). why do you care? because you can use this to configure dhclient to send the local hostname without knowing what that hostname is at the time dhclient.conf is written. lowkey genius 🧚
• hardware — returns a data string where the first element is the type of network interface indicated in the packet being considered, and the elements after that are the client's link-layer address. if there's no packet, or the RFC2131 hlen field is invalid, then the result is null. hardware types include ethernet (1), token-ring (6), and fddi (8). these types are specified by the IETF, and the deets on how the type numbers are defined live in RFC2131 (in the ISC DHCP distribution, that's chillin' in the doc/ subdirectory).
• packet (offset, length) — returns the specified portion of the packet being considered, or null in contexts where no packet is being considered. offset and length get applied to the packet contents exactly like in the substring operator.
• string — a string wrapped in quotes can be a data expression, and it returns the text between the quotes, encoded in ASCII. the backslash ('\') character is special, just like in C programming: '\t' means TAB, '\r' means carriage return, '\n' means newline, and '\b' means bell. any octal value can be specified with '\nnn', where nnn is any positive octal number less than 0400. any hexadecimal value can be specified with '\xnn', where nn is any positive hexadecimal number less than or equal to 0xff. cute escapes fr fr 🔥
• colon-separated hexadecimal list — a list of hexadecimal octet values, separated by colons, can be specified as a data expression. that's it, that's the whole thing 💀
• concat (data-expr1, ..., data-exprN) — the expressions get evaluated, and each result gets concatenated in the sequence the subexpressions are listed. if any subexpression evaluates to null, the whole concatenation result is null. all-or-nothing bestie 😭
• reverse (numeric-expr1, data-expr2) — both expressions get evaluated, then the data expression's result is reversed in place, using hunks of the size given by the numeric expression. example time: if the numeric expression evaluates to four, and the data expression evaluates to twelve bytes of data, then reverse evaluates to twelve bytes — made of the last four bytes of the input, then the middle four bytes, then the first four bytes. so like, a lil shuffle, but make it mathematical ✨
• leased-address — in any context where the client whose request is being processed has been assigned an IP address, this returns that IP address. in any context where that client has not been assigned an IP address, and this data expression shows up in executable statements run on that client's behalf, a log message saying "there is no lease associated with this client" gets syslogged to the debug level (this counts as dhcpd.conf debugging information). so heads up: check your logs, bestie 🙈
• binary-to-ascii (numeric-expr1, numeric-expr2, data-expr1, data-expr2) — converts the result of evaluating data-expr2 into a text string with one number for each element of that result. each number gets separated from the others by the result of evaluating data-expr1. numeric-expr1 gives the base (2 through 16) the numbers convert into. numeric-expr2 gives the width in bits of each number, which can be 8, 16, or 32.

and as a lil demo of the previous three types of expressions — to produce the name of a PTR record for the IP address being assigned to a client, you could write:

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

slay 💅

• encode-int (numeric-expr, width) — numeric-expr gets evaluated and encoded as a data string of the specified width, in network byte order (most significant byte first). if the numeric expression evaluates to the null value, the result is null too.
• pick-first-value (data-expr1 [ ... exprn ] ) — takes any number of data expressions as arguments. each one gets evaluated, starting with the first, until it finds one that doesn't evaluate to null. that one is returned, and none of the ones after it get evaluated. if every single expression evaluates to null, then the null value is returned. first-come-first-served, no cap 👑
• host-decl-name — returns the name of the host declaration that matched the client whose request is currently being processed, if any. if no host declaration matched, the result is the null value. mystery solved 🕵️‍♀️

---

🔢 NUMERIC EXPRESSIONS 🔢

so numeric expressions are expressions that evaluate to an integer. in general, don't assume the max size of such an integer is representable in fewer than 32 bits — but the precision of these integers may be more than 32 bits. okay? okay 💖

on top of the operators below, several standard math functions are available too. they are:

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

---

• extract-int (data-expr, width) — 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 evaluating the data expression doesn't give enough bits to extract an integer of the specified size, the null value is returned. sorry bestie, no partial credit 😭
• lease-time — the duration of the current lease. that is, the difference between the current time and the time the lease expires.
• number — any number between zero and the maximum representable size can be specified as a numeric expression.
• client-state — the current state of the client instance being processed. this one's only useful in DHCP client configuration files. possible values are:
  • Booting — DHCP client is in the INIT state, and does not yet have an IP address. the next message transmitted will be a DHCPDISCOVER, which will be broadcast.
  • Reboot — DHCP client is in the INIT-REBOOT state. it has an IP address, but is not yet using it. the next message transmitted will 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.
  • Select — DHCP client is in the SELECTING state. it has received at least one DHCPOFFER message, but is waiting to see if it might receive other DHCPOFFER messages from other servers. no messages are sent in the SELECTING state.
  • Request — DHCP client is in the REQUESTING state. it has received at least one DHCPOFFER message, and has chosen which one it will request. the next message to be sent will be a DHCPREQUEST message, which will be broadcast.
  • Bound — DHCP client is in the BOUND state. it has an IP address. no messages are transmitted in this state.
  • 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 to be sent will be a DHCPREQUEST message, which will be unicast directly to the server.
  • 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 to be sent will be a DHCPREQUEST, which will be broadcast.

the way this whole state machine just cycles... main character energy fr fr 🦋

---

✨ REFERENCE: ACTION EXPRESSIONS ✨

Okay bestie, this is where the config actually does stuff. Actions, not just vibes. 💅

📝 log (priority, data-expr)

The log statement is your lil messenger to the standard logging channels. It includes an optional priority — one of fatal, error, info, or debug — plus a data expression. Obsessed.

Logging statements take only a single data expression argument, so if you wanna output multiple data values, you will need to use the concat operator to concatenate them. No cap. 🫶

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

The execute statement runs an external command. The first argument is a string literal containing the name or path of the command to run. The other arguments, if present, are either string literals or data-expressions which evaluate to text strings, to be passed as command-line arguments to the command. It's giving "run this for me right now." ✨

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

execute is synchronous; the program will block until the external command being run has finished. Please note that lengthy program execution (for example, in an "on commit" in dhcpd.conf) may result in bad performance and timeouts. Only external applications with very short execution times are suitable for use. Keep it snappy, bestie. 💀

Passing user-supplied data to an external application might be dangerous. Make sure the external application checks input buffers for validity. Non-printable ASCII characters will be converted into dhcpd.conf language octal escapes ("\nnn"), make sure your external command handles them as such. Do not skip this warning, fr fr.

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 file you will execute that command every time a scope is evaluated. Like, every single time. Not just once. Be aware. 🌀

🧚 parse-vendor-option;

The parse-vendor-option statement attempts to parse a vendor option (code 43). It is only useful while processing a packet on the server and requires that the administrator has already used the vendor-option-space statement to select a valid vendor space. So no valid vendor space selected? It's not gonna work, periodt. 💅

This functionality may be used if the server needs to take different actions depending on the values the client placed in the vendor option and the sub-options are not at fixed locations. It is handled as an action to allow an administrator to examine the incoming options and choose the correct vendor space. Cute, right? 🎀

🌈 REFERENCE: DYNAMIC DNS UPDATES 🌈

See the dhcpd.conf and dhclient.conf man pages for more information about DDNS. That's the whole vibe here. Go read those for the deets. ✨

👀 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. That's the link, bestie. Go say hi. 👑

---

And that's the whole page, fr fr. This is dhcp-eval(5) from the ISC source/version, date stamped in the footer like a lil receipt. Bye bestie, go config slay 💖✨