--- /dev/null
+=== SFC IOS XE Renderer User Guide
+
+:SFCIOSXERNDR: SFC IOS-XE renderer
+
+==== Overview
+The early Service Function Chaining (SFC) renderer for IOS-XE devices
+({SFCIOSXERNDR}) implements Service Chaining functionality on IOS-XE
+capable switches. It listens for the creation of a Rendered Service
+Path (RSP) and sets up Service Function Forwarders (SFF) that are hosted
+on IOS-XE switches to steer traffic through the service chain.
+
+Common acronyms used in the following sections:
+
+* SF - Service Function
+* SFF - Service Function Forwarder
+* SFC - Service Function Chain
+* SP - Service Path
+* SFP - Service Function Path
+* RSP - Rendered Service Path
+* LSF - Local Service Forwarder
+* RSF - Remote Service Forwarder
+
+==== SFC IOS-XE Renderer Architecture
+When the {SFCIOSXERNDR} is initialized, all required listeners are registered
+to handle incoming data. It involves CSR/IOS-XE +NodeListener+ which stores
+data about all configurable devices including their mountpoints (used here
+as databrokers), +ServiceFunctionListener+, +ServiceForwarderListener+
+(see mapping) and +RenderedPathListener+ used to listen for
+RSP changes. When the {SFCIOSXERNDR} is invoked, +RenderedPathListener+ calls
+the +IosXeRspProcessor+ which processes the RSP change and creates all necessary
+Service Paths and Remote Service Forwarders (if necessary) on IOS-XE devices.
+
+==== Service Path details
+Each Service Path is defined by index (represented by NSP) and contains
+service path entries. Each entry has appropriate service index
+(NSI) and definition of next hop. Next hop can be Service Function, different
+Service Function Forwarder or definition of end of chain - terminate. After
+terminating, the packet is sent to destination. If a SFF is defined as a next hop,
+it has to be present on device in the form of Remote Service Forwarder.
+RSFs are also created during RSP processing.
+
+Example of Service Path:
+
+ service-chain service-path 200
+ service-index 255 service-function firewall-1
+ service-index 254 service-function dpi-1
+ service-index 253 terminate
+
+==== Mapping to IOS-XE SFC entities
+Renderer contains mappers for SFs and SFFs. IOS-XE capable device is using its
+own definition of Service Functions and Service Function Forwarders according to
+appropriate .yang file.
++ServiceFunctionListener+ serves as a listener for SF changes. If SF appears in
+datastore, listener extracts its management ip address and looks into cached IOS-XE
+nodes. If some of available nodes match, Service function is mapped
+in +IosXeServiceFunctionMapper+ to be understandable by IOS-XE device and it's
+written into device's config.
++ServiceForwarderListener+ is used in a similar way. All SFFs with suitable
+management ip address it mapped in +IosXeServiceForwarderMapper+. Remapped SFFs
+are configured as a Local Service Forwarders. It is not possible to directly create
+Remote Service Forwarder using IOS-XE renderer. RSF is created only during RSP processing.
+
+==== Administering {SFCIOSXERNDR}
+To use the SFC IOS-XE Renderer Karaf, at least the following Karaf
+features must be installed:
+
+* odl-aaa-shiro
+* odl-sfc-model
+* odl-sfc-provider
+* odl-restconf
+* odl-netconf-topology
+* odl-sfc-ios-xe-renderer
+
+==== {SFCIOSXERNDR} Tutorial
+
+===== Overview
+This tutorial is a simple example how to create Service Path on IOS-XE capable device
+using IOS-XE renderer
+
+===== Preconditions
+To connect to IOS-XE device, it is necessary to use several modified yang models and override
+device's ones. All .yang files are in the +Yang/netconf+ folder in the +sfc-ios-xe-renderer module+ in
+the SFC project. These files have to be copied to the +cache/schema+ directory, before
+Karaf is started. After that, custom capabilities have to be sent to network-topology:
+
+----
+PUT ./config/network-topology:network-topology/topology/topology-netconf/node/<device-name>
+
+<node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
+ <node-id>device-name</node-id>
+ <host xmlns="urn:opendaylight:netconf-node-topology">device-ip</host>
+ <port xmlns="urn:opendaylight:netconf-node-topology">2022</port>
+ <username xmlns="urn:opendaylight:netconf-node-topology">login</username>
+ <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
+ <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
+ <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">0</keepalive-delay>
+ <yang-module-capabilities xmlns="urn:opendaylight:netconf-node-topology">
+ <override>true</override>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2013-07-15
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ios?module=ned&revision=2016-03-08
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-common&revision=2015-05-22
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-meta-extensions&revision=2013-11-07
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-cli-extensions&revision=2015-03-19
+ </capability>
+ </yang-module-capabilities>
+</node>
+----
+
+NOTE: The device name in the URL and in the XML must match.
+
+===== Instructions
+When the IOS-XE renderer is installed, all NETCONF nodes in topology-netconf are
+processed and all capable nodes with accessible mountpoints are cached.
+The first step is to create LSF on node.
+
++Service Function Forwarder configuration+
+
+----
+PUT ./config/service-function-forwarder:service-function-forwarders
+
+{
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "CSR1Kv-2",
+ "ip-mgmt-address": "172.25.73.23",
+ "sff-data-plane-locator": [
+ {
+ "name": "CSR1Kv-2-dpl",
+ "data-plane-locator": {
+ "transport": "service-locator:vxlan-gpe",
+ "port": 6633,
+ "ip": "10.99.150.10"
+ }
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+If the IOS-XE node with appropriate management IP exists, this configuration
+is mapped and LSF is created on the device. The same approach is used for
+Service Functions.
+
+----
+PUT ./config/service-function:service-functions
+
+{
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "Firewall",
+ "ip-mgmt-address": "172.25.73.23",
+ "type": "service-function-type: firewall",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "firewall-dpl",
+ "port": 6633,
+ "ip": "12.1.1.2",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ },
+ {
+ "name": "Dpi",
+ "ip-mgmt-address": "172.25.73.23",
+ "type":"service-function-type: dpi",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "dpi-dpl",
+ "port": 6633,
+ "ip": "12.1.1.1",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ },
+ {
+ "name": "Qos",
+ "ip-mgmt-address": "172.25.73.23",
+ "type":"service-function-type: qos",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "qos-dpl",
+ "port": 6633,
+ "ip": "12.1.1.4",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+All these SFs are configured on the same device as the LSF. The next step is to
+prepare Service Function Chain. SFC is symmetric.
+
+----
+PUT ./config/service-function-chain:service-function-chains/
+
+{
+ "service-function-chains": {
+ "service-function-chain": [
+ {
+ "name": "CSR3XSF",
+ "symmetric": "true",
+ "sfc-service-function": [
+ {
+ "name": "Firewall",
+ "type": "service-function-type: firewall"
+ },
+ {
+ "name": "Dpi",
+ "type": "service-function-type: dpi"
+ },
+ {
+ "name": "Qos",
+ "type": "service-function-type: qos"
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+Service Function Path:
+
+----
+PUT ./config/service-function-path:service-function-paths/
+
+{
+ "service-function-paths": {
+ "service-function-path": [
+ {
+ "name": "CSR3XSF-Path",
+ "service-chain-name": "CSR3XSF",
+ "starting-index": 255,
+ "symmetric": "true"
+ }
+ ]
+ }
+}
+----
+
+Without a classifier, there is possibility to POST RSP directly.
+
+----
+POST ./operations/rendered-service-path:create-rendered-path
+
+{
+ "input": {
+ "name": "CSR3XSF-Path-RSP",
+ "parent-service-function-path": "CSR3XSF-Path",
+ "symmetric": true
+ }
+}
+----
+
+The resulting configuration:
+
+----
+!
+service-chain service-function-forwarder local
+ ip address 10.99.150.10
+!
+service-chain service-function firewall
+ip address 12.1.1.2
+ encapsulation gre enhanced divert
+!
+service-chain service-function dpi
+ip address 12.1.1.1
+ encapsulation gre enhanced divert
+!
+service-chain service-function qos
+ip address 12.1.1.4
+ encapsulation gre enhanced divert
+!
+service-chain service-path 1
+ service-index 255 service-function firewall
+ service-index 254 service-function dpi
+ service-index 253 service-function qos
+ service-index 252 terminate
+!
+service-chain service-path 2
+ service-index 255 service-function qos
+ service-index 254 service-function dpi
+ service-index 253 service-function firewall
+ service-index 252 terminate
+!
+----
+
+Service Path 1 is direct, Service Path 2 is reversed. Path numbers may vary.
+
+:SFCIOSXERNDR!:
=== SFC OpenFlow Renderer User Guide
+:SFCOFRNDR: SFC OF Renderer
+
==== Overview
-The Service Function Chaining (SFC) OpenFlow Renderer (SFCOFL2)
+The Service Function Chaining (SFC) OpenFlow Renderer ({SFCOFRNDR})
implements Service Chaining on OpenFlow switches. It listens for the
creation of a Rendered Service Path (RSP), and once received it programs
Service Function Forwarders (SFF) that are hosted on OpenFlow capable
* RSP - Rendered Service Path
==== SFC OpenFlow Renderer Architecture
-The SFCOFL2 is invoked after a RSP is created using an MD-SAL listener
-called +SfcL2RspDataListener+. Upon SFCOFL2 initialization, the
-+SfcL2RspDataListener+ registers itself to listen for RSP changes.
-When invoked, the +SfcL2RspDataListener+ processes the RSP and calls
-the +SfcL2FlowProgrammerOFImpl+ to create the necessary flows in the
+The {SFCOFRNDR} is invoked after a RSP is created using an MD-SAL listener
+called +SfcOfRspDataListener+. Upon {SFCOFRNDR} initialization, the
++SfcOfRspDataListener+ registers itself to listen for RSP changes.
+When invoked, the +SfcOfRspDataListener+ processes the RSP and calls
+the +SfcOfFlowProgrammerImpl+ to create the necessary flows in the
Service Function Forwarders configured in the RSP. Refer to the
following diagram for more details.
.SFC OpenFlow Renderer High Level Architecture
-image::sfc/sfcofl2_architecture.jpg["SFC OpenFlow Renderer High Level Architecture",width=500]
+image::sfc/sfcofrenderer_architecture.png["SFC OpenFlow Renderer High Level Architecture",width=500]
==== SFC OpenFlow Switch Flow pipeline
The SFC OpenFlow Renderer uses the following tables for its Flow pipeline:
diagram.
.SFC OpenFlow Renderer Typical Network Topology
-image::sfc/sfcofl2_architecture_nwtopo.jpg["SFC OpenFlow Renderer Typical Network Topology",width=500]
+image::sfc/sfcofrenderer_nwtopo.png["SFC OpenFlow Renderer Typical Network Topology",width=500]
===== Classifier Table detailed
GRE (UDP port 4789):
.Table Transport Ingress
-[width=60%]
+[cols="1,3,2"]
|===
|Priority |Match | Action
the source MAC address (MacSrc).
.Table Next Hop
-[width=75%]
+[cols="1,3,3"]
|===
|Priority |Match | Action
packets are just sent back where they came from.
.Table Transport Egress
-[width=60%]
+[cols="1,3,3"]
|===
|Priority |Match | Action
|Drop
|===
-==== Administering SFCOFL2
+==== Administering {SFCOFRNDR}
To use the SFC OpenFlow Renderer Karaf, at least the following Karaf
features must be installed.
* odl-openflowplugin-flow-services
* odl-sfc-provider
* odl-sfc-model
-* odl-sfcofl2
+* odl-sfc-openflow-renderer
* odl-sfc-ui (optional)
The following command can be used to view all of the currently installed Karaf features:
To install a particular feature, use the Karaf `feature:install` command.
-==== SFCOFL2 Tutorial
+==== {SFCOFRNDR} Tutorial
===== Overview
In this tutorial, 2 different encapsulations will be shown: MPLS and NSH. The
in creating the Service Chains.
.SFC OpenFlow Renderer Typical Network Topology
-image::sfc/sfcofl2_architecture_nwtopo.jpg["SFC OpenFlow Renderer Typical Network Topology",width=500]
+image::sfc/sfcofrenderer_nwtopo.png["SFC OpenFlow Renderer Typical Network Topology",width=500]
===== Prerequisites
To use this example, SFF OpenFlow switches must be created and
configuration chapters, the appropriate `curl` command is shown for
each configuration to be sent, including the URL.
-Steps to configure the SFCOFL2 tutorial:
+Steps to configure the {SFCOFRNDR} tutorial:
. Send the `SF` RESTCONF configuration
. Send the `SFF` RESTCONF configuration
string with the appropriate JSON configuration. Also, change the
`localhost` desintation in the URL accordingly.
-====== SFCOFL2 NSH Tutorial
+====== {SFCOFRNDR} NSH Tutorial
The following configuration sections show how to create the different elements
using NSH encapsulation.
curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
-====== SFCOFL2 MPLS Tutorial
+====== {SFCOFRNDR} MPLS Tutorial
The following configuration sections show how to create the different elements
using MPLS encapsulation.
curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
+
+
+
+:SFCOFRNDR!:
+
--- /dev/null
+=== SFC Proof of Transit User Guide
+
+:SFCPOT: SFC Proof of Transit
+
+==== Overview
+Early Service Function Chaining (SFC) Proof of Transit ({SFCPOT})
+implements Service Chaining Proof of Transit functionality on
+capable switches. After the creation of an Rendered Service
+Path (RSP), a user can configure to enable SFC proof of transit
+on the selected RSP to effect the proof of transit.
+
+Common acronyms used in the following sections:
+
+* SF - Service Function
+* SFF - Service Function Forwarder
+* SFC - Service Function Chain
+* SFP - Service Function Path
+* RSP - Rendered Service Path
+* SFCPOT - Service Function Chain Proof of Transit
+
+==== SFC Proof of Transit Architecture
+When {SFCPOT} is initialized, all required listeners are registered
+to handle incoming data. It involves +SfcPotNodeListener+ which stores
+data about all node devices including their mountpoints (used here
+as databrokers), +SfcPotRSPDataListener+, +RenderedPathListener+.
++RenderedPathListener+ is used to listen for RSP changes.
++SfcPotRSPDataListener+ implements RPC services to enable or disable
+SFC Proof of Transit on a particular RSP. When the {SFCPOT} is invoked,
+RSP listeners and service implementations are setup to receive SFCPOT
+configurations. When a user configures via a POST RPC call to enable
+SFCPOT on a particular RSP, the configuration drives the creation of
+necessary augmentations to the RSP to effect the SFCPOT configurations.
+
+==== SFC Proof of Transit details
+Several deployments use traffic engineering, policy routing,
+segment routing or service function chaining (SFC) to steer packets
+through a specific set of nodes. In certain cases regulatory obligations
+or a compliance policy require to prove that all packets that are
+supposed to follow a specific path are indeed being forwarded across
+the exact set of nodes specified. I.e. if a packet flow is supposed to
+go through a series of service functions or network nodes, it has to
+be proven that all packets of the flow actually went through the
+service chain or collection of nodes specified by the policy.
+In case the packets of a flow weren't appropriately processed, a
+proof of transit egress device would be required to identify the policy
+violation and take corresponding actions (e.g. drop or redirect the packet,
+send an alert etc.) corresponding to the policy.
+
+The SFCPOT approach is based on meta-data which is added to every packet.
+The meta data is updated at every hop and is used to verify whether
+a packet traversed all required nodes. A particular path is either
+described by a set of secret keys, or a set of shares of a single
+secret. Nodes on the path retrieve their individual keys or shares
+of a key (using for e.g. Shamir's Shared Sharing Secret scheme) from
+a central controller. The complete key set is only known to the
+verifier- which is typically the ultimate node on a path that
+requires proof of transit. Each node in the path uses its secret or share
+of the secret to update the meta-data of the packets as the packets
+pass through the node. When the verifier receives a packet, it can use
+its key(s) along with the meta-data to validate whether the packet
+traversed the service chain correctly.
+
+==== SFC Proof of Transit entities
+In order to implement SFC Proof of Transit for a service function chain,
+an RSP is a pre-requisite to identify the SFC to enable SFC PoT
+on. SFC Proof of Transit for a particular RSP is enabled by an RPC request
+to the controller along with necessary parameters to control some of the
+aspects of the SFC Proof of Transit process.
+
+The RPC handler identifies the RSP and generates SFC Proof of Transit
+parameters like secret share, secret etc., and adds the generated SFCPOT
+configuration parameters to SFC main as well as the various SFC hops.
+The last node in the SFC is configured as a verifier node to allow SFCPOT
+Proof of Transit process to be completed.
+
+The SFCPOT configuration generators and related handling are done by
++SfcPotAPI+, +SfcPotConfigGenerator+,
++SfcPotListener+, +SfcPotPolyAPI+,
++SfcPotPolyClassAPI+ and +SfcPotPolyClass+.
+
+==== Administering {SFCPOT}
+To use the SFC Proof of Transit Karaf, at least the following Karaf
+features must be installed:
+
+* odl-sfc-model
+* odl-sfc-provider
+* odl-sfc-netconf
+* odl-restconf
+* odl-netconf-topology
+* odl-netconf-connector-all
+* odl-sfc-pot
+
+==== {SFCPOT} Tutorial
+
+===== Overview
+This tutorial is a simple example how to configure Service Function Chain
+Proof of Transit using SFC POT feature.
+
+===== Preconditions
+To enable a device to handle SFC Proof of Transit, it is expected that the netconf server
+device advertise capability as under ioam-scv.yang present under src/main/yang folder of
+sfc-pot feature. It is also expected that netconf notifications be enabled and its
+support capability advertised as capabilities.
+
+It is also expected that the devices are netconf mounted and available in the
+topology-netconf store.
+
+===== Instructions
+When SFC Proof of Transit is installed, all netconf nodes in topology-netconf are
+processed and all capable nodes with accessible mountpoints are cached.
+
+First step is to create the required RSP as usually done.
+
+Once RSP name is avaiable it is used to send a POST RPC to the controller similar to
+below:
+
+----
+
+POST ./restconf/operations/sfc-ioam-nb-pot:enable-sfc-ioam-pot-rendered-path
+
+{
+ "input": {
+ "sfc-ioam-pot-rsp-name": "rsp1"
+ }
+}
+
+----
+
+The following can be used to disable the SFC Proof of Transit on an RSP which removes
+the augmentations and stores back the RSP without the SFCPOT enabled features and also
+sending down a delete configuration to the SFCPOT configuration sub-tree in the nodes.
+
+----
+
+POST ./restconf/operations/sfc-ioam-nb-pot:disable-sfc-ioam-pot-rendered-path
+
+{
+ "input": {
+ "sfc-ioam-pot-rsp-name": "rsp1"
+ }
+}
+
+----
+
+:SFCPOT!:
include::odl-sfc-classifier-user.adoc[SFC Classifier configuration User guide]
-include::odl-sfcofl2-user.adoc[SFC OpenFlow Renderer user guide]
+// SFC Renderers
+include::odl-sfc-openflow-renderer-user.adoc[SFC OpenFlow Renderer]
+
+include::odl-sfc-iosxe-renderer-user.adoc[SFC IOS XE Renderer]
+
+include::odl-sfc-vpp-renderer-user.adoc[SFC VPP Renderer]
+// SFC Renderers
include::odl-sfc-sf-scheduler-user.adoc[Service Function selection scheduler]
// include::odl-sfc-sf-monitoring-user.adoc[Service Function Monitoring]
include::odl-sfc-load-balance-user.adoc[Service Function Grouping and Load Balancing user guide]
+
+include::odl-sfc-pot-user.adoc[SFC Proof of Transit]
Code Review / docs.git / commitdiff
