14  Automation Control

The YANG language includes many ways to specify conditions for database validity, which traditionally are only documented in DESCRIPTION clauses.  The YANG language allows vendors and even data modelers to add new statements to the standard syntax, in a way that allows all tools to skip extension statements that they do not understand.

The yangdump-pro YANG compiler sames all the non-standard language statements it finds, even those it does not recognize.  These are stores in the ncx_appinfo_t data structure in ncx/ncxtypes.h..

There are also SIL access functions defined in ncx/ncx_appinfo.h that allow these language statements to be accessed.  If an argument string was provided, it is saved along with the command name.

Several data structures contains an 'appinfoQ' field to contain all the ncx_appinfo_t stuctures that were generated within the same YANG syntax block (e.g., within a typedef, type, leaf, import statement).

 

14.1  YANG Parser Object Template APIs

The YANG compiler built into the netconfd-pro server has some yp-system level callback APIs that allow YANG data structures to be customized to assist SIL automation or improve processing performance.

 

14.1.1  Object Template User Flags

There is a special field in the obj_template_t structure to allow vendor-specific flag definitions for an object template. This field is 32 bits wide and initialized to zero when the object template is created.

 

 

Field definition:  uint32 uflags;

 

Access Macro: OBJ_USER_FLAGS(obj)

 

 

14.1.2  Object Template Callback API

This feature allows the object template for YANG data nodes to be examined, and the user flags to be set as needed.

This API is called for all objects during YANG module parsing.  The callback may wish to use filters such as obj_is_data_db(obj) to limit scanning to only database objects.

The API template is defined in ncx/ncxtypes.h:

 

 

/* user function callback template when a YANG object is

 * parsed by yang_obj.c. This API is invoked at the

 * end of the resolve phase if the status is NO_ERR

 * It is skipped if the object has errors detected at the time

 *

 * ncx_yang_obj_cbfn_t

 *

 *  Run an instrumentation-defined function

 *  for a 'object parsed' event

 *

 * INPUTS:

 *   mod == module that is being parsed now

 *   obj == object being parsed

 */

typedef void

    (*ncx_yang_obj_cbfn_t) (ncx_module_t *mod,

                            struct obj_template_t_ *obj);

 

 

The registration function needs to be called from the yp-system initialization callbacks. This callback should be installed before any SIL-related YANG modules are loaded.

The registration functions are defined in ncx/ncx.h:

 

 

/********************************************************************

* FUNCTION ncx_set_yang_obj_callback

*

* Set the callback function for a YANG object parse event

*

* INPUT:

*   cbfn == callback function to set

*

* RETURNS:

*  status

*********************************************************************/

extern status_t

    ncx_set_yang_obj_callback (ncx_yang_obj_cbfn_t cbfn);

 

 

/********************************************************************

* FUNCTION ncx_clear_yang_obj_callback

*

* Clear the callback function for a parse-object event

*

* INPUT:

*   cbfn == callback function to find and clear

*

*********************************************************************/

extern void

    ncx_clear_yang_obj_callback (ncx_yang_obj_cbfn_t cbfn);

 

 

14.1.3  YANG Object template Callback Usage Example

This example callback function checks for a proprietary YANG extension within a YANG object.

 

 

/***********  Example YANG Object Template Callback **********/

 

/*

 * Assume YANG module foo exists with extension acme1

 *

 * module foo {

 *   prefix f;

 *   ...

 *   extension acme1 { ... }

 *

 * The extension is used inside object definitions. e.g:

 *

 *    leaf X {

 *      f:acme1;

 *      type string;

 *    }

 *

 * Assume there is a vendor bit defined for the user flags field

 */

 

#define FL_ACME_1  0x1

 

 

Callback function:

 

 

/* user function callback template when a YANG object is

 * parsed by yang_obj.c. This API is invoked at the

 * end of the resolve phase if the status is NO_ERR

 * It is skipped if the object has errors detected at the time

 *

 * ncx_yang_obj_cbfn_t

 *

 *  Run an instrumentation-defined function

 *  for a 'object parsed' event

 *

 * INPUTS:

 *   mod == module that is being parsed now

 *   obj == object being parsed

 */

void

    example_obj_template_cbfn (ncx_module_t *mod,

                               struct obj_template_t_ *obj)

{

    /* optional: use the module to check certain module names to

     * pre-filter the callback

     */

    (void)mod;

 

    /* get the appinfoQ for the object */

    dlq_hdr_t *appinfoQ = obj_get_appinfoQ(obj);

    if (appinfoQ == NULL) {

        return;   // error!

    }

 

    /* check the object template appinfoQ to see if the vendor

     * extensions are present

     */

    ncx_appinfo_t *appinfo =

        ncx_find_appinfo(appinfoQ,

                         (const xmlChar *)"f",

                         (const xmlChar *)"acme1");

    if (appinfo) {

        OBJ_USER_FLAGS(obj) |= FL_ACME_1;

    }

 

}

 

 

