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: Destination Lookup</h3>
 199
 200     <p>
 201       This table implements switching behavior.  It contains these logical
 202       flows:
 203     </p>
 204
 205     <ul>
 206       <li>
 207         <p>
 208           Priority-150 flows that matches ARP requests to each known IP address
 209           <var>A</var> of logical port <var>P</var>, and respond with ARP
 210           replies directly with corresponding Ethernet address <var>E</var>:
 211         </p>
 212
 213         <pre>
 214 eth.dst = eth.src;
 215 eth.src = <var>E</var>;
 216 arp.op = 2; /* ARP reply. */
 217 arp.tha = arp.sha;
 218 arp.sha = <var>E</var>;
 219 arp.tpa = arp.spa;
 220 arp.spa = <var>A</var>;
 221 outport = <var>P</var>;
 222 inport = ""; /* Allow sending out inport. */
 223 output;
 224         </pre>
 225
 226         <p>
 227           These flows are omitted for logical ports (other than router ports)
 228           that are down.
 229         </p>
 230       </li>
 231
 232       <li>
 233         A priority-100 flow that outputs all packets with an Ethernet broadcast
 234         or multicast <code>eth.dst</code> to the <code>MC_FLOOD</code>
 235         multicast group, which <code>ovn-northd</code> populates with all
 236         enabled logical ports.
 237       </li>
 238
 239       <li>
 240         One priority-50 flow that matches each known Ethernet address against
 241         <code>eth.dst</code> and outputs the packet to the single associated
 242         output port.
 243       </li>
 244
 245       <li>
 246         One priority-0 fallback flow that matches all packets and outputs them
 247         to the <code>MC_UNKNOWN</code> multicast group, which
 248         <code>ovn-northd</code> populates with all enabled logical ports that
 249         accept unknown destination packets.  As a small optimization, if no
 250         logical ports accept unknown destination packets,
 251         <code>ovn-northd</code> omits this multicast group and logical flow.
 252       </li>
 253     </ul>
 254
 255     <h3>Egress Table 0: <code>to-lport</code> Pre-ACLs</h3>
 256
 257     <p>
 258       This is similar to ingress table 1 except for <code>to-lport</code>
 259       traffic.
 260     </p>
 261
 262     <h3>Egress Table 1: <code>to-lport</code> ACLs</h3>
 263
 264     <p>
 265       This is similar to ingress table 2 except for <code>to-lport</code> ACLs.
 266     </p>
 267
 268     <h3>Egress Table 2: Egress Port Security</h3>
 269
 270     <p>
 271       This is similar to the ingress port security logic in ingress table 0,
 272       but with important differences.  Most obviously, <code>outport</code> and
 273       <code>eth.dst</code> are checked instead of <code>inport</code> and
 274       <code>eth.src</code>.  Second, packets directed to broadcast or multicast
 275       <code>eth.dst</code> are always accepted instead of being subject to the
 276       port security rules; this is implemented through a priority-100 flow that
 277       matches on <code>eth.mcast</code> with action <code>output;</code>.
 278       Finally, to ensure that even broadcast and multicast packets are not
 279       delivered to disabled logical ports, a priority-150 flow for each
 280       disabled logical <code>outport</code> overrides the priority-100 flow
 281       with a <code>drop;</code> action.
 282     </p>
 283
 284     <h2>Logical Router Datapaths</h2>
 285
 286     <h3>Ingress Table 0: L2 Admission Control</h3>
 287
 288     <p>
 289       This table drops packets that the router shouldn't see at all based on
 290       their Ethernet headers.  It contains the following flows:
 291     </p>
 292
 293     <ul>
 294       <li>
 295         Priority-100 flows to drop packets with VLAN tags or multicast Ethernet
 296         source addresses.
 297       </li>
 298
 299       <li>
 300         For each enabled router port <var>P</var> with Ethernet address
 301         <var>E</var>, a priority-50 flow that matches <code>inport ==
 302         <var>P</var> &amp;&amp; (eth.mcast || eth.dst ==
 303         <var>E</var></code>), with action <code>next;</code>.
 304       </li>
 305     </ul>
 306
 307     <p>
 308       Other packets are implicitly dropped.
 309     </p>
 310
 311     <h3>Ingress Table 1: IP Input</h3>
 312
 313     <p>
 314       This table is the core of the logical router datapath functionality.  It
 315       contains the following flows to implement very basic IP host
 316       functionality.
 317     </p>
 318
 319     <ul>
 320       <li>
 321         <p>
 322           L3 admission control: A priority-100 flow drops packets that match
 323           any of the following:
 324         </p>
 325
 326         <ul>
 327           <li>
 328             <code>ip4.src[28..31] == 0xe</code> (multicast source)
 329           </li>
 330           <li>
 331             <code>ip4.src == 255.255.255.255</code> (broadcast source)
 332           </li>
 333           <li>
 334             <code>ip4.src == 127.0.0.0/8 || ip4.dst == 127.0.0.0/8</code>
 335             (localhost source or destination)
 336           </li>
 337           <li>
 338             <code>ip4.src == 0.0.0.0/8 || ip4.dst == 0.0.0.0/8</code> (zero
 339             network source or destination)
 340           </li>
 341           <li>
 342             <code>ip4.src</code> is any IP address owned by the router.
 343           </li>
 344           <li>
 345             <code>ip4.src</code> is the broadcast address of any IP network
 346             known to the router.
 347           </li>
 348         </ul>
 349       </li>
 350
 351       <li>
 352         <p>
 353           ICMP echo reply.  These flows reply to ICMP echo requests received
 354           for the router's IP address.  Let <var>A</var> be an IP address or
 355           broadcast address owned by a router port.  Then, for each
 356           <var>A</var>, a priority-90 flow matches on <code>ip4.dst ==
 357           <var>A</var></code> and <code>icmp4.type == 8 &amp;&amp; icmp4.code
 358           == 0</code> (ICMP echo request).  These flows use the following
 359           actions where, if <var>A</var> is unicast, then <var>S</var> is
 360           <var>A</var>, and if <var>A</var> is broadcast, <var>S</var> is the
 361           router's IP address in <var>A</var>'s network:
 362         </p>
 363
 364         <pre>
 365 ip4.dst = ip4.src;
 366 ip4.src = <var>S</var>;
 367 ip.ttl = 255;
 368 icmp4.type = 0;
 369 inport = ""; /* Allow sending out inport. */
 370 next;
 371         </pre>
 372
 373         <p>
 374           Similar flows match on <code>ip4.dst == 255.255.255.255</code> and
 375           each individual <code>inport</code>, and use the same actions in
 376           which <var>S</var> is a function of <code>inport</code>.
 377         </p>
 378       </li>
 379
 380       <li>
 381         <p>
 382           ARP reply.  These flows reply to ARP requests for the router's own IP
 383           address.  For each router port <var>P</var> that owns IP address
 384           <var>A</var> and Ethernet address <var>E</var>, a priority-90 flow
 385           matches <code>inport == <var>P</var> &amp;&amp; arp.tpa ==
 386           <var>A</var> &amp;&amp; arp.op == 1</code> (ARP request) with the
 387           following actions:
 388         </p>
 389
 390         <pre>
 391 eth.dst = eth.src;
 392 eth.src = <var>E</var>;
 393 arp.op = 2; /* ARP reply. */
 394 arp.tha = arp.sha;
 395 arp.sha = <var>E</var>;
 396 arp.tpa = arp.spa;
 397 arp.spa = <var>A</var>;
 398 outport = <var>P</var>;
 399 inport = ""; /* Allow sending out inport. */
 400 output;
 401         </pre>
 402       </li>
 403
 404       <li>
 405         <p>
 406           UDP port unreachable.  Priority-80 flows generate ICMP port
 407           unreachable messages in reply to UDP datagrams directed to the
 408           router's IP address.  The logical router doesn't accept any UDP
 409           traffic so it always generates such a reply.
 410         </p>
 411
 412         <p>
 413           These flows should not match IP fragments with nonzero offset.
 414         </p>
 415
 416         <p>
 417           Details TBD.  Not yet implemented.
 418         </p>
 419       </li>
 420
 421       <li>
 422         <p>
 423           TCP reset.  Priority-80 flows generate TCP reset messages in reply to
 424           TCP datagrams directed to the router's IP address.  The logical
 425           router doesn't accept any TCP traffic so it always generates such a
 426           reply.
 427         </p>
 428
 429         <p>
 430           These flows should not match IP fragments with nonzero offset.
 431         </p>
 432
 433         <p>
 434           Details TBD.  Not yet implemented.
 435         </p>
 436       </li>
 437
 438       <li>
 439         <p>
 440           Protocol unreachable.  Priority-70 flows generate ICMP protocol
 441           unreachable messages in reply to packets directed to the router's IP
 442           address on IP protocols other than UDP, TCP, and ICMP.
 443         </p>
 444
 445         <p>
 446           These flows should not match IP fragments with nonzero offset.
 447         </p>
 448
 449         <p>
 450           Details TBD.  Not yet implemented.
 451         </p>
 452       </li>
 453
 454       <li>
 455         Drop other IP traffic to this router.  These flows drop any other
 456         traffic destined to an IP address of this router that is not already
 457         handled by one of the flows above, which amounts to ICMP (other than
 458         echo requests) and fragments with nonzero offsets.  For each IP address
 459         <var>A</var> owned by the router, a priority-60 flow matches
 460         <code>ip4.dst == <var>A</var></code> and drops the traffic.
 461       </li>
 462     </ul>
 463
 464     <p>
 465       The flows above handle all of the traffic that might be directed to the
 466       router itself.  The following flows (with lower priorities) handle the
 467       remaining traffic, potentially for forwarding:
 468     </p>
 469
 470     <ul>
 471       <li>
 472         Drop Ethernet local broadcast.  A priority-50 flow with match
 473         <code>eth.bcast</code> drops traffic destined to the local Ethernet
 474         broadcast address.  By definition this traffic should not be forwarded.
 475       </li>
 476
 477       <li>
 478         Drop IP multicast.  A priority-50 flow with match
 479         <code>ip4.mcast</code> drops IP multicast traffic.
 480       </li>
 481
 482       <li>
 483         <p>
 484           ICMP time exceeded.  For each router port <var>P</var>, whose IP
 485           address is <var>A</var>, a priority-40 flow with match <code>inport
 486           == <var>P</var> &amp;&amp; ip.ttl == {0, 1} &amp;&amp;
 487           !ip.later_frag</code> matches packets whose TTL has expired, with the
 488           following actions to send an ICMP time exceeded reply:
 489         </p>
 490
 491         <pre>
 492 icmp4 {
 493     icmp4.type = 11; /* Time exceeded. */
 494     icmp4.code = 0;  /* TTL exceeded in transit. */
 495     ip4.dst = ip4.src;
 496     ip4.src = <var>A</var>;
 497     ip.ttl = 255;
 498     next;
 499 };
 500         </pre>
 501
 502         <p>
 503           Not yet implemented.
 504         </p>
 505       </li>
 506
 507       <li>
 508         TTL discard.  A priority-30 flow with match <code>ip.ttl == {0,
 509         1}</code> and actions <code>drop;</code> drops other packets whose TTL
 510         has expired, that should not receive a ICMP error reply (i.e. fragments
 511         with nonzero offset).
 512       </li>
 513
 514       <li>
 515         Next table.  A priority-0 flows match all packets that aren't already
 516         handled and uses actions <code>next;</code> to feed them to the ingress
 517         table for routing.
 518       </li>
 519     </ul>
 520
 521     <h3>Ingress Table 2: IP Routing</h3>
 522
 523     <p>
 524       A packet that arrives at this table is an IP packet that should be routed
 525       to the address in <code>ip4.dst</code>.  This table implements IP
 526       routing, setting <code>reg0</code> to the next-hop IP address (leaving
 527       <code>ip4.dst</code>, the packet's final destination, unchanged) and
 528       advances to the next table for ARP resolution.
 529     </p>
 530
 531     <p>
 532       This table contains the following logical flows:
 533     </p>
 534
 535     <ul>
 536       <li>
 537         <p>
 538           Routing table.  For each route to IPv4 network <var>N</var> with
 539           netmask <var>M</var>, a logical flow with match <code>ip4.dst ==
 540           <var>N</var>/<var>M</var></code>, whose priority is the number of
 541           1-bits in <var>M</var>, has the following actions:
 542         </p>
 543
 544         <pre>
 545 ip.ttl--;
 546 reg0 = <var>G</var>;
 547 next;
 548         </pre>
 549
 550         <p>
 551           (Ingress table 1 already verified that <code>ip.ttl--;</code> will
 552           not yield a TTL exceeded error.)
 553         </p>
 554
 555         <p>
 556           If the route has a gateway, <var>G</var> is the gateway IP address,
 557           otherwise it is <code>ip4.dst</code>.
 558         </p>
 559       </li>
 560
 561       <li>
 562         <p>
 563           Destination unreachable.  For each router port <var>P</var>, which
 564           owns IP address <var>A</var>, a priority-0 logical flow with match
 565           <code>in_port == <var>P</var> &amp;&amp; !ip.later_frag &amp;&amp;
 566           !icmp</code> has the following actions:
 567         </p>
 568
 569         <pre>
 570 icmp4 {
 571     icmp4.type = 3; /* Destination unreachable. */
 572     icmp4.code = 0; /* Network unreachable. */
 573     ip4.dst = ip4.src;
 574     ip4.src = <var>A</var>;
 575     ip.ttl = 255;
 576     next(2);
 577 };
 578         </pre>
 579
 580         <p>
 581           (The <code>!icmp</code> check prevents recursion if the destination
 582           unreachable message itself cannot be routed.)
 583         </p>
 584
 585         <p>
 586           These flows are omitted if the logical router has a default route,
 587           that is, a route with netmask 0.0.0.0.
 588         </p>
 589       </li>
 590     </ul>
 591
 592     <h3>Ingress Table 3: ARP Resolution</h3>
 593
 594     <p>
 595       Any packet that reaches this table is an IP packet whose next-hop IP
 596       address is in <code>reg0</code>.  (<code>ip4.dst</code> is the final
 597       destination.)  This table resolves the IP address in <code>reg0</code>
 598       into an output port in <code>outport</code> and an Ethernet address in
 599       <code>eth.dst</code>, using the following flows:
 600     </p>
 601
 602     <ul>
 603       <li>
 604         <p>
 605           Known MAC bindings.  For each IP address <var>A</var> whose host is
 606           known to have Ethernet address <var>HE</var> and reside on router
 607           port <var>P</var> with Ethernet address <var>PE</var>, a priority-200
 608           flow with match <code>reg0 == <var>A</var></code> has the following
 609           actions:
 610         </p>
 611
 612         <pre>
 613 eth.src = <var>PE</var>;
 614 eth.dst = <var>HE</var>;
 615 outport = <var>P</var>;
 616 output;
 617         </pre>
 618
 619         <p>
 620           MAC bindings can be known statically based on data in the
 621           <code>OVN_Northbound</code> database.  For router ports connected to
 622           logical switches, MAC bindings can be known statically from the
 623           <code>addresses</code> column in the <code>Logical_Port</code> table.
 624           For router ports connected to other logical routers, MAC bindings can
 625           be known statically from the <code>mac</code> and
 626           <code>network</code> column in the <code>Logical_Router_Port</code>
 627           table.
 628         </p>
 629       </li>
 630
 631       <li>
 632         <p>
 633           Unknown MAC bindings.  For each non-gateway route to IPv4 network
 634           <var>N</var> with netmask <var>M</var> on router port <var>P</var>
 635           that owns IP address <var>A</var> and Ethernet address <var>E</var>,
 636           a logical flow with match <code>ip4.dst ==
 637           <var>N</var>/<var>M</var></code>, whose priority is the number of
 638           1-bits in <var>M</var>, has the following actions:
 639         </p>
 640
 641         <pre>
 642 arp {
 643     eth.dst = ff:ff:ff:ff:ff:ff;
 644     eth.src = <var>E</var>;
 645     arp.sha = <var>E</var>;
 646     arp.tha = 00:00:00:00:00:00;
 647     arp.spa = <var>A</var>;
 648     arp.tpa = ip4.dst;
 649     arp.op = 1;  /* ARP request. */
 650     outport = <var>P</var>;
 651     output;
 652 };
 653         </pre>
 654
 655         <p>
 656           TBD: How to install MAC bindings when an ARP response comes back.
 657           (Implement a "learn" action?)
 658         </p>
 659
 660         <p>
 661           Not yet implemented.
 662         </p>
 663       </li>
 664     </ul>
 665
 666     <h3>Egress Table 0: Delivery</h3>
 667
 668     <p>
 669       Packets that reach this table are ready for delivery.  It contains
 670       priority-100 logical flows that match packets on each enabled logical
 671       router port, with action <code>output;</code>.
 672     </p>
 673
 674 </manpage>