Overview


The Server Instrumentation Library for Sub-Agent support in YumaPro is called SIL-SA.

This is implemented as a YControl service.

The SIL-SA service running on a subsystem is composed of 3 components

  1. subsystem application (see sil-sa-app.c for an example subsystem application wrapper)
  2. Yumapro libraries to implement SIL-SA on a subsystem:
    1. libyumapro_ncx:  Core YANG and other support
    2. libyumapro_agt: Agent library used for some shared components with the main server
    3. libyumapro_sil-sa: SIL-SA support code
    4. libtumapro_ycontrol: YControl support code
  3. SIL-SA code to implement specific YANG modules


The user SIL-SA code (3) does not need to do anything to support these message flows. They are built into the YumaPro libraries.

The SIL-SA edit callbacks will be invoked as needed and the callback is just expected to process the transaction phase and return status.


Building the SIL_SA code stubs


The make_sil_sa_dir script can be used to generate SIL-SA code stubs


address.yang Example:


> make_sil_sa_dir  address --sil-get2 --sil-edit2
> cd address
> make
> sudo make install



SIL-SA Message Flows


Subsystem Initialization


The SIL-SA application will attempt to connect the main server when it starts.

The following message flow describes the initialization sequence.



  • config-request: the subsystem registers a 'sil-sa' service with YControl and request the server configuration
  • config-response: the server send a response containing the agent profile information and boot-time module and bundle information
  • register-request:
    • The subsystem checks the server config and decides if it should register callback handlers for any of the modules.
    • A subsystem can register for multiple YANG modules. Not all objects in a YANG module have to be supported by a subsystem.
    • Multiple subsystems can register for the same YANG module, but need to coordinate somehow so only 1 responds for a given data instance.
    • The subsystem does not send this message if no modules in the config-response need to be handled. If so, it waits for server events.
    • If registration is needed the server sends this message and waits for an 'ok' or 'error' response from the server
  • ok or error (register response): The server will send back registration status
  • trigger-replay:
    • if ok, the subsystem will send a trigger-event notification.
    • If there is any configuration for the subsystem, the Edit Transaction message exchange will be initiated by the server.
    • The subsystem waits for server requests or server events.
    • The trigger-replay can be sent at any time (except if transaction in progress) to cause the server to initiate its Configuration Replay procedure


Trigger Reply


The SIL-SA application will attempt to send <trigger-reply> event in order to retrieve configurations from the server.

The following message flow describes the trigger-reply sequence.




  • trigger-replay:
    • if ok, the subsystem will send a trigger-event notification to the server.
    • If there is any configuration for the subsystem, the Edit Transaction message exchange will be initiated by the server. The Init2 Phase callbacks will be invoked right after the Edit Transaction message exchange in this case.
    • If there is NO any configuration for the subsystem, the Server will wait until any request from the client, the request may be get, edit, action, rpc. When the server receives the request form the client it will be forwarded to the subsystem. The init2 Phase callbacks will be invoked right before the server request arrives to the subsystem and is about to be processed in this case.



Edit Transaction (success)


The server will initiate the edit transaction procedure when the configuration changes.

A subsystem will only be involved in the transaction if it has any objects registered that are changed in the transaction.

The following message flow describes the initialization sequence for a successful transaction:



  • rpc: The client send an edit-config request to the server
  • start-transaction: The server will send the transaction details that pertain to the subsystem. The subsystem will cache this data until the transaction is completed. The "validate" callback is invoked at this point.
  • ok: The subsystem accepts the edit and validates the data if needed. It sends a YControl ok message in response.
  • continue-transaction:  The server will send this message for the "apply" phase and then again for the "commit" phase.
  • rpc-reply: The server sends an RPC reply with "ok" status to the client



Edit Transaction (failure)


The server will initiate the edit transaction procedure when the configuration changes.

If some subsystem rejects an edit and returns an error, the transaction will be cancelled.



  • cancel-transaction: The server may send a cancel-transaction event if the transaction fails.
  • continue-transaction(rollback): The server may send a continue-transaction message for the "rollback" phase instead of a "commit" phase.
  • start-transaction(reverse-edit): If the transaction fails after a subsystem has been sent a continue-transaction message for the "commit" phase, then the server will send that subsystem a new transaction to undo the edits that actually failed. This is called a "reverse edit".


