Added networking-sfc from openstack project with merge date Dec 23 2015stable/coloradostable/brahmaputra

Added patch 13 for subject "add missing db migration files"

Change-Id: Id51a160335a14870c1dd816a44baf9b1958b9ac6

10 files changed, 1588 insertions, 0 deletions

diff --git a/doc/source/alembic_migration.rst b/doc/source/alembic_migration.rst
new file mode 100644
index 0000000..bb225af
--- /dev/null
+++ b/doc/source/alembic_migration.rst
@@ -0,0 +1,102 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+Alembic-migration
+=================
+
+Using alembic-migration, required data modeling for networking-sfc is defined and
+applied to the database. Refer to `Neutron alembic migration process <http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html>`_ for further details.
+
+Important operations:
+---------------------
+
+Checking migration:
+~~~~~~~~~~~~~~~~~~~
+
+::
+
+    neutron-db-manage --subproject networking-sfc check_migration
+      Running branches for networking-sfc ...
+    start_networking_sfc (branchpoint)
+                         -> 48072cb59133 (contract) (head)
+                         -> 24fc7241aa5 (expand)
+
+      OK
+
+Checking branch information:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    neutron-db-manage --subproject networking-sfc branches
+      Running branches for networking-sfc ...
+    start_networking_sfc (branchpoint)
+                         -> 48072cb59133 (contract) (head)
+                         -> 24fc7241aa5 (expand)
+
+      OK
+
+Checking migration history:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    neutron-db-manage --subproject networking-sfc history
+      Running history for networking-sfc ...
+    9768e6a66c9 -> 5a475fc853e6 (expand) (head), Defining OVS data-model
+    24fc7241aa5 -> 9768e6a66c9 (expand), Defining flow-classifier data-model
+    start_networking_sfc -> 24fc7241aa5 (expand), Defining Port Chain data-model.
+    start_networking_sfc -> 48072cb59133 (contract) (head), Initial Liberty no-op script.
+    <base> -> start_networking_sfc (branchpoint), start networking-sfc chain
+
+Applying changes:
+~~~~~~~~~~~~~~~~~
+
+::
+
+    neutron-db-manage --subproject networking-sfc upgrade head
+    INFO  [alembic.runtime.migration] Context impl MySQLImpl.
+    INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
+      Running upgrade for networking-sfc ...
+    INFO  [alembic.runtime.migration] Context impl MySQLImpl.
+    INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
+    INFO  [alembic.runtime.migration] Running upgrade  -> start_networking_sfc, start networking-sfc chain
+    INFO  [alembic.runtime.migration] Running upgrade start_networking_sfc -> 48072cb59133, Initial Liberty no-op script.
+    INFO  [alembic.runtime.migration] Running upgrade start_networking_sfc -> 24fc7241aa5, Defining Port Chain data-model.
+    INFO  [alembic.runtime.migration] Running upgrade 24fc7241aa5 -> 9768e6a66c9, Defining flow-classifier data-model
+    INFO  [alembic.runtime.migration] Running upgrade 9768e6a66c9 -> 5a475fc853e6, Defining OVS data-model
+      OK
+
+Checking current version:
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    neutron-db-manage --subproject networking-sfc current
+      Running current for networking-sfc ...
+    INFO  [alembic.runtime.migration] Context impl MySQLImpl.
+    INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
+    48072cb59133 (head)
+    5a475fc853e6 (head)
+      OK
+
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100755
index 0000000..aaa079a
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,626 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+=========
+API Model
+=========
+
+Problem Description
+===================
+
+Currently Neutron does not support service function chaining. To support
+service function chaining, Service VMs must be attached at points in the
+network and then traffic must be steered between these attachment
+points. Please refer to `Neutron Service Chain blue-print <https://blueprints.launchpad.net/neutron/+spec/neutron-api-extension-for-service-chaining>`_ and Bugs `[1] <https://bugs.launchpad.net/neutron/+bug/1450617>`_ `[2] <https://bugs.launchpad.net/neutron/+bug/1450625>`_
+releated to this specification for more information.
+
+Proposed Change
+===============
+
+All Neutron network services and VMs are connected to a Neutron network
+via Neutron ports. This makes it possible to create a traffic steering model
+for service chaining that uses only Neutron ports. This traffic steering
+model has no notion of the actual services attached to these Neutron
+ports.
+
+The service VM hosting the service functions is instantiated and configured,
+then VNICs are added to the VM and then these VNICs are attached to the
+network by Neutron ports. Once the service function is attached to Neutron
+ports, the ports may be included in a "port chain" to allow the service
+function to provide treatment to the user's traffic.
+
+A Port Chain (Service Function Path) consists of:
+
+* a set of Neutron ports, to define the sequence of service functions
+* a set of flow classifiers, to specify the classified traffic flows to
+  enter the chain
+
+If a service function has a pair of ports, the first port in
+the port-pair is the ingress port of the service function, and the second
+port is the egress port of the service function.
+If a service function has one bidirectional port, then both ports in
+the port-pair have the same value.
+A Port Chain is a directional service chain. The first port of the first port-pair
+is the head of the service chain. The second port of the last port-pair is the tail
+of the service chain. A bidirectional service chain would be composed of two unidirectional Port Chains.
+
+For example, [{'p1': 'p2'}, {'p3': 'p4'}, {'p5': 'p6'}] represents::
+
+       +------+     +------+     +------+
+       | SF1  |     | SF2  |     | SF3  |
+       +------+     +------+     +------+
+       p1|  |p2     p3|  |p4      p5| |P6
+         |  |         |  |          | |
+    ->---+  +---------+  +----------+ +---->
+
+where P1 is the head of the Port Chain and P6 is the tail of the Port Chain, and
+SF1 has ports p1 and p2, SF2 has ports p3 and p4, and SF3 has ports p5 and p6.
+
+In order to create a chain, the user needs to have the actual port objects.
+The work flow would typically be:
+
+a) create the ports
+b) create the chain
+c) boot the vm's passing the ports as nic's parameters
+
+The sequence of b) and c) can be switched.
+
+A SF's Neutron port may be associated with more than one Port Chain to allow
+a service function to be shared by multiple chains.
+
+If there is more than one service function instance of a specific type
+available to meet the user's service requirement, their Neutron ports are
+included in the port chain as a sub-list. For example, if {p3, p4}, {p7, p8}
+are the port-pairs of two FW instances, they
+both may be included in a port chain for load distribution as shown below.
+
+  [{'p1': 'p2'}, [{'p3': 'p4'},{'p7': 'p8'}], {'p5': 'p6'}]
+
+Flow classifiers are used to select the traffic that can
+access the chain. Traffic that matches any flow classifier will be
+directed to the first port in the chain. The flow classifier will be a generic
+independent module and may be used by other projects like FW, QOS, etc.
+
+A flow classifier cannot be part of two different port-chains otherwise ambiguity
+will arise as to which chain path that flow's packets should go. A check will be
+made to ensure no ambiguity. But multiple flow classifiers can be associated with
+a port chain since multiple different types of flows can request the same service
+treatment path.
+
+CLI Commands
+
+Syntax::
+
+ neutron port-pair-create [-h]
+         [--description <description>]
+         --ingress <port-id>
+         --egress <port-id>
+         [--service-function-parameters <parameter>] PORT-PAIR-NAME
+
+ neutron port-pair-group-create [-h]
+         [--description <description>]
+         --port-pairs <port-pair-id> PORT-PAIR-GROUP-NAME
+
+ neutron flow-classifier-create [-h]
+         [--description <description>]
+         [--protocol <protocol>]
+         [--ethertype <Ethertype>]
+         [--source-port <Minimum source protocol port>:<Maximum source protocol port>]
+         [--destination-port <Minimum destination protocol port>:<Maximum destination protocol port>]
+         [--source-ip-prefix <Source IP prefix>]
+         [--destination-ip-prefix <Destination IP prefix>]
+         [--logical-source-port <Neutron source port>]
+         [--logical-destination-port <Neutron destination port>]
+         [--l7-parameters <L7 parameter>] FLOW-CLASSIFIER-NAME
+
+ neutron port-chain-create [-h]
+         [--description <description>]
+          --port-pair-group <port-pair-group-id>
+         [--flow-classifier <classifier-id>]
+         [--chain-parameters <chain-parameter>] PORT-CHAIN-NAME
+
+1. neutron port-chain-create
+The port-chain-create returns the ID of the Port Chain.
+
+Each "port-pair-group" option specifies a type of SF. If a chain consists of a sequence
+of different types of SFs, then the chain will have multiple "port-pair-group"s.
+There must be at least one "port-pair-group" in the Port Chain.
+
+The "flow-classifier" option may be repeated to associate multiple flow classifiers
+with a port chain, with each classifier identifying a flow. If the flow-classifier is not
+specified, then no traffic will be steered through the chain.
+
+One chain parameter option is currently defined. More parameter options can be added
+in future extensions to accommodate new requirements.
+The "correlation" parameter is used to specify the type of chain correlation mechanism.
+This parameter allows different correlation mechanim to be selected.
+This will be set to "mpls" for now to be consistent with current OVS capability.
+If this parameter is not specified, it will default to "mpls".
+
+The port-chain-create command returns the ID of a Port chain.
+
+A port chain can be created, read, updated and deleted, and when a chain is
+created/read/updated/deleted, the options that are involved would be based on
+the CRUD in the "Port Chain" resource table below.
+
+2. neutron port-pair-group-create
+Inside each "port-pair-group", there could be one or more port-pairs.
+Multiple port-pairs may be included in a "port-pair-group" to allow the specification of
+a set of functionally equivalent SFs that can be be used for load distribution,
+i.e., the "port-pair" option may be repeated for multiple port-pairs of
+functionally equivalent SFs.
+
+The port-pair-group-create command returns the ID of a Port Pair group.
+
+3. neutron port-pair-create
+A Port Pair represents a service function instance. The ingress port and the
+egress port of the service function may be specified.  If a service function
+has one bidirectional port, the ingress port has the same value as the egress port.
+The "service-function-parameter" option allows the passing of SF specific parameter
+information to the data path. One parameter option is currently defined. More parameter
+options can be added in future extensions to accommodate new requirements.
+The "correlation" parameter is used to specify the type of chain correlation mechanism
+supported by a specific SF. This is needed by the data plane switch to determine
+how to associate a packet with a chain. This will be set to "none" for now since
+there is no correlation mechanism supported by the SF. In the future, it can be extended
+to include "mpls", "nsh", etc.. If this parameter is not specified, it will default to "none".
+
+The port-pair-create command returns the ID of a Port Pair.
+
+4. neutron flow-classifier-create
+A combination of the "source" options defines the source of the flow.
+A combination of the "destination" options defines the destination of the flow.
+The l7_parameter is a place-holder that may be used to support flow classification
+using L7 fields, such as URL. If an option is not specified, it will default to wildcard value
+except for ethertype which defaults to 'IPv4', for logical-source-port and
+logical-destination-port which defaults to none.
+
+The flow-classifier-create command returns the ID of a flow classifier.
+
+
+Data Model Impact
+-----------------
+
+Data model::
+
+        +-------+        +----------+        +------------+
+        | Port  |--------| Port Pair|--------| Port Pairs |
+        | Chain |*      *| Groups   | 1     *|            |
+        +-------+        +----------+        +------------+
+          |1
+          |
+          |*
+       +--------------+
+       | Flow         |
+       | Classifiers  |
+       +--------------+
+
+New objects:
+
+Port Chain
+  * id - Port chain ID.
+  * tenant_id - Tenant ID.
+  * name - Readable name.
+  * description - Readable description.
+  * port_pair_groups - List of port-pair-group IDs.
+  * flow_classifiers - List of flow-classifier IDs.
+  * chain_parameters - Dict. of chain parameters.
+
+Port Pair Group
+  * id - Port pair group ID.
+  * tenant_id - Tenant ID.
+  * name - Readable name.
+  * description - Readable description.
+  * port_pairs - List of service function (Neutron) port-pairs.
+
+Port Pair
+  * id - Port pair ID.
+  * tenant_id - Tenant ID.
+  * name - Readable name.
+  * description - Readable description.
+  * ingress - Ingress port.
+  * egress - Egress port.
+  * service_function_parameters - Dict. of service function parameters
+
+Flow Classifier
+  * id - Flow classifier ID.
+  * tenant_id - Tenant ID.
+  * name - Readable name.
+  * description - Readable description.
+  * ethertype - Ethertype ('IPv4'/'IPv6').
+  * protocol - IP protocol.
+  * source_port_range_min - Minimum source protocol port.
+  * source_port_range_max - Maximum source protocol port.
+  * destination_port_range_min - Minimum destination protocol port.
+  * destination_port_range_max - Maximum destination protocol port.
+  * source_ip_prefix - Source IP address or prefix.
+  * destination_ip_prefix - Destination IP address or prefix.
+  * logical_source_port - Neutron source port.
+  * logical_destination_port - Neutron destination port.
+  * l7_parameters - Dictionary of L7 parameters.
+
+REST API
+--------
+
+Port Chain Operations:
+
++------------+---------------------------+------------------------------------------+
+|Operation   |URL                        |Description                               |
++============+===========================+==========================================+
+|POST        |/sfc/port_chains           |Create a Port Chain                       |
++------------+---------------------------+------------------------------------------+
+|PUT         |/sfc/port_chains/{chain_id}|Update a specific Port Chain              |
++------------+---------------------------+------------------------------------------+
+|DELETE      |/sfc/port_chains/{chain_id}|Delete a specific Port Chain              |
++------------+---------------------------+------------------------------------------+
+|GET         |/sfc/port_chains           |List all Port Chains for specified tenant |
++------------+---------------------------+------------------------------------------+
+|GET         |/sfc/port_chains/{chain_id}|Show information for a specific Port Chain|
++------------+---------------------------+------------------------------------------+
+
+Port Pair Group Operations:
+
++------------+--------------------------------+-----------------------------------------------+
+|Operation   |URL                             |Description                                    |
++============+================================+===============================================+
+|POST        |/sfc/port_pair_groups           |Create a Port Pair Group                       |
++------------+--------------------------------+-----------------------------------------------+
+|PUT         |/sfc/port_pair_groups/{group_id}|Update a specific Port Pair Group              |
++------------+--------------------------------+-----------------------------------------------+
+|DELETE      |/sfc/port_pair_groups/{group_id}|Delete a specific Port Pair Group              |
++------------+--------------------------------+-----------------------------------------------+
+|GET         |/sfc/port_pair_groups           |List all Port Pair Groups for specified tenant |
++------------+--------------------------------+-----------------------------------------------+
+|GET         |/sfc/port_pair_groups/{group_id}|Show information for a specific Port Pair      |
++------------+--------------------------------+-----------------------------------------------+
+
+Port Pair Operations:
+
++------------+-------------------------+------------------------------------------+
+|Operation   |URL                      |Description                               |
++============+=========================+==========================================+
+|POST        |/sfc/port_pairs          |Create a Port Pair                        |
++------------+-------------------------+------------------------------------------+
+|PUT         |/sfc/port_pairs/{pair_id}|Update a specific Port Pair               |
++------------+-------------------------+------------------------------------------+
+|DELETE      |/sfc/port_pairs/{pair_id}|Delete a specific Port Pair               |
++------------+-------------------------+------------------------------------------+
+|GET         |/sfc/port_pairs          |List all Port Pairs for specified tenant  |
++------------+-------------------------+------------------------------------------+
+|GET         |/sfc/port_pairs/{pair_id}|Show information for a specific Port Pair |
++------------+-------------------------+------------------------------------------+
+
+Flow Classifier Operations:
+
++------------+-------------------------------+------------------------------------------------+
+|Operation   |URL                            |Description                                     |
++============+===============================+================================================+
+|POST        |/sfc/flow_classifiers          |Create a Flow-classifier                        |
++------------+-------------------------------+------------------------------------------------+
+|PUT         |/sfc/flow_classifiers/{flow_id}|Update a specific Flow-classifier               |
++------------+-------------------------------+------------------------------------------------+
+|DELETE      |/sfc/flow_classifiers/{flow_id}|Delete a specific Flow-classifier               |
++------------+-------------------------------+------------------------------------------------+
+|GET         |/sfc/flow_classifiers          |List all Flow-classifiers for specified tenant  |
++------------+-------------------------------+------------------------------------------------+
+|GET         |/sfc/flow_classifiers/{flow_id}|Show information for a specific Flow-classifier |
++------------+-------------------------------+------------------------------------------------+
+
+REST API Impact
+---------------
+
+The following new resources will be created as a result of the API handling.
+
+Port Chain resource:
+
++----------------+----------+--------+---------+----+-------------------------+
+|Attribute       |Type      |Access  |Default  |CRUD|Description              |
+|Name            |          |        |Value    |    |                         |
++================+==========+========+=========+====+=========================+
+|id              |uuid      |RO, all |generated|R   |Port Chain ID.           |
++----------------+----------+--------+---------+----+-------------------------+
+|tenant_id       |uuid      |RO, all |from auth|CR  |Tenant ID.               |
+|                |          |        |token    |    |                         |
++----------------+----------+--------+---------+----+-------------------------+
+|name            |string    |RW, all |''       |CRU |Port Chain name.         |
++----------------+----------+--------+---------+----+-------------------------+
+|description     |string    |RW, all |''       |CRU |Port Chain description.  |
++----------------+----------+--------+---------+----+-------------------------+
+|port_pair_groups|list(uuid)|RW, all |N/A      |CR  |List of port-pair-groups.|
++----------------+----------+--------+---------+----+-------------------------+
+|flow_classifiers|list(uuid)|RW, all |[]       |CRU |List of flow-classifiers.|
++----------------+----------+--------+---------+----+-------------------------+
+|chain_parameters|dict      |RW, all |mpls     |CR  |Dict. of parameters:     |
+|                |          |        |         |    |'correlation':String     |
++----------------+----------+--------+---------+----+-------------------------+
+
+Port Pair Group resource:
+
++-----------+--------+---------+---------+----+---------------------+
+|Attribute  |Type    |Access   |Default  |CRUD|Description          |
+|Name       |        |         |Value    |    |                     |
++===========+========+=========+=========+====+=====================+
+|id         |uuid    |RO, all  |generated|R   |Port pair group ID.  |
++-----------+--------+---------+---------+----+---------------------+
+|tenant_id  |uuid    |RO, all  |from auth|CR  |Tenant ID.           |
+|           |        |         |token    |    |                     |
++-----------+--------+---------+---------+----+---------------------+
+|name       |string  |RW, all  |''       |CRU |Port pair group name.|
++-----------+--------+---------+---------+----+---------------------+
+|description|string  |RW, all  |''       |CRU |Port pair group      |
+|           |        |         |         |    |description.         |
++-----------+--------+---------+---------+----+---------------------+
+|port_pairs |list    |RW, all  |N/A      |CRU |List of port-pairs.  |
++-----------+--------+---------+---------+----+---------------------+
+
+Port Pair resource:
+
++---------------------------+--------+---------+---------+----+----------------------+
+|Attribute Name             |Type    |Access   |Default  |CRUD|Description           |
++===========================+========+=========+=========+====+======================+
+|id                         |uuid    |RO, all  |generated|R   |Port pair ID.         |
++---------------------------+--------+---------+---------+----+----------------------+
+|tenant_id                  |uuid    |RO, all  |from auth|CR  |Tenant ID.            |
+|                           |        |         |token    |    |                      |
++---------------------------+--------+---------+---------+----+----------------------+
+|name                       |string  |RW, all  |''       |CRU |Port pair name.       |
++---------------------------+--------+---------+---------+----+----------------------+
+|description                |string  |RW, all  |''       |CRU |Port pair description.|
++---------------------------+--------+---------+---------+----+----------------------+
+|ingress                    |uuid    |RW, all  |N/A      |CR  |Ingress port ID.      |
++---------------------------+--------+---------+---------+----+----------------------+
+|egress                     |uuid    |RW, all  |N/A      |CR  |Egress port ID.       |
++---------------------------+--------+---------+---------+----+----------------------+
+|service_function_parameters|dict    |RW, all  |None     |CR  |Dict. of parameters:  |
+|                           |        |         |         |    |'correlation':String  |
++---------------------------+--------+---------+---------+----+----------------------+
+
+Flow Classifier resource:
+
++--------------------------+--------+---------+---------+----+-----------------------+
+|Attribute Name            |Type    |Access   |Default  |CRUD|Description            |
+|                          |        |         |Value    |    |                       |
++==========================+========+=========+=========+====+=======================+
+|id                        |uuid    |RO, all  |generated|R   |Flow-classifier ID.    |
++--------------------------+--------+---------+---------+----+-----------------------+
+|tenant_id                 |uuid    |RO, all  |from auth|CR  |Tenant ID.             |
+|                          |        |         |token    |    |                       |
++--------------------------+--------+---------+---------+----+-----------------------+
+|name                      |string  |RW, all  |''       |CRU |Flow-classifier name.  |
++--------------------------+--------+---------+---------+----+-----------------------+
+|description               |string  |RW, all  |''       |CRU |Flow-classifier        |
+|                          |        |         |         |    |description.           |
++--------------------------+--------+---------+---------+----+-----------------------+
+|ethertype                 |string  |RW, all  |'IPv4'   |CR  |L2 ethertype. Can be   |
+|                          |        |         |         |    |'IPv4' or 'IPv6' only. |
++--------------------------+--------+---------+---------+----+-----------------------+
+|protocol                  |string  |RW, all  |Any      |CR  |IP protocol name.      |
++--------------------------+--------+---------+---------+----+-----------------------+
+|source_port_range_min     |integer |RW, all  |Any      |CR  |Minimum source         |
+|                          |        |         |         |    |protocol port.         |
++--------------------------+--------+---------+---------+----+-----------------------+
+|source_port_range_max     |integer |RW, all  |Any      |CR  |Maximum source         |
+|                          |        |         |         |    |protocol port.         |
++--------------------------+--------+---------+---------+----+-----------------------+
+|destination_port_range_min|integer |RW, all  |Any      |CR  |Minimum destination    |
+|                          |        |         |         |    |protocol port.         |
++--------------------------+--------+---------+---------+----+-----------------------+
+|destination_port_range_max|integer |RW, all  |Any      |CR  |Maximum destination    |
+|                          |        |         |         |    |protocol port.         |
++--------------------------+--------+---------+---------+----+-----------------------+
+|source_ip_prefix          |CIDR    |RW, all  |Any      |CR  |Source IPv4 or IPv6    |
+|                          |        |         |         |    |prefix.                |
++--------------------------+--------+---------+---------+----+-----------------------+
+|destination_ip_prefix     |CIDR    |RW, all  |Any      |CR  |Destination IPv4 or    |
+|                          |        |         |         |    |IPv6 prefix.           |
++--------------------------+--------+---------+---------+----+-----------------------+
+|logical_source_port       |uuid    |RW, all  |None     |CR  |Neutron source port.   |
++--------------------------+--------+---------+---------+----+-----------------------+
+|logical_destination_port  |uuid    |RW, all  |None     |CR  |Neutron destination    |
+|                          |        |         |         |    |port.                  |
++--------------------------+--------+---------+---------+----+-----------------------+
+|l7_parameters             |dict    |RW, all  |Any      |CR  |Dict. of L7 parameters.|
++--------------------------+--------+---------+---------+----+-----------------------+
+
+Json Port-pair create request example::
+
+ {"port_pair": {"name": "SF1",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Firewall SF instance",
+        "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
+        "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
+    }
+ }
+
+ {"port_pair":  {"name": "SF2",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Loadbalancer SF instance",
+        "ingress": "797f899e-73d4-11e5-b392-2c27d72acb4c",
+        "egress": "797f899e-73d4-11e5-b392-2c27d72acb4c",
+    }
+ }
+
+Json Port-pair create response example::
+
+ {"port_pair": {"name": "SF1",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Firewall SF instance",
+        "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
+        "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
+        "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae",
+    }
+  }
+
+ {"port_pair":  {"name": "SF2",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Loadbalancer SF instance",
+        "ingress": "797f899e-73d4-11e5-b392-2c27d72acb4c",
+        "egress": "797f899e-73d4-11e5-b392-2c27d72acb4c",
+        "id": "d11e9190-73d4-11e5-b392-2c27d72acb4c"
+    }
+ }
+
+Json Port Pair Group create request example::
+
+ {"port_pair_group": {"name": "Firewall_PortPairGroup",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Grouping Firewall SF instances",
+        "port_pairs": [
+            "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
+        ]
+    }
+  }
+
+ {"port_pair_group": {"name": "Loadbalancer_PortPairGroup",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Grouping Loadbalancer SF instances",
+        "port_pairs": [
+            "d11e9190-73d4-11e5-b392-2c27d72acb4c"
+        ]
+    }
+ }
+
+Json Port Pair Group create response example::
+
+ {"port_pair_group": {"name": "Firewall_PortPairGroup",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Grouping Firewall SF instances",
+        "port_pairs": [
+            "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae
+        ],
+         "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
+    }
+ }
+
+ {"port_pair_group":  {"name": "Loadbalancer_PortPairGroup",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Grouping Loadbalancer SF instances",
+        "port_pairs": [
+            "d11e9190-73d4-11e5-b392-2c27d72acb4c"
+        ],
+         "id": "4a634d49-76dc-4fae-af4b-321c5e23d651",
+    }
+ }
+
+Json Flow Classifier create request example::
+
+ {"flow_classifier": {"name": "FC1",
+        "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
+        "description": "Flow rule for classifying TCP traffic",
+        "protocol": "TCP",
+        "source_port_range_min": 22, "source_port_range_max": 4000,
+        "destination_port_range_min": 80, "destination_port_range_max": 80,
+        "source_ip_prefix": null, "destination_ip_prefix": "22.12.34.45"
+    }
+ }
+
+ {"flow_classifier": {"name": "FC2",
+        "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
+        "description": "Flow rule for classifying UDP traffic",
+        "protocol": "UDP",
+        "source_port_range_min": 22, "source_port_range_max": 22,
+        "destination_port_range_min": 80, "destination_port_range_max": 80,
+        "source_ip_prefix": null, "destination_ip_prefix": "22.12.34.45"
+    }
+ }
+
+Json Flow Classifier create response example::
+
+ {"flow_classifier": {"name": "FC1",
+        "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
+        "description": "Flow rule for classifying TCP traffic",
+        "protocol": "TCP",
+        "source_port_range_min": 22, "source_port_range_max": 4000,
+        "destination_port_range_min": 80, "destination_port_range_max": 80,
+        "source_ip_prefix": null , "destination_ip_prefix": "22.12.34.45",
+        "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051"
+    }
+ }
+
+ {"flow_classifier": {"name": "FC2",
+        "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
+        "description": "Flow rule for classifying UDP traffic",
+        "protocol": "UDP",
+        "source_port_range_min": 22, "source_port_range_max": 22,
+        "destination_port_range_min": 80, "destination_port_range_max": 80,
+        "source_ip_prefix": null , "destination_ip_prefix": "22.12.34.45",
+        "id": "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
+    }
+ }
+
+Json Port Chain create request example::
+
+ {"port_chain": {"name": "PC1",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Steering TCP and UDP traffic first to Firewall and then to Loadbalancer",
+        "flow_classifiers": [
+            "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
+            "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
+        ],
+        "port_pair_groups": [
+            "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
+            "4a634d49-76dc-4fae-af4b-321c5e23d651"
+        ],
+    }
+ }
+
+Json Port Chain create response example::
+
+ {"port_chain": {"name": "PC2",
+        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
+        "description": "Steering TCP and UDP traffic first to Firewall and then to Loadbalancer",
+        "flow_classifiers": [
+            "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
+            "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
+        ],
+        "port_pair_groups": [
+            "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
+            "4a634d49-76dc-4fae-af4b-321c5e23d651"
+        ],
+         "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751"
+    }
+ }
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+Authors of the Specification and Primary contributors:
+ * Cathy Zhang (cathy.h.zhang@huawei.com)
+ * Louis Fourie (louis.fourie@huawei.com)
+
+Other contributors:
+ * Vikram Choudhary (vikram.choudhary@huawei.com)
+ * Swaminathan Vasudevan (swaminathan.vasudevan@hp.com)
+ * Yuji Azama (yuj-azama@rc.jp.nec.com)
+ * Mohan Kumar (nmohankumar1011@gmail.com)
+ * Ramanjaneya (ramanjieee@gmail.com)
+ * Stephen Wong (stephen.kf.wong@gmail.com)
+ * Nicolas Bouthors (Nicolas.BOUTHORS@qosmos.com)
+ * Akihiro Motoki <amotoki@gmail.com>
+ * Paul Carver <pcarver@att.com>
+
diff --git a/doc/source/command_extensions.rst b/doc/source/command_extensions.rst
new file mode 100644
index 0000000..abb4096
--- /dev/null
+++ b/doc/source/command_extensions.rst
@@ -0,0 +1,64 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+=================
+Command extension
+=================
+
+Networking-sfc uses python-neutronclient's existing command extension framework
+for adding required command lines for realizing service function chaining
+functionality. Refer to `Python-neutronclient command extension <http://docs.openstack.org/developer/python-neutronclient/devref/client_command_extensions.html>`_ for further details.
+
+
+List of New Neutron CLI Commands:
+---------------------------------
+Below listed command lines are introduced for realizing service function chaining.
+
+::
+
+    flow-classifier-create   Create a flow-classifier.
+    flow-classifier-delete   Delete a given flow-classifier.
+    flow-classifier-list     List flow-classifiers that belong to a given tenant.
+    flow-classifier-show     Show information of a given flow-classifier.
+    flow-classifier-update   Update flow-classifier information.
+
+    port-pair-create         Create a port-pair.
+    port-pair-delete         Delete a given port-pair.
+    port-pair-list           List port-pairs that belongs to a given tenant.
+    port-pair-show           Show information of a given port-pair.
+    port-pair-update         Update port-pair's information.
+
+    port-pair-group-create   Create a port-pair-group.
+    port-pair-group-delete   Delete a given port-pair-group.
+    port-pair-group-list     List port-pair-groups that belongs to a given tenant.
+    port-pair-group-show     Show information of a given port-pair-group.
+    port-pair-group-update   Update port-pair-group's information.
+
+    port-chain-create        Create a port-chain.
+    port-chain-delete        Delete a given port-chain.
+    port-chain-list          List port-chains that belong to a given tenant.
+    port-chain-show          Show information of a given port-chain.
+    port-chain-update        Update port-chain's information.
+
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100755
index 0000000..e70c181
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,76 @@
+# Copyright 2015 Futurewei. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    #'sphinx.ext.intersphinx',
+    'oslosphinx'
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'networking-sfc'
+copyright = u'2013, OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'OpenStack Foundation', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/contribution.rst b/doc/source/contribution.rst
new file mode 100644
index 0000000..852aa97
--- /dev/null
+++ b/doc/source/contribution.rst
@@ -0,0 +1,29 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+============
+Contribution
+============
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..da33019
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,66 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+Welcome to the Service Function Chaining Documentation!
+=======================================================
+.. include:: ../../README.rst
+
+
+===============
+Developer Guide
+===============
+
+In the Developer Guide, you will find information on Networking-SFC lower level
+programming APIs. There are sections that cover the core pieces of networking-sfc,
+including its api, command-lines, database, system-design, alembic-migration etc.
+There are also subsections that describe specific plugins inside networking-sfc.
+Finally, the developer guide includes information about testing infrastructure.
+
+Programming HowTos and Tutorials
+--------------------------------
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    usage
+    contribution
+
+Networking-SFC Internals
+------------------------
+.. toctree::
+   :maxdepth: 2
+
+   api
+   system_design and_workflow
+   ovs_driver_and_agent_workflow
+   command_extensions
+   alembic_migration
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
new file mode 100644
index 0000000..bf133b0
--- /dev/null
+++ b/doc/source/installation.rst
@@ -0,0 +1,37 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+============
+Installation
+============
+
+At the command line::
+
+    $ pip install networking-sfc
+
+Or, if you have virtualenvwrapper installed::
+
+    $ mkvirtualenv networking-sfc
+    $ pip install networking-sfc
diff --git a/doc/source/ovs_driver_and_agent_workflow.rst b/doc/source/ovs_driver_and_agent_workflow.rst
new file mode 100644
index 0000000..d8cda09
--- /dev/null
+++ b/doc/source/ovs_driver_and_agent_workflow.rst
@@ -0,0 +1,311 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+=============================
+OVS Driver and Agent Workflow
+=============================
+
+Blueprint about `Common Service chaining driver <https://blueprints.launchpad.net/neutron/+spec/common-service-chaining-driver-api>`_ describes the OVS driver and agent necessity for realizing service function chaining.
+
+Problem Description
+===================
+
+The service chain OVS driver and agents are used to configure back-end
+Openvswitch devices to render service chaining in the data-plane. The driver
+manager controls a common service chain API which provides a consistent interface
+between the service chain manager and different device drivers.
+
+Proposed Change
+===============
+
+
+Design::
+
+       Port Chain Plugin
+      +-------------------------------+
+      |  +-------------------------+  |
+      |  |    Port Chain API       |  |
+      |  +-------------------------+  |
+      |  |    Port Chain Database  |  |
+      |  +-------------------------+  |
+      |  |    Driver Manager       |  |
+      |  +-------------------------+  |
+      |  |    Common Driver API    |  |
+      |  +-------------------------+  |
+      |               |               |
+      |  +-------------------------+  |
+      |  |        OVS Driver       |  |
+      |  +-------------------------+  |
+      +-------|----------------|------+
+              |rpc             |rpc
+         +-----------+   +-----------+
+         | OVS Agent |   | OVS Agent |
+         +-----------+   +-----------+
+
+A OVS service chain driver and agents communicate via rpc.
+
+OVS Driver
+----------
+The OVS Driver is extended to support service chaining. The driver interfaces
+with the OVS agents that reside on each Compute node. The OVS driver is responsible
+for the following:
+
+* Identify the OVS agents that directly connects to the SF instances and establish
+  communication with OVS agents on the Compute nodes.
+* Send commands to the OVS agents to create bridges, flow tables and flows to steer
+  chain traffic to the SF instances.
+
+OVS Agent
+---------
+The OVS agent will manage the OVS using OVSDB commands to create bridges and tables,
+and install flows to steer chain traffic to the SF instances.
+
+Existing tunnels between the Tunnel bridges on each Compute node are used to
+transport Port Chain traffic between the CNs.
+
+The OVS Agent will create these tunnels to transport SFC traffic between Compute
+nodes on which there are SFs. Each tunnel port has the following attributes:
+
+* Name
+* Local tunnel IP address
+* Remote tunnel IP address
+* Tunnel Type: VXLAN, GRE
+
+The OVS agent installs additional flows on the Integration bridge and the Tunnel bridge
+to perform the following functions:
+
+* Traffic classification. The Integration bridge classifies traffic from a VM port or
+  Service VM port attached to the Integration bridge. The flow classification is based on
+  the n-tuple rules.
+* Service function forwarding. The Tunnel bridge forwards service chain
+  packets to the next-hop Compute node via tunnels, or to the next Service VM port
+  on that Compute node. Integration bridge will terminate a Service Function Path.
+
+The OVS Agent will use the MPLS header to transport the chain path identifier
+and chain hop index. The MPLS label will transport the chain path identifier,
+and the MPLS ttl will transport the chain hop index. The following packet encapsulation
+will be used::
+
+    IPv4 Packet:
+    +----------+------------------------+-------+
+    |L2 header | IP + UDP dst port=4790 | VXLAN |
+    +----------+------------------------+-------+
+    -----------------------------+---------------+--------------------+
+    Original Ethernet, ET=0x8847 | MPLS header   | Original IP Packet |
+    -----------------------------+---------------+--------------------+
+
+This is not intended as a general purpose MPLS implementation but rather as a
+temporary internal mechanism. It is anticipated that the MPLS label will be
+replaced with an NSH encapsulation
+(https://datatracker.ietf.org/doc/draft-ietf-sfc-nsh/) once NSH support is
+available upstream in Open vSwitch. If the service function does not support
+the header, then the vSwitch will act as Service Function Forwarder (SFF)
+Proxy which will strip off the header when forwarding the packet to the SF
+and re-add the header when receiving the packet from the SF.
+
+OVS Bridge and Tunnel
+---------------------
+Existing tunnels between the Tunnel bridges on each Compute node are used to
+transport Port Chain traffic between the CNs::
+
+         CN1                                 CN2
+        +--------------------------+        +-------------------------+
+        |  +-----+       +-----+   |        |  +-----+      +-----+   |
+        |  | VM1 |       | SF1 |   |        |  | SF2 |      | SF3 |   |
+        |  +-----+       +-----+   |        |  +-----+      +-----+   |
+        |     |.           ^|.     |        |   ^| |.         ^|.     |
+        | +----.-----------.-.--+  |        | +-.---.---------.-.---+ |
+        | |    ............. .. |  |        | | .   ........... .   | |
+        | | Integration Bridge. |  |        | | .Integration Bridge | |
+        | |           ......... |  |        | | ......   ........   | |
+        | +-----------.---------+  |        | +-------.--.----------+ |
+        |            |.            |        |         .| .            |
+        | +-----------.---------+  |        | +-------.--.----------+ |
+        | |           .................................  ..................>
+        | |    Tunnel Bridge    |-------------|   Tunnel Bridge     | |
+        | +---------------------+  | Tunnel | +---------------------+ |
+        |                          |        |                         |
+        +--------------------=-----+        +-------------------------+
+
+
+
+Flow Tables and Flow Rules
+--------------------------
+The OVS Agent adds additional flows (shown above) on the Integration bridge to support
+Port Chains:
+
+1. Egress Port Chain flows to steer traffic from SFs attached to the Integration bridge to a
+   Tunnel bridge to the next-hop Compute node. These flows may be handled using the OpenFlow
+   Group in the case where there are multiple port-pairs in the next-hop port-pair group.
+2. Ingress Port Chain flows on the Tunnel bridge to steer service chain traffic from a
+   tunnel from a previous Compute node to SFs attached to the Integration bridge.
+3. Internal Port Chain flows are used to steer service chain traffic from one SF to another SF
+   on the same Compute Node.
+
+The Port Chain flow rules have the higher priority, and will not impact
+the existing flow rules on the Integration bridge. If traffic from SF is not part of
+a service chain, e.g.,  DHCP messages, ARP packets etc., it will match the existing
+flow rules on the Integration bridge.
+
+The following tables are used to process Port Chain traffic:
+
+* Local Switching Table (Table 0). This existing table has two new flows to handle
+  incoming traffic from the SF egress port and the tunnel port between Compute nodes.
+
+* Group Table. This new table is used to select multiple paths for load-balancing across
+  multiple port-pairs in a port-pair group. There are multiple buckets in the group if the next
+  hop is a port-pair group with multiple port-pairs. The group actions will be to send the packet
+  to next hop SF instance.
+  If the next hop port-pair is on another Compute node, the action output to the tunnel port to the
+  next hop Compute node. If the next hop port-pair is on the same Compute node, then the
+  action will be to resubmit to the TUN_TABLE for local chaining process.
+
+Local Switching Table (Table 0) Flows
+-------------------------------------
+Traffic from SF Egress port: classify for chain and direct to group::
+
+ priority=10,in_port=SF_EGRESS_port,traffic_match_field,
+  actions=strip_vlan,set_tunnel:VNI,group:gid.
+
+Traffic from Tunnel port::
+
+ priority=10,in_port=TUNNEL_port,
+  actions=resubmit(,TUN_TABLE[type]).
+
+
+Group Table Flows
+-----------------
+The Group table is used for load distribution to spread the traffic load across a port-pair group of
+multiple port-pairs (SFs of the same type). This uses the hashing of several fields in the packet.
+There are multiple buckets in the group if the next hop is a port-pair group with multiple port-pairs.
+
+The group actions will be to send the packet to next hop SF instances. If the next hop port-pair
+is on another Compute node, the action output to the tunnel port to the next hop Compute node.
+If the next hop port-pair is on the same Compute node, then the action will be to resubmit
+to the TUN_TABLE for local chaining process.
+
+The OVSDB command to create a group of type Select with a hash selection method and two buckets
+is shown below. This is existing OVS functionality. The ip_src,nw_proto,tp_src packet fields are
+used for the hash::
+
+ group_id=gid,type=select,selection_method=hash,fields=ip_src,nw_proto,tp_src
+  bucket=set_field:10.1.1.3->ip_dst,output:10,
+  bucket=set_field:10.1.1.4->ip_dst,output:10
+
+
+Data Model Impact
+-----------------
+None
+
+Alternatives
+------------
+
+None
+
+Security Impact
+---------------
+
+None.
+
+Notifications Impact
+--------------------
+
+There will be logging to trouble-shoot and verify correct operation.
+
+Other End User Impact
+---------------------
+
+None.
+
+Performance Impact
+------------------
+
+It is not expected that these flows will have a significant performance impact.
+
+IPv6 Impact
+-----------
+
+None.
+
+Other Deployer Impact
+---------------------
+
+None
+
+Developer Impact
+----------------
+
+None
+
+Community Impact
+----------------
+
+Existing OVS driver and agent functionality will not be affected.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+* Cathy Zhang (cathy.h.zhang@huawei.com)
+* Louis Fourie (louis.fourie@huawei.com)
+* Stephen Wong (stephen.kf.wong@gmail.com)
+
+Work Items
+----------
+
+* Port Chain OVS driver.
+* Port Chain OVS agent.
+* Unit test.
+
+Dependencies
+============
+
+This design depends upon the proposed `Neutron Service Chaining API extensions <https://blueprints.launchpad.net/neutron/+spec/neutron-api-extension-for-service-chaining>`_
+
+Openvswitch.
+
+Testing
+=======
+
+Tempest and functional tests will be created.
+
+Documentation Impact
+====================
+
+Documented as extension.
+
+User Documentation
+------------------
+
+Update networking API reference.
+Update admin guide.
+
+Developer Documentation
+-----------------------
+
+None
+
diff --git a/doc/source/system_design and_workflow.rst b/doc/source/system_design and_workflow.rst
new file mode 100644
index 0000000..11e0849
--- /dev/null
+++ b/doc/source/system_design and_workflow.rst
@@ -0,0 +1,245 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+==========================
+System Design and Workflow
+==========================
+
+Problem Description
+===================
+The `Service Chaining API specification <http://docs.openstack.org/developer/networking-sfc/api.html>`_ proposes a Neutron port based solution for setting up a service chain. A specification on the system architecture and related API work flow is needed to guide the code design.
+
+System Architecture
+============================
+The following figure shows the generic architecture of the Port Chain
+Plugin. As shown in the diagram, Port Chain Plugin can be backed by
+different service providers such as OVS Driver and/or different types of
+SDN Controller Drivers. Through the "Common Driver API", these
+different drivers can provide different implementations for the service
+chain path rendering. In the first release and deployment based on this
+release, we will only deliver codes for the OVS driver. In the next release,
+we can add codes to support multiple active drivers::
+
+    Port Chain Plugin With Different Types of Drivers
+   +-----------------------------------------------------------------+
+   |  +-----------------------------------------------------------+  |
+   |  |                        Port Chain API                     |  |
+   |  +-----------------------------------------------------------+  |
+   |  |                        Port Chain Database                |  |
+   |  +-----------------------------------------------------------+  |
+   |  |                        Driver Manager                     |  |
+   |  +-----------------------------------------------------------+  |
+   |  |                        Common Driver API                  |  |
+   |  +-----------------------------------------------------------+  |
+   |                                   |                             |
+   |  +------------+------------------------+---------------------+  |
+   |  | OVS Driver |   Controller Driver1   |  Controller Driver2 |  |
+   |  +------------+------------------------+---------------------+  |
+   +-------|------------------|-------------------------|------------+
+           |                  |                         |
+      +-----------+   +-----------------+      +-----------------+
+      | OVS Agent |   | SDN Controller1 |      | SDN Controller2 |
+      +-----------+   +-----------------+      +-----------------+
+
+The second figure below shows the reference implementation architecture,
+which is through the OVS Driver path. The figure shows the components
+that will be added on the Neutron Server and the compute nodes to
+support this Neutron Based SFC functionality. As shown in the diagram,
+a new Port Chain Plugin will be added to the Neutron Server.
+The existing "OVS Driver" and "OVS Agent" will be extended to support
+the service chain functionality. The OVS Driver will communicate with
+each OVS Agent to program its OVS forwarding table properly so that a
+tenant's traffic flow can be steered through the user defined sequence
+of Neutron ports to get the desired service treatment from the Service
+Function running on the VMs.
+
+A separate `OVS Driver and Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_ will describe in more
+detail on the design consideration of the Driver, Agent, and how to set up the
+classification rules on the OVS to identify different flows and how to
+set up the OVS forwarding table. In the reference implementation, the OVS Driver
+communicates with OVS Agent through RPC to program the OVS. The communication
+between the OVS Agent and the OVS is through OVSDB/Openflow::
+
+
+       Port Chain Plugin With OVS Driver
+      +-------------------------------+
+      |  +-------------------------+  |
+      |  |    Port Chain API       |  |
+      |  +-------------------------+  |
+      |  |    Port Chain Database  |  |
+      |  +-------------------------+  |
+      |  |    Driver Manager       |  |
+      |  +-------------------------+  |
+      |  |    Common Driver API    |  |
+      |  +-------------------------+  |
+      |              |                |
+      |  +-------------------------+  |
+      |  |        OVS Driver       |  |
+      |  +-------------------------+  |
+      +-------|----------------|------+
+              |                |
+         +-----------+   +-----------+
+         | OVS Agent |   | OVS Agent |
+         +-----------+   +-----------+
+
+Port Chain Creation Workflow
+============================
+The following example shows how the Neutron CLI commands may be used to
+create a port-chain consisting of a service VM vm1 and a service VM
+vm2. The user can be an Admin/Tenant or an Application built on top.
+
+Traffic flow into the Port Chain will be from source IP address
+22.1.20.1 TCP port 23 to destination IP address 171.4.5.6 TCP port 100.
+The flow needs to be treated by SF1 running on VM1 identified by
+Neutron port pair [p1, p2] and SF2 running on VM2 identified by Neutron
+port pair [p3, p4].
+
+The net1 should be created before creating Neutron port using existing
+Neutron API. The design has no restriction on the type of net1, i.e. it
+can be any type of Neutron network since SFC traffic will be tunneled
+transparently through the type of communication channels of net1.
+If the transport between vSwitches is VXLAN, then we will use that VXLAN
+tunnel (and NOT create another new tunnel) to transport the SFC traffic
+through. If the transport between vSwitches is Ethernet, then the SFC
+traffic will be transported through Ethernet. In other words, the SFC
+traffic will be carried over existing transport channel between vSwitches
+and the external transport channel between vSwitches is set up for net1
+through existing Neutron API and ML2. The built-in OVS backend
+implements tunneling the original flow packets over VXLAN tunnel. The detailed
+outer VXLAN tunnel transport format and inner SFC flow format including
+how to leverage existing OVS's support for MPLS label to carry chain ID
+will be described in the `Port Chain OVS Driver and Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_.
+In the future we can add implementation of tunneling the SFC flow packets over
+flat L2 Ethernet or L3 IP network or GRE tunnel etc.
+
+Boot service VMs and attach ports
+---------------------------------
+Create Neutron ports on network net1::
+
+   neutron port-create --name p1 net1
+   neutron port-create --name p2 net1
+   neutron port-create --name p3 net1
+   neutron port-create --name p4 net1
+
+Boot VM1 from Nova with ports p1 and p2 using two --nic options::
+
+ nova boot --image xxx --nic port-id=p1 --nic port-id=p2 vm1
+
+Boot VM2 from Nova with ports p3 and p4 using two --nic options::
+
+ nova boot --image yyy --nic port-id=p3 --nic port-id=p4 vm2
+
+Alternatively, the user can create each VM with one VNIC and then
+attach another Neutron port to the VM::
+
+ nova boot --image xxx --nic port-id=p1 vm1
+ nova interface-attach --port-id p2 vm1
+ nova boot --image yyy --nic port-id=p3 vm2
+ nova interface-attach --port-id p4 vm2
+
+Once the Neutron ports p1 - p4 exist, the Port Chain is created using
+the steps described below.
+
+Create Flow Classifier
+----------------------
+Create flow-classifier FC1 that matches on source IP address 22.1.20.1
+(ingress direction) and destination IP address 171.4.5.6 (egress
+direction) with TCP connection, source port 23 and destination port
+100::
+
+ neutron flow-classifier-create
+  --ip-version ipv4
+  --source-ip-prefix 22.1.20.1/32
+  --destination-ip-prefix 172.4.5.6/32
+  --protocol tcp
+  --source-port 23:23
+  --destination-port 100:100 FC1
+
+Create Port Pair
+-----------------
+Create port-pair PP1 with ports p1 and p2, port-pair PP2 with
+ports p3 and p4, port-pair PP3 with ports P5 and P6::
+
+ neutron port-pair-create
+        --ingress=p1
+        --egress=p2 PP1
+ neutron port-pair-create
+        --ingress=p3
+        --egress=p4 PP2
+ neutron port-pair-create
+        --ingress=p5
+        --egress=p6 PP3
+
+Create Port Group
+-----------------
+Create port-pair-group PG1 with port-pair PP1 and PP2, and
+port-pair-group PG2 with port-pair PP3::
+
+ neutron port-pair-group-create
+        --port-pair PP1 --port-pair PP2 PG1
+ neutron port-pair-group-create
+        --port-pair PP3 PG2
+
+Create Port Chain
+-----------------
+
+Create port-chain PC1 with port-group PG1 and PG2, and flow
+classifier FC1::
+
+ neutron port-chain-create
+        --port-pair-group PG1 --port-pair-group PG2 --flow-classifier FC1 PC1
+
+This will result in the Port chain driver being invoked to create the
+Port Chain.
+
+The following diagram illustrates the code execution flow (not the
+exact codes) for the port chain creation::
+
+ PortChainAPIParsingAndValidation: create_port_chain
+                |
+                V
+ PortChainPlugin: create_port_chain
+                |
+                V
+ PortChainDbPlugin: create_port_chain
+                |
+                V
+ DriverManager: create_port_chain
+                |
+                V
+ portchain.drivers.OVSDriver: create_port_chain
+
+The vSwitch Driver needs to figure out which switch VM1 is connecting
+with and which switch VM2 is connecting with (for OVS case, the OVS
+driver has that information given the VMs' port info). As to the
+connection setup between the two vSwitches, it should be done through
+existing ML2 plugin mechanism. The connection between these two
+vSwitches should already be set up before the user initiates the SFC
+request. The service chain flow packets will be tunneled through the
+connecting type/technology (e.g. VXLAN or GRE) between the two
+vSwitches. For our reference code implementation, we will use VXLAN to
+show a complete data path setup. Please refer to the `OVS Driver and OVS
+Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_ for more detail info.
+
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
new file mode 100644
index 0000000..c097c33
--- /dev/null
+++ b/doc/source/usage.rst
@@ -0,0 +1,32 @@
+..
+      Copyright 2015 Futurewei. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+=====
+Usage
+=====
+
+To use networking-sfc in a project::
+
+    import networking_sfc