From patchwork Tue Oct 18 20:03:35 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 683849 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3sz5fx5hT6z9s2G for ; Wed, 19 Oct 2016 07:06:01 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=Xpkfg0V1; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 10DD3103B4; Tue, 18 Oct 2016 13:06:01 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx3v3.cudamail.com (mx3.cudamail.com [64.34.241.5]) by archives.nicira.com (Postfix) with ESMTPS id E5384103A2 for ; Tue, 18 Oct 2016 13:05:59 -0700 (PDT) Received: from bar6.cudamail.com (localhost [127.0.0.1]) by mx3v3.cudamail.com (Postfix) with ESMTPS id 7BC36162B44 for ; Tue, 18 Oct 2016 14:05:59 -0600 (MDT) X-ASG-Debug-ID: 1476821156-0b3237781926bd0001-byXFYA Received: from mx1-pf1.cudamail.com ([192.168.24.1]) by bar6.cudamail.com with ESMTP id jaDc9fTHv6L7gSCk (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Tue, 18 Oct 2016 14:05:56 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.1 Received: from unknown (HELO caracal.maple.relay.mailchannels.net) (23.83.214.30) by mx1-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 18 Oct 2016 20:05:54 -0000 Received-SPF: none (mx1-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.214.30 X-Barracuda-RBL-IP: 23.83.214.30 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id F1ACD127CED for ; Tue, 18 Oct 2016 20:05:52 +0000 (UTC) Received: from one.mxroute.com (ip-10-120-4-226.us-west-2.compute.internal [10.120.4.226]) by relay.mailchannels.net (Postfix) with ESMTPA id 6F12A127E74 for ; Tue, 18 Oct 2016 20:05:52 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([TEMPUNAVAIL]. [10.102.194.57]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Tue, 18 Oct 2016 20:05:52 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1476821152775:638619726 X-MC-Ingress-Time: 1476821152775 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=QTkjniW9Zcg0ZWSHvzDUKBYPIqTKihdcjHFJavAW+Vw=; b=Xpkfg0V1KWxA4VABZBO3snKzSW W6QpgTuAUyEEG4KbGzSzMwyIfzSvEvk7MPXJzaq6lQsfJS6b4K3RIkYN2T98y7V2NKCGuPe9nIy4c ZeGzBBWfY8YpJGIK6Ax0CnvvxP3XYwyrwKJYVBrXUK8BTYfj9ctuRn+1OtXfrkVldz+9l1x7X/v6F BhSYgXpKnZMTVMbiBgRHJzW3EQUQqXqBOkKbDyERgYV9IrC3CazrUQRFbKW+8rJ2POO8AO3Flqgn2 ajvpsqIZ2aNZXEh4YhrYBsFbdUcu3CGXu4pSbb3asvVfASupCrMaSIKyxtcPmZlVn7JIkogNndRug NUdIitCQ==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E1-1017071431 X-CudaMail-DTE: 101816 X-CudaMail-Originating-IP: 23.83.214.30 Date: Tue, 18 Oct 2016 21:03:35 +0100 X-ASG-Orig-Subj: [##CM-E1-1017071431##][PATCH 05/15] doc: Convert README to rST Message-Id: <1476821025-4915-6-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1476821025-4915-1-git-send-email-stephen@that.guru> References: <1476821025-4915-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-Barracuda-Connect: UNKNOWN[192.168.24.1] X-Barracuda-Start-Time: 1476821156 X-Barracuda-Encrypted: ECDHE-RSA-AES256-GCM-SHA384 X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.33831 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 05/15] doc: Convert README to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- INSTALL.rst | 2 +- Makefile.am | 2 +- README.md | 131 ---------------------------------------- README.rst | 116 +++++++++++++++++++++++++++++++++++ rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in | 2 +- utilities/ovs-ctl.8 | 2 +- 7 files changed, 121 insertions(+), 136 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/INSTALL.rst b/INSTALL.rst index 07d69f1..055f201 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -85,7 +85,7 @@ use the userspace-only implementation, at some cost in features and performance To compile the kernel module on Linux, you must also install the following: -- A supported Linux kernel version. Refer to the `README `__ +- A supported Linux kernel version. Refer to the `README `__ for a list of supported versions. For optional support of ingress policing, you must enable kernel diff --git a/Makefile.am b/Makefile.am index 73e94ba..6117ca8 100644 --- a/Makefile.am +++ b/Makefile.am @@ -89,7 +89,7 @@ docs = \ MAINTAINERS.rst \ OPENFLOW-1.1+.md \ PORTING.rst \ - README.md \ + README.rst \ README-lisp.md \ README-native-tunneling.md \ REPORTING-BUGS.md \ diff --git a/README.md b/README.md deleted file mode 100644 index f824581..0000000 --- a/README.md +++ /dev/null @@ -1,131 +0,0 @@ -Open vSwitch -============ - -Build Status: -------------- - -[![Build Status](https://travis-ci.org/openvswitch/ovs.png)](https://travis-ci.org/openvswitch/ovs) - -What is Open vSwitch? ---------------------- - -Open vSwitch is a multilayer software switch licensed under the open -source Apache 2 license. Our goal is to implement a production -quality switch platform that supports standard management interfaces -and opens the forwarding functions to programmatic extension and -control. - -Open vSwitch is well suited to function as a virtual switch in VM -environments. In addition to exposing standard control and visibility -interfaces to the virtual networking layer, it was designed to support -distribution across multiple physical servers. Open vSwitch supports -multiple Linux-based virtualization technologies including -Xen/XenServer, KVM, and VirtualBox. - -The bulk of the code is written in platform-independent C and is -easily ported to other environments. The current release of Open -vSwitch supports the following features: - -* Standard 802.1Q VLAN model with trunk and access ports -* NIC bonding with or without LACP on upstream switch -* NetFlow, sFlow(R), and mirroring for increased visibility -* QoS (Quality of Service) configuration, plus policing -* Geneve, GRE, VXLAN, STT, and LISP tunneling -* 802.1ag connectivity fault management -* OpenFlow 1.0 plus numerous extensions -* Transactional configuration database with C and Python bindings -* High-performance forwarding using a Linux kernel module - -The included Linux kernel module supports Linux 3.10 and up. - -Open vSwitch can also operate, at a cost in performance, entirely in -userspace, without assistance from a kernel module. This userspace -implementation should be easier to port than the kernel-based switch. -It is considered experimental. - -What's here? ------------- - -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-dpctl, a tool for configuring the switch kernel module. -* Scripts and specs for building RPMs for Citrix XenServer and Red - Hat Enterprise Linux. The XenServer RPMs allow Open vSwitch to - be installed on a Citrix XenServer host as a drop-in replacement - for its switch, with additional functionality. -* ovs-vsctl, a utility for querying and updating the configuration - of ovs-vswitchd. -* ovs-appctl, a utility that sends commands to running Open - vSwitch daemons. - -Open vSwitch also provides some tools: - -* ovs-ofctl, a utility for querying and controlling OpenFlow - switches and controllers. -* ovs-pki, a utility for creating and managing the public-key - infrastructure for OpenFlow switches. -* ovs-testcontroller, a simple OpenFlow controller that may be useful - for testing (though not for production). -* A patch to tcpdump that enables it to parse OpenFlow messages. - -What other documentation is available? --------------------------------------- - -To install Open vSwitch on a regular Linux or FreeBSD host, please -read [INSTALL.rst]. For specifics around installation on a specific -platform, please see one of these files: - -- [INSTALL.Debian.rst] -- [INSTALL.Fedora.md] -- [INSTALL.RHEL.md] -- [INSTALL.XenServer.rst] - -To use Open vSwitch... - -- ...with Docker on Linux, read [INSTALL.Docker.rst] - -- ...with KVM on Linux, read [INSTALL.rst], read [INSTALL.KVM.rst] - -- ...with Libvirt, read [INSTALL.Libvirt.md]. - -- ...without using a kernel module, read [INSTALL.userspace.rst]. - -- ...with DPDK, read [INSTALL.DPDK.rst]. - -- ...with SELinux, read [INSTALL.SELinux.md]. - -For answers to common questions, read [FAQ.md]. - -To learn how to set up SSL support for Open vSwitch, read [INSTALL.SSL.md]. - -To learn about some advanced features of the Open vSwitch software -switch, read the [tutorial/Tutorial.md]. - -Each Open vSwitch userspace program is accompanied by a manpage. Many -of the manpages are customized to your configuration as part of the -build process, so we recommend building Open vSwitch before reading -the manpages. - -Contact -------- - -bugs@openvswitch.org - -[INSTALL.rst]:INSTALL.rst -[INSTALL.Debian.rst]:INSTALL.Debian.rst -[INSTALL.Docker.rst]:INSTALL.Docker.rst -[INSTALL.DPDK.rst]:INSTALL.DPDK.rst -[INSTALL.Fedora.md]:INSTALL.Fedora.md -[INSTALL.KVM.rst]:INSTALL.KVM.rst -[INSTALL.Libvirt.md]:INSTALL.Libvirt.md -[INSTALL.RHEL.md]:INSTALL.RHEL.md -[INSTALL.SELinux.md]:INSTALL.SELinux.md -[INSTALL.SSL.md]:INSTALL.SSL.md -[INSTALL.userspace.rst]:INSTALL.userspace.rst -[INSTALL.XenServer.rst]:INSTALL.XenServer.rst -[FAQ.md]:FAQ.md -[tutorial/Tutorial.md]:tutorial/Tutorial.md diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b96ba1c --- /dev/null +++ b/README.rst @@ -0,0 +1,116 @@ +============ +Open vSwitch +============ + +Build Status +------------ + +.. image:: https://travis-ci.org/openvswitch/ovs.png + :target: https://travis-ci.org/openvswitch/ovs + +What is Open vSwitch? +--------------------- + +Open vSwitch is a multilayer software switch licensed under the open source +Apache 2 license. Our goal is to implement a production quality switch +platform that supports standard management interfaces and opens the forwarding +functions to programmatic extension and control. + +Open vSwitch is well suited to function as a virtual switch in VM environments. +In addition to exposing standard control and visibility interfaces to the +virtual networking layer, it was designed to support distribution across +multiple physical servers. Open vSwitch supports multiple Linux-based +virtualization technologies including Xen/XenServer, KVM, and VirtualBox. + +The bulk of the code is written in platform-independent C and is easily ported +to other environments. The current release of Open vSwitch supports the +following features: + +- Standard 802.1Q VLAN model with trunk and access ports +- NIC bonding with or without LACP on upstream switch +- NetFlow, sFlow(R), and mirroring for increased visibility +- QoS (Quality of Service) configuration, plus policing +- Geneve, GRE, VXLAN, STT, and LISP tunneling +- 802.1ag connectivity fault management +- OpenFlow 1.0 plus numerous extensions +- Transactional configuration database with C and Python bindings +- High-performance forwarding using a Linux kernel module + +The included Linux kernel module supports Linux 3.10 and up. + +Open vSwitch can also operate, at a cost in performance, entirely in userspace, +without assistance from a kernel module. This userspace implementation should +be easier to port than the kernel-based switch. It is considered experimental. + +What's here? +------------ + +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-dpctl, a tool for configuring the switch kernel module. +- Scripts and specs for building RPMs for Citrix XenServer and Red Hat + Enterprise Linux. The XenServer RPMs allow Open vSwitch to be installed on a + Citrix XenServer host as a drop-in replacement for its switch, with + additional functionality. +- ovs-vsctl, a utility for querying and updating the configuration of + ovs-vswitchd. +- ovs-appctl, a utility that sends commands to running Open vSwitch daemons. + +Open vSwitch also provides some tools: + +- ovs-ofctl, a utility for querying and controlling OpenFlow switches and + controllers. +- ovs-pki, a utility for creating and managing the public-key infrastructure + for OpenFlow switches. +- ovs-testcontroller, a simple OpenFlow controller that may be useful for + testing (though not for production). +- A patch to tcpdump that enables it to parse OpenFlow messages. + +What other documentation is available? +-------------------------------------- + +To install Open vSwitch on a regular Linux or FreeBSD host, please read the +`installation guide `__. For specifics around installation on a +specific platform, please see one of the below installation guides: + +- `Debian `__ +- `Fedora `__ +- `RHEL `__ +- `XenServer `__ +- `Windows `__. + +- ...with KVM on Linux, see `here `__ and `here + `__. + +- ...with Libvirt, see `here `__. + +- ...without using a kernel module, see `here `__. + +- ...with DPDK, see `here `__. + +- ...with SELinux, see `here `__. + +For answers to common questions, refer to the `FAQ `__. + +To learn how to set up SSL support for Open vSwitch, see `here +`__. + +To learn about some advanced features of the Open vSwitch software switch, read +the `tutorial `__. + +Each Open vSwitch userspace program is accompanied by a manpage. Many of the +manpages are customized to your configuration as part of the build process, so +we recommend building Open vSwitch before reading the manpages. + +Contact +------- + +bugs@openvswitch.org diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in index 25aae00..d3b03e1 100644 --- a/rhel/openvswitch-fedora.spec.in +++ b/rhel/openvswitch-fedora.spec.in @@ -478,7 +478,7 @@ fi %{_mandir}/man8/ovs-vswitchd.8* %{_mandir}/man8/ovs-parse-backtrace.8* %{_mandir}/man8/ovs-testcontroller.8* -%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md +%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md %doc FAQ.md NEWS INSTALL.DPDK.rst rhel/README.RHEL /var/lib/openvswitch /var/log/openvswitch diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index c260a00..1b4c757 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -247,7 +247,7 @@ exit 0 /usr/share/openvswitch/scripts/sysconfig.template /usr/share/openvswitch/vswitch.ovsschema /usr/share/openvswitch/vtep.ovsschema -%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md FAQ.md NEWS +%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md FAQ.md NEWS %doc INSTALL.DPDK.rst rhel/README.RHEL README-native-tunneling.md /var/lib/openvswitch /var/log/openvswitch diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8 index 6b8fba7..ca14e53 100644 --- a/utilities/ovs-ctl.8 +++ b/utilities/ovs-ctl.8 @@ -502,5 +502,5 @@ distribution are good examples of how to use \fBovs\-ctl\fR. . .SH "SEE ALSO" . -\fBREADME.md\fR, \fBINSTALL.Linux.md\fR, \fBovsdb\-server\fR(8), +\fBREADME.rst\fR, \fBINSTALL.Linux.md\fR, \fBovsdb\-server\fR(8), \fBovs\-vswitchd\fR(8).