1 <?xml version="1.0" encoding="utf-8"?>
2 <manpage program="ovn-northd" section="8" title="ovn-northd">
4 <p>ovn-northd -- Open Virtual Network central control daemon</p>
7 <p><code>ovn-northd</code> [<var>options</var>]</p>
11 <code>ovn-northd</code> is a centralized daemon responsible for
12 translating the high-level OVN configuration into logical
13 configuration consumable by daemons such as
14 <code>ovn-controller</code>. It translates the logical network
15 configuration in terms of conventional network concepts, taken
16 from the OVN Northbound Database (see <code>ovn-nb</code>(5)),
17 into logical datapath flows in the OVN Southbound Database (see
18 <code>ovn-sb</code>(5)) below it.
21 <h1>Configuration</h1>
23 <code>ovn-northd</code> requires a connection to the Northbound
24 and Southbound databases. The default is <code>db.sock</code>
25 in the local Open vSwitch's "run" directory. This may be
26 overridden with the following commands:
31 <code>--ovnnb-db=<var>database</var></code>
34 The database containing the OVN Northbound Database.
39 <code>--ovnsb-db=<var>database</var></code>
42 The database containing the OVN Southbound Database.
47 The <var>database</var> argument must take one of the following forms:
52 <code>ssl:<var>ip</var>:<var>port</var></code>
55 The specified SSL <var>port</var> on the host at the given
56 <var>ip</var>, which must be expressed as an IP address (not a DNS
57 name) in IPv4 or IPv6 address format. If <var>ip</var> is an IPv6
58 address, then wrap <var>ip</var> with square brackets, e.g.:
59 <code>ssl:[::1]:6640</code>. The <code>--private-key</code>,
60 <code>--certificate</code>, and <code>--ca-cert</code> options are
61 mandatory when this form is used.
66 <code>tcp:<var>ip</var>:<var>port</var></code>
69 Connect to the given TCP <var>port</var> on <var>ip</var>, where
70 <var>ip</var> can be IPv4 or IPv6 address. If <var>ip</var> is an
71 IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
72 <code>tcp:[::1]:6640</code>.
77 <code>unix:<var>file</var></code>
80 On POSIX, connect to the Unix domain server socket named
84 On Windows, connect to a localhost TCP port whose value is written
90 <h1>Runtime Management Commands</h1>
92 <code>ovs-appctl</code> can send commands to a running
93 <code>ovn-northd</code> process. The currently supported commands
96 <dt><code>exit</code></dt>
98 Causes <code>ovn-northd</code> to gracefully terminate.
103 <h1>Logical Flow Table Structure</h1>
106 One of the main purposes of <code>ovn-northd</code> is to populate the
107 <code>Logical_Flow</code> table in the <code>OVN_Southbound</code>
108 database. This section describes how <code>ovn-northd</code> does this
109 for switch and router logical datapaths.
112 <h2>Logical Switch Datapaths</h2>
114 <h3>Ingress Table 0: Admission Control and Ingress Port Security - L2</h3>
117 Ingress table 0 contains these logical flows:
122 Priority 100 flows to drop packets with VLAN tags or multicast Ethernet
127 Priority 50 flows that implement ingress port security for each enabled
128 logical port. For logical ports on which port security is enabled,
129 these match the <code>inport</code> and the valid <code>eth.src</code>
130 address(es) and advance only those packets to the next flow table. For
131 logical ports on which port security is not enabled, these advance all
132 packets that match the <code>inport</code>.
137 There are no flows for disabled logical ports because the default-drop
138 behavior of logical flow tables causes packets that ingress from them to
142 <h3>Ingress Table 1: Ingress Port Security - IP</h3>
145 Ingress table 1 contains these logical flows:
151 For each element in the port security set having one or more IPv4 or
152 IPv6 addresses (or both),
157 Priority 90 flow to allow IPv4 traffic if it has IPv4 addresses
158 which match the <code>inport</code>, valid <code>eth.src</code>
159 and valid <code>ip4.src</code> address(es).
163 Priority 90 flow to allow IPv4 DHCP discovery traffic if it has a
164 valid <code>eth.src</code>. This is necessary since DHCP discovery
165 messages are sent from the unspecified IPv4 address (0.0.0.0) since
166 the IPv4 address has not yet been assigned.
170 Priority 90 flow to allow IPv6 traffic if it has IPv6 addresses
171 which match the <code>inport</code>, valid <code>eth.src</code> and
172 valid <code>ip6.src</code> address(es).
176 Priority 90 flow to allow IPv6 DAD (Duplicate Address Detection)
177 traffic if it has a valid <code>eth.src</code>. This is is
178 necessary since DAD include requires joining an multicast group and
179 sending neighbor solicitations for the newly assigned address. Since
180 no address is yet assigned, these are sent from the unspecified
185 Priority 80 flow to drop IP (both IPv4 and IPv6) traffic which
186 match the <code>inport</code> and valid <code>eth.src</code>.
192 One priority-0 fallback flow that matches all packets and advances to
197 <h3>Ingress Table 2: Ingress Port Security - Neighbor discovery</h3>
200 Ingress table 2 contains these logical flows:
206 For each element in the port security set,
211 Priority 90 flow to allow ARP traffic which match the
212 <code>inport</code> and valid <code>eth.src</code> and
213 <code>arp.sha</code>. If the element has one or more
214 IPv4 addresses, then it also matches the valid
215 <code>arp.spa</code>.
219 Priority 90 flow to allow IPv6 Neighbor Solicitation and
220 Advertisement traffic which match the <code>inport</code>,
221 valid <code>eth.src</code> and
222 <code>nd.sll</code>/<code>nd.tll</code>.
223 If the element has one or more IPv6 addresses, then it also
224 matches the valid <code>nd.target</code> address(es) for Neighbor
225 Advertisement traffic.
229 Priority 80 flow to drop ARP and IPv6 Neighbor Solicitation and
230 Advertisement traffic which match the <code>inport</code> and
231 valid <code>eth.src</code>.
237 One priority-0 fallback flow that matches all packets and advances to
242 <h3>Ingress Table 3: <code>from-lport</code> Pre-ACLs</h3>
245 Ingress table 3 prepares flows for possible stateful ACL processing
246 in table 4. It contains a priority-0 flow that simply moves
247 traffic to table 4. If stateful ACLs are used in the logical
248 datapath, a priority-100 flow is added that sends IP packets to
249 the connection tracker before advancing to table 4.
252 <h3>Ingress table 4: <code>from-lport</code> ACLs</h3>
255 Logical flows in this table closely reproduce those in the
256 <code>ACL</code> table in the <code>OVN_Northbound</code> database
257 for the <code>from-lport</code> direction. <code>allow</code>
258 ACLs translate into logical flows with the <code>next;</code>
259 action, <code>allow-related</code> ACLs translate into logical
260 flows with the <code>ct_commit; next;</code> actions, other ACLs
261 translate to <code>drop;</code>. The <code>priority</code> values
262 from the <code>ACL</code> table have a limited range and have 1000
263 added to them to leave room for OVN default flows at both higher
264 and lower priorities.
268 Ingress table 4 also contains a priority 0 flow with action
269 <code>next;</code>, so that ACLs allow packets by default. If the
270 logical datapath has a statetful ACL, the following flows will
276 A priority-1 flow to commit IP traffic to the connection
277 tracker. This is needed for the default allow policy because,
278 while the initiater's direction may not have any stateful rules,
279 the server's may and then its return traffic would not be known
280 and marked as invalid.
284 A priority-65535 flow that allows any traffic that has been
285 committed to the connection tracker (i.e., established flows).
289 A priority-65535 flow that allows any traffic that is considered
290 related to a committed flow in the connection tracker (e.g., an
291 ICMP Port Unreachable from a non-listening UDP port).
295 A priority-65535 flow that drops all traffic marked by the
296 connection tracker as invalid.
300 <h3>Ingress Table 5: ARP responder</h3>
303 This table implements ARP responder for known IPs. It contains these
309 Priority-100 flows to skip ARP responder if inport is of type
310 <code>localnet</code>, and advances directly to table 6.
315 Priority-50 flows that matches ARP requests to each known IP address
316 <var>A</var> of logical port <var>P</var>, and respond with ARP
317 replies directly with corresponding Ethernet address <var>E</var>:
322 eth.src = <var>E</var>;
323 arp.op = 2; /* ARP reply. */
325 arp.sha = <var>E</var>;
327 arp.spa = <var>A</var>;
328 outport = <var>P</var>;
329 inport = ""; /* Allow sending out inport. */
334 These flows are omitted for logical ports (other than router ports)
340 One priority-0 fallback flow that matches all packets and advances to
345 <h3>Ingress Table 6: Destination Lookup</h3>
348 This table implements switching behavior. It contains these logical
354 A priority-100 flow that outputs all packets with an Ethernet broadcast
355 or multicast <code>eth.dst</code> to the <code>MC_FLOOD</code>
356 multicast group, which <code>ovn-northd</code> populates with all
357 enabled logical ports.
361 One priority-50 flow that matches each known Ethernet address against
362 <code>eth.dst</code> and outputs the packet to the single associated
367 One priority-0 fallback flow that matches all packets and outputs them
368 to the <code>MC_UNKNOWN</code> multicast group, which
369 <code>ovn-northd</code> populates with all enabled logical ports that
370 accept unknown destination packets. As a small optimization, if no
371 logical ports accept unknown destination packets,
372 <code>ovn-northd</code> omits this multicast group and logical flow.
376 <h3>Egress Table 0: <code>to-lport</code> Pre-ACLs</h3>
379 This is similar to ingress table 3 except for <code>to-lport</code>
383 <h3>Egress Table 1: <code>to-lport</code> ACLs</h3>
386 This is similar to ingress table 4 except for <code>to-lport</code> ACLs.
389 <h3>Egress Table 2: Egress Port Security - IP</h3>
392 This is similar to the ingress port security logic in table 1 except
393 that <code>outport</code>, <code>eth.dst</code>, <code>ip4.dst</code>
394 and <code>ip6.dst</code> are checked instead of <code>inport</code>,
395 <code>eth.src</code>, <code>ip4.src</code> and <code>ip6.src</code>
398 <h3>Egress Table 3: Egress Port Security - L2</h3>
401 This is similar to the ingress port security logic in ingress table 0,
402 but with important differences. Most obviously, <code>outport</code> and
403 <code>eth.dst</code> are checked instead of <code>inport</code> and
404 <code>eth.src</code>. Second, packets directed to broadcast or multicast
405 <code>eth.dst</code> are always accepted instead of being subject to the
406 port security rules; this is implemented through a priority-100 flow that
407 matches on <code>eth.mcast</code> with action <code>output;</code>.
408 Finally, to ensure that even broadcast and multicast packets are not
409 delivered to disabled logical ports, a priority-150 flow for each
410 disabled logical <code>outport</code> overrides the priority-100 flow
411 with a <code>drop;</code> action.
414 <h2>Logical Router Datapaths</h2>
417 Logical router datapaths will only exist for <ref table="Logical_Router"
418 db="OVN_Northbound"/> rows in the <ref db="OVN_Northbound"/> database
419 that do not have <ref column="enabled" table="Logical_Router"
420 db="OVN_Northbound"/> set to <code>false</code>
423 <h3>Ingress Table 0: L2 Admission Control</h3>
426 This table drops packets that the router shouldn't see at all based on
427 their Ethernet headers. It contains the following flows:
432 Priority-100 flows to drop packets with VLAN tags or multicast Ethernet
437 For each enabled router port <var>P</var> with Ethernet address
438 <var>E</var>, a priority-50 flow that matches <code>inport ==
439 <var>P</var> && (eth.mcast || eth.dst ==
440 <var>E</var></code>), with action <code>next;</code>.
445 Other packets are implicitly dropped.
448 <h3>Ingress Table 1: IP Input</h3>
451 This table is the core of the logical router datapath functionality. It
452 contains the following flows to implement very basic IP host
459 L3 admission control: A priority-100 flow drops packets that match
460 any of the following:
465 <code>ip4.src[28..31] == 0xe</code> (multicast source)
468 <code>ip4.src == 255.255.255.255</code> (broadcast source)
471 <code>ip4.src == 127.0.0.0/8 || ip4.dst == 127.0.0.0/8</code>
472 (localhost source or destination)
475 <code>ip4.src == 0.0.0.0/8 || ip4.dst == 0.0.0.0/8</code> (zero
476 network source or destination)
479 <code>ip4.src</code> is any IP address owned by the router.
482 <code>ip4.src</code> is the broadcast address of any IP network
490 ICMP echo reply. These flows reply to ICMP echo requests received
491 for the router's IP address. Let <var>A</var> be an IP address or
492 broadcast address owned by a router port. Then, for each
493 <var>A</var>, a priority-90 flow matches on <code>ip4.dst ==
494 <var>A</var></code> and <code>icmp4.type == 8 && icmp4.code
495 == 0</code> (ICMP echo request). These flows use the following
496 actions where, if <var>A</var> is unicast, then <var>S</var> is
497 <var>A</var>, and if <var>A</var> is broadcast, <var>S</var> is the
498 router's IP address in <var>A</var>'s network:
503 ip4.src = <var>S</var>;
506 inport = ""; /* Allow sending out inport. */
511 Similar flows match on <code>ip4.dst == 255.255.255.255</code> and
512 each individual <code>inport</code>, and use the same actions in
513 which <var>S</var> is a function of <code>inport</code>.
519 Reply to ARP requests. These flows reply to ARP requests for the
520 router's own IP address. For each router port <var>P</var> that owns
521 IP address <var>A</var> and Ethernet address <var>E</var>, a
522 priority-90 flow matches <code>inport == <var>P</var> &&
523 arp.op == 1 && arp.tpa == <var>A</var></code> (ARP request)
524 with the following actions:
529 eth.src = <var>E</var>;
530 arp.op = 2; /* ARP reply. */
532 arp.sha = <var>E</var>;
534 arp.spa = <var>A</var>;
535 outport = <var>P</var>;
536 inport = ""; /* Allow sending out inport. */
542 ARP reply handling. These flows use ARP replies to populate the
543 logical router's ARP table. A priority-90 flow with match <code>arp.op
544 == 2</code> has actions <code>put_arp(inport, arp.spa,
550 UDP port unreachable. Priority-80 flows generate ICMP port
551 unreachable messages in reply to UDP datagrams directed to the
552 router's IP address. The logical router doesn't accept any UDP
553 traffic so it always generates such a reply.
557 These flows should not match IP fragments with nonzero offset.
561 Details TBD. Not yet implemented.
567 TCP reset. Priority-80 flows generate TCP reset messages in reply to
568 TCP datagrams directed to the router's IP address. The logical
569 router doesn't accept any TCP traffic so it always generates such a
574 These flows should not match IP fragments with nonzero offset.
578 Details TBD. Not yet implemented.
584 Protocol unreachable. Priority-70 flows generate ICMP protocol
585 unreachable messages in reply to packets directed to the router's IP
586 address on IP protocols other than UDP, TCP, and ICMP.
590 These flows should not match IP fragments with nonzero offset.
594 Details TBD. Not yet implemented.
599 Drop other IP traffic to this router. These flows drop any other
600 traffic destined to an IP address of this router that is not already
601 handled by one of the flows above, which amounts to ICMP (other than
602 echo requests) and fragments with nonzero offsets. For each IP address
603 <var>A</var> owned by the router, a priority-60 flow matches
604 <code>ip4.dst == <var>A</var></code> and drops the traffic.
609 The flows above handle all of the traffic that might be directed to the
610 router itself. The following flows (with lower priorities) handle the
611 remaining traffic, potentially for forwarding:
616 Drop Ethernet local broadcast. A priority-50 flow with match
617 <code>eth.bcast</code> drops traffic destined to the local Ethernet
618 broadcast address. By definition this traffic should not be forwarded.
622 Drop IP multicast. A priority-50 flow with match
623 <code>ip4.mcast</code> drops IP multicast traffic.
628 ICMP time exceeded. For each router port <var>P</var>, whose IP
629 address is <var>A</var>, a priority-40 flow with match <code>inport
630 == <var>P</var> && ip.ttl == {0, 1} &&
631 !ip.later_frag</code> matches packets whose TTL has expired, with the
632 following actions to send an ICMP time exceeded reply:
637 icmp4.type = 11; /* Time exceeded. */
638 icmp4.code = 0; /* TTL exceeded in transit. */
640 ip4.src = <var>A</var>;
652 TTL discard. A priority-30 flow with match <code>ip.ttl == {0,
653 1}</code> and actions <code>drop;</code> drops other packets whose TTL
654 has expired, that should not receive a ICMP error reply (i.e. fragments
655 with nonzero offset).
659 Next table. A priority-0 flows match all packets that aren't already
660 handled and uses actions <code>next;</code> to feed them to the ingress
665 <h3>Ingress Table 2: IP Routing</h3>
668 A packet that arrives at this table is an IP packet that should be routed
669 to the address in <code>ip4.dst</code>. This table implements IP
670 routing, setting <code>reg0</code> to the next-hop IP address (leaving
671 <code>ip4.dst</code>, the packet's final destination, unchanged) and
672 advances to the next table for ARP resolution. It also sets
673 <code>reg1</code> to the IP address owned by the selected router port
674 (which is used later in table 4 as the IP source address for an ARP
679 This table contains the following logical flows:
685 Routing table. For each route to IPv4 network <var>N</var> with
686 netmask <var>M</var>, on router port <var>P</var> with IP address
687 <var>A</var> and Ethernet
688 address <var>E</var>, a logical flow with match <code>ip4.dst ==
689 <var>N</var>/<var>M</var></code>, whose priority is the number of
690 1-bits in <var>M</var>, has the following actions:
697 eth.src = <var>E</var>;
698 outport = <var>P</var>;
703 (Ingress table 1 already verified that <code>ip.ttl--;</code> will
704 not yield a TTL exceeded error.)
708 If the route has a gateway, <var>G</var> is the gateway IP address.
709 Instead, if the route is from a configured static route, <var>G</var>
710 is the next hop IP address. Else it is <code>ip4.dst</code>.
716 Destination unreachable. For each router port <var>P</var>, which
717 owns IP address <var>A</var>, a priority-0 logical flow with match
718 <code>in_port == <var>P</var> && !ip.later_frag &&
719 !icmp</code> has the following actions:
724 icmp4.type = 3; /* Destination unreachable. */
725 icmp4.code = 0; /* Network unreachable. */
727 ip4.src = <var>A</var>;
734 (The <code>!icmp</code> check prevents recursion if the destination
735 unreachable message itself cannot be routed.)
739 These flows are omitted if the logical router has a default route,
740 that is, a route with netmask 0.0.0.0.
745 <h3>Ingress Table 3: ARP Resolution</h3>
748 Any packet that reaches this table is an IP packet whose next-hop IP
749 address is in <code>reg0</code>. (<code>ip4.dst</code> is the final
750 destination.) This table resolves the IP address in <code>reg0</code>
751 into an output port in <code>outport</code> and an Ethernet address in
752 <code>eth.dst</code>, using the following flows:
758 Static MAC bindings. MAC bindings can be known statically based on
759 data in the <code>OVN_Northbound</code> database. For router ports
760 connected to logical switches, MAC bindings can be known statically
761 from the <code>addresses</code> column in the
762 <code>Logical_Port</code> table. For router ports connected to other
763 logical routers, MAC bindings can be known statically from the
764 <code>mac</code> and <code>network</code> column in the
765 <code>Logical_Router_Port</code> table.
769 For each IP address <var>A</var> whose host is known to have Ethernet
770 address <var>E</var> on router port <var>P</var>, a priority-100 flow
771 with match <code>outport === <var>P</var> && reg0 ==
772 <var>A</var></code> has actions <code>eth.dst = <var>E</var>;
777 For each logical router port with an IP address <var>A</var> and
778 a mac address of <var>E</var> that is reachable via a different
779 logical router port <var>P</var>, a priority-100 flow with
780 match <code>outport === <var>P</var> && reg0 ==
781 <var>A</var></code> has actions <code>eth.dst = <var>E</var>;
788 Dynamic MAC bindings. This flows resolves MAC-to-IP bindings that
789 have become known dynamically through ARP. (The next table will
790 issue an ARP request for cases where the binding is not yet known.)
794 A priority-0 logical flow with match <code>1</code> has actions
795 <code>get_arp(outport, reg0); next;</code>.
800 <h3>Ingress Table 4: ARP Request</h3>
803 In the common case where the Ethernet destination has been resolved, this
804 table outputs the packet. Otherwise, it composes and sends an ARP
805 request. It holds the following flows:
811 Unknown MAC address. A priority-100 flow with match <code>eth.dst ==
812 00:00:00:00:00:00</code> has the following actions:
817 eth.dst = ff:ff:ff:ff:ff:ff;
819 arp.op = 1; /* ARP request. */
825 (Ingress table 2 initialized <code>reg1</code> with the IP address
826 owned by <code>outport</code>.)
830 The IP packet that triggers the ARP request is dropped.
835 Known MAC address. A priority-0 flow with match <code>1</code> has
836 actions <code>output;</code>.
840 <h3>Egress Table 0: Delivery</h3>
843 Packets that reach this table are ready for delivery. It contains
844 priority-100 logical flows that match packets on each enabled logical
845 router port, with action <code>output;</code>.