From: Ben Pfaff Date: Sun, 28 Dec 2008 06:45:25 +0000 (-0800) Subject: Document vswitchd. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f25dacc3e81163fdf6d05eaf2b55fd549597122b;p=openvswitch Document vswitchd. --- diff --git a/vswitchd/automake.mk b/vswitchd/automake.mk index 98bc31b6..05bf98c8 100644 --- a/vswitchd/automake.mk +++ b/vswitchd/automake.mk @@ -1,4 +1,5 @@ bin_PROGRAMS += vswitchd/vswitchd +dist_man_MANS += vswitchd/vswitchd.conf.5 man_MANS += vswitchd/vswitchd.8 DISTCLEANFILES += vswitchd/vswitchd.8 diff --git a/vswitchd/cfg.c b/vswitchd/cfg.c index 2a1424dd..7996bde4 100644 --- a/vswitchd/cfg.c +++ b/vswitchd/cfg.c @@ -690,6 +690,7 @@ parse_mac(const char *s, uint8_t mac[6]) static bool is_key(const char *s) { + /* XXX needs to check the same things as is_valid_key() too. */ return *s && s[strspn(s, CC_KEY)] == '\0'; } diff --git a/vswitchd/vswitchd.8.in b/vswitchd/vswitchd.8.in index e69de29b..55deb649 100644 --- a/vswitchd/vswitchd.8.in +++ b/vswitchd/vswitchd.8.in @@ -0,0 +1,98 @@ +.ds PN vswitchd +. +.TH vswitchd 8 "December 2008" "OpenFlow" "OpenFlow Manual" +. +.SH NAME +vswitchd \- OpenFlow-based virtual switch daemon +. +.SH SYNOPSIS +.B vswitchd +\fB--config=\fIfile\fR|\fIdir\fR\&... +[\fIoption\fR]\&... +. +.SH DESCRIPTION +A daemon that manages and controls any number of OpenFlow-based +virtual switches on the local machine. +.PP +At startup or upon receipt of a \fBSIGHUP\fR signal, \fBvswitchd\fR +reads the configuration files or directories specified on the command +line. It sets up OpenFlow datapaths and then operates switching +across each bridge described in its configuration files. +.PP +\fBvswitchd\fR virtual switches may be configured with any of the +following features: +. +.IP \(bu +L2 switching with MAC learning. +. +.IP \(bu +NIC bonding with automatic fail-over and source MAC-based TX load +balancing ("SLB"). +. +.IP \(bu +802.1Q VLAN support. +. +.IP \(bu +Port mirroring, with optional VLAN tagging. +. +.IP \(bu +802.1D Spanning Tree Protocol support. +. +.IP \(bu +Connectivity to an external OpenFlow controller, such as NOX. +. +.PP +Only a single instance of \fBvswitchd\fR is intended to run at a time. +A single \fBvswitchd\fR can manage any number of virtual switches, up +to the maximum number of datapaths supported by the OpenFlow +implementation. +.PP +\fBvswitchd\fR does all the necessary management of OpenFlow datapaths +itself. Thus, external tools, such \fBdpctl\fR(8), are not needed for +managing datapaths in conjunction with \fBvswitchd\fR, and their use +to modify datapaths when \fBvswitchd\fR is running can interfere with +its operation. (\fBdpctl\fR may still be useful for diagnostics.) +.PP +An OpenFlow datapath kernel module must be loaded for \fBvswitchd\fR +to be useful. Please refer to the \fBINSTALL\fR file included in the +OpenFlow source distribution for instructions on how to build and load +the OpenFlow kernel module. +.PP +.SH OPTIONS +. +At least one of the following options is required: +. +.TP +\fB-F \fIfile\fR|\fIdir\fR, \fB--config=\fIfile\fR|\fIdir\fR +. +The \fB-F\fR or \fB--config\fR option specifies a configuration file +or directory. If a regular file is named, then \fBvswitchd\fR reads +that file. If a directory is named, then \fBvswitchd\fR reads all the +files in that directory whose names consist entirely of English +letters, digits, and the special characters \fB._-\fR and do not begin +with \fB.\fR. +.IP +For a description of \fBvswitchd\fR configuration syntax, see +\fBvswitchd.conf\fR(5). +. +.PP +The rest of \fBvswitchd\fR's options are truly optional: +. +.so lib/daemon.man +.so lib/vlog.man +.so lib/common.man +. +.SH "BUGS" +. +The \fB--brcompat\fR kluge should not be necessary. It will be +removed in the future. +.PP +Only OpenFlow kernel-based datapaths are currently supported. In the +future, this restriction may be lifted. +.PP +Only Linux 2.6.\fIx\fR is currently supported. +. +.SH "SEE ALSO" +.BR vswitchd.conf (5), +.BR vlogconf (8), +\fBINSTALL\fR in the OpenFlow distribution. diff --git a/vswitchd/vswitchd.conf.5 b/vswitchd/vswitchd.conf.5 new file mode 100644 index 00000000..d7d64542 --- /dev/null +++ b/vswitchd/vswitchd.conf.5 @@ -0,0 +1,132 @@ +.\" -*- nroff -*- +.TH vswitchd.conf 5 "December 2008" "OpenFlow" "OpenFlow Manual" +. +.SH NAME +vswitchd.conf \- configuration file for \fBvswitchd.conf\fR +. +.SH DESCRIPTION +\fBvswitchd\fR(8), the virtual switch daemon, is configured using one +or more configuration files named on the command line. This manual +page describes the syntax of these configuration files. +.PP +The configuration file is based on key-value pairs, which are given +one per line in the form \fIkey\fB=\fIvalue\fR. Each \fIkey\fR +consists of one or more parts separated by dots, +e.g. \fIpart1\fB.\fIpart2\fB.\fIpart3\fR. Each \fIpart\fR may consist +only of the English letters, digits, and the special characters +\fB_-@$:+\fR. White space within \fIvalue\fR is significant, the +presence of white space at the beginning of a line is used for +determining whether a key-value pair is within a section (see below), +and other white space is ignored. +.PP +Configuration files may optionally be divided into sections. A +section begins with a section header, which is a line of the form +\fB[\fIsection\fB]\fR or \fB[\fIsection\fB "\fIsubsection\fB"]\fR. +The \fIsection\fR and optional \fIsubsection\fR must fit the syntax +described for \fIkey\fR above, and the \fB[\fR must appear in the +leftmost column of the line. Following a section header, key-value +pairs indented with white space are implicitly within the specified +\fIsection\fR and optional \fIsubsection\fR; that is, +.RS +.nf +[mysec "mysubsec"] + key = value +.fi +.RE +and +.RS +.nf +mysec.mysubsec.key = value +.fi +.RE +are equivalent. The first key-value pair at the left margin following +a section header ends the section; outside a section, indented +key-value pairs will be flagged as an error. +.PP +If a single key is specified more than once, that key has multiple +values, one value for each time the key is specified. The ordering of +key-value pairs, and the ordering of multiple values for a single key, +within a configuration file or a set of configuration files is not +significant. +.PP +Blank lines, lines that consist only of white space, and lines that +begin with \fB#\fR (optionally preceded by white space) are ignored. +.PP +The following subsections describe how key-value pairs are used to +configure \fBswitchd\fR. +.SS "Bridge Configuration" +A bridge (switch) with a given \fIname\fR is configured by specifying +the names of its network devices as values for key +\fBbridge.\fIname\fB.port\fR. +.PP +The following syntax defines a bridge named \fBmybr\fR, configured +with network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR: +.RS +.nf + +[bridge "mybr"] + port = eth0 + port = eth1 + port = eth2 +.fi +.RE +.SS "802.1Q VLAN tagging" +By default, bridge ports are trunk ports. Define key +\fBvlan.\fIport\fB.tag\fR to an integer value \fIvid\fR between 1 and +4095, inclusive, to instead designate the named \fIport\fR as a member +of 802.1Q VLAN \fIvid\fR. When \fIport\fR is assigned a VLAN tag this +way, frames arriving on trunk ports will be forwarded to \fIport\fR +only if they are tagged with VLAN \fIvid\fR, and frames arriving on +other VLAN ports will be forwarded to \fIport\fR only if their +\fIvid\fR values are equal. (Frames received on \fIport\fR will not +have an 802.1Q header.) +.PP +The following syntax makes network device \fBeth0\fR a member of VLAN +101: +.PP +.RS +.nf + +[vlan "eth0"] + tag = 101 + +.fi +.RE +.SS "Network Device Bonding" +Bonding allows multiple "slave" network devices to be treated as if +they were a single virtual "bonded" network device. It is useful for +load balancing and fail-over. +.PP +\fBvswitchd\fR supports "source load balancing" (SLB) bonding, which +assigns flows to slaves based on source MAC address, with periodic +rebalancing as traffic patterns change. This form of bonding does not +require 802.3ad or other special support from the upstream switch to +which the slave devices are connected. +.PP +To configure bonding, create a virtual bonding device by specifying +the slave network device names as values for +\fBbonding.\fIname\fB.slave\fR, then specify \fIname\fR as a bridge +port. The chosen \fIname\fR should not be the name of any real +network device on the host system. +.PP +The following syntax bonds \fBeth0\fR and \fBeth1\fR into a bonding +device named \fBbond0\fR, which is added to bridge \fBmybr\fR along +with physical network devices \fBeth2\fR and \fBeth3\fR: +.PP +.RS +.nf + +[bridge "mybr"] + port = bond0 + port = eth2 + port = eth3 + +[bonding "bond0"] + slave = eth0 + slave = eth1 + +.fi +.RE + +.SH "SEE ALSO" +.BR vswitchd (8).