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 defaults are <code>ovnnb_db.sock</code>
25 and <code>ovnsb_db.sock</code> respectively
26 in the local Open vSwitch's "run" directory. This may be
27 overridden with the following commands:
32 <code>--ovnnb-db=<var>database</var></code>
35 The database containing the OVN Northbound Database.
40 <code>--ovnsb-db=<var>database</var></code>
43 The database containing the OVN Southbound Database.
48 The <var>database</var> argument must take one of the following forms:
53 <code>ssl:<var>ip</var>:<var>port</var></code>
56 The specified SSL <var>port</var> on the host at the given
57 <var>ip</var>, which must be expressed as an IP address (not a DNS
58 name) in IPv4 or IPv6 address format. If <var>ip</var> is an IPv6
59 address, then wrap <var>ip</var> with square brackets, e.g.:
60 <code>ssl:[::1]:6640</code>. The <code>--private-key</code>,
61 <code>--certificate</code>, and <code>--ca-cert</code> options are
62 mandatory when this form is used.
67 <code>tcp:<var>ip</var>:<var>port</var></code>
70 Connect to the given TCP <var>port</var> on <var>ip</var>, where
71 <var>ip</var> can be IPv4 or IPv6 address. If <var>ip</var> is an
72 IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
73 <code>tcp:[::1]:6640</code>.
78 <code>unix:<var>file</var></code>
81 On POSIX, connect to the Unix domain server socket named
85 On Windows, connect to a localhost TCP port whose value is written
91 <h1>Runtime Management Commands</h1>
93 <code>ovs-appctl</code> can send commands to a running
94 <code>ovn-northd</code> process. The currently supported commands
97 <dt><code>exit</code></dt>
99 Causes <code>ovn-northd</code> to gracefully terminate.
104 <h1>Logical Flow Table Structure</h1>
107 One of the main purposes of <code>ovn-northd</code> is to populate the
108 <code>Logical_Flow</code> table in the <code>OVN_Southbound</code>
109 database. This section describes how <code>ovn-northd</code> does this
110 for switch and router logical datapaths.
113 <h2>Logical Switch Datapaths</h2>
115 <h3>Ingress Table 0: Admission Control and Ingress Port Security - L2</h3>
118 Ingress table 0 contains these logical flows:
123 Priority 100 flows to drop packets with VLAN tags or multicast Ethernet
128 Priority 50 flows that implement ingress port security for each enabled
129 logical port. For logical ports on which port security is enabled,
130 these match the <code>inport</code> and the valid <code>eth.src</code>
131 address(es) and advance only those packets to the next flow table. For
132 logical ports on which port security is not enabled, these advance all
133 packets that match the <code>inport</code>.
138 There are no flows for disabled logical ports because the default-drop
139 behavior of logical flow tables causes packets that ingress from them to
143 <h3>Ingress Table 1: Ingress Port Security - IP</h3>
146 Ingress table 1 contains these logical flows:
152 For each element in the port security set having one or more IPv4 or
153 IPv6 addresses (or both),
158 Priority 90 flow to allow IPv4 traffic if it has IPv4 addresses
159 which match the <code>inport</code>, valid <code>eth.src</code>
160 and valid <code>ip4.src</code> address(es).
164 Priority 90 flow to allow IPv4 DHCP discovery traffic if it has a
165 valid <code>eth.src</code>. This is necessary since DHCP discovery
166 messages are sent from the unspecified IPv4 address (0.0.0.0) since
167 the IPv4 address has not yet been assigned.
171 Priority 90 flow to allow IPv6 traffic if it has IPv6 addresses
172 which match the <code>inport</code>, valid <code>eth.src</code> and
173 valid <code>ip6.src</code> address(es).
177 Priority 90 flow to allow IPv6 DAD (Duplicate Address Detection)
178 traffic if it has a valid <code>eth.src</code>. This is is
179 necessary since DAD include requires joining an multicast group and
180 sending neighbor solicitations for the newly assigned address. Since
181 no address is yet assigned, these are sent from the unspecified
186 Priority 80 flow to drop IP (both IPv4 and IPv6) traffic which
187 match the <code>inport</code> and valid <code>eth.src</code>.
193 One priority-0 fallback flow that matches all packets and advances to
198 <h3>Ingress Table 2: Ingress Port Security - Neighbor discovery</h3>
201 Ingress table 2 contains these logical flows:
207 For each element in the port security set,
212 Priority 90 flow to allow ARP traffic which match the
213 <code>inport</code> and valid <code>eth.src</code> and
214 <code>arp.sha</code>. If the element has one or more
215 IPv4 addresses, then it also matches the valid
216 <code>arp.spa</code>.
220 Priority 90 flow to allow IPv6 Neighbor Solicitation and
221 Advertisement traffic which match the <code>inport</code>,
222 valid <code>eth.src</code> and
223 <code>nd.sll</code>/<code>nd.tll</code>.
224 If the element has one or more IPv6 addresses, then it also
225 matches the valid <code>nd.target</code> address(es) for Neighbor
226 Advertisement traffic.
230 Priority 80 flow to drop ARP and IPv6 Neighbor Solicitation and
231 Advertisement traffic which match the <code>inport</code> and
232 valid <code>eth.src</code>.
238 One priority-0 fallback flow that matches all packets and advances to
243 <h3>Ingress Table 3: <code>from-lport</code> Pre-ACLs</h3>
246 Ingress table 3 prepares flows for possible stateful ACL processing
247 in table 4. It contains a priority-0 flow that simply moves
248 traffic to table 4. If stateful ACLs are used in the logical
249 datapath, a priority-100 flow is added that sends IP packets to
250 the connection tracker before advancing to table 4.
253 <h3>Ingress table 4: <code>from-lport</code> ACLs</h3>
256 Logical flows in this table closely reproduce those in the
257 <code>ACL</code> table in the <code>OVN_Northbound</code> database
258 for the <code>from-lport</code> direction. <code>allow</code>
259 ACLs translate into logical flows with the <code>next;</code>
260 action, <code>allow-related</code> ACLs translate into logical
261 flows with the <code>ct_commit; next;</code> actions, other ACLs
262 translate to <code>drop;</code>. The <code>priority</code> values
263 from the <code>ACL</code> table have a limited range and have 1000
264 added to them to leave room for OVN default flows at both higher
265 and lower priorities.
269 Ingress table 4 also contains a priority 0 flow with action
270 <code>next;</code>, so that ACLs allow packets by default. If the
271 logical datapath has a statetful ACL, the following flows will
277 A priority-1 flow to commit IP traffic to the connection
278 tracker. This is needed for the default allow policy because,
279 while the initiater's direction may not have any stateful rules,
280 the server's may and then its return traffic would not be known
281 and marked as invalid.
285 A priority-65535 flow that allows any traffic that has been
286 committed to the connection tracker (i.e., established flows).
290 A priority-65535 flow that allows any traffic that is considered
291 related to a committed flow in the connection tracker (e.g., an
292 ICMP Port Unreachable from a non-listening UDP port).
296 A priority-65535 flow that drops all traffic marked by the
297 connection tracker as invalid.
301 <h3>Ingress Table 5: ARP responder</h3>
304 This table implements ARP responder for known IPs. It contains these
310 Priority-100 flows to skip ARP responder if inport is of type
311 <code>localnet</code>, and advances directly to table 6.
316 Priority-50 flows that matches ARP requests to each known IP address
317 <var>A</var> of logical port <var>P</var>, and respond with ARP
318 replies directly with corresponding Ethernet address <var>E</var>:
323 eth.src = <var>E</var>;
324 arp.op = 2; /* ARP reply. */
326 arp.sha = <var>E</var>;
328 arp.spa = <var>A</var>;
329 outport = <var>P</var>;
330 inport = ""; /* Allow sending out inport. */
335 These flows are omitted for logical ports (other than router ports)
341 One priority-0 fallback flow that matches all packets and advances to
346 <h3>Ingress Table 6: Destination Lookup</h3>
349 This table implements switching behavior. It contains these logical
355 A priority-100 flow that outputs all packets with an Ethernet broadcast
356 or multicast <code>eth.dst</code> to the <code>MC_FLOOD</code>
357 multicast group, which <code>ovn-northd</code> populates with all
358 enabled logical ports.
362 One priority-50 flow that matches each known Ethernet address against
363 <code>eth.dst</code> and outputs the packet to the single associated
368 One priority-0 fallback flow that matches all packets and outputs them
369 to the <code>MC_UNKNOWN</code> multicast group, which
370 <code>ovn-northd</code> populates with all enabled logical ports that
371 accept unknown destination packets. As a small optimization, if no
372 logical ports accept unknown destination packets,
373 <code>ovn-northd</code> omits this multicast group and logical flow.
377 <h3>Egress Table 0: <code>to-lport</code> Pre-ACLs</h3>
380 This is similar to ingress table 3 except for <code>to-lport</code>
384 <h3>Egress Table 1: <code>to-lport</code> ACLs</h3>
387 This is similar to ingress table 4 except for <code>to-lport</code> ACLs.
390 <h3>Egress Table 2: Egress Port Security - IP</h3>
393 This is similar to the ingress port security logic in table 1 except
394 that <code>outport</code>, <code>eth.dst</code>, <code>ip4.dst</code>
395 and <code>ip6.dst</code> are checked instead of <code>inport</code>,
396 <code>eth.src</code>, <code>ip4.src</code> and <code>ip6.src</code>
399 <h3>Egress Table 3: Egress Port Security - L2</h3>
402 This is similar to the ingress port security logic in ingress table 0,
403 but with important differences. Most obviously, <code>outport</code> and
404 <code>eth.dst</code> are checked instead of <code>inport</code> and
405 <code>eth.src</code>. Second, packets directed to broadcast or multicast
406 <code>eth.dst</code> are always accepted instead of being subject to the
407 port security rules; this is implemented through a priority-100 flow that
408 matches on <code>eth.mcast</code> with action <code>output;</code>.
409 Finally, to ensure that even broadcast and multicast packets are not
410 delivered to disabled logical ports, a priority-150 flow for each
411 disabled logical <code>outport</code> overrides the priority-100 flow
412 with a <code>drop;</code> action.
415 <h2>Logical Router Datapaths</h2>
418 Logical router datapaths will only exist for <ref table="Logical_Router"
419 db="OVN_Northbound"/> rows in the <ref db="OVN_Northbound"/> database
420 that do not have <ref column="enabled" table="Logical_Router"
421 db="OVN_Northbound"/> set to <code>false</code>
424 <h3>Ingress Table 0: L2 Admission Control</h3>
427 This table drops packets that the router shouldn't see at all based on
428 their Ethernet headers. It contains the following flows:
433 Priority-100 flows to drop packets with VLAN tags or multicast Ethernet
438 For each enabled router port <var>P</var> with Ethernet address
439 <var>E</var>, a priority-50 flow that matches <code>inport ==
440 <var>P</var> && (eth.mcast || eth.dst ==
441 <var>E</var></code>), with action <code>next;</code>.
446 Other packets are implicitly dropped.
449 <h3>Ingress Table 1: IP Input</h3>
452 This table is the core of the logical router datapath functionality. It
453 contains the following flows to implement very basic IP host
460 L3 admission control: A priority-100 flow drops packets that match
461 any of the following:
466 <code>ip4.src[28..31] == 0xe</code> (multicast source)
469 <code>ip4.src == 255.255.255.255</code> (broadcast source)
472 <code>ip4.src == 127.0.0.0/8 || ip4.dst == 127.0.0.0/8</code>
473 (localhost source or destination)
476 <code>ip4.src == 0.0.0.0/8 || ip4.dst == 0.0.0.0/8</code> (zero
477 network source or destination)
480 <code>ip4.src</code> is any IP address owned by the router.
483 <code>ip4.src</code> is the broadcast address of any IP network
491 ICMP echo reply. These flows reply to ICMP echo requests received
492 for the router's IP address. Let <var>A</var> be an IP address or
493 broadcast address owned by a router port. Then, for each
494 <var>A</var>, a priority-90 flow matches on <code>ip4.dst ==
495 <var>A</var></code> and <code>icmp4.type == 8 && icmp4.code
496 == 0</code> (ICMP echo request). These flows use the following
497 actions where, if <var>A</var> is unicast, then <var>S</var> is
498 <var>A</var>, and if <var>A</var> is broadcast, <var>S</var> is the
499 router's IP address in <var>A</var>'s network:
504 ip4.src = <var>S</var>;
507 inport = ""; /* Allow sending out inport. */
512 Similar flows match on <code>ip4.dst == 255.255.255.255</code> and
513 each individual <code>inport</code>, and use the same actions in
514 which <var>S</var> is a function of <code>inport</code>.
520 Reply to ARP requests.
524 These flows reply to ARP requests for the router's own IP address.
525 For each router port <var>P</var> that owns IP address <var>A</var>
526 and Ethernet address <var>E</var>, a priority-90 flow matches
527 <code>inport == <var>P</var> && arp.op == 1 &&
528 arp.tpa == <var>A</var></code> (ARP request) with the following
534 eth.src = <var>E</var>;
535 arp.op = 2; /* ARP reply. */
537 arp.sha = <var>E</var>;
539 arp.spa = <var>A</var>;
540 outport = <var>P</var>;
541 inport = ""; /* Allow sending out inport. */
548 These flows reply to ARP requests for the virtual IP addresses
549 configured in the router for DNAT. For a configured DNAT IP address
550 <var>A</var>, for each router port <var>P</var> with Ethernet
551 address <var>E</var>, a priority-90 flow matches
552 <code>inport == <var>P</var> && arp.op == 1 &&
553 arp.tpa == <var>A</var></code> (ARP request)
554 with the following actions:
559 eth.src = <var>E</var>;
560 arp.op = 2; /* ARP reply. */
562 arp.sha = <var>E</var>;
564 arp.spa = <var>A</var>;
565 outport = <var>P</var>;
566 inport = ""; /* Allow sending out inport. */
572 ARP reply handling. These flows use ARP replies to populate the
573 logical router's ARP table. A priority-90 flow with match <code>arp.op
574 == 2</code> has actions <code>put_arp(inport, arp.spa,
580 UDP port unreachable. Priority-80 flows generate ICMP port
581 unreachable messages in reply to UDP datagrams directed to the
582 router's IP address. The logical router doesn't accept any UDP
583 traffic so it always generates such a reply.
587 These flows should not match IP fragments with nonzero offset.
591 Details TBD. Not yet implemented.
597 TCP reset. Priority-80 flows generate TCP reset messages in reply to
598 TCP datagrams directed to the router's IP address. The logical
599 router doesn't accept any TCP traffic so it always generates such a
604 These flows should not match IP fragments with nonzero offset.
608 Details TBD. Not yet implemented.
614 Protocol unreachable. Priority-70 flows generate ICMP protocol
615 unreachable messages in reply to packets directed to the router's IP
616 address on IP protocols other than UDP, TCP, and ICMP.
620 These flows should not match IP fragments with nonzero offset.
624 Details TBD. Not yet implemented.
629 Drop other IP traffic to this router. These flows drop any other
630 traffic destined to an IP address of this router that is not already
631 handled by one of the flows above, which amounts to ICMP (other than
632 echo requests) and fragments with nonzero offsets. For each IP address
633 <var>A</var> owned by the router, a priority-60 flow matches
634 <code>ip4.dst == <var>A</var></code> and drops the traffic. An
635 exception is made and the above flow is not added if the router
636 port's own IP address is used to SNAT packets passing through that
642 The flows above handle all of the traffic that might be directed to the
643 router itself. The following flows (with lower priorities) handle the
644 remaining traffic, potentially for forwarding:
649 Drop Ethernet local broadcast. A priority-50 flow with match
650 <code>eth.bcast</code> drops traffic destined to the local Ethernet
651 broadcast address. By definition this traffic should not be forwarded.
655 Drop IP multicast. A priority-50 flow with match
656 <code>ip4.mcast</code> drops IP multicast traffic.
661 ICMP time exceeded. For each router port <var>P</var>, whose IP
662 address is <var>A</var>, a priority-40 flow with match <code>inport
663 == <var>P</var> && ip.ttl == {0, 1} &&
664 !ip.later_frag</code> matches packets whose TTL has expired, with the
665 following actions to send an ICMP time exceeded reply:
670 icmp4.type = 11; /* Time exceeded. */
671 icmp4.code = 0; /* TTL exceeded in transit. */
673 ip4.src = <var>A</var>;
685 TTL discard. A priority-30 flow with match <code>ip.ttl == {0,
686 1}</code> and actions <code>drop;</code> drops other packets whose TTL
687 has expired, that should not receive a ICMP error reply (i.e. fragments
688 with nonzero offset).
692 Next table. A priority-0 flows match all packets that aren't already
693 handled and uses actions <code>next;</code> to feed them to the ingress
698 <h3>Ingress Table 2: UNSNAT</h3>
701 This is for already established connections' reverse traffic.
702 i.e., SNAT has already been done in egress pipeline and now the
703 packet has entered the ingress pipeline as part of a reply. It is
710 For each configuration in the OVN Northbound database, that asks
711 to change the source IP address of a packet from <var>A</var> to
712 <var>B</var>, a priority-100 flow matches <code>ip &&
713 ip4.dst == <var>B</var></code> with an action
714 <code>ct_snat; next;</code>.
718 A priority-0 logical flow with match <code>1</code> has actions
724 <h3>Ingress Table 3: DNAT</h3>
727 Packets enter the pipeline with destination IP address that needs to
728 be DNATted from a virtual IP address to a real IP address. Packets
729 in the reverse direction needs to be unDNATed.
734 For each configuration in the OVN Northbound database, that asks
735 to change the destination IP address of a packet from <var>A</var> to
736 <var>B</var>, a priority-100 flow matches <code>ip &&
737 ip4.dst == <var>A</var></code> with an action <code>inport = "";
738 ct_dnat(<var>B</var>);</code>.
742 For all IP packets of a Gateway router, a priority-50 flow with an
743 action <code>inport = ""; ct_dnat;</code>.
747 A priority-0 logical flow with match <code>1</code> has actions
753 <h3>Ingress Table 4: IP Routing</h3>
756 A packet that arrives at this table is an IP packet that should be routed
757 to the address in <code>ip4.dst</code>. This table implements IP
758 routing, setting <code>reg0</code> to the next-hop IP address (leaving
759 <code>ip4.dst</code>, the packet's final destination, unchanged) and
760 advances to the next table for ARP resolution. It also sets
761 <code>reg1</code> to the IP address owned by the selected router port
762 (which is used later in table 6 as the IP source address for an ARP
767 This table contains the following logical flows:
773 Routing table. For each route to IPv4 network <var>N</var> with
774 netmask <var>M</var>, on router port <var>P</var> with IP address
775 <var>A</var> and Ethernet
776 address <var>E</var>, a logical flow with match <code>ip4.dst ==
777 <var>N</var>/<var>M</var></code>, whose priority is the number of
778 1-bits in <var>M</var>, has the following actions:
785 eth.src = <var>E</var>;
786 outport = <var>P</var>;
791 (Ingress table 1 already verified that <code>ip.ttl--;</code> will
792 not yield a TTL exceeded error.)
796 If the route has a gateway, <var>G</var> is the gateway IP address.
797 Instead, if the route is from a configured static route, <var>G</var>
798 is the next hop IP address. Else it is <code>ip4.dst</code>.
804 Destination unreachable. For each router port <var>P</var>, which
805 owns IP address <var>A</var>, a priority-0 logical flow with match
806 <code>in_port == <var>P</var> && !ip.later_frag &&
807 !icmp</code> has the following actions:
812 icmp4.type = 3; /* Destination unreachable. */
813 icmp4.code = 0; /* Network unreachable. */
815 ip4.src = <var>A</var>;
822 (The <code>!icmp</code> check prevents recursion if the destination
823 unreachable message itself cannot be routed.)
827 These flows are omitted if the logical router has a default route,
828 that is, a route with netmask 0.0.0.0.
833 <h3>Ingress Table 5: ARP Resolution</h3>
836 Any packet that reaches this table is an IP packet whose next-hop IP
837 address is in <code>reg0</code>. (<code>ip4.dst</code> is the final
838 destination.) This table resolves the IP address in <code>reg0</code>
839 into an output port in <code>outport</code> and an Ethernet address in
840 <code>eth.dst</code>, using the following flows:
846 Static MAC bindings. MAC bindings can be known statically based on
847 data in the <code>OVN_Northbound</code> database. For router ports
848 connected to logical switches, MAC bindings can be known statically
849 from the <code>addresses</code> column in the
850 <code>Logical_Switch_Port</code> table. For router ports
851 connected to other logical routers, MAC bindings can be known
852 statically from the <code>mac</code> and <code>network</code>
853 column in the <code>Logical_Router_Port</code> table.
857 For each IP address <var>A</var> whose host is known to have Ethernet
858 address <var>E</var> on router port <var>P</var>, a priority-100 flow
859 with match <code>outport === <var>P</var> && reg0 ==
860 <var>A</var></code> has actions <code>eth.dst = <var>E</var>;
865 For each logical router port with an IP address <var>A</var> and
866 a mac address of <var>E</var> that is reachable via a different
867 logical router port <var>P</var>, a priority-100 flow with
868 match <code>outport === <var>P</var> && reg0 ==
869 <var>A</var></code> has actions <code>eth.dst = <var>E</var>;
876 Dynamic MAC bindings. This flows resolves MAC-to-IP bindings that
877 have become known dynamically through ARP. (The next table will
878 issue an ARP request for cases where the binding is not yet known.)
882 A priority-0 logical flow with match <code>1</code> has actions
883 <code>get_arp(outport, reg0); next;</code>.
888 <h3>Ingress Table 6: ARP Request</h3>
891 In the common case where the Ethernet destination has been resolved, this
892 table outputs the packet. Otherwise, it composes and sends an ARP
893 request. It holds the following flows:
899 Unknown MAC address. A priority-100 flow with match <code>eth.dst ==
900 00:00:00:00:00:00</code> has the following actions:
905 eth.dst = ff:ff:ff:ff:ff:ff;
907 arp.op = 1; /* ARP request. */
913 (Ingress table 4 initialized <code>reg1</code> with the IP address
914 owned by <code>outport</code>.)
918 The IP packet that triggers the ARP request is dropped.
923 Known MAC address. A priority-0 flow with match <code>1</code> has
924 actions <code>output;</code>.
928 <h3>Egress Table 0: SNAT</h3>
931 Packets that are configured to be SNATed get their source IP address
932 changed based on the configuration in the OVN Northbound database.
937 For each configuration in the OVN Northbound database, that asks
938 to change the source IP address of a packet from an IP address of
939 <var>A</var> or to change the source IP address of a packet that
940 belongs to network <var>A</var> to <var>B</var>, a flow matches
941 <code>ip && ip4.src == <var>A</var></code> with an action
942 <code>ct_snat(<var>B</var>);</code>. The priority of the flow
943 is calculated based on the mask of <var>A</var>, with matches
944 having larger masks getting higher priorities.
947 A priority-0 logical flow with match <code>1</code> has actions
953 <h3>Egress Table 1: Delivery</h3>
956 Packets that reach this table are ready for delivery. It contains
957 priority-100 logical flows that match packets on each enabled logical
958 router port, with action <code>output;</code>.