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