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.

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.

Warning

This extension is not compliant with YANG 1.1 It SHOULD NOT be used. Use the sx:structure extension instead.

YANG File: 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;
}

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.

Argument:
  • name: alternate YANG identifier name string to use for the object

Example:

leaf system-reset-time {
  ywx:alt-name last-reset;
  type yang:date-and-time;
  config false;
}

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:

  • leaf

  • leaf-list

  • choice

  • case

  • uses (if resolves to only the allowed node types)

Note

This is an internal extension and should not be used.

YANG File: yuma-ncx.yang
Argument: none
Example:
container yangcli-pro {
   ncx:cli;
   // leafs and choices of leafs inserted here
}

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.

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'
}

ywx:confirm-data

The ywx:confirm-data extension is used by the yangcli-pro and yp-shell programs to identify a Confirmed Parameter.

Used within a configuration leaf data node or input node definition statement to indicate that the data node should be confirmed by the user.

leaf email {
   ywx:confirm-data;
   type string;
   mandatory true;
}

The user must enter the same string as the first string to confirm the parameter.

  • Supported by yangcli-pro and yp-shell, starting 23.10-8.

  • This parameter only applies to interactive mode.

  • The parameters must be entered one at a time instead of all at once.

  • This parameter does not apply to config mode.

The CLI parameter --confirm-data-retries specifies the number of retries the user will get before giving up and canceling the command in progress.

The user can use escape sequences to skip the parameter instead of confirming or waiting for the maximum number of retries.

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.

It is 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 YANG parser will use the datapath attribute to select the object template to use for parsing, instead of generic anyxml.

Argument: path string
Example:
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.yang module.

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

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. It is defined in RFC 8341.

If present, and the NACM module is enabled (E.g., /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.

Argument: none
Example:
rpc shutdown {
    nacm:default-deny-all;
}

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. It is defined in RFC 8341.

If present, and the NACM module is enabled (E.g., /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.

Argument: none
Example:
leaf enable-system {
    nacm:default-deny-write;
    type boolean;
}

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: yuma-ncx.yang
Argument:
  • parm: name of the leaf to use as the default parameter

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;
      }
    }
 }

The "server" parameter does not need a keyword when used in yangcli-pro:

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

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: 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; }
  }
}

The "a" parameter can be entered without a keyword as "name=value"

yangcli> foo bogus-parm=fred

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

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

ywx:errmsg

The ywx:errmsg extension is used within a data node statement to define a custom error-message filed within an 'rpc-error' or 'error' structure for some or all error conditions.

The string format is restricted to plain text with the exception of the 2 character sequence '%s'. This special sequence will be replaced in the dynamic error message generation if an errmsg-parm statement is found to match the escape sequence.

  • If this extension statement has no sub-statements, then it matches all errors for the object.

  • If ywx:errmsg-tag sub-statements are found, then this entry will match only those error-tag values.

  • If ywx:errmsg-apptag sub-statements are found, then this entry will match only those error-app-tag values.

The 'basestr' argument must be a formatted string. If any parameters are specified, then the corresponding ywx:errmsg-parm extension statements must be encoded within this errmsg statement.

Multiple errmsg statements can be present in the same data node statement. They will be processed in order and the first matching statement will be used to generate the error-message value.

Argument: basestr
Example:
leaf my-network-id {
  type int32;
  ywx:errmsg 'Not a valid network ID for interface %s' {
    ywx:errmsg-parm '../../if:name';
    ywx:errmsg-apptag 'network-error';
  }
}

ywx:errmsg-apptag

The ywx:errmsg-apptag extension is used within a ywx:errmsg statement to define error-app-tag value that will filter this errmsg.

Multiple ywx:errmsg-tag and/or 'errmsg-apptag' values form a conceptual OR expression.

The 'apptagstr' argument must be the error-app-tag value that will be matched.

