diff options
| -rw-r--r-- | lib/automake.mk | 5 | ||||
| -rw-r--r-- | lib/ssl-bootstrap.man | 22 | ||||
| -rw-r--r-- | lib/ssl-peer-ca-cert.man | 12 | ||||
| -rw-r--r-- | lib/ssl.man | 20 | ||||
| -rw-r--r-- | lib/vconn-active.man | 13 | ||||
| -rw-r--r-- | lib/vconn-passive.man | 17 | ||||
| -rw-r--r-- | utilities/ovs-controller.8.in | 72 | ||||
| -rw-r--r-- | utilities/ovs-ofctl.8.in | 41 | ||||
| -rw-r--r-- | utilities/ovs-openflowd.8.in | 79 | ||||
| -rw-r--r-- | utilities/ovs-vsctl.8.in | 16 |
10 files changed, 108 insertions, 189 deletions
diff --git a/lib/automake.mk b/lib/automake.mk index 8c45ff667..cb5c3d7a7 100644 --- 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 index 000000000..178350d91 --- /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 000000000..183f93ea2 --- /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 000000000..8e530f45d --- /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 000000000..ef86f739b --- /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 000000000..4b7f4923b --- /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 040f63303..f4a388821 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 5b34a549e..cf4ead96d 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. @@ -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 ed21fa5ba..208cd875c 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 @@ -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 da017e621..dd4d4ce94 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 |