../_images/logo.png

YumaPro Quickstart Guide

Introduction

../_images/yumapro_tools.png

Refer to the YumaPro User Manual for a complete introduction to YumaPro Tools.

This section focuses on the client and server tools within the YumaPro Tools programs.

Intended Audience

This document is intended for users of the YumaPro Client and Server package programs. It covers the basic usage of the yangcli-pro client application and the netconfd-pro server.

What is NETCONF and YANG?

The YumaPro Tools suite provides automated support for development and usage of network management information. Information is exchanged in XML encoding within a session between a client and a server.

The "Network Configuration Protocol" (NETCONF) is defined in RFC 6241. It is used to provide the management sessions, operations, and database framework available on the server.

The operations, notifications, and the database contents supported by a particular NETCONF server are extensible, and defined with a modular and easy-to-learn language called YANG (RFC 7950). The database is used to contain YANG data structures which represent the configuration of the device containing the NETCONF server.

YANG is used to define the syntax and semantics of the NETCONF operations, notification events, and database content. Machine and human readable semantics and constraints are used by YANG tools (including YumaPro Tools) to automate behavior within the NETCONF protocol for clients and servers.

How Does an Operator Use NETCONF and YANG?

An operator uses a NETCONF session almost like it was a CLI session, except there are structured, schema-defined requests and responses, encoded in XML. YANG modules are like MIB modules for hierarchical content.

The NETCONF protocol is available for SSH and TLS transports. Using NETCONF over SSH is just like using CLI over SSH to manage a networking device, except the messages are exchanged in XML, not plain-text.

NETCONF is designed to provide a programmatic interface, so it is usually used with a management application, instead of a direct SSH terminal application. The yangcli-pro program within YumaPro Tools is a YANG-driven NETCONF client application that supports scripts, XPath, and many automated features to simplify management of NETCONF servers.

Once a session is started, similar to a CLI session, the operator issues commands (NETCONF operations) to the server, and the server performs each requested operation in order, and returns a status message and/or some data to the client.

How Does a Developer Use NETCONF and YANG?

A NETCONF server developer decides what modules need to be supported by the NETCONF server, and implements the device instrumentation code for those modules.

Much of the NETCONF protocol related code is handled by the NETCONF stack, based on the YANG module contents. Therefore, the most important task for a developer is designing a good YANG module.

After the YANG module is written, the yangdump-pro program can be used to generate the template C code for the server instrumentation library for the YANG module. The device instrumentation code for the YANG module is then added by the developer. This 'callback code' is invoked by the server when database operation requests for the object(s) in the YANG module are received from a client.

Once this library is completed, the YANG module and its binary server instrumentation library (SIL) can be loaded into the NETCONF server at boot-time or run-time.

Once the YANG module is completed, it needs be published, so operators and application developers can use the module information to manage the server.

Using the YumaPro Doxygen Browser

It is strongly recommended that developers use the supplied doxygen HTML documentation to learn the YumaPro APIs and access additional technical support resources. Doxygen is supported both online and can also be generated on a local machine if an SDK package or source code package is installed.

The SIL and SIL-SA code generated by yangdump-pro now has built-in doxygen browser support.

Refer the the YumaPro Doxygen Browser section for more details.

Getting Started with toaster.yang

This section will demonstrate the basic operation of YumaPro Tools to use a NETCONF session to manage a remote device with a YANG data model. The YumaPro Tools programs and libraries must already be installed. Refer to the YumaPro Installation Guide if this has not yet been done.

The yangcli-pro client program and netconfd-pro server program do not need to be installed on the same machine. Usually, they are not installed on the same machine. For simplicity, the server address 'localhost' is used in the examples below.

Libtoaster Fast Start:

This command summary is explained in depth in the rest of this section.

  1. Start the server with your user as the superuser

    /usr/sbin/netconfd-pro --superuser=<username>
    
  2. Start yangcli-pro

    /usr/bin/yangcli-pro
    
  3. yangcli-pro commands to the server

      connect server=localhost user=<username> password=<password>
      create-subscription
      load toaster
      mgrload toaster
      make-toast  # (will fail)
      get-locks
      create /toaster
      save
      release-locks
    . sget /toaster
      xget /toaster
      make-toast toasterDoneness=4 toasterToastType=toast:frozen-waffle
      cancel-toast
      close-session
    

What is libtoaster?

