summaryrefslogtreecommitdiffstats
path: root/docs/development
diff options
context:
space:
mode:
Diffstat (limited to 'docs/development')
-rw-r--r--docs/development/feature.templates/scenarios/scenario.name/index.rst16
-rw-r--r--docs/development/feature.templates/scenarios/scenario.name/scenario.description.rst32
-rw-r--r--docs/development/feature.templates/userguide/feature.userguide.rst19
-rw-r--r--docs/development/feature.templates/userguide/index.rst23
-rw-r--r--docs/development/opnfvsecguide/_static/temp0
-rw-r--r--docs/development/opnfvsecguide/_templates/temp0
-rw-r--r--docs/development/opnfvsecguide/audit.rst9
-rw-r--r--docs/development/opnfvsecguide/audit/audit_reqs.rst110
-rw-r--r--docs/development/opnfvsecguide/compute.rst8
-rw-r--r--docs/development/opnfvsecguide/compute/dacmaccontrols.rst3
-rw-r--r--docs/development/opnfvsecguide/compute/trust.rst124
-rw-r--r--docs/development/opnfvsecguide/contribution.rst45
-rw-r--r--docs/development/opnfvsecguide/getting_started.rst41
-rw-r--r--docs/development/opnfvsecguide/index.rst21
-rw-r--r--docs/development/opnfvsecguide/introduction.rst15
-rw-r--r--docs/development/opnfvsecguide/introduction/acknowledgements.rst3
-rw-r--r--docs/development/opnfvsecguide/introduction/background.rst38
-rw-r--r--docs/development/opnfvsecguide/network.rst8
-rw-r--r--docs/development/opnfvsecguide/network/neutron.rst2
-rw-r--r--docs/development/scenario/featurematrix.rst39
-rw-r--r--docs/development/scenario/scenariointro.rst13
-rw-r--r--docs/development/scenario/scenariomatrix.rst100
-rw-r--r--docs/development/scenario/scenariovalidation.rst0
23 files changed, 669 insertions, 0 deletions
diff --git a/docs/development/feature.templates/scenarios/scenario.name/index.rst b/docs/development/feature.templates/scenarios/scenario.name/index.rst
new file mode 100644
index 000000000..59ada34e9
--- /dev/null
+++ b/docs/development/feature.templates/scenarios/scenario.name/index.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+===================================
+<scenario> 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.
+
+.. toctree::
+ :maxdepth: 3
+
+ ./scenario.description.rst
+
diff --git a/docs/development/feature.templates/scenarios/scenario.name/scenario.description.rst b/docs/development/feature.templates/scenarios/scenario.name/scenario.description.rst
new file mode 100644
index 000000000..afd587915
--- /dev/null
+++ b/docs/development/feature.templates/scenarios/scenario.name/scenario.description.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+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 Colorado release, please visit
+http://www.opnfv.org/colorado
+
diff --git a/docs/development/feature.templates/userguide/feature.userguide.rst b/docs/development/feature.templates/userguide/feature.userguide.rst
new file mode 100644
index 000000000..b8adfa592
--- /dev/null
+++ b/docs/development/feature.templates/userguide/feature.userguide.rst
@@ -0,0 +1,19 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+<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.
+
diff --git a/docs/development/feature.templates/userguide/index.rst b/docs/development/feature.templates/userguide/index.rst
new file mode 100644
index 000000000..cc84670fc
--- /dev/null
+++ b/docs/development/feature.templates/userguide/index.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+====================
+<feature> user guide
+====================
+
+.. The feature user guide should provide an OPNFV user with enough information to
+.. use the features provided by the feature project in the supported scenarios.
+.. This guide should walk a user through the usage of the features once a scenario
+.. has been deployed and is active according to the installation guide provided
+.. by the installer project.
+
+.. toctree::
+ :maxdepth: 3
+
+.. The feature.userguide.rst file should contain the text for this document
+.. additional documents can be added to this directory and added in the right order
+.. to this file as a list below.
+
+ ./feature.userguide.rst
+
diff --git a/docs/development/opnfvsecguide/_static/temp b/docs/development/opnfvsecguide/_static/temp
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/development/opnfvsecguide/_static/temp
diff --git a/docs/development/opnfvsecguide/_templates/temp b/docs/development/opnfvsecguide/_templates/temp
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/development/opnfvsecguide/_templates/temp
diff --git a/docs/development/opnfvsecguide/audit.rst b/docs/development/opnfvsecguide/audit.rst
new file mode 100644
index 000000000..cdeecba60
--- /dev/null
+++ b/docs/development/opnfvsecguide/audit.rst
@@ -0,0 +1,9 @@
+Audit
+----------------
+
+.. toctree::
+ :maxdepth: 2
+
+ audit/audit_reqs
+ audit/configuring
+
diff --git a/docs/development/opnfvsecguide/audit/audit_reqs.rst b/docs/development/opnfvsecguide/audit/audit_reqs.rst
new file mode 100644
index 000000000..ce76d016b
--- /dev/null
+++ b/docs/development/opnfvsecguide/audit/audit_reqs.rst
@@ -0,0 +1,110 @@
+Requirements references related to OPNFV Audit
+
+------------------
+Source information
+------------------
+
+http://www.etsi.org/deliver/etsi_gs/NFV-INF/001_099/003/01.01.01_60/gs_NFV-INF003v010101p.pdf
+http://www.etsi.org/deliver/etsi_gs/NFV-INF/001_099/004/01.01.01_60/gs_NFV-INF004v010101p.pdf
+
+* ETSI GS NFV-SEC 003 V1.1.1 (2014-12)
+
+ - Network Functions Virtualisation NFV);
+ - NFV Security; Security and Trust Guidance
+ - NFV-SEC-003_.
+
+
+.. _NFV-SEC-003: http://www.etsi.org/deliver/etsi_gs/NFV-SEC/001_099/003/01.01.01_60/gs_NFV-SEC003v010101p.pdf
+* ETSI GS NFV 004 V1.1.1 (2013-10)
+
+ - Network Functions Virtualisation (NFV);
+ - Virtualisation Requirements
+ - NFV-SEC-004_.
+
+.. _NFV-SEC-004: http://www.etsi.org/deliver/etsi_gs/NFV/001_099/004/01.01.01_60/gs_NFV004v010101p.pdf
+
+Requirements on Auditing framework
+----------------------------------
+
+Audit records shall be maintained within protected binary logs so that the record of
+malicious actions cannot be deleted from the logs.
+
+Necessary auditable events
+--------------------------
+
+* access control management
+
+ - Adding a user account
+ - Modifying user account
+ - Deleting a user account
+ - login event
+ - logout event
+ - IP whitelisting update
+ - IP blacklisting update
+
+* VNFC Creation
+
+ - The instantiation of a newly-defined VNFC
+ - The instantiation of a VNFC with pre-configured state
+ - The cloning of an existing VNFC
+
+* VNFC Deletion
+
+ - The deletion of VNFC and of all of its instances (e.g. snapshots, backups, archives, cloned images)
+
+* Software management
+
+ - patching e.g. opreating system, drivers, VM components
+ - dynamic updates to the configuration e.g. DNS, DHCP
+ - application software updates
+ - software component updates
+
+* Data management
+
+ - Root level access to NFVI file system
+ - User level access to NFVI file system
+ - Secured wipe, disk and memory
+ - Verified destruction
+ - Certificate revocation
+
+* VNFC Migration
+
+ - VNFC original host identity
+ - VNFC target host identity
+ - high availability
+ - recovery
+ - data-in-motion changes
+
+* Other VNFC Operational State Changes
+
+ - Hibernation, sleep, resumption, abort, restore, suspension
+ - Power-on and power-off (either physical or virtual)
+ - Integrity verification failure, crash and OS compromise
+
+* VNFC Topology Changes
+
+ - Network IP address and VLAN updates
+ - Service chaining
+ - Failover and disaster recovery
+
+* traffic inspection
+
+ - enabling virtual port mirroring
+ - enabling hypervisor introspection
+ - enabling in-line traffic inspection
+ - application insertion
+
+* initial provisioning of a public/private key pair
+
+ - Self-generation of key pairs for later validation by an external party:
+
+ - Certificate Authority
+ - VNFM
+
+ - Provision by trusted party
+
+ - network
+ - storage
+
+ - Injection by hypervisor
+
diff --git a/docs/development/opnfvsecguide/compute.rst b/docs/development/opnfvsecguide/compute.rst
new file mode 100644
index 000000000..d6c1a0159
--- /dev/null
+++ b/docs/development/opnfvsecguide/compute.rst
@@ -0,0 +1,8 @@
+Compute Security
+----------------
+
+.. toctree::
+ :maxdepth: 2
+
+ compute/dacmaccontrols.rst
+ compute/trust.rst
diff --git a/docs/development/opnfvsecguide/compute/dacmaccontrols.rst b/docs/development/opnfvsecguide/compute/dacmaccontrols.rst
new file mode 100644
index 000000000..08cd7ee89
--- /dev/null
+++ b/docs/development/opnfvsecguide/compute/dacmaccontrols.rst
@@ -0,0 +1,3 @@
+DAC & MAC Controls
+------------------
+
diff --git a/docs/development/opnfvsecguide/compute/trust.rst b/docs/development/opnfvsecguide/compute/trust.rst
new file mode 100644
index 000000000..3022e59c0
--- /dev/null
+++ b/docs/development/opnfvsecguide/compute/trust.rst
@@ -0,0 +1,124 @@
+Trusted Compute
+---------------
+
+Trusted compute is centered on insuring the complete lifecycle of a VM, and
+the VM's underlying infrastructure is of a 'trustful' state.
+
+**Trusted computing in a cloud environment**
+
+To ensure overall security in an OPNFV deployment, both the launch and the
+operation of virtualized resources need to be secure. To build a trusted
+computing in a cloud environment the following core features are essential:
+
+* boot integrity - the hardware platform can guarantee a trustworthy RoT for the overall cloud environment
+* secure management of VMs – to secure the launch and migration of VMs in the cloud environment
+
+In this section we will cover some aspects of what is considered compute
+security, such as secure/trusted boot, although of course these can be
+extended to other actors such as neutron networking nodes.
+
+Secure Boot
+###########
+
+Secure boot, a UEFI-based feature that has become controversial lately,
+ensures that nodes in an OPNFV deployment boot only software that is trusted
+by the admin or end user.
+
+In order to understand the secure boot procedure, we need to explain the related technology
+and specification.
+
+**Unified Extensible Firmware Interface (UEFI)**
+
+UEFI is a specification intended to be the replacement and improvement on the
+old BIOS (Basic Input/Output System).
+
+One UEFI-based feature that has become controversial lately is the secure boot feature.
+
+The UEFI specification is a standard that’s handled by a non-profit organization
+with representatives of Intel, AMD, Microsoft, Apple, Dell, HP, IBM and others,
+called the Unified EFI Forum.
+
+UEFI supports 32 and 64 bit processors and can be used with Itanium, x86,
+x64 and ARM processors.
+
+**Trusted Execution Environment (TEE) vs Trusted Platform Mobile (TPM)**
+
+Two main components of platform security:
+
+* Trusted Execution Environment
+* Trusted Platform Module
+
+These are not designed as a replacement of the other. TEE is the bulletproof
+safe, while TPM is the 128-digit combination lock for the safe. Both are
+needed to ensure the safe is protected.
+
+TPM is a dependency of TEE but not the other way around.
+
+The TPM is where TEE will store the measurements - hash of components - of the platform.
+
+If TEE is not supported by a platform but a TPM is still present you still have
+all these features:
+
+* Integrity measurement – securely measure the platform's components (hashes stored within the TPM)
+
+* Authenticated boot – a process by which a platform's state (the sum of its
+ components) is reliably measured and stored
+
+* SRTM - Static Root of Trust for Measurements
+
+* Sealed Storage - encrypt data based on the current state of the platform
+ or in other words, what has been measured (the PCR hash values stored in the
+ TPM) - seal operation
+
+* Attestation - securely report to other parties the state of the platform
+
+
+Trusted Compute Pools
+#####################
+
+**Trusted Boot**
+
+Trusted boot (tboot) is an open source, pre- kernel/VMM module that uses
+Intel(R) Trusted Execution Technology (Intel(R) TXT) to perform a measured
+and verified launch of an OS kernel/VMM. The root of trust is in the hardware
+and a TPM is required. Compute nodes in an OPNFV deployment boot with Intel
+TXT technology enabled.
+
+Read more about `Trusted Boot <http://www.trustedcomputinggroup.org/resources/trusted_boot>`_ and
+`Trusted Computing. <http://www.trustedcomputinggroup.org/trusted_computing>`_
+
+**Trusted Execution Environments (TEE)**
+
+The Trusted Execution Environment is an isolated execution environment which
+provides higher level of security such as isolated execution, integrity of
+Trusted Applications along with confidentiality of their assets.
+
+**Goals of a Trusted Execution Environments:**
+
+* Isolated Execution
+* Secure Storage
+* Remote Attestation
+* Secure Provisioning
+* Trusted Path
+
+**TEE platforms/implementations**
+
+* Intel’s TXT (Trusted Execution Technology)
+* AMD Secure Execution Environment
+* ARM TrustZone
+
+All three of these TEE implementations provide a virtualized Execution
+Environment for the secure OS and applications.
+
+To switch between the secure world and the normal world, Intel provides SMX
+Instructions, while ARM uses SMC. Programmatically, they all achieve very
+similar results.
+
+Read more about Trusted Execution Environments `here. <http://www.openvirtualization.org/open-source-arm-trustzone.html>`_
+
+`NIST SP800-147 <http://csrc.nist.gov/publications/nistpubs/800-147/NIST-SP800-147-April2011.pdf>`_
+, is a guidelines for firmware security, to ensure that the firmware itself is secure.
+
+Read more about "Trusted compute pools", in the
+`OpenStack Security Guide. <http://docs.openstack.org/admin-guide-cloud/compute-security.html>`_
+
diff --git a/docs/development/opnfvsecguide/contribution.rst b/docs/development/opnfvsecguide/contribution.rst
new file mode 100644
index 000000000..683aa2d14
--- /dev/null
+++ b/docs/development/opnfvsecguide/contribution.rst
@@ -0,0 +1,45 @@
+How to Contribute
+-----------------
+
+Anyone is welcome to make additions, raise bugs, and fix issues within this Documentation.
+To do so, you will however need to first get an enviroment set up.
+
+Development Environment
+#######################
+
+All project data such as formatting guidelines, and upstream mapping is documented via sphinx
+which uses reStructuredText
+
+It is recommended that you use a python virtualenv to keep things clean and contained.
+
+VirtualEnv
+**********
+
+Use of a virtual environment is recommended, as not only is it a quick easy form of
+getting the needed modules in place, it isolates the module versions to a project.
+
+From within your inspector directory, set up a new virtualenv::
+
+ virtualenv venv
+
+Activate the new virtual environment::
+
+ source venv/bin/activate
+
+Install requirements::
+
+ pip install -r requirements.txt
+
+Sphinx Basics
+*************
+
+To get started with sphinx, visit the main tutorial which will provide a primer `http://sphinx-doc.org/tutorial.html`
+
+Hack your changes into opnfv-security-guide/source
+
+To compile changes:
+
+ make html
+
+From here you can run a basic python web server or just navigate to the
+file:///<repo>/opnfv-security-guide/build/html/index.html in your browser
diff --git a/docs/development/opnfvsecguide/getting_started.rst b/docs/development/opnfvsecguide/getting_started.rst
new file mode 100644
index 000000000..e09507dd2
--- /dev/null
+++ b/docs/development/opnfvsecguide/getting_started.rst
@@ -0,0 +1,41 @@
+Getting Started
+---------------
+
+Development Environment
+#######################
+
+All project data such as formatting guidelines, and upstream mapping is documented via sphinx
+which uses reStructuredText
+
+VirtualEnv
+**********
+
+Use of a virtual environment is recommended, as not only is it a quick easy form of
+getting the needed modules in place, it isolates the module versions to a project.
+
+From within your inspector directory, set up a new virtualenv::
+
+ virtualenv venv
+
+Activate the new virtual environment::
+
+ source venv/bin/activate
+
+Install requirements::
+
+ pip install -r requirements.txt
+
+Sphinx Basics
+*************
+
+To get started with sphinx, visit the main tutorial which will provide a primer
+`http://sphinx-doc.org/tutorial.html`
+
+Hack your changes into opnfv-security-guide/source
+
+To compile changes:
+
+ make html
+
+From here you can run a basic python web server or just navigate to the
+file:///<repo>/opnfv-security-guide/build/html/index.html in your browser
diff --git a/docs/development/opnfvsecguide/index.rst b/docs/development/opnfvsecguide/index.rst
new file mode 100644
index 000000000..ecefd61ce
--- /dev/null
+++ b/docs/development/opnfvsecguide/index.rst
@@ -0,0 +1,21 @@
+.. OPNFV Security Guide documentation master file, created by
+ sphinx-quickstart on Tue Oct 27 19:30:29 2015.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to OPNFV Security Guide
+================================================
+
+This guide seeks to inform operators who to secure and maintain the security of the OPNFV Platform and its components.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ compute
+ network
+ contribution
+ audit
+
diff --git a/docs/development/opnfvsecguide/introduction.rst b/docs/development/opnfvsecguide/introduction.rst
new file mode 100644
index 000000000..ad8083197
--- /dev/null
+++ b/docs/development/opnfvsecguide/introduction.rst
@@ -0,0 +1,15 @@
+Introduction
+---------------
+
+The OPNFV Security Guide is the collaborative work of many individuals,
+involved in both the OPNFV Security Group and the wider OPNFV community.
+
+The purpose of this guide is to provide the best practice security guidelines for
+deploying the OPNFV platfornm. It is a living document that is updated as
+new changes are merged into it's repository.
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction/background
+ introduction/acknowledgements
diff --git a/docs/development/opnfvsecguide/introduction/acknowledgements.rst b/docs/development/opnfvsecguide/introduction/acknowledgements.rst
new file mode 100644
index 000000000..60c687d05
--- /dev/null
+++ b/docs/development/opnfvsecguide/introduction/acknowledgements.rst
@@ -0,0 +1,3 @@
+Acknowledgements
+----------------
+
diff --git a/docs/development/opnfvsecguide/introduction/background.rst b/docs/development/opnfvsecguide/introduction/background.rst
new file mode 100644
index 000000000..bd7e44d01
--- /dev/null
+++ b/docs/development/opnfvsecguide/introduction/background.rst
@@ -0,0 +1,38 @@
+Background
+----------
+
+Pre-virtualization security protection was largely centered on the network.
+Malicious attacks from hostile machines, would seek to exploit network based
+operating systems and applications, with the goal of compromising their
+target node.
+
+Physical security had always been a much simpler business, with most focus on
+the secure access of the data center hardware.
+In-turn security was built up in layers (defense in depth) where machines
+would be
+daisy chained with network cables via security appliances to provide
+controlled segmentation and isolation.
+This form of security was built upon the principle of an 'air gap'
+being present,
+whereby machines were separate physical units, joined largely by the
+network stack.
+
+With the advent of virtualization (namely the hypervisor), new attack
+vectors have
+surfaced as the 'air-gap' is no longer key design aspect for security.
+Further to this elements orchestation nodes and network controllers
+lead to an even wider attack surface:
+
+* Guests breaking isolation of the hypervisor.
+
+* Unauthorized access and control of supporting orchestration nodes.
+
+* Unauthorized access and control of supporting overlay network control systems.
+
+The hypervisor and the overlay network have now become the 'Achilles heel'
+whereby all tenant data isolation is enforced within the hypervisor and its
+abstraction
+of hardware and the virtualized overlay network.
+
+This guide has been formulated, in order to assist users of the OPNFV platform
+in securing an Telco NFV / SDN environment.
diff --git a/docs/development/opnfvsecguide/network.rst b/docs/development/opnfvsecguide/network.rst
new file mode 100644
index 000000000..b1744796c
--- /dev/null
+++ b/docs/development/opnfvsecguide/network.rst
@@ -0,0 +1,8 @@
+Network Security
+----------------
+
+
+.. toctree::
+ :maxdepth: 2
+
+ network/neutron
diff --git a/docs/development/opnfvsecguide/network/neutron.rst b/docs/development/opnfvsecguide/network/neutron.rst
new file mode 100644
index 000000000..e7ca06075
--- /dev/null
+++ b/docs/development/opnfvsecguide/network/neutron.rst
@@ -0,0 +1,2 @@
+Neutron Security
+----------------
diff --git a/docs/development/scenario/featurematrix.rst b/docs/development/scenario/featurematrix.rst
new file mode 100644
index 000000000..2d00a4097
--- /dev/null
+++ b/docs/development/scenario/featurematrix.rst
@@ -0,0 +1,39 @@
+Each scenario provides a set of platform capabilities and features that it supports. It is
+possible to identify which features are provided by reviewing the scenario name, however
+not all features and capabilities are discernible from the name itself.
+
+Brahmaputra feature support matrix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table provides an overview of the available scenarios and supported features
+in the Brahmaputra release of OPNFV.
+
+.. image:: ../images/brahmaputrafeaturematrix.jpg
+ :alt: OPNFV Brahmaputra Feature Matrix
+
+The table above provides an overview of which scenarios will support certain feature capabilities.
+The table does not indicate if the feature or scenario has limitations. Refer to the
+`Configuration Guide <http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/configoptions.html#opnfv-scenarios>`_
+for details on the state of each scenario and further information.
+
+Feature development in the Brahmaputra release often consisted of the development of specific
+requirements and the further integration and validation of those requirements. This results in some
+features only being supported on the platform when a specific scenario, providing the
+capabilities necessary to run the feature, is deployed.
+
+Scenario Naming
+^^^^^^^^^^^^^^^
+
+In OPNFV, scenarios are identified by short scenario names. These names follow a scheme that
+identifies the key components and behaviours of the scenario, the rules for scenario naming are as follows:
+
+ os-[controller]-[feature]-[mode]-[option]
+
+For example: *os-nosdn-kvm-noha* provides an OpenStack based deployment using neutron including
+the OPNFV enhanced KVM hypervisor.
+
+The [feature] tag in the scenario name describes the main feature provided by the scenario.
+This scenario may also provide support for features, such as advanced fault management, which are
+not apparent in the scenario name.
+The following section describes the features available in each scenario.
+
diff --git a/docs/development/scenario/scenariointro.rst b/docs/development/scenario/scenariointro.rst
new file mode 100644
index 000000000..dd808432b
--- /dev/null
+++ b/docs/development/scenario/scenariointro.rst
@@ -0,0 +1,13 @@
+OPNFV Scenarios
+---------------
+
+The OPNFV project provides an integration and deployment environment for a variety of components
+that can make up a virtualisation platform. OPNFV identifies these variations on the composition of
+the platform as scenarios.
+
+A scenario in OPNFV can be defined as "a deployment of a specific set of platform components". The
+composition of a scenario may include specific SDN controller technologies, specific accelerate
+switching technologies, or even specific configurations of components to achieve targeted platform
+capabilities. Each scenario behaves differetly and it is important to understand the behaviour you
+want in order to target the specific scenario you wish to deploy prior to working with the
+OPNFV platform.
diff --git a/docs/development/scenario/scenariomatrix.rst b/docs/development/scenario/scenariomatrix.rst
new file mode 100644
index 000000000..64e115015
--- /dev/null
+++ b/docs/development/scenario/scenariomatrix.rst
@@ -0,0 +1,100 @@
+Scenarios are implemented as deployable compositions through integration with an installation tool.
+OPNFV supports multiple installation tools and for any given release not all tools will support all
+scenarios. While our target is to establish parity across the installation tools to ensure they
+can provide all scenarios, the practical challenge of achieving that goal for any given feature and
+release results in some disparity.
+
+Brahmaputra scenario overeview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table provides an overview of the installation tools and available scenario's
+in the Brahmaputra release of OPNFV.
+
+.. image:: ../images/brahmaputrascenariomatrix.jpg
+ :alt: OPNFV Brahmaputra Scenario Matrix
+
+Scenario status is indicated by a weather pattern icon. All scenarios listed with
+a weather pattern are possible to deploy and run in your environment or a Pharos lab,
+however they may have known limitations or issues as indicated by the icon.
+
+Weather pattern icon legend:
+
++---------------------------------------------+----------------------------------------------------------+
+| Weather Icon | Scenario Status |
++=============================================+==========================================================+
+| .. image:: ../images/weather-clear.jpg | Stable, no known issues |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-few-clouds.jpg | Stable, documented limitations |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-overcast.jpg | Deployable, stability or feature limitations |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-dash.jpg | Not deployed with this installer |
++---------------------------------------------+----------------------------------------------------------+
+
+Scenarios that are not yet in a state of "Stable, no known issues" will continue to be stabilised
+and updates will be made on the stable/brahmaputra branch. While we intend that all Brahmaputra
+scenarios should be stable it is worth checking regularly to see the current status. Due to
+our dependency on upstream communities and code some issues may not be resolved prior to the C release.
+
+Scenario Naming
+^^^^^^^^^^^^^^^
+
+In OPNFV scenarios are identified by short scenario names, these names follow a scheme that
+identifies the key components and behaviours of the scenario. The rules for scenario naming are as follows:
+
+ os-[controller]-[feature]-[mode]-[option]
+
+Details of the fields are
+ * os: mandatory
+
+ * Refers to the platform type used
+ * possible value: os (OpenStack)
+
+* [controller]: mandatory
+
+ * Refers to the SDN controller integrated in the platform
+ * example values: nosdn, ocl, odl, onos
+
+ * [feature]: mandatory
+
+ * Refers to the feature projects supported by the scenario
+ * example values: nofeature, kvm, ovs, sfc
+
+ * [mode]: mandatory
+
+ * Refers to the deployment type, which may include for instance high availability
+ * possible values: ha, noha
+
+ * [option]: optional
+
+ * Used for the scenarios those do not fit into naming scheme.
+ * The optional field in the short scenario name should not be included if there is no optional scenario.
+
+Some examples of supported scenario names are:
+
+ * os-nosdn-kvm-noha
+
+ * This is an OpenStack based deployment using neutron including the OPNFV enhanced KVM hypervisor
+
+ * os-onos-nofeature-ha
+
+ * This is an OpenStack deployment in high availability mode including ONOS as the SDN controller
+
+ * os-odl_l2-sfc
+
+ * This is an OpenStack deployment using OpenDaylight and OVS enabled with SFC features
+
+Installing your scenario
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two main methods of deploying your target scenario, one method is to follow this guide which will
+walk you through the process of deploying to your hardware using scripts or ISO images, the other method is
+to set up a Jenkins slave and connect your infrastructure to the OPNFV Jenkins master.
+
+For the purposes of evaluation and development a number of Brahmaputra scenarios are able to be deployed
+virtually to mitigate the requirements on physical infrastructure. Details and instructions on performing
+virtual deployments can be found in the installer specific installation instructions.
+
+To set up a Jenkins slave for automated deployment to your lab, refer to the `Jenkins slave connect guide.
+<http://artifacts.opnfv.org/brahmaputra.1.0/docs/opnfv-jenkins-slave-connection.brahmaputra.1.0.html>`_
+
diff --git a/docs/development/scenario/scenariovalidation.rst b/docs/development/scenario/scenariovalidation.rst
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/development/scenario/scenariovalidation.rst