Adjusted titles

Updated according to comments and added the SFC feature configuration as
template under release/configguide.
Adjusted all titles so they are handled through the index file.

Change-Id: Icb0339fb19394940dc969725ddfe0420cb547955
Signed-off-by: Sofia Wallin <sofia.wallin@ericsson.com>

11 files changed, 320 insertions, 59 deletions

diff --git a/docs/templates/release/configguide/feature.configuration.rst b/docs/templates/release/configguide/feature.configuration.rst
new file mode 100644
index 000000000..e2fcbbb08
--- /dev/null
+++ b/docs/templates/release/configguide/feature.configuration.rst
@@ -0,0 +1,256 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) Ferenc Cserepkei, Brady Allen Johnson, Manuel Buil and others
+
+Abstract
+========
+This document provides information on how to install the OpenDayLigh SFC
+features in OPNFV with the use of os_odl-l2_sfc-(no)ha scenario.
+
+SFC feature desciription
+========================
+For details of the scenarios and their provided capabilities refer to
+the scenario description documents:
+
+- http://artifacts.opnfv.org/sfc/colorado/docs/scenarios_os-odl_l2-sfc-ha/index.html
+
+- http://artifacts.opnfv.org/sfc/colorado/docs/scenarios_os-odl_l2-sfc-noha/index.html
+
+
+The SFC feature enables creation of Service Fuction Chains - an ordered list
+of chained network funcions (e.g. firewalls, NAT, QoS)
+
+The SFC feature in OPNFV is implemented by 3 major components:
+
+- OpenDayLight SDN controller
+
+- Tacker: Generic VNF Manager (VNFM) and a NFV Orchestrator (NFVO)
+
+- OpenvSwitch: The Service Function Forwarder(s)
+
+Hardware requirements
+=====================
+
+The SFC scenarios can be deployed on a bare-metal OPNFV cluster or on a
+virtual environment on a single host.
+
+Bare metal deployment on (OPNFV) Pharos lab
+-------------------------------------------
+Hardware requirements for bare-metal deployments of the OPNFV infrastructure
+are given by the Pharos project. The Pharos project provides an OPNFV
+hardware specification for configuring your hardware:
+http://artifacts.opnfv.org/pharos/docs/pharos-spec.html
+
+
+Virtual deployment
+------------------
+To perform a virtual deployment of an OPNFV SFC scenario on a single host,
+that host has to meet the following hardware requirements:
+
+- SandyBridge compatible CPU with virtualization support
+
+- capable to host 5 virtual cores (5 physical ones at least)
+
+- 8-12 GBytes RAM for virtual hosts (controller, compute), 48GByte at least
+
+- 128 GiBiBytes room on disk for each virtual host (controller, compute) +
+  64GiBiBytes for fuel master, 576 GiBiBytes at least
+
+- Ubuntu Trusty Tahr - 14.04(.5) server operating system with at least ssh
+  service selected at installation.
+
+- Internet Connection (preferably http proxyless)
+
+
+Pre-configuration activites - Preparing the host to install Fuel by script
+==========================================================================
+.. Not all of these options are relevant for all scenario's.  I advise following the
+.. instructions applicable to the deploy tool used in the scenario.
+
+Before starting the installation of the SFC scenarios some preparation of the
+machine that will host the Colorado Fuel cluster must be done.
+
+Installation of required packages
+---------------------------------
+To be able to run the installation of the basic OPNFV fuel installation the
+Jumphost (or the host which serves the VMs for the virtual deployment) needs to
+install the following packages:
+::
+
+ sudo apt-get install -y git make curl libvirt-bin libpq-dev qemu-kvm \
+                         qemu-system tightvncserver virt-manager sshpass \
+                         fuseiso genisoimage blackbox xterm python-pip \
+                         python-git python-dev python-oslo.config \
+                         python-pip python-dev libffi-dev libxml2-dev \
+                         libxslt1-dev libffi-dev libxml2-dev libxslt1-dev \
+                         expect curl python-netaddr p7zip-full
+
+ sudo pip install GitPython pyyaml netaddr paramiko lxml scp \
+                  scp pycrypto ecdsa debtcollector netifaces enum
+
+During libvirt install the user is added to the libvirtd group, so you have to
+logout then login back again
+
+
+Download the installer source code and artifact
+-----------------------------------------------
+To be able to install the scenario os_odl-l2_sfc-(no)ha one can follow the way
+CI is deploying the scenario.
+First of all the opnfv-fuel repository needs to be cloned:
+::
+
+ git clone -b 'stable/colorado' ssh://<user>@gerrit.opnfv.org:29418/fuel
+
+This command copies the whole colorado branch of repository fuel.
+
+Now download the appropriate OPNFV Fuel ISO into an appropriate folder:
+::
+
+ wget http://artifacts.opnfv.org/fuel/colorado/opnfv-colorado.1.0.iso
+
+The exact name of the ISO image may change.
+Check https://www.opnfv.org/opnfv-colorado-fuel-users to get the latest ISO.
+
+Simplified scenario deployment procedure using Fuel
+===================================================
+
+This section describes the installation of the os-odl-l2_sfc or
+os-odl-l2_sfc-noha OPNFV reference platform stack across a server cluster
+or a single host as a virtual deployment.
+
+Scenario Preparation
+--------------------
+dea.yaml and dha.yaml need to be copied and changed according to the
+lab-name/host where you deploy.
+Copy the full lab config from:
+::
+
+ cp -r <path-to-opnfv-fuel-repo>/deploy/config/labs/devel-pipeline/elx \
+    <path-to-opnfv-fuel-repo>/deploy/config/labs/devel-pipeline/<your-lab-name>
+
+Add at the bottom of dha.yaml
+::
+
+ disks:
+   fuel: 64G
+   controller: 128G
+   compute: 128G
+
+ define_vms:
+   controller:
+     vcpu:
+       value: 2
+     memory:
+       attribute_equlas:
+         unit: KiB
+       value: 12521472
+     currentMemory:
+       attribute_equlas:
+         unit: KiB
+       value: 12521472
+   compute:
+     vcpu:
+       value: 2
+     memory:
+       attribute_equlas:
+         unit: KiB
+       value: 8388608
+     currentMemory:
+       attribute_equlas:
+         unit: KiB
+       value: 8388608
+   fuel:
+     vcpu:
+       value: 2
+     memory:
+       attribute_equlas:
+         unit: KiB
+       value: 2097152
+     currentMemory:
+       attribute_equlas:
+         unit: KiB
+       value: 2097152
+
+Check if the default settings in dea.yaml are in line with your intentions
+and make changes as required.
+
+Installation procedures
+-----------------------
+
+We state here several alternatives.
+First, we describe methods that are based on the use of the deploy.sh script,
+what is used by the OPNFV CI system and can be found in the Fuel repository.
+
+In addition, the SFC feature can also be configured manually in the Fuel GUI
+what we will show in the last subsection.
+
+Before starting any of the following procedures, go to
+::
+
+ cd <opnfv-fuel-repo>/ci
+
+Full automatic virtual deployment, High Availablity mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example will deploy the high-availability flavor of SFC scenario
+os_odl-l2_sfc-ha in a fully automatic way, i.e. all installation steps
+(Fuel server installation, configuration, node discovery and platform
+deployment) will take place without any further prompt for user input.
+::
+
+ sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name>
+ -s os_odl-l2_sfc-ha -i file://<path-to-fuel-iso>
+
+Full automatic virtual deployment, non HIGH Availablity mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following command will deploy the SFC scenario with non-high-availability
+flavor (note the  different scenario name for the -s switch). Otherwise it
+does the same as described above.
+::
+
+ sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name>
+ -s os_odl-l2_sfc-noha -i file://<path-to-fuel-iso>
+
+Automatic Fuel installation and manual scenario deployment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A useful alternative to the full automatic procedure is to only deploy the Fuel host and to run host selection, role assignment and SFC scenario configuration manually.
+::
+
+ sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> -s os_odl-l2_sfc-ha -i file://<path-to-fuel-iso> -e
+
+With -e option the installer will skip environment deployment, so an user
+can do some modification before the scenario is really deployed. Another
+useful option is the -f option which deploys the scenario using an existing
+Fuel host.
+
+The result of this installation is a well configured Fuel sever. The use of
+the deploy button on Fuel dashboard can initiate the deployment. A user may
+perform manual post-configuration as well.
+
+Feature configuration on existing Fuel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a Fuel server is already provisioned but the fuel plugins for Opendaylight,
+Openvswitch are not provided install them by:
+::
+
+ cd /opt/opnfv/
+ fuel plugins --install fuel-plugin-ovs-*.noarch.rpm
+ fuel plugins --install opendaylight-*.noarch.rpm
+
+If plugins are installed and you want to update them use --force flag.
+
+Note that One may inject other - Colorado compatible - plugins to the Fuel
+Master host using the command scp:
+
+scp <plugin>.rpm root@10.20.0.2:<plugin>.rpm
+
+Now the feature can be configured. Create a new environment with
+Networking Setup:"OpenDayLight with tunneling segmentation". Then go to
+settings/other and check "OpenDaylight plugin, SFC enabled",
+"Install Openvswitch with NSH/DPDK, with NSH enabled". During node provision
+remember assign the OpenDayLight role to the (primary)controller
+
+Now the deploy button on fuel dashboard can be used to deploy the environment.
diff --git a/docs/templates/release/configguide/featureconfig.rst b/docs/templates/release/configguide/featureconfig.rst
index 8c063f06d..287715d4a 100644
--- a/docs/templates/release/configguide/featureconfig.rst
+++ b/docs/templates/release/configguide/featureconfig.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-========================
-<Project> Configuration
-========================
+========
+Abstract
+========
 Add a brief introduction to configure OPNFV with this specific feature including
 dependancies on platform components, this description should be at a level that
 will apply to any installer providing the pre-requisite components.