Registration inside yp_system_init1:

 

 

#include “ncx.h”

 

status_t yp_system_init1 (boolean pre_cli)

{

    status_t res = NO_ERR;

    log_debug("\nyp_system init1\n");

 

    if (pre_cli) {

;

    } else {

 

        /* example -- Register a YANG Object Template Callback */

        res = ncx_set_yang_obj_callback(example_obj_template_cbfn);

 

 

    }

    return res;

 

}  /* yp_system_init1 */

 

 

14.2  YANG Parser Extension Statement APIs

The YANG “extension” statement allows external language statements to be added to YANG. These external statements follow the same generic structure as all YANG statements. A YANG compiler must be able to skip over external statements.  Only tools which claim conformance to an extension are required to enforce the semantics of the extension.

The YANG compiler supports user callbacks to handle specific extension statements. There are two types of callbacks:

  1. Top-level extensions: These extensions have the module statement itself as its parent. These extensions may be wrappers for additional statements, such as the reserved extension “yang-data”.  The callback for these extensions is invoked during the module parsing phase (i.e,., consume_extension). The callback is responsible for completing the parsing phase and consume all tokens for the external statement, including the final semi-colon or right brace.

  2. Nested extensions: These extensions are contained within nested statements, which are not at the top-level. They are expected to be simple statements and not wrappers for YANG statements. The callback for these extensions is invoked during the module validation phase (i.e., resolve_extension). This callback is not responsible for parsing any module token input. All parsing has already been completed

 

14.2.1  YANG Extension Handler Callback

The following callback API is defined in ncx/ext.h:

 

 

/* One YANG Extension Handler Callback

 *

 * ext_cbfn_t

 *

 * Handle the parsing and processing of an external statement

 * using the associated YANG extension statement

 *

 * This callback is invoked when the external statement is

 * first encountered. The current token is the argument string

 * if any or the identifier token if none.

 * The next token is expected to be a semi-colon or a left brace

 * The callback is expected to parse the closing semi-colon or

 * entire sub-section including starting brace

 *

 * INPUTS:

 *   rawpcb == parser control block in progress (cast as void *)

 *   mod == module being processed

 *   tkc == token chain of module tokens parse in progress

 *   ext == extension definition record (allows a handler to

 *         process multiple extension types)

 *   cookie == cbfn_cookie from the extension 'ext'

 *   arg == argument string used in the external statement (if any)

 *   node_type == type of node being processed; direct parent

 *         statement of the external statement using the extension

 *         If NULL, then the parent statement is the module itself,

 *         and 'mod' should be used as the 'node' pointer

 *   node == pointer to node indicated by node_type

 * OUTPUTS:

 *

 * RETURNS:

 *   status of processing

 */

typedef status_t (*ext_cbfn_t)

    (void *rawpcb,    // struct yang_pcb_t_ *pcb

     ncx_module_t *mod,

     tk_chain_t *tkc,

     struct ext_template_t_ *ext,

     void *cookie,

     const xmlChar *arg,

     ncx_node_t node_type,

     void *node);

 

 

 

The registration function is defined in ncx/etc.h. This API should be registered in the yp-system initialization phase, before YANG modules are parsed.

 

 

/********************************************************************

* FUNCTION ext_register_cbfn

*

* Register a callback function for the specified extension

* If multiple callbacks for same extension, then last one wins

*

* INPUTS:

*   modname == module name defining the extension

*   extname == extension name

*   cbfn == pointer to callback function to register

*   cbfn_cookie == optional cookie to register; will not be

*             freed when the extension is freed

*             Use macro EXT_CBFN_COOKIE(ext) to access from callback

*               == NULL if not used

*********************************************************************/

extern status_t

    ext_register_cbfn (const xmlChar *modname,

                       const xmlChar *extname,

                       ext_cbfn_t cbfn,

                       void *cbfn_cookie);

 

 

14.2.2 Usage Example

This example callback function checks for a proprietary YANG extension within a YANG object.

It uses the same YANG module as the YANG Object Template Callback.

 

 

/*

 * Callback is invoked to check a specific extension in an

 * obj_template_t, typ_template_t, typ_def_t

 *

 * Assume the same YANG module foo exists with extension acme1

 *

 * The example callback does the same task as the

 * example_obj_template_cbfn, using the per-callback approach

 */

 

/* One YANG Extension Handler Callback

 *

 * example_ext_cbfn

 *

 * Handle the parsing and processing of an external statement

 * using the associated YANG extension statement

 *

 * This callback is invoked when the external statement is

 * first encountered. The current token is the argument string

 * if any or the identifier token if none.

 * The next token is expected to be a semi-colon or a left brace

 * The callback is expected to parse the closing semi-colon or

 * entire sub-section including starting brace

 *

 * INPUTS:

 *   rawpcb == parser control block in progress (cast as void *)

 *   mod == module being processed

 *   tkc == token chain of module tokens parse in progress

 *   ext == extension definition record (allows a handler to

 *         process multiple extension types)

 *   cookie == cbfn_cookie from the extension 'ext'

 *   arg == argument string used in the external statement (if any)

 *   node_type == type of node being processed; direct parent

 *         statement of the external statement using the extension

 *         If NULL, then the parent statement is the module itself,

 *         and 'mod' should be used as the 'node' pointer

 *   node == pointer to node indicated by node_type

 * OUTPUTS:

 *

 * RETURNS:

 *   status of processing

 */

