From 417372edd09848e0a5e6dfb9a1d8cc6b3dfea6fa Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Wed, 11 Mar 2009 17:07:56 -0700 Subject: [PATCH] secchan: Update documentation. --- lib/common.man | 4 +- lib/dpif.man | 16 +++++++ secchan/secchan.8.in | 105 +++++++++++++++++++------------------------ utilities/dpctl.8.in | 17 +------ 4 files changed, 66 insertions(+), 76 deletions(-) create mode 100644 lib/dpif.man diff --git a/lib/common.man b/lib/common.man index 1f12bb7c..84e81c2c 100644 --- a/lib/common.man +++ b/lib/common.man @@ -1,7 +1,7 @@ .TP -.BR \-h ", " \-\^\-help +\fB-h\fR, \fB--help\fR Prints a brief help message to the console. .TP -.BR \-V ", " \-\^\-version +\fB-V\fR, \fB--version\fR Prints version information to the console. diff --git a/lib/dpif.man b/lib/dpif.man new file mode 100644 index 00000000..72175b0a --- /dev/null +++ b/lib/dpif.man @@ -0,0 +1,16 @@ +.RS +.TP +\fBdp\fIN\fR +Datapath number \fIN\fR, where \fIN\fR is a number between 0 and 255, +inclusive. + +.TP +\fIname\fR +The name of the network device associated with the datapath's local +port. (\fB\*(PN\fR internally converts this into a datapath number, +as above.) + +.TP +\fBnl:\fIN\fR +This is an obsolete synonym for \fBdp\fIN\fR. +.RE diff --git a/secchan/secchan.8.in b/secchan/secchan.8.in index 5de780a2..cfc3e731 100644 --- a/secchan/secchan.8.in +++ b/secchan/secchan.8.in @@ -2,37 +2,27 @@ .ds PN secchan .SH NAME -secchan \- secure channel connecting an OpenFlow datapath to a controller +secchan \- OpenFlow switch implementation .SH SYNOPSIS .B secchan [\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR] .SH DESCRIPTION -The \fBsecchan\fR program sets up a secure channel between a local -OpenFlow datapath and a remote controller. \fBsecchan\fR connects to -the local datapath over Netlink and to the controller over TCP or SSL, -and then forwards OpenFlow messages from one endpoint to the other. +The \fBsecchan\fR program implements an OpenFlow switch using a +flow-based datapath. \fBsecchan\fR connects to an OpenFlow controller +over TCP or SSL. The mandatory \fIdatapath\fR argument argument specifies the local datapath to relay. It takes one of the following forms: -.TP -\fBnl:\fIdp_idx\fR -Attach to the local kernel-based datapath over the Netlink protocol. -The \fIdp_idx\fR argument is the number of a datapath created with -\fBdpctl\fR(8). - -.TP -\fBunix:\fIfile\fR -Attach to the userspace datapath implemented by \fBudatapath\fR(8). -The \fIfile\fR argument must the same one specified on the -\fBudatapath\fR command line. +.so lib/dpif.man .PP The optional \fIcontroller\fR argument specifies how to connect to the OpenFlow controller. It takes one of the following forms: +.RS .TP \fBssl:\fIhost\fR[\fB:\fIport\fR] The specified SSL \fIport\fR (default: 6633) on the given remote @@ -47,12 +37,13 @@ The specified TCP \fIport\fR (default: 6633) on the given remote .TP \fBunix:\fIfile\fR The Unix domain server socket named \fIfile\fR. +.RE .PP If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the location of the controller automatically (see below). -.SH "CONTACTING THE CONTROLLER" +.SS "Contacting the Controller" The OpenFlow switch must be able to contact the OpenFlow controller over the network. It can do so in one of two ways: @@ -157,33 +148,18 @@ controller on the \fBsecchan\fR command line as the \fIcontroller\fR argument. You must also configure the network device for the OpenFlow ``local port'' to allow \fBsecchan\fR to connect to that controller. The OpenFlow local port is a virtual network port that \fBsecchan\fR -bridges to the physical switch ports. Its network device name depends -on the \fIdatapath\fR specified on the \fBsecchan\fR command line: - -.RS -.TP -\fBnl:\fIdp_idx\fR -The local port network device for \fBnl:\fIdp_idx\fR is always named -\fBof\fIdp_idx\fR, i.e. the device for \fBnl:0\fR is \fBof0\fR. - -.TP -\fBunix:\fIfile\fR -The local port network device name may be specified on the -\fBudatapath\fR command line, using the \fB--local-port\fR option. It -is often \fBtap0\fR. -.RE +bridges to the physical switch ports. The name of the local port for +a given \fIdatapath\fR may be seen by running \fBdpctl showdp +\fIdatapath\fR; the local port is listed as port 0 in \fBshowdp\fR's +output. .IP Before \fBsecchan\fR starts, the local port network device is not bridged to any physical network, so the next step depends on whether connectivity is required to configure the device's IP address. If the switch has a static IP address, you may configure its IP address now -with a command such as: -.RS -.IP -ifconfig of0 192.168.1.1 -.RE -.IP +with a command such as +.B ifconfig of0 192.168.1.1 and then invoke \fBsecchan\fR. On the other hand, if the switch does not have a static IP address, @@ -194,24 +170,11 @@ the local port network device, and start the DHCP client afterward. .RE .SH OPTIONS -.SS "Configuration Options" -.TP -\fB-F \fIfile\fR, \fB--config=\fIfile\fR -The \fB-F\fR or \fB--config\fR option specifies a configuration file. -For a description of the configuration syntax, see \fBvswitchd.conf\fR(5). -Currently, only the NetFlow section applies to \fBsecchan\fR. - -.TP -\fB--br-name=\fIname\fR -When processing the configuration files specified with the \fB--config\fR -option, use \fIname\fR as the bridge identifier to look for applicable -lines. - .SS "Controller Discovery Options" .TP \fB--accept-vconn=\fIregex\fR -When \fBsecchan\fR performs controller discovery (see \fBCONTACTING -THE CONTROLLER\fR, above, for more information about controller +When \fBsecchan\fR performs controller discovery (see \fBContacting +the Controller\fR, above, for more information about controller discovery), it validates the controller location obtained via DHCP with a POSIX extended regular expression. Only controllers whose names match the regular expression will be accepted. @@ -229,8 +192,8 @@ When controller discovery is not performed, this option has no effect. .TP \fB--no-resolv-conf\fR -When \fBsecchan\fR performs controller discovery (see \fBCONTACTING -THE CONTROLLER\fR, above, for more information about controller +When \fBsecchan\fR performs controller discovery (see \fBContacting +the Controller\fR, above, for more information about controller discovery), by default it overwrites the system's \fB/etc/resolv.conf\fR with domain information and DNS servers obtained via DHCP. If the location of the controller is specified @@ -246,6 +209,24 @@ that it receives specifies one or more DNS servers. When controller discovery is not performed, this option has no effect. .SS "Networking Options" +.TP +\fB--datapath-id=\fIdpid\fR +Sets \fIdpid\fR, which must consist of exactly 12 hexadecimal digits, +as the datapath ID that the switch will use to identify itself to the +OpenFlow controller. + +If this option is omitted, the default datapath ID is taken from the +Ethernet address of the datapath's local port (which is typically +randomly generated). + +.TP +\fB--mgmt-id=\fImgmtid\fR +Sets \fImgmtid\fR, which must consist of exactly 12 hexadecimal +digits, as the switch's management ID. + +If this option is omitted, the management ID defaults to 0, signaling +to the controller that management is supported but not configured. + .TP \fB--fail=\fR[\fBopen\fR|\fBclosed\fR] The controller is, ordinarily, responsible for setting up all flows on @@ -301,7 +282,7 @@ fail-open delay. .IP \(bu When in-band control is in use, flows set up to bootstrap contacting -the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for +the controller (see \fBContacting the Controller\fR, above, for more information about in-band control). .RE @@ -344,7 +325,7 @@ Listens for connections on Unix domain server socket named \fIfile\fR. .TP \fB--in-band\fR, \fB--out-of-band\fR Configures \fBsecchan\fR to operate in in-band or out-of-band control -mode (see \fBCONTACTING THE CONTROLLER\fR above). When neither option +mode (see \fBContacting the Controller\fR above). When neither option is given, the default is in-band control. .TP @@ -354,6 +335,14 @@ at the switch. The default is \fB--no-stp\fR in this distribution, because bugs in the STP implementation are still being worked out. The default will change to \fB--stp\fR at some point in the future. +.TP +\fB--netflow=\fIhost\fB:\fIport\fR +Configures the given UDP \fIport\fR on the specified IP \fIhost\fR as +a recipient of NetFlow messages for expired flows. + +This option may be specified multiple times to configure additional +NetFlow collectors. + .SS "Rate-Limiting Options" These options configure how the switch applies a ``token bucket'' to @@ -465,4 +454,4 @@ require the controller to send the CA certificate, but .BR ofp-pki (8), .BR udatapath (8), .BR vlogconf (8), -.BR vswitchd.conf (5), +.BR vswitchd.conf (5) diff --git a/utilities/dpctl.8.in b/utilities/dpctl.8.in index 19550234..bf62c7b3 100644 --- a/utilities/dpctl.8.in +++ b/utilities/dpctl.8.in @@ -41,22 +41,7 @@ Most \fBdpctl\fR commands that work with datapaths take an argument that specifies the name of the datapath, in one of the following forms: -.RS -.TP -\fBdp\fIN\fR -Datapath number \fIN\fR, where \fIN\fR is a number between 0 and 255, -inclusive. - -.TP -\fIname\fR -The name of the network device associated with the datapath's local -port. (\fBdpctl\fR internally converts this into a datapath number, -as above.) - -.TP -\fBnl:\fIN\fR -This is an obsolete synonym for \fBdp\fIN\fR. -.RE +.so lib/dpif.man .PP The following commands manage datapaths. -- 2.30.2