Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sysrepo-archive/sysrepod

Last synced: 12 days ago
JSON representation

Host: GitHub
URL: https://github.com/sysrepo-archive/sysrepod
Owner: sysrepo-archive
License: other
Created: 2015-02-16T12:40:42.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2015-10-11T20:56:41.000Z (about 9 years ago)
Last Synced: 2024-07-24T04:32:45.149Z (4 months ago)
Language: C++
Homepage: http://www.sysrepo.org/
Size: 443 KB
Stars: 1
Watchers: 8
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README
- License: LICENSE

Awesome Lists containing this project

README

/* License : Apache 2.0
*
* Created on: Jan 30, 2015
* Author: Niraj Sharma
* Cisco Systems, Inc.
*/

1) To build, use 'make'.
2) To clean, use 'make clean'. After downloading from GitHub, create the directory "server/xsltDir" as it mentioned in
"server/param" file as a parameter to create a data store. Also install "jing" and "pyang" on your computer using
the instruction given under 16) below. After these steps, all example programs will run without any error.

3) To run server listening on 3500 port:
cd server
./sysrepod param

In another XTERM window start sample client that talks SRD (Sys Repo Daemon) protocol:
cd client_SRD
# To run client that issues a few commands and exits.
./clientsrd
# This client in the end will wait for a command from SysrepoD server requesting
# information about the Operational Data Store that this client is maintaining.
# There is a need of a North-bound client that initiates a request for Operational Data Store by
# send it to SysrepoD server. The server in turn forwards that request to this client "./clientsrd.
# To test this feature, it is time to start a sample North-Bound Client. To do that follow the following steps:
# Start a new XTERM window and be in the code directory.
cd client_SRD
./opDStoreClient
# It will start this North-Side Management Client. You will see messages going to server and to 'clientsrd'
# started earlier.

NOTE: Client Programs that use SRD API must call "xmlCleanupParser()" only once just before exiting. SRD library
does not make this call. <<<<<<<<<<<<<<<<<<<<<<

3.01) SysrepoD PARAMETERS and LOGGING SYSTEM
One can specify start-up parameters in a file and use the file at the time of starting 'sysrepod'.
In the command './sysrepod param', the file 'param' contains the start-up parameters for the 'sysrepod'. A description
of parameters is as follows. Each parameter must be specified on a separate line and must be terminated by ';'.

a) LOGDIR : It is used to specify where log files will be stored. Default value = "logs".
b) LOGSIZE : It is used to specify the maximum size (Bytes) of each log file. When a log file reaches this limit,
a new log file is created. Default value = 1 MB
c) NUMLOGS : It specifies the maximum number of log files to keep. When maximum number of log files get
created, the oldest file is deleted to create a new log file. Default value = 100.
d) LOGLEVEL : Higher the value for LOGLEVEL, more log messages will get generated. Default value = 10.
The server logs the RECEIVED and SENT commands at level 4.
e) SERVERPORT : It specifies the main listening port for the server. Default value = 3500.
f) MAXCLIENTS : It specifies the maximum number of concurrent clients that can connect to the server. Default value = 20
There is no limit for this value.
g) MAXDATASTORES : It specifies the maximum number of data stores that can be created on the server. Default value = 50.
There is no limit for this value.
h) MAXOPDATASTORES : It specifies the maximum number of operational data stores. Default value = 50.
There is no limit for this value.
i) DATASTORE : It is used to specify a Data Store at start-up time.
Data stores can also be defined using API. The parameter descriptions are as follows:
- Name of the data store to be created
- The path to an XML file that will be used to form the data store.
- The path to a dir that may contain 0 or more XSLT files that are used for semantic checks when data store
is modified. The XSLT scripts must generate node for the semantic test to pass. This value is optional
if the next parameter is not present. More description is given under 15).
- It specifies a dir containing a Yang file that is used to perform syntactic and semantic checks on the data store
at the time of all modifications. The yang file name must match the data store name. For example, if the data store
name is 'runtime', the correspoding Yang file name must be 'runtime.yang'. The value of could be any path.
Note that this parameter is optional, but if this parameter is present, must also be present.
more description is given under 16).

4) One can run many clients in parallel from separate XTERM windows.
5) ClientSRD.cpp implements a client class that talks SRD protocol. One can create additional classes
for different protocols by deriving from the base class Client implemented in Client.cpp.
6) mainSRDClient.cpp implements a sample client that talks SRD.
7) mainSysRedoD.cpp implements the SysRepo Daemon.
8) DataStore.cpp implements the Data Store class. One can have many Data Stores.
9) libsrd.a is the library that any client talking SRD protocol will link with.
To understand the API Calls available in libsrd.a, look at the file srd.h.
10) HOW TO WRITE A CLIENT: Look at the sample client mainSRDClient.cpp. The
API calls are listed in srd.h. To compile your client use the following
in Makefile:

client: mainSRDClient.o srd.o libsrd.a
$(GCC) -g -o client mainSRDClient.o libsrd.a -lxml2

A DESCRPTION OF THE API's IS GIVEN IN 'srd.h'

