OVN/OVS DHCP Internals: From `ovn-nbctl set-lsp` to the DHCP Response Packet

the setup

when you run a command like:

ovn-nbctl lsp-set-dhcpv4-options sw0-port0 dhcpv4opts

you’re telling OVN: “this logical port should have native DHCPv4 service, using the options defined in the dhcpv4opts DHCP_Options record.” the entire DHCP machinery — flow generation, packet construction, option encoding — kicks off from this single database reference.

the DHCP implementation in OVN spans the full stack:

NB Database stores the DHCP configuration (option values, CIDR, server parameters)
Northd syncs option definitions to the SB database and generates logical flows
OVN Controller reads option definitions and handles DHCP packet-Ins via pinctrl
OVS In-Band ensures DHCP replies from the local management port aren’t blocked by flow tables

i’m going to trace each layer. buckle up.

the nb database

DHCP options table

the NB database schema defines the DHCP_Options table (ovn/ovn-nb.ovsschema:711-719):

1
"DHCP_Options": {
2
    "columns": {
3
        "cidr": {"type": "string"},
4
        "options": {"type": {"key": "string", "value": "string",
5
                             "min": 0, "max": "unlimited"}},
6
        "external_ids": {
7
            "type": {"key": "string", "value": "string",
8
                     "min": 0, "max": "unlimited"}}},
9
    "isRoot": true},

three columns:

cidr: The subnet CIDR that these options apply to (e.g., "10.0.0.0/24")
options: A string→string map of DHCP option name/value pairs (e.g., "server_id" → "10.0.0.1", "server_mac" → "00:00:00:00:00:01")
external_ids: User-defined metadata

DHCP relay table

for DHCP relay scenarios, the NB schema defines DHCP_Relay (ovn/ovn-nb.ovsschema:720-731):

1
"DHCP_Relay": {
2
    "columns": {
3
        "name": {"type": "string"},
4
        "servers": {"type": {"key": "string", "min": 0, "max": 1}},
5
        "options": {"type": {"key": "string", "value": "string",
6
                             "min": 0, "max": "unlimited"}},
7
        "external_ids": {
8
            "type": {"key": "string", "value": "string",
9
                     "min": 0, "max": "unlimited"}}},
10
    "isRoot": true},

the servers column holds a single string — the IP address (and optionally port) of the remote DHCP server to relay to.

how ports reference DHCP configuration

logical switch ports reference DHCP options via weak UUID references (ovn/ovn-nb.ovsschema:161-170):

1
"dhcpv4_options": {"type": {"key": {"type": "uuid",
2
                            "refTable": "DHCP_Options",
3
                            "refType": "weak"},
4
                     "min": 0, "max": 1}},
5
"dhcpv6_options": {"type": {"key": {"type": "uuid",
6
                            "refTable": "DHCP_Options",
7
                            "refType": "weak"},
8
                     "min": 0, "max": 1}},

both are optional (min 0) and single-valued (max 1). they’re weak references — if the DHCP_Options record is deleted, the reference becomes NULL rather than cascading a delete.

logical router ports reference DHCP relay via a strong UUID reference (ovn/ovn-nb.ovsschema:597-601):

1
"dhcp_relay": {"type": {"key": {"type": "uuid",
2
                        "refTable": "DHCP_Relay",
3
                        "refType": "strong"},
4
                        "min": 0, "max": 1}},

and the logical switch itself has a runtime key dhcp_relay_port in its other_config map that identifies which switch port connects to the router performing relay:

1
"other_config": {
2
    "type": {"key": "string", "value": "string", "min": 0, "max": "unlimited"}},

this is set via ovn-nbctl set logical_switch <ls> other_config:dhcp_relay_port=<port>.

northd: syncing dhcp options to sb

the ovn-northd daemon maintains the SB database’s DHCP option definition tables. this ensures that every hypervisor knows the canonical set of DHCP options and their wire formats.

the built-in option tables

northd defines two static arrays of supported options in ovn/northd/ovn-northd.c:244-293:

DHCPv4 options (supported_dhcp_opts[], 39 entries):

1
static struct gen_opts_map supported_dhcp_opts[] = {
2
    OFFERIP,                        // "offerip", code 0, type "ipv4"
3
    DHCP_OPT_NETMASK,               // "netmask", code 1, type "ipv4"
4
    DHCP_OPT_ROUTER,                // "router", code 3, type "ipv4"
5
    DHCP_OPT_DNS_SERVER,            // "dns_server", code 6, type "ipv4"
6
    DHCP_OPT_LOG_SERVER,            // "log_server", code 7, type "ipv4"
7
    DHCP_OPT_LPR_SERVER,            // "lpr_server", code 9, type "ipv4"
8
    DHCP_OPT_SWAP_SERVER,           // "swap_server", code 16, type "ipv4"
9
    DHCP_OPT_POLICY_FILTER,         // "policy_filter", code 21, type "ipv4"
10
    DHCP_OPT_ROUTER_SOLICITATION,   // "router_solicitation", code 32, type "ipv4"
11
    DHCP_OPT_NIS_SERVER,            // "nis_server", code 41, type "ipv4"
12
    DHCP_OPT_NTP_SERVER,            // "ntp_server", code 42, type "ipv4"
13
    DHCP_OPT_SERVER_ID,             // "server_id", code 54, type "ipv4"
14
    DHCP_OPT_TFTP_SERVER,           // "tftp_server", code 66, type "host_id"
15
    DHCP_OPT_CLASSLESS_STATIC_ROUTE,// "classless_static_route", code 121, type "static_routes"
16
    DHCP_OPT_MS_CLASSLESS_STATIC_ROUTE, // "ms_classless_static_route", code 249, type "static_routes"
17
    DHCP_OPT_IP_FORWARD_ENABLE,     // "ip_forward_enable", code 19, type "bool"
18
    DHCP_OPT_ROUTER_DISCOVERY,      // "router_discovery", code 31, type "bool"
19
    DHCP_OPT_ETHERNET_ENCAP,        // "ethernet_encap", code 36, type "bool"
20
    DHCP_OPT_DEFAULT_TTL,           // "default_ttl", code 23, type "uint8"
21
    DHCP_OPT_TCP_TTL,               // "tcp_ttl", code 37, type "uint8"
22
    DHCP_OPT_MTU,                   // "mtu", code 26, type "uint16"
23
    DHCP_OPT_LEASE_TIME,            // "lease_time", code 51, type "uint32"
24
    DHCP_OPT_T1,                    // "T1", code 58, type "uint32"
25
    DHCP_OPT_T2,                    // "T2", code 59, type "uint32"
26
    DHCP_OPT_WPAD,                  // "wpad", code 252, type "str"
27
    DHCP_OPT_BOOTFILE,              // "bootfile_name", code 67, type "str"
28
    DHCP_OPT_PATH_PREFIX,           // "path_prefix", code 210, type "str"
29
    DHCP_OPT_TFTP_SERVER_ADDRESS,   // "tftp_server_address", code 150, type "ipv4"
30
    DHCP_OPT_HOSTNAME,              // "hostname", code 12, type "str"
31
    DHCP_OPT_DOMAIN_NAME,           // "domain_name", code 15, type "str"
32
    DHCP_OPT_ARP_CACHE_TIMEOUT,     // "arp_cache_timeout", code 35, type "uint32"
33
    DHCP_OPT_TCP_KEEPALIVE_INTERVAL,// "tcp_keepalive_interval", code 38, type "uint32"
34
    DHCP_OPT_DOMAIN_SEARCH_LIST,    // "domain_search_list", code 119, type "domains"
35
    DHCP_OPT_BOOTFILE_ALT,          // "bootfile_name_alt", code 254, type "str"
36
    DHCP_OPT_BROADCAST_ADDRESS,     // "broadcast_address", code 28, type "ipv4"
37
    DHCP_OPT_NETBIOS_NAME_SERVER,   // "netbios_name_server", code 44, type "ipv4"
38
    DHCP_OPT_NETBIOS_NODE_TYPE,     // "netbios_node_type", code 46, type "uint8"
39
    DHCP_OPT_NEXT_SERVER,           // "next_server", code 253, type "ipv4"
40
};

each entry is a struct gen_opts_map defined in ovn/lib/ovn-l7.h:57-62:

1
struct gen_opts_map {
2
    struct hmap_node hmap_node;
3
    char *name;
4
    char *type;
5
    size_t code;
6
};

the macros like DHCP_OPT_NETMASK expand via the DHCP_OPTION macro (ovn/lib/ovn-l7.h:77-78):

1
#define DHCP_OPTION(NAME, CODE, TYPE) \
2
    {.name = NAME, .code = CODE, .type = TYPE}
3

4
#define DHCP_OPT_NETMASK  DHCP_OPTION("netmask", 1, "ipv4")

DHCPv6 options (supported_dhcpv6_opts[], 7 entries):

1
static struct gen_opts_map supported_dhcpv6_opts[] = {
2
    DHCPV6_OPT_IA_ADDR,          // "ia_addr", code 5, type "ipv6"
3
    DHCPV6_OPT_SERVER_ID,        // "server_id", code 2, type "mac"
4
    DHCPV6_OPT_DOMAIN_SEARCH,    // "domain_search", code 24, type "str"
5
    DHCPV6_OPT_DNS_SERVER,       // "dns_server", code 23, type "ipv6"
6
    DHCPV6_OPT_BOOTFILE_NAME,    // "bootfile_name", code 59, type "str"
7
    DHCPV6_OPT_BOOTFILE_NAME_ALT,// "bootfile_name_alt", code 254, type "str"
8
    DHCPV6_OPT_FQDN,             // "fqdn", code 39, type "domain"
9
};

the sync function

the function check_and_add_supported_dhcp_opts_to_sb_db() (ovn/northd/ovn-northd.c:448-485) performs a full reconciliation:

1
static void
2
check_and_add_supported_dhcp_opts_to_sb_db(struct ovsdb_idl_txn *ovnsb_txn,
3
                                           struct ovsdb_idl *ovnsb_idl)
4
{
5
    struct hmap dhcp_opts_to_add = HMAP_INITIALIZER(&dhcp_opts_to_add);
6
    for (size_t i = 0; (i < sizeof(supported_dhcp_opts) /
7
                            sizeof(supported_dhcp_opts[0])); i++) {
8
        hmap_insert(&dhcp_opts_to_add, &supported_dhcp_opts[i].hmap_node,
9
                    dhcp_opt_hash(supported_dhcp_opts[i].name));
10
    }
11

12
    const struct sbrec_dhcp_options *opt_row;
13
    SBREC_DHCP_OPTIONS_FOR_EACH_SAFE (opt_row, ovnsb_idl) {
14
        struct gen_opts_map *dhcp_opt =
15
            dhcp_opts_find(&dhcp_opts_to_add, opt_row->name);
16
        if (dhcp_opt) {
17
            if (!strcmp(dhcp_opt->type, opt_row->type) &&
18
                 dhcp_opt->code == opt_row->code) {
19
                hmap_remove(&dhcp_opts_to_add, &dhcp_opt->hmap_node);
20
            } else {
21
                sbrec_dhcp_options_delete(opt_row);  /* Type/code mismatch → delete */
22
            }
23
        } else {
24
            sbrec_dhcp_options_delete(opt_row);  /* Unknown option → delete */
25
        }
26
    }
27

28
    struct gen_opts_map *opt;
29
    HMAP_FOR_EACH (opt, hmap_node, &dhcp_opts_to_add) {
30
        struct sbrec_dhcp_options *sbrec_dhcp_option =
31
            sbrec_dhcp_options_insert(ovnsb_txn);
32
        sbrec_dhcp_options_set_name(sbrec_dhcp_option, opt->name);
33
        sbrec_dhcp_options_set_code(sbrec_dhcp_option, opt->code);
34
        sbrec_dhcp_options_set_type(sbrec_dhcp_option, opt->type);
35
    }
36

37
    hmap_destroy(&dhcp_opts_to_add);
38
}

the algorithm is straightforward:

