xenserver: Include dbcache in xen-bugtool output
[sliver-openvswitch.git] / 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 \fBsecchan\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 By default, \fBovs\-discover\fR accepts any controller location
32 advertised over DHCP.  With this option, only controllers whose names
33 match POSIX extended regular expression \fIregex\fR will be accepted.
34 Specifying \fBssl:.*\fR for \fIregex\fR, for example, would cause only
35 SSL controller connections to be accepted.
36
37 The \fIregex\fR is implicitly anchored at the beginning of the
38 controller location string, as if it begins with \fB^\fR.
39
40 .TP
41 \fB--exit-without-bind\fR
42 By default, \fBovs\-discover\fR binds the network device that receives
43 the first acceptable response to the IP address received over DHCP.
44 With this option, the configuration of the network device is not
45 changed at all, except to bring it up if it is initially down, and
46 \fBovs\-discover\fR will exit immediately after it receives an
47 acceptable DHCP response.
48
49 This option is mutually exclusive with \fB--exit-after-bind\fR and
50 \fB--no-detach\fR.
51
52 .TP
53 \fB--exit-after-bind\fR
54 By default, after it receives an acceptable DHCP response,
55 \fBovs\-discover\fR detaches itself from the foreground session and
56 runs in the background maintaining the DHCP lease as necessary.  With
57 this option, \fBovs\-discover\fR will exit immediately after it
58 receives an acceptable DHCP response and configures the network device
59 with the received IP address.  The address obtained via DHCP could
60 therefore be used past the expiration of its lease.
61
62 This option is mutually exclusive with \fB--exit-without-bind\fR and
63 \fB--no-detach\fR.
64
65 .TP
66 \fB--no-detach\fR
67 By default, \fBovs\-discover\fR runs in the foreground until it obtains
68 an acceptable DHCP response, then it detaches itself from the
69 foreground session and run as a background process.  This option
70 prevents \fBovs\-discover\fR from detaching, causing it to run in the
71 foreground even after it obtains a DHCP response.
72
73 This option is mutually exclusive with \fB--exit-without-bind\fR and
74 \fB--exit-after-bind\fR.
75
76 .TP
77 \fB--pidfile\fR[\fB=\fIpidfile\fR]
78 Causes a file (by default, \fBovs\-discover.pid\fR) to be created indicating
79 the PID of the running process.  If \fIpidfile\fR is not specified, or
80 if it does not begin with \fB/\fR, then it is created in
81 \fB@RUNDIR@\fR.
82
83 The \fIpidfile\fR is created when \fBovs\-discover\fR detaches, so
84 this this option has no effect when one of \fB--exit-without-bind\fR,
85 \fB--exit-after-bind\fR, or \fB--no-detach\fR is also given.
86
87 .TP
88 \fB--overwrite-pidfile\fR
89 By default, when \fB--pidfile\fR is specified and the specified pidfile 
90 already exists and is locked by a running process, \fBcontroller\fR refuses 
91 to start.  Specify \fB--overwrite-pidfile\fR to cause it to instead 
92 overwrite the pidfile.
93
94 When \fB--pidfile\fR is not specified, this option has no effect.
95
96 .so lib/vlog.man
97 .so lib/common.man
98
99 .SH BUGS
100
101 If the network devices specified on the command line have been added
102 to an Open vSwitch datapath with \fBovs\-dpctl add\-if\fR, then controller
103 discovery will fail because \fBovs\-discover\fR will not be able to
104 see DHCP responses, even though tools such as \fBtcpdump\fR(8) and
105 \fBwireshark\fR(1) can see them on the wire.  This is because of the
106 structure of the Linux kernel networking stack, which hands packets
107 first to programs that listen for all arriving packets, then to
108 Open vSwitch, then to programs that listen for a specific kind of packet.
109 Open vSwitch consumes all the packets handed to it, so tools like
110 \fBtcpdump\fR that look at all packets will see packets arriving on
111 Open vSwitch interfaces, but \fRovs\-discover\fR, which listens only for
112 arriving IP packets, will not.
113
114 .SH "SEE ALSO"
115
116 .BR secchan (8),
117 .BR ovs-pki (8)