fixed typos, links, and nits
Change-Id: If5c60b8e6dfa2094d67e03450274a8468448f0a2
diff --git a/docs/README.md b/docs/README.md
index 5dadf14..64278b0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,11 +5,11 @@
If this is your first encounter with CORD, we suggest you start by
bringing up an emulated version called _CORD-in-a-Box_.
It installs CORD on a set of virtual machines running on a single
-physical server. Just follow our [CORD-in-a-Box Guide](quickstart.md).
+physical server. Just follow our instructions for
+[Installing CORD-in-a-Box](install_ciab.md).
You can also install CORD on a physical POD. This involves first assembling
a set of servers and switches, and then pointing the build system at
-that target hardware. You can either follow our
-[Quick Start Guide](quickstart_physical.md), or read a more detailed,
-step-by-step recipe for [Installing a Physical POD](install_pod.md).
+that target hardware. Just follow our instructoins for
+[Installing a Physical POD](install_pod.md).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 82590ff..1b793c7 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -3,20 +3,20 @@
* [Guide Overview](overview.md)
* [Terminology](terminology.md)
* [Building and Installing CORD](README.md)
- * [Quickstarts](quickstarts.md)
+ * [Quickstart](quickstarts.md)
* [Installing CORD-in-a-Box](install_ciab.md)
* [Installing a Physical POD](install_pod.md)
- * [Appendix: Network Settings](appendix_network_settings.md)
- * [Appendix: Basic Configuration](appendix_basic_config.md)
- * [Appendix: Container Images](appendix_images.md)
- * [Appendix: vSG Configuration](appendix_vsg.md)
+ * [Network Settings](appendix_network_settings.md)
+ * [Basic Configuration](appendix_basic_config.md)
+ * [Container Images](appendix_images.md)
+ * [vSG Configuration](appendix_vsg.md)
* [Connecting to Upstream Networks](vrouter.md)
* [Build System Internals](build_internals.md)
* [Operating and Managing CORD](operate/README.md)
- * [Configuring XOS: xosconfig](xos/modules/xosconfig.md)
+ * [Configuring XOS](xos/modules/xosconfig.md)
* [Powering Up a POD](operate/power_up.md)
* [ELK Stack Logs](operate/elk_stack.md)
- * [XOS](https://guide.opencord.org/{{ book.brach }}/api/xos/)
+ * [REST API](https://guide.opencord.org/{{ book.branch }}/api/xos/)
* [Defining Models in CORD](xos/README.md)
* [XOS Support for Models](xos/dev/xproto.md)
* [Core Models](xos/core_models.md)
@@ -26,7 +26,7 @@
* [Implementation Details](xos/dev/sync_impl.md)
* [Migrating Models to 4.0](xos/migrate-4.0.md)
* [Developing for CORD](develop.md)
- * [Getting the CORD source code](cord_repo.md)
+ * [Getting the Source Code](cord_repo.md)
* [Workflow: platform-install](platform-install/README.md)
* [Workflow: local dev](xos/dev/local_env.md)
* [Example Service](xos/example_service.md)
diff --git a/docs/appendix_basic_config.md b/docs/appendix_basic_config.md
index 68c0e25..73161c4 100644
--- a/docs/appendix_basic_config.md
+++ b/docs/appendix_basic_config.md
@@ -1,6 +1,6 @@
-#Appendix: Basic Configuration
+# Basic Configuration
-This appendix provides instructions on how to configure an installed POD.
+The following provides instructions on how to configure an installed POD.
##Fabric
diff --git a/docs/appendix_images.md b/docs/appendix_images.md
index abb5505..a047172 100644
--- a/docs/appendix_images.md
+++ b/docs/appendix_images.md
@@ -1,4 +1,4 @@
-#Appendix: Container Images
+# Container Images
In the installation process CORD fetches, builds, and deploys a set of container images.
These include:
diff --git a/docs/appendix_network_settings.md b/docs/appendix_network_settings.md
index 89d68fe..5f8a6a7 100644
--- a/docs/appendix_network_settings.md
+++ b/docs/appendix_network_settings.md
@@ -1,4 +1,4 @@
-# Appendix: Network Settings
+# Network Settings
The CORD POD uses two core network interfaces: fabric and mgmtbr.
The fabric interface is used to bond all interfaces meant to be used for CORD data traffic and the mgmtbr will be used to bridge all interfaces used for POD management (signaling) traffic. An additional interface of import on the head node is the external interface, or the interface through which the management network accesses upstream servers, such as the Internet.
diff --git a/docs/appendix_vsg.md b/docs/appendix_vsg.md
index df974bb..253af3f 100644
--- a/docs/appendix_vsg.md
+++ b/docs/appendix_vsg.md
@@ -1,4 +1,4 @@
-#Appendix: vSG Configuration
+# vSG Configuration
First, login to the CORD head node CLI and go to the `/opt/cord_profile` directory. To configure the fabric gateway, you will need to edit the file `cord-services.yaml`. You will see a section that looks like this:
diff --git a/docs/cord_repo.md b/docs/cord_repo.md
index 4aedda4..a087fdb 100644
--- a/docs/cord_repo.md
+++ b/docs/cord_repo.md
@@ -1,6 +1,6 @@
-#Getting the CORD source code
+# Getting the Source Code
-##Install repo
+## Install repo
Repo is a tool from Google that help us managing the code base.
```
@@ -9,14 +9,21 @@
sudo cp repo /usr/bin
```
-##Download the CORD repositories
+## Download CORD Repositories
<pre><code>mkdir ~/cord && \
cd ~/cord && \
repo init -u https://gerrit.opencord.org/manifest -b {{ book.branch }} && \
repo sync</code></pre>
->NOTE: master is used as example. You can substitute it with your favorite branch, for example cord-4.0 or cord-3.0. You can also use a "flavor" specific manifests such as “mcord” or “ecord”. The flavor you use here is not correlated to the profile you will choose to run later but it is suggested that you use the corresponding manifest for the deployment you want. AN example is to use the “ecord” profile and then deploy the ecord.yml service\_profile.
+>NOTE: `master` is used as an example. You can substitute your favorite
+>branch for `master`, for example, `cord-4.0` or `cord-3.0`. You can
+>also use flavor-specific manifests such as `mcord` or `ecord`. The
+>flavor you use here is not correlated to the profile you will choose
+>to run later, but it is suggested that you use the corresponding
+>manifest for the deployment you want. For example, if you use the
+>`ecord` manifest then it would be typical to deploy the
+>`ecord.yml` service profile.
When this is complete, a listing (`ls`) inside this directory should yield output similar to:
@@ -24,3 +31,12 @@
ls -F
build/ incubator/ onos-apps/ orchestration/ test/
```
+
+## Contribute Code to CORD
+
+We use [Gerrit](https://gerrit.opencord.org) to manage the code base.
+For more information about how to commit patches to Gerrit, click
+[here](https://wiki.opencord.org/display/CORD/Getting+the+Source+Code).
+For a general introduction to ways you can participate and contribute
+to the project, check out the
+[CORD wiki](https://wiki.opencord.org/display/CORD/Contributing+to+CORD).
diff --git a/docs/install_ciab.md b/docs/install_ciab.md
index ff3ad6c..6df2098 100644
--- a/docs/install_ciab.md
+++ b/docs/install_ciab.md
@@ -1,13 +1,20 @@
-# Installing CORD-in-a-Box (CiaB)
+# Installing CORD-in-a-Box
-This guide walks through the steps to bring up a demonstration CORD
-"POD", running in virtual machines on a single physical server (a.k.a.
-"CORD-in-a-Box" or just "CiaB"). The purpose of this demonstration POD is to enable those interested in understanding how CORD works to examine and interact with a running CORD environment. It is a good place for novice CORD users to start.
+This guide walks through the steps to bring up a virtual CORD
+POD, running in virtual machines on a single physical server. This
+version is also known as *CORD-in-a-Box* (or just *CiaB*).
+The purpose of this virtual POD is to enable those interested in
+understanding how CORD works to examine and interact with
+a running CORD environment. It also serves as a common
+[development environment](develop.md).
->NOTE: Looking for a quick list of essential build commands? You can find it [here](quickstarts.md)
+>NOTE: Looking for a quick list of essential build commands?
+>You can find it [here](quickstarts.md)
->NOTE: This guide describes how to install a simplified version of a CORD POD on a single server using virtual machines. If you are looking for instructions on how to install a multi-node POD, you will find them in the
-[Physical POD installtion guide](install_pod.md).
+>NOTE: This guide describes how to install a simplified version
+>of a CORD POD on a single server using virtual machines.
+>If you are looking for instructions on how to install a physical
+>POD, you can find it [here](install_pod.md).
## What you need (prerequisites)
@@ -32,8 +39,11 @@
account using your organization's email address and choose "Join Existing
Project"; for "Project Name" enter `cord-testdrive`.
->NOTE: CloudLab is supporting CORD as a courtesy. It is expected that you will not use CloudLab resources for purposes other than evaluating CORD. If, after a week or two, you wish to continue using CloudLab to experiment with or
-develop CORD, then you must apply for your own separate CloudLab project.
+>NOTE: CloudLab is supporting CORD as a courtesy. It is expected that
+>you will not use CloudLab resources for purposes other than
+>evaluating CORD. If, after a week or two, you wish to continue using
+>CloudLab to experiment with or develop CORD, then you must apply for
+>your own separate CloudLab project.
Once your account is approved, start an experiment using the
`OnePC-Ubuntu14.04.5` profile on the Wisconsin, Clemson, or Utah clusters.
@@ -43,13 +53,13 @@
Refer to the [CloudLab documentation](https://docs.cloudlab.us) for more
information.
-## Building a CiaB
+## Building CiaB
There are three main steps to building CiaB:
* Bootstrap the server by installing software dependencies and checking out the CORD code
* Customize the source and configuration if desired
-* Running `make` commands to build and deploy the CORD software, and run tests
+* Run `make` commands to build and deploy the CORD software, and run tests
### Download and run the bootstrap script
@@ -338,7 +348,7 @@
>NOTE: the `Service Graph` will need to be detangled. You can organize the nodes by dragging them around.
-### Kibana log viewing GUI
+### Kibana Logging GUI
The Kibana web interface to the ElasticStack log aggregation system can be
found at: `http://<target-server>:8080/kibana/`.
@@ -425,7 +435,7 @@
If the CiaB build fails, you may try simply resuming the build at the
place that failed. The easiest way is to do is to re-run the
-`make build` command; it will skip over the steps that have already completed.
+`make build` command. It will skip over the steps that have already completed.
If you need to force `make build` to re-run steps that have already completed,
remove the appropriate file in the `milestones` directory prior to re-running.
diff --git a/docs/install_pod.md b/docs/install_pod.md
index 5c76efc..7046108 100644
--- a/docs/install_pod.md
+++ b/docs/install_pod.md
@@ -12,8 +12,9 @@
### Physical Configuration
-A full POD includes a ToR management switch, four fabric switches, and three
-standard x86 servers. The following figure does not show access devices
+A full POD includes a Top-of-Rack (ToR) management switch,
+four fabric switches, and three standard x86 servers.
+The following figure does not show access devices
or any upstream connectivity to the metro network; those details are included
later in this section.
@@ -87,7 +88,7 @@
* Strongly Suggested NIC:
* Intel Ethernet Converged Network Adapters XL710 10/40 GbE PCIe 3.0, x8 Dual port.
* ConnectX®-3 EN Single/Dual-Port 10/40/56GbE Adapters w/ PCI Express 3.0.
- >NOTE: while the machines mentioned above are generic standard x86 servers, and can be potentially substituted with any other machine, it’s quite important to stick with either one of the network card suggested. CORD scripts will look for either an i40e or a mlx4_en driver, used by the two cards cards. To use other cards additional operations will need to be done. Please, see the [Network Settings](appendix_network_settings.md) appendix for more information.
+ >NOTE: while the machines mentioned above are generic standard x86 servers, and can be potentially substituted with any other machine, it’s quite important to stick with either one of the network card suggested. CORD scripts will look for either an i40e or a mlx4_en driver, used by the two cards cards. To use other cards additional operations will need to be done. Please, see [Network Settings](appendix_network_settings.md) for more information.
* 4x Fabric Switches
* Suggested Model: OCP-qualified Accton 6712 switch. Each switch
@@ -250,11 +251,11 @@
>NOTE: Some users prefer to connect as well the IPMI interfaces of the compute nodes to the external network, so they can have control on them also from outside the POD. This way the head node will be able to control them anyway.
-### Fabric switches: ONIE
+### Fabric Switches: ONIE
The ONIE installer should be already installed on the switch and set to boot in installation mode. This is usually the default for new switches sold without an Operating System. It might not be the case instead if switches have already an Operating System installed. In this case rebooting the switch in ONIE installation mode depends by different factors, such the version of the OS installed and the specific model of the switch.
-## Prepare POD configuration file and generate the composite configuration
+## Prepare POD Configuration
Each CORD POD deployment requires a POD configuration file that
describes how the system should be configured, including what IP
@@ -270,7 +271,8 @@
commented out, but can be used as needed.
More information about how the network configuration for the POD can
-be customized can be found in an Appendix: POD Network Settings.
+be customized can be found
+in [Network Settings](appendix_network_settings.md).
Once the POD config yaml file has been created, the composite configuration file should be generated with the following command.
@@ -279,11 +281,11 @@
make PODCONFIG={YOUR_PODCONFIG_FILE.yml} config
```
-The process generates a set of files in ~/cord/build/genconfig
+The process generates a set of files in `~/cord/build/genconfig`
->NOTE: Before the configuration process the ~/cord/build/genconfig directory contains a README.md file only.
+>NOTE: Before the configuration process the `~/cord/build/genconfig` directory contains a README.md file only.
-## Head node deployment
+## Head Node Deployment
Head node deployment works as follows:
@@ -489,6 +491,19 @@
### OpenStack
+From the head node CLI
+
+```
+$ sudo lxc list
+```
+
+lists the set of LXC containers running the various OpenStack-related services.
+These containers can be entered as follows:
+
+```
+$ ssh ubuntu@<container-name>
+```
+
### XOS UI
XOS is the cloud orchestrator that controls the entire POD. It allows
@@ -498,5 +513,8 @@
## Getting Help
-If it seems that something has gone wrong with your setup, there are a number of ways that you can get help -- in the documentation on the OpenCORD wiki, on the OpenCORDSlack channel (get an invitation here), or on the CORD-discuss mailing list.
-See the How to Contribute to CORD wiki page for more information.
+If it seems that something has gone wrong with your setup,
+the best way to ask for help is to join the CORD Slack channel
+or mailing lists. Information about both can be found at the
+[CORD wiki](https://wiki.opencord.org/display/CORD).
+
diff --git a/docs/operate/README.md b/docs/operate/README.md
index 2ae556b..5278d55 100644
--- a/docs/operate/README.md
+++ b/docs/operate/README.md
@@ -11,6 +11,8 @@
It is also the case that CORD's operations and management interface
is primarily defined by its Northbound API. The RESTful version of
-this API is documented at `<head-node>/apidocs/` on a running POD.
+this API is documented at `<head-node>/apidocs/` on a running
+POD (a composite API spec is also included in this
+[guide](https://guide.opencord.org/{{ book.branch }}/api/xos/)).
This API is auto-generated from a set of models, where CORD's
model-based design is describe [elsewhere](../xos/README.md).
diff --git a/docs/overview.md b/docs/overview.md
index b8a3eca..f2eeda4 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -4,4 +4,7 @@
Source for individual guides is available in the CORD code repository (https://gerrit.opencord.org); look in the `/docs` directory of each project, with the GitBook rooted in `cord/docs`. Updates and improvements to this documentation can be submitted through Gerrit.
-The community is in the process of migrating documents to these guides. You can find additional information on the [CORD wiki](https://wiki.opencord.org), and in particular, a set of _CORD Design Notes_ on the [Documentation](https://wiki.opencord.org/display/CORD/Documentation) page.
+CORD is a community-based open source project. In addition to this guide,
+you can find information about this community, its projects, and its governance
+on the [CORD wiki](https://wiki.opencord.org). This includes early white papers
+and design notes that have shaped [CORD's architecture](https://wiki.opencord.org/display/CORD/Documentation).
diff --git a/docs/quickstarts.md b/docs/quickstarts.md
index b0cfc47..5baa58b 100644
--- a/docs/quickstarts.md
+++ b/docs/quickstarts.md
@@ -1,12 +1,13 @@
-# Quickstarts
+# Quickstart
-The section provides a short list of essential commands that can be used to deploy CiaB and a physical.
+This section provides a short list of essential commands that can be
+used to deploy CORD-in-a-Box and a physical POD.
>NOTE: Looking for the full Cord-in-a-Box (CiaB) installation guide? You can find it [here](install_ciab.md).
>NOTE: Looking for the full physical pod installation guide? You can find it [here](install_pod.md).
-## Common step (both for CiaB and physical POD)
+## Common Step (for both CiaB and a Physical POD)
<pre><code>cd ~ && \
wget https://raw.githubusercontent.com/opencord/cord/{{ book.branch }}/scripts/cord-bootstrap.sh && \
chmod +x cord-bootstrap.sh && \
@@ -24,9 +25,9 @@
```
## Physical POD
-Following are the steps needed to install a physical POD.
+The following steps install a physical POD.
-### Prepare the head node:
+### Prepare the head node
```
sudo adduser cord && \
@@ -34,8 +35,8 @@
echo 'cord ALL=(ALL) NOPASSWD:ALL' | sudo tee --append /etc/sudoers.d/90-cloud-init-users
```
-### On the development machine:
-Create your POD configuration .yml file in ~/cord/build/podconfig.
+### On the development machine
+Create your POD configuration `.yml` file in `~/cord/build/podconfig`.
```
cd ~/cord/build && \
@@ -44,4 +45,4 @@
```
### Compute nodes and fabric switches
-After a successful build, set the compute nodes and the switches to boot from PXE and manually reboot them. They will get automatically deployed.
\ No newline at end of file
+After a successful build, set the compute nodes and the switches to boot from PXE and manually reboot them. They will be automatically deployed.
diff --git a/docs/service-profiles.md b/docs/service-profiles.md
index 6e2e8a7..679768d 100644
--- a/docs/service-profiles.md
+++ b/docs/service-profiles.md
@@ -1,3 +1,13 @@
# Service Profiles
This guide describes each of the service profiles that can be built on top of the CORD platform. The content in this guide is currently thin, but this is the place to document various profiles going forward.
+
+Both *Services* and *Service Profiles* are classified as either
+
+* **Official** – Passed QA tests, officially approved by the TST, to be supported in maintenance releases.
+
+* **Development** – Not fully tested, included in the release for evaluation, not currently supported.
+
+These classifications are defined by the CORD
+[Technical Steering Team (TST)](https://wiki.opencord.org/display/CORD/Technical+Steering+Team)
+and subject to change.
diff --git a/docs/terminology.md b/docs/terminology.md
index 7ce4729..81fd726 100644
--- a/docs/terminology.md
+++ b/docs/terminology.md
@@ -1,38 +1,40 @@
#Terminology
-This guide uses the following terminology.
+This guide uses the following terminology. (Additional terminology and
+definitions can be found in an overview of the
+[CORD Ecosystem](https://wiki.opencord.org/display/CORD/Defining+CORD).)
* **POD**: A single physical deployment of CORD.
-* **Full POD**: A typical configuration, and is used as example in this Guide.
-A full CORD POD is composed by three servers, and four fabric switches.
-It makes it possibile to experiment with all the core features of CORD and it
-is what the community uses for tests.
+* **Full POD**: A typical configuration, used as example in this Guide.
+A full CORD POD consists of three servers and four fabric switches.
+This makes it possibile to experiment with all the core features of CORD, and it
+is what the community typically uses for tests.
* **Half POD**: A minimum-sized configuration. It is similar to a full POD, but with less hardware. It consists of two servers (one head node and one compute node), and one fabric switch. It does not allow experimentation with all of the core features that
CORD offers (e.g., a switching fabric), but it is still good for basic experimentation and testing.
-* **Development (Dev) machine**: This is the machine used
+* **Development (Dev) Machine**: This is the machine used
to download, build and deploy CORD onto a POD.
-Sometimes it is a dedicated server, and sometime the developer's laptop.
+Sometimes it is a dedicated server, and sometimes the developer's laptop.
In principle, it can be any machine that satisfies the hardware and software
-requirements reported below.
+requirements.
* **Development (Dev) VM**: Bootstrapping the CORD installation requires a lot of
software to be installed and some non-trivial configurations to be applied.
-All this should happens on the dev machine.
+All this should happen on the dev machine.
To help users with the process, CORD provides an easy way to create a
VM on the dev machine with all the required software and configurations in place.
* **Compute Node(s)**: A server in a POD that run VMs or containers associated with
one or more tenant services. This terminology is borrowed from OpenStack.
-* **Head Node**: A compute node of the POD that runs also management services. This includes for example XOS (the orchestrator), two instances of ONOS
-(the SDN controller, one to control the underlay fabric, one to control the overlay), MAAS and all the services needed to automatically install and configure the rest of
+* **Head Node**: A compute node of the POD that also runs management services. This includes for example XOS (the orchestrator), two instances of ONOS
+(the SDN controller, one to control the underlay fabric and one to control the overlay), MAAS and all the services needed to automatically install and configure the rest of
the POD devices.
-* **Fabric Switch**: A switch in a POD that interconnects other switch and server
-elements inside the POD.
+* **Fabric Switch**: A switch in a POD that interconnects other switches and servers
+inside the POD.
* **vSG**: The virtual Subscriber Gateway (vSG) is the CORD counterpart for existing
-CPEs. It implements a bundle of subscriber-selected functions, such as Restricted Access, Parental Control, Bandwidth Metering, Access Diagnostics and Firewall. These functionalities run on commodity hardware located in the Central Office rather than on the customer’s premises. There is still a device in the home (which we still refer to as the CPE), but it has been reduced to a bare-metal switch.
\ No newline at end of file
+CPEs. It implements a bundle of subscriber-selected functions, such as Restricted Access, Parental Control, Bandwidth Metering, Access Diagnostics and Firewall. These functions run on commodity hardware located in the Central Office rather than on the customer’s premises. There is still a device in the home (which we still refer to as the CPE), but it has been reduced to a bare-metal switch.