Argument: apptagstr
Example:
leaf test2 {
  must "../test1 != 8" {
    ywx:errmsg "The test1 value '%s' is not allowed if test2 is '%s'" {
       ywx:errmsg-parm "../test1";
       ywx:errmsg-parm ".";
       ywx:errmsg-apptag "must-violation";
    }
  }

ywx:errmsg-lang

The ywx:errmsg-lang extension is used within a ywx:errmsg statement to define the language code value that will filter this errmsg.

  • This extension is used to define Dynamic Error Messages.

  • Only one errmsg-lang statement may appear within an errmsg statement.

  • The 'langstr' value will be compared to the --errmsg-lang CLI variable setting. If the strings are the same, the entry is used.

  • If this statement is not present, then the errmsg entry will be used regardless of the 'errmsg-lang' CLI variable setting.

  • The 'langstr' argument must be the language code value that will be matched.

Refer to the Multi-Language Error Messages section for more details.

Argument: langstr
Example:
leaf myleaf {
  ywx:errmsg "mauvais type de données" {
    ywx:errmsg-apptag "syntax-error";
    ywx:errmsg-lang "fr";
  }
  type string;
}

ywx:errmsg-parm

The ywx:errmsg-parm extension is used within a ywx:errmsg statement to define a parameter for expansion within the errmsg basestr.

  • This extension is used to define Dynamic Error Messages.

  • There should be the correct number of expected parameters for the corresponding 'basestr' format string.

The 'parmstr' argument must be an XPath path expression.

  • The context node will be the data node containing the errmsg statement.

Argument: parmstr
Example:
leaf my-network-id {
  type int32;
  ywx:errmsg 'Not a valid network ID for interface %s' {
    ywx:errmsg-parm '../../if:name';
    ywx:errmsg-apptag 'network-error';
  }
}

ywx:errmsg-tag

The ywx:errmsg-tag extension is used within a ywx:errmsg statement to define the error-tag value that will filter this errmsg.

  • This extension is used to define Dynamic Error Messages.

  • Multiple errmsg-tag and/or errmsg-apptag values form a conceptual OR expression.

The 'tagstr' argument must be the error-tag value that will be matched.

Argument: parmstr
Example:
list list1 {
  key a;
  leaf a { type string; }
  leaf b { type int32; }
  leaf test1 {
    ywx:errmsg "The value '%s' is invalid for the %s list entry" {
      ywx:errmsg-parm ".";
      ywx:errmsg-parm "../a";
      ywx:errmsg-tag "invalid-value";
    }
    type int8;
  }
}

ywx:exclusive-rpc

The ywx:exclusive-rpc extension is used to force "1 at a time" access to an RPC operation.

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.

Argument: none
Example:
rpc reset-system {
    ywx:exclusive-rpc;
    // only allow 1 session at a time to reset system
}

ywx:get-filter-element-attributes

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

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.

Argument: none

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.

Argument:
  • helptext: The help text string which should be 60 characters or less in length.

Example:

leaf mtu {
    ywx:help “Maximum transmission unit size”;
    type uint32;
    description “... long description …”;
}

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 --format=copy mode is not be affected by this extension.

YANG File: yuma-ncx.yang
Argument: none
Example:
container struct {
    ncx:hidden;
    ncx:abstract;
}

ywx:hidden-from-cli

The ywx:hidden-from-cli extension is used to prevent publication of a YANG data object, but only affecting the CLI interface. If present within a data object, that node and any sub-nodes will be ignored when prompting for input nodes from the client.

This extension is ignored if the ncx:hidden extension is set for the same object.

Argument: none
Example:
leaf internal-param {
    ywx:hidden-from-cli;
    type string;
}

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: yuma-ncx.yang
Argument:
  • syntax-string: syntax of the meta-data attribute The syntax string has the following format:

    [prefix:]typename attribute-name
    

    Any YANG typedef of builtin type can be specified as the type name, except 'empty'.

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;
}

