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.

• Refer to the netconfd-pro Introduction section for details on setting up the server configuration.

• Refer to the Configure SSH section for details on setting up the OpenSSH server to work with netconfd-pro.

• Refer to the Start netconfd-pro section for details on starting the netconfd-pro server.

• Refer to the Stopping netconfd-pro section for more details on stopping the netconfd-pro server.

• Refer to the Starting netconfd-pro with ypwatcher program section for more details on running the netconfd-pro server with the yp-watcher program.

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>