Check the Online Manual for Up to Date Information

SIL-SA Subsystem


Server Instrumentation Library - Sub Agent (SIL-SA)


  • The YANG module and bundle instrumentation can be deployed in one or more subsystems,
  • A subsystem can manage all or part of a "library"
    • A SIL-SA library can be for a single module. This is useful for simple data models
      • Use make_sil_sa_dir to create the code stubs
    • A SIL-SA library can be for a bundle of modules. This is useful when there are modules that augment one or more base modules
      • Use make_sil_sa_bundle to create the code stubs
  • The "sil-sa-app application can be used directly (or adapted) to implement the sub-agent
    • No modification to the sil-sa-app is required at all to support all server features
    • Multiple instances of sil-sa-app are allowed. Use the "subsys-id" CLI parameter to give each subsystem a unique ID
    • The subsystem is not required to support all possible YANG modules or bundles. Use the "library" CLI parameter to limit the SIL-SA libraries loaded by a sil-sa-app instance
  • SIL-SA libraries are usually dynamic shared libraries, which are loaded at run-time by sil-sa-app only if the module or bundle is being used
  • SIL-SA libraries can also be statically linked, but not covered in this article



SIL-SA Example: address.yang


module: address
  +--rw addresses
     +--rw address* [last-name first-name]
        +--rw last-name     string
        +--rw first-name    string
        +--rw street?       string
        +--rw city?         string
        +--rw zipcode?      string
        +--rw phone* [phone-type]
           +--rw phone-type      enumeration
           +--rw phone-number    string



1) Create the SIL-SA stub code with make_sil_sa_dir


make_sil_sa_dir --split address --sil-get2 --sil-edit2



2) Build and install the SIL-SA Library


> cd address
> make DEBUG=1
> sudo make DEBUG=1 install


  • If the library was created and installed correctly you should see the library file "libaddress_sa.so" in the install directory, which is usually the /usr/lib/yumapro directory.  
  • The library file does not have to be installed with "make install". It could be placed anywhere and the 
    --runpath CLI parameter or YUMAPRO_RUNPATH environment variable can be used to tell the server where to find the library.


Compiling in C++11 mode
mkdir -p /usr/lib/yumapro
install ../lib/libaddress.so /usr/lib/yumapro/libaddress_sa.so


  • NOTE: The SIL-SA library can be loaded into sil-sa-app at this point for demonstration purposes only.
    The stub code must be filled in in order to actually implement the YANG module or bundle.  


3) Start the netconfd-pro Server


  • A SIL-SA library for a module can be loaded at boot-time using the "module" parameter
  • A SIL-SA library for a bundle can be loaded at boot-time using the "bundle" parameter
  • A SIL-SA library for a module can be loaded at run-time using the "load" operation
  • A SIL-SA library for a bundle can be loaded at run-time using the "load-bundle" operation


> netconfd-pro --log-level=debug4 --module=address



4) Start the sil-sa-app Subsystem in a Different Terminal


> sil-sa-app --log-level=debug4




SIL-SA Message Exchanges


If the SIL-SA library for address.yang was loaded successfully, then the following message exchanges should be seen in the server and sil-sa-app log files



SIL-SA Sends <config-request>


  • A) The SIL-SA subsystem sends a <config-request> to the server


<?xml version="1.0" encoding="UTF-8"?>
<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>1</message-id>
 <message-type>subsys-request</message-type>
 <server-id/>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <config-request/>
  </sil-sa>
 </payload>
</ycontrol>



Server Sends <config-response>


  • B) The server responds with a <config-response> message


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>1</message-id>
 <message-type>server-response</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <config-response>
    <agt-profile>
       // DETAILS REMOVED
    </agt-profile>
    <module>address</module>
   </config-response>
  </sil-sa>
 </payload>
</ycontrol>


Notice the "module" leaf that is set to the string "address"?

The SIL-SA subsystem will attempt to find a SIL-SA library to open called "libaddress_sa.so".

In this case it is found in the default YUMAPRO_RUNPATH (/usr/lib/yumapro/libaddress_sa.so)

The modules and bundles needed on this subsystem are loaded before the register request is sent.



SIL-SA Phase I Initialization


After the module is loaded, the "init1" callback is invoked for library.  The purpose of this callback is to load the YANG modules and register the callbacks for the supported objects in those YANG modules. It is called before the user configuration (e.g., startup-cfg.xml) has been loaded.  The registration for many of the SIL-SA callback types can be generated automatically with the make_sil_sa_dir or make_sil_sa_bundle scripts.



Log File Example:


yang_parse: Start module 'address' OK
xmlns_reg:  id:24 mod:address  uri: http://www.yumaworks.com/ns/address
agt_cb: got new module 'address', rev '2016-01-22'
yang_parse: Finish module 'address@2016-01-22' OK
agt_cb: load OK for mod 'address', def '/addr:addresses'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address/addr:street'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address/addr:city'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address/addr:zipcode'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address/addr:phone'
agt_cb: load OK for mod 'address', def '/addr:addresses/addr:address/addr:phone/addr:phone-number'
*** address_init ***

Ran sil-sa init function OK for module 'address'