There is a sample server instrumentation library (SIL) included, named libtoaster. This is the module-specific server instrumentation code for the management data defined in toaster.yang. This is based on the original TOASTER-MIB by Epilogue. This YANG module provides simple operations to make toast, and some simple NETCONF database objects to enable and monitor the toaster.

The new YANG version of the TOASTER-MIB is different is some ways:

  • Extensible YANG identities are use to identify the bread type, instead of a hard-wired enumerated list.

  • Protocol operations (<make-toast> and <cancel-toast>) are instead of an 'up/down' switch within the database. NETCONF databases are intended to contain persistent data structures, and 'actions' such as starting or stopping the toaster are done with new protocol operations, instead of editing the database with the standard operations.

  • A simple configuration 'presence container' object is used to enable and disable the toaster service, instead of hard-wiring the toaster service availability.

  • A notification is generated when the toast is done or canceled. This notification can be used instead of polling the toaster status object.

Start the netconfd-pro server

If the netconfd-pro server is already running, then skip this section.

In order for NETCONF sessions to be enabled, the SSH server and the netconf-subsystem-pro programs must be properly installed first.

Start the yangcli-pro Client

Once the NETCONF server is running, it will accept client sessions If running netconfd-pro interactively on localhost, then start a new terminal window to continue.

The yangcli-pro program should be in found in the PATH environment variable.

  • Refer to the yangcli-pro Introduction section for details on setting up the client configuration.

  • Refer to the Starting yangcli-pro section for details on starting the yangcli-pro program.

  • Refer to the Stopping yangcli-pro section for more details on stopping the yangcli-pro program.

  • Refer to the Command Line Editing section for more details on using the yangcli-pro command line

  • Refer to the help command section for more details on getting help

Start a NETCONF session

Each yangcli-pro program instance can run multiple NETCONF sessions at a time. The interactive command line context can only be applied to one session at a time. This is called the "current session".

If no session is currently active, then the prompt will contain just the program name, indicating that the 'connect' command is available:

yangcli-pro>

The connect Command

The connect command is used to start a NETCONF session.

There are 3 mandatory parameters for this command:

  • user: the system (or SSH) user name to use

  • server: the IP address or DNS name of the NETCONF server to use

  • password: the password string to use

Make sure you have a user name and password already configured on the NETCONF server.

  • Change 'guest' to the real user-name.

  • Change 'yangrocks' to the real password

yangcli-pro> connect server=localhost user=guest password=yangrocks

After this command is entered, yangcli-pro will generate some informational log messages to the screen.

If the session is started successfully, a summary of the server session capabilities and available modules should be displayed. Also, the command prompt will change to indicate that a NETCONF session is currently active.

guest@localhost>

At this point any command supported by the server can be entered, in addition to any yangcli-pro command (except 'connect').

Fixing Connection Problems

If the session did not start correctly, check the error messages to fix the problem. Some common problems:

  • Make sure the netconfd-pro program is running.

  • Make sure the netconf-subsystem-pro program is properly installed.

  • Check if the SSH configuration contains the portion for NETCONF.

  • If the SSH configuration looks correct, then try restarting the SSH server to make sure that configuration file is the one being used.

  • If the SSH server seems to be running correctly, then check if any firewall or other security mechanism is blocking TCP port 830. If so, either enable TCP port 830, or enable port 22 on the NETCONF server (by restarting the server), and include 'port=22' in the 'connect' command parameters.

  • If no firewall or other security measure is blocking TCP port 830, try to establish a normal SSH session with the server.

  • If a normal SSH session works correctly, then check the log messages on the NETCONF server for more information.

Enable Notification Delivery

In order to receive the 'toastDone' notification event, a notification subscription has to be enabled.

A default NETCONF notification stream can be started with the create-subscription command:

guest@localhost> create-subscription

RPC OK Reply 2 for session 1:

guest@localhost>

Depending on other activity within the NETCONF server, it is possible other notification events, such as <netconf-session-start> Event or <netconf-session-end> Event will be generated. Notifications are displayed in their entirety, but not during 'rpc reply output'. If a command is being entered, the notification will be displayed, and then the command line restored.

Load the Toaster Module

The toaster module is not a core system module, and is not available automatically.

The module has to be explicitly loaded by the NETCONF client.

To load the server-supported version of the toaster module, use the 'load' command:

guest@localhost> load toaster

Incoming notification for session 2 [default]:
notification {
  eventTime 2022-01-26T00:31:58Z
  yang-library-change {
    module-set-id 4695
  }
}

