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] [--controller-ip CONTROLLER-IP]
 152                             [--controller-port CONTROLLER-PORT] [--device-count DEVICES-COUNT]
 153                             [--devices-per-port DEVICES-PER-PORT] [--schemas-dir SCHEMAS-DIR]
 154                             [--notification-file NOTIFICATION-FILE]
 155                             [--initial-config-xml-file INITIAL-CONFIG-XML-FILE] [--starting-port STARTING-PORT]
 156                             [--generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT]
 157                             [--generate-config-address GENERATE-CONFIG-ADDRESS]
 158                             [--generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE]
 159                             [--distribution-folder DISTRO-FOLDER] [--ssh {true,false}] [--exi {true,false}]
 160                             [--debug {true,false}] [--md-sal {true,false}] [--time-out TIME-OUT] [--ip IP]
 161                             [--thread-pool-size THREAD-POOL-SIZE] [--rpc-config RPC-CONFIG]
 162
 163     netconf testtool
 164
 165     named arguments:
 166       -h, --help             show this help message and exit
 167       --edit-content EDIT-CONTENT
 168       --async-requests {true,false}
 169                              (default: false)
 170       --thread-amount THREAD-AMOUNT
 171                              The number of threads to use for configuring devices. (default: 1)
 172       --throttle THROTTLE    Maximum amount of async requests that  can  be  open  at  a time, with mutltiple threads
 173                              this gets divided among all threads (default: 5000)
 174       --controller-auth-username CONTROLLER-AUTH-USERNAME
 175                              Username for HTTP basic authentication to destination controller. (default: admin)
 176       --controller-auth-password CONTROLLER-AUTH-PASSWORD
 177                              Password for HTTP basic authentication to destination controller. (default: admin)
 178       --controller-ip CONTROLLER-IP
 179                              Ip of controller if  available  it  will  be  used  for  spawning netconf connectors via
 180                              topology   configuration   as   a    part   of   URI(http://<controller-ip>:<controller-
 181                              port>/rests/data/...) otherwise it  will  just  start  simulated  devices  and  skip the
 182                              execution of PATCH requests
 183       --controller-port CONTROLLER-PORT
 184                              Port of controller if available  it  will  be  used  for spawning netconf connectors via
 185                              topology   configuration   as   a    part   of   URI(http://<controller-ip>:<controller-
 186                              port>/rests/data/...) otherwise it  will  just  start  simulated  devices  and  skip the
 187                              execution of PATCH requests
 188       --device-count DEVICES-COUNT
 189                              Number of simulated netconf devices to  spin.  This  is  the number of actual ports open
 190                              for the devices. (default: 1)
 191       --devices-per-port DEVICES-PER-PORT
 192                              Amount of config files  generated  per  port  to  spoof  more  devices than are actually
 193                              running (default: 1)
 194       --schemas-dir SCHEMAS-DIR
 195                              Directory containing yang  schemas  to  describe  simulated  devices.  Some schemas e.g.
 196                              netconf monitoring and inet types are included by default
 197       --notification-file NOTIFICATION-FILE
 198                              Xml  file  containing  notifications  that  should  be  sent  to  clients  after  create
 199                              subscription is called
 200       --initial-config-xml-file INITIAL-CONFIG-XML-FILE
 201                              Xml file containing initial simulatted configuration to be returned via get-config rpc
 202       --starting-port STARTING-PORT
 203                              First port for simulated device.  Each  other  device  will  have previous+1 port number
 204                              (default: 17830)
 205       --generate-config-connection-timeout GENERATE-CONFIG-CONNECTION-TIMEOUT
 206                              Timeout to be generated in initial config files (default: 1800000)
 207       --generate-config-address GENERATE-CONFIG-ADDRESS
 208                              Address to be placed in generated configs (default: 127.0.0.1)
 209       --generate-configs-batch-size GENERATE-CONFIGS-BATCH-SIZE
 210                              Number of connector configs per generated file (default: 1)
 211       --distribution-folder DISTRO-FOLDER
 212                              Directory where the karaf distribution for controller is located
 213       --ssh {true,false}     Whether to use ssh for transport or just pure tcp (default: true)
 214       --exi {true,false}     Whether to use exi to transport xml content (default: true)
 215       --debug {true,false}   Whether to use debug log level instead of INFO (default: false)
 216       --md-sal {true,false}  Whether to use md-sal datastore instead of default simulated datastore. (default: false)
 217       --time-out TIME-OUT    the maximum time in seconds for executing each PATCH request (default: 20)
 218       -ip IP                 Ip address which will be used for creating  a  socket address.It can either be a machine
 219                              name, such as java.sun.com, or  a  textual  representation  of its IP address. (default:
 220                              0.0.0.0)
 221       --thread-pool-size THREAD-POOL-SIZE
 222                              The number of threads to keep in  the  pool,  when  creating a device simulator. Even if
 223                              they are idle. (default: 8)
 224       --rpc-config RPC-CONFIG
 225                              Rpc config file. It can be used to  define  custom rpc behavior, or override the default
 226                              one.Usable for testing buggy device behavior.
 227
 228
 229
 230 Supported operations
 231 ^^^^^^^^^^^^^^^^^^^^
 232
 233 Testtool default simple datastore supported operations:
 234
 235 get-schema
 236     returns YANG schemas loaded from user specified directory,
 237
 238 edit-config
 239     always returns OK and stores the XML from the input in a local
 240     variable available for get-config and get RPC. Every edit-config
 241     replaces the previous data,
 242
 243 commit
 244     always returns OK, but does not actually commit the data,
 245
 246 get-config
 247     returns local XML stored by edit-config,
 248
 249 get
 250     returns local XML stored by edit-config with netconf-state subtree,
 251     but also supports filtering.
 252
 253 (un)lock
 254     returns always OK with no lock guarantee
 255
 256 create-subscription
 257     returns always OK and after the operation is triggered, provided
 258     NETCONF notifications (if any) are fed to the client. No filtering
 259     or stream recognition is supported.
 260
 261 Note: when operation="delete" is present in the payload for edit-config,
 262 it will wipe its local store to simulate the removal of data.
 263
 264 When using the MD-SAL datastore testtool behaves more like normal
 265 NETCONF server and is suitable for crud testing. create-subscription is
 266 not supported when testtool is running with the MD-SAL datastore.
 267
 268 Notification support
 269 ^^^^^^^^^^^^^^^^^^^^
 270
 271 Testtool supports notifications via the --notification-file switch. To
 272 trigger the notification feed, create-subscription operation has to be
 273 invoked. The XML file provided should look like this example file:
 274
 275 ::
 276
 277     <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
 278     <notifications>
 279
 280     <!-- Notifications are processed in the order they are defined in XML -->
 281
 282     <!-- Notification that is sent only once right after create-subscription is called -->
 283     <notification>
 284         <!-- 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 -->
 285         <content><![CDATA[
 286             <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 287                 <eventTime>2011-01-04T12:30:46</eventTime>
 288                 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
 289                     <random-content>single no delay</random-content>
 290                 </random-notification>
 291             </notification>
 292         ]]></content>
 293     </notification>
 294
 295     <!-- Repeated Notification that is sent 5 times with 2 second delay inbetween -->
 296     <notification>
 297         <!-- Delay in seconds from previous notification -->
 298         <delay>2</delay>
 299         <!-- Number of times this notification should be repeated -->
 300         <times>5</times>
 301         <content><![CDATA[
 302             <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 303                 <eventTime>XXXX</eventTime>
 304                 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
 305                     <random-content>scheduled 5 times 10 seconds each</random-content>
 306                 </random-notification>
 307             </notification>
 308         ]]></content>
 309     </notification>
 310
 311     <!-- Single notification that is sent only once right after the previous notification -->
 312     <notification>
 313         <delay>2</delay>
 314         <content><![CDATA[
 315             <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 316                 <eventTime>XXXX</eventTime>
 317                 <random-notification xmlns="http://www.opendaylight.org/netconf/event:1.0">
 318                     <random-content>single with delay</random-content>
 319                 </random-notification>
 320             </notification>
 321         ]]></content>
 322     </notification>
 323
 324     </notifications>
 325
 326 Connecting testtool with controller Karaf distribution
 327 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 328
 329 Auto connect to OpenDaylight
 330 ''''''''''''''''''''''''''''
 331
 332 It is possible to make OpenDaylight auto connect to the simulated
 333 devices spawned by testtool (so user does not have to post a
 334 configuration for every NETCONF connector via RESTCONF). The testtool is
 335 able to modify the OpenDaylight distribution to auto connect to the
 336 simulated devices after feature ``odl-netconf-connector-all`` is
 337 installed. When running testtool, issue this command (just point the
 338 testool to the distribution:
 339
 340 ::
 341
 342     java -jar netconf-testtool-1.1.0-SNAPSHOT-executable.jar --device-count 10 --distribution-folder ~/distribution-karaf-0.4.0-SNAPSHOT/ --debug true
 343
 344 With the distribution-folder parameter, the testtool will modify the
 345 distribution to include configuration for netconf-connector to connect
 346 to all simulated devices. So there is no need to spawn
 347 netconf-connectors via RESTCONF.
 348
 349 Running testtool and OpenDaylight on different machines
 350 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 351
 352 The testtool binds by default to 0.0.0.0 so it should be accessible from
 353 remote machines. However you need to set the parameter
 354 "generate-config-address" (when using autoconnect) to the address of
 355 machine where testtool will be run so OpenDaylight can connect. The
 356 default value is localhost.
 357
 358 Executing operations via RESTCONF on a mounted simulated device
 359 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 360
 361 Simulated devices support basic RPCs for editing their config. This part
 362 shows how to edit data for simulated device via RESTCONF.
 363
 364 Test YANG schema
 365 ''''''''''''''''
 366
 367 The controller and RESTCONF assume that the data that can be manipulated
 368 for mounted device is described by a YANG schema. For demonstration, we
 369 will define a simple YANG model:
 370
 371 ::
 372
 373     module test {
 374         yang-version 1;
 375         namespace "urn:opendaylight:test";
 376         prefix "tt";
 377
 378         revision "2014-10-17";
 379
 380
 381        container cont {
 382
 383             leaf l {
 384                 type string;
 385             }
 386        }
 387     }
 388
 389 Save this schema in file called test@2014-10-17.yang and store it a
 390 directory called test-schemas/, e.g., your home folder.
 391
 392 Editing data for simulated device
 393 '''''''''''''''''''''''''''''''''
 394
 395 -  Start the device with following command:
 396
 397    ::
 398
 399        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/
 400
 401 -  Start OpenDaylight
 402
 403 -  Install odl-netconf-connector-all feature
 404
 405 -  Install odl-restconf feature
 406
 407 -  Check that you can see config data for simulated device by executing
 408    GET request to
 409
 410    ::
 411
 412        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 413
 414 -  The data should be just and empty data container
 415
 416 -  Now execute edit-config request by executing a POST request to:
 417
 418    ::
 419
 420        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount
 421
 422    with headers:
 423
 424    ::
 425
 426        Accept application/xml
 427        Content-Type application/xml
 428
 429    and payload:
 430
 431    ::
 432
 433        <cont xmlns="urn:opendaylight:test">
 434          <l>Content</l>
 435        </cont>
 436
 437 -  Check that you can see modified config data for simulated device by
 438    executing GET request to
 439
 440    ::
 441
 442        http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 443
 444 -  Check that you can see the same modified data in operational for
 445    simulated device by executing GET request to
 446
 447    ::
 448
 449        http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
 450
 451 .. warning::
 452
 453     Data will be mirrored in operational datastore only when using the
 454     default simple datastore.
 455
 456
 457 Testing User defined RPC
 458 ^^^^^^^^^^^^^^^^^^^^^^^^
 459
 460 The NETCONF test-tool allows using custom RPC. Custom RPC needs to be defined in yang model provide to test-tool along
 461 with parameter ``--schemas-dir``.
 462
 463 The input and output of the custom RPC should be provided with ``--rpc-config`` parameter as a path to the file containing
 464 definition of input and output. The format of the custom RPC file is xml as shown below.
 465
 466 Start the device with following command:
 467
 468 ::
 469
 470     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
 471
 472 Example YANG model file:
 473
 474 ::
 475
 476     module example-ops {
 477          namespace "urn:example-ops:reboot";
 478          prefix "ops";
 479
 480         import ietf-yang-types {
 481         prefix "yang";
 482          }
 483
 484
 485          revision "2016-07-07" {
 486            description "Initial version.";
 487            reference "example document.";
 488          }
 489
 490
 491          rpc reboot {
 492            description "Reboot operation.";
 493            input {
 494              leaf delay {
 495                type uint32;
 496                units "seconds";
 497                default 0;
 498                description
 499                  "Delay in seconds.";
 500              }
 501              leaf message {
 502                type string;
 503                description
 504                  "Log message.";
 505              }
 506            }
 507          }
 508        }
 509
 510
 511 Example payload (RPC config file customrpc.xml):
 512
 513 ::
 514
 515     <rpcs>
 516       <rpc>
 517         <input>
 518           <reboot xmlns="urn:example-ops:reboot">
 519             <delay>300</delay>
 520             <message>message</message>
 521           </reboot>
 522         </input>
 523         <output>
 524           <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 525             <ok/>
 526           </rpc-reply>
 527         </output>
 528       </rpc>
 529     </rpcs>
 530
 531
 532
 533 Example of use:
 534
 535 ::
 536
 537     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
 538
 539 If successful the command will return code 200.
 540
 541
 542
 543 .. note::
 544
 545     A working example of user defined RPC can be found in TestToolTest.java class of the tools[netconf-testtool] project.
 546
 547
 548 Known problems
 549 ^^^^^^^^^^^^^^
 550
 551 Slow creation of devices on virtual machines
 552 ''''''''''''''''''''''''''''''''''''''''''''
 553
 554 When testtool seems to take unusually long time to create the devices
 555 use this flag when running it:
 556
 557 ::
 558
 559     -Dorg.apache.sshd.registerBouncyCastle=false
 560
 561 Too many files open
 562 '''''''''''''''''''
 563
 564 When testtool or OpenDaylight starts to fail with TooManyFilesOpen
 565 exception, you need to increase the limit of open files in your OS. To
 566 find out the limit in linux execute:
 567
 568 ::
 569
 570     ulimit -a
 571
 572 Example sufficient configuration in linux:
 573
 574 ::
 575
 576     core file size          (blocks, -c) 0
 577     data seg size           (kbytes, -d) unlimited
 578     scheduling priority             (-e) 0
 579     file size               (blocks, -f) unlimited
 580     pending signals                 (-i) 63338
 581     max locked memory       (kbytes, -l) 64
 582     max memory size         (kbytes, -m) unlimited
 583     open files                      (-n) 500000
 584     pipe size            (512 bytes, -p) 8
 585     POSIX message queues     (bytes, -q) 819200
 586     real-time priority              (-r) 0
 587     stack size              (kbytes, -s) 8192
 588     cpu time               (seconds, -t) unlimited
 589     max user processes              (-u) 63338
 590     virtual memory          (kbytes, -v) unlimited
 591     file locks                      (-x) unlimited
 592
 593 To set these limits edit file: /etc/security/limits.conf, for example:
 594
 595 ::
 596
 597     *         hard    nofile      500000
 598     *         soft    nofile      500000
 599     root      hard    nofile      500000
 600     root      soft    nofile      500000
 601
 602 "Killed"
 603 ''''''''
 604
 605 The testtool might end unexpectedly with a simple message: "Killed".
 606 This means that the OS killed the tool due to too much memory consumed
 607 or too many threads spawned. To find out the reason on linux you can use
 608 following command:
 609
 610 ::
 611
 612     dmesg | egrep -i -B100 'killed process'
 613
 614 Also take a look at this file: /proc/sys/kernel/threads-max. It limits
 615 the number of threads spawned by a process. Sufficient (but probably
 616 much more than enough) value is, e.g., 126676