X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Ftesttool.rst;h=3d4dc2fb5192a12f9594ef79fd234e41aede4084;hb=6ece24a63d5750ae0f7f66eda5241b1f1507d524;hp=9577ec5fda79d58c8b31dbc9ebe6b4a7680f42f3;hpb=c3d4db5a2b40883975e6495cce3e926193621a5f;p=netconf.git diff --git a/docs/testtool.rst b/docs/testtool.rst index 9577ec5fda..3d4dc2fb51 100644 --- a/docs/testtool.rst +++ b/docs/testtool.rst @@ -22,11 +22,6 @@ NETCONF testtool These jars are part of OpenDaylight’s controller project and are built from the NETCONF codebase in OpenDaylight. -.. tip:: - - Download testtool from OpenDaylight Nexus at: - https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.1.0-Boron/ - **Nexus contains 3 executable tools:** - executable.jar - device simulator @@ -51,8 +46,8 @@ NETCONF testtool (or NETCONF device simulator) is a tool that - Uses core implementation of NETCONF server from OpenDaylight -- Generates configuration files for controller so that the OpenDaylight - distribution (Karaf) can easily connect to all simulated devices +- Allows for automatic sending of connector configurations through RESTCONF to the controller. This makes it easy for + the OpenDaylight distribution (Karaf) to connect to all simulated devices once the simulator starts. - Provides broad configuration options @@ -64,7 +59,7 @@ Building testtool ^^^^^^^^^^^^^^^^^ 1. Check out latest NETCONF repository from - `git `__ + `git `__ 2. Move into the ``opendaylight/netconf/tools/netconf-testtool/`` folder @@ -74,23 +69,23 @@ Downloading testtool ^^^^^^^^^^^^^^^^^^^^ Netconf-testtool is now part of default maven build profile for -controller and can be also downloaded from nexus. The executable jar for -testtool can be found at: -`nexus-artifacts `__ +controller and can be also downloaded from nexus. The executable jars for +testtool can be found by release at this parent directory: +`nexus-artifacts `__ Running testtool ^^^^^^^^^^^^^^^^ 1. After successfully building or downloading, move into the ``opendaylight/netconf/tools/netconf-testtool/target/`` folder and - there is file ``netconf-testtool-1.1.0-SNAPSHOT-executable.jar`` (or - if downloaded from nexus just take that jar file) + there is file ``netconf-testtool-[VERSION]-executable.jar`` (or + if downloaded from nexus just take that \*-executable.jar file) 2. Execute this file using, e.g.: :: - java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar + java -jar netconf-testtool-[VERSION]-executable.jar This execution runs the testtool with default for all parameters and you should see this log output from the testtool : @@ -122,8 +117,7 @@ The default parameters for testtool are: - Debug level is set to false -- No distribution is modified to connect automatically to the NETCONF - testtool +- Other default parameters can be seen with ``--help`` option Verifying testtool ^^^^^^^^^^^^^^^^^^ @@ -145,14 +139,20 @@ Testtool help :: - usage: netconf testtool [-h] [--edit-content EDIT-CONTENT] [--async-requests {true,false}] [--thread-amount THREAD-AMOUNT] [--throttle THROTTLE] - [--auth AUTH AUTH] [--controller-destination CONTROLLER-DESTINATION] [--device-count DEVICES-COUNT] - [--devices-per-port DEVICES-PER-PORT] [--schemas-dir SCHEMAS-DIR] [--notification-file NOTIFICATION-FILE] + usage: netconf testtool [-h] [--edit-content EDIT-CONTENT] [--async-requests {true,false}] + [--thread-amount THREAD-AMOUNT] [--throttle THROTTLE] + [--controller-auth-username CONTROLLER-AUTH-USERNAME] + [--controller-auth-password CONTROLLER-AUTH-PASSWORD] [--controller-ip CONTROLLER-IP] + [--controller-port CONTROLLER-PORT] [--device-count DEVICES-COUNT] + [--devices-per-port DEVICES-PER-PORT] [--schemas-dir SCHEMAS-DIR] + [--notification-file NOTIFICATION-FILE] [--initial-config-xml-file INITIAL-CONFIG-XML-FILE] [--starting-port STARTING-PORT] [--generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT] - [--generate-config-address GENERATE-CONFIG-ADDRESS] [--generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE] - [--distribution-folder DISTRO-FOLDER] [--ssh {true,false}] [--exi {true,false}] [--debug {true,false}] - [--md-sal {true,false}] [--time-out TIME-OUT] [-ip IP] [--thread-pool-size THREAD-POOL-SIZE] [--rpc-config RPC-CONFIG] + [--generate-config-address GENERATE-CONFIG-ADDRESS] + [--generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE] + [--distribution-folder DISTRO-FOLDER] [--ssh {true,false}] [--exi {true,false}] + [--debug {true,false}] [--md-sal {true,false}] [--time-out TIME-OUT] [--ip IP] + [--thread-pool-size THREAD-POOL-SIZE] [--rpc-config RPC-CONFIG] netconf testtool @@ -160,48 +160,64 @@ Testtool help -h, --help show this help message and exit --edit-content EDIT-CONTENT --async-requests {true,false} + (default: false) --thread-amount THREAD-AMOUNT - The number of threads to use for configuring devices. - --throttle THROTTLE Maximum amount of async requests that can be open at a time, with mutltiple threads this gets divided among all threads - --auth AUTH AUTH Username and password for HTTP basic authentication in order username password. - --controller-destination CONTROLLER-DESTINATION - Ip address and port of controller. Must be in following format : if available it will be used for spawning - netconf connectors via topology configuration as a part of URI. Example (http:///restconf/config/network-topology:network-topology/topology/topology-netconf/node/)otherwise it will - just start simulated devices and skip the execution of PUT requests + The number of threads to use for configuring devices. (default: 1) + --throttle THROTTLE Maximum amount of async requests that can be open at a time, with mutltiple threads + this gets divided among all threads (default: 5000) + --controller-auth-username CONTROLLER-AUTH-USERNAME + Username for HTTP basic authentication to destination controller. (default: admin) + --controller-auth-password CONTROLLER-AUTH-PASSWORD + Password for HTTP basic authentication to destination controller. (default: admin) + --controller-ip CONTROLLER-IP + Ip of controller if available it will be used for spawning netconf connectors via + topology configuration as a part of URI(http://:/rests/data/...) otherwise it will just start simulated devices and skip the + execution of PATCH requests + --controller-port CONTROLLER-PORT + Port of controller if available it will be used for spawning netconf connectors via + topology configuration as a part of URI(http://:/rests/data/...) otherwise it will just start simulated devices and skip the + execution of PATCH requests --device-count DEVICES-COUNT - Number of simulated netconf devices to spin. This is the number of actual ports open for the devices. + Number of simulated netconf devices to spin. This is the number of actual ports open + for the devices. (default: 1) --devices-per-port DEVICES-PER-PORT - Amount of config files generated per port to spoof more devices than are actually running + Amount of config files generated per port to spoof more devices than are actually + running (default: 1) --schemas-dir SCHEMAS-DIR - Directory containing yang schemas to describe simulated devices. Some schemas e.g. netconf monitoring and inet types are - included by default + Directory containing yang schemas to describe simulated devices. Some schemas e.g. + netconf monitoring and inet types are included by default --notification-file NOTIFICATION-FILE - Xml file containing notifications that should be sent to clients after create subscription is called + Xml file containing notifications that should be sent to clients after create + subscription is called --initial-config-xml-file INITIAL-CONFIG-XML-FILE Xml file containing initial simulatted configuration to be returned via get-config rpc --starting-port STARTING-PORT - First port for simulated device. Each other device will have previous+1 port number + First port for simulated device. Each other device will have previous+1 port number + (default: 17830) --generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT - Timeout to be generated in initial config files + Timeout to be generated in initial config files (default: 1800000) --generate-config-address GENERATE-CONFIG-ADDRESS - Address to be placed in generated configs + Address to be placed in generated configs (default: 127.0.0.1) --generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE - Number of connector configs per generated file + Number of connector configs per generated file (default: 1) --distribution-folder DISTRO-FOLDER Directory where the karaf distribution for controller is located - --ssh {true,false} Whether to use ssh for transport or just pure tcp - --exi {true,false} Whether to use exi to transport xml content - --debug {true,false} Whether to use debug log level instead of INFO - --md-sal {true,false} Whether to use md-sal datastore instead of default simulated datastore. - --time-out TIME-OUT the maximum time in seconds for executing each PUT request - -ip IP Ip address which will be used for creating a socket address.It can either be a machine name, such as java.sun.com, or a - textual representation of its IP address. + --ssh {true,false} Whether to use ssh for transport or just pure tcp (default: true) + --exi {true,false} Whether to use exi to transport xml content (default: true) + --debug {true,false} Whether to use debug log level instead of INFO (default: false) + --md-sal {true,false} Whether to use md-sal datastore instead of default simulated datastore. (default: false) + --time-out TIME-OUT the maximum time in seconds for executing each PATCH request (default: 20) + --ip IP Ip address which will be used for creating a socket address.It can either be a machine + name, such as java.sun.com, or a textual representation of its IP address. (default: + 0.0.0.0) --thread-pool-size THREAD-POOL-SIZE - The number of threads to keep in the pool, when creating a device simulator. Even if they are idle. + The number of threads to keep in the pool, when creating a device simulator. Even if + they are idle. (default: 8) --rpc-config RPC-CONFIG - Rpc config file. It can be used to define custom rpc behavior, or override the default one.Usable for testing buggy device - behavior. + Rpc config file. It can be used to define custom rpc behavior, or override the default + one.Usable for testing buggy device behavior. Supported operations @@ -245,7 +261,7 @@ not supported when testtool is running with the MD-SAL datastore. Notification support ^^^^^^^^^^^^^^^^^^^^ -Testtool supports notifications via the --notification-file switch. To +Testtool supports notifications via the ``--notification-file`` switch. To trigger the notification feed, create-subscription operation has to be invoked. The XML file provided should look like this example file: @@ -306,22 +322,14 @@ Connecting testtool with controller Karaf distribution Auto connect to OpenDaylight '''''''''''''''''''''''''''' -It is possible to make OpenDaylight auto connect to the simulated -devices spawned by testtool (so user does not have to post a -configuration for every NETCONF connector via RESTCONF). The testtool is -able to modify the OpenDaylight distribution to auto connect to the -simulated devices after feature ``odl-netconf-connector-all`` is -installed. When running testtool, issue this command (just point the -testool to the distribution: +You can set up the testtool to automatically connect to the Controller. When you provide +the ``--controller-ip`` and ``--controller-port`` parameters, the testtool will send a PATCH request to the Controller +netconf-topology with the device connector configuration. :: - java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true + java -jar netconf-testtool-[VERSION]-executable.jar --device-count 10 --controller-ip 127.0.0.1 --controller-port 8181 --debug true -With the distribution-folder parameter, the testtool will modify the -distribution to include configuration for netconf-connector to connect -to all simulated devices. So there is no need to spawn -netconf-connectors via RESTCONF. Running testtool and OpenDaylight on different machines ''''''''''''''''''''''''''''''''''''''''''''''''''''''' @@ -348,45 +356,39 @@ will define a simple YANG model: :: module test { - yang-version 1; - namespace "urn:opendaylight:test"; - prefix "tt"; - - revision "2014-10-17"; - - - container cont { - - leaf l { - type string; - } - } + yang-version 1; + namespace "urn:opendaylight:test"; + prefix "tt"; + revision "2014-10-17"; + + container cont { + leaf l { + type string; + } + } } -Save this schema in file called test@2014-10-17.yang and store it a +Save this schema in file called ``test@2014-10-17.yang`` and store it a directory called test-schemas/, e.g., your home folder. Editing data for simulated device ''''''''''''''''''''''''''''''''' -- Start the device with following command: - - :: +- Start OpenDaylight - java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true --schemas-dir ~/test-schemas/ +- Install odl-netconf-topology and odl-restconf-nb features -- Start OpenDaylight +- Start the device with following command: -- Install odl-netconf-connector-all feature + :: -- Install odl-restconf feature + java -jar netconf-testtool-[VERSION]-executable.jar --controller-ip 127.0.0.1 --controller-port 8181 --debug true --schemas-dir ~/test-schemas/ -- Check that you can see config data for simulated device by executing - GET request to +- Check that you can see config data for simulated device by executing GET request to: :: - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/ + http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=17830-sim-device/yang-ext:mount?content=config - The data should be just and empty data container @@ -394,7 +396,7 @@ Editing data for simulated device :: - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount + http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=17830-sim-device/yang-ext:mount with headers: @@ -410,20 +412,21 @@ Editing data for simulated device Content +- Response should be 201 with empty body - Check that you can see modified config data for simulated device by executing GET request to :: - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/ + http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=17830-sim-device/yang-ext:mount?content=config - Check that you can see the same modified data in operational for simulated device by executing GET request to :: - http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/ + http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=17830-sim-device/yang-ext:mount?content=nonconfig .. warning:: @@ -440,52 +443,42 @@ with parameter ``--schemas-dir``. The input and output of the custom RPC should be provided with ``--rpc-config`` parameter as a path to the file containing definition of input and output. The format of the custom RPC file is xml as shown below. -Start the device with following command: - -:: - - java -jar netconf/tools/netconf-testtool/target/netconf-testtool-1.7.0-SNAPSHOT-executable.jar --schemas-dir ~/test-schemas/ --rpc-config ~/tmp/customrpc.xml --debug=true - -Example YANG model file: +Example YANG model file (stored in folder ~/test-schemas/): :: module example-ops { - namespace "urn:example-ops:reboot"; - prefix "ops"; + namespace "urn:example-ops:reboot"; + prefix "ops"; - import ietf-yang-types { + import ietf-yang-types { prefix "yang"; - } - - - revision "2016-07-07" { - description "Initial version."; - reference "example document."; - } - - - rpc reboot { - description "Reboot operation."; - input { - leaf delay { - type uint32; - units "seconds"; - default 0; - description - "Delay in seconds."; - } - leaf message { - type string; - description - "Log message."; - } - } - } - } + } + + revision "2016-07-07" { + description "Initial version."; + reference "example document."; + } + + rpc reboot { + description "Reboot operation."; + input { + leaf delay { + type uint32; + units "seconds"; + default 0; + description "Delay in seconds."; + } + leaf message { + type string; + description "Log message."; + } + } + } + } -Example payload (RPC config file customrpc.xml): +Example payload (RPC config file ~/tmp/customrpc.xml): :: @@ -505,15 +498,31 @@ Example payload (RPC config file customrpc.xml): +Start the device with following command: + +:: + + java -jar netconf-testtool-[VERSION]-executable.jar --controller-ip 127.0.0.1 --controller-port 8181 --schemas-dir ~/test-schemas/ --rpc-config ~/tmp/customrpc.xml --debug=true + Example of use: :: - POST http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/example-ops:get-reboot-info + POST http://localhost:8181/rests/operations/network-topology:network-topology/topology=topology-netconf/node=17830-sim-device/yang-ext:mount/example-ops:reboot + +With body: + +:: + + + + 300 + message + -If successful the command will return code 200. +If successful the response should be 204.