INSTALL.Debian: New instructions for installing on Debian.

Signed-off-by: Ben Pfaff <blp@nicira.com>

1 files changed, 125 insertions, 0 deletions

diff --git a/INSTALL.Debian b/INSTALL.Debian
new file mode 100644
index 000000000..62f4c196c
--- /dev/null
+++ b/INSTALL.Debian
@@ -0,0 +1,125 @@
+	    How to Build Debian Packages for Open vSwitch
+            =============================================
+
+This document describes how to build Debian packages for Open vSwitch.
+To install Open vSwitch on Debian without building Debian packages,
+see INSTALL instead.
+
+These instructions should also work on Ubuntu and other Debian
+derivative distributions.
+
+
+Before You Begin
+----------------
+
+Before you begin, consider whether you really need to build packages
+yourself.  Debian "wheezy" and "sid", as well as recent versions of
+Ubuntu, contain pre-built Debian packages for Open vSwitch.  It is
+easier to install these than to build your own.  To use packages from
+your distribution, skip ahead to "Installing .deb Packages", below.
+
+
+Building Open vSwitch Debian packages
+-------------------------------------
+
+You may build from an Open vSwitch distribution tarball or from an
+Open vSwitch Git tree with these instructions.
+
+You do not need to be the superuser to build the Debian packages.
+
+1. Install the "build-essential" and "fakeroot" packages, e.g. with
+   "apt-get install build-essential fakeroot".
+
+2. Obtain and unpack an Open vSwitch source distribution and "cd" into
+   its top level directory.
+
+3. Install the build dependencies listed under "Build-Depends:" near
+   the top of debian/rules.  You can install these any way you like,
+   e.g. with "apt-get install".
+
+   Check your work by running "dpkg-checkbuilddeps".  If you've
+   installed all the dependencies properly, dpkg-checkbuilddeps will
+   exit without printing anything.  If you forgot to install some
+   dependencies, it will tell you which ones.
+
+4. Run:
+
+       fakeroot debian/rules binary
+
+   This will do a serial build that runs the unit tests.  If you
+   prefer, you can run a faster parallel build, e.g.:
+
+       DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary
+
+   If you are in a big hurry, you can even skip the unit tests:
+
+       DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
+
+5. The generated .deb files will be in the parent directory of the
+   Open vSwitch source distribution.
+
+
+Installing .deb Packages
+------------------------
+
+These instructions apply to installing from Debian packages that you
+built yourself, as described in the previous section, or from packages
+provided by Debian or a Debian derivative distribution such as Ubuntu.
+In the former case, use a command such as "dpkg -i" to install the
+.deb files that you build, and in the latter case use a program such
+as "apt-get" or "aptitude" to download and install the provided
+packages.
+
+You must be superuser to install Debian packages.
+
+1. Start by installing the "openvswitch-switch" and
+   "openvswitch-common" packages.  These packages include the core
+   userspace components of the switch.
+
+2. Install an Open vSwitch kernel module.  There are multiple ways to
+   do this.  In order of increasing manual effort, these are:
+
+       * Use a Linux kernel 3.3 or later, which has an integrated Open
+	 vSwitch kernel module.
+
+	 The upstream Linux kernel module lacks a few features that
+	 are in the third-party module.  For details, please see the
+	 FAQ, "What features are not available in the Open vSwitch
+	 kernel datapath that ships as part of the upstream Linux
+	 kernel?".
+
+       * Install the "openvswitch-datapath-dkms" Debian package that
+	 you built earlier.  This should automatically build and
+	 install the Open vSwitch kernel module for your running
+	 kernel.
+
+	 This option requires that you have a compiler and toolchain
+	 installed on the machine where you run Open vSwitch, which
+	 may be unacceptable in some production server environments.
+
+       * Install the "openvswitch-datapath-source" Debian package, use
+	 "module-assistant" to build a Debian package of the Open
+	 vSwitch kernel module for your kernel, and then install that
+	 Debian package.
+
+	 You can install the kernel module Debian packages that you
+	 build this way on the same machine where you built it or on
+	 another machine or machines, which means that you don't
+	 necessarily have to have any build infrastructure on the
+	 machines where you use the kernel module.
+
+	 /usr/share/doc/openvswitch-datapath-source/README.Debian has
+	 details on the build process.
+
+       * Build and install the kernel module by hand.
+
+Open vSwitch .deb packages not mentioned above are rarely useful.
+Please refer to their individual package descriptions to find out
+whether any of them are useful to you.
+
+
+Bug Reporting
+-------------
+
+Please report problems to bugs@openvswitch.org.
+