Adding upstream version 2.0.24.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
e508fcfeb9
commit
afb0a8fea7
GPG key ID:
FBB4F0E80A80222F
118 changed files with 45084 additions and 0 deletions
285
README.md
Normal file
285
README.md
Normal file
|
|
@ -0,0 +1,285 @@
|
|||
# libnetconf2 – The NETCONF protocol library
|
||||
|
||||
[](https://opensource.org/licenses/BSD-3-Clause)
|
||||
[](https://github.com/CESNET/libnetconf2/actions?query=workflow%3A%22libnetconf2+CI%22)
|
||||
[](https://netopeer.liberouter.org/doc/libnetconf2/)
|
||||
[](https://scan.coverity.com/projects/7642)
|
||||
[](https://codecov.io/gh/CESNET/libnetconf2)
|
||||
|
||||
**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.
|
||||
|
||||
**libnetconf2** is a NETCONF library in C handling NETCONF authentication and all NETCONF RPC communication both server
|
||||
and client-side. Note that NETCONF datastore implementation is not a part of this library. The library supports both
|
||||
NETCONF 1.0 ([RFC 4741](https://tools.ietf.org/html/rfc4741)) as well as NETCONF 1.1
|
||||
([RFC 6241](https://tools.ietf.org/html/rfc6241)). The main features include:
|
||||
|
||||
* NETCONF over SSH ([RFC 4742](https://tools.ietf.org/html/rfc4742), [RFC 6242](https://tools.ietf.org/html/rfc6242)),
|
||||
using [libssh](https://www.libssh.org/).
|
||||
* NETCONF over TLS ([RFC 7589](https://tools.ietf.org/html/rfc7589)), using [OpenSSL](https://www.openssl.org/).
|
||||
* DNSSEC SSH Key Fingerprints ([RFC 4255](https://tools.ietf.org/html/rfc4255))
|
||||
* NETCONF over pre-established transport sessions (using this mechanism the communication can be tunneled through
|
||||
sshd(8), for instance).
|
||||
* NETCONF Call Home ([RFC 8071](https://tools.ietf.org/html/rfc8071)).
|
||||
* NETCONF Event Notifications ([RFC 5277](https://tools.ietf.org/html/rfc5277)),
|
||||
|
||||
**libnetconf2** is maintained and further developed by the [Tools for
|
||||
Monitoring and Configuration](https://www.liberouter.org/) department of
|
||||
[CESNET](http://www.ces.net/). Any testing or improving/fixing the library
|
||||
is welcome. Please inform us about your experiences with using **libnetconf2**
|
||||
via the [issue tracker](https://github.com/CESNET/libnetconf/issues).
|
||||
|
||||
Besides the [**libyang**](https://github.com/CESNET/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.
|
||||
|
||||
## Branches
|
||||
|
||||
The project uses 2 main branches `master` and `devel`. Other branches should not be cloned. In `master` there are files of the
|
||||
last official *release*. Any latest improvements and changes, which were tested at least briefly are found in `devel`. On every
|
||||
new *release*, `devel` is merged into `master`.
|
||||
|
||||
This means that when only stable official releases are to be used, either `master` can be used or specific *releases* downloaded.
|
||||
If all the latest bugfixes should be applied, `devel` branch is the one to be used. Note that whenever **a new issue is created**
|
||||
and it occurs on the `master` branch, the **first response will likely be** to use `devel` before any further provided support.
|
||||
|
||||
## libnetconf vs libnetconf2
|
||||
|
||||
**libnetconf2** was developed with experiences gained from the development
|
||||
of the [**libnetconf**](https://github.com/CESNET/libnetconf) library, which
|
||||
is now obsolete and should not be used.
|
||||
|
||||
# Installation
|
||||
|
||||
## Required Dependencies
|
||||
|
||||
Install the following libraries and tools the libnetconf2 depends on.
|
||||
|
||||
### libyang
|
||||
Follow the [libyang instructions](https://github.com/CESNET/libyang/blob/master/README.md),
|
||||
in short:
|
||||
```
|
||||
$ git clone https://github.com/CESNET/libyang.git
|
||||
$ cd libyang; mkdir build; cd build
|
||||
$ cmake ..
|
||||
$ make
|
||||
# make install
|
||||
```
|
||||
|
||||
### libssh
|
||||
Required version is at least 0.7.1. This dependency can be removed by disabling
|
||||
SSH support (see the [Build Options](#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](https://www.libssh.org/get-it/).
|
||||
```
|
||||
$ git clone http://git.libssh.org/projects/libssh.git
|
||||
$ cd libssh; mkdir build; cd build
|
||||
$ cmake ..
|
||||
$ make
|
||||
# make install
|
||||
```
|
||||
|
||||
### OpenSSL
|
||||
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](#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).
|
||||
|
||||
## Optional Dependencies
|
||||
|
||||
### libval (part of the DNSSEC-Tools suite)
|
||||
It is required only if DNSSEC SSHFP retrieval is enabled (it is disabled by
|
||||
default, see the [Build Options](#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. Otherwise,
|
||||
compile and install it from [source](https://github.com/DNSSEC-Tools/DNSSEC-Tools/).
|
||||
Only the validator component (`DNSSEC-Tools/dnssec-tools/validator`) is needed.
|
||||
|
||||
### cmocka
|
||||
For running the tests cmocka 1.0.1 is required (see the [Tests](#tests) section for more information).
|
||||
```
|
||||
$ sudo apt-get install libcmocka-dev
|
||||
```
|
||||
|
||||
### Doxygen
|
||||
For building the library documentation.
|
||||
|
||||
Doxygen is a standard part of the most distribution, so ask your package
|
||||
manager for doxygen package.
|
||||
|
||||
### gcov
|
||||
|
||||
For code coverage, `gcov`, `lcov`, and `genhtml` are needed.
|
||||
|
||||
## Building libnetconf2
|
||||
|
||||
```
|
||||
$ mkdir build; cd build
|
||||
$ cmake ..
|
||||
$ make
|
||||
# install
|
||||
```
|
||||
|
||||
The library documentation can be generated directly from the source codes using
|
||||
Doxygen tool:
|
||||
```
|
||||
$ make doc
|
||||
```
|
||||
|
||||
## Build Options
|
||||
|
||||
There are various options to change result of building.
|
||||
|
||||
### Changing Compiler
|
||||
|
||||
Set `CC` environment variable:
|
||||
|
||||
```
|
||||
$ CC=/usr/bin/clang cmake ..
|
||||
```
|
||||
|
||||
### Installation Prefix
|
||||
|
||||
By default, the library is installed with the `/usr/local` prefix, to change
|
||||
it, use the following option:
|
||||
```
|
||||
$ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
|
||||
```
|
||||
|
||||
### Transport Protocol Support
|
||||
|
||||
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 ..
|
||||
```
|
||||
|
||||
### DNSSEC SSHFP Retrieval
|
||||
|
||||
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 ..
|
||||
```
|
||||
|
||||
### Build Modes
|
||||
|
||||
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" ..
|
||||
```
|
||||
|
||||
### Inactive Read Timeout
|
||||
|
||||
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
|
||||
|
||||
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" ..
|
||||
```
|
||||
|
||||
### PSPoll Thread Count
|
||||
|
||||
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" ..
|
||||
```
|
||||
|
||||
### Code Coverage
|
||||
|
||||
Based on the tests run, it is possible to generate code coverage report. But
|
||||
it must be enabled and these commands are needed to generate the report:
|
||||
```
|
||||
$ cmake -DENABLE_COVERAGE=ON ..
|
||||
$ make
|
||||
$ make coverage
|
||||
```
|
||||
|
||||
Note that `gcc` compiler is required for this option and additional tools are required:
|
||||
* gcov
|
||||
* lcov
|
||||
* genhtml
|
||||
|
||||
### CMake Notes
|
||||
|
||||
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.
|
||||
|
||||
## Usage
|
||||
|
||||
All public functions are available via 2 headers:
|
||||
```
|
||||
#include <nc_server.h>
|
||||
#include <nc_client.h>
|
||||
```
|
||||
|
||||
You need to include either one if imeplementing a NETCONF server or a NETCONF client,
|
||||
respectively.
|
||||
|
||||
To compile your program with libnetconf2, it is necessary to link it with it using the
|
||||
following linker parameters:
|
||||
```
|
||||
-lnetconf2
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
The repository includes several tests built with [cmocka](https://cmocka.org/).
|
||||
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_TESTS=ON ..
|
||||
```
|
||||
|
||||
Note that if the necessary [cmocka](https://cmocka.org/) 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
|
||||
```
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue