diff options
Diffstat (limited to 'simulator-cli/README.md')
| -rw-r--r-- | simulator-cli/README.md | 309 |
1 files changed, 309 insertions, 0 deletions
diff --git a/simulator-cli/README.md b/simulator-cli/README.md new file mode 100644 index 0000000..0202cb2 --- /dev/null +++ b/simulator-cli/README.md @@ -0,0 +1,309 @@ +## NF SIMULATOR/NETCONF SERVER CLI + +### Overview +Anytime you want to see a basic usage of a tool, you can run fully descriptive help using command: +``` +./{tool_name}.py -h # --help argument is also acceptable +``` + +#### NF Simulator CLI +NF Simulator CLI provides command line interface to remotely interact with running NF Simulator. + +Using the NF Simulator CLI user is able to trigger events, retrieve simulator's configuration and change default VES url stored +inside simulator. + +#### Netconf Server CLI +Dedicated tool to help with management of the Netconf Server is also available. + +Using the Netconf Server CLI user is able to retrieve simulator's cm history stored inside simulator as well as open the live session to actively listen for new configuration changes. + +### Requirements and installation +Requirements +* Python > 3.5 + +Installation: +* Go to directory containing setup.py and invoke `python setup.py install` +* Go to cli directory +* Add executable privilege to nf_simulator.py and netconf_server.py (for example `chmod +x <path_to_nf_simulator.py>`) + +### Development and testing +To run unit tests for NF and Netconf servers cli execute `tox`. + +To develop unit tests run `tox`, then `source .tox/pytest/bin/activate` and after each code change run `pytest`. + +### Nf simulator +#### Usage +* [send](#send-action) +* [configure](#configure-action) +* [get-config](#get-config-action) +* [template](#template-action) +* [filter](#filter-templates-action) + + +#### Help +Invoke `nf_simulator.py [send|configure|get-config] -h` to display help. + +##### Send Action +Send action allows user to trigger sending events from Simulator to VES Collector. + +*sending repeating events backed by template persisted in db +`usage: nf_simulator.py send template [-h] --address ADDRESS --name NAME + [--patch PATCH] [--repeats REPEATS] + [--interval INTERVAL] + [--ves-server-url VES_SERVER_URL] [--verbose] +` + +Parameters +` --address ADDRESS` `IP address of simulator` +` --name NAME` `Name of template file which should be used as a base for event. + Cannot be used simultaneously with parameter: event.` +` --patch PATCH` `Json which should be merged into template to override parameters. + Acceptable format: valid json wrapped using single quotes (example:'{"abc":1}'). + Cannot be used simultaneously with parameter: event.` +` --repeats REPEATS` `Number of events to be send` +` --interval INTERVAL` `Interval between two consecutive events (in seconds)` +` --ves-server-url VES_SERVER_URL` `Well-formed URL which will override current VES endpoint stored in simulator's DB` +` --verbose` `Displays additional logs` + + +*sending event only once by passing path to file with complete event +`usage: nf_simulator.py send event [-h] --address ADDRESS --filepath FILEPATH + [--ves-server-url VES_SERVER_URL] [--verbose] +` +Parameters +` --address ADDRESS` `IP address of simulator` +` --filepath FILEPATH` `Path to file with full, legitimate event that is to be send directly to VES only once. + This event is not associated with template and will not be persisted in db. + Cannot be used simultaneously with parameters: template and patch.` +` --ves-server-url VES_SERVER_URL` `Well-formed URL which will override current VES endpoint stored in simulator's DB` +` --verbose` `Displays additional logs` + +example content of file with complete event: +``` +{ + "commonEventHeader": { + "eventId": "#Timestamp", + "sourceName": "#Increment", + "version": 3.0 + } +} +``` + +##### Configure Action +Configure action allows user to change Simulator's configuration (VES Server URL) +`usage: nf_simulator.py configure [-h] --address ADDRESS --ves-server-url + VES_SERVER_URL [--verbose] +` + +Parameters + +` --address ADDRESS` `IP address of simulator` +` --ves-server-url VES_SERVER_URL` `Well-formed URL which should be set as a default VES Server URL in simulator` +` --verbose` `Displays additional logs` + +##### Get Config Action +Get Config action allows user to retrieve actual Simulator's configuration +`usage: nf_simulator.py get-config [-h] --address ADDRESS [--verbose] ` + +Parameters + +`--address ADDRESS` `IP address of simulator` +`--verbose` `Displays additional logs` + +##### Template Action +Template action allows user to: +* retrieve a single template by name +* list all available templates. +* upload template to NF Simulator (can overwrite existing template) + +`usage: nf_simulator.py template [-h] + (--list | --get-content NAME | --upload FILENAME) + [--override] --address ADDRESS [--verbose]` + +Parameters + +`--get-content NAME` `Gets the template by name` +`--list` `List all templates` +`--upload FILENAME [--override]` `Uploads the template given as FILENAME file. Optionally overrides any exisitng templates with matching filename` +`--address ADDRESS` `IP address of simulator` +`--verbose` `Displays additional logs` + +#### Filter Templates Action +Filter template action allows to search through templates in order to find names of those that satisfy given criteria. +Criteria are passed in JSON format, as key-values pairs. Relation between pairs with criteria is AND (all conditions must be satisfied by template to have it returned). +No searching for null values is supported. +Search expression must be valid JSON, thus no duplicate keys are allowed - user could specify the same parameter multiple times, but only last occurrence will be applied to query. + + +`usage: nf_simulator.py filter [-h] + --criteria CRITERIA --address ADDRESS [--verbose]` + +Parameters +`--criteria CRITERIA` `Json with criteria as key-value pairs, where values can be one of following data types: string, integer, double, boolean. + Acceptable format: valid json wrapped using single quotes (example:'{"searchedInt":1}'). + Cannot be used simultaneously with parameter: event.` +`--address ADDRESS` `IP address of simulator` +`--verbose` `Displays additional logs` + + +### Netconf server +#### Usage +* [load-model](#load-model-action) +* [delete-model](#delete-model-action) +* [get-config](#get-config-action) +* [edit-config](#edit-config-action) +* [tailf](#tailf-action) +* [less](#less-action) +* [cm-history](#cm-history-action) + +#### Help +Invoke `netconf_server.py [tailf|less|cm-history] -h` to display help. + + +#### Load-model action +Loads to netconf server new YANG model that corresponds with schema passed as yang-model parameter, +assigns name specified in module-name and initializes model with startup configuration passed in config file. +`usage: netconf_server.py load-module [-h] --address ADDRESS ---module-name MODULE_NAME --yang-model YANG_MODEL_FILEPATH --config <XML_CONFIG_FILEPATH> [--verbose]` + +example YANG schema (file content for YANG_MODEL) +``` +Response status: 200 +module nf-simulator { + namespace "http://nokia.com/nf-simulator"; + prefix config; + container config { + config true; + leaf itemValue1 {type uint32;} + leaf itemValue2 {type uint32;} + leaf itemValue3 {type uint32;} + leaf-list allow-user { + type string; + ordered-by user; + description "A sample list of user names."; + } + } +} +``` + +example startup configuration (file content of XML_CONFIG) +``` +<config xmlns="http://nokia.com/nf-simulator"> + <itemValue1>100</itemValue1> + <itemValue2>200</itemValue2> + <itemValue3>300</itemValue3> +</config> +``` + + +example output (without verbose flag): +``` +Response status: 200 +Successfully started +``` + +#### Delete-model action +Deletes a YANG model loaded in the netconf server. + +`usage: netconf_server.py delete-model [-h] --address ADDRESS --model-name + MODEL_NAME [--verbose]` + +Example output (without verbose flag): +``` +Response status: 200 +Successfully deleted +``` + +#### Get-config Action +Returns active running configurations. +By default it returns all running configurations. To retrieve one specific configuration (represented by _/'module_name':'container'_ ) user needs to pass module-name and container. +Example: +` +netconf_server.py get-config --address localhost --module-name nf-simulator --container config +` + + +`usage: netconf_server.py get-config [-h] --address ADDRESS [--verbose] [--module-name MODULE-NAME] [--container CONTAINER]` + +example output (without verbose flag): +``` +Response status: 200 +<config xmlns="http://nokia.com/nf-simulator" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <itemValue1>2781</itemValue1> + <itemValue2>3782</itemValue2> + <itemValue3>3333</itemValue3> +</config> +``` + +#### Edit-config Action +Modifies existing configuration (e.g. change parameter values, modify or remove parameter from model). +To edit configuration, netconf compliant XML file should be prepared and used as one of edit-config parameters. +`usage: netconf_server.py edit-config [-h] --address ADDRESS --config <XML_CONFIG_FILEPATH> [--verbose]` + +example - parameter values modification +file content: +``` +<config xmlns="http://nokia.com/nf-simulator"> + <itemValue1>1</itemValue1> + <itemValue2>2</itemValue2> + <itemValue3>3</itemValue3> +</config> +``` + +example output (without verbose flag): +``` +Response status: 202 +<config xmlns="http://nokia.com/nf-simulator" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <itemValue1>1</itemValue1> + <itemValue2>2</itemValue2> + <itemValue3>3</itemValue3> +</config> +``` + +##### Less Action +Less action allows user to watch historical configuration changes. +Size of the configuration changes list is limited to the 100 last cm events by default, but can be incresed/decresead using a 'limit' attribute. +`usage: netconf_server.py less [-h] --address ADDRESS [--limit LIMIT] [--verbose]` + +Output from the command can be easily piped into other tools like native less, more, etc. e.g.: +`netconf_server.py less --address 127.0.0.1 | less` + +Last known configuration is last printed to the output, so order of the printed configuration events complies with time when the configuration was stored inside the simulator. + +Parameters: + +`--address ADDRESS` - `IP address of simulator` + +`--limit LIMIT` - ` Number of configurations to print at output` + +`--verbose` - ` Displays additional logs` + +Single message is represented as a pair of timestamp in epoch format and suitable configuration entry. + +##### Tailf Action +Tailf action allows user to actively listen for new uploaded configuration changes. +Size of the historical configuration changes list is limited to the 10 last cm events. +`usage: netconf_server.py tailf [-h] --address ADDRESS [--verbose]` + +The listener can be easily terminated at anytime using `CTRL+C` shortcut. + +Parameters: + +`--address ADDRESS` - `IP address of simulator` + +`--verbose` - ` Displays additional logs` + +Single message is represented as a pair of timestamp in epoch format and suitable configuration entry. + +##### Cm-history Action +Cm-history action allows user to view list of all uploaded configuration changes. +`usage: netconf_server.py cm-history [-h] --address ADDRESS [--verbose]` + +Last known configuration is last printed to the output, so order of the printed configuration events complies with time when the configuration was stored inside the simulator. + +Parameters: + +`--address ADDRESS` - `IP address of simulator` + +`--verbose` - ` Displays additional logs` + +Single message is represented as a pair of timestamp in epoch format and suitable configuration entry. |