Always use valid ids pointer in dec_ttl_cnt_ids_from_openflow()

[cascardo/ovs.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 5d62a90..bfccc64 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -16,13 +16,11 @@ Build Requirements
 To compile the userspace programs in the Open vSwitch distribution,
 you will need the following software:
 
-    - A make program, e.g. GNU make.  BSD make should also work.
+    - GNU make.
 
     - The GNU C compiler.  We generally test with version 4.1, 4.2, or
       4.3.
 
-    - pkg-config.  We test with version 0.22.
-
     - libssl, from OpenSSL, is optional but recommended if you plan to
       connect the Open vSwitch to an OpenFlow controller.  libssl is
       required to establish confidentiality and authenticity in the
@@ -192,15 +190,16 @@ Prerequisites section, follow the procedure below to build.
    additional environment variables.  For a full list, invoke
    configure with the --help option.
 
-3. Run make in the top source directory:
+3. Run GNU make in the top source directory, e.g.:
 
       % make
 
-   On FreeBSD you may need to use GNU make (gmake) or NetBSD make
-   (bmake) instead of the native make.
+   or if GNU make is installed as "gmake":
+
+      % gmake
 
    For improved warnings if you installed "sparse" (see
-   "Prerequisites"), add C=1 to the "make" command line.
+   "Prerequisites"), add C=1 to the command line.
 
 4. Consider running the testsuite.  Refer to "Running the Testsuite"
    below, for instructions.
@@ -344,6 +343,48 @@ also upgrade the database schema:
 4. Start the Open vSwitch daemons as described under "Building and
    Installing Open vSwitch for Linux or FreeBSD" above.
 
+Hot Upgrading
+=============
+Upgrading Open vSwitch from one version to the next version with minimum
+disruption of traffic going through the system that is using that Open vSwitch
+needs some considerations:
+
+1. If the upgrade only involves upgrading the userspace utilities and daemons
+of Open vSwitch, make sure that the new userspace version is compatible with
+the previously loaded kernel module.
+
+2. An upgrade of userspace daemons means that they have to be restarted.
+Restarting the daemons means that the Openflow flows in the ovs-vswitchd daemon
+will be lost.  One way to restore the flows is to let the controller
+re-populate it.  Another way is to save the previous flows using a utility
+like ovs-ofctl and then re-add them after the restart. Restoring the old flows
+is accurate only if the new Open vSwitch interfaces retain the old 'ofport'
+values.
+
+3. When the new userspace daemons get restarted, they automatically flush
+the old flows setup in the kernel. This can be expensive if there are hundreds
+of new flows that are entering the kernel but userspace daemons are busy
+setting up new userspace flows from either the controller or an utility like
+ovs-ofctl. Open vSwitch database provides an option to solve this problem
+through the other_config:flow-restore-wait column of the Open_vSwitch table.
+Refer to the ovs-vswitchd.conf.db(5) manpage for details.
+
+4. If the upgrade also involves upgrading the kernel module, the old kernel
+module needs to be unloaded and the new kernel module should be loaded. This
+means that the kernel network devices belonging to Open vSwitch is recreated
+and the kernel flows are lost. The downtime of the traffic can be reduced
+if the userspace daemons are restarted immediately and the userspace flows
+are restored as soon as possible.
+
+The ovs-ctl utility's "restart" function only restarts the userspace daemons,
+makes sure that the 'ofport' values remain consistent across restarts, restores
+userspace flows using the ovs-ofctl utility and also uses the
+other_config:flow-restore-wait column to keep the traffic downtime to the
+minimum. The ovs-ctl utility's "force-reload-kmod" function does all of the
+above, but also replaces the old kernel module with the new one. Open vSwitch
+startup scripts for Debian, XenServer and RHEL use ovs-ctl's functions and it
+is recommended that these functions be used for other software platforms too.
+
 Running the Testsuite
 =====================
 
@@ -390,7 +431,7 @@ check".  All the same options are available via TESTSUITEFLAGS.  When
 you do this, the "valgrind" results for test <N> are reported in files
 named tests/testsuite.dir/<N>/valgrind.*.  You may find that the
 valgrind results are easier to interpret if you put "-q" in
-~/.valgrindrc, since that reduces the amount of
+~/.valgrindrc, since that reduces the amount of output.
 
 Sometimes a few tests may fail on some runs but not others.  This is
 usually a bug in the testsuite, not a bug in Open vSwitch itself.  If