ncx:no-duplicates

Warning

The "xsdlist" data type is not supported in YANG. Do not use this extension.

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: yuma-ncx.yang
Argument: none
Example:
leaf number-list {
    type string {
        ncx:xsdlist int32;
        ncx:no-duplicates;
    }
}
<number-list>32 1 -6 103</number-list>

ncx:no-nvstore

The ncx:no-nvstore extension is used within a configuration data node definition statement to indicate that configuration changes made to the object will not be stored in non-volatile storage.

  • The configuration node will be handled in an implementation-specific manner.

  • There is no argument defined for this extension.

  • The extension applies to the specified node and all its descendants.

YANG File: yuma-ncx.yang
Argument: none
Example: (from yumaworks-server.yang)
container server {
  description
    "Runtime access to netconfd-pro CLI parameters for
     immediate change or activate-on-restart";
  nacm:default-deny-all;
  ywx:no-nvstore;
  uses ndpro:netconfd-pro-parms;
}

ncx:no-sil-delete-children-first

The ncx:no-sil-delete-children-first extension is used within a configuration data node definition statement to indicate that the --sil-delete-children-first parameter should be ignored for this subtree, if it is set to 'true'.

Faster server performance can be achieved by deleting an entire subtree at once, and this extension allows the developer to force this behavior for the selected SIL libraries that can support such deletion.

  • This is the opposite of the ncx:sil-delete-children-first extension.

  • This extension applies to the entire subtree, not just the node that contains this extension.

  • There are no parameters defined.

YANG File: yuma-ncx.yang
Argument: none
Example:
container topcon {
   list child-list {
     ncx:no-sil-delete-children-first;
     key "A";
     description
       "All nodes will be deleted at once if 'topcon' is deleted.";
     leaf A { type string; }
     container level3 {
       description
         "This container will not be deleted first if 'child-list'
          or 'topcon' is deleted.";
     }
   }
}

ncx:password

Warning

This extension is NOT SECURE. Use the "crypt-hash" data type from iana-crypt-hash.yang instead for secure password configuration.

The ncx:password extension is used 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: yuma-ncx.yang
Argument: none
Example:
leaf system-password {
    ncx:password;
    type string {
        length “8 .. 16”;
    }
}

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: yuma-ncx.yang
Argument: none
Example:
leaf bad-element {
    ncx:qname;
    type string;
}

oc-ext:openconfig-hashed-value

The oc-ext:openconfig-hashed-value extension is used to indicate that the leaf or leaf-list contains an openconfig hashed password string.

  • 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 sub-statement of a leaf or leaf-list statement. It will be ignored otherwise.

  • If this extension is found then the leaf or leaf-list will be treated as an OpenConfig Hashed Value:

  • value passed by client is a cleartext password

    • It is not a crypt-hash beginning with the prefix “$0$”

  • server immediately converts the cleartext to a hash

  • Only the hash value is ever returned to a client in a data retrieval operation

  • Only the hash value is stored in NV-storage (E.g., startup-cfg.xml)

YANG File: Not Available in YumaPro SDK
Argument: none
Example:
module test-ochash {
    yang-version 1.1;
    namespace "http://netconfcentral.org/ns/test-ochash";
    prefix toch;
    import openconfig-extensions { prefix oc-ext; }

    revision 2021-02-26;

    container octop {
      leaf ochash {
        type string;
        oc-ext:openconfig-hashed-value;
      }
    }
}

Example: Set the ochash leaf to the value ‘this is a test’

Note the value is passed as a string (highlighted below)

Incoming msg for session 3

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <octop xmlns="http://netconfcentral.org/ns/test-ochash">
    <ochash
     xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
     nc:operation="merge">this is a test</ochash>
   </octop>
  </config>
 </edit-config>
</rpc>

If logging is enabled a similar log trace should be present to this example:

agt_crypt: altering openconfig-hashed-value value from cleartext to
  '$6$PE1fq4I22dYjomxn$' for node 'ochash'

If the data is retrieved (E.g., get-config from <candidate>) then the hashed value will be returned.

The server never stores the original plaintext version and it cannot be retrieved from the server at all.

<data>
  <octop xmlns="http://netconfcentral.org/ns/test-ochash">
    <ochash>$6$PE1fq4I22dYjomxn$E60QUJiDIB6uZ.cx7WbsWATrs/.2Zp8NROf7SW3VnSrM4ZrTBlJUHbjtxxMb/hFcPxgdxZOQdzzKNRWiX6AF2/</ochash>
  </octop>
</data>

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 using 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;

}

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: yuma-ncx.yang
Argument: none
Example:
rpc my-edit {
    input {
        container my-config {
            ncx:root;
        }
    }
}

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.

Argument: none

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:

    • Predicates for keys are optional.

    • The dataRule will apply to all instance of any missing key leaf predicate.

  • 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: yuma-ncx.yang
Argument: none
Example:
leaf target {
    ncx:schema-instance;
    type string {
        length “1 .. max;
    }
}

nacm:secure

Warning

This extension is obsolete! Use nacm:default-deny-write instead.

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.

YANG File: yuma-nacm.yang
Argument: none
Example:
leaf my-leaf {
    nacm:secure;
    type string {
        length “1 .. max;
    }
}

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 provided JSON or XML encoded buffer.

  • The 'parmstr' argument can specify the encoding that will be used in the callback. Available options are:*

    • val: val_value_t tree is expected in return value

    • xml: XML element in a buffer is expected in return value

    • json: JSON object in a buffer is expected in return value

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

Argument:
  • string (val | 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; }
     }
   }
 }

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 this 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: 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 { type string; }
       }
       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.

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 ywx: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.

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 example:

<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.

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.

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.

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.

  • 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.

Argument:
  • prio: number from 1 to 255

Example:

 leaf A1 {
   type string;
    ywx:sil-priority 30;
 }

 leaf A2 {
   type string;
   ywx:sil-priority 20;
 }

 leaf A3 {
  type string;
  ywx:sil-priority 10;
}

ywx:sil-test-get-when

The ywx:sil-test-get-when extension is used within an operational data node definition to set the --sil-test-get-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.

  • Used within a data definition statement to define the --sil-test-get-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: (true or false)

Example:

leaf myoperleaf {
    ywx:sil-test-get-when true;
    type string;
}

ywx:sil-xpath-function

The ywx:sil-xpath-function extension is used within a configuration data node definition statement to define the YANG XPath Callback function for the object.

Note

  • This extension is only used by the yangdump-pro for SIL code generation.

  • There must be a function registered to use the XPath Callback.

  • First Available in 22.10T-8

It can also be added to a node using an annotation. This extension affects only the node containing the extension. The following data nodes are supported:

  • container

  • list

  • leaf

  • leaf-list

  • anydata

  • anyxml

Other data definition statements are allowed to have must or when statements but the context node will be one of the types listed above. The callback function is invoked any time the data node containing this extension is used as the context node for a must/when XPath evaluation.

This callback can be used to replace real must/when XPath expression evaluation, in case the constraint is enforced by the SIL code or can be checked internally by the SIL code. It is intended to speed up or prune XPath evaluation for a data node object.

The 'parmstr' argument must be present, and contain the callback function name to be used in the SIL code generation by yangdump-pro. This function is expected to exist and be present in the H files included by the SIL code module.

If the 'parmstr' argument contains the special value 'default', then an XPath callback function will be generated using the identifier assigned to that data node. This stub function will return 'ERR_NCX_SKIPPED' by default. It must be completed by a programmer in order to have any affect.

The callback function must conform to the 'xpath_bool_eval_fn_t' typedef defined in ncx/xpath.h.

Argument:
  • parmstr: (function name or 'default')

