docs/testtool.rst

   1 .. _testtool:
   2
   3 .. |ss| raw:: html
   4
   5    <strike>
   6
   7 .. |se| raw:: html
   8
   9    </strike>
  10
  11 NETCONF testtool
  12 ----------------
  13
  14 **NETCONF testtool is a set of standalone runnable jars that can:**
  15
  16 -  Simulate NETCONF devices (suitable for scale testing)
  17
  18 -  Stress/Performance test NETCONF devices
  19
  20 -  Stress/Performance test RESTCONF devices
  21
  22 These jars are part of OpenDaylight’s controller project and are built
  23 from the NETCONF codebase in OpenDaylight.
  24
  25 .. tip::
  26
  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/
  29
  30 **Nexus contains 3 executable tools:**
  31
  32 -  executable.jar - device simulator
  33
  34 -  stress.client.tar.gz - NETCONF stress/performance measuring tool
  35
  36 -  perf-client.jar - RESTCONF stress/performance measuring tool
  37
  38 .. tip::
  39
  40     Each executable tool provides help. Just invoke ``java -jar
  41     <name-of-the-tool.jar> --help``
  42
  43 NETCONF device simulator
  44 ~~~~~~~~~~~~~~~~~~~~~~~~
  45
  46 NETCONF testtool (or NETCONF device simulator) is a tool that
  47
  48 -  Simulates 1 or more NETCONF devices
  49
  50 -  Is suitable for scale, performance or crud testing
  51
  52 -  Uses core implementation of NETCONF server from OpenDaylight
  53
  54 -  Generates configuration files for controller so that the OpenDaylight
  55    distribution (Karaf) can easily connect to all simulated devices
  56
  57 -  Provides broad configuration options
  58
  59 -  Can start a fully fledged MD-SAL datastore
  60
  61 -  Supports notifications
  62
  63 Building testtool
  64 ^^^^^^^^^^^^^^^^^
  65
  66 1. Check out latest NETCONF repository from
  67    `git <https://git.opendaylight.org/gerrit/admin/repos/netconf>`__
  68
  69 2. Move into the ``opendaylight/netconf/tools/netconf-testtool/`` folder
  70
  71 3. Build testtool using the ``mvn clean install`` command
  72
  73 Downloading testtool
  74 ^^^^^^^^^^^^^^^^^^^^
  75
  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/>`__
  80
  81 Running testtool
  82 ^^^^^^^^^^^^^^^^
  83
  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)
  88
  89 2. Execute this file using, e.g.:
  90
  91    ::
  92
  93        java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar
  94
  95    This execution runs the testtool with default for all parameters and
  96    you should see this log output from the testtool :
  97
  98    ::
  99
 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
 102
 103 Default Parameters
 104 ''''''''''''''''''
 105
 106 The default parameters for testtool are:
 107
 108 -  Use SSH
 109
 110 -  Run 1 simulated device
 111
 112 -  Device port is 17830
 113
 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
 117    netconf-testtool)
 118
 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)
 122
 123 -  Debug level is set to false
 124
 125 -  No distribution is modified to connect automatically to the NETCONF
 126    testtool
 127
 128 Verifying testtool
 129 ^^^^^^^^^^^^^^^^^^
 130
 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:
 134
 135 ::
 136
 137     ssh admin@localhost -p 17830 -s netconf
 138
 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.
 142
 143 Testtool help
 144 ^^^^^^^^^^^^^
 145
 146 ::
 147
 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]
 156
 157     netconf testtool
 158
 159     named arguments:
 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
 178                              included by default
 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
 204                              behavior.
 205
 206
 207 Supported operations
 208 ^^^^^^^^^^^^^^^^^^^^
 209
 210 Testtool default simple datastore supported operations:
 211
 212 get-schema
 213     returns YANG schemas loaded from user specified directory,
 214
 215 edit-config
 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,
 219
 220 commit
 221     always returns OK, but does not actually commit the data,
 222
 223 get-config
 224     returns local XML stored by edit-config,
 225
 226 get
 227     returns local XML stored by edit-config with netconf-state subtree,
 228     but also supports filtering.
 229
 230 (un)lock
 231     returns always OK with no lock guarantee
 232
 233 create-subscription
 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.
 237
 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.
 240
 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.
 244
 245 Notification support
 246 ^^^^^^^^^^^^^^^^^^^^
 247
 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:
 251
 252 ::
 253
 254     <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
 255     <notifications>
 256
 257     <!-- Notifications are processed in the order they are defined in XML -->
 258
 259     <!-- Notification that is sent only once right after create-subscription is called -->
 260     <notification>
 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 -->
 262         <content><![CDATA[
 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>
 268             </notification>
 269         ]]></content>
 270     </notification>
 271
 272     <!-- Repeated Notification that is sent 5 times with 2 second delay inbetween -->
 273     <notification>
 274         <!-- Delay in seconds from previous notification -->
 275         <delay>2</delay>
 276         <!-- Number of times this notification should be repeated -->
 277         <times>5</times>
 278         <content><![CDATA[
 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>
 284             </notification>
 285         ]]></content>
 286     </notification>
 287
 288     <!-- Single notification that is sent only once right after the previous notification -->
 289     <notification>
 290         <delay>2</delay>
 291         <content><![CDATA[
 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>
 297             </notification>
 298         ]]></content>
 299     </notification>
 300
 301     </notifications>
 302
 303 Connecting testtool with controller Karaf distribution
 304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 305
 306 Auto connect to OpenDaylight
 307 ''''''''''''''''''''''''''''
 308
 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:
 316
 317 ::
 318
 319     java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true
 320
 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.
 325
 326 Running testtool and OpenDaylight on different machines
 327 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 328
 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.
 334
 335 Executing operations via RESTCONF on a mounted simulated device
 336 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 337
 338 Simulated devices support basic RPCs for editing their config. This part
 339 shows how to edit data for simulated device via RESTCONF.
 340
 341 Test YANG schema
 342 ''''''''''''''''
 343
 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:
 347
 348 ::
 349
 350     module test {
 351         yang-version 1;
 352         namespace "urn:opendaylight:test";
 353         prefix "tt";
 354
 355         revision "2014-10-17";
 356
 357
 358        container cont {
 359
 360             leaf l {
 361                 type string;
 362             }
 363        }
 364     }
 365
 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.
 368
 369 Editing data for simulated device
 370 '''''''''''''''''''''''''''''''''
 371
 372 -  Start the device with following command:
 373
 374    ::
 375
 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/
 377
 378 -  Start OpenDaylight
 379
 380 -  Install odl-netconf-connector-all feature
 381
 382 -  Install odl-restconf feature
 383
 384 -  Check that you can see config data for simulated device by executing
 385    GET request to
 386
 387    ::
 388
 389        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 390
 391 -  The data should be just and empty data container
 392
 393 -  Now execute edit-config request by executing a POST request to:
 394
 395    ::
 396
 397        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount
 398
 399    with headers:
 400
 401    ::
 402
 403        Accept application/xml
 404        Content-Type application/xml
 405
 406    and payload:
 407
 408    ::
 409
 410        <cont xmlns="urn:opendaylight:test">
 411          <l>Content</l>
 412        </cont>
 413
 414 -  Check that you can see modified config data for simulated device by
 415    executing GET request to
 416
 417    ::
 418
 419        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 420
 421 -  Check that you can see the same modified data in operational for
 422    simulated device by executing GET request to
 423
 424    ::
 425
 426        http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 427
 428 .. warning::
 429
 430     Data will be mirrored in operational datastore only when using the
 431     default simple datastore.
 432
 433
 434 Testing User defined RPC
 435 ^^^^^^^^^^^^^^^^^^^^^^^^
 436
 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``.
 439
 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.
 442
 443 Start the device with following command:
 444
 445 ::
 446
 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
 448
 449 Example YANG model file:
 450
 451 ::
 452
 453     module example-ops {
 454          namespace "urn:example-ops:reboot";
 455          prefix "ops";
 456
 457         import ietf-yang-types {
 458         prefix "yang";
 459          }
 460
 461
 462          revision "2016-07-07" {
 463            description "Initial version.";
 464            reference "example document.";
 465          }
 466
 467
 468          rpc reboot {
 469            description "Reboot operation.";
 470            input {
 471              leaf delay {
 472                type uint32;
 473                units "seconds";
 474                default 0;
 475                description
 476                  "Delay in seconds.";
 477              }
 478              leaf message {
 479                type string;
 480                description
 481                  "Log message.";
 482              }
 483            }
 484          }
 485        }
 486
 487
 488 Example payload (RPC config file customrpc.xml):
 489
 490 ::
 491
 492     <rpcs>
 493       <rpc>
 494         <input>
 495           <reboot xmlns="urn:example-ops:reboot">
 496             <delay>300</delay>
 497             <message>message</message>
 498           </reboot>
 499         </input>
 500         <output>
 501           <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 502             <ok/>
 503           </rpc-reply>
 504         </output>
 505       </rpc>
 506     </rpcs>
 507
 508
 509
 510 Example of use:
 511
 512 ::
 513
 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
 515
 516 If successful the command will return code 200.
 517
 518
 519
 520 .. note::
 521
 522     A working example of user defined RPC can be found in TestToolTest.java class of the tools[netconf-testtool] project.
 523
 524
 525 Known problems
 526 ^^^^^^^^^^^^^^
 527
 528 Slow creation of devices on virtual machines
 529 ''''''''''''''''''''''''''''''''''''''''''''
 530
 531 When testtool seems to take unusually long time to create the devices
 532 use this flag when running it:
 533
 534 ::
 535
 536     -Dorg.apache.sshd.registerBouncyCastle=false
 537
 538 Too many files open
 539 '''''''''''''''''''
 540
 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:
 544
 545 ::
 546
 547     ulimit -a
 548
 549 Example sufficient configuration in linux:
 550
 551 ::
 552
 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
 569
 570 To set these limits edit file: /etc/security/limits.conf, for example:
 571
 572 ::
 573
 574     *         hard    nofile      500000
 575     *         soft    nofile      500000
 576     root      hard    nofile      500000
 577     root      soft    nofile      500000
 578
 579 "Killed"
 580 ''''''''
 581
 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
 585 following command:
 586
 587 ::
 588
 589     dmesg | egrep -i -B100 'killed process'
 590
 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