static status_t

     example_ext_cbfn (void *rawpcb,  // struct yang_pcb_t_ *pcb

                       ncx_module_t *mod,

                       tk_chain_t *tkc,

                       struct ext_template_t_ *ext,

                       void *cookie,

                       const xmlChar *arg,

                       ncx_node_t node_type,

                       void *node)

{

    (void)rawpcb;

    (void)mod;

    (void)tkc;

    (void)ext;

    (void)cookie;

    (void)arg;

 

    /* ignore this extension in all contexts except object template */

    if (node_type != NCX_NT_OBJ) {

        return NO_ERR;

    }

 

    /* get the object template */

    obj_template_t *obj = (obj_template_t *)node;

 

    /* set the acme1 bit */

    OBJ_USER_FLAGS(obj) |= FL_ACME_1;

 

    return NO_ERR;

}

 

 

Registration inside yp_system_init1:

 

 

#include “ext.h”

 

status_t yp_system_init1 (boolean pre_cli)

{

    status_t res = NO_ERR;

    log_debug("\nyp_system init1\n");

 

    if (pre_cli) {

;

    } else {

 

        /* example -- Register a Extension Handler Callback */

        res = ext_register_cbfn((const xmlChar *)"acme-ext",

                                (const xmlChar *)"acme1",

                                example_ext_cbfn,

                                NULL);   // cookie

 

    }

    return res;

 

}  /* yp_system_init1 */

 

 

14.3  Abstract YANG Data APIs

YANG can be used to define abstract data that can be used within server SIL callbacks and system callbacks. This sort of data is commonly used to read/write files containing YANG data or protocol messages defined in YANG.

This functionality is already supported with the ncx:abstract extension, but this method of defining abstract data is more standards-compliant, so it should be used instead of ncx:abstract.

14.3.1  rc:yang-data

The RESTCONF Protocol (RFC 8040) includes the YANG extension definition for yang-data. It is used within ietf-restconf.yang and ietf-yang-patch.yang. Any module can define YANG data structures;

Restrictions: YANG does not allow multiple top-level nodes with the same name to be defined in the same module. Make sure that the top-level nodes defined within the yang-data statement do not conflict with other top-level object names. The data defined within the yang-data statement must be 1 container statement or 1 uses statement .

 

 

module foo {

   // header

   import ietf-restconf { prefix rc; }

 

   rc:yang-data test1 {

      container test1 {

        leaf leaf1 { type string; }

        leaf leaf2 { type int32; }

      }

   }

}

 

 

14.3.2  yd:augment-yang-data

The yang-data-ext.yang module defines a YANG extension to allow yang-data nodes to be augmented from a different module.  This is not supported by the RESTCONF standard, just supported in netconfd-pro. The plain augment statement can be used instead of this extension, but this should be avoided because a standard YANG compiler is not required to support the RESTCONF yang-data extension (so it will not find the augmented node)

 

 

module bar {

   // header

   import yang-data-ext { prefix yd; }

   import foo { prefix f; }

 

   yd:augment-yang-data /f:test1 {

      leaf test2 { type string; }

   }

}

 

 

14.4  SIL Language Extension Access Functions

The following table highlights the SIL functions in ncx/ncx_appinfo.h that allow SIL code to examine any of the non-standard language statements that were found in the YANG module:

 

Language Extension Access Functions

 

Function

Description

ncx_find_appinfo

Find an ncx_appinfo_t structure by its prefix  and name, in a queue of these entries.

ncx_find_next_appinfo

Find the next occurrence of the specified ncx_appinfo_t data structure.

ncx_clone_appinfo

Clone the specified ncx_appinfo_t data structure.

 

14.5  Built-in YANG Language Extensions

There are several YANG extensions that are supported by YumaPro.  They are all defined in the following YANG files:

 

These YANG extensions are used to 'tag' YANG definitions for some sort of automatic processing by YumaPro programs.  Extensions are position-sensitive, and if not used in the proper context, they will be ignored.  A YANG extension statement must be defined (somewhere) for every extension used in a YANG file, or an error will be occur.

Most of these extensions apply to netconfd-pro server behavior, but not all of them.  For example, the ncx:hidden extension will prevent yangcli-pro from displaying help for an object containing this extension.  Also, yangdump-pro will skip this object in HTML output mode.

The following sections describe the supported YANG language extensions.  All other YANG extension statements will be ignored by YumaPro, if encountered in a YANG file.

