Update Open vSwitch documentation.
authorBen Pfaff <blp@nicira.com>
Thu, 4 Mar 2010 00:54:00 +0000 (16:54 -0800)
committerBen Pfaff <blp@nicira.com>
Thu, 4 Mar 2010 18:05:44 +0000 (10:05 -0800)
INSTALL.Linux
INSTALL.OpenFlow
INSTALL.SSL
INSTALL.bridge
Makefile.am
README
REPORTING-BUGS
utilities/ovs-openflowd.8.in
vswitchd/.gitignore
xenserver/etc_profile.d_vswitch.sh

index c0344f23010bdad00857e7010f6e9e8f70f3be56..e25c193c91621398e3e74781e5ac8dd9857b04fd 100644 (file)
@@ -155,23 +155,34 @@ Prerequisites section, follow the procedure below to build.
    To verify that the modules have been loaded, run "/sbin/lsmod" and
    check that openvswitch_mod is listed.
 
-Configuration
-=============
+7. Initialize the configuration database using ovsdb-tool, e.g.:
 
-Open vSwitch is configured primarily through a configuration file,
-whose name is specified on the ovs-vswitchd command line.  Please
-refer to ovs-vswitchd(8) and ovs-vswitchd.conf(5) for information on
-how to start ovs-vswitchd and the syntax of its configuration file,
-respectively.
+      % ovsdb-tool create /etc/ovs-vswitchd.conf.db vswitchd/vswitch.ovsschema
 
-At runtime, you may make ovs-vswitchd reload its configuration file
-and update its configuration accordingly by sending it a SIGHUP
-signal.  The ovs-appctl utility can also be used to do this:
+Startup
+=======
 
-    % ovs-appctl vswitchd/reload
+Before starting ovs-vswitchd itself, you need to start its
+configuration database, ovsdb-server.  Configure it to use the
+database you created during step 7 of installation, above, and to
+listen on a Unix domain socket, e.g.:
 
-In the latter case, ovs-appctl will wait for ovs-vswitchd to finish
-reloading before it exits.
+      % ovsdb-server /etc/ovs-vswitchd.conf.db --remote=punix:/var/run/ovsdb-server
+
+Then start the main Open vSwitch daemon, telling it to connect to the
+same Unix domain socket:
+
+      % ovs-vswitchd unix:/var/run/ovsdb-server
+
+Now you may use ovs-vsctl to set up bridges and other Open vSwitch
+features.  For example, to create a bridge named br0 and add ports
+eth0 and vif1.0 to it:
+
+      % ovs-vsctl add-br br0
+      % ovs-vsctl add-port br0 eth0
+      % ovs-vsctl add-port br0 vif1.0
+
+Please refer to ovs-vsctl(8) for more details.
 
 Bug Reporting
 -------------
index a1b77997f328d138ac33d5483c091f921ac02ec8..7a4a7e6f174533a47e2933dcd99fca3b9d335a27 100644 (file)
@@ -1,15 +1,16 @@
             Using Open vSwitch as a Simple OpenFlow Switch
             ==============================================
 
-Open vSwitch uses OpenFlow as its preferred method of remote flow table
-configuration.  This is the simplest method of using it with an OpenFlow
-controller.  All that is required is to follow the instructions in
-INSTALL.Linux and add the bridge.<name>.controller set of parameters to the 
-ovs-vswitchd(8) configuration file as described in ovs-vswitchd.conf(5).  
-We recommend using OpenFlow in this manner.  However, it is also possible to 
-use Open vSwitch as a simple OpenFlow switch like that provided by the 
-OpenFlow reference implementation [1].  The remainder of this file describes 
-how to user it in that manner.
+Open vSwitch uses OpenFlow as its preferred method of remote flow
+table configuration.  This is the simplest method of using it with an
+OpenFlow controller.  The ovs-vsctl "set-controller" command will set
+the controller for one or more bridges.  We recommend using OpenFlow
+in this manner.
+
+However, it is also possible to use Open vSwitch as a simple OpenFlow
+switch like that provided by the OpenFlow reference implementation
+[1].  The remainder of this file describes how to use it in that
+manner.
 
 What is OpenFlow?
 -----------------