Load module 'toaster' revision '2009-11-20' OK

Incoming notification for session 2 [default]:
notification {
  eventTime 2022-01-26T00:31:58Z
  netconf-capability-change {
    changed-by {
      username andy
      session-id 3
      source-host 127.0.0.1
    }
    added-capability http://netconfcentral.org/ns/toaster?module=toaster&revision=2009-11-20
  }
}

guest@localhost>

If the module was successfully loaded, then a data response will be sent, containing the revision date of the toaster module that was loaded. This response will be returned even if the module was already loaded.

Note that the <yang-library-change> Event and <netconf-capability-change> Event notification events will only be sent if the module has not already been loaded into the server.

Since the server did not advertise the 'toaster' module, yangcli-pro does not have it loaded yet. This module needs to be loaded manually into yangcli-pro with the mgrload command:

guest@localhost> mgrload toaster

Load module 'toaster' OK

guest@localhost>

Enable the Toaster

Try to make some toast, using the 'make-toast' command:

guest@localhost> make-toast

RPC Error Reply 4 for session 1:

rpc-reply {
   rpc-error {
      error-type protocol
      error-tag resource-denied
      error-severity error
      error-app-tag no-access
      error-message 'resource denied'
      error-info {
         error-number 269
      }
   }
}

guest@localhost>

What happened?

A 'resource-denied' error was returned instead of 'OK', because the toaster service is not enabled yet. A node has to be created in the NETCONF database before the 'make-toast' command can be used.

Lock the Databases

The first step is to lock the NETCONF databases for writing. Locks do not affect read operations.

The yangcli-pro program has a high-level command to deal with locking, called get-locks. It will handle retries for any missing locks, until an overall timeout occurs or all the locks needed are acquired.

guest@localhost> get-locks

Sending <lock> operations for get-locks...

get-locks finished OK

guest@localhost>

Create the toaster Container

The toaster module uses a simple YANG 'presence' container to configure the toaster service.

Once the /toaster container is created, the read-only nodes within that container will be maintained by the server, and the toaster service will be enabled.

The first step is to create the /toaster node in the <candidate> configuration database:

guest@localhost> create /toaster

Filling container /toaster:

RPC OK Reply 5 for session 1:

guest@localhost>

Now the /toaster node is created in the <candidate> database.

Save the Database Changes

In order to activate these changes, the save command needs to be issued.

This is a high-level yangcli-pro operation that issues the commit or copy-config commands, depending on the database target for the current session.

guest@localhost> save

Saving configuration to non-volatile storage
RPC OK Reply 6 for session 1:

Incoming notification for session 2 [default]:
notification {
  eventTime 2022-01-26T00:36:28Z
  netconf-config-change {
    changed-by {
      username andy
      session-id 3
      source-host 127.0.0.1
    }
    datastore running
    edit {
      target /toast:toaster
      operation create
    }
  }
}

The 'RPC OK' message indicate that the server successfully saved the configuration.

The <netconf-config-change> Event notification indicates what was changed in the running configuration, and who made the change(s).

The toaster server should now be enabled.

Unlock the Databases

The database locks need to be released as soon as possible after the edits are completed or discarded.

The high-level command release-locks must be used if get-locks was used to acquire the database locks.

guest@localhost> release-locks

Sending <unlock> operations for release-locks...

guest@localhost>

Get the Toaster State Information

To discover the toaster model and its current status, the sget or xget commands can be used to retrieve just the toaster portion of the conceptual state data available on the server.

The sget command is high-level subtree filter handler for the <get> operation:

guest@localhost> sget /toaster

rpc-reply {
  data {
    toaster {
      toasterManufacturer 'Acme, Inc.'
      toasterModelNumber 'Super Toastamatic 2000'
      toasterStatus up
    }
  }
}

The xget command is high-level XPath filter handler for the <get> operation. It is only available if the NETCONF server supports the :xpath capability (like netconfd-pro).

guest@localhost> xget /toaster

rpc-reply {
  data {
    toaster {
      toasterManufacturer 'Acme, Inc.'
      toasterModelNumber 'Super Toastamatic 2000'
      toasterStatus up
    }
  }
}

Both commands should return the same data.

This data shows that the 'Super Toastamatic 2000' is ready to make toast!

Start Making Toast

Now that the toaster is enabled, the 'make-toast' command should work.

Instead of using the default parameter values, let's make a frozen waffle a little less done than normal:

guest@localhost> make-toast toasterDoneness=4 toasterToastType=toast:frozen-waffle

