Home

Yuma Developer Manual

1. Convention Description foo CLI parameter foo foo XML parameter foo foo yangcli command or parameter FOO Environment variable FOO foo yangcli global variable foo some text Example command or PDU some text Plain text Page 5 Version 2 2 Yuma Developer Manual 2 Software Overview Yuma Tools Data models written in SMIv2 Z Ka cli Network netconfd S smidump Ea Server Ue anslator Data models C code for agent C code for agent development written in YANG Cooked YANG for platform mgmt XSD for NMS development HTML for HTML for user documentation HTML for user documentation n SQL for object dictionary SQL for object dictionary object dictionary COPIC Refer to section 3 of the Yuma User Manual for a complete introduction to Yuma Tools This section focuses on the software development aspects of NETCONF YANG and the netconfd server This document is intended for developers of server instrumentation library software which can be used with the programs in the Yuma suite It covers the design and operation of the netconfd server and the development of server instrumentation library code intended for use with the netconfd server Page 6 Version 2 2 Yuma Developer Manual The Yuma Tools suite provides automated support for development and usage of network management information Refer to the Yuma User Guide for an introduction to the YANG data
2. NCX BT INT8 YANG int8 data type NCX BT INT16 YANG int16 data type NCX BT INT32 YANG int32 data type NCX BT INT64 YANG int64 data type NCX BT UINT8 YANG uint8 data type NCX BT UINT16 YANG uint16 data type NCX BT UINT32 YANG uint32 data type NCX BT UINT64 YANG uint64 data type NCX BT DECIMAL6 4 YANG decimal64 data type NCX BT FLOAT64 Hidden double type used just for XPath If the Version 2 2 Yuma Developer Manual Data Type Description HAS FLOAT define is false then this type will be implemented as a string not a double NCX BT STRING YANG string type There are also some Yuma extensions that are used with this data type for special strings The server needs to know if a string contains XML prefixes or not and there are several flavors to automatate processing of each one correctly NCX BT BINARY YANG binary data type NCX BT INSTANCE ID YANG instance identifier data type NCX BT UNION YANG union data type This is a meta type When the client or server parses a value it will resolve the union to one of the data types defined within the union NCX BT LEAFREF YANG leafref data type This is a meta type The client or server will resolve this data type to the type of the actual pointed at leaf that is being referenced NCX BT IDREF YANG identityref data type NCX BT SLIST XSD list da
3. 1 The client issues an rpc edit config to create an xpo container Page 91 Version 2 2 Yuma Developer Manual lt xml version 1 0 encoding UTF 8 lt rpc message id 4 xmlns nc urn ietf params xml ns netconf base 1 0 xmlns urn ietf params xml ns netconf base 1 0 lt edit config xmlns urn ietf params xml ns netconf base 1 0 target candidate target lt default operation gt merge lt default operation gt lt config gt xpo xmlns nc urn ietf params xml ns netconf base 1 0 nc operation create xmlns http www ericsson com television ns xpo3 base config lt edit config gt rpc 2 Netconf executes the xpo edit validate callback to validate the change to the candidate configuration 3 Netconf executes the xpo edit apply callback to apply the change to the candidate configuration 4 The client receives an rpc reply indicating success The client issues an rpc commit to commit the change to the running configuration Netconf executes the xpo edit validate callback to validate the change to the running configuration 7 Netconf executes the xpo edit commit create callback to perform a create operation change to the candidate configuration 8 The client receives an rpc reply indicating success The message sequence chart below shows the expected SIL callbacks for a create profile operation Page 92 Version 2 2 Yuma Developer Manual External Netconf
4. agt connect Handles the internal lt ncx connect gt message sent from the netconf subsystem to the netconfd server agt hello Handles the incoming client lt hello gt message and generates the server hello message agt if Yuma Interfaces module implementation Contains the yuma interfaces module SIL callback functions agt ncx NETCONF protocol operation implementation Contains the yuma netconf module SIL callback functions agt ncxserver Implements the ncxserver loop handling the IO between the server NETCONF sessions and the netconf subsystem thin client program agt not NETCONF Notifications implementation Contains the notifications and nc notifications modules SIL callback functions agt proc proc system monitoring implementation Contains the yuma proc module SIL callback functions agt rpc NETCONF RPC operation handler agt rpcerr NETCONF lt rpc error gt generation agt_ses NETCONF session support and implementation of the Yuma Session extensions Contains the yuma mysession module SIL callback functions agt_signal Server signal handling support agt_state Standard NETCONF monitoring implementation Contains the ietf netconf monitoring SIL callback functions agt_sys Server system monitoring and notification generation Contains the yama system module SIL callback functions agt_timer SIL periodic timer callback support functions Version 2 2 Yuma
5. Each data node contains a pointer back to its object tree schema node The value tree is comprised of the val value t structure Only real data is actually stored in the value tree For example there are no data tree nodes for choices and cases These are conceptual layers not real layers within the data tree The NETCONF server engine accesses individual SIL callback functions through the data tree and object tree Each data node contains a pointer to its corresponding object node Each data node may have several different callback functions stored in the object tree node Usually the actual configuration value is stored in the database However virtual data nodes are also Page 21 Version 2 2 Yuma Developer Manual supported These are simply placeholder nodes within the data tree and usually used for non configuration nodes such as counters Instead of using a static value stored in the data node a callback function is used to retrieve the instrumentation value each time it is accessed All of the major server functions are supported by service layers in the agt or ncx libraries Memory management macros in platform procdefs h are used instead of using direct heap functions The macros m getMem or m getObj are used by Yuma code to allocate memory Both of these functions increment a global counter called malloc count The macro m free is used to delete all malloced memory This macro increments a global counter called free c
6. Return TRUE if the value node should fit on 1 display line Sometimes a guess is made instead of determining the exact value XML namespace declarations generated during XML output can cause this function value to sometimes be wrong val create allowed Return TRUE if the NETCONF create operation is allowed for the specified value node val delete allowed Return TRUE if the NETCONF delete operation is allowed for the specified value node val is config data Return TRUE if the value node represents configuration data val get virtual value Get the value for a virtual node from its get callback function val is default Return TRUE if the value node is set to its YANG default value val is real Check if a value node is a real node or one of the abstract node types val get parent nsid Get the namespace ID for the parent value node of a specified child node val instance count Get the number of occurrences of the specified child value node within a parent value node Version 2 2 Yuma Developer Manual Function Description val need quotes Return TRUE if the printed string representation of a value node needs quotes because it contains some whitespace or special characters val get dirty flag Check if a value node has been altered by an RPC operation but this edit has not been finalized yet val get nest level Get the current numeric
7. LINT splint LINTFLAGS weak macrovarprefix m 3HILIBFLAGS lsocket LIBTOOL ar LFLAGS v no as needed LFLAGS 1m LPATH L LBASE CEES wildcard c Version 2 2 Yuma Developer Manual HEES wildcard h THHEHHHHHHHHHHHHHE OBIS RULE ZEBHHHHHHHHHE 0BJS patsubst c TARGET 0 CEES JHHHHHHHHHHHHHHHE DEPS RULE HHHHEHHHHHHHHI DEPS patsubst c D wildcard c JHHHHHHHHHHHHHHHHHHHHHHHE PLATFORM DEFINITIONS Z PLATFORM CPP PHONY all superclean clean test install uninstall distclean depend lint THEHEHEHHHHHHHHHHHHHHHHHHHHHE MAKE DEPENDENCIES ZEHEHHHHHEHHHHHBT COMPILE c CC CFLAGS CPPFLAGS PLATFORM CPP CINC SUBDIR CPP TARGET ARCH c TARGET 0 SC CC CFLAGS CPPFLAGS PLATFORM CPP CINC SUBDIR CPP TARGET ARCH c o lt Common library rule LBASE libs amp a 0BJS LIBTOOL cr 0BJS ranlib dependency rule to make temp D files from c sources all the D files are collected and appended to the appropriate Makefile when make depend is run this rule is kept here to make sure it matches COMPILE c D C CC MM MG MT TARGET patsubst c 0 lt Wall Wcomment CPPFLAGS PLATFORM_CPP CINC SUBDIR CPP TARGET ARCH c lt gt THHHHHHHHHHHHHHHHHE MAKE DEPENDENCIES JA following depend rule is the GNU version Other versions TBD this rule cannot be included by
8. SUBDIR NM so o 0BJS ldl gcc shared Wl soname libtoaster so o 0BJS lc LBASE lib SUBDIR NM dylib 0BJS gcc shared dynamiclib std gnu99 current version 1 0 undefined dynamic lookup O 8 install name lib SUBDIR NM dylib 0BJS lxml2 code yangdump format h indent 4 module SUBDIR NM output SUBDIR NM h yangdump format c indent 4 module SUBDIR NM output SUBDIR NM c prevent the make program from choking on all the symbols that get generated from autogenerated make rules NOEXPORT include dependencies Page 108 Version 2 2 Yuma Developer Manual The YANG language includes many ways to specify conditions for database validity which traditionally are only documented in DESCRIPTION clauses The YANG language allows vendors and even data modelers to add new statements to the standard syntax in a way that allows all tools to skip extension statements that they do not understand The yangdump YANG compiler sames all the non standard language statements it finds even those it does not recognize These are stores in the ncx appinfo t data structure in ncx ncxtypes h There are also SIL access functions defined in ncx ncx appinfo h that allow these language statements to be accessed If an argument string was provided it is saved along with the command name Several data structures contains an appinfoQ field to contain all the ncx appinfo t stuctures that were generated
9. The YUMA HOME Directory The second Yuma root checked when searching for files is the directory identified by the YUMA HOME environment variable This is usually set to private work directory but a shared directory could be Page 8 Version 2 2 Yuma Developer Manual used as well If a YUMA HOME modules YUMA HOME data and or YUMA HOMEJ scripts directory exists then it will be checked for the specified file s 3 The YUMA INSTALL Directory The last Yuma root checked when searching for files is the directory identified by the YUMA INSTALL environment variable If it is not set then the default value of usr share yuma is used instead This is usually set to the public directory where all users should find the default modules If a YUMA INSTALL modules YUMA INSTALL data and or YUMA INSTALL scripts directory exists then it will be checked for the specified file s A SIL is a Server Instrumentation Library It contains the glue code that binds YANG content managed by the netconfd server to your networking device which implements the specific behavior as defined by the YANG module statements The netconfd server handles all aspects of the NETCONF protocol operation except data model semantics that are contained in description statements The server uses YANG files directly loaded at boot time or run time to manage all NETCONF content operations and notifications Callback functions are used to h
10. to automate processing of all NETCONF messages After the core definition modules are loaded successfully the agt cli process input function in agt agt cli c is called to process any command line and or configuration file parameters that have been entered e Note Any defaults set in the G module definitions will be added to the CLI parameter set The val set by default function in ncx val c can be used to check if the node is set by the server to the YANG default value If not set and the node has the YANG default value then the client set this value explicitly This is different than the val is default function in ncx val c which just checks if the node contains the YANG default value All the configuration parameters are saved and those that can be processed right away are handled The agt cli get valset function in agt agt cli c can be used to retrieve the entire set of load time configuration parameters YANG modules and their associated device instrumentation can be loaded dynamically with the module configuration parameter Some examples are shown below module foo module bar module baz 2009 01 05 module mymodules myfoo yang e The ncxmod find sil file function in ncx ncxmod c is used to find the library code associated with the each module name The following search sequence is followed o Check the YUMA_HOME target lib directory o Check each directory in the YUMA_RUNPATH environment variable or runpath configurati
11. uint32 flags see 0BJ FL definitions ncx error t tkerr grp template t grp non NULL in a grp datadefQ 4 back pointers struct obj template t_ parent struct obj template t usesobj struct obj template t augobj struct xpath pcb t_ when optional when clause py dlq_hdr t metadataQ Q of obj metadata t iu dlq hdr t appinfoQ Q of ncx appinfo t uA dlq hdr t iffeatureQ Q of ncx iffeature t cbset is agt rpc cbset t for RPC or agt cb fnset t for OBJ void cbset object namespace ID assigned at runtime this can be changed over and over as a uses statement is expanded The final expansion into a real object will leave the correct value in place JA xmlns id t nsid union def obj container t q container obj leaf t leaf obj leaflist t leaflist obj list t list obj choice t choic obj case t cas obj uses t uses obj refine t refine obj augment t augment obj rpc t rpc Page 38 Version 2 2 Yuma Developer Manual obj rpcio t rpcio obj notif t notif def obj template t The following table highlights the fields within the obj template t data structure obj template t Fields Field Description ghdr Queue header to allow the object template to be stored in a child queue objtype enumeration to identify which variant of the def union is present flags Internal state and properties
12. Client rpc lt edit config gt profile create xpo profile edit validate xpo profile id edit validate xpo profile edit apply xpo profile id editeapply rpc reply xpo profile editcapply xpo profile id editeapply7 xpo profile edit commit creat xpo profile id edit commit create rpc reply e The client issues an rpc edit config to create a profile lt xml version 1 0 encoding UTF 8 lt rpc message id 5 xmins nc urn ietf params xml ns netconf base 1 0 xmlns urn ietf params xml ns netconf base 1 0 lt edit config xmlns urn ietf params xml ns netconf base 1 0 target candidate target lt default operation gt merge lt default operation gt lt config gt lt xpo xmlns http www ericsson com television ns xpo3 base profile xmlns nc urn ietf params xml ns netconf base 1 0 nc operation create gt lt id gt 1 lt id gt lt profile gt lt xpo gt lt config gt lt edit config gt lt rpc gt Page 93 Version 2 2 Yuma Developer Manual e Netconf executes the profile edit validate callback for the candidate configuration e Netconf executes the profile id edit validate callback for the candidate configuration e Netconf executes the profile edit apply callback for the candidate configuration e Netconf executes the profile id edit apply callback for the candidate configuration e The client receives an rpc reply indicating success e The client i
13. ES ENNEN 101 7 Development EnviFontnellb iui esto eoru sux xia ner senna re PER EE EE SEENEN 101 7 1 Programs and Libraries Needed sees 101 FSk E EE 102 7 2 1 Target PlatfOFtis oer e e o eerie ee hernia te i EXE Re Gea dee decr e Een 102 7 22 HUNG Ee e uu isset estet A es P M Vea ou D M eus 102 7 2 3 Command Line Build ODEIOFS need ere Eh Dex EE rer EEN 103 7 2 4 Example SIE GE erre neret is ere b da e eaa eee VR AH 104 7 3 Automation Kee bees DUE 108 7 3 1 Built in YANG Language Exvtensions Ak 109 7 3 2 SIL Language Extension Access Funchons mene 110 Page 3 Version 2 2 Yuma Developer Manual 1 Preface Copyright 2009 2012 Andy Bierman All Rights Reserved This document assumes you have successfully set up the software as described in the printed document Yuma Installation Guide Yuma Quickstart Guide Other documentation includes Yuma User Manual Yuma netconfd Manual Yuma yangcli Manual Yuma yangdiff Manual To obtain additional support you may join the yuma users group on sourceforge net and send email to this e mail address yuma users lists sourceforge net The SourceForge net Support Page for Yuma can be found at this WEB page http sourceforge net projects yuma support There are several sources of free information and tools for use with YANG and or NETCONF The following section lists the resources available at this time Netconf Central o http www netconfcentral org o
14. K E CE FK K CE K K E K OK OK K OK K OK K FUNCTION y toaster make toast validate RPC validation phase All YANG constraints have passed at this point Add description stmt checks in this function INPUTS see agt agt rpc h for details RETURNS error status 2K ok ok ok ok o K K K K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K OK CE CE CE CE CE CE CE CE CE CE CK CE CK OK PK K K K K K K K K K K K K SE SE SE 2K OE K 2K K 2K K 2K K K K K static status t y toaster make toast validate ses cb t scb rpc msg t msg xml node t methnode e a EX NGC a a a SS status t res val value t errorval const xmlChar errorstr val value t toasterDoneness val val value t toasterToastType val uint32 toasterDoneness val idref t toasterToastType res NO ERR errorval NULL errorstr NULL toasterDoneness val val find child msg gt rpc_input y_toaster M toaster y toaster N toasterDoneness if toasterDoneness val NULL amp amp toasterDoneness val res NO ERR toasterDoneness VAL UINT toasterDoneness val toasterToastType val val find child msg rpc input y toaster M toaster y toaster N toasterToastType if toasterToastType val NULL amp amp toasterToastType val gt res NO ERR toasterToastType VAL IDREF toasterToastType val Page 68 Version 2 2 Yuma Developer Manual added code starts here if toaster_enabled toaster service enabled check if in
15. K FK K K FK CE CE K K CE K K K K FK CE K FK K E K K K CE K FK K K K K K K K OK K K K static status_t y foo command post ses cb t scb rpc msg t msg xml node t methnode void scb void methnode if msg rpc userl NULL m free msg rpc user1 msg gt rpc_userl NULL return NO ERR y foo command post 5 2 Database Operations The server database is designed so that the SIL callback functions do not need to really know which database model is being used by the server e g target is candidate vs running configuration There are three SIL database edit callback phases 1 2 Validate Check the parameters no matter what database is the target Apply The server will manipulate the database nodes as needed The SIL usually has nothing to do in this phase unless internal resources need to be reserved Commit or Rollback Depending on the result of the previous phases either the commit or the rollback callback phase will be invoked if and when the changes are going to be finalized in the running configuration The SIL code is not responsible for maintaining the value tree for any database This is done by the server The SIL database edit callback code is responsible for the following tasks Perform any data model specific validation that is not already covered by a machine readable statement during the validation phase Reserve any data model specific resources for the proposed new
16. The following table describes the purpose of each file Refer to the actual include file e g ncx h in usr include yuma for more details on each external function in each C source module src ncx C Modules C Module Description b64 Encoding and decoding the YANG binary data type blob Encoding and decoding the SQL BLOB data type bobhash Implementation of the BOB hash function cap NETCONF capability definitions and support functions cfg NETCONF database data structures and configuration locking support cli CLI parameter parsing data driven by YANG definitions conf Text conf file encoding and decoding data driven by YANG definitions def reg Hash driven definition registry for quick lookup support of some data structures Contains back pointers to the actual data diq Double linked queue support ext YANG extension data structure support Page 11 Version 2 2 Page 12 Yuma Developer Manual C Module Description grp YANG grouping data structure support help Automatic help text data driven by YANG definitions log System logging support ncx appinfo Yuma Netconf Extensions NCX support ncx YANG module data structure support and some utilities ncx feature YANG feature and if feature statement data structure support ncx list Support for the ncx list t data structure used for YANG
17. UINT toasterDoneness val toasterToastType val val find child msg rpc input y toaster M toaster y toaster N toasterToastType if toasterToastType val NULL amp amp toasterToastType val res NO ERR toasterToastType VAL IDREF toasterToastType val invoke your device instrumentation code here make sure the toasterDoneness value is set if toasterDoneness val NULL toasterDoneness 5 set the default arbitrary formula to convert toaster doneness to the number of seconds the toaster should be on toaster duration toasterDoneness 12 this is where the code would go to adjust the duration based on the bread type if LOGDEBUG log debug Nntoaster starting toaster for Su seconds toaster duration this is where the code would go to start the toaster heater element start a timer to toast for the specified time interval res agt timer create toaster duration FALSE toaster timer fn NULL amp toaster timer id if res NO ERR toaster toasting TRUE else agt_record error scb amp msg gt mhdr NCX_LAYER_OPERATION res methnode NCX_NT_NONE NULL NCX_NT_NONE NULL added code ends here return res Page 72 Version 2 2 Yuma Developer Manual y toaster make toast invoke Page 73 Version 2 2 Yuma Developer Manual RPC Post Reply Phase del callback i static status
18. YnERE veh yee es pentane nese yet Saee oh Code e eg 17 2 3 YANG Native ODGEGU EE 18 23 2 YANG ODject e 20 E ale 21 TS isla iiu ciini ctp eT 22 23 5 SESSION COMEPOM BOCK EE 23 2 3 6 Server Message FlOWs re rore need de iu e rei Ex ENEE uge SEENEN Ye 23 2 3 7 Mam nexserver EDOD EE 25 2 3 9 SIL Callback FUNCION Saee initan ads Pet ede m npa Eden seta Sep ES Doa e iain oes renee eser 26 24 Server Operationer n 27 EN Ve EE e DEE 27 2 4 2 Loading Modules and SIL Code oce nee etre reete rex tun ie RE EN eed 28 2 4 3 Core Module IniElalizablOLi sn edere eese roe bc bance S dE EN Ee Ee 29 2 4 4 Startup Configuration Processing sie due tee co ce a Ru eua M pred etm t edt 29 2 4 5 Process an Incoming lt rpc gt Reouest AAA 30 241 6 Edit th ee 31 2 4 7 Save the RE 33 ee ege tel 33 2 5 1 Ne Ee E ue RE RE 33 2 5 2 jett netcont monitoririg y e e EE 24 Page 1 Version 2 2 Yuma Developer Manual 2 5 3 retr withederaults yarng EE 34 2 5 4 qetrsyang tyDes e EE 34 2 5 5 NC Notifications yang EE 34 2 5 6 e au lues E e EE 24 2 5 7 El egenen EE ue DEE 35 2 9 8 yurmasitertaces Varig EE 35 2 5 9 YUMA MYSESSION YAM Gee iic cisco erts en duncs taht wee Fark Fed deae Rx E eg eva raga cee eu xu Fe 35 2 5 10 Vitrmigsnaerm ANG EE 35 2 5 TI yuma NCXVaM J NR TT 35 2 5 12 yuma netconf yang e enari ER et rer ah as KENE Aa dh woe de AAE EAEE EEA revu 35 2 75 13 a E ene DEEN 36 2 5 D4 Vurnassvskelri alt E 36 2 5 15 yuma time filter
19. Yuma Home Page Free information on NETCONF and YANG tutorials on line YANG module validation and documentation database Yuma SourceFource OpenSource Project o http sourceforge net projects yuma Download Yuma source and binaries project forums and help Page A Version 2 2 Yuma Developer Manual Yang Central o http www yang central org o Free information and tutorials on YANG free YANG tools for download NETCONF Working Group Wiki Page o http trac tools ietf org wg netconf trac wiki o Free information on NETCONF standardization activities and NETCONF implementations e NETCONF WG Status Page o http tools ietf org wg netconf o IETF Internet draft status for NETCONF documents e libsmi Home Page o http www ibr cs tu bs de projects libsmi o Free tools such as smidump to convert SMIv2 to YANG e NETCONF Working Group o http www ietf org html charters netconf charter html o Technical issues related to the NETCONF protocol are discussed on the NETCONF WG mailing list Refer to the instructions on the WEB page for joining the mailing list NETMOD Working Group o http www ietf org html charters netmod charter html o Technical issues related to the YANG language and YANG data types are discussed on the NETMOD WG mailing list Refer to the instructions on the WEB page for joining the mailing list The following formatting conventions are used throughout this document Documentation Conventions
20. bits and ncx xsdlist data types ncxmod File Management Controls finding and searching for YANG YIN files data files and script files ncx num Yuma ncx num t data structure support Used for processing value nodes and XPath numbers ncx str Yuma string support obj Yuma object obj template t data structure access obj help Automated object help support used with help module op NETCONF operations definitions and support functions rpc NETCONF lt rpc gt and lt rpc reply gt data structures and support functions rpc err NETCONF lt rpc error gt data structures and support functions runstack Script execution stack support for yangcli scripts send_buff NETCONF send buffer function ses NETCONF session data structures and session access functions ses msg Message buffering support for NETCONF sessions status Error code definitions and error support functions tk Token chain data structures used for parsing YANG XPath and other syntaxes top Top level XML node registration support The lt rpc gt and lt hello gt elements are registered by the server The hello lt rpc reply gt and lt notification gt elements are registered by the client tstamp Time and date stamp support functions typ YANG typedef data structures and access functions val Yuma value tree data structures and access functions val_util High level utilities for some common SIL tasks related to the value tree var User variable support used by yangcli
21. change that did succeed if any before an error occured in the apply phase 2 boolean rpc need undo set by edit config validate R diq hdr t rpc undoQ Q of rpc undo rec t dlq hdr t rpc auditQ Q of rpc audit rec t Page 65 Version 2 2 Yuma Developer Manual rpc msg t The file agt agt rpc c contains some functions that are used by SIL callback functions The following table highlights the functions that may be useful to SIL developers agt agt rpc c Functions Function Description agt rpc register method Register a SIL RPC operation callback function for 1 callback phase agt rpc support method Tell the server that an RPC operation is supported by the system agt rpc unsupport method Tell the server that an RPC operation is not supported by the system agt rpc unregister method Remove all the SIL RPC operation callback functions for 1 RPC operation Page 66 Version 2 2 Yuma Developer Manual RPC Validate Phase POST REPLY post reply callback static status t 44 amp retum operation status y toaster make toast validate ses cb t scb a rpc msg t msg RPC request in progress xml node t methnode __ session making the request M ga XML node for the operation for error reporting purposes and vendor specific attributes The RPC validate callback function is optional to use Its p
22. configuration changes to non volatile storage If the with startup true parameter is used then the server will support the startup capability In this case the lt copy config gt command needs to be used to cause the running configuration to be saved e If the with startup false parameter is used then the server will not support the startup capability In this case the database will be saved each time the running configuration is changed e The lt copy config gt or commit operations will cause the startup configuration file to be saved even if nothing has changed This allows an operator to replace a corrupted or missing startup configuration file at any time The database is saved with the agt ncx cfg save function in agt agt ncx c e The with defaults explicit mode is used during the save operation to filter the database contents o Any values that have been set by the client will be saved in NV storage o Any value set by the server to a YANG default value will not be saved in the database o Ifthe server create a node that does not have a YANG default value e g containers lists keys then this node will be saved in NV storage Ifthe startup filespec parameter is used then the server will save the database by overwriting that file The file will be renamed to backup cfg xml first Ifthe no startup parameter is used or no startup file is specified and no default is found then the server will cre
23. configuration content during the apply phase Activate any data model behavior changes based on the new configuration content during the commit phase Page 75 Version 2 2 Yuma Developer Manual Release any reserved resources that were previously allocated in the apply phase during the rollback phase Every NETCONF database has a common template control block and common set of access functions NETCONF databases are not separate entities like separate SQL databases Each NETCONF database is conceptually the same database but in different states candidate A complete configuration that may contain changes that have not been applied yet This is only available if the candidate capability is advertised by the server The value tree for this database contains only configuration data nodes running The complete current server configuration This is available on every NETCONF server The value tree for this database contains configuration data nodes and non configuration nodes created and maintained by the server The server will maintain read only nodes when lt edit config gt lt copy config gt or commit operations are performed on the running configuration SIL code should not alter the data nodes within a configuration directly This work is handled by the server SIL callback code should only alter its own data structures if needed startup A complete configuration that will be used upon the next reboot of the device Th
24. do not require any editing by the developer Most of the work done by SIL code is through callback functions for specific RPC operations and database objects These callback functions are registered during the initialization functions 4 1 Stage 1 Initialization Page 56 Version 2 2 Yuma Developer Manual The stage 1 initialization function is the first function called in the library by the server If the netconfd configuration parameters include a load command for the module then this function will be called during server initialization It can also be called if the lt load gt operation is invoked during server operation This function MUST NOT attempt to access any database There will not be any configuration databases if this function is called during server initialization Use the init2 function to adjust the running configuration This callback function is expected to perform the following functions initialize any module static data e make sure the requested module name and optional revision date parameters are correct e load the requested module name and revision with ncxmod load module e setup top level object cache pointers if needed e register any RPC method callbacks with agt rpc register method register any database object callbacks with agt cb register callback e perform any device specific and or module specific initialization Name Format y modnames init Input e modname string containing module na
25. modeling language and the NETCONF protocol This section describes the Yuma development environment and the basic tasks that a software developer needs to perform in order to integrate YANG module instrumentation into a device This manual contains the following information e Yuma Development Environment e Yuma Runtime Environment e Yuma Source Code Overview e Yuma Server Instrumentation Library Development Guide Yuma Tools programs are written in the C programming language using the gnu99 C standard and should be easily integrated into any operating system or embedded device that supports the Gnu C compiler Yuma Root Directory A AA Default Yuma data directory layout Page 7 Version 2 2 Yuma Developer Manual The Yuma Tools programs will search for some types of files in default locations e YANG Modules The modules sub directory is used as the root of the YANG module library e Client Scripts The yangcli program looks in the scripts sub directory for user scripts e Program Data The yangcli and netconfd programs look for saved data structures in the data sub directory Searching For Yuma Roots 3 e Um e Default SYUMA INSTALL 1 HOME Directory The first Yuma root checked when searching for files is the directory identified by the HOME environment variable If a HOME modules HOME data and or HOME scripts directory exists then it will be checked for the specified file s 2
26. nest level of the specified value node val get mod name Get the module name for the specified value node val get mod prefix Get the module prefix string for the specified value node val get nsid Get the namespace ID for the specified value node val change nsid Change the namespace ID for the specified value node and all of its descendents val set pcookie Set the SIL pointer cookie in the value node editvars structure val set icookie Set the SIL integer cookie in the value node editvars structure val get pcookie Get the SIL pointer cookie in the value node editvars structure val get icookie Get the SIL integer cookie in the value node editvars structure val get typdef Get the typedef structure for a leaf or leaf list value node val move children Move all the child nodes of one complex value node to another complex value node val set canonical order Re order the descendant nodes of a value node so they are in YANG order Does not change the relative order of system ordered lists and leaf lists val gen index chain Generate the internal key leaf lookup chain for a list value node val add defaults Generate the leafs that have default values val instance check Check a value node against its template to see if the correct number of descendant nodes are present val get choice first set Get the first real node that is
27. one of the complex data types val init virtual Initialize a malloced value node as a virtual node provide a get callback function val init from template Initialize a malloced value node using an object template This is the most common form of the Version 2 2 Page 51 Yuma Developer Manual Function Description init function used by SIL callback functions vaL free value Clean and free a malloced value node val set name Set or replace the value node name val set qname Set or replace the value node namespace ID and name val string ok Check if the string value is valid for the value node object type val string ok errinfo Check if the string value is valid for the value node object type and provide the error information to use if it is not OK val list ok Check if the list value is valid for the value node object type val list ok errinfo Check if the list value is valid for the value node object type and provide the error information to use if it is not OK val enum ok Check if the enumeration value is valid for the value node object type val enum ok errinfo Check if the enumeration value is valid for the value node object type and provide the error information to use if it is not OK val bit ok Check if the bits value is valid for the value node object type val idref ok Check if the identityref value is
28. present for a conceptual choice statement val get choice next set Get the next real node that is present for a conceptual choice statement val choice is set Return TRUE if some real data node is present for a conceptual choice statement Version 2 2 Yuma Developer Manual Function Description val new child val Create a child node during an edit operation Used by the server SIL code does not need to maintain the value tree val gen instance id Malloc and generate the YANG instance identifier string for the value node val check obj when Check if an object node has any when statements and if so evaluate the XPath condition s against the value tree to determine if the object should be considered present or not val check child conditional Check if a child object node has any FALSE if feature or when statements val is mandatory Check if the child object node is currently mandatory or optional val get xpathpcb Access the XPath parser control block for this value node if any val make simval obj Malloc and fill in a value node from an object template and a value string val set simval obj Fill in a value node from an object template and a value string There are some high level SIL callback utilities in agt agt util h These functions access the lower level functions in libncx to provide simpler functions for common SIL tasks The following
29. profile edit commit create xpo profile id edit commit create xpo profile streamConnection editecommit create xpo profile streamConnection id edit commit create xpo profile streamConnection sourceld edit commit create xpo profile streamConnection bitrate editecommit create rpc reply EI n Page 95 Version 2 2 8 8 13 s s s IW BI e fa x fe g lg 3 JE 3 3 EEG a g amp 2 SIS SIL Callbacks sj ef l 8 8 Ls 8 85 L8 8 L8 L8 Yuma Developer Manual e The client issues an rpc edit config to create a profile stream connection Note the profile has not previously been created lt xml version 1 0 encoding UTF 8 gt lt rpc message id 5 xmlns nc urn ietf params xml ns netconf base 1 0 xmlns urn ietf params xml ns netconf base 1 0 lt edit config xmlns urn ietf params xml ns netconf base 1 0 target candidate target lt default operation gt merge lt default operation gt lt config gt xpo xmlns http www ericsson com television ns xpo3 base gt lt profile gt lt id gt 1 lt id gt lt streamConnection xmlns nc urn ietf params xml ns netconf base 1 0 nc operation create gt lt id gt 1 lt id gt lt sourcelId gt 100 lt sourceld gt lt bitrate gt 500 lt bitrate gt lt streamConnection gt lt profile gt lt xpo gt lt config gt lt edit config gt rpc e Netconf executes the profile edit vali
30. rpc unregister method e unregister any database object callbacks with agt cb unregister callbacks e perform any device specific and or module specific cleanup Name Format y modname cleanup Example function generated by yangdump FAK OK KK OK FK K OK OK K OK ECKE CK K CE CE OK K CE K K FK CE OK K OK CE K K K K FK CK CE CE FK K CE CE K GE OK K FK CE CE K K E CE K OK K K OK OK K K OK OK K OK OK OK K FUNCTION y toaster cleanup a cleanup the server instrumentation library x KKK KK K K K K K FK K K K K K K K ok K K K K K K K K K FK K K K K K K K K K K K 2K K K K K K K K K K K K K K K K K K K K K K K K K K void y toaster cleanup void 1 agt rpc unregister method y toaster M toaster y toaster N make toast agt rpc unregister method y toaster M toaster y toaster N cancel toast agt cb unregister callbacks y toaster M toaster const xmlChar toaster put your cleanup code here y toaster cleanup 5 SIL Callback Interface This section briefly describes the SIL code that a developer will need to create to handle the data model specific details SIL functions access internal server data structures either directly or through utility functions Database mechanics and XML processing are done by the server engine not the SIL code A more complete reference can be found in section 5 When a lt rpc gt request is received the NETCONF server engine will perform the following tasks before ca
31. t 4 4 return status should be NO ERR y foo command post ses cb t sch 4 rpc msg t msg completed RPC request xml node t methnode session making the request DE XML node for the operation ignored in this mode The RPC post reply callback function is used to clean up after a message has been processed Only 1 function can register for each YANG rpc statement The standard NETCONF operations are reserved by the server engine This callback is not needed unless the SIL validate or invoke callback allocated some memory that needs to deleted after the lt rpc reply gt is sent The RPC post reply callback function is optional to use It is enabled with the agt rpc register method function within the phase 1 initialization callback function The yangdump code generator will not create this SIL callback function by default Example SIL Function Registration res agt rpc register method y foo M foo y foo N command AGT RPC PH POST REPLY y foo command post if res NO ERR return res Page 74 Version 2 2 Yuma Developer Manual Example SIL Function SEI AIK ok okeokeokeokc oko ok ok oke ke kk ke ok ok ke kk RK kk ek 2K ok FUNCTION y foo command post RPC post reply phase E INPUTS E see agt agt_rpc h for details x RETURNS x error status DB KK FK K K FK K FK CK K FK FK K FK K CE FK K K FK K K FK K K K E CE FK
32. the Yuma engine core modules such as ncx val c and ncx xml wr c This module is defined in RFC 5277 the NETCONF Notifications specification It contains the lt replayComplete gt and lt notificationComplete gt notification event definitions The file agt agt not c contains the SIL support code for this module This module is defined in RFC 5277 the NETCONF Notifications specification All of this RFC is supported in the server This module contains the lt create subscription gt RPC operation The notification replay feature is controlled with the eventlog size configuration parameter The lt create subscription gt operation is fully supported including XPath and subtree filters The yuma nacm module can be used to control what notification events a user is allowed to receive The lt create subscription gt filter allows the client to select which notification events it wants to receive The file agt agt not c contains the SIL callback functions for this modules Page 34 Version 2 2 Yuma Developer Manual This module contains some common groupings of CLI parameters supported by some or all Yuma programs Each program with CLI parameters defines its own module of CLI parameters using the ncx cli extension The program name is used for the YANG module name as well e g yangdump yang or netconfd yang The SIL callback functions for the common groupings in this module are found in ncx val util c such as the val set feature par
33. the second function called in the library by the server e It will only be called if the stage 1 initialization is called first and it returns 0 NO ERR status e This function is used to initialize any needed data structures in the running configuration such as factory default configuration read only counters and status objects e Itis called after the startup configuration has been loaded into the server e Ifthe load operation is used during server operation then this function will be called immediately after the state 1 initialization function Note that configuration data structures that are loaded during server initialization load running config will be handled by the database callback functions registered during phase 1 initialization Any server created configuration nodes should be created during phase 2 initialization this function after examining the explicitly provided configuration data For example the top level nacm container will be created by agt acm c if it is not provided in the startup configuration Page 59 Version 2 2 Yuma Developer Manual This callback function is expected to perform the following functions e load non configuration data structures into the server if needed e initialize top level data node cache pointers if needed load factory default configuration data structures into the server if needed optionally save a cached pointer to a data tree node such as the root node for t
34. this document container xpo presence Indicates that the Device Test API is available description Top level container for all configuration and status objects TU E PR RSS S S e AT PL Start of main configuration block PLANILLA AAA LAMAMA ALALILA grouping connectionItem description Connection container leaf sourceld description The ID of the item providing the input to the connection type uint32 leaf bitrate description The maximum expected bitrate over this connection type uint32 units bps list profile key id description Profile container leaf id description Unique ID for this profile type uint32 list streamConnection description Connection between two streams key id leaf id description Connection identifier type uint32 uses connectionItem leaf activeProfile description The number of the active profile type uint32 Page 90 Version 2 2 Yuma Developer Manual The following sections identify the messages sent by the Nectonf Client and the SIL callbacks that will be made The message sequence charts do not show operations for locking and unlocking of the running and candidate configurations The message sequence chart below shows the expected SIL callbacks for a create xpo container operation rpc edit config xpo create xpo edit validate E EH xpo editcapply xpo editecommit create
35. tkerr Error message information grp back pointer to parent group if this is a top level data node within a grouping parent Parent node if any usesobj Back pointer to uses object if this is a top level data node within an expanded grouping augobj Back pointer to augment object if this is a top level data node within an expanded augment when XPath structure for YANG when statement metadataQ Queue of obj template t for any XML attributes ncx metadata defined for this object node appinfoQ Queue of ncx appinfo t for any YANG extensions found defined within the object that were not collected within a deeper appinfoQ e g within a type statement iffeatureQ Queue of ncx iffeature t for any if feature statements found within this object node cbset Set of server callback functions for this object node nsid Object node namespace ID assigned by xmlns c def Union of object type specific nodes containing the rest of the YANG statements Note that the server discards all descriptive statements such as description reference contact Page 39 Version 2 2 Yuma Developer Manual The file ncx obj h contains many API functions so that object properties do not have to be accessed directly The following table highlights the most commonly used functions Refer to the H file for a complete definition of each API function obj template t Access Functions Page 40 Function Description obj find
36. toast if toaster mod NULL return SET ERROR ERR NCX DEF NOT FOUND cancel toast obj ncx find object toaster mod y toaster N cancel toast if toaster mod NULL return SET ERROR ERR NCX DEF NOT FOUND I toastDone obj ncx find object toaster mod y toaster N toastDone if toaster mod NULL return SET ERROR ERR NCX DEF NOT FOUND res agt rpc register method y toaster M toaster y toaster N make toast AGT RPC PH VALIDATE y toaster make toast validate if res NO ERR return res res agt rpc register method y toaster M toaster y toaster N make toast Page 58 Version 2 2 Yuma Developer Manual AGT RPC PH INVOKE y toaster make toast invoke if res NO ERR return res res agt_rpc_register_method y_toaster M toaster y toaster N cancel toast AGT RPC PH VALIDATE y toaster cancel toast validate if res NO ERR return res res agt rpc register method y toaster M toaster y toaster N cancel toast AGT RPC PH INVOKE y toaster cancel toast invoke if res NO ERR return res res agt cb register callback y toaster M toaster const xmlChar toaster const xmlChar 2009 11 20 y toaster toaster edit if res NO ERR return res put your module initialization code here return res y toaster init 4 2 Stage 2 Initialization The stage 2 initialization function is
37. v list Internal data structure for YANG bits and NCX xsdlist data types v boo YANG boolean data type v enu Internal data structure for YANG enumeration data type v fname File name for NCX external data type v intbuff Malloced buffer for internal data type There are a set of macros defined to access the fields within a val_value_t structure These should be used instead of accessing the fields directly There are also functions defined as well These macros are provided in addition the the access functions for quick access to the actual node value These macros must only be used when the base type btyp field has been properly set and known by the SIL code Some auto generated SIL code uses these macros The following table summarized the val value t macros that are defined in ncx val h Macro Description VAL BOOL V Access value for NCX BT BOOLEAN VAL EMPTY V Access value for NCX BT EMPTY VAL DOUBLE V Access value for NCX BT FLOAT64 VAL STRING V Access value for NCX BT STRING VAL BINARY V Access value for NCX BT BINARY Page 49 VAL ENU V Access entire ncx enum t structure for NCX BT ENUM VAL ENUM V Access enumeration integer value for NCX BT ENUM Version 2 2 The file ncx val h contains many API functions so that object properties do not have to be accessed directly In addition the file ncx val util h contains more high level utility functio
38. values may be used in the future for different retrieval modes virval The virtual value node in the data tree that is being referenced The val get virtual value function was called for this value node dstval The destination value node that needs to be filled in This is just an empty value node that has been malloced and then initialized with the val init from template function The SIL callback function needs to set the value properly The val set simval and val set simval obj functions are two API functions that can be used for this purpose The following example from agt agt ses c shows a SIL get callback function for the ietf netconf monitoring data model which returns the in sessions counter value Page 85 FKK KK K K K FK FK FK K FK FK FK FK FK FK FK FK K FK K FKK K FK ook oko K KK K K K K K K K K K FK FK K K FK FK FK FK K FK K K K K K K KK K KKK K KK K FUNCTION agt ses get inSessions x get operation handler for the inSessions counter x INPUTS is see ncx getcb h getcb fn t for details x RETURNS s status 2K ok ok ok ok o K K KK 2K 2K 2K 2K 2K OE 2K 2K 2K 2K 2K OK CE CE CE CE CE CE CE GE CK OK OK CE CK K PK K K K K K K K K K K K K SE SE SE 2K 2K 2K 2K 2K 2K K 2K 2K K K K ied status t agt ses get inSessions ses cb t scb getcb mode t cbmode const val value t virval val value t dstval 1 void scb void virval if cbmode GETCB GET VALUE VAL UINT dstval
39. which is the Yuma YANG compiler program This is a stand alone binary that is part of the yama client package It is installed in the usr bin directory The following table describes the C modules contained in this directory src yangdump C Modules C Module Description C Implements SIL C file generation c util Utilities used for SIL code generation h Implements SIL H file generation html Implements YANG to HTML translation sql Implements SQL generation for YANG module WEB Docs xsd Implements YANG to XSD translation xsd_typ Implements YANG typedef type statement to XSD simpleType and complexType statements xsd_yang YANG to XSD translation utilities yangdump YANG module compiler yangdump util Utilities used by all yangdump C modules yangyin Implements YANG to YIN translation This section describes the basic design used in the netconfd server Page 17 Version 2 2 Yuma Developer Manual NETCONF Server shutdown Initialization The netconfd server will process the YANG modules CLI parameters config file parameters and startup device NETCONF database then wait for NETCONF sessions ncxserver Loop The SSH2 server will listen for incoming connections which request the netconf subsystem When a new session request is received the netconf subsystem program is called which opens a local connection to the netconfd server via the ncxserver loop NETCONF lt rpc gt re
40. within the same YANG syntax block e g within a typedef type leaf import statement There are several YANG extensions that are supported by Yuma They are all defined in the YANG file named ncx yang They are used to tag YANG definitions for some sort of automatic processing by Yuma 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 server behavior but not all of them For example the ncx hidden extension will prevent yangcli from displaying help for an object containing this extension Also yangdump will skip this object in HTML output mode The following table describes the supported YANG language extensions All other YANG extension statements will be ignored by Yuma if encountered in a YANG file YANG Language Extensions extension description ncx hidden Declares that the object definition should be hidden from all automatic documentation generation Help will not be available for the object in yangcli ncx metadata Defines a qualified XML attribute in the module attr type namespace attr name Allowed within an RPC input parameter attr type is a valid type name with optional YANG prefix attr name is the name of the XML attribute ncx no duplicates Declares that the ncx xsdlist data ty
41. 77 5 2 3 Database Callback Initialization and Ceanmup HH 78 5 2 4 Example SIL Database Edit Callback Function cece cece eee eee eee e een eeaeeeeaeeeae tenes 81 5 2 5 Database Edit Validate Callback Phase eiie eerie remi ties neun 83 5 2 6 Database Edit Apply Callback Phase 1 irent vents ne erre tene eda 83 5 2 7 Database Edit Commit Callback Plhi se iiie tette eg Eine ther Rite CH 83 5 2 8 Database Edit Rollback Callback Phase 5 eterne tre eres bea dedees 84 5 2 9 Database Virtual Node Get Callback Functhton cece eee teeter eee etre nee e eee aeeaeee 84 Br Leger e ARR TREE RINT 86 5 3 1 Notification Send Function erre etr ER RESTE RU Rec ORE dE e See PU 87 Page 2 Version 2 2 Yuma Developer Manual 5 4 Periodic Timer Service corto EE 88 5 4 1 Timer Callback Ei ee NEE 88 5 4 2 Timer Access Tue Lee 89 5 4 3 Example Timer Callback Funchon EEN 89 6 Server Callback EE Eege ege Eege Ee 90 mM CE 90 EE 91 6 2 1 Create an XPO CODEGITIQE EE 91 6 2 2 Created Profile ceiid eac hunted tees ave ei xa a Eua citra Oae ENE E E cho cadent ues dpa ie 92 6 2 3 Create a Stream COonnecLlOn i err tene ther ss ere LEHRER a EA EAN PS dE RE UE ger 94 6 2 4 Delete an XPO Container eeeeeeseeeeee sienne nenne nnnm nhanh anne saisis skis ken ENN 97 6 2 5 D letea Profile side i EE 99 6 2 6 Delete a Stream Connectlon oui oe erret then eon rh Rehd ENNEN ERE YA E Vas
42. Developer Manual C Module Description agt top Server registration and dispatch of top level XML messages agt tree Subtree filtering implementation agt util SIL callback utilities agt val Server validation commit and rollback support for NETCONF database operations agt val parse Incoming lt rpc gt and config content parse and complete YANG constraint validation agt xml Server XML processing interface to ncx xml util functions agt xpath XPath filtering implementation This module contains the NETCONF client support code It handles all the basic NETCONF details so a simple internal API can be used by NETCONF applications such as yangcli A static library called libmgr a is built and statically linked within the yangcli program The following table describes the C modules contained in this directory Page 15 src mgr C Modules C Module Description mgr Client initialization and cleanup control points Also contains manager session control block data structure support functions mgr cap Generate the client NETCONF capabilities element content mgr hello Handles the incoming server hello message and generates the client hello message mgr io Handles SSH server IO support for client NETCONF sessions mgr not Handles incoming server notification2 messages mgr rpc Generate lt rpc gt messages going to the NETCONF server and process inco
43. E CE K CE K CK K OK K K K K OK K K K void y toaster toastDone send const xmlChar toastStatus agt not msg t notif val value t parmval status t res res NO ERR if LOGDEBUG log debug NnGenerating lt toastDone gt notification notif agt_not_new_notification toastDone_obj if notif NULL log_error nError malloc failed cannot send lt toastDone gt notification return add toastStatus to payload parmval agt make leaf toastDone obj y toaster N toastStatus toastStatus amp res if parmval NULL 1 log error nError make leaf failed s cannot send lt toastDone gt notification get error string res else 1 Page 87 Version 2 2 Yuma Developer Manual agt not add to payload notif parmval agt not queue notification notif y toaster toastDone send Some SIL code may need to be called at periodic intervals to check system status update counters and or perhaps send notifications The file agt agt timer h contains the timer access function declarations This section provides a brief overview of the SIL timer service The timer callback function is expected to do a short amount of work and not block the running process The function returns zero for a normal exit and 1 if there was an error and the timer should be destroyed The agt timer fn t template in agt agt timer h is used to define the SIL timer callback function prototyp
44. Functions Function Description cfg_new_template Create a new configuration database cfg_free template Free a configuration database cfg_get_state Get the current internal database state cfg_get_config Get a configuration database template pointer from a configuration name string Page 77 Version 2 2 Yuma Developer Manual Function Description cfg get config id Get a configuration database template pointer from a configuration ID cfg fill candidate from inline Fill the candidate database from an internal value tree data structure cfg get dirty flag Returns TRUE if the database has changes in it that have not been saved yet This applies to the candidate and running databases at this time cfg ok to lock Check if the database could be successfully locked by a specific session cfg ok to unlock Check if the database could be successfully unlocked by a specific session cfg ok to read Check if the database is in a state where read operations are allowed cfg ok to write Check if the database could be successfully written by a specific session Checks the global configuration lock if any is set cfg is global locked Returns TRUE if the database is locked right now with a global lock cfg get global lock info Get some information about the current global lock on the database cfg lock Get a global lock on the database
45. ID assigned to this configuration cfg_loc Enumeration identifying the configuration source location cfg_state Current internal configuration state name Name string for this configuration src_url URL for use with cfg_loc to identify the configuration source load time Date and time string when the configuration was loaded lock_time Date and time string when the configuration was last locked last_ch_time Date and time string when the configuration was last changed flags Internal configuration flags Do not use directly locked_by Session ID that owns the global configuration lock if the database is currently locked lock_src If the database is locked identifies the protocol or other source that currently caused the database to be locked load_errQ Queue of rpc_err_rec_t structures that represent any lt rpc error gt records that were generated when the configuration was loaded if any root The root of the value tree representing the entire database The file ncx cfg h contains some high level database access functions that may be of interest to SIL callback functions for custom RPC operations All database access details are handled by the server if the database edit callback functions are used associated with a particular object node supported by the server The following table highlights the most commonly used functions Refer to the H file for a complete definition of each API function cfg_template_t Access
46. Message Header typedef struct rpc msg t diq hdr t qhdr generic XML message header xml msg hdr t mhdr incoming top level rpc element data xml attrs t rpc in attrs borrowed from rpc elem EE incoming 2nd level method name element data used in agt output filter to check get or get config f struct obj template t rpc method incoming SERVER RPC processing state int rpc agt state agt rpc phase t op errop t rpc err option op editop t rpc top editop val value t rpc input incoming hooks for method routines to save context or whatever void rpc userl void rpc user2 uint32 rpc returncode for nested callbacks incoming get method reply handling builtin If the rpc datacb is non NULL then it will be used as a callback to generate the rpc reply inline instead of buffering the output The rpc data and rpc filter parameters are optionally used by the rpc datacb function to generate a reply a rpc data t rpc data type type of data reply void rpc datacb agt rpc data cb t dlq hdr t rpc dataQ data reply Q of val value t e op filter t rpc filter backptrs for get methods KE incoming rollback or commit phase support builtin As an edit config or other RPC is processed a queue of undo records is collected If the apply phase succeeds then it is discarded otherwise if rollback on error is requested it is used to undo each
47. PC DATA STD A data container will be used to encapsulate any returned data within the lt rpc reply gt element RPC DATA YANG The lt rpc reply gt element will be the only container encapsulated any returned data rpc datacb void write For operations that return streamed data this pointer is set to the desired callback function to use for generated the data portion of the lt rpc reply gt XML response The template for this callback is agt rpc data cb t found in agt rpc h rpc dataQ do hdr t write For operations that return stored data this queue of val value t structures can be used to provide the response data Each val value t structure will be encoded as one of the corresponding RPC output parameters rpc filter op filter t none Internal structure for optimizing subtree and XPath retrieval operations rpc need undo boolean none Internal flag to indicate if rollback on error is in effect dusing an lt edit config gt operation rpc undoQ do hdr t none Queue of rpc undo rec t structures used to undo edits if rollback on error is in affect during an lt edit config gt operation rpc auditQ do hdr t none Queue of rpc audit rec t structures used internally to generate database alteration notifications and audit log entries Page 64 Version 2 2 Yuma Developer Manual The following C code represents the rpc msg t data structure NETCONF Server and Client RPC Request Reply
48. Page 44 Version 2 2 Yuma Developer Manual actually added to the config database TBD move into struct curparent parent of curnode for merge m struct val value t curparent op editop t editop effective edit operation op insertop t insertop YANG insert operation xmlChar insertstr saved value or key attr struct xpath pcb t_ insertxpcb key attr for insert struct val_value t_ insertval back ptr boolean iskey T key F value boolean operset nc operation here void pcookie user pointer cookie int icookie user integer cookie val editvars t The following fields within the val editvars t are highlighted val editvars t Fields Field Description curparent A new node will use this field to remember the parent of the current value This is needed to support the YANG insert operation editop The effective edit operation for this node insertop The YANG insert operation if any insertstr The YANG value or key attribute value string used to support the YANG insert operation insertxpcb XPath parser control block for the insert key expression if needed Used to support the YANG insert operation insertval Back pointer to the value node to insert ahead of or behind if needed Used to support the before and after modes of the YANG insert operation iskey TRUE if this is a key leaf FALSE otherwise operset TRUE if ther
49. The SIL callback code should not need this parameter except to pass to functions that need the SCB msg Incoming RPC message in progress The server uses some fields in this structure and there are 2 SIL fields for the RPC callback functions The SIL callback code should not need this parameter except to pass to functions that need the message header cbtyp Enumeration for the callback phase in progress editop The edit operation in effect as this node is being processed newval Value node containing the new value for a create merge replace or insert operation The newval parm may be NULL and should be ignored for a delete operation In that case the curval pointer contains the node being deleted curval Value node containing the current database node that corresponds to the newval node if any is available A SIL database edit callback function is hooked into the server with the agt cb register callback or agt cb register callbacks functions described below The SIL code generated by yangdump uses the first function to register a single callback function for all callback phases extern status t agt cb register callback const xmlChar modname Page 79 Version 2 2 Yuma Developer Manual const xmlChar defpath const xmlChar version const agt cb fn t cbfn agt cb register callback Parameter Description modname Module name string that defines this object node
50. Vang EE 36 2 5 TO Vurnastypes yallg EE 36 3 YANG Objects and Data Nodes e ebd isst ober deed geed dereen 36 BL ODIECE Definition EE 36 3 Lb alte ee EE o ea o ee e ede tb te oie bete a b obo th 36 3 1 2 Object Node Template obj template E AANEREN ENNEN 38 3 1 3 0D template t Access ie ei EE 39 3 2 DACA TOC T N 42 3x Data Node Types ous ost EE 43 3 2 2 Yuma Data Node Edit Variables val editvars t 44 3 2 3 Yuma Data Nodes val value EL tege teet errore rtr ner eorr rtr ee qn Fe cata deer VERSEN raa EES et 45 3 2 4 val_value_t Access MaC O05 EE 49 3 2 9 Val Value t Access F nctiONS ne a x Ora con te E AA AA E A 50 3 2 6 SIL Utility legt 55 4 SiL Ext rnal Interface EE 56 AA Stage L JEE EIER geet cte o ERR EEN 56 Ee EE e EE 59 ee EE 60 5 Slb CallbackInterfa EEN 61 5 1 RPC Operation Interfaca EE 62 5 E DT ES le e ei ae Een EE 62 5 1 2 RPC Message Header EE 63 5 1 3 SIL Support Functions For RPC Operations ccceeceeeeeee eee eee eee eee eeeaeeeeee eee een eee 66 5 1 4 RPC Validate Callback Function nete eee teret On Penick Sea ceca etter 66 5 1 5 RPC Invoke Callback E Lat dee DEE EE 69 5 1 6 RPC Post Reply Callback PUA COM eege gett et ore dvo ede 73 5 2 Database ODeratlonSissucscvssisessassawxcuarersacenes decd epe seh devia S bestiae Edge p des 75 5 2 1 Database Template cig template tye cesses ce tese ttes been etin tere E ES SX Ete peste 76 5 2 Database Access TF Uncblors EE
51. Yuma Developer Manual YANG Based Unified Modular Automation Tools Server Instrumentation Library Development Version 2 2 Last Updated January 31 2012 Yuma Developer Manual Table Of Contents Yuma Developer Manual T PRE GAC m T 4 e e EE En E EE 4 1 2 Additional e lee EE 4 IO WEB Site Siain Sege gege lee et A T2 2 Malling EE 5 1 3 Conventions Used in this Document 5 2 Software Overview M UL E 6 2 DN gg ele Tei ge QD ETIN DID Ute ES 6 2 1 1 Intended Audience EEN 6 2 1 2 What does Yuma Eege ee Ee deeg 6 2 1 3 WEL ER gt Ce TECH 7 2 1 4 Searching Y mMa ROOTS eaer a al edad cau m rM aa E tan da cix miro terius ue cuia t et cred 8 2 1 5 What 15 EE 9 2 1 6 Auto generated SILIFIIGS 6 roses bcd sre Pp tora e brav Qi ne iol ea nt es cerenutyn Boso e y eost dap QU Dr Rd 9 2 1 7 Basic Development Steps ech Dip Ger aree dE eh decedere Vd Edi ag 10 2 2 Yuma Source FH EE 11 2 2 oT SV E E DIEGGEOE nd SE e A die aa x o Pa M nd wads adeat ee 11 7 2 2 Sm platrormi DIFGCEOLUY EE 13 ee Lee ele M M PIE 14 de le el RT ele Me e RT T UM 15 2 2 5Src subsys Directo S Leger dee Pesce supe pisa danke deus tec a UE eO AU LESE Ne 16 2 216 Src netconfd Iisdem TTD TTE m 16 2 2 T Sty ANGE DIRECTO Y anna enaena aa aaa E AE EE E a E PA 16 2 2 8 src yangdiff DIFeGEOT EE 16 2 2 9 Src vangdurmp DIKGcEDEV EE 17 2 3 Server Desig Marire ve peo ea nnne queue ee
52. a conduit between the SSH server and the netconfd server Database management All configuration databases use a common configuration template defined in ncx cfg h Locking and other generic database functions are handled in this module Page 22 Version 2 2 Yuma Developer Manual The actual manipulation of the value tree is handled by API functions in ncx val h ncx val util h agt agt val parse h and agt agt val h e NETCONF operations All standard NETCONF RPC callback functions are located in agt agt ncx c All operations are completely automated so there is no server instrumentation APIs in this file e NETCONF request processing All lt rpc gt requests and replies use common data structures and APIs found in ncx rpc h and agt agt rpc h Automated reply generation automatic filter processing and message state data is contained in the RPC message control block e NETCONF error reporting All lt rpc error gt elements use common data structures defined in ncx rpc err h and agt agt rpcerr h Most errors are handled automatically but description statement semantics need to be enforced by the SIL callback functions These functions use the API functions in agt agt util h such as agt record error to generate data structures that will be translated to the proper lt rpc error gt contents when a reply is sent YANG module library management All YANG modules are loaded into a common data structure ncx module t located in ncx nc
53. act extension obj is xpath string Return TRUE if the object is a leaf or leaf list containing an XPath string obj is schema instance Return TRUE if the object is a leaf or leaf list string containing a schema instance identifier string obj is secure Return TRUE if object contains the nacm secure extension obj is very secure Return TRUE if object contains the nacm very secure extension obj is system ordered Return TRUE if the list or leaf list object is system ordered FALSE if it is user ordered obj is np container Return TRUE if the object is a YANG non presence container obj is enabled Return TRUE if the object is enabled FALSE if any if feature when stmt or deviation stmt has removed the object from the system obj sort children Rearrange any child nodes in YANG schema order 3 2 Data Tree A Yuma data tree is a representation of some subset of all possible object instances that a server is maintaining within a configuration database or other structure Each data tree starts with a root container and any child nodes represent top level YANG module data nodes that exist within the server Each configuration database maintains its own copy and version of the data tree There is only one object tree however and all data trees use the same object tree for reference Not all object types have a corresponding node within a data tree Only real data nodes are present Object nodes that are used as meta data to org
54. age sequence chart below shows the expected SIL callbacks for a delete xpo profile operation In this scenario the XPO container is populated with at last one profile prior to step 1 Page 99 Version 2 2 Yuma Developer Manual rpc edit config profile delete xpo profile edit validate xpo profile editcapply EN xpo profile edit apply EB xpo profile editecommit delete 1 The client issues an rpc edit config to delete a profile lt xml version 1 0 encoding UTF 8 lt rpc message id 10 xmins nc urn ietf params xml ns netconf base 1 0 xmlns urn ietf params xml ns netconf base 1 0 lt edit config xmlns urn ietf params xml ns netconf base 1 0 target candidate target lt default operation gt merge lt default operation gt lt config gt xpo xmlns nc urn ietf params xml ns netconf base 1 0 profile xmlns nc 2 urn ietf params xml ns netconf base 1 0 nc operation delete gt lt id gt 1 lt id gt lt profile gt lt xpo gt lt config gt lt edit config gt rpc Page 100 Version 2 2 Yuma Developer Manual 2 Netconf executes the xpo profile edit validate callback to validate the change to the candidate configuration 3 Netconf executes the xpo profile edit apply callback to apply the change to the candidate configuration 4 The client receives an rpc reply indicating success The client issues an rpc commit to commit the change to the running config
55. agttotals gt inSessions return NO ERR Version 2 2 Yuma Developer Manual else 1 return ERR NCX OPERATION NOT SUPPORTED agt_ses get_inSessions The following example from agt agt_state c shows a complex get callback function for the same data model which returns the entire lt capabilities gt element when it is requested This is done by simply cloning the official copy of the server capabilities that is maintained by the agt agt caps c module FE AK OK KK CK FK K FK K CE FK E CE CK K CE CE K K CE K K FK CE CE K OK CE K K K K FK CK CE CE FK K CE CE K K OK K FK CE CE K K E CE K OK K K K OK OK K E OK K OK OK OK K FUNCTION get caps get operation handler for the capabilities NP container x INPUTS i see ncx getcb h getcb fn t for details x RETURNS i status SK ok ok ok ok o K K K K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K OK CE CE CE CE CE CE CE CE CK CE CK CE CK K PK K K PK K K K K K K K K K SE K SE K 2K 2K 2K 2K 2K 2K K 2K K K K K A static status t get caps ses cb t scb getcb mode t cbmode val value t virval val value t dstval 1 val value t capsval status t res void scb void virval res NO ERR if cbmode GETCB GET VALUE capsval val clone agt cap get capsval if capsval return ERR INTERNAL MEM else change the namespace to this module and get rid of the netconf NSID g val_change_nsid capsval statemod gt nsid val move chil
56. ances It just defines the data instances that are allowed to exist on the server Raw YANG vs Cooked YANG Some of the nodes in this tree represent the exact YANG statements that the data modeler has used such as augment refine and uses but these noeds are not used directly in the object tree They exist in the object tree but they are processed to produce a final set of YANG data statements translated into cooked nodes in the object tree If any deviation statements are used by server implementation of a YANG data node to change it to match the actual platform implementation of the data node then these are also patched into the cooked YANG nodes in the object tree Page 20 Version 2 2 Yuma Developer Manual YANG Data Tree running candidate or startup Every data node is named by its module name and YANG identifier value lt module identifier gt A YANG data tree represents the instances of 1 or more of the objects in the object tree Each NETCONF database is a separate data tree A data tree is constructed for each incoming message as well The server has automated functions to process the data tree based on the desired NETCONF operation and the object tree node corresponding to each data node Every NETCONF node including database nodes are distinguished with XML Qualified Names QName The YANG module namespace is used as the XML namespace and the YANG identifier is used as the XML local name
57. and TBD XPath xml msg XML message data structures and support functions xmins XML Namespace registry xml util XML parse and utility functions Version 2 2 Yuma Developer Manual C Module Description xml val High level support functions for constructing XML ready val value t data structures xml wr XML output support functions and access control protected message generation support xpath1 XPath 1 0 implementation xpath XPath data structures and support functions xpath wr Support for generating XPath expression content within an XML instance document xpath yang Special YANG XPath construct support such as path expressions and instance identifiers yang YANG definitions and general support functions yang ext YANG parsing and validation of the extension statement yang grp YANG parsing and validation of the grouping statement yang obj YANG parsing and validation of the rpc notification and data definition statements yang parse Top level YANG parse and validation support yang typ YANG typedef and type statement support yin YANG to YIN mapping definitions yinyang YIN to YANG translation This directory contains platform support include files and Makefile support files It is used by all Yuma C modules to provide an insulating layer between Yuma programs and the hardware platform that is used For example the m getMem m getObj and m freeMem macros are used instead
58. and yuma source packages FKK KK K K FK FK FK FK K FK FK FK FK FK FK FK ook FK K KKK KK KKK K KK K K K K K K K K K K K K K FK FK FK FK FK K K K K K K K K KK KKK K KK K FUNCTION y toaster toaster edit Edit database object callback Path toaster Add object instrumentation in COMMIT phase INPUTS see agt agt_cb h for details RETURNS error status KKK ok ok oe K o K K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K CE CE CE 2K CE CK CE GE CK CE CK CE CK K PK K K K K K K K K K K K K SE K OE 2K 2K 2K K 2K 2K 2K K 2K K K K K static status t y toaster toaster edit ses cb t scb rpc msg t msg agt cbtyp t cbtyp op editop t editop val value t newval val value t curval status t res val value t errorval const xmlChar errorstr res NO ERR errorval NULL errorstr NULL switch cbtyp case AGT CB VALIDATE description stmt validation here break case AGT CB APPLY database manipulation done here break case AGT CB COMMIT device instrumentation done here Switch editop case OP EDITOR LOAD toaster enabled TRUE Page 81 Version 2 2 Yuma Developer Manual toaster toasting FALSE break case OP EDITOP MERGE break case OP EDITOP REPLACE break case OP EDITOP CREATE toaster enabled TRUE toaster toasting FALSE break case OP EDITOP DELETE toaster enabled FALSE if toaster toasting agt timer delete toaster timer id toa
59. anize the object tree e g choice augment are not present The following table lists the object types and whether each one is found in a data tree Page 42 Object Types in the Data Tree Object Type Found In Data Tree OBJ TYP ANYXML Yes OBJ TYP CONTAINER Yes OBJ TYP CONTAINER Yes ncx root OBJ TYP LEAF Yes OBJ TYP LEAF LIST Yes OBJ TYP LIST Yes Version 2 2 Yuma Developer Manual Object Type Found In Data Tree OBJ TYP CHOICE No OBJ TYP CASE No OBJ TYP USES No OB TYP REFINE No OBJ TYP AUGMENT No OBJ TYP RPC No OBJ TYP RPCIO No OBJ TYP NOTIF No The ncx btype t enumeration in ncx ncxtypes h is used within each val value t to quickly identify which variant of the data node structure is being used The following table describes the different enumeration values Yuma Data Types ncx btype t Page 43 Data Type Description NCX BT NONE No type has been set yet The val new value function has been called but no specific init function has been called to set the base type NCX BT ANY The node is a YANG anyxml node When the client or server parses an anyxml object it will be converted to containers and strings This type should not be used directly NCX BT BITS YANG bits data type NCX BT ENUM YANG enumeration data type NCX BT EMPTY YANG empty data type NCX BT BOOLEAN YANG boolean data type
60. ares that the database object is a very secure object Only the superuser will be allowed to access the object by default ncx xsdlist ist type Declares that a string data type is really an XSD style list list type is a valid type name with optional YANG prefix List processing within lt edit config gt will be automatically handled by netconfd ncx xpath Declares that a string data type is really an XPath expression XML prefixes and all XPath processing will be done automatically by yangcli and netconfd The following table highlights the SIL functions in ncx ncx appinfo h that allow SIL code to examine any of the non standard language statements that were found in the YANG module Language Extension Access Functions Function Description ncx find appinfo Find an ncx appinfo t structure by its prefix and name in a queue of these entries ncx find next appinfo Find the next occurrence of the specified ncx appinfo t data structure ncx clone appinfo Clone the specified ncx appinfo t data Page 110 Version 2 2 Page 111 Yuma Developer Manual Function Description structure Version 2 2
61. ate a file called startup cfg xml in the following manner o Ifthe SYUMA HOME variable is set the configuration will be saved in YUMA HOME data startup cfg xml o Otherwise the configuration will be saved in HOME yuma startup cfg xml The database is saved as an XML instance document using the config element in the NETCONF base namespace as the root element Each top level YANG module supported by the server which contains some explicit configuration data will be saved as a child node of the lt nc config gt element There is no particular order to the top level data model elements There are several YANG modules which are implemented within the server and not loaded at run time like a dynamic SIL module Some of them are NETCONF standard modules and some are Yuma extension modules Page 33 Version 2 2 Yuma Developer Manual This module contains the standard YANG Internet address types These types are available for commonly used management object types A YANG module author should check this module first before creating any new data types with the YANG typedef statement There are no accessible objects in this module so there are no SIL callback functions The YANG data types are supported within the Yuma engine core modules such as ncx val c and ncx xml wr c The standard NETCONF Monitoring module is used to examine the capabilities current state and statistics related to the NETCONF server The entire module i
62. ations 5 e Top Level The top level incoming messages are registered not hard wired in the server message processing design The agt ncxserver module accepts the lt ncxconnect gt message from netconf subsystem The agt rpc module accepts the NETCONF lt rpc gt message Additional messages can be supported by the server using the top register node function e All RPC operations are implemented in a data driven fashion by the server Each NETCONF operation is handled by a separate function in agt ncx c Any proprietary operation can be automatically supported using the agt rpc register method function o Note Once the YANG module is loaded into the server all RPC operations defined in the module are available If no SIL code is found these will be dummy no op functions This mode can be used to provide some server simulation capability for client applications under development e All database operations are performed in a structured manner using special database access callback functions Not all database nodes need callback functions One callback function can be used for each phase or the same function can be used for multiple phases The agt cb register callback function in agt agt cb c is used by SIL code to hook into NETCONF database operations 2 4 Server Operation This section briefly describes the server internal behavior for some basic NETCONF operations Page 27 Version 2 2 Yuma Developer Manual The file n
63. atus object The function agt make virtual leaf in agt agt util h is a common API used for creating a virtual leaf within an existing parent container The following typedef defines the getcb fn t template used by all virtual callback functions This function is responsible for filling in a value node with the current instance value The status NO ERR is returned if this is done successfully getcb fn t x Callback function for agent node get handler INPUTS scb session that issued the get may be NULL can be used for access control purposes cbmode reason for the callback virval place holder node in the data model for this virtual value node dstval pointer to value output struct OUTPUTS fil may be adjusted depending on callback reason dstval should be filled in depending on the callback reason x RETURNS S Status SE typedef status t getcb fn t ses cb t scb getcb mode t cbmode const val value t virval val value t dstval The following table describes the parameters Page 84 Version 2 2 Yuma Developer Manual getcb fn t Parameters Parameter Description scb This is the session control block making the request if available This pointer may be NULL so in the rare event this parameter is needed by the SIL callback function it should be checked first cbmode The callback type The only supported enumeration at this time is GETCB GET VALUE Other
64. brary so it is available to the netconfd server o Use the make install command in the SIL erc directory o Example mydir test src gt sudo make install Page 10 Version 2 2 Yuma Developer Manual e Run the netconfd server or build it again if linking with static libraries Load the new module o Be sure to add a load command to the configuration file if the module should be loaded upon each reboot o yangcli Example load test The netconfd server will load the specified YANG module and the SIL and make it available to all sessions This section describes the files that are contained in the yuma source package The important C include files are copied into usr include yuma when the yuma dev package is installed The full set of installation sources is installed in usr share yuma src if the yama source package is installed Yuma tools will check the YUMA HOMEJ src sub tree before checking this default installation location This allows a working copy of the Yuma sources to be used instead of the installation copy in case it has been modified for a particular embedded system for example This section lists the files that are included within the netconf src directory This directory contains the code that is used to build the libncx so binary shared library that is used by all Yuma Tools programs It handles many of the core NETCONF YANG data structure support including all of the YANG YIN XML and XPath processing
65. bxml endif endif added sw include for MacOSX ifdef MAC MACOSX version CINC I sw include CFLAGS DMACOSX 1 endif LBASE lib ifdef DESTDIR OWNER else ifdef MAC OWNER oroot else OWNER owner root endif endif GCC LINUX or MACOSX CWARN Wall Wno long long Wformat y2k Winit self Wmissing include dirs Wswitch default Wunused parameter Wextra Wundef Wshadow Wpointer arith Wwrite strings Wbad function cast Wcast qual Wcast align Waggregate return Wstrict prototypes Wold style definition Wmissing prototypes Wmissing declarations Wpacked Winvalid pch Wredundant decls Wnested externs Winline std gnu99 Werror Wunreachable code removed due to 03 Version 2 2 Page 106 Yuma Developer Manual 03 changed to 02 due to code bloat from inline functions CDEFS DDEBUG DLINUX DGCC ifndef NOFLOAT CDEFS DHAS FLOAT endif CFLAGS CDEFS CWARN fPIC production 0 or debug 1 build ifdef DEBUG CFLAGS ggdb3 else CFLAGS 02 endif memory leak debugging mode ifdef MEMTRACE CFLAGS DMEMORY_DEBUG 1 endif free or SDK version ifdef FREE CFLAGS DFREE_VERSION endif ifdef RELEASE CFLAGS DRELEASE RELEASE endif ifdef MAC GRP else ifdef DESTDIR GRP else GRP group root endif endif ifdef STATIC LIBSUFFIX a else ifdef MAC LIBSUFFIX dylib else LIBSUFFIX so endif endif CC gcc LINK gcc
66. cfg unlock Release the global lock on the database cfg release locks Release all locks on all databases The file agt agt cb h contains functions that a SIL developer needs to register and unregister database edit callback functions The same callback function can be used for different phases if desired The following function template definition is used for all SIL database edit callback functions Callback function for agent object handler Used to provide a callback sub mode for a specific named object INPUTS scb session control block making the request msg incoming rpc msg t in progress cbtyp reason for the callback editop the parent edit config operation type which Se is also used for all other callbacks Se that operate on objects newval container object holding the proposed changes to Page 78 Version 2 2 Yuma Developer Manual Ds apply to the current config depending on 2 the editop value Will not be NULL a curval current container values from the running E or candidate configuration if any Could be NULL x for create and other operations RETURNS ch Status typedef status t agt cb fn t ses cb t scb rpc msg t msg agt cbtyp t cbtyp op editop t editop val value t newval val value t curval SIL Database Callback Template Parameter Description scb The session control block making the edit request
67. d first This is essentially the same as the real apply phase except that changes are made to a copy of the target database Once all objects have been altered as requested the entire test database is validated including all cross referential integrity tests If this test completes without any errors then the procedure is repeated on the real target database o Note This phase is used for the internal data tree manipulation and validation only It is not used to alter device behavior Resources may need to be reserved during the SIL apply callback but the database changes are not activated at this time e Commit or Rollback Phase If the validate and apply phases complete without errors then then the server will search for SIL commit callback functions for the affected node s in the Page 32 Version 2 2 Yuma Developer Manual target database This SIL callback phase is used to apply the changes to the device and or network It is only called when a commit procedure is attempted This can be due to a lt commit gt operation or an lt edit config gt or lt copy config gt operation on the running database o Note If there are errors during the commit phase then the backup configuration will be applied and the server will search for a SIL callback to invoke with a rollback operation The same procedure is used for confirmed commit operations which timeout or canceled by the client The following bullets describe how the server saves
68. d for a leaf or leaf list object obj get parent Get the parent object node for an object obj get presence string Get the YANG presence statement for a container object obj get child count Get the number of child nodes for a complex object obj get fraction digits Get the YANG fraction digits statement for a decimal64 leaf or leaf list object obj is leafy Return TRUE if the object is a leaf or leaf list type obj is mandatory Return TRUE if the object is YANG mandatory obj is mandatory when Return TRUE if the object is YANG mandatory but first check if any when statements are FALSE first obj is cloned Return TRUE if the object is expanded from a grouping or augment statement obj is data db Return TRUE if the object is defined within a YANG database definition obj in rpc Return TRUE if the object is defined within an RPC statement obj in notif Return TRUE if the object is defined within a notification statement obj is hidden Return TRUE if object contains the ncx hidden extension obj is root Return TRUE if object contains the ncx root extension obj is password Return TRUE if object contains the ncx password extension Version 2 2 Yuma Developer Manual Function Description obj is cli Return TRUE if object contains the ncx cli extension obj is abstract Return TRUE if object contains the ncx abstr
69. date callback for the candidate configuration e Netconf executes the profile id edit validate callback for the candidate configuration e Netconf executes the profile streamConnection edit validate callback for the candidate configuration e Netconf executes the profile streamConnection id edit validate callback for the candidate configuration e Netconf executes the profile streamConnection sourceld edit validate callback for the candidate configuration e Netconf executes the profile streamConnection bitrate edit validate callback for the candidate configuration e Netconf executes the profile edit apply callback for the candidate configuration e Netconf executes the profile id edit apply callback for the candidate configuration e Netconf executes the profile streamConnection edit apply callback for the candidate configuration e Netconf executes the profile streamConnection id edit apply callback for the candidate configuration e Netconf executes the profile streamConnection sourceld edit apply callback for the candidate configuration e Netconf executes the profile streamConnection bitrate edit apply callback for the candidate configuration e The client receives an rpc reply indicating success e The client issues an roc commit to commit the change to the running configuration e Netconf executes the profile edit apply callback for the running configuration e Netconf executes the profile_id_edit
70. de an XML instance document SC struct obj template t X casobj these fields are for NCX BT LEAFREF NCX BT INSTANCE ID or tagged ncx xpath value stored in v union as a string S struct xpath pcb t_ xpathpcb union of all the NCX specific sub types note that the following invisible constructs should never show up in this struct NCX BT CHOICE NCX BT CASE NCX BT UNION EG union v complex types have a Q of val value t representing the child nodes with values NCX BT CONTAINER NCX BT LIST diq hdr t childQ Numeric data types NCX BT INT8 NCX BT_INT16 MO BT INT32 NCX BT INT64 NCX BT UINT8 NCX BT UINT16 NCX BT UINT32 NCX BT UINT64 NCX BT DECIMAL64 NCX BT FLOAT64 ncx num t num String data types NCX BT STRING NCX BT INSTANCE ID SCH ncx str t str val idref t idref ncx binary t binary NCX BT BINARY ncx list t list NCX BT BITS NCX BT SLIST boolean boo NCX BT EMPTY NCX BT BOOLEAN ncx enum t enu NCX BT UNION NCX BT ENUM xmlChar fname NCX BT EXTERN xmlChar intbuff NCX BT INTERN v val value t The following table highlights the fields in this data structure Page 47 Version 2 2 Page 48 Yuma Developer Manual val value t Fields Field Description qhdr Internal queue header to allow a value node to be stored in a queue A complex no
71. de maintains a child queue of val value t nodes obj Back pointer to the object template for this data node typdef Back pointer to the typedef structure if this is a leaf or leaf list node name Back pointer to the name string for this node dname Malloced name string if the client or server changed the name of this node so the object node name is not being used This is used for anyxml processing and other things to allow generic objects container string empty etc to be used to represent the contents of an anyxml node parent Back pointer to the parent of this node if any nsid Namespace ID for this node This may not be the same as the object node namespace ID e g anyxml child node contents will override the generic object namespace btyp The ncx btype t base type enumeration for this node This is the final resolved value in the event the object type is not a final resolved base type flags Internal flags field Do not access directly dataclass Internal config or non config enumeration metaQ Queue of val value t structures that represent any meta variables XML attributes found for this data node For example the NETCONF filter type and select attributes are defined for the filter element in yuma netconf yang editvars Pointer to the malloced edit variables structure for this data node This node will be freed and NULL value when t
72. defpath Absolute path expression string indicating which node the callback function is for version If non NULL indicates the exact module version expected cbfn The callback function address This function will be used for all callback phases extern status t agt cb register callbacks const xmlChar modname const xmlChar defpath const xmlChar version const agt cb fnset t cbfnset agt cb register callbacks Parameter Description modname Module name string that defines this object node defpath Absolute path expression string indicating which node the callback function is for version If non NULL indicates the exact module version expected cbfnset The callback function set structure fillied in with the addesses of all desired callback phases Any NULL slots will cause that phase to be skipped The agt cb unregister callbacks function is called during the module cleanup It is generated by yangdump automatically for all RPC operations extern void agt cb unregister callbacks const xmlChar modname const xmlChar defpath agt cb unregister callbacks Page 80 Version 2 2 Yuma Developer Manual Parameter Description modname Module name string that defines this object node defpath Absolute path expression string indicating which node the callback function is for The following example code is from the libtoaster source code available in yuma dev
73. directly to generate XPath results for NETCONF and YANG purposes NETCONF uses XPath differently than XSLT and libxml2 XPath processing is memory intensive These functions are located in ncx xpath h ncx xpath1 h and ncx xpath yang h XPath filtered get responses are generated in agt agt xpath c Logging service Encapsulates server output to a log file or to the standard output filtered by a configurable log level Located in ncx log h In addition the macro SET ERROR in ncx status h is used to report programming errors to the log Session management All server activity is associated with a session The session control block and API functions are located in ncx ses h All input output access control and protocol operation support is controlled through the session control block ses cb t Timer service A periodic timer service is available to SIL modules for performing background maintenance within the main service loop These functions are located in agt agt timer h Connection management All TCP connections to the netconfd server are controlled through a main service loop located in agt agt ncxserver c It is expected that the select loop in this file will be replaced in embedded systems The default netconfd server actually listens for local lt ncx connect gt connections on an AF LOCAL socket The openSSH server listens for connections on port 830 or other configured TCP ports and the netconf subsystem thin client acts as
74. dren capsval dstval val free value capsval else res ERR NCX OPERATION NOT SUPPORTED return res get caps Page 86 Version 2 2 Yuma Developer Manual The yangdump program will automatically generate functions to queue a specific notification type for processing It is up to the SIL callback code to invoke this function when the notification event needs to be generated The SIL code is expected to provide the value nodes that are needed for any notification payload objects The function to generate a notification control block and queue it for notification replay and delivery is generated by the yangdump program A function parameter will exist for each top level data node defined in the YANG notification definition In the example below the toastDone notification event contains just one leaf called the toastStatus There is SIL timer callback code which calls this function and provides the final toast status after the lt make toast gt operation has been completed or canceled DK OK OK AK K K OK FK K ok ok ok ok ok ok ok ok o K FK KE OK 2K OK OK OK SE OK FK K K OK K o FK K FK oo o o FK K FK K 2K 2K 2K 2K OK K K OK K K K OK K K K K K o E K K K FUNCTION y toaster toastDone send Send a y toaster toastDone notification Called by your code when notification event occurs GE DK KOK FK K OK FK K FK FK K CK CE CK CK K CE CE K CE CE K K FK CE CK CK E CE K K FK K K CR E CE K K CE CE SK K OK K FK CE CE K K
75. e This typedef defines the callback function template expected by the server for use with the timer service timer callback function k Process the timer expired event INPUTS i timer id timer identifier X cookie context pointer such as a session control block d passed to agt timer set function may be NULL x RETURNS 2 0 normal exit 1 error exit delete timer upon return typedef int agt timer fn t uint32 timer id void cookie The following table describes the parameters for this callback function SIL Timer Callback Function Parameters Parameter Description timer id The timer ID that was returned when the agt timer create function was called cookie The cookie parameter value that was passed to the server when the agt timer create function Page 88 Version 2 2 Yuma Developer Manual Parameter Description was called A SIL timer can be set up as a periodic timer or a one time event The timer interval in seconds and the SIL timer callback function are provided when the timer is created A timer can also be restarted if it is running and the time interval can be changed as well The following table highlights the SIL timer access functions in agt agt timer h SIL Timer Access Functions Function Description agt timer create Create a SIL timer agt timer restart Restart a SIL timer agt timer delete Delete a SIL
76. e was an nc operation attribute found in this node FALSE if the editop is derived from its parent pcookie SIL user pointer cookie Not used by the server Reserved for SIL callback code icookie SIL user integer cookie Not used by the server Reserved for SIL callback code The val value t data structure is used to maintain the internal representation of all NETCONF databases non configuration data available with the get operation all RPC operation input and output parameters and all notification contents The following typedef is used to define a value node Page 45 Version 2 2 Page 46 Yuma Developer Manual one value to match one type typedef struct val value t iA E kA ua eds ed ud py iA 7 dlq_hdr_t qhdr common fields struct obj template t obj bptr to object def typ def t typdef bptr to typdef if leaf const xmlChar name back pointer to elname xmlChar dname AND malloced name if needed struct val value t parent back ptr to parent if any xmlns id t nsid namespace ID for this node ncx btype t btyp base type of this value uint32 flags internal status flags ncx data class t dataclass config or state data YANG does not support user defined meta data but NCX does The edit config get and get config operations use attributes in the RPC parameters the metaQ is still used x The ncx metadata exte
77. etconfd netconfd c contains the initial main function that is used to start the server The common services support for most core data structures is located in libncx so The ncx init function is called to setup these data structures This function also calls the bootstrap cli function in ncx ncx c which processes some key configuration parameters that need to be set right away such as the logging parameters and the module search path e Most of the actual server code is located in the agt directory The agt init1 function is called to initialize core server functions The configuration parameters are processed and the server profile is completed o The agt profile t data structure in agt agt h is used to contain all the vendor related boot time options such as the database target candidate or running The init server profile function can be edited if the Yuma default values are not desired This will insure the proper factory defaults for server behavior are used even if no configuration parameters are provided e The function init server profile in agt agt c is used to set the factory defaults for the server behavior The agt init1 function also loads the core NETCONF protocol netconfd CLI and YANG data type modules e Note netconfd uses yuma netconf yang not ietf netconf yang to support a data driven implementation The only difference is that the yuma version adds some data structures and extensions such as ncx root
78. gister_method function in agt agt_rpc h is used to provide a callback function for a specific callback phase The same function can be used for multiple phases if desired Template for RPC server callbacks The same template is used for all RPC callback phases Page 62 Version 2 2 Yuma Developer Manual typedef status t agt rpc method t ses cb t scb rpc msg t msg xml node t methnode extern status t agt rpc register method const xmlChar module const xmlChar method name agt rpc phase t phase agt rpc method t method agt rpc register method Parameter Description module The name of the module that contains the rpc statement method name The identifier for the rpc statement phase AGT PH VALIDATE 0 validate phase AGT PH INVOKE 1 invoke phase AGT PH POST REPLY 2 post reply phase method The address of the callback function to register The NETCONF server will parse the incoming XML message and construct an RPC message header which is used to maintain state and any other message specific data during the processing of an incoming lt rpc gt request The rpc_msg t data structure in ncx rpc h is used for this purpose The following table summarizes the fields rpc_msg t Field Type User Description Mode qhdr do hdr t none Queue header to store RPC messages in a queue within the session header mhdr xml msg hd none XML message prefix map and other data rt used to par
79. he case if the module is be tested by an application developer using netconfd as a server simulator It is enabled with the agt rpc register method function within the phase 1 initialization callback function The yangdump code generator will create this SIL callback function by default There will C comments in the code to indicate where your additional C code should be added The val find child function is commonly used to retrieve particular parameters within the RPC input section which is encoded as a val value t tree The rpc user1 and rpc user2 cache pointers in the rpc msg t structure can also be used to store data in the validation phase so it can be immediately available in the invoke phase The agt record error function is commonly used to record any internal or platform specific errors In the libtoaster example if the request to create a timer callback control block fails then an error is recorded Page 70 Version 2 2 For RPC operations that return either an ok or lt rpc error gt response there is nothing more required Yuma Developer Manual of the RPC invoke callback function For operations which return some data or lt rpc error gt the SIL code must do 1 of 2 additional tasks e adda val value t structure to the rpc dataQ queue in the rpc msg t for each parameter listed in the YANG rpc output section e set the rpc datacb pointer in the rpc msg t structure to the address of your data reply callback fu
80. he edit variables are not in use res Internal validation result status for this node during editing or parsing getcb Internal server callback function pointer Used only if this is a virtual node and the actual value node contents are generated by a SIL callback function instead of being stored in the node itself virtualval The temporary cached virtual node value if the getcb pointer is non NULL indexQ Queue of internal data structures used during parsing and filtering streamed output casobj Back pointer to the OBJ TYP CASE object node for this data node if this node is a top level child of a YANG case statement xpathpcb XPath parser control block used if this value contains Version 2 2 Yuma Developer Manual Field Description some sort of XPath string or instance identifier For example the XML namespace ID mappings are stored so the XML prefix map generated for the lt rpc reply gt will contain and reuse the proper namespace attributes as needed V Union of different internal fields depending on the btyp field value v childQ Queue of val value t child nodes if this is a complex node v num ncx num t for all numeric data types v str Malloced string value for the string data type v idref Internal data structure for the YANG identityref data type v binary Internal data structure for the YANG binary data type
81. he module The agt create cache function in agt agt util h is used to initialize such a module static variable Name Format y modname init2 Returns e operation status 0 if success Example function generated by yangdump FK KK K KK FK K FK FK K FK FK OK CK K CE FK OK K OK K K FK CE CE K E CE K K 2K K FK FK K CE FK K CE CE K FK OK K FK E K K K OK CE K OK K OK K OK OK OK OK OK K OK OK OK K FUNCTION y toaster_init2 x SIL init phase 2 non config data structures Called after running config is loaded E E x RETURNS error status 2K 2K 2K OK 2K EE E K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K status_t y_toaster_init2 void status t res res NO ERR toaster val agt_init_cache y_toaster M toaster y_toaster N toaster amp res if res NO_ERR return res put your init2 code here return res y toaster init2 The cleanup function is called during server shutdown It is only called if the stage 1 initialization function is called It will be called right away if either the stage 1 or stage 2 initialization functions return a non zero error status This callback function is expected to perform the following functions Page 60 Version 2 2 Yuma Developer Manual e cleanup any module static data e free any top level object cache pointers if needed e unregister any RPC method callbacks with agt
82. ion is called and that function is expected to call the ncxmod load module function If no SIL file can be found for the module then the server will load the YANG module anyway and support database operations for the module for provisioning purposes Any RPC operations defined in the module will also be accepted depending on access control settings but the action will not actually be performed Only the input parameters will be checked and or or some lt rpc error gt returned The agt init2 function in agt agt c is called after the configuration parameters have been collected o Initialize the core server code modules o Static device specific modules can be added to the agt init2 function after the core modules have been initialized o Any module parameters found in the CLI or server configuration file are processed o The agt cap set modules function in agt agt cap c is called to set the initial module capabilities for the ietf netconf monitoring module After the static and dynamic server modules are loaded the startup or no startup parameter is processed by agt init2 in agt agt c e Ifthe startup parameter is used and includes any sub directories it is treated as a file and must be found as specified e Otherwise the YUMA DATAPATH environment variable or datapath configuration parameter can be used to determine where to find the startup configuration file If neither the startup or no startup configurat
83. ion parameter is present then the data search path will be used to find the default startup cfg xml Page 29 Version 2 2 Yuma Developer Manual The YUMA HOME environment variable or yuma home configuration parameter is checked if no file is found in the data search path The YUMA_HOME data directory is checked if this parameter is set The YUMA INSTALL environment variable or default location etc yuma is checked next if the startup configuration is still not found It is a fatal error if a startup config is specified and it cannot be found As the startup configuration is loaded any SIL callbacks that have been registered will be invoked for the association data present in the startup configuration file The edit operation will be OP EDITOP LOAD during this callback After the startup configuration is loaded into the running configuration database all the stage 2 initialization routines are called These are needed for modules which add read only data nodes to the tree containing the running configuration SIL modules may also use their init2 function to create factory default configuration nodes which can be saved for the next reboot 5 Phase RPC Processing Model Optional Callbacks e PARSE Phase The incoming buffer is converted to a stream of XML nodes using the xmlTextReader functions from libxml2 The agt val parse function is used to convert the stream of XML nodes to a val value t structure representing
84. ion statements and the new or altered default value specified there In addition range statements patterns XPath expressions and all other machine readable statements are all processed automatically so the YANG statements themselves are like server source code YANG also allows vendor and platform specific deviations to be specified which are like generic patches to the common YANG module for whatever purpose needed YANG also allows annotations to be defined and added to YANG modules which are specified with the extension statement Yuma uses some extensions to control some automation features but any module can define extensions and module instrumentation code can access these annotation during server operation to control device behavior There are CLI parameters that can be used to control parser behavior such as warning suppression and protocol behavior related to the YANG content such as XML order enforcement and NETCONF Page 19 Version 2 2 Yuma Developer Manual protocol operation support These parameters are stored in the server profile which can be customized for each platform YANG Object Tree The YANG statements found in a module are converted to internal data structures For NETCONF and database operations a single tree of obj template t data structures is maintained by the server This tree represents all the NETCONF data that is supported by the server It does not represent any actual data structure inst
85. is is only available if the startup capability is advertised by the server The value tree for this database contains only configuration data nodes NETCONF also recognized external files via the lt url gt parameter if the url capability is advertised by the server These databases will be supported in a future release of the server The NETCONF standard does not require that these external databases support the same set of protocol operations as the standard databases listed above A client application can reliably copy from and to an external database but editing and filtered retrieval may not be supported The following typedef is used to define a NETCONF database template struct representing 1 configuration database typedef struct cfg template t dlq hdr t qhdr ncx cfg t cfg id cfg location t cfg loc cfg state t cfg state xmlChar name xmlChar src url xmlChar load time xmlChar lock time xmlChar last ch time uint32 flags ses id t locked by cfg source t lock src diq hdr t load errQ Q of rpc err rec t val value t root btyp container cfg template t The following table highlights the fields in the cfg template t data structure cfg template t Fields Page 76 Version 2 2 Yuma Developer Manual Field Description qhdr Queue header to allow the object template to be stored in a queue cfg_id Internal configuration
86. its own SSH server Aclient request to start an SSH session results in an SSH channel being established to an instance of the netconf subsystem program Page 25 Version 2 2 Yuma Developer Manual The netconf subsystem program will open a local socket tmp ncxserver sock and send a proprietary lt ncxconnect gt message to the netconfd server which is listening on this local Socket with a select loop in agt ncxserver c e When a valid lt ncxconnect gt message is received by netconfd a new NETCONF session is created After sending the lt ncxconnect gt message the netconf subsystem program goes into transfer mode and simply passes input from the SSH channel to the netconfd server and passes output from the netconfd server to the SSH server e The ncxserver loop simply waits for input on the open connections with a quick timeout Each timeout the server checks if a reboot shutdown signal or other event occurred that needs attention e Notifications may also be sent during the timeout check if any events are queued for processing The max burst configuration parameter controls the number of notifications sent to each notification subscription during this timeout check e Input lt rpc gt messages are buffered and when a complete message is received based on the NETCONF End of Message marker it is processed by the server and any instrumentation module callback functions that are affected by the request Whe
87. lling any SIL e parse the RPC operation element and find its associated YANG rpc template e if found check if the session is allowed to invoke this RPC operation e if the RPC is allowed parse the rest of the XML message using the rpc template t for the RPC operation to determine if the basic structure is valid e ifthe basic structure is valid construct an rpc msg t data structure for the incoming message Page 61 Version 2 2 Yuma Developer Manual e check all YANG machine readable constraints such as must when if feature min elements etc e if the incoming message is completely YANG valid then the server will check for an RPC validate function and call it if found This SIL code is only needed if there are additional system constraints to check For example o need to check if a configuration name such as lt candidate gt is supported o need to check if a configuration database is locked by another session o need to check description statement constraints not covered by machine readable constraints o need to check if a specific capability or feature is enabled e Ifthe validate function returns a NO ERR status value then the server will call the SIL invoke callback if it is present This SIL code should always be present otherwise the RPC operation will have no real affect on the system e At this point an lt rpc reply gt is generated based on the data in the rpc msg t o Errors are recorded in a queue when
88. lt apply gt callback for the running configuration Page 96 Version 2 2 Yuma Developer Manual e Netconf executes the profile streamConnection edit apply callback for the running configuration e Netconf executes the profile streamConnection id edit apply callback for the running configuration e Netconf executes the profile streamConnection sourceld edit apply callback for the running configuration e Netconf executes the profile streamConnection bitrate edit apply callback for the running configuration e Netconf executes the profile edit commit create callback for the running configuration e Netconf executes the profile id edit commit create callback for the running configuration e Netconf executes the profile streamConnection edit commit create callback for the running configuration e Netconf executes the profile streamConnection id edit commit create callback for the running configuration e Netconf executes the profile streamConnection sourceld edit commit create callback for the running configuration e Netconf executes the profile streamConnection bitrate edit commit create callback for the running configuration e The client receives an rpc reply indicating success The message sequence chart below shows the expected SIL callbacks for a delete xpo container operation In this scenario the XPO container is populated with at last one profile prior to step 1 Page 97 Version 2 2 Yuma De
89. lt is not to generate symbols and instead use O2 optimization ETC_PREFIX Build etc install directory to use default etc LIB64 1 Build so that SIL libraries are installed in the libe4 directory MAC 1 Build the software for the MacOSX platform MEMTRACE 1 Enabled mtrace memory leak debugging to identify the exact nodes which were malloced but never freed NOFLOAT 1 Defining this make flag will force the server to implement XPath numbers with a string representation instead of using the double data type from the floating point library Version 2 2 Yuma Developer Manual Make Parameter Description This will impact the correctness of XPath expression evaluation so this should not be done unless the lt math h gt library support is not available Required for CYGWIN 1 PREFIX string Build Root path to use default usr RELEASE n Builds release n version release for Ubuntu or RPM package distribution STATIC 1 Build static libraries instead of dynamic libraries where needed This sometimes makes debugging simpler and faster Embedded systems without dynamic library support need to use this make option Required for CYGWIN 1 STATIC_SERVER Defining this make flag forces the server not to require or use the dylib functions to dynamically load SIL libraries at run time without requiring ldconfig Instead the server will assume the server code has been modified so these SIL libraries a
90. lue matched a valid user name The server will make sure the user name is well formed and could be a valid user name The callback function for this phase is called when database edits are being applied to the running configuration The resources needed for the requested operation may be reserved at this time if needed Page 83 Version 2 2 Yuma Developer Manual This callback function for this phase is called when database edits are being committed to the running configuration The SIL callback function is expected to finalize and apply any data model dependent system behavior at this time This callback function for this phase is called when database edits are being undone after some apply phase or commit phase callback function returned an error or a confirmed commit operation timed out The SIL callback function is expected to release any resources it allocated during the apply or commit phases Usually only the commit or the rollback function will be called for a given SIL callback but it is possible for both to be called For example if the rollback on error option is in effect and some SIL commit callback fails after your SIL commit callback succeeds then your SIL rollback callback may be called as well A common SIL callback function to use is a virtual node get function A virtual node can be either a configuration or non configuration node but is more likely to be a non configuration node such as a counter or hardware st
91. me to load e revision string containing revision date to use NULL if the operator did not specify a revision Returns e operation status 0 if success Example function generated by yangdump SOA AA k KK k kkk k kkk ook ok KKK K aK aK ook K 2k 2k 2k KK KK FUNCTION y toaster init x initialize the toaster server instrumentation library E x INPUTS modname requested module name i revision requested version NULL for any E x E RETURNS error status 2K 2K 2K OK 2K EE E K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K K status_t y toaster init const xmlChar modname const xmlChar revision agt profile t agt profile status t res Page 57 Version 2 2 Yuma Developer Manual y toaster init static vars change if custom handling done if xml strcmp modname y toaster M toaster return ERR NCX UNKNOWN MODULE if revision amp amp xml strcmp revision y toaster R toaster return ERR NCX WRONG VERSION agt profile agt get profile res ncxmod load module y toaster M toaster y toaster R toaster amp agt profile agt savedevQ amp toaster mod if res NO ERR return res toaster obj ncx find object toaster mod y toaster N toaster if toaster mod NULL return SET ERROR ERR NCX DEF NOT FOUND make toast obj ncx find object toaster mod y toaster N make
92. ming lt rpc reply gt messages from the NETCONF server mgr ses Handles all aspects of client NETCONF sessions mgr signal Client signal handler mgr top Client registration and dispatch of top level XML messages mgr val parse Incoming lt rpc reply gt notification2 and config content parse and complete YANG constraint validation mgr xml Client XML processing interface to ncx xml util functions Version 2 2 Yuma Developer Manual This directory contains the netconf subsystem program This is a thin client application that just transfers input and output between the SSH server and the NETCONF server It contains one C source module called netconf subsystem This is a stand alone binary that is part of the yama server package It is installed in the usr sbin directory This directory contains the netconfd program which implements the NETCONF server It contains one C module called netconfd which defines the NETCONF server main function This is a stand alone binary that is part of the yuma server package It is installed in the usr sbin directory This directory contains the yangcli program which is the Yuma NETCONF client program This is a stand alone binary that is part of the yuma client package It is installed in the usr bin directory The following table describes the C modules contained in this directory src yangcli C Modules C Module Description yangcli NETCONF client program provides in
93. ms function This module contains the Yuma interfaces table which is just a skeleton configuration list plus some basic interface counters This module is intended to provide an example for embedded developers to replace this module with their own interfaces table The Yuma table uses information in some files found in Unix systems which support the proc net dev system file The file agt agt if c contains the SIL callback functions for this module This module provides the Yuma proprietary lt get my session gt and lt set my session gt RPC operations These are used by the client to set some session output preferences such as the desired line length indentation amount and defaults handling behavior The file agt agt ses c contains the SIL callback functions for this module This module contains the Yuma NETCONF Access Control Model implementation It provides all user configurable access control settings and also provides API functions to check if a specific access request should be allowed or not The file agt agt acm c contains the SIL callback functions for this module This module provides the YANG language extension statements that are used by Yuma programs to automate certain parts of the NETCONF protocol document generation code generation etc There are no SIL callback functions for this module There are support functions within the src ncx directory that include the obj set ncx flags function in ncx obj c The NETCONF
94. n the agt ncxserver run function in agt agt ncxserver c is replaced within an embedded system the replacement code must handle the following tasks Call agt ses new session in agt agt ses c when a new NETCONF session starts e Call ses accept input in ncx ses c with the correct session control block when NETCONF data is received e Call agt ses process first ready in agt agt ses c after input is received This should be called repeatedly until all serialized NETCONF messages have been processed Call agt ses kill session in agt agt ses c when the NETCONF session is terminated e The following functions are used for sending NETCONF responses if responses are buffered instead of sent directly streamed o ses msg send buffs in ncx ses msg c is used to output any queued send buffers e The following functions need to be called periodically o agt shutdown requested in agt agt util c to check if the server should terminate or reboot o agt ses check timeouts in agt agt ses c to check for idle sessions or sessions stuck waiting for a NETCONF lt hello gt message o agt timer handler in agt agt timer c to process server and SIL periodic callback functions o send some notifications in agt agt ncxserver c to process some outgoing notifications Page 26 Version 2 2 Yuma Developer Manual NETCONF Callback Points top register node agt rpc register method remote procedure call agt cb register callback database edit oper
95. name field obj has text content Return TRUE if the object has text content obj get status Get the YANG status for the object obj get description Get the YANG description statement for an object Note that the server will always return a NULL pointer obj get reference Get the YANG reference statement for an object Note that the server will always return a NULL pointer obj get config flag Get the YANG config statement value for an object Version 2 2 Yuma Developer Manual Function Description obj get typestr Get the name string for the type of an object obj get default Get the YANG default value for an object obj get default case Get the name of the default case for a choice object obj get typdef Get the internal type definition for the leaf or leaf list object obj get basetype Get the internal base type enumeration for an object obj get mod prefix Get the module prefix for an object obj get mod name Get the module name containing an object obj get mod version Get the module revision date for the module containing an object obj get nsid Get the internal XML namespace ID for an object obj get min elements Get the YANG min elements value for a list or leaf list object obj get max elements Get the YANG max elements value for a list or leaf list object obj get units Get the YANG units fiel
96. nction See the agt rpc data cb t definition in agt agt rpc h for more details Example SIL Function Registration res agt rpc register method y toaster M toaster y toaster N make toast AGT RPC PH INVOKE y toaster make toast invoke if res NO ERR return res Example SIL Function DI KK FK K OK FK K E CK K FK FK CE CK K CE CE K K CE K K FK CE CK K E CE K K E CE FK CR CE CE K K CE K SK K OK K FK CE K K K E CE K OK K K K K K K OK K K OK K K K FUNCTION y toaster make toast invoke RPC invocation phase All constraints have passed at this point Call device instrumentation code in this function INPUTS see agt agt rpc h for details RETURNS error status FI AK OK K KK FK K FK FK K FK FK K CK K CE CE K K CE K K FK CE CE K E CE K K E K K CK E CE K K CE CE SK GE CE K FK CE CE K K 2K CE K OK K K K OK K K E OK K OK OK OK OK static status_t Page 71 y toaster make toast invoke ses cb t scb rpc msg t msg xml node t methnode status t res val value t toasterDoneness val val value t toasterToastType val uint32 toasterDoneness val idref t toasterToastType res NO ERR toasterDoneness 0 toasterDoneness val val find child msg rpc input y toaster M toaster y toaster N toasterDoneness Version 2 2 Yuma Developer Manual if toasterDoneness val NULL amp amp toasterDoneness val res NO ERR toasterDoneness VAL
97. netconfd server The netconfd server provides the following type of components e NETCONF session management e NETCONF YANG database management NETCONF YANG protocol operations Access control configuration and enforcement e RPC error reporting Notification subscription management Default data retrieval processing Database editing Database validation Subtree and XPath retrieval filtering Dynamic and static capability management e Conditional bbject management if feature when Memory management Logging management Page 24 Version 2 2 Yuma Developer Manual Timer services All NETCONF and YANG protocol operation details are handled automatically within the netconfd server All database locking and editing is also handled by the server There are callback functions available at different points of the processing model for your module specific instrumentation code to process each server request and or generate notifications Everything except the description statement semantics are usually handled The server instrumentation stub files associated with the data model semantics are generated automatically with the yangdump program The developer fills in server callback functions to activate the networking device behavior represented by each YANG data model NETCONF Server IO Loop S E jetconi SsuDs The ncxserver loop does very little and it is designed to be replaced in an embedded server that has
98. nit from template val set simval str Set a malloced value node as a specified simple type Used instead of val init from template Use a counted string value instead of a zero terminated string value val make string Create a complete malloced generic string value node val clone Clone a value node val clone test Clone a value node with a test callback function to prune certain descendant nodes during the clone procedure val clone config data Clone a value node but skip all the non configuration descendant nodes val add child Add a child value node to a parent value node val insert child Insert a child value node into a specific spot into a parent value node val remove child Remove a child value node from its parent val swap child Replace a child node within its parent with a different value node val first child match Match a child node name Used for partial command completion in yangcli val next child match Match the next child node name Used for partial command completion in yangcli val get first child Get the first child value node val get next child Get the next child value node val find child Find a specific child value node val find next child Find the next occurrence of a specified child node val match child Match a potential partial node name against the child node names and return the first ma
99. ns The following table highlights the most commonly used functions Refer to the H files for a complete definition of Yuma Developer Manual Macro Description VAL ENUM NAME V Access enumeration name string for NCX BT ENUM VAL FLAG V Deprecated use VAL BOOL instead VAL LONG V Access NCX BT INT64 value VAL INT V Access NCX BT INT32 value VAL INT8 V Access NCX BT INTS value VAL INT16 V Access NCX BT INT16 value VAL STR V Deprecated use VAL STRING instead VAL INSTANCE ID V Access NCX BT INSTANCE ID value VAL IDREF V Access entire val idref t structure for NCX BT IDREF VAL IDREF NSID V Access the identityref namespace ID for NCX BT IDREF VAL IDREF NAME V Access the identityref name string for NCX BT IDREF VAL UINT V Access the NCX BT UINT32 value VAL UINT8 V Access the NCX BT UINTS value VAL UINT16 V Access the NCX BT UINT16 value VAL ULONG V Access the NCX BT UINT64 value VAL DEC64 V Access the ncx dec64structure for NCX BT DEC64 VAL LIST V Access the ncx list t structure for NCX BT LIST VAL BITS Access the ncx list t structure for NCX BT BITS Same as VAL LIST each API function Page 50 val value t Access Functions Function Description val new value Malloc a new value node with type NCX BT NONE val init complex Initialize a malloced value node as
100. nsion allows optional attributes to be added to object nodes for anyxml leaf leaf list list and container nodes The config property will be inherited from the object that contains the metadata x This is used mostly for RPC input parameters and is strongly discouraged Full edit config support is not provided for metdata SC dLo hdr t metaQ Q of val value t value editing variables val editvars t editvars edit in progress vars status t res validationt result Used by Agent only if this field is non NULL then the entire value node is actually a placeholder for a dynamic read only object and all read access is done via this callback function the real data type is getcb fn t n void getcb if this field is non NULL then a malloced value struct representing the real value retrieved by val get virtual value is cached here for XPath filtering TBD add timestamp to reuse cached entries for some time period SCH struct val value t virtualval these fields are used for NCX BT LIST Version 2 2 Yuma Developer Manual struct val index t index back ptr flag in use as index A do hdr t indexQ Q of val index t or ncx filptr t this field is used for NCX BT CHOICE If set the object path for this node is really a this gt casobj casobj parent gt this parent the 0BJ TYP CASE and 0BJ TYP CHOICE nodes are skipped insi
101. nted with the if modified since leaf to allow all or none filtering of the configuration based on its modification timestamp The file agt agt sys c contains the SIL callback functions for this module This module provides some common data types that are used by other Yuma YANG modules There are no SIL callback functions for this module 3 YANG Objects and Data Nodes This section describes the basic design of the YANG object tree and the corresponding data tree that represents instances of various object nodes that the client or the server can create The object tree is a tree representation of all the YANG module rpc data definition and notification statements It starts with a root container This is defined with a YANG container statement which has an ncx root extension statement within it The config parameter within the lt edit config gt operation is an example of an object node which is treated as a root container Each configuration database maintained by the server e g lt candidate gt and lt running gt has a root container value node as its top level object A root container does not have any child nodes defined in it within the YANG file However the Yuma tools will treat this special container as if any top level YANG data node is allowed to be a child node of the root container type There are 14 different YANG object node types and a discriminated union of sub data structures contains fields common to each
102. odule User SIL foo h Combined User provided external definitions for Yuma and the foo module Should not edit User SIL The steps needed to create server instrumentation for use within Yuma are as follows e Create the YANG module data model definition or use an existing YANG module o Validate the YANG module with the yangdump program and make sure it does not contain any errors All warnings should also be examined to determine if they indicate data modeling bugs or not o Example toaster yang e Make sure the YUMA HOME environment variable is defined and pointing to your Yuma development tree e Create a SIL development subtree o Generate the directory structure and the Makefile with the make sil dir script installed in the usr bin directory This step will also call yangdump to generate the initial H and C files file the SIL o Example mydir gt make sil dir split test e Use your text editor to fill in the device specific instrumentation for each object RPC method and notification In this example edit test src u test c Almost all possible NETCONF specific code is either handled in the central stack or generated automatically so this code is responsible for implementing the semantics of the YANG data model e Compile your code o Use the make command in the SIL erc directory This should generate a library file in the SIL lib directory o Example mydir test src make Install the SIL li
103. of malloc and free functions directly The following table describes the files that are contained in this directory src platform Files File Description curversion h File generated during the build process to get the SVNVERSION number Included by Makefiles for build support platform profile platform profile cmn Included by Makefiles for build support platform profile depend Included by Makefiles for dependency generation support Platform definitions Contains basic data types and macros used throughout the Yuma code All C files include this file before any other Yuma files procdefs h setversion sh Shell script to generate the curversion h file Page 13 Version 2 2 Yuma Developer Manual This directory contains the NETCONF server implementation and built in module SIL code A static library called libagt a is built and statically linked within the netconfd program The following table describes the C modules contained in this directory Page 14 src agt C Modules C Module Description agt acm NETCONF access control implementation Contains the yuma nacm module SIL callback functions agt Server initialization and cleanup control points Also contains the agt profile t data structure agt cap Server capabilities Generates the server capabilities element content agt cb SIL callback support functions agt cli Server CLI and conf file control functions
104. on variable Page 28 Version 2 2 Yuma Developer Manual o Check the usr lib yuma directory e If the module parameter contains any sub directories or a file extension then it is treated as a file and the module search path will not be used Instead the absolute or relative file specification will be used e If the first term starts with an environment variable or the tilde character and will be expanded first Ifthe at sign followed by a revision date is present then that exact revision will be loaded e If no file extension or directories are specified then the module search path is checked for YANG and YIN files that match The first match will be used which may not be the newest depending on the actual search path sequence e The YUMA MODPATH environment variable or modpath configuration parameter can be used to configure one or more directory sub trees to be searched The YUMA HOME environment variable or yuma home configuration parameter can be used to specify the Yuma project tree to use if nothing is found in the currect directory or the module search path The YUMA INSTALL environment variable or default Yuma install location usr share yuma modules will be used as a last resort to find a YANG or YIN file The server processes module parameters by first checking if a dynamic library can be found which has an soname that matches the module name If so then the SIL phase 1 initialization funct
105. ook device and data model specific behavior to database objects and RPC operations The yangdump program is used to generate the initialization cleanup and empty callback functions for a particular YANG module The callback functions are then completed by you as required by the YANG module semantics This code is then compiled as a shared library and made available to the netconfd server The load command via CLI configuration file protocol operation is used by the operator to activate the YANG module and its SIL The SIL code for a YANG module can be generated with the make sil dir script described in the next section This script can generate combined SIL files or split SIL files if the split parameter is present A split SIL module for foo yang would be generated using the following files File name Type Description u foo c User SIL User provided server instrumentation code for the foo module u foo h User SIL User provided external definitions for the foo module Should not edit y foo c Yuma SIL Yuma server glue code for the foo module Do not edit y foo h Yuma SIL Yuma server external definitions for the foo module Do not edit Page 9 Version 2 2 Yuma Developer Manual A combined SIL module for foo yang would be generated using the following files File name Type Description foo c Combined User provided server instrumentation Yuma and code for the foo m
106. ount When a Yuma program exists it checks if malloc count equals free count and if not generates an error message If this occurs the MEMTRACE 1 parameter can be added to the make command to activate mtrace debugging Queue management APIs in ncx dlq h are used for all double linked queue management XML namespaces XML namespaces including YANG module namespaces are managed with functions in ncx xmlns h An internal namespace ID is used internally instead of the actual URI XML parsing XML input processing is found in ncx xml util h data structures and functions XML message processing XML message support is found in ncx xml msg h data structures and functions XML message writing with access control XML message generation is controlled through API functions located in ncx xml wr h High level value tree output and low level individual tag output XML output functions are provided which hide all namespace indentation and other details Access control is integrated into XML message output to enforce the configured data access policies uniformly for all RPC operations and notifications The access control model cannot be bypassed by any dynamically loaded module server instrumentation code XPath Services All NETCONF XPath filtering and all YANG XPath based constraint validation is handled with common data structures and API functions The XPath 1 0 implementation is native to the server and uses the object and value trees
107. p any memory allocation or other data model related tasks For example if the rpc user1 or rpc user2 pointers in the message header contain allocated memory then they need to be freed at this time Page 31 Version 2 2 Yuma Developer Manual 3 Phase Database Editing Model RPC Layer NETCONF server code 3 running candidate running database only or validate agt val server code SIL callbacks invoked for altered nodes e Validate Phase The server will determine the edit operation and the actual nodes in the target database candidate or running that will be affected by the operation All of the machine readable YANG statements which apply to the affected node s are tested against the incoming PDU and the target database If there are no errors the server will search for a SIL validate callback function for the affected node s If the SIL code has registered a database callback function for the node or its local ancestors it will be invoked This SIL callback function usually checks additional constraints that are contained in the YANG description statements for the database objects e Test Apply and Apply Phase If the validate phase completes without errors then the requested changes are applied to the target database If the target database is the running configuration or if the edit config test option parameter is set to test then set the default if with validate true then the test apply phase is execute
108. pe is not allowed to contain duplicate values The default is to allow duplicate token strings within an ncx xsdlist value ncx password Declares that a string data type is really a password and will not be displayed or matched by any filter ncx qname Declares that a string data type is really an XML qualified name XML prefixes will be properly generated by yangcli and netconfd ncx root Declares that the container parameter is really Page 109 Version 2 2 Yuma Developer Manual a NETCONF database root like config in the lt edit config gt operations The child nodes of this container are not specified in the YANG file Instead they are allowed to contain any top level object from any YANG file supported by the server ncx schema instance Declares that a string data type is really an special schema instance identifier string It is the same as an instance identifier built in type except the key leaf predicates are optional For example missing key values indicate wild cards that will match all values in nacm lt dataRule gt expressions ncx secure Declares that the database object is a secure object If the object is an rpc statement then only the netconfd superuser will be allowed to invoke this operation by default Otherwise only read access will be allowed to this object by default Write access will only be allowed by the superuser by default ncx very secure Decl
109. protocol operations message structures and error information are all data driven based on the YANG statements in the yama netconf yang module The ietf netconf yang module is not used at this time because it does not contain the complete set of YANG statements needed The yuma netconf yang version is a super set of the IETF version Only one YANG module can be associated with an XML namespace in Yuma In a future version the extra data structures will be moved to an annotation module The file agt agt ncx c contains the SIL callback functions for this module This module is not advertised in the server capabilities It is only used internally within the server Page 35 Version 2 2 Yuma Developer Manual This module provides some Unix proc file system data in nested XML format This module will not load if the files proc meminfo and proc cpuinfo are not found The file agt agt proc c contains the SIL callback functions for this module This module contains the Yuma system data structure providing basic server information unix uname data and all the Yuma proprietary notification event definitions The file agt agt sys c contains the SIL callback functions for this module This module contains the Yuma last modified leaf which extends the standard netconf state datastores datastore structure in ietf netconf monitoring yang with the database last modified timestamp The standard get and lt get config gt operations are augme
110. quests are processed by the internal NETCONF stack The module specific callback functions blue boxes can be loaded into the system at build time or run time This is the device instrumentation code also called a server implementation library SIL For example for libtoaster this is the code that controls the toaster hardware Cleanup If the shutdown or reboot operations are invoked then the server will cleanup For a reboot the init cycle is started again instead of exiting the program Page 18 Version 2 2 Yuma Developer Manual YANG Internal Data Yuma uses YANG source modules directly to implement NETCONF protocol operations automatically within the server The same YANG parser is used by all Yuma programs It is located in the ncx source directory libncx so There are several different parsing modes which is set by the application In the server mode the descriptive statements such as description and reference are discarded upon input Only the machine readable statements are saved All possible database validation filtering processing initialization NV storage and error processing is done based on these machine readable statements For example in order to set the platform specific default value for some leaf instead of hard coded it into the server instrumentation the default is stored in YANG data instead The YANG file can be altered either directly by editing or indirectly via deviat
111. re initialized and cleaned up statically The script usr bin make_sil_dir sh is used to automatically create a SIL work sub directory tree Support files are located in the usr share yuma util directory The following Makefile is for the libtoaster library supporting the toaster yang module SIL Makefile for Yuma Server Instrumentation Library THEHHHHHHHHHHHHHE SOURCE PROFILE JEEEEEBEHHHHHHBHEHHHHHHHBHHBHHHHE SUBDIR_NM toaster SUBDIR_CPP THEHHHHHHHHHHHHHE TARGET PROFILE JEHBEBEEBBHHHHHHBHEHHHHHHHHHHHHHHE TARGET bin LIB INST lib WORK INST YUMA HOME target lib REAL INST DESTDIR usr lib yuma THEHEHHHHHHHHHHHHHHHHHE MAKE RULES ZHEHEEEEHEHHHHHHHHHHHHHHHHE all sil dummy sil lib Page 104 Version 2 2 Page 105 Yuma Developer Manual THEHEHHHHHHHHHHHHHHHHR PLATFORM DEFINITIONS ZEHEHEHHHHEHBE ifdef YUMA HOME CINC I I YUMA_HOME src platform I YUMA_HOME src ncx I YUMA_HOME src agt I usr include I usr include libxml2 I usr include libxml2 libxml else ifdef YUMA_INSTALL CINC I I YUMA_INSTALL src platform I YUMA_INSTALL src ncx I YUMA_INSTALL src agt I usr include I usr include libxml2 I usr include libxml2 libxml else CINC I I usr share yuma src netconf src platform I usr share yuma src netconf src ncx I usr share yuma src netconf src agt I usr include I usr include libxml2 I usr include libxml2 li
112. s only allowed to be a child of a uses statement It does not have instances in the data tree OBJ TYP AUGMENT This object represents a YANG augment statement It is used to add additional objects to an existing data structure This object is only allowed to be a child of a uses statement or a child of a root container It does not have instances in the data tree however any children of the augment node will generate object nodes that have instances in the data tree OBJ TYP RPC This object represents a YANG rpc statement It is used to define new lt rpc gt operations This object will only appear as a child of a root container It does not have instances in the data tree Only rpcio nodes are allowed to be children of an RPC node OBJ TYP_RPCIO This object represents a YANG input or output statement It is used to define new lt rpc gt operations This object will only appear as a child of an RPC node It does not have instances in the Version 2 2 Yuma Developer Manual data tree OBJ TYP NOTIF This object represents a YANG notification statement It is used to define new notification event types This object will only appear as a child of a root container It does not have instances in the data tree The following typedef is used to represent an object tree node One YANG data def stmt typedef struct obj template t dlq hdr t qhdr obj type t objtype
113. s supported This module is also used to retrieve the actual YANG or YIN files or URLs for them that the server is using Clients can use the lt get schema gt RPC operation to retrieve the YANG or YIN files listed in the netconf state schemas subtree A client will normally check the hello message from the server for module capabilities and use its own local copy of a server YANG module if it can If not then the lt get schema gt function can be used to retrieve the YANG module The agt agt state c contains the SIL callback functions for this module The standard lt with defaults gt extension to some NETCONF operations is defined in this module This parameter is added to the get lt get config gt and lt copy config gt operations to let the client control how default leafs are returned by the server The Yuma server can be configured to use any of the default handling styles report all trim or explicit The filtering of default nodes is handled automatically by the server support functions in agt agt util c and the XML write functions in ncx xml wr c This module contains the standard YANG general user data types These types are available for commonly used derived types A YANG module author should check this module first before creating any new data types with the YANG typedef statement There are no accessible objects in this module so there are no SIL callback functions The YANG data types are supported within
114. se the request and generate the reply rpc in attrs xml attrs t read Queue of xml attr t representing any XML write attributes that were present in the lt rpc gt element A callback function may add xml attr t structs to this queue to send in the reply rpc method obj templat read Back pointer to the object template for et this RPC operation rpc agt state int read Enum value 0 1 2 for the current RPC callback phase rpc err option op errop t read Enum value for the lt error option gt Page 63 Version 2 2 Yuma Developer Manual Field Type User Description Mode parameter This is only set if the edit config operation is in progress rpc top editop op editop t read Enum value for the lt default operation gt parameter This is only set if the lt edit config gt operation is in progress rpc input val value t read Value tree representing the container of input parameters for this RPC operation rpc_user1 void read Void pointer that can be used by the SIL write functions to store their own message specific data rpc_user2 void read Void pointer that can be used by the SIL write functions to store their own message specific data rpc returncode uint32 none Internal return code used to control nested callbacks rpc data type rpc data t write For RPC operations that return data this enumeration is set to indicate which type of data is desired R
115. sshd when a new SSH2 connection to the netconf sub system is attempted Page 101 Version 2 2 Yuma Developer Manual This program will use an AF LOCAL socket using a proprietary lt ncxconnect gt message to communicate with the netconfd server After establishing a connection with the netconfd server this program simply transfers SSH2 NETCONF channel data between sshd and netconfd The following program is part of Yuma Tools and usually found within the Yuma development tree e netconfd o The NETCONF server that processes all protocol operations The agt ncxserver component will listen for ncxconnect messages on the designated socket tmp ncxserver sock If an invalid message is received the connection will be dropped Otherwise the netconf subsystem will begin passing NETCONF channel data to the netconfd server The first message is expected to be a valid NETCONF hello PDU If The following external libraries are used by Yuma and need to be pre installed ncurses needed by yangcli o character processing library needed by libtecla used within yangcli libc or glibc needed by all applications o unix system library e libssh2 needed by yangcli o SSH2 client library used by yangcli libxml2 needed by all applications o xmlTextReader XML parser o pattern support The SIL Makefile is based on the Makefile for Yuma sources The automake program is not used at this time There is no configure script
116. ssues an rpc commit to commit the change to the running configuration e Netconf executes the profile edit apply callback for the running configuration e Netconf executes the profile id edit apply callback for the running configuration e Netconf executes the profile edit commit create callback for the running configuration e Netconf executes the profile id edit commit create gt callback for the running configuration e The client receives an rpc reply indicating success The message sequence chart below shows the expected SIL callbacks for a create profile stream connection operation In this scenario the XPO container is empty prior to step 1 Page 94 Version 2 2 Yuma Developer Manual Netconf Netconf Client Server rpc edit config profile stream connection create xpo profile edit validate xpo profile id editevalidate xpo profile streamConnection edit validate xpo profile streamConnection id edit validate xpo profile streamConnection sourceld editcvalidate xpo profile streamConnection bitrate edit validate xpo profile edit apply xpo profile id editcapply xpo profile streamConnection edit apply xpo profile streamConnection id editeapply xpo profile streamConnection sourceld editcapply xpo profile streamConnection bitrate edit apply a rpc commit 15 xpo profile streamConnection sourceld edit apply xpo profile streamConnection bitrate edite apply xpo
117. ster timer id 0 toaster toasting FALSE y toaster toastDone send const xmlChar error break default res SET ERROR ERR INTERNAL VAL if res NO_ERR res agt_check_cache amp toaster val newval curval editop if res NO ERR amp amp editop OP_EDITOP_LOAD editop OP_EDITOP_CREATE res y toaster toaster mro newval break case AGT CB ROLLBACK undo device instrumentation here break default res SET ERROR ERR INTERNAL VAL if error set the res errorstr and errorval parms if res NO ERR agt_record error scb amp msg gt mhdr NCX_LAYER_CONTENT res NULL NCX_NT_STRING errorstr NCX_NT_VAL errorval return res y toaster toaster edit Page 82 Version 2 2 Yuma Developer Manual Database Edit Validate Phase return status y toaster toaster edit garten RPC request in progress Dc msg t msg 4 eg prog agt cbtyp t cbtyp 44 callback phase in progress session making the request A SIL database validation phase callback function is responsible for checking all the description statement sort of data model requirements that are not covered by any of the YANG machine readable statements For example if a user name parameter needed to match an existing user name in etc passwd then the SIL validation callback would call the system APIs needed to check if the newval string va
118. sub type Object templates are defined in ncx obj h Page 36 Version 2 2 Yuma Developer Manual YANG Object Types object type description OBJ TYP ANYXML This object represents a YANG anyxml data node OBJ TYP CONTAINER This object represents a YANG presence or non presence container OB TYP CONTAINER ncx root If the ncx root extension is present within a container definition then the object represents a NETCONF database root No child nodes OBJ TYP LEAF This object represents a YANG leaf data node OBJ TYP LEAF LIST This object represents a YANG leaf list data node OBJ TYP LIST This object represents a YANG list data node OBJ TYP CHOICE This object represents a YANG choice schema node The only children allowed are case objects This object does not have instances in the data tree OBJ TYP CASE This object represents a YANG case schema node This object does not have instances in the data tree OBJ TYP USES This object represents a YANG uses schema node The contents of the grouping it represents will be expanded into object tree It is saved in the object tree even during operation in order for the expanded objects to share common data This object does not have instances in the data tree OBJ TYP REFINE This object represents a YANG refine statement It is used to alter the grouping contents during the expansion of a uses statement This object i
119. ta type ncx xsdlist extension NCX BT CONTAINE R YANG container NCX BT CHOICE YANG choice This is a meta type and placeholder It does not appear in the data tree NCX BT CASE YANG case This is a meta type and placeholder It does not appear in the data tree NCX BT LIST YANG list NCX BT EXTERN Internal external data type used in yangcli It indicates that the content is actually in an external file NCX BT INTERN Internal buffer data type used in yangcli The content is actually stored verbatim in an internal buffer There is a temporary data structure which is attached to a data node while editing operations are in progress called val editvars t This structure is used by the functions in agt agt val c to manipulate the value tree nodes during an lt edit config gt lt copy config gt lt load config gt or commit operation The SIL callback functions may wish to refer to the fields in this data structure There is also a SIL cookie field to allow data to be transferred from one callback stage to the later stages For example if an edit operation caused the device instrumentation to reserve some memory then this cookie could store that pointer The following typedef is used to define the val editvars t structure one set of edit in progress variables for one value node typedef struct val editvars t these fields are only used in modified values before they are
120. table highlights the functions available in this module agt agt util Functions Function Description agt get cfg from parm For value nodes that represent a NETCONF configuration database name e g empty element named running The configuration control block for the referenced database is retrieved agt get inline cfg from parm For value nodes that represent inline NETCONF configuration data The value node for the inline config node is retrieved agt get parmval Get the specified parameter name within the RPC input section from an RPC message control block agt record error Generate a complete RPC error record to be used when the lt rpc reply gt is sent agt record error errinfo Generate a complete RPC error record to be used when the lt rpc reply gt is sent using the Page 55 Version 2 2 Yuma Developer Manual Function Description YANG specified error information not the default error information agt record attr error Generate a complete RPC error record to be used when the lt rpc reply gt is sent for an XML attribute error agt record insert error Generate a complete RPC error record to be used when the lt rpc reply gt is sent for a YANG insert operation error agt record unique error Generate a complete RPC error record to be used when the lt rpc reply gt is sent for a YANG unique statement contraint error agt check default val node
121. tch found if any val child cnt Get the number of child nodes within a parent node val liststr count Get the number of strings within an NCX BT LIST value node val index match Check if 2 value list nodes have the same set of key leaf values val compare Compare 2 value nodes Version 2 2 Yuma Developer Manual Function Description val compare ex Compare 2 value nodes with extra parameters val compare to string Compare a value node to a string value instead of another value node val sprintf simval nc Output the value node as a string into the specified buffer val make sprintf string Malloc a buffer and fill it with a zero terminated string representation of the value node val resolve scoped name Find a descendant node within a value node from a relative path expression val has content Return TRUE if the value node has any content FALSE if an empty XML element could represent its value val has index Return TRUE if the value node is a list with a key statement val get first index Get the first index node for the specified list value node val get next index Get the next index node for the specified list value node val set extern Set a malloced value node as an NCX BT EXTERN internal data type val set intern Set a malloced value node as an NCX BT INTERN internal data type val fit oneline
122. template Find a top level object template within a module obj find child Find the specified child node within a complex object template Skips over any nodes without names augment uses etc obj first child Get the first child node within a complex object template Skips over any nodes without names obj next child Get the next child node after the current specified child Skips over any nodes without names obj first child deep Get the first child node within a complex object template Skips over any nodes without names and also any choice and case nodes obj next child deep Get the next child node after the current specified child Skips over any nodes without names and also any choice and case nodes obj find case Find the specified case object child node within the specific complex object node obj find type Check if a typ template t in the obj typedefQ hierarchy obj find grouping Check if a grp template t in the obj typedefQ hierarchy obj find key Find a specific key component by key leaf identifier name obj first key Get the first obj key t struct for the specified list object type obj next key Get the next obj key t struct for the specified list object type obj gen object id Allocate and generate the YANG object ID for an object node obj get name Get the object name string obj has name Return TRUE if the object has a
123. teractive and script based CLI based on YANG modules yangcli autoload Uses the server capabilities from the hello message to automatically load any missing YANG modules from the server and apply all features and deviations yang autolock Provides protocol exchange support for the high level get locks and release locks commands yangcli cmd Main local command processor yangcli list Implements yangcli list command yangcli_save Implements yangcli save command yangcli show Implements yangcli show command yangcli tab Implements context sensitive tab word completion yangcli util Utilities used by other yangcli C modules This directory contains the yangdiff program which is the Yuma YANG module compare program This is a stand alone binary that is part of the yuma client package It is installed in the usr bin directory The following table describes the C modules contained in this directory src yangdiff Page 16 Version 2 2 Yuma Developer Manual C Module Description yangdiff YANG module semantic compare program yangdiff grp Implements semantic diff for YANG grouping statement yangdiff obj Implements semantic diff for YANG data definition statements yangdiff typ Implements semantic diff for YANG typedef and type statements yangdiff util Utilities used by the other yangdiff C modules This directory contains the yangdump program
124. test fn t Node Test Callback function to filter out default data from streamed replies according to the server s definition of a default node agt check save val nodetest fn t Node Test Callback function to filter out data nodes that should not be saved to NV storage agt enable feature Enable the specified YANG feature agt disable feature Disable the specified YANG feature agt make leaf Create a child value node agt make virtual leaf Create a virtual value child node Most device monitoring leafs use this function because the value is retrieved with a device specific API not stored in the value tree agt init cache Initialize a cached pointer to a node in a data tree agt check cache Check if a cached pointer to a node in a data tree needs to be updated or set to NULL 4 SIL External Interface Each SIL has 2 initialization functions and 1 cleanup function that must be present e The first initialization callback function is used to set up the configuration related objects e The second initialization callback is used to setup up non configuration objects after the running configuration has been loaded from the startup file e The cleanup callback is used to remove all SIL data structures and unregister all callback functions These are the only SIL functions that the server will invoke directly They are generated by yangdump with the format c parameter and usually
125. the incoming request according Page 30 Version 2 2 Yuma Developer Manual to the YANG definition for the RPC operation An rpc msg t structure is also built for the request e VALIDATE Phase If a message is parsed correctly then the incoming message is validated according to the YANG machine readable constraints Any description statement constraints need to be checked with a callback function The agt rpc register method function in agt agt rpc c is used to register callback functions e INVOKE Phase If the message is validated correctly then the invoke callback is executed This is usually the only required callback function Without it the RPC operation has no affect This callback will set fields in the rpc msg t header that will allow the server to construct or stream the lt rpc reply gt message back to the client e REPLY Phase Unless some catastrophic error occurs the server will generate an lt rpc reply gt response If any lt rpc error gt elements are needed they are generated first If there is any response data to send that is generated or streamed via callback function provided earlier at this time Any unauthorized data according to to the yama nacm yang module configuration will be silently dropped from the message payload If there were no errors and no data to send then an ok resonse is generated e POST REPLY Phase After the response has been sent a rarely used callback function can be invoked to cleanu
126. the top level makefile so platform profile cmn was created to allow that Makefile to define a different depend rule depend dependencies dependencies DEPS if f Makefile then echo Error Makefile missing exit 1 fi rm f dependencies for i in DEPS do if f i then cat i gt gt dependencies echo gt gt dependencies else echo Warning Dependency file i D is missing Skipping echo Warning Missing file i f X done Page 107 Version 2 2 Yuma Developer Manual echo gt gt dependencies delete the D files to force make depend to rebuild them each time that target is built rm f DEPS HHHHHHHHHHHHHHHH DEPENDENCIES 4HEEHHBHHHHHHHBHHHBHHHHHBHHHBE depend rule must be included after the all make rule include netconf src platform platform profile depend test install mkdir p REAL_INST SUDO install LIB INST lib SUBDIR NM LIBSUFFIX REAL INST work install LIB INST lib SUBDIR NM LIBSUFFIX WORK INST sil lib LIB INST lib SUBDIR NM LIBSUFFIX this dummy rule keeps make from deleting the 0BJS as intermediate files sil dummy dependencies 0BJS clean rm f 0BJS LIB INST lib SUBDIR NM superclean rm f DEPS dependencies 0BJS LIB INST lib SUBDIR NM LIB INST lib SUBDIR NM so 0BJS gcc shared rdynamic Wl soname lib
127. they are detected o The server will handle the error reply generation for all errors it detects o For SIL detected errors the agt record error function in agt agt util h is usually used to save the error details o Reply data can be generated by the SIL invoke callback function and stored in the rpc msg t structure o Replay data can be streamed by the SIL code via reply callback functions For example the get and lt get config gt operations use callback functions to deal with filters and stream the reply by walking the target data tree After the lt rpc reply gt is sent the server will check for an RPC post reply callback function This is only needed if the SIL code allocated some per message data structures For example the rpc msg t contains 2 SIL controlled pointers rpc userl and rpc user2 The post reply callback is used by the SIL code to free these pointers if needed The database edit SIL callbacks are only used for database operations that alter the database The validate and invoke callback functions for these operations will in turn invoke the data model specific SIL callback functions depending on the success or failure of the edit request All RPC operations are data driven within the server using the YANG rpc statement for the operation and SIL callback functions Any new protocol operation can be added by defining a new YANG rpc statement in a module and providing the proper SIL code The agt_rpc_re
128. timer The following example from toaster c simply completes the toast when the timer expires and calls the auto generated toastDone send notification function sk koksk ke AAI EEE E E K KE K K KK k KK k k Kk oko ok ok aK aK K k KKK k KK K 2k 2k 2k kK KKK FUNCTION toaster timer fn x Added timeout function for toaster function INPUTS e see agt agt timer h Se RETURNS is 0 for OK 1 to kill periodic timer FE KK K KK FK K FK FK K FK FK CK CK K CE CE OK PE CE K K CK CE CE K OK CE K K E K FK CE CE CE K K CE CE K GE OK K FK CE CE K K E CE K OK OK K K K OK OK K E OK K OK OK OK OK static int toaster timer fn uint32 timer id void cookie void timer id void cookie toast is finished toaster toasting FALSE toaster timer id 0 if LOGDEBUG2 log_debug2 ntoast is finished y toaster toastDone send const xmlChar done Page 89 Version 2 2 Yuma Developer Manual return 0 toaster timer fn 6 Server Callback Examples This section was written by Mark Pashley for the Yuma Integration Test Suite It is included here because it explains the details of SIL callback for several message flow examples This document details the SIL callbacks that are made when Yuma processes NETCONF edit queries when configured to use the candidate database configuration target candidate The following YANG defines the configuration that is used for all of the examples within
129. to run There are 2 basic build steps 1 make 2 sudo make install The installation step may require root access via the sudo program depending on the system The following target platforms are supported e Fedora and Ubuntu these are the default targets and no special command line options are needed The following table describes the build targets that are supported Page 102 Version 2 2 Yuma Developer Manual Yuma Build Targets Make Target Description all Make everything This is the default if not target is specified depend Make the dependencies files clean Remove the target files superclean Remove all the dependencies and the target files distclean Remove all the distribution files that make be installed all the dependencies and the target files test Make any test code lint Run a lint program on the source files install Install the components into the system uninstall Remove the components from the system There are several command line options that can be used when making the Yuma source code These may have an impact on building and linking the SIL source code The following table describes these options Yuma Build Parameters for make Make Parameter Description CYGWIN 1 Build for the Windows Cygwin target environment DEBUG 1 Generate debug symbols for gdb debugging and do not generate optimized binary code The defau
130. uration Netconf executes the xpo profile edit validate callback to validate the change to the running configuration 7 Netconf executes the xpo profile edit commit delete gt callback to perform a create operation change to the candidate configuration 8 The client receives an rpc reply indicating success Deleting a stream connection is no different to deleting a profile For delete operations SIL callbacks are only made for the highest level node that is being deleted 7 Development Environment This section describes the Yuma Tools development environment used to produce the Linux binaries There are several components used in the Yuma software development environment gcc compiler and linker e Idconfig and install programs e GNU make program e shell program such as bash e Yuma development tree the source tree containing Yuma code specified with the YUMA HOME environment variable SIL development tree the source tree containing server instrumentation code The following external program is used by Yuma and needs to be pre installed e opensshd needed by netconfd o The SSH2 server code does not link with netconfd Instead the netconf subsystem program is invoked and local connections are made to the netconfd server from this SSH2 subsystem The following program is part of Yuma Tools and needs to be installed e netconf subsystem needed by netconfd o The thin client sub program that is called by
131. urpose is to validate any aspects of an RPC operation beyond the constraints checked by the server engine Only 1 function can register for each YANG rpc statement The standard NETCONF operations are reserved by the server engine There is usually zero or one of these callback functions for every rpc statement in the YANG module associated with the SIL code It is enabled with the agt rpc register method function within the phase 1 initialization callback function The yangdump code generator will create this SIL callback function by default There will C comments in the code to indicate where your additional C code should be added The val find child function is commonly used to find particular parameters within the RPC input section which is encoded as a val value t tree The agt record error function is commonly used to record any parameter or other errors In the libtoaster example there are internal state variables toaster enabled and toaster toasting maintained by the SIL code which are checked in addition to any provided parameters Example SIL Function Registration Page 67 Version 2 2 Yuma Developer Manual res agt rpc register method y toaster M toaster y toaster N make toast AGT RPC PH VALIDATE y toaster make toast validate if res NO ERR return res Example SIL Function DK KK K K OK K FK FK FK K FK OK FK FK K OK FK K CE K K FK OK CE FK K CE FK K OK CE K K E CE K K CE CE K K CE K K CE K
132. use if toaster toasting res ERR NCX IN USE else this is where a check on bread inventory would go this is where a check on toaster HW ready would go else toaster service disabled res ERR NCX RESOURCE DENIED added code ends here if error set the res errorstr and errorval parms if res NO ERR agt_record error scb amp msg gt mhdr NCX_LAYER_OPERATION res methnode NCX_NT_STRING errorstr NCX_NT_VAL errorval return res y toaster make toast validate Page 69 Version 2 2 Yuma Developer Manual RPC Invoke Phase post reply callback Static statuis 4 retum operation status y toaster make toast invoke session making the request rpc msg t msg a validated RPC request xml node t methnode _ 7 XML node for the operation for error reporting purposes and vendor specific attributes The RPC invoke callback function is used to perform the operation requested by the client session Only 1 function can register for each YANG rpc statement The standard NETCONF operations are reserved by the server engine There is usually one of these callback functions for every rpc statement in the YANG module associated with the SIL code The RPC invoke callback function is optional to use although if no invoke callback is provided then the operation will have no affect Normally this is only t
133. valid for the value node object type val parse idref Convert a string to an internal QName string into its various parts and find the identity struct that is being referenced if available val simval ok Check if the smple value is valid for the value node object type val simval ok errinfo Check if the simple value is valid for the value node object type and provide the error information to use if it is not OK val get first meta Get the first meta variable XML attribute value for a value node val get next meta Get the next meta variable XML attribute value for a value node val find meta Find the specified meta variable in a value node val dump value Debug function to print the contents of any value node val dump value ex Debug function to print the contents of any value node with extended parameters to control the output val dump value max Debug function to print the contents of any value node with full control of the output Version 2 2 Page 52 Yuma Developer Manual Function Description parameters val set string Set a malloced value node as a generic string value Used instead of val init from template val set string2 Set a malloced value node as a specified string type Used instead of val init from template val set simval Set a malloced value node as a specified simple type Used instead of val i
134. veloper Manual rpc edit config xpo delete xpo edit validate xpo editcapply as d i xpo editcapply xpo editecommit delete 1 The client issues an rpc edit config to delete an xpo container lt xml version 1 0 encoding UTF 8 gt lt rpc message id 10 xmins nc urn ietf params xml ns netconf base 1 0 xmlns urn ietf params xml ns netconf base 1 0 lt edit config xmlns urn ietf params xml ns netconf base 1 0 target candidate target lt default operation gt merge lt default operation gt lt config gt xpo xmlns nc urn ietf params xml ns netconf base 1 0 nc operation delete xmlns http www ericsson com television ns xpo3 base lt config gt lt edit config gt rpc Page 98 Version 2 2 Yuma Developer Manual 2 Netconf executes the xpo edit validate callback to validate the change to the candidate configuration 3 Netconf executes the xpo edit apply callback to apply the change to the candidate configuration 4 The client receives an rpc reply indicating success The client issues an rpc commit to commit the change to the running configuration Netconf executes the xpo edit validate callback to validate the change to the running configuration 7 Netconf executes the xpo edit commit delete callback to perform a create operation change to the candidate configuration 8 The client receives an rpc reply indicating success The mess
135. xtypes h The API functions in ncx ncxmod h such as ncxmod load module are used to locate YANG modules parse them and store the internal data structures in a central library Multiple versions of the same module can be loaded at once as required by YANG Once a NETCONF session is started it is assigned a session control block for the life of the session All NETCONF and system activity in driven through this interface so the ncxserver loop can be replaced in an embedded system Each session control block ses scb t controls the input and output for one session which is associated with one SSH user name Access control see yuma nacm yang is enforced within the context of a session control block Unauthorized return data is automatically removed from the response Unauthorized lt rpc gt or database write requests are automatically rejected with an access denied error tag The user preferences for each session are also stored in this data structure They are initially derived from the server default values but can be altered with the lt set my session gt operation and retrieved with the get my session operation Page 23 Version 2 2 Yuma Developer Manual Main Server Components XML processing NETCONF sessions Connect to subsystem netconf subsystem opensshd SSH2 server Top level PDUs lt rpe gt ae Notifications Access control Server Instrumentation Libraries System Monitor YANG syntax YANG database

Yuma Developer Manual

Contents

Download Pdf Manuals

Related Search

Related Contents