index 8df47bc106934eacda318100d91e70d4ab8f1bbe..4ba092548021c1f3c757daab338e83e3420ab71a 100644 (file)
@@ -287,30 +287,31 @@ cacert.pem:
       OpenFlow controller by verifying a signature against this CA
       certificate.
 
-Once you have these files, configure ovs-vswitchd to use them by
-adding the following keys to your ovs-vswitchd.conf file:
+Once you have these files, configure ovs-vswitchd to use them using
+the ovs-vsctl "set-ssl" command, e.g.:
 
-    ssl.private-key=/etc/vswitch/sc-privkey.pem
-    ssl.certificate=/etc/vswitch/sc-cert.pem
-    ssl.ca-cert=/etc/vswitch/cacert.pem
+    ovs-vsctl set-ssl /etc/vswitch/sc-privkey.pem /etc/vswitch/sc-cert.pem /etc/vswitch/cacert.pem
 
 Substitute the correct file names, of course, if they differ from the
-ones used above.
+ones used above.  You should use absolute file names (ones that begin
+with "/"), because ovs-vswitchd's current directory is unrelated to
+the one from which you run ovs-vsctl.
 
 If you are using self-signed certificates (see "SSL Concepts for
 OpenFlow") and you did not copy controllerca/cacert.pem from the PKI
-machine to the Open vSwitch, then also add the following key:
+machine to the Open vSwitch, then add the --bootstrap option, e.g.:
 
-    ssl.bootstrap-ca-cert=true
+    ovs-vsctl -- --bootstrap set-ssl /etc/vswitch/sc-privkey.pem /etc/vswitch/sc-cert.pem /etc/vswitch/cacert.pem
 
 After you have added all of these configuration keys, you may specify
-"ssl:" connection methods elsewhere in ovs-vswitchd.conf, e.g.:
-
-    mgmt.controller=ssl:192.168.0.1
-
+"ssl:" connection methods elsewhere in the configuration database.
 "tcp:" connection methods are still allowed even after SSL has been
 configured, so for security you should use only "ssl:" connections.
 
+Unlike most Open vSwitch settings, the SSL settings are read only
+once, at ovs-vswitchd startup time.  For changes to take effect,
+ovs-vswitchd must be killed and restarted.
+
 Reporting Bugs
 --------------
 
index b30152d4baa2b518626ab770369468a87b41ccaa..75caaceebe3e71a436facc5632da5e62d1d5330b 100644 (file)
@@ -42,23 +42,16 @@ to update system scripts to follow these steps.
    bridge interfaces), to ensure that the Open vSwitch kernel modules
    are loaded before the Linux kernel bridge module.
 
-3. Create an initial version of the configuration file, for example
-   /etc/ovs-vswitchd.conf.  This file may be empty initially or may
-   contain add any valid configuration directives described in
-   ovs-vswitchd.conf(5).  However, it must exist when you start
-   ovs-vswitchd.
+3. Start ovsdb-server, ovs-vswitchd, and ovs-brcompatd, e.g.:
 
-   To create an empty configuration file:
-
-      % touch /etc/ovs-vswitchd.conf
-
-4. Start ovs-vswitchd and ovs-brcompatd, e.g.:
+      % ovsdb-server /etc/ovs-vswitchd.conf.db \
+                --remote=punix:/var/run/ovsdb-server
 
       % ovs-vswitchd --pidfile --detach -vANY:console:EMER \
-                /etc/ovs-vswitchd.conf
+                unix:/var/run/ovsdb-server
 
       % ovs-brcompatd --pidfile --detach -vANY:console:EMER \
-                /etc/ovs-vswitchd.conf
+                unix:/var/run/ovsdb-server
 
 5. Now you should be able to manage the Open vSwitch using brctl and
    related tools.  For example, you can create an Open vSwitch bridge,
@@ -71,11 +64,7 @@ to update system scripts to follow these steps.
       % brctl show
 
    Each of these commands actually uses or modifies the Open vSwitch
