summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/source/alembic_migration.rst102
-rwxr-xr-xdoc/source/api.rst626
-rw-r--r--doc/source/command_extensions.rst64
-rwxr-xr-xdoc/source/conf.py76
-rw-r--r--doc/source/contribution.rst29
-rw-r--r--doc/source/index.rst66
-rw-r--r--doc/source/installation.rst37
-rw-r--r--doc/source/ovs_driver_and_agent_workflow.rst311
-rw-r--r--doc/source/system_design and_workflow.rst245
-rw-r--r--doc/source/usage.rst32
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