From patchwork Sat Oct 1 19:01:34 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 677413 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 3smd3T1vhmz9s3s for ; Sun, 2 Oct 2016 06:02:29 +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=M8/iMVUE; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id BA487108D3; Sat, 1 Oct 2016 12:02:05 -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 0D950108BA for ; Sat, 1 Oct 2016 12:02:05 -0700 (PDT) Received: from bar6.cudamail.com (localhost [127.0.0.1]) by mx3v3.cudamail.com (Postfix) with ESMTPS id 9A34F1629A4 for ; Sat, 1 Oct 2016 13:02:04 -0600 (MDT) X-ASG-Debug-ID: 1475348519-0b323746cd1257b0001-byXFYA Received: from mx3-pf1.cudamail.com ([192.168.14.2]) by bar6.cudamail.com with ESMTP id Nwqo6WKzE04A02ir (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 01 Oct 2016 13:01:59 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.2 Received: from unknown (HELO nov-007-i630.relay.mailchannels.net) (46.232.183.184) by mx3-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 1 Oct 2016 19:01:56 -0000 Received-SPF: none (mx3-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 46.232.183.184 X-Barracuda-RBL-IP: 46.232.183.184 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 2C6AA20BB7 for ; Sat, 1 Oct 2016 19:01:50 +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 71B862096E for ; Sat, 1 Oct 2016 19:01:49 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.135.9.54]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sat, 01 Oct 2016 19:01:50 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1475348509807:2424138814 X-MC-Ingress-Time: 1475348509807 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=LHZGutwqw/sB4BgSlpcQdouSzfVSLUJEUSLS6OKqD1k=; b=M8/iMVUE0kBJv31H8u5mc+arkZ fAXlzQIcl827c4NHV1cu1qacCLzmFtDFrzDi35t0EAidg7I6rt/k8x3z994XemNfDCAY6QZgkV5q/ IRVUvH678TyVAozCzogNrll9F7X9RLD2D1aC/J7oLMs5r7t5xEBykD03Ofd3RJN/BKF4UqhHNfBtU lNMK1hAAnCViXISu4xSTQp950FBc4IP1IRTGRPjI/c4mNws7KbiCMbMMDiXSuXt+FP7CxlPZGfuqK WxyfdOVKGTy9xdSmQCYIiiF5p9YSdlaaiLzNj2ITVyAhSR7Nn8T8ZQ5ycLfXasdkM8gI2MVBpJj3c e7oyeBTA==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-V1-930014150 X-CudaMail-DTE: 100116 X-CudaMail-Originating-IP: 46.232.183.184 Date: Sat, 1 Oct 2016 20:01:34 +0100 X-ASG-Orig-Subj: [##CM-V1-930014150##][RFC 5/5] doc: Convert README to rST Message-Id: <1475348494-23944-6-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1475348494-23944-1-git-send-email-stephen@that.guru> References: <1475348494-23944-1-git-send-email-stephen@that.guru> X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 46.232.183.184, Ugly c=0 p=0 Source New X-MessageSniffer-Rules: 0-0-0-29360-c X-Barracuda-Connect: UNKNOWN[192.168.14.2] X-Barracuda-Start-Time: 1475348519 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA 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.60 X-Barracuda-Spam-Status: No, SCORE=1.60 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_RULE7568M, BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.33386 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.50 BSF_RULE7568M Custom Rule 7568M 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] [RFC 5/5] 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" This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- This is the first time we completely replace a Markdown file with its reStructuredText equivalent. How will this affect the 'dist-docs' target? --- Documentation/install-guide/general.rst | 2 +- INSTALL.md | 4 +- Makefile.am | 2 +- README.md | 131 -------------------------------- README.rst | 115 ++++++++++++++++++++++++++++ rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in | 2 +- utilities/ovs-ctl.8 | 2 +- 8 files changed, 122 insertions(+), 138 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/Documentation/install-guide/general.rst b/Documentation/install-guide/general.rst index e003563..cd3c4d5 100644 --- a/Documentation/install-guide/general.rst +++ b/Documentation/install-guide/general.rst @@ -86,7 +86,7 @@ details). To compile the kernel module on Linux, you must also install the following: -- A supported Linux kernel version. Refer to the `README <../../README.md>`__ +- A supported Linux kernel version. Refer to the `README <../../README.rst>`__ for a list of supported versions. For optional support of ingress policing, you must enable kernel diff --git a/INSTALL.md b/INSTALL.md index 36ecfb8..59cf762 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -60,7 +60,7 @@ at some cost in features and performance (see [INSTALL.userspace.md] for details). To compile the kernel module on Linux, you must also install the following: - - A supported Linux kernel version. Please refer to [README.md] for a + - A supported Linux kernel version. Please refer to [README] for a list of supported versions. For optional support of ingress policing, you must enable kernel @@ -811,7 +811,7 @@ Bug Reporting Please report problems to bugs@openvswitch.org. -[README.md]:README.md +[README]:README.rst [INSTALL.Debian.md]:INSTALL.Debian.md [INSTALL.Fedora.md]:INSTALL.Fedora.md [INSTALL.RHEL.md]:INSTALL.RHEL.md diff --git a/Makefile.am b/Makefile.am index 724a893..e05b1b1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -89,7 +89,7 @@ docs = \ MAINTAINERS.md \ OPENFLOW-1.1+.md \ PORTING.md \ - 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 53b0faf..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.md]. For specifics around installation on a specific -platform, please see one of these files: - -- [INSTALL.Debian.md] -- [INSTALL.Fedora.md] -- [INSTALL.RHEL.md] -- [INSTALL.XenServer.md] - -To use Open vSwitch... - -- ...with Docker on Linux, read [INSTALL.Docker.md] - -- ...with KVM on Linux, read [INSTALL.md], read [INSTALL.KVM.md] - -- ...with Libvirt, read [INSTALL.Libvirt.md]. - -- ...without using a kernel module, read [INSTALL.userspace.md]. - -- ...with DPDK, read [INSTALL.DPDK.md]. - -- ...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.md]:INSTALL.md -[INSTALL.Debian.md]:INSTALL.Debian.md -[INSTALL.Docker.md]:INSTALL.Docker.md -[INSTALL.DPDK.md]:INSTALL.DPDK.md -[INSTALL.Fedora.md]:INSTALL.Fedora.md -[INSTALL.KVM.md]:INSTALL.KVM.md -[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.md]:INSTALL.userspace.md -[INSTALL.XenServer.md]:INSTALL.XenServer.md -[FAQ.md]:FAQ.md -[tutorial/Tutorial.md]:tutorial/Tutorial.md diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..7cdb485 --- /dev/null +++ b/README.rst @@ -0,0 +1,115 @@ +============ +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 `__ + +To use Open vSwitch... + +- ...with Docker on Linux, see `here `__. + +- ...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 eda8767..42463b4 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.md rhel/README.RHEL /var/lib/openvswitch /var/log/openvswitch diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 0ef0b04..34b279b 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.md 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).