ovn/controller/ovn-controller.8.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <manpage program="ovn-controller" section="8" title="ovn-controller">
   3     <h1>Name</h1>
   4     <p>ovn-controller -- Open Virtual Network local controller</p>
   5
   6     <h1>Synopsis</h1>
   7     <p><code>ovn-controller</code> [<var>options</var>] [<var>ovs-database</var>]</p>
   8
   9     <h1>Description</h1>
  10     <p>
  11       <code>ovn-controller</code> is the local controller daemon for
  12       OVN, the Open Virtual Network.  It connects up to the OVN
  13       Southbound database (see <code>ovn-sb</code>(5)) over the OVSDB
  14       protocol, and down to the Open vSwitch database (see
  15       <code>ovs-vswitchd.conf.db</code>(5)) over the OVSDB protocol and
  16       to <code>ovs-vswitchd</code>(8) via OpenFlow.  Each hypervisor and
  17       software gateway in an OVN deployment runs its own independent
  18       copy of <code>ovn-controller</code>; thus,
  19       <code>ovn-controller</code>'s downward connections are
  20       machine-local and do not run over a physical network.
  21     </p>
  22
  23     <h1>Configuration</h1>
  24     <p>
  25       <code>ovn-controller</code> retrieves most of its configuration
  26       information from the local Open vSwitch's ovsdb-server instance.
  27       The default location is <code>db.sock</code> in the local Open
  28       vSwitch's "run" directory.  It may be overridden by specifying the
  29       <var>ovs-database</var> argument in one of the following forms:
  30     </p>
  31     <ul>
  32       <li>
  33         <p>
  34           <code>ssl:<var>ip</var>:<var>port</var></code>
  35         </p>
  36         <p>
  37           The specified SSL <var>port</var> on the host at the given
  38           <var>ip</var>, which must be expressed as an IP address (not a DNS
  39           name) in IPv4 or IPv6 address format.  If <var>ip</var> is an IPv6
  40           address, then wrap <var>ip</var> with square brackets, e.g.:
  41           <code>ssl:[::1]:6640</code>.  The <code>--private-key</code>,
  42           <code>--certificate</code> and either of <code>--ca-cert</code>
  43           or <code>--bootstrap-ca-cert</code> options are mandatory when this
  44           form is used.
  45         </p>
  46       </li>
  47       <li>
  48         <p>
  49           <code>tcp:<var>ip</var>:<var>port</var></code>
  50         </p>
  51         <p>
  52           Connect to the given TCP <var>port</var> on <var>ip</var>, where
  53           <var>ip</var> can be IPv4 or IPv6 address. If <var>ip</var> is an
  54           IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
  55           <code>tcp:[::1]:6640</code>.
  56         </p>
  57       </li>
  58       <li>
  59         <p>
  60           <code>unix:<var>file</var></code>
  61         </p>
  62         <p>
  63           On POSIX, connect to the Unix domain server socket named
  64           <var>file</var>.
  65         </p>
  66         <p>
  67           On Windows, connect to a localhost TCP port whose value is written
  68           in <var>file</var>.
  69         </p>
  70       </li>
  71     </ul>
  72     <p>
  73       <code>ovn-controller</code> assumes it gets configuration
  74       information from the following keys in the <code>Open_vSwitch</code>
  75       table of the local OVS instance:
  76     </p>
  77     <dl>
  78       <dt><code>external_ids:system-id</code></dt>
  79       <dd>The chassis name to use in the Chassis table.</dd>
  80
  81       <dt><code>external_ids:ovn-bridge</code></dt>
  82       <dd>
  83         The integration bridge to which logical ports are attached.  The
  84         default is <code>br-int</code>.  If this bridge does not exist when
  85         ovn-controller starts, it will be created automatically with the
  86         default configuration suggested in <code>ovn-architecture</code>(7).
  87       </dd>
  88
  89       <dt><code>external_ids:ovn-remote</code></dt>
  90       <dd>
  91         <p>
  92           The OVN database that this system should connect to for its
  93           configuration.
  94         </p>
  95
  96         <p>
  97           Currently, <code>ovn-controller</code> does not support changing this
  98           setting mid-run.  If the value needs to change, the daemon must be
  99           restarted.  (This behavior should be improved.)
 100         </p>
 101       </dd>
 102
 103       <dt><code>external_ids:ovn-encap-type</code></dt>
 104       <dd>
 105         <p>
 106           The encapsulation type that a chassis should use to connect to
 107           this node.  Multiple encapsulation types may be specified with
 108           a comma-separated list.  Each listed encapsulation type will
 109           be paired with <code>ovn-encap-ip</code>.
 110         </p>
 111
 112         <p>
 113           Supported tunnel types for connecting hypervisors
 114           are <code>geneve</code> and <code>stt</code>.  Gateways may
 115           use <code>geneve</code>, <code>vxlan</code>, or
 116           <code>stt</code>.
 117         </p>
 118
 119         <p>
 120           Due to the limited amount of metadata in <code>vxlan</code>,
 121           the capabilities and performance of connected gateways will be
 122           reduced versus other tunnel formats.
 123         </p>
 124       </dd>
 125
 126       <dt><code>external_ids:ovn-encap-ip</code></dt>
 127       <dd>
 128         The IP address that a chassis should use to connect to this node
 129         using encapsulation types specified by
 130         <code>external_ids:ovn-encap-type</code>.
 131       </dd>
 132
 133       <dt><code>external_ids:ovn-bridge-mappings</code></dt>
 134       <dd>
 135         A list of key-value pairs that map a physical network name to a local
 136         ovs bridge that provides connectivity to that network.  An example
 137         value mapping two physical network names to two ovs bridges would be:
 138         <code>physnet1:br-eth0,physnet2:br-eth1</code>.
 139       </dd>
 140     </dl>
 141
 142     <h1>Open vSwitch Database Usage</h1>
 143
 144     <p>
 145       <code>ovn-controller</code> uses a number of <code>external-ids</code>
 146       keys in the Open vSwitch database to keep track of ports and interfaces.
 147       For proper operation, users should not change or clear these keys:
 148     </p>
 149
 150     <dl>
 151       <dt>
 152         <code>external_ids:ovn-chassis-id</code> in the <code>Port</code> table
 153       </dt>
 154       <dd>
 155         The presence of this key identifies a tunnel port within the
 156         integration bridge as one created by <code>ovn-controller</code> to
 157         reach a remote chassis.  Its value is the chassis ID of the remote
 158         chassis.
 159       </dd>
 160
 161       <dt>
 162         <code>external-ids:ovn-localnet-port</code> in the <code>Port</code>
 163         table
 164       </dt>
 165       <dd>
 166         <p>
 167           The presence of this key identifies a patch port as one created by
 168           <code>ovn-controller</code> to connect the integration bridge and
 169           another bridge to implement a <code>localnet</code> logical port.
 170           Its value is the name of the physical network that the port
 171           implements.  See <code>external_ids:ovn-bridge-mappings</code>,
 172           above, for more information.
 173         </p>
 174
 175         <p>
 176           Each <code>localnet</code> logical port is implemented as a pair of
 177           patch ports, one in the integration bridge, one in a different
 178           bridge, with the same <code>external-ids:ovn-localnet-port</code>
 179           value.
 180         </p>
 181       </dd>
 182     </dl>
 183
 184     <h1>Runtime Management Commands</h1>
 185     <p>
 186       <code>ovs-appctl</code> can send commands to a running
 187       <code>ovn-controller</code> process.  The currently supported
 188       commands are described below.
 189       <dl>
 190       <dt><code>exit</code></dt>
 191       <dd>
 192         Causes <code>ovn-controller</code> to gracefully terminate.
 193       </dd>
 194
 195       <dt><code>ct-zone-list</code></dt>
 196       <dd>
 197         Lists each local logical port and its connection tracking zone.
 198       </dd>
 199       </dl>
 200     </p>
 201
 202 </manpage>