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/repos/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}]
149 [--thread-amount THREAD-AMOUNT] [--throttle THROTTLE]
150 [--controller-auth-username CONTROLLER-AUTH-USERNAME]
151 [--controller-auth-password CONTROLLER-AUTH-PASSWORD]
152 [--controller-ip CONTROLLER-IP] [--controller-port CONTROLLER-PORT]
153 [--device-count DEVICES-COUNT] [--devices-per-port DEVICES-PER-PORT]
154 [--schemas-dir SCHEMAS-DIR] [--notification-file NOTIFICATION-FILE]
155 [--initial-config-xml-file INITIAL-CONFIG-XML-FILE]
156 [--starting-port STARTING-PORT]
157 [--generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT]
158 [--generate-config-address GENERATE-CONFIG-ADDRESS]
159 [--generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE]
160 [--distribution-folder DISTRO-FOLDER] [--ssh {true,false}]
161 [--exi {true,false}] [--debug {true,false}] [--md-sal {true,false}]
162 [--time-out TIME-OUT] [-ip IP] [--thread-pool-size THREAD-POOL-SIZE]
163 [--rpc-config RPC-CONFIG]
168 -h, --help show this help message and exit
169 --edit-content EDIT-CONTENT
170 --async-requests {true,false}
171 --thread-amount THREAD-AMOUNT
172 The number of threads to use for configuring devices.
173 --throttle THROTTLE Maximum amount of async requests that can be open at a time, with
174 mutltiple threads this gets divided among all threads
175 --controller-auth-username CONTROLLER-AUTH-USERNAME
176 Username for HTTP basic authentication to destination controller.
177 --controller-auth-password CONTROLLER-AUTH-PASSWORD
178 Password for HTTP basic authentication to destination controller.
179 --controller-ip CONTROLLER-IP
180 Ip of controller if available it will be used for spawning netconf
181 connectors via topology configuration as a part of URI(http://<controller-
182 ip>:<controller-port>/restconf/config/...) otherwise it will just start
183 simulated devices and skip the execution of PATCH requests
184 --controller-port CONTROLLER-PORT
185 Port of controller if available it will be used for spawning netconf
186 connectors via topology configuration as a part of URI(http://<controller-
187 ip>:<controller-port>/restconf/config/...) otherwise it will just start
188 simulated devices and skip the execution of PATCH requests
189 --device-count DEVICES-COUNT
190 Number of simulated netconf devices to spin. This is the number of actual
191 ports open for the devices.
192 --devices-per-port DEVICES-PER-PORT
193 Amount of config files generated per port to spoof more devices than are
195 --schemas-dir SCHEMAS-DIR
196 Directory containing yang schemas to describe simulated devices. Some
197 schemas e.g. netconf monitoring and inet types are included by default
198 --notification-file NOTIFICATION-FILE
199 Xml file containing notifications that should be sent to clients after
200 create subscription is called
201 --initial-config-xml-file INITIAL-CONFIG-XML-FILE
202 Xml file containing initial simulatted configuration to be returned via
204 --starting-port STARTING-PORT
205 First port for simulated device. Each other device will have previous+1
207 --generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT
208 Timeout to be generated in initial config files
209 --generate-config-address GENERATE-CONFIG-ADDRESS
210 Address to be placed in generated configs
211 --generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE
212 Number of connector configs per generated file
213 --distribution-folder DISTRO-FOLDER
214 Directory where the karaf distribution for controller is located
215 --ssh {true,false} Whether to use ssh for transport or just pure tcp
216 --exi {true,false} Whether to use exi to transport xml content
217 --debug {true,false} Whether to use debug log level instead of INFO
218 --md-sal {true,false} Whether to use md-sal datastore instead of default simulated datastore.
219 --time-out TIME-OUT the maximum time in seconds for executing each PATCH request
220 -ip IP Ip address which will be used for creating a socket address.It can either
221 be a machine name, such as java.sun.com, or a textual representation of
223 --thread-pool-size THREAD-POOL-SIZE
224 The number of threads to keep in the pool, when creating a device
225 simulator. Even if they are idle.
226 --rpc-config RPC-CONFIG
227 Rpc config file. It can be used to define custom rpc behavior, or
228 override the default one.Usable for testing buggy device behavior.
235 Testtool default simple datastore supported operations:
238 returns YANG schemas loaded from user specified directory,
241 always returns OK and stores the XML from the input in a local
242 variable available for get-config and get RPC. Every edit-config
243 replaces the previous data,
246 always returns OK, but does not actually commit the data,
249 returns local XML stored by edit-config,
252 returns local XML stored by edit-config with netconf-state subtree,
253 but also supports filtering.
256 returns always OK with no lock guarantee
259 returns always OK and after the operation is triggered, provided
260 NETCONF notifications (if any) are fed to the client. No filtering
261 or stream recognition is supported.
263 Note: when operation="delete" is present in the payload for edit-config,
264 it will wipe its local store to simulate the removal of data.
266 When using the MD-SAL datastore testtool behaves more like normal
267 NETCONF server and is suitable for crud testing. create-subscription is
268 not supported when testtool is running with the MD-SAL datastore.
273 Testtool supports notifications via the --notification-file switch. To
274 trigger the notification feed, create-subscription operation has to be
275 invoked. The XML file provided should look like this example file:
279 <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
282 <!-- Notifications are processed in the order they are defined in XML -->
284 <!-- Notification that is sent only once right after create-subscription is called -->
286 <!-- 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 -->
288 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
289 <eventTime>2011-01-04T12:30:46</eventTime>
290 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
291 <random-content>single no delay</random-content>
292 </random-notification>
297 <!-- Repeated Notification that is sent 5 times with 2 second delay inbetween -->
299 <!-- Delay in seconds from previous notification -->
301 <!-- Number of times this notification should be repeated -->
304 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
305 <eventTime>XXXX</eventTime>
306 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
307 <random-content>scheduled 5 times 10 seconds each</random-content>
308 </random-notification>
313 <!-- Single notification that is sent only once right after the previous notification -->
317 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
318 <eventTime>XXXX</eventTime>
319 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
320 <random-content>single with delay</random-content>
321 </random-notification>
328 Connecting testtool with controller Karaf distribution
329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
331 Auto connect to OpenDaylight
332 ''''''''''''''''''''''''''''
334 It is possible to make OpenDaylight auto connect to the simulated
335 devices spawned by testtool (so user does not have to post a
336 configuration for every NETCONF connector via RESTCONF). The testtool is
337 able to modify the OpenDaylight distribution to auto connect to the
338 simulated devices after feature ``odl-netconf-connector-all`` is
339 installed. When running testtool, issue this command (just point the
340 testool to the distribution:
344 java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true
346 With the distribution-folder parameter, the testtool will modify the
347 distribution to include configuration for netconf-connector to connect
348 to all simulated devices. So there is no need to spawn
349 netconf-connectors via RESTCONF.
351 Running testtool and OpenDaylight on different machines
352 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
354 The testtool binds by default to 0.0.0.0 so it should be accessible from
355 remote machines. However you need to set the parameter
356 "generate-config-address" (when using autoconnect) to the address of
357 machine where testtool will be run so OpenDaylight can connect. The
358 default value is localhost.
360 Executing operations via RESTCONF on a mounted simulated device
361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
363 Simulated devices support basic RPCs for editing their config. This part
364 shows how to edit data for simulated device via RESTCONF.
369 The controller and RESTCONF assume that the data that can be manipulated
370 for mounted device is described by a YANG schema. For demonstration, we
371 will define a simple YANG model:
377 namespace "urn:opendaylight:test";
380 revision "2014-10-17";
391 Save this schema in file called test@2014-10-17.yang and store it a
392 directory called test-schemas/, e.g., your home folder.
394 Editing data for simulated device
395 '''''''''''''''''''''''''''''''''
397 - Start the device with following command:
401 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/
405 - Install odl-netconf-connector-all feature
407 - Install odl-restconf feature
409 - Check that you can see config data for simulated device by executing
414 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
416 - The data should be just and empty data container
418 - Now execute edit-config request by executing a POST request to:
422 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount
428 Accept application/xml
429 Content-Type application/xml
435 <cont xmlns="urn:opendaylight:test">
439 - Check that you can see modified config data for simulated device by
440 executing GET request to
444 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
446 - Check that you can see the same modified data in operational for
447 simulated device by executing GET request to
451 http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
455 Data will be mirrored in operational datastore only when using the
456 default simple datastore.
459 Testing User defined RPC
460 ^^^^^^^^^^^^^^^^^^^^^^^^
462 The NETCONF test-tool allows using custom RPC. Custom RPC needs to be defined in yang model provide to test-tool along
463 with parameter ``--schemas-dir``.
465 The input and output of the custom RPC should be provided with ``--rpc-config`` parameter as a path to the file containing
466 definition of input and output. The format of the custom RPC file is xml as shown below.
468 Start the device with following command:
472 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
474 Example YANG model file:
479 namespace "urn:example-ops:reboot";
482 import ietf-yang-types {
487 revision "2016-07-07" {
488 description "Initial version.";
489 reference "example document.";
494 description "Reboot operation.";
513 Example payload (RPC config file customrpc.xml):
520 <reboot xmlns="urn:example-ops:reboot">
522 <message>message</message>
526 <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
539 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
541 If successful the command will return code 200.
547 A working example of user defined RPC can be found in TestToolTest.java class of the tools[netconf-testtool] project.
553 Slow creation of devices on virtual machines
554 ''''''''''''''''''''''''''''''''''''''''''''
556 When testtool seems to take unusually long time to create the devices
557 use this flag when running it:
561 -Dorg.apache.sshd.registerBouncyCastle=false
566 When testtool or OpenDaylight starts to fail with TooManyFilesOpen
567 exception, you need to increase the limit of open files in your OS. To
568 find out the limit in linux execute:
574 Example sufficient configuration in linux:
578 core file size (blocks, -c) 0
579 data seg size (kbytes, -d) unlimited
580 scheduling priority (-e) 0
581 file size (blocks, -f) unlimited
582 pending signals (-i) 63338
583 max locked memory (kbytes, -l) 64
584 max memory size (kbytes, -m) unlimited
585 open files (-n) 500000
586 pipe size (512 bytes, -p) 8
587 POSIX message queues (bytes, -q) 819200
588 real-time priority (-r) 0
589 stack size (kbytes, -s) 8192
590 cpu time (seconds, -t) unlimited
591 max user processes (-u) 63338
592 virtual memory (kbytes, -v) unlimited
593 file locks (-x) unlimited
595 To set these limits edit file: /etc/security/limits.conf, for example:
601 root hard nofile 500000
602 root soft nofile 500000
607 The testtool might end unexpectedly with a simple message: "Killed".
608 This means that the OS killed the tool due to too much memory consumed
609 or too many threads spawned. To find out the reason on linux you can use
614 dmesg | egrep -i -B100 'killed process'
616 Also take a look at this file: /proc/sys/kernel/threads-max. It limits
617 the number of threads spawned by a process. Sufficient (but probably
618 much more than enough) value is, e.g., 126676