RESTCONF on OpenWRT
This text is an initial input to a discussion about possible motivations, deployment modes and problems of using RESTCONF for configuring and managing OpenWRT routers.
RESTCONF is a configuration and management protocol that is based on similar principles as its NETCONF predecessor but uses HTTP methods for client-server communication rather than a special RPC message layer. RESTCONF also permits several alternative data encodings/media types (XML, JSON, CBOR), whereas NETCONF is only limited to XML.
YANG is a data modelling language that is usable with both RESTCONF and NETCONF.
The canonical way of configuring OpenWRT routers is through the
Unified Configuration Interface (UCI). Its main aim of UCI is to keep
all user-accessible configuration files in a central location
/etc/config) and unify their format. Users are supposed to modify
these configuration files either in a text editor or by using the
command-line utility. The UCI system than transparently translates
these configuration files into “native” configuration files of a
From the perspective of a non-geek user, UCI is certainly an improvement over a traditional Unix/Linux systems where configuration files have daemon- or service-specific locations and a use a host of different formats. Nevertheless, every serious OpenWRT user will sooner or later run into the following problems and limitations (which are, in fact, correlated):
The flat format of UCI configuration files isn't suitable for expressing even moderately complex logic and relationships. Therefore, many services offer hooks that allow for augmenting UCI data with extra configuration in the native format. This means that the user needs to learn both UCI and native configuration.
The translation of UCI to native formats is only one-way: if the native files are directly modified, then UCI gets out of sync and may later overwrite new data with the old configuration.
Configuration errors are reported to the remote management application in a form that is not (easily) machine readable, or not reported at all.
Acquisition of run-time date from the device involves error-prone screen scraping.
Use Cases for RESTCONF
Motivation for managing OpenWRT routers via RESTCONF is essentially the same as on any other platform:
Effective and reliable remote management: operations are performed as RPCs, and returned output or error messages are in a machine-readable form.
Possibility of receiving asynchronous notifications with fine-grained subscription options.
Use of standard data models that are being developed in IETF and other SDOs (IEEE, Broadband Forum). This is especially useful in non-homogeneous networks, provided that all devices support RESTCONF and implement the same data models.
A number of YANG modules that already are (or will soon be) published as RFCs may be potentially useful for OpenWRT routers. A non-exhaustive selection can be found in the Appendix.
Three main deployment options may be considered (combinations are possible, too):
Translate RESTCONF data to UCI configurations, and then use the UCI system essentially unchanged.
Replace the UCI layer with RESTCONF, and then use RESTCONF data in a similar fashion as UCI data are currently being used, i.e. generate specific daemon or service configuration from them. The configuration datastore can be implemented as flat files of using a database.
Use a system like Sysrepo for improving back-end integration of daemons and services.
The first option is relatively light-weight in that it doesn't change anything in OpenWRT itself, just adds an extra configuration layer. It could be used only for configuration as there is in general no easy way for translating state data emitted by daemons into the format that's expected by standard models. On the other hand, the extra layer added by option #1 (closed) increases the complexity of the whole system and, since the flow of data is still only in one direction, it just amplifies the problems of UCI mentioned above. For example, if an admin directly edits a generated UCI file, this change won't be reflected in RESTCONF configuration. Whilst the conversion of RESTCONF to UCI is most likely doable, the reverse conversion and synchronization of both configuration sources seems next to impossible.
Option #2 (closed) essentially means substituting UCI with RESTCONF data. The pros and cons of this approach are similar to those of the UCI system.
Option #3 (closed) is the most sophisticated approach but certainly not a low-hanging fruit because it not only involves development of new software components but also requires that all participating daemons and services be modified to use the Sysrepo (or similar) API.
Available RESTCONF Implementations
At the time of writing, the following two open-source implementations of the RESTCONF server are known:
JetConf is a Python 3 implementation that provides several extensions of the RESTCONF protocol (support for user-specific candidate datastores, transactions and detailed access control).
It is currently difficult to decide which of the three approaches described in Deployment Options is the most promising. Option #1 (closed) is easiest to implement but is would also require tight administrative policies (write access has to be restricted to the RESTCONF API, i.e. no manual editing of UCI files can be permitted).
Options #2 (closed) and #3 (closed) not only mean significantly more development work but, arguably, they would lead to something that cannot be called OpenWRT anymore given that the UCI system is regarded as OpenWRT's flagship.
Regarding RESTCONF clients (remote management programs), two variants are worth considering:
A graphical client (e.g. client-side web application) with user interface tailored to the needs of SOHO router configuration and management. The client will use the RESTCONF API for sending requests and receiving data.
A domain-specific language that allows for creating configuration scripts, defining responses to asynchronous events etc.
The former option would be a user-friendly interface intended for remote management of a single router (or few, at most) while the latter would be more suitable for operators of large networks, and require deeper technical expertise.
It is also worth noting that neither of the open-source RESTCONF servers mentioned above is suitable for low-end OpenWRT routers with constrained resources (RAM) as long as they cannot run Python or Java interpreters. This is not an issue for the Turris platform though.
Appendix: Standard YANG Modules
ietf-yang-types – common data types such as
dotted-quad, integer parameters with special semantics (counters, gauges).
ietf-inet-types – data types related to TCP/IP (addresses, ports) and other Internet-related parameters.
ietf-interfaces – interface management (all layers).
ietf-ip – static configuration and management of IPv4/IPv6 on L3 interfaces.
ietf-routing – basic configuration and management of the routing subsystem, static routes (for both IPv4 and IPv6).
ietf-access-control-list – access control lists, packet filters.
ietf-dhcp – DHCP.
ietf-logical-network-element – management of virtual machines and NFV.
ietf-rip – RIP routing protocol.
ietf-ospf – OSPF routing protocol.
ietf-isis – IS-IS routing protocol.
ietf-snmp – SNMP monitoring.