build an hmap of all built-in options
walk existing SB rows — if an option matches (name + code + type), remove it from the “to add” map; if it mismatches or is unknown, delete it
insert any remaining options from the “to add” map as new SB rows

the SB schema for these tables (ovn/ovn-sb.ovsschema:305-328):

1
"DHCP_Options": {
2
    "columns": {
3
        "name": {"type": "string"},
4
        "code": {"type": {"key": {"type": "integer",
5
                                  "minInteger": 0, "maxInteger": 254}}},
6
        "type": {"type": {"key": {"type": "string",
7
            "enum": ["set", ["bool", "uint8", "uint16", "uint32",
8
                             "ipv4", "static_routes", "str",
9
                             "host_id", "domains"]]}}}},
10
    "isRoot": true},
11

12
"DHCPv6_Options": {
13
    "columns": {
14
        "name": {"type": "string"},
15
        "code": {"type": {"key": {"type": "integer",
16
                                  "minInteger": 0, "maxInteger": 254}}},
17
        "type": {"type": {"key": {"type": "string",
18
            "enum": ["set", ["ipv6", "str", "mac", "domain"]]}}}},
19
    "isRoot": true},

northd: generating logical flows for dhcp

this is where the real work happens. northd reads the DHCP configuration from the NB database and generates logical flows that will instruct ovn-controller how to handle DHCP packets.

pipeline stage architecture

DHCP-related pipeline stages are defined in ovn/northd/northd.h:548-605:

Logical Switch Ingress Pipeline:

Stage	Name	Purpose
28	`ls_in_dhcp_options`	Match DHCP packets, encode `put_dhcp_opts` action
29	`ls_in_dhcp_response`	If `put_dhcp_opts` succeeded, rewrite L2/L3 headers and output

Logical Router Ingress Pipeline (for DHCP Relay):

Stage	Name	Purpose
4	`lr_in_dhcp_relay_req`	Rewrite src/dst IPs, forward DHCP request to server
20	`lr_in_dhcp_relay_resp_chk`	Validate DHCP relay response from server
21	`lr_in_dhcp_relay_resp`	Rewrite headers and deliver response to client

register bits for DHCP state

the DHCP flow generation uses specific register bits to track state across pipeline stages (ovn/northd/northd.c:126,209-210,230):

1
#define REGBIT_DHCP_OPTS_RESULT   "reg0[3]"
2
#define REGBIT_DHCP_RELAY_REQ_CHK "reg9[7]"
3
#define REGBIT_DHCP_RELAY_RESP_CHK "reg9[8]"
4
#define REG_DHCP_RELAY_DIP_IPV4 "reg2"

reg0[3] (REGBIT_DHCP_OPTS_RESULT): Set to 1 by the put_dhcp_opts / put_dhcpv6_opts action if the option encoding succeeds. The next stage (ls_in_dhcp_response) checks this bit to decide whether to generate the response packet.
reg9[7] (REGBIT_DHCP_RELAY_REQ_CHK): Set by dhcp_relay_req_chk action on the router if the relay request is valid.
reg9[8] (REGBIT_DHCP_RELAY_RESP_CHK): Set by dhcp_relay_resp_chk action on the router if the relay response is valid.
reg2 (REG_DHCP_RELAY_DIP_IPV4): Stores the original destination IP from the relay response for matching in the next stage.

the entry point

the function build_lswitch_dhcp_options_and_response() (ovn/northd/northd.c:10958-11008) is called for each logical switch port during the build_ls_lflows() pass:

1
static void
2
build_lswitch_dhcp_options_and_response(struct ovn_port *op,
3
                                        struct lflow_table *lflows,
4
                                        const struct shash *meter_groups)
5
{
6
    ovs_assert(op->nbsp);
7
    if (!lsp_is_enabled(op->nbsp) || lsp_is_router(op->nbsp)) {
8
        return;
9
    }
10

11
    if (!op->nbsp->dhcpv4_options && !op->nbsp->dhcpv6_options) {
12
        return;
13
    }
14

15
    if (ls_dhcp_relay_port(op->od)) {
16
        /* Don't add DHCP server flows if DHCP Relay is enabled */
17
        return;
18
    }
19

20
    bool is_external = lsp_is_external(op->nbsp);
21
    if (is_external && (!ls_has_localnet_port(op->od) ||
22
                        !op->nbsp->ha_chassis_group)) {
23
        return;
24
    }
25

26
    for (size_t i = 0; i < op->n_lsp_addrs; i++) {
27
        build_dhcpv4_options_flows(op, &op->lsp_addrs[i], op,
28
                                   is_external, meter_groups,
29
                                   lflows, op->lflow_ref);
30
        build_dhcpv6_options_flows(op, &op->lsp_addrs[i], op,
31
                                   is_external, meter_groups,
32
                                   lflows, op->lflow_ref);
33
    }
34
}

three guards before any DHCP flows are generated:

the port must be enabled and not a router port
the port must have DHCP options configured (dhcpv4_options or dhcpv6_options)
DHCP relay must NOT be enabled on this switch (checked via ls_dhcp_relay_port())

the helper ls_dhcp_relay_port() (ovn/northd/northd.c:10079-10083) simply reads the other_config:dhcp_relay_port key:

1
static const char *
2
ls_dhcp_relay_port(const struct ovn_datapath *od)
3
{
4
    return smap_get(&od->nbs->other_config, "dhcp_relay_port");
5
}

building the DHCPv4 action string

the function build_dhcpv4_action() (ovn/northd/northd.c:5956-6040) constructs the action strings that will become logical flow actions:

1
static bool
2
build_dhcpv4_action(struct ovn_port *op, ovs_be32 offer_ip,
3
                    struct ds *options_action, struct ds *response_action,
4
                    struct ds *ipv4_addr_match)
5
{
6
    if (!op->nbsp->dhcpv4_options) {
7
        return false;
8
    }
9

10
    ovs_be32 host_ip, mask;
11
    char *error = ip_parse_masked(op->nbsp->dhcpv4_options->cidr, &host_ip,
12
                                  &mask);
13
    if (error || ((offer_ip ^ host_ip) & mask)) {
14
        free(error);
15
        return false;
16
    }
17

18
    const char *server_ip = smap_get(
19
        &op->nbsp->dhcpv4_options->options, "server_id");
20
    const char *server_mac = smap_get(
21
        &op->nbsp->dhcpv4_options->options, "server_mac");
22
    const char *lease_time = smap_get(
23
        &op->nbsp->dhcpv4_options->options, "lease_time");
24

25
    if (!(server_ip && server_mac && lease_time)) {
26
        return false;
27
    }
28
    /* ... */

three options are mandatory: server_id, server_mac, and lease_time. if any is missing, the function returns false and no DHCP flows are generated for this port. no server_mac? no DHCP. simple as that.

the function then builds two action strings:

the options action (executed in ls_in_dhcp_options):

1
    ds_put_format(options_action,
2
                  REGBIT_DHCP_OPTS_RESULT" = put_dhcp_opts(offerip = "
3
                  IP_FMT", ", IP_ARGS(offer_ip));
4
    /* ... sorted option encoding ... */
5
    ds_put_cstr(options_action, "); next;");

the response action (executed in ls_in_dhcp_response):

1
    ds_put_format(response_action, "eth.dst = eth.src; eth.src = %s; "
2
                  "ip4.src = %s; udp.src = 67; udp.dst = 68; "
3
                  "outport = inport; flags.loopback = 1; output;",
4
                  server_mac, server_ip);

the response action swaps MAC addresses (server MAC as src, client MAC as dst), sets the source IP to the server IP, swaps UDP ports (src=67, dst=68), and outputs the packet back out the ingress port with the loopback flag set.

the generated logical flows

the build_dhcpv4_options_flows() function (ovn/northd/northd.c:9900-9995) generates three flows per port:

Flow 1: DHCP options encoding (stage ls_in_dhcp_options, priority 100):

1
match: "inport == <port> && eth.src == <mac> &&
2
        (ip4.src == {<offer_ip>, 0.0.0.0}
3
         && ip4.dst == {<server_ip>, 255.255.255.255})
4
        && udp.src == 68 && udp.dst == 67"
5
action: "reg0[3] = put_dhcp_opts(offerip = <offer_ip>,
6
         netmask = <mask>, router = <router>, ...); next;"

this flow matches DHCP requests (DISCOVER/REQUEST) from the client. the match on ip4.src handles both initial requests (src=0.0.0.0) and renewals (src=offered IP). the match on ip4.dst handles both directed requests (dst=server_ip) and broadcasts (dst=255.255.255.255).

the flow also includes a CoPP meter reference via WITH_CTRL_METER(copp_meter_get(COPP_DHCPV4_OPTS, ...)) and a hint via WITH_HINT(&op->nbsp->dhcpv4_options->header_).

Flow 2: DHCP response generation (stage ls_in_dhcp_response, priority 100):

1
match: "inport == <port> && eth.src == <mac> &&
2
        ip4 && udp.src == 68 && udp.dst == 67
3
        && reg0[3]"
4
action: "eth.dst = eth.src; eth.src = <server_mac>;
5
         ip4.src = <server_ip>; udp.src = 67; udp.dst = 68;
6
         outport = inport; flags.loopback = 1; output;"

this flow fires only if reg0[3] (REGBIT_DHCP_OPTS_RESULT) was set to 1 by the previous stage — meaning the put_dhcp_opts action succeeded.

Flow 3: ACL bypass for DHCP replies (stage S_SWITCH_OUT_ACL_EVAL, priority 34000):

1
match: "outport == <port> && eth.src == <server_mac>
2
        && ip4.src == <server_ip> && udp && udp.src == 67
3
        && udp.dst == 68"
4
action: "reg1[0] = 1; next;"

this is a high-priority ACL flow that ensures DHCP replies from ovn-controller bypass any drop ACLs. it sets REGBIT_ACL_VERDICT_ALLOW (reg1[0]) to 1, allowing the packet to proceed through the ACL pipeline without being dropped. this is generated only for non-external ports.

the DHCPv6 equivalent (build_dhcpv6_options_flows, ovn/northd/northd.c:9997-10077) follows the same pattern but matches on multicast destination ff02::1:2 and UDP ports 546/547.

default flows

the function build_lswitch_dhcp_and_dns_defaults() (ovn/northd/northd.c:11016-11032) installs priority-0 default flows:

1
ovn_lflow_add(lflows, od, S_SWITCH_IN_DHCP_OPTIONS, 0, "1", "next;", lflow_ref);
2
ovn_lflow_add(lflows, od, S_SWITCH_IN_DHCP_RESPONSE, 0, "1", "next;", lflow_ref);

these ensure that non-DHCP packets pass through these stages without being dropped.

DHCP relay on the logical switch

when DHCP relay is enabled, the function build_lswitch_dhcp_relay_flows() (ovn/northd/northd.c:10085-10162) generates a flow at stage S_SWITCH_IN_L2_LKUP (priority 100) that redirects DHCP requests to the router port:

1
ds_put_format(
2
    match, "inport == %s && eth.src == %s && "
3
    "ip4.src == {0.0.0.0, %s/%u} && ip4.dst == 255.255.255.255 && "
4
    "udp.src == 68 && udp.dst == 67",
5
    op->json_key, op->lsp_addrs[0].ea_s,
6
    rp->lrp_networks.ipv4_addrs[0].network_s,
7
    rp->lrp_networks.ipv4_addrs[0].plen);
8
ds_put_format(actions,
9
              "eth.dst = %s; outport = %s; next; /* DHCP_RELAY_REQ */",
10
              rp->lrp_networks.ea_s, sp->json_key);

this rewrites the destination MAC to the router port’s MAC and outputs to the router port, effectively forwarding the DHCP request into the router pipeline.

DHCP relay on the logical router

the function build_dhcp_relay_flows_for_lrouter_port() (ovn/northd/northd.c:16815-16980) generates eight flows across three router stages. here’s the complete relay flow sequence:

request path (client → server):

