X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=INSTALL;h=001d3cbea6760420d4c0867d65703ea1b7347f4d;hb=1e827902be9194d71ea851c9ce2676f65eeed33a;hp=68805ee1ac65d327c9f4fe796353e4df4e1c0643;hpb=76d5beb9e7da6ca927ed5475273923ac8205ef7b;p=sliver-openvswitch.git diff --git a/INSTALL b/INSTALL index 68805ee1a..001d3cbea 100644 --- a/INSTALL +++ b/INSTALL @@ -9,6 +9,7 @@ on a specific platform, please see one of these files: - INSTALL.Fedora - INSTALL.RHEL - INSTALL.XenServer + - INSTALL.NetBSD Build Requirements ------------------ @@ -18,8 +19,13 @@ you will need the following software: - GNU make. - - The GNU C compiler. We generally test with version 4.1, 4.2, or - 4.3. + - A C compiler, such as: + + * GCC 4.x. + + * Clang. Clang 3.4 and later provide useful static semantic + analysis and thread-safety checks. For Ubuntu, there are + nightly built packages available on clang's website. - libssl, from OpenSSL, is optional but recommended if you plan to connect the Open vSwitch to an OpenFlow controller. libssl is @@ -28,6 +34,8 @@ you will need the following software: libssl is installed, then Open vSwitch will automatically build with support for it. + - Python 2.x, for x >= 4. + To compile the kernel module on Linux, you must also install the following. If you cannot build or install the kernel module, you may use the userspace-only implementation, at a cost in performance. The @@ -49,9 +57,9 @@ INSTALL.userspace for more information. NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is obsolete and not needed.) - If GRE tunneling is being used it is recommended that the kernel - be compiled with IPv6 support (CONFIG_IPV6). This allows for - special handling (such as path MTU discovery) of IPv6 packets. + To use GRE tunneling on Linux 2.6.37 or newer, kernel support + for GRE must be compiled in or available as a module + (CONFIG_NET_IPGRE_DEMUX). To configure HTB or HFSC quality of service with Open vSwitch, you must enable the respective configuration options. @@ -76,21 +84,15 @@ or the database schema, you will also need the following software: - Automake version 1.10 or later. - - Python 2.x, for x >= 4. - -If you modify the ovsdbmonitor tool, then you will also need the -following: - - - pyuic4 from PyQt4 (http://www.riverbankcomputing.co.uk). + - libtool version 2.4 or later. (Older versions might work too.) To run the unit tests, you also need: - Perl. Version 5.10.1 is known to work. Earlier versions should also work. -If you modify the vswitchd database schema, then the E-R diagram in -the ovs-vswitchd.conf.db(5) manpage will be updated properly only if -you have the following: +The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in +formats other than plain text, only if you have the following: - "dot" from graphviz (http://www.graphviz.org/). @@ -107,6 +109,10 @@ installing the following to obtain better warnings: - GNU make. + - clang, version 3.4 or later + +Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful. + Installation Requirements ------------------------- @@ -127,22 +133,6 @@ following software: On Linux you should ensure that /dev/urandom exists. To support TAP devices, you must also ensure that /dev/net/tun exists. -To run the ovsdbmonitor tool, the machine must also have the following -software: - - - Python 2.x, for x >= 4. - - - Python Twisted Conch. - - - Python JSON. - - - PySide or PyQt4. - - - Python Zope interface module. - -(On Debian "lenny" the above can be installed with "apt-get install -python-json python-qt4 python-zopeinterface python-twisted-conch".) - Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD ================================================================= @@ -171,6 +161,10 @@ Prerequisites section, follow the procedure below to build. % ./configure CC=gcc-4.2 + To use 'clang' compiler: + + % ./configure CC=clang + To build the Linux kernel module, so that you can run the kernel-based switch, pass the location of the kernel build directory on --with-linux. For example, to build for a running @@ -186,6 +180,11 @@ Prerequisites section, follow the procedure below to build. % ./configure --with-linux=/path/to/linux KARCH=mips + If you plan to do much Open vSwitch development, you might want to + add --enable-Werror, which adds the -Werror option to the compiler + command line, turning warnings into errors. That makes it + impossible to miss warnings generated by the build. + The configure script accepts a number of other options and honors additional environment variables. For a full list, invoke configure with the --help option. @@ -209,15 +208,15 @@ Prerequisites section, follow the procedure below to build. 6. Run "make install" to install the executables and manpages into the running system, by default under /usr/local. -7. If you built kernel modules, you may load them with "insmod", e.g.: +7. If you built kernel modules, you may install and load them, e.g.: - % insmod datapath/linux/openvswitch.ko + % make modules_install + % /sbin/modprobe openvswitch - You may need to specify a full path to insmod, e.g. /sbin/insmod. To verify that the modules have been loaded, run "/sbin/lsmod" and check that openvswitch is listed. - If the "insmod" operation fails, look at the last few kernel log + If the "modprobe" operation fails, look at the last few kernel log messages (e.g. with "dmesg | tail"): - The message "openvswitch: exports duplicate symbol @@ -264,11 +263,6 @@ Prerequisites section, follow the procedure below to build. you do not understand what this means or do not know if your driver will work, do not set this. - Once you verify that the kernel modules load properly, you should - install them: - - % make modules_install - 8. Initialize the configuration database using ovsdb-tool, e.g.: % mkdir -p /usr/local/etc/openvswitch @@ -286,10 +280,10 @@ any managers specified in the database itself, and to use the SSL configuration in the database: % ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \ - --remote=db:Open_vSwitch,manager_options \ - --private-key=db:SSL,private_key \ - --certificate=db:SSL,certificate \ - --bootstrap-ca-cert=db:SSL,ca_cert \ + --remote=db:Open_vSwitch,Open_vSwitch,manager_options \ + --private-key=db:Open_vSwitch,SSL,private_key \ + --certificate=db:Open_vSwitch,SSL,certificate \ + --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \ --pidfile --detach (If you built Open vSwitch without SSL support, then omit @@ -343,6 +337,48 @@ also upgrade the database schema: 4. Start the Open vSwitch daemons as described under "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD" 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 =====================