14.5.1  ncx:abstract

The ncx:abstract extension is used with object definitions to indicate that they do not represent CLI or NETCONF configuration database data instances.  Instead, the node is simply an object  identifier, an 'error-info' extension, or some other abstract data structure.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

  container server-hello {

     description "Generic Server Hello Message Parameters.";

 

     uses NcCapabilities;

 

     leaf session-id {

        type session-id-type;

        config false;

     }

 

     ncx:hidden;

     ncx:abstract;

   }

 

 

14.5.2  ywx:alt-name

The ywx:alt-name extension is used within a data node definition to specify an alternate name for the node.  The --alt-names parameter must be enabled for these names to be used.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument:

Example:

 

 

  leaf system-reset-time {

    ywx:alt-name last-reset;

    type yang:date-and-time;

    config false;

  }

 

 

14.5.3  ncx:cli

The ncx:cli extension is used within a container definition to indicate it is only used as a conceptual container for a set of CLI parameters. A top-level container containing this extension will not be included in any NETCONF configuration databases.

Only the following types of YANG objects are allowed within the CLI container at this time:

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

  container yangcli-pro {
    ncx:cli;

     // leafs and choices of leafs inserted here

  }

 

 

14.5.4  ywx:cli-text-block

The ywx:cli-text-block extension is used to force CLI text syntax within a container.  It is only used by yangcli-pro for test-suite 'setup' and 'cleanup' sections at this time.

If this extension is present in an empty container or list, it will be treated in unit-test parsing as a container or list of ordered text commands, 1 per line. Line extension is needed to wrap a command into many lines.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: none

Example:

 

 

        container setup {

           ywx:cli-text-block;

        }

 

       Example test script or conf file usage:

 

        setup {

          run test1-script

          get-config source=running

          lock target=candidate

          some-long-command parms='this is a wrapped \

            line in a text block'

        }

 

 

 

14.5.5  ywx:datapath

The ywx:datapath extension is used by the YControl subsystem to specify the real object to use for parsing an “anyxml” or “container” node as a different object type.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: path string

Example:

 

 

       "Used within a container or anyxml definition to indicate

       that the object path for the data node should be sent

       in the value as an attribute.  The SIL-SA parser will use

       the datapath attribute to select the object template

       to use for parsing, instead of generic anyxml.

 

          anyxml newval {

            ywx:datapath;

          }

          anyxml curval {

            ywx:datapath;

          }

 

          If /foo/bar/leaf2 is edited, the <edit> message

          will be generated with the datapath attribute

          from the yumaworks-attrs module.

 

           <newval ywattrs:datapath='/foo/bar/leaf2'>42</newval>

           <curval ywattrs:datapath='/foo/bar/leaf2'>67</curval>

 

 

14.5.6  nacm:default-deny-all

The nacm:default-deny-all extension is used by the to indicate that the data model node represents a sensitive security system parameter.

If present, and the NACM module is enabled (i.e.,/nacm/enable-nacm object equals 'true'), the NETCONF server will only allow the designated 'recovery session' to have read, write, or execute access to the node.  An explicit access control rule is required for all other users. The 'default-deny-write' extension MAY appear within a data definition statement.  It is ignored otherwise.

YANG Files:  (only 1 can be active on the server, selected in agt_profile)

Argument: none

Example:

 

 

    rpc shutdown {

      nacm:default-deny-all;

    }

 

 

14.5.7  nacm:default-deny-write

The nacm:default-deny-write extension is used by the to indicate that the data model node represents a sensitive security system parameter.

If present, and the NACM module is enabled (i.e.,/nacm/enable-nacm object equals 'true'), the NETCONF server will only allow the designated 'recovery session' to have write access to the node.  An explicit access control rule is required for all other users. The 'default-deny-write' extension MAY appear within a data definition statement.  It is ignored otherwise.

 

YANG Files:  (only 1 can be active on the server, selected in agt_profile)

Argument: none

Example:

 

 

    leaf enable-system {

      nacm:default-deny-write;

      type boolean;

    }

 

 

14.5.8  ncx:default-parm

The ncx:default-parm extension is used by the yangcli-pro program to select a default parameter for the specified RPC input section.    It can be used within a CLI container or rpc definition to specify leaf parameter within the CLI container or rpc input section, that is used as the default if no parameter name is entered.

These values must not begin with a dash (-) or double dash (--) sequence or they will be mistaken for CLI parameter names.

This option is somewhat risky because any unrecognized parameter without any prefix (- or --) will be tried as the default parameter type, instead of catching the unknown parameter error.  It can also be useful though,  for assigning file name parameters through shell expansion, or if there is only one parameter.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument:

