<commit_before># CORD-in-a-Box Quick Start Guide

This tutorial 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"). 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.

**NOTE:** *This tutorial installs 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
[quickstart_physical.md](./quickstart_physical.md).  For more details about the
actual build process, look there.*

## What you need (Prerequisites)

You will need a *target server*, which will run both a development environment
in a Vagrant VM (used to deploy CORD) as well as CORD-in-a-Box itself.

Target server requirements:

* 64-bit server, with
  * 32GB+ RAM
  * 8+ CPU cores
  * 200GB+ disk
* Access to the Internet
* Ubuntu 14.04 LTS freshly installed (see [TBF]() for instruction on how to
  install Ubuntu 14.04).
* User account used to install CORD-in-a-Box has password-less *sudo*
  capability (e.g., like the `ubuntu` user)

### Target Server on CloudLab (optional)

If you do not have a target server available that meets the above requirements,
you can borrow one on [CloudLab](https://www.cloudlab.us).  Sign up for an
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.*

Once your account is approved, start an experiment using the
`OnePC-Ubuntu14.04.5` profile on the Wisconsin, Clemson, or Utah clusters.
This will provide you with a temporary target server meeting the above
requirements.

Refer to the [CloudLab documentation](https://docs.cloudlab.us) for more
information.

## Download and Run the Script

On the target server, download the script that installs CORD-in-a-Box and run
it.  The script's output is displayed and also saved to `~/cord/install.out`:

```
curl -o ~/cord-in-a-box.sh https://raw.githubusercontent.com/opencord/cord/master/scripts/cord-in-a-box.sh
bash ~/cord-in-a-box.sh -t
```

**NOTE:** *If you are connecting to a remote target server, it is highly
recommended that you run the `cord-in-a-box.sh` script in a `tmux` session, or
use `mosh` to connect to the target rather than `ssh`.  Without one of these,
interrupted connectivity between your local machine and the remote server
may cause the CiaB install to hang.*

The script takes a *long time* (at least two hours) to run.  Be patient!  If it
hasn't completely failed yet, then assume all is well!

### Complete

The script builds the CORD-in-a-Box and runs a couple of tests to ensure that
things are working as expected.  Once it has finished running, you'll see a
**BUILD SUCCESSFUL** message.

The file `~/cord/install.out` contains the output of the build process,
post-bootstrap phase.

### Using cord-in-a-box.sh to download development code from Gerrit

There is an `-b` option to cord-in-a-box.sh that will checkout a specific
changeset from a gerrit repo during the run.  The syntax for this is `<project
path>:<changeset>/<revision>`.  It can be used multiple times - for example:

```
bash ~/cord-in-a-box.sh -b build/platform-install:1233/4 -b orchestration/service-profile:1234/2"
```

will check out the `platform-install` repo with changeset 1233, revision 4, and
`service-profile` repo changeset 1234, revision 2.

You can find the project path used by the `repo` tool in the [manifest/default.xml](https://gerrit.opencord.org/gitweb?p=manifest.git;a=blob;f=default.xml) file.

### Using cord-in-a-box.sh to run the CORD fabric

The `-f` option to cord-in-a-box.sh can be used to configure an ONOS
fabric for CORD-in-a-Box.  The fabric consists of two leaf and two
spine switches, each running a [CPqD OpenFlow software
switch](https://github.com/CPqD/ofsoftswitch13) controlled by ONOS.
The build process automatically generates a configuration file for the
fabric and pushes it to ONOS.  *THIS FEATURE IS EXPERIMENTAL AND STILL
UNDER DEVELOPMENT.*

## Inspecting CORD-in-a-Box

CORD-in-a-Box creates a virtual CORD POD running inside Vagrant VMs, using
libvirt as a backend.

As access to the libvirt socket depends on being in the `libvirtd` group, you
may need to to logout and back in to have your shell session gain this group
membership:

```
~$ groups
xos-PG0 root
~$ vagrant status
Call to virConnectOpen failed: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied
~$ logout
~$ ssh node_name.cloudlab.us
~$ groups
xos-PG0 root libvirtd
```

Once you have done this, you can inspect the status of the VM's by setting the
`VAGRANT_CWD` environmental variable to the path to the cord-in-a-box
`Vagrantfile`'s parent directory, then run `vagrant status`:

```
~$ export VAGRANT_CWD=~/cord/build/targets/cord-in-a-box
~$ vagrant status
Current machine states:

corddev                   running (libvirt)
prod                      running (libvirt)
switch                    not created (libvirt)
leaf-1                    running (libvirt)
leaf-2                    running (libvirt)
spine-1                   running (libvirt)
spine-2                   not created (libvirt)
testbox                   not created (libvirt)
compute-node-1            running (libvirt)
compute-node-2            not created (libvirt)
compute-node-3            not created (libvirt)

This environment represents multiple VMs. The VMs are all listed
above with their current state. For more information about a specific
VM, run `vagrant status NAME`.
```

### corddev VM

The `corddev` VM is a development machine used by the `cord-in-a-box.sh` script
to drive the installation.  It downloads and builds Docker containers and
publishes them to the virtual head node (see below). It then installs MaaS on
the virtual head node (for bare-metal provisioning) and the ONOS, XOS, and
OpenStack services in containers.  This VM can be entered as follows:

```
$ ssh corddev<commit_msg>Fix VAGRANT_CWD path<commit_after># CORD-in-a-Box Quick Start Guide

This tutorial 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"). 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.

**NOTE:** *This tutorial installs 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
[quickstart_physical.md](./quickstart_physical.md).  For more details about the
actual build process, look there.*

## What you need (Prerequisites)

You will need a *target server*, which will run both a development environment
in a Vagrant VM (used to deploy CORD) as well as CORD-in-a-Box itself.

Target server requirements:

* 64-bit server, with
  * 32GB+ RAM
  * 8+ CPU cores
  * 200GB+ disk
* Access to the Internet
* Ubuntu 14.04 LTS freshly installed (see [TBF]() for instruction on how to
  install Ubuntu 14.04).
* User account used to install CORD-in-a-Box has password-less *sudo*
  capability (e.g., like the `ubuntu` user)

### Target Server on CloudLab (optional)

If you do not have a target server available that meets the above requirements,
you can borrow one on [CloudLab](https://www.cloudlab.us).  Sign up for an
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.*

Once your account is approved, start an experiment using the
`OnePC-Ubuntu14.04.5` profile on the Wisconsin, Clemson, or Utah clusters.
This will provide you with a temporary target server meeting the above
requirements.

Refer to the [CloudLab documentation](https://docs.cloudlab.us) for more
information.

## Download and Run the Script

On the target server, download the script that installs CORD-in-a-Box and run
it.  The script's output is displayed and also saved to `~/cord/install.out`:

```
curl -o ~/cord-in-a-box.sh https://raw.githubusercontent.com/opencord/cord/master/scripts/cord-in-a-box.sh
bash ~/cord-in-a-box.sh -t
```

**NOTE:** *If you are connecting to a remote target server, it is highly
recommended that you run the `cord-in-a-box.sh` script in a `tmux` session, or
use `mosh` to connect to the target rather than `ssh`.  Without one of these,
interrupted connectivity between your local machine and the remote server
may cause the CiaB install to hang.*

The script takes a *long time* (at least two hours) to run.  Be patient!  If it
hasn't completely failed yet, then assume all is well!

### Complete

The script builds the CORD-in-a-Box and runs a couple of tests to ensure that
things are working as expected.  Once it has finished running, you'll see a
**BUILD SUCCESSFUL** message.

The file `~/cord/install.out` contains the output of the build process,
post-bootstrap phase.

### Using cord-in-a-box.sh to download development code from Gerrit

There is an `-b` option to cord-in-a-box.sh that will checkout a specific
changeset from a gerrit repo during the run.  The syntax for this is `<project
path>:<changeset>/<revision>`.  It can be used multiple times - for example:

```
bash ~/cord-in-a-box.sh -b build/platform-install:1233/4 -b orchestration/service-profile:1234/2"
```

will check out the `platform-install` repo with changeset 1233, revision 4, and
`service-profile` repo changeset 1234, revision 2.

You can find the project path used by the `repo` tool in the [manifest/default.xml](https://gerrit.opencord.org/gitweb?p=manifest.git;a=blob;f=default.xml) file.

### Using cord-in-a-box.sh to run the CORD fabric

The `-f` option to cord-in-a-box.sh can be used to configure an ONOS
fabric for CORD-in-a-Box.  The fabric consists of two leaf and two
spine switches, each running a [CPqD OpenFlow software
switch](https://github.com/CPqD/ofsoftswitch13) controlled by ONOS.
The build process automatically generates a configuration file for the
fabric and pushes it to ONOS.  *THIS FEATURE IS EXPERIMENTAL AND STILL
UNDER DEVELOPMENT.*

## Inspecting CORD-in-a-Box

CORD-in-a-Box creates a virtual CORD POD running inside Vagrant VMs, using
libvirt as a backend.

As access to the libvirt socket depends on being in the `libvirtd` group, you
may need to to logout and back in to have your shell session gain this group
membership:

```
~$ groups
xos-PG0 root
~$ vagrant status
Call to virConnectOpen failed: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied
~$ logout
~$ ssh node_name.cloudlab.us
~$ groups
xos-PG0 root libvirtd
```

Once you have done this, you can inspect the status of the VM's by setting the
`VAGRANT_CWD` environmental variable to the path to the cord-in-a-box
`Vagrantfile`'s parent directory, then run `vagrant status`:

```
~$ export VAGRANT_CWD=~/cord/build
~$ vagrant status
Current machine states:

corddev                   running (libvirt)
prod                      running (libvirt)
switch                    not created (libvirt)
leaf-1                    running (libvirt)
leaf-2                    running (libvirt)
spine-1                   running (libvirt)
spine-2                   not created (libvirt)
testbox                   not created (libvirt)
compute-node-1            running (libvirt)
compute-node-2            not created (libvirt)
compute-node-3            not created (libvirt)

This environment represents multiple VMs. The VMs are all listed
above with their current state. For more information about a specific
VM, run `vagrant status NAME`.
```

### corddev VM

The `corddev` VM is a development machine used by the `cord-in-a-box.sh` script
to drive the installation.  It downloads and builds Docker containers and
publishes them to the virtual head node (see below). It then installs MaaS on
the virtual head node (for bare-metal provisioning) and the ONOS, XOS, and
OpenStack services in containers.  This VM can be entered as follows:

```
$ ssh corddev
{'fraction_non_alphanumeric': 0.0796983127284037, 'fraction_numerical': 0.008086462950003887, 'mean_word_length': 3.725202057310801, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1502396', 'n_tokens_mistral': 3918, 'n_tokens_neox': 3694, 'n_words': 1747}