RPC OK Reply 8 for session 1:

At this point the toaster timer is running, and the simulated waffle is cooking,

After about 40 seconds, the 'toastDone' notification should be received:

Incoming notification:
   notification {
      eventTime 2009-12-29T01:20:05Z
      toastDone {
         toastStatus done
      }
      sequence-id 5
   }

This 'toastDone' event shows that the toast was completed, and is ready to eat.

Stop Making Toast

What if you change your mind, and want wheat toast instead of a waffle?

Repeat the previous command (Control-P should recall the previous command):

guest@localhost> make-toast toasterDoneness=4 toasterToastType=toast:frozen-waffle

RPC OK Reply 8 for session 1:

Now enter the 'cancel-toast' command right away, before the waffle finishes:

guest@localhost> cancel-toast

RPC OK Reply 10 for session 1:

Incoming notification:
   notification {
      eventTime 2009-12-29T01:24:36Z
      toastDone {
         toastStatus cancelled
      }
      sequence-id 6
   }

This 'toastDone' event shows that the toast was cancelled.

Close the NETCONF Session

To close the NETCONF session, use the close-session command:

guest@localhost> close-session

RPC OK Reply 11 for session 1:

ses: session 1 shut by remote peer
yangcli-pro>

Note that the prompt returned to the default form, once the session was dropped by the NETCONF server.

The terminate the yangcli-pro program, use the quit command:

yangcli-pro> quit

mydir>

Advanced Topics

This section introduces some advanced features of the NETCONF protocol and YANG data modeling language.

Data Retrieval

Basic NETCONF Retrieval Operations

The NETCONF protocol has 3 different retrieval operations:

  • <get>: get state data and the running configuration database.

  • <get-config>: get just the specified configuration database.

  • <get-data>: get NMDA datastore data

Each of these operations accepts a <filter> parameter, which has 2 forms:

  • subtree filter: retrieve just the subtrees in the database that match the XML subtrees in the filter.

  • XPath filter: retrieve just the subtrees that match the result node set produced by evaluating the specified XPath expression against the database. This mode cannot be used unless the :xpath capability must be advertised by the server.

The yangcli-pro program supports 3 different forms of each command:

  • plain: plain NETCONF operation with user-supplied filter

  • subtree: XPath path expression or user variable is converted to XML for the <filter> parameter subtree XML.

  • xpath: XPath path expression or user variable is converted to XML for the <filter> parameter 'select' XML attribute

yangcli-pro Retrieval Commands

Command

NETCONF operation

Example

get

plain <get> operation

get with-defaults=trim

get-config

plain <get-config> operation

get-config source=candidate

get-data

plain <get-data> operation

get-data datastore=operational

sget

<get> with a subtree filter

sget /system

sget-config

<get-config> with a subtree filter

sget-config source=running /nacm/rules

sget-data

<get-data> with a subtree filter

sget-data datastore=running /nacm/rules

xget

<get> with an XPath filter

xget /system

xget-config

<get-config> with an XPath filter

xget-config source=running /nacm/rules

xget-data

<get-data> with an XPath filter

xget-data datastore=running /nacm/rules

The retrieval commands return an element named <data> containing the requested XML subtrees.

If any identifier nodes (YANG key leafs) are needed to distinguish the data in the reply, they will be added as needed by the server. In the xget example above, the <name> element for each interface would be returned, even though it was not directly requested by the XPath expression.

Default Value Filtering

The data will also be filtered according to the defaults handling behavior of the server, unless the <with-defaults> parameter is added to the command. This parameter is only supported if the server advertised the :with-defaults capability, If not, the client does not get any indication from the server what type of defaults filtering is being done (if any).

There are 4 types of defaults filtering provided:

  • report-all-tagged: no filtering -- return all nodes even those the server might normally suppress because they are considerer to be default values by the server. Add the 'default' XML attribute to nodes that were set by default.

  • report-all: no filtering -- return all nodes even those the server might normally suppress because they are considerer to be default values by the server.

  • trim: return all nodes except skip any leaf nodes that match the schema defined default value

  • explicit: return all nodes that were set by the client or the server to some value, even if the value happens to be the schema defined default. This is normally the default behavior for the netconfd-pro server.

The defaults handling behavior can be changed just for a specific NETCONF session, using the <set-my-session> operation. This is only available on the netconfd-pro server.

guest@localhost> set-my-session with-defaults=report-all

RPC OK Reply 12 for session 1:

guest@localhost>

In this example, the 'basic' behavior is changed from 'explicit' to 'report-all', but just for session 1. This setting is temporary, and will not be remembered when the session is terminated. If the <with-defaults> parameter is present, it will be used instead of this value.

Special Retrieval Operations

Any YANG module can add new operations with the 'rpc' statement.

New retrieval operations may also be added which are associated with a protocol capability.

Just like any other data model content, the operator (or application) needs to understand the YANG file definitions, including the description statements, to understand how each custom retrieval operation works.

There are some custom retrieval operations supported by netconfd-pro:

Special Retrieval Operations

Command

Description

get-bulk

Iterate through YANG list data from the server This is a proprietary operation defined in the yumaworks-getbulk.yang module.

get-walk

yangcli-pro command to utilize the <get-bulk> operation to step through retrieval of YANG list entries

get-schema

Retrieve the YANG or YIN source file for one of the modules advertised by the server The <get-schema> operation is defined in the ietf-netconf-monitoring.yang module.

get-my-session

Retrieve the customizable settings for my session. This is a proprietary operation defined in the yuma-mysession.yang module.

Notification Messages

Notifications are used in NETCONF to send server event information to the client application.

A session must request notifications with the create-subscription command. The netconfd-pro server also supports new notifications that are started with the establish-subscription command.

Most NETCONF notifications are published to 'event streams'. (The YANG Push feature allows subscriptions to datastores, instead of event streams).

The standard 'NETCONF' event stream must be supported by all servers, but proprietary event streams can be configured as well. A notification subscription request specifies the stream name (and perhaps more parameters).

A NETCONF session on the netconfd-pro server will never expire due to inactivity, while a notification subscription is active. This allows notification processing applications to maintain long-lived connections without worrying about a NETCONF timeout. Note that the SSH server may also be configured to drop idle SSH sessions, whether a notification subscription is active or not.

Notification Contents

../_images/notification1.png

The 'notification' element is sent from the server to the client, if an event occurs, and the client has created a notification subscription.

The child nodes of this element comprise the notification content, and it is divided into 3 sections:

  1. event generation time-stamp: This standard NETCONF leaf is always the first child element within the notification element.

  2. event payload: The module-specific event payload is represented as a container with the name of the notification. Any data nodes defined within the YANG notification statement appear (in order) as child nodes of the event type container.

  3. proprietary extensions: Zero or more vendor-specific elements may appear after the event payload element. For example, the monotonically increasing 'sequence-id' element is added to each notification saved in the netconfd-pro event log.

Notification Replay

../_images/notification2.png

The NETCONF server will maintain an ordered buffer of saved notification events, if the :notification-replay capability is supported by the server. For the netconfd-pro server, this is a configurable feature, set by the --eventlog-size parameter.

The netconfd-pro default is to save the most recent 1000 notification events.

Only system events are saved and are available for retrieval. The <replayComplete> Event and <subscription-terminated> Event are session-specific events, and are therefore not saved in the replay buffer.

The create-subscription command has 2 parameters to request that stored notifications be delivered to the client session:

  • startTime: the date (or date-and-time) to compare against the event generation time-stamp. Only notification events that occurred after this time are delivered.

  • stopTime: the date (or date-and-time) to compare against the event generation time-stamp. Only notification events that occurred before this time are delivered. This parameter can specify a time in the future. When that time has passed, the subscription will be terminated. The stopTime does not cause the server to wait that period of time to generate an event. If the stopTime is in the past, then the subscription will terminate after all the matching event timestamps in the replay buffer have been delivered.

Notifications are delivered in the order they are stored. Each new netconfd-pro notification contains a monotonically increasing sequence-id (unsigned integer). This can be used to help determine if any configured notification filters are working as expected.

The interleave capability

The netconfd-pro server supports the :interleave capability, which means that all commands (except create-subscription) will be accepted by the server. The client should expect <rpc-reply> and <notification> messages. The server will always maintain proper message serialization. These messages will always be sent in their entirety, which may impact applications (e.g., a really long <get> response on the same session will delay notification delivery).

If the NETCONF server does not support the :interleave capability, then it may only allow the <close-session> operation while the notification subscription is active. In this case, a new NETCONF session is required to perform any management operations.

This special mode is only applicable while a notification subscription is active. It is possible for a replay subscription to terminate, without terminating the session as well. In this case, the 'notificationComplete' event will be generated, and the session will return to accepting all possible operations.