Example:

 

    rpc connect {

      description "Connect to a NETCONF server.";

      input {

        ncx:default-parm server;

 

        uses ConnectParms {

          refine user {

        mandatory true;

          }

          refine server {

      mandatory true;

          }

          refine password {

      mandatory true;

          }

        }

     }

 

     // note that the server parameter can be omitted

     yangcli-pro>  connect localhost user=andy password=yang-rocks

 

 

14.5.9  ncx:default-parm-equals-ok

The ncx:default-parm-equals-ok extension is used by the yangcli-pro program to select a default parameter for the specified RPC input section. It is used within a CLI container or rpc definition to specify a leaf parameter within the CLI container or rpc input section, that is used as the default if no parameter name  is entered.

This can be used in addition to ncx:default-parm to allow an equals sign '=' in the default parm string value.

This option is quite risky because any unrecognized parameter without any prefix (- or --) will be tried as the default parameter type, instead of catching the unknown parameter error.  This includes strings containing an equals sign, so an unknown parameter error will never be generated.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

           rpc foo {

             input {

               ncx:default-parm a;

               ncx:default-parm-equals-ok;

               leaf a { type string; }

               leaf b { type int32; }

             }

           }

 

           yangcli> foo bogus-parm=fred

 

      This will interpreted as if parameter 'a' were entered:

 

           yangcli> foo a='bogus-parm=fred'

 

 

14.5.10  ywx:get-filter-element-attributes

The ietf:get-filter-element-attributes extension is defined in ietf-netconf.yang.

This is a reserved extension name, used to define the  filter and type attributes used in the <get> operation. It cannot be used in other YANG modules.

 

14.5.11  ywx:exclusive-rpc

The ywx:exclusive-rpc extension is defined in yumaworks-extensions.yang.

It can be used within an rpc definition statement to indicate that the RPC is not allowed to be called    concurrently by different sessions.  The server will return an in-use error if another session is currently       invoking the RPC operation and this extension is present in the rpc-stmt.

 

 

           rpc reset-system {

              ywx:exclusive-rpc;

// only allow 1 session at a time to reset system

           }

 

 

14.5.12  ywx:help

The ywx:help extension is used to define a help text string for CLI.

It  can be defined within a rpc or data definition statement to provide a short help text string for CLI and other applications to use in addition to the description statement.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument:

Example:

 

 

  leaf mtu {

     ywx:help “Maximum transmission unit size”;

     type uint32;

     description “... long description …”;

  }

 

 

14.5.13  ncx:hidden

The ncx:hidden extension is used to prevent publication of a YANG data object. It will be ignored for typedefs and other constructs.  If present within a data object, that node and any sub-nodes will be ignored when generating HTML documentation or YANG output.

The yangdump-pro -f=copy mode is not be affected by this extension.

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

 container struct {

     ncx:hidden;

     ncx:abstract;

  }

 

 

14.5.14  ncx:metadata

The ncx:metadata extension is used to define an XML attribute to be associated with a data-def-stmt node.  Only optional metadata can be defined.  Errors for missing XML attributes (except as specified by the YANG language) will not be checked automatically.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument:

Example:

 

 

   container rpc-reply {

     description "Remote Procedure Call response message";

 

     reference "RFC 4741, section 4.2";

 

     uses RpcReplyType;

 

     // do not treat missing message-id as an error

     ncx:metadata  "MessageId message-id";

     ncx:abstract;

   }

 

 

14.5.15  ncx:no-duplicates

The ncx:no-duplicates extension is used to indicate that no duplicate values are allowed in an ncx:xsdlist leaf or leaf-list object.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

  leaf number-list {

     type string {

       ncx:xsdlist int32;

       ncx:no-duplicates;

     }

  }

 

  // the YANG string allowed is a whitespace-separated of numbers

  // and none of the numbers can be repeated

 

  <number-list>32 1 -6 103</number-list>

 

 

14.5.16  ncx:password

The ncx:password extension issed to indicate the data type for the leaf is really a password.  Only the encrypted version of the password is allowed to be generated in any output.

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

  leaf system-password {

    ncx:password;

    type string {

       length “8 .. 16”;

    }

  }

 

 

14.5.17  ncx:qname

The ncx:qname extension is used to indicate that the content of a data type is a Qualified Name.  This is needed to properly evaluate the namespace prefix, if used.

The qname extension may appear within the type-stmt, within a typedef, leaf, or leaf-list.  The builtin data type must be 'string', or the 'qname' extension will be ignored.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

  leaf bad-element {

    ncx:qname;

    type string;

  }

 

 

14.5.18  oc-ext:regexp-posix

The oc-ext:regexp-posix extension is used to indicate that the module uses Posix pattern statements instead of the XSD syntax defined in YANG. The openconfig-extensions module contains this extension. It is available from the openconfig github repository, and not included in the YumaPro SDK distribution.

 

The qname extension may appear as a body-stmt at the top-level of the module. It will be ignored otherwise.

If this extension is found then the module will be treated as an OpenConfig style module usingt Posix pattern statements.

This extension overrides the --with-ocpattern CLI parameter, so even if this parameter is false or the module does not begin with the string “openconfig-”, the Posix pattern syntax will be used.

 

YANG File: Not Available in YumaPro SDK

Argument: none

Example:

 

 

  module my-openconfig-ext {

     ….

 

     import openconfig-extensions { prefix oc-ext; }

 

     ….

 

     oc-ext:regexp-posix;

 

  }

 

 

14.5.19  ncx:root

The ncx:root extension is used within a container definition to indicate it is really a root container for a conceptual NETCONF database, instead of just an empty container.  This is needed for YumaPro to correctly process any RPC method that contains a 'config' parameter.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

  rpc my-edit {

    input {

      container my-config {

         ncx:root;

      }

    }

  }

 

 

 

14.5.20  ywx:rpc-root

The ywx:rpc-root extension is used  internally with the YANG-API protocol to identify a container definition to indicate it is really a root container for a conceptual NETCONF operations, instead of just a container.  The container is expected to be empty.  Any top-level rpc-stmt can be specified using a QName value with the same module and local name as the RPC operation definition.

This extension is reserved and only used internally by the server.

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

 

14.5.21  ncx:schema-instance

The ncx:schema-instance extension is used to indicate that the typedef or type statement for a string data type really identifies a special schema-instance node, not a generic string. A schema-instance value string is an unrestricted YANG instance-identifier expression.  All the same rules as an instance-identifier apply except:

This extension will be ignored unless it is present in the type-stmt of a typedef-stmt, leaf-stmt, or leaf-list-stmt, or directly within a leaf-stmt or leaf-list-stmt..

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

 leaf target {

   ncx:schema-instance;

   type string {

     length “1 .. max”;

   }

 }

 

 

 

14.5.22  nacm:secure

The nacm:secure extension is used to indicate that the data model node  represents a sensitive security system parameter.  It is equivalent to the IETF nacm:default-deny-write extension.  The IETF access control model is derived from the yuma-nacm module.

If present, the NETCONF server will only allow the designated 'superuser' to have write or execute default nacm-rights for the node.  An explicit access control rule is required for all other users.

The 'secure' extension may appear within a data, rpc, or notification node definition.  It is ignored otherwise.

This extension is obsolete and should not be used. Use nacm:default-deny-write instead.

 

YANG File: netconf/modules/netconfcentral/yuma-nacm.yang

Argument: none

Example:

 

 

 leaf mtu {

   nacm:secure;

   type string {

     length “1 .. max”;

   }

 }

 

 

14.5.23  ncx:sil-aio-get2

The ncx:sil-aio-get2 extension is used within a data definition statement to define the GET2 retrieval mechanism. This extension affects the descendant data nodes.

This extension can be used in a container or list to force the server to treat that data subtree as a All In One AIO node for GET2 callback.

The entire subtree would be expected in one retrieval in one callback invocation.

The entire subtree can be specified in the JSON or XML buffer that will be used for return values. The server will parse and handle the buffer and process retrieval based on the provide JSON or XML encoded buffer. The 'parmstr' argument can specify the encoding that will be used in the callback. Available options are:

If not specified default val value retrieval mechanism will be assumed.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: string (xml | json)

Example:

 

 

  /* All in One callback for Container with List */

  container get3-cont-list {            // All in One get2 CB

    ywx:sil-aio-get2 "json";

    config false;

 

    leaf D { type int8; }

 

    list nonconfig-list {               // No callback

      key name;

      leaf name { type string; }

      leaf not-keyname { type string; }

 

      container int-con {               // No callback

        leaf con-leaf { type int32; }

      }

    }

  }

 

 

14.5.24  ncx:sil-delete-children-first

The ncx:sil-delete-children-first extension is used within a container or list definition to indicate that the SIL callbacks for descendant nodes should be invoked first, when a data node instance of the object containing this extension is deleted.

Normally, the parent node is expected to delete all its own sub-structures when the SIL edit callback is invoked.  If this extension is present, then any SIL callbacks for any of the child nodes will be invoked first instead. If a child node is a list or a container, and it also contains an 'ncx:sil-delete-children-first' extension, then its children will be checked first.

The SIL edit callback will not be invoked for leaf, leaf-list, or anyxml descendant nodes in this mode. They will only will called if their parent node is not getting deleted.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

       container foo {

           ncx:sil-delete-children-first;

           list foos {

             ncx:sil-delete-children-first;

             key a;

             leaf a { type string; }

             container b {

               list c { ... }

             }

             leaf d { type empty; }

           }

         }

 

       In this example, assume node /foo gets deleted.

       Then the SIL edit callbacks would be done as follows:

 

       1) /foo/foos[a='n']/b   (called for row 'n' of /foo/foos)

       2) /foo/foos[a='n']     (called for row 'n' of /foo/foos)

       3) repeat (1,2) until all rows in /foo/foos are deleted

       4) /foo

 

     Note that the SIL edit callback is not done for list

     /foo/foos[a='n']/b/c because this extension is

     not present in container '/foo/foos/b'.

 

     Note that the SIL edit callback is not done for

     nodes /foo/foos[a='n']/a or /foo/foos[a='n']/d because

     they are leafs.

 

 

