experiments/clixon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Restconf stream debugging and README

Browse source
This commit is contained in:
Olof hagsand 2018-11-04 15:59:05 +01:00
parent 09e2e767fe
commit fdfbbcdb9e
6 changed files with 60 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

73
apps/restconf/README.md
View file

@ -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:
```
<CLICON_STREAM_PATH>streams</CLICON_STREAM_PATH>
<CLICON_STREAM_URL>https://example.com</CLICON_STREAM_URL>
<CLICON_STREAM_PUB>http://localhost/pub</CLICON_STREAM_PUB>
<CLICON_STREAM_RETENTION>3600</CLICON_STREAM_RETENTION>
```
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: <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>
```
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:
```
<CLICON_STREAM_PUB>http://localhost/pub</CLICON_STREAM_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:
```