README.rst

   1 .. NOTE(stephenfin): If making changes to this file, ensure that the
   2    start-after/end-before lines found in 'Documentation/intro/what-is-ovs'
   3    are kept up-to-date.
   4
   5 ============
   6 Open vSwitch
   7 ============
   8
   9 .. image:: https://github.com/openvswitch/ovs/workflows/Build%20and%20Test/badge.svg
  10     :target: https://github.com/openvswitch/ovs/actions
  11 .. image:: https://travis-ci.org/openvswitch/ovs.png
  12     :target: https://travis-ci.org/openvswitch/ovs
  13 .. image:: https://ci.appveyor.com/api/projects/status/github/openvswitch/ovs?branch=master&svg=true&retina=true
  14     :target: https://ci.appveyor.com/project/blp/ovs/history
  15 .. image:: https://api.cirrus-ci.com/github/openvswitch/ovs.svg
  16     :target: https://cirrus-ci.com/github/openvswitch/ovs
  17
  18 What is Open vSwitch?
  19 ---------------------
  20
  21 Open vSwitch is a multilayer software switch licensed under the open source
  22 Apache 2 license.  Our goal is to implement a production quality switch
  23 platform that supports standard management interfaces and opens the forwarding
  24 functions to programmatic extension and control.
  25
  26 Open vSwitch is well suited to function as a virtual switch in VM environments.
  27 In addition to exposing standard control and visibility interfaces to the
  28 virtual networking layer, it was designed to support distribution across
  29 multiple physical servers.  Open vSwitch supports multiple Linux-based
  30 virtualization technologies including Xen/XenServer, KVM, and VirtualBox.
  31
  32 The bulk of the code is written in platform-independent C and is easily ported
  33 to other environments.  The current release of Open vSwitch supports the
  34 following features:
  35
  36 - Standard 802.1Q VLAN model with trunk and access ports
  37 - NIC bonding with or without LACP on upstream switch
  38 - NetFlow, sFlow(R), and mirroring for increased visibility
  39 - QoS (Quality of Service) configuration, plus policing
  40 - Geneve, GRE, VXLAN, STT, and LISP tunneling
  41 - 802.1ag connectivity fault management
  42 - OpenFlow 1.0 plus numerous extensions
  43 - Transactional configuration database with C and Python bindings
  44 - High-performance forwarding using a Linux kernel module
  45
  46 The included Linux kernel module supports Linux 3.10 and up.
  47
  48 Open vSwitch can also operate entirely in userspace without assistance from
  49 a kernel module.  This userspace implementation should be easier to port than
  50 the kernel-based switch. OVS in userspace can access Linux or DPDK devices.
  51 Note Open vSwitch with userspace datapath and non DPDK devices is considered
  52 experimental and comes with a cost in performance.
  53
  54 What's here?
  55 ------------
  56
  57 The main components of this distribution are:
  58
  59 - ovs-vswitchd, a daemon that implements the switch, along with a companion
  60   Linux kernel module for flow-based switching.
  61 - ovsdb-server, a lightweight database server that ovs-vswitchd queries to
  62   obtain its configuration.
  63 - ovs-dpctl, a tool for configuring the switch kernel module.
  64 - Scripts and specs for building RPMs for Citrix XenServer and Red Hat
  65   Enterprise Linux.  The XenServer RPMs allow Open vSwitch to be installed on a
  66   Citrix XenServer host as a drop-in replacement for its switch, with
  67   additional functionality.
  68 - ovs-vsctl, a utility for querying and updating the configuration of
  69   ovs-vswitchd.
  70 - ovs-appctl, a utility that sends commands to running Open vSwitch daemons.
  71
  72 Open vSwitch also provides some tools:
  73
  74 - ovs-ofctl, a utility for querying and controlling OpenFlow switches and
  75   controllers.
  76 - ovs-pki, a utility for creating and managing the public-key infrastructure
  77   for OpenFlow switches.
  78 - ovs-testcontroller, a simple OpenFlow controller that may be useful for
  79   testing (though not for production).
  80 - A patch to tcpdump that enables it to parse OpenFlow messages.
  81
  82 What other documentation is available?
  83 --------------------------------------
  84
  85 .. TODO(stephenfin): Update with a link to the hosting site of the docs, once
  86    we know where that is
  87
  88 To install Open vSwitch on a regular Linux or FreeBSD host, please read the
  89 `installation guide <Documentation/intro/install/general.rst>`__. For specifics
  90 around installation on a specific platform, refer to one of the `other
  91 installation guides <Documentation/intro/install/index.rst>`__
  92
  93 For answers to common questions, refer to the `FAQ <Documentation/faq>`__.
  94
  95 To learn about some advanced features of the Open vSwitch software switch, read
  96 the `tutorial <Documentation/tutorials/ovs-advanced.rst>`__.
  97
  98 Each Open vSwitch userspace program is accompanied by a manpage.  Many of the
  99 manpages are customized to your configuration as part of the build process, so
 100 we recommend building Open vSwitch before reading the manpages.
 101
 102 License
 103 -------
 104
 105 The following is a summary of the licensing of files in this distribution.
 106 As mentioned, Open vSwitch is licensed under the open source Apache 2 license.
 107 Some files may be marked specifically with a different license, in which case
 108 that license applies to the file in question.
 109
 110
 111 Files under the datapath directory are licensed under the GNU General Public
 112 License, version 2.
 113
 114 File build-aux/cccl is licensed under the GNU General Public License, version 2.
 115
 116 The following files are licensed under the 2-clause BSD license.
 117     include/windows/getopt.h
 118     lib/getopt_long.c
 119     lib/conntrack-tcp.c
 120
 121 The following files are licensed under the 3-clause BSD-license
 122     include/windows/netinet/icmp6.h
 123     include/windows/netinet/ip6.h
 124     lib/strsep.c
 125
 126 Files under the xenserver directory are licensed on a file-by-file basis.
 127 Refer to each file for details.
 128
 129 Files lib/sflow*.[ch] are licensed under the terms of either the
 130 Sun Industry Standards Source License 1.1, that is available at:
 131         http://host-sflow.sourceforge.net/sissl.html
 132 or the InMon sFlow License, that is available at:
 133         http://www.inmon.com/technology/sflowlicense.txt
 134
 135 Contact
 136 -------
 137
 138 bugs@openvswitch.org