14.5.25  ywx:sil-force-replace-replay

The ywx:sil-force-replace-replay extension is used within a configuration data node definition statement to indicate that the SIL (or SIL-SA) callback should be invoked even for nodes that are not changing, during a replace operation.  All SIL callbacks for child nodes in the replace request (where the parent node contains  this extension) will be invoked during edit processing.  This extension can be used with the sil-force-replay extension.

If this extension is used within a list statement, then SIL callbacks for all instances of the list that are provided in the replace operation will be invoked.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: none

Example:

 

 

       container top {
        list bar {

           ywx:sil-force-replace-replay;

 

           key name;

           leaf name { type string; }

           leaf b { type int32; }

           leaf c { type int32; }

         }
      }

 

       Replace config:
      <config>
        <top nc:operation=”replace”>
          <bar>   // this entry is changing
            <name>fred</name>

             <b>22</b>

             <c>99</c>
          </bar>
          <bar>   // not changing but SIL will be called anyway
            <name>barney</name>

             <b>18</b>

             <c>82</c>
          </bar>
        </top>
      </config>

 

       In this example, all instances of /top/bar will get replaced.
      Normally the server will skip replacement of instances which
      are not changing at all.  If this extension is present, then
      the server will not skip any instances that are provided.

       Instead, the SIL edit callbacks would be done for these
      nodes as well. The 'newval' and 'curval' parameters will
      be the same for the replayed entries.

 

 

