AM_LDFLAGS = -export-dynamic
endif
+CLEANFILES =
DISTCLEANFILES =
EXTRA_DIST =
TESTS =
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
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
.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
-utilities/vlogconf.8
+_debian/utilities/vlogconf.8
_debian/utilities/ofp-pki.8
_debian/switch/switch.8
_debian/utilities/ofp-discover.8
_debian/utilities/ofp-kill.8
-utilities/dpctl.8
+_debian/utilities/dpctl.8
lib/dh4096.pem \
lib/dhparams.h
+CLEANFILES += lib/dirs.c
lib/dirs.c: Makefile
($(ro_c) && \
echo 'const char ofp_rundir[] = "@RUNDIR@";' && \
--- /dev/null
+.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).
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
.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
--- /dev/null
+#! /bin/sh
+exec sed -e "/^@$1@\$/{
+r $2
+d
+}"
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
.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
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)
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
+++ /dev/null
-.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)
--- /dev/null
+.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)
.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
+++ /dev/null
-.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)
--- /dev/null
+.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)
projects / openvswitch / commitdiff