utilities/ofp-discover.8.in

   1 .TH ofp\-discover 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 ofp\-discover \- controller discovery utility
   5
   6 .SH SYNOPSIS
   7 .B ofp\-discover
   8 [\fIoptions\fR] \fInetdev\fR [\fInetdev\fR...]
   9
  10 .SH DESCRIPTION
  11 The \fBofp\-discover\fR program attempts to discover the location of
  12 an OpenFlow controller on one of the network devices listed on the
  13 command line.  It repeatedly broadcasts a DHCP request with vendor
  14 class identifier \fBOpenFlow\fR on each network device until it
  15 receives an acceptable DHCP response.  It will accept any valid DHCP
  16 reply that has the same vendor class identifier and includes a
  17 vendor-specific option with code 1 whose contents are a string
  18 specifying the location of the controller in the same format used on
  19 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
  20
  21 When \fBofp\-discover\fR receives an acceptable response, it prints
  22 the details of the response on \fBstdout\fR.  Then, by default, it
  23 configures the network device on which the response was received with
  24 the received IP address, netmask, and default gateway, and detaches
  25 itself to the background.
  26
  27 .SH OPTIONS
  28 .TP
  29 \fB--accept-vconn=\fIregex\fR
  30 By default, \fBofp\-discover\fR accepts any controller location
  31 advertised over DHCP.  With this option, only controllers whose names
  32 match POSIX extended regular expression \fIregex\fR will be accepted.
  33 Specifying \fBssl:.*\fR for \fIregex\fR, for example, would cause only
  34 SSL 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 .TP
  40 \fB--exit-without-bind\fR
  41 By default, \fBofp\-discover\fR binds the network device that receives
  42 the first acceptable response to the IP address received over DHCP.
  43 With this option, the configuration of the network device is not
  44 changed at all, except to bring it up if it is initially down, and
  45 \fBofp\-discover\fR will exit immediately after it receives an
  46 acceptable DHCP response.
  47
  48 This option is mutually exclusive with \fB--exit-after-bind\fR and
  49 \fB--no-detach\fR.
  50
  51 .TP
  52 \fB--exit-after-bind\fR
  53 By default, after it receives an acceptable DHCP response,
  54 \fBofp\-discover\fR detaches itself from the foreground session and
  55 runs in the background maintaining the DHCP lease as necessary.  With
  56 this option, \fBofp\-discover\fR will exit immediately after it
  57 receives an acceptable DHCP response and configures the network device
  58 with the received IP address.  The address obtained via DHCP could
  59 therefore be used past the expiration of its lease.
  60
  61 This option is mutually exclusive with \fB--exit-without-bind\fR and
  62 \fB--no-detach\fR.
  63
  64 .TP
  65 \fB--no-detach\fR
  66 By default, \fBofp\-discover\fR runs in the foreground until it obtains
  67 an acceptable DHCP response, then it detaches itself from the
  68 foreground session and run as a background process.  This option
  69 prevents \fBofp\-discover\fR from detaching, causing it to run in the
  70 foreground even after it obtains a DHCP response.
  71
  72 This option is mutually exclusive with \fB--exit-without-bind\fR and
  73 \fB--exit-after-bind\fR.
  74
  75 .TP
  76 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
  77 Causes a file (by default, \fBofp\-discover.pid\fR) to be created indicating
  78 the PID of the running process.  If \fIpidfile\fR is not specified, or
  79 if it does not begin with \fB/\fR, then it is created in
  80 \fB@rundir@\fR.
  81
  82 The \fIpidfile\fR is created when \fBofp\-discover\fR detaches, so
  83 this this option has no effect when one of \fB--exit-without-bind\fR,
  84 \fB--exit-after-bind\fR, or \fB--no-detach\fR is also given.
  85
  86 .TP
  87 \fB-f\fR, \fB--force\fR
  88 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
  89 specified pidfile already exists and is locked by a running process,
  90 \fBcontroller\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
  91 to cause it to instead overwrite the pidfile.
  92
  93 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
  94 effect.
  95
  96 .TP
  97 .BR \-h ", " \-\^\-help
  98 Prints a brief help message to the console.
  99
 100 .TP
 101 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 102 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 103 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 104 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 105 special name \fBANY\fR to set the logging levels for all modules.  The
 106 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 107 for logging to the system log or to the console, respectively, or
 108 \fBANY\fR to set the logging levels for both facilities.  If it is
 109 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 110 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 111 the minimum severity of a message for it to be logged.  If it is
 112 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 113
 114 .TP
 115 \fB-v\fR, \fB--verbose\fR
 116 Sets the maximum logging verbosity level, equivalent to
 117 \fB--verbose=ANY:ANY:dbg\fR.
 118
 119 .TP
 120 .BR \-V ", " \-\^\-version
 121 Prints version information to the console.
 122
 123 .SH BUGS
 124
 125 If the network devices specified on the command line have been added
 126 to an OpenFlow switch with \fBdpctl addif\fR, then controller
 127 discovery will fail because \fBofp\-discover\fR will not be able to
 128 see DHCP responses, even though tools such as \fBtcpdump\fR(8) and
 129 \fBwireshark\fR(1) can see them on the wire.  This is because of the
 130 structure of the Linux kernel networking stack, which hands packets
 131 first to programs that listen for all arriving packets, then to
 132 OpenFlow, then to programs that listen for a specific kind of packet.
 133 OpenFlow consumes all the packets handed to it, so tools like
 134 \fBtcpdump\fR that look at all packets will see packets arriving on
 135 OpenFlow interfaces, but \fRofp\-discover\fR, which listens only for
 136 arriving IP packets, will not.
 137
 138 .SH "SEE ALSO"
 139
 140 .BR secchan (8),
 141 .BR ofp-pki (8)