Improve documentation

README.md

@@ -1,4 +1,49 @@
-# rose-srv6-control-plane
+# ROSE SRv6 Control Plane
+> Control plane functionalities for SDN.
+
+![Python package](https://github.com/netgroup/rose-srv6-control-plane/workflows/Python%20package/badge.svg)
+![Python Lint Code Base](https://github.com/netgroup/rose-srv6-control-plane/workflows/Lint%20Code%20Base/badge.svg)
+![GitHub](https://img.shields.io/github/license/netgroup/rose-srv6-control-plane)
+
+## Table of Contents
+* [Getting Started](#getting-started)
+* [Docker](#docker)
+    * [Build the Docker image](build-the-docker-image)
+    * [Run the controller container](#run-the-controller-container)
+    * [Run the node-manager container](#run-the-node-manager-container)
+    * [Access to the Docker container](#access-to-the-docker-container)
+* [Database utilities](#database-utilities)
+* [Control plane functionalities](#control-plane-functionalities)
+    * [Node manager](#node-manager)
+    * [Controller](#controller)
+    * [Protocol Buffers](#protocol-buffers)
+    * [Usage examples](#usage-examples)
+        * [How to use the Controller CLI](#how-to-use-the-controller-cli)
+        * [How to use the Controller API in your Python application](#how-to-use-the-controller-api-in-your-python-application)
+* [Requirements](#requirements)
+* [Links](#links)
+* [Issues](#issues)
+* [Contributing](#contributing)
+* [License](#license)
+
+
+## Getting Started
+
+This project provides a collection of modules implementing different control plane functionalities of a Software Defined Network (SDN).
+
+First, you need to clone this repository.
+
+```console
+$ git clone https://github.com/netgroup/rose-srv6-control-plane
+```
+
+The project is structured as follows:
+
+    .
+    ├── db_update           # Database utilities
+    ├── control_plane       # Modules implementing control plane functionalities
+    └── README.md
+
 
 ## Docker
 
@@ -30,3 +75,76 @@ Currently the exposed port is 12345
 for instance access to rose-srv6-controller with:
 
     docker exec -it rose-srv6-node-manager bash
+
+
+## Database utilities
+The *db_update* folder contains several modules used by the Controller to interact with an ArangoDB database.
+
+
+## Control plane functionalities
+
+The Controller uses a gRPC API to contact the Linux nodes. A gRPC server (Node Manager) must be run on the Linux nodes that you want to control through the Controller.
+
+The Controller interacts with the gRPC server executed on the nodes to enforce rules and commands, such as the setup of SRv6 paths and behaviors.
+
+The control-plane modules are organized as follows:
+
+    .
+    ├── ...
+    ├── control_plane     # Control plane modules
+    |   ├── controller      # Controller (gRPC client)
+    |   ├── examples        # Usage examples
+    |   ├── node-manager    # Node Manager (gRPC server)
+    |   └── protos          # Protocol buffer files
+    └── ...
+
+
+## Node manager
+
+The **control_plane/node-manager** package implements the functionalities of a gRPC server.
+A gRPC server must be executed on each node that you want to control from the Controller.
+
+For more information about the installation and usage of the Node Manager follow the instructions contained in the *README.md* file under the *node-manager* folder.
+
+
+## Controller
+The **control_plane/controller** package provides a collection of modules implmenting different functionalities of a Controller.
+
+For more information about the installation and usage of the Node Manager follow the instructions contained in the *README.md* file under the *controller* folder.
+
+
+## Protocol Buffers
+This project depends on the **grpcio** library that provides an implementation of the gRPC protocol. gRPC services use Protocol Buffers as Interface Description Language (IDL). Consequently, both the Controller and the Node Manager require some Python classes generated from the .proto files stored in the **control_plane/protos** folder.
+Since the compilation and generation of the Python classes from the .proto files has been automated in the setup scripts, the manual generation of this classes is no longer required.
+
+
+## Usage examples
+There are two ways to use the functionalities offered by the Controller. You can execute the Python Command-Line Interface (CLI) provided by the Controller or you can import the Controller modules in your Python modules and use the API exposed by the Controller.
+
+### How to use the Controller CLI
+A description of the CLI and the supported commands is provided in the documentation contained in [control_plane/controller](control_plane/controller/README.md).
+
+### How to use the Controller API in your Python application
+The **control_plane/examples** directory contains several usage examples for the API exposed by the Controller. For the description of the API and the examples, check the documentation contained in the [control_plane/examples folder](control_plane/examples/README.md).
+
+
+## Requirements
+Python >= 3.6
+
+
+## Links
+* Research on Open SRv6 Ecosystem (ROSE): https://netgroup.github.io/rose/
+* Source code: https://github.com/netgroup/rose-srv6-control-plane
+* Report a bug: https://github.com/netgroup/rose-srv6-control-plane/issues
+
+
+## Issues
+You are welcome to open github issues for bug reports and feature requests, in [this repository](https://github.com/netgroup/rose-srv6-control-plane/issues) or in the [ROSE repository](https://github.com/netgroup/rose/issues).
+
+
+## Contributing
+If you want to contribute to the ecosystem, provide feedback or get in touch with us, see our contact page: https://netgroup.github.io/rose/rose-contacts.html.
+
+
+## License
+This project is licensed under the [Apache License, Version 2.0](https://github.com/netgroup/rose-srv6-control-plane/blob/master/LICENSE).

control_plane/README.md

@@ -1,3 +1,3 @@
-# SRv6 tutorial controller
+# ROSE SRv6 Control Plane
 
 This project provides a collection of modules implementing different functionalities of a SRv6-SDN controller

control_plane/controller/README.md

@@ -0,0 +1,113 @@
+# Controller
+
+## Prerequisites
+
+The following dependencies are necessary:
+
+* Python 3.6 or above
+
+## Installation
+
+1. Create a Python 3 virtual environment for the controller:
+    ```console
+    $ python3 -m venv ~/.envs/controller-venv
+    ```
+1. Activate the virtual environment:
+    ```console
+    $ source ~/.envs/controller-venv/bin/activate
+    ```
+1. Clone the *rose-srv6-control-plane* repository using ```git```:
+    ```console
+    $ git clone https://github.com/netgroup/rose-srv6-control-plane.git
+    ```
+1. Then, ```cd``` to the *control_plane/controller* directory under the *rose-srv6-control-plane* folder and run the install command:
+    ```console
+    $ cd rose-srv6-control-plane/control_plane/controller
+    $ python setup.py install
+    ```
+1. This project depends on the gRPC protocol, which requires protobuf modules. ```cd``` to the *control_plane/protos* directory under the *rose-srv6-control-plane* folder and run the setup command to build and install the proto files:
+    ```console
+    $ cd rose-srv6-control-plane/control_plane/protos
+    $ python setup.py install
+    ```
+
+## Configuration
+
+* The controller comes with a default configuration. If you want to override the default settings, you can create a *.env* file containing the configuration parameters:
+    ```sh
+    export GRPC_SECURE=True
+    export GRPC_CA_CERTIFICATE_PATH=/tmp/ca.crt
+    export DEBUG=True
+    ```
+    * *GRPC_SECURE*: define whether to enable the gRPC secure mode or not
+    * *GRPC_CA_CERTIFICATE_PATH*: path to the certificate of the CA, required by gRPC secure mode
+    * *DEBUG*: enable debug logs
+* To enable the optional features, you need to set the following parameters in your *.env* file:
+    * ArangoDB integration:
+        ```sh
+        export ENABLE_ARANGO_INTEGRATION=True
+        export ARANGO_URL=http://localhost:8082
+        export ARANGO_USER=root
+        export ARANGO_PASSWORD=12345678
+        ```
+        Note: the *db_update* library is required to support ArangoDB integration. Follow the instructions provided in section [Optional requirements](#optional-requirements) to setup the required dependencies.
+    * Kafka integration:
+        ```sh
+        export ENABLE_KAFKA_INTEGRATION=True
+        export KAFKA_SERVERS=kafka:9092
+        ```
+        Note: the *kafka-python* package is required to support ArangoDB integration. Follow the instructions provided in section [Optional requirements](#optional-requirements) to setup the required dependencies.
+    * gRPC server on the controller (interface node->controller):
+        ```sh
+        export ENABLE_GRPC_SERVER=True
+        export GRPC_SERVER_IP=::
+        export GRPC_SERVER_PORT=12345
+        export GRPC_SERVER_SECURE=True
+        export GRPC_SERVER_CERTIFICATE_PATH=/tmp/server.crt
+        export GRPC_SERVER_KEY_PATH=/tmp/server.key
+        ```
+The *config* folder in the controller directory contains a sample configuration file.
+
+## Optional requirements
+
+* Database utilities are required for the ArangoDB integration features. You need to activate the controller virtual environment and install the *db_update* package contained in the *rose-srv6-control-plane* repository if you want to use these features:
+    ```console
+    $ source ~/.envs/controller-venv/bin/activate
+    $ cd rose-srv6-control-plane/db_update
+    $ python setup.py install
+    ```
+* Exporting the network topology as an image file requires *graphviz* and *libgraphviz-dev*:
+    ```console
+    $ apt-get install graphviz libgraphviz-dev
+    ```
+* *kafka-python* is required for Kafka integration. Activate the controller virtual environment and run the install command:
+    ```console
+    $ source ~/.envs/controller-venv/bin/activate
+    $ pip install kafka-python
+    ```
+
+## Starting the Controller CLI
+
+1. Activate the controller virtual environment:
+    ```console
+    $ source ~/.envs/controller-venv/bin/activate
+    ```
+1. To start the Controller CLI:
+    ```console
+    $ controller --env-file .env
+    ```
+    ```console
+    $ controller --help
+    usage: controller [-h] [-e ENV_FILE]
+
+    Controller CLI
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    -e ENV_FILE, --env-file ENV_FILE
+                            Path to the .env file containing the parameters for the controller
+    ```
+1. Show the usage of the CLI:
+    ```console
+    controller> help
+    ```

control_plane/controller/controller/cli/README.md

@@ -0,0 +1,4 @@
+**Command-Line Reference**
+----
+
+The Command-Line Interface documentation is available under the [folder *docs*](docs/cli.md)

control_plane/controller/controller/cli/docs/cli.md

@@ -0,0 +1,46 @@
+**Command-Line Reference**
+----
+
+This folder contains the documentation of the Command-Line Interface (CLI) for the Controller.
+
+The CLI can be started with the default configuration by typing the command **controller** in the Python environment where you installed it:
+```console
+$ controller
+```
+
+Optionally, you can pass a configuration file containing your settings:
+```console
+$ controller --env-file config/controller.env
+```
+
+The Controller CLI will start and load the configuration:
+```console
+INFO:controller.cli.cli:*** Loading configuration from /home/rose/.envs/controller-venv/lib/python3.8/site-packages/rose_srv6_control_plane_controller-0.0.1-py3.8.egg/controller/cli/../config/controller.env
+INFO:root:SERVER_DEBUG: False
+INFO:controller.cli.cli:*** Validating configuration
+
+****************** CONFIGURATION ******************
+
+ArangoDB URL: http://localhost:8529
+ArangoDB username: root
+ArangoDB password: ************
+Kafka servers: kafka:9092
+Enable debug: False
+
+***************************************************
+
+
+Welcome! Type ? to list commands
+controller> 
+```
+
+Now the CLI is ready to receive commands. For a list of the available commands, you can check the documentation in this folder or type the **help** command:
+```
+controller> help
+```
+
+* Description of the interactive CLI : ```help```
+* Exit from the CLI : ```exit```
+* [SRv6 functions](docs/srv6.md) : ```help```
+* [SRv6 Performance Measurement functions](docs/srv6pm.md) : ```help```
+* [Topology utilities](docs/topology.md) : ```topology```