Flow 1 (lr_in_ip_input, priority 110) — validate relay request:

1
match: "inport == <router_port> &&
2
        ip4.src == {0.0.0.0, <network>/<prefix>} &&
3
        ip4.dst == 255.255.255.255 &&
4
        ip.frag == 0 && udp.src == 68 && udp.dst == 67"
5
action: "reg9[7] = dhcp_relay_req_chk(<relay_ip>, <server_ip>); next;"

Flow 2 (lr_in_dhcp_relay_req, priority 100) — forward valid request:

1
match: "inport == <router_port> &&
2
        ip4.src == {0.0.0.0, <network>/<prefix>} &&
3
        ip4.dst == 255.255.255.255 &&
4
        udp.src == 68 && udp.dst == 67 &&
5
        reg9[7]"
6
action: "ip4.src = <relay_ip>; ip4.dst = <server_ip>;
7
         udp.src = 67; next;"

Flow 3 (lr_in_dhcp_relay_req, priority 1) — drop invalid request:

1
match: "inport == <router_port> &&
2
        ip4.src == {0.0.0.0, <network>/<prefix>} &&
3
        ip4.dst == 255.255.255.255 &&
4
        udp.src == 68 && udp.dst == 67 &&
5
        reg9[7] == 0"
6
action: "drop;"

response path (server → client):

Flow 4 (lr_in_ip_input, priority 110) — match non-fragmented response:

1
match: "ip4.src == <server_ip> && ip4.dst == <relay_ip> &&
2
        ip.frag == 0 && udp.src == 67 && udp.dst == 67"
3
action: "next;"

Flow 5 (lr_in_dhcp_relay_resp_chk, priority 100) — validate relay response:

1
match: "ip4.src == <server_ip> && ip4.dst == <relay_ip> &&
2
        udp.src == 67 && udp.dst == 67"
3
action: "reg2 = ip4.dst;
4
         reg9[8] = dhcp_relay_resp_chk(<relay_ip>, <server_ip>); next;"

Flow 6 (lr_in_dhcp_relay_resp, priority 100) — deliver valid response:

1
match: "ip4.src == <server_ip> &&
2
        reg2 == <relay_ip> &&
3
        udp.src == 67 && udp.dst == 67 &&
4
        reg9[8]"
5
action: "ip4.src = <relay_ip>; udp.dst = 68;
6
         outport = <router_port>; output;"

Flow 7 (lr_in_dhcp_relay_resp, priority 1) — drop invalid response:

1
match: "ip4.src == <server_ip> &&
2
        reg2 == <relay_ip> &&
3
        udp.src == 67 && udp.dst == 67 &&
4
        reg9[8] == 0"
5
action: "drop;"

Flow 8 — default passthrough for each relay stage (priority 0):

1
"1" → "next;"

the ovn action system: how put_dhcp_opts becomes openflow

the action opcodes

when northd generates a logical flow with put_dhcp_opts(...), this action must be encoded into an OpenFlow controller message. the action system defines five DHCP-related opcodes in ovn/include/ovn/actions.h:663-838:

Opcode	Purpose	Userdata Format
`ACTION_OPCODE_PUT_DHCP_OPTS`	DHCPv4 option encoding	OXM header + offset + offer_ip + DHCP options
`ACTION_OPCODE_PUT_DHCPV6_OPTS`	DHCPv6 option encoding	OXM header + offset + DHCPv6 options
`ACTION_OPCODE_DHCP6_SERVER`	DHCPv6 server-side handling	(actions in OF1.3 format)
`ACTION_OPCODE_DHCP_RELAY_REQ_CHK`	DHCP relay request validation	relay_ip + server_ip
`ACTION_OPCODE_DHCP_RELAY_RESP_CHK`	DHCP relay response validation	relay_ip + server_ip

each opcode is preceded by an action_header (ovn/include/ovn/actions.h:854-858):

1
struct action_header {
2
    ovs_be32 opcode;            /* One of ACTION_OPCODE_* */
3
    uint8_t pad[4];
4
};
5
BUILD_ASSERT_DECL(sizeof(struct action_header) == 8);

parsing DHCP actions

when ovn-controller processes a logical flow, it parses the action string via lflow_parse_actions() (ovn/controller/lflow.c:365-408):

1
static bool
2
lflow_parse_actions(const struct sbrec_logical_flow *lflow,
3
                    const struct lflow_ctx_in *l_ctx_in,
4
                    struct sset *template_vars_ref,
5
                    struct ofpbuf *ovnacts_out,
6
                    struct expr **prereqs_out)