Once the subsystem has received a continue-transaction message for either the "commit" or "rollback" phase, the subsystem can release temporary resources for the transaction.  If a transaction actually does fail after this point, the server will start a new transaction to undo edits as needed.



Edit Transaction (With Hook Callbacks)


The server will initiate the edit transaction procedure when the configuration changes and also may invoke Set Hook callbacks that may trigger additional message exchange between the server and the subsystem.




  • rpc: The client send an edit-config request to the server
  • start-transaction: The server will send the transaction details that pertain to the subsystem. The subsystem will cache this data until the transaction is completed. The "validate" callback is invoked at this point.
  • hook-get-request: The subsystem may send the get request to the server with help of get_data API to retrieve some node from the server.
  • hook-get-response: The server may reply with requested val_value based on XPath of object instance.
  • transaction-response: The subsystem may reply with this message and provide added edits to the server.
  • start-transaction for added edits: In case the subsystem added edits with help of add_edit API it will send another start-transaction for the added edits
  • ok: The subsystem accepts the edit and validates the data if needed. It sends a YControl ok message in response.
  • continue-transaction:  The server will send this message for the "apply" phase and then again for the "commit" phase.
  • rpc-reply: The server sends an RPC reply with "ok" status to the client


Once the subsystem has received a continue-transaction message for either the "commit" or "rollback" phase, the subsystem can release temporary resources for the transaction.  If a transaction actually does fail after this point, the server will start a new transaction to undo edits as needed.




Get Transaction


The server will start a retrieval procedure when a client requests operational data that is handled by SIL-SA subsystems.

  • For YANG lists, the server will send multiple requests as needed.
  • The <get-bulk> operation is supported for SIL-SA subsystems.
  • The --max-getbulk CLI parameter controls how many YANG list instances are requested at once



  • rpc: A NETCONF client will send a <get> operation. A RESTCONF client will send a GET operation.
  • get-request: The server will send this message to a subsystem if the client requested any objects handled by that subsystem.
  • get-response: The subsystem will send this message with the data requested by the server (or empty if requested instances not found)
  • rpc-reply: The server will be streaming data to the client, using this message, as it is received from the subsystems.


Additional Server Events


  • load-event: Sent by the server to a subsystem when a module is loaded or unloaded at run-time
  • bundle-load-event: Sent by the server to a subsystem when a bundle is loaded or unloaded at run-time


Edit Transaction Example


The following example message sequences show an edit operation to simply add a new addresses container.

If the --create-empty-npcontainers CLI parameter is set to 'true' then edit transactions for YANG non-presence containers will be done.


1) start-transaction (from server to subsystem)


<?xml version="1.0" encoding="UTF-8"?>
<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>
    <edit>
     <id>1</id>
     <newval>
      <addresses ya:datapath="/addr:addresses"
       xmlns="http://www.yumaworks.com/ns/address"/>
     </newval>
     <operation>load</operation>
     <path>/addr:addresses</path>
    </edit>
    <reverse-edit>false</reverse-edit>
    <target>running</target>
    <transaction-id>9992</transaction-id>
    <user-id>superuser</user-id>
    <validate>false</validate>
   </start-transaction>
  </sil-sa>
 </payload>
</ycontrol>



2) ok (from subsystem to server)


<?xml version="1.0" encoding="UTF-8"?>
<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>



3) continue-transaction (from server to subsystem)


<?xml version="1.0" encoding="UTF-8"?>
<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>
    <phase>apply</phase>
    <transaction-id>9992</transaction-id>
   </continue-transaction>
  </sil-sa>
 </payload>
</ycontrol>



4) ok (from subsystem to server)


<?xml version="1.0" encoding="UTF-8"?>
<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/>
</ycontrol>



5) continue-transaction (from server to subsystem)


<?xml version="1.0" encoding="UTF-8"?>
<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>
    <phase>commit</phase>
    <transaction-id>9992</transaction-id>
   </continue-transaction>
  </sil-sa>
 </payload>
</ycontrol>



6) ok (from subsystem to server)


<?xml version="1.0" encoding="UTF-8"?>
<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>