SIL-SA Sends <register-request>


  • C) The SIL-SA subsystem tries to load SIL-SA libraries, and sends a <register-request> message. In this case, a "register" subtree is generated for the "address" module. Since this is an EDIT-1 callback function shown, a callback is registered for each data node within the "addresses" container.
    • The proper YANG modules are loaded into the sil-sa-app
    • The SIL-SA libraries will register their callback functions, as if they were running in the main server.
      In fact, the info is just being saved for the registration message


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>2</message-id>
 <message-type>subsys-request</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <register-request>
    <register>
     <module>address</module>
     <path>/addr:addresses</path>
     <path>/addr:addresses/addr:address</path>
     <path>/addr:addresses/addr:address/addr:city</path>
     <path>/addr:addresses/addr:address/addr:phone</path>
     <path>/addr:addresses/addr:address/addr:phone/addr:phone-number</path>
     <path>/addr:addresses/addr:address/addr:street</path>
     <path>/addr:addresses/addr:address/addr:zipcode</path>
    </register>
   </register-request>
  </sil-sa>
 </payload>
</ycontrol>



Server Sends <ok>


  • D) The server responds with an <ok> message


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>2</message-id>
 <message-type>server-response</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <ok/>
</ycontrol>



SIL-SA Sends <trigger-replay>


  • E) The SIL-SA subsystem determines that it has callbacks for configuration data nodes so it needs to trigger a configuration replay for itself.  The server will only send the edit updates to this subsystem and not disrupt other subsystems that are already running


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>3</message-id>
 <message-type>subsys-event</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <trigger-replay/>
  </sil-sa>
 </payload>
</ycontrol>



Server Sends <start-transaction>   (Validate Phase)

  • F) The server starts a transaction in this case because the empty "addresses" container is considered to exist in the server. The SIL-SA subsystem is asked to apply this NP-container to its configuration.
    • No SIL-SA model specific data should be saved in the Validation Phase!
    • The server may not send any more messages after this one (e.g., another subsystem rejects the edit request so a rollback is done. In this case this subsystem will not get notified of the rollback)


<ycontrol xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
 xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>1</message-id>
 <message-type>server-request</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <start-transaction>
    <transaction-id>485</transaction-id>
    <user-id>superuser</user-id>
    <client-addr>127.0.0.1</client-addr>
    <target>running</target>
    <validate>false</validate>
    <reverse-edit>false</reverse-edit>
    <load-config>true</load-config>
    <edit>
     <id>1</id>
     <operation>load</operation>
     <path>/addr:addresses</path>
     <newval>
      <addresses ya:datapath="/addr:addresses"
       xmlns="http://www.yumaworks.com/ns/address"/>
     </newval>
    </edit>
   </start-transaction>
  </sil-sa>
 </payload>
</ycontrol>



SIL-SA Sends <ok>

  • G) The SIL-SA subsystem sends the "ok" response to accept the start of the edit transaction


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>1</message-id>
 <message-type>subsys-response</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <ok/>
</ycontrol>



Server Sends <continue-transaction>  (Apply Phase)

  • H) The server sends a "continue-transaction" message to tell the SIL-SA subsystem to execute the Apply Phase.  Any changes to internal configuration or system may need to be rolled back.
    • The server will send a follow-up message for this transaction if a SIL-SA subsystem responds with "ok" for the Apply Phase, to either complete or rollback the edit transaction


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>2</message-id>
 <message-type>server-request</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <continue-transaction>
    <transaction-id>485</transaction-id>
    <phase>apply</phase>
   </continue-transaction>
  </sil-sa>
 </payload>
</ycontrol>



SIL-SA Sends <ok>

  • I) The SIL-SA subsystem sends the "ok" response to accept the Apply Phase of the edit transaction



<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>2</message-id>
 <message-type>subsys-response</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <ok/>



Server Sends <continue-transaction>  (Commit Phase)

  • J) The server sends a "continue-transaction" message to tell the SIL-SA subsystem to execute the Commit Phase or Rollback Phase.  Any changes to internal configuration or system can be saved or rolled back at this time.
    • The server WILL NOT send a follow-up message for this edit transaction
    • The server might start a new transaction for a "reverse edit" transaction. This can occur if one subsystem accepts the Commit phase and another rejects this phase.
      • E.g. if the original transaction was to create the "addresses" container then the reverse edit would be to delete the "addresses" container


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>3</message-id>
 <message-type>server-request</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <payload>
  <sil-sa xmlns="http://yumaworks.com/ns/yumaworks-sil-sa">
   <continue-transaction>
    <transaction-id>485</transaction-id>
    <phase>commit</phase>
   </continue-transaction>
  </sil-sa>
 </payload>
</ycontrol>


SIL-SA Phase II Initialization 


After the SIL-SA subsystem accepts the commit phase for the transaction, it can assume there will be no more messages from the server for this transaction. The "init2" callback is now invoked for the library. This library is optional to use. It can be used to initialize internal data, possibly based on the initial configuration learned from the "register-response" message.



Log File Example:


