71eddeaa74
* Both a "native" stream support and one using nginx/nchan pub/sub. * See (apps/restconf/README.md) for details. * clixon-config YAML file has new revision: 2018-10-21.
167 lines
No EOL
4.8 KiB
Markdown
167 lines
No EOL
4.8 KiB
Markdown
# Clixon Restconf
|
|
|
|
### Installation using Nginx
|
|
|
|
Ensure www-data is member of the CLICON_SOCK_GROUP (default clicon). If not, add it:
|
|
```
|
|
sudo usermod -a -G clicon www-data
|
|
```
|
|
|
|
This implementation uses FastCGI, see http://www.mit.edu/~yandros/doc/specs/fcgi-spec.html.
|
|
|
|
Download and start nginx. For example on ubuntu:
|
|
```
|
|
sudo apt install ngnix
|
|
```
|
|
|
|
Define nginx config file: /etc/nginx/sites-available/default
|
|
```
|
|
server {
|
|
...
|
|
location /restconf {
|
|
fastcgi_pass unix:/www-data/fastcgi_restconf.sock;
|
|
include fastcgi_params;
|
|
}
|
|
}
|
|
```
|
|
|
|
Start nginx daemon
|
|
```
|
|
sudo /etc/init.d nginx start
|
|
```
|
|
Alternatively, start it via systemd:
|
|
```
|
|
sudo /etc/init.d/nginx start
|
|
sudo systemctl start start.service
|
|
```
|
|
|
|
Start clixon restconf daemon
|
|
```
|
|
olof@vandal> sudo su -c "/www-data/clixon_restconf -f /usr/local/etc/example.xml " -s /bin/sh www-data
|
|
```
|
|
|
|
Make restconf calls with curl
|
|
```
|
|
olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces
|
|
[
|
|
{
|
|
"interfaces": {
|
|
"interface":[
|
|
{
|
|
"name": "eth0",
|
|
"type": "eth",
|
|
"enabled": "true",
|
|
"name": "eth9",
|
|
"type": "eth",
|
|
"enabled": "true"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces/interface/name=eth9/type
|
|
[
|
|
{
|
|
"type": "eth"
|
|
}
|
|
]
|
|
|
|
curl -sX POST -d '{"interfaces":{"interface":{"name":"eth1","type":"eth","enabled":"true"}}}' http://localhost/restconf/data
|
|
```
|
|
|
|
### Event 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
|
|
next section.
|
|
|
|
The example [../../example/README.md] creates and EXAMPLE stream.
|
|
|
|
Set the Clixon configuration options if they differ from default values - if they are OK you do not need to modify them:
|
|
```
|
|
<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>
|
|
```
|
|
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.
|
|
|
|
You access the streams using curl, but they differ slightly in behaviour as described in the following two sections.
|
|
|
|
### Native event streams
|
|
|
|
Add the following to extend the nginx configuration file with the following statements:
|
|
```
|
|
location /streams {
|
|
fastcgi_pass unix:/www-data/fastcgi_restconf.sock;
|
|
include fastcgi_params;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Connection "";
|
|
}
|
|
```
|
|
|
|
You access a native stream as follos:
|
|
```
|
|
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
|
|
```
|
|
where the first command retrieves only new notifications, and the second receives a range of messages.
|
|
|
|
### Nginx Nchan streams
|
|
|
|
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).
|
|
|
|
Configure clixon with `--enable-publish` which enables curl code for publishing streams to nchan.
|
|
|
|
Download and install nchan, see (https://nchan.io/#install).
|
|
|
|
Add the following to extend the nginx configuration file with the following statements:
|
|
```
|
|
location ~ /streams/(\w+)$ {
|
|
nchan_subscriber;
|
|
nchan_channel_id $1; #first capture of the location match
|
|
}
|
|
location ~ /pub/(\w+)$ {
|
|
nchan_publisher;
|
|
nchan_channel_id $1; #first capture of the location match
|
|
}
|
|
```
|
|
|
|
Access the event stream EXAMPLE using curl:
|
|
```
|
|
curl -H "Accept: text/event-stream" -s -X GET http://localhost/streams/EXAMPLE
|
|
curl -H "Accept: text/event-stream" -H "Last-Event-ID: 1539961709:0" -s -X GET http://localhost/streams/EXAMPLE
|
|
```
|
|
where the first command retrieves the whole stream history, and the second only retreives the most recent messages given by the ID.
|
|
|
|
See (https://nchan.io/#eventsource) on more info on how to access an SSE sub endpoint.
|
|
|
|
### Debugging
|
|
|
|
Start the restconf fastcgi program with debug flag:
|
|
```
|
|
sudo su -c "/www-data/clixon_restconf -D 1 -f /usr/local/etc/example.xml" -s /bin/sh www-data
|
|
```
|
|
Look at syslog:
|
|
```
|
|
tail -f /var/log/syslog | grep clixon_restconf
|
|
```
|
|
|
|
Send command:
|
|
```
|
|
curl -G http://127.0.0.1/restconf/data/*
|
|
```
|
|
|
|
You can also run restconf in a debugger.
|
|
```
|
|
sudo gdb /www-data/clixon_restconf
|
|
(gdb) run -D 1 -f /usr/local/etc/example.xml
|
|
```
|
|
but you need to ensure /www-data/fastcgi_restconf.sock has the following access:
|
|
```
|
|
rwxr-xr-x 1 www-data www-data 0 sep 22 11:46 /www-data/fastcgi_restconf.sock
|
|
``` |