RESTCONF¶

Clixon can use different Restconf modules:

Architecture¶

                                     +---------------------------------+
                                     |        clixon options           |
                                     +---------------------------------+
                                         |- XML                   |- XML
                       FCGI              v                        v
       (1)  +-------+    |    +----------+--------+  Netconf +----------+
User  <-->  | nginx |  <--->  | restconf | plugin |    |     | backend  |
            +-------+         | daemon   |--------+  <--->   | daemon   |
User  <-------------------->  |          | plugin |          |          |
       (2)                    +----------+--------+          +----------+

The restconf deamon provides a http/https RESTCONF interface to the Clixon backend. It comes in two variants, as shown by the two variants in the figure above:

A reverse proxy (such as NGINX) and FCGI

Native http using libevhtp

The restconf daemon communicates with the backend using internal netconf over the CLIXON_SOCK. If FCGI is used, there is also a FCGI socket specified by CLICON_RESTCONF_PATH.

As other Clixon daemons and clients, the daemon reads its config options from the configuration file on startup.

You can add plugins to the restconf daemon, where the primary usecase is authentication, using the ca_auth callback.

Configuration¶

The RESTCONF daemon can be configured (by autotools) as follows:

`--without-restconf`
	No RESTCONF
`--with-restconf=fcgi`
	RESTCONF using fcgi/ reverse proxy. This is default.
`--with-restconf=evhtp`
	RESTCONF using native http with libevhtp
`--with-wwwuser=<user>`
	Set www user different from www-data

The restconf daemon can be started as root, but in that case drops privileges to wwwuser.

Config options¶

The configuration file options related to RESTCONF are as follows:

CLICON_RESTCONF_DIR: Location of restconf .so plugins. Load all .so plugins in this dir as restconf code plugins.
CLICON_RESTCONF_PATH: FCGI unix socket. Should be specified in webserver (only fcgi)
CLICON_RESTCONF_PRETTY: RESTCONF return value is pretty-printed or not
CLICON_RESTCONF_ADDRESS: RESTCONF default address to bind to, default is ipv4:0.0.0.0. (only evhtp)
CLICON_SSL_SERVER_CERT: SSL server cert for restconf https (only evhtp)
CLICON_SSL_SERVER_CERT: SSL server cert for restconf https (only evhtp)
CLICON_SSL_SERVER_KEY: SSL server private key for restconf https (only evhtp)
CLICON_SSL_CA_CERT: SSL CA cert for client authentication (only evhtp)
CLICON_STREAM_DISCOVERY_RFC8040: Enable monitoring information for the RESTCONF protocol from RFC 804 (only fcgi)
CLICON_STREAM_PATH: Stream path appended to CLICON_STREAM_URL to form stream subscription URL (only fcgi)

Plugin callbacks¶

Restconf plugins implement callbacks, some are same as for backend plugins. Most important is the auth callback where user authentication can be implemented.

init: Clixon plugin init function, called immediately after plugin is loaded into the restconf daemon.
start: Called when application is started and initialization is complete, and after drop privileges.
exit: Called just before plugin is unloaded
extension: Called at parsing of yang modules containing an extension statement.
auth: Called by restconf on each incoming request to check credentials and return username. This is done after cert validation, if any. For example, http basic authentication, oauth2 or just matching client certs with username can be implemented here.

NGINX¶

If you use FCGI, you need to configure a reverse-proxy, such as NGINX. A typical configuration is as follows:

server {
  ...
  location / {
    fastcgi_pass unix:/www-data/fastcgi_restconf.sock;
    include fastcgi_params;
  }
}

where fastcgi_pass setting must match CLICON_RESTCONF_PATH.

SSL Certificates¶

If you use native RESTCONF you may want to have server/client certs. If you use FCGI, certs are configured according to the reverse proxy documentation, such as NGINX. The rest of this section applies to native restconf only.

If you already have certified server certs, ensure CLICON_SSL_SERVER_CERT and CLICON_SSL_SERVER_KEY points to them.

If you do not have them, you can generate self-signed certs, for example as follows:

openssl req -x509 -nodes -newkey rsa:4096 -keyout /etc/ssl/private/clixon-server-key.pem -out /etc/ssl/certs/clixon-server-crt.pem -days 365

You can also generate client certs (not shown here) using CLICON_SSL_CA_CERT. Example using client certs and curl for client andy:

curl -Ssik --key andy.key --cert andy.crt -X GET https://localhost/restconf/data/example:x

RESTCONF streams¶

Clixon has an experimental RESTCONF event stream implementations following RFC8040 Section 6 using Server-Sent Events (SSE). Currently this is implemented in FCGI/Nginx only (not evhtp).

Note

RESTCONF streams are experimental and only implemented for FCGI.

Example: set the Clixon configuration options:

<CLICON_STREAM_PATH>streams</CLICON_STREAM_PATH>
<CLICON_STREAM_URL>https://example.com</CLICON_STREAM_URL>
<CLICON_STREAM_RETENTION>3600</CLICON_STREAM_RETENTION>

In this example, the stream example is accessed with https://example.com/streams/example.

Clixon defines an internal in-memory (not persistent) replay function controlled by the configure option above. In this example, the retention is configured to 1 hour, i.e., the stream replay function will only save timeseries one hour, but if the restconf daemon is restarted, the hisstory will be lost.

In the Nginx configuration, add the following to extend the nginx configuration file with the following statements (for example):

location /streams {
    fastcgi_pass unix:/www-data/fastcgi_restconf.sock;
    include fastcgi_params;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

An example of a stream access is as follows:

curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE
data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>2018-11-04T14:47:11.373124</eventTime><event><event-class>fault</event-class><reportingEntity><card>Ethernet0</card></reportingEntity><severity>major</severity></event></notification>
data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>2018-11-04T14:47:16.375265</eventTime><event><event-class>fault</event-class><reportingEntity><card>Ethernet0</card></reportingEntity><severity>major</severity></event></notification>

You can also specify start and stop time. Start-time enables replay of existing samples, while stop-time is used both for replay, but also for stopping a stream at some future time:

curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE?start-time=2014-10-25T10:02:00&stop-time=2014-10-25T12:31:00