if HAVE_IF_PACKET
SUBDIRS += switch
endif
-SUBDIRS += utilities tests man include third-party
+SUBDIRS += utilities tests include third-party
- 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
----------------
CFLAGS="$CFLAGS -Wall -Wno-sign-compare"
AC_CONFIG_FILES([Makefile
-man/Makefile
-man/man8/Makefile
datapath/Makefile
lib/Makefile
include/Makefile
include ../Make.vars
bin_PROGRAMS = controller
+dist_man_MANS = controller.8
controller_SOURCES = controller.c
controller_LDADD = ../lib/libopenflow.la -ldl
--- /dev/null
+.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.
+++ /dev/null
-/Makefile
-/Makefile.in
+++ /dev/null
-SUBDIRS = man8
+++ /dev/null
-/Makefile
-/Makefile.in
+++ /dev/null
-dist_man_MANS = controller.8 dpctl.8 secchan.8 vlogconf.8
+++ /dev/null
-.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.
+++ /dev/null
-.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)
+++ /dev/null
-.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)
+++ /dev/null
-.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
+++ /dev/null
-.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)
+++ /dev/null
-.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)
if HAVE_NETLINK
bin_PROGRAMS = secchan
+dist_man_MANS = secchan.8
else
bin_PROGRAMS =
+dist_man_MANS =
endif
secchan_SOURCES = secchan.c
--- /dev/null
+.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
include ../Make.vars
bin_PROGRAMS = switch
+dist_man_MANS = switch.8
switch_SOURCES = \
chain.c \
--- /dev/null
+.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)
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
--- /dev/null
+.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)
--- /dev/null
+.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)
--- /dev/null
+.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)
projects / openvswitch / commitdiff