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

* Native Restconf is now default, not fcgi/nginx

Browse source 
* That is, to configure with fcgi, you need to explicitly configure: `--with-restconf=fcgi`
* Updated main example to native restconf and several other fixes
This commit is contained in:
Olof hagsand 2021-07-07 16:14:01 +02:00
parent 98c5fcd20f
commit fe0541959f
7 changed files with 169 additions and 250 deletions
Download patch file Download diff file Expand all files Collapse all files

7
CHANGELOG.md
View file

@ -33,6 +33,13 @@
## 5.3.0
Expected: September, 2021
### C/CLI-API changes on existing features
Developers may need to change their code
* Native Restconf is now default, not fcgi/nginx
* That is, to configure with fcgi, you need to explicitly configure: `--with-restconf=fcgi`
## 5.2.0
1 July 2021

8
configure vendored
View file

@ -1378,6 +1378,7 @@ Optional Packages:
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--with-cligen=dir Use CLIGEN installation in this dir
--with-restconf=native Integration with embedded web server (DEFAULT)
--with-restconf=fcgi FCGI interface for stand-alone web rev-proxy eg
nginx (default)
--with-restconf=native Integrate restconf with embedded http server
@ -4995,15 +4996,17 @@ fi
# This is for restconf. There are three options:
# --without-restconf No restconf support
# --with-restconf=fcgi FCGI interface for separate web reverse proxy like nginx
# --with-restconf=native Integration with embedded web server
# --with-restconf=native Integration with embedded web server (DEFAULT)
# Check whether --with-restconf was given.
if test "${with_restconf+set}" = set; then :
withval=$with_restconf;
else
with_restconf=fcgi
with_restconf=native
fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: restconf mode ${with_restconf}" >&5
$as_echo "restconf mode ${with_restconf}" >&6; }
# Actions for each specific package
if test "x${with_restconf}" == xfcgi; then
# Lives in libfcgi-dev
@ -5063,6 +5066,7 @@ cat >>confdefs.h <<_ACEOF
_ACEOF
elif test "x${with_restconf}" == xnative; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for OPENSSL_init_ssl in -lssl" >&5
$as_echo_n "checking for OPENSSL_init_ssl in -lssl... " >&6; }
if ${ac_cv_lib_ssl_OPENSSL_init_ssl_+:} false; then :

8
configure.ac
View file

