From e7b0a579de3451eaa1ceea05c25c356ff4bbde8c Mon Sep 17 00:00:00 2001 From: Justin Pettit Date: Fri, 2 May 2008 21:46:39 -0700 Subject: [PATCH] - Update man pages to reflect recent spat of changes. - Clean-up man pages. --- man/man8/controller.8 | 22 ++++--- man/man8/dpctl.8 | 148 +++++++++++++++++++++++++++--------------- man/man8/ofp-pki.8 | 3 +- man/man8/secchan.8 | 3 +- man/man8/switch.8 | 8 +-- 5 files changed, 114 insertions(+), 70 deletions(-) diff --git a/man/man8/controller.8 b/man/man8/controller.8 index 4af54807..de0d41a4 100644 --- a/man/man8/controller.8 +++ b/man/man8/controller.8 @@ -1,7 +1,7 @@ -.TH controller 8 "December 2007" "OpenFlow" "OpenFlow Manual" +.TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME -controller \- OpenFlow controller reference implementation +controller \- simple OpenFlow controller reference implementation .SH SYNOPSIS .B controller @@ -11,12 +11,12 @@ controller \- OpenFlow controller reference implementation 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 a local datapath via netlink. -To connect to 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.) +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 @@ -27,7 +27,7 @@ single TCP server port. .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 ports. +all but the incoming port. .TP .BR \-h ", " \-\^\-help @@ -37,7 +37,8 @@ Prints a brief help message to the console. .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 ports. +to be passed to the controller before being sent out all but the +incoming port. .TP .BR \-v ", " \-\^\-verbose @@ -50,7 +51,7 @@ Prints version information to the console. .SH EXAMPLES .TP -To connect directly to local datapath 0 over Netlink (Linux only): +To connect directly to local datapath 0 over netlink (Linux only): .B % controller nl:0 @@ -62,6 +63,7 @@ To bind locally to port 975 (the default) and wait for incoming connections from .SH "SEE ALSO" .BR dpctl (8), +.BR switch (8), .BR secchan (8) .BR vlogconf (8) diff --git a/man/man8/dpctl.8 b/man/man8/dpctl.8 index 5c11a1f5..3456339a 100644 --- a/man/man8/dpctl.8 +++ b/man/man8/dpctl.8 @@ -1,25 +1,22 @@ -.TH dpctl 8 "December 2007" "OpenFlow" "OpenFlow Manual" +.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME dpctl \- command line tool to administer OpenFlow datapaths .SH SYNOPSIS .B dpctl -[OPTIONS] COMMAND [ARGS...] +[OPTIONS] COMMAND [SWITCH] [ARGS...] .SH DESCRIPTION The .B dpctl -program is a command line tool through which OpenFlow datapaths on the -local host 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. +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. -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. .SH OPTIONS .TP @@ -35,26 +32,43 @@ Prints debug messages to the console. 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 " DP_IDX" -Creates datapath numbered \fIDP_IDX\fR on the local host. 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. +.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 " DP_IDX" +.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 show " DP_IDX" -Prints to the console information on datapath \fIDP_IDX\fR including -information on its flow tables and ports. - -.TP -.BI addif " DP_IDX INTERFACE" +.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 @@ -63,86 +77,114 @@ 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 " DP_IDX INTERFACE" +.BI delif " nl:DP_IDX INTERFACE" Removes \fIINTERFACE\fR from the list of network interfaces datapath \fIDP_IDX\fR monitors. .TP -.BI monitor " DP_IDX" +.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 dump-tables " DP_IDX" +.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 \fIDP_IDX\fR, where \fIDP_IDX\fR is the ID of an existing -datapath. +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 " DP_IDX TABLE_ID" -Prints to the console all flow entries in datapath \fIDP_IDX\fR's table -\fITABLE_ID\fR, where \fIDP_IDX\fR is the ID of an existing datapath, -and \fITABLE_ID\fR is the integer ID of one of the datapath's tables -as displayed in the output produced by \fBdump-tables\fR. +.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 " DP_IDX [FLOWS]" +.BI dump-aggregate " SWITCH [FLOWS]" Prints to the console aggregate statistics for flows in datapath -\fIDP_IDX\fR's that match \fIFLOWS\fR. If \fIFLOWS\fR is omitted, the -statistics are aggregated across all flows in the datapath's flow +\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: +A typical dpctl command sequence for controlling an OpenFlow kernel module: .nf .TP Create datapath numbered 0: -.B % dpctl adddp 0 +.B % dpctl adddp nl:0 .TP Add two interfaces to the new datapath: -.B % dpctl addif 0 eth0 -.B % dpctl addif 0 eth1 +.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 0 +.B % dpctl monitor nl:0 .TP View the datapath's table stats after some traffic has passed through: -.B % dpctl dump-tables 0 +.B % dpctl dump-tables nl:0 .TP -View the flow entries in one of the datapath's tables (shown is the command for the table 1). (This assumes that there is running controller adding flows to the flowtables) +View the flow entries in the datapath: -.B % dpctl dump-flows 0 1 +.B % dpctl dump-flows nl:0 .TP -Remote interfaces from the datapath when finished: +Remove interfaces from the datapath when finished: -.B % dpctl delif 0 eth0 -.B % dpctl delif 0 eth1 +.B % dpctl delif nl:0 eth0 +.B % dpctl delif nl:0 eth1 .TP Delete the datapath: -.B % dpctl deldp 0 +.B % dpctl deldp nl:0 .fi .SH "SEE ALSO" .BR secchan (8), +.BR switch (8) .BR controller (8) .BR vlogconf (8) - -.SH BUGS - -dump-flows currently only prints the first action of each flow. This is -a shortcoming in the modules netlink flow query functionality and will -be addressed in future releases diff --git a/man/man8/ofp-pki.8 b/man/man8/ofp-pki.8 index 47c164ad..75ce3a07 100644 --- a/man/man8/ofp-pki.8 +++ b/man/man8/ofp-pki.8 @@ -1,4 +1,4 @@ -.TH ofp-pki 8 "March 2008" "OpenFlow" "OpenFlow Manual" +.TH ofp-pki 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME ofp\-pki \- OpenFlow public key infrastructure management utility @@ -140,5 +140,6 @@ 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 index b1eac3a9..2f73dc06 100644 --- a/man/man8/secchan.8 +++ b/man/man8/secchan.8 @@ -1,4 +1,4 @@ -.TH secchan 8 "December 2007" "OpenFlow" "OpenFlow Manual" +.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME secchan \- secure channel connecting an OpenFlow datapath to a controller @@ -35,6 +35,7 @@ Prints version information to the console. .SH "SEE ALSO" .BR dpctl (8), +.BR switch (8), .BR controller (8) .BR vlogconf (8) diff --git a/man/man8/switch.8 b/man/man8/switch.8 index 51638a36..c0811494 100644 --- a/man/man8/switch.8 +++ b/man/man8/switch.8 @@ -1,4 +1,4 @@ -.TH secchan 8 "March 2008" "OpenFlow" "OpenFlow Manual" +.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME switch \- userspace implementation of OpenFlow switch @@ -53,7 +53,7 @@ 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 consist of exactly 12 +identifies a controller) as \fIdpid\fR, which consists of exactly 12 hex digits. Without this option, \fBswitch\fR picks an ID randomly. .TP @@ -87,8 +87,6 @@ Prints version information to the console. .SH "SEE ALSO" .BR dpctl (8), +.BR ofp-pki (8), .BR controller (8) .BR vlogconf (8) - -.SH BUGS -Currently \fBsecchan\fR does not support SSL -- 2.30.2