vtep/vtep-ctl.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 vtep\-ctl 8 "March 2013" "Open vSwitch" "Open vSwitch Manual"
  14 .\" This program's name:
  15 .ds PN vtep\-ctl
  16 .
  17 .SH NAME
  18 vtep\-ctl \- utility for querying and configuring a VTEP database
  19 .
  20 .SH SYNOPSIS
  21 \fBvtep\-ctl\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 \fBvtep\-ctl\fR program configures a VTEP database.
  26 See \fBvtep\fR(5) for comprehensive documentation of
  27 the database schema.
  28 .PP
  29 \fBvtep\-ctl\fR connects to an \fBovsdb\-server\fR process that
  30 maintains a VTEP configuration database.  Using this connection, it
  31 queries and possibly applies changes to the database, depending on the
  32 supplied commands.
  33 .PP
  34 \fBvtep\-ctl\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 \fBvtep\-ctl\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 itself starts with command-specific options, if any, followed by
  43 the command name and any arguments.  See \fBEXAMPLES\fR below for syntax
  44 examples.
  45 .
  46 .SH OPTIONS
  47 .
  48 The following options affect the behavior \fBvtep\-ctl\fR as a whole.
  49 Some individual commands also accept their own options, which are
  50 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"
  55 Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR
  56 contacts to query or modify configuration.  The default is
  57 \fBunix:@RUNDIR@/db.sock\fR.  \fIserver\fR must take one of the
  58 following forms:
  59 .RS
  60 .so ovsdb/remote-active.man
  61 .so ovsdb/remote-passive.man
  62 .RE
  63 .
  64 .IP "\fB\-\-no\-syslog\fR"
  65 By default, \fBvtep\-ctl\fR logs its arguments and the details of any
  66 changes that it makes to the system log.  This option disables this
  67 logging.
  68 .IP
  69 This option is equivalent to \fB\-\-verbose=vtep_ctl:syslog:warn\fR.
  70 .
  71 .IP "\fB\-\-oneline\fR"
  72 Modifies the output format so that the output for each command is printed
  73 on a single line.  New-line characters that would otherwise separate
  74 lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that
  75 would otherwise appear in the output are doubled.
  76 Prints a blank line for each command that has no output.
  77 This option does not affect the formatting of output from the
  78 \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
  79 below.
  80 .
  81 .IP "\fB\-\-dry\-run\fR"
  82 Prevents \fBvtep\-ctl\fR from actually modifying the database.
  83 .
  84 .IP "\fB\-t \fIsecs\fR"
  85 .IQ "\fB\-\-timeout=\fIsecs\fR"
  86 By default, or with a \fIsecs\fR of \fB0\fR, \fBvtep\-ctl\fR waits
  87 forever for a response from the database.  This option limits runtime
  88 to approximately \fIsecs\fR seconds.  If the timeout expires,
  89 \fBvtep\-ctl\fR will exit with a \fBSIGALRM\fR signal.  (A timeout
  90 would normally happen only if the database cannot be contacted, or if
  91 the system is overloaded.)
  92 .
  93 .SS "Table Formatting Options"
  94 These options control the format of output from the \fBlist\fR and
  95 \fBfind\fR commands.
  96 .so lib/table.man
  97 .
  98 .SS "Public Key Infrastructure Options"
  99 .so lib/ssl.man
 100 .so lib/ssl-bootstrap.man
 101 .so lib/ssl-peer-ca-cert.man
 102 .so lib/vlog.man
 103 .so lib/common.man
 104 .
 105 .SH COMMANDS
 106 The commands implemented by \fBvtep\-ctl\fR are described in the
 107 sections below.
 108 .
 109 .SS "Physical Switch Commands"
 110 These commands examine and manipulate physical switches.
 111 .
 112 .IP "[\fB\-\-may\-exist\fR] \fBadd\-ps \fIpswitch\fR"
 113 Creates a new physical switch named \fIpswitch\fR.  Initially the switch
 114 will have no ports.
 115 .IP
 116 Without \fB\-\-may\-exist\fR, attempting to create a switch that
 117 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 118 nothing if \fIpswitch\fR already exists.
 119 .
 120 .IP "[\fB\-\-if\-exists\fR] \fBdel\-ps \fIpswitch\fR"
 121 Deletes \fIpswitch\fR and all of its ports.
 122 .IP
 123 Without \fB\-\-if\-exists\fR, attempting to delete a switch that does
 124 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 125 delete a switch that does not exist has no effect.
 126 .
 127 .IP "\fBlist\-ps\fR"
 128 Lists all existing physical switches on standard output, one per line.
 129 .
 130 .IP "\fBps\-exists \fIpswitch\fR"
 131 Tests whether \fIpswitch\fR exists.  If so, \fBvtep\-ctl\fR exits
 132 successfully with exit code 0.  If not, \fBvtep\-ctl\fR exits
 133 unsuccessfully with exit code 2.
 134 .
 135 .SS "Port Commands"
 136 .
 137 These commands examine and manipulate VTEP physical ports.
 138 .
 139 .IP "\fBlist\-ports \fIpswitch\fR"
 140 Lists all of the ports within \fIpswitch\fR on standard output, one per
 141 line.
 142 .
 143 .IP "[\fB\-\-may\-exist\fR] \fBadd\-port \fIpswitch port\fR"
 144 Creates on \fIpswitch\fR a new port named \fIport\fR from the network
 145 device of the same name.
 146 .IP
 147 Without \fB\-\-may\-exist\fR, attempting to create a port that exists
 148 is an error.  With \fB\-\-may\-exist\fR, this command does nothing if
 149 \fIport\fR already exists on \fIpswitch\fR.
 150 .
 151 .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIpswitch\fR] \fIport\fR"
 152 Deletes \fIport\fR.  If \fIpswitch\fR is omitted, \fIport\fR is removed
 153 from whatever switch contains it; if \fIpswitch\fR is specified, it
 154 must be the switch that contains \fIport\fR.
 155 .IP
 156 Without \fB\-\-if\-exists\fR, attempting to delete a port that does
 157 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 158 delete a port that does not exist has no effect.
 159 .
 160 .SS "Logical Switch Commands"
 161 These commands examine and manipulate logical switches.
 162 .
 163 .IP "[\fB\-\-may\-exist\fR] \fBadd\-ls \fIlswitch\fR"
 164 Creates a new logical switch named \fIlswitch\fR.  Initially the switch
 165 will have no locator bindings.
 166 .IP
 167 Without \fB\-\-may\-exist\fR, attempting to create a switch that
 168 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 169 nothing if \fIlswitch\fR already exists.
 170 .
 171 .IP "[\fB\-\-if\-exists\fR] \fBdel\-ls \fIlswitch\fR"
 172 Deletes \fIlswitch\fR.
 173 .IP
 174 Without \fB\-\-if\-exists\fR, attempting to delete a switch that does
 175 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 176 delete a switch that does not exist has no effect.
 177 .
 178 .IP "\fBlist\-ls\fR"
 179 Lists all existing logical switches on standard output, one per line.
 180 .
 181 .IP "\fBls\-exists \fIlswitch\fR"
 182 Tests whether \fIlswitch\fR exists.  If so, \fBvtep\-ctl\fR exits
 183 successfully with exit code 0.  If not, \fBvtep\-ctl\fR exits
 184 unsuccessfully with exit code 2.
 185 .
 186 .IP "\fBbind\-ls \fIpswitch port vlan lswitch\fR"
 187 Bind logical switch \fIlswitch\fR to the \fIport\fR/\fIvlan\fR
 188 combination on the physical switch \fIpswitch\fR.
 189 .
 190 .IP "\fBunbind\-ls \fIpswitch port vlan\fR"
 191 Remove the logical switch binding from the \fIport\fR/\fIvlan\fR
 192 combination on the physical switch \fIpswitch\fR.
 193 .
 194 .IP "\fBlist\-bindings \fIpswitch port\fR"
 195 List the logical switch bindings for \fIport\fR on the physical switch
 196 \fIpswitch\fR.
 197 .
 198 .IP "\fBset\-replication\-mode \fIlswitch replication\-mode\fR"
 199 Set logical switch \fIlswitch\fR replication mode to
 200 \fIreplication\-mode\fR; the only valid values for replication mode
 201 are "service_node" and "source_node".
 202 .
 203 For handling L2 broadcast, multicast and unknown unicast traffic,
 204 packets can be sent to all members of a logical switch referenced by
 205 a physical switch.  There are different modes to replicate the
 206 packets.  The default mode of replication is to send the traffic to
 207 a service node, which can be a hypervisor, server or appliance, and
 208 let the service node handle replication to other transport nodes
 209 (hypervisors or other VTEP physical switches).  This mode is called
 210 service node replication.  An alternate mode of replication, called
 211 source node replication involves the source node sending to all
 212 other transport nodes.  Hypervisors are always responsible for doing
 213 their own replication for locally attached VMs in both modes.
 214 Service node mode is the default, if the replication mode is not
 215 explicitly set.  Service node replication mode is considered a basic
 216 requirement because it only requires sending the packet to a single
 217 transport node.
 218 .
 219 .IP "\fBget\-replication\-mode \fIlswitch\fR"
 220 Get logical switch \fIlswitch\fR replication mode.  The only valid values
 221 for replication mode are "service_node" and "source_node".  An empty reply
 222 for replication mode implies a default of "service_node".
 223 .
 224 .SS "Logical Router Commands"
 225 These commands examine and manipulate logical routers.
 226 .
 227 .IP "[\fB\-\-may\-exist\fR] \fBadd\-lr \fIlrouter\fR"
 228 Creates a new logical router named \fIlrouter\fR.
 229 .IP
 230 Without \fB\-\-may\-exist\fR, attempting to create a router that
 231 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 232 nothing if \fIlrouter\fR already exists.
 233 .
 234 .IP "[\fB\-\-if\-exists\fR] \fBdel\-lr \fIlrouter\fR"
 235 Deletes \fIlrouter\fR.
 236 .IP
 237 Without \fB\-\-if\-exists\fR, attempting to delete a router that does
 238 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 239 delete a router that does not exist has no effect.
 240 .
 241 .IP "\fBlist\-lr\fR"
 242 Lists all existing logical routers on standard output, one per line.
 243 .
 244 .IP "\fBlr\-exists \fIlrouter\fR"
 245 Tests whether \fIlrouter\fR exists.  If so, \fBvtep\-ctl\fR exits
 246 successfully with exit code 0.  If not, \fBvtep\-ctl\fR exits
 247 unsuccessfully with exit code 2.
 248
 249 .SS "Local MAC Binding Commands"
 250 These commands examine and manipulate local MAC bindings for the logical
 251 switch.  The local maps are written by the VTEP to refer to MACs it has
 252 learned on its physical ports.
 253 .
 254 .IP "\fBadd\-ucast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 255 Map the unicast Ethernet address \fImac\fR to the physical location
 256 \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR.  If
 257 \fIencap\fR is not specified, the default is "vxlan_over_ipv4".  The
 258 local mappings are used by the VTEP to refer to MACs learned on its
 259 physical ports.
 260 .
 261 .IP "\fBdel\-ucast\-local \fIlswitch mac\fR"
 262 Remove the local unicast Ethernet address \fImac\fR map from
 263 \fIlswitch\fR.  The local mappings are used by the VTEP to refer to MACs
 264 learned on its physical ports.
 265 .
 266 .IP "\fBadd\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 267 Add physical location \fIip\fR using encapsulation \fIencap\fR to the
 268 local mac binding table for multicast Ethernet address \fImac\fR on
 269 \fIlswitch\fR.  If \fIencap\fR is not specified, the default is
 270 "vxlan_over_ipv4".  The local mappings are used by the VTEP to refer to
 271 MACs learned on its physical ports.
 272 .
 273 .IP "\fBdel\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 274 Remove physical location \fIip\fR using encapsulation \fIencap\fR from
 275 the local mac binding table for multicast Ethernet address \fImac\fR on
 276 \fIlswitch\fR.  If \fIencap\fR is not specified, the default is
 277 "vxlan_over_ipv4".  The local mappings are used by the VTEP to refer to
 278 MACs learned on its physical ports.
 279 .
 280 .IP "\fBclear\-local\-macs \fIlswitch\fR"
 281 Clear the local MAC bindings for \fIlswitch\fR.
 282 .
 283 .IP "\fBlist\-local\-macs \fIlswitch\fR"
 284 List the local MAC bindings for \fIlswitch\fR, one per line.
 285 .
 286 .SS "Remote MAC Binding Commands"
 287 These commands examine and manipulate local and remote MAC bindings for
 288 the logical switch.  The remote maps are written by the network
 289 virtualization controller to refer to MACs that it has learned.
 290 .
 291 .IP "\fBadd\-ucast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 292 Map the unicast Ethernet address \fImac\fR to the physical location
 293 \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR.  If
 294 \fIencap\fR is not specified, the default is "vxlan_over_ipv4".  The
 295 remote mappings are used by the network virtualization platform to refer
 296 to MACs that it has learned.
 297 .
 298 .IP "\fBdel\-ucast\-remote \fIlswitch mac\fR"
 299 Remove the remote unicast Ethernet address \fImac\fR map from
 300 \fIlswitch\fR.  The remote mappings are used by the network
 301 virtualization platform to refer to MACs that it has learned.
 302 .
 303 .IP "\fBadd\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 304 Add physical location \fIip\fR using encapsulation \fIencap\fR to the
 305 remote mac binding table for multicast Ethernet address \fImac\fR on
 306 \fIlswitch\fR.  If \fIencap\fR is not specified, the default is
 307 "vxlan_over_ipv4".  The remote mappings are used by the network
 308 virtualization platform to refer to MACs that it has learned.
 309 .
 310 .IP "\fBdel\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR"
 311 Remove physical location \fIip\fR using encapsulation \fIencap\fR from
 312 the remote mac binding table for multicast Ethernet address \fImac\fR on
 313 \fIlswitch\fR.  If \fIencap\fR is not specified, the default is
 314 "vxlan_over_ipv4".  The remote mappings are used by the network
 315 virtualization platform to refer to MACs that it has learned.
 316 .
 317 .IP "\fBclear\-remote\-macs \fIlswitch\fR"
 318 Clear the remote MAC bindings for \fIlswitch\fR.
 319 .
 320 .IP "\fBlist\-remote\-macs \fIlswitch\fR"
 321 List the remote MAC bindings for \fIlswitch\fR, one per line.
 322 .
 323 .SS "Manager Connectivity"
 324 .
 325 These commands manipulate the \fBmanagers\fR column in the \fBGlobal\fR
 326 table and rows in the \fBManagers\fR table.  When \fBovsdb\-server\fR is
 327 configured to use the \fBmanagers\fR column for OVSDB connections (as
 328 described in \fBINSTALL.Linux\fR and in the startup scripts provided
 329 with Open vSwitch), this allows the administrator to use \fBvtep\-ctl\fR
 330 to configure database connections.
 331 .
 332 .IP "\fBget\-manager\fR"
 333 Prints the configured manager(s).
 334 .
 335 .IP "\fBdel\-manager\fR"
 336 Deletes the configured manager(s).
 337 .
 338 .IP "\fBset\-manager\fR \fItarget\fR\&..."
 339 Sets the configured manager target or targets.  Each \fItarget\fR may
 340 use any of the following forms:
 341 .
 342 .RS
 343 .so ovsdb/remote-active.man
 344 .so ovsdb/remote-passive.man
 345 .RE
 346 .
 347 .SS "Database Commands"
 348 .
 349 These commands query and modify the contents of \fBovsdb\fR tables.
 350 They are a slight abstraction of the \fBovsdb\fR interface and as such
 351 they operate at a lower level than other \fBvtep\-ctl\fR commands.
 352 .PP
 353 .ST "Identifying Tables, Records, and Columns"
 354 .PP
 355 Each of these commands has a \fItable\fR parameter to identify a table
 356 within the database.  Many of them also take a \fIrecord\fR parameter
 357 that identifies a particular record within a table.  The \fIrecord\fR
 358 parameter may be the UUID for a record, and many tables offer
 359 additional ways to identify records.  Some commands also take
 360 \fIcolumn\fR parameters that identify a particular field within the
 361 records in a table.
 362 .PP
 363 The following tables are currently defined:
 364 .IP "\fBGlobal\fR"
 365 Top-level configuration for a hardware VTEP.  This table contains
 366 exactly one record, identified by specifying \fB.\fR as the record name.
 367 .IP "\fBManager\fR"
 368 Configuration for an OVSDB connection.  Records may be identified
 369 by target (e.g. \fBtcp:1.2.3.4\fR).
 370 .IP "\fBPhysical_Switch\fR"
 371 A physical switch that implements a VTEP.  Records may be identified by
 372 physical switch name.
 373 .IP "\fBPhysical_Port\fR"
 374 A port within a physical switch.
 375 .IP "\fBLogical_Binding_Stats\fR"
 376 Reports statistics for the logical switch with which a VLAN on a
 377 physical port is associated.
 378 .IP "\fBLogical_Switch\fR"
 379 A logical Ethernet switch.  Records may be identified by logical switch
 380 name.
 381 .IP "\fBUcast_Macs_Local\fR"
 382 Mapping of locally discovered unicast MAC addresses to tunnels.
 383 .IP "\fBUcast_Macs_Remote\fR"
 384 Mapping of remotely programmed unicast MAC addresses to tunnels.
 385 .IP "\fBMcast_Macs_Local\fR"
 386 Mapping of locally discovered multicast MAC addresses to tunnels.
 387 .IP "\fBMcast_Macs_Remote\fR"
 388 Mapping of remotely programmed multicast MAC addresses to tunnels.
 389 .IP "\fBPhysical_Locator_Set\fR"
 390 A set of one or more physical locators.
 391 .IP "\fBPhysical_Locator\fR"
 392 Identifies an endpoint to which logical switch traffic may be
 393 encapsulated and forwarded.  Records may be identified by physical
 394 locator name.
 395 .PP
 396 Record names must be specified in full and with correct
 397 capitalization.  Names of tables and columns are not case-sensitive,
 398 and \fB\-\-\fR and \fB_\fR are treated interchangeably.  Unique
 399 abbreviations are acceptable, e.g. \fBman\fR or \fBm\fR is sufficient
 400 to identify the \fBManager\fR table.
 401 .
 402 .so lib/db-ctl-base.man
 403 .PP
 404 .SH "EXIT STATUS"
 405 .IP "0"
 406 Successful program execution.
 407 .IP "1"
 408 Usage, syntax, or configuration file error.
 409 .IP "2"
 410 The \fIswitch\fR argument to \fBps\-exists\fR specified the name of a
 411 physical switch that does not exist.
 412 .SH "SEE ALSO"
 413 .
 414 .BR ovsdb\-server (1),
 415 .BR vtep (5).