utilities/ovs-discover.8.in

   1 .TH ovs\-discover 8 "May 2008" "Open vSwitch" "Open vSwitch Manual"
   2 .ds PN ovs\-discover
   3
   4 .SH NAME
   5 ovs\-discover \- controller discovery utility
   6
   7 .SH SYNOPSIS
   8 .B ovs\-discover
   9 [\fIoptions\fR] \fInetdev\fR [\fInetdev\fR...]
  10
  11 .SH DESCRIPTION
  12 The \fBovs\-discover\fR program attempts to discover the location of
  13 an OpenFlow controller on one of the network devices listed on the
  14 command line.  It repeatedly broadcasts a DHCP request with vendor
  15 class identifier \fBOpenFlow\fR on each network device until it
  16 receives an acceptable DHCP response.  It will accept any valid DHCP
  17 reply that has the same vendor class identifier and includes a
  18 vendor-specific option with code 1 whose contents are a string
  19 specifying the location of the controller in the same format used on
  20 the \fBovs\-openflowd\fR command line (e.g. \fBssl:192.168.0.1\fR).
  21
  22 When \fBovs\-discover\fR receives an acceptable response, it prints
  23 the details of the response on \fBstdout\fR.  Then, by default, it
  24 configures the network device on which the response was received with
  25 the received IP address, netmask, and default gateway, and detaches
  26 itself to the background.
  27
  28 .SH OPTIONS
  29 .TP
  30 \fB\-\-accept\-vconn=\fIregex\fR
  31 With this option, only controllers whose names match POSIX extended
  32 regular expression \fIregex\fR will be accepted.  Specifying
  33 \fBssl:.*\fR for \fIregex\fR, for example, would cause only SSL
  34 controller connections to be accepted.
  35
  36 The \fIregex\fR is implicitly anchored at the beginning of the
  37 controller location string, as if it begins with \fB^\fR.
  38
  39 When this option is not given, the default \fIregex\fR is
  40 \fBtcp:.*\fR.
  41 .TP
  42 \fB\-\-exit\-without\-bind\fR
  43 By default, \fBovs\-discover\fR binds the network device that receives
  44 the first acceptable response to the IP address received over DHCP.
  45 With this option, the configuration of the network device is not
  46 changed at all, except to bring it up if it is initially down, and
  47 \fBovs\-discover\fR will exit immediately after it receives an
  48 acceptable DHCP response.
  49
  50 This option is mutually exclusive with \fB\-\-exit\-after\-bind\fR and
  51 \fB\-\-no\-detach\fR.
  52
  53 .TP
  54 \fB\-\-exit\-after\-bind\fR
  55 By default, after it receives an acceptable DHCP response,
  56 \fBovs\-discover\fR detaches itself from the foreground session and
  57 runs in the background maintaining the DHCP lease as necessary.  With
  58 this option, \fBovs\-discover\fR will exit immediately after it
  59 receives an acceptable DHCP response and configures the network device
  60 with the received IP address.  The address obtained via DHCP could
  61 therefore be used past the expiration of its lease.
  62
  63 This option is mutually exclusive with \fB\-\-exit\-without\-bind\fR and
  64 \fB\-\-no\-detach\fR.
  65
  66 .TP
  67 \fB\-\-no\-detach\fR
  68 By default, \fBovs\-discover\fR runs in the foreground until it obtains
  69 an acceptable DHCP response, then it detaches itself from the
  70 foreground session and run as a background process.  This option
  71 prevents \fBovs\-discover\fR from detaching, causing it to run in the
  72 foreground even after it obtains a DHCP response.
  73
  74 This option is mutually exclusive with \fB\-\-exit\-without\-bind\fR and
  75 \fB\-\-exit\-after\-bind\fR.
  76
  77 .TP
  78 \fB\-\-pidfile\fR[\fB=\fIpidfile\fR]
  79 Causes a file (by default, \fBovs\-discover.pid\fR) to be created indicating
  80 the PID of the running process.  If \fIpidfile\fR is not specified, or
  81 if it does not begin with \fB/\fR, then it is created in
  82 \fB@RUNDIR@\fR.
  83
  84 The \fIpidfile\fR is created when \fBovs\-discover\fR detaches, so
  85 this this option has no effect when one of \fB\-\-exit\-without\-bind\fR,
  86 \fB\-\-exit\-after\-bind\fR, or \fB\-\-no\-detach\fR is also given.
  87
  88 .TP
  89 \fB\-\-overwrite\-pidfile\fR
  90 By default, when \fB\-\-pidfile\fR is specified and the specified pidfile
  91 already exists and is locked by a running process, \fBcontroller\fR refuses
  92 to start.  Specify \fB\-\-overwrite\-pidfile\fR to cause it to instead
  93 overwrite the pidfile.
  94
  95 When \fB\-\-pidfile\fR is not specified, this option has no effect.
  96
  97 .so lib/vlog.man
  98 .so lib/common.man
  99
 100 .SH BUGS
 101
 102 If the network devices specified on the command line have been added
 103 to an Open vSwitch datapath with \fBovs\-dpctl add\-if\fR, then controller
 104 discovery will fail because \fBovs\-discover\fR will not be able to
 105 see DHCP responses, even though tools such as \fBtcpdump\fR(8) and
 106 \fBwireshark\fR(1) can see them on the wire.  This is because of the
 107 structure of the Linux kernel networking stack, which hands packets
 108 first to programs that listen for all arriving packets, then to
 109 Open vSwitch, then to programs that listen for a specific kind of packet.
 110 Open vSwitch consumes all the packets handed to it, so tools like
 111 \fBtcpdump\fR that look at all packets will see packets arriving on
 112 Open vSwitch interfaces, but \fRovs\-discover\fR, which listens only for
 113 arriving IP packets, will not.
 114
 115 .SH "SEE ALSO"
 116
 117 .BR ovs\-openflowd (8),
 118 .BR ovs\-pki (8)