Merge "Adding R-CORD known issues and solutions"
diff --git a/.gitignore b/.gitignore
index 27384fe..0b1f37c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
npm-debug.log
node_modules
_book
+repos
xos/_book
venv-xosdocs
.DS_Store
diff --git a/Makefile b/Makefile
index f1d1b93..a084f5f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,93 +1,89 @@
# Makefile for building CORD docs site, guide.opencord.org
# Building docs requires the following tools:
# - Gitbook toolchain: https://toolchain.gitbook.com/setup.html
+# - git
# - NPM (for Gitbook and Swagger)
-# - Python (for build glossary script)
# - linkchecker (for test target) http://wummel.github.io/linkchecker/
+# - markdownlint (for lint target) https://github.com/markdownlint/markdownlint
default: serve
-# use bash for pushd/popd, and to fail if commands within a pipe fail
-SHELL = bash -o pipefail
+# use bash for pushd/popd, and to fail quickly
+SHELL = bash -eu -o pipefail
-GENERATED_DOCS =
+# Other repos with documentation that's included in the gitbook
+# edit the `git_refs` file with the commit/tag/branch that you want to use
+OTHER_REPO_DOCS ?= cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt openstack rcord simpleexampleservice exampleservice vrouter xos xos-gui xos-tosca
+GENERATED_DOCS ?= # should be 'swagger', but currently broken
+ALL_DOCS ?= $(OTHER_REPO_DOCS) $(GENERATED_DOCS)
-LINT_STYLE ?= mdl_relaxed.rb
-
-serve: setup
+# build targets
+serve: | $(ALL_DOCS) gitbook-setup
npm start
-build: setup
+build: _book
+
+_book: | $(ALL_DOCS) gitbook-setup
gitbook build
-setup: automation-tools cord-tester simpleexampleservice openstack fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter xos xos-gui xos-tosca swagger $(GENERATED_DOCS)
+gitbook-setup:
gitbook init
gitbook install
-test: linkcheck lint
+clean:
+ rm -rf _book
+ rm -rf node_modules
+ rm -rf repos/*
+ rm -rf $(ALL_DOCS)
-linkcheck: build
- linkchecker -a _book/
+# testing targets
+test: lint linkcheck
+LINT_STYLE ?= mdl_relaxed.rb
-lint:
+lint: | $(OTHER_REPO_DOCS)
@echo "markdownlint(mdl) version: `mdl --version`"
@echo "style config:"
@echo "---"
@cat $(LINT_STYLE)
@echo "---"
- mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
+ mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./repos/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
-# link directories that contain other documentation
-automation-tools:
- ln -s ../automation-tools automation-tools
+linkcheck: $(ALL_DOCS) _book
+ linkchecker -a _book/
-cord-tester:
- ln -s ../test/cord-tester/docs cord-tester
+# Host holding the git server
+REPO_HOST ?= https://gerrit.opencord.org
-fabric:
- ln -s ../orchestration/xos_services/fabric/docs fabric
+# checkout the repos inside repos/ dir
+repos:
+ mkdir repos
-hippie-oss:
- ln -s ../orchestration/xos_services/hippie-oss/docs hippie-oss
+# build directory paths in repos/* to perform 'git clone <repo>' into
+CHECKOUT_REPOS=$(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
-olt-service:
- ln -s ../orchestration/xos_services/olt-service/docs olt-service
+# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
+# pre-populate it under epos with the specific commit to being validated
+SKIP_CHECKOUT ?=
-onos-service:
- ln -s ../orchestration/xos_services/onos-service/docs onos-service
+# clone (only if doesn't exist), then checkout ref in repos/*
+$(CHECKOUT_REPOS): git_refs | repos
+ GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
+ if [ ! -d '$@' ] ;\
+ then git clone $(REPO_HOST)/$(@F) $@ ;\
+ fi ;\
+ if [ "$(SKIP_CHECKOUT)" = "$(@F)" ] ;\
+ then echo "Skipping checkout of repo $(SKIP_CHECKOUT) as it's being tested" ;\
+ else pushd $@ ;\
+ git checkout $$GIT_REF ;\
+ popd ;\
+ fi
-kubernetes-service:
- ln -s ../orchestration/xos_services/kubernetes-service/docs kubernetes-service
+# link subdirectories (if applicable) into main docs dir
+$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
+ GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
+ ln -s repos/$(@)$$GIT_SUBDIR $@
-openolt:
- ln -s ../incubator/openolt openolt
-
-rcord:
- ln -s ../orchestration/profiles/rcord/docs rcord
-
-vrouter:
- ln -s ../orchestration/xos_services/vrouter/docs vrouter
-
-openstack:
- ln -s ../orchestration/xos_services/openstack/docs openstack
-
-simpleexampleservice:
- ln -s ../orchestration/xos_services/simpleexampleservice/docs simpleexampleservice
-
-xos:
- ln -s ../orchestration/xos/docs xos
-
-xos-gui:
- ln -s ../orchestration/xos-gui/docs xos-gui
-
-xos-tosca:
- ln -s ../orchestration/xos-tosca/docs xos-tosca
-
+# swagger docs generation
swagger: xos
- pushd ../orchestration/xos/docs/; make swagger_docs; popd;
+ pushd repos/xos/docs; make swagger_docs; popd;
-clean:
- rm -rf $(GENERATED_DOCS)
- rm -rf _book
- rm -rf node_modules
- rm -rf openstack automation-tools cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter test xos xos-gui xos-tosca simpleexampleservice
diff --git a/SUMMARY.md b/SUMMARY.md
index 70dc248..5da0124 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -64,17 +64,17 @@
* [Synchronizer Reference](xos/dev/sync_reference.md)
* [Core Models](xos/core_models.md)
* [Security Policies](xos/security_policies.md)
+ * [Tutorial](xos/tutorials/basic_synchronizer.md)
* [Developer Workflows](developer/workflows.md)
* [Working on R-CORD Without an OLT/ONU](developer/configuration_rcord.md)
* [Building Docker Images](developer/imagebuilder.md)
- * Tutorials
- * [Synchronizer Hello World](developer/tutorials/basic-synchronizer/intro.md)
* [Platform Services](developer/platform.md)
* [Kubernetes](kubernetes-service/kubernetes-service.md)
* [OpenStack](openstack/openstack-service.md)
* [VTN and Service Composition](xos/xos_vtn.md)
* [Example Services](examples/examples.md)
* [SimpleExampleService](simpleexampleservice/simple-example-service.md)
+ * [ExampleService](exampleservice/example-service.md)
* [GUI Development](xos-gui/developer/README.md)
* [Quickstart](xos-gui/developer/quickstart.md)
* [GUI Extensions](xos-gui/developer/gui_extensions.md)
diff --git a/examples/examples.md b/examples/examples.md
new file mode 100644
index 0000000..4f484f2
--- /dev/null
+++ b/examples/examples.md
@@ -0,0 +1,8 @@
+# Example Services
+
+There are two examples of services, which show how to create models and
+synchronizers:
+
+- ExampleService, which sets up a VM in Openstack
+- SimpleExampleService, which sets up a container in Kubernetes
+
diff --git a/git_refs b/git_refs
new file mode 100644
index 0000000..7faa57f
--- /dev/null
+++ b/git_refs
@@ -0,0 +1,29 @@
+# git_refs
+#
+# This file contains a list of repos, paths within those repos, and git
+# references (branch/tag/commit hash) that are checked out with `git checkout
+# <ref>` during creation of documentation.
+#
+# - First column is the git repo name
+# - Second column is the subdirectory of the repo to symlink into the
+# docs directory
+# - Third column is the reference (branch/tag/commit) to checkout
+
+_REPO NAME_ _DIR_ _REF_
+
+cord-tester /docs master
+fabric /docs master
+hippie-oss /docs master
+kubernetes-service /docs master
+olt-service /docs master
+onos-service /docs master
+openolt / master
+openstack /docs master
+rcord /docs master
+simpleexampleservice /docs master
+exampleservice /docs master
+vrouter /docs master
+xos-gui /docs master
+xos-tosca /docs master
+xos /docs master
+
diff --git a/operating_cord/rest_apis.md b/operating_cord/rest_apis.md
index 7b29be0..5f3f476 100644
--- a/operating_cord/rest_apis.md
+++ b/operating_cord/rest_apis.md
@@ -1,18 +1,11 @@
# RESTful APIs
A RESTful interface is available for configuring and controlling CORD. It is
-auto-generated from the set of [models](/xos/README.md) configured
-into the POD manifest, and includes both core and service-specific models.
+auto-generated from the set of [models](/xos/intro.md) configured
+into a POD, and includes both core and service-specific models. Click
+[here](https://guide.opencord.org/master/api/xos/) to see API defined
+for the full set of services checked into [Gerrit](https://gerrit.opencord.org).
-* [Core](https://guide.opencord.org/{{ book.branch }}/api/xos/#/core)
-* [Address Manager](https://guide.opencord.org/{{ book.branch }}/api/xos/#/addressmanager)
-* [vTR](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vtr)
-* [vSG](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vsg)
-* [vNoD Local](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vnodlocal)
-* [vRouter](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vrouter)
-* [ONOS Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/onos)
-* [Fabric Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/fabric)
-* [Example Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/exampleservice)
-* [vEE](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vee)
-* [vEG](https://guide.opencord.org/{{ book.branch }}/api/xos/#/veg)
-* [vnaas](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vnaas)
+You can access the REST API specification on a running POD by going to
+the `/apidocs/` URL on the Chameleon REST endpoint (exposed at
+port 30006 by default): <http://pod-ip-or-dns-address:30006/apidocs/>.
diff --git a/prereqs/docker-registry.md b/prereqs/docker-registry.md
index a94587e..cce78ee 100644
--- a/prereqs/docker-registry.md
+++ b/prereqs/docker-registry.md
@@ -27,7 +27,7 @@
The registry can be queried at any time, for example:
```shell
-curl -X GET https://KUBERNETES_IP:30500/v2/_catalog
+curl -X GET http://KUBERNETES_IP:30500/v2/_catalog
```
{% include "/partials/push-images-to-registry.md" %}
diff --git a/prereqs/hardware.md b/prereqs/hardware.md
index 20eb576..820ff9a 100644
--- a/prereqs/hardware.md
+++ b/prereqs/hardware.md
@@ -72,14 +72,22 @@
copper cable, 3m length - S/N: QSFP-40G-03C
* **R-CORD Access Devices and Optics**
+ * **GPON**
+ * **OLT**: Celestica CLS Ruby S1010 (experimental, only top-down provisioning is supported - through manual customizations)
+ * Compatible **OLT optics**
+ * OptoWiz LSP4343-CKSA-R GPON SFP OLT Transceiver
+ * **ONUs**:
+ * Celestica Tellion GP-1204
+ * Movistar ONU (with CPE included) (manifactured by Telefonica: <http://www.movistar.es/particulares/movil/moviles/hgu>)
* **XGS-PON**
* **OLT**: EdgeCore ASFVOLT16 (for more info <bartek_raszczyk@edge-core.com>)
- * Compatible **OLT optics**
- * Hisense/Ligent: LTH7226-PC, LTH7226-PC+
- ** Source Photonics: XPP-XG2-N1-CDFA
- * **ONU**: AlphaNetworks PON-34000B (for more info <ed-y_chen@alphanetworks.com>)
- * Compatible **ONU optics**
- * Hisense/Ligent: LTF7225-BC, LTF7225-BH+
+ * Compatible **OLT optics**
+ * Hisense/Ligent: LTH7226-PC, LTH7226-PC+
+ * Source Photonics: XPP-XG2-N1-CDFA
+ * **ONUs**:
+ * AlphaNetworks PON-34000B (for more info <ed-y_chen@alphanetworks.com>)
+ * Compatible **ONU optics**
+ * Hisense/Ligent: LTF7225-BC, LTF7225-BH+
* **M-CORD Specific Requirements**
* **Servers**: Some components of CORD require at least a Intel XEON CPU with Haswell microarchitecture or better.
diff --git a/prereqs/openstack-helm.md b/prereqs/openstack-helm.md
index d60f9a8..7627a45 100644
--- a/prereqs/openstack-helm.md
+++ b/prereqs/openstack-helm.md
@@ -61,6 +61,15 @@
```
```bash
+cat <<EOF > /tmp/libvirt-cord.yaml
+---
+network:
+ backend: []
+EOF
+export OSH_EXTRA_HELM_ARGS_LIBVIRT="-f /tmp/libvirt-cord.yaml"
+```
+
+```bash
cat <<EOF > /tmp/nova-cord.yaml
---
labels:
diff --git a/profiles/mcord/enodeb-setup.md b/profiles/mcord/enodeb-setup.md
index 7e2eaa6..a1a7665 100644
--- a/profiles/mcord/enodeb-setup.md
+++ b/profiles/mcord/enodeb-setup.md
@@ -1,2 +1,153 @@
-# eNodeB Setup
+# eNodeB and HSS Database Setup
+
+## Supported eNodeBs
+
+M-CORD's virtual EPC should work with any standard eNodeB. We tested the
+Cavium eNodeB (model CNF7100-REF2-RF17). In this section we describe how
+to configure this eNodeB to work with M-CORD.
+
+## Connect the eNodeB to the pod
+
+For physical connectivity, this eNodeB has a single Ethernet interface. Our
+test setup uses a single physical compute node for hosting the VNFs. We
+connect the eNodeB to one of the NICs on the compute node.
+
+There are two logical connectivities for a eNodeB: (1) S1MME interface
+connection, between eNodeB and MME for attaching process. (2) S1U interface
+connection, between eNodeB and SPGWU (SGWU+PGWU) for user traffic. To enable
+this connectivity, on the compute node we add the NIC connected to the eNodeB
+to the `fabric` bridge.
+
+## eNodeB configuration
+
+The configuration file on Cavium eNodeB is located at /mnt/app/startup.cfg.
+Find the following lines and change the values:
+
+```bash
+configure net net u32enbipaddress 119.0.0.10
+configure net net u32enbsubnetmask 255.255.255.0
+configure net net u32enbgwipaddress 119.0.0.254
+...
+configure net mme u32mmeipaddress 0 118.0.0.5
+configure net mme u16mmesctpportnumber 0 36412
+...
+configure net sgw u32sgwipaddress 0 119.0.0.2
+```
+
+`u32enbipaddress` is the eNodeB data plane IP address for S1U interface. The
+default IP address in M-CORD is 119.0.0.10/24. You will need to specify it
+when you create the EPC in XOS; see below.
+
+Since `u32enbipaddress` and SPGWU IP on S1U address are on the
+same flat network inside OVS, `u32enbgwipaddress` (gateway IP) does not matter.
+You can give any IP as long as it is not used by eNodeB or SPGWU.
+
+`u32mmeipaddress`: MME IP address on S1MME interface.
+
+`36412`: the default communication port number.
+
+`u32sgwipaddress`: SPGWU IP address on S1U interface.
+
+Where to get those IP addresses? As described at the end of the [M-CORD quick start
+page](https://guide.opencord.org/profiles/mcord/install.html), the command
+`openstack server list --all-projects` will list the VNFs and their IP
+addresses. For example, the
+`flat_network_s1mme` of MME VM is the `u32mmeipaddress`. The `flat_network_s1u`
+is the `u32sgwipaddress`.
+
+Besides this, you should also config the S1U IP and S1MME interface IP address
+on eNodeB by the following command lines. The default value of S1MME we use is
+118.0.0.10/24, while the default value of S1U is 119.0.0.10/24.
+
+```bash
+sudo ifconfig eth0 119.0.0.10/24
+sudo ip addr add 118.0.0.10/24 dev eth0
+```
+
+## Configure the VNFs on the pod for the eNodeB
+
+Specify the eNodeB IP addresses when creating the EPC in the XOS UI.
+To create one, click on `Add` on the `Virtual Evolved Packet Core ServiceInstances` page. You will see:
+
+```bash
+Enodeb ip addr s1mme
+118.0.0.10
+external eNodeB IP address of S1-MME
+119.0.0.10
+```
+
+118.0.0.10 is the default S1MME interface IP on the eNodeB.
+
+119.0.0.10 is the default S1U interface IP on the eNodeB.
+
+Make sure that the IP addresses here are the same as the IP addresses you
+configed on your eNodeB.
+
+## Add subscriber infomation to the HSS database
+
+Prepare the three values of a SIM card: IMSI, key, and opc.
+For apn value, we will use the default value "apn1".
+Login to the HSS-DB VM, with user name "c3po" and password "c3po", and run:
+
+```bash
+~/c3po/db_docs/data_provisioning_users.sh <imsi> 1122334456 apn1 <key> 1 <ip>
+```
+
+Then login to the database:
+
+```bash
+cqlsh <ip>
+```
+
+Set the opc value:
+
+```bash
+cqlsh> use vhss;
+cqlsh:vhss> update users_imsi set opc='<opc>' where imsi='<imsi>';
+```
+
+## Connect a phone to the eNodeB
+
+You can use any phone, as long as it supports the same band as your eNodeB.
+Search the mobile networks. You should see your eNodeB relative name
+as one of the choices.
+
+## Setup verification
+
+Download a ping applicaiton on your phone. You can ping the SGI interface IP
+address of SPGWU from the phone.
+
+Another way to test is to use our InternetEmulator VM. The username and
+password are also "c3po" and "c3po". You need to modify a route on this machine:
+
+```bash
+sudo route add -net 16.0.0.0/8 gw <SPGWU-SGI-IP> dev ens3
+```
+
+16.0.0.0/8 is the default subnet assigned for the phones, you can ignore it.
+SPGWU-SGI-IP is the SGI interface IP address on SPGWU. You can find this IP
+through the same method as with the `u32mmeipaddress` above.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/profiles/mcord/install.md b/profiles/mcord/install.md
index 4df44df..d97a874 100644
--- a/profiles/mcord/install.md
+++ b/profiles/mcord/install.md
@@ -146,7 +146,7 @@
| ID | Name | Status | Networks | Image | Flavor |
+--------------------------------------+-----------------+--------+----------------------------------------------------------------------------------------------------+------------------+-----------+
| 7e197142-afb1-459d-b421-cad91306d19f | mysite_vmme-2 | ACTIVE | s6a_network=120.0.0.9; flat_network_s1mme=118.0.0.5; management=172.27.0.15; s11_network=112.0.0.2 | image_mme_v0.1 | m1.large |
-| 9fe385f5-a064-40e0-94d3-17ea87b955fc | mysite_vspgwu-1 | ACTIVE | management=172.27.0.5; sgi_network=115.0.0.3; spgw_network=117.0.0.3; flat_network_s1u=119.0.0.10 | image_spgwu_v0.1 | m1.xlarge |
+| 9fe385f5-a064-40e0-94d3-17ea87b955fc | mysite_vspgwu-1 | ACTIVE | management=172.27.0.5; sgi_network=115.0.0.3; spgw_network=117.0.0.3; flat_network_s1u=119.0.0.2 | image_spgwu_v0.1 | m1.xlarge |
| aa6805fe-3d72-4f1e-a2eb-5546d7916073 | mysite_hssdb-5 | ACTIVE | management=172.27.0.13; db_network=121.0.0.12 | image_hssdb_v0.1 | m1.large |
| e53138ed-2893-4073-9c9a-6eb4aa1892f1 | mysite_vhss-4 | ACTIVE | s6a_network=120.0.0.2; management=172.27.0.4; db_network=121.0.0.5 | image_hss_v0.1 | m1.large |
| 4a5960b5-b5e4-4777-8fe4-f257c244f198 | mysite_vspgwc-3 | ACTIVE | management=172.27.0.7; spgw_network=117.0.0.8; s11_network=112.0.0.4 | image_spgwc_v0.1 | m1.large |