NSO Web UI development information.
Web UI development is thought to be in the hands of the customer's front-end developers. They know best the requirements and how to fulfill those requirements in terms of aesthetics, functionality, and toolchain (frameworks, libraries, external data sources, and services).
NSO comes with a nortbound interface in the shape of a JSON-RPC API. This API is designed with Web UI applications in mind, and it complies with the JSON-RPC 2.0 specification while using HTTP/S as the transport mechanism.
The JSON-RPC API contains a handful of methods with well-defined input method and params, along with the output result.
In addition, the API also implements a Comet model, as long polling, to allow the client to subscribe to different server events and receive event notifications about those events in near real-time.
You can call these from a browser via:
AJAX (e.g., XMLHTTPRequest, jQuery [https://jquery.com/])
Or from the command line (e.g., curl [https://github.com/bagder/curl], httpie [https://github.com/jkbr/httpie])
// with jQuery
$.ajax({
type: 'post',
url: '/jsonrpc',
contentType: 'application/json',
data: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'login',
params: {
'user': 'joe',
'passwd': 'SWkkasE32'
}
}),
dataType: 'json'
})
.done(function(data) {
if (data.result)
alert(data.result);
else
alert(data.error.type);
}); # with curl
curl \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "login",
"params": {"user": "joe",
"passwd": "SWkkasE32"}}' \
http://127.0.0.1:8008/jsonrpc
# with httpie
http POST http://127.0.0.1:8008/jsonrpc \
jsonrpc=2.0 id:=1 \
method=login \
params:='{"user": "joe", "passwd": "SWkkasE32"}'You can read in the JSON-RPC API section about all the available methods and their signatures, but here is a working example of how a common flow would look like:
Log in.
Create a new read transaction.
Read a value.
Create a new WebUI (read-write) transaction, in preparation for changing the value.
Change a value.
Commit (save) the changes.
Meanwhile, subscribe to changes and receive a notification.
In the release package, under ${NCS_DIR}/var/ncs/webui/example, you will find the working code to run the example below.
/*jshint devel:true*/
// !!!
// The following code is purely for example purposes.
// The code has inline comments for a better understanding.
// Your mileage might vary.
// !!!
define([
'lodash',
'bluebird',
'./JsonRpc',
'./Comet'
], function(
_,
Promise,
JsonRpc,
Comet
) {
'use strict';
// CHANGE AT LEAST THESE
// IN ORDER TO MAKE THIS EXAMPLE WORK IN YOUR SETUP
var jsonrpcUrl = '/jsonrpc', // 'http://localhost:8008/jsonrpc';
path = '/dhcp:dhcp/max-lease-time',
value = Math.floor(Math.random() * 800) + 7200;
var log,
jsonRpc,
comet,
funs = {},
ths = {
read: undefined,
webui: undefined
};
// UTILITY
log = function(msg) {
document.body.innerHTML =
'<pre>' +
msg +
'</pre>' +
document.body.innerHTML;
};
// SETUP
jsonRpc = new JsonRpc({
url: jsonrpcUrl,
onError: function(method, params, deferred, reply) {
var error = reply.error,
msg = [method,
params,
reply.id,
error.code,
error.type,
error.message
];
if (method === 'comet') {
return;
}
window.alert('JsonRpc error: ' + msg);
}
});
comet = new Comet({
jsonRpc: jsonRpc,
onError: function(reply) {
var error = reply.error,
msg = [reply.id, error.code, error.type, error.message];
window.alert('Comet error: ' + msg);
}
});
// CALLS FOR A COMMON SCENARIO
funs.login = function() {
log('Logging in as admin:admin...');
return jsonRpc.call('login', {
user: 'admin',
passwd: 'admin'
}).done(function() {
log('Logged in.');
});
};
funs.getSystemSetting = function() {
log('Getting system settings...');
return jsonRpc.call('get_system_setting').done(function(result) {
log(JSON.stringify(result, null, 1));
});
};
funs.newReadTrans = function() {
log('Create a new read-only transaction...');
return jsonRpc.call('new_read_trans', {
db: 'running'
}).done(function(result) {
ths.read = result.th;
log('Read-only transaction with th (transaction handle) id: ' +
result.th + '.');
});
};
funs.newWebuiTrans = function() {
log('Create a new webui (read-write) transaction...');
return jsonRpc.call('new_webui_trans', {
conf_mode: 'private',
db: 'candidate'
}).done(function(result) {
ths.webui = result.th;
log('webui (read-write) transaction with th (transaction handle) id: ' +
result.th + '.');
});
};
funs.getValue = function(args /*{th, path}*/) {
log('Get value for ' + args.path + ' in ' + args.th + ' transaction...');
if (typeof args.th === 'string') {
args.th = ths[args.th];
}
return jsonRpc.call('get_value', {
th: args.th,
path: path
}).done(function(result) {
log(path + ' is now set to: ' + result.value + '.');
});
};
funs.setValue = function(args /*{th, path, value}*/) {
log('Set value for ' + args.path +
' to ' + args.value +
' in ' + args.th + ' transaction...');
if (typeof args.th === 'string') {
args.th = ths[args.th];
}
return jsonRpc.call('set_value', {
th: args.th,
path: path,
value: args.value
}).done(function(result) {
log(path + ' is now set to: ' + result.value + '.');
});
};
funs.validate = function(args /*{th}*/) {
log('Validating changes in ' + args.th + ' transaction...');
if (typeof args.th === 'string') {
args.th = ths[args.th];
}
return jsonRpc.call('validate_commit', {
th: args.th
}).done(function() {
log('Validated.');
});
};
funs.commit = function(args /*{th}*/) {
log('Commiting changes in ' + args.th + ' transaction...');
if (typeof args.th === 'string') {
args.th = ths[args.th];
}
return jsonRpc.call('commit', {
th: args.th
}).done(function() {
log('Commited.');
});
};
funs.subscribeChanges = function(args /*{path, handle}*/) {
log('Subcribing to changes of ' + args.path +
' (with handle ' + args.handle + ')...');
return jsonRpc.call('subscribe_changes', {
comet_id: comet.id,
path: args.path,
handle: args.handle,
}).done(function(result) {
log('Subscribed with handle id ' + result.handle + '.');
});
};
// RUN
Promise.resolve([
funs.login,
funs.getSystemSetting,
funs.newReadTrans,
function() {
return funs.getValue({th: 'read', path: path});
},
function() {
var handle = comet.id + '-max-lease-time';
comet.on(handle, function(msg) {
log('>>> Notification >>>\n' +
JSON.stringify(msg, null, 2) +
'\n<<< Notification <<<');
});
return funs.subscribeChanges({th: 'read', path: path, handle: handle});
},
funs.newWebuiTrans,
function() {
return funs.setValue({th: 'webui', path: path, value: value.toString()});
},
function() {
return funs.getValue({th: 'webui', path: path});
},
function() {
return funs.validate({th: 'webui'});
},
function() {
return funs.commit({th: 'webui'});
},
function() {
return new Promise(function(resolve) {
log('Waiting 2.5 seconds before one last call to get_value');
window.setTimeout(function() {
resolve();
}, 2500);
});
},
function() {
return funs.getValue({th: 'read', path: path});
},
]).each(function(fn){
return fn().then(function() {
log('--------------------------------------------------');
});
});
});
// Local Variables:
// mode: js
// js-indent-level: 2
// End:In the example above describing a common flow, a reference is made to using a JSON-RPC client to make the RPC calls.
An example implementation of a JSON-RPC client, used in the example above:
/*jshint devel:true*/
// !!!
// The following code is purely for example purposes.
// The code has inline comments for a better understanding.
// Your mileage might vary.
// !!!
define([
'jquery',
'lodash'
], function(
$,
_
) {
'use strict';
var JsonRpc;
JsonRpc = function(params) {
$.extend(this, {
// API
// Call a JsonRpc method with params
call: undefined,
// API (OPTIONAL)
// Decide what to do when there is no active session
onNoSession: undefined,
// Decide what to do when the request errors
onError: undefined,
// Set an id to start using in requests
id: 0,
// Set another url for the JSON-RPC API
url: '/jsonrpc',
// INTERNAL
makeOnCallDone: undefined,
makeOnCallFail: undefined
}, params || {});
_.bindAll(this, [
'call',
'onNoSession',
'onError',
'makeOnCallDone',
'makeOnCallFail'
]);
};
JsonRpc.prototype = {
call: function(method, params, timeout) {
var deferred = $.Deferred();
// Easier to associate request/response logs
// when the id is unique to each request
this.id = this.id + 1;
$.ajax({
// HTTP method is always POST for the JSON-RPC API
type: 'POST',
// Let's show <method> rather than just "jsonrpc"
// in the browsers' Developer Tools - Network tab - Name column
url: this.url + '/' + method,
// Content-Type is mandatory
// and is always "application/json" for the JSON-RPC API
contentType: 'application/json',
// Optionally set a timeout for the request
timeout: timeout,
// Request payload
data: JSON.stringify({
jsonrpc: '2.0',
id: this.id,
method: method,
params: params
}),
dataType: 'json',
// Just in case you are doing cross domain requests
// NOTE: make sure you are setting CORS headers similarly to
// --
// Access-Control-Allow-Origin: http://server1.com, http://server2.com
// Access-Control-Allow-Credentials: true
// Access-Control-Allow-Headers: Origin, Content-Type, Accept
// Access-Control-Request-Method: POST
// --
// if you want to allow JSON-RPC calls from server1.com and server2.com
crossDomain: true,
xhrFields: {
withCredentials: true
}
})
// When done, or on failure,
// call a function that has access to both
// the request and the response information
.done(this.makeOnCallDone(method, params, deferred))
.fail(this.makeOnCallFail(method, params, deferred));
return deferred.promise();
},
makeOnCallDone: function(method, params, deferred) {
var me = this;
return function(reply/*, status, xhr*/) {
if (reply.error) {
return me.onError(method, params, deferred, reply);
}
deferred.resolve(reply.result);
};
},
onNoSession: function() {
// It is common practice that when missing a session identifier
// or when the session crashes or it times out due to inactivity
// the user is taken back to the login page
_.defer(function() {
window.location.href = 'login.html';
});
},
onError: function(method, params, deferred, reply) {
if (reply.error.type === 'session.missing_sessionid' ||
reply.error.type === 'session.invalid_sessionid') {
this.onNoSession();
}
deferred.reject(reply.error);
},
makeOnCallFail: function(method, params, deferred) {
return function(xhr, status, errorMessage) {
var error;
error = $.extend(new Error(errorMessage), {
type: 'ajax.response.error',
detail: JSON.stringify({method: method, params: params})
});
deferred.reject(error);
};
}
};
return JsonRpc;
});
// Local Variables:
// mode: js
// js-indent-level: 2
// End:In the example above describing a common flow, a reference is made to starting a Comet channel and subscribing to changes on a specific path.
An example implementation of a Comet client, used in the example above:
/*jshint devel:true*/
// !!!
// The following code is purely for example purposes.
// The code has inline comments for a better understanding.
// Your mileage might vary.
// !!!
define([
'jquery',
'lodash',
'./JsonRpc'
], function(
$,
_,
JsonRpc
) {
'use strict';
var Comet;
Comet = function(params) {
$.extend(this, {
// API
// Add a callback for a notification handle
on: undefined,
// Remove a specific callback or all callbacks for a notification handle
off: undefined,
// Stop all comet notifications
stop: undefined,
// API (OPTIONAL)
// Decide what to do when the comet errors
onError: undefined,
// Optionally set a different id for this comet channel
id: 'main-1.' + String(Math.random()).substring(2),
// Optionally give an existing JsonRpc client
jsonRpc: new JsonRpc(),
// Optionally wait 1 second in between polling the comet channel
sleep: 1 * 1000,
// INTERNAL
handlers: [],
polling: false,
poll: undefined,
onPollDone: undefined,
onPollFail: undefined
}, params || {});
_.bindAll(this, [
'on',
'off',
'stop',
'onError',
'poll',
'onPollDone',
'onPollFail'
]);
};
Comet.prototype = {
on: function(handle, callback) {
if (!callback) {
throw new Error('Missing a callback for handle ' + handle);
}
// Add a handler made of handle id and a callback function
this.handlers.push({handle: handle, callback: callback});
// Start polling
_.defer(this.poll);
},
off: function(handle, callback) {
if (!handle) {
throw new Error('Missing a handle');
}
// Remove all handlers matching the handle,
// and optionally also the callback function
_.remove(this.handlers, {handle: handle, callback: callback});
// If there are no more handlers matching the handle,
// then unsubscribe from notifications, in order to releave
// the server and the network from redundancy
if (!_.find(this.handlers, {handle: handle}).length) {
this.jsonRpc.call('unsubscribe', {handle: handle});
}
},
stop: function() {
var me = this,
deferred = $.Deferred(),
deferreds = [];
if (this.polling) {
// Unsubcribe from all known notifications, in order to releave
// the server and the network from redundancy
_.each(this.handlers, function(handler) {
deferreds.push(me.jsonRpc('unsubscribe', {
handle: handler.handle
}));
});
$.when.apply($, deferreds).done(function() {
deferred.resolve();
}).fail(function(err) {
deferred.reject(err);
}).always(function() {
me.polling = false;
me.handlers = [];
});
} else {
deferred.resolve();
}
return deferred.promise();
},
poll: function() {
var me = this;
if (this.polling) {
return;
}
this.polling = true;
this.jsonRpc.call('comet', {
comet_id: this.id
}).done(function(notifications) {
me.onPollDone(notifications);
}).fail(function(err) {
me.onPollFail(err);
}).always(function() {
me.polling = false;
});
},
onPollDone: function(notifications) {
var me = this;
// Polling has stopped meanwhile
if (!this.polling) {
return;
}
_.each(notifications, function(notification) {
var handle = notification.handle,
message = notification.message,
handlers = _.where(me.handlers, {handle: handle});
// If we received a notification that we cannot handle,
// then unsubcribe from it, in order to releave
// the server and the network from redundancy
if (!handlers.length) {
return this.jsonRpc.call('unsubscribe', {handle: handle});
}
_.each(handlers, function(handler) {
_.defer(function() {handler.callback(message);});
});
});
_.defer(this.poll);
},
onPollFail: function(error) {
switch (error.type) {
case 'comet.duplicated_channel':
this.onError(error);
break;
default:
this.onError(error);
_.wait(this.poll, this.sleep);
}
},
onError: function(reply) {
var error = reply.error,
msg = [reply.id, error.code, error.type, error.message].join(' ');
console.error('Comet error: ' + msg);
}
};
return Comet;
});
// Local Variables:
// mode: js
// js-indent-level: 2
// End:The Single Sign-On functionality enables users to log in via HTTP-based northbound APIs with a single sign-on authentication scheme, such as SAMLv2. Currently, it is only supported for the JSON-RPC northbound interface.
For Single Sign-On to work, the Package Authentication needs to be enabled, see Package Authentication).
When enabled, the endpoint /sso is made public and handles Single Sign-on attempts.
An example configuration for the cisco-nso-saml2-auth Authentication Package is presented below. Note that /ncs-config/aaa/auth-order does not need to be set for Single Sign-On to work!
<aaa>
<package-authentication>
<enabled>true</enabled>
<packages>
<package>cisco-nso-saml2-auth</package>
</packages>
</package-authentication>
<single-sign-on>
<enabled>true</enabled>
</single-sign-on>
</aaa>A client attempting single sign-on authentication should request the /sso endpoint and then follow the continued authentication operation from there. For example, for cisco-nso-saml2-auth, the client is redirected to an Identity Provider (IdP), which subsequently handles the authentication, and then redirects the client back to the /sso endpoint to validate the authentication and set up the session.
An embedded basic web server can be used to deliver static and Common Gateway Interface (CGI) dynamic content to a web client, such as a web browser. See Web Server for more information.
API documentation for JSON-RPC API.
The contains all the details you need to understand the protocol but a short version is given here:
A request payload typically looks like this:
Where, the method and params properties are as defined in this manual page.
A response payload typically looks like this:
Or:
The request id param is returned as-is in the response to make it easy to pair requests and responses.
The batch JSON-RPC standard is dependent on matching requests and responses by id, since the server processes requests in any order it sees fit e.g.:
With a possible response like (first result for add, the second result for subtract):
The URL for the JSON-RPC API is `/jsonrpc`. For logging and debugging purposes, you can add anything as a subpath to the URL, for example turning the URL into `/jsonrpc/<method>` which will allow you to see the exact method in different browsers' Developer Tools - Network tab - Name column, rather than just an opaque jsonrpc.
For brevity, in the upcoming descriptions of each method, only the input params and the output result are mentioned, although they are part of a fully formed JSON-RPC payload.
Authorization is based on HTTP cookies. The response to a successful call to login would create a session, and set an HTTP-only cookie, and even an HTTP-only secure cookie over HTTPS, named sessionid. All subsequent calls are authorized by the presence and the validity of this cookie.
The th param is a transaction handle identifier as returned from a call to new_read_trans or new_write_trans.
The comet_id param is a unique ID (decided by the client) that must be given first in a call to the comet method, and then to upcoming calls which trigger comet notifications.
The handle param needs to have a semantic value (not just a counter) prefixed with the comet ID (for disambiguation), and overrides the handle that would have otherwise been returned by the call. This gives more freedom to the client and sets semantic handles.
The JSON-RPC specification defines the following error code values:
-32700 - Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600 - The JSON sent is not a valid Request object.
-32601 - The method does not exist/is not available.
-32602 - Invalid method parameter(s).
-32603 - Internal JSON-RPC error.
-32000 to -32099 - Reserved for application-defined errors (see below).
To make server errors easier to read, along with the numeric code, we use a type param that yields a literal error token. For all application-defined errors, the code is always -32000. It's best to ignore the code and just use the type param.
Which results in:
The message param is a free text string in English meant for human consumption, which is a one-to-one match with the type param. To remove noise from the examples, this param is omitted from the following descriptions.
An additional method-specific data param may be added to give further details on the error, most predominantly a reason param which is also a free text string in English meant for human consumption. To remove noise from the examples, this param is omitted from the following descriptions. However any additional data params will be noted by each method description.
All methods may return one of the following JSON RPC or application-defined errors, in addition to others, specific to each method.
The JSON-RPC session ties the client and the server via an HTTP cookie, named sessionid which contains a randomly server-generated number. This cookie is not only secure (when the requests come over HTTPS), meaning that HTTPS cookies do not leak over HTTP, but even more importantly this cookie is also HTTP-only, meaning that only the server and the browser (e.g. not the JavaScript code) have access to the cookie. Furthermore, this cookie is a session cookie, meaning that a browser restart would delete the cookie altogether.
The JSON-RPC session lives as long as the user does not request to log out, as long as the user is active within a 30-minute (default value, which is configurable) time frame, and as long as there are no severe server crashes. When the session dies, the server will reply with the intention to delete any sessionid cookies stored in the browser (to prevent any leaks).
The embedded server allows for custom headers to be set, in this case, CORS headers, like:
A server hosted at http://server.com responding with these headers would mean that the JSON-RPC API can be contacted from a browser that is showing a web page from http://webpage.com, and will allow the browser to make POST requests, with a limited amount of headers and with credentials (i.e. cookies).
This is not enough though, because the browser also needs to be told that your JavaScript code really wants to make a CORS request. A jQuery example would show like this:
Without this setup, you will notice that the browser will not send the sessionid cookie on post-login JSON-RPC calls.
A tagpath is a path pointing to a specific position in a YANG module's schema.
A keypath is a path pointing to a specific position in a YANG module's instance.
These kinds of paths are used for several of the API methods (e.g. set_value, get_value, subscribe_changes), and could be seen as XPath path specifications in abbreviated format.
Let's look at some examples using the following YANG module as input:
Valid tagpaths:
`/d:config/description`
`/d:config/device/interface`
Valid keypaths:
`/d:config/device{eth0}/date` - the date leaf value within a device with an interface key set to eth0.
Note how the prefix is prepended to the first tag in the path. This prefix is compulsory.
The AAA infrastructure can be used to restrict access to library functions using command rules:
Note how the command is prefixed with ::jsonrpc::. This tells the AAA engine to apply the command rule to JSON-RPC API functions.
session.overload error?A series of limits are imposed on the load that one session can put on the system. This reduces the risk that a session takes over the whole system and brings it into a DoS situation.
The response will include details about the limit that triggered the error.
Known limits:
Only 10000 commands/subscriptions are allowed per session
init_cmdStarts a batch command.
Note: The start_cmd method must be called to actually get the batch command to generate any messages unless the handle is provided as input.
Note: As soon as the batch command prints anything on stdout, it will be sent as a message and turn up as a result to your polling call to the comet method.
Params
The name param is one of the named commands defined in ncs.conf.
The args param specifies any extra arguments to be provided to the command except for the ones specified in ncs.conf.
The emulate param specifies if terminal emulation should be enabled.
The width, height, scroll properties define the screen properties.
Result
A handle to the batch command is returned (equal to handle if provided).
send_cmd_dataSends data to batch command started with init_cmd.
Params
The handle param is as returned from a call to init_cmd and the data param is what is to be sent to the batch command started with init_cmd.
Result
Errors (specific)
start_cmdSignals that a batch command can start to generate output.
Note: This method must be called to actually start the activity initiated by calls to one of the methods init_cmd.
Params
The handle param is as returned from a call to init_cmd.
Result
suspend_cmdSuspends output from a batch command.
Note: the init_cmd method must have been called with the emulate param set to true for this to work
Params
The handle param is as returned from a call to init_cmd.
Result
resume_cmdResumes a batch command started with init_cmd.
Note: the init_cmd method must have been called with the emulate param set to true for this to work.
Params
The handle param is as returned from a call to init_cmd.
Result
stop_cmdStops a batch command.
Note: This method must be called to stop the activity started by calls to one of the methods init_cmd.
Params
The handle param is as returned from a call to init_cmd.
Result
subscribe_cdboperStarts a subscriber to operational data in CDB. Changes done to configuration data will not be seen here.
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated it will be sent as a message and turn up as result to your polling call to the comet method.
Params
The path param is a keypath restricting the subscription messages to only be about changes done under that specific keypath.
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format of that message will be an array of changes of the same type as returned by the subscribe_changes method. See below.
Errors (specific)
subscribe_changesStarts a subscriber to configuration data in CDB. Changes done to operational data in CDB data will not be seen here. Furthermore, subscription messages will only be generated when a transaction is successfully committed.
Note: The start_subscription method must be called to actually get the subscription to generate any messages, unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated, it will be sent as a message and turn up as result to your polling call to the comet method.
Params
The path param is a keypath restricting the subscription messages to only be about changes done under that specific keypath.
The skip_local_changes param specifies if configuration changes done by the owner of the read-write transaction should generate subscription messages.
The hide_changes and hide_values params specify a lower level of information in subscription messages, in case it is enough to receive just a "ping" or a list of changed keypaths, respectively, but not the new values resulted in the changes.
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format of that message will be an object such as:
The user and ip properties are the username and IP address of the committing user.
The changes param is an array of changes of the same type as returned by the changes method. See above.
subscribe_poll_leafStarts a polling subscriber to any type of operational and configuration data (outside of CDB as well).
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated, it will be sent as a message and turn up as result to your polling call to the comet method.
Params
The path param is a keypath pointing to a leaf value.
The interval is a timeout in seconds between when to poll the value.
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format is a simple string value.
subscribe_upgradeStarts a subscriber to upgrade messages.
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated, it will be sent as a message and turn up as result to your polling call to the comet method.
Params
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format of that message will be an object such as:
subscribe_jsonrpc_batchStarts a subscriber to JSONRPC messages for batch requests.
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated it will be sent as a message and turn up as result to your polling call to the comet method.
Params
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method having exact same structure like a JSON-RPC response:
subscribe_progress_traceStarts a subscriber to progress trace events.
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated, it will be sent as a message and turn up as result to your polling call to the comet method.
Params
The verbosity param specifies the verbosity of the progress trace.
The filter_context param can be used to only get progress events from a specific context For example, if filter_context is set to cli only progress trace events from the CLI are returned.
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format of that message will be an object such as:
start_subscriptionSignals that a subscribe command can start to generate output.
Note: This method must be called to actually start the activity initiated by calls to one of the methods subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade **with no handle.
Params
The handle param is as returned from a call to subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade.
Result
unsubscribeStops a subscriber.
Note: This method must be called to stop the activity started by calls to one of the methods subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade.
Params
The handle param is as returned from a call to subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade.
Result
createCreate a list entry, a presence container, or a leaf of type empty.
Params
The path param is a keypath pointing to data to be created.
Result
Errors (specific)
deleteDeletes an existing list entry, a presence container, or an optional leaf and all its children (if any).
Params
The path param is a keypath pointing to data to be deleted.
Result
Errors (specific)
existsChecks if optional data exists.
Params
The path param is a keypath pointing to data to be checked for existence.
Result
get_caseGet the case of a choice leaf.
Params
The path param is a keypath pointing to data that contains the choice leaf given by the choice param.
Result
show_configRetrieves configuration and operational data from the provided transaction.
Params
The path param is a keypath to the configuration to be returned. result_as controls the output format, string for a compact string format, json for JSON-compatible with RESTCONF and json2 for a variant of the RESTCONF JSON format. max_size sets the maximum size of the data field in kb, set to 0 to disable the limit.
Result
result_as string:
result_as JSON:
loadLoad XML configuration into the current transaction.
Params
The data param is the data to be loaded into the transaction. mode controls how the data is loaded into the transaction, analogous with the CLI command load. format informs load about which format data is in. If format is xml, the data must be an XML document encoded as a string. If format is json, data can either be a JSON document encoded as a string or the JSON data itself.
Result
Errors (specific)
get_attrsGet node attributes.
Params
The path param is a keypath pointing to the node and the names param is a list of attribute names that you want to retrieve.
Result
set_attrsSet node attributes.
Params
The path param is a keypath pointing to the node and the attrs param is an object that maps attribute names to their values.
Result
get_valueGets a leaf value.
Params
The path param is a keypath pointing to a value.
The check_default param adds is_default to the result if set to true. is_default is set to true if the default value handling returned the value.
Result
Example
get_valuesGet leaf values.
Params
The path param is a keypath pointing to a container. The leafs param is an array of children names residing under the parent container in the YANG module.
The check_default param adds is_default to the result if set to true. is_default is set to true if the default value handling returned the value.
Result
Note: The access object has no read and/or write properties if there are no read and/or access rights.
set_valueSets a leaf value.
Params
The path param is the keypath to give a new value as specified with the value param.
value can be an array when the path is a leaf-list node.
When value is null, the set_value method acts like delete.
When dryrun is true, this function can be used to test if a value is valid or not.
Result
Errors (specific)
Example
derefDereferences a leaf with a leafref type.
Params
The path param is a keypath pointing to a leaf with a leafref type.
Result
get_leafref_valuesGets all possible values for a leaf with a leafref type.
Params
The th param is as returned from a call to new_read_trans or new_write_trans. The path param is a keypath pointing to a leaf with a leafref type.
Note: If the leafref is within an action or RPC, th should be created with an action_path.
The offset param is used to skip as many values as it is set to. E.g. an offset of 2 will skip the first 2 values. If not given the value defaults to 0, which means no values are skipped. The offset needs to be a non-negative integer or an invalid params error will be returned. An offset that is bigger than the length of the leafref list will result in a method failed error being returned.
Note: offset used together with limit (see below) can be used repeatedly to paginate the leafref values.
The limit param can be set to limit the number of returned values. E.g. a limit of 5 will return a list with 5 values. If not given, the value defaults to -1, which means no limit. The limit needs to be -1 or a non-negative integer or an invalid params error will be returned. A Limit of 0 will result in an empty list being returned
The starts_with param can be used to filter values by prefix.
The skip_grouping param is by default set to false and is only needed to be set to true if a set of sibling leafref leafs points to a list instance with multiple keys and if get_leafref_values should return an array of possible leaf values instead an array of arrays with possible key value combinations.
The keys param is an optional array of values that should be set if more than one leafref statement is used within action/RPC input parameters and if they refer to each other using `deref()` or `current()` XPath functions. For example, consider this model:
The leaf if refers to leaf name in its XPath expression so to be able to successfully run get_leafref_values on that node you need to provide a valid value for the name leaf using the keys parameter. The keys parameter could for example look like this:
Result
The source param will point to the keypath where the values originate. If the keypath cannot be resolved due to missing/faulty items in the keys parameter source will be false.
rename_list_entryRenames a list entry.
Params
The from_path is a keypath pointing out the list entry to be renamed.
The list entry to be renamed will, under the hood, be deleted all together and then recreated with the content from the deleted list entry copied in.
The to_keys param is an array with the new key values. The array must contain a full set of key values.
Result
Errors (specific)
copy_list_entryCopies a list entry.
Params
The from_path is a keypath pointing out the list entry to be copied.
The to_keys param is an array with the new key values. The array must contain a full set of key values.
Copying between different ned-id versions works as long as the schema nodes being copied has not changed between the versions.
Result
Errors (specific)
move_list_entryMoves an ordered-by user list entry relative to its siblings.
Params
The from_path is a keypath pointing out the list entry to be moved.
The list entry to be moved can either be moved to the first or the last position, i.e. if the mode param is set to first or last the to_path keypath param has no meaning.
If the mode param is set to before or after the to_path param must be specified, i.e. the list entry will be moved to the position before or after the list entry which the to_path keypath param points to.
Result
Errors (specific)
append_list_entryAppend a list entry to a leaf-list.
Params
The path is a keypath pointing to a leaf-list.
Result
count_list_keysCounts the number of keys in a list.
Params
The path parameter is a keypath pointing to a list.
Result
get_list_keysEnumerates keys in a list.
Params
The th parameter is the transaction handle.
The path parameter is a keypath pointing to a list. Required on first invocation - optional in following.
The chunk_size parameter is the number of requested keys in the result. Optional - default is unlimited.
The start_with parameter will be used to filter out all those keys that do not start with the provided strings. The parameter supports multiple keys e.g. if the list has two keys, then start_with can hold two items.
The lh (list handle) parameter is optional (on the first invocation) but must be used in the following invocations.
Result
Each invocation of get_list_keys will return at most chunk_size keys. The returned lh must be used in the following invocations to retrieve the next chunk of keys. When no more keys are available the returned lh will be set to `-1`.
On the first invocation lh can either be omitted or set to `-1`.
queryStarts a new query attached to a transaction handle, retrieves the results, and stops the query immediately. This is a convenience method for calling start_query, run_query and stop_query in a one-time sequence.
This method should not be used for paginated results, as it results in performance degradation - use start_query, multiple run_query and stop_query instead.
Example
start_queryStarts a new query attached to a transaction handle. On success, a query handle is returned to be in subsequent calls to run_query.
Params
The xpath_expr param is the primary XPath expression to base the query on. Alternatively, one can give a keypath as the path param, and internally the keypath will be translated into an XPath expression.
A query is a way of evaluating an XPath expression and returning the results in chunks. The primary XPath expression must evaluate to a node-set, i.e. the result. For each node in the result, a selection Xpath expression is evaluated with the result node as its context node.
Note: The terminology used here is as defined in http://en.wikipedia.org/wiki/XPath.
For example, given this YANG snippet:
The xpath_expr could be `/interface[enabled='true']` and selection could be `{ "name", "number" }`.
Note that the selection expressions must be valid XPath expressions, e.g. to figure out the name of an interface and whether its number is even or not, the expressions must look like: `{ "name", "(number mod 2) == 0" }`.
The result are then fetched using run_query, which returns the result on the format specified by result_as param.
There are two different types of results:
string result is just an array with resulting strings of evaluating the selection XPath expressions
`keypath-value` result is an array the keypaths or values of the node that the selection XPath expression evaluates to.
This means that care must be taken so that the combination of selection expressions and return types actually yield sensible results (for example `1 + 2` is a valid selection XPath expression, and would result in the string 3 when setting the result type to string - but it is not a node, and thus have no keypath-value.
It is possible to sort the result using the built-in XPath function `sort-by()` but it is also also possible to sort the result using expressions specified by the sort param. These expressions will be used to construct a temporary index which will live as long as the query is active. For example, to start a query sorting first on the enabled leaf, and then on number one would call:
The context_node param is a keypath pointing out the node to apply the query on; only taken into account when the xpath_expr uses relatives paths. Lack of a context_node, turns relatives paths into absolute paths.
The chunk_size param specifies how many result entries to return at a time. If set to 0, a default number will be used.
The initial_offset param is the result entry to begin with (1 means to start from the beginning).
Result
A new query handler handler id to be used when calling run_query etc
Example
run_queryParams
The qh param is as returned from a call to start_query.
Result
The position param is the number of the first result entry in this chunk, i.e. for the first chunk it will be 1.
How many result entries there are in this chunk is indicated by the number_of_results param. It will be 0 for the last chunk.
The chunk_size and the result_as properties are as given in the call to start_query.
The total_number_of_results param is total number of result entries retrieved so far.
The result param is as described in the description of start_query.
Example
reset_queryReset/rewind a running query so that it starts from the beginning again. The next call to run_query will then return the first chunk of result entries.
Params
The qh param is as returned from a call to start_query.
Result
Example
stop_queryStops the running query identified by query handler. If a query is not explicitly closed using this call, it will be cleaned up when the transaction the query is linked to ends.
Params
The qh param is as returned from a call to start_query.
Result
Example
lock_dbTakes a database lock.
Params
The db param specifies which datastore to lock.
Result
Errors (specific)
The `data.sessions` param is an array of strings describing the current sessions of the locking user, e.g., an array of "admin tcp (cli from 192.245.2.3) on since 2006-12-20 14:50:30 exclusive".
cometListens on a comet channel, i.e. all asynchronous messages from batch commands started by calls to start_cmd, subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf, or subscribe_upgrade ends up on the comet channel.
You are expected to have a continuous long polling call to the comet method at any given time. As soon as the browser or server closes the socket, due to browser or server connect timeout, the comet method should be called again.
As soon as the comet method returns with values they should be dispatched and the comet method should be called again.
Params
Result
Errors (specific)
Example
Hangs, and finally:
In this case, the admin user seems to have set `/dhcp:dhcp/default-lease-time` to 100.
get_system_settingExtracts system settings such as capabilities, supported datastores, etc.
Params
The operation param specifies which system setting to get:
capabilities - the server-side settings are returned, e.g. is rollback and confirmed commit supported.
customizations - an array of all WebUI customizations.
models - an array of all loaded YANG modules are returned, i.e. prefix, namespace, name.
user - the username of the currently logged in user is returned.
version - the system version.
all - all of the above is returned.
(DEPRECATED) namespaces - an object of all loaded YANG modules are returned, i.e. prefix to namespace.
Result
The above is the result if using the all operation.
abortAbort a JSON-RPC method by its associated ID.
Params
The id param is the id of the JSON-RPC method to be aborted.
Result
eval_XPathEvaluates an xpath expression on the server side.
Params
The xpath_expr param is the XPath expression to be evaluated.
Result
send_messageSends a message to another user in the CLI or Web UI.
Params
The to param is the user name of the user to send the message to and the message param is the actual message.
Note: The username all will broadcast the message to all users.
Result
subscribe_messagesStarts a subscriber to messages.
Note: The start_subscription method must be called to actually get the subscription to generate any messages unless the handle is provided as input.
Note: The unsubscribe method should be used to end the subscription.
Note: As soon as a subscription message is generated, it will be sent as a message and turn up as a result to your polling call to the comet method.
Params
Result
A handle to the subscription is returned (equal to handle if provided).
Subscription messages will end up in the comet method and the format of these messages depend on what has happened.
When a new user has logged in:
When a user logs out:
When receiving a message:
get_rollbacksLists all available rollback files.
Result
The nr param is a rollback number to be used in calls to load_rollback etc.
The creator and date properties identify the name of the user responsible for committing the configuration stored in the rollback file and when it happened.
The via param identifies the interface that was used to create the rollback file.
The label and comment properties is as given calling the methods set_comment and set_label on the transaction.
get_rollbackGets the content of a specific rollback file. The rollback format is as defined in a curly bracket format as defined in the CLI.
Params
Result
install_rollbackInstalls a specific rollback file into a new transaction and commits it. The configuration is restored to the one stored in the rollback file and no further operations are needed. It is the equivalent of creating a new private write private transaction handler with new_write_trans, followed by calls to the methods load_rollback, validate_commit and commit.
Params
Result
load_rollbackRolls back within an existing transaction, starting with the latest rollback file, down to a specified rollback file, or selecting only the specified rollback file (also known as "selective rollback").
Params
The nr param is a rollback number returned by get_rollbacks.
The path param is a keypath that restricts the rollback to be applied only to a subtree.
The selective param, false by default, can restrict the rollback process to use only the rollback specified by nr, rather than applying all known rollback files starting with the latest down to the one specified by nr.
Result
get_descriptionGet description. To be able to get the description in the response, the fxs file needs to be compiled with the flag --include-doc. This operation can be heavy so instead of calling get_description directly, we can confirm that there is a description before calling in CS_HAS_DESCR flag that we get from get_schema response.
Params
A path is a tagpath/keypath pointing into a specific sub-tree of a YANG module.
Result
get_schemaExports a JSON schema for a selected part (or all) of a specific YANG module (with optional instance data inserted).
Params
One of the properties namespace or path must be specified.
A namespace is as specified in a YANG module.
A path is a tagpath/keypath pointing into a specific sub-tree of a YANG module.
The levels param limits the maximum depth of containers and lists from which a JSON schema should be produced (-1 means unlimited depth).
The insert_values param signals that instance data for leafs should be inserted into the schema. This way the need for explicit forthcoming calls to get_elem are avoided.
The evaluate_when_entries param signals that schema entries should be included in the schema even though their when or tailf:display-when statements evaluate to false, i.e. instead a boolean evaluated_when_entry param is added to these schema entries.
The stop_on_list param limits the schema generation to one level under the list when true.
The cdm_namespace param signals the inclusion of cdm-namespace entries where appropriate.
Result
This is a fairly complex piece of JSON but it essentially maps what is seen in a YANG module. Keep that in mind when scrutinizing the above.
The meta param contains meta-information about the YANG module such as namespace and prefix but it also contains type stack information for each type used in the YANG module represented in the data param. Together with the meta param, the data param constitutes a complete YANG module in JSON format.
Example
hide_schemaHides data that has been adorned with a hidden statement in YANG modules. hidden statement is an extension defined in the tail-common YANG module (http://tail-f.com/yang/common).
Params
The group_name param is as defined by a hidden statement in a YANG module.
Result
unhide_schemaUnhides data that has been adorned with a hidden statement in the YANG modules. hidden statement is an extension defined in the tail-common YANG module (http://tail-f.com/yang/common).
Params
The group_name param is as defined by a hidden statement in a YANG module.
The passwd param is a password needed to hide the data that has been adorned with a hidden statement. The password is as defined in the ncs.conf file.
Result
get_module_prefix_mapReturns a map from module name to module prefix.
Params
Method takes no parameters.
Result
Example
run_actionInvokes an action or RPC defined in a YANG module.
Params
Actions are as specified in the YANG module, i.e. having a specific name and a well-defined set of parameters and result. The path param is a keypath pointing to an action or RPC in and the params param is a JSON object with action parameters.
The format param defines if the result should be an array of key values or a pre-formatted string on bracket format as seen in the CLI. The result is also as specified by the YANG module.
Both a comet_id and handle need to be provided in order to receive notifications.
The details param can be given together with comet_id and handle in order to get a progress trace for the action. details specifies the verbosity of the progress trace. After the action has been invoked, the comet method can be used to get the progress trace for the action. If the details param is omitted progress trace will be disabled.
Note: This method is often used to call an action that uploads binary data (e.g. images) and retrieving them at a later time. While retrieval is not a problem, uploading is a problem, because JSON-RPC request payloads have a size limitation (e.g. 64 kB). The limitation is needed for performance concerns because the payload is first buffered before the JSON string is parsed and the request is evaluated. When you have scenarios that need binary uploads, please use the CGI functionality instead which has a size limitation that can be configured, and which is not limited to JSON payloads, so one can use streaming techniques.
Result
Errors (specific)
Example
loginCreates a user session and sets a browser cookie.
Params
There are two versions of the login method. The method with no parameters only invokes Package Authentication, since credentials can be supplied with the whole HTTP request. The method with parameters is used when credentials may need to be supplied with the method parameters, this method invokes all authentication methods including Package Authentication.
The user and passwd are the credentials to be used in order to create a user session. The common AAA engine in NSO is used to verify the credentials.
If the method fails with a warning, the warning needs to be displayed to the user, along with a checkbox to allow the user to acknowledge the warning. The acknowledgment of the warning translates to setting ack_warning to true.
Result
Note: The response will have a `Set-Cookie` HTTP header with a sessionid cookie which will be your authentication token for upcoming JSON-RPC requests.
The warning is a free-text string that should be displayed to the user after a successful login. This is not to be mistaken with a failed login that has a warning as well. In case of a failure, the user should also acknowledge the warning, not just have it displayed for optional reading.
Multi-factor authentication
Note: A challenge response will have a challenge_id and challenge_prompt which needs to be responded to with an upcoming JSON-RPC challenge_response requests.
Note: The challenge_prompt may be a multi-line, why it is base64 encoded.
Example
Note: sessionid cookie is set at this point in your User Agent (browser). In our examples, we set the cookie explicitly in the upcoming requests for clarity.
challenge_responseCreates a user session and sets a browser cookie.
Params
The challenge_id and response is the multi-factor response to be used in order to create a user session. The common AAA engine in NSO is used to verify the response.
If the method fails with a warning, the warning needs to be displayed to the user, along with a checkbox to allow the user to acknowledge the warning. The acknowledgment of the warning translates to setting ack_warning to true.
Result
Note: The response will have a `Set-Cookie` HTTP header with a sessionid cookie which will be your authentication token for upcoming JSON-RPC requests.
The warning is a free-text string that should be displayed to the user after a successful challenge response. This is not to be mistaken with a failed challenge response that has a warning as well. In case of a failure, the user should also acknowledge the warning, not just have it displayed for optional reading.
Example
Note: sessionid cookie is set at this point in your User Agent (browser). In our examples, we set the cookie explicitly in the upcoming requests for clarity.
logoutRemoves a user session and invalidates the browser cookie.
The HTTP cookie identifies the user session so no input parameters are needed.
Params
None.
Result
Example
kick_userKills a user session, i.e. kicking out the user.
Params
The user param is either the username of a logged-in user or session ID.
Result
get_session_dataGets session data from the session store.
Params
The key param for which to get the stored data for. Read more about the session store in the put_session_data method.
Result
put_session_dataPuts session data into the session store. The session store is a small key-value server-side database where data can be stored under a unique key. The data may be an arbitrary object, but not a function object. The object is serialized into a JSON string and then stored on the server.
Params
The key param is the unique key for which the data in the value param is to be stored.
Result
erase_session_dataErases session data previously stored with put_session_data.
Params
The key param for which all session data will be erased. Read more about the session store in the put_session_data method.
Result
new_transCreates a new transaction.
Params
The conf_mode param specifies which transaction semantics to use when it comes to lock and commit strategies. These three modes mimic the modes available in the CLI.
The meaning of private, shared and exclusive have slightly different meaning depending on how the system is configured; with a writable running, startup, or candidate configuration.
private (*writable running enabled*) - Edit a private copy of the running configuration, no lock is taken.
private (*writable running disabled, startup enabled*) - Edit a private copy of the startup configuration, no lock is taken.
exclusive (*candidate enabled*) - Lock the running configuration and the candidate configuration and edit the candidate configuration.
exclusive (*candidate disabled, startup enabled*) - Lock the running configuration (if enabled) and the startup configuration and edit the startup configuration.
shared (*writable running enabled, candidate enabled*) - Is a deprecated setting.
The tag param is a way to tag transactions with a keyword so that they can be filtered out when you call the get_trans method.
The action_path param is a keypath pointing to an action or RPC. Use action_path when you need to read action/rpc input parameters.
The th param is a way to create transactions within other read_write transactions.
The on_pending_changes param decides what to do if the candidate already has been written to, e.g. a CLI user has started a shared configuration session and changed a value in the configuration (without committing it). If this parameter is omitted, the default behavior is to silently reuse the candidate. If reject is specified, the call to the new_trans method will fail if the candidate is non-empty. If discard is specified, the candidate is silently cleared if it is non-empty.
Result
A new transaction handler ID.
Errors (specific)
The `data.sessions` param is an array of strings describing the current sessions of the locking user, e.g. an array of "admin tcp (cli from 192.245.2.3) on since 2006-12-20 14:50:30 exclusive".
Example
set_trans_commentAdds a comment to the active read-write transaction. This comment will be stored in rollback files and can be seen with a call to get_rollbacks.
Params
Result
set_trans_labelAdds a label to the active read-write transaction. This label will be stored in rollback files and can be seen with a call to get_rollbacks.
Params
Result
get_trans_changesExtracts modifications done to a transaction.
Params
The output parameter controls the result content. legacy format include old and value for all operation types even if their value is undefined. undefined values are represented by an empty string. compact format excludes old and value if their value is undefined.
Result
The value param is only interesting if op is set to one of modified or value_set.
The old param is only interesting if op is set to modified.
Example
validate_transValidates a transaction.
Params
Result
Or:
Errors (specific)
The data.users param is an array of conflicting usernames.
The data.errors param points to a keypath that is invalid.
get_trans_conflictsGets the conflicts registered in a transaction.
Params
Result
The value param is only interesting if op is set to one of created, modified or value_set.
The old param is only interesting if op is set to modified.
validate_commitValidates a transaction before calling commit. If this method succeeds (with or without warnings) then the next operation must be a call to either commit or clear_validate_lock. The configuration will be locked for access by other users until one of these methods is called.
Params
The comet_id, handle, and details params can be given together in order to get progress tracing for the validate_commit operation. The same comet_id can also be used to get the progress trace for any coming commit operations. In order to get progress tracing for commit operations, these three parameters have to be provided with the validate_commit operation. The details parameter specifies the verbosity of the progress trace. After the operation has been invoked, the comet method can be used to get the progress trace for the operation.
See the commit method for available flags.
Note: If you intend to pass flags to the commit method, it is recommended to pass the same flags to validate_commit since they may have an effect during the validate step.
Result
Or:
Errors (specific)
Same as for the validate_trans method.
commitCopies the configuration into the running datastore.
Params
The commit with a timeout parameter represents a confirmed commit.
If rollback-id is set to true, the response will include the ID of the rollback file created during the commit if any.
Commit behavior can be changed via an extra flags param:
The flags param is a list of flags that can change the commit behavior:
dry-run=FORMAT - Where FORMAT is the desired output format: xml, cli, or native. Validate and display the configuration changes but do not perform the actual commit. Neither CDB nor the devices are affected. Instead, the effects that would have taken place is shown in the returned output.
dry-run-reverse - Used with the dry-run=native flag this will display the device commands for getting back to the current running state in the network if the commit is successfully executed. Beware that if any changes are done later on the same data the reverse device commands returned are invalid.
no-revision-drop - NSO will not run its data model revision algorithm, which requires all participating managed devices to have all parts of the data models for all data contained in this transaction. Thus, this flag forces NSO to never silently drop any data set operations towards a device.
no-overwrite - NSO will check that the data that should be modified has not changed on the device compared to NSO's view of the data. Can't be used with no-out-of-sync-check.
no-networking - Do not send data to the devices; this is a way to manipulate CDB in NSO without generating any southbound traffic.
no-out-of-sync-check - Continue with the transaction even if NSO detects that a device's configuration is out of sync. It can't be used with no-overwrite.
no-deploy - Commit without invoking the service create method, i.e., write the service instance data without activating the service(s). The service(s) can later be redeployed to write the changes of the service(s) to the network.
reconcile=OPTION - Reconcile the service data. All data which existed before the service was created will now be owned by the service. When the service is removed that data will also be removed. In technical terms, the reference count will be decreased by one for everything that existed prior to the service. If manually configured data exists below in the configuration tree, that data is kept unless the option discard-non-service-config is used.
use-lsa - Force handling of the LSA nodes as such. This flag tells NSO to propagate applicable commit flags and actions to the LSA nodes without applying them on the upper NSO node itself. The commit flags affected are dry-run, no-networking, no-out-of-sync-check, no-overwrite and no-revision-drop.
no-lsa - Do not handle any of the LSA nodes as such. These nodes will be handled as any other device.
commit-queue=MODE - Where MODE is: async, sync, or bypass. Commit the transaction data to the commit queue.
If the async value is set, the operation returns successfully if the transaction data has been successfully placed in the queue.
The sync value will cause the operation to not return until the transaction data has been sent to all devices, or a timeout occurs.
The bypass value means that if /devices/global-settings/commit-queue/enabled-by-default is true, the data in this transaction will bypass the commit queue. The data will be written directly to the devices.
commit-queue-atomic=ATOMIC - Where ATOMIC is: true or false. Sets the atomic behavior of the resulting queue item. If ATOMIC is set to false, the devices contained in the resulting queue item can start executing if the same devices in other non-atomic queue items ahead of it in the queue are completed. If set to true, the atomic integrity of the queue item is preserved.
commit-queue-block-others - The resulting queue item will block subsequent queue items, that use any of the devices in this queue item, from being queued.
commit-queue-lock - Place a lock on the resulting queue item. The queue item will not be processed until it has been unlocked, see the actions unlock and lock in /devices/commit-queue/queue-item. No following queue items, using the same devices, will be allowed to execute as long as the lock is in place.
commit-queue-tag=TAG - Where TAG is a user-defined opaque tag. The tag is present in all notifications and events sent referencing the specific queue item.
commit-queue-timeout=TIMEOUT - Where TIMEOUT is infinity or a positive integer. Specifies a maximum number of seconds to wait for the transaction to be committed. If the timer expires, the transaction data is kept in the commit queue, and the operation returns successfully. If the timeout is not set, the operation waits until completion indefinitely.
commit-queue-error-option=OPTION - Where OPTION is: continue-on-error, rollback-on-error or stop-on-error. Depending on the selected error option NSO will store the reverse of the original transaction to be able to undo the transaction changes and get back to the previous state. This data is stored in the /devices/commit-queue/completed tree from where it can be viewed and invoked with the rollback action. When invoked, the data will be removed.
The continue-on-error value means that the commit queue will continue on errors. No rollback data will be created.
The rollback-on-error value means that the commit queue item will roll back on errors. The commit queue will place a lock with block-others on the devices and services in the failed queue item. The rollback action will then automatically be invoked when the queue item has finished its execution. The lock is removed as part of the rollback.
The stop-on-error means that the commit queue will place a lock with block-others on the devices and services in the failed queue item. The lock must then either manually be released when the error is fixed or the rollback action under /devices/commit-queue/completed be invoked.
trace-id=TRACE_ID - Use the provided trace ID as part of the log messages emitted while processing. If no trace ID is given, NSO is going to generate and assign a trace ID to the processing.
For backward compatibility, the flags param can also be a bit mask with the following limit values:
`1 << 0` - Do not release locks, overridden by the release_locks if set.
`1 << 2` - Do not drop revision.
If a call to confirm_commit is not done within timeout seconds an automatic rollback is performed. This method can also be used to "extend" a confirmed commit that is already in progress, i.e. set a new timeout or add changes.
A call to abort_commit can be made to abort the confirmed commit.
Note: Must be preceded by a call to validate_commit.
Note: The transaction handler is deallocated as a side effect of this method.
Result
Successful commit without any arguments.
Successful commit with rollback-id=true:
Successful commit with commit-queue=async:
The commit_queue_id is returned if the commit entered the commit queue, either by specifying commit-queue=async or by enabling it in the configuration.
Errors (specific)
new_webui_transCreates a read-write transaction that can be retrieved by get_webui_trans.
Params
See new_trans for the semantics of the parameters and specific errors.
The on_pending_changes param decides what to do if the candidate already has been written to, e.g. a CLI user has started a shared configuration session and changed a value in the configuration (without committing it). If this parameter is omitted, the default behavior is to silently reuse the candidate. If reject is specified, the call to the new_webui_trans method will fail if the candidate is non-empty. If discard is specified, the candidate is silently cleared if it is non-empty.
Result
A new transaction handler ID.
get_template_variablesExtracts all variables from an NSO service/device template.
Params
The name param is the name of the template to extract variables from.
Result
list_packagesLists packages in NSO.
Params
The status param specifies which package status to list:
installable - an array of all packages that can be installed.
installed - an array of all packages that are installed, but not loaded.
loaded - an array of all loaded packages.
all - all of the above is returned.
Result
JSON-RPC runs on top of the embedded web server (see ), which accepts HTTP and/or HTTPS.
When used in a browser, the JSON-RPC API does not accept cross-domain requests by default but can be configured to do so via the custom headers functionality in the embedded web server, or by adding a reverse proxy (see ).
You can read more about the command rules in .
Note: If the permission to delete is denied on a child, the 'warnings' array in the result will contain a warning 'Some elements could not be removed due to NACM rules prohibiting access.'. The delete method will still delete as much as is allowed by the rules. See for more information about permissions and authorization.
Note: If this method is used for deletion and permission to delete is denied on a child, the 'warnings' array in the result will contain a warning ''Some elements could not be removed due to NACM rules prohibiting access.'. The delete will still delete as much as is allowed by the rules. See for more information about permissions and authorization.
Retrieves the result to a query (as chunks). For more details on queries, read the description of .
Note: If the permission to rollback is denied on some nodes, the 'warnings' array in the result will contain a warning 'Some changes could not be applied due to NACM rules prohibiting access.'. The install_rollback will still rollback as much as is allowed by the rules. See for more information about permissions and authorization.
Note: If the permission to rollback is denied on some nodes, the 'warnings' array in the result will contain a warning 'Some changes could not be applied due to NACM rules prohibiting access.'. The load_rollback will still rollback as much as is allowed by the rules. See for more information about permissions and authorization.
Note: Read about error recovery in for a more detailed explanation.
{}{"th": <integer>,
"path": <string>}{}{"type": "db.locked"}{"th": <integer>,
"path": <string>}{} |
{"warnings": <array of strings>}{"type": "db.locked"}{"th": <integer>,
"path": <string>}{"exists": <boolean>}{"th": <integer>,
"path": <string>,
"choice": <string>}{"case": <string>}{"th": <integer>,
"path": <string>
"result_as": <"string" | "json" | "json2", default: "string">
"with_oper": <boolean, default: false>
"max_size": <"integer", default: 0>}{"config": <string>}{"data": <json>}{"th": <integer>,
"data": <string>
"path": <string, default: "/">
"format": <"json" | "xml", default: "xml">
"mode": <"create" | "merge" | "replace", default: "merge">}{}{"row": <integer>, "message": <string>}{"th": <integer>,
"path": <string>,
"names": <array of string>}{"attrs": <object of attribute name/value>}{"th": <integer>,
"path": <string>,
"attrs": <object of attribute name/value>}{}{"th": <integer>,
"path": <string>,
"check_default": <boolean, default: false>}{"value": <string>}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "get_value",
"params": {"th": 4711,
"path": "/dhcp:dhcp/max-lease-time"}}' \
http://127.0.0.1:8008/jsonrpc
{
"jsonrpc": "2.0",
"id": 1,
"result": {"value": "7200"}
}{"th": <integer>,
"path": <string>,
"check_default": <boolean, default: false>,
"leafs": <array of string>}{"values": <array of value/error>}
value = {"value": <string>, "access": <access>}
error = {"error": <string>, "access": <access>} |
{"exists": true, "access": <access>} |
{"not_found": true, "access": <access>}
access = {"read": true, write: true}{"th": <integer>,
"path": <string>,
"value": <string | boolean | integer | array | null>,
"dryrun": <boolean, default: false}{} |
{"warnings": <array of strings>}{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}
{"type": "db.locked"}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "set_value",
"params": {"th": 4711,
"path": "/dhcp:dhcp/max-lease-time",
"value": "4500"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {}
}{"th": <integer>,
"path": <string>,
"result_as": <"paths" | "target" | "list-target", default: "paths">}{"paths": <array of string, a keypath to a leaf>}{"target": <a keypath to a leaf>}{"list-target": <a keypath to a list>}{"th": <integer>,
"path": <string>,
"offset": <integer, default: 0>,
"limit": <integer, default: -1>,
"starts_with": <string, optional>,
"skip_grouping": <boolean, default: false>,
"keys": <object>} rpc create-service {
tailf:exec "./run.sh";
input {
leaf name {
type leafref {
path "/myservices/service/name";
}
}
leaf if {
type leafref {
path "/myservices/service[name=current()/../name]/interfaces/name"
}
}
}
output {
leaf result { type string; }
}
}{"/create-service/name": "service1"}{"values": <array of string>,
"source": <string> | false}{"th": <integer>,
"from_path": <string>,
"to_keys": <array of string>}{}{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}{"th": <integer>,
"from_path": <string>,
"to_keys": <array of string>}{}{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}{"th": <integer>,
"from_path": <string>,
"to_path": <string>,
"mode": <"first" | "last" | "before" | "after">}{}{"type": "db.locked"}{"th": <integer>,
"path": <string>,
"value": <string>}{}{"th": <integer>
"path": <string>}{"count": <integer>}{"th": <integer>,
"path": <string>,
"chunk_size": <integer greater than zero, optional>,
"start_with": <array of string, optional>,
"lh": <integer, optional>}{"keys": <array of array of string>,
"total_count": <integer>,
"lh": <integer, optional>}curl \
--cookie "sessionid=sess11635875109111642;" \
-X POST \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "query",
"params": {"th": 1,
"xpath_expr": "/dhcp:dhcp/dhcp:foo",
"result_as": "keypath-value"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result":
{"current_position": 2,
"total_number_of_results": 4,
"number_of_results": 2,
"number_of_elements_per_result": 2,
"results": ["foo", "bar"]}}{"th": <integer>,
"xpath_expr": <string, optional if path is given>,
"path": <string, keypath, optional if xpath_expr is given>,
"selection": <array of xpath expressions, optional>
"chunk_size": <integer greater than zero, optional>
"initial_offset": <integer, optional>,
"sort", <array of xpath expressions, optional>,
"sort_order": <"ascending" | "descending", optional>,
"include_total": <boolean, default: true>,
"context_node": <string, keypath, optional>,
"result_as": <"string" | "keypath-value" | "leaf_value_as_string", default: "string">}list interface {
key name;
unique number;
leaf name {
type string;
}
leaf number {
type uint32;
mandatory true;
}
leaf enabled {
type boolean;
default true;
}
}$.post("/jsonrpc", {
jsonrpc: "2.0",
id: 1,
method: "start_query",
params: {
th: 1,
xpath_expr: "/interface[enabled='true']",
selection: ["name", "number", "enabled"],
sort: ["enabled", "number"]
}
})
.done(...);{"qh": <integer>}curl \
--cookie "sessionid=sess11635875109111642;" \
-X POST \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "start_query",
"params": {"th": 1,
"xpath_expr": "/dhcp:dhcp/dhcp:foo",
"result_as": "keypath-value"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": 47}{"qh": <integer>}{"position": <integer>,
"total_number_of_results": <integer>,
"number_of_results": <integer>,
"chunk_size": <integer greater than zero, optional>,
"result_as": <"string" | "keypath-value" | "leaf_value_as_string">,
"results": <array of result>}
result = <string> |
{"keypath": <string>, "value": <string>}curl \
--cookie "sessionid=sess11635875109111642;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "run_query",
"params": {"qh": 22}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result":
{"current_position": 2,
"total_number_of_results": 4,
"number_of_results": 2,
"number_of_elements_per_result": 2,
"results": ["foo", "bar"]}}{"qh": <integer>}{}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "reset_query",
"params": {"qh": 67}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": true}{"qh": <integer>}{}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "stop_query",
"params": {"qh": 67}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": true}{}{"db": <"startup" | "running" | "candidate">}{}{"type": "db.locked", "data": {"sessions": <array of string>}}{"db": <"startup" | "running" | "candidate">}{}{}{"comet_id": <string>}[{"handle": <integer>,
"message": <a context specific json object, see example below>},
...]{"type": "comet.duplicated_channel"}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "subscribe_changes",
"params": {"comet_id": "main",
"path": "/dhcp:dhcp"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {"handle": "2"}}
curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "batch_init_done",
"params": {"handle": "2"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {}}
curl \
-m 15 \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "comet",
"params": {"comet_id": "main"}}' \
http://127.0.0.1:8008/jsonrpc{"jsonrpc": "2.0",
"id": 1,
"result":
[{"handle": "1",
"message":
{"db": "running",
"changes":
[{"keypath": "/dhcp:dhcp/default-lease-time",
"op": "value_set",
"value": "100"}],
"user": "admin",
"ip": "127.0.0.1"}}]}{"operation": <"capabilities" | "customizations" | "models" | "user" | "version" | "all" | "namespaces", default: "all">}{"user:" <string>,
"models:" <array of YANG modules>,
"version:" <string>,
"customizations": <array of customizations>,
"capabilities":
{"rollback": <boolean>,
"copy_running_to_startup": <boolean>,
"exclusive": <boolean>,
"confirmed_commit": <boolean>
},
"namespaces": <object of YANG modules prefix/namespace>}{"id": <integer>}{}{"th": <integer>,
"xpath_expr": <string>}{"value": <string>}{"to": <string>,
"message": <string>}{}{"comet_id": <string>,
"handle": <string, optional>}<string>{"new_user": <integer, a session id to be used by "kick_user">
"me": <boolean, is it myself?>
"user": <string>,
"proto": <"ssh" | "tcp" | "console" | "http" | "https" | "system">,
"ctx": <"cli" | "webui" | "netconf">
"ip": <string, user's ip-address>,
"login": <string, login timestamp>}{"del_user": <integer, a session id>,
"user": <string>}{"sender": <string>,
"message": <string>}{"rollbacks": <array of rollback>}
rollback =
{"nr": <integer>,
"creator": <string>,
"date": <string>,
"via": <"system" | "cli" | "webui" | "netconf">,
"comment": <string>,
"label": <string>}{"nr": <integer>}<string, rollback file in curly bracket format>{"nr": <integer>}{}{"th": <integer>,
"nr": <integer>,
"path": <string>,
"selective": <boolean, default: false>}{}{"th": <integer>,
"path": <string, optional>{"description": <string>}{"th": <integer>,
"namespace": <string, optional>,
"path": <string, optional>,
"levels": <integer, default: -1>,
"insert_values": <boolean, default: false>,
"evaluate_when_entries": <boolean, default: false>,
"stop_on_list": <boolean, default: false>,
"cdm_namespace": <boolean, default: false>}{"meta":
{"namespace": <string, optional>,
"keypath": <string, optional>,
"prefix": <string>,
"types": <array of type>},
"data": <array of child>}
type = <array of {<string, type name with prefix>: <type_stack>}>
type_stack = <array of type_stack_entry>
type_stack_entry =
{"bits": <array of string>, "size": <32 | 64>} |
{"leaf_type": <type_stack>, "list_type": <type_stack>} |
{"union": <array of type_stack>} |
{"name": <primitive_type | "user_defined">,
"info": <string, optional>,
"readonly": <boolean, optional>,
"facets": <array of facet, only if not primitive type>}
primitive_type =
"empty" |
"binary" |
"bits" |
"date-and-time" |
"instance-identifier" |
"int64" |
"int32" |
"int16" |
"uint64" |
"uint32" |
"uint16" |
"uint8" |
"ip-prefix" |
"ipv4-prefix" |
"ipv6-prefix" |
"ip-address-and-prefix-length" |
"ipv4-address-and-prefix-length" |
"ipv6-address-and-prefix-length" |
"hex-string" |
"dotted-quad" |
"ip-address" |
"ipv4-address" |
"ipv6-address" |
"gauge32" |
"counter32" |
"counter64" |
"object-identifier"
facet_entry =
{"enumeration": {"label": <string>, "info": <string, optional>}} |
{"fraction-digits": {"value": <integer>}} |
{"length": {"value": <integer>}} |
{"max-length": {"value": <integer>}} |
{"min-length": {"value": <integer>}} |
{"leaf-list": <boolean>} |
{"max-inclusive": {"value": <integer>}} |
{"max-length": {"value": <integer>}} |
{"range": {"value": <array of range_entry>}} |
{"min-exclusive": {"value": <integer>}} |
{"min-inclusive": {"value": <integer>}} |
{"min-length": {"value": <integer>}} |
{"pattern": {"value": <string, regular expression>}} |
{"total-digits": {"value": <integer>}}
range_entry =
"min" |
"max" |
<integer> |
[<integer, min value>, <integer, max value>]
child =
{"kind": <kind>,
"name": <string>,
"qname": <string, same as "name" but with prefix prepended>,
"info": <string>,
"namespace": <string>,
"xml-namespace": <string>,
"is_action_input": <boolean>,
"is_action_output": <boolean>,
"is_cli_preformatted": <boolean>,
"is_mount_point": <boolean>
"presence": <boolean>,
"ordered_by": <boolean>,
"is_config_false_callpoint": <boolean>,
"key": <boolean>,
"exists": <boolean>,
"value": <string | number | boolean>,
"is_leafref": <boolean>,
"leafref_target": <string>,
"when_targets": <array of string>,
"deps": <array of string>
"hidden": <boolean>,
"default_ref":
{"namespace": <string>,
"tagpath": <string>
},
"access":
{"create": <boolean>,
"update": <boolean>,
"delete": <boolean>,
"execute": <boolean>
},
"config": <boolean>,
"readonly": <boolean>,
"suppress_echo": <boolean>,
"type":
{"name": <primitive_type>,
"primitive": <boolean>
}
"generated_name": <string>,
"units": <string>,
"leafref_groups": <array of string>,
"active": <string, active case, only if "kind" is "choice">,
"cases": <array of case, only of "kind" is "choice">,
"default": <string | number | boolean>,
"mandatory": <boolean>,
"children": <children>
}
kind =
"module" |
"access-denies" |
"list-entry" |
"choice" |
"key" |
"leaf-list" |
"action" |
"container" |
"leaf" |
"list" |
"notification"
case_entry =
{"kind": "case",
"name": <string>,
"children": <array of child>
}curl \
--cookie "sessionid=sess11635875109111642;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "get_schema",
"params": {"th": 2,
"path": "/aaa:aaa/authentication/users/user{admin}",
"levels": -1,
"insert_values": true}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result":
{"meta":
{"namespace": "http://tail-f.com/ns/aaa/1.1",
"keypath": "/aaa:aaa/authentication/users/user{admin}",
"prefix": "aaa",
"types":
{"http://tail-f.com/ns/aaa/1.1:passwdStr":
[{"name": "http://tail-f.com/ns/aaa/1.1:passwdStr"},
{"name": "MD5DigestString"}]}}},
"data":
{"kind": "list-entry",
"name": "user",
"qname": "aaa:user",
"access":
{"create": true,
"update": true,
"delete": true},
"children":
[{"kind": "key",
"name": "name",
"qname": "aaa:name",
"info": {"string": "Login name of the user"},
"mandatory": true,
"access": {"update": true},
"type": {"name": "string", "primitive": true}},
...]}}{"th": <integer>,
"group_name": <string>{}{"th": <integer>,
"group_name": <string>,
"passwd": <string>}{}<key-value object>
result = {"module-name": "module-prefix"}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", id: 1,
"method": "get_module_prefix_map",
"params": {}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {
"cli-builtin": "cli-builtin",
"confd_cfg": "confd_cfg",
"iana-crypt-hash": "ianach",
"ietf-inet-types": "inet",
"ietf-netconf": "nc",
"ietf-netconf-acm": "nacm",
"ietf-netconf-monitoring": "ncm",
"ietf-netconf-notifications": "ncn",
"ietf-netconf-with-defaults": "ncwd",
"ietf-restconf": "rc",
"ietf-restconf-monitoring": "rcmon",
"ietf-yang-library": "yanglib",
"ietf-yang-types": "yang",
"tailf-aaa": "aaa",
"tailf-acm": "tacm",
"tailf-common-monitoring2": "tfcg2",
"tailf-confd-monitoring": "tfcm",
"tailf-confd-monitoring2": "tfcm2",
"tailf-kicker": "kicker",
"tailf-netconf-extensions": "tfnce",
"tailf-netconf-monitoring": "tncm",
"tailf-netconf-query": "tfncq",
"tailf-rest-error": "tfrerr",
"tailf-rest-query": "tfrestq",
"tailf-rollback": "rollback",
"tailf-webui": "webui",
}
}{"th": <integer>,
"path": <string>,
"params": <json, optional>
"format": <"normal" | "bracket" | "json", default: "normal">,
"comet_id": <string, optional>,
"handle": <string, optional>,
"details": <"normal" | "verbose" | "very_verbose" | "debug", optional>}<string | array of result | key-value object>
result = {"name": <string>, "value": <string>}{"type": "action.invalid_result", "data": {"path": <string, path to invalid result>}}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", id: 1,
"method": "run_action",
"params": {"th": 2,
"path": "/dhcp:dhcp/set-clock",
"params": {"clockSettings": "2014-02-11T14:20:53.460%2B01:00"}}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": [{"name":"systemClock", "value":"0000-00-00T03:00:00+00:00"},
{"name":"inlineContainer/bar", "value":"false"},
{"name":"hardwareClock","value":"0000-00-00T04:00:00+00:00"}]}
curl \
-s \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d'{"jsonrpc": "2.0", "id": 1,
"method": "run_action",
"params": {"th": 2,
"path": "/dhcp:dhcp/set-clock",
"params": {"clockSettings":
"2014-02-11T14:20:53.460%2B01:00"},
"format": "bracket"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": "systemClock 0000-00-00T03:00:00+00:00\ninlineContainer {\n \
bar false\n}\nhardwareClock 0000-00-00T04:00:00+00:00\n"}
curl \
-s \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d'{"jsonrpc": "2.0", "id": 1,
"method": "run_action",
"params": {"th": 2,
"path": "/dhcp:dhcp/set-clock",
"params": {"clockSettings":
"2014-02-11T14:20:53.460%2B01:00"},
"format": "json"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {"systemClock": "0000-00-00T03:00:00+00:00",
"inlineContainer": {"bar": false},
"hardwareClock": "0000-00-00T04:00:00+00:00"}}{}{"user": <string>, "passwd": <string>, "ack_warning": <boolean, default: false>}{"warning": <string, optional>}{"challenge_id": <string>, "challenge_prompt": <string>}curl \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "login",
"params": {"user": "joe",
"passwd": "SWkkasE32"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32000,
"type": "rpc.method.failed",
"message": "Method failed"}}
curl \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "login",
"params": {"user": "admin",
"passwd": "admin"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {}}curl \
--cookie "sessionid=sess4245223558720207078;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "get_trans"}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {"trans": []}}{"challenge_id": <string>, "response": <string>, "ack_warning": <boolean, default: false>}{"warning": <string, optional>}curl \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "challenge_response",
"params": {"challenge_id": "123",
"response": "SWkkasE32"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32000,
"type": "rpc.method.failed",
"message": "Method failed"}}
curl \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "challenge_response",
"params": {"challenge_id": "123",
"response": "SWEddrk1"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {}}curl \
--cookie "sessionid=sess4245223558720207078;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "get_trans"}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {"trans": []}}{}curl \
--cookie "sessionid=sess4245223558720207078;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "logout"}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": {}}
curl \
--cookie "sessionid=sess4245223558720207078;" \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "logout"}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32000,
"type": "session.invalid_sessionid",
"message": "Invalid sessionid"}}{"user": <string | number>}{}{"key": <string>}{"value": <string>}{"key": <string>,
"value": <string>}{}{"key": <string>}{}{"trans": <array of transaction>}
transaction =
{"db": <"running" | "startup" | "candidate">,
"mode": <"read" | "read_write", default: "read">,
"conf_mode": <"private" | "shared" | "exclusive", default: "private">,
"tag": <string>,
"th": <integer>}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "get_trans"}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result":
{"trans":
[{"db": "running",
"th": 2}]}}{"db": <"startup" | "running" | "candidate", default: "running">,
"mode": <"read" | "read_write", default: "read">,
"conf_mode": <"private" | "shared" | "exclusive", default: "private">,
"tag": <string>,
"action_path": <string>,
"th": <integer>,
"on_pending_changes": <"reuse" | "reject" | "discard", default: "reuse">}{"th": <integer>}{"type": "trans.confirmed_commit_in_progress"}
{"type": "db.locked", "data": {"sessions": <array of string>}}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "new_trans",
"params": {"db": "running",
"mode": "read"}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result": 2}{"th": <integer>}{}{"th": <integer>}{}{"th": <integer>}{}{"th": <integer>}{"modified": <boolean>}{"th": <integer>},
"output": <"compact" | "legacy", default: "legacy">{"changes": <array of change>}
change =
{"keypath": <string>,
"op": <"created" | "deleted" | "modified" | "value_set">,
"value": <string,>,
"old": <string>
}curl \
--cookie 'sessionid=sess12541119146799620192;' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": 1,
"method": "changes",
"params": {"th": 2}}' \
http://127.0.0.1:8008/jsonrpc
{"jsonrpc": "2.0",
"id": 1,
"result":
[{"keypath":"/dhcp:dhcp/default-lease-time",
"op": "value_set",
"value": "100",
"old": ""}]}{"th": <integer>}{}{"warnings": <array of warning>}
warning = {"paths": <array of string>, "message": <string>}{"type": "trans.resolve_needed", "data": {"users": <array string>}}{"type": "trans.validation_failed", "data": {"errors": <array of error>}}
error = {"paths": <array of string>, "message": <string>}{"th": <integer>}{"conflicts:" <array of conflicts>}
conflict =
{"keypath": <string>,
"op": <"created" | "deleted" | "modified" | "value_set">,
"value": <string>,
"old": <string>}{"th": <integer>}{}{"th": <integer>}{"comet_id": <string, optional>}{"handle": <string, optional>}{"details": <"normal" | "verbose" | "very_verbose" | "debug", optional>}{"flags": <flags, default: []>}
flags = <array of string or bitmask>{}{"warnings": <array of warning>}
warning = {"paths": <array of string>, "message": <string>}{"th": <integer>}{}{"th": <integer>,
"timeout": <integer, default: 0>,
"release_locks": <boolean, default: true>,
"rollback-id": <boolean, default: true>}{"flags": <flags, default: []>}
flags = <array of string or bitmask>{}{"rollback-id": {"fixed": 10001}}{"commit_queue_id": <integer>}{"type": "trans.confirmed_commit_in_progress"}{"type": "trans.confirmed_commit_is_only_valid_for_candidate"}{"type": "trans.confirmed_commit_needs_config_writable_through_candidate"}{"type": "trans.confirmed_commit_not_supported_in_private_mode"}{}{}{"trans": <array of trans>}
trans =
{"db": <"startup" | "running" | "candidate", default: "running">,
"conf_mode": <"private" | "shared" | "exclusive", default: "private">,
"th": <integer>
}{"db": <"startup" | "running" | "candidate", default: "running">,
"conf_mode": <"private" | "shared" | "exclusive", default: "private">
"on_pending_changes": <"reuse" | "reject" | "discard", default: "reuse">}{"th": <integer>}{"th": <integer>,
"name": <string>}{"template_variables": <array of string>}{"status": <"installable" | "installed" | "loaded" | "all", default: "all">}{"packages": <array of key-value objects>}Access-Control-Allow-Origin: http://webpage.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, Content-Type, Accept
Access-Control-Request-Method: POST{"jsonrpc": "2.0",
"id": 1,
"method": "subtract",
"params": [42, 23]}{"jsonrpc": "2.0",
"id": 1,
"result": 19}{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32601,
"type": "rpc.request.method.not_found",
"message": "Method not found"}}[{"jsonrpc": "2.0",
"id": 1,
"method": "subtract",
"params": [42, 23]}
,{"jsonrpc": "2.0",
"id": 2,
"method": "add",
"params": [42, 23]}][{"jsonrpc": "2.0",
"id": 2,
"result": 65}
,{"jsonrpc": "2.0",
"id": 1,
"result": 19}]{"jsonrpc": "2.0",
"id": 1,
"method": "login",
"params":
{"foo": "joe",
"bar": "SWkkasE32"}}{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32602,
"type": "rpc.method.unexpected_params",
"message": "Unexpected params",
"data":
{"param": "foo"}}}{"type": "rpc.request.parse_error"}
{"type": "rpc.request.invalid"}
{"type": "rpc.method.not_found"}
{"type": "rpc.method.invalid_params", "data": {"param": <string>}}
{"type": "rpc.internal_error"}
{"type": "rpc.request.eof_parse_error"}
{"type": "rpc.request.multipart_broken"}
{"type": "rpc.request.too_big"}
{"type": "rpc.request.method_denied"}
{"type": "rpc.method.unexpected_params", "data": {"param": <string>}}
{"type": "rpc.method.invalid_params_type", "data": {"param": <string>}}
{"type": "rpc.method.missing_params", "data": {"param": <string>}}
{"type": "rpc.method.unknown_params_value", "data": {"param": <string>}}
{"type": "rpc.method.failed"}
{"type": "rpc.method.denied"}
{"type": "rpc.method.timeout"}
{"type": "session.missing_sessionid"}
{"type": "session.invalid_sessionid"}
{"type": "session.overload"}// with jQuery
$.ajax({
type: 'post',
url: 'http://server.com/jsonrpc',
contentType: 'application/json',
data: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'login',
params: {
'user': 'joe',
'passwd': 'SWkkasE32'
}
}),
dataType: 'json',
crossDomain: true, // CORS specific
xhrFields: { // CORS specific
withCredentials: true // CORS specific
} // CORS specific
})module devices {
namespace "http://acme.com/ns/devices";
prefix d;
container config {
leaf description { type string; }
list device {
key "interface";
leaf interface { type string; }
leaf date { type string; }
}
}
}<cmdrule xmlns="http://tail-f.com/yang/acm">
<name>webui</name>
<context xmlns="http://tail-f.com/yang/acm">webui</context>
<command>::jsonrpc:: get_schema</command>
<access-operations>read exec</access-operations>
<action>deny</action>
</cmdrule>{}{"cmds": <array of cmd>}
cmd =
{"params": <object>,
"comet_id": <string>,
"handle": <string>,
"tag": <"string">,
"started": <boolean>,
"stopped": <boolean; should be always false>}{"th": <integer>,
"name": <string>,
"args": <string>,
"emulate": <boolean, default: false>,
"width": <integer, default: 80>,
"height": <integer, default: 24>,
"scroll": <integer, default: 0>,
"comet_id": <string>,
"handle": <string, optional>}{"handle": <string>}{"handle": <string>,
"data": <string>}{}{"type": "cmd.not_initialized"}{"handle": <string>}{}{"handle": <string>}{}{"handle": <string>}{}{"handle": <string>}{}{}{"subscriptions": <array of subscription>}
subscription =
{"params": <object>,
"comet_id": <string>,
"handle": <string>,
"tag": <"string">,
"started": <boolean>,
"stopped": <boolean; should be always false>}{"comet_id": <string>,
"handle": <string, optional>,
"path": <string>}{"handle": <string>}{"type": "db.cdb_operational_not_enabled"}{"comet_id": <string>,
"handle": <string, optional>,
"path": <string>,
"skip_local_changes": <boolean, default: false>,
"hide_changes": <boolean, default: false>,
"hide_values": <boolean, default: false>}{"handle": <string>}{"db": <"running" | "startup" | "candidate">,
"user": <string>,
"ip": <string>,
"changes": <array>}{"th": <integer>,
"path": <string>,
"interval": <integer between 0 and 3600>,
"comet_id": <string>,
"handle": <string, optional>}{"handle": <string>}{"comet_id": <string>,
"handle": <string, optional>}{"handle": <string>}{"upgrade_state": <"wait_for_init" | "init" | "abort" | "commit">,
"timeout": <number, only if "upgrade_state" === "wait_for_init">}{"comet_id": <string>,
"handle": <string, optional>}{"handle": <string>}{"jsonrpc":"2.0",
"result":"admin",
"id":1}
{"jsonrpc": "2.0",
"id": 1,
"error":
{"code": -32602,
"type": "rpc.method.unexpected_params",
"message": "Unexpected params",
"data":
{"param": "foo"}}}{"comet_id": <string>,
"handle": <string, optional>,
"verbosity": <"normal" | "verbose" | "very_verbose" | "debug", default: "normal">
"filter_context": <"webui" | "cli" | "netconf" | "rest" | "snmp" | "system" | string, optional>}{"handle": <string>}{"timestamp": <string>,
"duration": <string, optional if end of span>,
"span-id": <string>,
"parent-span-id": <string, optional if parent span exists>,
"trace-id": <string>,
"session-id": <integer>,
"transaction-id": <integer, optional if transaction exists>,
"datastore": <string, optional if transaction exists>,
"context": <string>,
"subsystem": <string, optional if in subsystem>,
"message": <string>,
"annotation": <string, optional if end of span>,
"attributes": <object with key-value attributes, optional>,
"links": <array with objects, each containing a trace-id and span-id
key, optional>}{"handle": <string>}{}{"handle": <string>}