Database Editing

NETCONF supports multiple conceptual configuration databases. Only the 'running' database is actually active. All other databases are scratch-pad databases, or some other special-purpose off-line database.

Every NETCONF server must allow arbitrary partial (and concurrent) editing to its configuration with the <edit-config> operation. The yangcli-pro program has simplified editing commands, which are explained below.

The <config> element within an <edit-config> PDU represents the 'root node' (/) in the path expression for each node in the conceptual database. Each top-level YANG object that is supported and configured will be represented as child nodes this root node. The conceptual database can be processed as an XML instance document with multiple top nodes (similar to XSLT rules).

Database editing in NETCONF has several variants, but basically, it follows this simple procedure:

  1. Lock the database(s) that will be affected.

  2. Use <edit-config> or <copy-config> on the target database to make changes.

  3. Activate and save the database edits.

  4. Unlock the database(s) that were previously locked.

The Target Database

Usually a NETCONF server supports the <edit-config> operation on only one database, which is either the candidate or the running database. This is called the 'target' database, which corresponds to the <target> parameter in the <edit-config> operation.

If the target database is the candidate configuration, then the <edit-config> operation does not always cause all possible database validation checking to be done by the server. Since the candidate database is just a scratch-pad for (possibly) incremental edits, the server is not required to completely validate its contents. Instead, these 'final validation' tests are only required to be done when the <commit> operation is invoked.

The yangcli-pro program will automatically handle the target database management, based on the server capabilities reported each session, if the save command is used. The manual procedure (<commit> and/or maybe <copy-config> operations) is also supported, but do not mix them within the same editing session.

NETCONF Database Locking

NETCONF supports database locking so a session can have exclusive write access to the configuration.

These locks are intended to be short-lived, but there is no actual time limit on a lock. If the session terminates for any reason with any locks, they will be released automatically by the server.

All the databases that are involved in the edit should be locked. This always includes the running database, and the candidate and startup databases, if they are supported by the server.

Refer to the Database Locking section for more details on netconfd-pro database locking.

The yangcli-pro program has 2 special commands to handle all locking:

  • get-locks: Wait until all database locks have been acquired or the timeout occurs

  • release-locks: Release any locks that were obtained with get-locks

Non-Volatile Storage

The startup configuration is the conceptual database used on the next reboot of the NETCONF server. It is important to know whether the NETCONF server supports the :startup capability or not. If yes, then the operator must explicitly save the running database to non-volatile storage (the startup database), using the <copy-config> operation. If no, then the server will keep the running and startup databases synchronized.

The yangcli-pro program has a high-level save command, used after the editing operations, that will automatically issue the correct protocol operations to complete the edit, and save the changes in non-volatile storage.

The startup database is configurable in the netconfd-pro server. The --with-startup configuration parameter controls whether the startup database will be used or not. The --startup parameter can be used to control the initial load of the running configuration in 3 different ways:

  1. no startup: skip this step and just use factory defaults

  2. default startup: look for the default startup-cfg.xml file in the configured data path.

  3. specific startup: use a specified file, either absolute file-spec, or a relative path in the configured data path

Refer to the YumaPro User Manual for more details on controlling non-volatile storage.

Editing Commands

The <edit-config> operation should be used make configuration changes. The <copy-config> operation can also be used, but this is a blunt hammer approach. Although the netconfd-pro server will always analyze the edit request and only affect the nodes that actually changed, this is not a requirement in the standard.