@@ -13,18 +13,20 @@ will apply to any installer providing the pre-requisite components.
    :local:
 
 Pre-configuration activities
-----------------------------
+============================
 Describe specific pre-configuration activities. This should include ensuring the
 right components are installed by the installation tools as required for your
 feature to function.  Refer to the previous installer configuration chapters,
 installations guide and release notes
 
+
 Hardware configuration
-----------------------
+======================
 Describe the hardware configuration needed for this specific feature
 
+
 Feature configuration
----------------------
+=====================
 Describe the procedures to configure your feature on the platform in order
 that it is ready to use according to the feature instructions in the platform
 user guide.  Where applicable you should add content in the postinstall.rst
diff --git a/docs/templates/release/configguide/index.rst b/docs/templates/release/configguide/index.rst
index 9c940eb1a..1789179d8 100644
--- a/docs/templates/release/configguide/index.rst
+++ b/docs/templates/release/configguide/index.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-=========================================================
-OPNFV <Project Name> Configuration Guide
-=========================================================
+**********************************
+<Project Name> Configuration Guide
+**********************************
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/templates/release/configguide/postinstall.rst b/docs/templates/release/configguide/postinstall.rst
index daca1ff51..59a20c6b0 100644
--- a/docs/templates/release/configguide/postinstall.rst
+++ b/docs/templates/release/configguide/postinstall.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-=======================================
+*************************************
 <Project> Post Installation Procedure
