OVN (Open Virtual Network)

OVN (Open Virtual Network) is a series of userspace daemons that provides a high-level abstraction for virtual networking. Instead of managing individual OpenFlow rules, OVN allows users to work with logical routers and logical switches.

Key characteristics:

• Abstraction Layer: Translates virtual network configuration into OpenFlow for Open vSwitch.
• Userspace Execution: Runs entirely in userspace and does not require kernel modules.
• Core Features: Provides distributed virtual routers, distributed logical switches, Access Control Lists (ACLs), DHCP, and DNS services.
• Target Audience: Primarily intended for use by Cloud Management Software (CMS).

OVN uses Autotest to generate its test suite. The test code is structured such that the top-level file tests/testsuite.at is expanded into a shell script that executes all OVN tests.

To write tests, you should understand that:

• All test code resides in the tests/ directory at the repository root.
• Files ending in .at contain the actual test logic.
• Files ending in -macros.at contain macros and shell functions used to assist in test writing.
• Macros are named using ALL_UPPERCASE convention.
• Functions are named using lowercase convention.
• Most macros and functions are implicitly available in all test files when running the suite via make check.

The OVN documentation is categorized into several functional areas to help you find specific information:

• Installation guides: Platform-specific instructions for installing OVN.
• Tutorials: Step-by-step configuration in sandboxed environments.
• Topic guides: High-level overviews of OVS and OVN internals and operations.
• How-to guides: Advanced recipes and specific use-case implementations.
• Frequently Asked Questions (FAQ): Insights into configuration and operational topics.
• Architecture: Information on system integration.
• Testing: Documentation regarding testing procedures.
• Packaging: Specific guides for Debian and Fedora packaging.

OVN (Open Virtual Network) is a system designed to support virtual network abstraction. It complements Open vSwitch (OVS) by providing native support for virtual network abstractions such as:

• Distributed virtual routers
• Distributed logical switches
• Access Control Lists (ACLs)
• DHCP
• DNS server

OVN is primarily intended for use by Cloud Management Software (CMS). For architectural details, refer to the ovn-architecture(7) manpage.

The OVN distribution consists of several key daemons and utilities used to manage and debug logical networks:

• ovn-northd: A centralized daemon that translates northbound configuration (from a CMS) into logical flows for the southbound database.
• ovn-controller: A daemon running on every hypervisor in the cluster. It translates logical flows from the southbound database into OpenFlow for Open vSwitch and handles traffic like DHCP and DNS.
• ovn-nbctl: A command-line tool for interfacing with the northbound database.
• ovn-sbctl: A command-line tool for interfacing with the southbound database.
• ovn-trace: A debugging utility used to trace packets through the logical network.
• ovn-debug: A tool designed to simplify the debugging of OVN setups.

Traffic from external logical ports enters via the localnet port and is processed in Ingress Table 32. This table prevents incorrect ARP/NS responses from non-resident chassis.

• Drop ARP/NS for non-resident routers: For an external port not residing on the current chassis, OVN drops ARP/IPv6 NS requests destined for the logical switch's router IP(s). This ensures only the chassis claiming the external port responds to the router.
• Drop packets to router MAC: Drops packets where inport == external && eth.src == E && eth.dst == R && !is_chassis_resident("external"), where E is the external port MAC and R is the router port MAC.

For distributed logical routers with a gateway chassis, Ingress Table 25 redirects traffic to the chassisredirect (CR) port. This is used for:

• Load Balancing: Redirects backend IPv4/IPv6 addresses (defined in load balancing rules) to the chassisredirect port.
• Distributed NAT: Redirects traffic matching distributed NAT rules to the gateway port. For distributed NAT, traffic is managed locally by setting reg1 to the NAT external IP and eth.src to the NAT external MAC.
• Stateless NAT: For dnat_and_snat rules with stateless=true, traffic destined for allowed_ext_ips is redirected to the chassisredirect port, while traffic for exempted_ext_ips is dropped.
• Unclaimed Ports: Drops traffic if the NAT logical port is a virtual port not yet claimed by any chassis.

OVN handles packets with expired TTL (Time To Live) using priority-31 flows. For each router port P with IP A, if a packet matches inport == P && ip.ttl == {0, 1} && !ip.later_frag, OVN sends an ICMP Time Exceeded reply.

IPv4 Time Exceeded Actions:

icmp4 {
          icmp4.type = 11; /* Time exceeded. */
          icmp4.code = 0;  /* TTL exceeded in transit. */
          ip4.dst = ip4.src;
          ip4.src = A;
          ip.ttl = 254;
          next;
      };

IPv6 Time Exceeded Actions:

icmp6 {
          icmp6.type = 3; /* Time exceeded. */
          icmp6.code = 0;  /* TTL exceeded in transit. */
          ip6.dst = ip6.src;
          ip6.src = A;
          ip.ttl = 254;
          next;
      };

Note: A priority-32 flow drops multicast packets with expired TTL to avoid sending ICMP time exceeded messages for multicast.

OVN uses specific register bits to communicate ACL verdicts through the logical pipeline. These bits are set in the ACL eval stage and interpreted by subsequent tables to decide whether to allow, drop, or reject a packet.

Key verdict bits:

• Allow bit: reg8[16] is set for allow-type ACLs.
• Drop bit: reg8[17] is set for drop ACLs.
• Reject bit: reg8[17] is set for reject ACLs.

When using ACLs with a tier value, the current tier counter is supplied in reg8[30..31] and is matched against the ACL's configured tier.

OVN documentation is primarily written in reStructuredText (rST) and processed using Sphinx. Sphinx is used to handle cross-referencing, indexing, and converting rST into various output formats. Man pages are the only exception to the rST standard.

When contributing documentation, follow the heading level convention to ensure proper rendering:

=======  Heading 0 (reserved for the title in a document)
-------  Heading 1
~~~~~~~  Heading 2
+++++++  Heading 3
'''''''  Heading 4

Avoid using heading levels deeper than Heading 4, as they may not render correctly.