diff --git a/CHANGELOG.md b/CHANGELOG.md index 55aa4a03..280aa77b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/configure b/configure index a131afc1..548b893a 100755 --- a/configure +++ b/configure @@ -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 : diff --git a/configure.ac b/configure.ac index aaac5f5d..f6046718 100644 --- a/configure.ac +++ b/configure.ac @@ -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 diff --git a/example/README.md b/example/README.md index db0d41b2..020e9afe 100644 --- a/example/README.md +++ b/example/README.md @@ -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) diff --git a/example/main/README.md b/example/main/README.md index 4430c2cb..71186626 100644 --- a/example/main/README.md +++ b/example/main/README.md @@ -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@.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`). -* `example_backend.c` Backend callback plugin including example of: - * transaction callbacks (validate/commit), - * notification, - * rpc handler - * state-data handler, ie non-config data +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: * `example_backend_nacm.c` Secondary backend plugin. Plugins are loaded alphabetically. -* `example_restconf.c` Restconf callback plugin containing an HTTP basic authentication callback -* `example_netconf.c` Netconf callback plugin -* `Makefile.in` Example makefile where plugins are built and installed +* `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@.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,53 +77,139 @@ 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 ? + + 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 - eth9 - ex:eth + eth1 + ianaift:ip true + + true + false + + 1.2.3.4 + 24 + + -cli> delete interfaces interface eth9 +cli> delete interfaces interface eth1 +cli> commit ``` ## Using Netconf The following example shows how to set data using netconf: ``` - - - - eth1 - true - -
- 9.2.3.4 - 24 -
- - - -]]>]]> +sh> clixon_netconf -qf /usr/local/etc/example.xml + +urn:ietf:params:netconf:base:1.1]]>]]> + + + + + + + eth1 + ianaift:ip + true + +
+ 1.2.3.4 + 24 +
+ + + + + +]]>]]> +# Reply: ]]>]]> + + +]]>]]> ``` -### Getting data using netconf +Getting data: ``` -]]>]]> -]]>]]> -]]>]]> -eth9ex:eth]]>]]> -]]>]]> -]]>]]> +# Reply: ]]>]]> + + + + +]]>]]> +# Reply: eth1ianaift:iptruetruefalse1.2.3.424]]>]]> +``` + +Examples of a filtered GET statement: +``` +]]>]]> +``` + +## 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): +``` + + true + none + + default +
0.0.0.0
+ 80 + false + + +``` + +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 `` entries, such as IPv6, TLS and another network namespace, for example: +``` + + dataplane +
::
+ 443 + true + +``` + +For TLS, cert files need to be given, such as follows: +``` + + ... + /path/to/server/cert + /path/to/server/key + /path/to/ca/cert +``` + +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 ``` -## Restconf 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 diff --git a/example/main/clixon-example@2020-03-11.yang b/example/main/clixon-example@2020-03-11.yang deleted file mode 100644 index a4b0c23b..00000000 --- a/example/main/clixon-example@2020-03-11.yang +++ /dev/null @@ -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; - } - } - } -} diff --git a/example/main/example.xml b/example/main/example.xml index d745a759..179db40f 100644 --- a/example/main/example.xml +++ b/example/main/example.xml @@ -1,6 +1,8 @@ /usr/local/etc/example.xml ietf-netconf:startup + clixon-restconf:allow-auth-none + clixon-restconf:fcgi /usr/local/share/clixon clixon-example example @@ -21,4 +23,5 @@ disabled true false + truenonedefault
0.0.0.0
8081false