Enter address_addresses_edit callback for commit phase
Enter u_address_addresses_edit callback for commit phase
ycontrol_msg: sending subsys-response # 3 for sil-sa
ses_msg: reused out buff 0x55cdd7499260 for s 1
sil_sa: finish transaction 
sil_sa: Calling init2 callbacks after load
Calling sil-sa Init2 fn for module 'address'
*** address_init2 ***




SIL-SA Sends <ok>

  • K) The SIL-SA subsystem sends the "ok" response to accept the Commit Phase of the edit transaction.


<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>3</message-id>
 <message-type>subsys-response</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>sil-sa</service-id>
 <ok/>
</ycontrol>



Server Shutdown


When the server is shut down by the operator, it will send a "shutdown-event" message to the YControl layer within the SIL-SA subsystem. This will cause the SIL-SA layer to be shutdown. At this point the "cleanup" callback functions are invoked for the SIL-SA library. 


The un-registration function calls for many of the SIL-SA callback types can be generated automatically with the make_sil_sa_dir or make_sil_sa_bundle scripts.


Incoming msg for session 1
<?xml version="1.0" encoding="UTF-8"?>
<ycontrol xmlns="http://yumaworks.com/ns/yumaworks-ycontrol">
 <message-id>4</message-id>
 <message-type>server-event</message-type>
 <server-id>server1</server-id>
 <subsys-id>subsys1</subsys-id>
 <service-id>*</service-id>
 <payload>
  <shutdown-event/>
 </payload>
</ycontrol>

ycontrol: Got server-event 4 from server1
ycontrol: shutdown requested

ses_msg: free msg 0x55cdd748c5c0 for session 1
ycontrol: shutting down service 'sil-sa'
sil_sa: shutting down
Server Cleanup Starting...

agt_cb: Enter run_shutdown
Running sil-sa cleanup function for module 'address'
*** address_cleanup ***

Closing sil-sa library 'address'






SIL-SA Trouble Shooting




Server Not Running or Unreachable
(waiting 5000 mSec before attempting re-connect)


  • If the netconfd-pro process is not running or cannot be reached on the network by the subsystem then you should see the log messages for the server to attempt a reconnect to the server
    • Use at least --log-level=debug to see these messages (Example shows --log-level=debug4)


ycontrol_ses: Attempting new control connection
ses_msg: new out buff 0x55db6bc009d0 for s 0
ses: Setting session 0 protocol from 'NETCONF 1.0' to 'YControl'
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection
ycontrol: waiting 5000 mSec before attempting re-connect
ycontrol_ses: Attempting new control connection




Server Not Configured to Load Any Modules For This Subsystem
(No SIL-SA Objects)


  • If the netconfd-pro process is not configured to load any modules or bundles that the SIL-SA subsystem supports, then the <trigger-replay> message will not be sent.  No callbacks for such a SIL-SA library will be registered because the module is not requested.
  • This is the expected behavior if the --library CLI parameter is used for sil-sa-app and this parameter is not found for any of the modules or bundles found in the <config-response>
  • This is the expected behavior if no SIL-SA library was loaded for any of the modules or bundles found in the <config-response>. The library must be in the standard library location (e.g., /usr/lib/yumapro) or the
     --runpath CLI parameter must be used by sil-sa-app
  • Look for the sil-sa-app log message "skipping <register-request>"
    • Use at least --log-level=debug to see these messages  (Example shows --log-level=debug4)


ycontrol: dispatch message to service 'sil-sa'
Attempting to load module 'yumaworks-term-msg'
Loading YANG module from file:
   'yumaworks-term-msg.yang'
Loading YIN module from file: 
  yumaworks-term-msg.yin
Loading YANG module from file:
   '/home/andy/swdev/ypwork/netconf/modules/yumaworks/yumaworks-term-msg.yang'
yang_parse: Start module 'yumaworks-term-msg' OK
xmlns_reg:  id:23 mod:yumaworks-term-msg  uri: http://yumaworks.com/ns/yumaworks-term-msg
agt_cb: got new module 'yumaworks-term-msg', rev '2019-05-05'
yang_parse: Finish module 'yumaworks-term-msg@2019-05-05' OK
sil-sa: load SIL-SA code OK
agt_cb: No callbacks registered, skip make <register-request> msg
No SIL-SA objects; skipping <register-request>
ses_msg: free msg 0x563d631395c0 for session 1



Server Not Allowing Clients to Access Datastores
(Error 302: wrong config state)


Under certain conditions the server will not allow access to the configuration datastores because the YANG modules have not been loaded yet. This is usually because a SIL-SA bundle was loaded with the --bundle parameter, but the subsystem that supports the bundle has not registered with the server yet.  The server does not know the modules that are in the bundle until the SIL-SA subsystem sends a "register-request" with this information.


If this error occurs, the server will send an "operation-failed" error to the client.


<rpc-reply message-id="3" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <rpc-error>
  <error-type>protocol</error-type>
  <error-tag>operation-failed</error-tag>
  <error-severity>error</error-severity>
  <error-app-tag>no-access</error-app-tag>
  <error-message xml:lang="en">wrong config state</error-message>
  <error-info>
   <error-number>302</error-number>
  </error-info>
 </rpc-error>
</rpc-reply>