ovs-vsctl: Add tests that adding duplicate bridges or ports fails.

[ovs.git] / utilities / ovs-discover.8.in

.TH ovs\-discover 8 "May 2008" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovs\-discover

.SH NAME
ovs\-discover \- controller discovery utility

.SH SYNOPSIS
.B ovs\-discover
[\fIoptions\fR] \fInetdev\fR [\fInetdev\fR...]

.SH DESCRIPTION
The \fBovs\-discover\fR program attempts to discover the location of
an OpenFlow controller on one of the network devices listed on the
command line.  It repeatedly broadcasts a DHCP request with vendor
class identifier \fBOpenFlow\fR on each network device until it
receives an acceptable DHCP response.  It will accept any valid DHCP
reply that has the same vendor class identifier and includes a
vendor-specific option with code 1 whose contents are a string
specifying the location of the controller in the same format used on
the \fBovs\-openflowd\fR command line (e.g. \fBssl:192.168.0.1\fR).

When \fBovs\-discover\fR receives an acceptable response, it prints
the details of the response on \fBstdout\fR.  Then, by default, it
configures the network device on which the response was received with
the received IP address, netmask, and default gateway, and detaches
itself to the background.

.SH OPTIONS
.TP
\fB--accept-vconn=\fIregex\fR
With this option, only controllers whose names match POSIX extended
regular expression \fIregex\fR will be accepted.  Specifying
\fBssl:.*\fR for \fIregex\fR, for example, would cause only SSL
controller connections to be accepted.

The \fIregex\fR is implicitly anchored at the beginning of the
controller location string, as if it begins with \fB^\fR.

When this option is not given, the default \fIregex\fR is
\fBtcp:.*\fR.
.TP
\fB--exit-without-bind\fR
By default, \fBovs\-discover\fR binds the network device that receives
the first acceptable response to the IP address received over DHCP.
With this option, the configuration of the network device is not
changed at all, except to bring it up if it is initially down, and
\fBovs\-discover\fR will exit immediately after it receives an
acceptable DHCP response.

This option is mutually exclusive with \fB--exit-after-bind\fR and
\fB--no-detach\fR.

.TP
\fB--exit-after-bind\fR
By default, after it receives an acceptable DHCP response,
\fBovs\-discover\fR detaches itself from the foreground session and
runs in the background maintaining the DHCP lease as necessary.  With
this option, \fBovs\-discover\fR will exit immediately after it
receives an acceptable DHCP response and configures the network device
with the received IP address.  The address obtained via DHCP could
therefore be used past the expiration of its lease.

This option is mutually exclusive with \fB--exit-without-bind\fR and
\fB--no-detach\fR.

.TP
\fB--no-detach\fR
By default, \fBovs\-discover\fR runs in the foreground until it obtains
an acceptable DHCP response, then it detaches itself from the
foreground session and run as a background process.  This option
prevents \fBovs\-discover\fR from detaching, causing it to run in the
foreground even after it obtains a DHCP response.

This option is mutually exclusive with \fB--exit-without-bind\fR and
\fB--exit-after-bind\fR.

.TP
\fB--pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fBovs\-discover.pid\fR) to be created indicating
the PID of the running process.  If \fIpidfile\fR is not specified, or
if it does not begin with \fB/\fR, then it is created in
\fB@RUNDIR@\fR.

The \fIpidfile\fR is created when \fBovs\-discover\fR detaches, so
this this option has no effect when one of \fB--exit-without-bind\fR,
\fB--exit-after-bind\fR, or \fB--no-detach\fR is also given.

.TP
\fB--overwrite-pidfile\fR
By default, when \fB--pidfile\fR is specified and the specified pidfile 
already exists and is locked by a running process, \fBcontroller\fR refuses 
to start.  Specify \fB--overwrite-pidfile\fR to cause it to instead 
overwrite the pidfile.

When \fB--pidfile\fR is not specified, this option has no effect.

.so lib/vlog.man
.so lib/common.man

.SH BUGS

If the network devices specified on the command line have been added
to an Open vSwitch datapath with \fBovs\-dpctl add\-if\fR, then controller
discovery will fail because \fBovs\-discover\fR will not be able to
see DHCP responses, even though tools such as \fBtcpdump\fR(8) and
\fBwireshark\fR(1) can see them on the wire.  This is because of the
structure of the Linux kernel networking stack, which hands packets
first to programs that listen for all arriving packets, then to
Open vSwitch, then to programs that listen for a specific kind of packet.
Open vSwitch consumes all the packets handed to it, so tools like
\fBtcpdump\fR that look at all packets will see packets arriving on
Open vSwitch interfaces, but \fRovs\-discover\fR, which listens only for
arriving IP packets, will not.

.SH "SEE ALSO"

.BR ovs\-openflowd (8),
.BR ovs\-pki (8)