Data Validation

RFC 6241 defines NETCONF :validate capability intended to allow validation of the configuration data. This capability specifies new operation <validate> and adds <test-option> parameter to the <edit-config> operation.

On the client side, libnetconf allows to create <validate> RPC as well as to specify <test-option> of <edit-config> RPC. When the :validate capability is supported by the server, the default <test-option> value is test-then-set, so each <edit-config> change is validated.

On the server side, libnetconf performs data validation on datastore parts that provides validators. libnetconf use Relax NG schema to validate syntax of the datastore content and Schematron to check semantics. Validators are loaded as a standalone files generated by lnctool(1), which is part of libnetconf standard instalation.

libnetconf automatically searches for the validators during ncds_new() and ncds_new_transapi() calls. Validators are supposed to be placed in the same directory as data model provided to the mentioned function as its model_path parameter. Alternatively, validators can be connected with the datastore manually, using ncds_set_validation(). This function also allows to switch off validation on a specific datastore part.

lnctool(1) Usage

Complete list of lnctool(1)'s options can be displayed using -h option:

$ lnctool -h

lnctool(1) is used to perform the following 3 actions:

1. convert - converts YANG model to the YIN format
2. validation - generates validation files for a given YANG data model
3. transapi - prepares a transAPI module template

Each next action includes all the previous actions, so executing the transapi action generates also the YIN format of the data model and all the validation files. More information about using lnctool(1) for creating a transAPI modules can be found in the Transaction API (transAPI) section. Here we focus on the validation action.

As the main input, you have to specify the main YANG data model of the datastore (--model option). If there are also some augmenting models, you should specify them as a parameter to the (multiple) --augment-model option(s). If you need some imported data models, specify the path where to search for them as the --search-path option.

Based on a YANG data model, lnctool(1) generates all necessary files needed by libnetconf. Basically, it generates YIN format of the data model required by ncds_new() and ncds_new_transapi() functions. If you use some extension models via ncds_add_model() or ncds_add_models_path(), you have to specify also these models as lnctool(1)'s <augment models> parameter.

The following commands generate validation files for the NACM data model:

$ cd libnetconf/models/
$ lnctool --model ./ietf-netconf-acm.yang --output-dir ./nacm/ validation

The output directory nacm/ now contains generated NACM data model in YIN format, Relax NG schemas and Schematron XSL stylesheet for validation.

Path to the search directory should be also specified in the server source code to allow libnetconf to find imported data model (ietf-yang-types.yin in this case).

Note

Return value checks are skipped in this example for simplicity. Do not copy-paste this example. Also note, that NACM is one of internal libnetconf datastores and it is not needed to add it manually by ncds_new(). This is JUST a simple (stupid) example.

ds = ncds_new(NCDS_TYPE_FILE, "./models/nacm/ietf-netconf-acm.yin", NULL);
ncds_file_set_path(ds, ds_path);
ncds_init(ds);
ncds_add_models_path("./models/");
ncds_consolidate();

If the validators files are stored in the same directory as a basic data model (ietf-netconf-acm.yin in this case), libnetconf automatically loads them during ncds_new() or ncds_new_transapi() calls. If you store the validators files somewhere else, ncds_set_validation() function can be used to specify their location:

ncds_set_validation(ds, 1, "./models/nacm/ietf-netconf-acm-config.rng", "./models/nacm/ietf-netconf-acm-schematron.xsl");

If validators files are not found or validation is switched off (via ncds_set_validation() with enable parameter set to 0), validation is not performed on such datastore part.

Data Model Features

When the data model includes some feature definition and corresponding if-feature statement(s), all such features are enabled for validation by default. If you want to enable only specific features (or disable all of them), you have to use the lnctool(1)'s --feature option. The option can be use multiple times and the given value has the following form:

--feature module_name:feature_to_enable

If you want to disable all features of the module, use the following syntax:

--feature module_name:

Remember that if you have some augmenting modules, you should also set features of those augmenting modules.