utilities/ovs-vsctl.8.in

   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 ovs\-vsctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
  14 .\" This program's name:
  15 .ds PN ovs\-vsctl
  16 .
  17 .SH NAME
  18 ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR
  19 .
  20 .SH SYNOPSIS
  21 \fBovs\-vsctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand
  22 \fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]...
  23 .
  24 .SH DESCRIPTION
  25 The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by
  26 providing a high\-level interface to its configuration database.
  27 See \fBovs\-vswitchd.conf.db\fR(5) for comprehensive documentation of
  28 the database schema.
  29 .PP
  30 \fBovs\-vsctl\fR connects to an \fBovsdb\-server\fR process that
  31 maintains an Open vSwitch configuration database.  Using this
  32 connection, it queries and possibly applies changes to the database,
  33 depending on the supplied commands.  Then, if it applied any changes,
  34 by default it waits until \fBovs\-vswitchd\fR has finished
  35 reconfiguring itself before it exits.  (If you use \fBovs\-vsctl\fR
  36 when \fBovs\-vswitchd\fR is not running, use \fB\-\-no\-wait\fR.)
  37 .PP
  38 \fBovs\-vsctl\fR can perform any number of commands in a single run,
  39 implemented as a single atomic transaction against the database.
  40 .PP
  41 The \fBovs\-vsctl\fR command line begins with global options (see
  42 \fBOPTIONS\fR below for details).  The global options are followed by
  43 one or more commands.  Each command should begin with \fB\-\-\fR by
  44 itself as a command-line argument, to separate it from the following
  45 commands.  (The \fB\-\-\fR before the first command is optional.)  The
  46 command
  47 itself starts with command-specific options, if any, followed by the
  48 command name and any arguments.  See \fBEXAMPLES\fR below for syntax
  49 examples.
  50 .
  51 .SS "Linux VLAN Bridging Compatibility"
  52 The \fBovs\-vsctl\fR program supports the model of a bridge
  53 implemented by Open vSwitch, in which a single bridge supports ports
  54 on multiple VLANs.  In this model, each port on a bridge is either a
  55 trunk port that potentially passes packets tagged with 802.1Q headers
  56 that designate VLANs or it is assigned a single implicit VLAN that is
  57 never tagged with an 802.1Q header.
  58 .PP
  59 For compatibility with software designed for the Linux bridge,
  60 \fBovs\-vsctl\fR also supports a model in which traffic associated
  61 with a given 802.1Q VLAN is segregated into a separate bridge.  A
  62 special form of the \fBadd\-br\fR command (see below) creates a ``fake
  63 bridge'' within an Open vSwitch bridge to simulate this behavior.
  64 When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it
  65 much like a bridge separate from its ``parent bridge,'' but the actual
  66 implementation in Open vSwitch uses only a single bridge, with ports on
  67 the fake bridge assigned the implicit VLAN of the fake bridge of which
  68 they are members.  (A fake bridge for VLAN 0 receives packets that
  69 have no 802.1Q tag or a tag with VLAN 0.)
  70 .
  71 .SH OPTIONS
  72 .
  73 The following options affect the behavior \fBovs\-vsctl\fR as a whole.
  74 Some individual commands also accept their own options, which are
  75 given just before the command name.  If the first command on the
  76 command line has options, then those options must be separated from
  77 the global options by \fB\-\-\fR.
  78 .
  79 .IP "\fB\-\-db=\fIserver\fR"
  80 Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR
  81 contacts to query or modify configuration.  The default is
  82 \fBunix:@RUNDIR@/db.sock\fR.  \fIserver\fR must take one of the
  83 following forms:
  84 .RS
  85 .so ovsdb/remote-active.man
  86 .so ovsdb/remote-passive.man
  87 .RE
  88 .
  89 .IP "\fB\-\-no\-wait\fR"
  90 Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to
  91 reconfigure itself according to the modified database.  This
  92 option should be used if \fBovs\-vswitchd\fR is not running;
  93 otherwise, \fBovs\-vsctl\fR will not exit until \fBovs\-vswitchd\fR
  94 starts.
  95 .IP
  96 This option has no effect if the commands specified do not change the
  97 database.
  98 .
  99 .IP "\fB\-\-no\-syslog\fR"
 100 By default, \fBovs\-vsctl\fR logs its arguments and the details of any
 101 changes that it makes to the system log.  This option disables this
 102 logging.
 103 .IP
 104 This option is equivalent to \fB\-\-verbose=vsctl:syslog:warn\fR.
 105 .
 106 .IP "\fB\-\-oneline\fR"
 107 Modifies the output format so that the output for each command is printed
 108 on a single line.  New-line characters that would otherwise separate
 109 lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that
 110 would otherwise appear in the output are doubled.
 111 Prints a blank line for each command that has no output.
 112 This option does not affect the formatting of output from the
 113 \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
 114 below.
 115 .
 116 .IP "\fB\-\-dry\-run\fR"
 117 Prevents \fBovs\-vsctl\fR from actually modifying the database.
 118 .
 119 .IP "\fB\-t \fIsecs\fR"
 120 .IQ "\fB\-\-timeout=\fIsecs\fR"
 121 By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-vsctl\fR waits
 122 forever for a response from the database.  This option limits runtime
 123 to approximately \fIsecs\fR seconds.  If the timeout expires,
 124 \fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal.  (A timeout
 125 would normally happen only if the database cannot be contacted, or if
 126 the system is overloaded.)
 127 .
 128 .IP "\fB\-\-retry\fR"
 129 Without this option, if \fBovs\-vsctl\fR connects outward to the
 130 database server (the default) then \fBovs\-vsctl\fR will try to
 131 connect once and exit with an error if the connection fails (which
 132 usually means that \fBovsdb\-server\fR is not running).
 133 .IP
 134 With this option, or if \fB\-\-db\fR specifies that \fBovs\-vsctl\fR
 135 should listen for an incoming connection from the database server,
 136 then \fBovs\-vsctl\fR will wait for a connection to the database
 137 forever.
 138 .IP
 139 Regardless of this setting, \fB\-\-timeout\fR always limits how long
 140 \fBovs\-vsctl\fR will wait.
 141 .
 142 .SS "Table Formatting Options"
 143 These options control the format of output from the \fBlist\fR and
 144 \fBfind\fR commands.
 145 .so lib/table.man
 146 .
 147 .SS "Public Key Infrastructure Options"
 148 .so lib/ssl.man
 149 .so lib/ssl-bootstrap.man
 150 .so lib/ssl-peer-ca-cert.man
 151 .so lib/vlog.man
 152 .so lib/common.man
 153 .
 154 .SH COMMANDS
 155 The commands implemented by \fBovs\-vsctl\fR are described in the
 156 sections below.
 157 .SS "Open vSwitch Commands"
 158 These commands work with an Open vSwitch as a whole.
 159 .
 160 .IP "\fBinit\fR"
 161 Initializes the Open vSwitch database, if it is empty.  If the
 162 database has already been initialized, this command has no effect.
 163 .IP
 164 Any successful \fBovs\-vsctl\fR command automatically initializes the
 165 Open vSwitch database if it is empty.  This command is provided to
 166 initialize the database without executing any other command.
 167 .
 168 .IP "\fBshow\fR"
 169 Prints a brief overview of the database contents.
 170 .
 171 .IP "\fBemer\-reset\fR"
 172 Reset the configuration into a clean state.  It deconfigures OpenFlow
 173 controllers, OVSDB servers, and SSL, and deletes port mirroring,
 174 \fBfail_mode\fR, NetFlow, sFlow, and IPFIX configuration.  This
 175 command also removes all \fBother\-config\fR keys from all database
 176 records, except that \fBother\-config:hwaddr\fR is preserved if it is
 177 present in a Bridge record.  Other networking configuration is left
 178 as-is.
 179 .
 180 .SS "Bridge Commands"
 181 These commands examine and manipulate Open vSwitch bridges.
 182 .
 183 .IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge\fR"
 184 Creates a new bridge named \fIbridge\fR.  Initially the bridge will
 185 have no ports (other than \fIbridge\fR itself).
 186 .IP
 187 Without \fB\-\-may\-exist\fR, attempting to create a bridge that
 188 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 189 nothing if \fIbridge\fR already exists as a real bridge.
 190 .
 191 .IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge parent vlan\fR"
 192 Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
 193 vSwitch bridge \fIparent\fR, which must already exist and must not
 194 itself be a fake bridge.  The new fake bridge will be on 802.1Q VLAN
 195 \fIvlan\fR, which must be an integer between 0 and 4095.  The parent
 196 bridge must not already have a fake bridge for \fIvlan\fR.  Initially
 197 \fIbridge\fR will have no ports (other than \fIbridge\fR itself).
 198 .IP
 199 Without \fB\-\-may\-exist\fR, attempting to create a bridge that
 200 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 201 nothing if \fIbridge\fR already exists as a VLAN bridge under
 202 \fIparent\fR for \fIvlan\fR.
 203 .
 204 .IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR"
 205 Deletes \fIbridge\fR and all of its ports.  If \fIbridge\fR is a real
 206 bridge, this command also deletes any fake bridges that were created
 207 with \fIbridge\fR as parent, including all of their ports.
 208 .IP
 209 Without \fB\-\-if\-exists\fR, attempting to delete a bridge that does
 210 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 211 delete a bridge that does not exist has no effect.
 212 .
 213 .IP "[\fB\-\-real\fR|\fB\-\-fake\fR] \fBlist\-br\fR"
 214 Lists all existing real and fake bridges on standard output, one per
 215 line.  With \fB\-\-real\fR or \fB\-\-fake\fR, only bridges of that type
 216 are returned.
 217 .
 218 .IP "\fBbr\-exists \fIbridge\fR"
 219 Tests whether \fIbridge\fR exists as a real or fake bridge.  If so,
 220 \fBovs\-vsctl\fR exits successfully with exit code 0.  If not,
 221 \fBovs\-vsctl\fR exits unsuccessfully with exit code 2.
 222 .
 223 .IP "\fBbr\-to\-vlan \fIbridge\fR"
 224 If \fIbridge\fR is a fake bridge, prints the bridge's 802.1Q VLAN as a
 225 decimal integer.  If \fIbridge\fR is a real bridge, prints 0.
 226 .
 227 .IP "\fBbr\-to\-parent \fIbridge\fR"
 228 If \fIbridge\fR is a fake bridge, prints the name of its parent
 229 bridge.  If \fIbridge\fR is a real bridge, print \fIbridge\fR.
 230 .
 231 .IP "\fBbr\-set\-external\-id \fIbridge key\fR [\fIvalue\fR]"
 232 Sets or clears an ``external ID'' value on \fIbridge\fR.  These values
 233 are intended to identify entities external to Open vSwitch with which
 234 \fIbridge\fR is associated, e.g. the bridge's identifier in a
 235 virtualization management platform.  The Open vSwitch database schema
 236 specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR
 237 are otherwise arbitrary strings.
 238 .IP
 239 If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for
 240 \fIbridge\fR, overwriting any previous value.  If \fIvalue\fR is
 241 omitted, then \fIkey\fR is removed from \fIbridge\fR's set of external
 242 IDs (if it was present).
 243 .IP
 244 For real bridges, the effect of this command is similar to that of a
 245 \fBset\fR or \fBremove\fR command in the \fBexternal\-ids\fR column of
 246 the \fBBridge\fR table.  For fake bridges, it actually modifies keys
 247 with names prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table.
 248 .
 249 .IP "\fBbr\-get\-external\-id \fIbridge\fR [\fIkey\fR]"
 250 Queries the external IDs on \fIbridge\fR.  If \fIkey\fR is specified,
 251 the output is the value for that \fIkey\fR or the empty string if
 252 \fIkey\fR is unset.  If \fIkey\fR is omitted, the output is
 253 \fIkey\fB=\fIvalue\fR, one per line, for each key-value pair.
 254 .IP
 255 For real bridges, the effect of this command is similar to that of a
 256 \fBget\fR command in the \fBexternal\-ids\fR column of the
 257 \fBBridge\fR table.  For fake bridges, it queries keys with names
 258 prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table.
 259 .
 260 .SS "Port Commands"
 261 .
 262 These commands examine and manipulate Open vSwitch ports.  These
 263 commands treat a bonded port as a single entity.
 264 .
 265 .IP "\fBlist\-ports \fIbridge\fR"
 266 Lists all of the ports within \fIbridge\fR on standard output, one per
 267 line.  The local port \fIbridge\fR is not included in the list.
 268 .
 269 .IP "[\fB\-\-may\-exist\fR] \fBadd\-port \fIbridge port \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR"
 270 Creates on \fIbridge\fR a new port named \fIport\fR from the network
 271 device of the same name.
 272 .IP
 273 Optional arguments set values of column in the Port record created by
 274 the command.  For example, \fBtag=9\fR would make the port an access
 275 port for VLAN 9.  The syntax is the same as that for the \fBset\fR
 276 command (see \fBDatabase Commands\fR below).
 277 .IP
 278 Without \fB\-\-may\-exist\fR, attempting to create a port that exists
 279 is an error.  With \fB\-\-may\-exist\fR, this command does nothing if
 280 \fIport\fR already exists on \fIbridge\fR and is not a bonded port.
 281 .
 282 .IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&... [\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR"
 283 Creates on \fIbridge\fR a new port named \fIport\fR that bonds
 284 together the network devices given as each \fIiface\fR.  At least two
 285 interfaces must be named.  If the interfaces are DPDK enabled then
 286 the transaction will need to include operations to explicitly set the
 287 interface type to 'dpdk'.
 288 .IP
 289 Optional arguments set values of column in the Port record created by
 290 the command.  The syntax is the same as that for the \fBset\fR command
 291 (see \fBDatabase Commands\fR below).
 292 .IP
 293 With \fB\-\-fake\-iface\fR, a fake interface with the name \fIport\fR is
 294 created.  This should only be used for compatibility with legacy
 295 software that requires it.
 296 .IP
 297 Without \fB\-\-may\-exist\fR, attempting to create a port that exists
 298 is an error.  With \fB\-\-may\-exist\fR, this command does nothing if
 299 \fIport\fR already exists on \fIbridge\fR and bonds together exactly
 300 the specified interfaces.
 301 .
 302 .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR"
 303 Deletes \fIport\fR.  If \fIbridge\fR is omitted, \fIport\fR is removed
 304 from whatever bridge contains it; if \fIbridge\fR is specified, it
 305 must be the real or fake bridge that contains \fIport\fR.
 306 .IP
 307 Without \fB\-\-if\-exists\fR, attempting to delete a port that does
 308 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 309 delete a port that does not exist has no effect.
 310 .
 311 .IP "[\fB\-\-if\-exists\fR] \fB\-\-with\-iface del\-port \fR[\fIbridge\fR] \fIiface\fR"
 312 Deletes the port named \fIiface\fR or that has an interface named
 313 \fIiface\fR.  If \fIbridge\fR is omitted, the port is removed from
 314 whatever bridge contains it; if \fIbridge\fR is specified, it must be
 315 the real or fake bridge that contains the port.
 316 .IP
 317 Without \fB\-\-if\-exists\fR, attempting to delete the port for an
 318 interface that does not exist is an error.  With \fB\-\-if\-exists\fR,
 319 attempting to delete the port for an interface that does not exist has
 320 no effect.
 321 .
 322 .IP "\fBport\-to\-br \fIport\fR"
 323 Prints the name of the bridge that contains \fIport\fR on standard
 324 output.
 325 .
 326 .SS "Interface Commands"
 327 .
 328 These commands examine the interfaces attached to an Open vSwitch
 329 bridge.  These commands treat a bonded port as a collection of two or
 330 more interfaces, rather than as a single port.
 331 .
 332 .IP "\fBlist\-ifaces \fIbridge\fR"
 333 Lists all of the interfaces within \fIbridge\fR on standard output,
 334 one per line.  The local port \fIbridge\fR is not included in the
 335 list.
 336 .
 337 .IP "\fBiface\-to\-br \fIiface\fR"
 338 Prints the name of the bridge that contains \fIiface\fR on standard
 339 output.
 340 .
 341 .SS "OpenFlow Controller Connectivity"
 342 .
 343 \fBovs\-vswitchd\fR can perform all configured bridging and switching
 344 locally, or it can be configured to communicate with one or more
 345 external OpenFlow controllers.  The switch is typically configured to
 346 connect to a primary controller that takes charge of the bridge's flow
 347 table to implement a network policy.  In addition, the switch can be
 348 configured to listen to connections from service controllers.  Service
 349 controllers are typically used for occasional support and maintenance,
 350 e.g. with \fBovs\-ofctl\fR.
 351 .
 352 .IP "\fBget\-controller\fR \fIbridge\fR"
 353 Prints the configured controller target.
 354 .
 355 .IP "\fBdel\-controller\fR \fIbridge\fR"
 356 Deletes the configured controller target.
 357 .
 358 .IP "\fBset\-controller\fR \fIbridge\fR \fItarget\fR\&..."
 359 Sets the configured controller target or targets.  Each \fItarget\fR may
 360 use any of the following forms:
 361 .
 362 .RS
 363 .so lib/vconn-active.man
 364 .so lib/vconn-passive.man
 365 .RE
 366 .
 367 .ST "Controller Failure Settings"
 368 .PP
 369 When a controller is configured, it is, ordinarily, responsible for
 370 setting up all flows on the switch.  Thus, if the connection to
 371 the controller fails, no new network connections can be set up.  If
 372 the connection to the controller stays down long enough, no packets
 373 can pass through the switch at all.
 374 .PP
 375 If the value is \fBstandalone\fR, or if neither of these settings
 376 is set, \fBovs\-vswitchd\fR will take over
 377 responsibility for setting up
 378 flows when no message has been received from the controller for three
 379 times the inactivity probe interval.  In this mode,
 380 \fBovs\-vswitchd\fR causes the datapath to act like an ordinary
 381 MAC-learning switch.  \fBovs\-vswitchd\fR will continue to retry connecting
 382 to the controller in the background and, when the connection succeeds,
 383 it discontinues its standalone behavior.
 384 .PP
 385 If this option is set to \fBsecure\fR, \fBovs\-vswitchd\fR will not
 386 set up flows on its own when the controller connection fails.
 387 .
 388 .IP "\fBget\-fail\-mode\fR \fIbridge\fR"
 389 Prints the configured failure mode.
 390 .
 391 .IP "\fBdel\-fail\-mode\fR \fIbridge\fR"
 392 Deletes the configured failure mode.
 393 .
 394 .IP "\fBset\-fail\-mode\fR \fIbridge\fR \fBstandalone\fR|\fBsecure\fR"
 395 Sets the configured failure mode.
 396 .
 397 .SS "Manager Connectivity"
 398 .
 399 These commands manipulate the \fBmanager_options\fR column in the
 400 \fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table.  When
 401 \fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for
 402 OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup
 403 scripts provided with Open vSwitch), this allows the administrator to use
 404 \fBovs\-vsctl\fR to configure database connections.
 405 .
 406 .IP "\fBget\-manager\fR"
 407 Prints the configured manager(s).
 408 .
 409 .IP "\fBdel\-manager\fR"
 410 Deletes the configured manager(s).
 411 .
 412 .IP "\fBset\-manager\fR \fItarget\fR\&..."
 413 Sets the configured manager target or targets.  Each \fItarget\fR may
 414 use any of the following forms:
 415 .
 416 .RS
 417 .so ovsdb/remote-active.man
 418 .so ovsdb/remote-passive.man
 419 .RE
 420 .
 421 .SS "SSL Configuration"
 422 When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
 423 controller connectivity, the following parameters are required:
 424 .TP
 425 \fIprivate-key\fR
 426 Specifies a PEM file containing the private key used as the virtual
 427 switch's identity for SSL connections to the controller.
 428 .TP
 429 \fIcertificate\fR
 430 Specifies a PEM file containing a certificate, signed by the
 431 certificate authority (CA) used by the controller and manager, that
 432 certifies the virtual switch's private key, identifying a trustworthy
 433 switch.
 434 .TP
 435 \fIca-cert\fR
 436 Specifies a PEM file containing the CA certificate used to verify that
 437 the virtual switch is connected to a trustworthy controller.
 438 .PP
 439 These files are read only once, at \fBovs\-vswitchd\fR startup time.  If
 440 their contents change, \fBovs\-vswitchd\fR must be killed and restarted.
 441 .PP
 442 These SSL settings apply to all SSL connections made by the virtual
 443 switch.
 444 .
 445 .IP "\fBget\-ssl\fR"
 446 Prints the SSL configuration.
 447 .
 448 .IP "\fBdel\-ssl\fR"
 449 Deletes the current SSL configuration.
 450 .
 451 .IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR"
 452 Sets the SSL configuration.  The \fB\-\-bootstrap\fR option is described
 453 below.
 454 .
 455 .ST "CA Certificate Bootstrap"
 456 .PP
 457 Ordinarily, all of the files named in the SSL configuration must exist
 458 when \fBovs\-vswitchd\fR starts.  However, if the \fIca-cert\fR file
 459 does not exist and the \fB\-\-bootstrap\fR
 460 option is given, then \fBovs\-vswitchd\fR will attempt to obtain the
 461 CA certificate from the controller on its first SSL connection and
 462 save it to the named PEM file.  If it is successful, it will
 463 immediately drop the connection and reconnect, and from then on all
 464 SSL connections must be authenticated by a certificate signed by the
 465 CA certificate thus obtained.
 466 .PP
 467 \fBThis option exposes the SSL connection to a man-in-the-middle
 468 attack obtaining the initial CA certificate\fR, but it may be useful
 469 for bootstrapping.
 470 .PP
 471 This option is only useful if the controller sends its CA certificate
 472 as part of the SSL certificate chain.  The SSL protocol does not
 473 require the controller to send the CA certificate.
 474 .
 475 .SS "Auto-Attach Commands"
 476 .
 477 The IETF Auto-Attach SPBM draft standard describes a compact method of using
 478 IEEE 802.1AB Link Layer Discovery Protocol (LLDP) together with a IEEE 802.1aq
 479 Shortest Path Bridging (SPB) network to automatically attach network devices to
 480 individual services in a SPB network.  The intent here is to allow network
 481 applications and devices using OVS to be able to easily take advantage of
 482 features offered by industry standard SPB networks. A fundamental element of
 483 the Auto-Attach feature is to map traditional VLANs onto SPB I_SIDs. These
 484 commands manage the Auto-Attach I-SID/VLAN mappings.
 485 .
 486 .IP "\fBadd\-aa\-mapping \fIbridge i-sid vlan\fR"
 487 Creates a new Auto-Attach mapping on \fIbridge\fR for \fIi-sid\fR
 488 and \fIvlan\fR.
 489 .
 490 .IP "\fBdel\-aa\-mapping \fIbridge i-sid vlan\fR"
 491 Deletes an Auto-Attach mapping on \fIbridge\fR for \fIi-sid\fR
 492 and \fIvlan\fR.
 493 .IP "\fBget\-aa\-mapping \fIbridge\fR"
 494 Lists all of the Auto-Attach mappings within \fIbridge\fR on standard output.
 495 .
 496 .SS "Database Commands"
 497 .
 498 These commands query and modify the contents of \fBovsdb\fR tables.
 499 They are a slight abstraction of the \fBovsdb\fR interface and as such
 500 they operate at a lower level than other \fBovs\-vsctl\fR commands.
 501 .PP
 502 .ST "Identifying Tables, Records, and Columns"
 503 .PP
 504 Each of these commands has a \fItable\fR parameter to identify a table
 505 within the database.  Many of them also take a \fIrecord\fR parameter
 506 that identifies a particular record within a table.  The \fIrecord\fR
 507 parameter may be the UUID for a record, and many tables offer
 508 additional ways to identify records.  Some commands also take
 509 \fIcolumn\fR parameters that identify a particular field within the
 510 records in a table.
 511 .PP
 512 The following tables are currently defined:
 513 .IP "\fBOpen_vSwitch\fR"
 514 Global configuration for an \fBovs\-vswitchd\fR.  This table contains
 515 exactly one record, identified by specifying \fB.\fR as the record
 516 name.
 517 .IP "\fBBridge\fR"
 518 Configuration for a bridge within an Open vSwitch.  Records may be
 519 identified by bridge name.
 520 .IP "\fBPort\fR"
 521 A bridge port.  Records may be identified by port name.
 522 .IP "\fBInterface\fR"
 523 A network device attached to a port.  Records may be identified by
 524 name.
 525 .IP "\fBFlow_Table\fR"
 526 Configuration for a particular OpenFlow flow table.  Records may be
 527 identified by name.
 528 .IP "\fBQoS\fR"
 529 Quality-of-service configuration for a \fBPort\fR.  Records may be
 530 identified by port name.
 531 .IP "\fBQueue\fR"
 532 Configuration for one queue within a \fBQoS\fR configuration.  Records
 533 may only be identified by UUID.
 534 .IP "\fBMirror\fR"
 535 A port mirroring configuration attached to a bridge.  Records may be
 536 identified by mirror name.
 537 .IP "\fBController\fR"
 538 Configuration for an OpenFlow controller.  A controller attached to a
 539 particular bridge may be identified by the bridge's name.
 540 .IP "\fBManager\fR"
 541 Configuration for an OVSDB connection.  Records may be identified
 542 by target (e.g. \fBtcp:1.2.3.4\fR).
 543 .IP "\fBNetFlow\fR"
 544 A NetFlow configuration attached to a bridge.  Records may be
 545 identified by bridge name.
 546 .IP "\fBSSL\fR"
 547 The global SSL configuration for \fBovs\-vswitchd\fR.  The record
 548 attached to the \fBOpen_vSwitch\fR table may be identified by
 549 specifying \fB.\fR as the record name.
 550 .IP "\fBsFlow\fR"
 551 An sFlow exporter configuration attached to a bridge.  Records may be
 552 identified by bridge name.
 553 .IP "\fBIPFIX\fR"
 554 An IPFIX exporter configuration attached to a bridge.  Records may be
 555 identified by bridge name.
 556 .IP "\fBFlow_Sample_Collector_Set\fR"
 557 An IPFIX exporter configuration attached to a bridge for sampling
 558 packets on a per-flow basis using OpenFlow \fBsample\fR actions.
 559 .IP "\fBAutoAttach\fR"
 560 Configuration for Auto Attach within a bridge.
 561 .PP
 562 Record names must be specified in full and with correct
 563 capitalization.  Names of tables and columns are not case-sensitive,
 564 and \fB\-\-\fR and \fB_\fR are treated interchangeably.  Unique
 565 abbreviations are acceptable, e.g. \fBnet\fR or \fBn\fR is sufficient
 566 to identify the \fBNetFlow\fR table.
 567 .
 568 .so lib/db-ctl-base.man
 569 .SH "EXAMPLES"
 570 Create a new bridge named br0 and add port eth0 to it:
 571 .IP
 572 .B "ovs\-vsctl add\-br br0"
 573 .br
 574 .B "ovs\-vsctl add\-port br0 eth0"
 575 .PP
 576 Alternatively, perform both operations in a single atomic transaction:
 577 .IP
 578 .B "ovs\-vsctl add\-br br0 \-\- add\-port br0 eth0"
 579 .PP
 580 Delete bridge \fBbr0\fR, reporting an error if it does not exist:
 581 .IP
 582 .B "ovs\-vsctl del\-br br0"
 583 .PP
 584 Delete bridge \fBbr0\fR if it exists:
 585 .IP
 586 .B "ovs\-vsctl \-\-if\-exists del\-br br0"
 587 .PP
 588 Set the \fBqos\fR column of the \fBPort\fR record for \fBeth0\fR to
 589 point to a new \fBQoS\fR record, which in turn points with its queue 0
 590 to a new \fBQueue\fR record:
 591 .IP
 592 .B "ovs\-vsctl \-\- set port eth0 qos=@newqos \-\- \-\-id=@newqos create qos type=linux\-htb other\-config:max\-rate=1000000 queues:0=@newqueue \-\- \-\-id=@newqueue create queue other\-config:min\-rate=1000000 other\-config:max\-rate=1000000"
 593 .SH "CONFIGURATION COOKBOOK"
 594 .SS "Port Configuration"
 595 .PP
 596 Add an ``internal port'' \fBvlan10\fR to bridge \fBbr0\fR as a VLAN
 597 access port for VLAN 10, and configure it with an IP address:
 598 .IP
 599 .B "ovs\-vsctl add\-port br0 vlan10 tag=10 \-\- set Interface vlan10 type=internal"
 600 .IP
 601 .B "ifconfig vlan10 192.168.0.123"
 602 .
 603 .PP
 604 Add a GRE tunnel port \fBgre0\fR to remote IP address 1.2.3.4 to
 605 bridge \fBbr0\fR:
 606 .IP
 607 .B "ovs\-vsctl add\-port br0 gre0 \-\- set Interface gre0 type=gre options:remote_ip=1.2.3.4"
 608 .
 609 .SS "Port Mirroring"
 610 .PP
 611 Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto
 612 \fBeth2\fR, assuming that all of those ports exist on bridge \fBbr0\fR
 613 (as a side-effect this causes any packets received on \fBeth2\fR to be
 614 ignored):
 615 .IP
 616 .B "ovs\-vsctl \-\- set Bridge br0 mirrors=@m \(rs"
 617 .IP
 618 .B "\-\- \-\-id=@eth0 get Port eth0 \(rs"
 619 .IP
 620 .B "\-\- \-\-id=@eth1 get Port eth1 \(rs"
 621 .IP
 622 .B "\-\- \-\-id=@eth2 get Port eth2 \(rs"
 623 .IP
 624 .B "\-\- \-\-id=@m create Mirror name=mymirror select-dst-port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2"
 625 .PP
 626 Remove the mirror created above from \fBbr0\fR, which also destroys
 627 the Mirror record (since it is now unreferenced):
 628 .IP
 629 .B "ovs\-vsctl \-\- \-\-id=@rec get Mirror mymirror \(rs"
 630 .IP
 631 .B "\-\- remove Bridge br0 mirrors @rec"
 632 .PP
 633 The following simpler command also works:
 634 .IP
 635 .B "ovs\-vsctl clear Bridge br0 mirrors"
 636 .SS "Quality of Service (QoS)"
 637 .PP
 638 Create a \fBlinux\-htb\fR QoS record that points to a few queues and
 639 use it on \fBeth0\fR and \fBeth1\fR:
 640 .IP
 641 .B "ovs\-vsctl \-\- set Port eth0 qos=@newqos \(rs"
 642 .IP
 643 .B "\-\- set Port eth1 qos=@newqos \(rs"
 644 .IP
 645 .B "\-\- \-\-id=@newqos create QoS type=linux\-htb other\-config:max\-rate=1000000000 queues=0=@q0,1=@q1 \(rs"
 646 .IP
 647 .B "\-\- \-\-id=@q0 create Queue other\-config:min\-rate=100000000 other\-config:max\-rate=100000000 \(rs"
 648 .IP
 649 .B "\-\- \-\-id=@q1 create Queue other\-config:min\-rate=500000000"
 650 .PP
 651 Deconfigure the QoS record above from \fBeth1\fR only:
 652 .IP
 653 .B "ovs\-vsctl clear Port eth1 qos"
 654 .PP
 655 To deconfigure the QoS record from both \fBeth0\fR and \fBeth1\fR and
 656 then delete the QoS record (which must be done explicitly because
 657 unreferenced QoS records are not automatically destroyed):
 658 .IP
 659 .B "ovs\-vsctl \-\- destroy QoS eth0 \-\- clear Port eth0 qos \-\- clear Port eth1 qos"
 660 .PP
 661 (This command will leave two unreferenced Queue records in the
 662 database.  To delete them, use "\fBovs\-vsctl list Queue\fR" to find
 663 their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR
 664 \fIuuid2\fR" to destroy each of them or use
 665 "\fBovs\-vsctl -- --all destroy Queue\fR" to delete all records.)
 666 .SS "Connectivity Monitoring"
 667 .PP
 668 Monitor connectivity to a remote maintenance point on eth0.
 669 .IP
 670 .B "ovs\-vsctl set Interface eth0 cfm_mpid=1"
 671 .PP
 672 Deconfigure connectivity monitoring from above:
 673 .IP
 674 .B "ovs\-vsctl clear Interface eth0 cfm_mpid"
 675 .SS "NetFlow"
 676 .PP
 677 Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on
 678 host 192.168.0.34, with an active timeout of 30 seconds:
 679 .IP
 680 .B "ovs\-vsctl \-\- set Bridge br0 netflow=@nf \(rs"
 681 .IP
 682 .B "\-\- \-\-id=@nf create NetFlow targets=\(rs\(dq192.168.0.34:5566\(rs\(dq active\-timeout=30"
 683 .PP
 684 Update the NetFlow configuration created by the previous command to
 685 instead use an active timeout of 60 seconds:
 686 .IP
 687 .B "ovs\-vsctl set NetFlow br0 active_timeout=60"
 688 .PP
 689 Deconfigure the NetFlow settings from \fBbr0\fR, which also destroys
 690 the NetFlow record (since it is now unreferenced):
 691 .IP
 692 .B "ovs\-vsctl clear Bridge br0 netflow"
 693 .SS "sFlow"
 694 .PP
 695 Configure bridge \fBbr0\fR to send sFlow records to a collector on
 696 10.0.0.1 at port 6343, using \fBeth1\fR\'s IP address as the source,
 697 with specific sampling parameters:
 698 .IP
 699 .B "ovs\-vsctl \-\- \-\-id=@s create sFlow agent=eth1 target=\(rs\(dq10.0.0.1:6343\(rs\(dq header=128 sampling=64 polling=10 \(rs"
 700 .IP
 701 .B "\-\- set Bridge br0 sflow=@s"
 702 .PP
 703 Deconfigure sFlow from \fBbr0\fR, which also destroys the sFlow record
 704 (since it is now unreferenced):
 705 .IP
 706 .B "ovs\-vsctl \-\- clear Bridge br0 sflow"
 707 .SS "IPFIX"
 708 .PP
 709 Configure bridge \fBbr0\fR to send one IPFIX flow record per packet
 710 sample to UDP port 4739 on host 192.168.0.34, with Observation Domain
 711 ID 123 and Observation Point ID 456, a flow cache active timeout of 1
 712 minute (60 seconds), maximum flow cache size of 13 flows, and flows
 713 sampled on output port with tunnel info(sampling on input and output
 714 port is enabled by default if not disabled) :
 715 .IP
 716 .B "ovs\-vsctl \-\- set Bridge br0 ipfix=@i \(rs"
 717 .IP
 718 .B "\-\- \-\-id=@i create IPFIX targets=\(rs\(dq192.168.0.34:4739\(rs\(dq obs_domain_id=123 obs_point_id=456 cache_active_timeout=60 cache_max_flows=13 \(rs"
 719 .IP
 720 .B "other_config:enable-input-sampling=false other_config:enable-tunnel-sampling=true"
 721 .PP
 722 Deconfigure the IPFIX settings from \fBbr0\fR, which also destroys the
 723 IPFIX record (since it is now unreferenced):
 724 .IP
 725 .B "ovs\-vsctl clear Bridge br0 ipfix"
 726 .SS "802.1D Spanning Tree Protocol (STP)"
 727 .PP
 728 Configure bridge \fBbr0\fR to participate in an 802.1D spanning tree:
 729 .IP
 730 .B "ovs\-vsctl set Bridge br0 stp_enable=true"
 731 .PP
 732 Set the bridge priority of \fBbr0\fR to 0x7800:
 733 .IP
 734 .B "ovs\-vsctl set Bridge br0 other_config:stp-priority=0x7800"
 735 .PP
 736 Set the path cost of port \fBeth0\fR to 10:
 737 .IP
 738 .B "ovs\-vsctl set Port eth0 other_config:stp-path-cost=10"
 739 .PP
 740 Deconfigure STP from above:
 741 .IP
 742 .B "ovs\-vsctl set Bridge br0 stp_enable=false"
 743 .PP
 744 .SS "Multicast Snooping"
 745 .PP
 746 Configure bridge \fBbr0\fR to enable multicast snooping:
 747 .IP
 748 .B "ovs\-vsctl set Bridge br0 mcast_snooping_enable=true"
 749 .PP
 750 Set the multicast snooping aging time \fBbr0\fR to 300 seconds:
 751 .IP
 752 .B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-aging-time=300"
 753 .PP
 754 Set the multicast snooping table size \fBbr0\fR to 2048 entries:
 755 .IP
 756 .B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-table-size=2048"
 757 .PP
 758 Disable flooding of unregistered multicast packets to all ports. When
 759 set to \fBtrue\fR, the switch will send unregistered multicast packets only
 760 to ports connected to multicast routers. When it is set to \fBfalse\fR, the
 761 switch will send them to all ports. This command disables the flood of
 762 unregistered packets on bridge \fBbr0\fR.
 763 .IP
 764 .B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-disable-flood-unregistered=true"
 765 .PP
 766 Enable flooding of multicast packets (except Reports) on a specific port.
 767 .IP
 768 .B "ovs\-vsctl set Port eth1 other_config:mcast-snooping-flood=true"
 769 .PP
 770 Enable flooding of Reports on a specific port.
 771 .IP
 772 .B "ovs\-vsctl set Port eth1 other_config:mcast-snooping-flood-reports=true"
 773 .PP
 774 Deconfigure multicasting snooping from above:
 775 .IP
 776 .B "ovs\-vsctl set Bridge br0 mcast_snooping_enable=false"
 777 .PP
 778 .SS "802.1D-2004 Rapid Spanning Tree Protocol (RSTP)"
 779 .PP
 780 Configure bridge \fBbr0\fR to participate in an 802.1D-2004 Rapid Spanning Tree:
 781 .IP
 782 .B "ovs\-vsctl set Bridge br0 rstp_enable=true"
 783 .PP
 784 Set the bridge address of \fBbr0\fR to 00:aa:aa:aa:aa:aa :
 785 .IP
 786 .B "ovs\-vsctl set Bridge br0 other_config:rstp-address=00:aa:aa:aa:aa:aa"
 787 .PP
 788 Set the bridge priority of \fBbr0\fR to 0x7000. The value must be specified in
 789 decimal notation and should be a multiple of 4096 (if not, it is rounded down to
 790 the nearest multiple of 4096). The default priority value is 0x800 (32768).
 791 .IP
 792 .B "ovs\-vsctl set Bridge br0 other_config:rstp-priority=28672"
 793 .PP
 794 Set the bridge ageing time of \fBbr0\fR to 1000 s. The ageing time value should be
 795 between 10 s and 1000000 s. The default value is 300 s.
 796 .IP
 797 .B "ovs\-vsctl set Bridge br0 other_config:rstp-ageing-time=1000"
 798 .PP
 799 Set the bridge force protocol version of \fBbr0\fR to 0. The force protocol version
 800 has two acceptable values: 0 (STP compatibility mode) and 2 (normal operation).
 801 .IP
 802 .B "ovs\-vsctl set Bridge br0 other_config:rstp-force-protocol-version=0"
 803 .PP
 804 Set the bridge max age of \fBbr0\fR to 10 s. The max age value should be between 6 s
 805 and 40 s. The default value is 20 s.
 806 .IP
 807 .B "ovs\-vsctl set Bridge br0 other_config:rstp-max-age=10"
 808 .PP
 809 Set the bridge forward delay of \fBbr0\fR to 15 s.
 810 This value should be between 4 s and 30 s. The default value is 15 s.
 811 .IP
 812 .B "ovs\-vsctl set Bridge br0 other_config:rstp-forward-delay=15"
 813 .PP
 814 Set the bridge transmit hold count of \fBbr0\fR to 7 s. This value should be between
 815 1 s and 10 s. The default value is 6 s.
 816 .IP
 817 .B "ovs\-vsctl set Bridge br0 other_config:rstp-transmit-hold-count=7"
 818 .PP
 819 Enable RSTP on the Port \fBeth0\fR:
 820 .IP
 821 .B "ovs\-vsctl set Port eth0 other_config:rstp-enable=true"
 822 .PP
 823 Disable RSTP on the Port \fBeth0\fR:
 824 .IP
 825 .B "ovs\-vsctl set Port eth0 other_config:rstp-enable=false"
 826 .PP
 827 Set the priority of port \fBeth0\fR to 32. The value must be specified in
 828 decimal notation and should be a multiple of 16 (if not, it is rounded down to the
 829 nearest multiple of 16). The default priority value is 0x80 (128).
 830 .IP
 831 .B "ovs\-vsctl set Port eth0 other_config:rstp-port-priority=32"
 832 .PP
 833 Set the port number of port \fBeth0\fR to 3:
 834 .IP
 835 .B "ovs\-vsctl set Port eth0 other_config:rstp-port-num=3"
 836 .PP
 837 Set the path cost of port \fBeth0\fR to 150:
 838 .IP
 839 .B "ovs\-vsctl set Port eth0 other_config:rstp-path-cost=150"
 840 .PP
 841 Set the admin edge value of port \fBeth0\fR:
 842 .IP
 843 .B "ovs\-vsctl set Port eth0 other_config:rstp-port-admin-edge=true"
 844 .PP
 845 Set the auto edge value of port \fBeth0\fR:
 846 .IP
 847 .B "ovs\-vsctl set Port eth0 other_config:rstp-port-auto-edge=true"
 848 .PP
 849 Set the admin point to point MAC value of port \fBeth0\fR.  Acceptable
 850 values are \fB0\fR (not point-to-point), \fB1\fR (point-to-point, the
 851 default value) or \fB2\fR (automatic detection).  The auto-detection
 852 mode is not currently implemented, and the value \fB2\fR has the same
 853 effect of \fB0\fR (not point-to-point).
 854 .IP
 855 .B "ovs\-vsctl set Port eth0 other_config:rstp-admin-p2p-mac=1"
 856 .PP
 857 Set the admin port state value of port \fBeth0\fR.  \fBtrue\fR is the
 858 default value.
 859 .IP
 860 .B "ovs\-vsctl set Port eth0 other_config:rstp-admin-port-state=false"
 861 .PP
 862 Set the mcheck value of port \fBeth0\fR:
 863 .IP
 864 .B "ovs\-vsctl set Port eth0 other_config:rstp-port-mcheck=true"
 865 .PP
 866 Deconfigure RSTP from above:
 867 .IP
 868 .B "ovs\-vsctl set Bridge br0 rstp_enable=false"
 869 .PP
 870 .SS "OpenFlow Version"
 871 .PP
 872 Configure bridge \fBbr0\fR to support OpenFlow versions 1.0, 1.2, and
 873 1.3:
 874 .IP
 875 .B "ovs\-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow12,OpenFlow13"
 876 .
 877 .SS "Flow Table Configuration"
 878 Limit flow table 0 on bridge br0 to a maximum of 100 flows:
 879 .IP
 880 .B "ovs\-vsctl \-\- \-\-id=@ft create Flow_Table flow_limit=100 overflow_policy=refuse \-\- set Bridge br0 flow_tables=0=@ft"
 881 .SH "EXIT STATUS"
 882 .IP "0"
 883 Successful program execution.
 884 .IP "1"
 885 Usage, syntax, or configuration file error.
 886 .IP "2"
 887 The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a
 888 bridge that does not exist.
 889 .SH "SEE ALSO"
 890 .
 891 .BR ovsdb\-server (1),
 892 .BR ovs\-vswitchd (8),
 893 .BR ovs\-vswitchd.conf.db (5).