14 **NETCONF testtool is a set of standalone runnable jars that can:**
16 - Simulate NETCONF devices (suitable for scale testing)
18 - Stress/Performance test NETCONF devices
20 - Stress/Performance test RESTCONF devices
22 These jars are part of OpenDaylight’s controller project and are built
23 from the NETCONF codebase in OpenDaylight.
27 Download the Sodium SR2 testtool from OpenDaylight Nexus at:
28 https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.7.2/
30 **Nexus contains 3 executable tools:**
32 - executable.jar - device simulator
34 - stress.client.tar.gz - NETCONF stress/performance measuring tool
36 - perf-client.jar - RESTCONF stress/performance measuring tool
40 Each executable tool provides help. Just invoke ``java -jar
41 <name-of-the-tool.jar> --help``
43 NETCONF device simulator
44 ~~~~~~~~~~~~~~~~~~~~~~~~
46 NETCONF testtool (or NETCONF device simulator) is a tool that
48 - Simulates 1 or more NETCONF devices
50 - Is suitable for scale, performance or crud testing
52 - Uses core implementation of NETCONF server from OpenDaylight
54 - Generates configuration files for controller so that the OpenDaylight
55 distribution (Karaf) can easily connect to all simulated devices
57 - Provides broad configuration options
59 - Can start a fully fledged MD-SAL datastore
61 - Supports notifications
66 1. Check out latest NETCONF repository from
67 `git <https://git.opendaylight.org/gerrit/#/admin/projects/netconf>`__
69 2. Move into the ``opendaylight/netconf/tools/netconf-testtool/`` folder
71 3. Build testtool using the ``mvn clean install`` command
76 Netconf-testtool is now part of default maven build profile for
77 controller and can be also downloaded from nexus. The executable jars for
78 testtool can be found by release at this parent directory:
79 `nexus-artifacts <https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/>`__
84 1. After successfully building or downloading, move into the
85 ``opendaylight/netconf/tools/netconf-testtool/target/`` folder and
86 there is file ``netconf-testtool-1.1.0-SNAPSHOT-executable.jar`` (or
87 if downloaded from nexus just take that jar file)
89 2. Execute this file using, e.g.:
93 java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar
95 This execution runs the testtool with default for all parameters and
96 you should see this log output from the testtool :
100 10:31:08.206 [main] INFO o.o.c.n.t.t.NetconfDeviceSimulator - Starting 1, SSH simulated devices starting on port 17830
101 10:31:08.675 [main] INFO o.o.c.n.t.t.NetconfDeviceSimulator - All simulated devices started successfully from port 17830 to 17830
106 The default parameters for testtool are:
110 - Run 1 simulated device
112 - Device port is 17830
114 - YANG modules used by device are only: ietf-netconf-monitoring,
115 ietf-yang-types, ietf-inet-types (these modules are required for
116 device in order to support NETCONF monitoring and are included in the
119 - Connection timeout is set to 30 minutes (quite high, but when testing
120 with 10000 devices it might take some time for all of them to fully
121 establish a connection)
123 - Debug level is set to false
125 - No distribution is modified to connect automatically to the NETCONF
131 To verify that the simulated device is up and running, we can try to
132 connect to it using command line ssh tool. Execute this command to
133 connect to the device:
137 ssh admin@localhost -p 17830 -s netconf
139 Just accept the server with yes (if required) and provide any password
140 (testtool accepts all users with all passwords). You should see the
141 hello message sent by simulated device.
148 usage: netconf testtool [-h] [--edit-content EDIT-CONTENT] [--async-requests {true,false}] [--thread-amount THREAD-AMOUNT] [--throttle THROTTLE]
149 [--auth AUTH AUTH] [--controller-destination CONTROLLER-DESTINATION] [--device-count DEVICES-COUNT]
150 [--devices-per-port DEVICES-PER-PORT] [--schemas-dir SCHEMAS-DIR] [--notification-file NOTIFICATION-FILE]
151 [--initial-config-xml-file INITIAL-CONFIG-XML-FILE] [--starting-port STARTING-PORT]
152 [--generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT]
153 [--generate-config-address GENERATE-CONFIG-ADDRESS] [--generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE]
154 [--distribution-folder DISTRO-FOLDER] [--ssh {true,false}] [--exi {true,false}] [--debug {true,false}]
155 [--md-sal {true,false}] [--time-out TIME-OUT] [-ip IP] [--thread-pool-size THREAD-POOL-SIZE] [--rpc-config RPC-CONFIG]
160 -h, --help show this help message and exit
161 --edit-content EDIT-CONTENT
162 --async-requests {true,false}
163 --thread-amount THREAD-AMOUNT
164 The number of threads to use for configuring devices.
165 --throttle THROTTLE Maximum amount of async requests that can be open at a time, with mutltiple threads this gets divided among all threads
166 --auth AUTH AUTH Username and password for HTTP basic authentication in order username password.
167 --controller-destination CONTROLLER-DESTINATION
168 Ip address and port of controller. Must be in following format <ip>:<port> if available it will be used for spawning
169 netconf connectors via topology configuration as a part of URI. Example (http://<controller
170 destination>/restconf/config/network-topology:network-topology/topology/topology-netconf/node/<node-id>)otherwise it will
171 just start simulated devices and skip the execution of PUT requests
172 --device-count DEVICES-COUNT
173 Number of simulated netconf devices to spin. This is the number of actual ports open for the devices.
174 --devices-per-port DEVICES-PER-PORT
175 Amount of config files generated per port to spoof more devices than are actually running
176 --schemas-dir SCHEMAS-DIR
177 Directory containing yang schemas to describe simulated devices. Some schemas e.g. netconf monitoring and inet types are
179 --notification-file NOTIFICATION-FILE
180 Xml file containing notifications that should be sent to clients after create subscription is called
181 --initial-config-xml-file INITIAL-CONFIG-XML-FILE
182 Xml file containing initial simulatted configuration to be returned via get-config rpc
183 --starting-port STARTING-PORT
184 First port for simulated device. Each other device will have previous+1 port number
185 --generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT
186 Timeout to be generated in initial config files
187 --generate-config-address GENERATE-CONFIG-ADDRESS
188 Address to be placed in generated configs
189 --generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE
190 Number of connector configs per generated file
191 --distribution-folder DISTRO-FOLDER
192 Directory where the karaf distribution for controller is located
193 --ssh {true,false} Whether to use ssh for transport or just pure tcp
194 --exi {true,false} Whether to use exi to transport xml content
195 --debug {true,false} Whether to use debug log level instead of INFO
196 --md-sal {true,false} Whether to use md-sal datastore instead of default simulated datastore.
197 --time-out TIME-OUT the maximum time in seconds for executing each PUT request
198 -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
199 textual representation of its IP address.
200 --thread-pool-size THREAD-POOL-SIZE
201 The number of threads to keep in the pool, when creating a device simulator. Even if they are idle.
202 --rpc-config RPC-CONFIG
203 Rpc config file. It can be used to define custom rpc behavior, or override the default one.Usable for testing buggy device
210 Testtool default simple datastore supported operations:
213 returns YANG schemas loaded from user specified directory,
216 always returns OK and stores the XML from the input in a local
217 variable available for get-config and get RPC. Every edit-config
218 replaces the previous data,
221 always returns OK, but does not actually commit the data,
224 returns local XML stored by edit-config,
227 returns local XML stored by edit-config with netconf-state subtree,
228 but also supports filtering.
231 returns always OK with no lock guarantee
234 returns always OK and after the operation is triggered, provided
235 NETCONF notifications (if any) are fed to the client. No filtering
236 or stream recognition is supported.
238 Note: when operation="delete" is present in the payload for edit-config,
239 it will wipe its local store to simulate the removal of data.
241 When using the MD-SAL datastore testtool behaves more like normal
242 NETCONF server and is suitable for crud testing. create-subscription is
243 not supported when testtool is running with the MD-SAL datastore.
248 Testtool supports notifications via the --notification-file switch. To
249 trigger the notification feed, create-subscription operation has to be
250 invoked. The XML file provided should look like this example file:
254 <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
257 <!-- Notifications are processed in the order they are defined in XML -->
259 <!-- Notification that is sent only once right after create-subscription is called -->
261 <!-- Content of each notification entry must contain the entire notification with event time. Event time can be hardcoded, or generated by testtool if XXXX is set as eventtime in this XML -->
263 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
264 <eventTime>2011-01-04T12:30:46</eventTime>
265 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
266 <random-content>single no delay</random-content>
267 </random-notification>
272 <!-- Repeated Notification that is sent 5 times with 2 second delay inbetween -->
274 <!-- Delay in seconds from previous notification -->
276 <!-- Number of times this notification should be repeated -->
279 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
280 <eventTime>XXXX</eventTime>
281 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
282 <random-content>scheduled 5 times 10 seconds each</random-content>
283 </random-notification>
288 <!-- Single notification that is sent only once right after the previous notification -->
292 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
293 <eventTime>XXXX</eventTime>
294 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
295 <random-content>single with delay</random-content>
296 </random-notification>
303 Connecting testtool with controller Karaf distribution
304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
306 Auto connect to OpenDaylight
307 ''''''''''''''''''''''''''''
309 It is possible to make OpenDaylight auto connect to the simulated
310 devices spawned by testtool (so user does not have to post a
311 configuration for every NETCONF connector via RESTCONF). The testtool is
312 able to modify the OpenDaylight distribution to auto connect to the
313 simulated devices after feature ``odl-netconf-connector-all`` is
314 installed. When running testtool, issue this command (just point the
315 testool to the distribution:
319 java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true
321 With the distribution-folder parameter, the testtool will modify the
322 distribution to include configuration for netconf-connector to connect
323 to all simulated devices. So there is no need to spawn
324 netconf-connectors via RESTCONF.
326 Running testtool and OpenDaylight on different machines
327 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
329 The testtool binds by default to 0.0.0.0 so it should be accessible from
330 remote machines. However you need to set the parameter
331 "generate-config-address" (when using autoconnect) to the address of
332 machine where testtool will be run so OpenDaylight can connect. The
333 default value is localhost.
335 Executing operations via RESTCONF on a mounted simulated device
336 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
338 Simulated devices support basic RPCs for editing their config. This part
339 shows how to edit data for simulated device via RESTCONF.
344 The controller and RESTCONF assume that the data that can be manipulated
345 for mounted device is described by a YANG schema. For demonstration, we
346 will define a simple YANG model:
352 namespace "urn:opendaylight:test";
355 revision "2014-10-17";
366 Save this schema in file called test@2014-10-17.yang and store it a
367 directory called test-schemas/, e.g., your home folder.
369 Editing data for simulated device
370 '''''''''''''''''''''''''''''''''
372 - Start the device with following command:
376 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/
380 - Install odl-netconf-connector-all feature
382 - Install odl-restconf feature
384 - Check that you can see config data for simulated device by executing
389 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
391 - The data should be just and empty data container
393 - Now execute edit-config request by executing a POST request to:
397 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount
403 Accept application/xml
404 Content-Type application/xml
410 <cont xmlns="urn:opendaylight:test">
414 - Check that you can see modified config data for simulated device by
415 executing GET request to
419 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
421 - Check that you can see the same modified data in operational for
422 simulated device by executing GET request to
426 http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
430 Data will be mirrored in operational datastore only when using the
431 default simple datastore.
434 Testing User defined RPC
435 ^^^^^^^^^^^^^^^^^^^^^^^^
437 The NETCONF test-tool allows using custom RPC. Custom RPC needs to be defined in yang model provide to test-tool along
438 with parameter ``--schemas-dir``.
440 The input and output of the custom RPC should be provided with ``--rpc-config`` parameter as a path to the file containing
441 definition of input and output. The format of the custom RPC file is xml as shown below.
443 Start the device with following command:
447 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
449 Example YANG model file:
454 namespace "urn:example-ops:reboot";
457 import ietf-yang-types {
462 revision "2016-07-07" {
463 description "Initial version.";
464 reference "example document.";
469 description "Reboot operation.";
488 Example payload (RPC config file customrpc.xml):
495 <reboot xmlns="urn:example-ops:reboot">
497 <message>message</message>
501 <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
514 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
516 If successful the command will return code 200.
522 A working example of user defined RPC can be found in TestToolTest.java class of the tools[netconf-testtool] project.
528 Slow creation of devices on virtual machines
529 ''''''''''''''''''''''''''''''''''''''''''''
531 When testtool seems to take unusually long time to create the devices
532 use this flag when running it:
536 -Dorg.apache.sshd.registerBouncyCastle=false
541 When testtool or OpenDaylight starts to fail with TooManyFilesOpen
542 exception, you need to increase the limit of open files in your OS. To
543 find out the limit in linux execute:
549 Example sufficient configuration in linux:
553 core file size (blocks, -c) 0
554 data seg size (kbytes, -d) unlimited
555 scheduling priority (-e) 0
556 file size (blocks, -f) unlimited
557 pending signals (-i) 63338
558 max locked memory (kbytes, -l) 64
559 max memory size (kbytes, -m) unlimited
560 open files (-n) 500000
561 pipe size (512 bytes, -p) 8
562 POSIX message queues (bytes, -q) 819200
563 real-time priority (-r) 0
564 stack size (kbytes, -s) 8192
565 cpu time (seconds, -t) unlimited
566 max user processes (-u) 63338
567 virtual memory (kbytes, -v) unlimited
568 file locks (-x) unlimited
570 To set these limits edit file: /etc/security/limits.conf, for example:
576 root hard nofile 500000
577 root soft nofile 500000
582 The testtool might end unexpectedly with a simple message: "Killed".
583 This means that the OS killed the tool due to too much memory consumed
584 or too many threads spawned. To find out the reason on linux you can use
589 dmesg | egrep -i -B100 'killed process'
591 Also take a look at this file: /proc/sys/kernel/threads-max. It limits
592 the number of threads spawned by a process. Sufficient (but probably
593 much more than enough) value is, e.g., 126676