From: Ben Pfaff Date: Thu, 23 Oct 2008 21:03:44 +0000 (-0700) Subject: Update manpages to mention new --log-file option. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9795d7d750d84e2fdc86a6c737f2bf07f0efef80;p=openvswitch Update manpages to mention new --log-file option. Move vlog option descriptions into a separate file lib/vlog.man that is substituted into manpages. Get rid of individual rules for substituting most files in favor of a single suffix rule. Unfortunately this loses the (Emacs-specific) read-only markings but it simplifies the makefiles. --- diff --git a/Makefile.am b/Makefile.am index bb69db7a..8634a218 100644 --- a/Makefile.am +++ b/Makefile.am @@ -27,6 +27,7 @@ else AM_LDFLAGS = -export-dynamic endif +CLEANFILES = DISTCLEANFILES = EXTRA_DIST = TESTS = @@ -40,14 +41,18 @@ noinst_LIBRARIES = noinst_PROGRAMS = noinst_SCRIPTS = -do_subst = sed -e 's,[@]PKIDIR[@],$(PKIDIR),g' \ - -e 's,[@]RUNDIR[@],$(RUNDIR),g' \ - -e 's,[@]PERL[@],$(PERL),g' +EXTRA_DIST += README.hwtables + +do_subst = ($(srcdir)/subst VLOG_OPTIONS $(srcdir)/lib/vlog.man | \ + sed -e 's,[@]PKIDIR[@],$(PKIDIR),g' \ + -e 's,[@]RUNDIR[@],$(RUNDIR),g' \ + -e 's,[@]PERL[@],$(PERL),g') ro_script = sed "`printf '1a\\' && printf '\\n\# -*- buffer-read-only: t -*-'`" -ro_man = printf '.\\" Local\040variables:\n.\\" buffer-read-only: t\n.\\" End:\n' ro_c = echo '/* -*- mode: c; buffer-read-only: t -*- */' -EXTRA_DIST += README.hwtables +SUFFIXES = .in +.in: + $(do_subst) < $< > $@ include lib/automake.mk include secchan/automake.mk diff --git a/controller/automake.mk b/controller/automake.mk index b6c2291a..ff9f627c 100644 --- a/controller/automake.mk +++ b/controller/automake.mk @@ -6,7 +6,3 @@ controller_controller_SOURCES = controller/controller.c controller_controller_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS) EXTRA_DIST += controller/controller.8.in -controller/controller.8: controller/controller.8.in Makefile - ($(do_subst) && $(ro_man)) \ - < $(srcdir)/controller/controller.8.in \ - > controller/controller.8 diff --git a/controller/controller.8.in b/controller/controller.8.in index f7f265c3..b608c939 100644 --- a/controller/controller.8.in +++ b/controller/controller.8.in @@ -150,29 +150,7 @@ run as a background process. .BR \-h ", " \-\^\-help Prints a brief help message to the console. -.TP -\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\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 facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \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. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to -\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. +@VLOG_OPTIONS@ .TP .BR \-V ", " \-\^\-version diff --git a/debian/openflow-common.manpages b/debian/openflow-common.manpages index ee20d1ea..fbb88201 100644 --- a/debian/openflow-common.manpages +++ b/debian/openflow-common.manpages @@ -1,2 +1,2 @@ -utilities/vlogconf.8 +_debian/utilities/vlogconf.8 _debian/utilities/ofp-pki.8 diff --git a/debian/openflow-switch.manpages b/debian/openflow-switch.manpages index b012d8db..e50d9978 100644 --- a/debian/openflow-switch.manpages +++ b/debian/openflow-switch.manpages @@ -3,4 +3,4 @@ _debian/secchan/secchan.8 _debian/switch/switch.8 _debian/utilities/ofp-discover.8 _debian/utilities/ofp-kill.8 -utilities/dpctl.8 +_debian/utilities/dpctl.8 diff --git a/lib/automake.mk b/lib/automake.mk index 1d0f8fab..7b4da911 100644 --- a/lib/automake.mk +++ b/lib/automake.mk @@ -60,6 +60,7 @@ EXTRA_DIST += \ lib/dh4096.pem \ lib/dhparams.h +CLEANFILES += lib/dirs.c lib/dirs.c: Makefile ($(ro_c) && \ echo 'const char ofp_rundir[] = "@RUNDIR@";' && \ diff --git a/lib/vlog.man b/lib/vlog.man new file mode 100644 index 00000000..6bc7d298 --- /dev/null +++ b/lib/vlog.man @@ -0,0 +1,45 @@ +.TP +\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] + +Sets the logging level for \fImodule\fR in \fIfacility\fR to +\fIlevel\fR: + +.RS +.IP \(bu +\fImodule\fR may be any valid module name (as displayed by the +\fB--list\fR action on \fBvlogconf\fR(8)), or the special name +\fBANY\fR to set the logging levels for all modules. + +.IP \(bu +\fIfacility\fR may be \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR to +set the levels for logging to the system log, the console, or a file +respectively, or \fBANY\fR to set the logging levels for both +facilities. If it is omitted, \fIfacility\fR defaults to \fBANY\fR. + +Regardless of the log levels set for \fBfile\fR, logging to a file +will not take place unless \fB--log-file\fR is also specified (see +below). + +.IP \(bu +\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. If it is omitted, \fIlevel\fR defaults to \fBdbg\fR. +.RE + +.TP +\fB-v\fR, \fB--verbose\fR +Sets the maximum logging verbosity level, equivalent to +\fB--verbose=ANY:ANY:dbg\fR. + +.TP +\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR +Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to +\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. + +.TP +\fB--log-file\fR[\fB=\fIfile\fR] +Enables logging to a file. If \fIfile\fR is specified, then it is +used as the exact name for the log file. The default log file name +used if \fIfile\fR is omitted is @LOGDIR@/\fIprogram\fR.log, where +\fIprogram\fR is the name of the program as invoked +(e.g. \fBsecchan\fR). diff --git a/secchan/automake.mk b/secchan/automake.mk index 3c57d7f8..fb4662d0 100644 --- a/secchan/automake.mk +++ b/secchan/automake.mk @@ -6,6 +6,3 @@ secchan_secchan_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS) EXTRA_DIST += secchan/secchan.8.in DISTCLEANFILES += secchan/secchan.8 -secchan/secchan.8: secchan/secchan.8.in Makefile - ($(do_subst) && $(ro_man)) \ - < $(srcdir)/secchan/secchan.8.in > secchan/secchan.8 diff --git a/secchan/secchan.8.in b/secchan/secchan.8.in index d7dd9b81..cc14d61e 100644 --- a/secchan/secchan.8.in +++ b/secchan/secchan.8.in @@ -422,29 +422,7 @@ run as a background process. .BR \-h ", " \-\^\-help Prints a brief help message to the console. -.TP -\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\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 facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \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. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to -\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. +@VLOG_OPTIONS@ .TP .BR \-V ", " \-\^\-version diff --git a/subst b/subst new file mode 100755 index 00000000..c2e71df8 --- /dev/null +++ b/subst @@ -0,0 +1,5 @@ +#! /bin/sh +exec sed -e "/^@$1@\$/{ +r $2 +d +}" diff --git a/switch/automake.mk b/switch/automake.mk index 58e13c9d..d9826f4c 100644 --- a/switch/automake.mk +++ b/switch/automake.mk @@ -23,6 +23,3 @@ switch_switch_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS) EXTRA_DIST += switch/switch.8.in DISTCLEANFILES += switch/switch.8 -switch/switch.8: switch/switch.8.in Makefile - ($(do_subst) && $(ro_man)) \ - < $(srcdir)/switch/switch.8.in > switch/switch.8 diff --git a/switch/switch.8.in b/switch/switch.8.in index 4b3584e9..c6aa6060 100644 --- a/switch/switch.8.in +++ b/switch/switch.8.in @@ -110,29 +110,7 @@ run as a background process. .BR \-h ", " \-\^\-help Prints a brief help message to the console. -.TP -\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\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 facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \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. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to -\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. +@VLOG_OPTIONS@ .TP .BR \-V ", " \-\^\-version diff --git a/utilities/automake.mk b/utilities/automake.mk index e359d5fa..f9ce28d6 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -7,25 +7,28 @@ bin_SCRIPTS += utilities/ofp-pki noinst_SCRIPTS += utilities/ofp-pki-cgi EXTRA_DIST += \ + utilities/dpctl.8.in \ utilities/ofp-discover.8.in \ utilities/ofp-kill.8.in \ utilities/ofp-pki-cgi.in \ utilities/ofp-pki.8.in \ - utilities/ofp-pki.in + utilities/ofp-pki.in \ + utilities/vlogconf.8.in DISTCLEANFILES += \ + utilities/dpctl.8 \ utilities/ofp-discover.8 \ utilities/ofp-kill.8 \ utilities/ofp-pki \ + utilities/ofp-pki.8 \ utilities/ofp-pki-cgi \ - utilities/ofp-pki.8 + utilities/vlogconf.8 -dist_man_MANS += \ - utilities/vlogconf.8 \ - utilities/dpctl.8 man_MANS += \ - utilities/ofp-pki.8 \ + utilities/dpctl.8 \ utilities/ofp-discover.8 \ - utilities/ofp-kill.8 + utilities/ofp-kill.8 \ + utilities/ofp-pki.8 \ + utilities/vlogconf.8 utilities_dpctl_SOURCES = utilities/dpctl.c utilities_dpctl_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS) @@ -38,21 +41,3 @@ utilities_ofp_discover_LDADD = lib/libopenflow.a utilities_ofp_kill_SOURCES = utilities/ofp-kill.c utilities_ofp_kill_LDADD = lib/libopenflow.a - -utilities/ofp-pki: utilities/ofp-pki.in Makefile - $(do_subst) < $(srcdir)/utilities/ofp-pki.in \ - | $(ro_script) > utilities/ofp-pki - chmod +x utilities/ofp-pki -utilities/ofp-pki-cgi: utilities/ofp-pki-cgi.in Makefile - $(do_subst) < $(srcdir)/utilities/ofp-pki-cgi.in \ - | $(ro_script) > utilities/ofp-pki-cgi - chmod +x utilities/ofp-pki-cgi -utilities/ofp-pki.8: utilities/ofp-pki.8.in Makefile - ($(do_subst) && $(ro_man)) \ - < $(srcdir)/utilities/ofp-pki.8.in > utilities/ofp-pki.8 -utilities/ofp-discover.8: utilities/ofp-discover.8.in Makefile - ($(do_subst) && $(ro_man)) < $(srcdir)/utilities/ofp-discover.8.in \ - > utilities/ofp-discover.8 -utilities/ofp-kill.8: utilities/ofp-kill.8.in Makefile - ($(do_subst) && $(ro_man)) < $(srcdir)/utilities/ofp-kill.8.in \ - > utilities/ofp-kill.8 diff --git a/utilities/dpctl.8 b/utilities/dpctl.8 deleted file mode 100644 index c7805932..00000000 --- a/utilities/dpctl.8 +++ /dev/null @@ -1,507 +0,0 @@ -.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -dpctl \- administer OpenFlow datapaths - -.SH SYNOPSIS -.B dpctl -[\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR&...] - -.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. - -Most \fBdpctl\fR commands take an argument that specifies the -method for connecting to an OpenFlow switch. The following connection -methods are supported: - -.TP -\fBnl:\fIdp_idx\fR -The local Netlink datapath numbered \fIdp_idx\fR. This form requires -that the local host has the OpenFlow kernel module for Linux loaded. - -.TP -\fBssl:\fIhost\fR[\fB:\fIport\fR] -The specified SSL \fIport\fR (default: 6633) 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. - -.TP -\fBtcp:\fIhost\fR[\fB:\fIport\fR] -The specified TCP \fIport\fR (default: 6633) on the given remote -\fIhost\fR. - -.TP -\fBunix:\fIfile\fR -The Unix domain server socket named \fIfile\fR. - -.SH COMMANDS - -With the \fBdpctl\fR program, datapaths running in the kernel can be -created, deleted, and modified. 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 devices thus does not process any incoming -traffic. To intercept and process traffic on a given network device, the -network device must be explicitly added to a datapath through the -\fBaddif\fR command. - -The following commands manage local datapaths. - -.TP -\fBadddp nl:\fIdp_idx\fR -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 -\fBdeldp nl:\fIdp_idx\fR -Deletes datapath \fIdp_idx\fR on the local host. \fIdp_idx\fR must be -an existing datapath. All of a datapath's network devices must be -explicitly removed before the datapath can be deleted (see \fBdelif\fR -command). - -.TP -\fBaddif nl:\fIdp_idx netdev\fR... -Adds each \fInetdev\fR to the list of network devices datapath -\fIdp_idx\fR monitors, where \fIdp_idx\fR is the ID of an existing -datapath, and \fInetdev\fR is the name of one of the host's -network devices, e.g. \fBeth0\fR. Once a network device has been added -to a datapath, the datapath has complete ownership of the network device's -traffic and the network device appears silent to the rest of the system. - -.TP -\fBdelif nl:\fIdp_idx netdev\fR... -Removes each \fInetdev\fR from the list of network devices datapath -\fIdp_idx\fR monitors. - -.PP -The following commands can be apply to OpenFlow switches regardless of -the connection method. - -.TP -\fBshow \fIswitch\fR -Prints to the console information on datapath \fIswitch\fR including -information on its flow tables and ports. - -.TP -\fBstatus \fIswitch\fR [\fIkey\fR] -Prints to the console a series of key-value pairs that report the -status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value -pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is -omitted, all key-value pairs are printed. - -(In the OpenFlow reference implementation, the \fBstatus\fR command is -implemented in \fBsecchan\fR(8), not in the kernel module, so the -\fBnl:\fIdp_idx\fR connection method should not be used with this -command. Instead, specify \fB-l\fR or \fB--listen\fR on the -\fBsecchan\fR command line and tell \fBdpctl\fR to use the connection -method specified there.) - -.TP -\fBdump-tables \fIswitch\fR -Prints to the console statistics for each of the flow tables used by -datapath \fIswitch\fR. - -.TP -\fBdump-ports \fIswitch\fR -Prints to the console statistics for each of the network devices -associated with datapath \fIswitch\fR. - -.TP -\fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR -Modify characteristics of an interface monitored by \fIswitch\fR. -\fInetdev\fR can be referred to by its OpenFlow assigned port number or -the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the -following: - -.RS -.IP \fBup\fR -Enables the interface. This is equivalent to ``ifconfig up'' on a Unix -system. - -.IP \fBdown\fR -Disables the interface. This is equivalent to ``ifconfig down'' on a Unix -system. - -.IP \fBflood\fR -When a \fIflood\fR action is specified, traffic will be sent out this -interface. This is the default posture for monitored ports. - -.IP \fBnoflood\fR -When a \fIflood\fR action is specified, traffic will not be sent out -this interface. This is primarily useful to prevent loops when a -spanning tree protocol is not in use. - -.RE - -.TP -\fBdump-flows \fIswitch \fR[\fIflows\fR] -Prints to the console all flow entries in datapath \fIswitch\fR's -tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows -in the datapath are retrieved. See \fBFLOW SYNTAX\fR, below, for the -syntax of \fIflows\fR. - -.TP -\fBdump-aggregate \fIswitch \fR[\fIflows\fR] -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. See \fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR. - -.TP -\fBadd-flow \fIswitch flow\fR -Add the flow entry as described by \fIflow\fR to the datapath \fIswitch\fR's -tables. The flow entry is in the format described in \fBFLOW SYNTAX\fR, -below. - -.TP -\fBadd-flows \fIswitch file\fR -Add flow entries as described in \fIfile\fR to the datapath \fIswitch\fR's -tables. Each line in \fIfile\fR is a flow entry in the format -described in \fBFLOW SYNTAX\fR, below. - -.TP -\fBmod-flows \fIswitch flow\fR -Modify the actions in entries from the datapath \fIswitch\fR's tables -that match \fIflow\fR. When invoked with the \fB--strict\fR option, -wildcards are not treated as active for matching purposes. See -\fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR. - -.TP -\fBdel-flows \fIswitch \fR[\fIflow\fR] -Deletes entries from the datapath \fIswitch\fR's tables that match -\fIflow\fR. When invoked with the \fB--strict\fR option, wildcards are -not treated as active for matching purposes. If \fIflow\fR is -omitted and the \fB--strict\fR option is not used, all flows in the -datapath's tables are removed. See \fBFLOW SYNTAX\fR, below, for the -syntax of \fIflows\fR. - -.TP -\fBmonitor \fIswitch\fR -Connects to \fIswitch\fR and prints to the console all OpenFlow -messages received. Usually, \fIswitch\fR should specify a connection -named on \fBsecchan\fR(8)'s \fB-m\fR or \fB--monitor\fR command line -option, in which the messages printed will be all those sent or -received by \fBsecchan\fR to or from the kernel datapath module. A -\fIswitch\fR of the form \fBnl:\fIdp_idx\fR will print all -asynchronously generated OpenFlow messages (such as packet-in -messages), but it will not print any messages sent to the kernel by -\fBsecchan\fR and other processes, nor will it print replies sent by -the kernel in response to those messages. - -.PP -The following commands can be used regardless of the connection -method. They apply to OpenFlow switches and controllers. - -.TP -\fBprobe \fIvconn\fR -Connects to \fIvconn\fR and sends a single OpenFlow echo-request -packet and waits for the response. With the \fB-t\fR or -\fB--timeout\fR option, this command can test whether an OpenFlow -switch or controller is up and running. - -.TP -\fBping \fIvconn \fR[\fIn\fR] -Sends a series of 10 echo request packets to \fIvconn\fR and times -each reply. The echo request packets consist of an OpenFlow header -plus \fIn\fR bytes (default: 64) of randomly generated payload. This -measures the latency of individual requests. - -.TP -\fBbenchmark \fIvconn n count\fR -Sends \fIcount\fR echo request packets that each consist of an -OpenFlow header plus \fIn\fR bytes of payload and waits for each -response. Reports the total time required. This is a measure of the -maximum bandwidth to \fIvconn\fR for round-trips of \fIn\fR-byte -messages. - -.SH "FLOW SYNTAX" - -Some \fBdpctl\fR commands accept an argument that describes a flow or -flows. Such flow descriptions comprise a series -\fIfield\fB=\fIvalue\fR assignments, separated by commas or white -space. - -The following field assignments describe how a flow matches a packet. -If any of these assignments is omitted from the flow syntax, the field -is treated as a wildcard; thus, if all of them are omitted, the -resulting flow matches all packets. The string \fB*\fR or \fBANY\fR -may be specified a value to explicitly mark any of these fields as a -wildcard. - -.IP \fBin_port=\fIport_no\fR -Matches physical port \fIport_no\fR. Switch ports are numbered as -displayed by \fBdpctl show\fR. - -.IP \fBdl_vlan=\fIvlan\fR -Matches IEEE 802.1q virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR -as \fIvlan\fR to match packets that are not tagged with a virtual LAN; -otherwise, specify a number between 0 and 4095, inclusive, as the -12-bit VLAN ID to match. - -.IP \fBdl_src=\fImac\fR -Matches Ethernet source address \fImac\fR, which should be specified -as 6 pairs of hexadecimal digits delimited by colons, -e.g. \fB00:0A:E4:25:6B:B0\fR. - -.IP \fBdl_dst=\fImac\fR -Matches Ethernet destination address \fImac\fR. - -.IP \fBdl_type=\fIethertype\fR -Matches Ethernet protocol type \fIethertype\fR, which should be -specified as a integer between 0 and 65535, inclusive, either in -decimal or as a hexadecimal number prefixed by \fB0x\fR, -e.g. \fB0x0806\fR to match ARP packets. - -.IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR] -Matches IPv4 source address \fIip\fR, which should be specified as an -IP address or host name, e.g. \fB192.168.1.1\fR or -\fBwww.example.com\fR. The optional \fInetmask\fR allows matching -only on an IPv4 address prefix. It may be specified as a dotted quad -(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a count of bits -(e.g. \fB192.168.1.0/24\fR). - -.IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR] -Matches IPv4 destination address \fIip\fR. - -.IP \fBnw_proto=\fIproto\fR -Matches IP protocol type \fIproto\fR, which should be specified as a -decimal number between 0 and 255, inclusive, e.g. 6 to match TCP -packets. - -.IP \fBtp_src=\fIport\fR -Matches UDP or TCP source port \fIport\fR, which should be specified -as a decimal number between 0 and 65535, inclusive, e.g. 80 to match -packets originating from a HTTP server. - -.IP \fBtp_dst=\fIport\fR -Matches UDP or TCP destination port \fIport\fR. - -.PP -The following shorthand notations are also available: - -.IP \fBip\fR -Same as \fBdl_type=0x0800\fR. - -.IP \fBicmp\fR -Same as \fBdl_type=0x0800,nw_proto=1\fR. - -.IP \fBtcp\fR -Same as \fBdl_type=0x0800,nw_proto=6\fR. - -.IP \fBudp\fR -Same as \fBdl_type=0x0800,nw_proto=17\fR. - -.IP \fBarp\fR -Same as \fBdl_type=0x0806\fR. - -.PP -The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field: - -.IP \fIactions\fB=\fItarget\fR[\fB,\fItarget\fR...]\fR -Specifies a comma-separated list of actions to take on a packet when the -flow entry matches. The \fItarget\fR may be a decimal port number -designating the physical port on which to output the packet, or one of -the following keywords: - -.RS -.IP \fBoutput\fR:\fIport\fR -Outputs the packet on the port specified by \fIport\fR. - -.IP \fBnormal\fR -Subjects the packet to the device's normal L2/L3 processing. (This -action is not implemented by all OpenFlow switches.) - -.IP \fBflood\fR -Outputs the packet on all switch physical ports other than the port on -which it was received and any ports on which flooding is disabled -(typically, these would be ports disabled by the IEEE 802.1D spanning -tree protocol). - -.IP \fBall\fR -Outputs the packet on all switch physical ports other than the port on -which it was received. - -.IP \fBcontroller\fR:\fImax_len\fR -Sends the packet to the OpenFlow controller as a ``packet in'' -message. If \fImax_len\fR is a number, then it specifies the maximum -number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or -omitted, then the entire packet is sent. - -.IP \fBlocal\fR -Outputs the packet on the ``local port,'' which corresponds to the -\fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in -\fBsecchan\fR(8) for information on the \fBof\fIn\fR network device). - -.IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR -Modifies the VLAN id on a packet. The VLAN tag is added or modified -as necessary to match the value specified. If the VLAN tag is added, -a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set -this). - -.IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR -Modifies the VLAN priority on a packet. The VLAN tag is added or modified -as necessary to match the value specified. Valid values are between 0 -(lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used -(see the \fBmod_vlan_vid\fR action to set this). - -.IP \fBstrip_vlan\fR -Strips the VLAN tag from a packet if it is present. -.RE - -.IP -(The OpenFlow protocol supports other actions that \fBdpctl\fR does -not yet expose to the user.) - -.PP -The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands -support an additional optional field: - -.IP \fBpriority=\fIvalue\fR -Sets the priority of the flow to be added or deleted to \fIvalue\fR, -which should be a number between 0 and 65535, inclusive. If this -field is not specified, it defaults to 32768. - -.PP -The \fBadd-flow\fR and \fBadd-flows\fR commands support additional -optional fields: - -.TP -\fBidle_timeout=\fIseconds\fR -Causes the flow to expire after the given number of seconds of -inactivity. A value of 0 prevents a flow from expiring due to -inactivity. The default is 60 seconds. - -.IP \fBhard_timeout=\fIseconds\fR -Causes the flow to expire after the given number of seconds, -regardless of activity. A value of 0 (the default) gives the flow no -hard expiration deadline. - -.PP -The \fBdump-flows\fR and \fBdump-aggregate\fR commands support an -additional optional field: - -.IP \fBtable=\fInumber\fR -If specified, limits the flows about which statistics are gathered to -those in the table with the given \fInumber\fR. Tables are numbered -as shown by the \fBdump-tables\fR command. - -If this field is not specified, or if \fInumber\fR is given as -\fB255\fR, statistics are gathered about flows from all tables. - -.SH OPTIONS -.TP -\fB--strict\fR -Uses strict matching when running flow modification commands. - -.TP -\fB-t\fR, \fB--timeout=\fIsecs\fR -Limits \fBdpctl\fR runtime to approximately \fIsecs\fR seconds. If -the timeout expires, \fBdpctl\fR will exit with a \fBSIGALRM\fR -signal. - -.TP -\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR -Specifies a PEM file containing the private key used as the -identity for SSL connections to a switch. - -.TP -\fB-c\fR, \fB--certificate=\fIcert.pem\fR -Specifies a PEM file containing a certificate, signed by the -controller's certificate authority (CA), that certifies the -private key to identify a trustworthy controller. - -.TP -\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR -Specifies a PEM file containing the CA certificate used to verify that -a switch is trustworthy. - -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\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 facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \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. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to -\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. - -.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 network devices 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 network devices 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/dpctl.8.in b/utilities/dpctl.8.in new file mode 100644 index 00000000..2ab5f327 --- /dev/null +++ b/utilities/dpctl.8.in @@ -0,0 +1,485 @@ +.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +dpctl \- administer OpenFlow datapaths + +.SH SYNOPSIS +.B dpctl +[\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR&...] + +.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. + +Most \fBdpctl\fR commands take an argument that specifies the +method for connecting to an OpenFlow switch. The following connection +methods are supported: + +.TP +\fBnl:\fIdp_idx\fR +The local Netlink datapath numbered \fIdp_idx\fR. This form requires +that the local host has the OpenFlow kernel module for Linux loaded. + +.TP +\fBssl:\fIhost\fR[\fB:\fIport\fR] +The specified SSL \fIport\fR (default: 6633) 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. + +.TP +\fBtcp:\fIhost\fR[\fB:\fIport\fR] +The specified TCP \fIport\fR (default: 6633) on the given remote +\fIhost\fR. + +.TP +\fBunix:\fIfile\fR +The Unix domain server socket named \fIfile\fR. + +.SH COMMANDS + +With the \fBdpctl\fR program, datapaths running in the kernel can be +created, deleted, and modified. 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 devices thus does not process any incoming +traffic. To intercept and process traffic on a given network device, the +network device must be explicitly added to a datapath through the +\fBaddif\fR command. + +The following commands manage local datapaths. + +.TP +\fBadddp nl:\fIdp_idx\fR +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 +\fBdeldp nl:\fIdp_idx\fR +Deletes datapath \fIdp_idx\fR on the local host. \fIdp_idx\fR must be +an existing datapath. All of a datapath's network devices must be +explicitly removed before the datapath can be deleted (see \fBdelif\fR +command). + +.TP +\fBaddif nl:\fIdp_idx netdev\fR... +Adds each \fInetdev\fR to the list of network devices datapath +\fIdp_idx\fR monitors, where \fIdp_idx\fR is the ID of an existing +datapath, and \fInetdev\fR is the name of one of the host's +network devices, e.g. \fBeth0\fR. Once a network device has been added +to a datapath, the datapath has complete ownership of the network device's +traffic and the network device appears silent to the rest of the system. + +.TP +\fBdelif nl:\fIdp_idx netdev\fR... +Removes each \fInetdev\fR from the list of network devices datapath +\fIdp_idx\fR monitors. + +.PP +The following commands can be apply to OpenFlow switches regardless of +the connection method. + +.TP +\fBshow \fIswitch\fR +Prints to the console information on datapath \fIswitch\fR including +information on its flow tables and ports. + +.TP +\fBstatus \fIswitch\fR [\fIkey\fR] +Prints to the console a series of key-value pairs that report the +status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value +pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is +omitted, all key-value pairs are printed. + +(In the OpenFlow reference implementation, the \fBstatus\fR command is +implemented in \fBsecchan\fR(8), not in the kernel module, so the +\fBnl:\fIdp_idx\fR connection method should not be used with this +command. Instead, specify \fB-l\fR or \fB--listen\fR on the +\fBsecchan\fR command line and tell \fBdpctl\fR to use the connection +method specified there.) + +.TP +\fBdump-tables \fIswitch\fR +Prints to the console statistics for each of the flow tables used by +datapath \fIswitch\fR. + +.TP +\fBdump-ports \fIswitch\fR +Prints to the console statistics for each of the network devices +associated with datapath \fIswitch\fR. + +.TP +\fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR +Modify characteristics of an interface monitored by \fIswitch\fR. +\fInetdev\fR can be referred to by its OpenFlow assigned port number or +the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the +following: + +.RS +.IP \fBup\fR +Enables the interface. This is equivalent to ``ifconfig up'' on a Unix +system. + +.IP \fBdown\fR +Disables the interface. This is equivalent to ``ifconfig down'' on a Unix +system. + +.IP \fBflood\fR +When a \fIflood\fR action is specified, traffic will be sent out this +interface. This is the default posture for monitored ports. + +.IP \fBnoflood\fR +When a \fIflood\fR action is specified, traffic will not be sent out +this interface. This is primarily useful to prevent loops when a +spanning tree protocol is not in use. + +.RE + +.TP +\fBdump-flows \fIswitch \fR[\fIflows\fR] +Prints to the console all flow entries in datapath \fIswitch\fR's +tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows +in the datapath are retrieved. See \fBFLOW SYNTAX\fR, below, for the +syntax of \fIflows\fR. + +.TP +\fBdump-aggregate \fIswitch \fR[\fIflows\fR] +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. See \fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR. + +.TP +\fBadd-flow \fIswitch flow\fR +Add the flow entry as described by \fIflow\fR to the datapath \fIswitch\fR's +tables. The flow entry is in the format described in \fBFLOW SYNTAX\fR, +below. + +.TP +\fBadd-flows \fIswitch file\fR +Add flow entries as described in \fIfile\fR to the datapath \fIswitch\fR's +tables. Each line in \fIfile\fR is a flow entry in the format +described in \fBFLOW SYNTAX\fR, below. + +.TP +\fBmod-flows \fIswitch flow\fR +Modify the actions in entries from the datapath \fIswitch\fR's tables +that match \fIflow\fR. When invoked with the \fB--strict\fR option, +wildcards are not treated as active for matching purposes. See +\fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR. + +.TP +\fBdel-flows \fIswitch \fR[\fIflow\fR] +Deletes entries from the datapath \fIswitch\fR's tables that match +\fIflow\fR. When invoked with the \fB--strict\fR option, wildcards are +not treated as active for matching purposes. If \fIflow\fR is +omitted and the \fB--strict\fR option is not used, all flows in the +datapath's tables are removed. See \fBFLOW SYNTAX\fR, below, for the +syntax of \fIflows\fR. + +.TP +\fBmonitor \fIswitch\fR +Connects to \fIswitch\fR and prints to the console all OpenFlow +messages received. Usually, \fIswitch\fR should specify a connection +named on \fBsecchan\fR(8)'s \fB-m\fR or \fB--monitor\fR command line +option, in which the messages printed will be all those sent or +received by \fBsecchan\fR to or from the kernel datapath module. A +\fIswitch\fR of the form \fBnl:\fIdp_idx\fR will print all +asynchronously generated OpenFlow messages (such as packet-in +messages), but it will not print any messages sent to the kernel by +\fBsecchan\fR and other processes, nor will it print replies sent by +the kernel in response to those messages. + +.PP +The following commands can be used regardless of the connection +method. They apply to OpenFlow switches and controllers. + +.TP +\fBprobe \fIvconn\fR +Connects to \fIvconn\fR and sends a single OpenFlow echo-request +packet and waits for the response. With the \fB-t\fR or +\fB--timeout\fR option, this command can test whether an OpenFlow +switch or controller is up and running. + +.TP +\fBping \fIvconn \fR[\fIn\fR] +Sends a series of 10 echo request packets to \fIvconn\fR and times +each reply. The echo request packets consist of an OpenFlow header +plus \fIn\fR bytes (default: 64) of randomly generated payload. This +measures the latency of individual requests. + +.TP +\fBbenchmark \fIvconn n count\fR +Sends \fIcount\fR echo request packets that each consist of an +OpenFlow header plus \fIn\fR bytes of payload and waits for each +response. Reports the total time required. This is a measure of the +maximum bandwidth to \fIvconn\fR for round-trips of \fIn\fR-byte +messages. + +.SH "FLOW SYNTAX" + +Some \fBdpctl\fR commands accept an argument that describes a flow or +flows. Such flow descriptions comprise a series +\fIfield\fB=\fIvalue\fR assignments, separated by commas or white +space. + +The following field assignments describe how a flow matches a packet. +If any of these assignments is omitted from the flow syntax, the field +is treated as a wildcard; thus, if all of them are omitted, the +resulting flow matches all packets. The string \fB*\fR or \fBANY\fR +may be specified a value to explicitly mark any of these fields as a +wildcard. + +.IP \fBin_port=\fIport_no\fR +Matches physical port \fIport_no\fR. Switch ports are numbered as +displayed by \fBdpctl show\fR. + +.IP \fBdl_vlan=\fIvlan\fR +Matches IEEE 802.1q virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR +as \fIvlan\fR to match packets that are not tagged with a virtual LAN; +otherwise, specify a number between 0 and 4095, inclusive, as the +12-bit VLAN ID to match. + +.IP \fBdl_src=\fImac\fR +Matches Ethernet source address \fImac\fR, which should be specified +as 6 pairs of hexadecimal digits delimited by colons, +e.g. \fB00:0A:E4:25:6B:B0\fR. + +.IP \fBdl_dst=\fImac\fR +Matches Ethernet destination address \fImac\fR. + +.IP \fBdl_type=\fIethertype\fR +Matches Ethernet protocol type \fIethertype\fR, which should be +specified as a integer between 0 and 65535, inclusive, either in +decimal or as a hexadecimal number prefixed by \fB0x\fR, +e.g. \fB0x0806\fR to match ARP packets. + +.IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR] +Matches IPv4 source address \fIip\fR, which should be specified as an +IP address or host name, e.g. \fB192.168.1.1\fR or +\fBwww.example.com\fR. The optional \fInetmask\fR allows matching +only on an IPv4 address prefix. It may be specified as a dotted quad +(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a count of bits +(e.g. \fB192.168.1.0/24\fR). + +.IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR] +Matches IPv4 destination address \fIip\fR. + +.IP \fBnw_proto=\fIproto\fR +Matches IP protocol type \fIproto\fR, which should be specified as a +decimal number between 0 and 255, inclusive, e.g. 6 to match TCP +packets. + +.IP \fBtp_src=\fIport\fR +Matches UDP or TCP source port \fIport\fR, which should be specified +as a decimal number between 0 and 65535, inclusive, e.g. 80 to match +packets originating from a HTTP server. + +.IP \fBtp_dst=\fIport\fR +Matches UDP or TCP destination port \fIport\fR. + +.PP +The following shorthand notations are also available: + +.IP \fBip\fR +Same as \fBdl_type=0x0800\fR. + +.IP \fBicmp\fR +Same as \fBdl_type=0x0800,nw_proto=1\fR. + +.IP \fBtcp\fR +Same as \fBdl_type=0x0800,nw_proto=6\fR. + +.IP \fBudp\fR +Same as \fBdl_type=0x0800,nw_proto=17\fR. + +.IP \fBarp\fR +Same as \fBdl_type=0x0806\fR. + +.PP +The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field: + +.IP \fIactions\fB=\fItarget\fR[\fB,\fItarget\fR...]\fR +Specifies a comma-separated list of actions to take on a packet when the +flow entry matches. The \fItarget\fR may be a decimal port number +designating the physical port on which to output the packet, or one of +the following keywords: + +.RS +.IP \fBoutput\fR:\fIport\fR +Outputs the packet on the port specified by \fIport\fR. + +.IP \fBnormal\fR +Subjects the packet to the device's normal L2/L3 processing. (This +action is not implemented by all OpenFlow switches.) + +.IP \fBflood\fR +Outputs the packet on all switch physical ports other than the port on +which it was received and any ports on which flooding is disabled +(typically, these would be ports disabled by the IEEE 802.1D spanning +tree protocol). + +.IP \fBall\fR +Outputs the packet on all switch physical ports other than the port on +which it was received. + +.IP \fBcontroller\fR:\fImax_len\fR +Sends the packet to the OpenFlow controller as a ``packet in'' +message. If \fImax_len\fR is a number, then it specifies the maximum +number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or +omitted, then the entire packet is sent. + +.IP \fBlocal\fR +Outputs the packet on the ``local port,'' which corresponds to the +\fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in +\fBsecchan\fR(8) for information on the \fBof\fIn\fR network device). + +.IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR +Modifies the VLAN id on a packet. The VLAN tag is added or modified +as necessary to match the value specified. If the VLAN tag is added, +a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set +this). + +.IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR +Modifies the VLAN priority on a packet. The VLAN tag is added or modified +as necessary to match the value specified. Valid values are between 0 +(lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used +(see the \fBmod_vlan_vid\fR action to set this). + +.IP \fBstrip_vlan\fR +Strips the VLAN tag from a packet if it is present. +.RE + +.IP +(The OpenFlow protocol supports other actions that \fBdpctl\fR does +not yet expose to the user.) + +.PP +The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands +support an additional optional field: + +.IP \fBpriority=\fIvalue\fR +Sets the priority of the flow to be added or deleted to \fIvalue\fR, +which should be a number between 0 and 65535, inclusive. If this +field is not specified, it defaults to 32768. + +.PP +The \fBadd-flow\fR and \fBadd-flows\fR commands support additional +optional fields: + +.TP +\fBidle_timeout=\fIseconds\fR +Causes the flow to expire after the given number of seconds of +inactivity. A value of 0 prevents a flow from expiring due to +inactivity. The default is 60 seconds. + +.IP \fBhard_timeout=\fIseconds\fR +Causes the flow to expire after the given number of seconds, +regardless of activity. A value of 0 (the default) gives the flow no +hard expiration deadline. + +.PP +The \fBdump-flows\fR and \fBdump-aggregate\fR commands support an +additional optional field: + +.IP \fBtable=\fInumber\fR +If specified, limits the flows about which statistics are gathered to +those in the table with the given \fInumber\fR. Tables are numbered +as shown by the \fBdump-tables\fR command. + +If this field is not specified, or if \fInumber\fR is given as +\fB255\fR, statistics are gathered about flows from all tables. + +.SH OPTIONS +.TP +\fB--strict\fR +Uses strict matching when running flow modification commands. + +.TP +\fB-t\fR, \fB--timeout=\fIsecs\fR +Limits \fBdpctl\fR runtime to approximately \fIsecs\fR seconds. If +the timeout expires, \fBdpctl\fR will exit with a \fBSIGALRM\fR +signal. + +.TP +\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR +Specifies a PEM file containing the private key used as the +identity for SSL connections to a switch. + +.TP +\fB-c\fR, \fB--certificate=\fIcert.pem\fR +Specifies a PEM file containing a certificate, signed by the +controller's certificate authority (CA), that certifies the +private key to identify a trustworthy controller. + +.TP +\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR +Specifies a PEM file containing the CA certificate used to verify that +a switch is trustworthy. + +.TP +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +@VLOG_OPTIONS@ + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. + +.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 network devices 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 network devices 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-discover.8.in b/utilities/ofp-discover.8.in index e2ba8b2d..304c3c7d 100644 --- a/utilities/ofp-discover.8.in +++ b/utilities/ofp-discover.8.in @@ -97,29 +97,7 @@ effect. .BR \-h ", " \-\^\-help Prints a brief help message to the console. -.TP -\fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\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 facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \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. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to -\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR. +@VLOG_OPTIONS@ .TP .BR \-V ", " \-\^\-version diff --git a/utilities/vlogconf.8 b/utilities/vlogconf.8 deleted file mode 100644 index 7298d29d..00000000 --- a/utilities/vlogconf.8 +++ /dev/null @@ -1,156 +0,0 @@ -.TH vlogconf 8 "June 2008" "OpenFlow" "OpenFlow Manual" - -.SH NAME -vlogconf \- configuration utility for OpenFlow logging in userspace - -.SH SYNOPSIS -\fBvlogconf\fR [\fB-h\fR | \fB--help\fR] [\fItarget\fR...] [\fIaction\fR...] -.sp 1 -The available \fItarget\fR options are: -.br -[\fB-a\fR | \fB--all\fR] [\fB-t\fR \fIpid\fR | \fB--target=\fIpid\fR] -.sp 1 -The available \fIaction\fR options are: -.br -[\fB-l\fR | \fB--list\fR] [\fB-s\fR -\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] | -\fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]] - -.SH DESCRIPTION -The \fBvlogconf\fR program configures the logging system used by -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\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] - -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR option) or the special name \fBANY\fR to -set the logging levels for all modules. The \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 facilities. If it is omitted, -\fIfacility\fR defaults to \fBANY\fR. The \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. If it is omitted, -\fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-s PATTERN:\fIfacility\fB:\fIpattern\fR, \fB--set=PATTERN:\fIfacility\fB:\fIpattern\fR - -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Each time a -message is logged to \fIfacility\fR, \fIpattern\fR determines the -message's formatting. Most characters in \fIpattern\fR are copied -literally to the log, but special escapes beginning with \fB%\fR are -expanded as follows: - -.RS -.TP -\fB%A\fR -The name of the application logging the message, e.g. \fBsecchan\fR. - -.TP -\fB%c\fR -The name of the module (as shown by \fBvlogconf --list\fR) logging -the message. - -.TP -\fB%d\fR -The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS). - -.TP -\fB%d{\fIformat\fB}\fR -The current date and time in the specified \fIformat\fR, which takes -the same format as the \fItemplate\fR argument to \fBstrftime\fR(3). - -.TP -\fB%m\fR -The message being logged. - -.TP -\fB%N\fR -A serial number for this message within this run of the program, as a -decimal number. The first message a program logs has serial number 1, -the second one has serial number 2, and so on. - -.TP -\fB%n\fR -A new-line. - -.TP -\fB%p\fR -The level at which the message is logged, e.g. \fBDBG\fR. - -.TP -\fB%P\fR -The program's process ID (pid), as a decimal number. - -.TP -\fB%r\fR -The number of milliseconds elapsed from the start of the application -to the time the message was logged. - -.TP -\fB%%\fR -A literal \fB%\fR. -.RE - -.IP -A few options may appear between the \fB%\fR and the format specifier -character, in this order: - -.RS -.TP -\fB-\fR -Left justify the escape's expansion within its field width. Right -justification is the default. - -.TP -\fB0\fR -Pad the field to the field width with \fB0\fRs. Padding with spaces -is the default. - -.TP -\fIwidth\fR -A number specifies the minimum field width. If the escape expands to -fewer characters than \fIwidth\fR then it is padded to fill the field -width. (A field wider than \fIwidth\fR is not truncated to fit.) -.RE - -.IP -The default pattern for console output is \fB%d{%b %d -%H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. - -.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/utilities/vlogconf.8.in b/utilities/vlogconf.8.in new file mode 100644 index 00000000..f1acf62b --- /dev/null +++ b/utilities/vlogconf.8.in @@ -0,0 +1,183 @@ +.TH vlogconf 8 "June 2008" "OpenFlow" "OpenFlow Manual" + +.SH NAME +vlogconf \- configuration utility for OpenFlow logging in userspace + +.SH SYNOPSIS +\fBvlogconf\fR [\fB-h\fR | \fB--help\fR] [\fItarget\fR...] [\fIaction\fR...] +.sp 1 +The available \fItarget\fR options are: +.br +[\fB-a\fR | \fB--all\fR] [\fB-t\fR \fIpid\fR | \fB--target=\fIpid\fR] +.sp 1 +The available \fIaction\fR options are: +.br +[\fB-l\fR | \fB--list\fR] [\fB-s\fR +\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] | +\fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]] +[\fB-r\fR | \fB--reopen\fR] + +.SH DESCRIPTION +The \fBvlogconf\fR program configures the logging system used by +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 \fItarget\fR, \fB--target=\fItarget\fR +The specified \fItarget\fR, which must take one of the following forms: + +.RS +.IP \(bu +A PID (process ID). + +.IP \(bu +An absolute path (beginning with `/') to the Unix domain socket for a +\fBvlogconf\fR-controllable process. + +.IP \(bu +An absolute path (beginning with `/') to a pidfile (created by, e.g., +passing the \fB-P\fR or \fB--pidfile\fR option to one of the OpenFlow +programs). + +.IP \(bu +None of the above, in which case \fItarget\fR prefixed by +\fB@RUNDIR@/\fR must match one of the cases for absolute paths listed +above. (The default name for a program's pidfile is +\fB@RUNDIR@/\fIprogram\fB.pid\fR, so this means that, say, +\fBsecchan\fR's default pidfile may be referred to simply as +\fBsecchan.pid\fR.) +.RE + +.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\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] + +Sets the logging level for \fImodule\fR in \fIfacility\fR to +\fIlevel\fR. The \fImodule\fR may be any valid module name (as +displayed by the \fB--list\fR option) or the special name \fBANY\fR to +set the logging levels for all modules. The \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 facilities. If it is omitted, +\fIfacility\fR defaults to \fBANY\fR. The \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. If it is omitted, +\fIlevel\fR defaults to \fBdbg\fR. + +.TP +\fB-s PATTERN:\fIfacility\fB:\fIpattern\fR, \fB--set=PATTERN:\fIfacility\fB:\fIpattern\fR + +Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Each time a +message is logged to \fIfacility\fR, \fIpattern\fR determines the +message's formatting. Most characters in \fIpattern\fR are copied +literally to the log, but special escapes beginning with \fB%\fR are +expanded as follows: + +.RS +.TP +\fB%A\fR +The name of the application logging the message, e.g. \fBsecchan\fR. + +.TP +\fB%c\fR +The name of the module (as shown by \fBvlogconf --list\fR) logging +the message. + +.TP +\fB%d\fR +The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS). + +.TP +\fB%d{\fIformat\fB}\fR +The current date and time in the specified \fIformat\fR, which takes +the same format as the \fItemplate\fR argument to \fBstrftime\fR(3). + +.TP +\fB%m\fR +The message being logged. + +.TP +\fB%N\fR +A serial number for this message within this run of the program, as a +decimal number. The first message a program logs has serial number 1, +the second one has serial number 2, and so on. + +.TP +\fB%n\fR +A new-line. + +.TP +\fB%p\fR +The level at which the message is logged, e.g. \fBDBG\fR. + +.TP +\fB%P\fR +The program's process ID (pid), as a decimal number. + +.TP +\fB%r\fR +The number of milliseconds elapsed from the start of the application +to the time the message was logged. + +.TP +\fB%%\fR +A literal \fB%\fR. +.RE + +.IP +A few options may appear between the \fB%\fR and the format specifier +character, in this order: + +.RS +.TP +\fB-\fR +Left justify the escape's expansion within its field width. Right +justification is the default. + +.TP +\fB0\fR +Pad the field to the field width with \fB0\fRs. Padding with spaces +is the default. + +.TP +\fIwidth\fR +A number specifies the minimum field width. If the escape expands to +fewer characters than \fIwidth\fR then it is padded to fill the field +width. (A field wider than \fIwidth\fR is not truncated to fit.) +.RE + +.IP +The default pattern for console output is \fB%d{%b %d +%H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. + +.TP +\fB-r\fR, \fB--reopen\fR +Causes the target application to close and reopen its log file. (This +is useful after rotating log files, to cause a new log file to be +used.) + +.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)