Example:

leaf foo {
  ywx:sil-xpath-function 'foo_xpath_callback';
  type string;
  must 'some expr';
}

This annotation should not be used directly. Instead, an annotation module using the 'deviation' stmt should be used to add this property. The --deviation parameter should be passed to the SIL code generation script.

deviation "/bbf-l2-fwd:forwarding/bbf-l2-fwd:forwarders"
  + "/bbf-l2-fwd:forwarder/bbf-l2-fwd:ports/bbf-l2-fwd:port"
  + "/bbf-l2-fwd:sub-interface" {

  deviate add {
    ywx:sil-xpath-function "agt_xpath_force_true";
  }

}

ywx:sort-type

The ywx:sort-type extension is used within a configuration data node definition statement to define the System Ordered Sort Type for the object.

It can also be added to a node using an annotation. This extension affects only the node containing the extension. The following data nodes are supported:

  • list

  • leaf-list

This extension only applies to ordered-by 'system' data nodes.

Introduced in 23.10-6.

This extension is ignored if the --system-sorted CLI parameter is set to 'false'. Otherwise this extension will override the --system-sort-type CLI parameter value.

The 'parmstr' argument is a string with the same values as the --system-sort-type parameter:

  • off

  • ascending

  • descending

Argument: parmstr
Examples:
leaf-list path {
    ywx:sort-type ascending;
    type string;
}

list foo {
    ywx:sort-type 'descending';
    // ...
}

deviation "/ex:example/ex:list" {
    deviate add {
        ywx:sort-type off;
    }
}

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.

Argument: none
Example:
leaf restpath {
    ywx:urlpath;
    type string;
}

Example XML Usage:

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

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 override all NACM access control rules, even if NACM is disabled.

  • This extension does not apply to descendant nodes!

  • This extension has no effect if config-stmt is false!

The following values are supported:

  • create: allow users to create instances of the object

  • update : allow users to modify instances of the object

  • delete : allow users to delete instances of the object

  • 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.

Equivalent YANG leaf for this extension:

leaf user-write {
    type bits {
      bit create;
      bit update;
      bit delete;
    }
    default 'create update delete';
    description 'equivalent YANG definition';
  }
YANG File: yuma-ncx.yang
Argument:
  • exceptions: the list of operations to permit for the data node. The YANG bits definition shown above defines the syntax for the exceptions string.

Example:

container interfaces {
    ncx:user-write “update”;
    list physical-interface {
        ncx:user-write “update”;
        // ... more fields
    }
}

nacm:very-secure

Warning

This extension is obsolete! Use the nacm:default-deny-all extension instead.

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.yang module.

  • If present, the NETCONF server will only allow a designated 'superuser' account 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.

YANG File: yuma-nacm.yang
Argument: none
Example:
leaf social-security-id {
    nacm:very-secure;
    type string {
        length “1 .. max;
    }
}

ncx:xpath

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

Note

This extension is deprecated. Use the xpath1.0 data type found in ietf-yang-types.yang instead.

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: yuma-ncx.yang
Argument: none
Example:
leaf target {
    ncx:xpath;
    type string {
        length “1 .. max;
    }
}

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.

  • There is no parameter for this extension.

Warning

Use of this extension 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.

Argument: none
Example:

In the following example, the list “/c3/l3” has a when-stmt that accesses the /interfaces-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;}
    }
  }
}

ncx:xsdlist

The ncx:xsdlist extension is used to indicate the leaf string type is really an XSD list, which is a series of white space 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.

Warning

This non-standard extension should not be used. Use the 'bits' data type instead.

YANG File: yuma-ncx.yang
Argument:
  • type: name of the data type to use for list members

Example:

typedef MyEnumType {
  enum up;
  enum down;
  enum left;
  enum right;
}

leaf enum-list {
  ncx:xsdlist MyEnumType;
  type string;
}

Example XML Usage:

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