Factor vconn and SSL documentation into manpage include files.

diff --git a/lib/automake.mk b/lib/automake.mk
index 8c45ff6..cb5c3d7 100644 (file)
--- a/lib/automake.mk
+++ b/lib/automake.mk
@@ -192,6 +192,11 @@ EXTRA_DIST += \
        lib/daemon-syn.man \
        lib/dpif.man \
        lib/leak-checker.man \
+       lib/ssl-bootstrap.man \
+       lib/ssl-peer-ca-cert.man \
+       lib/ssl.man \
+       lib/vconn-active.man \
+       lib/vconn-passive.man \
        lib/vlog-unixctl.man \
        lib/vlog-syn.man \
        lib/vlog.man

diff --git a/lib/ssl-bootstrap.man b/lib/ssl-bootstrap.man
new file mode 100644 (file)
index 0000000..178350d
--- /dev/null
+++ b/lib/ssl-bootstrap.man
@@ -0,0 +1,22 @@
+.IP "\fB\-\-bootstrap\-ca\-cert=\fIcacert.pem\fR"
+When \fIcacert.pem\fR exists, this option has the same effect as
+\fB\-C\fR or \fB\-\-ca\-cert\fR.  If it does not exist, then
+\fB\*(PN\fR will attempt to obtain the CA certificate from the
+SSL peer on its first SSL connection and save it to the named PEM
+file.  If it is successful, it will immediately drop the connection
+and reconnect, and from then on all SSL connections must be
+authenticated by a certificate signed by the CA certificate thus
+obtained.
+.IP
+\fBThis option exposes the SSL connection to a man-in-the-middle
+attack obtaining the initial CA certificate\fR, but it may be useful
+for bootstrapping.
+.IP
+This option is only useful if the SSL peer sends its CA certificate as
+part of the SSL certificate chain.  The SSL protocol does not require
+the controller to send the CA certificate, but
+\fBovs\-controller\fR(8) can be configured to do so with the
+\fB\-\-peer\-ca\-cert\fR option.
+.IP
+This option is mutually exclusive with \fB-C\fR and
+\fB\-\-ca\-cert\fR.

diff --git a/lib/ssl-peer-ca-cert.man b/lib/ssl-peer-ca-cert.man
new file mode 100644 (file)
index 0000000..183f93e
--- /dev/null
+++ b/lib/ssl-peer-ca-cert.man
@@ -0,0 +1,12 @@
+.IP "\fB--peer-ca-cert=\fIpeer-cacert.pem\fR"
+Specifies a PEM file that contains one or more additional certificates
+to send to SSL peers.  \fIpeer-cacert.pem\fR should be the CA
+certificate used to sign the \fB\*(PN\fR own certificate (the
+certificate specified on \fB-c\fR or \fB--certificate\fR).
+.IP
+This option is not useful in normal operation, because the SSL peer
+must already have the CA certificate for the peer to have any
+confidence in \fB\*(PN\fR's identity.  However, this option allows a
+newly installed switch to obtain the peer CA certificate on first boot
+using, e.g., the \fB\-\-bootstrap-ca-cert\fR option to
+\fBovs\-openflowd\fR(8).

diff --git a/lib/ssl.man b/lib/ssl.man
new file mode 100644 (file)
index 0000000..8e530f4
--- /dev/null
+++ b/lib/ssl.man
@@ -0,0 +1,20 @@
+.SS "Public Key Infrastructure Options"
+.IP "\fB\-p\fR \fIprivkey.pem\fR"
+.IQ "\fB\-\-private\-key=\fIprivkey.pem\fR"
+Specifies a PEM file containing the private key used as \fB\*(PN\fR's
+identity for outgoing SSL connections.
+
+.IP "\fB\-c\fR \fIcert.pem\fR"
+.IQ "\fB\-\-certificate=\fIcert.pem\fR"
+Specifies a PEM file containing a certificate that certifies the
+private key specified on \fB\-p\fR or \fB\-\-private\-key\fR to be
+trustworthy.  The certificate must be signed by the certificate
+authority (CA) that the peer in SSL connections will use to verify it.
+
+.IP "\fB\-C\fR \fIswitch\-cacert.pem\fR"
+.IQ "\fB\-\-ca\-cert=\fIswitch\-cacert.pem\fR"
+Specifies a PEM file containing the CA certificate that \fB\*(PN\fR
+should use to verify certificates presented to it by SSL peers.  (This
+may be the same certificate that SSL peers use to verify the
+certificate specified on \fB\-c\fR or \fB\-\-certificate\fR, or it may
+beq a different one, depending on the PKI design in use.)

diff --git a/lib/vconn-active.man b/lib/vconn-active.man
new file mode 100644 (file)
index 0000000..ef86f73
--- /dev/null
+++ b/lib/vconn-active.man
@@ -0,0 +1,13 @@
+.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
+The specified SSL \fIport\fR (default: 6633) on the host at the given
+\fIip\fR, which must be expressed as an IP address (not a DNS name).
+The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
+\fB\-\-ca\-cert\fR options are mandatory when this form is used.
+
+.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
+The specified TCP \fIport\fR (default: 6633) on the host at the given
+\fIip\fR, which must be expressed as an IP address (not a DNS name).
+
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.

diff --git a/lib/vconn-passive.man b/lib/vconn-passive.man
new file mode 100644 (file)
index 0000000..4b7f492
--- /dev/null
+++ b/lib/vconn-passive.man
@@ -0,0 +1,17 @@
+.IP "\fBpssl:\fR[\fIport\fR][\fB:\fIip\fR]"
+Listens for OpenFlow SSL connections on \fIport\fR (default: 6633).
+The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
+\fB\-\-ca\-cert\fR options are mandatory when this form is used.  By
+default, \fB\*(PN\fR listens for connections to any local IP address,
+but \fIip\fR may be specified to listen only for connections to the
+given \fIip\fR.
+
+.IP "\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]"
+Listens for OpenFlow TCP connections on \fIport\fR (default: 6633).
+By default, \fB\*(PN\fR listens for connections to any local IP
+address, but \fIip\fR may be specified to listen only for connections
+to the given \fIip\fR.
+
+.IP "\fBpunix:\fIfile\fR"
+Listens for OpenFlow connections on the Unix domain server socket
+named \fIfile\fR.

diff --git a/utilities/ovs-controller.8.in b/utilities/ovs-controller.8.in
index 040f633..f4a3888 100644 (file)
--- a/utilities/ovs-controller.8.in
+++ b/utilities/ovs-controller.8.in
@@ -15,74 +15,12 @@ protocol, causing them to function as L2 MAC-learning switches or hub.
 \fBovs\-controller\fR controls one or more OpenFlow switches, specified as
 one or more of the following OpenFlow connection methods:
 
-.TP
-\fBpssl:\fR[\fIport\fR][\fB:\fIip\fR]
-Listens for SSL connections from remote OpenFlow switches on
-\fIport\fR (default: 6633).  The \fB--private-key\fR,
-\fB--certificate\fR, and \fB--ca-cert\fR options are mandatory when
-this form is used.
-By default, \fB\*(PN\fR listens for connections to any local IP
-address, but \fIip\fR may be specified to listen only for connections
-to the given \fIip\fR.
-
-.TP
-\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]
-Listens for TCP connections from remote OpenFlow switches on
-\fIport\fR (default: 6633).
-By default, \fB\*(PN\fR listens for connections to any local IP
-address, but \fIip\fR may be specified to listen only for connections
-to the given \fIip\fR.
-
-.TP
-\fBpunix:\fIfile\fR
-Listens for connections from OpenFlow switches on the Unix domain
-server socket named \fIfile\fR.
-
-.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
-The specified SSL \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-The \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR
-options are mandatory when this form is used.
-
-.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
-The specified TCP \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-
-.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.
+.RS
+.so lib/vconn-passive.man
+.so lib/vconn-active.man
+.RE
 
 .SH OPTIONS
-.TP
-\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
-Specifies a PEM file containing the private key used as the switch's
-identity for SSL connections to the controller.
-
-.TP
-\fB-c\fR, \fB--certificate=\fIcert.pem\fR
-Specifies a PEM file containing a certificate, signed by the
-controller's certificate authority (CA), that certifies the switch's
-private key to identify a trustworthy switch.
-
-.TP
-\fB-C\fR, \fB--ca-cert=\fIswitch-cacert.pem\fR
-Specifies a PEM file containing the CA certificate used to verify that
-the switch is connected to a trustworthy controller.
-
-.TP
-\fB--peer-ca-cert=\fIcontroller-cacert.pem\fR
-Specifies a PEM file that contains one or more additional certificates
-to send to switches.  \fIcontroller-cacert.pem\fR should be the CA
-certificate used to sign the controller's own certificate (the
-certificate specified on \fB-c\fR or \fB--certificate\fR).
-
-This option is not useful in normal operation, because the switch must
-already have the controller CA certificate for it to have any
-confidence in the controller's identity.  However, this option allows
-a newly installed switch to obtain the controller CA certificate on
-first boot using, e.g., the \fB--bootstrap-ca-cert\fR option to
-\fBovs\-openflowd\fR(8).
-
 .IP "\fB-n\fR, \fB--noflow\fR"
 By default, \fBovs\-controller\fR sets up a flow in each OpenFlow switch
 whenever it receives a packet whose destination is known due through
@@ -143,6 +81,8 @@ to it by switches.
 This option is only for debugging the Open vSwitch implementation of
 ``fail open'' mode.  It must not be used in production.
 
+.so lib/ssl.man
+.so lib/ssl-peer-ca-cert.man
 .so lib/daemon.man
 .so lib/vlog.man
 .so lib/common.man

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index 5b34a54..cf4ead9 100644 (file)
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -26,24 +26,12 @@ connecting to an OpenFlow switch.  The following connection methods
 are supported:
 
 .RS
-.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
-The specified SSL \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-The \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR
-options are mandatory when this form is used.
-
-.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
-The specified TCP \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-
-.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.  
-
+.so lib/vconn-active.man
+.
 .IP "\fIfile\fR"
 This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not
 contain a colon.
-
+.
 .IP \fIdp\fR
 This is short for \fBunix:@RUNDIR@/\fIdp\fB.mgmt\fR, as long as
 \fIdp\fR does not contain a colon.
@@ -442,28 +430,7 @@ described in \fBFlow Syntax\fR, above.
 \fB--strict\fR
 Uses strict matching when running flow modification commands.
 
-.TP
-\fB-t\fR, \fB--timeout=\fIsecs\fR
-Limits \fBovs\-ofctl\fR runtime to approximately \fIsecs\fR seconds.  If
-the timeout expires, \fBovs\-ofctl\fR will exit with a \fBSIGALRM\fR
-signal.
-
-.TP
-\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
-Specifies a PEM file containing the private key used as the
-identity for SSL connections to a switch.
-
-.TP
-\fB-c\fR, \fB--certificate=\fIcert.pem\fR
-Specifies a PEM file containing a certificate, signed by the
-controller's certificate authority (CA), that certifies the
-private key to identify a trustworthy controller.
-
-.TP
-\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
-Specifies a PEM file containing the CA certificate used to verify that
-a switch is trustworthy.
-
+.so lib/ssl.man
 .so lib/vlog.man
 .so lib/common.man
 

diff --git a/utilities/ovs-openflowd.8.in b/utilities/ovs-openflowd.8.in
index ed21fa5..208cd87 100644 (file)
--- a/utilities/ovs-openflowd.8.in
+++ b/utilities/ovs-openflowd.8.in
@@ -21,23 +21,9 @@ to relay.  It takes one of the following forms:
 .PP
 The optional \fIcontroller\fR argument specifies how to connect to
 the OpenFlow controller.  It takes one of the following forms:
-
-.RS
-.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
-The specified SSL \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-The \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR
-options are mandatory when this form is used.
-
-.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
-The specified TCP \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-
-.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.
-.RE
-
+.
+.so lib/vconn-active.man
+.
 .PP
 If \fIcontroller\fR is omitted, \fBovs\-openflowd\fR attempts to discover the
 location of the controller automatically (see below).
@@ -310,25 +296,7 @@ multiple connection methods.  If a single \fImethod\fR of \fBnone\fR is
 used, no listeners will be created.
 
 .RS
-.TP
-\fBpssl:\fR[\fIport\fR][\fB:\fIip\fR]
-Listens for SSL connections on \fIport\fR (default: 6633).  The
-\fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
-are mandatory when this form is used.
-By default, \fB\*(PN\fR listens for connections to any local IP
-address, but \fIip\fR may be specified to listen only for connections
-to the given \fIip\fR.
-
-.TP
-\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]
-Listens for TCP connections on \fIport\fR (default: 6633).
-By default, \fB\*(PN\fR listens for connections to any local IP
-address, but \fIip\fR may be specified to listen only for connections
-to the given \fIip\fR.
-
-.TP
-\fBpunix:\fIfile\fR
-Listens for connections on Unix domain server socket named \fIfile\fR.
+.so lib/vconn-passive.man
 .RE
 
 .TP
@@ -407,43 +375,8 @@ switching.
 .SS "Daemon Options"
 .so lib/daemon.man
 
-.SS "Public Key Infrastructure Options"
-
-.TP
-\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
-Specifies a PEM file containing the private key used as the switch's
-identity for SSL connections to the controller.
-
-.TP
-\fB-c\fR, \fB--certificate=\fIcert.pem\fR
-Specifies a PEM file containing a certificate, signed by the
-controller's certificate authority (CA), that certifies the switch's
-private key to identify a trustworthy switch.
-
-.TP
-\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
-Specifies a PEM file containing the CA certificate used to verify that
-the switch is connected to a trustworthy controller.
-
-.TP
-\fB--bootstrap-ca-cert=\fIcacert.pem\fR
-When \fIcacert.pem\fR exists, this option has the same effect as
-\fB-C\fR or \fB--ca-cert\fR.  If it does not exist, then \fBovs\-openflowd\fR
-will attempt to obtain the CA certificate from the controller on its
-first SSL connection and save it to the named PEM file.  If it is
-successful, it will immediately drop the connection and reconnect, and
-from then on all SSL connections must be authenticated by a
-certificate signed by the CA certificate thus obtained.
-
-\fBThis option exposes the SSL connection to a man-in-the-middle
-attack obtaining the initial CA certificate\fR, but it may be useful
-for bootstrapping.
-
-This option is only useful if the controller sends its CA certificate
-as part of the SSL certificate chain.  The SSL protocol does not
-require the controller to send the CA certificate, but
-\fBcontroller\fR(8) can be configured to do so with the
-\fB--peer-ca-cert\fR option.
+.so lib/ssl.man
+.so lib/ssl-bootstrap.man
 
 .SS "Logging Options"
 .so lib/vlog.man

diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index da017e6..dd4d4ce 100644 (file)
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -114,6 +114,7 @@ zero will cause \fBovs\-vsctl\fR to wait forever.  If the timeout expires,
 not used, \fBovs\-vsctl\fR uses a timeout of five seconds.
 (A timeout would normally happen only if the database cannot be contacted.)
 .
+.so lib/ssl.man
 .so lib/vlog.man
 .
 .SH COMMANDS
@@ -296,20 +297,9 @@ the following forms:
 .
 .RS
 .TP
-\fBssl:\fIip\fR[\fB:\fIport\fR]
-The specified SSL \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-SSL must be configured when this form is used (see \fBSSL
-Configuration\fR, below).
-.
-.TP
-\fBtcp:\fIip\fR[\fB:\fIport\fR]
-The specified TCP \fIport\fR (default: 6633) on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name).
-.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.
+.so lib/vconn-active.man
 .RE
+.
 .ST "Controller Failure Settings"
 .
 When a controller is configured, it is, ordinarily, responsible for