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>--ovsnb-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</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: <code>from-lport</code> Pre-ACLs</h3>
145 Ingress table 1 prepares flows for possible stateful ACL processing
146 in table 2. It contains a priority-0 flow that simply moves
147 traffic to table 2. If stateful ACLs are used in the logical
148 datapath, a priority-100 flow is added that sends IP packets to
149 the connection tracker before advancing to table 2.
152 <h3>Ingress table 2: <code>from-lport</code> ACLs</h3>
155 Logical flows in this table closely reproduce those in the
156 <code>ACL</code> table in the <code>OVN_Northbound</code> database
157 for the <code>from-lport</code> direction. <code>allow</code>
158 ACLs translate into logical flows with the <code>next;</code>
159 action, <code>allow-related</code> ACLs translate into logical
160 flows with the <code>ct_next;</code> action, other ACLs translate
161 to <code>drop;</code>. The <code>priority</code> values from the
162 <code>ACL</code> table are used directly.
166 Ingress table 2 also contains a priority 0 flow with action
167 <code>next;</code>, so that ACLs allow packets by default. If the
168 logical datapath has a statetful ACL, the following flows will
174 A priority-1 flow to commit IP traffic to the connection
175 tracker. This is needed for the default allow policy because,
176 while the initiater's direction may not have any stateful rules,
177 the server's may and then its return traffic would not be known
178 and marked as invalid.
182 A priority-65535 flow that allows any traffic that has been
183 committed to the connection tracker (i.e., established flows).
187 A priority-65535 flow that allows any traffic that is considered
188 related to a committed flow in the connection tracker (e.g., an
189 ICMP Port Unreachable from a non-listening UDP port).
193 A priority-65535 flow that drops all traffic marked by the
194 connection tracker as invalid.
198 <h3>Ingress Table 3: ARP responder</h3>
201 This table implements ARP responder for known IPs. It contains these
207 Priority-100 flows to skip ARP responder if inport is of type
208 <code>localnet</code>, and advances directly to table 3.
213 Priority-50 flows that matches ARP requests to each known IP address
214 <var>A</var> of logical port <var>P</var>, and respond with ARP
215 replies directly with corresponding Ethernet address <var>E</var>:
220 eth.src = <var>E</var>;
221 arp.op = 2; /* ARP reply. */
223 arp.sha = <var>E</var>;
225 arp.spa = <var>A</var>;
226 outport = <var>P</var>;
227 inport = ""; /* Allow sending out inport. */
232 These flows are omitted for logical ports (other than router ports)
238 One priority-0 fallback flow that matches all packets and advances to
243 <h3>Ingress Table 4: Destination Lookup</h3>
246 This table implements switching behavior. It contains these logical
252 A priority-100 flow that outputs all packets with an Ethernet broadcast
253 or multicast <code>eth.dst</code> to the <code>MC_FLOOD</code>
254 multicast group, which <code>ovn-northd</code> populates with all
255 enabled logical ports.
259 One priority-50 flow that matches each known Ethernet address against
260 <code>eth.dst</code> and outputs the packet to the single associated
265 One priority-0 fallback flow that matches all packets and outputs them
266 to the <code>MC_UNKNOWN</code> multicast group, which
267 <code>ovn-northd</code> populates with all enabled logical ports that
268 accept unknown destination packets. As a small optimization, if no
269 logical ports accept unknown destination packets,
270 <code>ovn-northd</code> omits this multicast group and logical flow.
274 <h3>Egress Table 0: <code>to-lport</code> Pre-ACLs</h3>
277 This is similar to ingress table 1 except for <code>to-lport</code>
281 <h3>Egress Table 1: <code>to-lport</code> ACLs</h3>
284 This is similar to ingress table 2 except for <code>to-lport</code> ACLs.
287 <h3>Egress Table 2: Egress Port Security</h3>
290 This is similar to the ingress port security logic in ingress table 0,
291 but with important differences. Most obviously, <code>outport</code> and
292 <code>eth.dst</code> are checked instead of <code>inport</code> and
293 <code>eth.src</code>. Second, packets directed to broadcast or multicast
294 <code>eth.dst</code> are always accepted instead of being subject to the
295 port security rules; this is implemented through a priority-100 flow that
296 matches on <code>eth.mcast</code> with action <code>output;</code>.
297 Finally, to ensure that even broadcast and multicast packets are not
298 delivered to disabled logical ports, a priority-150 flow for each
299 disabled logical <code>outport</code> overrides the priority-100 flow
300 with a <code>drop;</code> action.
303 <h2>Logical Router Datapaths</h2>
305 <h3>Ingress Table 0: L2 Admission Control</h3>
308 This table drops packets that the router shouldn't see at all based on
309 their Ethernet headers. It contains the following flows:
314 Priority-100 flows to drop packets with VLAN tags or multicast Ethernet
319 For each enabled router port <var>P</var> with Ethernet address
320 <var>E</var>, a priority-50 flow that matches <code>inport ==
321 <var>P</var> && (eth.mcast || eth.dst ==
322 <var>E</var></code>), with action <code>next;</code>.
327 Other packets are implicitly dropped.
330 <h3>Ingress Table 1: IP Input</h3>
333 This table is the core of the logical router datapath functionality. It
334 contains the following flows to implement very basic IP host
341 L3 admission control: A priority-100 flow drops packets that match
342 any of the following:
347 <code>ip4.src[28..31] == 0xe</code> (multicast source)
350 <code>ip4.src == 255.255.255.255</code> (broadcast source)
353 <code>ip4.src == 127.0.0.0/8 || ip4.dst == 127.0.0.0/8</code>
354 (localhost source or destination)
357 <code>ip4.src == 0.0.0.0/8 || ip4.dst == 0.0.0.0/8</code> (zero
358 network source or destination)
361 <code>ip4.src</code> is any IP address owned by the router.
364 <code>ip4.src</code> is the broadcast address of any IP network
372 ICMP echo reply. These flows reply to ICMP echo requests received
373 for the router's IP address. Let <var>A</var> be an IP address or
374 broadcast address owned by a router port. Then, for each
375 <var>A</var>, a priority-90 flow matches on <code>ip4.dst ==
376 <var>A</var></code> and <code>icmp4.type == 8 && icmp4.code
377 == 0</code> (ICMP echo request). These flows use the following
378 actions where, if <var>A</var> is unicast, then <var>S</var> is
379 <var>A</var>, and if <var>A</var> is broadcast, <var>S</var> is the
380 router's IP address in <var>A</var>'s network:
385 ip4.src = <var>S</var>;
388 inport = ""; /* Allow sending out inport. */
393 Similar flows match on <code>ip4.dst == 255.255.255.255</code> and
394 each individual <code>inport</code>, and use the same actions in
395 which <var>S</var> is a function of <code>inport</code>.
401 ARP reply. These flows reply to ARP requests for the router's own IP
402 address. For each router port <var>P</var> that owns IP address
403 <var>A</var> and Ethernet address <var>E</var>, a priority-90 flow
404 matches <code>inport == <var>P</var> && arp.tpa ==
405 <var>A</var> && arp.op == 1</code> (ARP request) with the
411 eth.src = <var>E</var>;
412 arp.op = 2; /* ARP reply. */
414 arp.sha = <var>E</var>;
416 arp.spa = <var>A</var>;
417 outport = <var>P</var>;
418 inport = ""; /* Allow sending out inport. */
425 UDP port unreachable. Priority-80 flows generate ICMP port
426 unreachable messages in reply to UDP datagrams directed to the
427 router's IP address. The logical router doesn't accept any UDP
428 traffic so it always generates such a reply.
432 These flows should not match IP fragments with nonzero offset.
436 Details TBD. Not yet implemented.
442 TCP reset. Priority-80 flows generate TCP reset messages in reply to
443 TCP datagrams directed to the router's IP address. The logical
444 router doesn't accept any TCP traffic so it always generates such a
449 These flows should not match IP fragments with nonzero offset.
453 Details TBD. Not yet implemented.
459 Protocol unreachable. Priority-70 flows generate ICMP protocol
460 unreachable messages in reply to packets directed to the router's IP
461 address on IP protocols other than UDP, TCP, and ICMP.
465 These flows should not match IP fragments with nonzero offset.
469 Details TBD. Not yet implemented.
474 Drop other IP traffic to this router. These flows drop any other
475 traffic destined to an IP address of this router that is not already
476 handled by one of the flows above, which amounts to ICMP (other than
477 echo requests) and fragments with nonzero offsets. For each IP address
478 <var>A</var> owned by the router, a priority-60 flow matches
479 <code>ip4.dst == <var>A</var></code> and drops the traffic.
484 The flows above handle all of the traffic that might be directed to the
485 router itself. The following flows (with lower priorities) handle the
486 remaining traffic, potentially for forwarding:
491 Drop Ethernet local broadcast. A priority-50 flow with match
492 <code>eth.bcast</code> drops traffic destined to the local Ethernet
493 broadcast address. By definition this traffic should not be forwarded.
497 Drop IP multicast. A priority-50 flow with match
498 <code>ip4.mcast</code> drops IP multicast traffic.
503 ICMP time exceeded. For each router port <var>P</var>, whose IP
504 address is <var>A</var>, a priority-40 flow with match <code>inport
505 == <var>P</var> && ip.ttl == {0, 1} &&
506 !ip.later_frag</code> matches packets whose TTL has expired, with the
507 following actions to send an ICMP time exceeded reply:
512 icmp4.type = 11; /* Time exceeded. */
513 icmp4.code = 0; /* TTL exceeded in transit. */
515 ip4.src = <var>A</var>;
527 TTL discard. A priority-30 flow with match <code>ip.ttl == {0,
528 1}</code> and actions <code>drop;</code> drops other packets whose TTL
529 has expired, that should not receive a ICMP error reply (i.e. fragments
530 with nonzero offset).
534 Next table. A priority-0 flows match all packets that aren't already
535 handled and uses actions <code>next;</code> to feed them to the ingress
540 <h3>Ingress Table 2: IP Routing</h3>
543 A packet that arrives at this table is an IP packet that should be routed
544 to the address in <code>ip4.dst</code>. This table implements IP
545 routing, setting <code>reg0</code> to the next-hop IP address (leaving
546 <code>ip4.dst</code>, the packet's final destination, unchanged) and
547 advances to the next table for ARP resolution.
551 This table contains the following logical flows:
557 Routing table. For each route to IPv4 network <var>N</var> with
558 netmask <var>M</var>, a logical flow with match <code>ip4.dst ==
559 <var>N</var>/<var>M</var></code>, whose priority is the number of
560 1-bits in <var>M</var>, has the following actions:
570 (Ingress table 1 already verified that <code>ip.ttl--;</code> will
571 not yield a TTL exceeded error.)
575 If the route has a gateway, <var>G</var> is the gateway IP address,
576 otherwise it is <code>ip4.dst</code>.
582 Destination unreachable. For each router port <var>P</var>, which
583 owns IP address <var>A</var>, a priority-0 logical flow with match
584 <code>in_port == <var>P</var> && !ip.later_frag &&
585 !icmp</code> has the following actions:
590 icmp4.type = 3; /* Destination unreachable. */
591 icmp4.code = 0; /* Network unreachable. */
593 ip4.src = <var>A</var>;
600 (The <code>!icmp</code> check prevents recursion if the destination
601 unreachable message itself cannot be routed.)
605 These flows are omitted if the logical router has a default route,
606 that is, a route with netmask 0.0.0.0.
611 <h3>Ingress Table 3: ARP Resolution</h3>
614 Any packet that reaches this table is an IP packet whose next-hop IP
615 address is in <code>reg0</code>. (<code>ip4.dst</code> is the final
616 destination.) This table resolves the IP address in <code>reg0</code>
617 into an output port in <code>outport</code> and an Ethernet address in
618 <code>eth.dst</code>, using the following flows:
624 Known MAC bindings. For each IP address <var>A</var> whose host is
625 known to have Ethernet address <var>HE</var> and reside on router
626 port <var>P</var> with Ethernet address <var>PE</var>, a priority-200
627 flow with match <code>reg0 == <var>A</var></code> has the following
632 eth.src = <var>PE</var>;
633 eth.dst = <var>HE</var>;
634 outport = <var>P</var>;
639 MAC bindings can be known statically based on data in the
640 <code>OVN_Northbound</code> database. For router ports connected to
641 logical switches, MAC bindings can be known statically from the
642 <code>addresses</code> column in the <code>Logical_Port</code> table.
643 For router ports connected to other logical routers, MAC bindings can
644 be known statically from the <code>mac</code> and
645 <code>network</code> column in the <code>Logical_Router_Port</code>
652 Unknown MAC bindings. For each non-gateway route to IPv4 network
653 <var>N</var> with netmask <var>M</var> on router port <var>P</var>
654 that owns IP address <var>A</var> and Ethernet address <var>E</var>,
655 a logical flow with match <code>ip4.dst ==
656 <var>N</var>/<var>M</var></code>, whose priority is the number of
657 1-bits in <var>M</var>, has the following actions:
662 eth.dst = ff:ff:ff:ff:ff:ff;
663 eth.src = <var>E</var>;
664 arp.sha = <var>E</var>;
665 arp.tha = 00:00:00:00:00:00;
666 arp.spa = <var>A</var>;
668 arp.op = 1; /* ARP request. */
669 outport = <var>P</var>;
675 TBD: How to install MAC bindings when an ARP response comes back.
676 (Implement a "learn" action?)
685 <h3>Egress Table 0: Delivery</h3>
688 Packets that reach this table are ready for delivery. It contains
689 priority-100 logical flows that match packets on each enabled logical
690 router port, with action <code>output;</code>.