ovn: Implement basic ARP support for L3 logical routers.
[cascardo/ovs.git] / ovn / northd / ovn-northd.8.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <manpage program="ovn-northd" section="8" title="ovn-northd">
3     <h1>Name</h1>
4     <p>ovn-northd -- Open Virtual Network central control daemon</p>
5
6     <h1>Synopsis</h1>
7     <p><code>ovn-northd</code> [<var>options</var>]</p>
8
9     <h1>Description</h1>
10     <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.
19     </p>
20
21     <h1>Configuration</h1>
22     <p>
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:
27     </p>
28     <ul>
29       <li>
30         <p>
31           <code>--ovnnb-db=<var>database</var></code>
32         </p>
33         <p>
34           The database containing the OVN Northbound Database.
35         </p>
36       </li>
37       <li>
38         <p>
39           <code>--ovsnb-db=<var>database</var></code>
40         </p>
41         <p>
42           The database containing the OVN Southbound Database.
43         </p>
44       </li>
45     </ul>
46     <p>
47       The <var>database</var> argument must take one of the following forms:
48     </p>
49     <ul>
50       <li>
51         <p>
52           <code>ssl:<var>ip</var>:<var>port</var></code>
53         </p>
54         <p>
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.
62         </p>
63       </li>
64       <li>
65         <p>
66           <code>tcp:<var>ip</var>:<var>port</var></code>
67         </p>
68         <p>
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>.
73         </p>
74       </li>
75       <li>
76         <p>
77           <code>unix:<var>file</var></code>
78         </p>
79         <p>
80           On POSIX, connect to the Unix domain server socket named
81           <var>file</var>.
82         </p>
83         <p>
84           On Windows, connect to a localhost TCP port whose value is written
85           in <var>file</var>.
86         </p>
87       </li>
88     </ul>
89
90     <h1>Runtime Management Commands</h1>
91     <p>
92       <code>ovs-appctl</code> can send commands to a running
93       <code>ovn-northd</code> process.  The currently supported commands
94       are described below.
95       <dl>
96       <dt><code>exit</code></dt>
97       <dd>
98         Causes <code>ovn-northd</code> to gracefully terminate.
99       </dd>
100       </dl>
101     </p>
102
103     <h1>Logical Flow Table Structure</h1>
104
105     <p>
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.
110     </p>
111
112     <h2>Logical Switch Datapaths</h2>
113
114     <h3>Ingress Table 0: Admission Control and Ingress Port Security</h3>
115
116     <p>
117       Ingress table 0 contains these logical flows:
118     </p>
119
120     <ul>
121       <li>
122         Priority 100 flows to drop packets with VLAN tags or multicast Ethernet
123         source addresses.
124       </li>
125
126       <li>
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>.
133       </li>
134     </ul>
135
136     <p>
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
139       be dropped.
140     </p>
141
142     <h3>Ingress Table 1: <code>from-lport</code> Pre-ACLs</h3>
143
144     <p>
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.
150     </p>
151
152     <h3>Ingress table 2: <code>from-lport</code> ACLs</h3>
153
154     <p>
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.
163     </p>
164
165     <p>
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
169       also be added:
170     </p>
171
172     <ul>
173       <li>
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.
179       </li>
180
181       <li>
182         A priority-65535 flow that allows any traffic that has been
183         committed to the connection tracker (i.e., established flows).
184       </li>
185
186       <li>
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).
190       </li>
191
192       <li>
193         A priority-65535 flow that drops all traffic marked by the
194         connection tracker as invalid.
195       </li>
196     </ul>
197
198     <h3>Ingress Table 3: ARP responder</h3>
199
200     <p>
201       This table implements ARP responder for known IPs.  It contains these
202       logical flows:
203     </p>
204
205     <ul>
206       <li>
207         Priority-100 flows to skip ARP responder if inport is of type
208         <code>localnet</code>, and advances directly to table 3.
209       </li>
210
211       <li>
212         <p>
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>:
216         </p>
217
218         <pre>
219 eth.dst = eth.src;
220 eth.src = <var>E</var>;
221 arp.op = 2; /* ARP reply. */
222 arp.tha = arp.sha;
223 arp.sha = <var>E</var>;
224 arp.tpa = arp.spa;
225 arp.spa = <var>A</var>;
226 outport = <var>P</var>;
227 inport = ""; /* Allow sending out inport. */
228 output;
229         </pre>
230
231         <p>
232           These flows are omitted for logical ports (other than router ports)
233           that are down.
234         </p>
235       </li>
236
237       <li>
238         One priority-0 fallback flow that matches all packets and advances to
239         table 4.
240       </li>
241     </ul>
242
243     <h3>Ingress Table 4: Destination Lookup</h3>
244
245     <p>
246       This table implements switching behavior.  It contains these logical
247       flows:
248     </p>
249
250     <ul>
251       <li>
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.
256       </li>
257
258       <li>
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
261         output port.
262       </li>
263
264       <li>
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.
271       </li>
272     </ul>
273
274     <h3>Egress Table 0: <code>to-lport</code> Pre-ACLs</h3>
275
276     <p>
277       This is similar to ingress table 1 except for <code>to-lport</code>
278       traffic.
279     </p>
280
281     <h3>Egress Table 1: <code>to-lport</code> ACLs</h3>
282
283     <p>
284       This is similar to ingress table 2 except for <code>to-lport</code> ACLs.
285     </p>
286
287     <h3>Egress Table 2: Egress Port Security</h3>
288
289     <p>
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.
301     </p>
302
303     <h2>Logical Router Datapaths</h2>
304
305     <h3>Ingress Table 0: L2 Admission Control</h3>
306
307     <p>
308       This table drops packets that the router shouldn't see at all based on
309       their Ethernet headers.  It contains the following flows:
310     </p>
311
312     <ul>
313       <li>
314         Priority-100 flows to drop packets with VLAN tags or multicast Ethernet
315         source addresses.
316       </li>
317
318       <li>
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> &amp;&amp; (eth.mcast || eth.dst ==
322         <var>E</var></code>), with action <code>next;</code>.
323       </li>
324     </ul>
325
326     <p>
327       Other packets are implicitly dropped.
328     </p>
329
330     <h3>Ingress Table 1: IP Input</h3>
331
332     <p>
333       This table is the core of the logical router datapath functionality.  It
334       contains the following flows to implement very basic IP host
335       functionality.
336     </p>
337
338     <ul>
339       <li>
340         <p>
341           L3 admission control: A priority-100 flow drops packets that match
342           any of the following:
343         </p>
344
345         <ul>
346           <li>
347             <code>ip4.src[28..31] == 0xe</code> (multicast source)
348           </li>
349           <li>
350             <code>ip4.src == 255.255.255.255</code> (broadcast source)
351           </li>
352           <li>
353             <code>ip4.src == 127.0.0.0/8 || ip4.dst == 127.0.0.0/8</code>
354             (localhost source or destination)
355           </li>
356           <li>
357             <code>ip4.src == 0.0.0.0/8 || ip4.dst == 0.0.0.0/8</code> (zero
358             network source or destination)
359           </li>
360           <li>
361             <code>ip4.src</code> is any IP address owned by the router.
362           </li>
363           <li>
364             <code>ip4.src</code> is the broadcast address of any IP network
365             known to the router.
366           </li>
367         </ul>
368       </li>
369
370       <li>
371         <p>
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 &amp;&amp; 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:
381         </p>
382
383         <pre>
384 ip4.dst = ip4.src;
385 ip4.src = <var>S</var>;
386 ip.ttl = 255;
387 icmp4.type = 0;
388 inport = ""; /* Allow sending out inport. */
389 next;
390         </pre>
391
392         <p>
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>.
396         </p>
397       </li>
398
399       <li>
400         <p>
401           Reply to ARP requests.  These flows reply to ARP requests for the
402           router's own IP address.  For each router port <var>P</var> that owns
403           IP address <var>A</var> and Ethernet address <var>E</var>, a
404           priority-90 flow matches <code>inport == <var>P</var> &amp;&amp;
405           arp.op == 1 &amp;&amp; arp.tpa == <var>A</var></code> (ARP request)
406           with the following actions:
407         </p>
408
409         <pre>
410 eth.dst = eth.src;
411 eth.src = <var>E</var>;
412 arp.op = 2; /* ARP reply. */
413 arp.tha = arp.sha;
414 arp.sha = <var>E</var>;
415 arp.tpa = arp.spa;
416 arp.spa = <var>A</var>;
417 outport = <var>P</var>;
418 inport = ""; /* Allow sending out inport. */
419 output;
420         </pre>
421       </li>
422
423       <li>
424         ARP reply handling.  These flows use ARP replies to populate the
425         logical router's ARP table.  A priority-90 flow with match <code>arp.op
426         == 2</code> has actions <code>put_arp(inport, arp.spa,
427         arp.sha);</code>.
428       </li>
429
430       <li>
431         <p>
432           UDP port unreachable.  Priority-80 flows generate ICMP port
433           unreachable messages in reply to UDP datagrams directed to the
434           router's IP address.  The logical router doesn't accept any UDP
435           traffic so it always generates such a reply.
436         </p>
437
438         <p>
439           These flows should not match IP fragments with nonzero offset.
440         </p>
441
442         <p>
443           Details TBD.  Not yet implemented.
444         </p>
445       </li>
446
447       <li>
448         <p>
449           TCP reset.  Priority-80 flows generate TCP reset messages in reply to
450           TCP datagrams directed to the router's IP address.  The logical
451           router doesn't accept any TCP traffic so it always generates such a
452           reply.
453         </p>
454
455         <p>
456           These flows should not match IP fragments with nonzero offset.
457         </p>
458
459         <p>
460           Details TBD.  Not yet implemented.
461         </p>
462       </li>
463
464       <li>
465         <p>
466           Protocol unreachable.  Priority-70 flows generate ICMP protocol
467           unreachable messages in reply to packets directed to the router's IP
468           address on IP protocols other than UDP, TCP, and ICMP.
469         </p>
470
471         <p>
472           These flows should not match IP fragments with nonzero offset.
473         </p>
474
475         <p>
476           Details TBD.  Not yet implemented.
477         </p>
478       </li>
479
480       <li>
481         Drop other IP traffic to this router.  These flows drop any other
482         traffic destined to an IP address of this router that is not already
483         handled by one of the flows above, which amounts to ICMP (other than
484         echo requests) and fragments with nonzero offsets.  For each IP address
485         <var>A</var> owned by the router, a priority-60 flow matches
486         <code>ip4.dst == <var>A</var></code> and drops the traffic.
487       </li>
488     </ul>
489
490     <p>
491       The flows above handle all of the traffic that might be directed to the
492       router itself.  The following flows (with lower priorities) handle the
493       remaining traffic, potentially for forwarding:
494     </p>
495
496     <ul>
497       <li>
498         Drop Ethernet local broadcast.  A priority-50 flow with match
499         <code>eth.bcast</code> drops traffic destined to the local Ethernet
500         broadcast address.  By definition this traffic should not be forwarded.
501       </li>
502
503       <li>
504         Drop IP multicast.  A priority-50 flow with match
505         <code>ip4.mcast</code> drops IP multicast traffic.
506       </li>
507
508       <li>
509         <p>
510           ICMP time exceeded.  For each router port <var>P</var>, whose IP
511           address is <var>A</var>, a priority-40 flow with match <code>inport
512           == <var>P</var> &amp;&amp; ip.ttl == {0, 1} &amp;&amp;
513           !ip.later_frag</code> matches packets whose TTL has expired, with the
514           following actions to send an ICMP time exceeded reply:
515         </p>
516
517         <pre>
518 icmp4 {
519     icmp4.type = 11; /* Time exceeded. */
520     icmp4.code = 0;  /* TTL exceeded in transit. */
521     ip4.dst = ip4.src;
522     ip4.src = <var>A</var>;
523     ip.ttl = 255;
524     next;
525 };
526         </pre>
527
528         <p>
529           Not yet implemented.
530         </p>
531       </li>
532
533       <li>
534         TTL discard.  A priority-30 flow with match <code>ip.ttl == {0,
535         1}</code> and actions <code>drop;</code> drops other packets whose TTL
536         has expired, that should not receive a ICMP error reply (i.e. fragments
537         with nonzero offset).
538       </li>
539
540       <li>
541         Next table.  A priority-0 flows match all packets that aren't already
542         handled and uses actions <code>next;</code> to feed them to the ingress
543         table for routing.
544       </li>
545     </ul>
546
547     <h3>Ingress Table 2: IP Routing</h3>
548
549     <p>
550       A packet that arrives at this table is an IP packet that should be routed
551       to the address in <code>ip4.dst</code>.  This table implements IP
552       routing, setting <code>reg0</code> to the next-hop IP address (leaving
553       <code>ip4.dst</code>, the packet's final destination, unchanged) and
554       advances to the next table for ARP resolution.  It also sets
555       <code>reg1</code> to the IP address owned by the selected router port
556       (which is used later in table 4 as the IP source address for an ARP
557       request, if needed).
558     </p>
559
560     <p>
561       This table contains the following logical flows:
562     </p>
563
564     <ul>
565       <li>
566         <p>
567           Routing table.  For each route to IPv4 network <var>N</var> with
568           netmask <var>M</var>, on router port <var>P</var> with IP address
569           <var>A</var> and Ethernet
570           address <var>E</var>, a logical flow with match <code>ip4.dst ==
571           <var>N</var>/<var>M</var></code>, whose priority is the number of
572           1-bits in <var>M</var>, has the following actions:
573         </p>
574
575         <pre>
576 ip.ttl--;
577 reg0 = <var>G</var>;
578 reg1 = <var>A</var>;
579 eth.src = <var>E</var>;
580 outport = <var>P</var>;
581 next;
582         </pre>
583
584         <p>
585           (Ingress table 1 already verified that <code>ip.ttl--;</code> will
586           not yield a TTL exceeded error.)
587         </p>
588
589         <p>
590           If the route has a gateway, <var>G</var> is the gateway IP address,
591           otherwise it is <code>ip4.dst</code>.
592         </p>
593       </li>
594
595       <li>
596         <p>
597           Destination unreachable.  For each router port <var>P</var>, which
598           owns IP address <var>A</var>, a priority-0 logical flow with match
599           <code>in_port == <var>P</var> &amp;&amp; !ip.later_frag &amp;&amp;
600           !icmp</code> has the following actions:
601         </p>
602
603         <pre>
604 icmp4 {
605     icmp4.type = 3; /* Destination unreachable. */
606     icmp4.code = 0; /* Network unreachable. */
607     ip4.dst = ip4.src;
608     ip4.src = <var>A</var>;
609     ip.ttl = 255;
610     next(2);
611 };
612         </pre>
613
614         <p>
615           (The <code>!icmp</code> check prevents recursion if the destination
616           unreachable message itself cannot be routed.)
617         </p>
618
619         <p>
620           These flows are omitted if the logical router has a default route,
621           that is, a route with netmask 0.0.0.0.
622         </p>
623       </li>
624     </ul>
625
626     <h3>Ingress Table 3: ARP Resolution</h3>
627
628     <p>
629       Any packet that reaches this table is an IP packet whose next-hop IP
630       address is in <code>reg0</code>.  (<code>ip4.dst</code> is the final
631       destination.)  This table resolves the IP address in <code>reg0</code>
632       into an output port in <code>outport</code> and an Ethernet address in
633       <code>eth.dst</code>, using the following flows:
634     </p>
635
636     <ul>
637       <li>
638         <p>
639           Static MAC bindings.  MAC bindings can be known statically based on
640           data in the <code>OVN_Northbound</code> database.  For router ports
641           connected to logical switches, MAC bindings can be known statically
642           from the <code>addresses</code> column in the
643           <code>Logical_Port</code> table.  For router ports connected to other
644           logical routers, MAC bindings can be known statically from the
645           <code>mac</code> and <code>network</code> column in the
646           <code>Logical_Router_Port</code> table.
647         </p>
648
649         <p>
650           For each IP address <var>A</var> whose host is known to have Ethernet
651           address <var>E</var> on router port <var>P</var>, a priority-100 flow
652           with match <code>outport === <var>P</var> &amp;&amp; reg0 ==
653           <var>A</var></code> has actions <code>eth.dst = <var>E</var>;
654           next;</code>.
655         </p>
656       </li>
657
658       <li>
659         <p>
660           Dynamic MAC bindings.  This flows resolves MAC-to-IP bindings that
661           have become known dynamically through ARP.  (The next table will
662           issue an ARP request for cases where the binding is not yet known.)
663         </p>
664
665         <p>
666           A priority-0 logical flow with match <code>1</code> has actions
667           <code>get_arp(outport, reg0); next;</code>.
668         </p>
669       </li>
670     </ul>
671
672     <h3>Ingress Table 4: ARP Request</h3>
673
674     <p>
675       In the common case where the Ethernet destination has been resolved, this
676       table outputs the packet.  Otherwise, it composes and sends an ARP
677       request.  It holds the following flows:
678     </p>
679
680     <ul>
681       <li>
682         <p>
683           Unknown MAC address.  A priority-100 flow with match <code>eth.dst ==
684           00:00:00:00:00:00</code> has the following actions:
685         </p>
686
687         <pre>
688 arp {
689     eth.dst = ff:ff:ff:ff:ff:ff;
690     arp.spa = reg1;
691     arp.op = 1;  /* ARP request. */
692     output;
693 };
694         </pre>
695
696         <p>
697           (Ingress table 2 initialized <code>reg1</code> with the IP address
698           owned by <code>outport</code>.)
699         </p>
700
701         <p>
702           The IP packet that triggers the ARP request is dropped.
703         </p>
704       </li>
705
706       <li>
707         Known MAC address.  A priority-0 flow with match <code>1</code> has
708         actions <code>output;</code>.
709       </li>
710     </ul>
711
712     <h3>Egress Table 0: Delivery</h3>
713
714     <p>
715       Packets that reach this table are ready for delivery.  It contains
716       priority-100 logical flows that match packets on each enabled logical
717       router port, with action <code>output;</code>.
718     </p>
719
720 </manpage>