]>
Commit | Line | Data |
---|---|---|
fed00ab1 AW |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
7 | .de ST | |
8 | . PP | |
9 | . RS -0.15in | |
10 | . I "\\$1" | |
11 | . RE | |
12 | .. | |
13 | .TH ovn\-sbctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" | |
14 | .\" This program's name: | |
15 | .ds PN ovn\-sbctl | |
16 | . | |
17 | .SH NAME | |
18 | ovn\-sbctl \- utility for querying and configuring \fBOVN_Southbound\fR database | |
19 | . | |
20 | .SH SYNOPSIS | |
21 | \fBovn\-sbctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand | |
22 | \fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]... | |
23 | . | |
24 | .SH DESCRIPTION | |
fed00ab1 AW |
25 | The \fBovn\-sbctl\fR program configures the \fBOVN_Southbound\fR database |
26 | by providing a high\-level interface to its configuration database. See | |
27 | \fBovn\-sb\fR(5) for comprehensive documentation of the database schema. | |
28 | .PP | |
29 | \fBovn\-sbctl\fR connects to an \fBovsdb\-server\fR process that | |
30 | maintains an OVN_Southbound configuration database. Using this | |
31 | connection, it queries and possibly applies changes to the database, | |
32 | depending on the supplied commands. | |
33 | .PP | |
34 | \fBovn\-sbctl\fR can perform any number of commands in a single run, | |
35 | implemented as a single atomic transaction against the database. | |
36 | .PP | |
37 | The \fBovn\-sbctl\fR command line begins with global options (see | |
38 | \fBOPTIONS\fR below for details). The global options are followed by | |
39 | one or more commands. Each command should begin with \fB\-\-\fR by | |
40 | itself as a command-line argument, to separate it from the following | |
41 | commands. (The \fB\-\-\fR before the first command is optional.) The | |
42 | command | |
43 | itself starts with command-specific options, if any, followed by the | |
44 | command name and any arguments. | |
45 | . | |
46 | .SH OPTIONS | |
47 | . | |
48 | The following options affect the behavior of \fBovn\-sbctl\fR as a | |
49 | whole. Some individual commands also accept their own options, which | |
50 | are given just before the command name. If the first command on the | |
51 | command line has options, then those options must be separated from | |
52 | the global options by \fB\-\-\fR. | |
53 | . | |
54 | .IP "\fB\-\-db=\fIserver\fR" | |
cce9c163 BP |
55 | The OVSDB database remote to contact. If the \fBOVN_SB_DB\fR |
56 | environment variable is set, its value is used as the default. | |
a576470f | 57 | Otherwise, the default is \fBunix:@RUNDIR@/ovnsb_db.sock\fR, but this |
cce9c163 BP |
58 | default is unlikely to be useful outside of single-machine OVN test |
59 | environments. | |
60 | .IP | |
61 | \fIserver\fR must take one of the following forms: | |
fed00ab1 AW |
62 | .RS |
63 | .so ovsdb/remote-active.man | |
64 | .so ovsdb/remote-passive.man | |
65 | .RE | |
66 | . | |
67 | .IP "\fB\-\-no\-syslog\fR" | |
68 | By default, \fBovn\-sbctl\fR logs its arguments and the details of any | |
69 | changes that it makes to the system log. This option disables this | |
70 | logging. | |
71 | .IP | |
72 | This option is equivalent to \fB\-\-verbose=sbctl:syslog:warn\fR. | |
73 | . | |
74 | .IP "\fB\-\-oneline\fR" | |
75 | Modifies the output format so that the output for each command is printed | |
76 | on a single line. New-line characters that would otherwise separate | |
77 | lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that | |
78 | would otherwise appear in the output are doubled. | |
79 | Prints a blank line for each command that has no output. | |
80 | This option does not affect the formatting of output from the | |
81 | \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR | |
82 | below. | |
83 | . | |
84 | .IP "\fB\-\-dry\-run\fR" | |
85 | Prevents \fBovn\-sbctl\fR from actually modifying the database. | |
86 | . | |
87 | .IP "\fB\-t \fIsecs\fR" | |
88 | .IQ "\fB\-\-timeout=\fIsecs\fR" | |
89 | By default, or with a \fIsecs\fR of \fB0\fR, \fBovn\-sbctl\fR waits | |
90 | forever for a response from the database. This option limits runtime | |
91 | to approximately \fIsecs\fR seconds. If the timeout expires, | |
92 | \fBovn\-sbctl\fR will exit with a \fBSIGALRM\fR signal. (A timeout | |
93 | would normally happen only if the database cannot be contacted, or if | |
94 | the system is overloaded.) | |
95 | . | |
14bf7951 LR |
96 | .so lib/vlog.man |
97 | .so lib/common.man | |
98 | . | |
fed00ab1 AW |
99 | .SS "Table Formatting Options" |
100 | These options control the format of output from the \fBlist\fR and | |
101 | \fBfind\fR commands. | |
102 | .so lib/table.man | |
103 | . | |
10471820 LR |
104 | .SS "Public Key Infrastructure Options" |
105 | .so lib/ssl.man | |
106 | .so lib/ssl-bootstrap.man | |
107 | .so lib/ssl-peer-ca-cert.man | |
108 | . | |
fed00ab1 AW |
109 | .SH COMMANDS |
110 | The commands implemented by \fBovn\-sbctl\fR are described in the | |
111 | sections below. | |
112 | .SS "OVN_Southbound Commands" | |
113 | These commands work with an \fBOVN_Southbound\fR database as a whole. | |
114 | . | |
fa183acc BP |
115 | .IP "\fBinit\fR" |
116 | Initializes the database, if it is empty. If the database has already | |
117 | been initialized, this command has no effect. | |
118 | . | |
fed00ab1 AW |
119 | .IP "\fBshow\fR" |
120 | Prints a brief overview of the database contents. | |
121 | . | |
122 | .SS "Chassis Commands" | |
123 | These commands manipulate \fBOVN_Southbound\fR chassis. | |
124 | . | |
7971b36c BP |
125 | .IP "[\fB\-\-may\-exist\fR] \fBchassis\-add \fIchassis\fR \fIencap-type\fR \fIencap-ip\fR" |
126 | Creates a new chassis named \fIchassis\fR. \fIencap-type\fR is a | |
3c653533 JP |
127 | comma-separated list of tunnel types. The chassis will have |
128 | one encap entry for each specified tunnel type with \fIencap-ip\fR | |
129 | as the destination IP for each. | |
fed00ab1 AW |
130 | .IP |
131 | Without \fB\-\-may\-exist\fR, attempting to create a chassis that | |
132 | exists is an error. With \fB\-\-may\-exist\fR, this command does | |
5b9db326 | 133 | nothing if \fIchassis\fR already exists. |
fed00ab1 AW |
134 | . |
135 | .IP "[\fB\-\-if\-exists\fR] \fBchassis\-del \fIchassis\fR" | |
136 | Deletes \fIchassis\fR and its \fIencaps\fR and \fIgateway_ports\fR. | |
137 | .IP | |
138 | Without \fB\-\-if\-exists\fR, attempting to delete a chassis that does | |
139 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
140 | delete a chassis that does not exist has no effect. | |
141 | . | |
142 | .SS "Port binding Commands" | |
143 | . | |
144 | These commands manipulate \fBOVN_Southbound\fR port bindings. | |
145 | . | |
7971b36c BP |
146 | .IP "[\fB\-\-may\-exist\fR] \fBlsp\-bind \fIlogical-port\fR \fIchassis\fR" |
147 | Binds the logical port named \fIlogical-port\fR to \fIchassis\fR. | |
fed00ab1 AW |
148 | .IP |
149 | Without \fB\-\-may\-exist\fR, attempting to bind a logical port that | |
150 | has already been bound is an error. With \fB\-\-may\-exist\fR, this | |
7971b36c | 151 | command does nothing if \fIlogical-port\fR has already been bound to |
fed00ab1 AW |
152 | a chassis. |
153 | . | |
7971b36c BP |
154 | .IP "[\fB\-\-if\-exists\fR] \fBlsp\-unbind\fR \fIlogical-port\fR" |
155 | Resets the binding of \fIlogical-port\fR to \fINULL\fR. | |
fed00ab1 AW |
156 | .IP |
157 | Without \fB\-\-if\-exists\fR, attempting to unbind a logical port | |
158 | that is not bound is an error. With \fB\-\-if\-exists\fR, attempting | |
159 | to unbind logical port that is not bound has no effect. | |
160 | . | |
dc70b67b RB |
161 | .SS "Logical Flow Commands" |
162 | . | |
c2f4c39b | 163 | .IP "[\fB\-\-uuid\fR] [\fB\-\-ovs\fR[\fB=\fIremote\fR]] [\fB\-\-stats\fR] \fBlflow\-list\fR [\fIlogical-datapath\fR] [\fIlflow\fR...]" |
7971b36c | 164 | List logical flows. If \fIlogical-datapath\fR is specified, only list |
c80eac1f BP |
165 | flows for that logical datapath. The \fIlogical-datapath\fR may be |
166 | given as a UUID or as a datapath name (reporting an error if multiple | |
167 | datapaths have the same name). | |
168 | .IP | |
169 | If at least one \fIlflow\fR is given, only matching logical flows, if | |
170 | any, are listed. Each \fIlflow\fR may be specified as a UUID or the | |
171 | first few characters of a UUID, optionally prefixed by \fB0x\fR. | |
172 | (Because \fBovn\-controller\fR sets OpenFlow flow cookies to the first | |
173 | 32 bits of the corresponding logical flow's UUID, this makes it easy | |
174 | to look up the logical flow that generated a particular OpenFlow | |
175 | flow.) | |
176 | .IP | |
177 | If \fB\-\-uuid\fR is specified, the output includes the first 32 bits | |
178 | of each logical flow's UUID. This makes it easier to find the | |
179 | OpenFlow flows that correspond to a given logical flow. | |
c2f4c39b BP |
180 | .IP |
181 | If \fB\-\-ovs\fR is included, \fBovn\-sbctl\fR attempts to obtain and | |
182 | display the OpenFlow flows that correspond to each OVN logical flow. | |
183 | To do so, \fBovn\-sbctl\fR connects to \fIremote\fR (by default, | |
184 | \fBunix:@RUNDIR@/br-int.mgmt\fR) over OpenFlow and retrieves the | |
185 | flows. If \fIremote\fR is specified, it must be an active OpenFlow | |
186 | connection method described in \fBovs\-ofctl\fR(8). Please see the | |
187 | discussion of the similar \fB\-\-ovs\fR option in \fBovn-trace\fR(8) | |
188 | for more information about the OpenFlow flow output. | |
189 | .IP | |
190 | By default, OpenFlow flow output includes only match and actions. Add | |
191 | \fB\-\-stats\fR to include all OpenFlow information, such as packet | |
192 | and byte counters, duration, and timeouts. | |
dc70b67b | 193 | . |
c80eac1f | 194 | .IP "[\fB\-\-uuid\fR] \fBdump\-flows\fR [\fIlogical-datapath\fR]" |
dc70b67b RB |
195 | Alias for \fBlflow\-list\fB. |
196 | . | |
10471820 LR |
197 | .SS "Remote Connectivity Commands" |
198 | . | |
199 | These commands manipulate the \fBconnections\fR column in the \fBSB_Global\fR | |
200 | table and rows in the \fBConnection\fR table. When \fBovsdb\-server\fR | |
201 | is configured to use the \fBconnections\fR column for OVSDB connections, | |
202 | this allows the administrator to use \fBovn\-sbctl\fR to configure database | |
203 | connections. | |
204 | . | |
205 | .IP "\fBget\-connection\fR" | |
206 | Prints the configured connection(s). | |
207 | . | |
208 | .IP "\fBdel\-connection\fR" | |
209 | Deletes the configured connection(s). | |
210 | . | |
211 | .IP "\fBset\-connection\fR [\fIaccess\-specifier\fR] \fItarget\fR\&..." | |
212 | Sets the configured manager target or targets. Each \fItarget\fR may | |
213 | be preceded by an optional access-specifier (\fBread\-only\fR or | |
214 | \fBread\-write\fR) and may use any of the following forms: | |
215 | . | |
216 | .RS | |
217 | .so ovsdb/remote-active.man | |
218 | .so ovsdb/remote-passive.man | |
219 | .RE | |
220 | ||
221 | If provided, the effect of the access specifier persists for subsequent | |
222 | targets until changed by another access specifier. | |
223 | . | |
224 | .SS "SSL Configuration" | |
225 | When \fBovsdb\-server\fR is configured to connect using SSL, the | |
226 | following parameters are required: | |
227 | .TP | |
228 | \fIprivate-key\fR | |
229 | Specifies a PEM file containing the private key used for SSL connections. | |
230 | .TP | |
231 | \fIcertificate\fR | |
232 | Specifies a PEM file containing a certificate, signed by the | |
233 | certificate authority (CA) used by the connection peers, that | |
234 | certifies the private key, identifying a trustworthy peer. | |
235 | .TP | |
236 | \fIca-cert\fR | |
237 | Specifies a PEM file containing the CA certificate used to verify that | |
238 | the connection peers are trustworthy. | |
239 | .PP | |
240 | These SSL settings apply to all SSL connections made by the southbound | |
241 | database server. | |
242 | . | |
243 | .IP "\fBget\-ssl\fR" | |
244 | Prints the SSL configuration. | |
245 | . | |
246 | .IP "\fBdel\-ssl\fR" | |
247 | Deletes the current SSL configuration. | |
248 | . | |
249 | .IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR" | |
250 | Sets the SSL configuration. The \fB\-\-bootstrap\fR option is described | |
251 | below. | |
252 | . | |
253 | .ST "CA Certificate Bootstrap" | |
254 | .PP | |
255 | Ordinarily, all of the files named in the SSL configuration must exist | |
256 | before SSL connectivity can be used. However, if the \fIca-cert\fR file | |
257 | does not exist and the \fB\-\-bootstrap\fR | |
258 | option is given, then \fBovsdb\-server\fR will attempt to obtain the | |
259 | CA certificate from the target on its first SSL connection and | |
260 | save it to the named PEM file. If it is successful, it will | |
261 | immediately drop the connection and reconnect, and from then on all | |
262 | SSL connections must be authenticated by a certificate signed by the | |
263 | CA certificate thus obtained. | |
264 | .PP | |
265 | \fBThis option exposes the SSL connection to a man-in-the-middle | |
266 | attack obtaining the initial CA certificate\fR, but it may be useful | |
267 | for bootstrapping. | |
268 | .PP | |
269 | This option is only useful if the SSL peer sends its CA certificate | |
270 | as part of the SSL certificate chain. The SSL protocol does not | |
271 | require the controller to send the CA certificate. | |
272 | . | |
4e3000a0 BP |
273 | .SS "Database Commands" |
274 | . | |
275 | These commands query and modify the contents of \fBovsdb\fR tables. | |
276 | They are a slight abstraction of the \fBovsdb\fR interface and as such | |
277 | they operate at a lower level than other \fBovs\-sbctl\fR commands. | |
278 | .PP | |
279 | .ST "Identifying Tables, Records, and Columns" | |
280 | .PP | |
281 | Each of these commands has a \fItable\fR parameter to identify a table | |
282 | within the database. Many of them also take a \fIrecord\fR parameter | |
283 | that identifies a particular record within a table. The \fIrecord\fR | |
284 | parameter may be the UUID for a record, and many tables offer | |
285 | additional ways to identify records. Some commands also take | |
286 | \fIcolumn\fR parameters that identify a particular field within the | |
287 | records in a table. | |
288 | .\" It would be kind to list all the tables and their supported identifiers | |
289 | .\" here. | |
290 | .PP | |
291 | Record names must be specified in full and with correct | |
292 | capitalization, except that UUIDs may be abbreviated to their first 4 | |
293 | (or more) hex digits, as long as that is unique within the table. | |
294 | Names of tables and columns are not case-sensitive, and \fB\-\fR and | |
295 | \fB_\fR are treated interchangeably. Unique abbreviations of table | |
296 | and column names are acceptable, e.g. \fBaddr\fR or \fBa\fR is | |
297 | sufficient to identify the \fBAddress_Set\fR table. | |
298 | . | |
fed00ab1 AW |
299 | .so lib/db-ctl-base.man |
300 | .SH "EXIT STATUS" | |
301 | .IP "0" | |
302 | Successful program execution. | |
303 | .IP "1" | |
304 | Usage, syntax, or configuration file error. | |
fed00ab1 AW |
305 | .SH "SEE ALSO" |
306 | . | |
307 | .BR ovn\-sb (5). |