From: Ben Pfaff Date: Mon, 9 Jun 2008 18:01:46 +0000 (-0700) Subject: Move manpages from man directory to next to their programs. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9446ee791c5fe89e1c96b550cd22e7791f6d4535;p=openvswitch Move manpages from man directory to next to their programs. --- diff --git a/Makefile.am b/Makefile.am index 7ebc633e..4644b057 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,4 +3,4 @@ SUBDIRS = lib datapath secchan controller if HAVE_IF_PACKET SUBDIRS += switch endif -SUBDIRS += utilities tests man include third-party +SUBDIRS += utilities tests include third-party diff --git a/README b/README index 75c01300..a5d7a308 100644 --- a/README +++ b/README @@ -61,9 +61,8 @@ This distribution includes some additional software as well: - A patch to tcpdump that enables it to parse OpenFlow messages. -For installation instructions, read INSTALL. This distribution also -includes manpages for each of its userspace programs, in the man/ -directory. +For installation instructions, read INSTALL. Each userspace program +is also accompanied by a manpage. Platform support ---------------- diff --git a/configure.ac b/configure.ac index eb80441d..0cdc593a 100644 --- a/configure.ac +++ b/configure.ac @@ -109,8 +109,6 @@ AC_CHECK_LIB([dl], [dladdr]) CFLAGS="$CFLAGS -Wall -Wno-sign-compare" AC_CONFIG_FILES([Makefile -man/Makefile -man/man8/Makefile datapath/Makefile lib/Makefile include/Makefile diff --git a/controller/Makefile.am b/controller/Makefile.am index 87642e98..e783a7e9 100644 --- a/controller/Makefile.am +++ b/controller/Makefile.am @@ -1,6 +1,7 @@ include ../Make.vars bin_PROGRAMS = controller +dist_man_MANS = controller.8 controller_SOURCES = controller.c controller_LDADD = ../lib/libopenflow.la -ldl diff --git a/controller/controller.8 b/controller/controller.8 new file mode 100644 index 00000000..de0d41a4 --- /dev/null +++ b/controller/controller.8 @@ -0,0 +1,71 @@ +.TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +controller \- simple OpenFlow controller reference implementation + +.SH SYNOPSIS +.B controller +[OPTIONS] ptcp:[\fIPORT\fR] | nl:\fIDP_IDX\fR + +.SH DESCRIPTION +A sample OpenFlow controller which functions as an L2 MAC-learning +switch or hub. \fBcontroller\fR can manage a remote datapath through +a secure channel (see \fBsecchan(8)\fR). It can also connect directly +to a local datapath via netlink. + +To connect over netlink to a local datapath number \fIDP_IDX\fR (Linux +only), specify nl:\fIDP_IDX\fR on the command line. To listen for +TCP connections from remote datapaths on port \fIPORT\fR, specify +ptcp:[\fIPORT\fR]. (\fIPORT\fR defaults to 975 if omitted.) + +\fBcontroller\fR can control multiple datapaths. Multiple ptcp: or +nl: arguments may be given. Multiple TCP clients may connect to a +single TCP server port. + +.SH OPTIONS +.TP +.BR \-H ", " \-\^\-hub +By default, the controller acts as an L2 MAC-learning switch. This +option changes its behavior to that of a hub that floods packets on +all but the incoming port. + +.TP +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +.TP +.BR \-n ", " \-\^\-noflow +This is similar to the \fB\-\^\-hub\fR option, but does not add a +flow entry in the switch. This causes all traffic seen by the switch +to be passed to the controller before being sent out all but the +incoming port. + +.TP +.BR \-v ", " \-\^\-verbose +Prints debug messages to the console. + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. + +.SH EXAMPLES + +.TP +To connect directly to local datapath 0 over netlink (Linux only): + +.B % controller nl:0 + +.TP +To bind locally to port 975 (the default) and wait for incoming connections from secure channels: + +.B % controller ptcp: + +.SH "SEE ALSO" + +.BR dpctl (8), +.BR switch (8), +.BR secchan (8) +.BR vlogconf (8) + +.SH BUGS +Currently \fBcontroller\fR does not support SSL. diff --git a/man/.gitignore b/man/.gitignore deleted file mode 100644 index b336cc7c..00000000 --- a/man/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -/Makefile -/Makefile.in diff --git a/man/Makefile.am b/man/Makefile.am deleted file mode 100644 index 9bc48012..00000000 --- a/man/Makefile.am +++ /dev/null @@ -1 +0,0 @@ -SUBDIRS = man8 diff --git a/man/man8/.gitignore b/man/man8/.gitignore deleted file mode 100644 index b336cc7c..00000000 --- a/man/man8/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -/Makefile -/Makefile.in diff --git a/man/man8/Makefile.am b/man/man8/Makefile.am deleted file mode 100644 index 0f28df8c..00000000 --- a/man/man8/Makefile.am +++ /dev/null @@ -1 +0,0 @@ -dist_man_MANS = controller.8 dpctl.8 secchan.8 vlogconf.8 diff --git a/man/man8/controller.8 b/man/man8/controller.8 deleted file mode 100644 index de0d41a4..00000000 --- a/man/man8/controller.8 +++ /dev/null @@ -1,71 +0,0 @@ -.TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -controller \- simple OpenFlow controller reference implementation - -.SH SYNOPSIS -.B controller -[OPTIONS] ptcp:[\fIPORT\fR] | nl:\fIDP_IDX\fR - -.SH DESCRIPTION -A sample OpenFlow controller which functions as an L2 MAC-learning -switch or hub. \fBcontroller\fR can manage a remote datapath through -a secure channel (see \fBsecchan(8)\fR). It can also connect directly -to a local datapath via netlink. - -To connect over netlink to a local datapath number \fIDP_IDX\fR (Linux -only), specify nl:\fIDP_IDX\fR on the command line. To listen for -TCP connections from remote datapaths on port \fIPORT\fR, specify -ptcp:[\fIPORT\fR]. (\fIPORT\fR defaults to 975 if omitted.) - -\fBcontroller\fR can control multiple datapaths. Multiple ptcp: or -nl: arguments may be given. Multiple TCP clients may connect to a -single TCP server port. - -.SH OPTIONS -.TP -.BR \-H ", " \-\^\-hub -By default, the controller acts as an L2 MAC-learning switch. This -option changes its behavior to that of a hub that floods packets on -all but the incoming port. - -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -.BR \-n ", " \-\^\-noflow -This is similar to the \fB\-\^\-hub\fR option, but does not add a -flow entry in the switch. This causes all traffic seen by the switch -to be passed to the controller before being sent out all but the -incoming port. - -.TP -.BR \-v ", " \-\^\-verbose -Prints debug messages to the console. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. - -.SH EXAMPLES - -.TP -To connect directly to local datapath 0 over netlink (Linux only): - -.B % controller nl:0 - -.TP -To bind locally to port 975 (the default) and wait for incoming connections from secure channels: - -.B % controller ptcp: - -.SH "SEE ALSO" - -.BR dpctl (8), -.BR switch (8), -.BR secchan (8) -.BR vlogconf (8) - -.SH BUGS -Currently \fBcontroller\fR does not support SSL. diff --git a/man/man8/dpctl.8 b/man/man8/dpctl.8 deleted file mode 100644 index 3456339a..00000000 --- a/man/man8/dpctl.8 +++ /dev/null @@ -1,190 +0,0 @@ -.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -dpctl \- command line tool to administer OpenFlow datapaths - -.SH SYNOPSIS -.B dpctl -[OPTIONS] COMMAND [SWITCH] [ARGS...] - -.SH DESCRIPTION -The -.B dpctl -program is a command line tool for monitoring and administering OpenFlow -datapaths. It is able to show the current state of a datapath, -including features, configuration, and tables entries. When using the -OpenFlow kernel module, -.B dpctl -is used to add, delete, modify, and monitor datapaths. - - -.SH OPTIONS -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -.BR \-v ", " \-\^\-verbose -Prints debug messages to the console. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. - -.SH COMMANDS - -Depending on the type of datapath, \fBdpctl\fR communicates using -different connection methods. As such, one must provide the method to -use as the \fISWITCH\fR argument. To communicate with userspace, -\fItcp:host[:port]\fR is used. The netlink interface is used to -communicate with the kernel module directly. This uses the form -\fInl:DP_IDX\fR, where \fIDP_IDX\fR is explained below. - -.B COMMANDS FOR THE KERNEL MODULE - -With the \fBdpctl\fR program, datapaths running in the kernel can be -created, deleted, modified, and monitored. A single machine may -host up to 32 datapaths (numbered 0 to 31). In most situations, -a machine hosts only one datapath. - -A newly created datapath is not associated with any of the -host's network interfaces and thus does not process any incoming -traffic. To intercept and process traffic on a given interface, the -interface must be explicitly added to a datapath through the -\fBaddif\fR command. - - -.TP -.BI adddp " nl:DP_IDX" -Creates datapath numbered \fIDP_IDX\fR on the local host. This will -fail if \fIDP_IDX\fR is not in the range 0 to 31, or if the datapath -with that number already exists on the host. - -.TP -.BI deldp " nl:DP_IDX" -Deletes datapath \fIDP_IDX\fR on the local host. \fIDP_IDX\fR must be -an existing datapath. All of a datapath's interfaces must be -explicitly removed before the datapath can be deleted (see \fBdelif\fR -command). - -.TP -.BI addif " nl:DP_IDX INTERFACE" -Adds \fIINTERFACE\fR to the list of network interfaces datapath -\fIDP_IDX\fR monitors, where \fIDP_IDX\fR is the ID of an existing -datapath, and \fIINTERFACE\fR is the name of one of the host's -interfaces, e.g. \fBeth0\fR. Once an interface has been added -to a datapath, the datapath has complete ownership of the interface's -traffic and the interface appears silent to the rest of the system. - -.TP -.BI delif " nl:DP_IDX INTERFACE" -Removes \fIINTERFACE\fR from the list of network interfaces datapath -\fIDP_IDX\fR monitors. - -.TP -.BI monitor " nl:DP_IDX" -Prints to the console all OpenFlow packets sent by datapath -\fIDP_IDX\fR to its controller, where \fIDP_IDX\fR is the ID of an -existing datapath. - -.TP -.BI benchmark-nl " nl:DP_IDX N SIZE" -Checks the netlink performance between the kernel and userspace. -This is done by sending \fIN\fR packets of \fISIZE\fR bytes from -the kernel module to dpctl. - - -.TP -.B GENERAL COMMANDS - -.TP -The following commands can be used regardless of the connection method. - -.TP -.BI show " SWITCH" -Prints to the console information on datapath \fISWITCH\fR including -information on its flow tables and ports. - -.TP -.BI dump-tables " SWITCH" -Prints to the console statistics for each of the flow tables used by -datapath \fISWITCH\fR. - -.TP -.BI dump-ports " SWITCH" -Prints to the console statistics for each of the physical interfaces -associated with datapath \fISWITCH\fR. - -.TP -.BI dump-flows " SWITCH [FLOW]" -Prints to the console all flow entries in datapath \fISWITCH\fR's tables -that match \fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the -datapath are retrieved. - -.TP -.BI dump-aggregate " SWITCH [FLOWS]" -Prints to the console aggregate statistics for flows in datapath -\fSWITCH\fR's tables that match \fIFLOWS\fR. If \fIFLOWS\fR is omitted, -the statistics are aggregated across all flows in the datapath's flow -tables. - -.TP -.BI add-flows " SWITCH FILE" -Add flow entries as described in \fIFILE\fR to the datapath \fISWITCH\fR's -tables. Each line in \fIFILE\fR describes an entry in the format used -to describe a \fIFLOW\fR in other commands.. - -.TP -.BI del-flows " SWITCH [FLOW]" -Deletes entries from the datapath \fISWITCH\fR's tables that match -\fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the datapath's -tables are removed. - -.SH EXAMPLES - -A typical dpctl command sequence for controlling an OpenFlow kernel module: -.nf -.TP -Create datapath numbered 0: - -.B % dpctl adddp nl:0 - -.TP -Add two interfaces to the new datapath: - -.B % dpctl addif nl:0 eth0 -.B % dpctl addif nl:0 eth1 - -.TP -Monitor traffic received by the datapath (exit with control-C): - -.B % dpctl monitor nl:0 - - -.TP -View the datapath's table stats after some traffic has passed through: - -.B % dpctl dump-tables nl:0 - -.TP -View the flow entries in the datapath: - -.B % dpctl dump-flows nl:0 - -.TP -Remove interfaces from the datapath when finished: - -.B % dpctl delif nl:0 eth0 -.B % dpctl delif nl:0 eth1 - -.TP -Delete the datapath: - -.B % dpctl deldp nl:0 -.fi -.SH "SEE ALSO" - -.BR secchan (8), -.BR switch (8) -.BR controller (8) -.BR vlogconf (8) diff --git a/man/man8/ofp-pki.8 b/man/man8/ofp-pki.8 deleted file mode 100644 index 113b3256..00000000 --- a/man/man8/ofp-pki.8 +++ /dev/null @@ -1,145 +0,0 @@ -.TH ofp-pki 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -ofp\-pki \- OpenFlow public key infrastructure management utility - -.SH SYNOPSIS -\fBofp\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR] -.sp -Commands with their arguments: -.br -\fBofp\-pki\fR \fBnew-pki\fR -.br -\fBofp\-pki\fR \fBreq\fR \fINAME\fR -.br -\fBofp\-pki\fR \fBsign\fR \fINAME\fR \fITYPE\fR -.br -\fBofp\-pki\fR \fBreq+sign\fR \fINAME\fR \fITYPE\fR -.br -\fBofp\-pki\fR \fBverify\fR \fINAME\fR \fITYPE\fR -.sp -The available options are: -.br -[\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR] [\fB-f\fR | \fB--force\fR] [\fB-b\fR | \fB--batch\fR] [\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR] [\fB-h\fR | \fB--help\fR] - -.SH DESCRIPTION -The \fBofp-pki\fR program sets up and manages a public key -infrastructure for use with OpenFlow. It is intended to be a simple -interface for organizations that do not have an established public key -infrastructure. Other PKI tools can substitute for or supplement the -use of \fBofp-pki\fR. - -\fBofp-pki\fR uses \fBopenssl\fR(1) for certificate management and key -generation. - -The commands supported by \fBofp-pki\fR are: - -.TP -\fBnew-pki\fR -Creates a new PKI directory (by default named \fBpki\fR) and populates -it with a pair of certificate authorities for controllers and -switches. - -This command should ideally be run on a high-security machine separate -from any OpenFlow controller or switch, called the CA machine. The -files \fBpki/controllerca/cacert.pem\fR and -\fBpki/switchca/cacert.pem\fR that it produces will need to be copied -over to the OpenFlow switches and controllers, respectively. Their -contents may safely be made public. - -Other files generated by \fBnew-pki\fR may remain on the CA machine. -The files \fBpki/controllerca/private/cakey.pem\fR and -\fBpki/switchca/private/cakey.pem\fR have particularly sensitive -contents that should not be exposed. - -.TP -\fBreq\fR \fINAME\fR -Generates a new private key named \fINAME\fR\fB-privkey.pem\fR and -corresponding certificate request named \fINAME\fR\fB-req.pem\fR. -The private key can be intended for use by a switch or a controller. - -This command should ideally be run on the switch or controller that -will use the private key to identify itself. The file -\fINAME\fR\fB-req.pem\fR must be copied to the CA machine for signing -with the \fBsign\fR command (below). - -This command will output a fingerprint to stdout as its final step. -Write down the fingerprint and take it to the CA machine before -continuing with the \fBsign\fR step. - -\fINAME\fR\fB-privkey.pem\fR has sensitive contents that should not be -exposed. \fINAME\fR\fB-req.pem\fR may be safely made public. - -.TP -\fBsign\fR \fINAME\fR \fITYPE\fR -Signs the certificate request named \fINAME\fR\fB-req.pem\fR that was -produced in the previous step, producing a certificate named -\fINAME\fR\fB-cert.pem\fR. \fITYPE\fR, which must be \fBswitch\fR or -\fBcontroller\fR, indicates the use for which the key is being -certified. - -This command must be run on the CA machine. - -The command will output a fingerprint to stdout and request that you -verify that it is the same fingerprint output by the \fBreq\fR -command. This ensures that the request being signed is the same one -produced by \fBreq\fR. - -The file \fINAME\fR\fB-cert.pem\fR will need to be copied back to the -switch or controller for which it is intended. Its contents may -safely be made public. - -.TP -\fBreq+sign\fR \fINAME\fR \fITYPE\fR -Combines the \fBreq\fR and \fBsign\fR commands into a single step, -outputting all the files produced by each. The -\fINAME\fR\fB-privkey.pem\fR and \fINAME\fR\fB-cert.pem\fR files must -be copied securely to the switch or controller. -\fINAME\fR\fB-privkey.pem\fR has sensitive contents and must not be -exposed in transit. Afterward, it should be deleted from the CA -machine. - -This combined method is, theoretically, less secure than the -individual steps performed separately on two different machines, -because there is additional potential for exposure of the private -key. However, it is also more convenient. - -.TP -\fBverify\fR \fINAME\fR \fITYPE\fR -Verifies that \fINAME\fR\fB-cert.pem\fR is a valid certificate for the -given \fITYPE\fR of use (either \fBswitch\fR or \fBcontroller\fR). If -the certificate is valid for this use, it prints the message -``\fINAME\fR\fB-cert.pem\fR: OK''; otherwise, it prints an error -message. - -.SH OPTIONS -.TP -[\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR] -Specifies the location of the PKI hierarchy to be used or created by -the command (default: \fBpki\fR under the current directory). The -\fBreq\fR command does not need access to a PKI hierarchy. - -.TP -[\fB-f\fR | \fB--force\fR] -By default, \fBofp-pki\fR will not overwrite existing files or -directories. This option overrides this behavior. - -.TP -[\fB-b\fR | \fB--batch\fR] -Suppresses the interactive verification of fingerprints that the -\fBsign\fR command by default requires. - -.TP -[\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR] -Sets the log file to \fIFILE\fR (default: ofp-pki.log). - -.TP -[\fB-h\fR | \fB--help\fR] -Prints a help usage message and exits. - -.SH "SEE ALSO" - -.BR dpctl (8), -.BR switch (8), -.BR secchan (8), -.BR controller (8) diff --git a/man/man8/secchan.8 b/man/man8/secchan.8 deleted file mode 100644 index 2f73dc06..00000000 --- a/man/man8/secchan.8 +++ /dev/null @@ -1,43 +0,0 @@ -.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -secchan \- secure channel connecting an OpenFlow datapath to a controller - -.SH SYNOPSIS -.B secchan -[OPTIONS] nl:\fIDP_IDX\fR tcp:\fICONTROLLER_IP\fR[:\fICONTROLLER_TCP_PORT\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 datapath over netlink and to the controller over TCP, and then -proceeds to forward packets from one endpoint to the other. - -\fIDP_IDX\fR \- the ID of the local datapath to connect to - -\fICONTROLLER_IP\fR \- the controller's IP address - -\fICONTROLLER_TCP_PORT\fR \- the controller's TCP port to connect to \- defaults to 975 - -.SH OPTIONS -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -.BR \-v ", " \-\^\-verbose -Prints debug messages to the console. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. - -.SH "SEE ALSO" - -.BR dpctl (8), -.BR switch (8), -.BR controller (8) -.BR vlogconf (8) - -.SH BUGS -Currently \fBsecchan\fR does not support SSL diff --git a/man/man8/switch.8 b/man/man8/switch.8 deleted file mode 100644 index c0811494..00000000 --- a/man/man8/switch.8 +++ /dev/null @@ -1,92 +0,0 @@ -.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -switch \- userspace implementation of OpenFlow switch - -.SH SYNOPSIS -.B switch -[\fIoptions\fR] -\fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR]... -\fIcontroller\fR - -.SH DESCRIPTION -The \fBswitch\fR is a userspace implementation of an OpenFlow switch. -It implements all three parts of the OpenFlow switch specification: a -``flow table'' in which each flow entry is associated with an action -telling the switch how to process the flow; a ``secure channel'' -connecting the switch to a remote process (a controller), allowing -commands and packets to be sent between the controller and the switch; -and an OpenFlow protocol implementation. - -\fBswitch\fR monitors one or more network device interfaces, -forwarding packets between them according to the entries in the flow -table. It also maintains a connection to an OpenFlow controller over -a TCP or SSL connection, relaying packets that do not match a flow -table entry to the controller and executing commands sent by the -controller. - -For access to network devices, the switch program must normally run as -root. - -The mandatory \fIcontroller\fR argument specifies how to connect to -the OpenFlow controller. It takes one of the following forms: - -.TP -\fBtcp:\fIhost\fR[\fB:\fIport\fR] -The specified TCP \fIport\fR (default: 975) on the given remote -\fIhost\fR. - -.TP -\fBssl:\fIhost\fR[\fB:\fIport\fR] -The specified SSL \fIport\fR (default: 976) on the given remote -\fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and -\fB--ca-cert\fR options are mandatory when this form is used. - -.SH OPTIONS -.TP -\fB-i\fR, \fB--interfaces=\fR\fInetdev\fR[\fB,\fInetdev\fR]... -Specifies each \fInetdev\fR (e.g., \fBeth0\fR) as a switch port. The -specified network devices should not have any configured IP addresses. -This option may be given any number of times to specify additional -network devices. - -.TP -\fB-d\fR, \fB--datapath-id=\fIdpid\fR -Specifies the OpenFlow switch ID (a 48-bit number that uniquely -identifies a controller) as \fIdpid\fR, which consists of exactly 12 -hex digits. Without this option, \fBswitch\fR picks an ID randomly. - -.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 -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -.BR \-v ", " \-\^\-verbose -Prints debug messages to the console. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. - -.SH "SEE ALSO" - -.BR dpctl (8), -.BR ofp-pki (8), -.BR controller (8) -.BR vlogconf (8) diff --git a/man/man8/vlogconf.8 b/man/man8/vlogconf.8 deleted file mode 100644 index 46842fe8..00000000 --- a/man/man8/vlogconf.8 +++ /dev/null @@ -1,68 +0,0 @@ -.TH vlogconf 8 "March 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -vlogconf \- configuration utility for OpenFlow logging in userspace - -.SH SYNOPSIS -\fBvlogconf\fR [\fB-h\fR | \fB--help\fR] [TARGET...] [ACTION...] -.sp 1 -The available TARGET options are: -.br -[\fB-a\fR | \fB--all\fR] [\fB-t\fR PID | \fB--target=\fIPID\fR] -.sp 1 -The available ACTION options are: -.br -[\fB-l\fR | \fB--list\fR] [\fB-s\fR -\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR | -\fB--set=\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR] - -.SH DESCRIPTION -The \fBvlogconf\fR program configures the logging system used by the -OpenFlow userspace programs. The logging configuration may be modified -while OpenFlow programs are running. - -\fBvlogconf\fR applies one or more actions to each of one or more -target processes. Targets may be specified as: - -.TP -\fB-a\fR, \fB--all\fR -All running processes that \fBvlogconf\fR can control. - -.TP -\fB-t \fIPID\fR, \fB--target=\fIPID\fR -The process with the specified \fIPID\fR. \fIPID\fR may also specify -an absolute path (beginning with `/') to the Unix domain socket for a -\fBvlogconf\fR-controllable process. - -.PP -The available actions are: - -.TP -\fB-l\fR, \fB--list\fR -Print the list of known modules and their current logging levels to -stdout. - -.TP -\fB-s\fR \fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR, \fB--set=\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR - -Sets the logging level for \fIMODULE\fR in \fIFACILITY\fR to -\fILEVEL\fR. \fIMODULE\fR may be any valid module name (as displayed -by the \fB--list\fR option) or the special name \fBANY\fR to set all -modules logging level. \fIFACILITY\fR may be \fBsyslog\fR or -\fBconsole\fR to set the levels for logging to the system log or to -the console, respectively, or \fBANY\fR to set the logging levels for -both modules. \fILEVEL\fR must be one of \fBemer\fR, \fBerr\fR, -\fBwarn\fR, or \fBdbg\fR, designating the minimum severity of a -message for it to be logged. - -.SH OPTIONS -.TP -\fB\-h\fR, \fB\-\^\-help\fR -Prints a brief help message to the console and exits. - - -.SH "SEE ALSO" - -.BR dpctl (8), -.BR secchan (8), -.BR controller (8) diff --git a/secchan/Makefile.am b/secchan/Makefile.am index 882c98e7..10de2324 100644 --- a/secchan/Makefile.am +++ b/secchan/Makefile.am @@ -2,8 +2,10 @@ include ../Make.vars if HAVE_NETLINK bin_PROGRAMS = secchan +dist_man_MANS = secchan.8 else bin_PROGRAMS = +dist_man_MANS = endif secchan_SOURCES = secchan.c diff --git a/secchan/secchan.8 b/secchan/secchan.8 new file mode 100644 index 00000000..2f73dc06 --- /dev/null +++ b/secchan/secchan.8 @@ -0,0 +1,43 @@ +.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +secchan \- secure channel connecting an OpenFlow datapath to a controller + +.SH SYNOPSIS +.B secchan +[OPTIONS] nl:\fIDP_IDX\fR tcp:\fICONTROLLER_IP\fR[:\fICONTROLLER_TCP_PORT\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 datapath over netlink and to the controller over TCP, and then +proceeds to forward packets from one endpoint to the other. + +\fIDP_IDX\fR \- the ID of the local datapath to connect to + +\fICONTROLLER_IP\fR \- the controller's IP address + +\fICONTROLLER_TCP_PORT\fR \- the controller's TCP port to connect to \- defaults to 975 + +.SH OPTIONS +.TP +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +.TP +.BR \-v ", " \-\^\-verbose +Prints debug messages to the console. + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. + +.SH "SEE ALSO" + +.BR dpctl (8), +.BR switch (8), +.BR controller (8) +.BR vlogconf (8) + +.SH BUGS +Currently \fBsecchan\fR does not support SSL diff --git a/switch/Makefile.am b/switch/Makefile.am index c16cef72..2ea1ac2d 100644 --- a/switch/Makefile.am +++ b/switch/Makefile.am @@ -1,6 +1,7 @@ include ../Make.vars bin_PROGRAMS = switch +dist_man_MANS = switch.8 switch_SOURCES = \ chain.c \ diff --git a/switch/switch.8 b/switch/switch.8 new file mode 100644 index 00000000..c0811494 --- /dev/null +++ b/switch/switch.8 @@ -0,0 +1,92 @@ +.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +switch \- userspace implementation of OpenFlow switch + +.SH SYNOPSIS +.B switch +[\fIoptions\fR] +\fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR]... +\fIcontroller\fR + +.SH DESCRIPTION +The \fBswitch\fR is a userspace implementation of an OpenFlow switch. +It implements all three parts of the OpenFlow switch specification: a +``flow table'' in which each flow entry is associated with an action +telling the switch how to process the flow; a ``secure channel'' +connecting the switch to a remote process (a controller), allowing +commands and packets to be sent between the controller and the switch; +and an OpenFlow protocol implementation. + +\fBswitch\fR monitors one or more network device interfaces, +forwarding packets between them according to the entries in the flow +table. It also maintains a connection to an OpenFlow controller over +a TCP or SSL connection, relaying packets that do not match a flow +table entry to the controller and executing commands sent by the +controller. + +For access to network devices, the switch program must normally run as +root. + +The mandatory \fIcontroller\fR argument specifies how to connect to +the OpenFlow controller. It takes one of the following forms: + +.TP +\fBtcp:\fIhost\fR[\fB:\fIport\fR] +The specified TCP \fIport\fR (default: 975) on the given remote +\fIhost\fR. + +.TP +\fBssl:\fIhost\fR[\fB:\fIport\fR] +The specified SSL \fIport\fR (default: 976) on the given remote +\fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and +\fB--ca-cert\fR options are mandatory when this form is used. + +.SH OPTIONS +.TP +\fB-i\fR, \fB--interfaces=\fR\fInetdev\fR[\fB,\fInetdev\fR]... +Specifies each \fInetdev\fR (e.g., \fBeth0\fR) as a switch port. The +specified network devices should not have any configured IP addresses. +This option may be given any number of times to specify additional +network devices. + +.TP +\fB-d\fR, \fB--datapath-id=\fIdpid\fR +Specifies the OpenFlow switch ID (a 48-bit number that uniquely +identifies a controller) as \fIdpid\fR, which consists of exactly 12 +hex digits. Without this option, \fBswitch\fR picks an ID randomly. + +.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 +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +.TP +.BR \-v ", " \-\^\-verbose +Prints debug messages to the console. + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. + +.SH "SEE ALSO" + +.BR dpctl (8), +.BR ofp-pki (8), +.BR controller (8) +.BR vlogconf (8) diff --git a/utilities/Makefile.am b/utilities/Makefile.am index b07dd49f..9b3e4df2 100644 --- a/utilities/Makefile.am +++ b/utilities/Makefile.am @@ -1,6 +1,7 @@ include ../Make.vars bin_PROGRAMS = vlogconf dpctl +dist_man_MANS = vlogconf.8 dpctl.8 ofp-pki.8 dpctl_SOURCES = dpctl.c dpctl_LDADD = ../lib/libopenflow.la diff --git a/utilities/dpctl.8 b/utilities/dpctl.8 new file mode 100644 index 00000000..3456339a --- /dev/null +++ b/utilities/dpctl.8 @@ -0,0 +1,190 @@ +.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +dpctl \- command line tool to administer OpenFlow datapaths + +.SH SYNOPSIS +.B dpctl +[OPTIONS] COMMAND [SWITCH] [ARGS...] + +.SH DESCRIPTION +The +.B dpctl +program is a command line tool for monitoring and administering OpenFlow +datapaths. It is able to show the current state of a datapath, +including features, configuration, and tables entries. When using the +OpenFlow kernel module, +.B dpctl +is used to add, delete, modify, and monitor datapaths. + + +.SH OPTIONS +.TP +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +.TP +.BR \-v ", " \-\^\-verbose +Prints debug messages to the console. + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. + +.SH COMMANDS + +Depending on the type of datapath, \fBdpctl\fR communicates using +different connection methods. As such, one must provide the method to +use as the \fISWITCH\fR argument. To communicate with userspace, +\fItcp:host[:port]\fR is used. The netlink interface is used to +communicate with the kernel module directly. This uses the form +\fInl:DP_IDX\fR, where \fIDP_IDX\fR is explained below. + +.B COMMANDS FOR THE KERNEL MODULE + +With the \fBdpctl\fR program, datapaths running in the kernel can be +created, deleted, modified, and monitored. A single machine may +host up to 32 datapaths (numbered 0 to 31). In most situations, +a machine hosts only one datapath. + +A newly created datapath is not associated with any of the +host's network interfaces and thus does not process any incoming +traffic. To intercept and process traffic on a given interface, the +interface must be explicitly added to a datapath through the +\fBaddif\fR command. + + +.TP +.BI adddp " nl:DP_IDX" +Creates datapath numbered \fIDP_IDX\fR on the local host. This will +fail if \fIDP_IDX\fR is not in the range 0 to 31, or if the datapath +with that number already exists on the host. + +.TP +.BI deldp " nl:DP_IDX" +Deletes datapath \fIDP_IDX\fR on the local host. \fIDP_IDX\fR must be +an existing datapath. All of a datapath's interfaces must be +explicitly removed before the datapath can be deleted (see \fBdelif\fR +command). + +.TP +.BI addif " nl:DP_IDX INTERFACE" +Adds \fIINTERFACE\fR to the list of network interfaces datapath +\fIDP_IDX\fR monitors, where \fIDP_IDX\fR is the ID of an existing +datapath, and \fIINTERFACE\fR is the name of one of the host's +interfaces, e.g. \fBeth0\fR. Once an interface has been added +to a datapath, the datapath has complete ownership of the interface's +traffic and the interface appears silent to the rest of the system. + +.TP +.BI delif " nl:DP_IDX INTERFACE" +Removes \fIINTERFACE\fR from the list of network interfaces datapath +\fIDP_IDX\fR monitors. + +.TP +.BI monitor " nl:DP_IDX" +Prints to the console all OpenFlow packets sent by datapath +\fIDP_IDX\fR to its controller, where \fIDP_IDX\fR is the ID of an +existing datapath. + +.TP +.BI benchmark-nl " nl:DP_IDX N SIZE" +Checks the netlink performance between the kernel and userspace. +This is done by sending \fIN\fR packets of \fISIZE\fR bytes from +the kernel module to dpctl. + + +.TP +.B GENERAL COMMANDS + +.TP +The following commands can be used regardless of the connection method. + +.TP +.BI show " SWITCH" +Prints to the console information on datapath \fISWITCH\fR including +information on its flow tables and ports. + +.TP +.BI dump-tables " SWITCH" +Prints to the console statistics for each of the flow tables used by +datapath \fISWITCH\fR. + +.TP +.BI dump-ports " SWITCH" +Prints to the console statistics for each of the physical interfaces +associated with datapath \fISWITCH\fR. + +.TP +.BI dump-flows " SWITCH [FLOW]" +Prints to the console all flow entries in datapath \fISWITCH\fR's tables +that match \fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the +datapath are retrieved. + +.TP +.BI dump-aggregate " SWITCH [FLOWS]" +Prints to the console aggregate statistics for flows in datapath +\fSWITCH\fR's tables that match \fIFLOWS\fR. If \fIFLOWS\fR is omitted, +the statistics are aggregated across all flows in the datapath's flow +tables. + +.TP +.BI add-flows " SWITCH FILE" +Add flow entries as described in \fIFILE\fR to the datapath \fISWITCH\fR's +tables. Each line in \fIFILE\fR describes an entry in the format used +to describe a \fIFLOW\fR in other commands.. + +.TP +.BI del-flows " SWITCH [FLOW]" +Deletes entries from the datapath \fISWITCH\fR's tables that match +\fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the datapath's +tables are removed. + +.SH EXAMPLES + +A typical dpctl command sequence for controlling an OpenFlow kernel module: +.nf +.TP +Create datapath numbered 0: + +.B % dpctl adddp nl:0 + +.TP +Add two interfaces to the new datapath: + +.B % dpctl addif nl:0 eth0 +.B % dpctl addif nl:0 eth1 + +.TP +Monitor traffic received by the datapath (exit with control-C): + +.B % dpctl monitor nl:0 + + +.TP +View the datapath's table stats after some traffic has passed through: + +.B % dpctl dump-tables nl:0 + +.TP +View the flow entries in the datapath: + +.B % dpctl dump-flows nl:0 + +.TP +Remove interfaces from the datapath when finished: + +.B % dpctl delif nl:0 eth0 +.B % dpctl delif nl:0 eth1 + +.TP +Delete the datapath: + +.B % dpctl deldp nl:0 +.fi +.SH "SEE ALSO" + +.BR secchan (8), +.BR switch (8) +.BR controller (8) +.BR vlogconf (8) diff --git a/utilities/ofp-pki.8 b/utilities/ofp-pki.8 new file mode 100644 index 00000000..113b3256 --- /dev/null +++ b/utilities/ofp-pki.8 @@ -0,0 +1,145 @@ +.TH ofp-pki 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +ofp\-pki \- OpenFlow public key infrastructure management utility + +.SH SYNOPSIS +\fBofp\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR] +.sp +Commands with their arguments: +.br +\fBofp\-pki\fR \fBnew-pki\fR +.br +\fBofp\-pki\fR \fBreq\fR \fINAME\fR +.br +\fBofp\-pki\fR \fBsign\fR \fINAME\fR \fITYPE\fR +.br +\fBofp\-pki\fR \fBreq+sign\fR \fINAME\fR \fITYPE\fR +.br +\fBofp\-pki\fR \fBverify\fR \fINAME\fR \fITYPE\fR +.sp +The available options are: +.br +[\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR] [\fB-f\fR | \fB--force\fR] [\fB-b\fR | \fB--batch\fR] [\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR] [\fB-h\fR | \fB--help\fR] + +.SH DESCRIPTION +The \fBofp-pki\fR program sets up and manages a public key +infrastructure for use with OpenFlow. It is intended to be a simple +interface for organizations that do not have an established public key +infrastructure. Other PKI tools can substitute for or supplement the +use of \fBofp-pki\fR. + +\fBofp-pki\fR uses \fBopenssl\fR(1) for certificate management and key +generation. + +The commands supported by \fBofp-pki\fR are: + +.TP +\fBnew-pki\fR +Creates a new PKI directory (by default named \fBpki\fR) and populates +it with a pair of certificate authorities for controllers and +switches. + +This command should ideally be run on a high-security machine separate +from any OpenFlow controller or switch, called the CA machine. The +files \fBpki/controllerca/cacert.pem\fR and +\fBpki/switchca/cacert.pem\fR that it produces will need to be copied +over to the OpenFlow switches and controllers, respectively. Their +contents may safely be made public. + +Other files generated by \fBnew-pki\fR may remain on the CA machine. +The files \fBpki/controllerca/private/cakey.pem\fR and +\fBpki/switchca/private/cakey.pem\fR have particularly sensitive +contents that should not be exposed. + +.TP +\fBreq\fR \fINAME\fR +Generates a new private key named \fINAME\fR\fB-privkey.pem\fR and +corresponding certificate request named \fINAME\fR\fB-req.pem\fR. +The private key can be intended for use by a switch or a controller. + +This command should ideally be run on the switch or controller that +will use the private key to identify itself. The file +\fINAME\fR\fB-req.pem\fR must be copied to the CA machine for signing +with the \fBsign\fR command (below). + +This command will output a fingerprint to stdout as its final step. +Write down the fingerprint and take it to the CA machine before +continuing with the \fBsign\fR step. + +\fINAME\fR\fB-privkey.pem\fR has sensitive contents that should not be +exposed. \fINAME\fR\fB-req.pem\fR may be safely made public. + +.TP +\fBsign\fR \fINAME\fR \fITYPE\fR +Signs the certificate request named \fINAME\fR\fB-req.pem\fR that was +produced in the previous step, producing a certificate named +\fINAME\fR\fB-cert.pem\fR. \fITYPE\fR, which must be \fBswitch\fR or +\fBcontroller\fR, indicates the use for which the key is being +certified. + +This command must be run on the CA machine. + +The command will output a fingerprint to stdout and request that you +verify that it is the same fingerprint output by the \fBreq\fR +command. This ensures that the request being signed is the same one +produced by \fBreq\fR. + +The file \fINAME\fR\fB-cert.pem\fR will need to be copied back to the +switch or controller for which it is intended. Its contents may +safely be made public. + +.TP +\fBreq+sign\fR \fINAME\fR \fITYPE\fR +Combines the \fBreq\fR and \fBsign\fR commands into a single step, +outputting all the files produced by each. The +\fINAME\fR\fB-privkey.pem\fR and \fINAME\fR\fB-cert.pem\fR files must +be copied securely to the switch or controller. +\fINAME\fR\fB-privkey.pem\fR has sensitive contents and must not be +exposed in transit. Afterward, it should be deleted from the CA +machine. + +This combined method is, theoretically, less secure than the +individual steps performed separately on two different machines, +because there is additional potential for exposure of the private +key. However, it is also more convenient. + +.TP +\fBverify\fR \fINAME\fR \fITYPE\fR +Verifies that \fINAME\fR\fB-cert.pem\fR is a valid certificate for the +given \fITYPE\fR of use (either \fBswitch\fR or \fBcontroller\fR). If +the certificate is valid for this use, it prints the message +``\fINAME\fR\fB-cert.pem\fR: OK''; otherwise, it prints an error +message. + +.SH OPTIONS +.TP +[\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR] +Specifies the location of the PKI hierarchy to be used or created by +the command (default: \fBpki\fR under the current directory). The +\fBreq\fR command does not need access to a PKI hierarchy. + +.TP +[\fB-f\fR | \fB--force\fR] +By default, \fBofp-pki\fR will not overwrite existing files or +directories. This option overrides this behavior. + +.TP +[\fB-b\fR | \fB--batch\fR] +Suppresses the interactive verification of fingerprints that the +\fBsign\fR command by default requires. + +.TP +[\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR] +Sets the log file to \fIFILE\fR (default: ofp-pki.log). + +.TP +[\fB-h\fR | \fB--help\fR] +Prints a help usage message and exits. + +.SH "SEE ALSO" + +.BR dpctl (8), +.BR switch (8), +.BR secchan (8), +.BR controller (8) diff --git a/utilities/vlogconf.8 b/utilities/vlogconf.8 new file mode 100644 index 00000000..46842fe8 --- /dev/null +++ b/utilities/vlogconf.8 @@ -0,0 +1,68 @@ +.TH vlogconf 8 "March 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +vlogconf \- configuration utility for OpenFlow logging in userspace + +.SH SYNOPSIS +\fBvlogconf\fR [\fB-h\fR | \fB--help\fR] [TARGET...] [ACTION...] +.sp 1 +The available TARGET options are: +.br +[\fB-a\fR | \fB--all\fR] [\fB-t\fR PID | \fB--target=\fIPID\fR] +.sp 1 +The available ACTION options are: +.br +[\fB-l\fR | \fB--list\fR] [\fB-s\fR +\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR | +\fB--set=\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR] + +.SH DESCRIPTION +The \fBvlogconf\fR program configures the logging system used by the +OpenFlow userspace programs. The logging configuration may be modified +while OpenFlow programs are running. + +\fBvlogconf\fR applies one or more actions to each of one or more +target processes. Targets may be specified as: + +.TP +\fB-a\fR, \fB--all\fR +All running processes that \fBvlogconf\fR can control. + +.TP +\fB-t \fIPID\fR, \fB--target=\fIPID\fR +The process with the specified \fIPID\fR. \fIPID\fR may also specify +an absolute path (beginning with `/') to the Unix domain socket for a +\fBvlogconf\fR-controllable process. + +.PP +The available actions are: + +.TP +\fB-l\fR, \fB--list\fR +Print the list of known modules and their current logging levels to +stdout. + +.TP +\fB-s\fR \fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR, \fB--set=\fIMODULE\fB:\fIFACILITY\fB:\fILEVEL\fR + +Sets the logging level for \fIMODULE\fR in \fIFACILITY\fR to +\fILEVEL\fR. \fIMODULE\fR may be any valid module name (as displayed +by the \fB--list\fR option) or the special name \fBANY\fR to set all +modules logging level. \fIFACILITY\fR may be \fBsyslog\fR or +\fBconsole\fR to set the levels for logging to the system log or to +the console, respectively, or \fBANY\fR to set the logging levels for +both modules. \fILEVEL\fR must be one of \fBemer\fR, \fBerr\fR, +\fBwarn\fR, or \fBdbg\fR, designating the minimum severity of a +message for it to be logged. + +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\^\-help\fR +Prints a brief help message to the console and exits. + + +.SH "SEE ALSO" + +.BR dpctl (8), +.BR secchan (8), +.BR controller (8)