diff --git a/README.md b/README.md index c06986ad..85eae788 100644 --- a/README.md +++ b/README.md @@ -133,16 +133,18 @@ Clixon does not yet support the following netconf features: Restconf ======== -Clixon restconf is a daemon based on FASTCGI. Instructions are available to +Clixon Restconf is a daemon based on FastCGI C-API. Instructions are available to run with NGINX. The implementatation is based on [RFC 8040: RESTCONF Protocol](https://tools.ietf.org/html/rfc8040). + The following features are supported: - OPTIONS, HEAD, GET, POST, PUT, DELETE -- stream notifications +- stream notifications (RFC8040 sec 6) +- query parameters start-time and stop-time(RFC8040 section 4.9) -The following are not implemented +The following features are not implemented: - PATCH -- query parameters (section 4.9) +- query parameters other than start/stop-time. See [more detailed instructions](apps/restconf/README.md). diff --git a/apps/restconf/README.md b/apps/restconf/README.md index 2bf8c224..4db81e72 100644 --- a/apps/restconf/README.md +++ b/apps/restconf/README.md @@ -1,6 +1,13 @@ # Clixon Restconf -### Installation using Nginx + * [Installation](#Installation) + * [Streams](Streams) + * [Nchan Streams](Nchan) + * [Debugging](Debugging) + +### 1. Installation + +The examples are based on Nginx. Other reverse proxies should work but are not verified. Ensure www-data is member of the CLICON_SOCK_GROUP (default clicon). If not, add it: ``` @@ -69,28 +76,31 @@ olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces/interface/name=et curl -sX POST -d '{"interfaces":{"interface":{"name":"eth1","type":"eth","enabled":"true"}}}' http://localhost/restconf/data ``` -### Event streams +### 2. Streams Clixon have two experimental restconf event stream implementations following RFC8040 Section 6 using SSE. One native and one using Nginx -nchan. The two variants to subscribe to the stream is described in the +nchan. The Nchan alternaitve is described in the next section. -The example [../../example/README.md] creates and EXAMPLE stream. +The (example)[../../example/README.md] creates an EXAMPLE stream. -Set the Clixon configuration options if they differ from default values - if they are OK you do not need to modify them: +Set the Clixon configuration options: ``` streams https://example.com -http://localhost/pub +3600 ``` -where -- https://example.com/streams is the public fronting subscription base URL. A specific stream NAME can be accessed as https://example.com/streams/NAME -- http://localhost/pub is the local internal base publish stream. +In this example, the stream EXAMPLE would be accessed with `https://example.com/streams/EXAMPLE`. -You access the streams using curl, but they differ slightly in behaviour as described in the following two sections. +The retention is configured as 1 hour, i.e., the stream replay function will only save timeseries one other. -Add the following to extend the nginx configuration file with the following statements: +Clixon defines an internal in-memory (not persistent) replay function +controlled by the configure option above. + +You may access a restconf streams using curl. + +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; @@ -100,26 +110,36 @@ Add the following to extend the nginx configuration file with the following stat } ``` -You access a native stream as follos: +AN example of a stream access is as follows: ``` - curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE - curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE?start-time=2014-10-25T10%3A02%3A00Z&stop-time=2014-10-25T12%3A31%3A00Z +vandal> curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE +data: 2018-11-04T14:47:11.373124faultEthernet0major + +data: 2018-11-04T14:47:16.375265faultEthernet0major ``` -where the first command retrieves only new notifications, and the second receives a range of messages. -### Nginx Nchan streams +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 +``` -As an alternative, Nginx/Nchan can be used for streams. +See (stream tests)[../test/test_streams.sh] for more examples. + +### 3. Nchan + +As an alternative streams implementation, Nginx/Nchan can be used. Nginx uses pub/sub channels and can be configured in a variety of ways. The following uses a simple variant with one generic subscription -channel (streams) and one publication channel (pub). +channel (streams) and one publication channel (pub). -Configure clixon with `--enable-publish` which enables curl code for publishing streams to nchan. -Set configure option CLICON_STREAM_PUB to, for example, http://localhost/pub to enable pushing notifications to nchan. +The advantage with Nchan is the large eco-system of + +Native mode and Nchan mode can co-exist? +Nchan mode does not use Clixon retention, Download and install nchan, see (https://nchan.io/#install). -Add the following to extend the nginx configuration file with the following statements: +Add the following to extend the Nginx configuration file with the following statements (example): ``` location ~ /streams/(\w+)$ { nchan_subscriber; @@ -131,6 +151,15 @@ Add the following to extend the nginx configuration file with the following stat } ``` +Configure clixon with `--enable-publish` which enables curl code for +publishing streams to nchan. + +You also need to configure CLICON_STREAM_PUB to enable pushing notifications to Nginx/Nchan. Example: +``` +http://localhost/pub +``` +Clicon will then publish events from stream EXAMPLE to `http://localhost/pub/EXAMPLE + Access the event stream EXAMPLE using curl: ``` curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE @@ -140,7 +169,7 @@ where the first command retrieves the whole stream history, and the second only See (https://nchan.io/#eventsource) on more info on how to access an SSE sub endpoint. -### Debugging +### 4. Debugging Start the restconf fastcgi program with debug flag: ``` diff --git a/apps/restconf/restconf_main.c b/apps/restconf/restconf_main.c index 9ee20fd4..ed7fdc43 100644 --- a/apps/restconf/restconf_main.c +++ b/apps/restconf/restconf_main.c @@ -662,7 +662,6 @@ main(int argc, clixon_plugin_start(h, argc+1, argv-1); *(argv-1) = tmp; - /**/ if ((sockpath = clicon_option_str(h, "CLICON_RESTCONF_PATH")) == NULL){ clicon_err(OE_CFG, errno, "No CLICON_RESTCONF_PATH in clixon configure file"); goto done; diff --git a/apps/restconf/restconf_stream.c b/apps/restconf/restconf_stream.c index ba47d75e..08424521 100644 --- a/apps/restconf/restconf_stream.c +++ b/apps/restconf/restconf_stream.c @@ -467,7 +467,6 @@ api_stream(clicon_handle h, #ifdef STREAM_FORK FCGX_Finish_r(r); FCGX_Free(r, 0); - fprintf(stderr, "child exit and free\n"); restconf_terminate(h); exit(0); } diff --git a/util/Makefile.in b/util/Makefile.in index d04af611..22edf3d1 100644 --- a/util/Makefile.in +++ b/util/Makefile.in @@ -75,6 +75,7 @@ APPSRC += clixon_util_xpath.c APPS = $(APPSRC:.c=) all: $(APPS) + echo "You may want to make clixon_util_stream separately (curl dependency)" clean: rm -f $(APPS) *.core diff --git a/util/clixon_util_stream.c b/util/clixon_util_stream.c index 15c3cef3..10275ecf 100644 --- a/util/clixon_util_stream.c +++ b/util/clixon_util_stream.c @@ -135,8 +135,8 @@ stream_url_get(char *url, curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); /* HEADERS */ list = curl_slist_append(list, "Accept: text/event-stream"); - list = curl_slist_append(list, "Cache-Control: no-cache"); - list = curl_slist_append(list, "Connection: keep-alive"); + // list = curl_slist_append(list, "Cache-Control: no-cache"); + // list = curl_slist_append(list, "Connection: keep-alive"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); /* specify URL to get */ cprintf(cbf, "%s", url);