@ -206,11 +206,12 @@ AC_CHECK_LIB(cligen, cligen_init,, AC_MSG_ERROR([CLIgen missing. Try: git clone
# This is for restconf. There are three options:
# --without-restconf No restconf support
# --with-restconf=fcgi FCGI interface for separate web reverse proxy like nginx
# --with-restconf=native Integration with embedded web server
# --with-restconf=native Integration with embedded web server (DEFAULT)
AC_ARG_WITH([restconf],
AS_HELP_STRING([--with-restconf=fcgi],[FCGI interface for stand-alone web rev-proxy eg nginx (default)]),
AS_HELP_STRING([--with-restconf=native],[Integration with embedded web server (DEFAULT)]),
,
[with_restconf=fcgi])
[with_restconf=native])
AC_MSG_RESULT(restconf mode ${with_restconf})
# Actions for each specific package
if test "x${with_restconf}" == xfcgi; then
# Lives in libfcgi-dev
@ -218,6 +219,7 @@ if test "x${with_restconf}" == xfcgi; then
AC_DEFINE(WITH_RESTCONF_FCGI, 1, [Use fcgi restconf mode]) # For c-code that cant use strings
AC_DEFINE_UNQUOTED(WWWDIR, "$wwwdir", [WWW dir for fcgi stuff / nginx])
elif test "x${with_restconf}" == xnative; then
AC_CHECK_LIB(ssl, OPENSSL_init_ssl ,, AC_MSG_ERROR([libssl missing]))
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, , AC_MSG_ERROR([libcrypto missing]))
# Check if evhtp is enabled for http/1

4
example/README.md
View file

@ -1,7 +1,7 @@
# Clixon examples
See the separate
[clixon-examples](https://github.com/clicon/clixon-examples) repo.
See also the separate
[clixon-examples](https://github.com/clicon/clixon-examples) repo
The only Clixon example remaining is for internal testing:
* [Main example](main/README.md)

176
example/main/README.md
View file

@ -1,5 +1,6 @@
# Clixon main example
* [Background](#background)
* [Content](#content)
* [Compile and run](#compile)
* [Using the CLI](#using-the-cli)
@ -13,40 +14,45 @@
* [Docker](#docker)
* [Plugins](#plugins)
## Background
The aim of the main clixon example is to illustrate common features
and for internal testing. See the simpler [hello world](https://github.com/clicon/clixon-examples/tree/master/hello) if you want to start from the simplest possible example.
See also other examples in: [clixon-examples](https://github.com/clicon/clixon-examples).
## Content
This directory contains a Clixon example used primarily as a part of the Clixon test suites. It can be used as a basis for making new Clixon applications. But please consider also the minimal [hello](../hello) example as well. It contains the following files:
* `example.xml` The configuration file. See [yang/clixon-config@<date>.yang](../../yang/clixon-config@2019-03-05.yang) for the documentation of all available fields.
* `clixon-example@2019-01-13.yang` The yang spec of the example.
* `example_cli.cli` CLIgen specification.
* `example_cli.c` CLI callback plugin containing functions called in the cli file above: a generic callback (`mycallback`) and an example RPC call (`example_client_rpc`).
This directory contains a Clixon example used primarily as a part of the Clixon test suites. It can be used as a basis for making new Clixon applications. It contains the following files:
* `clixon-example@2020-12-20.yang` The yang spec of the example.
* `example_backend.c` Backend callback plugin including example of:
* transaction callbacks (validate/commit),
* notification,
* rpc handler
* state-data handler, ie non-config data
* `example_backend_nacm.c` Secondary backend plugin. Plugins are loaded alphabetically.
* `example_restconf.c` Restconf callback plugin containing an HTTP basic authentication callback
* `example_cli.c` CLI callback plugin containing functions called in the .cli file
* `example_cli.cli` CLIgen specification of example CLI commands
* `example_netconf.c` Netconf callback plugin
* `example_restconf.c` Restconf callback plugin containing HTTP basic authentication
* `example.xml` Main configuration file.
* `Makefile.in` Example makefile where plugins are built and installed
See [yang/clixon-config@<date>.yang](https://github.com/clicon/clixon/blob/master/yang/clixon/clixon-config%402021-05-20.yang) for documentation of all available fields in `example.xml`.
## Compile and run
Before you start,
* You must configure with: `--enable-optyangs` to run the main example.
* Make [group setup](../../doc/FAQ.md#do-i-need-to-setup-anything-important)
* Setup [restconf](../../doc/FAQ.md#how-do-i-use-restconf)
* You must configure with: `--enable-optyangs` to install all yang files required for the example. This is not necessary for the base colixon system
* Setup clicon [groups](https://github.com/clicon/clixon/blob/master/doc/FAQ.md#do-i-need-to-setup-anything)
```
cd example
cd example/main
make && sudo make install
```
Start backend:
```
sudo clixon_backend -f /usr/local/etc/example.xml -s init
```
Edit cli:
Start cli:
```
clixon_cli -f /usr/local/etc/example.xml
```
@ -54,13 +60,13 @@ Send netconf command:
```
clixon_netconf -f /usr/local/etc/example.xml
```
Start clixon restconf daemon
Start clixon restconf daemon (default config listens on http IPv4 0.0.0.0 on port 8080):
```
sudo /usr/local/bin/clixon_restconf -f /usr/local/etc/example.xml
sudo clixon_restconf -f /usr/local/etc/example.xml
```
Send restconf command
```
curl -X GET http://127.0.0.1/restconf/data
curl -X GET http://127.0.0.1:8080/restconf/data
```
## Using the CLI
@ -71,54 +77,140 @@ There are also many other commands available as examples. View the source file (
The following example shows how to add an interface in candidate, validate and commit it to running, then look at it (as xml) and finally delete it.
```
clixon_cli -f /usr/local/etc/example.xml
cli> set interfaces interface eth9 ?
description enabled ipv4
ipv6 link-up-down-trap-enable type
cli> set interfaces interface eth9 type ex:eth
cli> set interfaces interface eth1 ?
<cr>
description A textual description of the interface.
enabled This leaf contains the configured, desired state of the
interface.
ipv4 Parameters for the IPv4 address family.
ipv6 Parameters for the IPv6 address family.
type The type of the interface.
cli> set interfaces interface eth1 type ianaift:ip
cli> set interfaces interface eth1 enabled true
cli> set interfaces interface eth1 ipv4 address 1.2.3.4 prefix-length 24
cli> validate
cli> commit
cli> show configuration xml
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth9</name>
<type>ex:eth</type>
<name>eth1</name>
<type>ianaift:ip</type>
<enabled>true</enabled>
<ip:ipv4 xmlns:ip="urn:ietf:params:xml:ns:yang:ietf-ip">
<ip:enabled>true</ip:enabled>
<ip:forwarding>false</ip:forwarding>
<ip:address>
<ip:ip>1.2.3.4</ip:ip>
<ip:prefix-length>24</ip:prefix-length>
</ip:address>
</ip:ipv4>
</interface>
</interfaces>
cli> delete interfaces interface eth9
cli> delete interfaces interface eth1
cli> commit
```
## Using Netconf
The following example shows how to set data using netconf:
```
<rpc><edit-config><target><candidate/></target><config>
sh> clixon_netconf -qf /usr/local/etc/example.xml
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><capabilities><capability>urn:ietf:params:netconf:base:1.1</capability></capabilities></hello>]]>]]>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="0">
<edit-config>
<target><candidate/></target>
<config>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth1</name>
<type>ianaift:ip</type>
<enabled>true</enabled>
<ipv4>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>9.2.3.4</ip>
<ip>1.2.3.4</ip>
<prefix-length>24</prefix-length>
</address>
</ipv4>
</interface>
</interfaces>
</config></edit-config></rpc>]]>]]>
</config>
</edit-config>
</rpc>]]>]]>
# Reply: <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="0"><ok/></rpc-reply>]]>]]>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
<commit/>
</rpc>]]>]]>
```
### Getting data using netconf
Getting data:
```
<rpc><get-config><source><candidate/></source></get-config></rpc>]]>]]>
<rpc><get-config><source><candidate/></source><filter/></get-config></rpc>]]>]]>
<rpc><get-config><source><candidate/></source><filter type="xpath"/></get-config></rpc>]]>]]>
<rpc><get-config><source><candidate/></source><filter type="subtree"><data><interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"><interface><name>eth9</name><type>ex:eth</type></interface></interfaces></data></filter></get-config></rpc>]]>]]>
<rpc><get-config><source><candidate/></source><filter type="xpath" select="/interfaces/interface"/></get-config></rpc>]]>]]>
<rpc><validate><source><candidate/></source></validate></rpc>]]>]]>
# Reply: <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"><ok/></rpc-reply>]]>]]>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<get-config>
<source><candidate/></source>
</get-config>
</rpc>]]>]]>
# Reply: <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2"><data><interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"><interface><name>eth1</name><type>ianaift:ip</type><enabled>true</enabled><ip:ipv4 xmlns:ip="urn:ietf:params:xml:ns:yang:ietf-ip"><ip:enabled>true</ip:enabled><ip:forwarding>false</ip:forwarding><ip:address><ip:ip>1.2.3.4</ip:ip><ip:prefix-length>24</ip:prefix-length></ip:address></ip:ipv4></interface></interfaces></data></rpc-reply>]]>]]>
```
Examples of a filtered GET statement:
```
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"><get-config><source><candidate/></source><filter type="xpath" select="/if:interfaces/if:interface[if:name='eth1']" xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces"/></get-config></rpc>]]>]]>
```
## Restconf
By default clixon from release 5.3 uses "native" restconf, see next
section for an alternative. General clixon [restconf
documentation](https://clixon-docs.readthedocs.io/en/latest/restconf.html). By
default restconf supports http/1.1 and http/2 with the standard way
(ALPN vs switch protocol) of selecting and upgrading from 1.1 to 2.
In the example, a restconf config is included in the [config file](example.xml):
```
<restconf>
<enable>true</enable>
<auth-type>none</auth-type>
<socket>
<namespace>default</namespace>
<address>0.0.0.0</address>
<port>80</port>
<ssl>false</ssl>
</socket>
</restconf>
```
In this example, a listening socket is opened using http on port 80. You can extend the restconf config by modifying the entry or add multiple `<socket>` entries, such as IPv6, TLS and another network namespace, for example:
```
<socket>
<namespace>dataplane</namespace>
<address>::</address>
<port>443</port>
<ssl>true</ssl>
</socket>
```
For TLS, cert files need to be given, such as follows:
```
<restconf>
...
<server-cert-path>/path/to/server/cert</server-cert-path>
<server-key-path>/path/to/server/key</server-key-path>
<server-ca-cert-path>/path/to/ca/cert</server-ca-cert-path>
```
For more info, such as client-certs, authentication, etc, see: [restconf documentation](https://clixon-docs.readthedocs.io/en/latest/restconf.html)
## Restconf using nginx
Alternatively, restconf can use a reverse-proxy such as nginx.
Configure:
```
./configure --with-restconf=fcgi
```
Setup a web/reverse-proxy server.
For example, using nginx, install, and edit config file: /etc/nginx/sites-available/default:
```
@ -141,11 +233,13 @@ server {
}
}
```
Start nginx daemon
```
sudo /etc/init.d/nginx start
sudo systemctl start nginx.service # alternative using systemd
```
Start the clixon restconf daemon
```
sudo /usr/local/sbin/clixon_restconf -f /usr/local/etc/example.xml
@ -155,8 +249,6 @@ then access using curl or wget:
curl -X GET http://127.0.0.1/restconf/data/ietf-interfaces:interfaces/interface=eth1/type
```
More info: (restconf)[../../apps/restconf/README.md].
## Streams
The example has an EXAMPLE stream notification triggering every 5s. To start a notification
@ -181,9 +273,6 @@ cli> no notify
cli>
```
Restconf support is also supported, see (restconf)[../../apps/restconf/README.md].
## RPC Operations
Clixon implements Yang RPC operations by a mechanism that enables you
@ -307,8 +396,7 @@ Example systemd files for backend and restconf daemons are found under the [syst
## Docker
See [docker](../../docker/system) for instructions on how to build this example
as a docker container.
See [clixon docker main example](../../docker/main) for instructions on how to build this example as a docker container.
## Plugins

185
example/main/clixon-example@2020-03-11.yang
View file

@ -1,185 +0,0 @@
module clixon-example {
yang-version 1.1;
namespace "urn:example:clixon";
prefix ex;
description
"Clixon example used as a part of the Clixon test suite.
It can be used as a basis for making new Clixon applications.";
revision 2020-03-11 {
description "Added container around translation list. Released in Clixon 4.4.0";
}
revision 2019-11-05 {
description "Augment interface. Released in Clixon 4.3.0";
}
revision 2019-07-23 {
description "Extension e4. Released in Clixon 4.1.0";
}
revision 2019-01-13 {
description "Released in Clixon 3.9";
}
import ietf-interfaces {
prefix if;
}
import ietf-ip {
prefix ip;
}
import iana-if-type {
prefix ianaift;
}
/* Example interface type for tests, local callbacks, etc */
identity eth {
base if:interface-type;
}
identity loopback {
base if:interface-type;
}
/* Translation function example - See also example_cli */
container translate{
description "dont have lists directly under top since restconf cant address list directly";
list translate{
key k;
leaf k{
type string;
}
leaf value{
type string;
}
}
}
/* State data (not config) for the example application*/
container state {
config false;
description "state data for the example application (must be here for example get operation)";
leaf-list op {
type string;
}
}
augment "/if:interfaces/if:interface" {
container my-status {
config false;
description "For testing augment+state";
leaf int {
type int32;
}
leaf str {
type string;
}
}
}
/* yang extension implemented by the example backend code. */
extension e4 {
description
"The first child of the ex:e4 (unknown) statement is inserted into
the module as a regular data statement. This means that 'uses bar;'
in the ex:e4 statement below is a valid data node";
argument arg;
}
grouping bar {
leaf bar{
type string;
}
}
ex:e4 arg1{
uses bar;
}
/* Example notification as used in RFC 5277 and RFC 8040 */
notification event {
description "Example notification event.";
leaf event-class {
type string;
description "Event class identifier.";
}
container reportingEntity {
description "Event specific information.";
leaf card {
type string;
description "Line card identifier.";
}
}
leaf severity {
type string;
description "Event severity description.";
}
}
rpc client-rpc {
description "Example local client-side RPC that is processed by the
the netconf/restconf and not sent to the backend.
This is a clixon implementation detail: some rpc:s
are better processed by the client for API or perf reasons";
input {
leaf x {
type string;
}
}
output {
leaf x {
type string;
}
}
}
rpc empty {
description "Smallest possible RPC with no input or output sections";
}
rpc optional {
description "Small RPC with optional input and output";
input {
leaf x {
type string;
}
}
output {
leaf x {
type string;
}
}
}
rpc example {
description "Some example input/output for testing RFC7950 7.14.
RPC simply echoes the input for debugging.";
input {
leaf x {
description
"If a leaf in the input tree has a 'mandatory' statement with
the value 'true', the leaf MUST be present in an RPC invocation.";
type string;
mandatory true;
}
leaf y {
description
"If a leaf in the input tree has a 'mandatory' statement with the
value 'true', the leaf MUST be present in an RPC invocation.";
type string;
default "42";
}
leaf-list z {
description
"If a leaf-list in the input tree has one or more default
values, the server MUST use these values (XXX not supported)";
type string;
}
leaf w {
description
"If any node has a 'when' statement that would evaluate to
'false',then this node MUST NOT be present in the input tree.
(XXX not supported)";
type string;
when "/translate/k=5/value='w'";
}
}
output {
leaf x {
type string;
}
leaf y {
type string;
}
leaf z {
type string;
}
leaf w {
type string;
}
}
}
}

3
example/main/example.xml
View file

@ -1,6 +1,8 @@
<clixon-config xmlns="http://clicon.org/config">
<CLICON_CONFIGFILE>/usr/local/etc/example.xml</CLICON_CONFIGFILE>
<CLICON_FEATURE>ietf-netconf:startup</CLICON_FEATURE>
<CLICON_FEATURE>clixon-restconf:allow-auth-none</CLICON_FEATURE>
<CLICON_FEATURE>clixon-restconf:fcgi</CLICON_FEATURE>
<CLICON_YANG_DIR>/usr/local/share/clixon</CLICON_YANG_DIR>
<CLICON_YANG_MODULE_MAIN>clixon-example</CLICON_YANG_MODULE_MAIN>
<CLICON_CLI_MODE>example</CLICON_CLI_MODE>
@ -21,4 +23,5 @@
<CLICON_NACM_MODE>disabled</CLICON_NACM_MODE>
<CLICON_STREAM_DISCOVERY_RFC5277>true</CLICON_STREAM_DISCOVERY_RFC5277>
<CLICON_MODULE_LIBRARY_RFC7895>false</CLICON_MODULE_LIBRARY_RFC7895>
<restconf><enable>true</enable><auth-type>none</auth-type><socket><namespace>default</namespace><address>0.0.0.0</address><port>8081</port><ssl>false</ssl></socket></restconf>
</clixon-config>