Default Node Handling

The handling of a 'default' node is somewhat complex. There are some standards, CLI parameters, and protocol operation parameters that affect server behavior.

Default Data Node Definition

The YANG language contains a 'default-stmt'. This is called a schema-default. For example, RFC 7950#section-7.6.4 specifies the behavior for a default leaf node.

Note

The YANG default is the value used if the leaf (or leaf-list) is not present.
The standards are not clear wrt/ whether 'present' means 'provided by a client'.

Default Leaf or Leaf-List

Within the netconfd-pro server, a default leaf or leaf-list node is defined to follow the 'With-defaults Capability for NETCONF' (RFC 6243)

The --default-style CLI parameter is used to select the default handling behavior the server will follow.

If not set, then the 'explicit' mode will be used.
If set to 'report-all' then all default nodes are treated as real nodes. If this mode is used then it is as if all retrieval operations use with-defaults='report-all', unless that parameter is actually provided.

Default NP Container

An empty non-presence container has no meaning in NETCONF/YANG so it may be created by the server or not. It is an implementation choice. All clients must be capable of receiving empty NP containers in a response.

A 'Default NP Container' is an NP container that has at least one child node with a schema default defined. This default node can also be nested within additional empty NP containers.

Example: The 'enabled' leaf makes the 'npcon1' container a Default NP Container.

container npcon1 {
  leaf name {
    type string;
  }
  leaf enabled {
    type boolean;
    default true;
  }
}

The 'default' property of an NP-container is passed to its parent, same as other properties.

Example: The 'npcon2' container is also a Default NP Container due to the 'timeout' leaf.

container npcon2 {
  container npcon-child {
    leaf timeout {
      type uint8;
      units "seconds";
      default 10;
    }
  }
}

The --default-style CLI parameter will affect whether default NP containers are returned in retrieval operations.

If set to 'report-all' then Default NP containers will always be returned.
Otherwise Default NP Containers will only be returned if the with-defaults' parameter is set to 'report-all' or 'report-all-tagged'

Empty NP Container

An Empty NP Container has the following properties:

A configuration NP container
Not a Default NP Container
No configuration child nodes are present in the datastore expect possibly nested empty NP containers.
There are no read-only (config=false) child nodes defined

If the ancestor configuration nodes for a read-only data node are not present then that node will not be returned, and no GET2 callbacks will be invoked for the object. If these ancestor nodes are NP containers, then they are normally created by the server.

The server usually creates these empty NP containers when configuration is added to the 'candidate' or 'running' datastore.

This usually applies when the parent of the Empty NP Container is created.

These NP containers are returned to clients in retrieval operations under two conditions:

Client uses the 'with-defaults' parameter set to 'report-all' or 'report-all-tagged'
Server is configured with --default-style='report-all'

Starting in release 23.10-6, the server can be configured so these empty NP containers are not returned to clients at all. The --return-empty-npcontainers parameter should be set to 'false' to prune empty configuration NP containers in responses to clients.

Note

The default behavior is to return empty NP containers for backward-compatibility.
Set --return-empty-npcontainers='false' instead of setting --create-empty-npcontainers to 'false'

Example: <get-config> operation with server using default setting 'true'.

The highlighted parts are empty NP containers.

 andy@localhost> get-config source=candidate with-defaults=report-all

 RPC Data Reply 4 for session 3 [default]:

 rpc-reply {
   data {
     event-streams {
     }
     nacm {
       enable-nacm true
       read-default permit
       write-default deny
       exec-default permit
       enable-external-groups true
       groups {
       }
     }
     templates {
     }
   }
 }

Example: <get-config> operation with server using setting 'false'.

The empty NP containers are not returned by the server.
The '/nacm' container is returned because it has default child nodes, but the '/nacm/groups' container is not returned.

andy@localhost> get-config source=candidate with-defaults=report-all

RPC Data Reply 3 for session 3 [default]:

rpc-reply {
  data {
    nacm {
      enable-nacm true
      read-default permit
      write-default deny
      exec-default permit
      enable-external-groups true
    }
  }
}

For backwards compatibility for some deployments, there are two CLI parameters to control creation of these data nodes within the configuration.

The --create-empty-npcontainers CLI parameter can be set to 'false' to disable creation of Empty NP Containers in every case. This parameter is deprecated and should not be used.
The --create-empty-npcontainers-ro CLI parameter can be set to 'true' to disable creation of Empty NP Containers in every case except if the NP container has read-only child nodes. This parameter is deprecated and should not be used.
Refer to the Empty NP Container Example section for more details.