11) AN EXAMPLE of running TWO Daemons (south-side clients) with two separate Operational Data Stores specified
using Name Spaces and ONE North-side Management Client sending XPath expression for the two Operational
Data Stores. Execute the following commands:

a) Open an XTerm window in the code directory and execute:
cd server
./sysrepod param
b) Open another XTerm window in the code directory and execute:
cd client_SRD
./opDStoreSubTree1
c) Open another XTerm window in the code directory and execute:
cd client_SRD
./opDStoreSubTree2

b) and c) starr two Daemons that register two Operational Data Stores
Now let us start a north-side client to send XPATH to these two Daemons
d) Open another XTerm window in the code directory and execute:
cd client_SRD
./opDStoreGetSubTree

You will see the results of XPath in this XTerm window.

12) INSTRUCTIONS to run a performance test on a huge data store with 20,000 xml nodes and a query that retrieves

You will see that the query is answered in an instant. The reply is calculated, transmitted, and parsed in milli-seconds.

1000 XML nodes in the result.

a) To generate a large XML file with name huge.xml, run the following command:
cd server
./genHuge

b) To start server, execute:
./sysrepod param

c) To start a client that sends a XPATH query to retreive 1000 nodes, run the commands:
Open another XTERM window
cd client_SRD
./hugeTest

You will see that the query is answered in an instant. The reply is calculated, transmitted, and parsed in milli-seconds.
You can change parameters defined in the progream server/mainHugeTest.c to generate arbitrarily large xml in huge.xml
and just follow the same instructions to execute XPATH to check the performance of SYSREPOD server.

13) INSTRUCTIONS to run a signal test: SIGHUP is registed with the server by a client.
It causes the server to send the signal to the client whenever the Data Store is modified.

a) To start server, execute:
cd server
./sysrepod param

c) To start a client that registers SIGHUP and is ready to receive it, run the commands:
Open another XTERM window
cd client_SRD
./signalTest

14) INSTRUCTIONS to run an XSLT test: It applies an XSLT to the data store and prints results.
This XSLT filters all LEAF nodes and prints "name" and "value" pairs separated by ':' on
a separate line. XSLT's can be used to generate XML, HTML, and flat data suitable for consumption
by conventional program like SSHD.
Note that XSLT must be enclosed within CDATA clause.

a) To start server, execute:
cd server
./sysrepod param

c) To start this client to apply XSLT on the data store, run the commands:
Open another XTERM window
cd client_SRD
./xsltTest

15) SEMANTIC CONSTRAINTS USING XSLT: One can express semantic constraints in YANG Model also, but
there may be many constraints that can not be expressed in Yang Model due to its limitations. XSLT is
a quite complete programming language and can be used to express all semanitc contraints. Due to this
reason, SysrepoD provides support for XSLT in addition to Yang Model.

An example of a semantic constraint is that the number of
nodes must be greater than 1. Arbitrarily complex semantic constraints can
be expressed using XSLT as it is a full-fledged programming language. We assume that XSLT
generates xml if the constraints are met. If constraints are not met, the generated xml
should not contain node. Constriaints are expressed by a third parameter in the parameter
file within the line defining a data store. For example:

DATASTORE runtime deviceConfig.xml checkDir;

defines a data store 'runtime', its XML, and the third parameter is a directory path 'checkDir'.
Since, the current dir for server is './server', 'checkDir' exists under './server'.
This dir contains XSLT files specifying Data Store's semantic
contraints (many files possible in one directory). Note that this third parameter, a dir path, is optional.

'checkDir' contains one sample XSL file checking that the data store must have at least one 1 node.
For a -ve test, you can edit this XSL file and replace 8th line with the following line:

This new line expresses that the number of nodes must be more than 3. With the given XML
for 'runtime' data store, this constraint will fail and server will not create the data store
printing the following error message:

XSL sheet checkDir/deviceConfigSemanticCheck.xsl generated semantic error.
Warning: Constraints failed. Data store will not be created.
Warning in creating a new data store: runtime
Warning: Could not add data store runtime

To test the semantic constraints, run the following command:
cd server
./sysrepod param

The constrains checks will also be performed when a client modifies the data store using API.
Another way to check this constraint is by trying to remove both nodes present
in 'runtime' data store. The attempt should fail. There is a sample program to test constraint
failure via API. To run this example, follow the instructions:
To run server, "cd server" and execute "./sysrepod param". In another xterm window, type:
cd client_SRD
./deleteNodeConstraintFailTest
You will semantic constraint violation. No changes will be made to 'runtime' data store.

16) SEMANTIC CONSTRAINTS USING YANG: Semantic constraints are expressed in a Yang model.
Pyang and Jing tools are used to apply these semantic contraints when the data store is
created or modified. To install these tools, use the following commands:

sudo apt-get install jing
git clone git://github.com/mbj4668/pyang.git

To set environment variables for Pyang and run sysrepod, use the following commands:

cd
source ./env.sh
cd
./sysrepod param

To use Yang based constraint verification, let us consider the following in the server/param
file:

DATASTORE sshd_config sshd---config.xml xsltDir yangDirFor_sshd_config;

Here, ssh_config is the name of the data store to be created.
sshd---config.xml is used to create the contents of the data store.
xslDir may be used to store a set of XSL files for custom constraint verification.
Create xslDir directory under 'server'.
'yangDirFor_sshd_config' directory is created to store a yang model for 'sshd_config' data store.
The name of the file must be '.yang'. In this case, it would be
'sshd_config.yang'.

Now 'sshd_config' data store is ready for yang based constrained verification. There is an example
implemented in 'client_SRD/mainYangTest.c' file. This example, tries to add a new node that
violates yang model. After starting sysrepod server as mentioned above, start the client to
test yang model using the following command:

cd client_SRD
./yangTest

The test will report that the act of adding a new node failed as it violates constraints.

NOTE that there may be many constraints that can not be expressed in Yang Model. One can use
XSLT based constraints as described under 15) above to express any constraint.

17) TRANSACTION MODEL: srd_startTransaction () starts a transaction owned by the caller.
If the caller disconnects without commiting its transaction, the transaction is aborted automatically.
One client can start only one transaction at a time. It means there can not be nested transactions.
All operations in a transaction must be applicable to only one data store. In other words, in
the middle of a transaction data stores can not be switched. Only one client can be active within a
data store when there is an open transaction for the data store. Starting a transaction will be successful
only when no other client has a lock on the data store and no other client has an open transaction for the
same data store. One can abort its transaction using srd_abortTransaction (). One can commit its transaction
using srd_commitTransaction (). It returns a transaction ID that is unique among all committed transactions on
all data stores during one execution of the server.

One can use srd_rollbackTransaction () to rollback the transaction whose transaction ID is in the second parameter.
Currently, the server has a capability to roll back only the last committed transaction on a specific data store.
The following contexts are worth understanding:

- A caller commits a transaction with ID 12 for data store (A).
- Switches to data store (B).
- Requests rollback of transaction 12.
- Rollback will fail as the transaction 12 is not on data store (B).
- The caller switches back to data store (A).
- Repeats the request to rollback the transaciton 12.
- The requested rollback will succeed if no other transaction was committed on data store (A), no other transaction is
in progress on (A) and (A) is not locked by any client. In other words, trasaction 12 is the last committed
transaction on data store (A).

- A caller issues a request to rollback transaction ID 11 after committing transaction 12.
- The request to rollback will fail as transaction 11 is not the last transaction.

- A caller X issues a commit for transaction ID 12 on data store (A) and passes on this transaction ID to caller Y.
- Caller Y switches to data store (A) and sends a request to rollback transaction 12.
- The requested rollback will succeed if no other transaction was committed on data store (A), no other transaction is
in progress on (A) and (A) is not locked by any client. In other workds, transaction 12 is the last committed
transaction on data store (A).

srd_getLastTransactionId () retrieves the ID of the last transaction committed by any client on the current data store.

TRANSACTION MODEL SUMMARY:

srd_startTransaction () - To start a transaction
srd_abortTransaction () - To abort a transaction in progress
srd_commitTransaction () - To commit a transaction in progress. Returns Transaction ID
srd_rollbackTransaction () - To rollback the last committed transaction whose ID is present in second parameter.
Transaction ID must have been returned by srd_commitTransaction () or
srd_getLastTransactionId () call.
srd_getLastTransactionId ()- To retrieve the ID of the last transaction committed by any client on the current data store.

To run a sample program to test transacton, start syrepod and execute the following instructions:
cd client_SRD
./testTransaction

18) 'edit-config' command in NETCONF has many options and is more complex than other commands. Below a description
about mapping 'edit-config' command to SRD API is given in case there is a need to implement 'edit-config' command
using SRD API.

can have different types of operations within it. Each is described below:
"merge" : It is used to change an atomic values. srd_updateNodes () call performs this task.

"replace" : It is used to replace a sub-tree by another one. If the specified sub-tree does not exist in
the data store, add a new sub-tree using the values present in the command.
srd_replaceNodes () call performs this task.

"create" : A new sub-tree is to be added. If it already exists, report error.
It can be implemented using srd_addNodes ().
Presence of sub-tree can be tested using srd_applyXPath ().

"delete" : It is used to delete a subtree. It can be implemented using srd_deleteNodes ().
This call returns the number of nodes deleted. Agent can use the returned value to
determine if there is an error or not.

"remove" : It is same as "delete" except that if sub-tree does not exist, "remove" does not
report error. It can be implemented using srd_deleteNode().

With command, one can specify .

"test-then-set": If validation fails, do not perform the operation. All SysrepoD edit
commands have a parameter to implement this option.
"set" : Set the values without any validation. This option is present in SysrepoD.
"test-only" : Just test, do not set any values. This options is present in SysrepoD.

With command, one can specify .

"stop-on-error" : It is the current behavior SysrepoD.
"continue-on-error" : It means continure on syntatic and semantic errors. It can be specified in
SysrepoD calls.
"rollback-on-error" : SysrepoD follows this behavior by default.