-=======================================
+*************************************
 
 Add a brief introduction to the methods of validating the installation
 according to this specific installer or feature.
@@ -12,8 +12,9 @@ according to this specific installer or feature.
    :depth: 3
    :local:
 
+
 Automated post installation activities
-----------------------------------------
+======================================
 Describe specific post installation activities performed by the OPNFV
 deployment pipeline including testing activities and reports. Refer to
 the relevant testing guides, results, and release notes.
@@ -23,13 +24,15 @@ once we have one test suite to run for all deploy tools.  This is not the
 case yet so each deploy tool will need to provide (hopefully very simillar)
 documentation of this.
 
+
 <Project> post configuration procedures
------------------------------------------
+=======================================
 Describe any deploy tool or feature specific scripts, tests or procedures
 that should be carried out on the deployment post install and configuration
 in this section.
 
+
 Platform components validation
----------------------------------
+==============================
 Describe any component specific validation procedures necessary for your
 deployment tool in this section.
diff --git a/docs/templates/release/installation/index.rst b/docs/templates/release/installation/index.rst
index fe0134112..3dbb7c596 100644
--- a/docs/templates/release/installation/index.rst
+++ b/docs/templates/release/installation/index.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-==================================================
-OPNFV <Project Name> Installation
-==================================================
+***************************************
+<Project Name> Installation Instruction
+***************************************
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/templates/release/installation/installation.instruction.rst b/docs/templates/release/installation/installation.instruction.rst
index c9476095e..449f25f93 100644
--- a/docs/templates/release/installation/installation.instruction.rst
+++ b/docs/templates/release/installation/installation.instruction.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-=========================================
-OPNFV <Project Name> Installation Guide
-=========================================
+========
+Abstract
+========
 
 This document describes how to install <Component>, it's dependencies and required system resources.
 
