digggy / orc

A RESTCONF implementation for OpenWrt Systems (OpenWrt RESTCONF) with support for operations.

OpenWrt RESTCONF

This is a prototype implementation of RESTCONF for the OpenWrt system that utilizes the UCI configuration files as a datastore. The implementation also extends support to run operations.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Building
3. Testing
4. Usage
5. Roadmap
6. Contributing
7. License
8. Contact

About The Project

The efficient automation of operations in heterogeneous network devices from different vendors is a great challenge. OpenWrt an open-source embedded operating system has become a popular firmware choice replacing proprietary firmware on networking devices, whether home routers or enterprise networks.

RESTCONF is a network management protocol that offers a programmatic interface for accessing state and configuration data, RPC operations, and event notifications on a networking device. Although OpenWrt pro- vides ways to run common network-related operations via the web user interface and the command-line interface, it still lacks an efficient implementation of RESTCONF that allows for efficient automated operation tasks across devices. Contemplating this pos- sibility, OpenWrt RESTCONF (ORC) was extended to support operations.

Getting Started

The steps to setup the development environment can be quite hectic. The following resources can help in development environment setup.

OpenWrt/LEDE Quick Start

UCI setup outside OpenWrt

Architecture

Prerequisites

1. Python 3 for the YANG conversion script
2. Tool for converting YANG to YIN

Adding YANG modules

To add YANG modules for OpenWrt they have to go through some pre-processing. This is what the ./yin2json/yin2json.py script does.

Annotations

Before YANG modules can be used with this implementation they have to be annotated with the extensions provided in /yang/openwrt-uci-extension.yang. An example of an annotated module is /yang/restconf-example.yang

Script

1. Convert the YANG modules to be included to YIN and put them in one folder, i.e. /yin. For example with pyang

   pyang -f yin ./yang/restconf-example.yang -p ./yang -o ./yin/restconf-example.yin 

2. Run the yin2json.py script

   python3 ./yin2json/yin2json.py -y ./yin -o ./generated-for-openwrt ./yin/restconf-example.yin ...

   This converts the YIN files and generates a .h file in ./generated-for-openwrt that has to be included in /src/generated/yang.h

   A script file yang2json.sh is also provided for automation of conversion directly from yang to the yang.h header file.

Building

1. Clone this repository
2. cd docker
3. docker build -t digggy/orc-sdk:1.0 .
4. cd ..
5. docker run -v $(pwd):/restconf digggy/openwrt-build
6. The generated .ipk will be in the build folder

Testing

The tests are inside the /test directory and are based on the Python Tavern Testing Framework. After installing the framework the tests can be run using either of the following commands:

tavern-ci ./test/test_restconf.tavern.yml
# or
py.test ./test/test_restconf.tavern.yml

This will run integration tests that check the actual implementation. The url where the server is located can be changed in /test/common.yaml.

Usage

The .ipk file can be installed in the Openwrt system to utlize the features of restconf for the Openwrt devices.

For more examples, please refer to the Documentation

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the BSD-3 License. See LICENSE for more information.

Contact

Your Name - @_dkunwar - [e-mail]

Project Link: https://github.com/digggy/orc