The YControl protocol is a proprietary protocol used by the netconfd-pro server to communicate with subsystems and other servers.
It is designed to be layered and is entirely modeled with YANG. There is a <payload> field that is augmented by each service that uses the YControl protocol. Current services include YP-HA, DB-API, and SIL-SA.
The YControl layer handles asynchronous message processing between different processes. It handles registration, initialization and cleanup, and other functions for all services layered on top of YControl.
Each server must have a unique server ID specified with the --server-id CLI parameter. The default is "server1".
Each subsystem must have a unique subsystem ID specified internally in the YControl registration APIs. The default is "subsys1".
There are 6 types of messages:
- server-event: Server event to subsystem; No response
- server-request: Server request to subsystem; subsys-response expected
- server-response: Server response to subsys-request; No response
- subsys-event: Subsystem event to server; No response
- subsys-request: Subsystem request to subsystem; server-response expected
- subsys-response: Subsystem response to server-request; No response
YControl Messages are defined with the following YANG module:
module yumaworks-ycontrol {
namespace "http://yumaworks.com/ns/yumaworks-ycontrol";
prefix "yctl";
import yuma-ncx { prefix ncx; }
import yuma-types { prefix yt; }
organization "YumaWorks, Inc.";
contact
"Support <support at yumaworks.com>";
description
"YumaPro control system message definition.";
revision 2014-11-19 {
description
"Support '*' as the service-id to indicate a server
event message that is intended for the YControl layer
itself, called ALL_SERVICES.
Add shutdown-event message for ALL_SERVICES";
}
revision 2014-04-08 {
description
"Initial version.";
}
container ycontrol {
ncx:abstract;
ncx:hidden;
leaf message-id {
mandatory true;
type uint32 {
range "1 .. max";
}
description
"Message identifier.
For server-response and subsys-response message types,
this value is the same as the corresponding request
message.";
}
leaf message-type {
mandatory true;
type enumeration {
enum server-event {
description
"Message from server to sub-system.
No response expected.";
}
enum server-request {
description
"Request message from server to sub-system.
A response is expected.";
}
enum server-response {
description
"Response message from server to sub-system.
Sent when subsys-req received.
No response is expected";
}
enum subsys-event {
description
"Message from sub-system to server.
No response expected.";
}
enum subsys-request {
description
"Request message from sub-system to server.
A response is expected.";
}
enum subsys-response {
description
"Response message from sub-system to server.
Sent when server-req received.
No response is expected";
}
enum ycontrol-error {
description
"Response message from either sub-system or server.
Sent when a recoverable YControl or service layer
error occurs.
If non-recoverable error, then session is dropped
and no response is sent. Example error: message
is for a service-id that does not exist.
No response is expected";
}
}
description "Message type";
}
leaf server-id {
mandatory true;
type union {
type yt:NcxName;
type string { length 0; }
}
description "Server identifier or empty if not known by subsys";
}
leaf subsys-id {
mandatory true;
type yt:NcxName;
description "Subsystem identifier";
}
leaf service-id {
mandatory true;
type union {
type yt:NcxName;
type string {
pattern '\*';
}
}
description
"Service identifier. The value '*' indicates a
server-event message to all services. These messages
are handled by the ycontrol library, not the individual
service libraries.";
}
choice message-payload {
mandatory true;
container payload {
description
"This <payload> container is augmented with a
service-specific container from other modules.";
leaf shutdown-event {
type empty;
description
"Message type: server-event;
Purpose: The server is shutting down. Sent to
all services (service-id = '*')
Expected Response Message: none";
} // leaf shutdown-event
}
leaf ok {
type empty;
description
"Sent when a request message is processed
successfully and no data is needed in the
response.";
}
container error {
leaf error-number {
mandatory true;
type uint32;
description "Internal error number";
}
leaf transaction-id {
type string;
description
"Server specific transaction identifier.
Sent from subsystem to server in
subsys-response.
It identifies the transaction in case multiple
transactions are in progress at once.";
}
leaf error-message {
type string;
description
"Internal error message, if different from
get_error_string(error-number).";
}
leaf error-index {
type uint32 {
range "1 .. max";
}
description
"Internal edit index number from <start-transaction>
message. Set only if an edit-specific error occurred.";
}
}
} // choice message-payload
} // container ycontrol
}