[ovs-dev] [PATCH 1/9] Factor vconn and SSL documentation into manpage include files.

Justin Pettit jpettit at nicira.com
Tue Jan 5 03:21:42 UTC 2010


This looks like mostly this was mostly just moving text around, so I didn't read in great detail.  Looks good to me.

--Justin


On Dec 21, 2009, at 1:15 PM, Ben Pfaff wrote:

> ---
> lib/automake.mk               |    5 +++
> lib/ssl-bootstrap.man         |   22 +++++++++++
> lib/ssl-peer-ca-cert.man      |   12 ++++++
> lib/ssl.man                   |   20 ++++++++++
> lib/vconn-active.man          |   13 +++++++
> lib/vconn-passive.man         |   17 +++++++++
> utilities/ovs-controller.8.in |   72 +++----------------------------------
> utilities/ovs-ofctl.8.in      |   41 ++-------------------
> utilities/ovs-openflowd.8.in  |   79 +++-------------------------------------
> utilities/ovs-vsctl.8.in      |   16 ++-------
> 10 files changed, 108 insertions(+), 189 deletions(-)
> create mode 100644 lib/ssl-bootstrap.man
> create mode 100644 lib/ssl-peer-ca-cert.man
> create mode 100644 lib/ssl.man
> create mode 100644 lib/vconn-active.man
> create mode 100644 lib/vconn-passive.man
> 
> diff --git a/lib/automake.mk b/lib/automake.mk
> index cace97c..5fd17c5 100644
> --- a/lib/automake.mk
> +++ b/lib/automake.mk
> @@ -194,6 +194,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
> 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
> 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
> 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
> 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
> 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
> --- 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 439d3f5..63af9ca 100644
> --- 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.
> @@ -451,28 +439,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 25b222f..16dbb33 100644
> --- 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
> @@ -435,43 +403,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 16fd849..09c3a04 100644
> --- 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
> -- 
> 1.6.3.3
> 
> 
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev_openvswitch.org





More information about the dev mailing list