1 <?xml version="1.0" encoding="utf-8"?>
2 <manpage program="ovn-nbctl" section="8" title="ovn-nbctl">
4 <p>ovn-nbctl -- Open Virtual Network northbound db management utility</p>
7 <p><code>ovn-nbctl</code> [<var>options</var>] <var>command</var> [<var>arg</var>...]</p>
10 <p>This utility can be used to manage the OVN northbound database.</p>
12 <h1>General Commands</h1>
15 <dt><code>show [<var>lswitch</var> | <var>router</var>]</code></dt>
17 Prints a brief overview of the database contents. If
18 <var>lswitch</var> is provided, only records related to that
19 logical switch are shown. If
20 <var>router</var> is provided, only records related to that
21 logical router are shown.
25 <h1>Logical Switch Commands</h1>
28 <dt><code>lswitch-add</code></dt>
31 Creates a new, unnamed logical switch, which initially has no ports.
32 The switch does not have a name, other commands must refer to this
37 <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lswitch-add</code> <var>lswitch</var></dt>
40 Creates a new logical switch named <var>lswitch</var>, which
41 initially has no ports.
45 The OVN northbound database schema does not require logical switch
46 names to be unique, but the whole point to the names is to provide an
47 easy way for humans to refer to the switches, making duplicate names
48 unhelpful. Thus, without any options, this command regards it as an
49 error if <var>lswitch</var> is a duplicate name. With
50 <code>--may-exist</code>, adding a duplicate name succeeds but does
51 not create a new logical switch. With <code>--add-duplicate</code>,
52 the command really creates a new logical switch with a duplicate
53 name. It is an error to specify both options.
57 <dt>[<code>--if-exists</code>] <code>lswitch-del</code> <var>lswitch</var></dt>
59 Deletes <var>lswitch</var>. It is an error if <var>lswitch</var> does
60 not exist, unless <code>--if-exists</code> is specified.
63 <dt><code>lswitch-list</code></dt>
65 Lists all existing switches on standard output, one per line.
71 <dt>[<code>--log</code>] <code>acl-add</code> <var>lswitch</var> <var>direction</var> <var>priority</var> <var>match</var> <var>action</var></dt>
73 Adds the specified ACL to <var>lswitch</var>.
74 <var>direction</var> must be either <code>from-lport</code> or
75 <code>to-lport</code>. <var>priority</var> must be between
76 <code>1</code> and <code>65534</code>, inclusive. If
77 <code>--log</code> is specified, packet logging is enabled for the
78 ACL. A full description of the fields are in <code>ovn-nb</code>(5).
81 <dt><code>acl-del</code> <var>lswitch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
83 Deletes ACLs from <var>lswitch</var>. If only
84 <var>lswitch</var> is supplied, all the ACLs from the logical
85 switch are deleted. If <var>direction</var> is also specified,
86 then all the flows in that direction will be deleted from the
87 logical switch. If all the fields are given, then a single flow
88 that matches all the fields will be deleted.
91 <dt><code>acl-list</code> <var>lswitch</var></dt>
93 Lists the ACLs on <var>lswitch</var>.
97 <h1>Logical Port Commands</h1>
99 <dt>[<code>--may-exist</code>] <code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
102 Creates on <var>lswitch</var> a new logical port named
107 It is an error if a logical port named <var>lport</var> already
108 exists, unless <code>--may-exist</code> is specified. Regardless of
109 <code>--may-exist</code>, it is an error if the existing port is in
110 some logical switch other than <var>lswitch</var> or if it has a
115 <dt>[<code>--may-exist</code>] <code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
118 Creates on <var>lswitch</var> a logical port named <var>lport</var>
119 that is a child of <var>parent</var> that is identifed with VLAN ID
120 <var>tag</var>. This is useful in cases such as virtualized
121 container environments where Open vSwitch does not have a direct
122 connection to the container's port and it must be shared with
123 the virtual machine's port.
127 It is an error if a logical port named <var>lport</var> already
128 exists, unless <code>--may-exist</code> is specified. Regardless of
129 <code>--may-exist</code>, it is an error if the existing port is not
130 in <var>lswitch</var> or if it does not have the specified
131 <var>parent</var> and <var>tag</var>.
135 <dt>[<code>--if-exists</code>] <code>lport-del</code> <var>lport</var></dt>
137 Deletes <var>lport</var>. It is an error if <var>lport</var> does
138 not exist, unless <code>--if-exists</code> is specified.
141 <dt><code>lport-list</code> <var>lswitch</var></dt>
143 Lists all the logical ports within <var>lswitch</var> on
144 standard output, one per line.
147 <dt><code>lport-get-parent</code> <var>lport</var></dt>
149 If set, get the parent port of <var>lport</var>. If not set, print
153 <dt><code>lport-get-tag</code> <var>lport</var></dt>
155 If set, get the tag for <var>lport</var> traffic. If not set, print
159 <dt><code>lport-set-addresses</code> <var>lport</var> [<var>address</var>]...</dt>
161 Sets the addresses associated with <var>lport</var> to
162 <var>address</var>. Each <var>address</var> should be either an
163 Ethernet address or an Ethernet address followed by an IP address
164 (separated by a space and quoted to form a single command-line
165 argument). The special form <code>unknown</code> is also valid.
166 Multiple Ethernet addresses or Ethernet+IP pairs may be set. If no
167 <var>address</var> argument is given, <var>lport</var> will have no
168 addresses associated with it.
171 <dt><code>lport-get-addresses</code> <var>lport</var></dt>
173 Lists all the addresses associated with <var>lport</var> on standard
174 output, one per line.
177 <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
180 Sets the port security addresses associated with <var>lport</var> to
181 <var>addrs</var>. Multiple sets of addresses may be set by using
182 multiple <var>addrs</var> arguments. If no <var>addrs</var> argument
183 is given, <var>lport</var> will not have port security enabled.
187 Port security limits the addresses from which a logical port may send
188 packets and to which it may receive packets. See the
189 <code>ovn-nb</code>(5) documentation for the <ref
190 column="port_security" table="Logical_Port"/> column in the <ref
191 table="Logical_Port"/> table for details.
195 <dt><code>lport-get-port-security</code> <var>lport</var></dt>
197 Lists all the port security addresses associated with <var>lport</var>
198 on standard output, one per line.
201 <dt><code>lport-get-up</code> <var>lport</var></dt>
203 Prints the state of <var>lport</var>, either <code>up</code> or
207 <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
209 Set the administrative state of <var>lport</var>, either <code>enabled</code>
210 or <code>disabled</code>. When a port is disabled, no traffic is allowed into
214 <dt><code>lport-get-enabled</code> <var>lport</var></dt>
216 Prints the administrative state of <var>lport</var>, either <code>enabled</code>
217 or <code>disabled</code>.
220 <dt><code>lport-set-type</code> <var>lport</var> <var>type</var></dt>
222 Set the type for the logical port. No special types have been implemented yet.
225 <dt><code>lport-get-type</code> <var>lport</var></dt>
227 Get the type for the logical port.
230 <dt><code>lport-set-options</code> <var>lport</var> [<var>key=value</var>]...</dt>
232 Set type-specific key-value options for the logical port.
235 <dt><code>lport-get-options</code> <var>lport</var></dt>
237 Get the type-specific options for the logical port.
242 <h1>Logical Router Commands</h1>
245 <dt><code>lr-add</code></dt>
248 Creates a new, unnamed logical router, which initially has no ports.
249 The router does not have a name, other commands must refer to this
254 <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lr-add</code> <var>router</var></dt>
257 Creates a new logical router named <var>router</var>, which
258 initially has no ports.
262 The OVN northbound database schema does not require logical router
263 names to be unique, but the whole point to the names is to provide an
264 easy way for humans to refer to the routers, making duplicate names
265 unhelpful. Thus, without any options, this command regards it as an
266 error if <var>router</var> is a duplicate name. With
267 <code>--may-exist</code>, adding a duplicate name succeeds but does
268 not create a new logical router. With <code>--add-duplicate</code>,
269 the command really creates a new logical router with a duplicate
270 name. It is an error to specify both options.
274 <dt>[<code>--if-exists</code>] <code>lr-del</code> <var>router</var></dt>
276 Deletes <var>router</var>. It is an error if <var>router</var> does
277 not exist, unless <code>--if-exists</code> is specified.
280 <dt><code>lr-list</code></dt>
282 Lists all existing routers on standard output, one per line.
286 <h1>Logical Router Port Commands</h1>
289 <dt>[<code>--may-exist</code>] <code>lrp-add</code> <var>router</var> <var>port</var> <var>mac</var> <var>network</var> [<var>peer</var>]</dt>
292 Creates on <var>router</var> a new logical router port named
293 <var>port</var> with Ethernet address <var>mac</var> and IP
294 address/netmask <var>network</var>. If <var>peer</var> is
295 specified, it identifies a logical router port that connects
300 It is an error if a logical router port named <var>port</var>
301 already exists, unless <code>--may-exist</code> is specified.
302 Regardless of <code>--may-exist</code>, it is an error if the
303 existing router port is in some logical router other than
308 <dt>[<code>--if-exists</code>] <code>lrp-del</code> <var>port</var></dt>
310 Deletes <var>port</var>. It is an error if <var>port</var> does
311 not exist, unless <code>--if-exists</code> is specified.
314 <dt><code>lrp-list</code> <var>router</var></dt>
316 Lists all the logical router ports within <var>router</var> on
317 standard output, one per line.
320 <dt><code>lrp-set-enabled</code> <var>port</var> <var>state</var></dt>
322 Set the administrative state of <var>port</var>, either
323 <code>enabled</code> or <code>disabled</code>. When a port is
324 disabled, no traffic is allowed into or out of the port.
327 <dt><code>lrp-get-enabled</code> <var>port</var></dt>
329 Prints the administrative state of <var>port</var>, either
330 <code>enabled</code> or <code>disabled</code>.
334 <h1>Logical Router Static Route Commands</h1>
337 <dt>[<code>--may-exist</code>] <code>lr-route-add</code> <var>router</var> <var>prefix</var> <var>nexthop</var> [<var>port</var>]</dt>
340 Adds the specified route to <var>router</var>.
341 <var>prefix</var> describes an IPv4 or IPv6 prefix for this
342 route, such as <code>192.168.100.0/24</code>.
343 <var>nexthop</var> specifies the gateway to use for this
344 route, which should be the IP address of one of
345 <var>router</var> logical router ports or the IP address of a
346 logical port. If <var>port</var> is specified, packets that
347 match this route will be sent out that port. When
348 <var>port</var> is omitted, OVN infers the output port based
349 on <var>nexthop</var>.
353 It is an error if a route with <var>prefix</var> already exists,
354 unless <code>--may-exist</code> is specified.
358 <dt>[<code>--if-exists</code>] <code>lr-route-del</code> <var>router</var> [<var>prefix</var>]</dt>
361 Deletes routes from <var>router</var>. If only <var>router</var>
362 is supplied, all the routes from the logical router are
363 deleted. If <var>prefix</var> is also specified, then all the
364 routes that match the prefix will be deleted from the logical
369 It is an error if <code>prefix</code> is specified and there
370 is no matching route entry, unless <code>--if-exists</code> is
375 <dt><code>lr-route-list</code> <var>router</var></dt>
377 Lists the routes on <var>router</var>.
381 <h1>Database Commands</h1>
382 <p>These commands query and modify the contents of <code>ovsdb</code> tables.
383 They are a slight abstraction of the <code>ovsdb</code> interface and
384 as suchthey operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
385 <p><var>Identifying Tables, Records, and Columns</var></p>
386 <p>Each of these commands has a <var>table</var> parameter to identify a table
387 within the database. Many of them also take a <var>record</var> parameter
388 that identifies a particular record within a table. The <var>record</var>
389 parameter may be the UUID for a record, and many tables offer
390 additional ways to identify records. Some commands also take
391 <var>column</var> parameters that identify a particular field within the
392 records in a table.</p>
393 <p>The following tables are currently defined:</p>
395 <dt><code>Logical_Switch</code></dt>
397 An L2 logical switch. Records may be identified by name.
400 <dt><code>Logical_Port</code></dt>
402 A port within an L2 logical switch. Records may be identified by name.
405 <dt><code>ACL</code></dt>
407 An ACL rule for a logical switch that points to it through its <var>acls</var> column.
410 <dt><code>Logical_Router</code></dt>
412 An L3 logical router. Records may be identified by name.
415 <dt><code>Logical_Router_Port</code></dt>
417 A port within an L3 logical router. Records may be identified by name.
420 <dt><code>Logical_Router_Static_Route</code></dt>
422 A static route belonging to an L3 logical router.
427 <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
432 <dt><code>--db</code> <var>database</var></dt>
434 The OVSDB database remote to contact. If the <env>OVN_NB_DB</env>
435 environment variable is set, its value is used as the default.
436 Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
437 default is unlikely to be useful outside of single-machine OVN test
441 <dt><code>-h</code> | <code>--help</code></dt>
442 <dt><code>-o</code> | <code>--options</code></dt>
443 <dt><code>-V</code> | <code>--version</code></dt>
446 <h1>Logging options</h1>
448 <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
449 <dt><code>-v</code>, <code>--verbose</code></dt>
450 <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
451 <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
454 <h1>PKI configuration (required to use SSL)</h1>
456 <dt><code>-p</code>, <code>--private-key=</code><var>file</var> file with private key</dt>
457 <dt><code>-c</code>, <code>--certificate=</code><var>file</var> file with certificate for private key</dt>
458 <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var> file with peer CA certificate</dt>