libnetconf2 is a NETCONF library in C intended for building NETCONF clients and servers. NETCONF is the [NETwork CONFiguration protocol] (http://trac.tools.ietf.org/wg/netconf/trac/wiki) introduced by IETF.
The library provides functions to connect NETCONF client and server to each other via SSH and to send, receive and process NETCONF messages.
libnetconf2 is maintained and further developed by the Tools for Monitoring and Configuration department of CESNET. Any testing or improving/fixing the library is welcome. Please inform us about your experiences with using libnetconf2 via the issue tracker.
Besides the libyang, libnetconf2 is another basic building block for the [Netopeer2 toolset] (https://github.com/CESNET/Netopeer2). For a reference implementation of NETCONF client and server, check the Netopeer2 project.
libnetconf2 is being developed with experiences gained from the development of the libnetconf library. Here are the main differences between the both libraries that would help you to decide which of them is more suitable for your needs.
To represent the schema and data trees, libnetconf uses libxml2, which is intended for different purposes - schema and data trees connected with YANG have specific needs and restrictions in comparison to more generic XML. Therefore, in libnetconf2, we have completely replaced libxml2 by [libyang] (https://github.com/CESNET/libyang). It is much more efficient in work with YANG modeled data (which is the case of NETCONF messages) and this advantage then applies also to libnetconf2. The library connects data with the YANG schemas, so for example the data validation according to the provided YANG schemas is done internally by libyang instead of using external and extremely slow DSDL tools (as it was in the first generation of libnetconf).
libnetconf was trying to be all-in-one, so besides the NETCONF transport, it also implements configuration datastores, NETCONF Access Control Module or the NETCONF Event Notification storage. In contrast, to allow better design of the NETCONF servers, libnetconf2 is focused strictly to the NETCONF transport and message manipulation.
Therefore, all the features from libnetconf that are connected to the datastore implementation are not available in libnetconf2. In the case of the Netopeer2 server, all these features (and much more) are implemented as part of the server itself or its datastore implementation - sysrepo.
While libnetconf2 is able to send (on the server side) and receive (on the client side) the NETCONF Event Notification messages, its generation and storage is left up to the server implementation. In case of the Netopeer2 server, the Notifications implementation is split between the server itself (managing subscriptions) and sysrepo (Events storage).
Similarly as in case of Notifications, libnetconf2 provides supporting functions implementing the Call Home mechanism, but its management (setting the connection parameters) is supposed to be done in the server. Again, as a reference implementation, you can check the Netopeer2 server.
In contrast to libnetconf, libnetconf2 actually implements more of the Call Home functionality.
- NETCONF v1.0 and v1.1 compliant (RFC 6241)
- NETCONF over SSH (RFC 6242) including Chunked Framing Mechanism
- DNSSEC SSH Key Fingerprints (RFC 4255)
- NETCONF over TLS (RFC 5539bis)
- Transport support for NETCONF Event Notifications (RFC 5277)
- NETCONF Call Home (NETCONF Call Home Draft)
Install the following libraries and tools the libnetconf2 depends on.
Follow the libyang instructions, in short:
$ git clone https://github.com/CESNET/libyang.git
$ cd libyang; mkdir build; cd build
$ cmake ..
$ make
# make install
Required version is at least 0.6.4. This dependency can be removed by disabling SSH support (see the Build Options section). Below si the basic sequence of commands for compiling and installing it from source. However, there are packages for certain Linux distributions available here.
$ git clone http://git.libssh.org/projects/libssh.git
$ cd libssh; mkdir build; cd build
$ cmake ..
$ make
# make install
This dependency is required when the TLS support is enabled, which it is by default but libssh requires it too. So, to remove this dependency, you need to disable both SSH and TLS (see the Build Options section).
OpenSSL is a standard part of the most distribution, so ask your package manager for OpenSSL package including the necessary development files (usually -dev or -devel package).
It is required only if DNSSEC SSHFP retrieval is enabled (it is disabled by default, see the Build Options section).
The easier way of installing it is as the libval-dev package (or a part of the dnssec-tools package), if you can find it for your distribution. Packages for some distributions or the source can be downloaded from here.
For running the tests (see the Tests section for more information).
$ git clone git://git.cryptomilk.org/projects/cmocka.git
$ cd cmocka
$ git checkout tags/cmocka-1.0.1
$ mkdir build; cd build
$ cmake ..
$ make
# make install
For building the library documentation.
Doxygen is a standard part of the most distribution, so ask your package manager for doxygen package.
$ mkdir build; cd build
$ cmake ..
$ make
# install
The library documentation can be generated directly from the source codes using Doxygen tool:
$ make doc
There are various options to change result of building.
Set CC environment variable:
$ CC=/usr/bin/clang cmake ..
By default, the library is installed with the /usr/local prefix, to change
it, use the following option:
$ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
The NETCONF protocol specification allows to use the protocol on top of several transport protocols. libnetconf2 provides support for SSH and TLS transport. By default, both SSH and TLS transport is enabled. Disabling and enabling both the transport protocols can be made in the same way. The following command has actually the same effect as specifying no option since it specifies the default settings.
$ cmake -DENABLE_TLS=ON -DENABLE_SSH=ON ..
In SSH connections, if the remote NETCONF server supports it and it is enabled, it is possible to safely retrieve server host key fingerprints using DNSSEC and automatically consider them to be trusted without any interaction. Enable it with the following command.
$ cmake -DENABLE_DNSSEC=ON ..
There are two build modes:
- Release. This generates library for the production use without any debug information.
- Debug. This generates library with the debug information and disables optimization of the code.
The Debug mode is currently used as the default one. to switch to the
Release mode, enter at the command line:
$ cmake -D CMAKE_BUILD_TYPE:String="Release" ..
It is possible to adjust inactive read timeout. It is used when a new message is being read and no new data had arrived for this amount of seconds. 20 is the default value.
$ cmake -D READ_INACTIVE_TIMEOUT:String="20" ..
Active read timeout is used to limit the maximum number of seconds a message is given to arrive in its entirety once a beginning is read. The default is 300 (5 minutes).
$ cmake -D READ_ACTIVE_TIMEOUT:String="300" ..
This value limits the maximum number of threads that can concurrently access (wait for access) a single pspoll structure. To simplify, how many threads could simultaneously call a function whose parameter is one and the same pspoll structure. If using netopeer2-server, it will warn that this value needs to be adjusted if too small.
$ cmake -D MAX_PSPOLL_THREAD_COUNT:String="6" ..
Note that, with CMake, if you want to change the compiler or its options after you already ran CMake, you need to clear its cache first - the most simple way to do it is to remove all content from the 'build' directory.
The repository includes several tests built with cmocka.
The tests can be found in tests subdirectory and they are designed for
checking library functionality after code changes.
The tests are by default built in the Debug build mode by running
$ make
In case of the Release mode, the tests are not built by default (it requires
additional dependency), but it can be enabled via cmake option:
$ cmake -DENABLE_BUILD_TESTS=ON ..
Note that if the necessary cmocka headers are not present in the system include paths, tests are not available despite the build mode or cmake's options.
Tests can be run by the make's test target:
$ make test