[cascardo/ovs.git] / ovn / ovn-nb.xml

<?xml version="1.0" encoding="utf-8"?>
<database name="ovn-nb" title="OVN Northbound Database">
  <p>
    This database is the interface between OVN and the cloud management system
    (CMS), such as OpenStack, running above it.  The CMS produces almost all of
    the contents of the database.  The <code>ovn-northd</code> program
    monitors the database contents, transforms it, and stores it into the <ref
    db="OVN_Southbound"/> database.
  </p>

  <p>
    We generally speak of ``the'' CMS, but one can imagine scenarios in
    which multiple CMSes manage different parts of an OVN deployment.
  </p>

  <h2>External IDs</h2>

  <p>
    Each of the tables in this database contains a special column, named
    <code>external_ids</code>.  This column has the same form and purpose each
    place it appears.
  </p>

  <dl>
    <dt><code>external_ids</code>: map of string-string pairs</dt>
    <dd>
      Key-value pairs for use by the CMS.  The CMS might use certain pairs, for
      example, to identify entities in its own configuration that correspond to
      those in this database.
    </dd>
  </dl>

  <table name="Logical_Switch" title="L2 logical switch">
    <p>
      Each row represents one L2 logical switch.
    </p>

    <column name="name">
      <p>
        A name for the logical switch.  This name has no special meaning or purpose
        other than to provide convenience for human interaction with the ovn-nb
        database.  There is no requirement for the name to be unique.  The
        logical switch's UUID should be used as the unique identifier.
      </p>
    </column>

    <column name="ports">
      <p>
        The logical ports connected to the logical switch.
      </p>

      <p>
        It is an error for multiple logical switches to include the same
        logical port.
      </p>
    </column>

    <column name="router_port">
      <p>
        The router port to which this logical switch is connected, or empty if
        this logical switch is not connected to any router.  A switch may be
        connected to at most one logical router, but this is not a significant
        restriction because logical routers may be connected into arbitrary
        topologies.
      </p>

      <p>
        It is an error for multiple logical switches to refer to the same
        router port.
      </p>
    </column>

    <column name="acls">
      Access control rules that apply to packets within the logical switch.
    </column>

    <group title="Common Columns">
      <column name="external_ids">
        See <em>External IDs</em> at the beginning of this document.
      </column>
    </group>
  </table>

  <table name="Logical_Port" title="L2 logical switch port">
    <p>
      A port within an L2 logical switch.
    </p>

    <column name="name">
      <p>
      The logical port name.
      </p>

      <p>
      For entities (VMs or containers) that are spawned in the hypervisor,
      the name used here must match those used in the <ref key="iface-id"
      table="Interface" column="external_ids" db="Open_vSwitch"/> in the
      <ref db="Open_vSwitch"/> database's <ref table="Interface"
      db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
      table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
      key to identify the network interface of that entity.
      </p>

      <p>
      For containers that are spawned inside a VM, the name can be
      any unique identifier.  In such a case, <ref column="parent_name"/>
      must be populated.
      </p>
    </column>

    <column name="type">
      <p>
      Specify a type for this logical port.  Logical ports can be used to model
      other types of connectivity into an OVN logical switch.  Leaving this column
      blank maintains the default logical port behavior.
      </p>

      <p>
        When this column is set to <code>localnet</code>, this logical port
        represents a connection to a locally accessible network from each
        <code>ovn-controller</code> instance.  A logical switch can only have a
        single <code>localnet</code> port attached and at most one regular
        logical port.  This is used to model direct connectivity to an existing
        network.
      </p>
    </column>

    <column name="options">
      <p>
        This column provides key/value settings specific to the logical port
        <ref column="type"/>.
      </p>

      <p>
        When <ref column="type"/> is set to <code>localnet</code>, you must set
        the option <code>network_name</code>.  <code>ovn-controller</code> uses
        local configuration to determine exactly how to connect to this locally
        accessible network.
      </p>
    </column>

    <column name="parent_name">
      When <ref column="name"/> identifies the interface of a container
      spawned inside a tenant VM, this column represents the VM interface
      through which the container interface sends its network traffic.
      The name used here must match those used in the <ref key="iface-id"
      table="Interface" column="external_ids" db="Open_vSwitch"/> in the
      <ref db="Open_vSwitch"/> table, because hypervisors in this case use
      <ref key="iface-id" table="Interface" column="external_ids"
      db="Open_vSwitch"/> as a lookup key to identify the network interface
      of the tenant VM.
    </column>

    <column name="tag">
      When <ref column="name"/> identifies the interface of a container
      spawned inside a tenant VM, this column identifies the VLAN tag in
      the network traffic associated with that container's network interface.
      When there are multiple container interfaces inside a VM, all of
      them send their network traffic through a single VM network interface and
      this value helps OVN identify the correct container interface.
    </column>

    <column name="up">
      This column is populated by <code>ovn-northd</code>, rather than by
      the CMS plugin as is most of this database.  When a logical port is bound
      to a physical location in the OVN Southbound database <ref
      db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
      sets this column to <code>true</code>; otherwise, or if the port
      becomes unbound later, it sets it to <code>false</code>.  This
      allows the CMS to wait for a VM's (or container's) networking to
      become active before it allows the VM (or container) to start.
    </column>

    <column name="enabled">
      This column is used to administratively set port state.  If this column is
      empty or is set to <code>true</code>, the port is enabled.  If this column
      is set to <code>false</code>, the port is disabled.  A disabled port has all
      ingress and egress traffic dropped.
    </column>

    <column name="macs">
      The logical port's own Ethernet address or addresses, each in the form
      <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
      Like a physical Ethernet NIC, a logical port ordinarily has a single
      fixed Ethernet address.  The string <code>unknown</code> is also allowed
      to indicate that the logical port has an unknown set of (additional)
      source addresses.
    </column>

    <column name="port_security">
      <p>
        A set of L2 (Ethernet) addresses
        from which the logical port is allowed to send packets and to which it
        is allowed to receive packets.  If this column is empty, all addresses
        are permitted.  Logical ports are always allowed to receive packets
        addressed to multicast and broadcast addresses.
      </p>

      <p>
        Each member of the set is an Ethernet address in the form
        <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
      </p>

      <p>
        This specification will be extended to support L3 port security.
      </p>
    </column>

    <group title="Common Columns">
      <column name="external_ids">
        See <em>External IDs</em> at the beginning of this document.
      </column>
    </group>
  </table>

  <table name="ACL" title="Access Control List (ACL) rule">
    <p>
      Each row in this table represents one ACL rule for a logical switch
      that points to it through its <ref column="acls"/> column.  The <ref
      column="action"/> column for the highest-<ref column="priority"/>
      matching row in this table determines a packet's treatment.  If no row
      matches, packets are allowed by default.  (Default-deny treatment is
      possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
      <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
    </p>

    <column name="priority">
      <p>
        The ACL rule's priority.  Rules with numerically higher priority
        take precedence over those with lower.  If two ACL rules with
        the same priority both match, then the one actually applied to a
        packet is undefined.
      </p>

      <p>
        Return traffic from an <code>allow-related</code> flow is always
        allowed and cannot be changed through an ACL.
      </p>
    </column>

    <column name="direction">
      <p>Direction of the traffic to which this rule should apply:</p>
      <ul>
        <li>
          <code>from-lport</code>: Used to implement filters on traffic
          arriving from a logical port.  These rules are applied to the
          logical switch's ingress pipeline.
        </li>
        <li>
          <code>to-lport</code>: Used to implement filters on traffic
          forwarded to a logical port.  These rules are applied to the
          logical switch's egress pipeline.
        </li>
      </ul>
    </column>

    <column name="match">
      <p>
        The packets that the ACL should match, in the same expression
        language used for the <ref column="match" table="Logical_Flow"
        db="OVN_Southbound"/> column in the OVN Southbound database's
        <ref table="Logical_Flow" db="OVN_Southbound"/> table.  The
        <code>outport</code> logical port is only available in the
        <code>to-lport</code> direction (the <code>inport</code> is
        available in both directions).
      </p>

      <p>
        By default all traffic is allowed.  When writing a more
        restrictive policy, it is important to remember to allow flows
        such as ARP and IPv6 neighbor discovery packets.
      </p>

      <p>
        In logical switches connected to logical routers, the special
        port name <code>ROUTER</code> refers to the logical router port.
      </p>
    </column>

    <column name="action">
      <p>The action to take when the ACL rule matches:</p>
      
      <ul>
        <li>
          <code>allow</code>: Forward the packet.
        </li>

        <li>
          <code>allow-related</code>: Forward the packet and related traffic
          (e.g. inbound replies to an outbound connection).
        </li>

        <li>
          <code>drop</code>: Silently drop the packet.
        </li>

        <li>
          <code>reject</code>: Drop the packet, replying with a RST for TCP or
          ICMP unreachable message for other IP-based protocols.
          <code>Not implemented--currently treated as drop</code>
        </li>
      </ul>
    </column>

    <column name="log">
      <p>
        If set to <code>true</code>, packets that match the ACL will trigger a
        log message on the transport node or nodes that perform ACL processing.
        Logging may be combined with any <ref column="action"/>.
      </p>

      <p>
        Logging is not yet implemented.
      </p>
    </column>

    <group title="Common Columns">
      <column name="external_ids">
        See <em>External IDs</em> at the beginning of this document.
      </column>
    </group>
  </table>

  <table name="Logical_Router" title="L3 logical router">
    <p>
      Each row represents one L3 logical router.
    </p>

    <column name="name">
      <p>
        A name for the logical router.  This name has no special meaning or purpose
        other than to provide convenience for human interaction with the ovn-nb
        database.  There is no requirement for the name to be unique.  The
        logical router's UUID should be used as the unique identifier.
      </p>
    </column>

    <column name="ports">
      The router's ports.  This is a set of weak references, so a <ref
      table="Logical_Switch"/> must also refer to any given <ref
      table="Logical_Router_Port"/> or it will automatically be deleted.
    </column>

    <column name="default_gw">
      IP address to use as default gateway, if any.
    </column>

    <group title="Common Columns">
      <column name="external_ids">
        See <em>External IDs</em> at the beginning of this document.
      </column>
    </group>
  </table>

  <table name="Logical_Router_Port" title="L3 logical router port">
    <p>
      A port within an L3 logical router.
    </p>

    <p>
      A router port is always attached to a logical switch and to a logical
      router.  The former attachment, which is enforced by the database schema,
      can be identified by finding the <ref table="Logical_Switch"/> row whose
      <ref column="router_port" table="Logical_Switch"/> column points to the
      router port.  The latter attachment, which the database schema does not
      enforce, can be identified by finding the <ref table="Logical_Router"/>
      row whose <ref column="ports" table="Logical_Router"/> column includes
      the router port.
    </p>

    <column name="name">
      <p>
        A name for the logical router port.  This name has no special meaning or purpose
        other than to provide convenience for human interaction with the ovn-nb
        database.  There is no requirement for the name to be unique.  The
        logical router port's UUID should be used as the unique identifier.
      </p>
    </column>

    <column name="network">
      The IP address of the router and the netmask.  For example,
      <code>192.168.0.1/24</code> indicates that the router's IP address is
      192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
      routed to this port.
    </column>

    <column name="mac">
      The Ethernet address that belongs to this router port.
    </column>

    <group title="Common Columns">
      <column name="external_ids">
        See <em>External IDs</em> at the beginning of this document.
      </column>
    </group>
  </table>
</database>