-   configuration file, then notifies the ovs-vswitchd daemon of the
-   change.  For example, after executing the commands above starting
-   from an empty configuration file, "cat /etc/ovs-vswitchd.conf"
-   should show that the configuration file now contains the following:
-
-      bridge.br0.port=br0
-      bridge.br0.port=eth0
-      bridge.br0.port=eth1
+   configuration database, then notifies the ovs-vswitchd daemon of
+   the change.  For example, after executing the commands above
+   starting from an empty configuration file, "ovs-vsctl list-ports
+   br0" should show that bridge br0 contains two ports, eth0 and eth1.
index bb8245efd804a3453023619f9d2f20e1d248e47b..6a82ba3cad30dc851494a93bb96d39190dcfd50f 100644 (file)
@@ -1,4 +1,4 @@
-# Copyright (C) 2007, 2008, 2009 Nicira Networks, Inc.
+# Copyright (C) 2007, 2008, 2009, 2010 Nicira Networks, Inc.
 #
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright
@@ -40,6 +40,7 @@ bin_PROGRAMS =
 sbin_PROGRAMS =
 bin_SCRIPTS =
 dist_man_MANS =
+dist_pkgdata_DATA =
 dist_pkgdata_SCRIPTS =
 dist_sbin_SCRIPTS =
 man_MANS =
diff --git a/README b/README
index a0c9a2e1de450609921a04dd7a08cb1a4965e1a8..5b8099890682be2a9e8f14a919b76d8be96052da 100644 (file)
--- a/README
+++ b/README
@@ -47,6 +47,9 @@ The main components of this distribution are:
     * ovs-vswitchd, a daemon that implements the switch, along with 
       a companion Linux kernel module for flow-based switching.
 
+    * ovsdb-server, a lightweight database server that ovs-vswitchd
+      queries to obtain its configuration.
+
     * ovs-brcompatd, a daemon that allows ovs-vswitchd to act as a
       drop-in replacement for the Linux bridge in many environments, 
       along with a companion Linux kernel module to intercept bridge 
index 8412ec633844bad1f8b786fe2764e1176ab895e0..75da3d6ebe17738445a5d84a5a9f4532a8fdd898 100644 (file)
@@ -20,8 +20,8 @@ as much of the following information as you can in your report:
           /proc/version) and the distribution and version number of
           your OS (e.g. "Centos 5.0").
 
-        * The contents of the vswitchd configuration file (usually
-          /etc/ovs-vswitchd.conf).
+        * The contents of the vswitchd configuration database (usually
+          /etc/ovs-vswitchd.conf.db).
 
         * The output of "ovs-dpctl show".
 
index 7b349b5ff4f1f737ec903b371a99762a612c0cb9..e65121eb895cb8d2bc7f236d250a2b80ce01c4ef 100644 (file)
@@ -429,5 +429,4 @@ switching.
 .BR ovs\-discover (8),
 .BR ovs\-dpctl (8),
 .BR ovs\-ofctl (8),
-.BR ovs\-pki (8),
-.BR ovs\-vswitchd.conf (5)
+.BR ovs\-pki (8)
index 872a72673f056d4267d66fee146f3f81b449e8a5..fd0945dc44478bcd699f50fac54fc8405bc4cc1a 100644 (file)
@@ -4,7 +4,6 @@
 /ovs-brcompatd.8
 /ovs-vswitchd
 /ovs-vswitchd.8
-/ovs-vswitchd.conf.5
 /vswitch-idl.c
 /vswitch-idl.h
 /vswitch-idl.ovsidl
index 527bfcf9259eba3f823331ec5931fb3a5fda6aea..a001e2158b7980090ca4e54d89954c885c29da5f 100644 (file)
@@ -1,4 +1,4 @@
-# Copyright (C) 2009 Nicira Networks, Inc.
+# Copyright (C) 2009, 2010 Nicira Networks, Inc.
 #
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright
@@ -7,10 +7,6 @@
 
 alias vswitch='service vswitch'
 
-function watchconf {
-    watch cat /etc/ovs-vswitchd.conf
-}
-
 function watchdp {
        watch ovs-dpctl show "$@"
 }