14.5.26  ywx:sil-force-replay

The ywx:sil-force-replay extension is used within a container or list definition to indicate that the SIL callbacks for all child nodes should be invoked when one of the child nodes is modified.

Normally, only the SIL callbacks for the child nodes that are changed are called during an edit transaction.  

If the parent node for the changed child node contains the “sil-force-replay” extension, then all the child node SIL callbacks will be invoked instead.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: none

Example:

 

 

       list foo {

           ywx:sil-force-replay;

           key a;

           leaf a { type string; }

           container b {

             list c { ... }

           }

           leaf d { type int32; }

           leaf e { type int32; }

       }

 

       In this example, assume node /foo/d gets modified.

       Then the SIL edit callbacks would be done for sibling nodes as well.
      The 'newval' and 'curval' parameters will be the same for the replayed
      sibling nodes.

 

       1) /foo/a

       2) /foo/b

       3) /foo/d

       4) /foo/e

 

 

14.5.27  ywx:sil-priority

The ywx:sil-priority extension is used within a configuration data node definition to set the SIL priority for an object.  The lower the number of the SIL priority, the higher priority it is assigned.  SIL callbacks are normally invoked in the order that the edits appear in the edit request.  If the sil-priority is set then the order SIL callbacks are invoked will be based on the numeric priority value instead.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: prio: number from 1 to 255

Example:

 

 

      "Used to control the order that SIL or SIL-SA callbacks

       are invoked for specific objects.

 

       If this extension is used within a configuration database

       object then the SIL priority for the object will be assigned

       the value of the 'prio' argument.

 

       Only the order of the 'apply', 'commit' and 'rollback'

       callback phases will be affected by this parameter.

       The 'validate' phase callbacks are invoked in the

       order they appear in the edit request.

 

       The 'prio' argument must be a number between 1 and 255.

       If two objects are edited in the same edit request, the

       the one with the lowest SIL priority number will be

       executed first.

 

       If no sil-priority is set, then the default value of

       '255' will be used instead.

 

       If the SIL priority is the same for two objects in the

       same edit request, then the server will pick an order

       in an implementation-specific manner.";

 

       leaf A1 {

         type string;

          ywx:sil-priority 30;

       }

 

       leaf A2 {

         type string;

         ywx:sil-priority 20;

       }

 

       leaf A3 {

        type string;

        ywx:sil-priority 10;

      }

 

 

14.5.28  ywx:sil-test-get-when

The ywx:sil-test-get-when extension is used within an operational data node definition to set thesil-get-test-when parameter setting for an object.  This parameter controls whether “when-stmt” expressions will be evaluated by the server. Normally the SIL or SIL-SA code is expected to check these conditions but the server can run the Xpath test during retrieval operations.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: boolval: boolean (true or false)

 

 

  extension sil-test-get-when {

    description

      "Used within a data definition statement to define

       the --sil-get-test-when CLI parameter behavior for

       a single object. This extension does not affect the

       descendant data nodes.

 

       The 'boolval' argument must be the string 'true'

       or 'false'; If 'true' the object will be tested

       for when-stmts if any need to be evaluated during

       retrieval operations. If 'false' then any when-stmts

       will be ignored during retrieval operations.

 

       This extension will override the --sil-test-get-when

       global CLI parameter. This extension will have no affect

       unless the value is different than this CLI parameter.

     ";

     argument boolval;

   }

 

 

