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           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> &amp;&amp; arp.tpa ==
 405           <var>A</var> &amp;&amp; arp.op == 1</code> (ARP request) with the
 406           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         <p>
 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.
 429         </p>
 430
 431         <p>
 432           These flows should not match IP fragments with nonzero offset.
 433         </p>
 434
 435         <p>
 436           Details TBD.  Not yet implemented.
 437         </p>
 438       </li>
 439
 440       <li>
 441         <p>
 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
 445           reply.
 446         </p>
 447
 448         <p>
 449           These flows should not match IP fragments with nonzero offset.
 450         </p>
 451
 452         <p>
 453           Details TBD.  Not yet implemented.
 454         </p>
 455       </li>
 456
 457       <li>
 458         <p>
 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.
 462         </p>
 463
 464         <p>
 465           These flows should not match IP fragments with nonzero offset.
 466         </p>
 467
 468         <p>
 469           Details TBD.  Not yet implemented.
 470         </p>
 471       </li>
 472
 473       <li>
 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.
 480       </li>
 481     </ul>
 482
 483     <p>
 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:
 487     </p>
 488
 489     <ul>
 490       <li>
 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.
 494       </li>
 495
 496       <li>
 497         Drop IP multicast.  A priority-50 flow with match
 498         <code>ip4.mcast</code> drops IP multicast traffic.
 499       </li>
 500
 501       <li>
 502         <p>
 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> &amp;&amp; ip.ttl == {0, 1} &amp;&amp;
 506           !ip.later_frag</code> matches packets whose TTL has expired, with the
 507           following actions to send an ICMP time exceeded reply:
 508         </p>
 509
 510         <pre>
 511 icmp4 {
 512     icmp4.type = 11; /* Time exceeded. */
 513     icmp4.code = 0;  /* TTL exceeded in transit. */
 514     ip4.dst = ip4.src;
 515     ip4.src = <var>A</var>;
 516     ip.ttl = 255;
 517     next;
 518 };
 519         </pre>
 520
 521         <p>
 522           Not yet implemented.
 523         </p>
 524       </li>
 525
 526       <li>
 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).
 531       </li>
 532
 533       <li>
 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
 536         table for routing.
 537       </li>
 538     </ul>
 539
 540     <h3>Ingress Table 2: IP Routing</h3>
 541
 542     <p>
 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.
 548     </p>
 549
 550     <p>
 551       This table contains the following logical flows:
 552     </p>
 553
 554     <ul>
 555       <li>
 556         <p>
 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:
 561         </p>
 562
 563         <pre>
 564 ip.ttl--;
 565 reg0 = <var>G</var>;
 566 next;
 567         </pre>
 568
 569         <p>
 570           (Ingress table 1 already verified that <code>ip.ttl--;</code> will
 571           not yield a TTL exceeded error.)
 572         </p>
 573
 574         <p>
 575           If the route has a gateway, <var>G</var> is the gateway IP address,
 576           otherwise it is <code>ip4.dst</code>.
 577         </p>
 578       </li>
 579
 580       <li>
 581         <p>
 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> &amp;&amp; !ip.later_frag &amp;&amp;
 585           !icmp</code> has the following actions:
 586         </p>
 587
 588         <pre>
 589 icmp4 {
 590     icmp4.type = 3; /* Destination unreachable. */
 591     icmp4.code = 0; /* Network unreachable. */
 592     ip4.dst = ip4.src;
 593     ip4.src = <var>A</var>;
 594     ip.ttl = 255;
 595     next(2);
 596 };
 597         </pre>
 598
 599         <p>
 600           (The <code>!icmp</code> check prevents recursion if the destination
 601           unreachable message itself cannot be routed.)
 602         </p>
 603
 604         <p>
 605           These flows are omitted if the logical router has a default route,
 606           that is, a route with netmask 0.0.0.0.
 607         </p>
 608       </li>
 609     </ul>
 610
 611     <h3>Ingress Table 3: ARP Resolution</h3>
 612
 613     <p>
 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:
 619     </p>
 620
 621     <ul>
 622       <li>
 623         <p>
 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
 628           actions:
 629         </p>
 630
 631         <pre>
 632 eth.src = <var>PE</var>;
 633 eth.dst = <var>HE</var>;
 634 outport = <var>P</var>;
 635 output;
 636         </pre>
 637
 638         <p>
 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>
 646           table.
 647         </p>
 648       </li>
 649
 650       <li>
 651         <p>
 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:
 658         </p>
 659
 660         <pre>
 661 arp {
 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>;
 667     arp.tpa = ip4.dst;
 668     arp.op = 1;  /* ARP request. */
 669     outport = <var>P</var>;
 670     output;
 671 };
 672         </pre>
 673
 674         <p>
 675           TBD: How to install MAC bindings when an ARP response comes back.
 676           (Implement a "learn" action?)
 677         </p>
 678
 679         <p>
 680           Not yet implemented.
 681         </p>
 682       </li>
 683     </ul>
 684
 685     <h3>Egress Table 0: Delivery</h3>
 686
 687     <p>
 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>.
 691     </p>
 692
 693 </manpage>