Merge "Some edits to install guides to clarify different installation procedures and tools. Added structure to SEBA profile."
diff --git a/README.md b/README.md
index 248aff3..8f18a6e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Installation Guide
-This guide describes how to install CORD. It identifies a set of
+This guide describes how to install CORD on a physical POD. It identifies a set of
[prerequisites](prereqs/README.md), and then walks through
the steps involved in bringing up the [Platform](platform.md). Once
the Platform is installed, you are ready to bring up one of the
@@ -9,9 +9,17 @@
* [SEBA](./profiles/seba/install.md)
* [M-CORD](./profiles/mcord/install.md)
-If you are anxious to jump straight to a [Quick Start](quickstart.md)
-procedure that brings up an emulated version of CORD running
-on your laptop (sorry, no subscriber data plane), then that's an option.
+This installation procedure requires management-network connectivity to the Internet.
+If your installation does not have such connectivity, or you are behind a restrictive
+firewall, consider [Offline Install](./offline-install.md).
-Alternatively, if you want to get a broader lay-of-the-land, you
+If you do not have the [prerequisite hardware](./prereqs/hardware.md) needed for a POD,
+consider running a complete system entirely emulated in software using
+[SEBA-in-a-Box](./profiles/seba/siab-overview.md).
+
+If you are anxious to jump straight to a [Quick Start](quickstart.md)
+procedure that brings up a subset of the CORD platform running
+on your laptop (without a subscriber data plane), that too is an option.
+
+Finally, if you want to get a broader lay-of-the-land, you
might step back and start with an [Overview](overview.md).
diff --git a/SUMMARY.md b/SUMMARY.md
index 3bd98dd..de4174f 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -65,14 +65,31 @@
* [SEBA](profiles/seba/README.md)
* Install
* [Install SEBA Charts](profiles/seba/install.md)
- * [SEBA-in-a-Box](profiles/seba/siab.md)
- * [SEBA-in-a-Box with Fabric Switch](profiles/seba/siab-with-fabric-switch.md)
- * [Scale testing with BBSim](profiles/seba/bbsim.md)
- * [Celestica / Microsemi Setup](profiles/rcord/celestica-olt-setup.md)
- * [Emulated OLT/ONU](profiles/rcord/emulate.md)
* Workflows
- * [AT&T](profiles/seba/workflows/att.md)
- * [Configure](profiles/seba/configuration.md)
+ * [Install AT&T workflow](profiles/seba/workflows/att-install.md)
+ * [SEBA-in-a-Box Overview](profiles/seba/siab-overview.md)
+ * [SEBA-in-a-Box](profiles/seba/siab.md)
+ * [SEBA-in-a-Box with Fabric Switch](profiles/seba/siab-with-fabric-switch.md)
+ * [Scale testing with BBSim](profiles/seba/bbsim.md)
+ * [BETA: Celestica / Microsemi Setup](profiles/seba/celestica-olt-setup.md)
+ * Configure
+ * [POD specific configuration](profiles/seba/configuration.md)
+ * Workflow specific configuration
+ * [Configure AT&T workflow](profiles/seba/workflows/att-configure.md)
+ * Operate
+ * [Disable/Enable an ONU](profiles/seba/operate/onu-ops.md)
+ * [Edit a Whitelist entry](profiles/seba/operate/whitelist-ops.md)
+ * [Disable/Delete an OLT](profiles/seba/operate/olt-ops.md)
+ * [Fix configuration errors](profiles/seba/operate/config-ops.md)
+ * [Add a cross-connect in the AGG switch](profiles/seba/operate/agg-ops.md)
+ * [Try a new version of *](profiles/seba/operate/k8s-helm-ops.md)
+ * [Known Issues](profiles/seba/known-issues.md)
+ * Troubleshoot (FAQ)
+ * [I can't ping](profiles/seba/troubleshoot/no-ping.md)
+ * [No ONUs discovered](profiles/seba/troubleshoot/no-onus.md)
+ * [I can't authenticate](profiles/seba/troubleshoot/no-aaa.md)
+ * [DHCP is not working](profiles/seba/troubleshoot/no-dhcp.md)
+ * [No AttWorkflowDriver service instances](profiles/seba/troubleshoot/no-att-si.md)
* [M-CORD](profiles/mcord/README.md)
* Install
* [Install M-CORD Charts](profiles/mcord/install.md)
@@ -102,4 +119,3 @@
* [Logging and Monitoring](charts/logging-monitoring.md)
* [Persistent Storage](charts/storage.md)
* [BBSim](charts/bbsim.md)
-
diff --git a/profiles/seba/README.md b/profiles/seba/README.md
index a23023d..30220ff 100644
--- a/profiles/seba/README.md
+++ b/profiles/seba/README.md
@@ -1,8 +1,7 @@
# SEBA Profile
-SEBA (Software-Enabled Broadband Access) is a lightweight profile that
-supports white-box OLT devices.
+SEBA (SDN Enabled Broadband Access) is a profile meant for residential access networks
[Click here for a high-level overview.](https://www.opennetworking.org/seba/).
-The following pages describe how to install SEBA with some workload,
-and how to configure an installed SEBA POD.
+The following pages describe how to install SEBA with an operator defined workflow,
+and how to configure, operate and troubleshoot an installed SEBA POD.
diff --git a/profiles/seba/bbsim.md b/profiles/seba/bbsim.md
index 12f8e67..339d3b5 100644
--- a/profiles/seba/bbsim.md
+++ b/profiles/seba/bbsim.md
@@ -1,20 +1,25 @@
# Scale testing using BBSim
Broadband Simulator (BBSim) is a control-plane only simulator that is used to
-test the sistem at scale.
+test a SEBA POD at scale. On the one hand, unlike ponsim which emulates both the
+control and data plane, BBSim only does the former. On the other hand, BBsim can
+potentially simulate tens of OLTs and thousands of ONUs, making it an ideal tool
+for control plane scale testing. One additional benefit of BBSim is that it
+uses the OpenOLT adaptor in VOLTHA, unlike ponsim which uses its own specialized
+adaptor.
-You can run BBSim on top of any SEBA installation, for instructions on how to
-install it you can refer to the [bbsim](../../charts/bbsim.md) helm reference.
+You can run BBSim on top of any SEBA installation, physical or virtual (SiaB).
+For instructions on how to install it you can refer to the [bbsim](../../charts/bbsim.md) helm reference.
## System configurations that affects BBSim
-The most important detail that determine how BBSim will behave is the DHCP
-configuration.
+The most important detail that determines how BBSim will behave is the L2-DHCP-relay
+configuration of the SEBA installation.
There are two options:
-- sending packets out of the switch
-- sending packets back to the OLT
+- sending DHCP packets out of the AGG switch's uplink port
+- sending DHCP packets out of the OLT's NNI port
### DHCP Packets through the aggregation switch
@@ -30,4 +35,4 @@
that runs inside BBSim itself. To do that you need to send the DHCP Packets
back to the OLT.
-To do that you can use this TOSCA recipe: <https://github.com/opencord/helm-charts/blob/master/examples/bbsim-dhcp.yaml>
\ No newline at end of file
+To do that you can use this TOSCA recipe: <https://github.com/opencord/helm-charts/blob/master/examples/bbsim-dhcp.yaml>
diff --git a/profiles/seba/operate/agg-ops.md b/profiles/seba/operate/agg-ops.md
new file mode 100644
index 0000000..c0b324d
--- /dev/null
+++ b/profiles/seba/operate/agg-ops.md
@@ -0,0 +1 @@
+# AGG Switch Operations
diff --git a/profiles/seba/operate/config-ops.md b/profiles/seba/operate/config-ops.md
new file mode 100644
index 0000000..10140c8
--- /dev/null
+++ b/profiles/seba/operate/config-ops.md
@@ -0,0 +1 @@
+# Fixing Config Errors
diff --git a/profiles/seba/operate/k8s-helm-ops.md b/profiles/seba/operate/k8s-helm-ops.md
new file mode 100644
index 0000000..d122edd
--- /dev/null
+++ b/profiles/seba/operate/k8s-helm-ops.md
@@ -0,0 +1 @@
+# Container Operations
diff --git a/profiles/seba/operate/olt-ops.md b/profiles/seba/operate/olt-ops.md
new file mode 100644
index 0000000..a4317c1
--- /dev/null
+++ b/profiles/seba/operate/olt-ops.md
@@ -0,0 +1 @@
+# OLT Operations
diff --git a/profiles/seba/operate/onu-ops.md b/profiles/seba/operate/onu-ops.md
new file mode 100644
index 0000000..6186438
--- /dev/null
+++ b/profiles/seba/operate/onu-ops.md
@@ -0,0 +1 @@
+# ONU Operations
diff --git a/profiles/seba/operate/whitelist-ops.md b/profiles/seba/operate/whitelist-ops.md
new file mode 100644
index 0000000..c1335fe
--- /dev/null
+++ b/profiles/seba/operate/whitelist-ops.md
@@ -0,0 +1 @@
+# Whitelist Operations
diff --git a/profiles/seba/siab-overview.md b/profiles/seba/siab-overview.md
new file mode 100644
index 0000000..a45c2fe
--- /dev/null
+++ b/profiles/seba/siab-overview.md
@@ -0,0 +1,14 @@
+# SEBA-in-a-Box
+
+If you do not have the [prerequisite hardware](../../prereqs/hardware.md) to
+install SEBA we have you covered. You can get a complete CORD system together
+with the CORD platform, a profile such as SEBA, an exemplar operator workflow and
+an emulated data-plane using SEBA-in-a-Box.
+
+There are two ways to get started with SEBA-in-a-Box (SiaB). If you want to emulate
+the access network (OLTs and ONUs) as well as the Aggregation switch in software,
+use [SiaB](./siab.md).
+
+If you want to emulate **just** the access network (OLTs and ONUs) but connect it
+to a physical AGG switch (sometimes called a Fabric switch), use
+[SiaB-with-fabric-switch](./siab-with-fabric-switch.md)
diff --git a/profiles/seba/troubleshoot/no-aaa.md b/profiles/seba/troubleshoot/no-aaa.md
new file mode 100644
index 0000000..cbb591f
--- /dev/null
+++ b/profiles/seba/troubleshoot/no-aaa.md
@@ -0,0 +1 @@
+# I can't authenticate my RGs
diff --git a/profiles/seba/troubleshoot/no-att-si.md b/profiles/seba/troubleshoot/no-att-si.md
new file mode 100644
index 0000000..7a73d5b
--- /dev/null
+++ b/profiles/seba/troubleshoot/no-att-si.md
@@ -0,0 +1 @@
+# I don't see any AttWorkflowInstances
diff --git a/profiles/seba/troubleshoot/no-dhcp.md b/profiles/seba/troubleshoot/no-dhcp.md
new file mode 100644
index 0000000..63c1675
--- /dev/null
+++ b/profiles/seba/troubleshoot/no-dhcp.md
@@ -0,0 +1 @@
+# RG is not getting IP from DHCP
diff --git a/profiles/seba/troubleshoot/no-onus.md b/profiles/seba/troubleshoot/no-onus.md
new file mode 100644
index 0000000..5412c69
--- /dev/null
+++ b/profiles/seba/troubleshoot/no-onus.md
@@ -0,0 +1 @@
+# ONUs are not getting discovered
diff --git a/profiles/seba/troubleshoot/no-ping.md b/profiles/seba/troubleshoot/no-ping.md
new file mode 100644
index 0000000..152bd5d
--- /dev/null
+++ b/profiles/seba/troubleshoot/no-ping.md
@@ -0,0 +1 @@
+# I can't ping
diff --git a/profiles/seba/workflows/att-configure.md b/profiles/seba/workflows/att-configure.md
new file mode 100644
index 0000000..056c2c9
--- /dev/null
+++ b/profiles/seba/workflows/att-configure.md
@@ -0,0 +1,111 @@
+# Configure AT&T Workflow
+
+We assume your POD is already configured as per[this instructions](../configuration.md)
+(you need to complete only the first section)
+
+## Whitelist population
+
+To configure the ONU whitelist, you can use this TOSCA:
+
+```yaml
+tosca_definitions_version: tosca_simple_yaml_1_0
+imports:
+ - custom_types/attworkflowdriverwhitelistentry.yaml
+ - custom_types/attworkflowdriverservice.yaml
+description: Create an entry in the whitelist
+topology_template:
+ node_templates:
+
+ service#att:
+ type: tosca.nodes.AttWorkflowDriverService
+ properties:
+ name: att-workflow-driver
+ must-exist: true
+
+ whitelist:
+ type: tosca.nodes.AttWorkflowDriverWhiteListEntry
+ properties:
+ serial_number: BRCM22222222
+ pon_port_id: 536870912
+ device_id: of:000000000a5a0072
+ requirements:
+ - owner:
+ node: service#att
+ relationship: tosca.relationships.BelongsToOne
+```
+
+For instructions on how to push TOSCA into a CORD POD, please
+refer to this [guide](../../../xos-tosca/README.md).
+
+## Pre-provision subscribers
+
+You can `pre-provision` subscribers using this TOSCA:
+
+```yaml
+tosca_definitions_version: tosca_simple_yaml_1_0
+imports:
+ - custom_types/rcordsubscriber.yaml
+
+description: Pre-provsion a subscriber
+
+topology_template:
+ node_templates:
+
+ # Pre-provision the subscriber the subscriber
+ my_house:
+ type: tosca.nodes.RCORDSubscriber
+ properties:
+ name: My House
+ status: pre-provisioned
+ c_tag: 111
+ onu_device: BRCM22222222
+ nas_port_id : "PON 1/1/03/1:1.1.1"
+ circuit_id: foo
+```
+
+For instructions on how to push TOSCA into a CORD POD, please
+refer to this [guide](../../../xos-tosca/README.md).
+
+## OLT Activation
+
+Once the system knows about whitelisted ONUs and subscribers,
+you can activate the OLT:
+
+```yaml
+tosca_definitions_version: tosca_simple_yaml_1_0
+imports:
+ - custom_types/oltdevice.yaml
+ - custom_types/voltservice.yaml
+description: Create a simulated OLT Device in VOLTHA
+topology_template:
+ node_templates:
+
+ service#volt:
+ type: tosca.nodes.VOLTService
+ properties:
+ name: volt
+ must-exist: true
+
+ olt_device:
+ type: tosca.nodes.OLTDevice
+ properties:
+ name: ONF OLT
+ device_type: openolt
+ host: 10.90.0.114
+ port: 9191
+ switch_datapath_id: of:0000000000000001
+ switch_port: "1"
+ outer_tpid: "0x8100"
+ uplink: "128"
+ requirements:
+ - volt_service:
+ node: service#volt
+ relationship: tosca.relationships.BelongsToOne
+```
+
+For instructions on how to push TOSCA into a CORD POD, please
+refer to this [guide](../../../xos-tosca/README.md).
+
+## Device monitoring
+
+Please refer to the [monitoring](../../../charts/logging-monitoring.md) chart.
diff --git a/profiles/seba/workflows/att-install.md b/profiles/seba/workflows/att-install.md
new file mode 100644
index 0000000..c3a77ae
--- /dev/null
+++ b/profiles/seba/workflows/att-install.md
@@ -0,0 +1,39 @@
+# Install AT&T Workflow
+
+You can find a complete description of the SEBA workflow for At&t in [this document](https://docs.google.com/document/d/1nou2c8AsRzhaDJmA_eYvFgd0Y33KiCsioveU77AOVCI/edit#heading=h.x73smxj2xaib). This pages focus exclusively on the internals details of the workflow such as actions triggered by the environment and decisions taken by NEM.
+
+## Install the `att-workflow` chart
+
+```shell
+helm dep update xos-profiles/att-workflow
+helm install -n att-workflow xos-profiles/att-workflow
+```
+
+## Workflow description
+
+1. ONT discovered bottom-up
+2. If ONT serial number is not allowed or unknown (i.e it has NOT been provisioned by OSS), disable the ONT; generate an event to external OSS that an ONU has been discovered but not yet provisioned.
+3. When OSS provisions the ONT, re-enable it & program 802.1x flow - UNI port(s) will be UP
+4. Ensure that DHCP fails here (because subscriber/service-binding has not been provisioned by OSS yet)
+5. 802.1x EAPOL message happens from RG, and ONOS AAA app adds options and sends to radius server. Options are pulled from Sadis/NEM - no subscriber information is required here
+6. If RG authentication fails, allow it to keep trying (in the future consider redirection to captive / self-help portal). DHCP should not succeed since RG authentication has failed
+7. If RG authentication succeeds, ONOS AAA app notifies via an event on the kafka bus that authentication has succeeded
+8. NEM can listen for the event, and then check to see if subscriber/service-binding has happened on that port from OSS - if not, then nothing to be done
+9. Must ensure that DHCP fails here even though RG has been authenticated (because subscriber/service-binding has not been provisioned by OSS yet)
+10. When OSS provisions the subscriber/service-binding on the UNI port and gives the C and S vlan info, then DHCP trap will be programmed on the port, and DHCP process can start
+11. If RG is disconnected from UNI port, force authentication again (even if subscriber/service-binding has been provisioned by OSS). Upon reconnection to UNI port, RG must re-authenticate before DHCP/other-traffic can flow on the provisioned VLANs.
+12. DHCP L2 relay -> add option 82, learn public IP address, forward via dataplane to external DHCP server
+
+
+This schema summarizes the workflow, please note:
+
+- in `light blue` are environment events (wether they are triggered from hardware or from an operator)
+- in `yellow` are NEM configuration calls to ONOS or VOLTHA
+- in `green` are decisions
+- in `orange` event published on the kafka bus
+
+
+
+> NOTE: when we refer to `service chain` we are talking about the set of
+subscriber specific service instances that will trigger the `add_subscriber`
+call in ONOS-VOLTHA and provision the crossconnect in ONOS-FABRIC
diff --git a/profiles/seba/workflows/att.md b/profiles/seba/workflows/att.md
deleted file mode 100644
index 90a2556..0000000
--- a/profiles/seba/workflows/att.md
+++ /dev/null
@@ -1,161 +0,0 @@
-# AT&T Workflow
-
-You can find a complete description of the SEBA workflow for At&t in [this document](https://docs.google.com/document/d/1nou2c8AsRzhaDJmA_eYvFgd0Y33KiCsioveU77AOVCI/edit#heading=h.x73smxj2xaib). This pages focus exclusively on the internals details of the workflow such as actions triggered by the environment and decisions taken by NEM.
-
-## Helm charts
-
-To replicate this workflow you'll need to install:
-
-- [xos-core](../../../charts/xos-core.md)
-- [cord-kafka](../../../charts/kafka.md)
-- [voltha](../../../charts/voltha.md)
-- [onos](../../../charts/onos.md#generic-onos)
-- att-workflow
-
-### Install the `att-workflow` chart
-
-```shell
-helm dep update xos-profiles/att-workflow
-helm install -n att-workflow xos-profiles/att-workflow
-```
-
-## Workflow description
-
-1. ONT discovered bottom-up
-2. If ONT serial number is not allowed or unknown (i.e it has NOT been provisioned by OSS), disable the ONT; generate an event to external OSS that an ONU has been discovered but not yet provisioned.
-3. When OSS provisions the ONT, re-enable it & program 802.1x flow - UNI port(s) will be UP
-4. Ensure that DHCP fails here (because subscriber/service-binding has not been provisioned by OSS yet)
-5. 802.1x EAPOL message happens from RG, and ONOS AAA app adds options and sends to radius server. Options are pulled from Sadis/NEM - no subscriber information is required here
-6. If RG authentication fails, allow it to keep trying (in the future consider redirection to captive / self-help portal). DHCP should not succeed since RG authentication has failed
-7. If RG authentication succeeds, ONOS AAA app notifies via an event on the kafka bus that authentication has succeeded
-8. NEM can listen for the event, and then check to see if subscriber/service-binding has happened on that port from OSS - if not, then nothing to be done
-9. Must ensure that DHCP fails here even though RG has been authenticated (because subscriber/service-binding has not been provisioned by OSS yet)
-10. When OSS provisions the subscriber/service-binding on the UNI port and gives the C and S vlan info, then DHCP trap will be programmed on the port, and DHCP process can start
-11. If RG is disconnected from UNI port, force authentication again (even if subscriber/service-binding has been provisioned by OSS). Upon reconnection to UNI port, RG must re-authenticate before DHCP/other-traffic can flow on the provisioned VLANs.
-12. DHCP L2 relay -> add option 82, learn public IP address, forward via dataplane to external DHCP server
-
-
-This schema summarizes the workflow, please note:
-
-- in `light blue` are environment events (wether they are triggered from hardware or from an operator)
-- in `yellow` are NEM configuration calls to ONOS or VOLTHA
-- in `green` are decisions
-- in `orange` event published on the kafka bus
-
-
-
-> NOTE: when we refer to `service chain` we are talking about the set of
-subscriber specific service instances that will trigger the `add_subscriber`
-call in ONOS-VOLTHA and provision the crossconnect in ONOS-FABRIC
-
-## Operations
-
-We assume your POD is already configured as per[this instructions](../configuration.md)
-(you need to complete only the first section)
-
-### Whitelist population
-
-To configure the ONU whitelist, you can use this TOSCA:
-
-```yaml
-tosca_definitions_version: tosca_simple_yaml_1_0
-imports:
- - custom_types/attworkflowdriverwhitelistentry.yaml
- - custom_types/attworkflowdriverservice.yaml
-description: Create an entry in the whitelist
-topology_template:
- node_templates:
-
- service#att:
- type: tosca.nodes.AttWorkflowDriverService
- properties:
- name: att-workflow-driver
- must-exist: true
-
- whitelist:
- type: tosca.nodes.AttWorkflowDriverWhiteListEntry
- properties:
- serial_number: BRCM22222222
- pon_port_id: 536870912
- device_id: of:000000000a5a0072
- requirements:
- - owner:
- node: service#att
- relationship: tosca.relationships.BelongsToOne
-```
-
-For instructions on how to push TOSCA into a CORD POD, please
-refer to this [guide](../../../xos-tosca/README.md).
-
-### Pre-provision subscribers
-
-You can `pre-provision` subscribers using this TOSCA:
-
-```yaml
-tosca_definitions_version: tosca_simple_yaml_1_0
-imports:
- - custom_types/rcordsubscriber.yaml
-
-description: Pre-provsion a subscriber
-
-topology_template:
- node_templates:
-
- # Pre-provision the subscriber the subscriber
- my_house:
- type: tosca.nodes.RCORDSubscriber
- properties:
- name: My House
- status: pre-provisioned
- c_tag: 111
- onu_device: BRCM22222222
- nas_port_id : "PON 1/1/03/1:1.1.1"
- circuit_id: foo
-```
-
-For instructions on how to push TOSCA into a CORD POD, please
-refer to this [guide](../../../xos-tosca/README.md).
-
-### OLT Activation
-
-Once the system knows about whitelisted ONUs and subscribers,
-you can activate the OLT:
-
-```yaml
-tosca_definitions_version: tosca_simple_yaml_1_0
-imports:
- - custom_types/oltdevice.yaml
- - custom_types/voltservice.yaml
-description: Create a simulated OLT Device in VOLTHA
-topology_template:
- node_templates:
-
- service#volt:
- type: tosca.nodes.VOLTService
- properties:
- name: volt
- must-exist: true
-
- olt_device:
- type: tosca.nodes.OLTDevice
- properties:
- name: ONF OLT
- device_type: openolt
- host: 10.90.0.114
- port: 9191
- switch_datapath_id: of:0000000000000001
- switch_port: "1"
- outer_tpid: "0x8100"
- uplink: "128"
- requirements:
- - volt_service:
- node: service#volt
- relationship: tosca.relationships.BelongsToOne
-```
-
-For instructions on how to push TOSCA into a CORD POD, please
-refer to this [guide](../../../xos-tosca/README.md).
-
-### Device monitoring
-
-Please refer to the [monitoring](../../../charts/logging-monitoring.md) chart.
diff --git a/quickstart.md b/quickstart.md
index 544963d..3dfab6b 100644
--- a/quickstart.md
+++ b/quickstart.md
@@ -11,7 +11,11 @@
complete these steps, you might be interested in jumping ahead to the
[SimpleExampleService Tutorial](simpleexampleservice/simple-example-service.md)
to learn more about the make-up of a CORD service. Another option
-would be to explore CORD's [operational interfaces](operating_cord/general.md).
+would be to explore CORD's [operational interfaces](operating_cord/general.md).
* [MacOS](macos.md)
* [Linux](linux.md)
+
+Instead if you want to quickly get started with a complete CORD system together
+with the CORD platform, a profile such as SEBA, an exemplar operator workflow and
+an emulated data-plane, consider [SEBA-in-a-Box](./profiles/seba/siab-overview.md).