Example:

 

 

  leaf myoperleaf {

    ywx:sil-test-get-when true;

    type string;

  }

 

 

14.5.29  ywx:urlpath

The ywx:urlpath extension is used to indicate that a string data node is really using the YANG-API URL path expression syntax.  It can be used within a leaf or leaf-list definition.

 

YANG File: netconf/modules/yumaworks/yumaworks-extensions.yang

Argument: none

Example:

 

 

  leaf restpath {

    ywx:urlpath;

    type string;

  }

 

  <restpath>/interfaces/interface/eth0/mtu</restpath>

 

 

14.5.30  ncx:user-write

The ncx:user-write extension is used within database configuration data definition statements to control user write access to the database object containing this statement.

The 'exceptions' argument is a list of operations that users are permitted to invoke for the specified node. These permissions will over-ride all NACM access control rules, even if NACM is disabled.

The following values are supported:

To dis-allow all user access, provide an empty string for the 'exceptions' argument (user-write '';)

To allow only create and delete user access, provide the string 'create delete' for the 'exceptions' parameter.

Use this for parameters that cannot be changed once they are set. Providing all 3 parameters has the same affect as not using this extension at all, but can be used anyway.

YANG leaf version:

 

 

     leaf user-write {

         type bits {

           bit create;

           bit update;

           bit delete;

         }

         default 'create update delete';

         description 'equivalent YANG definition';

       }

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument:

Example:

 

 

 container interfaces {

   ncx:user-write “update”;

   list physical-interface {

     ncx:user-write “update”;

     …

   }

 }

 

14.5.31  nacm:very-secure

The nacm:very-secure extension is used to indicate that the data model node  represents a sensitive security system parameter.  It is equivalent to the IETF nacm:default-deny-all extension.  The IETF access control model is derived from the yuma-nacm module.

If present, the NETCONF server will only allow the designated 'superuser' to have read, write, or execute nacm-rights for the node.  An explicit access control rule is required for all other users.

The 'very-secure' extension may appear within a data, rpc, or notification node definition.  It is ignored otherwise.

 

This extension is obsolete and should not be used. Use nacm:default-deny-all instead.

 

YANG File: netconf/modules/netconfcentral/yuma-nacm.yang

Argument: none

Example:

 

 

 leaf social-security-id {

   nacm:very-secure;

   type string {

     length “1 .. max”;

   }

 }

 

 

14.5.32  ncx:xpath

The ncx:xpath extension is used to indicate that the content of a data type is an XPath expression.  This is needed to properly evaluate the namespace prefixes within the expression.

 

       Note that this extension is deprecated.  Use the xpath1.0 data type found in ietf-yang-types.yang

 

The xpath extension may appear within the type-stmt, within a typedef, leaf, or leaf-list.  The builtin data type must be 'string', or the 'xpath' extension will be ignored.

All data using the 'instance-identifier' built-in type will automatically be processed as an XPath string, so the xpath extension is not needed in that case.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument: none

Example:

 

 

 leaf target {

   ncx:xpath;

   type string {

     length “1 .. max”;

   }

 }

 

 

14.5.33  ywx:xpath-operational-ok

The ywx:xpath-operational-ok extension is used to indicate that the “must” and “when” expressions within the indicated object are allowed to access config=false data nodes.

This extension is used within a data-definition statement for a configuration data node to alter the must-stmt and when-stmt found within the data node. This allows an XPath expression in such a node to reference config=false data nodes.

This property does not apply to any child nodes, just the data node containing this external statement.

This violates the standard in RFC 7950, sec 6.4.1 so use with caution since the YANG module will not be valid according to YANG 1.1 rules.

There is no parameter for this extension.

 

In the following example, the list “/c3/l3” has a when-stmt that accesses the /interrfaces-state subtree:

 

 

module mytest2 {

  namespace "urn:yumaworks:params:xml:ns:yang:mytest2";

  prefix "mt2";

  import ietf-interfaces { prefix if; }

  import yumaworks-extensions { prefix ywx; }

 

  revision 2019-12-06 {

  description

  "Initial version";

  }

 

  container c3 {

    list l3 {

      ywx:xpath-operational-ok;

      when "/if:interfaces-state/if:interface/if:speed > 1000";

      key "name";

      leaf name{type string;}

      leaf if-index {type int32;}

    }

  }

}

14.5.34  ncx:xsdlist

The ncx:xsdlist extension is used to indicate the leaf string type is really an XSD list, which is a series of whitespace separated token strings. The type argument represents the data type to use for the list members, for validation purposes. This extension is allowed to be present within the type sub-section for a string.

 

YANG File: netconf/modules/netconfcentral/yuma-ncx.yang

Argument:

Example:

 

 

 typedef MyEnumType {

   enum up;

   enum down;

   enum left;

   enum right;

 }

 

 leaf enum-list {

   ncx:xsdlist MyEnumType;

   type string;

 }

 

 <enum-list>up right down</enum-list>