A RESTCONF server for sysrepo

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 either only "read" access operation or only "exec" operation on ietf-subscribed-notifications:establish-subscription RPC.
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

SSE proxy for configured subscriptions

If the configured-subscriptions-sse-proxy YANG feature is enabled, then configured subscriptions are available via the /streams/rousette:sse-proxy/ HTTP endpoint. This is an extension of the RESTCONF protocol. If an appropriate notification receiver is configured with the rousette:sse-proxy transport, then all notification events created by the referring configured subscription will be transformed to HTTP-level SSE events and passed to HTTP clients. The notification events themselves are subject to NACM access control as configured for the internal subscription between a datastore and the SSE proxy. Furthermore, only clients which are granted read access to the /sn:subscriptions/snr:receiver-instances/snr:receiver-instance/snr:transport-type/rousette:sse-proxy/nacm-access-check are allowed to connect to the SSE endpoint. The NACM user of the internal subscription and the NACM access check to the SSE endpoint are independent on each other.

In YANG push, the data nodes which might become visible over this SSE channel also depend on a subscription filter. With default YANG-push ACLs, setting the filter for configured subscribed notifications is an unprivileged operation. This has security implications. When using the SSE proxy, do not rely on subscription filters as a security mechanism. Instead, use the rousette:sse-proxy/nacm-username to force the internal subscription to use an unprivileged user who does not have access to sensitive data.

Dependencies

• nghttp2-asio - asynchronous C++ library for HTTP/2
  • we strongly recommend using our fork which appears to be better maintained, and which contains important bugfixes which have not been merged upstream yet
• 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.