Merge "Adding initial trouble shooting E-CORD guide"
diff --git a/docs/README.md b/docs/README.md
index 505eceb..3121dbf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,9 +1,38 @@
# E-CORD Profile
-This repository is intended to host the E-CORD documentation, XOS Models definitions and XOS GUI Extensions that are horizontal to the profile and not tied to a single service.
+The E-CORD (Enterprise CORD) profile is `Official` as of 4.1.
-It contains an overview of E-CORD and an installation guide that outlines step by step how to deploy an end to end E-CORD solution.
+## Service Manifest
+E-CORD includes two service manifests:
-It contains models and GUIs for both `ecord-local` and `ecord-global` profiles.
+#### [ecord-global](https://github.com/opencord/platform-install/blob/master/profile_manifest s/ecord-global.yml)
+
+| Service | Source Code |
+|-------------|---------------|
+| vNaaS | https://github.com/opencord/vnaas |
+| ONOS | https://github.com/opencord/onos-service |
+
+#### [ecord-local](https://github.com/opencord/platform-install/blob/master/profile_manifest s/ecord.yml)
+
+| Service | Source Code |
+|--------------|---------------|
+| vEE | https://github.com/opencord/vee |
+| vEG | https://github.com/opencord/veg |
+| vRouter | https://github.com/opencord/vrouter |
+| AddressManager | https://github.com/opencord/addressmanager |
+| VTN | https://github.com/opencord/vtn |
+| Fabric | https://github.com/opencord/fabric |
+| OpenStack | https://github.com/opencord/openstack |
+| ONOS | https://github.com/opencord/onos-service |
+
+## Model Extensions
+E-CORD does not extend CORD's core models.
+
+## GUI Extensions
+E-CORD includes two GUI extension:
+
+* [vnaas](https://github.com/opencord/vnaas/tree/master/xos/gui)
+* [veestat](https://github.com/opencord/vEE/tree/master/xos/veestat)
+
diff --git a/docs/installation_guide.md b/docs/installation_guide.md
index 7bebfaf..b664799 100644
--- a/docs/installation_guide.md
+++ b/docs/installation_guide.md
@@ -1,25 +1,30 @@
-# Installation guide
+# Installation Guide
-The paragraph describes how to install and configure the E-CORD global node and the local sites on a phsyical POD.
+Installing E-CORD is based on the standard CORD
+[installation process](https://guide.opencord.org/install_physical.html). This
+section describes the additional steps required.
-## Hardware requirements (BOM)
+## Hardware Requirements (BOM)
+
Following is a list of hardware needed to create a typical E-CORD deployment. References will be often made to the generic CORD BOM.
-**NOTE**: The hardware suggested is a reference implementation. Hardware listed have been usually used by ONF and its community for lab trials and deployments to validate the platform and demonstrate it's capabilities. You’re very welcome to replace any of the components and bring in yours into the ecosystem. As a community, we would be happy to acknowledge your contribution and put new tested devices in the BOM as well.
+> The hardware suggested is a reference implementation. Hardware listed have been usually used by ONF and its community for lab trials and deployments to validate the platform and demonstrate it's capabilities. You’re very welcome to replace any of the components and bring in yours into the ecosystem. As a community, we would be happy to acknowledge your contribution and put new tested devices in the BOM as well.
-Following the suggested hardware list is reported.
+The following suggests specific hardware.
-### Global node
+### Global Node
+
* 1x development machine - same model used for a [generic CORD POD](https://guide.opencord.org/install_physical.html#bill-of-materials-bom--hardware-requirements)
* 1x compute node (server) - same model used for a [generic CORD POD](https://guide.opencord.org/install_physical.html#bill-of-materials-bom--hardware-requirements)
-### Local site (POD)
-The hardware listed is needed for each POD.
+### Local Site (POD)
+
+The following hardware is required for each POD.
* Everything listed in the BOM of a generic CORD POD
-**WARNING** Currently E-CORD does not support more than 1 fabric switch per
-POD. While soon will be possible to use more than one fabric switch, it is useless now to buy more than a fabric switch per local site.
+> **WARNING**: Currently E-CORD does not support more than 1 fabric switch per
+> POD. While soon will be possible to use more than one fabric switch, it is useless now to buy more than a fabric switch per local site.
* 1x Centec v350, used as “Ethernet Edge switch”
* 1x CPE, composed by
@@ -28,10 +33,14 @@
* 1x fiber cable (or DAC) to connect the CPE to the Ethernet Edge switch
* 1x 40G to 4x10G QSFP+ module to connect the Ethernet Edge switch to the access leaf fabric switch (EdgeCore QSFP to 4x SFP+ DAC, model ET6402-10DAC-3M, part M0OEC6402T06Z)
-**NOTE**: The role of the CPE is to get users’ traffic, tag it with a VLAN id, and forward it to the Ethernet Edge switch. Additionally, the CPE sends and receives OAM probes to let CORD monitor the status of the network. For lab trials, a combination of two components has been used to emulate the CPE functionalities: a media converter, used to collect users’ traffic from an Ethernet CAT5/6 interface (where a traditional host, like a laptop, is connected) and send it out from its other SFP interface; a programmable SFP (plugged into the SFP port of the media converter), that a) tags the traffic with a specific VLAN id and forwards it to the Ethernet Edge switch; b) sends and receives OEM probes to let CORD monitor the network. The programmable SFP is currently configured through NETCONF, using the ONOS Flow Rule abstraction translated into NETCONF XML for the drivers, and the ONOS-based CarrierEthernet application to generate the Flow Rules based on requests.
+> **NOTE**: The role of the CPE is to receive end-user traffic, tag it with a VLAN id, and forward it to the Ethernet Edge switch. Additionally, the CPE sends and receives OAM probes to let CORD monitor the status of the network. For lab trials, a combination of two components has been used to emulate the CPE functionalities: a media converter, used to collect users’ traffic from an Ethernet CAT5/6 interface (where a traditional host, like a laptop, is connected) and send it out from its other SFP interface; a programmable SFP (plugged into the SFP port of the media converter), that a) tags the traffic with a specific VLAN id and forwards it to the Ethernet Edge switch; b) sends and receives OEM probes to let CORD monitor the network. The programmable SFP is currently configured through NETCONF, using the ONOS Flow Rule abstraction translated into NETCONF XML for the drivers, and the ONOS-based CarrierEthernet application to generate the Flow Rules based on requests.
-## Local site connectivity diagram
-The main CORD physical POD [installation guide](https://guide.opencord.org/install_physical.html#connectivity-requirements) already provides a basic POD connectivity diagram. These connections are anyway needed to bring up an E-CORD local site. Please, carefully review them before going through this section.
+## Local Site Connectivity
+
+The main CORD physical POD
+[installation guide](https://guide.opencord.org/install_physical.html#connectivity-requirements)
+already provides a basic POD connectivity diagram. These connections
+are also needed to bring up an E-CORD local site. Carefully review them before going through this section.
<img src="static/images/connectivity-diagram.png" alt="E-CORD connectivity diagram" style="width: 800px;"/>
@@ -61,33 +70,33 @@
A letter, plus "N" represents a generic port on a specific device.
-### References and informations needed: letters and numbers in the diagram
-Some informations are needed to
-* Properly configure E-CORD, following in the guide.
-* Have a reference when debugging an installation
+## Installing the Global Node
-## Installing the global node
-To install the global orchestrator on a physical node, you should follow the steps described in the main [physical POD installation](https://guide.opencord.org/install_physical.html).
+To install the global node, you should follow the steps described in
+the main
+[physical POD installation](https://guide.opencord.org/install_physical.html). At
+a high level, bootstrap the development machine and download the code.
-At a high level, bootstrap the development machine and download the code.
+### Global Node Configuration File
-### Global node configuration file
When it’s time to write your POD configuration, use the [physical-example.yml](https://github.com/opencord/cord/blob/master/podconfig/physical-example.yml) file as a template. Either modify it or make a copy of it in the same directory.
Fill in the configuration with your own head node data.
-As cord_scenario, use *single*. This won’t install OpenStack and other software, which are not needed on the global node.
+As `cord_scenario`, use `single`. This won’t install OpenStack and other software, which are not needed on the global node.
-As cord_profile, use *ecord-global*.
+As `cord_profile`, use `ecord-global`.
### POD Build
-Continue the installation as described in the guide by running the make build target:
+
+Continue the installation as described in the standard installation guide by running the make build target:
```
make build
```
-### DNS Services restart
-As soon as the procedure is finished you need to restart two services on the pod.
+### DNS Services Restart
+
+As soon as the procedure is finished you need to restart two services on the POD.
```
sudo service nsd restart
@@ -96,51 +105,67 @@
Now your global node is ready to be connected to the local sites.
-## Installing an E-CORD local site
-To install the local node you should follow the steps described in the main [physical POD installation](https://guide.opencord.org/install_physical.html). Bootstrap the development machine and download the code.
-When it’s time to write your pod configuration, use the [physical-example.yml](https://github.com/opencord/cord/blob/master/podconfig/physical-example.yml) file as a template. Either modify it or make a copy of it in the same directory.
+## Installing an E-CORD Local Site
+
+To install each local site you should follow the steps described in the
+main
+[physical POD installation](https://guide.opencord.org/install_physical.html). Bootstrap
+the development machine and download the code.
+
+When it’s time to write your POD configuration, use the [physical-example.yml](https://github.com/opencord/cord/blob/master/podconfig/physical-example.yml) file as a template. Either modify it or make a copy of it in the same directory.
Fill in the configuration with your own head node data.
-As cord_scenario use *cord*.
+As `cord_scenario` use `cord`.
-As cord_profile use *ecord*.
+As `cord_profile` use `ecord`.
-## Configure the Global node
-It’s essential to configure the global node properly, in order to instruct it about the existing local sites, have them connected and coordinated.
-Configuring the global node consists of two parts, an XOS/Tosca configuration and an ONOS/JSON.
+## Configure the Global Node
+
+It is essential to configure the global node properly, in order to
+instruct it about the existing local sites, have them connected and
+coordinated. Configuring the global node consists of two parts, an
+XOS/Tosca configuration and an ONOS/JSON.
### Configuring XOS (Tosca Configuration)
-The first part consists of instructing the XOS running on the global node about the other XOS instances, orchestrating the local sites.
-
-To configure your XOS instance, do the following:
-* Create your TOSCA file, using as template the file on your development/management machine, under *CORD_ROOT/orchestration/profiles/ecord/examples/vnaasglobal-service-reference.yaml* (available also online, [here](https://github.com/opencord/ecord/blob/master/examples/vnaasglobal-service-reference.yaml))
-* Save it on the global node.
-* SSH into your global node
-* On the global node, run the following command
+The first part consists of instructing XOS running on the global node
+about the set of local sites. To configure your XOS instance, do the following:
+
+* Create your TOSCA file, using as template the file on your
+ development/management machine, under
+ *CORD_ROOT/orchestration/profiles/ecord/examples/vnaasglobal-service-reference.yaml*
+ (available also online,
+ [here](https://github.com/opencord/ecord/blob/master/examples/vnaasglobal-service-reference.yaml)).
+
+ * Save it on the global node.
+
+ * SSH into your global node.
+
+ * On the global node, run the following command:
```
python /opt/cord/build/platform-install/scripts/run_tosca.py 9000 xosadmin@opencord.org YOUR_XOS_PASSWORD PATH_TO_YOUR_TOSCA FILE
```
-**NOTE**: If the XOS password has been auto-generated, you can find it on the global node, in
+>**NOTE**: If the XOS password has been auto-generated, you can find it on the global node, in
```
/opt/credentials/xosadmin@opencord.org
```
-### Configuring ONOS (JSON configuration)
+### Configuring ONOS (JSON Configuration)
+
To configure ONOS on the global node:
-* SSH into the global node
-* Login to ONOS_CORD: *ssh -p 8102 onos@onos-cord*
-* In the ONOS CLI (*onos>*) verify that apps are loaded by executing: *apps -a -s*
+* SSH into the global node.
+* Login to ONOS_CORD: *ssh -p 8102 onos@onos-cord*.
+* In the ONOS CLI (*onos>*) verify that apps are loaded by executing: `apps -a -s`
The following applications should be enabled:
```
org.onosproject.drivers
org.opencord.ce-api
org.opencord.ce.global
```
- If one or more apps mentioned above are not present in the list, they can be activated with *app activate APP-NAME*
+ If one or more apps mentioned above are not present in the list, they can be activated with `app activate APP-NAME`.
* Logout from ONOS (CTRL+D or exit)
-* Anywhere, either on the global node itself, or on any machine able to reach the global node, write your ONOS configuration file. The following is an example configuration for a global node that communicates with two local sites, with domain names site1 and site2.
+* Anywhere, either on the global node itself or on any machine able to reach the global node, write your ONOS configuration file. The following is an example configuration for a global node that communicates with two local sites, with domain names site1 and site2.
```
{
@@ -200,33 +225,36 @@
}
```
- **NOTE** Under the key “topics” you can specify as many topics (string of your choice) as you prefer for sake of load balancing the communication with the underlying (local-site) controllers among the instance of the global ONOS cluster. For each domain you also have to specify one of these topics.
+> **NOTE** Under the key “topics” you can specify as many topics (string of your choice) as you prefer for sake of load balancing the communication with the underlying (local-site) controllers among the instance of the global ONOS cluster. For each domain you also have to specify one of these topics.
- **NOTE**: If the XOS password has been auto-generated, you can find it on the global node, in /opt/credentials/xosadmin@opencord.org
+> **NOTE**: If the XOS password has been auto-generated, you can find it on the global node, in /opt/credentials/xosadmin@opencord.org
* Use CURL to push your file:
```
curl -X POST -H "content-type:application/json" http://YOUR-GLOBAL-NODE-IP:8182/onos/v1/network/configuration -d @YOUR-JSON-FILE.json --user onos:rocks
```
-## Configure the local sites
+## Configure the Local Sites
+
Local sites configuration consists of four parts:
* Ethernet Edge (Centec V350) configuration
-* **Optional** Fabric Breakout configuration
+* Fabric Breakout configuration (optional)
* ONOS_Fabric configuration
* The ONOS_CORD configuration
### Configure the Ethernet Edge device - B - (Centec v350)
+
The steps below assume that
* The Centec device to an A(Access)-leaf fabric switch
* ONOS_CORD is running
Follow the steps below to assign an IP address to the Ethernet Edge device and connect it to ONOS_CORD.
-#### Set a management IP address on the switch OOB interface
+#### Set a Management IP Address on the Switch OOB Interface
+
The switch management interface should be set with a static IP address (DHCP not supported yet), in the same subnet of the POD internal/management network (by default 10.6.0.0/24).
-**NOTE**: Please, use high values for the IP last octet, since lower values are usually allocated first by the MAAS DHCP server running on the head node.
+> **NOTE**: Please, use high values for the IP last octet, since lower values are usually allocated first by the MAAS DHCP server running on the head node.
To configure the static IP address, do the following:
* Log into the CLI of the Centec switch (through SSH or console cable)
@@ -235,21 +263,26 @@
* *end*
* *show management ip address*
-### **Optional** Configure the breakout cable on the fabric switch
-If you use a fabric switch with 40G interfaces and a 4 x 10G breakout cable to go to the Centec Etherned Edge you need to properly configure the interface on which the breakout cable is connected.
-By default, all 32 ports are running in 1 x 40G mode. The */etc/accton/ofdpa.conf* needs to be modified if we want to break out 1 x 40G into 4 x 10G.
+### **Optional** Configure the Breakout Cable on the Fabric Switch
+
+If you use a fabric switch with 40G interfaces and a 4 x 10G breakout
+cable to connect to the Centec Etherned Edge, you need to properly configure
+the interface on which the breakout cable is connected.
+
+By default, all 32 ports are running in 1 x 40G mode. The `/etc/accton/ofdpa.conf` needs to be modified to break out 1 x 40G into 4 x 10G.
Do the following:
* ssh into the fabric switch (username and password are usually root/onl)
-* *vi /etc/accton/ofdpa.conf*
-* uncomment this line *port_mode_1=4x10g # front port 1* for the prot you have the breakout cable connected to
+* `vi /etc/accton/ofdpa.conf`
+* uncomment this line `port_mode_1=4x10g # front port 1` for the port you have the breakout cable connected to
* save the file and exit from it.
-* *cd ~*
-* *./killit*
-* *./connect -bg*
+* `cd ~`
+* `./killit`
+* `./connect -bg`
For any more reference you can go to this particular step [Fabric configuration guide](https://wiki.opencord.org/display/CORD/Hardware+Switch+Installation+Guide#HardwareSwitchInstallationGuide-C3)
-### Set ONOS-CORD as the Openflow controller
+### Set ONOS-CORD as the Openflow Controller
+
To set ONOS-CORD as the default switch OpenFlow controller and verify the configuration:
* Log into the CLI of the Centec switch (through SSH or console cable)
* *configure terminal*
@@ -259,13 +292,14 @@
The local site configurations explained below need to happen on the head nodes of all local sites.
-### ONOS_fabric configuration
+### ONOS_Fabric Configuration
+
ONOS_Fabric manages the underlay network (the connectivity between the fabric switches).
To configure ONOS_Fabric do the following:
* SSH on the local site head node
-* Log into ONOS_Fabric: *ssh -p 8101 onos@onos-fabric*
-* In the ONOS CLI (*onos>*) verify that apps are loaded: *apps -a -s*
+* Log into ONOS_Fabric: `ssh -p 8101 onos@onos-fabric`
+* In the ONOS CLI (*onos>*) verify that apps are loaded: `apps -a -s`
The list of applications enabled should include:
```
org.onosproject.segmentrouting
@@ -274,15 +308,15 @@
org.opencord.ce.local.channel.http
org.opencord.ce.local.fabric
```
- If one or more apps mentioned above are not present in the list, they can be activated with *app activate APP-NAME*
+ If one or more apps mentioned above are not present in the list, they can be activated with `app activate APP-NAME`
* Check that the site domain id is correctly set in ONOS, running
```
cfg get org.opencord.ce.local.bigswitch.BigSwitchManager
```
- The value should be *YOUR-HEAD-NODE-IP-fabric-onos*
+ The value should be `YOUR-HEAD-NODE-IP-fabric-onos`
* Check that the fabric switch is connected to onos typing devices. If no devices are there, make sure your fabric switch is connected to ONOS and go through the [Fabric configuration guide](https://guide.opencord.org/appendix_basic_config.html#connect-the-fabric-switches-to-onos).
* Logout from ONOS (CTRL+D or exit)
-* Anywhere, either on the head node itself, or on any machine able to reach the head node, write your ONOS configuration file.
+* Anywhere, either on the head node itself or on any machine able to reach the head node, write your ONOS configuration file.
Following, is an example configuration for a local site.
```
@@ -330,28 +364,38 @@
curl -X POST -H "content-type:application/json" http://YOUR-LOCAL-HEAD-NODE-IP:8181/onos/v1/network/configuration -d @YOUR-JSON-FILE.json --user onos:rocks
```
-#### The MEF ports
-Under the key “mefPorts” there is the list of physical ports that have to be exposed to the global node. These ports represent MEF ports and can belong to different physical devices, but they will be part of a single abstract “bigswitch” in the topology of the global ONOS (see [E-CORD topology abstraction](https://guide.opencord.org/profiles/ecord/overview.html#e-cord-topology-abstraction)). These ports represent also the boundary between physical topologies controlled by different ONOS controllers.
+#### MEF Ports
+
+Under the key `mefPorts` there is the list of physical ports that have to be exposed to the global node. These ports represent MEF ports and can belong to different physical devices, but they will be part of a single abstract “bigswitch” in the topology of the global ONOS (see [E-CORD topology abstraction](https://guide.opencord.org/profiles/ecord/overview.html#e-cord-topology-abstraction)). These ports represent also the boundary between physical topologies controlled by different ONOS controllers.
In the Json above:
* *of:C-DPID/C1* is the DPID and the port of the fabric device where the Ethernet Edge Device is connected to.
* *of:C-DPID/C4* is the DPID and the port of the fabric device where the transport network is connected to (in the example fabric switches are connected together).
-This is hinted through the interlinkId.
+This is hinted through the `interlinkId` value.
-#### The topic attribute
-The *topic* attribute under the *org.opencord.ce.local.channel.http* is a string of your choice. It is used to run an election in an ONOS cluster to choose the ONOS instance that interacts with the global node.
+#### Topic Attribute
-### ONOS_CORD configuration
-ONOS_CORD manages the overlay network. It controls both the users' CPEs and the Ethernet Edge devices.
-The programmable microsemi SFP -part of your emulated CPE- is configured and managed through Netconf (more information about NETCONF and ONOS can be found [here](https://wiki.onosproject.org/display/ONOS/NETCONF)).
-The Ethernet Edge device is managed through OpenFlow.
-Both the devices, at the end of the configuration procedure should show up in ONOS_CORD, which can be confirmed by typing *devices* in the ONOS CLI (*onos>*).
+The `topic` attribute under the `org.opencord.ce.local.channel.http` is a string of your choice. It is used to run an election in an ONOS cluster to choose the ONOS instance that interacts with the global node.
+
+### ONOS_CORD Configuration
+
+ONOS_CORD manages the overlay network. It controls both the users'
+CPEs and the Ethernet Edge devices.
+
+The programmable microsemi SFP -part of your emulated CPE- is
+configured and managed through Netconf (more information about NETCONF
+and ONOS can be found
+[here](https://wiki.onosproject.org/display/ONOS/NETCONF)).
+
+The Ethernet Edge device is managed through OpenFlow.
+Both the devices, at the end of the configuration procedure should
+show up in ONOS_CORD, which can be confirmed by typing `devices` in the ONOS CLI (*onos>*).
To configure ONOS_CORD do the following:
* SSH into the head node
-* Login to onos-cord: *ssh -p 8102 onos@onos-cord*
-* At the ONOS CLI verify that apps are loaded: *apps -a -s*
+* Login to onos-cord: `ssh -p 8102 onos@onos-cord`
+* At the ONOS CLI verify that apps are loaded: `apps -a -s`
The following applications should be enabled:
```
org.onosproject.drivers.microsemi
@@ -425,20 +469,20 @@
curl -X POST -H "content-type:application/json" http://YOUR-LOCAL-SITE-HEAD-IP:8182/onos/v1/network/configuration -d @YOUR-JSON-FILE.json --user onos:rocks
```
-**Warning** The JSON above tries to configure devices and links at the same time. It may happen that ONOS denies your request of link creation, since it does not find devices present (because their creation is still in progress). If this happens, just wait few seconds and try to push again the same configuration, using the *curl* command above.
+> **Warning** The JSON above tries to configure devices and links at the same time. It may happen that ONOS denies your request of link creation, since it does not find devices present (because their creation is still in progress). If this happens, just wait few seconds and try to push again the same configuration, using the *curl* command above.
# Done!
After the global node and the local sites are properly configured, the global node should maintain an abstract view of the topology and you should see UNIs distributed on the map of the XoS GUI. You can start requests to setup Ethernet Virtual Circuit (EVC) from XoS.
-# Demo: create an E-Line through the UI
+# Demo: Create an E-Line Using the GUI
* SSH into global node
* From */opt/credentials/xosadmin@opencord.org* copy the XOS password
* From a computer, able to reach the global node, open a browser and go to *http://YOUR_GLOBAL_NODE_IP/xos*
* Use the following username/password to access:
- * Username: *xosadmin@opencord.org*
+ * Username: `xosadmin@opencord.org`
* Password: YOUR_PASSWORD_COPIED_AT_THE_STEP_BEFORE
-* From the left menu of the XOS UI, choose *VNaaS GUI*
+* From the left menu of the XOS UI, choose `VNaaS GUI`
* You should see CORD symbols on the map (your UNIs / end-points)
* Click on one of them
* Choose “Create connection”
@@ -452,8 +496,12 @@
A line should appear between the two icons, meaning that a request to connect the two end-points has been saved. The line should become green in few seconds. Green lines are good signs of a working environment.
-## End-points communication
-You should now be able to let communicate together the two end-points connected to the CPEs. Each of the two end-points need to be configured to send-out packets tagged with the same VLAN Id(s).
+## End-Point Communication
+
+You should now be able to let communicate together the two end-points
+connected to the CPEs. Each of the two end-points need to be
+configured to send-out packets tagged with the same VLAN Id(s).
+
Assuming you just configured VLAN id 100 in the UI, and that the two end-points will communicate together using the 192.168.1.0/24 subnet, on each head do the following:
* *apt-get install vlan*
* *sudo modprobe 8021q*
@@ -469,5 +517,5 @@
* Save
* Bring up the interface with *sudo ifup YOUR_INTERFACE_CONNECTED_TO_THE_CPE.100*
-## Success, Ping!
+## Success: Ping!
If everything works fine, the two hosts should be able to ping one each other.
diff --git a/docs/overview.md b/docs/overview.md
index 5c59139..5bbbda1 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,100 +1,110 @@
# What is E-CORD?
-Enterprise CORD (E-CORD) is a CORD use-case that offers enterprise connectivity services over metro and wide area networks, using open source software and commodity hardware.
+Enterprise CORD (E-CORD) is a CORD use case that offers enterprise connectivity services over metro and wide area networks, using open source software and commodity hardware.
<img src="static/images/overview.png" alt="E-CORD overview" style="width: 800px;"/>
-E-CORD builds on the CORD infrastructure to support enterprise customers, and allows Service Providers to offer enterprise connectivity services (L2 and L3VPN).
-It can go far beyond these simple connectivity services, as it includes Virtual Network Functions (VNFs) and service composition capabilities to support disruptive cloud-based enterprise services.
-In turn, enterprise customers can use E-CORD to rapidly create on-demand networks between any number of endpoints or company branches. These networks are dynamically configurable, implying connection attributes and SLAs can be specified and provisioned on the fly. Furthermore, enterprise customers may choose to run network functions such as firewalls, WAN accelerators, traffic analytic tools, virtual routers, etc. as on-demand services that are provisioned and maintained inside the service provider network.
+E-CORD builds on the CORD platform to support enterprise customers, and allows Service Providers to offer enterprise connectivity services (L2 and L3VPN).
+It can also go beyond these simple connectivity services to include Virtual Network Functions (VNFs) and service composition capabilities to support disruptive cloud-based enterprise services.
+
+Enterprise customers can use E-CORD to rapidly create on-demand networks between any number of endpoints or company branches. These networks are dynamically configurable, implying connection attributes and SLAs can be specified and provisioned on the fly. Furthermore, enterprise customers may choose to run network functions such as firewalls, WAN accelerators, traffic analytic tools, virtual routers, etc. as on-demand services that are provisioned and maintained inside the service provider network.
# Glossary
The section provides a list of the basic terms used in E-CORD
-* **CO/Local POD**: Each local CORD POD (also identified in the guide as an E-CORD site) is a standard CORD POD equipped with specific access equipment, such as the “Enterprise Edge”. It is usually located in the Service Provider’s Central Offices and is mainly used to: 1) connect the enterprise user to the Service Provider network; b) run value added user services at the edge of the network, closed to the user, such as firewalls, traffic analytic tools or WAN accelerators. Upstream, the POD usually connects to the Service Provider metro/transport network or to the public internet.
-* **Global Node**: The global node is a single machine running either in the cloud, or in any other part of the Service Provider network, used as general orchestrator that coordinates between all the local PODs of the E-CORD deployment. It is composed by an instance of XOS and one of ONOS.
+ * **Local POD**: Each local CORD POD (also identified in the guide as an E-CORD site) is a standard CORD POD equipped with specific access equipment. It is usually located in the Service Provider’s Central Offices and is mainly used to: 1) connect the enterprise user to the Service Provider network; and 2) run value added user services (e.g., firewalls, traffic analytic tools, WAN accelerators) at the edge of the network, close to the enterprise sites. Upstream, the POD usually connects to the Service Provider metro/transport network or to the public internet.
+
+* **Global Node**: The global node is a single machine running either in the cloud, or in any other part of the Service Provider network, used to coordinate connectivity and services among all the local PODs of the E-CORD deployment. It consists of an instance of XOS (global orchestrator) and ONOS (controlling the transport network interconnecting edge sites).
-# System overview
+# System Overview
-A typical E-CORD deployment is made of one orchestrator “global node” and multiple (min 2) CORD sites (PODs), connected to the same transport network.
+A typical E-CORD deployment is made of one global node and multiple (minimum two) CORD sites (PODs), connected to the same transport network.
<img src="static/images/ecord-dataplane.png" alt="E-CORD dataplane" style="width: 800px;"/>
-Each site is a “typical” CORD POD comprised of one or more compute nodes, and one or more fabric switches (see here for details).
-The transport network provides connectivity between the CORD sites. It can be anything from a converged packet-optical network, to a single packet switch. The transport network can be composed of white-box switches, legacy equipment, or a mix of both. The minimum requirement in order to deploy E-CORD is to provide Layer 2 connectivity between the PODs, specifically between the leaf fabric switches, facing the upstream/metro network of the COs.
+Each site is a standard CORD POD comprised of one or more compute nodes, and one or more fabric switches. The transport network provides connectivity between the CORD sites. It can be anything from a converged packet-optical network, to a single packet switch for demo purposes. The transport network can be composed of white-box switches, legacy equipment, or a mix of both. The minimum requirement in order to deploy E-CORD is to provide Layer 2 connectivity between the PODs, specifically between the leaf fabric switches that face the upstream/metro network of the COs.
-**INFO** Usually, for lab trials, the leaf switches of the two sites (PODs) are connected directly through a cable, or through a legacy L2 switch.
+> Usually, for lab trials, the leaf switches of the two sites (PODs) are connected directly through a cable, or through a legacy L2 switch.
-## The E-CORD global node
-The global node is responsible for orchestrating users’ requests and to manage the connectivity and the services provisioning.
-
-It runs only an instance of the orchestrator, XOS, and an instance of ONOS, in specific the ONOS_CORD one.
-
-The ONOS instance (ONOS_CORD) manages the end-to-end traffic forwarding between the sites.
+## Global Node
+
+The global node is responsible for orchestrating users’ requests and to manage the connectivity and the services provisioning. It runs only an instance of XOS and an instance of ONOS (specifically ONOS_CORD). The ONOS instance (ONOS_CORD) manages the end-to-end traffic forwarded between the sites.
The global ONOS is composed of three modules:
-* **Carrier Ethernet Orchestrator** application, exposing a NB REST interface to receive requests to create Ethernet Virtual Circuits (EVCs).
-* **Virtual Provider**, that manages the abstract view of the local E-CORD sites topologies.
-* **Global HTTP channel** for the communication with the underlying local sites.
-## The E-CORD local sites
-Local sites are responsible for collecting users’ traffic and forward it either to other local sites or to Internet.
-Each local site comes with two ONOS controllers that are part of the reference architecture of CORD: ONOS_CORD and ONOS_Fabric.
+* **Carrier Ethernet Orchestrator**: Exposes a Northbound REST interface to receive requests to create Ethernet Virtual Circuits (EVCs).
+
+* **Virtual Provider**: Manages the abstract view of the local E-CORD sites topologies.
+
+* **Global HTTP Channel**: Supports communication with the local sites.
+
+## Local Sites
+
+Local sites are responsible for collecting users’ traffic and forwarding it either to other local sites or to the Internet. Each local site comes with two ONOS controllers that are part of the reference architecture of CORD: ONOS_CORD and ONOS_Fabric. The Carrier Ethernet application of E-CORD uses both controllers to provision the physical network:
-The Carrier Ethernet application of E-CORD uses both controllers to provision the physical network:
-* **ONOS_CORD** runs the application that controls the edge access: the CPE devices and the Ethernet Edge (EE) devices.
-* **ONOS_Fabric** runs the application configuring the cross connections within the fabric of CORD (Trellis), to bridge the CPEs to the transport network and to the remote sites.
+ * **ONOS_CORD**: Runs the application that controls the edge access, including the CPE devices and the Ethernet Edge (EE) devices.
-The added components to ONOS_CORD ONOS are these applications:
+* **ONOS_Fabric**: Runs the application configuring the cross connections within the fabric of CORD, to bridge the CPEs to the transport network and to the remote sites.
+
+The following components are added to ONOS_CORD:
* CE-API
* Bigswitch service
* HTTP channel
* CE-VEE
-The added components to ONOS_Fabric ONOS are these applications:
+The following components are added to ONOS_Fabric:
* CE-API
* Bigswitch service
* HTTP channel
* CE-fabric
-The CE-API, the bigswitch service and the HTTP channel are common to both ONOS_CORD and ONOS_Fabric. They are used to put in communication the ONOS running on the global node and the ones running on the local sites.
-The local sites abstract their network topology and expose it to the global node, they receive requests from the global ONOS, and provision the network for the EVCs setup.
-
-## XOS service chain
-XOS is the default CORD orchestrator. More info about it can be found here.
+The CE-API, the bigswitch service, and the HTTP channel are common to both ONOS_CORD and ONOS_Fabric. They are used to put in communication the ONOS running on the global node and the ones running on the local sites.
-The Global pod only implements a single service called **vNaaS**, **virtual Network as a Service** that is responsible for orchestrating the end to end connectivity between the PODs.
-
-E-CORD local sites implement multiple services -wired together- that control the underlying hardware and software, and are thus able to connect the Enterprise Subscriber from the edge of the Central Office to the upstream network.
-
-A representation of the default E-CORD local site service chain is shown in the picture below.
+The local sites abstract their network topology and expose it to the global node. They receive requests from the global ONOS, and provision the network for the EVCs setup.
-<img src="static/images/xos-service-chain.png" alt="XOS Service Chain" style="width: 600px;"/>
+## Service Graph
-The local chain comprises of 5 different services with different responsibilities each.
+The global node implements a single service called **vNaaS** (**virtual Network as a Service**) that is responsible for controlling end-to-end connectivity between the PODs.
-* **vCPE (virtual Customer Premise Equipment)** inserts an 802.1ad (QinQ) header to the upstream packets of an Enterprise Subscriber and removes it for downstream flows. Packets are tagged with a vlanId (the Service Provider tag, s-tag) and then forwarded to the Ethernet Edge. The s-tag is associated with one or more c-tag (customer tags, the vlanId of the 802.1q protocol) to isolate the traffic within the Service Provider network. The vCPE function is very similar to that of vOLT in R-CORD.
-* **vEE (virtual Ethernet Edge)** aggregates traffic from multiple customers with CPEs and applies policing and forwarding to the fabric. The vEE is also responsible for making routing decisions on the traffic. The vEE filters the traffic meant for the enterprise network and sends it through pseudo-wire in the fabric directly to the transport network and the other enterprise branch. If the vEE recognizes that the traffic is instead meant for the public Internet, it will send it to the vEG and then to the vRouter.
-* **vEG (virtual Enterprise Gateway)** runs the subscriber desired VNFs, such as bandwidth metering, firewall, diagnostics etc, and possibly forwards the traffic to the vRouter.
-* **vRouter (virtual Router)** is responsible for sending traffic out of the CORD POD to the public Internet. It is the same service that is present in the R-CORD service chain. More information about it can be found [here](https://guide.opencord.org/vrouter.html#connecting-to-upstream-networks-using-vrouter)
-* **PWaaS enables a “pass-through”** in the leaf-spine fabric (Trellis), allowing traffic to directly go out to the metro network. This is done through a configuration of the segment routing application.
+Each local site implements multiple services that collectively control the underlying hardware and software, and are thus able to connect the Enterprise Subscriber from the edge of the Central Office to the upstream network.
+
+A representation of the default E-CORD local site service graph is shown below.
-## E-CORD Topology Abstraction
-The global node maintains an abstract view of the underlying topology for the sake of scalability and to separate domain-specific and domain-agnostic concerns. Note that in a single CORD PODs there are two independent ONOS controllers: ONOS_CORD and ONOS_Fabric. For each local site, the E-CORD application exposes two abstract devices to the global node: one is exposed by the ONOS_CORD and the other by the ONOS_Fabric. They represent an aggregation of the real network elements that compose the topology of a local site.
+<img src="static/images/xos-service-chain.png" alt="XOS Service Graph" style="width: 600px;"/>
+
+The local graph consists of five different services with different responsibilities.
+
+ * **vCPE (Virtual Customer Premise Equipment)**: Inserts an 802.1ad (QinQ) header to the upstream packets of an Enterprise Subscriber and removes it for downstream flows. Packets are tagged with a vlanId (the Service Provider tag, s-tag) and then forwarded to the Ethernet Edge. The s-tag is associated with one or more c-tag (customer tags, the vlanId of the 802.1q protocol) to isolate the traffic within the Service Provider network. The vCPE function is very similar to that of vOLT in R-CORD.
+
+ * **vEE (Virtual Ethernet Edge)**: Aggregates traffic from multiple customers with CPEs and applies policing and forwarding to the fabric. The vEE is also responsible for making routing decisions on the traffic. The vEE filters the traffic meant for the enterprise network and sends it through pseudo-wire in the fabric directly to the transport network and the other enterprise branch. If the vEE recognizes that the traffic is instead meant for the public Internet, it will send it to the vEG and then to the vRouter.
+
+ * **vEG (Virtual Enterprise Gateway)**: Runs selected VNFs, such as bandwidth metering, firewall, diagnostics etc, and possibly forwards the traffic to the vRouter.
+
+ * **vRouter (Virtual Router)**: Responsible for sending traffic out of the CORD POD to the public Internet. It is the same service that is present in the R-CORD service chain. More information about it can be found [here](https://guide.opencord.org/vrouter.html#connecting-to-upstream-networks-using-vrouter).
+
+* **PWaaS**: Enables a “pass-through”** in the leaf-spine fabric, allowing traffic to directly go out to the metro network. This is done through a configuration of the segment routing application.
+
+## Topology Abstraction
+
+The global node maintains an abstract view of the underlying topology for the sake of scalability and to separate domain-specific and domain-agnostic concerns. Note that in a single CORD POD there are two independent ONOS controllers: ONOS_CORD and ONOS_Fabric. For each local site, the E-CORD application exposes two abstract devices to the global node: one is exposed by the ONOS_CORD and the other by the ONOS_Fabric. They represent an aggregation of the real network elements that compose the topology of a local site.
The picture below shows how the two topologies get abstracted and exposed to the ONOS instance running on the global node.
-<img src="static/images/topology-abstraction-01.png" alt="XOS Service Chain" style="width: 600px;"/>
+<img src="static/images/topology-abstraction-01.png" alt="Topology Abstraction" style="width: 600px;"/>
-This way, the global ONOS has fewer devices and link data structures to deal with. Path computation will involve only these aggregated items, while the actual network provisioning will be achieved by the local site controllers.
+In this way, the global ONOS has fewer devices and link data structures to deal with. Path computation involves only these aggregated items, while the actual network provisioning is achieved by the local site controllers.
The relevant topology information for the global node include
-* **User-to-Network Interfaces (UNIs)** - see [MEF specs](https://www.mef.net/resources/technical-specifications)
-* **Network-to-Network Interfaces (NNIs)** see see [MEF specs](https://www.mef.net/resources/technical-specifications)
-* **Associated bandwidth capacities** for admission control
-
-The NNI ports are annotated with an interlinkId so that the global node can understand which ports are at the ends of which inter-domain links.
-An inter-domain link, from now on simply called interlink, is a link that connects to devices controlled by different ONOS controllers at local level (see the ONOS_FABRIC and ONOS_CORD json configuration sections in the installation guide for more examples).
-<img src="static/images/topology-abstraction-02.png" alt="XOS Service Chain" style="width: 600px;"/>
+* **User-to-Network Interfaces (UNIs)**: See [MEF specs](https://www.mef.net/resources/technical-specifications).
+
+* **Network-to-Network Interfaces (NNIs)**: See [MEF specs](https://www.mef.net/resources/technical-specifications).
+
+* **Associated bandwidth capacities**: For admission control.
+
+The NNI ports are annotated with an inter-link identifier (`interlinkId`) so that the global node can understand which ports are at the ends of which inter-domain links.
+
+The inter-domain link connects to devices controlled by different ONOS controllers at local level. See the ONOS_FABRIC and ONOS_CORD json configuration sections in the installation guide for more examples,
+
+<img src="static/images/topology-abstraction-02.png" alt="Topology Abstraction" style="width: 600px;"/>