An almost-RESTCONF server

This is a RESTCONF server built on top of sysrepo.

Features

• Full RESTCONF server
  • XML and JSON encoding
  • YANG module library
  • Data retrieval and edits
  • RPC/action execution
  • YANG schema retrieval
  • explicit default handling
  • NETCONF notification streams
  • Those features are currently not implemented:
    • TLS termination (use a reverse proxy for that)
    • TLS certificate authentication (see Access control model below)
    • the Last-Modified and ETag headers for edit collision prevention in the datastore resource
    • the Last-Modified and ETag headers in the data resource
• NMDA datastore access
  • no with-operational-default capability
  • no with-origin capability
• YANG Patch support for fine-grained edits, using both JSON and XML encodings
• NACM access control, with extensions for anonymous reads

Usage

Since this service only talks cleartext HTTP/2, it's recommended to run it behind a reverse proxy. Here's an example with nghttp2-apps:

nghttpx --accesslog-syslog --add-forwarded=for -f '*,80;no-tls' \
    -b '::1,10080;/restconf/:/yang/:/streams/:/.well-known/;proto=h2' \
    -b '::1,81;;proto=h2' # for serving static files

For debugging without a reverse proxy, use e.g. curl --http2-prior-knowledge.

Required YANG models

Rousette requires the following YANG models to be present in sysrepo:

• ietf-yang-library@2019-01-04 (installed by sysrepo)
• ietf-netconf (installed by sysrepo)
• ietf-restconf@2017-01-26
• ietf-restconf-monitoring@2017-01-26
• ietf-yang-patch@2017-02-22

Access control model

Rousette implements RFC 8341 (NACM). The access rights for users (and groups) are configurable via ietf-netconf-acm YANG model.

The reverse proxy must pass the authorization header as-is and delegate authentication/authorization to the RESTCONF server. The server currently supports two authentication/authorization methods:

• a systemwide PAM setup through the Basic HTTP authentication,
• a special anonymous access.

When the request does not contain the authorization header, and anonymous access is enabled (see below), the server will perform extra safety checks. When certain conditions are met, the anonymous access will be mapped to a NACM account named in the ANONYMOUS_USER CMake option and the ANONYMOUS_USER_GROUP group. There must be some specific access rights set up in ietf-netconf-acm model (these are currently very opinionated for our use-case):

1. The first entry of rule-list list must be configured for ANONYMOUS_USER_GROUP.
2. All the rules except the last one in this rule-list entry must enable only "read" access operation.
3. The last rule in the first rule-set must be a wildcard rule that disables all operations over all modules.

The anonymous user access is disabled whenever these rules are not met.

YANG schema retrieval

As an extension to the RESTCONF protocol, all YANG modules which are available through sysrepo can be fetched via the /yang/ endpoint. This access is controlled through NACM as-if the access was made against the location leaf-list within the ietf-yang-library. In practical terms, this means that the NACM access rules for the following XPaths also control schema retrieval:

• /ietf-yang-library:yang-library/module-set[name='complete']/module/location
• /ietf-yang-library:yang-library/module-set[name='complete']/import-only-module/location
• /ietf-yang-library:yang-library/module-set[name='complete']/module/submodule/location
• /ietf-yang-library:yang-library/module-set[name='complete']/import-only-module/submodule/location

Dependencies

• nghttp2-asio - asynchronous C++ library for HTTP/2
• sysrepo-cpp - object-oriented bindings of the sysrepo library
• libyang-cpp - C++ bindings for libyang
• PAM - for authentication
• spdlog - Very fast, header-only/compiled, C++ logging library
• docopt-cpp - command-line argument parser
• Boost's system and thread
• C++20 compiler (e.g., GCC 10.x+, clang 10+)
• CMake 3.19+
• optionally systemd - the shared library for logging to sd-journal
• optionally for built-in tests, Doctest as a C++ unit test framework
• optionally for built-in tests, trompeloeil for mock objects in C++
• optionally for built-in tests, pam_matrix and pam_wrapper for PAM mocking

Building

The standard way of building rousette looks like this:

mkdir build
cd build
cmake ..
make
make install

Contributing

The development is being done on Gerrit here. Instructions on how to submit patches can be found here. GitHub Pull Requests are not used.