7
{
8
    bool ingress = !strcmp(lflow->pipeline, "ingress");
9
    struct ovnact_parse_params pp = {
10
        .symtab = &symtab,
11
        .dhcp_opts = l_ctx_in->dhcp_opts,
12
        .dhcpv6_opts = l_ctx_in->dhcpv6_opts,
13
        .nd_ra_opts = l_ctx_in->nd_ra_opts,
14
        .controller_event_opts = l_ctx_in->controller_event_opts,
15
        .pipeline = ingress ? OVNACT_P_INGRESS : OVNACT_P_EGRESS,
16
        .n_tables = ingress ? LOG_PIPELINE_INGRESS_LEN : LOG_PIPELINE_EGRESS_LEN,
17
        .cur_ltable = lflow->table_id,
18
    };
19
    /* ... */
20
    char *error = ovnacts_parse_string(lex_str_get(&actions_s), &pp,
21
                                       ovnacts_out, prereqs_out);

the ovnact_parse_params struct (ovn/include/ovn/actions.h:860-898) carries dhcp_opts and dhcpv6_opts as const struct hmap * — these are the option definition maps loaded from the SB database. during parsing, when the parser encounters put_dhcp_opts(offerip = ..., netmask = ..., ...), it looks up each option name (like "netmask") in the dhcp_opts hmap to resolve its DHCP option code and type.

the parser entry point for put_dhcp_opts is in parse_set_action() (ovn/lib/actions.c:5920-5927):

1
} else if (!strcmp(ctx->lexer->token.s, "put_dhcp_opts")
2
           && lexer_lookahead(ctx->lexer) == LEX_T_LPAREN) {
3
    parse_put_dhcp_opts(ctx, &lhs, ovnact_put_PUT_DHCPV4_OPTS(
4
                                    ctx->ovnacts));
5
} else if (!strcmp(ctx->lexer->token.s, "put_dhcpv6_opts")
6
           && lexer_lookahead(ctx->lexer) == LEX_T_LPAREN) {
7
    parse_put_dhcp_opts(ctx, &lhs, ovnact_put_PUT_DHCPV6_OPTS(
8
                                    ctx->ovnacts));

the parse_put_dhcp_opts() function (ovn/lib/actions.c:2976-2995) selects the appropriate option map based on the action type:

1
static void
2
parse_put_dhcp_opts(struct action_context *ctx,
3
                    const struct expr_field *dst,
4
                    struct ovnact_put_opts *po)
5
{
6
    const struct hmap *dhcp_opts =
7
        (po->ovnact.type == OVNACT_PUT_DHCPV6_OPTS) ?
8
            ctx->pp->dhcpv6_opts : ctx->pp->dhcp_opts;
9
    const char *opts_type =
10
        (po->ovnact.type == OVNACT_PUT_DHCPV6_OPTS) ? "DHCPv6" : "DHCPv4";
11

12
    parse_put_opts(ctx, dst, po, dhcp_opts, opts_type);
13

14
    if (!ctx->lexer->error && po->ovnact.type == OVNACT_PUT_DHCPV4_OPTS
15
        && !find_opt(po->options, po->n_options, 0)) {
16
        lexer_error(ctx->lexer,
17
                    "put_dhcp_opts requires offerip to be specified.");
18
        return;
19
    }
20
}

critical validation: DHCPv4 put_dhcp_opts requires offerip (option code 0) to be present. without it, parsing fails. makes sense — what’s a DHCP offer without an IP to offer?

encoding DHCP actions into openflow

the struct ovnact_put_opts (ovn/include/ovn/actions.h:406-411) stores the parsed options:

1
struct ovnact_put_opts {
2
    struct ovnact ovnact;
3
    struct expr_field dst;      /* 1-bit destination field. */
4
    struct ovnact_gen_option *options;
5
    size_t n_options;
6
};

each option is an ovnact_gen_option (ovn/include/ovn/actions.h:400-403):

1
struct ovnact_gen_option {
2
    const struct gen_opts_map *option;
3
    struct expr_constant_set value;
4
};

the encoding function encode_PUT_DHCPV4_OPTS() (ovn/lib/actions.c:3228-3292) converts the parsed options into an OpenFlow controller message:

1
static void
2
encode_PUT_DHCPV4_OPTS(const struct ovnact_put_opts *pdo,
3
                       const struct ovnact_encode_params *ep,
4
                       struct ofpbuf *ofpacts)
5
{
6
    struct mf_subfield dst = expr_resolve_field(&pdo->dst);
7

8
    size_t oc_offset = encode_start_controller_op(ACTION_OPCODE_PUT_DHCP_OPTS,
9
                                                  true, ep->ctrl_meter_id,
10
                                                  ofpacts);
11
    nx_put_header(ofpacts, dst.field->id, OFP15_VERSION, false);
12
    ovs_be32 ofs = htonl(dst.ofs);
13
    ofpbuf_put(ofpacts, &ofs, sizeof ofs);
14

15
    /* Encode offerip first — it must be first in the DHCP response */
16
    const struct ovnact_gen_option *offerip_opt = find_opt(
17
        pdo->options, pdo->n_options, 0);
18
    const struct expr_constant *c =
19
        vector_get_ptr(&offerip_opt->value.values, 0);
20
    ovs_be32 offerip = c->value.ipv4;
21
    ofpbuf_put(ofpacts, &offerip, sizeof offerip);
22

23
    /* Encode bootfile_name (67), bootfile_name_alt (254), next_server (253)
24
     * in that specific order, then encode everything else */
25
    /* ... */
26

27
    for (size_t i = 0; i < pdo->n_options; i++) {
28
        const struct ovnact_gen_option *o = &pdo->options[i];
29
        if (o != offerip_opt && o != boot_opt && o != boot_alt_opt &&
30
            o != next_server_opt) {
31
            encode_put_dhcpv4_option(o, ofpacts);
32
        }
33
    }
34

35
    encode_finish_controller_op(oc_offset, ofpacts);
36
}

the encoding order matters:

Offer IP (always first)
bootfile_name (option 67) — for PXE/iPXE boot
bootfile_name_alt (option 254) — iPXE alternate bootfile
next_server (option 253) — TFTP server address
All other options — in the order they were defined

the final controller message format is:

1
[action_header: 8 bytes (opcode=PUT_DHCP_OPTS + padding)]
2
[OXM header: 4-8 bytes (field MFF_REG0, offset 3)]
3
[offer_ip: 4 bytes]
4
[DHCP option: code + len + value]
5
[DHCP option: code + len + value]
6
...

option encoding by type

the function encode_put_dhcpv4_option() (ovn/lib/actions.c:3026-3192) handles each option type differently:

1
static void
2
encode_put_dhcpv4_option(const struct ovnact_gen_option *o,
3
                         struct ofpbuf *ofpacts)
4
{
5
    uint8_t *opt_header = ofpbuf_put_zeros(ofpacts, 2);
6
    opt_header[0] = o->option->code;
7

8
    const struct expr_constant *c = vector_get_ptr(&o->value.values, 0);
9
    size_t n_values = vector_len(&o->value.values);
10
    if (!strcmp(o->option->type, "bool") ||
11
        !strcmp(o->option->type, "uint8")) {
12
        opt_header[1] = 1;
13
        ofpbuf_put(ofpacts, &c->value.u8_val, 1);
14
    } else if (!strcmp(o->option->type, "uint16")) {
15
        opt_header[1] = 2;
16
        ofpbuf_put(ofpacts, &c->value.be16_int, 2);
17
    } else if (!strcmp(o->option->type, "uint32")) {
18
        opt_header[1] = 4;
19
        ofpbuf_put(ofpacts, &c->value.be32_int, 4);
20
    } else if (!strcmp(o->option->type, "ipv4")) {
21
        opt_header[1] = n_values * sizeof(ovs_be32);
22
        for (size_t i = 0; i < n_values; i++) {
23
            ofpbuf_put(ofpacts, &c[i].value.ipv4, sizeof(ovs_be32));
24
        }
25
    } else if (!strcmp(o->option->type, "static_routes")) {
26
        /* RFC 3442 classless static route encoding */
27
        /* ... complex encoding with plen + destination + router ... */
28
    } else if (!strcmp(o->option->type, "str")) {
29
        opt_header[1] = strlen(c->string);
30
        ofpbuf_put(ofpacts, c->string, opt_header[1]);
31
    } else if (!strcmp(o->option->type, "host_id")) {
32
        /* Can be string or IPv4 */
33
        if (o->value.type == EXPR_C_STRING) {
34
            opt_header[1] = strlen(c->string);
35
            ofpbuf_put(ofpacts, c->string, opt_header[1]);
36
        } else {
37
            opt_header[1] = sizeof(ovs_be32);
38
            ofpbuf_put(ofpacts, &c->value.ipv4, sizeof(ovs_be32));
39
        }
40
    } else if (!strcmp(o->option->type, "domains")) {
41
        /* RFC 1035 DNS-encoded domain search list with compression pointers */
42
        /* ... complex encoding ... */
43
    }
44
}

the static_routes type deserves special attention — it encodes according to RFC 3442, with variable-length destination descriptors:

1
Destination descriptor examples:
2
  0              → 0 (default route)
3
  10.0.0.0/8     → 8.10
4
  10.0.0.0/24    → 24.10.0.0
5
  10.229.0.128/25 → 25.10.229.0.128

the domains type encodes domain search lists using RFC 1035 label compression, where shared suffixes are replaced with two-byte pointers (0xC0xx) to avoid duplication.

DHCPv6 option encoding

the DHCPv6 encoding function encode_put_dhcpv6_option() (ovn/lib/actions.c:3194-3226) is simpler:

1
static void
2
encode_put_dhcpv6_option(const struct ovnact_gen_option *o,
3
                         struct ofpbuf *ofpacts)
4
{
5
    struct dhcpv6_opt_header *opt = ofpbuf_put_uninit(ofpacts, sizeof *opt);
6
    const struct expr_constant *c = vector_get_ptr(&o->value.values, 0);
7
    size_t n_values = vector_len(&o->value.values);
8
    size_t size;
9

10
    opt->code = htons(o->option->code);
11

12
    if (!strcmp(o->option->type, "ipv6")) {
13
        size = n_values * sizeof(struct in6_addr);
14
        opt->len = htons(size);
15
        for (size_t i = 0; i < n_values; i++) {
16
            ofpbuf_put(ofpacts, &c[i].value.ipv6, sizeof(struct in6_addr));
17
        }
18
    } else if (!strcmp(o->option->type, "mac")) {
19
        size = sizeof(struct eth_addr);
20
        opt->len = htons(size);
21
        ofpbuf_put(ofpacts, &c->value.mac, size);
22
    } else if (!strcmp(o->option->type, "str")) {
23
        size = strlen(c->string);
24
        opt->len = htons(size);
25
        ofpbuf_put(ofpacts, c->string, size);
26
    } else if (!strcmp(o->option->type, "domain")) {
27
        char *encoded = encode_fqdn_string(c->string, &size);
28
        opt->len = htons(size);
29
        ofpbuf_put(ofpacts, encoded, size);
30
        free(encoded);
31
    }
32
}

DHCPv6 option headers use 16-bit code and length fields (vs. 8-bit for DHCPv4).

DHCP relay action encoding

the encode_dhcpv4_relay_chk() function (ovn/lib/actions.c:2883-2901) encodes the relay check action:

1
static void
2
encode_dhcpv4_relay_chk(const struct ovnact_dhcp_relay *dhcp_relay,
3
                        const struct ovnact_encode_params *ep,
4
                        struct ofpbuf *ofpacts,
5
                        enum action_opcode dhcp_relay_opcode)
6
{
7
    struct mf_subfield dst = expr_resolve_field(&dhcp_relay->dst);
8
    size_t oc_offset = encode_start_controller_op(dhcp_relay_opcode, true,
9
                                                  ep->ctrl_meter_id,
10
                                                  ofpacts);
11
    nx_put_header(ofpacts, dst.field->id, OFP15_VERSION, false);
12
    ovs_be32 ofs = htonl(dst.ofs);
13
    ofpbuf_put(ofpacts, &ofs, sizeof ofs);
14
    ofpbuf_put(ofpacts, &dhcp_relay->relay_ipv4,
15
               sizeof(dhcp_relay->relay_ipv4));
16
    ofpbuf_put(ofpacts, &dhcp_relay->server_ipv4,
17
               sizeof(dhcp_relay->server_ipv4));
18
    encode_finish_controller_op(oc_offset, ofpacts);
19
}

the userdata contains: the result field (OXM header + offset), the 32-bit relay IP, and the 32-bit server IP.

ovn controller: reading dhcp options from sb

the engine node

OVN controller uses an incremental processing engine. the dhcp_options engine node (ovn/controller/ovn-controller.c:3811-3862) reads the SB DHCP option tables:

1
struct ed_type_dhcp_options {
2
    struct hmap v4_opts;
3
    struct hmap v6_opts;
4
};
5

6
static enum engine_node_state
7
en_dhcp_options_run(struct engine_node *node, void *data)
8
{
9
    struct ed_type_dhcp_options *dhcp_opts = data;
10

11
    const struct sbrec_dhcp_options_table *dhcp_table =
12
        EN_OVSDB_GET(engine_get_input("SB_dhcp_options", node));
13

14
    const struct sbrec_dhcpv6_options_table *dhcpv6_table =
15
        EN_OVSDB_GET(engine_get_input("SB_dhcpv6_options", node));
16

17
    dhcp_opts_clear(&dhcp_opts->v4_opts);
18
    dhcp_opts_clear(&dhcp_opts->v6_opts);
19

20
    const struct sbrec_dhcp_options *dhcp_opt_row;
21
    SBREC_DHCP_OPTIONS_TABLE_FOR_EACH (dhcp_opt_row, dhcp_table) {
22
        dhcp_opt_add(&dhcp_opts->v4_opts, dhcp_opt_row->name,
23
                     dhcp_opt_row->code, dhcp_opt_row->type);
24
    }
25

26
    const struct sbrec_dhcpv6_options *dhcpv6_opt_row;
27
    SBREC_DHCPV6_OPTIONS_TABLE_FOR_EACH (dhcpv6_opt_row, dhcpv6_table) {
28
        dhcp_opt_add(&dhcp_opts->v6_opts, dhcpv6_opt_row->name,
29
                     dhcpv6_opt_row->code, dhcpv6_opt_row->type);
30
    }
31
    return EN_UPDATED;
32
}

the engine graph connections (ovn/controller/ovn-controller.c:7075-7078):

1
engine_add_input(&en_dhcp_options, &en_sb_dhcp_options, NULL);
2
engine_add_input(&en_dhcp_options, &en_sb_dhcpv6_options, NULL);
3
engine_add_input(&en_lflow_output, &en_dhcp_options, NULL);

1
en_sb_dhcp_options  ──→ en_dhcp_options ──→ en_lflow_output
2
en_sb_dhcpv6_options ─┘

the NULL handler means any change in either SB table triggers a full recompute.

feeding into logical flow processing

the init_lflow_ctx() function (ovn/controller/ovn-controller.c:3995-4035) passes the DHCP option maps into the logical flow context:

1
struct ed_type_dhcp_options *dhcp_opts =
2
    engine_get_input_data("dhcp_options", node);
3
/* ... */
4
l_ctx_in->dhcp_opts = &dhcp_opts->v4_opts;
5
l_ctx_in->dhcpv6_opts = &dhcp_opts->v6_opts;

these maps flow into ovnact_parse_params during action parsing, allowing the parser to resolve option names to codes.

ovn controller pinctrl: handling dhcp packet-ins

this is where the rubber meets the road. when a DHCP packet matches a logical flow with a put_dhcp_opts action, the packet is sent to ovn-controller as a packet-in. the pinctrl module handles it.

the dispatch table

the function process_packet_in() (ovn/controller/pinctrl.c:3746-3919) is the central dispatcher. it reads the opcode from the packet-in userdata and dispatches to the appropriate handler:

1
switch (ntohl(ah->opcode)) {
2
    /* ... */
3
    case ACTION_OPCODE_DHCP_RELAY_REQ_CHK:
4
        pinctrl_handle_dhcp_relay_req_chk(swconn, &packet, &pin,
5
                                          &userdata, &continuation);
6
        break;
7

8
    case ACTION_OPCODE_DHCP_RELAY_RESP_CHK:
9
        pinctrl_handle_dhcp_relay_resp_chk(swconn, &packet, &pin,
10
                                           &userdata, &continuation);
11
        break;
12

13
    case ACTION_OPCODE_PUT_DHCP_OPTS:
14
        pinctrl_handle_put_dhcp_opts(swconn, &packet, &pin, &headers,
15
                                     &userdata, &continuation);
16
        break;
17

18
    case ACTION_OPCODE_PUT_DHCPV6_OPTS:
19
        pinctrl_handle_put_dhcpv6_opts(swconn, &packet, &pin, &userdata,
20
                                       &continuation);
21
        break;
22

23
    case ACTION_OPCODE_DHCP6_SERVER:
24
        ovs_mutex_lock(&pinctrl_mutex);
25
        pinctrl_handle_dhcp6_server(swconn, &headers, &packet,
26
                                    &pin.flow_metadata);
27
        ovs_mutex_unlock(&pinctrl_mutex);
28
        break;
29
    /* ... */
30
}

DHCP packet validation: dhcp_get_hdr_from_pkt

before handling any DHCP packet, the function dhcp_get_hdr_from_pkt() (ovn/controller/pinctrl.c:2112-2168) validates the packet structure:

1
static const struct dhcp_header *
2
dhcp_get_hdr_from_pkt(struct dp_packet *pkt_in, const char **in_dhcp_pptr,
3
                      const char *end)
4
{
5
    *in_dhcp_pptr = dp_packet_get_udp_payload(pkt_in);
6
    if (*in_dhcp_pptr == NULL) {
7
        VLOG_WARN_RL(&rl, "DHCP: Invalid or incomplete DHCP packet received");
8
        return NULL;
9
    }
10

11
    const struct dhcp_header *dhcp_hdr
12
        = (const struct dhcp_header *) *in_dhcp_pptr;
13
    (*in_dhcp_pptr) += sizeof *dhcp_hdr;
14
    if (*in_dhcp_pptr > end) {
15
        VLOG_WARN_RL(&rl, "DHCP: Invalid or incomplete DHCP packet received, "
16
                     "bad data length");
17
        return NULL;
18
    }
19

20
    if (dhcp_hdr->htype != 0x1) {
21
        VLOG_WARN_RL(&rl, "DHCP: Packet is recieved with "
22
                     "unsupported hardware type");
23
        return NULL;
24
    }
25

26
    if (dhcp_hdr->hlen != 0x6) {
27
        VLOG_WARN_RL(&rl, "DHCP: Packet is recieved with "
28
                     "unsupported hardware length");
29
        return NULL;
30
    }
31

32
    ovs_be32 magic_cookie = htonl(DHCP_MAGIC_COOKIE);
33
    if ((*in_dhcp_pptr) + sizeof magic_cookie > end ||
34
        get_unaligned_be32((const void *) (*in_dhcp_pptr)) != magic_cookie) {
35
        VLOG_WARN_RL(&rl, "DHCP: Magic cookie not present in the DHCP packet");
36
        return NULL;
37
    }
38

39
    (*in_dhcp_pptr) += sizeof magic_cookie;
40
    return dhcp_hdr;
41
}

validation checks:

UDP payload must exist
DHCP header must fit within the packet
Hardware type must be Ethernet (0x1)
Hardware length must be 6 (0x6, ETH_ADDR_LEN)
Magic cookie (0x63825363) must be present after the header

DHCP option parsing: dhcp_parse_options

the function dhcp_parse_options() (ovn/controller/pinctrl.c:2180-2243) walks the DHCP options area and extracts the fields needed for decision-making:

1
struct parsed_dhcp_options {
2
    uint8_t dhcp_msg_type;
3
    ovs_be32 request_ip;
4
    ovs_be32 server_id;
5
    ovs_be32 netmask;
6
    ovs_be32 router_ip;
7
    bool ipxe_req;
8
};
9

10
static struct parsed_dhcp_options
11
dhcp_parse_options(const char **in_dhcp_pptr, const char *end)
12
{
13
    struct parsed_dhcp_options parsed_dhcp_opts = {0};
14
    while ((*in_dhcp_pptr) < end) {
15
        const struct dhcp_opt_header *in_dhcp_opt =
16
            (const struct dhcp_opt_header *) *in_dhcp_pptr;
17
        if (in_dhcp_opt->code == DHCP_OPT_END) {
18
            break;
19
        }
20
        if (in_dhcp_opt->code == DHCP_OPT_PAD) {
21
            (*in_dhcp_pptr) += 1;
22
            continue;
23
        }
24
        (*in_dhcp_pptr) += sizeof *in_dhcp_opt;
25
        if ((*in_dhcp_pptr) > end) {
26
            break;
27
        }
28
        (*in_dhcp_pptr) += in_dhcp_opt->len;
29
        if ((*in_dhcp_pptr) > end) {
30
            break;
31
        }
32

33
        switch (in_dhcp_opt->code) {
34
        case DHCP_OPT_MSG_TYPE:    /* code 53 */
35
            if (in_dhcp_opt->len == 1) {
36
                const uint8_t *dhcp_msg_type = DHCP_OPT_PAYLOAD(in_dhcp_opt);
37
                parsed_dhcp_opts.dhcp_msg_type = *dhcp_msg_type;
38
            }
39
            break;
40
        case DHCP_OPT_REQ_IP:      /* code 50 */
41
            if (in_dhcp_opt->len == 4) {
42
                parsed_dhcp_opts.request_ip = get_unaligned_be32(
43
                    DHCP_OPT_PAYLOAD(in_dhcp_opt));
44
            }
45
            break;
46
        case OVN_DHCP_OPT_CODE_SERVER_ID:  /* code 54 */
47
            if (in_dhcp_opt->len == 4) {
48
                parsed_dhcp_opts.server_id = get_unaligned_be32(
49
                    DHCP_OPT_PAYLOAD(in_dhcp_opt));
50
            }
51
            break;
52
        case OVN_DHCP_OPT_CODE_NETMASK:    /* code 1 */
53
            if (in_dhcp_opt->len == 4) {
54
                parsed_dhcp_opts.netmask = get_unaligned_be32(
55
                    DHCP_OPT_PAYLOAD(in_dhcp_opt));
56
            }
57
            break;
58
        case OVN_DHCP_OPT_CODE_ROUTER_IP:  /* code 3 */
59
            if (in_dhcp_opt->len == 4) {
60
                parsed_dhcp_opts.router_ip = get_unaligned_be32(
61
                    DHCP_OPT_PAYLOAD(in_dhcp_opt));
62
            }
63
            break;
64
        case DHCP_OPT_ETHERBOOT:   /* code 175 */
65
            parsed_dhcp_opts.ipxe_req = true;
66
            break;
67
        default:
68
            break;
69
        }
70
    }
71
    return parsed_dhcp_opts;
72
}

the parser specifically extracts six fields because they’re needed for validation and decision-making downstream: message type, requested IP, server ID, netmask, router IP, and iPXE request flag.

DHCPv4: building the response packet

the function pinctrl_handle_put_dhcp_opts() (ovn/controller/pinctrl.c:2604-2944) is the core DHCPv4 handler — 340 lines of packet construction. i read every single one of them. here’s the control flow:

step 1: parse userdata

1
const struct mf_field *f;
2
enum ofperr ofperr = nx_pull_header(userdata, NULL, &f, NULL);
3
/* ... */
4
ovs_be32 *ofsp = ofpbuf_try_pull(userdata, sizeof *ofsp);
5
ovs_be32 *offer_ip = ofpbuf_try_pull(userdata, sizeof *offer_ip);

the userdata contains the result field (where to write success/failure), the offer IP, and the encoded DHCP options.

step 2: parse the incoming DHCP packet

1
const struct dhcp_header *in_dhcp_data =
2
    dhcp_get_hdr_from_pkt(pkt_in, &in_dhcp_ptr, end);
3

4
if (in_dhcp_data->op != DHCP_OP_REQUEST) {
5
    VLOG_WARN_RL(&rl, "Invalid opcode in the DHCP packet: %d",
6
                 in_dhcp_data->op);
7
    goto exit;
8
}
9

10
struct parsed_dhcp_options dhcp_opts = dhcp_parse_options(&in_dhcp_ptr, end);
11
if (!dhcp_opts.request_ip) {
12
    dhcp_opts.request_ip = in_dhcp_data->ciaddr;
13
}

if the requested IP (option 50) is not present, the handler falls back to ciaddr from the DHCP header.

step 3: determine response type

1
switch (dhcp_opts.dhcp_msg_type) {
2
case DHCP_MSG_DISCOVER:
3
    msg_type = DHCP_MSG_OFFER;
4
    break;
5
case DHCP_MSG_REQUEST: {
6
    msg_type = DHCP_MSG_ACK;
7
    if (dhcp_opts.request_ip != *offer_ip) {
8
        msg_type = DHCP_MSG_NAK;
9
    }
10
    break;
11
}
12
case OVN_DHCP_MSG_RELEASE:
13
    /* Just log it */
14
    break;
15
case OVN_DHCP_MSG_INFORM: {
16
    msg_type = DHCP_MSG_ACK;
17
    /* Strip lease/netmask/T1/T2 options from reply */
18
    break;
19
}
20
case OVN_DHCP_MSG_DECLINE:
21
    /* Log and exit */
22
    goto exit;
23
}

the DISCOVER→OFFER mapping is straightforward. for REQUEST, the handler validates that the requested IP matches the offer IP — if not, it sends a NAK. for INFORM (RFC 2131 section 3.4), the handler strips time-lease and netmask options from the reply.

step 4: handle iPXE bootfile selection

the handler processes the bootfile options with iPXE awareness:

1
case DHCP_OPT_BOOTFILE_CODE:
2
    /* Check if bootfile_name_alt (254) follows */
3
    if (next_dhcp_opt->code == DHCP_OPT_BOOTFILE_ALT_CODE) {
4
        if (!dhcp_opts.ipxe_req) {
5
            /* Not iPXE: skip alt, use standard bootfile */
6
            ofpbuf_pull(reply_dhcp_opts_ptr, len);
7
            next_dhcp_opt->code = DHCP_OPT_BOOTFILE_CODE;
8
        } else {
9
            /* iPXE: use alt bootfile, skip standard */
10
            /* ... swap logic ... */
11
        }
12
    }

step 5: construct the reply packet

1
uint16_t new_l4_size = UDP_HEADER_LEN + DHCP_HEADER_LEN + 16;
2
if (msg_type != DHCP_MSG_NAK) {
3
    new_l4_size += reply_dhcp_opts_ptr->size;
4
}
5

6
struct dp_packet pkt_out;
7
dp_packet_init(&pkt_out, new_packet_size);
8

9
/* Copy L2 and L3 headers from pkt_in */
10
dp_packet_put(&pkt_out, dp_packet_pull(pkt_in, pkt_in->l4_ofs), pkt_in->l4_ofs);
11

12
struct udp_header *udp = dp_packet_put(
13
    &pkt_out, dp_packet_pull(pkt_in, UDP_HEADER_LEN), UDP_HEADER_LEN);
14

15
struct dhcp_header *dhcp_data = dp_packet_put(
16
    &pkt_out, dp_packet_pull(pkt_in, DHCP_HEADER_LEN), DHCP_HEADER_LEN);
17
dhcp_data->op = DHCP_OP_REPLY;
18

19
if (dhcp_opts.dhcp_msg_type != OVN_DHCP_MSG_INFORM) {
20
    dhcp_data->yiaddr = (msg_type == DHCP_MSG_NAK) ? 0 : *offer_ip;
21
    dhcp_data->siaddr = (msg_type == DHCP_MSG_NAK) ? 0 : next_server;
22
}

the reply packet structure is:

1
┌──────────────────────────────────────────────────────────────┐
2
│ L2 Header (copied from request)                              │
3
├──────────────────────────────────────────────────────────────┤
4
│ L3 Header (copied, with ip_dst updated)                      │
5
├──────────────────────────────────────────────────────────────┤
6
│ UDP Header (src=67, dst=68)                                  │
7
├──────────────────────────────────────────────────────────────┤
8
│ DHCP Header (op=REPLY, yiaddr=offer_ip, siaddr=next_server) │
9
├──────────────────────────────────────────────────────────────┤
10
│ Magic Cookie (0x63825363)                                    │
11
├──────────────────────────────────────────────────────────────┤
12
│ Option 53: Message Type (OFFER/ACK/NAK)                      │
13
├──────────────────────────────────────────────────────────────┤
14
│ [Encoded DHCP options from userdata]                         │
15
├──────────────────────────────────────────────────────────────┤
16
│ 4 bytes padding + Option END (0xFF)                          │
17
└──────────────────────────────────────────────────────────────┘

step 6: handle broadcast flag

1
ovs_be32 ip_dst;
2
if (!is_dhcp_flags_broadcast(dhcp_data->flags)) {
3
    ip_dst = *offer_ip;
4
} else {
5
    ip_dst = htonl(0xffffffff);
6
}
7
put_16aligned_be32(&out_ip->ip_dst, ip_dst);

if the client set the broadcast flag, the response is sent as a broadcast (255.255.255.255); otherwise, it’s unicast to the offered IP.

step 7: set success and resume the pipeline

1
success = 1;
2
exit:
3
    if (!ofperr) {
4
        union mf_subvalue sv;
5
        sv.u8_val = success;
6
        mf_write_subfield(&dst, &sv, &pin->flow_metadata);
7
    }
8
    queue_msg(swconn, ofputil_encode_resume(pin, continuation, proto));

the handler writes 1 (success) or 0 (failure) into reg0[3] via the mf_write_subfield call, then resumes the logical pipeline with the modified packet.

finally-done-with-this-handler

DHCPv6: building the response packet

the function pinctrl_handle_put_dhcpv6_opts() (ovn/controller/pinctrl.c:3138-3364) follows a similar pattern but for DHCPv6:

message type mapping:

1
switch (hdr->msg_type) {
2
case DHCPV6_MSG_TYPE_SOLICIT:
3
    out_dhcpv6_msg_type = DHCPV6_MSG_TYPE_ADVT;
4
    break;
5
case DHCPV6_MSG_TYPE_REQUEST:
6
case DHCPV6_MSG_TYPE_CONFIRM:
7
case DHCPV6_MSG_TYPE_DECLINE:
8
case DHCPV6_MSG_TYPE_INFO_REQ:
9
    out_dhcpv6_msg_type = DHCPV6_MSG_TYPE_REPLY;
10
    break;
11
case DHCPV6_MSG_TYPE_RELEASE:
12
    out_dhcpv6_msg_type = DHCPV6_MSG_TYPE_REPLY;
13
    status_only = true;
14
    break;
15
}

parsing client options:

the handler extracts IA_NA (for IAID), Client ID, User Class (for iPXE detection), and FQDN flags from the client’s packet:

1
for (in_opt = next_dhcpv6_opt(DHCPV6_PAYLOAD(hdr), opts_len, &len, &opt_len);
2
     in_opt;
3
     in_opt = next_dhcpv6_opt(DHCPV6_PAYLOAD(hdr), opts_len, &len, &opt_len)) {
4
    switch (ntohs(in_opt->code)) {
5
    case DHCPV6_OPT_IA_NA_CODE:
6
        iaid = opt_ia_na->iaid;
7
        break;
8
    case DHCPV6_OPT_CLIENT_ID_CODE:
9
        in_opt_client_id = in_opt;
10
        break;
11
    case DHCPV6_OPT_USER_CLASS:
12
        if (!strncmp(user_class + DHCPV6_UC_PXE_OFFSET, "iPXE", 4)) {
13
            ipxe_req = true;
14
        }
15
        break;
16
    case DHCPV6_OPT_FQDN_CODE:
17
        fqdn_flags = *(uint8_t *) DHCPV6_OPT_PAYLOAD(in_opt);
18
        break;
19
    }
20
}

composing the response:

the handler delegates option composition to compose_out_dhcpv6_opts() (ovn/controller/pinctrl.c:2967-3098), which processes each option from the userdata:

Server ID (code 2): Re-encoded with encode_dhcpv6_server_id_opt()
IA Address (code 5): Wrapped in an IA_NA option with the client’s IAID, T1=T2=infinity
DNS Server (code 23): Copied with header
Domain Search (code 24): Copied with length prefix
Boot File URL (code 59/254): Conditionally included based on iPXE detection
FQDN (code 39): Flags always include N=1 (server-managed); if client sent S, O is also set

packet construction:

1
uint16_t new_l4_size
2
    = (UDP_HEADER_LEN + 4 + sizeof *in_opt_client_id +
3
       ntohs(in_opt_client_id->len) + out_dhcpv6_opts.size);
4

5
struct dp_packet pkt_out;
6
/* Copy L2/L3 from pkt_in */
7
/* Copy UDP header and DHCPv6 header (preserving transaction ID) */
8

9
*out_dhcpv6 = out_dhcpv6_msg_type;  /* Set message type */
10

11
/* Copy Client Identifier */
12
dp_packet_put(&pkt_out, in_opt_client_id,
13
              sizeof *in_opt_client_id + ntohs(in_opt_client_id->len));
14

15
/* Copy composed options */
16
dp_packet_put(&pkt_out, out_dhcpv6_opts.data, out_dhcpv6_opts.size);
17

18
/* Compute UDP checksum */
19
uint32_t csum = packet_csum_pseudoheader6(dp_packet_l3(&pkt_out));
20
csum = csum_continue(csum, out_udp, dp_packet_size(&pkt_out) - ...);
21
out_udp->udp_csum = csum_finish(csum);

DHCPv6 prefix delegation handling

the function pinctrl_handle_dhcp6_server() (ovn/controller/pinctrl.c:1155-1184) handles DHCPv6 server-side messages (Advertisements and Replies) for prefix delegation:

1
static void
2
pinctrl_handle_dhcp6_server(struct rconn *swconn, const struct flow *ip_flow,
3
                            struct dp_packet *pkt_in, const struct match *md)
4
{
5
    if (ip_flow->dl_type != htons(ETH_TYPE_IPV6) ||
6
        ip_flow->nw_proto != IPPROTO_UDP) {
7
        return;
8
    }
9

10
    struct udp_header *udp_in = dp_packet_l4(pkt_in);
11
    size_t dlen = MIN(ntohs(udp_in->udp_len), dp_packet_l4_size(pkt_in));
12
    if (dlen < UDP_HEADER_LEN + DHCPV6_HEADER_LEN) {
13
        return;
14
    }
15

16
    const struct dhcpv6_header *hdr = dp_packet_get_udp_payload(pkt_in);
17
    switch (hdr->msg_type) {
18
    case DHCPV6_MSG_TYPE_ADVT:
19
        pinctrl_parse_dhcpv6_advt(swconn, ip_flow, DHCPV6_PAYLOAD(hdr),
20
                                  opts_len, md);
21
        break;
22
    case DHCPV6_MSG_TYPE_REPLY:
23
        pinctrl_parse_dhcpv6_reply(DHCPV6_PAYLOAD(hdr), opts_len, ip_flow);
24
        break;
25
    }
26
}

for Advertisements, pinctrl_parse_dhcpv6_advt() (ovn/controller/pinctrl.c:908-1053) extracts IA_PD options with prefix delegation info and constructs a DHCPv6 Request packet to send back to the server:

1
eth_compose(&packet, (struct eth_addr) ETH_ADDR_C(33,33,00,01,00,02),
2
            ip_flow->dl_dst, ETH_TYPE_IPV6, IPV6_HEADER_LEN);
3

4
struct udp_header *udp_h = compose_ipv6(&packet, IPPROTO_UDP,
5
                                        &ip_flow->ipv6_dst,
6
                                        &in6addr_all_dhcp_agents,
7
                                        0, 0, 255,
8
                                        data_len + UDP_HEADER_LEN + 4);
9
/* ... */
10
unsigned char *dhcp_hdr = (unsigned char *)(udp_h + 1);
11
*dhcp_hdr = DHCPV6_MSG_TYPE_REQUEST;
12
memcpy(dhcp_hdr + 4, data, data_len);

DHCP relay: request validation

the function pinctrl_handle_dhcp_relay_req_chk() (ovn/controller/pinctrl.c:2245-2388) validates and modifies incoming DHCP relay requests:

validation checks (in order):

Parse the result field from userdata
Parse relay_ip and server_ip from userdata
Validate DHCP packet structure via dhcp_get_hdr_from_pkt()
Verify op == DHCP_OP_REQUEST (opcode must be 1)
Verify giaddr == 0 (relay agent IP must not already be set)
Parse DHCP options and verify message type is present
If request_ip is not in option 50, fall back to ciaddr

packet modification:

1
uint8_t hops = dhcp_data->hops + 1;
2
if (udp->udp_csum) {
3
    udp->udp_csum = recalc_csum16(udp->udp_csum,
4
        htons((uint16_t) dhcp_data->hops), htons((uint16_t) hops));
5
}
6
dhcp_data->hops = hops;
7

8
dhcp_data->giaddr = *relay_ip;
9
if (udp->udp_csum) {
10
    udp->udp_csum = recalc_csum32(udp->udp_csum,
11
        0, dhcp_data->giaddr);
12
}

the handler increments the hop count and sets giaddr (gateway IP address) to the relay IP. UDP checksums are incrementally updated for both changes.

DHCP relay: response validation

the function pinctrl_handle_dhcp_relay_resp_chk() (ovn/controller/pinctrl.c:2390-2600) validates incoming DHCP relay responses with extensive security checks:

validation checks (in order):

Parse result field, relay_ip, server_ip from userdata
Validate DHCP packet structure
Verify op == DHCP_OP_REPLY (opcode must be 2)
Verify giaddr != 0 (must be set in the relay request)
Verify giaddr == relay_ip (giaddr must match the relay’s IP)
Parse DHCP options and verify message type is present
Verify server_id (option 54) is present
Verify server_id == server_ip (server identifier must match configured server)
For OFFER/ACK messages: verify (yiaddr & netmask) == (giaddr & netmask) — allocated IP must be in the same subnet as the relay
For OFFER/ACK messages: if router_ip is present, log a warning if router_ip != giaddr (but continue processing)

packet modification for delivery:

1
memcpy(&eth->eth_dst, dhcp_data->chaddr, sizeof(eth->eth_dst));
2

3
/* Handle broadcast flag */
4
ovs_be32 ip_dst;
5
if (!is_dhcp_flags_broadcast(dhcp_data->flags)) {
6
    ip_dst = dhcp_data->yiaddr;
7
} else {
8
    ip_dst = htonl(0xffffffff);
9
}
10
put_16aligned_be32(&out_ip->ip_dst, ip_dst);
11
out_ip->ip_csum = recalc_csum32(out_ip->ip_csum, ip_dst_orig, ip_dst);

the destination MAC is set to the client’s hardware address (from chaddr), and the destination IP is set to either the client’s IP or broadcast, depending on the BROADCAST flag.

ovs in-band: making sure dhcp actually works

OVS has an in-band control mechanism that ensures management traffic isn’t blocked by flow tables. this includes DHCP traffic from the local management port.

the DHCP output check

the function in_band_must_output_to_local_port() (ovs/ofproto/in-band.c:233-243) checks if a packet is a DHCP reply that must reach the local port:

1
bool
2
in_band_must_output_to_local_port(const struct flow *flow)
3
{
4
    return (flow->dl_type == htons(ETH_TYPE_IP)
5
            && flow->nw_proto == IPPROTO_UDP
6
            && flow->tp_src == htons(DHCP_SERVER_PORT)
7
            && flow->tp_dst == htons(DHCP_CLIENT_PORT));
8
}

this matches UDP from port 67 (server) to port 68 (client) — i.e., DHCP replies from a DHCP server running on the local OVS bridge.

the DHCP request rule

in update_rules() (ovs/ofproto/in-band.c:286-295), a rule is created to allow DHCP requests from the local port:

1
if (ib->n_remotes && !eth_addr_is_zero(ib->local_mac)) {
2
    match_init_catchall(&match);
3
    match_set_in_port(&match, OFPP_LOCAL);
4
    match_set_dl_type(&match, htons(ETH_TYPE_IP));
5
    match_set_dl_src(&match, ib->local_mac);
6
    match_set_nw_proto(&match, IPPROTO_UDP);
7
    match_set_tp_src(&match, htons(DHCP_CLIENT_PORT));
8
    match_set_tp_dst(&match, htons(DHCP_SERVER_PORT));
9
    add_rule(ib, &match, IBR_FROM_LOCAL_DHCP);
10
}

the priority constant IBR_FROM_LOCAL_DHCP is defined as 180000 (ovs/ofproto/in-band.c:53):

1
enum {
2
    IBR_FROM_LOCAL_DHCP = 180000, /* (a) From local port, DHCP. */
3
    IBR_TO_LOCAL_ARP,             /* (b) To local port, ARP. */
4
    /* ... */
5
};

this high-priority rule ensures DHCP requests from the local bridge management interface are always allowed through, even if other flow rules would block them.

control plane policing (copp) for dhcp

OVN supports rate-limiting DHCP control plane traffic via CoPP. the CoPP protocol constants are defined in ovn/lib/copp.h:22-44:

1
enum copp_proto {
2
    COPP_PROTO_FIRST,
3
    COPP_ARP = COPP_PROTO_FIRST,
4
    COPP_ARP_RESOLVE,
5
    COPP_DHCPV4_OPTS,
6
    COPP_DHCPV6_OPTS,
7
    COPP_DNS,
8
    /* ... */
9
    COPP_DHCPV4_RELAY,
10
    COPP_PROTO_MAX,
11
};

these map to string names in ovn/lib/copp.c:25-44:

1
static char *copp_proto_names[COPP_PROTO_MAX] = {
2
    [COPP_DHCPV4_OPTS]   = "dhcpv4-opts",
3
    [COPP_DHCPV6_OPTS]   = "dhcpv6-opts",
4
    [COPP_DHCPV4_RELAY]  = "dhcpv4-relay",
5
    /* ... */
6
};

the copp_meter_get() function (ovn/lib/copp.c:55-70) retrieves the meter name for a given protocol:

1
const char *
2
copp_meter_get(enum copp_proto proto, const struct nbrec_copp *copp,
3
               const struct shash *meter_groups)
4
{
5
    if (!copp || proto >= COPP_PROTO_MAX) {
6
        return NULL;
7
    }
8

9
    const char *meter = smap_get(&copp->meters, copp_proto_names[proto]);
10

11
    if (meter && shash_find(meter_groups, meter)) {
12
        return meter;
13
    }
14

15
    return NULL;
16
}

when generating DHCP flows, northd attaches CoPP meters via the WITH_CTRL_METER() macro. for example, in build_dhcpv4_options_flows():

1
ovn_lflow_add(lflows, op->od, S_SWITCH_IN_DHCP_OPTIONS, 100,
2
              ds_cstr(&match), ds_cstr(&options_action), lflow_ref,
3
              WITH_IO_PORT(inport->key),
4
              WITH_CTRL_METER(copp_meter_get(COPP_DHCPV4_OPTS,
5
                                             op->od->nbs->copp,
6
                                             meter_groups)),
7
              WITH_HINT(&op->nbsp->dhcpv4_options->header_));

this means the DHCP options flow is rate-limited by the dhcpv4-opts meter if one is configured in the NB Copp table. the DHCP relay flows use COPP_DHCPV4_RELAY for rate-limiting.

end-to-end packet walk

DHCPv4 DISCOVER → OFFER

setup:

Logical switch port sw0-port0 with DHCP options: server_id=10.0.0.1, server_mac=00:00:00:00:00:01, lease_time=3600, netmask=255.255.255.0, router=10.0.0.1
Port’s offer IP: 10.0.0.2

packet: client sends DHCPDISCOVER

1
Ethernet: src=aa:bb:cc:dd:ee:ff, dst=ff:ff:ff:ff:ff:ff
2
IP: src=0.0.0.0, dst=255.255.255.255
3
UDP: src=68, dst=67
4
DHCP: op=REQUEST(1), chaddr=aa:bb:cc:dd:ee:ee
5
     Options: msg_type=DISCOVER(1)

pipeline traversal:

ls_in_port_sec → ls_in_pre_acl → … → ls_in_dhcp_options (stage 28)

match at priority 100:

1
inport == "sw0-port0" && eth.src == "aa:bb:cc:dd:ee:ff" &&
2
(ip4.src == {10.0.0.2, 0.0.0.0} && ip4.dst == {10.0.0.1, 255.255.255.255}) &&
3
udp.src == 68 && udp.dst == 67

✓ matches (ip4.src=0.0.0.0, ip4.dst=255.255.255.255)

action executes: reg0[3] = put_dhcp_opts(offerip = 10.0.0.2, netmask = 255.255.255.0, ...); next;
packet-in to ovn-controller: opcode ACTION_OPCODE_PUT_DHCP_OPTS, userdata contains encoded options
pinctrl_handle_put_dhcp_opts() validates the packet, determines msg_type=DISCOVER → msg_type=OFFER, constructs the reply packet
pipeline resumes at ls_in_dhcp_response (stage 29)

match at priority 100:

1
inport == "sw0-port0" && eth.src == "aa:bb:cc:dd:ee:ff" &&
2
ip4 && udp.src == 68 && udp.dst == 67 && reg0[3]

✓ matches (reg0[3]=1)

action executes:

1
eth.dst = eth.src; eth.src = 00:00:00:00:00:01;
2
ip4.src = 10.0.0.1; udp.src = 67; udp.dst = 68;
3
outport = inport; flags.loopback = 1; output;

packet sent back to client

response:

1
Ethernet: src=00:00:00:00:00:01, dst=aa:bb:cc:dd:ee:ff
2
IP: src=10.0.0.1, dst=10.0.0.2
3
UDP: src=67, dst=68
4
DHCP: op=REPLY(2), yiaddr=10.0.0.2
5
     Options: msg_type=OFFER(2), netmask=255.255.255.0, router=10.0.0.1, ...

DHCPv4 REQUEST → ACK

same as above, but the client sends a DHCPREQUEST with msg_type=REQUEST(3) and requested_ip=10.0.0.2. the handler validates that requested_ip == offer_ip and responds with msg_type=ACK(5).

DHCPv4 REQUEST → NAK (wrong IP)

if the client sends a DHCPREQUEST with requested_ip=10.0.0.99 (which doesn’t match the offer), the handler sets msg_type=NAK(6):

1
case DHCP_MSG_REQUEST: {
2
    msg_type = DHCP_MSG_ACK;
3
    if (dhcp_opts.request_ip != *offer_ip) {
4
        msg_type = DHCP_MSG_NAK;
5
    }
6
    break;
7
}

the NAK response has yiaddr=0 and siaddr=0:

1
dhcp_data->yiaddr = (msg_type == DHCP_MSG_NAK) ? 0 : *offer_ip;
2
dhcp_data->siaddr = (msg_type == DHCP_MSG_NAK) ? 0 : next_server;

and DHCP options are not included in NAK messages:

1
if (msg_type != DHCP_MSG_NAK) {
2
    new_l4_size += reply_dhcp_opts_ptr->size;
3
}

packet: client sends DHCPv6 SOLICIT

1
Ethernet: src=aa:bb:cc:dd:ee:ff, dst=33:33:00:01:00:02
2
IPv6: src=fe80::..., dst=ff02::1:2
3
UDP: src=546, dst=547
4
DHCPv6: msg_type=SOLICIT(1), transaction_id=...
5
     Options: Client_ID, IA_NA(iaid=...), ...

pipeline traversal at ls_in_dhcp_options:

match:

1
inport == "sw0-port0" && eth.src == "aa:bb:cc:dd:ee:ff"
2
&& ip6.mcast && ip6.dst == ff02::1:2
3
&& udp.src == 546 && udp.dst == 547

action: reg0[3] = put_dhcpv6_opts(ia_addr = fe80::..., server_id = 00:00:00:00:00:01, ...); next;

at pinctrl_handle_put_dhcpv6_opts():

message type SOLICIT → response type ADVERT
IAID extracted from client’s IA_NA option
Client ID extracted and copied to response
options composed via compose_out_dhcpv6_opts()
Client ID + composed options assembled into the response packet

DHCP relay: client request to remote server

setup:

Logical switch sw0 with other_config:dhcp_relay_port = "sw0-lr0"
Logical router port lr0-sw0 with dhcp_relay pointing to a DHCP_Relay with servers = "192.168.1.100"
Router port IP: 10.0.0.1/24

packet: client sends DHCPDISCOVER

1
Ethernet: src=aa:bb:cc:dd:ee:ff, dst=ff:ff:ff:ff:ff:ff
2
IP: src=0.0.0.0, dst=255.255.255.255
3
UDP: src=68, dst=67
4
DHCP: op=REQUEST(1), chaddr=aa:bb:cc:dd:ee:ff, giaddr=0

pipeline traversal:

ls_in_l2_lkup (stage 14): the relay flow at priority 100 matches:

1
inport == "sw0-port0" && eth.src == "aa:bb:cc:dd:ee:ff" &&
2
ip4.src == {0.0.0.0, 10.0.0.0/24} && ip4.dst == 255.255.255.255 &&
3
udp.src == 68 && udp.dst == 67

action: eth.dst = <router_mac>; outport = "sw0-lr0"; next;

lr_in_ip_input (stage 3): the relay request validation flow at priority 110 matches:
```
1
inport == "lr0-sw0" &&
2
ip4.src == {0.0.0.0, 10.0.0.0/24} && ip4.dst == 255.255.255.255 &&
3
ip.frag == 0 && udp.src == 68 && udp.dst == 67
```
action: reg9[7] = dhcp_relay_req_chk(10.0.0.1, 192.168.1.100); next;
packet-in to ovn-controller: opcode ACTION_OPCODE_DHCP_RELAY_REQ_CHK
pinctrl_handle_dhcp_relay_req_chk() validates the packet:
- op == DHCP_OP_REQUEST ✓
- giaddr == 0 ✓
- message type present ✓
- sets giaddr = 10.0.0.1 (relay IP)
- increments hops to 1
- updates UDP checksum
lr_in_dhcp_relay_req (stage 4): the flow at priority 100 matches (reg9[7]=1):
```
1
inport == "lr0-sw0" &&
2
ip4.src == {0.0.0.0, 10.0.0.0/24} && ip4.dst == 255.255.255.255 &&
3
udp.src == 68 && udp.dst == 67 && reg9[7]
```
action: ip4.src = 10.0.0.1; ip4.dst = 192.168.1.100; udp.src = 67; next;
the packet is now addressed to the remote DHCP server and is routed normally.

DHCP relay: server response back to client

packet: DHCP server sends DHCPOFFER

1
Ethernet: src=<server_mac>, dst=<router_mac>
2
IP: src=192.168.1.100, dst=10.0.0.1
3
UDP: src=67, dst=67
4
DHCP: op=REPLY(2), yiaddr=10.0.0.2, giaddr=10.0.0.1, chaddr=aa:bb:cc:dd:ee:ff

pipeline traversal:

lr_in_ip_input (stage 3): the relay response flow at priority 110 matches:

1
ip4.src == 192.168.1.100 && ip4.dst == 10.0.0.1 &&
2
ip.frag == 0 && udp.src == 67 && udp.dst == 67

action: next;

lr_in_dhcp_relay_resp_chk (stage 20): the flow at priority 100 matches:
```
1
ip4.src == 192.168.1.100 && ip4.dst == 10.0.0.1 &&
2
udp.src == 67 && udp.dst == 67
```
action: reg2 = ip4.dst; reg9[8] = dhcp_relay_resp_chk(10.0.0.1, 192.168.1.100); next;
packet-in to ovn-controller: opcode ACTION_OPCODE_DHCP_RELAY_RESP_CHK
pinctrl_handle_dhcp_relay_resp_chk() validates:
- op == DHCP_OP_REPLY ✓
- giaddr != 0 ✓ (giaddr=10.0.0.1)
- giaddr == relay_ip ✓
- message type present ✓
- server_id present ✓
- server_id == server_ip ✓
- for OFFER: (yiaddr & netmask) == (giaddr & netmask) ✓
- sets eth.dst = client_mac (from chaddr)
- handles broadcast flag for ip_dst
lr_in_dhcp_relay_resp (stage 21): the flow at priority 100 matches (reg9[8]=1):
```
1
ip4.src == 192.168.1.100 && reg2 == 10.0.0.1 &&
2
udp.src == 67 && udp.dst == 67 && reg9[8]
```
action: ip4.src = 10.0.0.1; udp.dst = 68; outport = "lr0-sw0"; output;
the packet is forwarded back to the logical switch and delivered to the client.

that-was-a-lot-of-pipeline-stages

access controls: the priority 34000 acl flow

one of the most important but easily overlooked aspects of DHCP in OVN is the ACL bypass flow. without it, DHCP replies from ovn-controller would be dropped by default-deny ACLs. i spent a good while staring at “why isn’t my DHCP reply getting through?” before i found this.

for each port with DHCP options configured, northd generates a flow at stage S_SWITCH_OUT_ACL_EVAL with priority 34000 (ovn/northd/northd.c:9967-9989):

1
if (!is_external) {
2
    const char *server_id = smap_get(
3
        &op->nbsp->dhcpv4_options->options, "server_id");
4
    const char *server_mac = smap_get(
5
        &op->nbsp->dhcpv4_options->options, "server_mac");
6
    const char *lease_time = smap_get(
7
        &op->nbsp->dhcpv4_options->options, "lease_time");
8
    ovs_assert(server_id && server_mac && lease_time);
9
    const char *dhcp_actions =
10
        REGBIT_ACL_VERDICT_ALLOW" = 1; next;";
11
    ds_clear(&match);
12
    ds_put_format(&match, "outport == %s && eth.src == %s "
13
                  "&& ip4.src == %s && udp && udp.src == 67 "
14
                  "&& udp.dst == 68", op->json_key,
15
                  server_mac, server_id);
16
    ovn_lflow_add(lflows, op->od, S_SWITCH_OUT_ACL_EVAL, 34000,
17
                  ds_cstr(&match), dhcp_actions, lflow_ref,
18
                  WITH_IO_PORT(op->key),
19
                  WITH_HINT(&op->nbsp->dhcpv4_options->header_));
20
}

this flow matches DHCP replies (udp.src=67, udp.dst=68) from the server MAC and server IP to the specific logical port, and sets REGBIT_ACL_VERDICT_ALLOW (reg1[0]) to 1. priority 34000 is high enough to match before most user-defined ACLs but lower than the universal flows at 65532+.

the same pattern applies for DHCPv6 (ovn/northd/northd.c:10043-10072):

1
ds_put_format(&match, "outport == %s && eth.src == %s "
2
              "&& ip6.src == %s && udp && udp.src == 547 "
3
              "&& udp.dst == 546", op->json_key,
4
              server_mac, server_ip);
5
ovn_lflow_add(lflows, op->od, S_SWITCH_OUT_ACL_EVAL, 34000,
6
              ds_cstr(&match), dhcp6_actions, lflow_ref, ...);

appendix a: dhcp packet structure reference

the DHCP packet structure is defined in ovs/lib/dhcp.h:31-49:

1
OVS_PACKED(
2
struct dhcp_header {
3
    uint8_t op;                 /* DHCP_BOOTREQUEST(1) or DHCP_BOOTREPLY(2). */
4
    uint8_t htype;              /* ARP_HRD_ETHERNET (0x1). */
5
    uint8_t hlen;               /* ETH_ADDR_LEN (0x6). */
6
    uint8_t hops;               /* Hop count; set to 0 by client. */
7
    ovs_be32 xid;               /* Transaction ID. */
8
    ovs_be16 secs;              /* Since client started address acquisition. */
9
    ovs_be16 flags;             /* DHCP_FLAGS_* (bit 15 = broadcast). */
10
    ovs_be32 ciaddr;            /* Client IP, if it has a lease for one. */
11
    ovs_be32 yiaddr;            /* Client ("your") IP address. */
12
    ovs_be32 siaddr;            /* Next server IP address. */
13
    ovs_be32 giaddr;            /* Relay agent IP address. */
14
    uint8_t chaddr[16];         /* Client hardware address. */
15
    char sname[64];             /* Optional server host name. */
16
    char file[128];             /* Boot file name. */
17
    /* Followed by variable-length options field. */
18
});
19
BUILD_ASSERT_DECL(DHCP_HEADER_LEN == sizeof(struct dhcp_header));

key constants from ovs/lib/dhcp.h:24-64:

1
#define DHCP_SERVER_PORT        67
2
#define DHCP_CLIENT_PORT        68
3
#define DHCP_MAGIC_COOKIE       0x63825363
4
#define DHCP_HEADER_LEN         236
5

6
#define DHCP_OP_REQUEST         1
7
#define DHCP_OP_REPLY           2
8

9
#define DHCP_MSG_DISCOVER       1
10
#define DHCP_MSG_OFFER          2
11
#define DHCP_MSG_REQUEST        3
12
#define DHCP_MSG_ACK            5
13
#define DHCP_MSG_NAK            6
14

15
#define DHCP_OPT_PAD            0
16
#define DHCP_OPT_REQ_IP         50
17
#define DHCP_OPT_MSG_TYPE       53
18
#define DHCP_OPT_END            255

additional OVN-specific DHCP message types from ovn/lib/ovn-l7.h:247-249:

1
#define OVN_DHCP_MSG_DECLINE    4
2
#define OVN_DHCP_MSG_RELEASE    7
3
#define OVN_DHCP_MSG_INFORM     8

the DHCPv6 header (ovn/lib/ovn-l7.h:316-321):

1
OVS_PACKED(
2
struct dhcpv6_header {
3
    uint8_t msg_type;
4
    uint8_t transaction_id[3];
5
});
6
BUILD_ASSERT_DECL(DHCPV6_HEADER_LEN == sizeof(struct dhcpv6_header));

the DHCP option header (ovn/lib/ovn-l7.h:236-244):

1
#define DHCP_OPT_HEADER_LEN 2
2
struct dhcp_opt_header {
3
    uint8_t code;
4
    uint8_t len;
5
};
6

7
#define DHCP_OPT_PAYLOAD(hdr) \
8
    (void *)((char *)hdr + sizeof(struct dhcp_opt_header))

appendix b: complete action opcode reference for dhcp

Opcode	Enum Value	Userdata Format	Handler
`ACTION_OPCODE_PUT_DHCP_OPTS`	(auto)	`[OXM][offset][offer_ip][opt1][opt2]...`	`pinctrl_handle_put_dhcp_opts`
`ACTION_OPCODE_PUT_DHCPV6_OPTS`	(auto)	`[OXM][offset][opt1][opt2]...`	`pinctrl_handle_put_dhcpv6_opts`
`ACTION_OPCODE_DHCP6_SERVER`	(auto)	(OF1.3 actions)	`pinctrl_handle_dhcp6_server`
`ACTION_OPCODE_DHCP_RELAY_REQ_CHK`	(auto)	`[OXM][offset][relay_ip][server_ip]`	`pinctrl_handle_dhcp_relay_req_chk`
`ACTION_OPCODE_DHCP_RELAY_RESP_CHK`	(auto)	`[OXM][offset][relay_ip][server_ip]`	`pinctrl_handle_dhcp_relay_resp_chk`

the struct action_header (ovn/include/ovn/actions.h:854-858) is always the first 8 bytes of userdata:

1
struct action_header {
2
    ovs_be32 opcode;            /* One of ACTION_OPCODE_* */
3
    uint8_t pad[4];
4
};

appendix c: ovn dhcp option wire format types

Type String	Wire Format	Example
`"ipv4"`	4 bytes per value, network byte order	`10.0.0.1` → `0x0a000001`
`"uint8"`	1 byte	`128` → `0x80`
`"uint16"`	2 bytes, network byte order	`1500` → `0x05dc`
`"uint32"`	4 bytes, network byte order	`3600` → `0x00000e10`
`"bool"`	1 byte (0 or 1)	`true` → `0x01`
`"str"`	Raw bytes, length = strlen	`"hello"` → `0x68656c6c6f`
`"host_id"`	String or IPv4	`"tftp.example.com"` or `10.0.0.1`
`"mac"`	6 bytes (ETH_ADDR_LEN)	`00:01:02:03:04:05` → 6 bytes
`"ipv6"`	16 bytes per value	`fe80::1` → 16 bytes
`"domains"`	RFC 1035 DNS-encoded with compression	See Section 5.4
`"static_routes"`	RFC 3442 classless route encoding	See Section 5.4
`"domain"`	FQDN encoded per RFC 3696	See `encode_fqdn_string()`

appendix d: source file reference

Component	File	Key Functions/Lines
DHCP packet structure	`ovs/lib/dhcp.h`	`struct dhcp_header` (L31-49), constants (L24-64)
OVN DHCP option definitions	`ovn/lib/ovn-l7.h`	`DHCP_OPTION` macros (L77-156), `struct dhcp_opt_header` (L236-244)
DHCPv6 structures	`ovn/lib/ovn-l7.h`	`struct dhcpv6_header` (L316-321), option structs (L326-411)
CoPP definitions	`ovn/lib/copp.h`	`enum copp_proto` (L22-44)
CoPP implementation	`ovn/lib/copp.c`	`copp_meter_get()` (L55-70)
Action opcodes	`ovn/include/ovn/actions.h`	`ACTION_OPCODES` macro (L663-844)
Action structs	`ovn/include/ovn/actions.h`	`ovnact_put_opts` (L406-411), `ovnact_dhcp_relay` (L414-419)
Action encoding	`ovn/lib/actions.c`	`encode_PUT_DHCPV4_OPTS` (L3228-3292), `encode_PUT_DHCPV6_OPTS` (L3294-3313)
Option encoding	`ovn/lib/actions.c`	`encode_put_dhcpv4_option` (L3026-3192), `encode_put_dhcpv6_option` (L3194-3226)
Relay encoding	`ovn/lib/actions.c`	`encode_dhcpv4_relay_chk` (L2883-2901)
Action parsing	`ovn/lib/actions.c`	`parse_put_dhcp_opts` (L2976-2995), `parse_dhcp_relay_chk` (L2846-2881)
NB DB schema	`ovn/ovn-nb.ovsschema`	`DHCP_Options` (L711-719), `DHCP_Relay` (L720-731)
SB DB schema	`ovn/ovn-sb.ovsschema`	`DHCP_Options` (L305-317), `DHCPv6_Options` (L318-328)
Northd option sync	`ovn/northd/ovn-northd.c`	`supported_dhcp_opts[]` (L244-283), sync functions (L448-519)
Northd flow generation	`ovn/northd/northd.c`	`build_dhcpv4_options_flows` (L9900-9995), `build_dhcpv6_options_flows` (L9997-10077)
Northd action building	`ovn/northd/northd.c`	`build_dhcpv4_action` (L5956-6040), `build_dhcpv6_action` (L6042-6121)
Northd relay flows	`ovn/northd/northd.c`	`build_lswitch_dhcp_relay_flows` (L10085-10162), `build_dhcp_relay_flows_for_lrouter_port` (L16815-16980)
Northd stage defs	`ovn/northd/northd.h`	Pipeline stages (L548-605)
Northd register defs	`ovn/northd/northd.c`	`REGBIT_DHCP_OPTS_RESULT` (L126), relay registers (L209-230)
Controller engine	`ovn/controller/ovn-controller.c`	`en_dhcp_options_run` (L3836-3862), graph (L7075-7078)
Controller flow parsing	`ovn/controller/lflow.c`	`lflow_parse_actions` (L365-408)
Controller pinctrl	`ovn/controller/pinctrl.c`	`process_packet_in` (L3746-3919), `pinctrl_handle_put_dhcp_opts` (L2604-2944)
Controller DHCPv6	`ovn/controller/pinctrl.c`	`pinctrl_handle_put_dhcpv6_opts` (L3138-3364)
Controller relay req	`ovn/controller/pinctrl.c`	`pinctrl_handle_dhcp_relay_req_chk` (L2245-2388)
Controller relay resp	`ovn/controller/pinctrl.c`	`pinctrl_handle_dhcp_relay_resp_chk` (L2390-2600)
Controller packet parsing	`ovn/controller/pinctrl.c`	`dhcp_get_hdr_from_pkt` (L2112-2168), `dhcp_parse_options` (L2180-2243)
Controller DHCPv6 PD	`ovn/controller/pinctrl.c`	`pinctrl_handle_dhcp6_server` (L1155-1184)
OVS in-band DHCP	`ovs/ofproto/in-band.c`	`in_band_must_output_to_local_port` (L233-243), rule creation (L286-295)
OVS DHCP constants	`ovs/lib/dhcp.h`	All constants and structs
NB CLI	`ovn/utilities/ovn-nbctl.c`	DHCP CLI commands

OVN/OVS DHCP Internals: From `ovn-nbctl set-lsp` to the DHCP Response Packet

the setup

the nb database

DHCP options table

DHCP relay table

how ports reference DHCP configuration

northd: syncing dhcp options to sb

the built-in option tables

the sync function

northd: generating logical flows for dhcp

pipeline stage architecture

register bits for DHCP state

the entry point

building the DHCPv4 action string

the generated logical flows

default flows

DHCP relay on the logical switch

DHCP relay on the logical router

the ovn action system: how put_dhcp_opts becomes openflow

the action opcodes

parsing DHCP actions

encoding DHCP actions into openflow

option encoding by type

DHCPv6 option encoding

DHCP relay action encoding

ovn controller: reading dhcp options from sb

the engine node

feeding into logical flow processing

ovn controller pinctrl: handling dhcp packet-ins

the dispatch table

DHCP packet validation: dhcp_get_hdr_from_pkt

DHCP option parsing: dhcp_parse_options

DHCPv4: building the response packet

DHCPv6: building the response packet

DHCPv6 prefix delegation handling

DHCP relay: request validation

DHCP relay: response validation

ovs in-band: making sure dhcp actually works

the DHCP output check

the DHCP request rule

control plane policing (copp) for dhcp

end-to-end packet walk

DHCPv4 DISCOVER → OFFER

DHCPv4 REQUEST → ACK

DHCPv4 REQUEST → NAK (wrong IP)

DHCPv6 SOLICIT → ADVERT

DHCP relay: client request to remote server

DHCP relay: server response back to client

access controls: the priority 34000 acl flow

appendix a: dhcp packet structure reference

appendix b: complete action opcode reference for dhcp

appendix c: ovn dhcp option wire format types

appendix d: source file reference