The <edit-config> operation allows the operator to have precise control of the server. These database edits are performed by the server using a combination of 3 factors:

  1. The nodes that currently exist in the target database.

  2. The nodes that exist in the 'source' of the edits (either the inline <config> element or indirectly through the <url> element.

  3. The <default-operation> parameter and any XML attributes in the source XML elements (nc:operation attribute and YANG insert operation attributes).

The yangcli-pro program provides some high-level commands to automatically handle the complexity of the <edit-config> operation. These commands use XPath expressions and a series of interactive prompts (e.g., for the mandatory nodes and key leafs) to fill in the specified data structures, and construct an optimized NETCONF message.

yangcli-pro Editing Commands

Command

Description

create

Create a new sub-tree, only if it does not already exist

delete

Delete an existing sub-tree. It is an error if it does not exist

delete-all

Delete all instances of a list or leaf-list. It is an error if no entries exist.

merge

Merge the source sub-tree into the target sub-tree, keeping any existing nodes that are not explicitly contained in the source.

remove

Delete an existing sub-tree. It is not an error if it does not exist.

remove-all

Delete all instances of a list or leaf-list. It is not an error if no entries exist.

replace

Merge the source sub-tree into the target sub-tree, deleting any existing nodes that are not explicitly contained in the source. This is the mode used for the <copy-config> operation.

insert

Insert or move a YANG list or leaf-list entry

NETCONF Access Control

The netconfd-pro server can be configured to give precise access rights to each user (the SSH user name associated with the NETCONF session). By default, the access control model used is 'ietf' (RFC 8341).

Refer to the Access Control section for additional NACM details.

Some important points to remember about access control:

  • There are 3 types of access -- read, write, and execute.

  • If a user does not have read access to some data, then it is silently omitted from the reply.

  • The 'access-denied' error is not generated for read requests. It is only generated for write requests to the database, or <rpc> operation execution requests.

  • An access request results in 1 of 2 outcomes: permit or deny

  • The server resolves the access request by searching the access control rules. Either an explicit rule will apply, or the default access rights will be checked if no rule is found.

  • The default access rights are configurable, but usually set as follows:

    • read access is permitted

    • write access is denied

    • exec access is permitted

  • The nacm:default-deny-write and nacm:default-deny-all extensions can be used by the YANG module author to override the default access rights, and deny access instead. For example, the <shutdown> operation is not permitted by default.

  • There is a configurable 'superuser' user name. If desired, one or more specific user names will be considered to be 'superuser' accounts, and all access control will be bypassed for these user (e.g.,--superuser=joe). By default, there is no superuser account configured.

yangcli-pro Variables

The yangcli-pro program supports variables for easier reuse and script-based operations.

There are 2 types of variables:

  • file variables: the variable name is a file name, and the contents of the variable are stored in this file.

  • internal variables: the variable name is just an internal identifier, and the contents of the variable are stored in memory

Variables are set with assignment statements. Here are some examples:

guest@localhost> $$backup = get-config source=running

guest@localhost> $$bad-data = "warn"

guest@localhost> $itf = "//interface[name='eth0']"

Refer to the Variables section for details on using yangcli-pro variables.

yangcli-pro Scripts

Scripts are simply a collection of yangcli-pro commands and/or assignment statements that are stored in a text file, instead of typed directly. Scripts can call other scripts and pass parameter values.

The run command is used to invoke a yangcli-pro script.

Bash (and other) shell scripts are also supported by yangcli-pro. The run-shell command is used to invoke such a script.

Refer to the Scripts section for details on using yangcli-pro scripts and shell scripts.

toaster YANG Module

The toaster.yang module is included here for reference.

module toaster {

    namespace "http://netconfcentral.org/ns/toaster";

    prefix "toast";

    organization
        "Netconf Central";

    contact
        "Andy Bierman <andy@netconfcentral.org>";

    description
        "YANG version of the TOASTER-MIB.

     Copyright (c) 2009 Andy Bierman and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the BSD 3-Clause License
     http://opensource.org/licenses/BSD-3-Clause";

    revision 2009-11-20 {
        description "Toaster module in progress.";
    }

    identity toast-type {
        description
          "Base for all bread types supported by the toaster.
           New bread types not listed here nay be added in the 
           future.";
    }

    identity white-bread {
        description
          "White bread.";
        base toast:toast-type;
    }

    identity wheat-bread {
        description
          "Wheat bread.";
        base toast-type;
    }

    identity wonder-bread {
        description
          "Wonder bread.";
        base toast-type;
    }

    identity frozen-waffle {
        description
          "Frozen waffle.";
        base toast-type;
    }

    identity frozen-bagel {
        description
          "Frozen bagel.";
        base toast-type;
    }

    identity hash-brown {
        description
          "Hash browned potatos.";
        base toast-type;
    }

    typedef DisplayString {
        description
          "YANG version of the SMIv2 DisplayString TEXTUAL-CONVENTION.";
        reference "RFC 2579, section 2.";
        type string {
            length "0 .. 255";
        }
    }

    container toaster {
        presence
          "Indicates the toaster service is available";

        description
          "Top-level container for all toaster database objects.";

        leaf toasterManufacturer {
            type DisplayString;
            config false;
            mandatory true;
            description 
              "The name of the toaster's manufacturer. For instance, 
                Microsoft Toaster.";
        }
 
        leaf toasterModelNumber {
            type DisplayString;
            config false;
            mandatory true;
            description
              "The name of the toaster's model. For instance,
               Radiant Automatic.";
        }

        leaf toasterStatus {
            type enumeration {
                enum up {
                  value 1;
                  description
                    "The toaster knob position is up.
                      No toast is being made now.";
                }
                enum down {
                  value 2;
                  description
                    "The toaster knob position is down.
                      Toast is being made now.";

                }
            }
            config false;
            mandatory true;
            description
              "This variable indicates the current state of 
               the toaster.";
        }
    }

    rpc make-toast {
        description
          "Make some toast.
           The toastDone notification will be sent when 
           the toast is finished.
           An 'in-use' error will be returned if toast
           is already being made.
           A 'resource-denied' error will be returned 
           if the toaster service is disabled.";
        input {
            leaf toasterDoneness {
                type uint32 {
                    range "1 .. 10";
                }
                default 5;
                description
                  "This variable controls how well-done is the 
                   ensuing toast. It should be on a scale of 1 to 10.
                   Toast made at 10 generally is considered unfit 
                   for human consumption; toast made at 1 is warmed 
                   lightly.";
            }
            leaf toasterToastType {
                type identityref {
                    base toast:toast-type;
                }
                default toast:wheat-bread;
                description
                  "This variable informs the toaster of the type of 
                   material that is being toasted. The toaster 
                   uses this information, combined with 
                   toasterDoneness, to compute for how 
                   long the material must be toasted to achieve 
                   the required doneness.";
            }
        }
    }

    rpc cancel-toast {
        description
          "Stop making toast, if any is being made.
           A 'resource-denied' error will be returned 
           if the toaster service is disabled.";
    }

    notification toastDone {
        description
          "Indicates that the toast in progress has completed.";

        leaf toastStatus {
           description
             "Indicates the final toast status";
           type enumeration {
               enum done {
                  description
                    "The toast is done.";
               }
               enum cancelled {
                  description
                    "The toast was cancelled.";
               }
               enum error {
                  description
                    "The toaster service was disabled or
                     the toaster is broken.";
               }
            }
        }
    }
               
                       
/*************************************************************

   Original TOASTER-MIB

TOASTER-MIB DEFINITIONS ::= BEGIN

IMPORTS
        enterprises
                FROM RFC1155-SMI
        OBJECT-TYPE
                FROM RFC-1212
        DisplayString
                FROM RFC-1213;

epilogue        OBJECT IDENTIFIER ::= {enterprises 12}
toaster         OBJECT IDENTIFIER ::= {epilogue 2}


toasterManufacturer OBJECT-TYPE
  SYNTAX  DisplayString
  ACCESS  read-only
  STATUS  mandatory
  DESCRIPTION
          "The name of the toaster's manufacturer. For  instance, 
          Microsoft Toaster."
  ::= {toaster 1}

toasterModelNumber OBJECT-TYPE
  SYNTAX  DisplayString
  ACCESS  read-only
  STATUS  mandatory
  DESCRIPTION
          "The name of the toaster's model. For instance,
          Radiant Automatic."
  ::= {toaster 2}

toasterControl OBJECT-TYPE
  SYNTAX  INTEGER  {up (1), down (2)}
  ACCESS  read-write
  STATUS  mandatory
  DESCRIPTION
          "This variable controls the current state of the toaster.
           To begin toasting, set it to down (2). To abort toasting 
          (perhaps in the event of an emergency), set it to up (2)."
  ::= {toaster 3}

toasterDoneness OBJECT-TYPE
  SYNTAX  INTEGER (1..10)
  ACCESS  read-write
  STATUS  mandatory
  DESCRIPTION
          "This variable controls how well-done is the 
           ensuing toast. It should be on a scale of 1 to 10.
           Toast made at 10 generally is considered unfit 
           for human consumption; toast made at 1 is warmed 
           lightly."
  ::= {toaster 4}

toasterToastType OBJECT-TYPE
  SYNTAX  INTEGER {
                    white-bread (1),
                    wheat-bread (2),
                    wonder-bread (3),
                    frozen-waffle (4),
                    frozen-bagel (5),
                    hash-brown (6),
                    other (7)
                  }
  ACCESS  read-write
  STATUS  mandatory
  DESCRIPTION
          "This variable informs the toaster of the type of 
           material that is being toasted. The toaster 
           uses this information, combined with 
           toasterToastDoneness, to compute for how 
           long the material must be toasted to achieve 
           the required doneness."
  ::= {toaster 5}

END

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

}