--- /dev/null
+Service Function Chaining
+=========================
+
+OpenDaylight Service Function Chaining (SFC) Overiew
+----------------------------------------------------
+
+OpenDaylight Service Function Chaining (SFC) provides the ability to
+define an ordered list of a network services (e.g. firewalls, load
+balancers). These service are then "stitched" together in the network to
+create a service chain. This project provides the infrastructure
+(chaining logic, APIs) needed for ODL to provision a service chain in
+the network and an end-user application for defining such chains.
+
+- ACE - Access Control Entry
+
+- ACL - Access Control List
+
+- SCF - Service Classifier Function
+
+- SF - Service Function
+
+- SFC - Service Function Chain
+
+- SFF - Service Function Forwarder
+
+- SFG - Service Function Group
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+- NSH - Network Service Header
+
+SFC Classifier Control and Date plane Developer guide
+-----------------------------------------------------
+
+Overview
+~~~~~~~~
+
+Description of classifier can be found in:
+https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
+
+Classifier manages everything from starting the packet listener to
+creation (and removal) of appropriate ip(6)tables rules and marking
+received packets accordingly. Its functionality is **available only on
+Linux** as it leverdges **NetfilterQueue**, which provides access to
+packets matched by an **iptables** rule. Classifier requires **root
+privileges** to be able to operate.
+
+So far it is capable of processing ACL for MAC addresses, ports, IPv4
+and IPv6. Supported protocols are TCP and UDP.
+
+Classifier Architecture
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Python code located in the project repository
+sfc-py/common/classifier.py.
+
+.. note::
+
+ classifier assumes that Rendered Service Path (RSP) **already
+ exists** in ODL when an ACL referencing it is obtained
+
+1. sfc\_agent receives an ACL and passes it for processing to the
+ classifier
+
+2. the RSP (its SFF locator) referenced by ACL is requested from ODL
+
+3. if the RSP exists in the ODL then ACL based iptables rules for it are
+ applied
+
+After this process is over, every packet successfully matched to an
+iptables rule (i.e. successfully classified) will be NSH encapsulated
+and forwarded to a related SFF, which knows how to traverse the RSP.
+
+Rules are created using appropriate iptables command. If the Access
+Control Entry (ACE) rule is MAC address related both iptables and
+ip6tabeles rules re issued. If ACE rule is IPv4 address related, only
+iptables rules are issued, same for IPv6.
+
+.. note::
+
+ iptables **raw** table contains all created rules
+
+Information regarding already registered RSP(s) are stored in an
+internal data-store, which is represented as a dictionary:
+
+::
+
+ {rsp_id: {'name': <rsp_name>,
+ 'chains': {'chain_name': (<ipv>,),
+ ...
+ },
+ 'sff': {'ip': <ip>,
+ 'port': <port>,
+ 'starting-index': <starting-index>,
+ 'transport-type': <transport-type>
+ },
+ },
+ ...
+ }
+
+- ``name``: name of the RSP
+
+- ``chains``: dictionary of iptables chains related to the RSP with
+ information about IP version for which the chain exists
+
+- ``SFF``: SFF forwarding parameters
+
+ - ``ip``: SFF IP address
+
+ - ``port``: SFF port
+
+ - ``starting-index``: index given to packet at first RSP hop
+
+ - ``transport-type``: encapsulation protocol
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This features exposes API to configure classifier (corresponds to
+service-function-classifier.yang)
+
+API Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See: sfc-model/src/main/yang/service-function-classifier.yang
+
+SFC-OVS Plugin
+--------------
+
+Overview
+~~~~~~~~
+
+SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
+Integration is realized through mapping of SFC objects (like SF, SFF,
+Classifier, etc.) to OVS objects (like Bridge,
+TerminationPoint=Port/Interface). The mapping takes care of automatic
+instantiation (setup) of corresponding object whenever its counterpart
+is created. For example, when a new SFF is created, the SFC-OVS plugin
+will create a new OVS bridge and when a new OVS Bridge is created, the
+SFC-OVS plugin will create a new SFF.
+
+SFC-OVS Architecture
+~~~~~~~~~~~~~~~~~~~~
+
+SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing
+information from/to OVS devices. The core functionality consists of two
+types of mapping:
+
+a. mapping from OVS to SFC
+
+ - OVS Bridge is mapped to SFF
+
+ - OVS TerminationPoints are mapped to SFF DataPlane locators
+
+b. mapping from SFC to OVS
+
+ - SFF is mapped to OVS Bridge
+
+ - SFF DataPlane locators are mapped to OVS TerminationPoints
+
+.. figure:: ./images/sfc/sfc-ovs-architecture.png
+ :alt: SFC < — > OVS mapping flow diagram
+
+ SFC < — > OVS mapping flow diagram
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- SFF to OVS mapping API (methods to convert SFF object to OVS Bridge
+ and OVS TerminationPoints)
+
+- OVS to SFF mapping API (methods to convert OVS Bridge and OVS
+ TerminationPoints to SFF object)
+
+SFC Southbound REST Plugin
+--------------------------
+
+Overview
+~~~~~~~~
+
+The Southbound REST Plugin is used to send configuration from DataStore
+down to network devices supporting a REST API (i.e. they have a
+configured REST URI). It supports POST/PUT/DELETE operations, which are
+triggered accordingly by changes in the SFC data stores.
+
+- Access Control List (ACL)
+
+- Service Classifier Function (SCF)
+
+- Service Function (SF)
+
+- Service Function Group (SFG)
+
+- Service Function Schedule Type (SFST)
+
+- Service Function Forwader (SFF)
+
+- Rendered Service Path (RSP)
+
+Southbound REST Plugin Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **listeners** - used to listen on changes in the SFC data stores
+
+2. **JSON exporters** - used to export JSON-encoded data from
+ binding-aware data store objects
+
+3. **tasks** - used to collect REST URIs of network devices and to send
+ JSON-encoded data down to these devices
+
+.. figure:: ./images/sfc/sb-rest-architecture.png
+ :alt: Southbound REST Plugin Architecture diagram
+
+ Southbound REST Plugin Architecture diagram
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The plugin provides Southbound REST API designated to listening REST
+devices. It supports POST/PUT/DELETE operations. The operation (with
+corresponding JSON-encoded data) is sent to unique REST URL belonging to
+certain datatype.
+
+- Access Control List (ACL):
+ ``http://<host>:<port>/config/ietf-acl:access-lists/access-list/``
+
+- Service Function (SF):
+ ``http://<host>:<port>/config/service-function:service-functions/service-function/``
+
+- Service Function Group (SFG):
+ ``http://<host>:<port>/config/service-function:service-function-groups/service-function-group/``
+
+- Service Function Schedule Type (SFST):
+ ``http://<host>:<port>/config/service-function-scheduler-type:service-function-scheduler-types/service-function-scheduler-type/``
+
+- Service Function Forwarder (SFF):
+ ``http://<host>:<port>/config/service-function-forwarder:service-function-forwarders/service-function-forwarder/``
+
+- Rendered Service Path (RSP):
+ ``http://<host>:<port>/operational/rendered-service-path:rendered-service-paths/rendered-service-path/``
+
+Therefore, network devices willing to receive REST messages must listen
+on these REST URLs.
+
+.. note::
+
+ Service Classifier Function (SCF) URL does not exist, because SCF is
+ considered as one of the network devices willing to receive REST
+ messages. However, there is a listener hooked on the SCF data store,
+ which is triggering POST/PUT/DELETE operations of ACL object,
+ because ACL is referenced in ``service-function-classifier.yang``
+
+Service Function Load Balancing Developer Guide
+-----------------------------------------------
+
+Overview
+~~~~~~~~
+
+SFC Load-Balancing feature implements load balancing of Service
+Functions, rather than a one-to-one mapping between Service Function
+Forwarder and Service Function.
+
+Load Balancing Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Service Function Groups (SFG) can replace Service Functions (SF) in the
+Rendered Path model. A Service Path can only be defined using SFGs or
+SFs, but not a combination of both.
+
+Relevant objects in the YANG model are as follows:
+
+1. Service-Function-Group-Algorithm:
+
+ ::
+
+ Service-Function-Group-Algorithms {
+ Service-Function-Group-Algorithm {
+ String name
+ String type
+ }
+ }
+
+ ::
+
+ Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
+
+2. Service-Function-Group:
+
+ ::
+
+ Service-Function-Groups {
+ Service-Function-Group {
+ String name
+ String serviceFunctionGroupAlgorithmName
+ String type
+ String groupId
+ Service-Function-Group-Element {
+ String service-function-name
+ int index
+ }
+ }
+ }
+
+3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature enhances the existing SFC API.
+
+REST API commands include: \* For Service Function Group (SFG): read
+existing SFG, write new SFG, delete existing SFG, add Service Function
+(SF) to SFG, and delete SF from SFG \* For Service Function Group
+Algorithm (SFG-Alg): read, write, delete
+
+Bundle providing the REST API: sfc-sb-rest \* Service Function Groups
+and Algorithms are defined in: sfc-sfg and sfc-sfg-alg \* Relevant JAVA
+API: SfcProviderServiceFunctionGroupAPI,
+SfcProviderServiceFunctionGroupAlgAPI
+
+Service Function Scheduling Algorithms
+--------------------------------------
+
+Overview
+~~~~~~~~
+
+When creating the Rendered Service Path (RSP), the earlier release of
+SFC chose the first available service function from a list of service
+function names. Now a new API is introduced to allow developers to
+develop their own schedule algorithms when creating the RSP. There are
+four scheduling algorithms (Random, Round Robin, Load Balance and
+Shortest Path) are provided as examples for the API definition. This
+guide gives a simple introduction of how to develop service function
+scheduling algorithms based on the current extensible framework.
+
+Architecture
+~~~~~~~~~~~~
+
+The following figure illustrates the service function selection
+framework and algorithms.
+
+.. figure:: ./images/sfc-sf-selection-arch.png
+ :alt: SF Scheduling Algorithm framework Architecture
+
+ SF Scheduling Algorithm framework Architecture
+
+The YANG Model defines the Service Function Scheduling Algorithm type
+identities and how they are stored in the MD-SAL data store for the
+scheduling algorithms.
+
+The MD-SAL data store stores all informations for the scheduling
+algorithms, including their types, names, and status.
+
+The API provides some basic APIs to manage the informations stored in
+the MD-SAL data store, like putting new items into it, getting all
+scheduling algorithms, etc.
+
+The RESTCONF API provides APIs to manage the informations stored in the
+MD-SAL data store through RESTful calls.
+
+The Service Function Chain Renderer gets the enabled scheduling
+algorithm type, and schedules the service functions with scheduling
+algorithm implementation.
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+While developing a new Service Function Scheduling Algorithm, a new
+class should be added and it should extend the base schedule class
+SfcServiceFunctionSchedulerAPI. And the new class should implement the
+abstract function:
+
+``public List<String> scheduleServiceFuntions(ServiceFunctionChain chain, int serviceIndex)``.
+
+- **``ServiceFunctionChain chain``**: the chain which will be rendered
+
+- **``int serviceIndex``**: the initial service index for this rendered
+ service path
+
+- **``List<String>``**: a list of service funtion names which scheduled
+ by the Service Function Scheduling Algorithm.
+
+API Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please refer the API docs generated in the mdsal-apidocs.
+
+++ /dev/null
-=== SFC Southbound REST Plugin
-
-==== Overview
-The Southbound REST Plugin is used to send configuration from DataStore down to
-network devices supporting a REST API (i.e. they have a configured REST URI).
-It supports POST/PUT/DELETE operations, which are triggered accordingly by
-changes in the SFC data stores.
-
-.In its current state it listens to changes in these SFC data stores:
-* Access Control List (ACL)
-* Service Classifier Function (SCF)
-* Service Function (SF)
-* Service Function Group (SFG)
-* Service Function Schedule Type (SFST)
-* Service Function Forwader (SFF)
-* Rendered Service Path (RSP)
-
-==== Southbound REST Plugin Architecture
-.The Southbound REST Plugin is built from three main components:
-. *listeners* - used to listen on changes in the SFC data stores
-. *JSON exporters* - used to export JSON-encoded data from binding-aware data
-store objects
-. *tasks* - used to collect REST URIs of network devices and to send JSON-encoded
-data down to these devices
-
-.Southbound REST Plugin Architecture diagram
-image::sfc/sb-rest-architecture.png[width=500]
-
-==== Key APIs and Interfaces
-The plugin provides Southbound REST API designated to listening REST devices. It supports
-POST/PUT/DELETE operations. The operation (with corresponding JSON-encoded data) is sent
-to unique REST URL belonging to certain datatype.
-
-.The URLs are following:
-* Access Control List (ACL):
-+http://<host>:<port>/config/ietf-acl:access-lists/access-list/+
-* Service Function (SF):
-+http://<host>:<port>/config/service-function:service-functions/service-function/+
-* Service Function Group (SFG):
-+http://<host>:<port>/config/service-function:service-function-groups/service-function-group/+
-* Service Function Schedule Type (SFST):
-+http://<host>:<port>/config/service-function-scheduler-type:service-function-scheduler-types/service-function-scheduler-type/+
-* Service Function Forwarder (SFF):
-+http://<host>:<port>/config/service-function-forwarder:service-function-forwarders/service-function-forwarder/+
-* Rendered Service Path (RSP):
-+http://<host>:<port>/operational/rendered-service-path:rendered-service-paths/rendered-service-path/+
-
-Therefore, network devices willing to receive REST messages must listen on
-these REST URLs.
-
-[NOTE]
-Service Classifier Function (SCF) URL does not exist, because SCF is considered
-as one of the network devices willing to receive REST messages. However, there
-is a listener hooked on the SCF data store, which is triggering POST/PUT/DELETE
-operations of ACL object, because ACL is referenced in +service-function-classifier.yang+
Code Review / docs.git / commitdiff