@@ -29,8 +29,9 @@ Version history
 |                    |                    |                    |                    |
 +--------------------+--------------------+--------------------+--------------------+
 
+
 Introduction
--------------------
+============
 <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
 
 <EXAMPLE>:
@@ -46,8 +47,9 @@ a result that is OPNFV compliant.
 
 The audience of this document is assumed to have good knowledge in network and Unix/Linux administration.
 
+
 Preface
--------------
+=======
 <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
 
 <EXAMPLE>:
@@ -81,8 +83,9 @@ Secondly, a number of deployment specific parameters must be collected, those ar
 
 This information will be needed for the configuration procedures provided in this document.
 
+
 Hardware requirements
-------------------------
+=====================
 <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
 
 <EXAMPLE>:
@@ -115,8 +118,9 @@ Following minimum hardware requirements must be met for installation of Fuel@OPN
 |                    |                                                    |
 +--------------------+----------------------------------------------------+
 
+
 Top of the rack (TOR) Configuration requirements
----------------------------------------------------
+================================================
 <DESCRIBE NEEDED NETWORK TOPOLOGY SETUP IN THE TORs>
 
 <EXAMPLE>:
@@ -139,8 +143,9 @@ VLAN considerations and blue-print
 IP Address plan considerations and blue-print
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+
 OPNFV Software installation and deployment
---------------------------------------------
+==========================================
 <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE OPNFV COMPONENT INSTALLATION AND DEPLOYMENT>
 
 <EXAMPLE>:
@@ -161,8 +166,9 @@ Configure the OPNFV environment
 Deploy the OPNFV environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+
 Installation health-check
----------------------------
+=========================
 <DESCRIBE ANY MEANS TO DO VERIFY THE INTEGRITY AND HEALTHYNESS OF THE INSTALL>
 
 <EXAMPLE>:
@@ -187,8 +193,9 @@ for the system to work according OPNFV standards.
 **Change host OS password:**
 Change the Host OS password by......
 
+
 References
--------------
+==========
 <PROVIDE NEEDED/USEFUL REFERENCES>
 
 <EXAMPLES>:
diff --git a/docs/templates/release/release-notes/index.rst b/docs/templates/release/release-notes/index.rst
index a0759f77f..e703944ef 100644
--- a/docs/templates/release/release-notes/index.rst
+++ b/docs/templates/release/release-notes/index.rst
@@ -1,9 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-==================================================
-OPNFV <Project Name> Release Notes
-==================================================
+****************************
+<Project Name> Release Notes
+****************************
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/templates/release/release-notes/release-notes.rst b/docs/templates/release/release-notes/release-notes.rst
index ad6759b08..ead095cc3 100644
--- a/docs/templates/release/release-notes/release-notes.rst
+++ b/docs/templates/release/release-notes/release-notes.rst
@@ -1,9 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-======================================================================
-OPNFV <Project Name> Release Notes
-======================================================================
 
 This document provides the release notes for <RELEASE> of <COMPONENT>.
 
@@ -13,7 +10,7 @@ This document provides the release notes for <RELEASE> of <COMPONENT>.
 
 
 Version history
-------------------
+---------------
 
 +--------------------+--------------------+--------------------+--------------------+
 | **Date**           | **Ver.**           | **Author**         | **Comment**        |
@@ -30,7 +27,7 @@ Version history
 +--------------------+--------------------+--------------------+--------------------+
 
 Important notes
------------------
+===============
 
 <STATE IMPORTANT NOTES/DEVIATIONS SINCE PREVIOUS ITERATIVE RELEASE AND OTHER IMPORTANT NOTES FOR THIS RELEASE>
 
@@ -39,8 +36,9 @@ Important notes
 **Attention:** Please be aware that since LSV3 a pre-deploy script must be ran on the Fuel master -
 see the OPNFV@Fuel SW installation instructions
 
+
 Summary
-------------
+=======
 
 <SUMMARIZE THE RELEASE - THE CONTENT - AND OTHER IMPORTANT HIGH LEVEL PROPERTIES>
 
@@ -49,8 +47,9 @@ Summary
 Arno Fuel@OPNFV is based the OpenStack Fuel upstream project version 6.0.1,
 but adds OPNFV unique components such as OpenDaylight version: Helium as well as other OPNFV unique configurations......
 
