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}]
 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]
 164
 165     netconf testtool
 166
 167     named arguments:
 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
 194                              actually running
 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
 203                              get-config rpc
 204       --starting-port STARTING-PORT
 205                              First port for simulated device.  Each  other  device will have previous+1
 206                              port number
 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
 222                              its IP address.
 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.
 229
 230
 231
 232 Supported operations
 233 ^^^^^^^^^^^^^^^^^^^^
 234
 235 Testtool default simple datastore supported operations:
 236
 237 get-schema
 238     returns YANG schemas loaded from user specified directory,
 239
 240 edit-config
 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,
 244
 245 commit
 246     always returns OK, but does not actually commit the data,
 247
 248 get-config
 249     returns local XML stored by edit-config,
 250
 251 get
 252     returns local XML stored by edit-config with netconf-state subtree,
 253     but also supports filtering.
 254
 255 (un)lock
 256     returns always OK with no lock guarantee
 257
 258 create-subscription
 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.
 262
 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.
 265
 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.
 269
 270 Notification support
 271 ^^^^^^^^^^^^^^^^^^^^
 272
 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:
 276
 277 ::
 278
 279     <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
 280     <notifications>
 281
 282     <!-- Notifications are processed in the order they are defined in XML -->
 283
 284     <!-- Notification that is sent only once right after create-subscription is called -->
 285     <notification>
 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 -->
 287         <content><![CDATA[
 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>
 293             </notification>
 294         ]]></content>
 295     </notification>
 296
 297     <!-- Repeated Notification that is sent 5 times with 2 second delay inbetween -->
 298     <notification>
 299         <!-- Delay in seconds from previous notification -->
 300         <delay>2</delay>
 301         <!-- Number of times this notification should be repeated -->
 302         <times>5</times>
 303         <content><![CDATA[
 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>
 309             </notification>
 310         ]]></content>
 311     </notification>
 312
 313     <!-- Single notification that is sent only once right after the previous notification -->
 314     <notification>
 315         <delay>2</delay>
 316         <content><![CDATA[
 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>
 322             </notification>
 323         ]]></content>
 324     </notification>
 325
 326     </notifications>
 327
 328 Connecting testtool with controller Karaf distribution
 329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 330
 331 Auto connect to OpenDaylight
 332 ''''''''''''''''''''''''''''
 333
 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:
 341
 342 ::
 343
 344     java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true
 345
 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.
 350
 351 Running testtool and OpenDaylight on different machines
 352 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 353
 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.
 359
 360 Executing operations via RESTCONF on a mounted simulated device
 361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 362
 363 Simulated devices support basic RPCs for editing their config. This part
 364 shows how to edit data for simulated device via RESTCONF.
 365
 366 Test YANG schema
 367 ''''''''''''''''
 368
 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:
 372
 373 ::
 374
 375     module test {
 376         yang-version 1;
 377         namespace "urn:opendaylight:test";
 378         prefix "tt";
 379
 380         revision "2014-10-17";
 381
 382
 383        container cont {
 384
 385             leaf l {
 386                 type string;
 387             }
 388        }
 389     }
 390
 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.
 393
 394 Editing data for simulated device
 395 '''''''''''''''''''''''''''''''''
 396
 397 -  Start the device with following command:
 398
 399    ::
 400
 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/
 402
 403 -  Start OpenDaylight
 404
 405 -  Install odl-netconf-connector-all feature
 406
 407 -  Install odl-restconf feature
 408
 409 -  Check that you can see config data for simulated device by executing
 410    GET request to
 411
 412    ::
 413
 414        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 415
 416 -  The data should be just and empty data container
 417
 418 -  Now execute edit-config request by executing a POST request to:
 419
 420    ::
 421
 422        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount
 423
 424    with headers:
 425
 426    ::
 427
 428        Accept application/xml
 429        Content-Type application/xml
 430
 431    and payload:
 432
 433    ::
 434
 435        <cont xmlns="urn:opendaylight:test">
 436          <l>Content</l>
 437        </cont>
 438
 439 -  Check that you can see modified config data for simulated device by
 440    executing GET request to
 441
 442    ::
 443
 444        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 445
 446 -  Check that you can see the same modified data in operational for
 447    simulated device by executing GET request to
 448
 449    ::
 450
 451        http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 452
 453 .. warning::
 454
 455     Data will be mirrored in operational datastore only when using the
 456     default simple datastore.
 457
 458
 459 Testing User defined RPC
 460 ^^^^^^^^^^^^^^^^^^^^^^^^
 461
 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``.
 464
 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.
 467
 468 Start the device with following command:
 469
 470 ::
 471
 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
 473
 474 Example YANG model file:
 475
 476 ::
 477
 478     module example-ops {
 479          namespace "urn:example-ops:reboot";
 480          prefix "ops";
 481
 482         import ietf-yang-types {
 483         prefix "yang";
 484          }
 485
 486
 487          revision "2016-07-07" {
 488            description "Initial version.";
 489            reference "example document.";
 490          }
 491
 492
 493          rpc reboot {
 494            description "Reboot operation.";
 495            input {
 496              leaf delay {
 497                type uint32;
 498                units "seconds";
 499                default 0;
 500                description
 501                  "Delay in seconds.";
 502              }
 503              leaf message {
 504                type string;
 505                description
 506                  "Log message.";
 507              }
 508            }
 509          }
 510        }
 511
 512
 513 Example payload (RPC config file customrpc.xml):
 514
 515 ::
 516
 517     <rpcs>
 518       <rpc>
 519         <input>
 520           <reboot xmlns="urn:example-ops:reboot">
 521             <delay>300</delay>
 522             <message>message</message>
 523           </reboot>
 524         </input>
 525         <output>
 526           <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 527             <ok/>
 528           </rpc-reply>
 529         </output>
 530       </rpc>
 531     </rpcs>
 532
 533
 534
 535 Example of use:
 536
 537 ::
 538
 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
 540
 541 If successful the command will return code 200.
 542
 543
 544
 545 .. note::
 546
 547     A working example of user defined RPC can be found in TestToolTest.java class of the tools[netconf-testtool] project.
 548
 549
 550 Known problems
 551 ^^^^^^^^^^^^^^
 552
 553 Slow creation of devices on virtual machines
 554 ''''''''''''''''''''''''''''''''''''''''''''
 555
 556 When testtool seems to take unusually long time to create the devices
 557 use this flag when running it:
 558
 559 ::
 560
 561     -Dorg.apache.sshd.registerBouncyCastle=false
 562
 563 Too many files open
 564 '''''''''''''''''''
 565
 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:
 569
 570 ::
 571
 572     ulimit -a
 573
 574 Example sufficient configuration in linux:
 575
 576 ::
 577
 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
 594
 595 To set these limits edit file: /etc/security/limits.conf, for example:
 596
 597 ::
 598
 599     *         hard    nofile      500000
 600     *         soft    nofile      500000
 601     root      hard    nofile      500000
 602     root      soft    nofile      500000
 603
 604 "Killed"
 605 ''''''''
 606
 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
 610 following command:
 611
 612 ::
 613
 614     dmesg | egrep -i -B100 'killed process'
 615
 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