+
 Release Data
----------------
+============
 <STATE RELEVANT RELEASE DATA/RECORDS>
 
 <EXAMPLE>:
@@ -147,8 +146,9 @@ Documentation deliverables
 
 <EXAMPLE>:
 
+
 Known Limitations, Issues and Workarounds
---------------------------------------------
+=========================================
 
 System Limitations
 ^^^^^^^^^^^^^^^^^^^^
@@ -198,7 +198,7 @@ Workarounds
 - In case the disk is full on a controller - delete all files in /tmp
 
 Test Result
----------------
+===========
 <STATE THE QA COVERAGE AND RESULTS>
 
 <EXAMPLE>:
@@ -223,7 +223,7 @@ Fuel@OPNFV Arno RC2 has undergone QA test runs with the following results:
 +--------------------------------------+--------------------------------------+
 
 References
-------------
+==========
 <STATE RELEVANT REFERENCES FOR THIS RELEASE/VERSION>
 
 <EXAMPLE>:
diff --git a/docs/templates/release/scenarios/scenario.name/index.rst b/docs/templates/release/scenarios/scenario.name/index.rst
index 7487e63bd..37aab8458 100644
--- a/docs/templates/release/scenarios/scenario.name/index.rst
+++ b/docs/templates/release/scenarios/scenario.name/index.rst
@@ -2,9 +2,9 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) <optionally add copywriters name>
 
-==================
-<scenario name>
-==================
+****************************************
+<scenario name> overview and description
+****************************************
 .. This document will be used to provide a description of the scenario for an end user.
 .. You should explain the purpose of the scenario, the types of capabilities provided and
 ..  the unique components that make up the scenario including how they are used.
diff --git a/docs/templates/release/scenarios/scenario.name/scenario.description.rst b/docs/templates/release/scenarios/scenario.name/scenario.description.rst
index 9c45b7da4..8c2cbabd1 100644
--- a/docs/templates/release/scenarios/scenario.name/scenario.description.rst
+++ b/docs/templates/release/scenarios/scenario.name/scenario.description.rst
@@ -2,40 +2,37 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) <optionally add copywriters name>
 
-=========================
-OPNFV <Scenario Name>
-=========================
-
 This document provides scenario level details for <RELEASE> of <COMPONENT>.
 
 .. contents::
    :depth: 3
    :local:
 
+============
 Introduction
----------------
+============
 .. In this section explain the purpose of the scenario and the types of capabilities provided
 
 Scenario components and composition
--------------------------------------
+===================================
 .. In this section describe the unique components that make up the scenario,
 .. what each component provides and why it has been included in order
 .. to communicate to the user the capabilities available in this scenario.
 
 Scenario usage overview
-----------------------------
+=======================
 .. Provide a brief overview on how to use the scenario and the features available to the
 .. user.  This should be an "introduction" to the userguide document, and explicitly link to it,
 .. where the specifics of the features are covered including examples and API's
 
 Limitations, Issues and Workarounds
----------------------------------------
+===================================
 .. Explain scenario limitations here, this should be at a design level rather than discussing
 .. faults or bugs.  If the system design only provide some expected functionality then provide
 .. some insight at this point.
 
 References
------------------
+==========
 
 For more information on the OPNFV Danube release, please visit
 http://www.opnfv.org/danube
diff --git a/docs/templates/release/userguide/feature.userguide.rst b/docs/templates/release/userguide/feature.userguide.rst
index 733c2f99a..1d54d0ec7 100644
--- a/docs/templates/release/userguide/feature.userguide.rst
+++ b/docs/templates/release/userguide/feature.userguide.rst
@@ -2,26 +2,22 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) <optionally add copywriters name>
 
-===================================
-OPNFV <Project Name> User Guide
-===================================
-
 .. contents::
    :depth: 3
    :local:
 
 <Feature> description
-------------------------
+=====================
 .. Describe the specific features and how it is realised in the scenario in a brief manner
 .. to ensure the user understand the context for the user guide instructions to follow.
 
 <Feature> capabilities and usage
-------------------------------------
+================================
 .. Describe the specific capabilities and usage for <XYZ> feature.
 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 
 <Feature and API usage guidelines and example>
------------------------------------------------
+==============================================
 .. Describe with examples how to use specific features, provide API examples and details required to
 .. operate the feature on the platform.